1 :Info: qedx_: 1983-02-07 qedx_
2
3 Function: provides a subroutine interface to the Multics qedx Editor
4 for use by subsystems wishing to edit arbitrary strings of ASCII text.
5
6
7 Syntax:
8 dcl qedx_ entry ptr fixed bin 35;
9 call qedx_ qedx_info_ptr code;
10
11
12 Arguments:
13 qedx_info_ptr
14 is a pointer to the qedx_info structure which defines the buffers
15 initially available in qedx_ along with other options. See "The
16 qedx_info structure" below. Input
17 code
18 is a standard system status code. See "List of status code" below.
19 Output
20
21
22 Notes:
23 The caller of qedx_ does not need to print an error message when a
24 non-zero status code is returned by the subroutine. Any appropriate
25 error messages will have already been printed by qedx_ itself. The
26 returned code is only intended to inform the caller of conditions
27 requiring further attention.
28
29
30 List of status codes:
31 0
32 editing completed successfully.
33 error_table_$unimplemented_version
34 qedx_ does not recognize the version of the qedx_info structure
35 supplied by the caller.
36 error_table_$fatal_error
37 an error occured during initialization of qedx_ which prevented the
38 user from performing any editing. The caller of qedx_ should abort
39 its execution.
40
41
42 error_table_$recoverable_error
43 one of several non-fatal conditions were detected upon exit from
44 qedx_. The exact condition is reflected to the caller in the
45 qedx_info structure see below. The caller of qedx_ must decide
46 how to proceed after each of the possible conditions. Eg: the
47 program may decide not to update the permanent copy of the data
48 being edited if the user exited via quit-force qf.
49
50
51 Notes on initial buffers:
52 The qedx_info structure defines the initial environment to be presented
53 to the user by qedx_. This environment includes an initial set of
54 buffers along with their contents and default pathnames. The contents
55 of these buffers can be read or written from the storage system, from
56 regions supplied by the caller eg: the message in send_mail, or by
57 using a caller supplied procedure eg: to read/write abbreviation
58 definitions. The caller may also request that the initial contents of
59 one or more of these buffers be executed as qedx requests before
60 reading the first request line from the user.
61
62
63 qedx_ always creates a buffer named "0" which it makes the current
64 buffer before executing any requests. If the initial buffers marked
65 for execution do not use the buffer b request to change the default
66 buffer, buffer "0" will remain the current buffer when the first
67 request line is read from the terminal.
68
69
70 Each initial buffer must have a default pathname. As part of
71 initialization, qedx_ will read the contents of the object specified by
72 this default pathname into the buffer. If the buffer is read and
73 written from the storage system, the default pathname must identify an
74 existing segment or archive component. If the buffer is read and
75 written from a caller supplied region, the default pathname may be
76 omitted but is normally used as comment to described the contents of
77 the buffer eg: "<send_mail message>" as the data is read directly
78 from the caller's region. If the buffer is read and written by a
79 caller supplied procedure, the default pathname must identify an
80 existing object eg: abbreviation definition as defined by that
81 procedure.
82
83
84 For each initial buffer, the caller may specify whether or not the
85 default pathname of the buffer is locked. If the default pathname is
86 locked, use of the read r and write w requests with a pathname will
87 never change the default pathname of the buffer nor cause qedx_ to
88 consider the default pathname untrustworthy. See "Notes on default
89 pathnames" in the description of the qedx command.
90
91 With a locked default pathname, use of the read and write requests
92 without a pathname will always read/write the original segment, region,
93 or whatever when using the caller's I/O module specified by the
94 caller of qedx_. In this case, use of the read request with a pathname
95 will simplly insert the contents of a segment into the buffer and use
96 of the write request with a pathname will simply make a copy of the
97 buffer in a segment for later use.
98
99
100 Locking the default pathname is useful in cases where it would be
101 difficult if not impossible for the user to reconstruct the default
102 pathname. For example, in send_mail, buffer "0" contains the message
103 being created. The default pathname in this case identifies the region
104 supplied by send_mail and there is no mechanism by which the user can
105 explicitly specify this default by a pathname. Therefore, send_mail
106 locks the default pathname to insure that the write w request without
107 a pathname will always update send_mail's copy of the message.
108
109
110 For each initial buffer which is being read and written from a caller
111 supplied region, the caller may request that qedx_ automatically write
112 the contents of the buffer into the region upon exit. If the user
113 exits qedx_ via the quit-force qf request, however, the automatic
114 write will be suppressed. If, when writing a buffer to the caller's
115 region, the buffer is too long to fit in that region, qedx_ will issue
116 a warning to the user and the buffer will be marked as truncated.
117 While still in qedx_, the user can make any necessary changes to the
118 buffer to shorten it sufficiently to fit within the caller's region.
119 If, on exit from qedx_, there are truncated buffers, the user will be
120 asked for permission to exit and actually truncate those buffers. Once
121 again, this query is suppressed if the quit-force request is used.
122
123
124 Notes on the qedx_info structure:
125 The qedx_info structure and the named constants referenced below are
126 defined in the qedx_info.incl.pl1 include file.
127
128
129 dcl 1 qedx_info aligned based qedx_info_ptr,
130 2 header,
131 3 version character 8,
132 3 editor_name character 72 unaligned,
133 3 buffer_io entry pointer fixed binary 35,
134 3 flags,
135 4 no_rw_path bit 1 unaligned,
136 4 query_if_modified bit 1 unaligned,
137 4 caller_does_io bit 1 unaligned,
138 4 quit_forced bit 1 unaligned,
139 4 buffers_truncated bit 1 unaligned,
140 4 pad bit 29 unaligned,
141 3 n_buffers fixed binary,
142
143
144 2 buffers qedx_info_n_buffers refer qedx_info.n_buffers,
145 3 buffer_name character 16 unaligned,
146 3 buffer_pathname character 256 unaligned,
147 3 region_ptr pointer,
148 3 region_max_lth fixed binary 21,
149 3 region_initial_lth fixed binary 21,
150 3 region_final_lth fixed binary 21,
151
152
153 3 flags,
154 4 read_write_region bit 1 unaligned,
155 4 locked_pathname bit 1 unaligned,
156 4 execute_buffer bit 1 unaligned,
157 4 default_read_ok bit 1 unaligned,
158 4 default_write_ok bit 1 unaligned,
159 4 auto_write bit 1 unaligned,
160 4 truncated bit 1 unaligned,
161 4 pad bit 29 unaligned;
162
163
164 List of qedx_info structure elements:
165 version
166 identifies the version of the qedx_info structure supplied by the
167 caller. It must have the value of the named constant
168 QEDX_INFO_VERSION_1. Input
169 editor_name
170 is the name to be used by qedx_ in error messages and queries.
171 Eg: "send_mail qedx" Input
172 buffer_io
173 is only used if flags.caller_does_io is set and is the procedure to
174 be invoked by qedx_ to read/write buffers. For details about this
175 subroutine, type: help qedx_buffer_io
176 Input
177
178
179 flags.no_rw_path
180 specifies whether any read r or write w request within qedx_ may
181 ever be given an explicit pathname. Input
182 flags.query_if_modified
183 specifies whether qedx_ should query when the quit q request is
184 issued and there are buffers which have been modified since they
185 were last written. Initial buffers with the buffers.auto_write flag
186 set are not considered as modified as they are always written before
187 exit. Input
188 flags.caller_does_io
189 specifies whether qedx_ should call the buffer_io procedure above or
190 perform I/O itself when reading/writing buffers. Input
191
192
193 flags.quit_forced
194 is set by qedx_ to "1"b to indicate that the user either used the
195 quit-force qf request or answered "yes" to the modified buffers
196 query in order to exit; it is set to "0"b to indicate that the user
197 used the quit q request and there were no modified buffers
198 present. Output
199 flags.buffers_truncated
200 is set by qedx_ to "1"b to indicate that the final contents of one
201 or more initial buffers were truncated on exit from qedx_. The
202 buffers which were truncated are marked by the buffers.truncated
203 flag. Output
204
205
206 n_buffers
207 is the number of initial buffers defined below. Input
208 buffers
209 defines the initial buffers available within this invocation of
210 qedx_. See "Notes on initial buffers" above.
211 buffers.buffer_name
212 is the name of this buffer. Input
213 buffers.buffer_pathname
214 is the initial default pathname for this buffer. Input
215 buffers.region_ptr
216 is a pointer to the region where qedx_ will read and write this
217 buffer if buffers.read_write_region is set. Input
218
219
220 buffers.region_max_lth
221 is the maximum number of characters which may be written into the
222 above region if buffers.read_write_region is set. Input
223 buffers.region_initial_lth
224 is the number of characters present in the caller's region on entry
225 to qedx_ if buffers.read_write_region is set. qedx_ will
226 automatically read the specified characters into the buffer.
227 Input
228 buffers.region_final_lth
229 is set by qedx_ to the number of characters written into the
230 caller's region upon exit from qedx_ if bufers.read_write_region is
231 set. This value will be larger than buffers.region_max_lth if
232 buffers.truncated is set by qedx_. Output
233
234
235 buffers.read_write_region
236 specifies that qedx_ will use the caller's region to read/write the
237 contents of this buffer until the user changes the default pathname.
238 Use of this flag is incompatible with flags.caller_does_io. Input
239 buffers.locked_pathname
240 specifies that the default pathname of this buffer is locked and can
241 not be changed by read r or write w requests. Input
242 buffers.execute_buffer
243 specifies that the contents of this buffer should be executed as
244 qedx requests before reading requests from the user. Input
245
246
247 buffers.default_read_ok
248 specifies that the read r request can be given without a pathname
249 to read the current contents of the caller's region. This flag is
250 ignored if flags.read_write_region is not set or the default
251 pathname is not the caller's region. Input
252 buffers.default_write_ok
253 specifies that the write w request can be given without a pathname
254 to write the buffer to the caller's region. This flag is ignored if
255 flags.read_write_region is not set or the default pathname is not
256 the caller's region. Input
257
258
259 buffers.auto_write
260 specifies that the contents of this buffer will be written to the
261 caller's region on exit from qedx_ unless the user uses the
262 quit-force qf request or answers "yes" to the query to exit with
263 modified buffers. Input
264 buffers.truncated
265 is set by qedx_ to "1"b if the entire contents of the buffer could
266 not be written to the caller's region on exit from qedx_. Output
267
268
269 :Info: qedx_buffer_io: 2020-05-18 qedx_buffer_io
270
271 Function:
272 When using the qedx_ subroutine, if qedx_info.flags.caller_does_io is
273 set, qedx_ will invoke the caller supplied qedx_buffer_io procedure
274 in order to read and write the contents of any buffer. qedx_
275 determines the pathname to which the buffer is to be read or written;
276 the interpretation of this pathname is the responsibility of the
277 caller's buffer_io procedure. Eg: the procedure may use the
278 pathname as the name of an abbreviation whose definition is to be
279 read/written.
280
281
282 For a read r request, qedx_ supplies an I/O region into which the
283 buffer_io procedure should place the text copied from the object
284 designated by the pathname; qedx_ will then insert this text into its
285 proper place in the buffer. For a write w request, qedx_ copies the
286 text from the buffer into an I/O region; the buffer_io procedure should
287 then place this text into the object designated by the pathname.
288
289
290 Syntax:
291 dcl qedx_buffer_io entry ptr bit1 aligned;
292 call qedx_buffer_io qedx_buffer_io_info_ptr success;
293
294
295 Arguments:
296 qedx_buffer_io_info_ptr
297 is a pointer to the qedx_buffer_io_info structure describing the
298 read/write operation to be undertaken. Input
299 success
300 is set by the buffer_io procedure to "1"b if the operation was
301 successfull and to "0"b if it failed. Output
302
303
304 Notes:
305 It is the responsibilty of the qedx_buffer_io procedure to print any
306 appropriate error messages if the operation does not succeed.
307
308
309 Notes on the qedx_buffer_io_info structure:
310 The qedx_buffer_io_info structure and the named constants referenced
311 below are defined in the qedx_buffer_io_info.incl.pl1 include file.
312
313 dcl 1 qedx_buffer_io_info aligned based qbii_ptr,
314 2 version character 8,
315 2 editor_name character 72,
316 2 pathname character 256 unaligned,
317 2 buffer_ptr pointer,
318 2 buffer_max_lth fixed binary 21,
319 2 buffer_lth fixed binary 21,
320 2 direction fixed binary,
321 2 flags,
322 3 default_pathname bit 1 unaligned,
323 3 pad bit 35 unaligned;
324
325
326 List of qedx_buffer_io_info elements:
327 version
328 identifies the version of the qedx_buffer_io_info structure supplied
329 by qedx_. This version of the structure is given by the named
330 constant QEDX_BUFFER_IO_INFO_VERSION_1. Output
331 editor_name
332 is the name of the editor to be used by the buffer_io procedure in
333 any error messages and queries. Input
334 pathname
335 is the pathname to be read/written as determined by qedx_. Input
336
337
338 buffer_ptr
339 is a pointer to the I/O buffer allocated by qedx_. When reading
340 from the pathname, the buffer_io procedure must place the text into
341 this buffer; when writing to the pathname, the buffer_io procedure
342 must take the text from this buffer. Input
343 buffer_max_lth
344 is the maximum size of the I/O buffer. This value is only used when
345 reading from the pathname and specifies a limit on the amount of
346 text which may be returned by the buffer_io procedure. Input
347
348
349 buffer_lth
350 is the length of the text read/written from the pathname. When
351 reading from the pathname, the buffer_io procedure must set this
352 value to the number of characters read from the pathname and placed
353 in the I/O buffer. Output When writing to the pathname, this
354 value is set by qedx_ to the number of characters to be written into
355 the pathname. Input
356 direction
357 specifies the operation to be undertaken. If it has the value of
358 the named constant QEDX_READ_FILE, the text is to be read from the
359 pathname and placed into the I/O buffer. It is has the value of the
360 named constant QEDX_WRITE_FILE, the text is to be written from the
361 I/O buffer into the pathname. Input
362
363
364 flags.default_pathname
365 is "1"b if the pathname supplied above by qedx_ is the default
366 pathname of the buffer being read/written. Input
367
368
369 :hcom:
370
371
372
373 /****^ HISTORY COMMENTS:
374 1) change2020-05-18GDixon, approve2021-02-22MCR10088,
375 audit2021-05-27Swenson, install2021-05-27MR12.6g-0056:
376 Move documentation of the caller-supplied qedx_buffer_io routine to a
377 separate :Info: block within qedx_.info.
378 END HISTORY COMMENTS */
379
380
381