Manipulating User records and Indexes
DACCEPT
%externalintegerfn DACCEPT(%string(31)FILE INDEX, FILE, NEWNAME, %integer FSYS) This procedure causes the transfer to the caller's main file index of file FILE belonging to file index FILE INDEX on disc-pack FSYS. The file must previously have been "offered to" the caller of this procedure, using procedure DOFFER. The file is named NEWNAME under its new ownership, but NEWNAME and FILE may be identical names.
DCHECKBPASS
%externalintegerfn D CHECK BPASS(%string(6)USER, %string(63)BPASS, %integer FSYS) 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(%integer N) 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(%string(6)USER, %integer FSYS, UNITS) 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.
DEXECMESS
%externalintegerfn DEXECMESS(%string(6)USER, %integer SACT, LEN, ADR) 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 8 LEN invalid 45 message not readable 61 no process belonging to user
DFILENAMES
%externalintegerfn DFILENAMES(%string(18)FILE INDEX, %record(OINFF)%arrayname INFS, %integername FILENO, MAXREC, NFILES, %integer FSYS, TYPE) 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 file index FILE INDEX on fsys FSYS (or -1 if not known). 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 actually 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 used only for TYPE=1. Filenames are stored in chronological order (by archive date). FILENO is set by the caller to specify the "file-number" from which descriptions are to be returned, zero represents the most recently archived file. (The intention here is to allow the caller to receive subsets of descriptions of a possibly very large number of files.) The format of the records delivered in the array INF is as follows: For on-line files (32 bytes) %string(11)NAME, %integer SP12, KBYTES, %byteinteger ARCH, CODES, CCT, OWNP, EEP, USE, CODES2, SSBYTE, FLAGS, POOL, DAYNO, SP31) and for archived files (40 bytes) %string(11)NAME, %integer KBYTES, %string(8)DATE, %string(6)TAPE, %integer CHAPTER, FLAGS) TAPE and CHAPTER are returned null to unprivileged callers.
DFINFO
%externalintegerfn DFINFO(%string(31)FILE INDEX, FILE, %integer FSYS, ADR) This procedure returns detailed information about the attributes of file 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 will receive 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, POOL, CODES2, %integer SSBYTE, %string(6)OFFER) where NKB the number of Kbytes (physical file size) 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 POOL 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(%string(31)FILE INDEX, FILE, %integer FSYS, ACT, VALUE) 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. 10 ARCH Operation 0 (PRIVILEGED). Shift ARCH byte usage bits (2**3 to 2**6 inclusive) left one place. If A is the resulting value of the ARCH byte, set bit 2**7 if (A>>2)&B'11111' = 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 archive byte to be bottom 8 bits of 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
DFSYS
%externalintegerfn DFSYS(%string(31)FILE INDEX, %integername FSYS) 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(%integer ADR, LEN, %longintegername STB) 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.
DLOWERACR
%externalintegerfn DLOWER ACR(%integer NEWACR) This privileged procedure (currently accessible from ACR 4) enables the calling procedure to acquire a lower ACR (>0) and optionally to acquire PRIV (bit 2**4 set in parameter NEWACR) and/or DGW and ISR in SSR (bit 2**5 set in NEWACR).
DMAIL
%externalintegerfn DMAIL(%record(PARMF)%name P, %integer LEN, ADR) Like DSPOOL but for MAILER, see below
DMESSAGE
%externalintegerfn DMESSAGE(%string(255)USER, %integername LEN, %integer ACT, FSYS, ADR) This is identical to a call of DMESSAGE2 with INVOC = 0
DMESSAGE2
%externalintegerfn DMESSAGE2(%string(255)USER, %integername LEN, %integer ACT, INVOC, FSYS, ADR) 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(%string(31)FILE INDEX, OFFERTO, FILE, %integer FSYS) 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(%string(31)FILE INDEX, USER, %string(8)DATE, %string(11)FILE, %integer FSYS, TYPE, ADRPRM) 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.
DSFI
%externalintegerfn DSFI(%string(31)FILE INDEX, %integer FSYS, TYPE, SET, ADR) 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(18) 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(x16) 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
DSPOOL
%externalintegerfn DSPOOL(%record(PARMF)%name P, %integer LEN, ADR) 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, %integer LEN, ADR, SACT, %string(6)USER) Allows a privileged caller to submit a batch job for user USER.
DTRANSFER
%externalintegerfn DTRANSFER(%string(31)FILE INDEX1, FILE INDEX2, FILE1, FILE2, %integer FSYS1, FSYS2, TYPE) 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(%integer ADR) This privileged procedure unlocks an area of virtual memory, identified by its start virtual address ADR, previously locked by a call of procedure DLOCK.