Creating and Connecting Files
[Maintenance Note]
In addition to procedures for creating and connecting files,this module
also contains the procedure to complete the loading process and hence
must come first in the load module. DIRFIX has to plant a jump
instruction of the form X1B8000nn at the word 16 bytes from the start
of the object file. This jump takes control to the first instruction
in DIRLDR. nn is a number of half words, current value X32. The first
two instructions in DIRLDR are X5883 and X6E09 respectively. DIRFIX
also puts the length of the GLAP into the header. On entry, B either
contains the address of a record or, for an entry to SIGNAL, is 0.
BADPAGE
%externalintegerfn BAD PAGE(%integer TYPE, FSYS, BITNO)
This can be called by a privileged process with TYPE = 4 to clear bit
BITNO in the bad pages list on fsys FSYS. The result returned is the
original value of the bit.
DCHACCESS
%externalintegerfn DCHACCESS(%string(31)FILE INDEX, FILE,
%integer FSYS, NEWMODE)
This procedure is used to change the access mode (Segment table access
permission field, APF) for connected file FILE belonging to file index
FILE INDEX on disc-pack FSYS (0-99). Bits in NEWMODE have the following
meanings (as in the MODE parameter to procedure DCONNECT):
2**0 set - read access to be allowed
2**1 set - write access to be allowed
2**2 set - execute access to be allowed
2**9 set - advisory sequential(not set, then clear)
The bottom 3 bits of NEWMODE must have one of the values 1, 3
or 5. The file must be permitted to the caller in the appropriate
mode.
DCHSIZE
%externalintegerfn DCHSIZE(%string(31)FILE INDEX, FILE,
%integer FSYS, NEWKB)
The physical size of file FILE belonging to file index FILE INDEX on
disc-pack FSYS (or -1) is altered (if necessary) so that its new size
is NEWKB Kbytes. The size may not be reduced to zero. The file may
be connected in the caller's virtual memory (only). If the caller is
not the file owner, he must either have W access to the file index or
be privileged.
DCONNECT
%externalintegerfn DCONNECT(%string(31)FILE INDEX, FILE,
%integer FSYS, MODE, APF, %integername SEG, GAP)
Provided that the file is suitably permitted to the caller, the file of
name FILE belonging to file index FILE INDEX on disc-pack FSYS (or -1)
is connected into the caller's virtual memory.
The bits in the parameter MODE have the following meanings (when set):
2**0 Read access required
1 Write access required
2 Execute access required
3 Write access by other processes to be allowed
4 New copy of file to be written
5 Communications mode
6 Not to be allocated space on the drum
7 Segment to be used as a process stack
The purpose of bit 2**3 is to allow (read and) write access by more
than one process to be achieved only when each user specifically allows
the situation (by setting the bit in his request).
Bits 2**1 or 2**3 may not be set in the request if bit 2**2 (execute
access) is also set.
SEG either specifies the segment number at which the file is to be
connected (in the range 34 to 127), or is zero, indicating that the
choice of segment number is to be left to Director. If the result of
the function is 0 or 34 (file already connected), SEG is set to the
chosen segment number.
GAP specifies the number of segments which are to be reserved for the
file, even though the current size of the file may be less than that
number of segments. Attempts to specify a value of SEG which conflicts
with this GAP, in subsequent connect requests before this file is
disconnected, will be rejected.
If GAP is set to zero then no segments of virtual memory, other than
those required by the current file size, are reserved for the file.
If the result of the function is 0 or 34 (file already connected), GAP
is set to the number of segments reserved for the file.
APF may be used to specify the access permission field in the
segment(s) being connected. The bottom 9 bits are significant:
1 4 4
EXE- WRITE READ
CUTE ACR ACR
The read and write ACR values supplied must be greater than or equal to
the ACR at which the calling program (subsystem) is running. If the APF
parameter is set to zero, a value of X'1nn' is used, where n is the ACR
at which the caller is executing.
DCPUTIME
%externalintegerfn DCPUTIME
DCREATE2
%externalintegerfn DCREATE2(%string(31)FILE INDEX, FILE,
%integer FSYS, NKB, TYPE, %integername DA)
A file of name FILE is created, in file index FILE INDEX on disc-pack
FSYS, of E Epages, where E is the smallest number of Epages containing
NKB Kbytes. The maximum size of file allowed is 16 Mbytes. Subsystems
requiring larger files should arrange that they be made up of subfiles
comprising files created by this procedure.
Bits in TYPE may be set:
2**0 For a temporary file (destroyed when the creating process
stops if the file was connected, or at System start-up).
2**1 For a very temporary file (destroyed when the file is
disconnected).
2**2 For a file which is to be zeroed when created.
2**3 To set "CHERISHed" status for the file.
Temporary files are made into ordinary files (that is, the "temporary"
attribute is removed) on being RENAMEd, OFFERed, TRANSFERred or
PERMITted, and also explicitly by an appropriate call on procedure
DFSTATUS.
The disc address of the first section of the file is returned in DA.
DCREATE
%externalintegerfn DCREATE(%string(31)FILE INDEX, FILE,
%integer FSYS, NKB, TYPE)
%INTEGER DA
%RESULT = DCREATE2(FILE INDEX, FILE, FSYS, NKB, TYPE, DA)
%END; ! DCREATE
This is simply a call on DCREATE2
DDESTROY
%externalintegerfn DDESTROY(%string(31)FILE INDEX, FILE, %string(8)DATE,
%integer FSYS, TYPE)
File FILE belonging to file index FILE INDEX on disc-pack FSYS, is
destroyed. TYPE should be set to 1 to destroy a file from archive
storage, otherwise it should be set to zero. When TYPE=1, DATE should
be set to the archive date. DATE is ignored if TYPE=0.
The procedure fails if 'OWNP' for the file is either zero (no access)
or 8 (do not destroy).
DDISCONNECT
%externalintegerfn DDISCONNECT(%string(31)FILE INDEX, FILE,
%integer FSYS, DSTRY)
The file of name FILE belonging to file index FILE INDEX on disc-pack
FSYS is disconnected from the caller's virtual memory. Parameter
DESTROY should be set either to 0 or 1. If set to 1 the file will be
destroyed, provided that it belongs to the process owner (not necessary
if the process is privileged) and the "use-count" for the file is zero
after disconnection. Otherwise the parameter is ignored.
DGETDA
%externalintegerfn DGETDA(%string(31)FILE INDEX, FILE,
%integer FSYS, ADR)
This procedure provides the disc addresses of the sections of file FILE
belonging to file index FILE INDEX on disc-pack FSYS. Data is written
from address ADR in the format
(%integer SECTSI, NSECTS, LASTSECT, SPARE, %integerarray DA(0:255))
where SECTSI is the size (in epages) of the sections (except
possibly the final section)
NSECTS is the number of sections, and hence the number
of entries returned in array DA
LASTSECT is the size (in epages) of the final section
In each entry in the DA array, the top byte contains the FSYS number.
DMDC
%externalroutine DMDC
DMODE
%externalintegerfunction dmode(%integer set,adr,command)
****** Kent version of DMODE ******
If 'set' = 1, then 'adr' specifies the address of N bytes (N<65) of
TCP command data, the first being a length byte containing N-1, which
are to be dispatched (via the buffers and control streams attached to
the executive process DIRECT) to the TCP. A copy of the current TCP
mode settings is retained, and is used to return current mode settings
to the user if requested. The GETMODE action (function code 4) is not
required, since the local copy of the mode settings is always correct
(as long as no other mechanism but DMODE is used to set TCP modes).
For compatibility with ERCC, GETMODE is accepted, but treated as a
no-op.
If 'set' = 0, then 'command' specifies a TCP command byte for which
the corresponding mode data are required. 'adr' specifies an
eight-byte area into which the relevant mode settings are to be
placed. This interface routine, which accesses the local copy of the
mode settings, is provided to enable changes to be made to the
internal representation of the data without requiring user programs to
be modified.
Possible error results: 8, 45, 61
DNEWGEN
%externalintegerfn DNEWGEN(%string(31)FILE INDEX, FILE, NEWGEN OF FILE,
%integer FSYS)
This procedure provides a means of introducing an updated version
(i.e. a new generation) of file FILE belonging to file index FILE INDEX
even though it may be connected in other users' virtual memories.
If FILE is not connected in any virtual memory, a call on DNEWGEN is
equivalent to destroying FILE and then renaming NEWGEN OF FILE to FILE,
except that the new version of FILE retains the former FILE's access
permissions.
If FILE is connected in some virtual memory, then the filename
NEWGEN OF FILE "disappears", and any subsequent connection of FILE into
a virtual memory yields the contents of the new generation formerly
held in NEWGEN OF FILE.
When the number of users of a former copy of FILE becomes zero
(i.e. when it is not connected in any virtual memory), that copy is
destroyed.
DRENAME
%externalintegerfn DRENAME(%string(31)FILE INDEX, OLDNAME, NEWNAME,
%integer FSYS)
File OLDNAME belonging to file index FILE INDEX on disc-pack FSYS is
renamed NEWNAME.
A file may not be renamed while it is connected in any virtual memory.
DSETIC
%externalintegerfn DSETIC(%integer KINSTRUCTIONS)
This procedure is used to set a number of K instructions (1K=1024)
which may be executed before an instruction-counter program error
contingency is generated. The value of the parameter is subject to the
following constraints:
it must lie between the nominal values for the number of K
instructions which the machine will execute in 1 second and
two hours. The field KINSTRS in the public segment 48
communications record format (see Ref. 11) is required for
this calculation.
it must not, when added to the number of K instructions so far
executed this session, exceed the session K instruction limit
(value available in the UINF record of the process, as
described in this manual).
DSTOP
%externalroutine DSTOP(%integer REASON)
This is the means by which a subsystem terminates its process.
Director disconnects all files, disconnects interactive terminal
streams, unlocks locked-down areas and destroys temporary files. The
integer REASON, which conventionally should be 100 for a normal stop or
greater than 100 for an abnormal stop, is printed in a stopping message
in the log file. Values less than 100 are generated by Director itself
in abnormal circumstances:
REASON Meaning
0 Error condition noted in monitor printing (Dirlog).
1 A contingency occurred, but the Director procedure PRIME
CONTINGENCY (used to specify a subsystem contingency
procedure to be executed)had not previously been called.
2 A program error has occurred during execution of the
subsystem's contingency handling procedure and before
a call of Director procedure DRESUME. (A call of DRESUME
indicates that diagnostic actions are complete, and more
specifically that the contingency procedure itself is
again ready to handle further contingencies.)
3 The number of program error and virtual store
contingencies for the process has exceeded a certain
fixed number, currently 32. The purpose of this limit is
to terminate the contingency loop which will occur if the
subsystem contingency procedure executes satisfactorily
but the computation repeatedly "resumed to" immediately
fails.
4 The number of instructions executed by the process
exceeds the limit specified for the session. In the case
of an interactive session this is currently a very large
number, but may be subject to the System Manager's
control. In the case of a batch session, it is the
number specified when the batch job was submitted to the
SPOOLR process. A subsystem should normally arrange,
through use of Director procedures DSETIC and DSFI
(TYPE=21), that this session limit is not violated, in
order to initiate the termination under its own control.
5 Not used.
6 A program error has occurred during execution of a
Director procedure. Currently this may be caused by
supplying the wrong number of parameter words to a
procedure, later machine modification levels will enable
this condition to generate a "subsystem program error"
contingency.
7 Illegal call of Director procedure DRESUME: the value of
the LNB parameter is >0 but is not at least 5 words
below the machine register LNB contents at the time of
the call of DRESUME.
8 Illegal call of Director procedure DRESUME: the parameter
LNB specifies Director's contingency stack segment, which
is reserved.
9 Illegal call of Director procedure DRESUME, specifying
resumption of a computation in which a virtual store
error (address error) has just occurred.
10 Illegal call of Director procedure DRESUME, specifying
resumption of a computation when a contingency has not in
fact occurred.
11 A processor stack-switch has failed to occur, perhaps
when a call of Director procedure DRESUME has specified
(through parameter LNB) a segment which is not the normal
or other nominated stack segment.
12 Illegal call of Director procedure DASYNC INH to despatch
(accept) a queued asynchronous contingency, either when
no contingency is queued, or before the subsystem
contingency-handling procedure has indicated, through a
suitable call of Director procedure DRESUME, that it is
able to accept further contingency notifications.
13 An "emergency stop" command has been sent to the process
Director from the machine Operator console. This REASON
for stopping may be printed in addition to one of the
above-specified stopping messages when certain of the
above failures occur during processing using the
subsystem-nominated processor stack segment. In this
case the message printed previously specifies the true
reason for stopping.
14 A "stop" command has been sent from the Operator console
or from DIRECT as part of the System automatic close-down
sequence, or from the interactive communications system
following line or network-processor failure.
FBASE
%externalintegerfn FBASE(%integername LO, HI, %integer FSYS)
This procedure returns the characteristics of an on-line disc.
LO is set to X40 for an ordinary disc and X800 for an IPL disc
HI is set as follows:
EDS 80 X3F1F
EDS 100 X59F3
EDS 160 X8F6F
EDS 200 XB3E7
EDS 640 X24797
FBASE2
%externalintegerfn FBASE2(%integer FSYS, ADR)
This returns the characteristics of an on-line disc in a record
of format DISCDATAF at address ADR
GETAVFSYS
%externalroutine GET AV FSYS(%integername N, %integerarrayname A)
This procedure supplies the numbers of the disc-packs currently
on-line. Array A, which should be declared (0:99), is filled from
A(0), A(1), ..... with as many numbers as there are on-line EMAS
disc-packs, and N is set to the number of entries returned.
By on-line we mean that the disk must be
- mounted
- consistency checked (CCK'd)
- not closing
The IPL disc is always placed first in the list.
PRINTMP
%externalroutine PRINTMP(%integer SEG1, SEG2)
PRINTMP stands for PRINT Master Page tables. The procedure lists
details of the segments SEG1 to SEG2 to DIRLOG. If SEG2 is zero,
then HISEG is used, a value supplied by Supervisor.