Multics Technical Bulletin MTB-754
New tssi_ Interface
To: Distribution
From: Richard Gray
Date: 22 July 1986
Subject: A New tssi_ Interface to Obtain Translator Files.
1. Abstract
This MTB describes a possible new interface to the system |
routine tssi_ that will be used by languages that access source, |
object, and listing files. It describes two new entrypoints and |
an information structure that will be used to access these files. |
Comments on this MTB should be sent to the author -
via Multics mail:
JRGray.Multics on System M
via posted mail:
Richard Gray
Advanced Computing Technology Center
Foothills Professional Building
Room #301, 1620 - 29th Street N.W.
Calgary, Alberta T2N 4L7
CANADA
via telephone:
(403)-284-6400
(403)-284-6410
_________________________________________________________________
Multics project internal documentation; not to be reproduced or
distributed outside the Multics project.
MTB-754 Multics Technical Bulletin
New tssi_ Interface
TABLE OF CONTENTS
Section Page Subject
======= ==== =======
1 i Abstract
2 1 Preface
3 1 Introduction
4 2 New Work Proposed For tssi_
4.1 2 . . The Source
4.2 3 . . The Object
4.3 3 . . The Listing
5 4 Error handling
6 4 Access Changes
7 5 Interface
Multics Technical Bulletin MTB-754
New tssi_ Interface
2. Preface
This MTB describes a possible new interface to the system routine
tssi_ that will be used by languages to access storage system
segments. This interface is designed to be used by languages |
that read source segments and generate listing files and object |
segments. Hence, this MTB is intended for language developers |
and maintainers.
The first section describes how translators use source, object
and listing files. This is followed by a brief discussion on
error handling. Next comes a section that describes how tssi_
changes Access Control lists. The final section describes in
detail the proposed interface.
3. Introduction
There is a common class of language translator that shares common |
methods of accessing storage segments. We propose to move as |
much of this work as possible into one routine. This will |
simplify the work done by such translators as well as provide |
error detection that does not currently exist in most languages.
Several PL/1 Trouble Reports will become resolved when this new
interface is used.
Upon installation of this new tssi_ interface, PL/1, FORTRAN, and
ALM will all be updated immediately to take advantage of the new
features.
MTB-754 Multics Technical Bulletin
New tssi_ Interface
4. New Work Proposed For tssi_
| Currently, certain languages obtain source, object, and listing
files through several calls to tssi_ subroutines. If there were
one subroutine interface in tssi_ that would return all three
| files, less work would have to be done by the translators. In
| addition, errors involving interactions between these segments
| could be detected (for example, the infamous PL/1 message: "The
source segment is the same as the object segment. It has been
truncated." would be only a bad memory).
| A summary of the procedure used by the subroutine interface
| follows:
|
| 1) Access the source segment.
|
| 2) Access the object segment. If a new object segment had to be
| created then fix up the initial ACL. If the object segment is
| the same as the source then quit. Coerce access so that the
| translator can write into the object.
|
| 3) Access the list file. If the list file is the same as the
| object or source then quit. Coerce access so that the
| translator can write into the list file. Return the maximum
| length of the listing. Truncate so that all the listing
| information is relevant to the current translation.
|
|
| The following three subsections discuss in detail the behaviour
| that the new tssi_ interface will have to support for each of the
| translator files.
|
4.1. The Source
The source segment is used as input to translators. It is
usually accessed via a pointer and length (bit count).
Translators require read access only to this segment. If the
user does not have access to this segment, the new tssi_
interface will not coerce access. Instead, an error is returned
and presumably the compilation ceases.
Multics Technical Bulletin MTB-754
New tssi_ Interface
4.2. The Object
The object segment contains output from translators. It is
usually referenced via a pointer and a length (bit count).
Translators require read and write access to this segment. If
necessary, tssi_ will coerce access to this segment. (See the |
section on "Access Changes" for more details.) |
There are several ways in which different translators may wish to
access the object segment. A translator might want to zero the
object before it writes to it, or it might just overwrite the
segment and truncate after the compilation. To allow for options
like the "-check" option in PL/1, the language might want to use
a temporary object segment in the process directory. In
addition, FORTRAN protects object segments in a unique way that
would be advantageous to carry over to other languages. FORTRAN
compiles its object segments in the process directory and only
copies over existing object segments upon completion of a
successful compilation. We propose that the new tssi_ interface
support all of these behaviours in a transparent manner.
4.3. The Listing
The listing file is also output from translators. It can be a
multisegment file that is referenced via a pointer to a File
Control Block and related information. This related information
includes a component pointer, component bit count, and component
number as documented in the description of msf_manager_ in the
Multics Subroutines and I/O Modules (AG93) manual. Translators
require read and write access to this file. If necessary, tssi_
will coerce access to this file. Translators will honour the
max_length on the listing if it is set. This file contains
information about the compilation process including error
messages (if any).
MTB-754 Multics Technical Bulletin
New tssi_ Interface
5. Error handling
Since the new tssi_ interface will be detecting a number of
errors that can occur from interactions between the translator
files, returning a simple error code is not sufficient. (e.g.,
if the error code "error_table_$same_seg" were returned, the
translator would be unable to report if it were caused by the
object and source or the object and listing being the same
segment.)
| The proposed method for handing such errors is to have tssi_
| return a character string that expands on the error code. As in
| the previous example the error code "error_table_$same_seg" would
| be returned, but in addition the string "Source and Listing."
| would also be returned.
6. Access Changes
The tssi_ interface will change the access on files for two
| reasons: to coerce access and to modify an object segment's
| IACL. Access coercion is the temporary changing of the access on
a file to allow certain access constrained operations. Access
coercion allows translators to write into the list and object
| files when they originally lacked write permission on the entry.
Initial Access Control Lists (IACLs) are used to set the initial
| access on all segments created in a directory. As users require
| execute permission on object segments in order to run them,
| non-null ACL entries are changed to read_execute permission.
|
| The "mode" term is used by tssi_ to store information necessary
| to restore access to the list file and object segment in the
| event of an access coercion. When a coercion is performed and an
| existing ACL term is modified, then the mode string contains the
| original ACL entry's permission (3 significant bits followed by
| 33 zero bits). Alternately, it can contain one of two constants
| each of which has at least one bit set in the last 33 bits of the
| word used to indicate the two other possibilities: 1) a coercion
| acl entry was added and 2) no coercion was done.
Multics Technical Bulletin MTB-754
New tssi_ Interface
7. Interface
We propose two new entrypoints in tssi_:
I) tssi_$get_files will be used by translators to prepare the
source and optionally the object and list segments. It will
return a pointer to the source and object segments and a
pointer to an MSF FCB for the listing segment. It will
create temporary segments as necessary (see object_options). |
If an object segment is created then IACL fixup will be |
performed (see the section titled Access Changes). It will |
coerce access to the object and list segments if necessary |
and truncates the list.
Syntax:
declare tssi_$get_files entry(ptr, char(*), fixed bin(35));
call tssi_$get_files(tssi_info_ptr, err_msg, code);
Arguments:
tssi_info_ptr
is a pointer to the tssi_info structure. This structure is
described in the include file tssi_info.incl.pl1 . (Input)
err_msg |
is a character string that is used when necessary to elaborate |
on the status code. (Output) |
code
is a standard storage system status code. (Output)
Notes:
Example of error reporting:
alm: Attempt to specify the same segment as both old and new.
Source and Object. |
MTB-754 Multics Technical Bulletin
New tssi_ Interface
II) tssi_$finish_files will be used by translators to conclude
use of the source, object, and list segments. It will
terminate the segments and will set the bitcount, truncate,
| and reset the ACL on the object and listing if access
| coercion was necessary (see the section titled Access
| Changes). It will also delete any temporary files that were
| created by the tssi_$get_files entrypoint.
Syntax:
declare tssi_$finish_files
entry(ptr, char(*), fixed bin(35));
call tssi_$finish_files(tssi_info_ptr, err_msg, code);
Arguments:
tssi_info_ptr
is a pointer to the tssi_info structure. This structure is
described in the include file tssi_info.incl.pl1 . (Input)
| err_msg
| is a character string that is used when necessary to elaborate
| on the status code. (Output)
code
is a standard storage system status code. (Output)
Multics Technical Bulletin MTB-754
New tssi_ Interface
The following include file will be needed to describe the
structure used to pass information to/from the new tssi_
entrypoints:
/* BEGIN INCLUDE FILE ... tssi_info.incl.pl1 */
/* Written June 26, 1986 by JRGray */
/* This include file describes the tssi_info structure that is
used to exchange information with tssi_$get_files and
tssi_$finish_files. All the info in this structure is input for
the tssi_$finish_files entrypoint. The tssi_$get_files entrypoint
will input, output and update some of the information. */
dcl 1 tssi_info based,
2 version char(8),
2 translator char(8),
2 flags aligned,
3 object_options fixed bin(3) uns unaligned,
3 (create_list, check_object,
query_check_object) bit(1) unaligned,
3 mbz bit(30) unaligned,
2 source,
3 path char(168),
3 suffix char(32),
3 pntr ptr,
3 bc fixed bin(24),
2 object,
3 path char(168),
3 pntr ptr,
3 actual_pntr ptr,
3 bc fixed bin(24),
3 mode bit(36) aligned,
2 list,
3 path char(168),
3 fcb_pntr ptr,
3 pntr ptr,
3 max_length fixed bin(19),
3 component fixed bin,
3 bc fixed bin(24),
2 mode bit(36) aligned;
dcl TSSI_INFO_V1 char(8) static options(constant) init("tssi_1");
dcl TSSI_NO_OBJECT fixed bin static options(constant) init(0);
dcl TSSI_NO_TRUNCATE_OBJECT fixed bin static options(constant) init(1);
dcl TSSI_TRUNCATE_OBJECT fixed bin static options(constant) init(2);
dcl TSSI_TEMP_OBJECT fixed bin static options(constant) init(3);
dcl TSSI_COPY_TEMP_OBJECT fixed bin static options(constant) init(4);
/* END INCLUDE FILE ... tssi_info.incl.pl1 */
MTB-754 Multics Technical Bulletin
New tssi_ Interface
version
is the version string for this structure, currently defined by
the constant TSSI_INFO_V1. (Input)
| translator
| is the name of the translator. This field is used when the
| query_check_object flag is specified and a question is asked.
| (Input)
object_options
is a number between 0 and 7 specifying action to take in regard
to the object segment. (Input)
TSSI_NO_OBJECT (0) No object needed.
TSSI_NO_TRUNCATE_OBJECT (1) Open without truncation.
TSSI_TRUNCATE_OBJECT (2) Open and truncate object.
TSSI_TEMP_OBJECT (3) Create a temporary object
in the process dir.
TSSI_COPY_TEMP_OBJECT (4) Create a temporary in the
process dir and overwrite
specified object when finished.
Note: a negative object.bc will
abort the copy.
(5-7) Future expansion.
create_list
if set then create a list file. (Input)
| check_object
| this flag is used to help protect against the accidental
| overwritting of information by object segments. If this flag
| is set then the status code error_table_$improper_data_format
| will be returned when the segment is not zero length and is a
| bound or invalid object segment. See also query_check_object
| below. (Input)
| query_check_object
| this flag modifies the check_object error process by querying
| the user about whether or not to abort. (Input)
source.path
on input is the relative pathname of the source segment. The
suffix is added if it is not already present. The absolute
pathname is output. (Input/Output)
source.suffix
is the suffix to add to the entryname of the source segment.
(Input)
source.pntr
is a pointer to the beginning of the source segment. (Output)
source.bc
is the length of the source segment in bits (bitcount).
(Output)
object.path
on input is the relative pathname of the object segment. If
blank then the name is taken to be the same as the source with
the source suffix removed. The absolute pathname is output.
This field is ignored if TSSI_TEMP_OBJECT or TSSI_NO_OBJECT is
Multics Technical Bulletin MTB-754
New tssi_ Interface
specified. (Input/Output)
object.pntr
is a pointer to the beginning of the object segment. (Output)
object.actual_pntr
is used internally by tssi_ to keep a pointer to the
actual object segment. This field is only valid when object_option
COPY_TEMP_OBJECT is used. This field should not be modified
by the user as it is used to pass information between
tssi_$get_files and tssi_$finish_files. (Special)
object.bc
is the length of the object segment in bits (bitcount). This
value is used only by the tssi_$finish_files entrypoint. A |
negative bitcount is used to indicate that the object segment |
is to be deleted (exception: see the description of |
object_option TSSI_COPY_TEMP_OBJECT). (Input) |
object.mode
is used internally by tssi_ to store ACL mode information.
This field should not be modified by the user as it is used to
pass information between tssi_$get_files and
tssi_$finish_files. (Special)
list.path
on input is the relative pathname of the list file. If blank
then the name is taken to be the same as the source with the
sources suffix replaced with ".list". The absolute pathname is
output. This variable is unchanged unless the create_list flag
is set. (Input/Output)
list.fcb_pntr
is a pointer to the fcb describing the list file. For more
information on MSF FCBs see the description of msf_manager_ .
(Output)
list.pntr
is a pointer to the beginning of the first component of the
list file. Additional components of the list segments are
usually accessed via the msf_manager_$get_ptr routine.
(Output)
list.max_length
is the maximum length of the listing segment. See the
description of hcs_$get_max_length_seg in MPM Subroutines
(AG93) for more details. (Output)
list.component
is a number specifying the final component of the list segment
file. This value is used only by the tssi_$finish_files
entrypoint. For more information see the description of
msf_manager_$adjust. (Input)
list.bc
is the length of the final component of the list file in bits
(bitcount). This value is used only by the tssi_$finish_files
entrypoint. A negative bitcount is used to indicate that |
the listing is to be deleted. For more information see the |
MTB-754 Multics Technical Bulletin
New tssi_ Interface
description of msf_manager_$adjust. (Input)
list.mode
is used internally by tssi_ to store ACL mode information.
This field should not be modified by the user as it is used to
pass information between tssi_$get_files and
tssi_$finish_files. (Special)