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.