──────────────────────────────────────────────────────────────────────────
TOOLS
Disk/Conference Management System
TOOLSRUN
Control File Language Reference
Service Level 6 Version 6.8
Document Number TOOLS-002-03
──────────────────────────────────────────────────────────────────────────
┌─── Production of this document ────────────────────────────────────┐
│ │
│ This document was prepared and formatted using the BookMaster• │
│ document markup language. │
│ │
└────────────────────────────────────────────────────────────────────┘
Fifth Edition, January 30th, 1995
This is the fifth edition of this document, and applies to the
TOOLSRUN EXEC, Version 6.8, Service Level 6.
Cover art by Bill Trautman and Scott Tietjen, using CUADRAW.
© Copyright International Business Machines Corporation 1995
All Rights Reserved
This is the first document that has listed everything you can do in a
Toolsrun control file. It is a reference document only, and is not
intended to be used as a tutorial. There are some very simple examples
that could be used to get you started, but until a tutorial is available,
you should ask for help from others who are familiar with Toolsrun. See
"Getting Help" in topic BACK_1.
The TOOLS and TOOLSRUN programs are owned by the IBM ISSC Solution Center
- Northeast. These programs and supporting documentation are provided
as-is. We do not warrant uninterrupted or error free operation of the
programs. We have no obligation to provide service, defect correction, or
any maintenance for the programs or documentation. We have no obligation
to supply any program or documentation updates or enhancements to you even
if such are or later become available.
TOOLSRUN EXEC was developed by Mike Cowlishaw and is maintained by Bob
Cronin. TOOLSCTL SCRIPT is maintained by Scott Hightower.
If you need to report a problem or have a question regarding TOOLSRUN EXEC
or this documentation, you should append it to the TOOLS FORUM on IBMVM.
If you have a suggestion for an enhancement, you should append it to the
TOOLWISH FORUM on IBMVM.
You can use the TOOLS EXEC to access the IBMVM disk. The disk name is
IBMVM, managed by IBMVM at KGNVMC.
If you have a problem with TOOLSRUN and are not running the most recently
distributed service level, you will be required to upgrade to the latest
level and demonstrate that the problem still occurs before it will be
actively investigated.
Book Cover COVER
Notices NOTICES
Edition Notice EDITION
Preface PREFACE
Maintenance of TOOLSRUN PREFACE.1
Table of Contents CONTENTS
Figures FIGURES
Summary of Changes CHANGES
Fifth Edition CHANGES.1
Fourth Edition CHANGES.2
Third Edition CHANGES.3
Second Edition CHANGES.4
Toolsrun Control File 1.0
General Requirements for the Control File 1.1
Major Sections of the Control File 1.2
Global Section 1.2.1
Disk Sections 1.2.2
Include Files 1.2.3
Disk Control Files 1.2.4
Sample Control File 1.2.5
Authorization algorithm 1.3
Control Verbs Organized by Application 2.0
Control File Verbs Used in the Global Section 2.1
Control File Verbs Used in each Disk Section 2.2
Verbs Used for Controlling the Disk 2.2.1
Disk Networking Verbs 2.2.2
Composite Authorization Verbs 2.2.3
Primitive Authorization Verbs 2.2.4
Comprehensive List of All Authorization and Control Verbs 3.0
Examples of Syntax Notation 3.1
ACCESSER 3.2
ADDER 3.3
ALTERNATE 3.4
APPEND 3.5
APPENDER 3.6
BADGMT 3.7
BATCH-CANCEL 3.8
BATCH-QUERY 3.9
BATCH-RELEASE 3.10
CLEAN-ALL 3.11
CLEAN-ALLSAFE 3.12
CLEAN-BACKUP 3.13
CLEAN-BACKUPSAFE 3.14
CLEAN-ERASABLE 3.15
CLEAN-NAMES 3.16
CLEAN-SAFE 3.17
COMMAND 3.18
COPIER 3.19
COPY (forward successful changes to shadows) 3.20
COPY (group COPY statements by *LIST processor) 3.21
CREATE 3.22
CREATE-OWNED 3.23
DISK 3.24
DISK-NOCOPY 3.25
DISK-SHUTDOWN 3.26
DISK-SHUTPERM 3.27
DISK-START 3.28
EQUATE DISK 3.29
EQUATE NODE 3.30
EQUATE VERB 3.31
ERASE 3.32
GET 3.33
GETTER 3.34
HELP 3.35
HIDE 3.36
HISTORY 3.37
HISTORY MODE0 3.38
INCLUDE 3.39
INFORM 3.40
INFORM-ALL 3.41
INFORM-COP 3.42
INFORM-EXC 3.43
INFORM-NEW 3.44
INFORM-REF 3.45
INFORM-SUB 3.46
INFORM-UPD 3.47
INSERT-HEADER 3.48
INTERVAL 3.49
LIMITS 3.50
LIST 3.51
LOCAL 3.52
LOCK 3.53
MASTER 3.54
MODIFY 3.55
MODIFY-HEADER 3.56
MSG 3.57
NEARBY 3.58
NEWOWN 3.59
newverb 3.60
NOTIFY 3.61
OPTION ADISKFULL 3.62
OPTION BACKUP 3.63
OPTION BATCH 3.64
OPTION CLEAN 3.65
OPTION CLEANFIRST 3.66
OPTION CLEANFULL 3.67
OPTION CLEANIDLE 3.68
OPTION CLEANSTART 3.69
OPTION DISKFULL 3.70
OPTION FILE 3.71
OPTION FORVERBS 3.72
OPTION GMTTIME 3.73
OPTION INDEX 3.74
OPTION LOCALTIME 3.75
OPTION LOCALNAMES 3.76
OPTION NETAUDIT 3.77
OPTION NOBACKUP 3.78
OPTION NOBATCH 3.79
OPTION NOCLEAN 3.80
OPTION NOCLEANFULL 3.81
OPTION NOFILE 3.82
OPTION NOFORVERBS 3.83
OPTION NOINDEX 3.84
OPTION NOLOCALNAMES 3.85
OPTION NONETAUDIT 3.86
OPTION NOORDER 3.87
OPTION NOSUBSEXPIRE 3.88
OPTION NOWARNOWNER 3.89
OPTION ORDER 3.90
OPTION SUBSEXPIRE 3.91
OPTION UNSAFE 3.92
OPTION WARNOWNER 3.93
OWN 3.94
OWNER 3.95
PACKAGER 3.96
PACKFILE-ERASE 3.97
PACKFILE-OWN 3.98
PEER 3.99
PLACE 3.100
PRIV 3.101
PRUNE 3.102
QUERY-DISK 3.103
QUERY-FILE 3.104
QUERY-INFORM 3.105
REFRESH 3.106
REGISTER 3.107
RENEW 3.108
REGRESS 3.109
REPLACE 3.110
REPLACER 3.111
REQUESTS 3.112
REQUESTS MODE0 3.113
REROUTE 3.114
REROUTER 3.115
RESPONSE 3.116
ROUTE 3.117
SERVANT 3.118
SET-ADDRESS 3.119
SET-DESCRIPTION 3.120
SET-FILE 3.121
SET-MODE 3.122
SOURCE 3.123
SUMMARY 3.124
SYSTEM 3.125
TITLE 3.126
TRACE 3.127
UNINFORM 3.128
UNLOCK 3.129
UPDATE 3.130
VOTE 3.131
Appendix A. TOOLSRUN Exit Files A.0
Sequence of exits following receipt of a request A.1
TOOLDAY EXEC A.2
When Called A.2.1
Information Passed A.2.2
Information Returned A.2.3
Action After Return A.2.4
TOOLDECK EXEC A.3
When Called A.3.1
Information Passed A.3.2
Information Returned A.3.3
Action After Return A.3.4
TOOLDISK EXEC A.4
When Called A.4.1
Information Passed A.4.2
Information Returned A.4.3
Action After Return A.4.4
TOOLEXIT EXEC A.5
When Called A.5.1
Information Passed A.5.2
Information Returned A.5.3
Action After Return A.5.4
TOOLEXIT TIMES A.6
When Used A.6.1
Format A.6.2
TOOLEXIT TIMES versus TOOLDAY and INTERVAL A.6.3
TOOLFILE EXEC A.7
When Called A.7.1
Information Passed A.7.2
Information Returned A.7.3
Action After Return A.7.4
TOOLMSG EXEC A.8
When Called A.8.1
Information Passed A.8.2
Information Returned A.8.3
Action After Return A.8.4
Appendix B. Miscellaneous Topics B.0
Message Levels B.1
Reader Classes B.2
Toolsrun Return Codes B.3
Toolsrun Use of GLOBALV B.4
Toolsrun and SFS B.5
Differences B.5.1
Limitations B.5.2
Effects of ... B.6
CP Tag Information B.6.1
FORM B.6.2
TOOLS Library BIBLIOGRAPHY
Getting Help BACK_1
1. Sample Control File - Global Section 1.2.5
2. Sample Control File - One Disk Section 1.2.5
3. Control verbs used in the global section of the control file 2.1
4. Verbs used in each disk section to control disk operation 2.2.1
5. Verbs used to set up networks of duplicate disks 2.2.2
6. Composite authorization verbs 2.2.3
7. Primitive authorization verbs 2.2.4
| 8. TOOLS and TOOLSRUN Publications BIBLIOGRAPHY
Changes from the previous edition are marked with vertical bars (|) in the
margins.
| This version of the document has been brought up to date for TOOLSRUN
| version 6.8, service level 6.
| The following topics had significant changes:
| • OPTION BATCH (self release permitted)
| • OPTION SUBSEXPIRE (extensive rewording to clarify)
| • SFS (general notes throughout document, expanded SFS topic)
| Numerous minor corrections and clarifications were also made.
This version of the document has been brought up to date for TOOLSRUN
version 6.8, service level 2.
Important Notice:
1. Toolsrun 6.8.2 will, by default, begin subscription expiration. While
it is possible to suppress this, it is strongly recommended that you
do not do so. One of the most significant avoidable costs is the
handling of obsolete userids, and processing of unwanted
subscriptions.
2. It is strongly recommended that you take advantage of the new OPTION
BATCH, at least on disks that receive large numbers of GET requests
over the network. When combined with list processing, network costs
are reduced.
The following significant changes and corrections were made:
• New verbs and syntax changes:
- Disk
-- Default of None for password parameter
-- Dir keyword to indicate SFS directory
- Batch-Cancel, Batch-Query and Batch-Release
- Option Batch and Option NoBatch
- Option NetAudit and Option NoNetAudit
- Option SubsExpire and Option NoSubsExpire
- Renew
- ReRouter disk parameter
• Specific authorizations and other effects described for:
- Copier
- Copy
- Master
- Peer
- Rerouter
- Servant
- Source
• Expanded descriptions for:
- Clean - consolidated the descriptions of backup files, erasable
files and the cleaning process, cross referenced under related
verbs.
- Limits - define GET and REFRESH
- Option WarnOwner - include a list of the actions that normally
generate warnings to the owner.
- Copier, Master, Peer and Servant - imply Rerouter.
- Source - Added another example.
- Appendix A (Exits) - Note EXECLOAD of exits.
- TOOLEXIT TIMES:
-- Corrected the string passed to TOOLEXIT EXEC.
-- Note recognition of TOOLSRUN BATCH RELEASE.
- Appendix B - added new topics:
-- Toolsrun Return Codes
-- SFS Support
-- Tag and Distribution Code Effects
In addition, several minor changes were made for clarity.
This version of the document has been declassified and prepared for
external release.
The following changes and corrections were made:
LOCAL MSGHDR and RSCS keywords documented.
MASTER Not allowed in disk control file.
INFORM Added note about informational messages and expanded the
defaults to cover all cases.
PEER Not allowed in disk control file.
SERVANT Not allowed in disk control file.
SOURCE Not allowed in disk control file.
In addition, a couple of minor typographical errors were corrected.
This is a revised version of TOOLSRUN 6.0 Control File Language Reference
by Louis M. Puster, Jr..
This version of the document has been brought up to date for TOOLSRUN
version 6.6, service level 11., expanded and reformatted. Appendices have
been added, describing the various TOOLSRUN exit files that may be used
and various miscellaneous topics.
When Toolsrun is first started, a control file is read that establishes
what disks are to be maintained and many factors that control options on
how this is to be done.
This document first describes the general requirements of the control
file, then presents a number of tables (starting on page 2.0) that are
intended to enable you to select the desired control file statements you
will need. Following the tables is a comprehensive alphabetical list
(starting on page 3.0) of all control file statements with syntax and
description. Redundancy is used to reduce cross-referencing.
The general requirements for the control file are:
The name of the control file may be specified with the CONTROL option
| of TOOLSRUN EXEC. (See TOOLSRUN Administrators Guide for Toolsrun
| invocation syntax.) If it is not specified, TOOLSRUN will search
first for TOOLSRUN CONTROL and then for thisnode CONTROL where
thisnode is the nodeid of the service machine, as determined by the
CMS Identify command.
Control file verbs and keywords may be entered in mixed case.
Control files should have a record format of V to save space.
Control statements may not be continued from one line to the next.
However, certain control file verbs are cumulative; repeating them
effectively continues them:
| • Badgmt
• Equate Node
• Equate Verb
• Help
• Nearby
• Any authorization verb using ONLY.
Blank lines will be ignored.
Lines starting with an asterisk (*) are regarded as comments and
ignored.
All characters to the right of a semicolon (;) in a control statement
are regarded as a comment and ignored.
There must always be at least one System statement.
Beyond these requirements, there are a few general recommendations.
(There are also some recommendations specific to the global and to the
disk sections, described below.) Mainly, it pays to remember that you
will not always be the one reading or altering the control file, and that
you will not always be able to figure out what you had in mind when you
wrote something. Therefore, make liberal use of comments to explain what
is going on; use blank lines and mixed case to enhance readability; and
make logical groupings of similar statements to maximize your chances of
finding what you are looking for. Spelling out options, instead of using
abbreviations, will help the next person understand what is going on.
Finally, while Include has some specific uses for which it is really
great, it does make reading a bit harder.
The control file has two major sections:
• The group of all statements up to, but not including, the first Disk
statement is called the global section. This section controls options
for Toolsrun in general, and also defaults for parameters that apply
to all the disks.
• The group of all statements from a Disk statement up to, but not
including the following one (if any) is called the disk section for
one specific disk. There will be one disk section for each disk to be
maintained.
Optionally, other files may be included into the control file, as if their
statements were part of it. There are two ways to do this:
• The Include statement names a file whose contents are treated as if
they replaced the statement.
• Option File enables a diskname CONTROL file. This file resides on a
maintained disk, and has a filename the same as diskname and a
filetype of CONTROL. If it exists, its contents are treated as if
they appeared at the end of the current disk section.
There must always be a System statement; therefore, there is always a
global section. The global section contains statements that affect the
operation of the whole system, including alteration of defaults.
The following verbs are used only in the global section:
Alternate BadGMT Equate Disk Equate Node
Equate Verb Interval Local Msg
Nearby Option AdiskFull Reroute Route
System
The following verbs may not appear in the global section:
Copy Copier Disk Master
Peer Servant Source
The following verbs have different meanings when used in the global
section and when used in a disk section:
Help Notify
The Include statement may be used in either the global section or a disk
section (but not a diskname CONTROL file) and does the same thing in
either case.
All other verbs may appear in the global section, and will alter the
normal defaults for the disk sections.
There is no particular order required of statements within the global
section. However, there are a couple of strong recommendations. These
are based on the philosophy that if anything can go wrong, it will. So,
arrange the control file in a way that maximizes your chances of finding
out by a note or message, rather than someone noticing that TOOLSRUN is
dead.
• Put at least one System statement before any other statement
(especially Include). If anything goes wrong during startup, at least
this one person will be told about it.
• The first System statement should not use an equated node. In order
to tell this person that it choked on the second statement, TOOLSRUN
must have a real node and userid to contact.
• Have Notify statements, and group them close to the top. These are
the people who should hear about catastrophes. The first System is
your failsafe, but grouping these near the top will ensure that you
and your backup(s) will find out about nearly anything that can go
wrong.
• If a Local statement is required (e.g. because CMS IDENTIFY doesn't
work or doesn't return the correct RSCS userid), put it close to the
top, also. This is particularly important if the information on this
statement would be required to send a message to the first system
person or to the notify people.
Beyond this, the general guidelines apply, particularly as to logical
groupings. As a system grows in complexity, it becomes crucial that you
be able to find what you are looking for. It is probably best to save the
default altering statements for the end of the global section, so that the
system statements are toward the top.
Nearly every control verb described in "Comprehensive List of All
Authorization and Control Verbs" in topic 3.0 has a described default
behavior; that is, what will happen if the control verb is omitted. This
default behavior may be overridden for verbs that apply to disk sections:
If the verb is used prior to the first Disk statement, it applies to all
disks.
There are a couple of exceptions:
Help appearing in the global section provides the help text
for the whole system.
Notify appearing in the global section identifies a system
notify person.
| There are also two verbs to be used with caution in the global section:
Option UnSafe appearing in the global section applies to all disks,
and cannot be overridden.
| Inform appearing in the global section applies to all disks,
| and cannot be overridden. However, details can be
| modified (such as list processor and whether
| subscriptions are enabled or not).
Broadly, there are two kinds of verbs used in disk sections: Those used
to control disk behavior (such as cleaning) and those used to grant
authorizations. Generally, it makes more sense for disk control verbs to
appear in the global section than for authorization verbs. Also, the
effects are slightly different.
When a disk control verb appears in the global section, the normal
TOOLSRUN default behavior for all the disks is altered. Within a
particular disk section, the same verb (or a related one) may appear,
overriding the new default. Thus, alteration of defaults can be used to
ensure all disks behave the same (such as Option CleanIdle for fast
startup) or have the same policy (such as Option NoForVerbs). Adding a
new disk can be as simple as adding just a Disk statement and a couple of
Priv and Help statements.
When an authorization verb appears in the global section, that
authorization is granted for all disks and cannot be overridden except by
another authorization that matches it exactly in node, userid and Only
filetypes. On a small system consisting of a few public disks, it might
appear to make sense to have one or two people be PRIV for all disks, or
to grant GETTER or maybe OWNER authority to everyone for all disks, or
maybe to ensure that FORUM files are always appendable. However, small
systems often do not remain small for long. Shadow systems pick up a
master or two; public systems pick up a private disk or two; conference
systems pick up a repository or two.
It is possible to have a TOOLSRUN control file with no Disk statements,
but it is rare and temporary: Reroute *. On the contrary, it is quite
common for a system to have dozens of maintained disks.
The Disk statement begins the disk section for a particular maintained
disk. The Disk statement gives a TOOLSRUN name to the disk, and gives
TOOLSRUN the information it needs to link and access the disk. All verbs
that follow apply only to that disk, up to the next Disk statement (or the
end of the file if this is the last one).
The following verbs may not appear in a disk section:
Alternate BadGMT Equate Disk Equate Node
Equate Verb Interval Local Msg
Nearby Option AdiskFull Reroute Route
System
There is no particular order required of statements within a disk section.
However, there are some logical groupings:
Disk Setup This would include everything that users and other
TOOLSRUN machines would see: Who am I (e.g. Help)? Who
is my master? Who are my shadows?
Disk Behavior This would include things like cleaning, handling of
disk history and requests files, and so on.
Authorizations Except for Priv, these are likely to be kept in the disk
control file on most systems. However, regardless of
where they are described, they are clearly different
from the other two categories, and represent the most
frequent source of control file changes. On some disks,
the authorization statements far outnumber all other
types of statements. Some logical sub-grouping is
certainly appropriate (e.g. geographical, team
membership, alphabetical).
A strong word of advice: Get into the habit of adding
the person's name on the same line as the authorization
(as a comment, following a semicolon). It is a little
bit of extra typing that will repay itself many times
over.
Beyond this, the usual guidelines apply: Keep it clear and readable.
These are nothing more than other files, read and applied right where the
Include statement appeared. You can even include other files from within
included files.
Nothing can beat an include file in certain cases; nothing can make a
control file harder to read than an unnecessarily complex set of includes.
So, use them when you need them, but don't do it just because you can.
Some possible uses:
• Common disk maintainers: The same set of Priv and Notify people for
several disks, in a separate file that is included for each of those
disks. Note, however, that it is uncommon for there to be many such
people or that the list would be exactly the same for each disk.
• Shared control files: Several TOOLSRUN machines, each with the same
(or very similar) statements in their control files. The common parts
can be kept on disks that all can access, and included into their
respective control files.
• Common authorizations: This would allow a peer network, or a
master-servant network to share authorizations by keeping them on the
maintained disk, in a file that is included after the Disk statement.
It could also be used for tight control of a restricted access
network: The list of authorized GETTER statements is propagated from
the master, to be included at each shadow.
• List of shadows: If the Copy statements are kept in a file on the
maintained disk, to be included in the control file, it becomes a
self-documenting directory of shadow disks.
There are some problems with included files:
• If the file is not on the system's A-disk, there is some risk that the
TOOLSRUN machine will try to start without having the disk accessed.
• If a disk is permanently shut down, so that it remains shut down when
TOOLSRUN restarts, TOOLSRUN will not be able to read any included
files that are on the maintained disk itself. This can lead to manual
intervention and complete recycling of the system.
• Any changes in an included file will take effect only when TOOLSRUN is
restarted.
A disk control file is kept on the maintained disk, and has the same name
as the disk and a filetype of CONTROL. Option File enables the disk
control file; Option NoFile disables it. A disk control file may be
present while Option NoFile is in effect; a disk control file need not be
present while Option File is in effect.
Any regular authorization (i.e. not Priv and not one of the primitives
that make up Priv) may appear in a disk control file, along with Copy
statements. Any changes take effect as soon as the file is replaced. Any
person who has Priv authority for the disk may create a disk control file
(if it does not already exist) or replace it. This means that
authorizations may be changed and shadows added and removed without
bothering a system person and without shutting down a busy TOOLSRUN
machine.
The chief drawbacks are that the file is present on the maintained disk,
and so may be visible to users who are able to link to the disk (if this
matters to you), and that the authorizations in the file cannot be shared
readily with any shadow disks (Include is not allowed).
──────────────────────────────────────────────────────────────────────────
* Control file
Local KGNVMZ RSCS SMSG MSG
* Sets: Local node name
* Local RSCS machine userid
* Command to use to talk to RSCS
* Command to use to talk to local users
* List of users authorized to submit SYSTEM requests.
* SYSTEM does not imply any authority to access disks.
System BC
* List of users to notify of any serious errors.
* One of these may be named the contact for the system.
Notify BC Contact Bob Cronin
* Enable the receipt of special messages
Msg Smsg
* Request that the machine wake up at regular intervals
* (e.g. +10 = every 10 minutes). Note TOOLEXIT TIMES is
* more reliable.
Interval +10
* Treat Yorktown systems as if they were all named YORKTOWN.
Equate Node YORKTOWN YKTVMT YKTVMV YKTVMX YKTVMZ
──────────────────────────────────────────────────────────────────────────
Figure 1. Sample Control File - Global Section
──────────────────────────────────────────────────────────────────────────
* Define a disk to maintain (required, remainder optional).
Disk IBMVM TOOLS 103 None
* nickname userid vaddr MR-password
* List of privileged users for this disk.
Priv BC
* List of users to notify of any serious errors.
* One of these may be named the contact for the disk.
Notify BC Contact Bob Cronin
* Description for this disk, if we don't mind anyone learning
* about it (as obtaining this requires no authorization).
Help IBMVM Conference Disk
* Keep all history in a single file named 'nickname HISTORY'.
History Single
* Enable INFORM and SUBSCRIBE support for this disk.
* Specify the node and link name of a list processor
* instead of '* *' to send files to the named node for
* distribution by the local list processor.
Inform * * Subscribe
* Anyone, anywhere may create new files on this disk.
Owner * *
* Nobody may create new EXEC, MODULE or XEDIT files.
Replacer * * Only EXEC MODULE XEDIT
* Anyone authorized to use the APPEND verb may append to FORUM
* files regardless of whether they own the file or not.
Adder * * Only FORUM
* Certain users may not read from or write to this disk at all.
Accesser CLTVMF *
* Broadcast all requests that successfully change the disk.
* Destinations preceded by a COPY card specifying the node and
* link name of a list processor will have files sent to the
* named node for distribution by the local list processor.
Copy KGNBB *LIST
Copy KGNVMC IBMVM
Copy VENTA TOOLS
──────────────────────────────────────────────────────────────────────────
Figure 2. Sample Control File - One Disk Section. This may be repeated
for each maintained disk.
When TOOLSRUN is started, the auth= information from each authorization
statement is stored in a table indexed by the diskname, node, user and
ftype. Therefore, if a second authorization statement for diskname is
found with the same auth=, node and user information, the Only data will
not replace the previous information, but will be added to it. The order
in which the authorization statements appear is not significant, except
that a subsequent statement for diskname with the same node, user and
ftype information will override the authority for that ftype listed on
previous statement(s). Authorizations in a disk section will override
global authorizations. The diskname CONTROL file will be read last and
can override statements found in TOOLSRUN CONTROL. However, note that
PRIV cannot be overridden and that SYSTEM is a separate authorization and
cannot be overridden.
Authorization checks proceed from most specific to least specific by
scanning the table in the order listed below. The diskname, node, user
and ftype information in the incoming request is used to retrieve the
auth= value from the internal authorization tables. If no value is found,
the next form is attempted. When a value is found, the algorithm ends and
returns that value. (If no matches are found, the value returned is
ACCESSER.) The returned value is one of ACCESSER, GETTER, APPENDER,
REPLACER, PACKAGER, OWNER, PRIV or equated verb. This value is then used
as an index into another table to obtain the corresponding list of
primitive verbs. If the requested action appears in that list, the action
is permitted (subject to other checking specific to the action).
Otherwise, the action fails.
This list is presented in the form of authorization statements.
1. auth= diskname node user Only ftype
2. auth= global node user Only ftype
3. auth= diskname node user
4. auth= global node user
5. auth= diskname eqnode user Only ftype
6. auth= global eqnode user Only ftype
7. auth= diskname eqnode user
8. auth= global eqnode user
9. auth= diskname * user Only ftype
10. auth= global * user Only ftype
11. auth= diskname * user
12. auth= global * user
13. auth= diskname node * Only ftype
14. auth= global node * Only ftype
15. auth= diskname node *
16. auth= global node *
17. auth= diskname eqnode * Only ftype
18. auth= global eqnode * Only ftype
19. auth= diskname eqnode *
20. auth= global eqnode *
21. auth= diskname * * Only ftype
22. auth= global * * Only ftype
23. auth= diskname * *
24. auth= global * *
25. auth= ACCESSER
Note: eqnode means a node name which has been translated by an Equate
Node statement in the global section. global means the authorization
statement appeared in the global section. diskname means the
authorization statement appeared in a disk section.
These verbs may be in an include file, but not in a diskname CONTROL file.
Include may also be in a disk section.
┌────────────────────────────────────────────────────────────────────────┐
│ Figure 3. Control verbs used in the global section of the control file │
├────────────────────────┬───────────────────────────────────────────────┤
│ Verb │ Usage and/or Description of the Verb │
├────────────────────────┼───────────────────────────────────────────────┤
│ ALTERNATE │ Allows specified local users to send files │
│ │ that appear to have originated elsewhere. May │
│ │ also be used to specify alternate network │
│ │ machines. │
├────────────────────────┼───────────────────────────────────────────────┤
│ BADGMT │ A list of nodes that have incorrect GMT │
│ │ offsets. You can recognize them because │
│ │ files (or appends) received from these nodes │
│ │ have incorrect dates. │
├────────────────────────┼───────────────────────────────────────────────┤
│ EQUATE DISK │ Redirects incoming requests for a specific │
│ │ disk to a different disk on this service │
│ │ machine. │
├────────────────────────┼───────────────────────────────────────────────┤
│ EQUATE NODE │ Defines a name that stands for a group of │
│ │ nodes. │
├────────────────────────┼───────────────────────────────────────────────┤
│ EQUATE VERB │ Defines a new authorization class. You │
│ │ select which verbs are included in this │
│ │ class. │
├────────────────────────┼───────────────────────────────────────────────┤
│ HELP │ Will be sent to users on request, or when │
│ │ they try to use an unknown disk. Could │
│ │ contain general information about the service │
│ │ machine. │
├────────────────────────┼───────────────────────────────────────────────┤
│ INCLUDE │ Process control statements in another file as │
│ │ if the entire content of the file replaced │
│ │ the Include statement. │
├────────────────────────┼───────────────────────────────────────────────┤
│ INTERVAL │ The service machine wakes up at this timed │
│ │ interval when there is no work to do, running │
│ │ the TOOLEXIT EXEC just before going to sleep │
│ │ each time. │
├────────────────────────┼───────────────────────────────────────────────┤
│ LOCAL │ Identifies the node where TOOLSRUN will run, │
│ │ the userid of the RSCS network service │
│ │ machine, the CP message command for sending │
│ │ messages to the RSCS service machine, the CP │
│ │ message command for sending messages to local │
│ │ users, and the lengths of headers prefixed to │
│ │ messages received from users and RSCS. │
├────────────────────────┼───────────────────────────────────────────────┤
│ MSG │ Specify the type of immediate messages that │
│ │ are to be examined for Toolsrun requests. │
├────────────────────────┼───────────────────────────────────────────────┤
│ NEARBY │ A list of nodes that receive direct │
│ │ distribution from the service machine and not │
│ │ from a list processor, even if specified on a │
│ │ Copy ... *LIST, Inform or Route statement. │
├────────────────────────┼───────────────────────────────────────────────┤
│ NOTIFY │ Specify the person to receive the text of │
│ │ Notify requests that are not for a specific │
│ │ disk. The optional Contact keyword will │
│ │ cause this person's name to be returned to │
│ │ users in the help text. │
├────────────────────────┼───────────────────────────────────────────────┤
│ OPTION ADISKFULL │ Specify percent full for A-disk at which │
│ │ warnings will be issued. The default is 75%. │
├────────────────────────┼───────────────────────────────────────────────┤
│ REROUTE │ Redirects incoming requests for a specific │
│ │ disk to another service machine. │
├────────────────────────┼───────────────────────────────────────────────┤
│ ROUTE │ Force files for a specified node to be routed │
│ │ through a selected list processor. │
│ │ Experimental. │
├────────────────────────┼───────────────────────────────────────────────┤
│ SYSTEM │ Authorize a Toolsrun Administrator for the │
│ │ system class request verbs. │
└────────────────────────┴───────────────────────────────────────────────┘
These verbs may be in an include file, but not in a diskname CONTROL file
unless yes appears in the file column. Unless no appears in the dflt
column, these verbs also may be used in the global section of the control
file, in which case they provide defaults for the disk sections. A * in
the Dflt column indicates that the verb also may be used in the global
section, but has a different meaning and does not set defaults. A ! in
the Dflt column indicates that the verb also may be used in the global
section, but will then apply to all disks and cannot be overridden.
┌────────────────────────────────────────────────────────────────────────┐
│ Figure 4. Verbs used in each disk section to control disk operation │
├─────────────────────────────┬──────────────────────┬─────────┬─────────┤
│ Verb │ Usage and/or │ File │ Dflt │
│ │ Description of the │ │ │
│ │ Verb │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ DISK │ This statement must │ No │ No │
│ │ precede all control │ │ │
│ │ statements for the │ │ │
│ │ specified disk. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ ADDER │ Relaxes the │ Yes │ Yes │
│ │ authorization check │ │ │
│ │ to allow users to │ │ │
│ │ Append to files that │ │ │
│ │ they do not own. │ │ │
│ │ Required for public │ │ │
│ │ forums. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ HELP │ May be used to │ No │ * │
│ │ provide descriptive │ │ │
│ │ information about │ │ │
│ │ the disk. This │ │ │
│ │ information is │ │ │
│ │ supplied upon │ │ │
│ │ specific request and │ │ │
│ │ when a request is │ │ │
│ │ received for an │ │ │
│ │ unknown disk. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ HISTORY │ Specifies whether │ No │ Yes │
│ │ file alteration │ │ │
│ │ activity will be │ │ │
│ │ recorded in one file │ │ │
│ │ or a separate one │ │ │
│ │ for each different │ │ │
│ │ filename. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ HISTORY MODE0 │ Specifies that new │ No │ Yes │
│ │ history file(s) will │ │ │
│ │ have a filemode │ │ │
│ │ digit of zero. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
| │ INFORM │ Allows the INFORM │ No │ ! │
| │ │ requests (if │ │ │
| │ │ authorized) which │ │ │
| │ │ are disabled by │ │ │
| │ │ default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ LIMITS │ Places an upper │ No │ Yes │
│ │ limit on the number │ │ │
│ │ of files that can │ │ │
│ │ you can GET or │ │ │
│ │ REFRESH with a │ │ │
│ │ single request. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ NOTIFY │ Identifies a user │ No │ * │
│ │ who is to be │ │ │
│ │ notified about │ │ │
│ │ trouble with the │ │ │
│ │ disk, security │ │ │
│ │ violation attempts, │ │ │
│ │ and Notify requests │ │ │
│ │ sent to the disk. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION BACKUP │ Specifies that the │ No │ Yes │
│ │ previous version of │ │ │
│ │ a replaced file is │ │ │
│ │ to be kept as a │ │ │
│ │ backup file. This │ │ │
│ │ is the default. │ │ │
│ │ Experimental. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION BATCH │ Specifies that GET │ No │ Yes │
│ │ requests are to be │ │ │
│ │ batched instead of │ │ │
│ │ being sent │ │ │
│ │ immediately. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION CLEAN │ Specify type of │ No │ Yes │
│ │ startup automatic │ │ │
│ │ cleaning to be done. │ │ │
│ │ The default is │ │ │
│ │ OPTION CLEAN SAFE 0. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION CLEANFIRST │ Specify that │ No │ Yes │
│ │ automatic cleaning │ │ │
│ │ is to be done prior │ │ │
│ │ to processing the │ │ │
│ │ first request for │ │ │
│ │ the maintained disk │ │ │
│ │ and/or when the │ │ │
│ │ TOOLSRUN machine is │ │ │
│ │ idle. The default │ │ │
│ │ is to do automatic │ │ │
│ │ cleaning only when │ │ │
│ │ the maintained disk │ │ │
│ │ is first started │ │ │
│ │ after a TOOLSRUN │ │ │
│ │ start. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION CLEANFULL │ Specify that │ No │ Yes │
│ │ automatic cleaning │ │ │
│ │ is to be done when a │ │ │
│ │ request has been │ │ │
│ │ deferred due to a │ │ │
│ │ full disk. The │ │ │
│ │ default is to do │ │ │
│ │ automatic cleaning │ │ │
│ │ only when the │ │ │
│ │ maintained disk is │ │ │
│ │ first started after │ │ │
│ │ a TOOLSRUN start. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION CLEANIDLE │ Specify that │ No │ Yes │
│ │ automatic cleaning │ │ │
│ │ is to be done when │ │ │
│ │ the TOOLSRUN machine │ │ │
│ │ is idle. The │ │ │
│ │ default is to do │ │ │
│ │ automatic cleaning │ │ │
│ │ only when the │ │ │
│ │ maintained disk is │ │ │
│ │ first started after │ │ │
│ │ a TOOLSRUN start. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION CLEANSTART │ Specify that │ No │ Yes │
│ │ automatic cleaning │ │ │
│ │ is to be done when │ │ │
│ │ the maintained disk │ │ │
│ │ is first started │ │ │
│ │ after a TOOLSRUN │ │ │
│ │ start. This is the │ │ │
│ │ default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION DISKFULL │ Specify percent full │ No │ Yes │
│ │ for a maintained │ │ │
│ │ disk at which │ │ │
│ │ warnings will be │ │ │
│ │ issued. The default │ │ │
│ │ is 95%. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION FILE │ Enable the diskname │ No │ Yes │
│ │ CONTROL file, │ │ │
│ │ otherwise any such │ │ │
│ │ file on the │ │ │
│ │ maintained disk is │ │ │
│ │ ignored. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION FORVERBS │ Enable the FOR │ No │ Yes │
│ │ override for the │ │ │
│ │ specified verbs. │ │ │
│ │ The default is all │ │ │
│ │ verbs, so long as │ │ │
│ │ the sender is │ │ │
│ │ authorized for the │ │ │
│ │ request verb. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION GMTime │ Specifies that time │ No │ Yes │
│ │ stamps on the │ │ │
│ │ maintained disk will │ │ │
│ │ be in GMT. This is │ │ │
│ │ the default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION INDEX │ Specifies that a │ No │ Yes │
│ │ diskname NAMINDEX │ │ │
│ │ file will be built │ │ │
│ │ on the maintained │ │ │
│ │ disk. This is the │ │ │
│ │ default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION LOCALNames │ Use the STATE │ No │ Yes │
│ │ command to determine │ │ │
│ │ if a fileid contains │ │ │
│ │ illegal characters. │ │ │
│ │ Otherwise, Toolsrun │ │ │
│ │ limits the │ │ │
│ │ characters to those │ │ │
│ │ in CMS │ │ │
│ │ documentation: A-Z, │ │ │
│ │ a-z, 0-9, $, #, @, │ │ │
│ │ +, - and _. Colons │ │ │
│ │ are not allowed │ │ │
│ │ because they could │ │ │
│ │ cause parsing │ │ │
│ │ problems in the │ │ │
│ │ NAMES file. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION LOCALTime │ Specifies that time │ No │ Yes │
│ │ stamps on the │ │ │
│ │ maintained disk will │ │ │
│ │ be in local time. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NETAUDIT │ Specifies that │ No │ Yes │
│ │ network usage │ │ │
│ │ information is to be │ │ │
│ │ kept. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NOBACKUP │ Specifies that the │ No │ Yes │
│ │ previous version of │ │ │
│ │ a replaced file is │ │ │
│ │ to be discarded. │ │ │
│ │ Experimental. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NOBATCH │ Specifies that GET │ No │ Yes │
│ │ requests are to be │ │ │
│ │ sent immediately │ │ │
│ │ instead of being │ │ │
│ │ batched. This is │ │ │
│ │ the default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NOCLEAN │ Do not ever │ No │ Yes │
│ │ automatically clean │ │ │
│ │ the maintained disk. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NOCLEANFULL │ Do not automatically │ No │ Yes │
│ │ clean the maintained │ │ │
│ │ disk when a request │ │ │
│ │ is deferred due to a │ │ │
│ │ full disk. This is │ │ │
│ │ the default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NOFILE │ Ignore the diskname │ No │ Yes │
│ │ CONTROL file. This │ │ │
│ │ is the default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NOFORVERBS │ Only PRIV users may │ No │ Yes │
│ │ issue the FOR │ │ │
│ │ override. The │ │ │
│ │ default is all │ │ │
│ │ verbs, so long as │ │ │
│ │ both are authorized │ │ │
│ │ for the request │ │ │
│ │ verb. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NOINDEX │ Specifies that a │ No │ Yes │
│ │ diskname NAMINDEX │ │ │
│ │ file will not be │ │ │
│ │ built on the │ │ │
│ │ maintained disk. │ │ │
│ │ The default is │ │ │
│ │ OPTION INDEX. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NOLOCALNAMES │ Allow only CMS │ No │ Yes │
│ │ documented │ │ │
│ │ characters in │ │ │
│ │ fileids (i.e. A-Z, │ │ │
│ │ a-z, 0-9, $, #, @, │ │ │
│ │ +, - and _). This │ │ │
│ │ is the default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NONETAUDIT │ Specifies that │ No │ Yes │
│ │ network usage │ │ │
│ │ information is not │ │ │
│ │ to be kept. This is │ │ │
│ │ the default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NOORDER │ Process incoming │ No │ Yes │
│ │ requests in the │ │ │
│ │ order that they are │ │ │
│ │ received. This is │ │ │
│ │ the default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NOSUBSEXPIRE │ Indicates that disk │ No │ Yes │
│ │ subscriptions do not │ │ │
│ │ expire. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION NOWARNOWNER │ Do not warn the │ No │ Yes │
│ │ owner of a file when │ │ │
│ │ their ownership is │ │ │
│ │ overridden. The │ │ │
│ │ default is to warn │ │ │
│ │ them. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION ORDER │ Process incoming │ No │ Yes │
│ │ requests out of │ │ │
│ │ sequence to minimize │ │ │
│ │ re-accessing the │ │ │
│ │ disk. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION SUBSEXPIRE │ Indicates that disk │ No │ Yes │
│ │ subscriptions │ │ │
│ │ (except COPy) will │ │ │
│ │ expire. This is the │ │ │
│ │ default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION UNSAFE │ Specifies that │ No │ ! │
│ │ discarded files are │ │ │
│ │ to be erased │ │ │
│ │ immediately. │ │ │
│ │ Experimental. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ OPTION WARNOWNER │ Warn the owner of a │ No │ Yes │
│ │ file when their │ │ │
│ │ ownership is │ │ │
│ │ overridden (e.g. by │ │ │
│ │ a PRIV user). This │ │ │
│ │ is the default. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ REROUTER │ Authorize another │ No │ Yes │
│ │ service machine to │ │ │
│ │ reroute files to │ │ │
│ │ this service machine │ │ │
│ │ for this disk. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ REQUESTS │ Specifies whether │ No │ Yes │
│ │ PACKAGE file GETs │ │ │
│ │ and REGISTERs will │ │ │
│ │ be recorded in one │ │ │
│ │ REQUESTS file or a │ │ │
│ │ separate one for │ │ │
│ │ each different │ │ │
│ │ PACKAGE filename. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ REQUESTS MODE0 │ Specifies that new │ No │ Yes │
│ │ REQUESTS file(s) │ │ │
│ │ will have a filemode │ │ │
│ │ digit of zero. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ RESPONSE │ Specify how the │ No │ Yes │
│ │ service machine will │ │ │
│ │ communicate with │ │ │
│ │ users. │ │ │
├─────────────────────────────┼──────────────────────┼─────────┼─────────┤
│ TITLE │ Specify additional │ No │ Yes │
│ │ text to be placed at │ │ │
│ │ the top of List, │ │ │
│ │ Summary, and Query │ │ │
│ │ Disk responses. For │ │ │
│ │ example, the │ │ │
│ │ security │ │ │
│ │ classification of │ │ │
│ │ the disk. │ │ │
└─────────────────────────────┴──────────────────────┴─────────┴─────────┘
These verbs may be in an include file, but not in a diskname CONTROL file
unless yes appears in the file column. These verbs may never be used in
the global section.
┌────────────────────────────────────────────────────────────────────────┐
│ Figure 5. Verbs used to set up networks of duplicate disks │
├───────────────────────────┬──────────────────────────────────┬─────────┤
│ Verb │ Usage and/or Description of the │ File │
│ │ Verb │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ COPY │ Specifies a destination for │ Yes │
│ │ copies of all requests that are │ │
│ │ forwarded. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ COPIER │ Authorizes a source of forwarded │ No │
│ │ requests; the authorization │ │
│ │ level of the original submittor │ │
│ │ is rechecked locally. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ MASTER │ Authorizes a source of forwarded │ No │
│ │ requests; the original submittor │ │
│ │ does not need to be authorized │ │
│ │ locally. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ PEER │ Authorizes a source of forwarded │ No │
│ │ requests; the authorization │ │
│ │ level of the original submittor │ │
│ │ is rechecked locally. Also │ │
│ │ specifies a destination for │ │
│ │ copies of all requests that are │ │
│ │ forwarded but ONLY if the │ │
│ │ request arrived directly from │ │
│ │ the submittor. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ SERVANT │ Authorizes a source of forwarded │ No │
│ │ requests; the authorization │ │
│ │ level of the original submittor │ │
│ │ is rechecked locally. Also │ │
│ │ specifies a destination for │ │
│ │ copies of all requests that are │ │
│ │ forwarded. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ SOURCE │ Specifies the node and userid to │ No │
│ │ which Get-Copy requests are to │ │
│ │ be forwarded, in response to │ │
│ │ Refresh requests. │ │
└───────────────────────────┴──────────────────────────────────┴─────────┘
The composite authorization verbs authorize logical groups of requests.
Each verb includes all the authority contained in the ones listed below it
in this table. Normally, these are the only authorization verbs you will
need to use.
These verbs may be in an include file, but not in a diskname CONTROL file
unless yes appears in the file column. These verbs may be used in the
global section, in which case the authorization applies to all disks.
┌────────────────────────────────────────────────────────────────────────┐
│ Figure 6. Composite authorization verbs │
├───────────────────────────┬──────────────────────────────────┬─────────┤
│ Verb │ Usage and/or Description of the │ File │
│ │ Verb │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ PRIV │ Authorizes a user for the set of │ No │
│ │ requests allowed PRIV users and │ │
│ │ gives them the authority to │ │
│ │ issue requests to all files on │ │
│ │ the disk, regardless of │ │
│ │ ownership. TOOLSRUN will also │ │
│ │ accept requests from PRIV users │ │
│ │ which are attributed to (FOR) │ │
│ │ others, without regard to the │ │
│ │ attributed user's authority. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ OWNER │ Normal blanket authority. │ Yes │
│ │ OWNERs can create new files and │ │
│ │ have full rights to manipulate │ │
│ │ the files that they own. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ PACKAGER │ Essentially the same as OWNER │ Yes │
│ │ except that no new files may be │ │
│ │ placed on the disk unless a │ │
│ │ package file including it was │ │
│ │ placed there first. It insures │ │
│ │ that all files placed on the │ │
│ │ disk by people so authorized │ │
│ │ will be included in at least one │ │
│ │ package file. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ REPLACER │ This allows users to change │ Yes │
│ │ files which they own, but they │ │
│ │ are not allowed to create any │ │
│ │ new files or erase any old ones. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ APPENDER │ An APPENDER can do what a GETTER │ Yes │
│ │ can do plus Append and Vote. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ GETTER │ This is the basic read-only │ Yes │
│ │ privilege. All requests are │ │
│ │ authorized except the ones that │ │
│ │ can alter files. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ ACCESSER │ Exclude a user that would have │ Yes │
│ │ been granted some authority │ │
│ │ without this statement. Used to │ │
│ │ make exceptions. │ │
├───────────────────────────┴──────────────────────────────────┴─────────┤
│ Note: See also Adder in "Verbs Used for Controlling the Disk" in │
│ topic 2.2.1. │
├────────────────────────────────────────────────────────────────────────┤
│ Note: System, in "Control File Verbs Used in the Global Section" in │
│ topic 2.1, is separate from this hierarchy and does not imply any of │
│ these authorizations. │
└────────────────────────────────────────────────────────────────────────┘
This is a complete list of all primitive authorization verbs. They may be
used to provide an unusual authorization scheme, or they may appear in
Equate Verb statements to allow you to design your own authorization
verbs, for example one allowing write access but not read access.
These verbs may be in an include file, but not in a diskname CONTROL file
unless yes appears in the file column. These verbs may be used in the
global section, in which case the authorization applies to all disks.
┌────────────────────────────────────────────────────────────────────────┐
│ Figure 7. Primitive authorization verbs │
├───────────────────────────┬──────────────────────────────────┬─────────┤
│ Verb │ Usage and/or Description of the │ File │
│ │ Verb │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ APPEND │ Authorizes a user for the Append │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ BATCH-CANCEL │ Authorizes a user for the Batch │ Yes │
│ │ Cancel request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ BATCH-QUERY │ Authorizes a user for the Batch │ Yes │
│ │ Query request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ BATCH-RELEASE │ Authorizes a user for the Batch │ No │
│ │ Release request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ CLEAN-ALL │ Authorizes a user for the Clean │ No │
│ │ All request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ CLEAN-ALLSAFE │ Authorizes a user for the Clean │ No │
│ │ AllSafe request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ CLEAN-BACKUP │ Authorizes a user for the Clean │ No │
│ │ Backup request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ CLEAN-BACKUPSAFE │ Authorizes a user for the Clean │ No │
│ │ BackupSafe request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ CLEAN-ERASABLE │ Authorizes a user for the Clean │ No │
│ │ Erasable request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ CLEAN-NAMES │ Authorizes a user for the Clean │ No │
│ │ Names request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ CLEAN-SAFE │ Authorizes a user for the Clean │ Yes │
│ │ Safe request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ COPY │ Authorizes a user for the Copy │ n/a │
│ │ request. However, this verb is │ │
│ │ already used for another │ │
│ │ purpose, and therefore only │ │
│ │ functions as an authorization │ │
│ │ primitive in Equate Verb │ │
│ │ statements. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ CREATE │ Authorizes a user for the Create │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ CREATE-OWNED │ Authorizes a user for the Create │ Yes │
│ │ request, but only in the case │ │
│ │ where the file is already owned. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ DISK-NOCOPY │ Authorizes a user for the Nocopy │ No │
│ │ keyword on the Disk request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ DISK-SHUTDOWN │ Authorizes a user for the │ No │
│ │ Shutdown keyword on the Disk │ │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ DISK-SHUTPERM │ Authorizes a user for the │ No │
│ │ Shutperm keyword on the Disk │ │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ DISK-START │ Authorizes a user for the Start │ No │
│ │ keyword on the Disk request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ ERASE │ Authorizes a user for the Erase │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ GET │ Authorizes a user for the Get │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ HIDE │ Authorizes a user for the Hide │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ INFORM-ALL │ Authorizes a user for the Inform │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ INFORM-COP │ Authorizes a user for the Inform │ Yes │
│ │ request with the Copy keyword. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ INFORM-EXC │ Authorizes a user for the Inform │ Yes │
│ │ request with the Exclude │ │
│ │ keyword. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ INFORM-NEW │ Authorizes a user for the Inform │ Yes │
│ │ request with the New keyword. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ INFORM-REF │ Authorizes a user for the Inform │ Yes │
│ │ request with the Reference │ │
│ │ keyword. Experimental. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ INFORM-SUB │ Authorizes a user for the Inform │ Yes │
│ │ request with the Subscribe │ │
│ │ keyword. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ INFORM-UPD │ Authorizes a user for the Inform │ Yes │
│ │ request with the Update keyword. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ INSERT-HEADER │ Authorizes a user for the Append │ Yes │
│ │ request with a date of all zeros │ │
│ │ and the keyword Insert following │ │
│ │ it. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ LIST │ Authorizes a user for the List │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ LOCK │ Authorizes a user for the Lock │ Yes │
│ │ request. Experimental. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ MODIFY │ Authorizes a user for the Append │ Yes │
│ │ request with a non-zero date. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ MODIFY-HEADER │ Authorizes a user for the Append │ Yes │
│ │ request with a date of all │ │
│ │ zeros. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ NEWOWN │ Authorizes a user for the Newown │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ NOTIFY │ Authorizes a user for the Notify │ n/a │
│ │ request. However, this verb is │ │
│ │ already used for another │ │
│ │ purpose, and therefore only │ │
│ │ functions as an authorization │ │
│ │ primitive in Equate Verb │ │
│ │ statements. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ OWN │ Authorizes a user for the Own │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ PACKFILE-OWN │ Automatically issues the Own │ Yes │
│ │ request for an unowned file │ │
│ │ newly referenced by the CREATE │ │
│ │ or REPLACE of a PACKAGE file. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ PACKFILE-ERASE │ Automatically issues the Erase │ Yes │
│ │ request for an owned file not │ │
│ │ referenced by any PACKAGE file, │ │
│ │ and that did not exist prior to │ │
│ │ first being referenced by a │ │
│ │ PACKAGE file. The Erase occurs │ │
│ │ on the second replacement or │ │
│ │ first erasure of the last │ │
│ │ PACKAGE file to reference the │ │
│ │ owned file. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ PLACE │ Authorizes a user for the Place │ No │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ PRUNE │ Authorizes a user for the Prune │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ QUERY-DISK │ Authorizes a user for the Query │ Yes │
│ │ Disk request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ QUERY-FILE │ Authorizes a user for the Query │ Yes │
│ │ File request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ QUERY-INFORM │ Authorizes a user for the Query │ Yes │
│ │ Inform request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ REFRESH │ Authorizes a user for the │ No │
│ │ Refresh request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ REGISTER │ Authorizes a user for the │ Yes │
│ │ Register request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ REGRESS │ Authorizes a user for the │ Yes │
│ │ Regress request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ RENEW │ Authorizes a user for the Renew │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ REPLACE │ Authorizes a user for the │ Yes │
│ │ Replace request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ RESPONSE │ Authorizes a user for the │ n/a │
│ │ Response request. However, this │ │
│ │ verb is already used for another │ │
│ │ purpose, and therefore only │ │
│ │ functions as an authorization │ │
│ │ primitive in Equate Verb │ │
│ │ statements. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ SET-ADDRESS │ Authorizes a user for the Set │ Yes │
│ │ Address request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ SET-DESCRIPTION │ Authorizes a user for the Set │ Yes │
│ │ Description request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ SET-FILE │ Authorizes a user for the Set │ Yes │
│ │ File request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ SET-MODE │ Authorizes a user for the Set │ Yes │
│ │ Mode request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ SUMMARY │ Authorizes a user for the │ Yes │
│ │ Summary request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ TRACE │ Authorizes a user for the Trace │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ UNINFORM │ Authorizes a user for the │ Yes │
│ │ Uninform request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ UNLOCK │ Authorizes a user for the Unlock │ Yes │
│ │ request. Experimental. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ UPDATE │ Authorizes a user for the Update │ Yes │
│ │ request. │ │
├───────────────────────────┼──────────────────────────────────┼─────────┤
│ VOTE │ Authorizes a user for the Vote │ Yes │
│ │ request. │ │
└───────────────────────────┴──────────────────────────────────┴─────────┘
Context
The effects of a verb often depend on whether it is encountered in the
global section or in a disk section. Also, some verbs are not allowed in
the global section, other verbs are not allowed in a disk section, and
some other verbs, while allowed in a disk section, are not allowed in a
diskname CONTROL file.
Format
Syntax Explanation
{SMSG | IUCVMSG | BOTH} You must specify one of these items.
[NONETwork | NETwork] You may specify one of these items, or
omit to get the indicated default. UPPER
case means keyword must be entered as
shown, except trailing lower case letters
are optional. For example, NONET works
just as well as NONETWORK.
[{userid | *} [NOSUBscribe | SUBscribe]]
You may omit everything to get the
defaults of * and NOSUBSCRIBE. Or, you
may specify userid and get the default of
NOSUBSCRIBE. However, in order to
specify one of SUBSCRIBE or NOSUBSCRIBE,
you must specify userid or *.
[node] The nodeid is optional; it will default
to the same as the service machine.
[msglvl] The message level is optional; the
default value is documented.
thing [thing ... ] A list of one or more things separated by
spaces.
text A line of mixed case text.
Comments
All parameters (except text) are uppercased before they are interpreted.
Defaults
Many of the verbs have defaults for omitted parameters, or if the verb is
omitted altogether. Some verbs, if used in the global section, alter the
standard defaults for the disk sections. The defaults described for each
verb assume that this has not been done. If it has, then the altered
defaults apply.
In many cases, intermediate parameters may be defaulted by specifying an
asterisk in their place. A notable exception is Response - an asterisk
means "no restriction" and an equal sign is used to obtain the default for
a parameter.
Purpose
Accesser is an authorization verb that explicitly disallows access.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── ACCESSER ───────────────────────────────────────────────────────────┐
│ │
│ ACCESSER [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be excluded, defaults to the same as
the service machine.
userid The userid of a person to be excluded from access.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Since TOOLSRUN never provides any access by default, this verb is only
meaningful when it is more specific than another verb. For example, if
all users on a certain node are authorized, ACCESSER may used to exclude
certain individuals and/or filetypes.
Defaults
ACCESSER * *
unless overridden by
verb * *
where verb is some other authorization verb (e.g. Getter).
Purpose
Adder is an authorization modifier, allowing users other than the owner to
append to a file, and defining the publicly appendable file types.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── ADDER ──────────────────────────────────────────────────────────────┐
│ │
│ ADDER [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be allowed, defaults to the same as
the service machine. Normally specified as an asterisk (*).
userid The userid of a person to be allowed to append to files that
they don't own. Normally specified as an asterisk (*).
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
Note: Adder used without the Only keyword makes all files on
the disk publicly appendable. Generally, this is not a good
idea.
ftype A list of all publicly appendable file types the user is allowed
to append to.
Usage
The Adder verb is NOT an authorization verb. It modifies authorizations
already in effect. Without Adder, only the owner of a file would be
allowed to append to it. To allow others to append to the file, you must
do two things. First, authorize them to use the Append verb. Second,
they must be included on an Adder statement. For example, you grant your
users OWNER authority if they are to be allowed to create new appendable
files or simply APPENDER if they are only to be allowed to append to the
ones that already exist. You would also include an Adder * * Only FORUM
statement, which has two effects. First, it extends to anyone with the
ability to use the Append verb the right to append to any file whose
filetype is FORUM and it causes TOOLSRUN to regard all files with that
filetype to be "publicly appendable."
Results
Aside from allowing appends to files owned by someone else (if one is
already authorized to append), Adder also affects files when they are
created: If a file has a filetype that appears on any Adder statement for
the disk (or in the global section), TOOLSRUN considers the file to be
publicly appendable. When an appendable file is first created, TOOLSRUN
will search the disk for a file named diskname HEADER. If it exists, the
contents will be copied at the top. (This allows the disk owner to ensure
that a common set of rules appears at the top of all appendable files.)
The completion message that is returned to the Create sender, and inform
notes sent to subscribers, contain the phrase "(and is publicly
appendable)."
Many shadow disks do not bother to maintain Adder statements, since all
updates are sent to the master. The Create request that is propagated
from the master does not indicate that the file is appendable at the
master, and does not contain the header lines. As a consequence, the
header line(s) will not appear in copies on shadow disks. (One solution
would be to maintain a small file on the master, to be included into all
shadow control files, with applicable Adder statements. Besides ensuring
uniformity, it also answers a frequent user question: What filetypes are
appendable?)
When a file is replaced, TOOLSRUN does not check for a header or insert a
new one.
Examples
1. Assume a local, private TOOLSRUN disk. We wish to allow ALAN, BRENDA
and CARL to append to files of type FORUM, and also to get, inform,
subscribe, etcetera, to any other file on the disk. They are not to
create or erase any files.
ADDER * ONLY FORUM
APPENDER ALAN
APPENDER BRENDA
APPENDER CARL
2. Assume a public access disk. Anyone is able to create any file, and
do all of the usual getting, subscribing and so on. We also wish to
have publicly appendable FORUM and NEWS files, and to be able to
conduct votes.
ADDER * * ONLY FORUM NEWS VOTE VOTERS
OWNER * *
3. A TOOLSRUN disk is to be set up for collecting certain types of data.
Anyone on node LEXVMK is to be able to access the disk. Two different
teams will contribute data to the disk, by creating appendable files
and appending data to them. The teams are TEAMA and TEAMB, with
members TEAMA1, TEAMA2, TEAMB1 and so on. Team leaders (TEAMA1,
TEAMB1) may create appendable data files for their team (ADATA, BDATA)
and team members may append data to their own team's files. All team
members (and some others) may get, subscribe, etcetera, to any of the
team data files, as well as any other file on the disk. There are
also FORUM files that any authorized person can append to.
ADDER * * ONLY FORUM ADATA BDATA CDATA; Appendable filetypes
APPENDER LEXVMK * ONLY FORUM; Anyone can append to this
GETTER LEXVMK *; Anyone can get, etcetera
OWNER LEXVMK TEAMA1 ONLY ADATA; Can create and append these
OWNER LEXVMK TEAMB1 ONLY BDATA; Can create and append these
APPENDER LEXVMK TEAMA2 ONLY ADATA; Can append these files
APPENDER LEXVMK TEAMA3 ONLY ADATA; Can append these files
APPENDER LEXVMK TEAMB2 ONLY BDATA; Can append these files
APPENDER LEXVMK TEAMB3 ONLY BDATA; Can append these files
Defaults
Only the owner of a file may append to it. The file is not considered
publicly appendable, so it is not altered when first created.
Purpose
Alternate identifies an alternate network machine or a trusted user who
may transfer files.
Context
Allowed only in global section.
Format
┌─── ALTERNATE ──────────────────────────────────────────────────────────┐
│ │
│ ALTERNATE userid [NONETwork | NETwork] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
userid The userid of a person allowed to send files to the service
machine with CP TAGs in the format that the TAG on a file from a
network machine would have. If such a tag is present, the origin
of the file will be determined from the tag data rather than
from the ORIGINID.
NONETwork The NONETWORK option allows such files from this userid
regardless of whether they arrived directly or were transferred.
This is the default.
NETwork ALTERNATE may also be used to specify an alternate network
machine in those situations where files can arrive from more
than one such machine. If it is used for this purpose, the
NETWORK option should be used to cause any transferred files
from this userid to be rejected, since the true origin of such
files cannot be reliably determined.
Usage
The local installation may have set up more than one network machine from
which the TOOLSRUN Service Machine may receive request files. Alternate
Network identifies additional machines.
When setting up a shadow, it may be that the TOOLSRUN Service Machine's
userid is not yet authorized at the master. A userid that is authorized
may be identified as an Alternate Nonetwork, allowing it to Inform Copy *
* at the master, and transfer files to the TOOLSRUN Service Machine as
they arrive.
Defaults
Files with network tags will be accepted from only one machine: The one
identified on the Local statement (or by the CMS IDENTIFY command, if
there is no Local statement).
Transferred files are never accepted.
Purpose
Append authorizes a user to issue Append requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── APPEND ─────────────────────────────────────────────────────────────┐
│ │
│ APPEND [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Append verb.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Append is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Any person with at least APPENDER authority may make appends.
Purpose
Appender is a composite authorization verb.
Group Definition of the Group
Appender Append + Vote + GETTER
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── APPENDER ───────────────────────────────────────────────────────────┐
│ │
│ APPENDER [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for this group of verbs.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
APPENDER is a less frequently used authorization. It permits users to
make appends, vote, get, list, etcetera, but does not allow the creation
or replacement of any files.
Note that APPENDER by itself does not allow the user to append to files
that someone else owns. (See "ADDER" in topic 3.3.)
Comments
Only the owner of a file may append to it, except for file types permitted
by the Adder statement.
Defaults
ACCESSER * *
unless overridden by
verb * *
where verb is some other authorization verb (e.g. Getter).
Purpose
Badgmt is used to identify a node known to have an incorrect GMT offset,
until the offset is fixed.
Context
Allowed only in global section.
Format
┌─── BADGMT ─────────────────────────────────────────────────────────────┐
│ │
│ BADGMT node [node ... ] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node A node known to have an incorrect GMT offset. The time of
arrival at your service machine is used instead of the time
supplied by RSCS.
Usage
The time of transactions are recorded in various places, e.g. the diskname
NAMES file and in append headers. Normally, this will be the time the
spool file was sent as provided by RSCS; however, if this information is
obviously incorrect (in the future) the time of arrival at the master is
used instead. Each node in a network "knows" the local GMT offset (the
difference between local and GMT times) and GMT time is always used in
network communications, leaving it to the destination node to convert that
to local time. When the GMT offset is incorrectly specified at a node,
all times it communicates over the network will be incorrect. This
statement is intended as a temporary bypass for that problem.
Defaults
Transaction time will be as recorded by RSCS when a spool file was sent.
Purpose
Batch-Cancel authorizes a user for the Cancel keyword of the Batch
request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── BATCH-CANCEL ───────────────────────────────────────────────────────┐
│ │
│ BATCH-CANCEL [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for Batch Cancel.
Usage
Batch-Cancel is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with GETTER authority may issue Batch Cancel requests.
Purpose
Batch-Query authorizes a user for the Query keyword of the Batch request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── BATCH-QUERY ────────────────────────────────────────────────────────┐
│ │
│ BATCH-QUERY [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for Batch Query.
Usage
Batch-Query is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with GETTER authority may issue Batch Query requests.
Purpose
Batch-Release authorizes a user for the Release keyword of the Batch
request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── BATCH-RELEASE ──────────────────────────────────────────────────────┐
│ │
│ BATCH-RELEASE [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for Batch Release.
Usage
Batch-Release is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with PRIV authority may issue Batch Release requests.
Purpose
Clean-All authorizes a user for the All keyword of the Clean request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── CLEAN-ALL ──────────────────────────────────────────────────────────┐
│ │
│ CLEAN-ALL [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for Clean All.
Usage
Clean-All is a primitive authorization verb, usually used with Equate Verb
to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with PRIV authority may issue Clean All requests.
Purpose
Clean-AllSafe authorizes a user for the AllSafe keyword of the Clean
request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── CLEAN-ALLSAFE ──────────────────────────────────────────────────────┐
│ │
│ CLEAN-ALLSAFE [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for Clean AllSafe.
Usage
Clean-AllSafe is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with PRIV authority may issue Clean AllSafe requests.
Purpose
Clean-Backup authorizes a user for the Backup keyword of the Clean
request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── CLEAN-BACKUP ───────────────────────────────────────────────────────┐
│ │
│ CLEAN-BACKUP [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for Clean Backup.
Usage
Clean-Backup is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with PRIV authority may issue Clean Backup requests.
Purpose
Clean-BackupSafe authorizes a user for the BackupSafe keyword of the Clean
request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── CLEAN-BACKUPSAFE ───────────────────────────────────────────────────┐
│ │
│ CLEAN-BACKUPSAFE [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for Clean BackupSafe.
Usage
Clean-BackupSafe is a primitive authorization verb, usually used with
Equate Verb to create a new composite authorization verb. It has little
use by itself.
Defaults
Only users with PRIV authority may issue Clean BackupSafe requests.
Purpose
Clean-Erasable authorizes a user for the Erasable keyword of the Clean
request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── CLEAN-ERASABLE ─────────────────────────────────────────────────────┐
│ │
│ CLEAN-ERASABLE [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for Clean Erasable.
Usage
Clean-Erasable is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with PRIV authority may issue Clean Erasable requests.
Purpose
Clean-Names authorizes a user for the Names keyword of the Clean request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── CLEAN-NAMES ────────────────────────────────────────────────────────┐
│ │
│ CLEAN-NAMES [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for Clean Names.
Usage
Clean-Names is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with PRIV authority may issue Clean Names requests.
Purpose
Clean-Safe authorizes a user for the Safe verb. keyword of the Clean
request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── CLEAN-SAFE ─────────────────────────────────────────────────────────┐
│ │
│ CLEAN-SAFE [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for Clean Safe.
Usage
Clean-Safe is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with at least REPLACER authority may issue Clean Safe requests.
Format
┌─── COMMAND ────────────────────────────────────────────────────────────┐
│ │
│ COMMAND [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Comments
This verb is obsolete, and is ignored.
Purpose
Authorizes a source of forwarded requests; the authorization level of the
original submittor is rechecked locally.
Context
Section Effects
Global Not allowed
Disk Applies only to that disk
diskname CONTROL Not allowed
Format
┌─── COPIER ─────────────────────────────────────────────────────────────┐
│ │
│ COPIER node userid [msglvl | 4] [RETAIN hours] [CONTACT name] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of another service machine.
userid The userid of another service machine.
msglvl The minimum level of response message, default is 4. See
"Message Levels" in topic B.1.
hours Number of hours to retain a forwarded request that has been
deferred, before purging it and requesting a refresh from the
source.
If hours is zero, forwarded requests will not be deferred.
name Information about the contact person at the source. This is now
obsolete and is ignored. The same effect of "self
documentation" may be achieved with a semicolon comment.
Usage
Specifically, Copier authorizes node userid to send Put requests, and to
propagate requests (i.e. the request deck contains Origin) and reroute
requests (i.e. the request deck contains From). Propagated requests will
still be checked for originator authorization. In addition, node userid
will be sent a Get-Copy in response to a Refresh, if no Source is
specified. (See "SOURCE" in topic 3.123.)
Copier is less commonly used. Master is more appropriate for most
shadows. Otherwise, the shadow must duplicate all of the authorizations
at the master. Servant is more appropriate at a master that will accept
requests forwarded from a shadow. Otherwise, a Copy statement will also
be required to cause the master to forward requests to the shadow. This
combination of Copy+Copier is more like a Peer, because the master could
attempt to refresh from node userid (by sending a Get-Copy) if it is a
Copier, but not if it is a Servant.
RETAIN applies to requests that might have raced ahead of an earlier
request. Examples would be a CREATE arriving before an ERASE (or vice
versa), an APPEND MODIFY arriving before an APPEND, or a REGRESS arriving
before a HIDE (or vice versa). It is assumed that the request succeeded
at the source (else it would not have been forwarded), and so some other
request may arrive later that will allow this one to succeed. The request
is deferred for hours hours. If the request has not been undeferred
successfully at the end of the retention period, it is purged and a
refresh (where appropriate) is requested from the source.
| Comments
| Unless you are asked to do so by an administrator of the other service
| machine (say, for debugging a particular problem), it is a bad idea to set
| the msglvl less than 10; this can cause a flood of responses sent back to
| the other machine if, for example, this disk is shut down for an extended
| period.
Defaults
RETAIN 48
Purpose
Specifies a destination to which all successful changes should be
forwarded. (See also "COPY (group COPY statements by *LIST processor)" in
topic 3.21.)
Context
Section Effects
Global Not allowed
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── COPY ───────────────────────────────────────────────────────────────┐
│ │
│ COPY node userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of another service machine.
userid The userid of another service machine.
Usage
Specifically, Copy authorizes node userid as if GETTER, and also causes
all successful requests to be propagated to node userid. In particular,
Copy authorizes Get-Copy from the shadow machine, thereby enabling
refreshes. Refresh limits apply (see "LIMITS" in topic 3.50). Without
Copy, Peer or Servant, Get limits apply, and the machine must be
authorized for Get-Copy some other way (e.g. GETTER).
Copy is typically used at a master to identify a shadow, to which all
requests should be forwarded. It is also used at a servant to forward
local changes to the master.
Defaults
Requests are not forwarded, except where Inform Copy is in effect.
Purpose
Forces distribution to subsequent Copy destinations for this disk only
through the specified list processor. (See also "COPY (forward successful
changes to shadows)" in topic 3.20.)
Context
Section Effects
Global Not allowed
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── COPY ───────────────────────────────────────────────────────────────┐
│ │
│ COPY node listuser [LISTPROC] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of the list processor service machine.
listuser The userid of the list processor, usually *LIST or sometimes
LISTPROC.
LISTPROC A keyword that must be coded as shown, if listuser is neither
*LIST nor LISTPROC, in order to distinguish this from a normal
COPY statement.
Usage
| (See "NEARBY" in topic 3.58 for a discussion of list processing.)
You may divide your Copy statements into one or more groups and place a
COPY node *LIST statement at the head of each one in order to control the
method of distribution. Under normal conditions, it is better to let the
network decide how all the files should be routed.
Defaults
The network service machines determine the list processor.
Purpose
Create authorizes a user for the Create verb.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── CREATE ─────────────────────────────────────────────────────────────┐
│ │
│ CREATE [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Create request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Create is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Files may be created by users with at least OWNER authority.
Purpose
Create-Owned authorizes a user for the Create verb, for files that are
already owned.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── CREATE-OWNED ───────────────────────────────────────────────────────┐
│ │
│ CREATE-OWNED [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to Create files when
they already own the name.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Create-Owned is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Owned files may be created by users with at least REPLACER authority.
Purpose
The Disk starts a Disk Control Section, describing one of the disks
maintained by the TOOLSRUN service machine.
Context
Section Effects
Global Not allowed (defines start of disk section).
Disk Starts a new disk.
diskname CONTROL Not allowed.
Format
┌─── DISK ───────────────────────────────────────────────────────────────┐
│ │
│ DISK diskname address [password | NONE [mode | *]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
diskname The name that must be on all requests for this disk.
address The address to be used by toolsrun to link to the disk.
| • For a VM minidisk, address consists of ownerid owneraddr
| where:
| ownerid is the userid that owns the disk, use "*" for the
| TOOLSRUN machine.
| owneraddr is the hexadecimal address of the disk.
| • For SFS directories, address consists of
| [poolid:dir].subpool DIR
| where:
| poolid is the SFS Pool ID
| dir is a directory path.
| subdir is the subdirectory.
| The DIR keyword is required. If the Pool ID and directory
| path are omitted, they default to the Toolsrun machine's
| base directory.
password The MULTI password for a disk, or None if not required (as in
RACF). (An asterisk may be used instead of None.) If omitted,
the default is None..
mode The file mode letter at which the disk will be accessed
permanently. If omitted, the default is * and the disk will be
accessed at mode Z when needed, and released when not in use.
Restrictions
The TOOLSRUN userid must be able to link the minidisk (or SFS directory)
in write mode, even if other users are currently linked in read mode. The
following authorities will allow this:
• Provide the MULTI password under a password controlled security
system.
• Provide at least CONTROL access authorization under RACF.
| • Under SFS, provide WRITE and NEWWRITE authorization for the directory
and WRITE authorization for all files currently in the subdirectory.
Usage
Each disk maintained by the TOOLSRUN Service Machine is described by a
Disk statement. All statements that follow the Disk statement, up to the
next Disk statement or the end of the control file, apply to this
maintained disk.
Comments
The clean, days and file parameters (following mode) are also valid, to be
compatible with existing control files, however the Option statements
should now be used instead because these obsolete parameters may be
removed in the future.
For more information about using Toolsrun under SFS, see "Toolsrun and
SFS" in topic B.5.
The TOOLSRUN machine's own 191 disk may also be used as a maintained disk,
by describing it with a Disk statement. This permits distribution of
common files (e.g. TOOLSRUN EXEC, common control file includes, exits,
support files) among multiple TOOLSRUN machines using TOOLSRUN itself.
Care must be used, however, as there are some files (e.g. AUDIT) that will
be created or updated without being reflected in the NAMES file for the
disk, and files may be created, replaced or erased via SYSTEM commands
without being reflected in the NAMES file for the disk.
Purpose
Disk-Nocopy authorizes a user for the Nocopy keyword of the Disk request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── DISK-NOCOPY ────────────────────────────────────────────────────────┐
│ │
│ DISK-NOCOPY [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Nocopy
keyword on incoming Disk request statements.
Usage
Disk-Nocopy is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only PRIV users may issue NoCopy requests.
Purpose
Disk-Nocopy authorizes a user for the Disk Shutdown request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── DISK-SHUTDOWN ──────────────────────────────────────────────────────┐
│ │
│ DISK-SHUTDOWN [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Shutdown
keyword on incoming Disk request statements.
Usage
Disk-Shutdown is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only PRIV users may issue Shutdown requests to a disk.
Purpose
Disk-ShutPerm authorizes a user for the Shutperm keyword of the Disk
request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── DISK-SHUTPERM ──────────────────────────────────────────────────────┐
│ │
│ DISK-SHUTPERM [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Shutperm
keyword on incoming Disk requests.
Usage
Disk-ShutPerm is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only PRIV users may issue Disk Shutperm requests to a disk.
Purpose
Disk-Start authorizes a user for the Start request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── DISK-START ─────────────────────────────────────────────────────────┐
│ │
│ DISK-START [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Start keyword
on incoming Disk request statements.
Usage
Disk-Start is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It could be used to
give a non-Priv user authority to start a disk, such as when it could not
start due to a disk pack not mounted.
Defaults
Only PRIV users may issue Start requests to a disk.
Purpose
Intercept incoming requests from fromuser at fromnode that are directed to
disk fordisk and redirect them to disk diskname.
Context
Allowed only in global section.
Format
┌─── EQUATE DISK ────────────────────────────────────────────────────────┐
│ │
│ EQUATE DISK diskname fromnode fromuser fordisk │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
diskname The name of the disk on your service machine to receive the
updates.
fromnode The nodeid from which requests will be intercepted. An asterisk
(*) may be used to intercept requests from any node.
userid The userid from which requests will be intercepted. An asterisk
(*) may be used to intercept requests from any userid.
fordisk The diskname from which requests will be intercepted. An
asterisk (*) may be used to intercept requests for any unknown
disk.
Usage
Equate Disk may be used to:
• Redirect requests from an obsolete or renamed disk to the new disk,
while waiting for all users to get the word.
• Direct requests coming from a master to a shadow whose disk nickname
is different from the master.
• Direct requests coming from more than one master to a single shadow
disk.
• Route requests from specific users or nodes to a different disk.
Comments
Disk equates are applied before rerouting.
Examples
See "SOURCE" in topic 3.123 for an example using Equate Disk.
Defaults
Requests are applied to the disk specified in the request deck if the disk
exists on this service machine; rerouted if a Reroute is in effect for the
disk; or failed if the disk does not exist and is not rerouted.
Purpose
Intercept all requests from a listed node and translate the nodeid to
newnode. This means that newnode must appear instead of node in
authorization statements. A node may not be equated to more than one
newnode.
Context
Allowed only in global section.
Format
┌─── EQUATE NODE ────────────────────────────────────────────────────────┐
│ │
│ EQUATE [NODE] newnode node [node ... ] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
newnode The node to translate incoming requests to.
node A node to be translated into newnode. If you can't get all the
nodes on one line, duplicate the line up through newnode and
list additional nodes there. Any number of statements can be
used.
Usage
There exist several arrangements whereby a user may log onto more than one
system with the same userid. In such cases, it may be convenient to
equate all of the system nodes to one node name. Where explicit
authorizations are required, this can save duplication of authorization
for each node from which a user might send requests. Perhaps more
important (from the user's viewpoint), ownership (of files, appends,
informs, etc.) is shared by the userid on each of the equated nodes.
Comments
You may omit the keyword NODE, but we recommend that you don't.
Examples
Example of EQUATE NODE with authorization:
Equate Node IEC IECVM1 IECVM2 IECVM3
...
Owner IEC BOB; Allow user BOB from any of the nodes
Example of multiple records to handle many nodes:
Equate ALM ALMVMA ALMVMB ALMVMC ALMVMD
Equate ALM ALMVMX ALMVMZ ALMVSA ALMADEN
Equate AUS AUSVM1 AUSVM2 AUSVM3 AUSVM4
Equate AUS AUSVM5 AUSVM6 AUSVMQ
Node ALM includes both ALMVMA and ALMVMX.
Purpose
Equate Verb creates a new authorization verb that combines primitive
authorizations in some way not provided by the standard composite
authorizations.
Context
Allowed only in global section.
Format
┌─── EQUATE VERB ────────────────────────────────────────────────────────┐
│ │
│ EQUATE VERB newverb verb [verb ... ] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
newverb The new authorization verb being defined by this statement,
which may now be used in control file(s).
verb Persons who are given newverb authority will be allowed to use
this request verb. If you can't get all the verbs on one line,
duplicate the line up through newverb and list additional verbs
there. Any number of statements can be used. Other composite
verbs may be used, including those built in to TOOLSRUN (except
System).
Usage
Equate Verb is used when the standard composite authorizations do not meet
the needs of a special application. This might include:
• Removal of an undesired capability from one of the existing composite
authorizations, when the next lower composite is inadequate.
• Addition of a desired capability to one of the existing composite
authorizations, when the next higher composite is too powerful.
• Design of a wholly new composite.
Restrictions
EQUATE VERB may not be used to redefine any existing verb, including those
created by a prior EQUATE VERB.
verb may only be a primitive authorization verb or composite authorization
verb (except System). Other types of verbs are not allowed.
Examples
GETTER authorization is desired, with informs and subscribes, but without
Inform Copy:
* Global section
EQUATE VERB GETNOCOP INFORM-ALL INFORM-NEW INFORM-SUB INFORM-EXC
EQUATE VERB GETNOCOP INFORM-REF INFORM-UPD
EQUATE VERB GETNOCOP QUERY-DISK QUERY-FILE QUERY-INFORM GET LIST
EQUATE VERB GETNOCOP SUMMARY UNINFORM SET-ADDRESS REGISTER TRACE
* Disk section
GETNOCOP * *; Allow everyone GETTER without Inform Copy
Defaults
The following composite verbs are built in to TOOLSRUN:
• GETTER
• APPENDER
• REPLACER
• PACKAGER
• OWNER
• PRIV
• SYSTEM (1)
(1) System is a special composite: Its primitives may not be
used separately, and System may not be used in EQUATE VERB.
Purpose
Erase authorizes a user for the Erase request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── ERASE ──────────────────────────────────────────────────────────────┐
│ │
│ ERASE [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Erase request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Erase is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Only users with at least OWNER authority may issue Erase requests.
Purpose
Get authorizes a user for the Get request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── GET ────────────────────────────────────────────────────────────────┐
│ │
│ GET [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Get request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Get is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Only users with at least GETTER authority may issue Get requests.
Purpose
Getter is a composite authorization verb.
Group Definition of the Group
Getter Batch-Cancel + Batch-Query + Get + Inform-All +
Inform-Cop + Inform-Exc + Inform-New + Inform-Ref +
Inform-Sub + Inform-Upd + Query-Disk + Query-File +
Query-Inform + List + Register + Renew + Set-Address +
Summary + Trace + Uninform
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── GETTER ─────────────────────────────────────────────────────────────┐
│ │
│ GETTER [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine. group of request verbs listed.
userid The userid of a person to be authorized for this group of
request verbs.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
GETTER is the normal authorization for users who are permitted to get
files from a disk, but not to create, replace or append to files on the
disk.
Defaults
ACCESSER * *
unless overridden by
verb * *
where verb is some other authorization verb (e.g. Getter).
Purpose
One or more Help statements prior to the first Disk statement form the
"general help text" which will appear along with the text from all other
Help statements when a request is received for a disk that is not known,
or if Help All is requested.
One or more Help statements after a Disk statement form the "disk help
text" which will be presented upon request for help for that specific
| disk, included in the response to a failed request and added to the
response to a Query Disk request.
Context
Section Effects
Global Response to Help All or Help for an unknown disk.
Disk Response to Help for just that disk.
diskname CONTROL Not Allowed
Format
┌─── HELP ───────────────────────────────────────────────────────────────┐
│ │
│ HELP text │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
text A line of mixed case text. If you can't get all the text on one
line, additional Help statements may be used.
Usage
Help statements provide guidance for the user who wants to know what disks
are supported by the TOOLSRUN service machine, or who has forgotten the
exact spelling of a disk name. Additional information, such as the fact
that access is restricted and the procedure for getting authorization, may
also be useful. Note that the Contact keyword on Notify statements will
automatically supply the node, userid and name of the person to contact
about the disk or TOOLSRUN service machine when help is requested.
Defaults
If there is no Help statement for a disk, it will not be listed in the
"general help". Also, the response to a Help request for that specific
disk will be "There is no help available for the diskname disk."
Purpose
Hide authorizes a user for the Hide request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── HIDE ───────────────────────────────────────────────────────────────┐
│ │
│ HIDE [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Hide request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Hide is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Only users with at least REPLACER authority may issue Hide requests.
Purpose
History Single overrides the default of History Multiple, concentrating
all history information for the disk into a single file. (See also
"HISTORY MODE0" in topic 3.38.)
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── HISTORY ────────────────────────────────────────────────────────────┐
│ │
│ HISTORY {MULTIPLE | SINGLE} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
MULTIPLE Specifies that the history information will be kept in a
separate HISTORY file for each different filename. This is the
default.
SINGLE Specifies that all history information will be kept in one file.
Usage
History Multiple provides a convenient way to examine the history of one
file, while effectively doubling the number of files on the disk. History
Single, while not saving any disk space (the total amount of information
is the same), reduces "clutter" on the disk when most users are not
interested in history information.
Defaults
HISTORY MULTIPLE
Purpose
This statement causes new HISTORY file(s) to have a filemode digit of zero
so that they are not normally visible to users. (See also "HISTORY" in
topic 3.37.)
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── HISTORY MODE0 ──────────────────────────────────────────────────────┐
│ │
│ HISTORY MODE0 │
│ │
└────────────────────────────────────────────────────────────────────────┘
Usage
Where history information is considered sensitive, it may be desirable to
hide the diskname HISTORY file by making its filemode digit zero.
Non-PRIV users will not be able to Get the file, and local users who link
to the disk will not normally see the file.
Defaults
History files are normally visible to local users linked to the disk, and
can be accessed via TOOLS requests.
When History Multiple is in effect, and history information is not
considered useful to most users, History Mode0 can be used to eliminate
the large number of history files from the view of most users. As needed,
individual history files may be made visible, using Set Mode requests.
They will remain visible until returned to file mode zero by another Set
Mode request.
Purpose
When the control file is processed at initialization time, the included
files are processed exactly as if their entire content replaced the
Include statement.
Context
Not allowed in a Disk CONTROL file.
Format
┌─── INCLUDE ────────────────────────────────────────────────────────────┐
│ │
│ INCLUDE fname ftype [fmode | A | = | *] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
fname Specifies the file name of a control file subroutine.
ftype Specifies the file type of a control file subroutine.
fmode Specifies the file mode letter of a control file subroutine.
The file mode may be any valid filemode letter, * or =. A file
mode letter of = is valid only if the Include appears after a
Disk statement, and means that the included file is on the
maintained disk. A file mode letter of * means that all disks
are to be searched for the included file, and that the first
file encountered in the CMS search order, that matches fname.
ftype, will be used.
The default is A.
Usage
Include is most useful for cases where TOOLSRUN CONTROL statements are
brought in from some other source. The most notable example would be
IBMNODE EQUATES, a collection of EQUATE NODE statements for all known IBM
systems where request files from a particular user may show any of several
nodes. (IBMNODE EQUATES is available from the IBMVM disk.)
Similar examples would be global section statements shared by more than
one TOOLSRUN Service Machine, and diskname SHADOWS files (containing Copy
statements) kept on the maintained disks as a convenience to users.
(While Copy statements can appear in a diskname CONTROL file, the
trade-off is between being able to change the shadow list without
restarting TOOLSRUN, and not having to remember to update the diskname
SHADOWS file when changes are made.)
Still another example would be a Peer network. A common file listing all
of the peers in the network can be shared, perhaps as a file on the
maintained disk. If each of the peer TOOLSRUN Service Machines includes
this file (with a filemode of "z") after the Disk statement, then the list
can be updated from any one of the peers, and will go into effect
completely when all have re-started. This is facilitated by the fact that
a Peer statement for "self" is ignored.
Include also permits statements common to several disks to be kept in one
file, yet be processed as if repeated after each Disk statement. While
this once was useful for all statements that could follow a Disk
statement, most of those statements can now appear before the first Disk
statement, providing new defaults for the disks. Non-PRIV authorizations
should generally be moved to a diskname CONTROL file, although Include
might be useful in a case where there are several authorizations common to
more than one disk, and where re-starting TOOLSRUN to process changes is
acceptable. Mostly, Include would be used to repeat PRIV and Notify
statements, where those are common to several disks. In some cases, it
might be useful to repeat network control verbs, such as Master.
Comments
Toolsrun imposes no restriction on nesting depth, fname or ftype.
Maintained disks may have both a diskname CONTROL file and one or more
included files. Unlike the former, the latter may contain any control
verbs.
We recommend the use of diskname CONTROL rather than an included file on
the maintained disk because it will be reprocessed when replaced and
provides more control.
Purpose
| This enables the Inform request for the disk (see below for individual
| user authorization) and optionally enables list processing.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── INFORM ─────────────────────────────────────────────────────────────┐
│ │
| │ INFORM [{rscsnode | *} [{listid | *} [NOSUBscribe | SUBscribe]]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
| rscsnode The nodeid of the RSCS service machine that is to handle
distribution. Enter an asterisk (*) to get the default of
thisnode - the same node as the TOOLSRUN service machine.
| This is the default.
| listid The userid of the RSCS list processor (usually *LIST).
Enter an asterisk (*) for both the nodeid and userid to get
the default - no list processing.
NOSUBscribe Allow users to be informed of changes, but not receive
updated files by subscription, by enabling the All, Exclude
| and New keywords on the Inform request. You may also
| specify an asterisk (*) to mean the same thing. This is the
default.
SUBscribe Allow users to be informed of changes and/or receive updated
files automatically by additionally enabling the Copy,
Reference, Subscribe and Update keywords on the Inform
request.
Usage
Inform requests are enabled for the disk. However, this does not affect
authorization to use the requests. Authorization to issue Inform requests
is controlled by the Inform-All, Inform-Cop, Inform-Exc, Inform-New,
Inform-Ref, Inform-Sub and Inform-Upd primitive verbs, which are included
in the Getter composite verb.
List processing is an efficient method for distributing informs and
subscriptions to remote users: In general, the TOOLSRUN service machine
need send only one file to the network. When set up as shown, inform and
subscription files will be distributed by the RSCS list processor, except
for Nearby nodes (see "NEARBY" in topic 3.58). You may code asterisks (*)
for the node and userid to cause the service machine to handle all
distribution.
Restrictions
You may not use both NOSUBSCRIBE and SUBSCRIBE in the same disk section.
Comments
If an Inform statement is specified, the response to a Query Disk request
will note this. The response will also indicate whether list processing
and subscriptions are enabled.
Inform and subscription processing is expensive, both in terms of TOOLSRUN
service machine CPU cycles and network resources. While it is normal to
enable it for conference disks, it may not be necessary for other types of
TOOLSRUN controlled disks.
Removing the Inform statement is a good way to temporarily suspend informs
and subscriptions while preserving the contents of the diskname INFOLIST
file.
How to determine the list processor id: First, enter the CMS Identify
command. The response names the RSCS service machine ("userid AT node VIA
rscs-machine" - often called RSCS). Next, ask the RSCS service machine
what links are connected: CP SMSG rscs-machine Q LINKS. The response
will list several columns titled Name, Status, Type, and so on. The name
that has type LISTPROC is the local list processor.
Defaults
The Inform request is disabled if there is no INFORM statement in effect
for this disk.
List processing is disabled if there is no INFORM statement in effect for
this disk (except where affected by COPY or ROUTE statements). While
there is no Inform statement in effect for this disk, the Set Address
request will not alter addresses in the diskname INFOLIST file,
subscription expiration is suspended, and the following requests will
fail: Inform, Renew, Uninform.
Purpose
Inform-All authorizes a user for the Inform request with the All keyword.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── INFORM-ALL ─────────────────────────────────────────────────────────┐
│ │
│ INFORM-ALL [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Inform
request with the All keyword.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Inform-All is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with at least GETTER authority may issue Inform requests with
the All keyword, and only if informs have been enabled for the disk with
the Inform statement.
Purpose
Inform-Cop authorizes a user for the Inform request with the Copy keyword.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── INFORM-COP ─────────────────────────────────────────────────────────┐
│ │
│ INFORM-COP [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Inform
request with the Copy keyword.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Inform-Cop is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with at least GETTER authority may issue Inform requests with
the Copy keyword, and only if subscribes have been enabled for the disk
with the Subscribe keyword on the Inform statement.
Purpose
Inform-Exc authorizes a user for the Inform request with the Exclude
keyword.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── INFORM-EXC ─────────────────────────────────────────────────────────┐
│ │
│ INFORM-EXC [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Inform
request with the Exclude keyword.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Inform-Exc is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with at least GETTER authority may issue Inform-Exc requests,
and only if informs have been enabled for the disk with the Inform
statement.
Purpose
Inform-New authorizes a user for the Inform request with the New keyword.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── INFORM-NEW ─────────────────────────────────────────────────────────┐
│ │
│ INFORM-NEW [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Inform
request with the New keyword.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Inform-New is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with at least GETTER authority may issue Inform requests with
the New keyword, and only if informs have been enabled for the disk with
the Inform statement.
Purpose
Inform-Ref authorizes a user for the Inform request with the Reference
keyword.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── INFORM-REF ─────────────────────────────────────────────────────────┐
│ │
│ INFORM-REF [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Inform
request with the Reference keyword.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Inform-Ref is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Comments
Inform-Ref is experimental and may be changed or removed in the future.
Defaults
Only users with at least GETTER authority may issue Inform requests with
the Reference keyword, and only if subscribes have been enabled for the
disk with the Subscribe keyword on the Inform statement.
Purpose
Inform-Sub authorizes a user for the Inform request with the Subscribe
keyword.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── INFORM-SUB ─────────────────────────────────────────────────────────┐
│ │
│ INFORM-SUB [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Inform
request with the Subscribe keyword.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Inform-Sub is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with at least GETTER authority may issue Inform requests with
the Subscribe keyword, and only if subscribes have been enabled for the
disk with the Subscribe keyword on the Inform statement.
Purpose
Inform-Upd authorizes a user for the Inform request with the Update
keyword.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── INFORM-UPD ─────────────────────────────────────────────────────────┐
│ │
│ INFORM-UPD [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Inform
request with the Update keyword.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Inform-Upd is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Comments
Inform-Upd is experimental and may be changed or removed in the future.
Defaults
Only users with at least GETTER authority may issue Inform requests with
the Update keyword, and only if subscribes have been enabled for the disk
with the Subscribe keyword on the Inform statement.
Purpose
Insert-Header authorizes a user for the Append request with the Insert
option and a timestamp of zero.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── INSERT-HEADER ──────────────────────────────────────────────────────┐
│ │
│ INSERT-HEADER [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use the Append
request with a timestamp of zero and the keyword Insert which
places a header at the beginning of an appendable file.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Insert-Header is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with at least REPLACER authority may issue requests to insert a
header, and only if they own the file.
Purpose
Interval sets the maximum period that Toolsrun will remain asleep. The
TOOLEXIT EXEC exit will be run at this interval when there is no work to
do.
Context
Allowed only in global section.
Format
┌─── INTERVAL ───────────────────────────────────────────────────────────┐
│ │
│ INTERVAL time │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
time May be specified as minutes, minutes:seconds or
hours:minutes:seconds.
Usage
Without this statement, the TOOLDAY EXEC exit will not be run until after
| the first batch of requests after midnight are processed, or the first
| TOOLEXIT TIMES event of the day expires.
Requests sent from MVS systems are normally class B, and so must be
recognized and changed to class M by the TOOLEXIT EXEC. Interval should
be set to some acceptable delay for such requests arriving when there is
no other activity on the disk.
On some systems, the TOOLSRUN service machine may be logged off after a
period of inactivity. To prevent this, Interval should be set to some
time less than this period.
Comments
If message processing is enabled, Interval is less reliable than using
TOOLEXIT TIMES to trigger periodic events. This is because the interval
timer is reset, but TOOLEXIT EXEC is not called, when a message is
processed. See "TOOLEXIT TIMES" in topic A.6.
Defaults
TOOLSRUN will not wake up except to process class M requests (and
messages, if the Msg statement is specified) (and TOOLEXIT TIMES events,
if both TOOLEXIT EXEC and TOOLEXIT TIMES are present).
Purpose
Used to limit the amount of data that can be obtained with a single
request. In each case, asterisk (*) means no limit.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── LIMITS ─────────────────────────────────────────────────────────────┐
│ │
│ LIMITS getfiles gdays reffiles rdays │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
getfiles The maximum number of files that will be sent in response to a
single Get request, defaults to 30. Code an equal sign (=) to
get the default. Code an asterisk to specify no restriction.
gdays The oldest since date that will be allowed in a Get request,
defaults to 30. Code an equal sign (=) to get the default.
Code an asterisk to specify no restriction.
reffiles The maximum number of files that will be sent in response to a
single Refresh request, defaults to no restriction. Code an
equal sign (=) to get the default. Code an asterisk to specify
no restriction.
rdays The oldest since date that will be allowed in a Refresh request,
defaults to no restriction. Code an equal sign (=) to get the
default. Code an asterisk to specify no restriction.
Usage
A Refresh request is a Get-Copy request from a userid and node identified
on a Copy, Peer or Servant card. (It is usually generated by a shadow
machine in response to a Refresh request sent to it.) If a Get-Copy
request is received from any other userid and node, it is subject to the
Get limits.
Get and Refresh requests that use patterns for the filename and filetype
(in particular, "* *") can cause a large number of files to be
transmitted. This will often occur during peak daytime periods,
effectively overloading the network. Get * * is a common new user
mistake: The user has just discovered a "new" disk, and requests
everything on it. The default limits protect this user against a barrage
of thousands of files, many of them years old, and protects the network
from overload and the local system from spool space exhaustion.
In some cases, it is normal and desirable for users to request large
numbers of files by pattern. Limits may be used to loosen the
restrictions.
While PRIV users are expected to be more knowledgeable than the average
user, someone who is setting up a shadow for the first time may naively
send a Refresh * * request to his disk, causing a &getcop. * * to a master
with a large number of files. This can effectively halt all other
activity on an otherwise busy disk, clog the network, and exhaust spool
space on the master's system as other requests queue up. Limits can be
used to protect a busy master disk against this.
Defaults
LIMITS 30 30 * *
A maximum of 30 files, no more than 30 days old, will be sent in response
to a single Get request. There is no restriction on the number or age of
files that will be sent in response to a single Get-Copy request from a
shadow or peer.
Purpose
List authorizes a user for the List request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── LIST ───────────────────────────────────────────────────────────────┐
│ │
│ LIST [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the List request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
List is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Only users with at least GETTER authority may issue List requests.
Purpose
Local gives TOOLSRUN the information it needs to communicate with the
local RSCS service machine and local users, and to format messages sent to
local users.
Context
Allowed only in global section.
Format
┌─── LOCAL ──────────────────────────────────────────────────────────────┐
│ │
│ LOCAL {thisnode | *} {net | *} [{netmsg | SMSG} [{usrmsg | MSG } │
│ [{lclhdrlen | *} [nethdrlen | *]]]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
thisnode The node where TOOLSRUN will run (code asterisk to use
IDENTIFY).
net The userid of the RSCS network service machine (code asterisk to
use IDENTIFY).
netmsg The command for sending messages to the RSCS service machine.
If omitted, the default is the CP SMSG command.
usrmsg The command for sending messages to local users. The following
keywords are recognized:
MSGHDR ToolsRun is to use the MSGNOH command, if
available, and prefix each message with "MSG
FROM."
RSCS ToolsRun is to send messages via the network.
If omitted, the default is the CP MSG command.
lclhdrlen The length of the header prefixed to the left of messages to
local users, defaults to 20 for VM/SP or 32 otherwise. The
allowed range is 0-40. Code an asterisk to get the default.
nethdrlen The length of the header prefixed to the left of messages to
users from RSCS, defaults to 10+Length(node)+Length(userid)
where "node" and "userid" are the TOOLSRUN service machine's
node and userid. The allowed range is 0-40. Code an asterisk
to get the default.
Usage
Local is used when:
• The CMS IDENTIFY command does not return the userid of the local RSCS
service machine.
• Some command other than SMSG is used to communicate with the RSCS
service machine.
• Some command other than MSG is used to communicate with local users.
For example, MSGNOH may be used at some installations to send messages
to local users without the usual MESSAGE FROM USERID header.
• The local RSCS service machine formats messages with a different
header length.
• The command used to send messages to local users formats messages with
a different header length.
The lclhdrlen default of 20 assumes an 8 character userid for the TOOLSRUN
service machine, plus 12 other characters in the message header (including
spaces). If your TOOLSRUN service machine userid is less than 8
characters, or if the message header is not 12 characters, you can tell
TOOLSRUN the correct value via LOCAL. This may result in cleaner looking
TOOLSRUN messages sent to local users.
The nethdrlen default assumes, in addition to the lengths of the node and
userid, 10 other characters in the message header (including spaces). If
these values are not correct for your TOOLSRUN service machine or for your
installation, you can tell TOOLSRUN the correct value via LOCAL. This may
result in cleaner looking TOOLSRUN messages sent to users over the
network.
Restrictions
thisnode must match the node returned by the CMS IDENTIFY command, else
TOOLSRUN will not start.
net must match one of the RSCS network service machine userids returned by
the CMS IDENTIFY command. If it does not match, TOOLSRUN will start, but
will issue a warning while starting.
Defaults
LOCAL identify-node identify-net SMSG MSG 20 26
where identify-node and identify-net are the node and RSCS userid returned
from the CMS IDENTIFY command.
Purpose
Lock authorizes a user for the Lock request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── LOCK ───────────────────────────────────────────────────────────────┐
│ │
│ LOCK [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Lock request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Lock is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Comments
The Lock request is experimental and may be changed or removed in the
future.
Defaults
Only users with at least REPLACER authority may issue Lock requests.
Purpose
Authorizes a source of forwarded requests.
Context
Section Effects
Global Not allowed
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── MASTER ─────────────────────────────────────────────────────────────┐
│ │
│ MASTER node userid [msglvl | 10] [RETAIN hours] [CONTACT name] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of another service machine.
userid The userid of another service machine.
msglvl The minimum level of a response, the default is 10 to suppress
all messages. See "Message Levels" in topic B.1.
hours Number of hours to retain a forwarded request that has been
deferred, before purging it and requesting a refresh from the
source.
If hours is zero, forwarded requests will not be deferred.
name Information about the contact person at the source. This is now
obsolete and is ignored. The same effect of "self
documentation" may be achieved with a semicolon comment.
Usage
Specifically, Master authorizes node userid to send Put requests, and to
propagate requests (i.e. the request deck contains Origin) and reroute
requests (i.e. the request deck contains From). Propagated requests will
not be checked for originator authorization, but will be processed as
though the original submittor were PRIV at this service machine. In
addition, node userid will be sent a Get-Copy in response to a Refresh, if
no Source is specified. (See "SOURCE" in topic 3.123.)
RETAIN applies to requests that might have raced ahead of an earlier
request. Examples would be a CREATE arriving before an ERASE (or vice
versa), an APPEND MODIFY arriving before an APPEND, or a REGRESS arriving
before a HIDE (or vice versa). It is assumed that the request succeeded
at the source (else it would not have been forwarded), and so some other
request may arrive later that will allow this one to succeed. The request
is deferred for hours hours. If the request has not been undeferred
successfully at the end of the retention period, it is purged and a
refresh (where appropriate) is requested from the source.
| Comments
| Unless you are asked to do so by an administrator of the other service
| machine (say, for debugging a particular problem), it is a bad idea to set
| the msglvl less than 10; this can cause a flood of responses sent back to
| the other machine under certain circumstances.
Examples
See "SOURCE" in topic 3.123 for an example of multiple Master cards used
for a partial shadow.
Defaults
RETAIN 48
Purpose
Modify authorizes a user for the Append request with the Modify option and
a non-zero timestamp.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── MODIFY ─────────────────────────────────────────────────────────────┐
│ │
│ MODIFY [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use a non-zero
timestamp and a keyword of Modify on an Append request to modify
an append in an appendable file.
Note: If no keyword follows a timestamp on an Append request,
it is as if Modify were present.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Modify is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Only users with at least APPENDER authority may issue requests to modify
an append. In addition, only the owner of the file may insert appends
(i.e. the timestamp on the append and the node and userid of the
submitter do not match an existing append).
Purpose
Modify-Header authorizes a user for the Append request with the Modify
option and a timestamp of zero.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── MODIFY-HEADER ──────────────────────────────────────────────────────┐
│ │
│ MODIFY-HEADER [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to use a timestamp of
zero and a keyword of Modify on an Append request to modify the
header portion of an appendable file.
Note: If no keyword follows a timestamp on an Append request,
it is as if Modify were present.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Modify-Header is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with at least REPLACER authority may issue requests to modify a
header, and only if they own the file.
Purpose
This allows the service machine to accept requests via immediate messages.
Context
Allowed only in global section.
Format
┌─── MSG ────────────────────────────────────────────────────────────────┐
│ │
│ MSG {IUCVMSG | SMSG | BOTH} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
IUCVMSG The CP MSG command is allowed. IUCV is used to capture the
text.
SMSG The CP SMSG command is allowed. In this case, IUCV may be
used for another purpose.
BOTH Both MSG and SMSG will be allowed.
Usage
The service machine will convert the message into a Tools-format request
and punch it to itself. If the request came from a SYSTEM user, it will
be ordered to the top and performed next.
Comments
LOCAL is a synonym for SMSG for compatibility reasons, but may be removed
in the future.
Defaults
Requests via immediate messages will not be accepted.
Purpose
Nearby lists nodes that are near (network-wise) to the TOOLSRUN service
machine. TOOLSRUN will forward files, informs, etcetera directly to
nearby nodes, instead of routing them through a list processor.
Context
Allowed only in global section.
Format
┌─── NEARBY ─────────────────────────────────────────────────────────────┐
│ │
│ NEARBY node [node ... ] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node A nodeid that will receive forwarded requests directly, rather
than being distributed by a list processor. If you can't get
all the nodes on one line, additional Nearby statements may be
used.
| You may specify a pattern instead of an actual nodeid. The
| pattern may have a single asterisk (*) as either the first or
| last character. This permits nodeids to match if they end with
| or begin with the rest of the pattern, respectively.
Usage
| To reduce network traffic, TOOLSRUN may take advantage of list processing,
wherein a single copy of a file is sent to the nearest list processor.
The list processor examines the list of addressees, and makes copies of
the file and splits up the address list, sending individual copies to
nearby nodes, and forwards single copies to more distant list processors
for additional copying and subdivision. This may cause excessive local
traffic, however, if there are nodes that are as close or closer than the
list processor: A single file is sent out, only to be returned as
multiple copies. In this case, Nearby may be used to reduce network delay
and clogging by causing TOOLSRUN to send the files directly to the nearby
nodes.
Comments
List processing is used only if specifically enabled by the INFORM
statement (except as affected by COPY or ROUTE statements).
Defaults
| No node is considered nearby. However, list processing is never used to
| send files to users on the same node as the Toolsrun service machine, nor
| to any node in the same CSE complex as the Toolsrun service machine's
| node.
Purpose
Newown authorizes a user to issue Newown requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── NEWOWN ─────────────────────────────────────────────────────────────┐
│ │
│ NEWOWN [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Newown request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Newown is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Users must have at least REPLACER authority to issue Newown requests.
Purpose
The authorization verb newverb represents a verb that has been defined
using the Equate Verb statement.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk (Not allowed if any PRIV
primitives are included)
Format
┌─── newverb ────────────────────────────────────────────────────────────┐
│ │
│ newverb [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for a group of request
verbs defined elsewhere on an Equate Verb statement.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Equate Verb may be used to combine primitive authorization verbs in ways
that are not provided by the standard composite verbs. The new verb
newverb may be used just as any of the other composite verbs.
Restrictions
The Equate Verb for newverb must precede its first use in the control
file.
If newverb is composed of any PRIV authorization primitives, it may not be
used in the &diskname. CONTROL file.
Defaults
The following composite verbs are built in to TOOLSRUN:
• GETTER
• APPENDER
• REPLACER
• PACKAGER
• OWNER
• PRIV
• SYSTEM
Purpose
One or more Notify statements may be placed before the first Disk
statement to specify the user to receive the text in notify requests
received by the service machine, and messages about unusual occurrences on
the service machine.
One or more Notify statements may be placed after a Disk statement to
specify the destination of notify text concerning that disk, and messages
about unusual occurrences on the disk.
Context
Section Effects
Global Identifies System Notify recipients.
Disk Identifies diskname Notify recipients.
diskname CONTROL Not Allowed
Format
┌─── NOTIFY ─────────────────────────────────────────────────────────────┐
│ │
│ NOTIFY [node] userid [CONTACT name] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person, defaults to the same as the service
machine.
userid The userid of a person to receive the text in Notify requests.
CONTACT An optional keyword, to be entered as shown if name is
specified.
name The name of the person who is the primary contact for the
service machine or disk. The name, node and userid of the
contact will be appended automatically to the help text (if
| any). The name, node and userid of the disk contact will be
| appended automatically to the disk help text (if any), the text
| of responses to failed requests, and to the text of subscription
| expiration warnings and notices.
Usage
Notify users will receive the text of notify requests sent by users. This
provides a means for communicating with the disk or TOOLSRUN system
maintainers, without identifying their node and userid.
Notify users will also receive the text of messages about unusual
occurrences (such as disk full or failed requests). They will also
receive informational messages (e.g. TOOLSRUN STARTING) if logged on to
the same system as the ToolsRun machine.
Restrictions
If specified, node must not be an equated node.
| Comments
| If more than one CONTACT is specified for the system, or for a disk, the
| last one specified is used.
Defaults
System Notify If no system notify user is specified, the first SYSTEM
user will receive notify text. (If no SYSTEM user
exists, ToolsRun will abend.)
System Contact If NOTIFY cards exist, but no CONTACT is given, the
first system notify user will receive notify text. If
no NOTIFY cards exist, the first SYSTEM user will
receive notify text.
Disk Notify If no NOTIFY cards exist in the disk section, the system
notify users will receive disk notify text.
Disk Contact If NOTIFY cards exist, but no CONTACT is given, the
first disk notify user is used. If no NOTIFY cards
exist in the disk section, the SYSTEM CONTACT is used.
Purpose
Option Adiskfull specifies the threshold at which system A-disk full
warnings will be sent.
Context
Allowed only in global section.
Format
┌─── OPTION ADISKFULL ───────────────────────────────────────────────────┐
│ │
│ OPTION ADISKFULL percentfull [blocksleft | 0] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
percentfull A whole number between 0 and 100, defaults to 75.
blocksleft A positive whole number, defaults to zero.
Usage
| When TOOLSRUN starts, warning messages will be issued to all SYSTEM NOTIFY
users if the system's A-disk is more than percentfull full and either
blocksleft is zero, or there are fewer than blocksleft unused blocks left
on the system's A-disk.
As every request generally results in lines added to both the @SYSTEM
AUDIT file and a diskname AUDIT file, a small disk can fill up pretty
rapidly on a busy day. If not attended to, TOOLSRUN may have to shut
itself down, so it is important that the threshold be set low enough to
allow time to react to the impending problem.
The defaults assume a relatively small A-disk. Where a larger A-disk is
used, Option Adiskfull may be used to prevent warning messages until there
is truly a need to deal with an impending space problem.
| Comments
| This option does not work well if the A-disk is actually an SFS
| subdirectory, as there is no fixed space associated with an individual
| subdirectory. (See "Toolsrun and SFS" in topic B.5.)
Defaults
OPTION ADISKFULL 75 0
Purpose
Option Backup specifies that the old copy of a file is to be kept as a
backup file when replaced.
Option NoBackup specifies that the old copy of a file is to be discarded
when replaced.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION BACKUP ──────────────────────────────────────────────────────┐
│ │
│ OPTION {BACKUP | NOBACKUP} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
BACKUP Keep the old copy of a file as a backup when replaced.
NOBACKUP Discard the old copy of a file when replaced.
Usage
Option NoBackup is used to help reduce disk filling due to keeping backup
files. No space is immediately saved, unless Option UnSafe is also
specified, but cleaning with Clean Erasable will erase the previous copy
of the file right away.
See "OPTION CLEAN" in topic 3.65 for a description of backup files.
This option affects only the creation of backups as a result of replacing
the file, by a Replace or Place request, or as a result of an Update
request that is not an update-in-place.
Comments
Option (No)Backup is experimental and subject to change or deletion in the
future.
Error Conditions
Option NoBackup entails some risk:
• Regression is prevented, so recovery of previous versions may be
difficult or impossible.
• If users are accessed to the disk while files go from visible to
erasable to erased, the effects on these users are unpredictable.
• If Option UnSafe is also specified, there is greatly increased chance
of unpredictable effects on user's sessions, as files will go directly
from visible to erased.
Defaults
OPTION BACKUP
Purpose
Option Batch specifies the type of requests that should be kept in the
batch queue for this disk. Batched requests will be sent out at a later
time (when a BATCH RELEASE command is received).
Option NoBatch inhibits the batching of requests.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION BATCH ───────────────────────────────────────────────────────┐
│ │
| │ OPTION {BATCH batchtype [batchdays | 0] [batchmsg] | NOBATCH} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
BATCH Specifies the type of batching to be performed.
batchtype Choose one of:
ALL Batch both get- and refresh-type requests.
GET Batch only get-type requests.
REFRESH Batch only refresh-type requests.
batchmsg This message will be appended to the message that goes back to
the originator of a request that gets batched. The message can
be as many words as necessary and is sent exactly how it is
specified here, including case. This is optional.
| batchdays Specifies how often (in days) users may release one of their
| own requests from the batch queue, using BATCH RELEASE fnpat
| ftpat (Zero means a user may release any number of their own
| requests.) This is optional. If omitted, users may not
| release their own requests.
NOBATCH Specifies that batching is turned off.
Usage
If OPTION BATCH REFRESH is specified, only those requests that would
normally have come from a shadow (ie.- GET ... COPY requests, or COPY
requests that come from a full shadow) will be batched. If OPTION BATCH
GET is specified, only those requests that would normally have come from
an individual (ie. - GET ... NETDATA or GET ... ASIS requests) will be
batched. If OPTION BATCH ALL is specified, both of these types of
requests will be batched.
| Releasing:
• A PRIV user may release batched requests with a BATCH RELEASE request.
• Automatic release may also be done via TOOLEXIT TIMES. (See "TOOLEXIT
TIMES" in topic A.6.)
| • If batchdays is above zero, users may release their own batched
| requests, or those of other users, once every batchdays days, using
| BATCH RELEASE fnpat ftpat, where the filename filetype pattern exactly
| matches the pattern specified in a request currently in the batch
| queue. If batchdays is zero, users may release any number of
| reqeusts. If batchdays was not specified, users may not release their
| own requests.
Requests are not batched if:
• From a PRIV user.
• The filename in the request is the same as the diskname.
• The filetype in the request is REQUESTS or HISTORY.
• A sincedate parameter is specified.
• No list processor is specified in an applicable Inform, Copy or Route
control card.
• Batching has been disabled on the fly by setting BATCH.diskname=0 in
GLOBALV.
• This is a GET request and only REFRESH requests are being batched, or
this is a REFRESH request and only GET requests are being batched.
• The destination node is too close to benefit from list process
distribution:
- The same node as the Toolsrun service machine.
- In the same CSE complex as the Toolsrun service machine.
- Specified on a Nearby control card.
Comments
Although OPTION NOBATCH is currently the default, it is strongly suggested
that this not be used. In order to reduce costs and increase efficiency,
OPTION BATCH should be specified, and list processing should be enabled
(see "INFORM" in topic 3.40).
Results
When a GET (or a certain type of COPY (2) ) request is received, the exact
request is added to an on-disk batch database (diskname BATCHDB) instead
of immediately being processed. (The request, of course, may contain
asterisks or may be a request for a package file. These are not expanded
when the request is added to the database.) The response to the requester
tells what happened.
Some time later, requests in the queue are released:
• By a BATCH RELEASE request from a PRIV user
• By a BATCH RELEASE request in the TOOLEXIT TIMES file (see "TOOLEXIT
TIMES" in topic A.6)
• Just before TOOLDAY is run, if there is no TOOLEXIT TIMES file (BATCH
RELEASE ALL)
• If batching is disabled for the disk (BATCH RELEASE ALL)
All the files are then sent out (using the list processor if available).
This may result in fewer individual copies of a file being sent out.
| In an emergency, a PRIV user may release a particular user's requests from
| the batch queue, by issuing a BATCH RELEASE request with the FOR override,
| specifying that user. In addition, if batchdays is specified, users may
| release one request for themselves or another user, once every batchdays
| days, by issuing a BATCH RELEASE request that specifies a fileid pattern
| that exactly matches a fileid pattern in a batched request.
Defaults
OPTION NOBATCH
Note: This may change in a future release.
(2) COPY requests with an ORIGIN, received from a full shadow,
represent an older method of refresh, and so are batched as
if GET COPY. (These are generated by older versions of
TOOLCARE, still in widespread use.)
Purpose
Option Clean specifies the type of startup automatic cleaning to be
performed and the age of files eligible to be deleted by startup automatic
cleaning.
Option NoClean inhibits startup automatic cleaning.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION CLEAN ───────────────────────────────────────────────────────┐
│ │
│ OPTION {CLEAN cleantype [days | 0 ] | NOCLEAN} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
CLEAN Specifies the type of startup automatic cleaning to be
performed, and provides a default cleantype for OPTION
CLEANFULL.
cleantype Choose one of:
| SAFE Remove erasable files older than the most recent
| system IPL. This is the default.
| ERASABLE Remove all erasable files now.
| BACKUPSAFE Remove all erasable files older than the most
| recent system IPL. Convert backup files to
| erasable for later removal.
| BACKUP Remove all erasable and backup files now.
| ALLSAFE Remove all erasable files older than the most
| recent system IPL. Convert backup and hidden
| files to erasable for later removal.
| ALL Remove all erasable, backup and hidden files
| now.
NAMES Clean the diskname NAMES and diskname INFOLIST
files.
days Preserve a file eligible for erasure for this many days,
| defaults to zero. (Erasable files older than the most recent
| system IPL are never preserved.)
NOCLEAN Specifies that startup automatic cleaning is not to be
performed.
Usage
When files are replaced or erased, the old copy is hidden (but preserved)
to protect accessed users from I/O errors.
Backup files are the previous version of a file, with the fileid in
reverse order (e.g. TOOLSRUN CONTROL becomes LORTNOC
NURSLOOT). The filemode number is changed to zero, so
the file is normally invisible to users. They are
| created indirectly by replacing the file. Backup files
may be recovered (replacing the new copy) by the Regress
| request.
| To determine if a mode zero file is a backup file, look
| for a file that is listed in the diskname NAMES file and
| exists on the disk, and whose fileid is in reverse order
| from the fileid of the mode zero file.
| Hidden files are just like backup files, except that they are created
| directly by the Hide request or indirectly by action on
| the last PACKAGE file that references them. They may be
| recovered by the Regress request or indirectly by action
| on a PACKAGE file that used to reference them.
| To determine if a mode zero file is a hidden file, look
| for a file that is listed in the diskname NAMES file,
| but does not exist on the disk (the :fr. and :fs. tags
| have "?" as their values), and whose fileid is in
| reverse order from the fileid of the mode zero file.
Erasable files are older versions of files, renamed to a fileid of
@nnnnnnn ERASABLE, where "nnnnnnn" is a randomly
selected seven digit number. The random filename is
recorded in the disk AUDIT file, on the line that
describes the action that caused a file (usually a
backup file) to become erasable. While it is possible
to manually sort through the erasable files to recover
an earlier version of a file, the primary intent is to
prevent unpredictable effects (including crashes) on
user sessions that are accessed to the disk while a file
is erased.
Backup and erasable file creation may be suppressed by Option NoBackup and
| Option UnSafe, respectively.
| These files are actually erased later, during a Clean operation, which by
| default normally automatically occurs every time the TOOLSRUN machine
restarts and also upon request by an authorized user. Automatic cleaning
may occur at times other than actual TOOLSRUN machine start, if other
clean options are specified. (See "OPTION CLEANFIRST" in topic 3.66,
"OPTION CLEANIDLE" in topic 3.68 and "OPTION CLEANSTART" in topic 3.69.
See also "OPTION CLEANFULL" in topic 3.67.)
You may specify more than one OPTION CLEAN in the global section or a disk
section. Each unique combination of cleantype and days is added to a
list, in the order encountered. When startup automatic cleaning is done,
every combination on the list is applied.
Comments
Multiple OPTION CLEAN statements can be used to control how long each of
the different "cleanable" categories remains on the disk. The default of
| OPTION CLEAN SAFE 0 removes only erasable files older than the last system
IPL. If the system is not IPLed very frequently, the disk may fill up
| with erasable files that are several days old, even if TOOLSRUN is
restarted every day. In addition, the disk may fill up with backup and
hidden files that are days or weeks old.
Caution is called for, however. If the users of the disk expect backup
and hidden files to remain indefinitely, automatic removal by cleaning
will not be appreciated. (In fact, if backup and/or hidden files can be
removed by automatic cleaning, it is probably a good idea to mention this
in the disk policy description.) Also, if the disk is a shadow, there may
be no point in having a more restrictive policy than the master disk:
Automatic cleaning might be negated by automatic refreshes.
Finally, some common sense is called for: TOOLSRUN will let you specify
any number of cleantype and days combinations, in any order, no matter how
inefficient or nonsensical. Remember that BACKUP[SAFE] will also remove
| erasable files, and that ALL[SAFE] will also remove both backup and
| erasable files. Thus, specifying both SAFE m and BACKUPSAFE n is
meaningful only if m<n. Specifying the same cleantype more than once
(with different days values) just wastes TOOLSRUN CPU time: The smaller
days value "wins." The order in which cleantype statements are specified
requires a little thought, too: If BACKUPSAFE 10 and SAFE 0 are
specified, in that order, TOOLSRUN may spend some extra CPU cycles during
| the BACKUPSAFE processing deciding not to remove erasable files that will
then be erased during the SAFE processing. Reversing the order would
eliminate this waste.
| If the maintained disk is a SFS subdirectory, see "Toolsrun and SFS" in
| topic B.5 for some remarks about the effectiveness of cleaning.
Examples
It is the stated policy of a certain disk that:
| • Erasable files are to be removed after a system IPL.
| • Any erasable file more than 2 days old is to be removed.
| • Backup files more than 10 days old are to be removed.
| • Hidden files more than 15 days old are to be removed.
The following will implement this policy (assuming that TOOLSRUN is
automatically restarted each day):
OPTION CLEAN SAFE 0
OPTION CLEAN ERASABLE 2
OPTION CLEAN BACKUP 10
OPTION CLEAN ALL 15
Defaults
OPTION CLEAN SAFE 0
Purpose
| Option CleanFirst specifies that automatic cleaning is to be triggered by
| the first request for the disk since TOOLSRUN start.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION CLEANFIRST ──────────────────────────────────────────────────┐
│ │
│ OPTION CLEANFirst [ANDIDLE | FIRST | ORIDLE] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
ANDIDLE The disk will be cleaned automatically if TOOLSRUN is idle and
the disk has not been cleaned previously and at least one
request for the disk has already been processed.
FIRST The disk will be cleaned automatically if TOOLSRUN is about to
process the first request for the disk and the disk has not been
cleaned previously. This is the default if none of ANDIDLE,
FIRST or ORIDLE is specified.
ORIDLE The disk will be cleaned automatically if TOOLSRUN is idle and
the disk has not been cleaned previously, or if TOOLSRUN is
about to process the first request for the disk and the disk has
not been cleaned previously.
Usage
See "OPTION CLEAN" in topic 3.65 for descriptions of backup files,
erasable files and cleaning.
OPTION CLEANFIRST is an alternative to OPTION CLEANSTART - automatic
cleaning of the maintained disk when TOOLSRUN starts. By deferring
automatic cleaning until later, TOOLSRUN can start more quickly.
OPTION CLEANFIRST ANDIDLE is appropriate for a disk that is not likely to
be full, and is used infrequently. TOOLSRUN will start quickly, and no
cleaning of the maintained disk will be done unless a request is received.
This first request will be processed quickly, and cleaning will be done
| during a later idle period (not necessarily the next one). Total CPU time
expended by TOOLSRUN can be reduced if the disk typically receives no
requests between TOOLSRUN starts. Since cleaning is done after processing
the first request, there is some risk that the request will be deferred
due to the maintained disk being full.
OPTION CLEANFIRST FIRST is appropriate for a disk that might be full prior
to processing the first request, but is used infrequently. TOOLSRUN will
start quickly, and no cleaning of the maintained disk will be done unless
a request is received. This first request will be delayed while TOOLSRUN
cleans the disk, thereby reducing the risk that the request will be
deferred due to the maintained disk being full. Total CPU time expended
by TOOLSRUN can be reduced if the disk typically receives no requests
between TOOLSRUN starts.
OPTION CLEANFIRST ORIDLE is appropriate for a disk that might be full
prior to processing the first request, and typically receives at least one
request between TOOLSRUN starts. TOOLSRUN will start quickly, but will
| eventually clean the disk during an idle time (not necessarily the next
| one). The first request may be delayed if TOOLSRUN has not yet had enough
idle time to clean the disk. This option does not save CPU time, because
the disk will usually be cleaned at some time after each TOOLSRUN start.
Defaults
OPTION CLEANSTART
Purpose
Option CleanFull specifies that automatic cleaning is to be done when a
request is deferred due to disk full.
Option NoCleanFull specifies that automatic cleaning is not to be done
when the disk is full, and is the default.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION CLEANFULL ───────────────────────────────────────────────────┐
│ │
│ OPTION {CLEANFUll [cleantype [days | 0] | * ] | NOCLEANFULL} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
CLEANFUll The disk will be cleaned automatically if a request is deferred
due to the maintained disk being full. This will be done only
if there are no other requests currently deferred due to the
maintained disk being full.
cleantype Choose one of:
* Use whatever options are in effect for startup
automatic cleaning (OPTION CLEAN). This is the
default.
| SAFE Remove erasable files older than the most recent
| system IPL.
| ERASABLE Remove all erasable files now.
| BACKUPSAFE Remove all erasable files older than the most
| recent system IPL. Convert backup files to
| erasable for later removal.
| BACKUP Remove all erasable and backup files now.
| ALLSAFE Remove all erasable files older than the most
| recent system IPL. Convert backup and hidden
| files to erasable for later removal.
| ALL Remove all erasable, backup and hidden files now.
NAMES Clean the diskname NAMES and diskname INFOLIST
files.
days Preserve a file eligible for erasure for this many days.
Defaults to zero if any cleantype other than asterisk is
specified. Ignored if cleantype of asterisk is specified.
| (Erasable files older than the most recent system IPL are never
| preserved.)
NOCLEANFULL The disk will not be cleaned automatically if a request is
deferred due to the maintained disk being full. This is the
default.
Usage
See "OPTION CLEAN" in topic 3.65 for descriptions of backup files,
erasable files and cleaning.
When requests start being deferred due to a full disk, it is common for
the disk maintainer to try to free up space with CLEAN commands. OPTION
DISKFULL automates this process (quite convenient at 2:00 A.M. on a
holiday weekend). This can prevent rapid accumulation of deferred
requests - only the first will be deferred (if enough space is freed by
cleaning to process subsequent requests).
Other statements may be used to cause automatic cleaning to be done one
time after a TOOLSRUN start. If TOOLSRUN is restarted often enough
(perhaps once a day), with appropriate automatic cleaning options, it
should be rare that any request will be deferred due to disk full. See
"OPTION CLEANFIRST" in topic 3.66, "OPTION CLEANIDLE" in topic 3.68 and
"OPTION CLEANSTART" in topic 3.69. See also "OPTION CLEAN" in topic 3.65.
You may specify more than one OPTION CLEANFULL in the global section or a
disk section. Each unique combination of cleantype and days is added to a
list, in the order encountered. When automatic cleaning is done, every
combination on the list is applied.
Comments
Multiple OPTION CLEANFULL statements may be less useful than multiple
OPTION CLEAN statements. (See "Comments" in topic 3.65 for a discussion.)
Once requests start being deferred, a single, drastic action may be called
for. The objective is to avoid filling up system spool space with
deferred requests, and to avoid user frustration ("I sent a request and
nothing happened" and "Why is this disk out of date?"). If the disk is
not particularly busy, something more drastic than the startup automatic
cleaning, but less drastic than the extreme (OPTION CLEANFULL ALL 0) may
be sufficient. In any event, some sort of more permanent solution should
be sought, but the immediate emergency is handled automatically by
TOOLSRUN.
Defaults
OPTION NOCLEANFULL
Purpose
OPTION CLEANIDLE indicates that automatic cleaning is be done during
TOOLSRUN idle time (no requests are being processed).
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION CLEANIDLE ───────────────────────────────────────────────────┐
│ │
│ OPTION CLEANIdle │
│ │
└────────────────────────────────────────────────────────────────────────┘
Usage
See "OPTION CLEAN" in topic 3.65 for descriptions of backup files,
erasable files and cleaning.
This is appropriate for a disk that might need cleaning each time that
TOOLSRUN starts, but is unlikely to be full prior to processing the first
request. TOOLSRUN will start more quickly, but no CPU time will be saved.
A particular disk might not be cleaned at the first available idle time,
if other disks also are to be cleaned at idle time. Incoming requests
will be processed as soon as an ongoing automatic clean is finished, so
other idle-time cleans may be delayed until the next TOOLSRUN idle.
Defaults
OPTION CLEANSTART
Purpose
OPTION CLEANSTART specifies that automatic cleaning is to be done during
TOOLSRUN start, and is the normal TOOLSRUN default.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION CLEANSTART ──────────────────────────────────────────────────┐
│ │
│ OPTION CLEANStart │
│ │
└────────────────────────────────────────────────────────────────────────┘
Usage
See "OPTION CLEAN" in topic 3.65 for descriptions of backup files,
erasable files and cleaning.
| The disk is cleaned automatically each time that TOOLSRUN starts, before
| any requests are processed. (If the disk is not started when TOOLSRUN
starts, it will be cleaned prior to processing the first request after it
is started.) This is the default, and is appropriate for a disk that
might need cleaning each time that TOOLSRUN starts, and might be full
prior to processing the first request.
Defaults
OPTION CLEANSTART
Purpose
OPTION DISKFULL specifies the threshold at which disk full warnings will
be sent.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION DISKFULL ────────────────────────────────────────────────────┐
│ │
│ OPTION DISKFULL percentfull [blocksleft | 0] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
percentfull A whole number between 0 and 100, defaults to 95.
blocksleft A positive whole number, defaults to zero.
Usage
| When TOOLSRUN starts, warning messages will be issued to the disk Notify
users if the maintained disk is more than percentfull full and either
blocksleft is zero, or there are fewer than blocksleft unused blocks left
on the disk.
| Comments
| This option does not work well if the disk is actually an SFS
| subdirectory, as there is no fixed space associated with an individual
| subdirectory. (See "Toolsrun and SFS" in topic B.5.)
Defaults
OPTION DISKFULL 95 0
Purpose
OPTION FILE allows most of the authorizations for a maintained disk to
reside in a file called diskname CONTROL on the maintained disk.
OPTION NOFILE causes TOOLSRUN to ignore a diskname CONTROL file on the
maintained disk.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION FILE ────────────────────────────────────────────────────────┐
│ │
│ OPTION {FILE | NOFILE} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
NOFILE Any file called diskname CONTROL on the maintained disk will be
ignored.
FILE Any file called diskname CONTROL on the maintained disk will be
processed at the end of the disk section in the master control
file.
Usage
All authorizations except PRIV, and those primitive authorization verbs
that are included in PRIV may be included in this file. In addition, the
COPY verb may be included.
The file does not have to exist prior to adding OPTION FILE to TOOLSRUN
CONTROL.
Any user with PRIV authority for the disk may create or replace diskname
CONTROL. Authorizations will be processed immediately, eliminating the
need to restart TOOLSRUN after changing most authorizations or routings to
shadows. This gives the disk maintainer almost complete control over the
disk, and prevents shutting down and restarting a busy TOOLSRUN machine.
Defaults
OPTION NOFILE
Purpose
This option allows the For override to be restricted to a specified list
of verbs or disallowed altogether.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION FORVERBS ────────────────────────────────────────────────────┐
│ │
│ OPTION {FORverbs verblist ... | NOFORverbs} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
FORverbs A keyword to precede verblist, enter as shown.
verblist A list of one or more verbs that may be done on behalf of
another user.
NOFORverbs Only PRIV users will be allowed to do requests on behalf of
another user.
Usage
Historically, only PRIV users could make requests on behalf of other
users. As disks have become very large and very busy, PRIV users have
welcomed a change that allows knowledgeable non-PRIV users to solve other
users' problems via For overrides. It is also convenient for a user to be
able to Get a file on behalf of someone else, instead of having to explain
how to use TOOLSRUN, or issuing a Get and then receiving and re-sending
the file.
Option Noforverbs restores the restriction for cases where the current
default is too liberal. Option Forverbs is a more refined restriction,
allowing non-PRIV use of For for certain verbs, while prohibiting it for
verbs that have proven to be problematic.
Defaults
TOOLSRUN will allow requests to be done on behalf of another person so
long as the requestor is PRIV; or
• the requestor is authorized for the request, and
• the requestor is the owner of the file (if the request would update or
change ownership of the file), and
• the request is not
- GET COPY
- GET ASIS
- INFORM COPY
Note: While SET ADDRESS may be done FOR someone, file ownership is not
transferred unless the owner is PRIV.
Purpose
OPTION GMTTIME specifies that time stamps on the maintained disk are GMT.
OPTION LOCALTIME specifies that time stamps on the maintained disk are
local time.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION GMTTIME ─────────────────────────────────────────────────────┐
│ │
│ OPTION {GMTtime | LOCALtime} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
GMTtime Time stamps on the maintained disk will be in GMT, which is
the default.
LOCALTime Time stamps on the maintained disk will be in local time.
Usage
Normally, the time stamps in files on the maintained disk are in GMT. If
Option Localtime is specified, then the time stamps on the maintained disk
will be kept in local time. Time stamps on the A-disk are always in GMT
and the console log is always in local time.
Comments
We recommend that this option not be used on disks that send files to
other Toolsrun systems, especially if those systems are in other time
zones.
Defaults
OPTION GMTTIME
Purpose
OPTION INDEX specifies that diskname NAMINDEX is to be built and used by
TOOLSRUN, and is the normal TOOLSRUN default.
OPTION NOINDEX suppresses this.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION INDEX ───────────────────────────────────────────────────────┐
│ │
│ OPTION {IINDEX | NOINDEX} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
INDEX TOOLSRUN will build and maintain a diskname NAMINDEX file for
the maintained disk. This is the default, and is a performance
enhancement for large disks with many files.
NOINDEX TOOLSRUN will not use a diskname NAMINDEX file.
Usage
diskname NAMINDEX is an alphabetically sorted list of files on the
maintained disk, with a diskname NAMES file index associated with each
file. Allowing TOOLSRUN to build and maintain this file enables faster
lookup of diskname NAMES information, when needed, and is used as a quick
check for the existence of a file on the disk.
In some rare cases, it may be necessary to override the normal default and
prevent the creation of this file. For example, if a large disk is nearly
full, OPTION NOINDEX might temporarily be used to free up the space
normally used by the file, until more disk space can be obtained.
Defaults
OPTION INDEX
See OPTION GMTtime on page 3.73.
Purpose
OPTION LOCALNAMES is used to validate file names with the CMS STATE
command, allowing files to be created with file names composed of locally
allowed characters.
OPTION NOLOCALNAMES specifies that file names are to be validated
internally by TOOLSRUN, and is the normal default.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION LOCALNAMES ──────────────────────────────────────────────────┐
│ │
│ OPTION {LOCALNames | NOLOCALNames} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
LOCALNames The CMS STATE command is used to validate file names prior to
creation, instead of using the built in list of valid
characters.
NOLOCALNames File names are validated with the built in list of valid
characters documented for CMS: A-Z, a-z, 0-9, $, #, @, +, - and
_. This is the default.
Usage
This option may be needed on systems where CMS will accept characters in
file names that are not documented in the CMS manuals. When you specify
Option Localnames, the STATE command is used to validate file names prior
to creation instead of using the built in list of valid characters: A-Z,
a-z, 0-9, $, #, @, +, - and _. Colons are not allowed because they would
create parsing problems in the NAMES file.
Comments
We recommend that this option not be used on disks that send files to
other Toolsrun systems that may not have this option enabled.
Defaults
OPTION NOLOCALNAMES
Purpose
OPTION NETAUDIT is used to track how many 4K blocks are transmitted to the
network.
OPTION NONETAUDIT specifies that network traffic is not to be tracked, and
is the normal default.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION NETAUDIT ────────────────────────────────────────────────────┐
│ │
│ OPTION {NEtaudit | NONEtaudit} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
| NEtaudit For each disk being tracked, and for the Toolsrun system, the
| number of 4K blocks transmitted is added to the information
| recorded for each action in the respective AUDIT file.
NONEtaudit ToolsRun will not track network usage. This is the default.
Usage
This option allows system administrators to monitor network usage. The
information may be used to identify and control activity that contributes
to network transmission costs.
Defaults
OPTION NONETAUDIT
See OPTION BACKUP on page 3.63.
See OPTION BATCH on page 3.64.
See OPTION CLEAN on page 3.65.
See OPTION CLEANFULL on page 3.67.
See OPTION FILE on page 3.71.
See OPTION FORverbs on page 3.72.
See OPTION INDEX on page 3.74.
See OPTION LOCALNAMES on page 3.76.
See OPTION NETAUDIT on page 3.77.
See OPTION ORDER on page 3.90.
See OPTION SUBSEXPIRE on page 3.91.
See OPTION WARNOWNER on page 3.93.
Purpose
| OPTION ORDER specifies that all queued requests for this disk are to be
| ordered to the top of the reader.
OPTION NOORDER specifies that queued requests are to be processed in the
order received, and is the normal default.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION ORDER ───────────────────────────────────────────────────────┐
│ │
│ OPTION {ORDER [num] | NOORDER} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
| ORDER When processing a request for a disk different than the
| previous request, other requests with a FORM ID equal to the
disk name will be ordered to the top of the reader to reduce
re-access overhead.
num The reordering will not occur unless there are at least this
many files with a FORM ID equal to the diskname in the
reader, defaults to one.
NOORDER Files will be processed in the order received.
Usage
OPTION ORDER can be used to improve performance on a busy TOOLSRUN service
machine by "batching" incoming requests by disk. A performance
improvement will be noticed only if there are frequently large numbers of
requests queued in the reader.
Defaults
OPTION NOORDER
Purpose
OPTION SUBSEXPIRE specifies that disk subscriptions (except COPy) will
expire periodically.
OPTION NOSUBSEXPIRE specifies that disk subscriptions will not expire.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION SUBSEXPIRE ──────────────────────────────────────────────────┐
│ │
│ OPTION {SUBSEXPIRE [renew_days] [wng_days] [initial_sub_days] | │
│ NOSUBSEXPIRE} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
SUBSEXPIRE specifies that disk subscriptions will expire periodically
(INFORM COPy is exempt). This is the default.
A subscription is any kind of INFORM (but INFORM COPy is
exempted from expiration). Prior to expiration, a one-time
renewal notice is sent to the subscriber, explaining
• that their subscriptions are about to expire
• how to renew (send a RENEW request)
• how to cancel unwanted subscriptions (UNINFORM)
• how to correct their address (SET ADDRESS)
A list of current subscriptions is also included.
If the subscriber takes no action, all their subscriptions to
that disk will be deleted when the subscription days value
reaches 0. An expiration notice is sent to the subscriber,
explaining what happened, and how to (manually) reinstate the
subscriptions.
renew_days Number of days a subscription is set to when the RENEW verb
is processed, and when new subscribers are encountered. A
whole number between 1 and 365, defaults to 184. An asterisk
(*) may be specified to get the default.
wng_days Number of days before subscription expiration to send renewal
notice. A whole number between 1 and 365, and less than
renew_days, defaults to 30. An asterisk (*) may be specified
to get the default.
initial_sub_days Maximum number of days a subscription is set to when
TOOLSRUN first encounters the SUBSEXPIRE control word. A
whole number between 1 and 365, less than renew_days and
greater than wng_days, defaults to 90. An asterisk (*) may
be specified to get the default.
NOSUBSEXPIRE Subscriptions do not expire, Renew requests rejected.
Usage
OPTION SUBSEXPIRE can be used to reduce the number of subscription informs
sent to invalid or obsolete nodes and/or userids by deleting those
subscriptions that are not renewed.
Results
| If OPTION SUBSEXPIRE is in effect for a disk, subscriptions are processed
| once a day (just before TOOLDAY is run). In addition, an individual
| user's expiration date may be renewed or created as part of RENEW or
| INFORM request processing.
| First, the diskname INFOLIST and diskname SUBSCRIB files are compared.
| Each unique node/userid that is in the SUBSCRIB file, but not in the
| INFOLIST file, is removed from the SUBSCRIB file. Each unique node/userid
| that is in the INFOLIST file, but not in the SUBSCRIB file, is added to
| the SUBSCRIB file with an expiration date. (If the SUBSCRIB file did not
| already exist, Toolsrun assumes this is the first time subscription
| expiration has been in effect for this disk, and assigns each user an
| expiration date randomly chosen between wng_days+1 and initial_sub_days+1.
| Otherwise, renew_days is used.) Any node/userid that is not authorized is
| set to wng_days+1 (unless there is already an expiration date and it is
| less than wng_days and thus a warning has been sent already). Any local
| userid that is not in the CP directory is set to 1.
| Next, all expiration dates in the diskname SUBSCRIB file are decremented.
| Any node/userid now at wng_days or zero will receive a notice. The notice
| tells them what is about to happen (or has happened), what to do about it
| and who to contact (the disk CONTACT) for more help.
Whenever a RENEW request is processed for node/userid, the subscription
| days value is set to renew_days. (An INFORM request received with less
| than wng_days left has the same effect. If either informs or subscription
| expiration are disabled, the RENEW request is rejected.)
New subscribers' node/userid are added to diskname SUBSCRIB, with a
| subscription days value of renew_days.
Comments
No attempt is made to relate equated nodes; each node/userid will receive
a separate renewal notice and must be separately renewed.
Decrementing the subscription days values is suspended while INFORM
processing is suspended (by removal of the INFORM card) and while
subscription expiration is suspended (by specifying OPTION NOSUBSEXPIRE).
Defaults
OPTION SUBSEXPIRE 184 30 90
Purpose
Option Unsafe specifies that discarded files are to be erased immediately
from the disk.
Context
Section Effects
Global Applies to all disks - cannot be overridden.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION UNSAFE ──────────────────────────────────────────────────────┐
│ │
│ OPTION UNSAFE │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
UNSAFE Erase discarded files immediately.
Usage
Option UnSafe is used to help reduce disk filling due to keeping erasable
files. (See "OPTION CLEAN" in topic 3.65 for a description of erasable
files.)
Comments
Option UnSafe is experimental and subject to change or deletion in the
future.
Error Conditions
The following caveats do not apply to maintained disks that are SFS
directories. Option UnSafe is encouraged for SFS directories. (See
"Toolsrun and SFS" in topic B.5.)
Warning: Use of Option UnSafe is unsafe; hence the name. If users are
accessed to the disk while a file is discarded, the effects are
unpredictable, and have included session crashes.
DANGER
┌────────────────────────────────────────────────────────────────────────┐
│ Use of Option UnSafe and Option NoBackup together means that the │
│ previous version of a replaced file is erased immediately, greatly │
│ increasing the risk to users who are currently accessed to the disk. │
└────────────────────────────────────────────────────────────────────────┘
Warning: Use of Option UnSafe in the global section of the control file
means that all disks become unsafe; there is no statement that can restore
the default behavior for an individual disk.
Defaults
If omitted, discarded files are renamed to erasable files and erased
sometime later by a Clean request.
Purpose
Option WarnOwner specifies that the owner of a file is to be warned
whenever someone else issues a request that the owner might want to know
about immediately (such as a change of ownership or PACKAGE referenced
files not found), and is the normal default.
Option NoWarnOwner suppresses these warnings.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── OPTION WARNOWNER ───────────────────────────────────────────────────┐
│ │
│ OPTION {WARNOwner | NOWARNOwner} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
WARNOwner The owner of a file receives warning if:
• The file is affected by a request that is normally
restricted to the file owner:
- APPEND-MODIFY (someone else's append)
- APPEND-INSERT
- ERASE
- HIDE
- LOCK
- NEWOWN
- PLACE
- PRUNE
- REGRESS
- REPLACE
- SET-FILE
- SET-MODE
- SET-DESCRIPTION
- UPDATE
• The file is involved in certain types of failed requests:
- APPEND (a file that is not publicly appendable)
- CREATE (a file that is already owned)
- GET a PACKAGE file, not all referenced files exist
This is the default.
NOWARNOwner The owner of a file is not warned if one of the above
requests occurs.
Usage
Option NoWarnOwner might be used on a disk with many PRIV users who
collectively maintain several files. When such a "multiple ownership"
arrangement is used, the frequent warning messages may be viewed as
nuisances. Another use would be when a PRIV user is making many changes
to a disk, and wishes to notify file owners of the action in a single
note, rather than bombarding them with messages as the action proceeds.
He would then include Option NoWarnOwner, send everyone a note, make the
changes, and then remove the option.
Comments
The owner is warned only if he would be able to perform the action
himself. For example, the owner of a file normally cannot directly
perform any actions on the file at a shadow disk. This prevents owners
receiving warnings from every affected shadow.
Defaults
OPTION WARNOWNER
Purpose
Own authorizes a user to issue Own requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── OWN ────────────────────────────────────────────────────────────────┐
│ │
│ OWN [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Own request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Own is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Any person with at least OWNER authority may issue Own requests.
Purpose
Owner is a composite authorization verb.
Group Definition of the group
Owner Create + Erase + Own + Set-File + PACKAGER
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── OWNER ──────────────────────────────────────────────────────────────┐
│ │
│ OWNER [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the group of
requests shown.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
OWNER is the normal authorization for users who are permitted to create
and maintain any kind of file on a disk.
Defaults
ACCESSER * *
unless overridden by
verb * *
where verb is some other authorization verb (e.g. Getter).
Purpose
Packager is a composite authorization verb.
Group Definition of the group
Packager Packfile-Erase + Packfile-Own + REPLACER
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── PACKAGER ───────────────────────────────────────────────────────────┐
│ │
│ PACKAGER [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to be able to create and
erase package files and their contents.
ONLY This optional keyword is used to restrict the effect of the
Packager verb to only the filetypes listed. If you can't get
all the filetypes on one line, duplicate the line up through
ONLY and list additional filetypes there. Any number of
statements can be used.
ftype Restrict this authorization to cover only the filetypes listed.
That is, if any action on a PACKAGE could cause any referenced
file to be erased, its filetype must be one of those on the
list, else it will be left as is, and if any action on a PACKAGE
could cause any referenced file to be owned, its filetype must
be one of those on the list, else it will not be owned. If
there is no list, there will be no restriction by filetype.
(Note that PACKAGE files themselves cannot be implicitly owned
or erased.)
Usage
The intent of PACKAGER is that it may be used instead of OWNER to ensure
that all files are included in package files, since no files may be
created (except package files) unless ownership has already been granted.
This may occur only as a by-product of creating (or replacing) a package
file.
Defaults
ACCESSER * *
unless overridden by
verb * *
where verb is some other authorization verb (e.g. Getter).
Purpose
Packfile-Erase authorizes a user to issue Erase requests for files with a
filetype of PACKAGE.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── PACKFILE-ERASE ─────────────────────────────────────────────────────┐
│ │
│ PACKFILE-ERASE [node] userid [ONLY ftype [ftype ...]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to be able to erase
package files and their contents.
ONLY This optional keyword is used to restrict the effect of the
Packfile-Erase verb to only the filetypes listed. If you can't
get all the filetypes on one line, duplicate the line up through
ONLY and list additional filetypes there. Any number of
statements can be used.
ftype Restrict this authorization to cover only the filetypes listed.
That is, if any action on a PACKAGE could cause any referenced
file to be erased, its filetype must be one of those on the
list, else it will be left as is. If there is no list, there
will be no restriction by filetype. (Note that PACKAGE files
themselves cannot be implicitly erased.)
Usage
Packfile-Erase is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Any person with at least PACKAGER authority may issue Erase requests for
PACKAGE files.
Purpose
Packfile-Own authorizes a user to issue Own and Create requests for files
with a filetype of PACKAGE.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── PACKFILE-OWN ───────────────────────────────────────────────────────┐
│ │
│ PACKFILE-OWN [node] userid [ONLY ftype [ftype ...]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized to be able to create
package files and their contents.
ONLY This optional keyword is used to restrict the effect of the
Packfile-Own verb to only the filetypes listed. If you can't
get all the filetypes on one line, duplicate the line up through
ONLY and list additional filetypes there. Any number of
statements can be used.
ftype Restrict this authorization to cover only the filetypes listed.
That is, if any action on a PACKAGE could cause any referenced
file to be owned, its filetype must be one of those on the list,
else it will not be owned. If there is no list, there will be
no restriction by filetype. (Note that PACKAGE files themselves
cannot be implicitly owned.)
Usage
Packfile-Own is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Any person with at least PACKAGER authority may issue Own and Create
requests for PACKAGE files.
Purpose
Specifies both a source of forwarded requests and a destination for copied
requests.
Context
Section Effects
Global Not allowed
Disk Applies only to that disk
diskname CONTROL Not allowed
Format
┌─── PEER ───────────────────────────────────────────────────────────────┐
│ │
│ PEER node userid [msglvl | 4] [RETAIN hours] [CONTACT name] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of another service machine.
userid The userid of another service machine.
msglvl The minimum level of a response, the default is 4. See "Message
Levels" in topic B.1.
hours Number of hours to retain a forwarded request that has been
deferred, before purging it and requesting a refresh from the
source.
If hours is zero, forwarded requests will not be deferred.
name Information about the contact person at the source. This is now
obsolete and is ignored. The same effect of "self
documentation" may be achieved with a semicolon comment.
Usage
Specifically, Peer authorizes node userid as if GETTER and to propagate
requests (i.e. the request deck contains Origin) and reroute requests
(i.e. the request deck contains From). Propagated requests will still be
checked for originator authorization. In particular, Peer authorizes node
userid to send Put requests, allowing it to refresh this disk, and
Get-Copy requests, allowing it to be refreshed by this disk. REFRESH
limits apply, instead of GET limits. (See "LIMITS" in topic 3.50.) In
addition, node userid will be sent a Get-Copy in response to a Refresh, if
no Source is specified. (See "SOURCE" in topic 3.123.)
There is a subtle distinction between Servant and Peer. In the case of
Peer, the other service machine would have already distributed the request
to the other peers, so this service machine would not forward it to any
other peer. However, requests that have come from a servant have not been
forwarded to other shadows, so the master must do it.
RETAIN applies to requests that might have raced ahead of an earlier
request. Examples would be a CREATE arriving before an ERASE (or vice
versa), an APPEND MODIFY arriving before an APPEND, or a REGRESS arriving
before a HIDE (or vice versa). It is assumed that the request succeeded
at the source (else it would not have been forwarded), and so some other
request may arrive later that will allow this one to succeed. The request
is deferred for hours hours. If the request has not been undeferred
successfully at the end of the retention period, it is purged and a
refresh (where appropriate) is requested from the source.
Comments
You may include a full set of Peer statements at each service machine, the
one specifying itself will be ignored.
| Unless you are asked to do so by an administrator of the other service
| machine (say, for debugging a particular problem), it is a bad idea to set
| the msglvl less than 10; this can cause a flood of responses sent back to
| the other machine under certain circumstances.
Defaults
RETAIN 48
Purpose
Place authorizes a user to issue Place requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── PLACE ──────────────────────────────────────────────────────────────┐
│ │
│ PLACE [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Place request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Place is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Any person with PRIV authority may issue Place requests.
Purpose
Priv is a composite authorization verb, with special additional
privileges.
Group Definition of the Group
Priv Batch-Release + Copy + Clean-All + Clean-Allsafe +
Clean-Backup + Clean-Backupsafe + Clean-Erasable +
Clean-Names + Disk-Nocopy + Disk-Shutdown +
Disk-Shutperm + Disk-Start + Place + Refresh + OWNER
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── PRIV ───────────────────────────────────────────────────────────────┐
│ │
│ PRIV [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized as a disk administrator.
Special Privileges
| Note: These special privileges apply only to a user who is explicitly
| PRIV. They do not apply to any of the PRIV primitives or to any equated
| verb that includes them.
Requests sent directly by PRIV users are never batched. (However, a
Refresh request sent to a shadow will result in a Get Copy request sent
from the shadow to its master - this request may be batched.)
Authorizes a user for all the request verbs that apply to a specific disk.
It also disables ownership checking which allows a PRIV user to change or
delete any file at all, regardless of ownership. However, the file owner
will be notified, unless Option Nowarnowner is in effect.
PRIV may also:
• Get the diskname AUDIT file from the TOOLSRUN system A-disk. (Issue
Get diskname AUDIT to the disk. The file will be retrieved
automatically from the TOOLSRUN system A-disk.)
• If Option File is in effect for the disk:
- Grant, modify or revoke any authorization on the disk, except PRIV
and the primitive verbs that are unique to PRIV.
- Grant, modify or revoke shadow authorization for the disk, via the
Copy disk networking verb.
Authorizations are granted, modified and revoked by creating or
replacing the diskname CONTROL file. This will have no effect on
authorizations that appear in TOOLSRUN CONTROL.
• Issue requests to the disk on behalf of (For) any user, even if the
user is not authorized.
Usage
PRIV is used primarily to designate disk maintainers: those persons
responsible for the integrity of the maintained disk. They may start,
stop and clean the disk, refresh files on the disk (if it is a shadow) and
copy files to shadows. The ability to issue any request, and any request
on behalf of any user, gives them the power they need to rescue users from
mistakes, and to take over or reassign ownership of files for defunct
userids. If Option File is in effect for the disk, they may also grant,
modify and revoke authorizations (except PRIV and the PRIV primitives) and
add and remove shadow disks without intervention from a SYSTEM user, and
without need to shut down the TOOLSRUN service machine.
Defaults
ACCESSER * *
unless overridden by
verb * *
where verb is some other authorization verb (e.g. Getter).
Purpose
Prune authorizes a user to issue Prune requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── PRUNE ──────────────────────────────────────────────────────────────┐
│ │
│ PRUNE [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Prune request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Prune is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Any person with at least REPLACER authority may issue Prune requests.
Purpose
Query-Disk authorizes a user to issue Query Disk requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── QUERY-DISK ─────────────────────────────────────────────────────────┐
│ │
│ QUERY-DISK [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Query Disk
request.
Usage
Query-Disk is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Any person with at least GETTER authority may issue Query Disk requests.
Purpose
Query-File authorizes a user to issue Query File requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── QUERY-FILE ─────────────────────────────────────────────────────────┐
│ │
│ QUERY-FILE [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Query File
request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Query-File is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Any person with at least GETTER authority may issue Query File requests.
Purpose
Query-Inform authorizes a user to issue Query Inform requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── QUERY-INFORM ───────────────────────────────────────────────────────┐
│ │
│ QUERY-INFORM [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Query Inform
request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Query-Inform is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Any person with at least GETTER authority may issue Query Inform requests.
Purpose
Refresh authorizes a user to issue Refresh requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── REFRESH ────────────────────────────────────────────────────────────┐
│ │
│ REFRESH [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Refresh request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Refresh is a primitive authorization verb, usually used with Equate Verb
to create a new composite authorization verb. It has little use by
itself.
Defaults
Any person with PRIV authority may issue Refresh requests.
Purpose
Register authorizes a user to issue Register requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── REGISTER ───────────────────────────────────────────────────────────┐
│ │
│ REGISTER [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Register
request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Register is a primitive authorization verb, usually used with Equate Verb
to create a new composite authorization verb. It has little use by
itself.
Defaults
Any person with at least GETTER authority may issue Register requests.
Purpose
Renew authorizes a user to issue Renew requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── RENEW ──────────────────────────────────────────────────────────────┐
│ │
│ RENEW [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Renew request.
Usage
Renew is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Any person with at least GETTER authority may issue Renew requests.
Purpose
Regress authorizes a user to issue Regress requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── REGRESS ────────────────────────────────────────────────────────────┐
│ │
│ REGRESS [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Regress request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Regress is a primitive authorization verb, usually used with Equate Verb
to create a new composite authorization verb. It has little use by
itself.
Defaults
Only the owner of a file may regress it, and only if they have at least
REPLACER authority.
Purpose
Replace authorizes a user to issue Replace requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── REPLACE ────────────────────────────────────────────────────────────┐
│ │
│ REPLACE [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Replace request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Replace is a primitive authorization verb, usually used with Equate Verb
to create a new composite authorization verb. It has little use by
itself.
Defaults
Only the owner of a file may replace it, and only if they have at least
REPLACER authority.
Purpose
Replacer is a composite authorization verb.
Group Definition of the group
Replacer Clean-Safe + Create-Owned + Hide + Insert-Header + Lock
+ Modify-Header + Newown + Prune + Regress + Replace +
Set-Description + Set-Mode + Unlock + Update + APPENDER
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── REPLACER ───────────────────────────────────────────────────────────┐
│ │
│ REPLACER [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine. group of request verbs listed above.
userid The userid of a person to be authorized for the group of request
verbs shown.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
REPLACER is a less frequently used authorization. It might be used to
delegate file maintenance responsibility to certain users, while not
permitting them to create new files (unless already owned).
Defaults
ACCESSER * *
unless overridden by
verb * *
where verb is some other authorization verb (e.g. Getter).
Purpose
Requests may be used to collect package file request information (i.e. GET
and REGISTER) in a single file for the whole disk (Requests Single) or in
a separate file for each package (Requests Multiple). (See also "REQUESTS
MODE0" in topic 3.113.)
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── REQUESTS ───────────────────────────────────────────────────────────┐
│ │
│ REQUESTS {MULTIPLE | SINGLE} │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
Multiple Specifies that the requestor information will be kept in a
separate REQUESTS file for each different PACKAGE filename.
This is the default.
Single Specifies that all requestor information will be kept in one
file.
Usage
Requests Multiple (the default) makes it convenient to examine the list of
requestors for individual package files, as each package file has its own
matching REQUESTS file. Package owners in particular may be interested in
the request statistics for just their package.
Requests Single reduces the number of files on a disk by collecting
request statistics in a single file. It also makes it convenient to
determine how many total package file requests were made within a certain
time range, or which packages were (or were not) requested within a
certain time range. Keeping the information in this form may be more
convenient for the disk maintainer(s).
Defaults
REQUESTS MULTIPLE
Purpose
This statement causes new REQUESTS file(s) to have a filemode digit of
zero so that they are not normally visible to users. (See also "REQUESTS"
in topic 3.112.)
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── REQUESTS MODE0 ─────────────────────────────────────────────────────┐
│ │
│ REQUESTS MODE0 │
│ │
└────────────────────────────────────────────────────────────────────────┘
Usage
Information about who has requested a package may be considered sensitive.
Accordingly, REQUESTS files may be made invisible to normal users via this
verb.
Defaults
REQUESTS files normally have non-zero filemode digits, and are therefore
visible to any user who has at least GETTER authority for filetypes of
REQUESTS.
Purpose
This statement is used in the global section to cause requests for
diskname, which is not on this service machine, to be intercepted and
redirected to the specified service machine, which must declare this
service machine a Rerouter.
Context
Allowed only in global section.
Format
┌─── REROUTE ────────────────────────────────────────────────────────────┐
│ │
│ REROUTE diskname [node] userid [QUIET | message] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
diskname The name of a disk controlled by another service machine, or *
to route all requests for unknown disks to another service
machine.
node The nodeid of the other service machine, defaults to the same as
this service machine.
userid The userid of the other service machine.
QUIET Suppresses the rerouting message returned to the sender.
message Text to replace the default rerouting message.
Usage
If * is specified for the disk name, all requests to disks unknown to this
service machine will be routed to the other service machine. This could
be useful for moving a service machine to a new node, new userid, or both.
The old machine would contain a Reroute * newnode newuserid statement and
no disk statements. After everyone has gotten the message about the move,
the old machine would then be discontinued.
Comments
Any EQUATE DISK is applied before deciding whether a request should be
rerouted.
Defaults
If neither QUIET nor message is specified, the default rerouting message
text is:
Your request has been rerouted. Please send future requests for
the diskname disk to userid at node.
Purpose
This statement is used after the appropriate Disk statement to authorize a
source of rerouted files for this disk. It may also be used before the
first Disk statement to authorize a source of rerouted files for all
disks.
Context
Section Effects
Global Alters default for all disks, unless the diskname
parameter is specified.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── REROUTER ───────────────────────────────────────────────────────────┐
│ │
│ REROUTER [node] userid [diskname] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of the other service machine, defaults to the same as
the service machine.
userid The userid of the other service machine.
diskname Limits Rerouter in the Global section to the specified disk.
Usage
Specifically, Rerouter authorizes node userid to reroute requests (i.e.
request deck contains a From card).
The Rerouter statement points to a service machine that has a Reroute
statement for this disk.
The diskname parameter is used when there is no Disk card for diskname;
typically, there is a Reroute card to forward the requests elsewhere.
More than one Rerouter card may be specified to permit a particular
ToolsRun machine to reroute for more than one disk.
Comments
Copier, Master, Peer and Servant imply Rerouter.
Defaults
Rerouted requests will not be accepted.
Purpose
Response sets the disk or system defaults for responses sent by the
TOOLSRUN service machine to users.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── RESPONSE ───────────────────────────────────────────────────────────┐
│ │
│ RESPONSE class reply mail disposition │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
class Spool class for files and mail sent to users. The default
(normally B) may be specified by an asterisk.
reply Choose one of:
None Suppress all responses.
Fail Suppress the response unless the request failed.
Msg Respond by immediate message if you are logged on,
else do not respond.
Mail Always respond by mail to your reader.
Both Both Msg and Mail.
Either Respond by immediate message if you are logged on to
the same node as the service machine, else send mail.
This is the default.
mail Choose one of:
New Use the normal network file communication protocol,
this is the default.
Old Use the RMSG protocol. This method is obsolete and
may be removed in the future.
disposition Choose one of:
RETURN Bounce failed requests back to the requestor. This
is the default.
DISCARD Discard failed requests.
Either way, you get told why the request failed, unless
reply=None.
Usage
Response affects the way that TOOLSRUN responds to requests that do not
have a Response override in the deck, and all Inform and Subscribe
responses.
Defaults
RESPONSE B EITHER NEW RETURN
Purpose
Route is used to bypass the normal RSCS determined list processor for
files going to a specific node.
Context
Allowed only in global section.
Format
┌─── ROUTE ──────────────────────────────────────────────────────────────┐
│ │
│ ROUTE node listnode [userid] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The specified destination node. An asterisk (*) may be coded to
specify all nodes.
listnode The nodeid of the list processor to be used when routing files
to node. An asterisk (*) may be used to specify the same node
as the TOOLSRUN service machine.
userid The userid of the RSCS list processor, defaults to *LIST.
Usage
Whenever a file is to be sent to "node," force routing through the
specified list processor. Use sparingly.
Route might temporarily be used to bypass a list processor that does not
recognize the target node, or to provide a more efficient path to the
target node than is realized by normal RSCS list processing. In either
case, Network Control personnel should be contacted to develop a permanent
solution to the problem.
A node parameter of "*" handles the case when an INFORM statement is not
used, but the RSCS userid returned by the CMS IDENTIFY command is to be
overridden.
Comments
Route is experimental, and may be changed or removed in the future.
Defaults
If neither INFORM nor COPY is in effect, normal RSCS routing is performed
without list processing.
Purpose
Servant identifies a shadow that is authorized to forward requests to this
master.
Context
Section Effects
Global Not allowed
Disk Applies only to that disk
diskname CONTROL Not allowed
Format
┌─── SERVANT ────────────────────────────────────────────────────────────┐
│ │
│ SERVANT node userid [msglvl | 4] [RETAIN hours] [CONTACT name] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a shadow authorized to forward requests to the
master.
userid The userid of a shadow authorized to forward requests to the
master.
msglvl The minimum level of response messages, defaults to 4. See
"Message Levels" in topic B.1.
hours Number of hours to retain a forwarded request that has been
deferred, before purging it and requesting a refresh from the
source.
If hours is zero, forwarded requests will not be deferred.
name Information about the contact person at the source. This is now
obsolete and is ignored. The same effect of "self
documentation" may be achieved with a semicolon comment.
Usage
Specifically, Servant authorizes node userid as if GETTER, and to
propagate requests (i.e. the request deck contains Origin) and reroute
requests (i.e. the request deck contains From). Propagated requests will
still be checked for originator authorization. Servant also causes all
successful requests to be propagated to node userid. In particular,
Servant authorizes Get-Copy from the shadow machine, thereby enabling
refreshes. Refresh limits apply (see "LIMITS" in topic 3.50). Without
one of Copy, Peer or Servant, Get limits apply, and the machine must be
authorized for Get-Copy some other way. In contrast to Copy+Copier or
Peer, Servant will not be sent a Get-Copy in response to a Refresh.
The Servant statement is used at a master node instead of a Copy statement
to allow the other service machine to forward requests to the master by
using a Copy statement pointing to the master. The authority of the
submitting user will be rechecked at the master.
There is a subtle distinction between Servant and Peer. In the case of
Peer, the other service machine already would have distributed the request
to the other peers, so this service machine would not forward it to any
other peer. However, requests that have come from a servant have not been
forwarded to other shadows, so the master must do it.
RETAIN applies to requests that might have raced ahead of an earlier
request. Examples would be a CREATE arriving before an ERASE (or vice
versa), an APPEND MODIFY arriving before an APPEND, or a REGRESS arriving
before a HIDE (or vice versa). It is assumed that the request succeeded
at the source (else it would not have been forwarded), and so some other
request may arrive later that will allow this one to succeed. The request
is deferred for hours hours. If the request has not been undeferred
successfully at the end of the retention period, it is purged and a
refresh (where appropriate) is requested from the source.
You may include a full set of Peer statements at each service machine, the
one specifying itself will be ignored.
| Comments
| Unless you are asked to do so by an administrator of the other service
| machine (say, for debugging a particular problem), it is a bad idea to set
| the msglvl less than 10; this can cause a flood of responses sent back to
| the other machine under certain circumstances.
Defaults
RETAIN 48
Purpose
Set-Address authorizes a user to issue Set Address requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── SET-ADDRESS ────────────────────────────────────────────────────────┐
│ │
│ SET-ADDRESS [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Set Address
request.
Usage
Set-Address is a primitive authorization verb, usually used with Equate
Verb to create a new composite authorization verb. It has little use by
itself.
Defaults
Any person with at least GETTER authority may issue Set Address requests.
Purpose
Set-Description authorizes a user to issue Set Description requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── SET-DESCRIPTION ────────────────────────────────────────────────────┐
│ │
│ SET-DESCRIPTION [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Set Description
request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Set-Description is a primitive authorization verb, usually used with
Equate Verb to create a new composite authorization verb. It has little
use by itself.
Defaults
Only the owner of a file, with at least REPLACER authority, may issue Set
Description requests for the file.
Purpose
Set-File authorizes a user to issue Set File requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── SET-FILE ───────────────────────────────────────────────────────────┐
│ │
│ SET-FILE [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Set File
request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Set-File is a primitive authorization verb, usually used with Equate Verb
to create a new composite authorization verb. It has little use by
itself.
Defaults
Only the owner of a file, with at least OWNER authority, may issue Set
File requests for the file.
Purpose
Set-Mode authorizes a user to issue Set Mode requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── SET-MODE ───────────────────────────────────────────────────────────┐
│ │
│ SET-MODE [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Set Mode
request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Set-Mode is a primitive authorization verb, usually used with Equate Verb
to create a new composite authorization verb. It has little use by
itself.
Defaults
Only the owner of a file, with at least REPLACER authority, may issue Set
Mode requests for the file.
Only a user with PRIV authority may change the filemode digit of a file to
zero.
Purpose
This is used to direct Get-Copy requests to the appropriate service
machine, in response to Refresh requests to the maintained disk.
Context
Section Effects
Global Not allowed
Disk Applies only to that disk
diskname CONTROL Not allowed
Format
┌─── SOURCE ─────────────────────────────────────────────────────────────┐
│ │
│ SOURCE node userid [disk] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of the service machine to which Get-Copy requests are
to be forwarded, in response to Refresh requests.
userid The userid of the service machine to which Get-Copy requests are
to be forwarded, in response to Refresh requests.
disk The disk nickname to which Get-Copy requests are to be
forwarded, in response to Refresh requests; defaults to the same
as the Disk statement preceding this Source statement.
Usage
The Source statement is used when none of Copier, Master or Peer is
appropriate, or when there is more than one of these. The normal default
of the first Copier, Master or Peer can be overridden with a Source
statement. (See TOOLS Request File Submission Program Users Guide and
Reference for a discussion of settup up Partial Shadows.)
In the case of multiple master disks shadowed on a single disk (via Equate
Disk), each Equate Disk statement can be matched with a Source statement
(with the diskname nickname specified).
Examples
For example, shaddisk might be shadowing disk1, disk2 and disk3. The
control file for the shaddisk service machine (shadid at shadnode) might
contain the following statements:
*Global Section
Equate Disk shaddisk * * disk1 ; Route disk1 to shaddisk
Equate Disk shaddisk * * disk2 ; Route disk2 to shaddisk
Equate Disk shaddisk * * disk3 ; Route disk3 to shaddisk
*Disk Section
Disk shaddisk shadid 307 none
Master node1 user1 10 ; Master for disk1
Master node2 user2 10 ; Master for disk2
Master node3 user3 10 ; Master for disk3
Source node1 user1 disk1 ; Route disk1 refreshes
Source node2 user2 disk2 ; Route disk2 refreshes
Source node3 user3 disk3 ; Route disk3 refreshes
A Refresh request sent to shadnode shadid disk2 would generate a Get-Copy
request to node2 user2 disk2. When the Put request is returned from node2
user2, it is directed to shadnode shaduser disk2, and redirected (by the
Equate Disk) to shaddisk.
One deficiency in the above is that the shadid machine will accept disk1,
disk2 and disk3 requests from anyone. This could be confusing. With a
little more work in the global section, the chance of confusion is
minimized, while still allowing files to be received from each of the
masters and refreshes to be sent by the disk maintainer and backup (maint1
and maint2 at shadnode). For example:
*Global Section
Equate Disk shaddisk node1 user1 disk1 ; Route disk1 to shaddisk
Equate Disk shaddisk shadnode maint1 disk1 ; Allow refreshes
Equate Disk shaddisk shadnode maint2 disk1 ; Allow refreshes
Equate Disk shaddisk node2 user2 disk2 ; Route disk1 to shaddisk
Equate Disk shaddisk shadnode maint1 disk2 ; Allow refreshes
Equate Disk shaddisk shadnode maint2 disk2 ; Allow refreshes
Equate Disk shaddisk node3 user3 disk3 ; Route disk1 to shaddisk
Equate Disk shaddisk shadnode maint1 disk3 ; Allow refreshes
Equate Disk shaddisk shadnode maint2 disk3 ; Allow refreshes
Defaults
Refresh requests use this diskname, and are directed to the first Copier,
Master or Peer listed for this disk.
Purpose
Summary authorizes a user to issue Summary requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── SUMMARY ────────────────────────────────────────────────────────────┐
│ │
│ SUMMARY [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Summary request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Summary is a primitive authorization verb, usually used with Equate Verb
to create a new composite authorization verb. It has little use by
itself.
Defaults
Any user with at least GETTER authority may issue Summary requests.
Purpose
System identifies a user as a Toolsrun Administrator.
System is a special composite authorization verb. The requests that are
allowed are not available as Equate Verb primitive verbs, and apply to the
TOOLSRUN system A-disk and to the TOOLSRUN Service Machine itself.
Group Definition of the Group
Priv Aget + Alist + Aplace + CMS + Logoff + Query-Usage +
Query-System + Shutdown
Context
Allowed only in global section.
Format
┌─── SYSTEM ─────────────────────────────────────────────────────────────┐
│ │
│ SYSTEM [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized as a Toolsrun
Administrator, defaults to the same as the service machine. We
recommend that Toolsrun Administrators be on the same node as
the service machine for maximum security.
userid The userid of a person to be authorized.
Usage
Toolsrun System Administrators are those persons responsible for the
integrity of the whole TOOLSRUN Service Machine. They may shut down and
log off the system, and they may list, get and place/replace files on the
TOOLSRUN system A-disk. They may also cause the TOOLSRUN Service Machine
to issue CMS commands, and may query system information and usage
statistics.
None of these requests may be issued by non-SYSTEM users. (The one
exception is the diskname AUDIT file for a maintained disk: Any PRIV user
for that disk may request a copy of the file.) SYSTEM authority by itself
does not allow the use of any other requests.
The ability to replace the TOOLSRUN CONTROL file, shut down and
(presumably) restart the TOOLSRUN service machine gives Toolsrun System
Administrators the power they need to set the service machine operating
characteristics, and to add, remove or modify the operation of individual
maintained disks. They also control which individuals have PRIV authority
for the various maintained disks. They can specify Option File for any or
all disks, thereby delegating non-PRIV authorization to the disk
maintainers, or they can specify Option Nofile to retain authorization
control over a disk.
The absence of any authority with respect to individual disks means that a
Toolsrun System Administrator can maintain a system that controls one or
more disks for which he or she is not authorized, and not accidentally
gain access to data on those disks.
Restrictions
There must be at least one Toolsrun Administrator for a TOOLSRUN Service
Machine.
Defaults
ACCESSER * *
unless overridden by
verb * *
where verb is some other authorization verb (e.g. Getter).
Purpose
A Title statement is used to provide text (limited to 64 characters) that
appears at the top of List, Summary, and Query Disk output.
Context
Section Effects
Global Alters default for all disks.
Disk Applies only to that disk
diskname CONTROL Not allowed.
Format
┌─── TITLE ──────────────────────────────────────────────────────────────┐
│ │
│ TITLE text │
│ │
└────────────────────────────────────────────────────────────────────────┘
Usage
It could be used to contain the Security classification of the disk.
Purpose
Trace authorizes a user to issue Trace requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── TRACE ──────────────────────────────────────────────────────────────┐
│ │
│ TRACE [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Trace request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Trace is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Comments
The Trace request is valid only for interpreted TOOLSRUN. If the service
machine is running compiled TOOLSRUN, the request cannot be honored.
Defaults
Any user with at least GETTER authority may issue Trace requests.
Purpose
Uninform authorizes a user for the Uninform request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── UNINFORM ───────────────────────────────────────────────────────────┐
│ │
│ UNINFORM [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Uninform
request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Uninform is a primitive authorization verb, usually used with Equate Verb
to create a new composite authorization verb. It has little use by
itself.
Defaults
Only users with at least GETTER authority may issue Uninform requests, and
only if informs have been enabled for the disk with the Inform statement.
Purpose
Unlock authorizes a user for the Unlock request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── UNLOCK ─────────────────────────────────────────────────────────────┐
│ │
│ UNLOCK [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Unlock request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Unlock is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Comments
The Unlock control verb is experimental and may be changed or removed in
the future.
Defaults
Only the owner of a file may issue Unlock requests for the file, and only
if they have at least REPLACER authority.
Purpose
Update authorizes a user for the Update request.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── UPDATE ─────────────────────────────────────────────────────────────┐
│ │
│ UPDATE [node] userid [ONLY ftype [ftype ... ]] │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Update request.
ONLY This optional keyword is used to restrict the effect of this
verb to only the filetypes listed. If you can't get all the
filetypes on one line, duplicate the line up through ONLY and
list additional filetypes there. Any number of statements can
be used.
ftype Restrict this authorization to cover only the filetypes listed.
Otherwise, there will be no restriction by filetype.
Usage
Update is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Only the owner of a file may issue Update requests for the file, and only
if they have at least REPLACER authority.
Purpose
Vote authorizes a user to issue Vote requests.
Context
Section Effects
Global Applies to all disks
Disk Applies only to that disk
diskname CONTROL Applies only to that disk
Format
┌─── VOTE ───────────────────────────────────────────────────────────────┐
│ │
│ VOTE [node] userid │
│ │
└────────────────────────────────────────────────────────────────────────┘
Parameters
node The nodeid of a person to be authorized, defaults to the same as
the service machine.
userid The userid of a person to be authorized for the Vote request.
Usage
Vote is a primitive authorization verb, usually used with Equate Verb to
create a new composite authorization verb. It has little use by itself.
Defaults
Any person with at least APPENDER authority may vote.
TOOLSRUN checks for the existence of these files when starting. Any of
the files that exist will be used at appropriate times during processing.
With the exception of TOOLEXIT TIMES, all of the files are executable and
are called as subroutines of TOOLSRUN. During startup, any of the
executable files will be loaded into storage, using EXECLOAD, if they are
not already loaded into storage. In general, TOOLSRUN passes certain
information to the exit routine, and is prepared to accept return
information.
• TOOLDAY is not directly affected by receipt of a request. However, it
may be delayed if a request is being processed at midnight.
• TOOLEXIT is not directly affected by receipt of a request. However,
if a TOOLEXIT TIMES event expires, it may be delayed if requests are
being processed. If messages are enabled, each non-Toolsrun message
received will reset the Interval without calling TOOLEXIT.
1. If a request is first received as a message:
a. TOOLMSG can alter or replace the contents of the message.
b. The message is converted to a normal spool file if it is
recognized as a TOOLSRUN request. If the originator has SYSTEM
authority for the service machine, the spool file is ordered ahead
of all other spool files.
2. TOOLDECK is called once for each request spool file. The file may
contain more than one request (verb). TOOLDECK may not alter the
contents of a request file, but it may cause the whole file to fail,
or it may change the origin or target disk.
3. TOOLFILE is called once for each request in a file that has data
appended (e.g. CREATE, REPLACE, APPEND). TOOLFILE may alter the data,
or it may cause the request (and the rest of the request file) to
fail.
4. TOOLDISK is called once for each request in a file that creates or
changes data on the disk (e.g. CREATE, REPLACE, APPEND and also ERASE,
HIDE). TOOLDISK may alter the data, but changes will not be reflected
in the diskname NAMES file.
At the start of a new day. This is not necessarily right at midnight, as
TOOLSRUN may be finishing other work. If TOOLSRUN is shut down before
midnight, and is restarted after midnight, TOOLDAY will not be called.
(See "TOOLEXIT TIMES" in topic A.6 for a more reliable alternative to
TOOLDAY.)
No information is passed.
No return information is expected. Data on a Return statement is ignored.
Any records stacked are flushed.
The virtual punch and virtual reader are restored.
After receipt of a request file, and before it is processed. (It has been
checked as far as is possible.) The request file may contain more than
one request (verb).
spoolid orgnode orguser system
Parameter Description
spoolid The spool id of the request file in the reader.
orgnode The node at which the request file originated.
orguser The userid from which the request file originated.
system 1 if the user has SYSTEM authority, else 0.
If there is any data on the Return statement, and it is not zero:
[@ORIGIN newnode newuserid [newdisk]] [msglvl message]
Parameter Description
@ORIGIN The originating node and userid are changed.
Optionally, the disk may be changed.
newnode The new originating node.
newuserid The new originating userid.
newdisk The new disk to which the request is to be directed. If
this is specified, any Disk cards in the request deck
will be ignored.
msglvl A valid message level (see "Message Levels" in
topic B.1).
message The text to be returned to the user. It will be
prefixed with "(TOOLDECK exit)"
1. The virtual punch is restored.
2. The virtual reader is closed and restored.
3. If the request file is purged or disturbed by TOOLDECK, the request is
not processed.
4. If a message is specified, it is returned to the user in addition to
the normal TOOLSRUN messages.
5. If the message level is greater than DONE, and is not INFORM, then the
request is not processed.
After successful processing of a request that creates, replaces or changes
a file on a disk (Append, Create, Place, Replace, Put or Update; also
Erase, Hide, Lock, Newown, Own, Prune, Regress, Set Description, Set File,
Set Mode, Unlock, Update or Vote). The diskname NAMES file has been
updated.
TOOLDISK EXEC is called with at least 2 and as many as 10 arguments:
Arg(1) = nick on ou priv append dtime dmode for bn bu org rn ru
Arg(2) = verb args
Arg(3) = descrip_1
Arg(4) = descrip_2
Arg(5) = descrip_3
Arg(6) = descrip_4
Arg(7) = descrip_5
Arg(8) = descrip_6
Arg(9) = descrip_7
Arg(10)= descrip_8
Parameter Description
First Argument
nick The disk name to which the request was directed.
on The node from which the request originated.
ou The userid from which the request originated.
priv 1 if "on ou" has PRIV authority for the disk, else 0.
append 1 if the request is for a publicly appendable file, else
0.
dtime Origin transaction time, GMT or local.
dmode Disk access mode letter.
for 1 if the request deck had a FOR card, else 0. If for=1
then "bn bu" sent the request on behalf of "on ou".
bn The FOR requestor's node.
bu The FOR requestor's userid.
org 1 if the request deck had an ORIGIN card, else 0. If
org=1 then "rn ru" forwarded the request from "bn bu" if
for=1, otherwise from "on ou".
rn The ORIGIN requestor's node.
ru The ORIGIN requestor's userid.
Second Argument
verb The request verb.
args The request verb arguments.
Third through Tenth Arguments
descrip_# Up to 8 lines of description data. The request verb
must support descriptions, and must therefore have a
"number of description cards" argument (ncds). ncds is
the number of valid description cards associated with
this request.
If there is any data on the Return statement, and it is not zero:
msglvl message
Parameter Description
msglvl A valid message level (see "Message Levels" in
topic B.1).
message The text to be returned to the user. It will be
prefixed with "(TOOLDISK exit)".
1. The virtual punch and virtual reader are restored.
2. The maintained disk is re-accessed, if necessary.
3. If a message is specified, it is returned to the user in addition to
the normal TOOLSRUN messages.
Note: If the file is altered on the disk, the new contents will be sent
to subscribers. However, the original data will be propagated to shadows.
TOOLSRUN is about to go idle, the Interval has expired (see "INTERVAL" in
topic 3.49) or a TOOLEXIT TIMES event has expired (see "TOOLEXIT TIMES" in
topic A.6).
toolevent line
Parameter Description
toolevent line If TOOLEXIT is called due to a TOOLEXIT TIMES event
expiration, this is the one-line description of the
event from TOOLEXIT TIMES. Otherwise, this is null, and
it may be assumed that TOOLSRUN is about to go idle or
the Interval has expired.
If called due to a TOOLEXIT TIMES event expiration,
toolevent line consists of the entire line in TOOLEXIT
TIMES associated with the event:
nnnnn The line number within the TOOLEXIT TIMES
file.
dddddddd
tttttttt The date and time fields.
rrrrrrrr Reserved for WAKEUP.
toolevent The free form field describing the event.
No return information is expected. Data on a Return statement is ignored.
Any records stacked are flushed.
The virtual punch is restored. The virtual reader is closed and restored.
TOOLSRUN has no more files or messages to process, and there is a TOOLEXIT
EXEC, and there is a TOOLEXIT TIMES file, and it is on a Read/Write disk.
WAKEUP is invoked with the FILE(TOOLEXIT) option.
Each line in the file is composed of three 8 character fields and one
free-format field, separated by one blank each:
dddddddd tttttttt rrrrrrrr toolevent
Field Description
dddddddd Date
tttttttt Time
rrrrrrrr Reserved for WAKEUP.
toolevent Event description, returned to TOOLEXIT EXEC.
When the date and time have expired, the string nnnnn dddddddd tttttttt
rrrrrrrr toolevent is passed to TOOLEXIT EXEC, where nnnnn is the line
number within TOOLEXIT TIMES.
If the first token of toolevent is TOOLSRUN, the rest of the string is
taken as a disk name, request verb and parameters. This is processed
internally by Toolsrun and is not passed to TOOLEXIT. Currently, the only
verb supported this way is Batch Release:
TOOLSRUN disk BATCH RELEASE [method | ALL]
where disk is a single disk name or is an asterisk (*), meaning all disks.
For more information, refer to the documentation for WAKEUP.
TOOLDAY EXEC is the traditional method of controlling once-a-day
housekeeping chores (such as catalog updates and automatic
shutdown/restart). With the addition of some date checking logic, it can
also be used for once-a-week chores, once-a-month chores, and so on.
| However, TOOLDAY has a few drawbacks:
• It cannot be used to control events that must start at some other time
during the day.
• Eventually, TOOLDAY may be assigned so many chores that it might
significantly delay processing of request files received around
midnight.
• Some systems are routinely IPLed shortly after midnight, preventing
completion of a lengthy TOOLDAY.
INTERVAL is the traditional method of preventing automatic logoff of idle
TOOLSRUN machines, and of triggering TOOLEXIT periodically in order to
check for non-class M files (such as class B requests from MVS or class A
notes to be processed by TOOLNOTE). However, if message requests are
enabled (via MSG), TOOLEXIT might be called much less frequently than the
time specified by Interval, because TOOLEXIT is not called following
processing of a message, but the interval timer is reset. (Even a
moderately active TOOLSRUN machine receives a lot of messages, most of
which are not requests. If TOOLEXIT were called after every message, it
would have to be very carefully written to minimize CPU usage.)
TOOLEXIT TIMES may be used to schedule events at any time desired during
the day, on a particular day of the week or month, and also at any desired
periodic interval. This allows for distribution of events throughout the
day, so that TOOLSRUN is not tied up every midnight. In addition,
TOOLEXIT TIMES events will always trigger TOOLEXIT calls at some time
after they expire. Thus TOOLEXIT TIMES is more flexible than TOOLDAY, and
more reliable than either TOOLDAY or Interval triggering of TOOLEXIT.
After receiving a file associated with a request (Append, Create, Place,
Replace, Put or Update). The request has already passed most
authorization checks, but the file itself has not yet been checked
(imbedded append separators, mode 0, etcetera). The diskname NAMES file
has not yet been updated.
The file data is contained in a temporary file. The target file has not
yet been updated.
TOOLFILE EXEC is called with at least 2 and as many as 10 arguments:
Arg(1) = nick on ou priv append dtime tn tt tm for bn bu org rn ru
Arg(2) = verb args
Arg(3) = descrip_1
Arg(4) = descrip_2
Arg(5) = descrip_3
Arg(6) = descrip_4
Arg(7) = descrip_5
Arg(8) = descrip_6
Arg(9) = descrip_7
Arg(10)= descrip_8
Parameter Description
First Argument
nick The disk name to which the request was directed.
on The node from which the request originated.
ou The userid from which the request originated.
priv 1 if "on ou" has PRIV authority for the disk, else 0.
append 1 if the request is for a publicly appendable file, else
0.
dtime Origin transaction time, GMT or local.
tn The temporary file name to which the file has been
received.
tt The temporary file type to which the file has been
received.
tm The disk mode letter to which the file has been
received.
for 1 if the request deck had a FOR card, else 0. If for=1
then "bn bu" sent the request on behalf of "on ou".
bn The FOR requestor's node.
bu The FOR requestor's userid.
org 1 if the request deck had an ORIGIN card, else 0. If
org=1 then "rn ru" forwarded the request from "bn bu" if
for=1, otherwise from "on ou".
rn The ORIGIN requestor's node.
ru The ORIGIN requestor's userid.
Second Argument
verb The request verb.
args The request verb arguments.
Third through Tenth Arguments
descrip_# Up to 8 lines of description data. The request verb
must support descriptions, and must therefore have a
"number of description cards" argument (ncds). ncds is
the number of valid description cards associated with
this request.
If there is any data on the Return statement, and it is not zero:
msglvl message
Parameter Description
msglvl A valid message level (see "Message Levels" in
topic B.1).
message The text to be returned to the user. It will be
prefixed with "(TOOLFILE exit)".
1. The virtual punch and reader are restored.
2. If the request file is purged or disturbed by TOOLFILE, the request is
not processed.
3. The temporary file is closed.
4. The maintained disk is re-accessed, if necessary.
5. If a message is specified, it is returned to the user in addition to
the normal TOOLSRUN messages.
6. If the message level is greater than DONE, and is not INFORM, then the
request (and any other requests remaining in the request file) is not
processed.
Note: If the temporary file is altered, the new contents will be written
to the disk and sent to subscribers. However, the original data will be
propagated to shadows.
A message has been received by TOOLSRUN.
msgclass userid message
Parameter Description
msgclass The message class. For example, MSG, SMSG or IUCV.
userid The userid of the message sender.
message The text of the message.
If there is no data on the Return statement, it is treated as a null
return. If the returned data is not null, it is substituted for the
message text.
1. The virtual punch and reader are restored.
2. If the returned data is null, the message is ignored. Otherwise, the
returned data is processed in place of the actual message received.
Message levels are hierarchical. This means that when you specify 4 you
will get all responses with level 4 and above while suppressing responses
that are below level 4.
MSGLVL Filetype of mail file (in caps) and description
0 Responses that would be sent via immediate message.
1 MAIL responses that are for your information only.
2 WARNING notes that somebody updated your file.
3 DONE responses that indicate success.
4 FAIL responses that indicate that something went wrong.
5 NOTIFY responses where something is suspicious or
unusual.
6 INFORM responses that you have requested.
7 STOP responses indicating the service machine is being
stopped.
8 ERROR responses when there are serious problems or bad
return codes.
9 ABEND notifications - a catastrophic error has
terminated the service machine.
10 Suppress all responses.
TOOLSRUN recognizes or creates the following classes of reader files:
Class Usage
B Default for responses and files sent. User may override
with Response card in request deck. May be overridden
for the disk with Response statement.
C Failed requests.
D Deferred requests. Retried periodically to see if they
can be processed.
M Unprocessed requests (input).
N Unprocessed test requests (input) in test mode.
Other classes may be examined, created or altered by various exits, but
TOOLSRUN itself will ignore all classes except M (or N if in test mode)
and D.
0 Ended normally (i.e. no files and started with PENDING option,
or a SHUTDOWN ALL or SHUTDOWN IMMEDIATE request was issued).
4 Ended normally due to someone typing at the console.
16 Some fatal error occurred, or a SHUTDOWN FORCED request was
issued. Automatic restart is not advisable in this case.
| Toolsrun reads and reports the following variables from group TOOLCARE, as
| part of the response to a QUERY DISK:
| VERSION Version of Toolcare installed.
| nickname Statistics (for the disk) concerning the last time when
| the last check was done, how many files need refreshing,
| the last time a file was refreshed, how many unknown
| requests were in the reader.
| All other usage of GLOBALV is in group TOOLSRUN.
| Toolsrun writes the following variable:
| CONTROL Control file id used.
| Toolsrun writes and reads the following variables:
| LASTVERSION Version of Toolsrun installed.
| LASTDAY Last day that end-of-day processing was run. When this
| does not match the current day, end-of-day processing is
| triggered.
| SHUTDOWN.nickname 1 if the disk is permanently shut down.
| SHUTDESC.nickname The description (if any) provided when the disk was shut
| down.
| Toolsrun reads the following variables:
| BATCH Disable request batching for all disks if zero.
| BATCH.nickname Disable request batching for this disk if zero.
| Toolsrun will supprt SFS subdirectories for use as the system A-disk or
any maintained disk.
Toolsrun requires the FORCERW option on ACCESS. If it is not the owner of
the directory, the Toolsrun userid must have WRITE and NEWWRITE authority
for the directory, and WRITE authority for all files currently in the
directory:
GRANT AUTH * * dir.subdir TO truserid (WRITE
GRANT AUTH dir.subdir TO truserid (WRITE NEWWRITE
Nothing special is required if the directory is to be used as the system
A-disk. IPL CMS PARM FILEPOOL poolid is recommended in the Toolsrun
userid logon directory.
| The Toolsrun SFS support handles both FILECONTROL and DIRCONTROL
| directories, including DIRCONTROL directories in a dataspace. However,
| note that DIRCONTROL directories will consume more system resources if the
| "disk" is changed often while people have it accessed, since old files
| will stay around as long as someone has that generation of the directory
| accessed. Thus, the choice is between frequency of change and user need
| to see changes without having to reaccess.
For a maintained disk, there is a syntax change in the DISK card. (For
more information, see "DISK" in topic 3.24.) Also, Option UnSafe is
encouraged - erasable files are not necessary. (See "OPTION UNSAFE" in
topic 3.92.)
| OPTION ADISKFULL and OPTION DISKFULL do not work the same for SFS
| subdirectories as for VM minidisks: No fixed space is associated with an
| individual subdirectory. Therefore, if more than one of the A-disk and
| any maintained disks is a subdirectory of the same SFS directory, warnings
| will not be given for any disk until the entire directory is nearly full;
| then warnings may be given for all of the disks at once.
| The effects of various cleaning strategies are also different: Requests
| for one or more disks in the same directory may be deferred until space is
| freed by cleaning one or more other disks in the directory.
| 1. Toolsrun does not preserve file authorities when a file is replaced.
| 2. There is no indication when filepool limits are exceeded; OPTION
| DISKFULL and OPTION ADISKFULL are therefore meaningless, and OPTION
| CLEANFULL is questionable.
| 3. Filepool limits generally apply to all your SFS disks.
Toolsrun will examine the CP Tag information associated with an incoming
request file.
1. If NODEID=ACTUAL or NODEID=GENERIC is found enclosed between
parentheses, then
• If NODEID=ACTUAL, no special processing is done.
• If NODEID=GENERIC, and Generic Node Support is installed on the
system on which Toolsrun is running and the request originated on
the same node as the Toolsrun userid, then the request will be
treated as if coming from the generic node.
2. Otherwise, if FROMN=node FROMU=userid is found to the right of a
parenthesis pair, and node is equated to the node from which the
request actually came, the request will be treated as if it came from
node.
A direct response to an incoming request file will have the same
distribution code as the FORM on the request file. (If the distribution
code is null, Toolsrun will use "Tools.") The TOOLS EXEC sets the request
file FORM to the disk name, if sent to a disk, or to @SYSTEM, if it is a
system request.
Files sent for other reasons (such as INFORM) will have a distribution
code of the disk name, if associated with a disk.
All of these documents (except those being developed) are available on
VMTOOLS, managed by VMTOOLS at RALVM17, in the TOOLSDOC package. You can
order the package by entering this:
TOOLS SENDTO RALVM17 VMTOOLS VMTOOLS GET TOOLSDOC PACKAGE
Here's what you can get:
┌───────────┬──────────┬─────────────────────────────────────────────────┐
| │ Number │ Filename │ Title │
├───────────┼──────────┼─────────────────────────────────────────────────┤
| │ TOOLS-001 │ TOOLS │ TOOLS Request File Submission Program Users │
| │ │ │ Guide and Reference │
├───────────┼──────────┼─────────────────────────────────────────────────┤
| │ TOOLS-002 │ TOOLSCTL │ TOOLSRUN Control File Language Reference │
├───────────┼──────────┼─────────────────────────────────────────────────┤
| │ TOOLS-003 │ TOOLSREQ │ TOOLSRUN Request File Language Reference │
├───────────┼──────────┼─────────────────────────────────────────────────┤
| │ TOOLS-005 │ TOOLSRUN │ TOOLSRUN Administrators Guide │
├───────────┴──────────┴─────────────────────────────────────────────────┤
| │ Note: The following are under development: │
├───────────┬──────────┬─────────────────────────────────────────────────┤
| │ TOOLS-004 │ │ Zen and the Art of Shadow Maintenance │
├───────────┼──────────┼─────────────────────────────────────────────────┤
| │ TOOLS-006 │ │ TOOLS Conferencing Guide │
└───────────┴──────────┴─────────────────────────────────────────────────┘
| Figure 8. TOOLS and TOOLSRUN Publications. Numbered documents are
| available as BookMaster source, files already formatted for
| various printers, and BookManager online books.
| When you order the TOOLSDOC PACKAGE, you will receive TOOLSDOC PACKLIB and
| a separate BOOK file for each document. The BOOK files are suitable for
| immediate use via BookManager READ. The TOOLSDOC PACKLIB is an FCOPY
| packlib: It contains copies of the BookMaster source and preformatted
| printable files for each document. To view the list of files contained in
| the packlib, enter:
| FCOPY TOOLSDOC PACKLIB fmode (LIST
| where fmode is the filemode of the disk containing the packlib.
| To unpack one of the files and place it on a disk, display the list of
| files and type the following on the same line as the file to be unpacked:
| SELECT /N /T fmode
| where fmode is the filemode of the disk to receive the unpacked file. (If
| you just type SELECT it will unpack onto your A-disk.)
Toolsrun is a volunteer effort - but there are a lot of volunteers. The
most efficient way to get help is to post your question or problem where a
lot of people will see it. This gives you the maximum chance that someone
who knows the answer will see it, others will benefit from the answer and
you have not interrupted someone who cannot really afford interruptions
today. The place to do that is a FORUM. Here is a list of some of the
more popular ones:
TOOLS FORUM For reporting problems and asking general TOOLS and
TOOLSRUN related questions.
TOOLWISH FORUM For making suggestions and asking for enhancements.
TOOLSADM FORUM For asking fellow Toolsrun administrators for advice.
TOOLSIC FORUM For administrators of IBM Confidential disks.
TOOLSRUN LESSONS Q&A on how Toolsrun works.
TOOLS TIPS Answers to the most frequently asked questions.
TOOLTOOL FORUM Discussions about tools (EXECs and such) to help with
TOOLS and TOOLSRUN.
In addition, there are a couple of other files worth browsing, although
you cannot ask questions there:
TOOLS ANSWERS More answers to frequently asked questions.
TOOLTOOL INDEX An index of tools (EXECs and such) to help with TOOLS
and TOOLSRUN.
All of these files are found on the IBMVM conference disk, and many are
also found on IBMPC, IBMMVS and other popular conference disks.
To ask a question:
1. See if it has been asked already. (3)
2. Make sure you will see the answer before you ask the question. (4)
Otherwise, you may miss it.
You will start getting copies of appends about all sorts of things.
Among them should be the answer to your question.
3. Append your question to the forum. (5) Make it brief - if more
information is needed, someone will ask for it.
4. Wait for an answer. Sometimes it will take a day or more, so be
patient.
5. Once you have your answer, cancel your subscription (6) (if you don't
want to continue following the forum). However, wait a little while
before doing this. Sometimes you will get more than one answer, and
the first one might not be the best one, and may even be incorrect.
(3) We know you may not have the time to read all of the
suggested files. TOOLS TIPS and TOOLS ANSWERS are short
enough to be worthwhile, though. If you don't know how to
link and access a local shadow, here's how to request a copy
of a file: TOOLS SENDTO KGNVMC IBMVM IBMVM GET filename
filetype, where "filename filetype" name the file you want.
For example, TOOLS TIPS.
Note: This is a very busy master disk, and GET requests add
to its burden. You should really make an effort to find the
nearest shadow - perhaps as your next question. You may
notice that you get a response from somewhere other than
IBMVM at KGNVMC. If this happens, a shadow was selected for
you automatically. Use it in the future.
(4) If you don't know how to view local shadows or use the
various types of Inform, do this: TOOLS SENDTO KGNVMC IBMVM
IBMVM SUBSCRIBE filename filetype, where "filename filetype"
name the forum you are about to append to. For example,
TOOLS FORUM.
(5) If you don't know how to append to a forum, do the
following: Create and edit a file called "filename APPEND",
where "filename" is the same as the filename of the forum to
which you will append your question. When you are ready to
send it: TOOLS SENDTO KGNVMC IBMVM IBMVM APPEND filename
filetype, where "filename filetype" name the forum where you
want your question posted. For example, TOOLWISH APPEND is
the file containing your question, and TOOLWISH FORUM is
where it will go.
(6) Remember the "filename filetype" that you used to subscribe
in the first place? Just do this: TOOLS SENDTO KGNVMC IBMVM
IBMVM UNSUBSCRIBE filename filetype.