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.