02/07/83 qedx_ Syntax: dcl qedx_ entry (ptr, fixed bin (35)); call qedx_ (qedx_info_ptr, code); Function: provides a subroutine interface to the Multics qedx Editor for use by subsystems wishing to edit arbitrary strings of ASCII text. Arguments: qedx_info_ptr is a pointer to the qedx_info structure which defines the buffers initially available in qedx_ along with other options. See "The qedx_info structure" below. (Input) code is a standard system status code. See "List of status code" below. (Output) Notes: The caller of qedx_ does not need to print an error message when a non-zero status code is returned by the subroutine. Any appropriate error messages will have already been printed by qedx_ itself. The returned code is only intended to inform the caller of conditions requiring further attention. List of status codes: 0 editing completed successfully. error_table_$unimplemented_version qedx_ does not recognize the version of the qedx_info structure supplied by the caller. error_table_$fatal_error an error occured during initialization of qedx_ which prevented the user from performing any editing. The caller of qedx_ should abort its execution. error_table_$recoverable_error one of several non-fatal conditions were detected upon exit from qedx_. The exact condition is reflected to the caller in the qedx_info structure (see below). The caller of qedx_ must decide how to proceed after each of the possible conditions. (Eg: the program may decide not to update the permanent copy of the data being edited if the user exited via quit-force (qf).) Notes on initial buffers: The qedx_info structure defines the initial environment to be presented to the user by qedx_. This environment includes an initial set of buffers along with their contents and default pathnames. The contents of these buffers can be read or written from the storage system, from regions supplied by the caller (eg: the message in send_mail), or by using a caller supplied procedure (eg: to read/write abbreviation definitions). The caller may also request that the initial contents of one or more of these buffers be executed as qedx requests before reading the first request line from the user. qedx_ always creates a buffer named "0" which it makes the current buffer before executing any requests. If the initial buffers marked for execution do not use the buffer (b) request to change the default buffer, buffer "0" will remain the current buffer when the first request line is read from the terminal. Each initial buffer must have a default pathname. As part of initialization, qedx_ will read the contents of the object specified by this default pathname into the buffer. If the buffer is read and written from the storage system, the default pathname must identify an existing segment or archive component. If the buffer is read and written from a caller supplied region, the default pathname may be omitted but is normally used as comment to described the contents of the buffer (eg: "") as the data is read directly from the caller's region. If the buffer is read and written by a caller supplied procedure, the default pathname must identify an existing object (eg: abbreviation definition) as defined by that procedure. For each initial buffer, the caller may specify whether or not the default pathname of the buffer is locked. If the default pathname is locked, use of the read (r) and write (w) requests with a pathname will never change the default pathname of the buffer nor cause qedx_ to consider the default pathname untrustworthy. (See "Notes on default pathnames" in the description of the qedx command). With a locked default pathname, use of the read and write requests without a pathname will always read/write the original segment, region, or whatever (when using the caller's I/O module) specified by the caller of qedx_. In this case, use of the read request with a pathname will simplly insert the contents of a segment into the buffer and use of the write request with a pathname will simply make a copy of the buffer in a segment for later use. Locking the default pathname is useful in cases where it would be difficult (if not impossible) for the user to reconstruct the default pathname. For example, in send_mail, buffer "0" contains the message being created. The default pathname in this case identifies the region supplied by send_mail and there is no mechanism by which the user can explicitly specify this default by a pathname. Therefore, send_mail locks the default pathname to insure that the write (w) request without a pathname will always update send_mail's copy of the message. For each initial buffer which is being read and written from a caller supplied region, the caller may request that qedx_ automatically write the contents of the buffer into the region upon exit. If the user exits qedx_ via the quit-force (qf) request, however, the automatic write will be suppressed. If, when writing a buffer to the caller's region, the buffer is too long to fit in that region, qedx_ will issue a warning to the user and the buffer will be marked as truncated. While still in qedx_, the user can make any necessary changes to the buffer to shorten it sufficiently to fit within the caller's region. If, on exit from qedx_, there are truncated buffers, the user will be asked for permission to exit and actually truncate those buffers. Once again, this query is suppressed if the quit-force request is used. The qedx_info structure: The qedx_info structure and the named constants referenced below are defined in the qedx_info.incl.pl1 include file. dcl 1 qedx_info aligned based (qedx_info_ptr), 2 header, 3 version character (8), 3 editor_name character (72) unaligned, 3 buffer_io entry (pointer, fixed binary (35)), 3 flags, 4 no_rw_path bit (1) unaligned, 4 query_if_modified bit (1) unaligned, 4 caller_does_io bit (1) unaligned, 4 quit_forced bit (1) unaligned, 4 buffers_truncated bit (1) unaligned, 4 pad bit (29) unaligned, 3 n_buffers fixed binary, 2 buffers (qedx_info_n_buffers refer (qedx_info.n_buffers)), 3 buffer_name character (16) unaligned, 3 buffer_pathname character (256) unaligned, 3 region_ptr pointer, 3 region_max_lth fixed binary (21), 3 region_initial_lth fixed binary (21), 3 region_final_lth fixed binary (21), 3 flags, 4 read_write_region bit (1) unaligned, 4 locked_pathname bit (1) unaligned, 4 execute_buffer bit (1) unaligned, 4 default_read_ok bit (1) unaligned, 4 default_write_ok bit (1) unaligned, 4 auto_write bit (1) unaligned, 4 truncated bit (1) unaligned, 4 pad bit (29) unaligned; version identifies the version of the qedx_info structure supplied by the caller. It must have the value of the named constant QEDX_INFO_VERSION_1. (Input) editor_name is the name to be used by qedx_ in error messages and queries. (Eg: "send_mail (qedx)") (Input) buffer_io is only used if flags.caller_does_io is set and is the procedure to be invoked by qedx_ to read/write buffers. See "Notes on buffer I/O" below. (Input) flags.no_rw_path specifies whether any read (r) or write (w) request within qedx_ may ever be given an explicit pathname. (Input) flags.query_if_modified specifies whether qedx_ should query when the quit (q) request is issued and there are buffers which have been modified since they were last written. Initial buffers with the buffers.auto_write flag set are not considered as modified as they are always written before exit. (Input) flags.caller_does_io specifies whether qedx_ should call the buffer_io procedure above or perform I/O itself when reading/writing buffers. (Input) flags.quit_forced is set by qedx_ to "1"b to indicate that the user either used the quit-force (qf) request or answered "yes" to the modified buffers query in order to exit; it is set to "0"b to indicate that the user used the quit (q) request and there were no modified buffers present. (Output) flags.buffers_truncated is set by qedx_ to "1"b to indicate that the final contents of one or more initial buffers were truncated on exit from qedx_. The buffers which were truncated are marked by the buffers.truncated flag. (Output) n_buffers is the number of initial buffers defined below. (Input) buffers defines the initial buffers available within this invocation of qedx_. See "Notes on initial buffers" above. buffers.buffer_name is the name of this buffer. (Input) buffers.buffer_pathname is the initial default pathname for this buffer. (Input) buffers.region_ptr is a pointer to the region where qedx_ will read and write this buffer if buffers.read_write_region is set. (Input) buffers.region_max_lth is the maximum number of characters which may be written into the above region if buffers.read_write_region is set. (Input) buffers.region_initial_lth is the number of characters present in the caller's region on entry to qedx_ if buffers.read_write_region is set. qedx_ will automatically read the specified characters into the buffer. (Input) buffers.region_final_lth is set by qedx_ to the number of characters written into the caller's region upon exit from qedx_ if bufers.read_write_region is set. This value will be larger than buffers.region_max_lth if buffers.truncated is set by qedx_. (Output) buffers.read_write_region specifies that qedx_ will use the caller's region to read/write the contents of this buffer until the user changes the default pathname. Use of this flag is incompatible with flags.caller_does_io. (Input) buffers.locked_pathname specifies that the default pathname of this buffer is locked and can not be changed by read (r) or write (w) requests. (Input) buffers.execute_buffer specifies that the contents of this buffer should be executed as qedx requests before reading requests from the user. (Input) buffers.default_read_ok specifies that the read (r) request can be given without a pathname to read the current contents of the caller's region. This flag is ignored if flags.read_write_region is not set or the default pathname is not the caller's region. (Input) buffers.default_write_ok specifies that the write (w) request can be given without a pathname to write the buffer to the caller's region. This flag is ignored if flags.read_write_region is not set or the default pathname is not the caller's region. (Input) buffers.auto_write specifies that the contents of this buffer will be written to the caller's region on exit from qedx_ unless the user uses the quit-force (qf) request or answers "yes" to the query to exit with modified buffers. (Input) buffers.truncated is set by qedx_ to "1"b if the entire contents of the buffer could not be written to the caller's region on exit from qedx_. (Output) Notes on buffer I/O: If flags.caller_does_io is set, qedx_ will invoke the caller supplied buffer_io procedure in order to read and write the contents of any buffer. qedx_ determines the pathname to which the buffer is to be read or written; the interpretation of this pathname is the responsibility of the caller's buffer_io procedure. (Eg: the procedure may use the pathname as the name of an abbreviation whose definition is to be read/written). For a read (r) request, qedx_ supplies an I/O region into which the buffer_io procedure should place the text copied from the object designated by the pathname; qedx_ will then insert this text into its proper place in the buffer. For a write (w) request, qedx_ copies the text from the buffer into an I/O region; the buffer_io procedure should then place this text into the object designated by the pathname. The buffer_io procedure: qedx_ invokes the buffer_io procedure as follows -- dcl buffer_io entry (ptr, bit(1) aligned); call buffer_io (qedx_buffer_io_info_ptr, success); Arguments-- qedx_buffer_io_info_ptr is a pointer to the qedx_buffer_io_info structure describing the read/write operation to be undertaken. (Input) success is set by the buffer_io procedure to "1"b if the operation was successfull and to "0"b if it failed. (Output) Notes-- It is the responsibilty of the buffer_io procedure to print any appropriate error messages if the operation does not succeed. The qedx_buffer_io_info structure: The qedx_buffer_io_info structure and the named constants referenced below are defined in the qedx_buffer_io_info.incl.pl1 include file. dcl 1 qedx_buffer_io_info aligned based (qbii_ptr), 2 version character (8), 2 editor_name character (72), 2 pathname character (256) unaligned, 2 buffer_ptr pointer, 2 buffer_max_lth fixed binary (21), 2 buffer_lth fixed binary (21), 2 direction fixed binary, 2 flags, 3 default_pathname bit (1) unaligned, 3 pad bit (35) unaligned; version identifies the version of the qedx_buffer_io_info structure supplied by qedx_. This version of the structure is given by the named constant QEDX_BUFFER_IO_INFO_VERSION_1. (Output) editor_name is the name of the editor to be used by the buffer_io procedure in any error messages and queries. (Input) pathname is the pathname to be read/written as determined by qedx_. (Input) buffer_ptr is a pointer to the I/O buffer allocated by qedx_. When reading from the pathname, the buffer_io procedure must place the text into this buffer; when writing to the pathname, the buffer_io procedure must take the text from this buffer. (Input) buffer_max_lth is the maximum size of the I/O buffer. This value is only used when reading from the pathname and specifies a limit on the amount of text which may be returned by the buffer_io procedure. (Input) buffer_lth is the length of the text read/written from the pathname. When reading from the pathname, the buffer_io procedure must set this value to the number of characters read from the pathname and placed in the I/O buffer. (Output) When writing to the pathname, this value is set by qedx_ to the number of characters to be written into the pathname. (Input) direction specifies the operation to be undertaken. If it has the value of the named constant QEDX_READ_FILE, the text is to be read from the pathname and placed into the I/O buffer. It is has the value of the named constant QEDX_WRITE_FILE, the text is to be written from the I/O buffer into the pathname. (Input) flags.default_pathname is "1"b if the pathname supplied above by qedx_ is the default pathname of the buffer being read/written. (Input) ----------------------------------------------------------- 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