Manipulating User records and Indexes
DOUT
%externalintegerfn DOUT(%record(PARMF)%name P) This is equivalent to DPON3("",P,0,0,7), causing the message P to be dispatched and the calling process to be suspended until a reply on the process's "sync2" service number is available, it is then received into the record P.
DOUT11
%externalintegerfn DOUT11(%record(PARMF)%name P) This invokes the Supervisor "OUT" no. 11, which causes the message P to be dispatched and the calling process's pages to remain in main store until a reply is available (not one of the sync1, sync2 or async replies referred to above, but one having the DEST field equal to the SRCE field of the outgoing message, the Local Controller having set the left-hand half of SRCE). The reply is received in the record P. This "OUT" number should be invoked only when it is certain that a reply will be received, and in a very short time (e.g. the duration of a single magnetic tape transfer).
DOUT18
%externalintegerfn DOUT18(%record(PARMF)%name P) This invokes the Supervisor "OUT" no. 18, which causes the message P to be dispatched with the following side effects: 1. The local virtual store described by P_P5 and P_P6 (P5 = number of bytes, not exceeding (2**24)-1, P6 = address of start of area) is held in main store until a reply is available corresponding to the dispatched message. 2. Director places the caller's ACR value in bits 4-7 of P_P5 before executing the OUT instruction. 3. The Local Controller replaces the contents of P5 and P6 with the Local Segment Table base and limit for the process, and the ACR value, as required for the first two words of a GPC request block. 4. The caller may in addition set bit 0 of P_P5, in this case the Local Controller marks the page table entry (or entries) describing the store area as "written-to", thus ensuring that the pages are returned to disc when the process is removed from store, if required. (The GPC does not so mark page table entries into which it transfers data, for example.) On return from this routine, the caller should check that P_DEST is not -1, which indicates either a failure to "lock down" the specified area of store or a condition preventing dispatch of the message.
DPOFF
%externalintegerfn DPOFF(%record(PARMF)%name P) This is equivalent to DPON3("",P,0,0,5) with P_DEST set to zero. "No message is generated and the calling process is suspended until a message on the process's "sync1" service number is available, it is then received into the record P. It is not privileged since SS uses it for processes started from the OPER (D/START)
DPON
%externalintegerfn DPON(%record(PARMF)%name P) This is equivalent to DPON3("",P,0,0,6), causing the message P to be dispatched and allowing the calling process to continue processing.
DPON3
%externalintegerfn DPON3(%stringname USER, %record(PARMF)%name P, %integername INVOC, MSGTYPE, OUTNO) This function is used to pass System messages, as referred to in Ref. 10. Definitions: "PON" means send a message "POFF" means take next message, or if none available suspend until one is available "TOFF" means take next message if one available, otherwise set P_DEST=0 and continue execution "sync1", "sync2" and "async" service numbers, mean the "N2", "N3" and "N4" service numbers referred to in Ref. 10. No checking is performed by Director on the parameters passed to this procedure. USER is the 6-character username of a paged process to which the record P is to be sent. (Relevant only when the left- hand half of P_DEST=X'FFFF', see Ref. 10.) P is a record containing the 32-byte System message to be dispatched. (The right-hand halves of DEST and SRCE are unchanged during the process of dispatching the message, the left-hand half of SRCE, and also of DEST when the left- hand half of DEST=X'FFFF', are set by the Local Controller) INVOC is the invocation number of the paged process to which the record P is to be sent. (Relevant only when the left-hand half of P_DEST=X'FFFF', see Ref. 10). MSGTYPE should be set to 1, 2 or 3 to indicate that the message generated is of the sync1, sync2 or async (i.e. N2, N3 or N4) type respectively. (Relevant only when the LH half of P_DEST=X'FFFF'). OUTNO is the "OUT" number which is to be used, valid numbers being 5, 6, 7, 8, 9 or 10 (see Ref. 10). The result of the function is always zero, except when the left hand half of P_DEST=X'FFFF', when it is 61 if there is currently no process owned by the given username, the message has not then been dispatched. P_DEST may be set on return to indicate error conditions, as described in Ref. 10.
DTOFF
%externalintegerfn DTOFF(%record(PARMF)%name P) This is equivalent to DPON2 ("",P,0,6) with P_DEST=0. No message is generated and the calling process always continues to execute. If no message on the process's "sync1" service number was available, P_DEST will still be zero, otherwise P contains the received message.
DBMESSAGE
%externalintegerfn dbmessage(%integername invoc, type) %integer j %record(parmf) class68 j = into(65, "II") -> out %unless j = 0 class68 = 0 class68_dest = x'ffff0009' class68_p1 = (d_invoc << 24) ! (i(1) {type} & X'ffffff') j = dpon3i(d_procuser, class68, i(0) {invoc}, 3 {msgtype - async}, 6 {outno - pon and continue}) out: %result = outof(j) %end; ! dbmessage -----------------------------------------------------------------------
DDISABLETERMINALSTREAM
%externalintegerfn DDISABLE TERMINAL STREAM(%integername xCURSOR, xSTREAM, xREASON) This procedure is used to suspend (REASON=4) or abort (REASON=5) an input (STREAM=0) or output (STREAM=1) operation. For interactive I/O streams, only the "abort" option is likely to be required, and the effect is to send a "control message" through the communications system. For an output stream, as much unprinted data as possible is flushed from the system, for an input stream, similarly any data which has been typed is flushed from the system. In each case the stream is re-initialised and further operations may not be carried out on the stream until it has been re-enabled using the DENABLE TERMINAL STREAM procedure. The DDISABLE TERMINAL STREAM procedure may be called at any time, but is typically invoked in response to an asynchronous "INT:" message generated by the user at the interactive terminal (see the procedure DCLEAR INT MESSAGE, described below, and the contingency handling procedures, described in Section A1.6).
DENABLETERMINALSTREAM
%externalintegerfn DENABLE TERMINAL STREAM(%integername STREAM, MODE, LEVEL, ADR, LEN, CURSOR) When a user logs in to EMAS 2900 from an interactive terminal, a process is created and two interactive streams, one for input and one for output, connect the process to the terminal. (Note that this usage of the word "connect" is distinct from that pertaining to files and virtual memories in EMAS 2900.) The process sends output to its terminal by writing the data into a file. Similarly, input from the terminal is placed by the System in a file. In each case, the file (or part of it) is used by the process and the communications system as a circular buffer. Procedure DENABLE TERMINAL STREAM is used to connect a file into the virtual memory and to specify the circular buffer within the file. ADR is the start of the buffer and LEN is its length (in bytes). STREAM should be set to 0 or 1, indicating input or output respectively LEVEL is not used and should be set to zero. MODE should be set to 1. After this procedure has been successfully executed, the specified circular buffer is available for interactive input or output. After a stream has been disabled or aborted (see procedure DDISABLE TERMINAL STREAM), this procedure may be called again to re-specify a circular buffer, to allow input or output to be resumed. Each EMAS 2900 process may have at most one input and one output stream connected to the communications system.
ACREATE
%externalintegerfn DACREATE(%stringname zINDEX, zTAPE, zFDATE, zFILE, %integername zFSYS, zNKB, zCHAPTER, zTYPE) This procedure is provided for use by the archive program. A new archive index entry is created for USER, giving TAPE, CHAPTER and no-of-Kbytes attributes to be associated with FILE. (Access permission attributes are given to FILE by separate calls of DPERMISSION.) DATE should normally be left null, when the current date will be used.
DMODARCH
%externalintegerfn DMOD ARCH(%stringname xFILE INDEX, xFILE, xDATE, %record(AINFF)%name ENT, %integername xFSYS, xTYPE) This procedure is provided for the System Manager to make amendments to archive index entries. FILE INDEX, FILE, DATE and FSYS determine the entry to be modified. Record ENT has the same format as that supplied by DFILENAMES (TYPE=1). Fields (other than NAME) which differ from those of the specified index entry will be used to update the entry. Bits in TYPE as for 'ADESTROY'.
DNEWARCHINDEX
%externalintegerfn DNEW ARCH INDEX(%stringname xFILE INDEX, %integername xFSYS, xNKB) This privileged procedure creates a new archive index of NKB Kbytes for file index FILE INDEX on disc FSYS. The minimum size allowed is 4 Kbytes, allowing about 80 archive files to be described.
DRESTORE
%externalintegerfn DRESTORE(%stringname xFILE INDEX, xFILE, xDATE, %integername xFSYS, xTYPE) This procedure passes a restore request (if FILE exists on archive storage and is permitted to the caller) to VOLUMS. DATE may be left null, when the most recently archived copy of FILE will be restored. The file is restored into the file owner's index FILE INDEX. TYPE is currently ignored and should be set to zero.
DRETRIEVE
%externalintegerfn DRETRIEVE(%stringname xTAPE, %integername xCHAPTER) Provides an interface to VOLUMS for users to restore files which they have written to tape themselves.
DACCEPT
%EXTERNALINTEGERFN DACCEPT(%STRINGNAME FILE INDEX, FILE, NEWNAME, %INTEGERNAME FSYS) This procedure causes the transfer to the caller's main file index of file FILE belonging to file index FILE INDEX on fsys FSYS. The file must have been previously 'offered' to the caller of this procedure by a call of procedure DOFFER. The file is named NEWNAME in the caller's index, but FILE and NEWNAME may be the same.
DCHECKBPASS
%externalintegerfn D CHECK BPASS(%stringname xUSER, xBPASS, %integername xFSYS) This procedure allows a privileged process to check that a supplied background password corresponds to the version in the index for USER on FSYS. Result is zero if password is correct.
DDELAY
%externalintegerfn DDELAY(%integername xN) This procedure checks that 1 <= N <= 7200. If it is not, result 8 is returned. Otherwise, the process is suspended for N seconds and then returns with result 0
DDONATE
%externalintegerfn DDONATE(%stringname xUSER, %integername xFSYS, xUNITS) Allows a process owner, who has no group holder, to transfer some of his funds to USER on FSYS or, if USER has a group holder, to the group holder.
DEXEC
%externalintegerfn dexec(%stringname xEXEC, %record(parmf)%name P, %integername xLEN, xADR)
DEXECMESS
%externalintegerfn DEXECMESS(%stringname xUSER, %integername xSACT, xLEN, xADR) Checks that the message held at ADR of length LEN is readable and not > 2000 characters. Adds a prefix of **user.bel.date.time to the message then sends it to USER on the SYNC1 service, act X16. Control returns to the sending process immediately, the result being 0 successful E + 129 LEN invalid 45 message not readable 61 no process belonging to user
DFILENAMES
%externalintegerfn DFILENAMES(%stringname xGROUP, %integername xFILENO, xMAXREC, xNFILES, xFSYS, xTYPE, %record(OINFF)%arrayname INFS) This procedure delivers, in the record array INFS (which should be declared (0:n)), a sequence of records describing the on-line files (for TYPE=0), archived files (for TYPE=1) or backed-up files (for TYPE=2) belonging to group GROUP on fsys FSYS (or -1 if not known). The procedure works differently for on-line files (TYPE=0) and off-line files (TYPE>0). For on-line files, the records returned give the names of files and groups belonging to GROUP but not the contents of any of these groups. DFILENAMES must be called again with GROUP set to the name of the subgroup to determine these. Thus FLAG = DFILENAMES(ERCC99,... returns the names of files and groups in ERCC99's main file index. If there is a group called PROJ:, the contents of it can be found with FLAG = DFILENAMES(ERCC99.PROJ:,... The group separator, :, may be omitted if desired. Note that the usage of . and : (USEP and GSEP) is reversed in EMAS3. The UINF fields USEP, USEPCH etc allow utilities to be written which will work for both EMAS2 and EMAS3. MAXREC is set by the caller to specify the maximum number of records he is prepared to accept in the array INFS, and is set by Director to be the number of records returned. NFILES is set by Director to be the number of files actually held on on-line storage or on archive storage, depending on the value of TYPE. FILENO is not normally used. [ If the top bit of MAXREC is set, FILENO is used in the same way as for off-line files, described below ] The format of the records returned in INFS is %string(11)NAME, %integer SPARE1, KBYTES, %byteinteger ARCH, CODES, CCT, OWNP, EEP, USE, CODES2, SSBYTE, flags, PHEAD, DAYNO, GROUP ( 32 bytes ) PHEAD is non-zero if the file or group has been permitted itself to a user or user group. GROUP is non-zero if NAME is the name of a group. For off-line files, TYPE = 1 or 2, GROUP will normally be be the name of a file index eg ERCC99 or ERCC99{UTILS} when all the names in the index will be returned. If an actual group name is given eg ERCC99.PROJ: then only names of the form ERCC99.PROJ:name are returned. MAXREC and NFILES are used in the same way as above. Filenames are stored in chronological order of archive (or backup) date, youngest first. FILENO is set by the caller to specify the "file-number" from which names are to be returned, zero representing the most recently archived file. Thus the caller can conveniently receive subsets of names of a very large number of files. The format of the records returned in INFS is %string(11)NAME, %integer KBYTES, %string(8)DATE, %string(6)TAPE, %halfinteger PREFIX, CHAPTER, %byteinteger EEP, PHEAD, SPARE, COUNT ( 40 bytes ) To allow the full filenames to be reconstructed, the array INFS, in general, contains some records which hold group names. Records refering to filenames can be distinguished by the fact that KBYTES > 0. If PREFIX is > 0, the name is a member of a group whose name is given in the record INFS(PREFIX). The chain can be followed back until a record with a zero PREFIX field is found. Note. MAXREC does not give the number of filenames returned but the number of records in INFS. TAPE and CHAPTER are returned null to unprivileged callers.
DFINFO
%externalintegerfn DFINFO(%stringname xFILE INDEX, xFILE, %integername xFSYS, %stringname xS, %integerarrayname xI) This procedure returns detailed information about the attributes of file or group FILE belonging to file index FILE INDEX on disc-pack FSYS, in a record written to address ADR. A caller of the procedure having no permitted access to the file receives an error result of 32, as though the file did not exist. The format of the record returned is: %recordformat DFINFOF(%integer NKB, RUP, EEP, APF, USE, ARCH, FSYS, CONSEG, CCT, CODES, %byteinteger SP1, DAYNO, SP2, CODES2, %integer SSBYTE, %string(6)OFFER) where NKB the number of Kbytes (physical file size) zero indicates a group name RUP the caller's permitted access modes EEP the general access permission APF 1-4-4 bits, right-justified, giving respectively the Execute, Write and Read fields of APF, if the file is connected in this VM USE the current number of users of the file ARCH the value of the archive byte for the file (see procedure DFSTATUS) FSYS disc-pack number on which the file resides CONSEG the segment number at which the file is connected in the caller's VM, zero if not connected CCT the number of times the file has been connected since this field was last zeroed (see procedure DFSTATUS) CODES information for privileged processes SP1 spare DAYNO Day number when file last connected SP2 spare CODES2 information for internal use SSBYTE information for the subsystem's exclusive use OFFER the username to which the file has been offered, otherwise null
DFSTATUS
%externalintegerfn DFSTATUS(%stringname xFILE INDEX, xFILE, %integername xFSYS, xACT, xVALUE) This procedure is supplied to enable the attributes of file FILE belonging to file index FILE INDEX on disc-pack FSYS to be modified, as follows. Parameter VALUE is for use by the archive/backup program (ACT=13), and by the subsystem (ACT=18), otherwise it should be set to zero. ACT ACTION 0 HAZARD Remove CHERISHed attribute 1 CHERISH Make subject to automatic System back-up procedures Note: If the file is one of SS#DIR, SS#OPT or SS#PROFILE then the 'archive-inhibit' bit is also set. Similarly, the 'archive-inhibit' bit is cleared by HAZARD for these files. 2 UNARCHIVE Remove the "to-be-archived" attribute 3 ARCHIVE Mark the file for removal from on-line to archive storage. 4 NOT TEMP Remove the "temporary" attribute. 5 TEMPFI Mark the file as "temporary", that is, to be destroyed when the process belonging to the file owner stops (if the file is connected at that time), or at system start-up. 6 VTEMPFI Mark the file as "very temporary", that is, to be destroyed when it is disconnected from the owner's VM. 7 NOT PRIVATE May now be written to magnetic tape either for back-up or archive. May be called only by privileged programs. 8 PRIVATE Not to be written to magnetic tape either for back-up or archive. May be called only by privileged programs. 9 SET CCT Set the connect count for the file to VALUE. 11 ARCH Operation 1 (PRIVILEGED). Set currently-being-backed-up bit (bit 2**1 in ARCH byte), unless the file is currently connected in write mode, when error result 52 is given. 12 ARCH Operation 2 (PRIVILEGED). Clear currently-being-backed-up bit (2**1) and has-been-connected-in-write-mode bit (2**0). 13 ARCH Operation 3 PRIVILEGED). Set the ARCH byte to VALUE and clear the UNAVAilable bit in CODES 14 ARCH Operation 4 (PRIVILEGED). Clear the UNAVAilable and privacy VIOLATed bits in CODES. Used by the back-up and archive programs when the file has been read in from magnetic tape. 15 CLR USE Clear file use-count and WRITE-CONNECTED status (PRIVILEGED). 16 CLR NOARCH Clear archive-inhibit bit in CODES. PRIVILEGED - for System 17 SET NOARCH Set archive-inhibit bit in CODES. Library use 18 SSBYTE Set SSBYTE to be the bottom 8 bits of VALUE (byte for a subsystem's exclusive use). 19 ARCH Operation 5 (PRIVILEGED). Set the WRCONN bit in CODES2. Used to prevent any user connecting the file in write mode during back-up or archive. 20 ARCH Operation 6 (PRIVILEGED). Clear the WRCONN bit in CODES2. Used when back-up is complete. 21 DAYNO Set DAYNO to bottom 8 bits of VALUE 22 MONITOR BIT Set non zero to monitor connects of this file
DFSYS
%externalintegerfn DFSYS(%stringname xFILE INDEX, %integername xFSYS) This procedure is used to determine on which disc pack a user's FILE INDEX resides. If FSYS is set to -1 before the procedure is called, it is set with the first disc-pack number on which FILE INDEX is found. If FSYS is set non-negative, only that disc-pack number is searched. If FILE INDEX is not found, FSYS is unchanged.
DLOCK
%externalintegerfn DLOCK(%integername xADR, xLEN, xSTB0, xSTB1) This privileged procedure is used exceptionally to lock down areas of virtual memory in main store for short durations. ADR and LEN determine the extent of virtual storage to be made resident. On successful return STB contains a word-pair which may be used as a local segment table base for specially created local segment and page tables describing the locked-down area. This word-pair may be passed, for example, to the GPC routine to achieve a "private" data transfer to or from the locked-down area. Up to 3 separate non-overlapping areas may be simultaneously locked by repeated calls of this procedure. Exceptionally it may not be possible for the locking to be effected, for example if the System is unusually busy or if little main store is available, in this case result 68 is given.
DMAGCLAIM
%externalintegerfn DMAG CLAIM(%stringname xTSN, %integername xSNO, xTYPE, xMODE) The magnetic tape volume labelled TSN is either claimed (TYPE=0) or released (TYPE=1). MODE should be set to 1 to allow read access to the tape, 2 if write access is required, or 3 for either read or write access. If a CLAIM call is successful, SNO is set with a number to be used in subsequent calls of DMAG IO. If TSN is null in a RELEASE call, then all claimed tapes are released. Possible error results from Volumes: 101 Bad parameters 102 Duplicate request 103 Request lists full 104 Volume not available (Operators have said "V/NO <volid>") 105 Volume request list full 106 No tapes in tape list (A, B, S or E) 107 Device not claimed when a "release" is done. 73 ("Should not occur") Software fault. 90 Too many tapes requested. 92 Interactive use of tapes not allowed.
DMAGIO
%externalintegerfn DMAG IO(%integername xFLAG, xCONTROL, xLEN, xTYPE, xSNO, xADR) The parameter TYPE determines the action of the procedure: TYPE = 0 erase 1 read 2 write 3 check-write (not implemented) 4 check-read (no data transfer) 5 private chain (not implemented) 6 rewind to BT 7 spare 8 file position 9 tape position 10 write tape-mark SNO should be set with the value returned by a previous CLAIM (procedure DMAG CLAIM). ADR and LEN specify the area from or to which data is to be transferred (if relevant). In the case of TYPE = 1 (read) LEN is set on return to be the number of bytes transferred. Bits in parameter CONTROL are used to specify detailed actions by the tape handler routine, as follows: 2**0 - 2**1 suppress error re-try 2**2 ignore short-block indication 2**3 ignore long-block indication Bits in CONTROL on return are used to indicate the occurrence of conditions during execution of a request, as follows: 2**0 short-block indication 2**1 long-block indication These bits will not be set on return if the respective bits for "ignore short/long-block indication" were specified in the request. REPLY FLAG (valid when the result of the function is zero) is set to zero for a successful operation, or 1 failure (parity etc.) 2 request rejected 4 beginning of tape, end of tape or unexpected tape mark found, but operation otherwise successful TYPE=8 For request TYPE=8 (file position), LEN specifies the number of blocks to be skipped: negative means backwards, positive forwards, zero is invalid. If a tape-mark is found (REPLY FLAG=4) then a skip back of one block is performed before the reply is given. It is thus impossible to pass a tape-mark except by the use of a "tape position" request. TYPE=9 For request TYPE=9 (tape position), LEN is the number of (notional) files to be skipped, and CONTROL is the number of tape-marks in a notional file, CONTROL must be positive. If LEN is negative the skip is backwards, if positive then it is forwards, zero is invalid. CONTROL*LEN tape-marks are skipped. A backwards skip will stop at BT. A forward skip will stop if the first block within a (notional) file is a tape-mark, the tape will then be positioned before the tape-mark and REPLY FLAG=4 will be returned. Thus if CONTROL=1 and LEN="very large", the tape will be positioned between the first double tape-mark encountered.
DMAIL
%externalintegerfn DMAIL(%record(PARMF)%name P, %integername xLEN, xADR) Like DSPOOL but for MAILER, see below
DMESSAGE
%externalintegerfn DMESSAGE(%stringname xUSER, %integername xLEN, xACT, xINVOC, xFSYS, xADR) ACT=0 Delivers to ADR the next message sent to this user process. LEN should be previously set to the maximum length you are prepared to accept, it is set by the procedure to the number of bytes returned. LEN will be set to zero if no further messages are available. ACT=1 Sends message (ADR, LEN) to USER on FSYS. INVOC is the invocation number of the paged process to which the message is to be notified. Currently LEN is restricted to 2000 bytes. Result 61 from this call means that a process belonging to USER is not currently present (but the message goes into his file anyway). ACT=2 Determines whether USER on FSYS currently has a process of invocation number INVOC. Result 61 if not, else zero.
DOFFER
%externalintegerfn DOFFER(%stringname xFILE INDEX, xOFFERTO, xFILE, %integername xFSYS) This procedure causes file FILE belonging to file index FILE INDEX on disc-pack FSYS to be marked as being "on offer" to user OFFERTO. The file may not be connected in any virtual memory either at the time of the call of this procedure or subsequently while the file is on offer. The procedure DACCEPT is used by user OFFERTO to accept the file. A file may be on offer to at most one user. An offer may be withdrawn by calling this procedure with OFFERTO set as a null string.
DPERMISSION
%externalintegerfn DPERMISSION(%stringname xFILE INDEX, xUSER, xDATE, xFILE, %integername xFSYS, xTYPE, xADRPRM) This procedure allows the caller to set access permissions, or specific preventions, for file connection to individual users, groups of users or to all users to file FILE belonging to file index FILE INDEX. It also allows a caller to determine the modes (if any) in which he may access the file. TYPE determines the service required of the procedure: TYPE Action 0 set OWNP (not for files on archive storage) 1 set EEP 2 put USER into the file list (see "Use of file access permissions", below) 3 remove USER from file list 4 return the file list 5 destroy the file list 6 put USER into the index list (see "Use of file access permissions", below) 7 remove USER from the index list 8 return the index list 9 destroy the index list 10 give modes of access available to USER for FILE 11 set EEP for the file index as a whole TYPEs 0 to 9 and 11 are available only to the file owner and to privileged processes. For TYPE 10, ADRPRM (see below) should be the address of an integer into which the access permission of USER to the file is returned. If USER has no access to the file, error result 32 will be returned from the function, as though the file did not exist. If the file is on archive storage, TYPE should be set to 16 plus the above values to obtain the equivalent effects. ADRPRM is either the permission being attached to the file, bit values interpreted as follows: all bits zero prevent access 2**0 allow READ access 2**1 allow WRITE access not allowed for files 2**2 allow EXECUTE access on archive storage 2**3 If TYPE = 0, prevent the file from being destroyed by e.g. DDESTROY, DDISCONNECT (and destroy). or, except for type 10, it is the address of an area into which access permission information is to be written %recordformat(%integer BYTES RETURNED, OWNP, EEP, SPARE, %record(EF)%array INDIV PRMS(0:15)) and EF is %recordformat EF(%string(6)USER, %byteinteger PERMISSION) where: BYTES indicates the amount of data returned. RETURNED OWNP is the file owner's own permission to the file, or the requesting user's "net" permission if the caller of the procedure is not the file owner (see "Use of file access permissions", below). EEP is the general (all users) access permission to the file ("everyone else's permission"). UPRM The PERMISSION values in the sub-records are those for the corresponding users or groups of users denoted by USER. Up to 16 such permissions may be attached to a file. Use of file access permissions The general scheme for permissions is as follows. With each file there are associated: OWNP the permission of the owner of the file to access it EEP everyone else's permission to access it (other than users whose names are explicitly or implicitly attached to the file) INDIV PRMS a list of up to 16 items describing permissions for individual users, e.g. ERCC00, or groups of users, e.g. ERCC?? (specifying all usernames of which the first four characters are "ERCC") In addition, a user may attach a similar list of up to 16 items to his file index as a whole and an EEP for the file index. These permissions apply to any file described in the index along with those attached to that particular file. In determining the mode or modes in which a particular user may access a file, the following rules apply: 1. If the user is the file owner then OWNP applies. 2. Otherwise, if the user's name appears explicitly in the list for the file, the corresponding permission applies. 3. Otherwise, if the user's name is a member of a group of users represented by a list item for the file, the corresponding permission applies. 4. Otherwise EEP applies if greater than zero. 5. Otherwise, if the user's name appears explicitly in the list for the index, the corresponding permission applies. 6. Otherwise, if the user's name is a member of a group of users represented by a list item for the index, the corresponding permission applies. 7. Otherwise, everybody else's permission to the file index applies. In the event of a user's name appearing more than once (implicitly) within groups specified in a single list, the actual list item to be selected to give the permission should be regarded as indeterminate.
DSECURE
%externalintegerfn DSECURE(%stringname FILE INDEX, %integername FSYS, SET, %record(securef)%name SECURE)
DSFI
%externalintegerfn DSFI(%stringname xFILE INDEX, %integername xFSYS, xTYPE, xSET, %stringname xS, %integerarrayname xI) This procedure is used to set or read information in file index FILE INDEX (or user record in some cases) on disc-pack FSYS. TYPE specifies which data item is to be referenced (see list below). SET must be 1 to write the data item into the index, or 0 to read the item from the index. ADR is the address of an area, which must be available in write or read mode, to or from which the data item is to be transferred. TYPE Data item Data type & size 0 BASEFILE name (the file to be connected and entered at process start-up) string(18) 1 DELIVERY information (to identify string(31) slow-device output requested by the index owner) 2 CONTROLFILE name (a file for use by the subsystem for retaining control information) string(31) 3 ADDRTELE address and telephone number of user string(63) 4 INDEX USE (may not be reset) Gives (in successive integers from ADR): a) number of files b) number of file descriptors currently in use c) number of free file descriptors d) index size (Kbytes) e) Number of section descriptors (SDs) f) Number of free section descriptors g) Number of permission descriptors (PDs) h) Number of free permission descriptors integer(x8) 5 Foreground and background passwords (reading is a privileged operation), a zero value means "do not change" integer(x2) 6 Date last logged-in: (Y-70)<<9 ! (M<<5) ! D and date last started (non-interactive) (same) (may not be reset) integer(x2) 7 ACR level at which the process owning this index is to run (may be set only by privileged processes) integer 8 Director Version (may be set only by privileged processes) integer(x2) 9 ARCHIVE INDEX USE (may not be reset) Gives (in successive integers from ADR): a) number of archived files b) number of archived Kbytes c) number of backed-up files d) number of backed-up Kbytes e) index size (Kbytes) f) number of file descriptors g) number of free file descriptors h) number of permission descriptors i) number of free permission descriptors integer(x9) 10 Stack size (Kbytes) integer 11 Limit for total size of all files in disc storage (Kbytes) (may be set only by privileged processes integer 12 Maximum file size (Kbytes) (may be set only by privileged processes) integer 13 Current numbers of interactive and batch processes, respectively, for the user (may not be reset) integer(x2) 14 Process concurrency limits (may be set only by privileged processes). The three words denote respectively the maximum number of interactive, batch and total processes which may be concurrently running for the user. (Setting the fields to -1 implies using the default values, currently 1, 1 and 1.) integer(x3) 15 When bit 2**0 is set, TELL messages to the index owner are rejected with flag 48. integer 16 Set Director monitor level (may be set only by privileged processes) integer(x2) 17 Set SIGNAL monitor level (may be set only by privileged processes) integer 18 Initials and surnames of user (may be set only by privileged processes) string(31) 19 Director monitor file string(11) 20 Thousands of instructions executed, interactive and batch modes (may be reset only by privileged processes) integer(x2) 21 Thousands of instructions executed (current session only) integer 22 Thousands of instructions executed in Director procedures (current process session only) (may not be reset) integer 23 Page-turns, interactive and batch modes (may be reset only by privileged processes) integer(x2) 24 Page-turns (current process session only) integer 25 Thousands of bytes output to slow-devices (local or remote) (may be reset only by privileged processes) integer 26 Thousands of bytes input from slow-devices (local or remote) (may be reset only by privileged processes) integer 27 Milliseconds of OCP time used, interactive and batch modes (may be reset only by privileged processes) integer(x2) 28 Milliseconds of OCP time used (current session only) integer 29 Seconds of interactive terminal connect time (may be reset only by privileged processes) integer 30 No. of disc files, total disc Kbytes, no. of cherished files, total cherished Kbytes, no. of temporary files, total temporary Kbytes (cannot be reset) integer(x6) 31 No. of archive files, total archive Kbytes integer(x2) 32 Interactive session length in minutes integer 0 or 5 <= x <= 240 33 Funds integer 34 The FSYS of the Group Holder of the index integer owners funds, if he has a GH 35 Test BASEFILE name string(18) 36 Batch BASEFILE name string(18) 37 Group Holder of funds for scarce resources string(6) 38 Privileges integer 39 Default LP string(15) 40 Dates passwords last changed integer(x2) (may not be reset) 41 Password data integer(x8) 42 Get accounting data integer(x17) 43 Mail count integer (may be reset only by privileged processes) 44 Supervisor string(6) 45 Secure record about 512 bytes 46 Gateway access id string(15) 47 File index attributes byte 48 User type byte 49 Rule1 - special control field string(18)
DSPOOL
%externalintegerfn DSPOOL(%record(PARMF)%name P, %integername xLEN, xADR) This procedure transmits a spool request message to the Spooler process. ADR and LEN describe the text to be transmitted. The result of the function is 61 if the Spooler process is not available, or 0 if the request was successful. If Spooler was available, the record P contains reply information from Spooler on return. P1 is zero for a successful request, and P2 gives the Spooler's unique identifier for the document. Error messages from Spooler, in P1, are in the range 201-236, as follows: 201 Bad Parameters 202 No Such Queue 203 Queue Full 204 All Queues Full 205 Not In Queue 206 User Not Known 207 No Files In Queue 208 File Not Valid 209 No Free Document Descriptors 210 Not Enough Privilege 211 Invalid Password 212 Invalid Filename 213 Invalid Descriptor 214 Command Not Known 215 Invalid Username 216 Username Not Specified 217 Not Available From A Process 218 Invalid Length 219 Document Destination Not Specified 220 Invalid Destination 221 Invalid Source 222 Invalid Name 223 Invalid Delivery 224 Invalid Time 225 Invalid Priority 226 Invalid Copies 227 Invalid Forms 228 Invalid Mode 229 Invalid Order 230 Invalid Start 231 Invalid Rerun 232 Invalid Tapes 233 Invalid Discs 234 Invalid Start After 235 Invalid Fsys 236 SPOOLR File Create Fails In the event of a syntax error in the message, P3 is the offset from ADR of the offending character.
DSUBMIT
%externalintegerfn DSUBMIT(%record(PARMF)%name P, %integername xLEN, xADR, xSACT, %stringname xUSER) Allows a privileged caller to submit a batch job for user USER.
DTRANSFER
%externalintegerfn DTRANSFER(%stringname xFILE INDEX1, xFILE INDEX2, xFILE1, xFILE2, %integername xFSYS1, xFSYS2, xTYPE) This procedure transfers FILE1 belonging to file index FILE INDEX1 on FSYS1 to the ownership of file index FILE INDEX2 on FSYS2 under name FILE2. TYPE = 0 'accepts' a file which has been 'offered'. This call is non-privileged. 1 a privileged call to transfer a file. 2 like 1, but, in addition, forces a re-allocation of the disc space. 3 a privileged call to copy the file. 4 as 3 but works even when file connected W (for test purposes)
DUNLOCK
%externalintegerfn DUNLOCK(%integername xADR) This privileged procedure unlocks an area of virtual memory, identified by its start virtual address ADR, previously locked by a call of procedure DLOCK.