────────────────────────────────────────────────────────────────────────── TOOLS Disk/Conference Management System TOOLSRUN Administrator's Guide Service Level 6 Version 6.8 Document Number TOOLS-005-01 ──────────────────────────────────────────────────────────────────────────
┌─── Production of this document ────────────────────────────────────┐ │ │ │ This document was prepared and formatted using the BookMaster• │ │ document markup language. │ │ │ └────────────────────────────────────────────────────────────────────┘
| Second Edition, January 30th, 1995 | This is the second 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 document forms the installation guide and operation manual for using the TOOLSRUN disk management program. It describes how to set up a TOOLSRUN service machine, using a CONTROL file. Detailed information is included on many aspects of setting up disks and conferences. TOOLSRUN runs under the IBM VM/SP CMS (Virtual Machine/System Product Conversational Monitor System) environment, and this manual is intended to be used by people with some experience of CMS and VM/SP. The TOOLS program for submitting requests to a TOOLSRUN service machine is not described here; for information about TOOLS the reader should refer to the companion document TOOLS Request File Submission Program Users Guide and Reference.
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. TOOLSRUN 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
Second Edition CHANGES.1
First Edition CHANGES.2
Introduction 1.0
What is TOOLS? 1.1
Acknowledgements 1.2
TOOLSRUN - The Service Machine 2.0
Setting up a TOOLSRUN Service Machine 2.1
The TOOLSRUN Command 2.2
Starting TOOLSRUN 2.2.1
Stopping TOOLSRUN 2.2.2
TOOLSRUN Return Codes 2.2.3
The TOOLSRUN CONTROL File 3.0
General Description of the CONTROL File 3.1
CONTROL Files on Maintained Disks 3.2
TOOLSRUN - Method of Operation. 4.0
Initialisation 4.1
Request Processing 4.2
Times on TOOLSRUN Disks 4.3
Copying to Multiple Systems/Userids 4.4
Peer Networks 4.5
Computer Conferencing 4.6
The NAMES File 4.7
Errors in Processing 4.8
Processing Files from MVS Systems 4.9
AUDIT Files. 4.10
User Exit Execs 4.11
Message Levels 4.12
Performance 4.13
Appendix A. Sample CONTROL Files A.0
Appendix B. Sample TOOLEXIT EXECs B.0
Appendix C. Sample TOOLDECK EXEC C.0
TOOLS Library BIBLIOGRAPHY
Getting Help BACK_1
Index INDEX
1. Sample Control File - Global Section A.0
2. Sample Control File - One Disk Section A.0
3. Sample TOOLEXIT EXEC B.0
4. Sample TOOLEXIT EXEC for TOOLEXIT TIMES. B.0
5. Sample TOOLEXIT TIMES. B.0
6. Sample TOOLDECK EXEC. C.0
| 7. 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. No significant changes were made, but | several minor corrections and clarifications were made.
This version of the document replaces TOOLSRUN 5.2 - DISK/CONFERENCE MANAGER, and has been brought up to date for TOOLSRUN version 6.8, service level 2. No significant new material has been added, although several minor changes have been made. Much material has been removed that had become dated and is now covered in companion documents.
TOOLS is a set of programs that uses a REXX Exec, called TOOLSRUN, to
allow the sharing of one or more disks between many or a few users.
TOOLSRUN runs in a service virtual machine, and authorised users may use
the TOOLS EXEC to send requests to that machine. The requests may
replace, hide, own, or append to files on a tools or conference disk.
Identical requests are used for managing files used for conferencing or
for general use: indeed, the same disk may hold conference files as well
as other data and programs.
This document describes the TOOLSRUN service machine disk manager. The
companion document, TOOLS Request File Submission Program Users Guide and
Reference, introduces the concepts used by TOOLS and TOOLSRUN. It is
assumed that the reader has read that document and is familiar with these
concepts. It also describes the TOOLS EXEC which may be used to send
requests to the service machine.
Considerable effort has been made to ensure the security and integrity of
data managed by TOOLSRUN. As well as a variety of mechanisms for
controlling the authorisation of access to the data, any changes are made
to the disk in such a way that:
• Users already accessing the disk will not find that replaced or hidden
files become unreadable.
• Normally only the registered owner of a set of files may change those
files (however, ownership can be simply transferred between users).
• At least one backup of a changed file is kept on the disk: users may
easily regress a change back to that level.
• A history file detailing the changes to files is automatically
maintained on the disk, and an audit trail of all changes to the disk
is maintained elsewhere.
• Remote users may maintain, list, and retrieve files on the disk.
Files may be retrieved by name, and/or restricted by date to get
recent changes. Files may be made appendable for people other than
the owner.
• Any user can ask to be informed of changes to the disk, selected by
filename and/or filetype.
• All of the above may be restricted to specific users and/or nodes
and/or filetypes.
Note that no attempt is made to prevent malicious changes by the real
owner of a file: only manual detailed inspection of changes could prevent
this. However the audit trail, histories, and other mechanisms provide
security sufficient for most environments.
The TOOLS and TOOLSRUN programs were originally written in 1981 by Mike Cowlishaw, following many of the ideas used in the MAINTAIN program implemented at the T. J. Watson Research Center by Walt Daniels. TOOLS is more secure than its predecessor, and also supports network communication and conferencing. TOOLS was later used by Walt as the base for the IBMPC system, which again led to major enhancements (by Walt, Dave Chess, David Levine and others) now re-implemented in TOOLSRUN. Louis Puster owned the TOOLSRUN EXEC for a year, and made significant organisational improvements. For TOOLS 3.3, Barry Dorfman reviewed and improved the authorisation algorithms and rewrote the authorisation section of this document. He further improved these algorithms for TOOLS 4, and also coded the SUBSCRIBE option of INFORM and the NEARBY node support. Bob Marshall reorganised this document in 1984, including new titling and the addition of an index. Bert Wijnen updated the original TOOLS EXEC so that it would run on a PID CMS/SP3 system, using XEDIT for its menu support. Louis | Puster continued to improve the security and CP aspects of TOOLSRUN. Ray Mansell wrote the TOOLINFO function. Carlos Pfitzner prototyped the NAMES file binary search. Louis Puster carried out most of the updates to this document for TOOLS 5.2, and broke out the request file and control file language syntaxes into separate documents for TOOLS 6.0. Scott Hightower has made all HELP and documentation updates since TOOLS 6.5. More recent contributions: Dave Ellis Integrated BATCH support into TOOLSRUN. Glenn Knickerbocker Chief kibitzer and source of PIPE lore. Vincent Kruskal Fix NODEID= syntax, add FROMN= support. Barry Leiba Added CSE/ISF and SFS support. Fred Newell RENEW verb, subscription expiration. Marty Shapiro Generic node support. Other especially helpful suggestions have been made by John Alvord, Doug Buttimer, Peter Capek, Steve Davies, Bertrand Denoix, Marc Donner, Dick Dunbar, Forrest Garnett, Rob Golden, Rick Haeckel, Rick Holt, Mike Kay, Howard Koslow, Tim McMurray, Albert Modderkolk, Dave Morris, and John Thomas. Many others, too, have contributed in various ways: my thanks to everybody concerned. Bob Cronin, 1st July 1986 Scott Hightower, 22 August 1994
This section describes how to set up and run a TOOLSRUN service machine.
A service machine should be set up for running TOOLSRUN. TOOLSRUN can be
run on personal userids for test purposes, but this is not recommended.
It is strongly suggested that TOOLSRUN have its own Virtual Machine.
TOOLSRUN can be used for many purposes, and can manage any number of
disks. Disks tend to fall into various categories:
Local tools disks - disks that contain programs for local use, tools
either shared by a group of users or by everyone using a
machine.
Local data disks - disks that contain data of various kinds, again either
shared between groups or between all.
Local conferencing disks - disks that primarily contain files used for
computer conferencing and documentation. These may be anything
from small design discussions through widely accessed
discussions on topics of common interest.
Externally accessed disks Every kind of disk just described may also be
shared between a number of machines or even open to an entire
network such as VNET or BITNET. Tools, data, and conferences
may be shared on a network basis. In this case, the disks at a
particular location can be just passive shadows of another disk,
the "master copy" of such a disk, or part of a peer network of a
number of service machines.
Whatever the uses of a particular installation of TOOLSRUN, the same
procedure is used to set up the service machine. Disks of different types
may be mixed at will. A single control file is used to define all the
disks and how they may be accessed.
┌─── Notice ─────────────────────────────────────────────────────────────┐
│ │
│ TOOLSRUN EXEC is under controlled distribution. │
│ Due to the nature of its purpose and sensitivity of its operation, do │
│ not place it on a publicly accessible disk or re-distribute it other │
│ than within your own site and under your own control and │
│ responsibility. │
│ │
└────────────────────────────────────────────────────────────────────────┘
The following are required:
CMS Pipelines Type PIPE QUERY. If the response looks something like "CMS
Pipelines (VM/ESA)," you have pipelines installed on your
system.
IUPDATE This module is required for the update request to perform
incremental updates. Type IUPDATE ?. If the response is brief
help for IUPDATE, it is present on your system.
RXTOOLIN This module is the TOOLINFO function. Type RXTOOLIN ?. If the
response looks something like "TOOLINFO may only be called as a
REXX function.," it is present on your system.
WAKEUP This module is required for TOOLSRUN to respond to class M
files, messages and console and other interrupts, and to
schedule TOOLEXIT TIMES events. type WAKEUP ?. if the response
is brief help for WAKEUP, it is present on your system.
The procedure for setting up a TOOLSRUN service machine is as follows:
1. Set up a Class G Virtual Machine to use. (1) A userid of TOOLS (2) is
| recommended. A virtual machine size of 8 Megabytes is a practical
| minimum, though more may be needed for managing very large disks (e.g.
| 16 Megabytes for 20 large disks). Only a few Megabytes of "A" disk
will be needed unless the tools system is expected to be very heavily
used. The AUDIT files grow by about 180 bytes total per request.
When TOOLSRUN starts up it will warn all SYSTEM NOTIFY users if the
"A" disk is more than 75% full.
2. Place TOOLSRUN EXEC and TOOLSRUN CONTROL on the "A" disk (3) (see "The
TOOLSRUN CONTROL File" in topic 3.0 to see how to set up a control
file). It is also recommended that you place the utility modules
| (RXTOOLIN, UPDATE and WAKEUP) on the same disk.
3. Allocate space for the disks to be managed, if they do not already
exist. For a general tools disk for a whole location, the disk name
TOOLS at virtual address TOOLS 200 is suggested. Note that the disk
must not be attached when TOOLSRUN is started. (4) TOOLSRUN will link
the disk itself to ensure that the correct disk is being processed.
Before using a disk for the first time, it must be formatted with a
blocksize which is a multiple of 1024 bytes. (800-byte blocked disks
cannot be managed safely by TOOLSRUN.)
4. Check that TOOLSRUN works by issuing "TOOLSRUN START" under CMS, and
then submitting requests to it from another virtual machine. TOOLSRUN
will display messages on its console if any modules that it needs are
missing, or any problem is found with the control file. (See
"Starting TOOLSRUN" in topic 2.2.1 for other starting options.)
5. Finally set up the PROFILE EXEC to invoke TOOLSRUN, and arrange for
the virtual machine to be AUTOLOGged at IPL time (e.g. by STARTER0 or
AUTOLOG1). You may wish to put the call to TOOLSRUN in a loop, so
that a 0 return code (see "TOOLSRUN Return Codes" in topic 2.2.3) will
cause a restart.
(1) TOOLSRUN will also tolerate a Class B userid, but this is
untested because the developers of TOOLSRUN have no access to
a Class B userid.
(2) It is common for there to be more than one TOOLSRUN service
machine on a system. If TOOLS is already in use, try to use
something that begins with TOOLS, such as TOOLS01, TOOLS02,
etcetera. SAFE, and other "I'm not here" type programs, will
often send notes to your TOOLSRUN service machine, unless its
name begins with TOOLS.
(3) Any of these files may actually be placed on any disk that
is accessed by the TOOLSRUN service machine userid. If not
on the "A" disk, you must make certain that the disks will
always be accessed (e.g. in the PROFILE EXEC) and that
replacement of the modules on the disk will not affect
TOOLSRUN execution.
(4) If the disk has already been linked due to its being already
in the CP Directory, you should use the CP DETACH command to
detach it. (TOOLSRUN will use any disks that are already
linked, but it will not detach them if the individual disk is
shut down. This requires shutting down the entire TOOLSRUN
service machine to perform DASD maintenance or manual
alterations of the disk contents.)
TOOLSRUN EXEC always gives a summary console trace of its activities. It
may be invoked with one of several parameters and one option:
┌─── TOOLSRUN Invocation ────────────────────────────────────────────────┐
│ │
│ TOOLSRUN parameter [(CONTROL(fname [ftype [fmode]])] │
│ │
└────────────────────────────────────────────────────────────────────────┘
where parameter is one of:
| STart Start the Exec running normally. (This is the default if
| running disconnected.)
DISConnect Start the Exec running normally, and disconnect if start-up is
successful.
PENDing Start the Exec running normally. Only pending files will be
read. i.e. as soon as no more class M files are found in the
reader then the Exec will terminate.
TEST Same as START except that only class N files will be processed.
This is intended for development use only.
A control file may optionally be specified:
fname
ftype
fmode Control file fileid. Default fmode is asterisk (*). Default
ftype is CONTROL. If this option is omitted, TOOLSRUN will
search first for TOOLSRUN CONTROL, and then for nodeid CONTROL,
where nodeid is the node returned by IDENTIFY.
TOOLSRUN is stopped manually by pressing ENTER twice, to enter a null
line. You will be prompted to enter your name (which is recorded). Any
string will be accepted and then entered into the console log, and all
SYSTEM NOTIFY users will be notified. You should normally include a short
description, e.g., "Jones - to add a PRIV".
Instead of shutting down TOOLSRUN, it may be interrupted by responding CMS
to the prompt. TOOLSRUN will not be shutdown, but will execute the
commands you type as CMS commands until you enter a null line. (5) This
feature is also handy for testing installation exit Execs, as they will be
run in the same environment as when in production.
If the CMS response is followed by a valid CMS command, TOOLSRUN will
execute that one command and automatically return to production.
This CMS interrupt should be used with extreme caution! There is no
protection against a CMS command disturbing some crucial aspect of
TOOLSRUN's environment nor are any of the commands executed in this
fashion audited anywhere but on the console log (if it is started).
(5) Note that if you edit the control file, the changes are not
processed until TOOLSRUN is next shutdown and restarted.
When TOOLSRUN terminates for some reason, the return code passed back to
the caller will be set to indicate the kind of termination:
RC=0 Normal exit. The Exec was invoked with the PENDING option (or a
tools SHUTDOWN ALL or SHUTDOWN IMMEDIATE request was made by a
SYSTEM user), and there are no more files to process.
RC=4 Normal exit. Someone entered data at the console.
RC=16 Abnormal exit. Some unrecoverable error was detected, or a
SHUTDOWN FORCED request was made by a SYSTEM user. Automatic
restart is not advised.
This return code may be used to determine whether the Exec should be
automatically restarted.
The operation of TOOLSRUN EXEC is controlled by means of a file called TOOLSRUN CONTROL that may reside on any disk accessed by the service machine. This file is composed of a number of records (lines) each starting with a keyword with various other tokens determining parameters for each keyword. Blank lines, and lines whose first non-blank character is an asterisk, are ignored and may be used to aid readability and for commentary. The CONTROL file has a simple structure. It starts with a section of control records which define "global" parameters (such as network information; which users have "SYSTEM" privileges; and so on). The global section is then followed by one or more sections (each starting with a DISK record) which describe the options and authorisations in force for each disk being managed by TOOLSRUN. Each DISK record marks the start of the control cards that apply to that disk only. The control file may contain as many lines as are needed to tailor the activities of the service machine (see Appendix A, "Sample CONTROL Files" in topic A.0). All the control records are optional, except that there must be at least one "SYSTEM" card, and at least one "DISK" or "REROUTE" card. Records that control authorisation of users for various options may specify just the userid (implying that the node is the same as the service machine), or a node followed by a userid. Both the node and/or userid may be "*" (meaning "any") if desired, and the authorisation may usually be qualified by a list of filetypes following the keyword ONLY. For details of the authorisation mechanism see TOOLSRUN Control File Language Reference. To ease the maintenance of multiple CONTROL files, the TOOLSRUN Exec will look for the file "nodename CONTROL" (where nodename is the name of the node at which TOOLSRUN is running) if "TOOLSRUN CONTROL" cannot be found. Also, any fileid may be specified with the CONTROL option when TOOLSRUN is started. In addition, some of the disk-specific information may be placed on the disk itself - see "CONTROL Files on Maintained Disks" in topic 3.2. For more information and descriptions of individual control records, see TOOLSRUN Control File Language Reference.
For greater flexibility than that provided by the TOOLSRUN CONTROL file (which can only be updated by SYSTEM users), some of the control entries may be placed in a file on the disk to which they refer. This file is called "nickname CONTROL" and must be filemode 0 (i.e. hidden from remote access). It can only be altered by PRIV users for that disk. Only COPY entries and the privilege control entries for OWNER and below may be placed in this file. Entries in the disk CONTROL file have the identical format to those in the main control file (and may contain comment or blank records). They are processed after the last control record for that disk in the main file (both the main file and the disk file can contain authorisation and COPY entries). As the file is processed authorisations are added to the internal tables just as though the lines in the disk file had been placed in the main file. The disk CONTROL file is also processed automatically whenever it is CREATEd or REPLACEd. The authorisations are replaced in the existing tables. For security, SYSTEM NOTIFY users are notified when a disk CONTROL file is first CREATEd, so they are aware that the file is in use. Use of the control file is activated by the OPTION FILE card in the main control file. This must be set before the CONTROL file on disk will be accepted, to ensure that authorisations are under the control of the administrator. Errors in a disk CONTROL file will not cause termination of TOOLSRUN (as this would make it impossible to start up a TOOLS machine if any of the disks had a bad CONTROL file). Instead, the error is reported and processing of that CONTROL file will stop. Authorisation tables may therefore only be partially complete in this case. If the error is detected during automatic processing of a file after REPLACE, the original CONTROL file (if any) is regressed, and partial processing of the new one has no effect. The CONTROL file on a disk will not be copied automatically to shadows. Only an explicit COPY command for that file will cause the file to be | copied, or specifying PROPAGATE on the CREATE, REPLACE or PLACE.
When invoked, TOOLSRUN first checks that all modules it needs are available, and that the "Z" filemode is available for use. (Mode "Z" is used for accessing all serviced disks, so there is no possibility of a MODULE (such as ACCESS) being read from a user disk instead of the system disk). The control file is then read, and the various authorisation tables are built. As each disk is specified by the control file, it is explicitly linked in R/W mode to ensure that the correct disk is being processed. It is then accessed to ensure that the disk is usable. The file "nickname $VERSION" is checked to ensure we are not using a down-level TOOLSRUN EXEC. The disk is then CLEANed according to the specification on the OPTION CLEAN card, and the NAMES and INFOLIST files are also compressed (blank lines are removed). Once the control file has been successfully processed, TOOLSRUN waits for reader files of class M or any other event (such as messages) for which it has been enabled.
TOOLSRUN waits for reader files of class M. When one arrives, each record
in the file is processed for the commands it contains.
A command record is composed of a number of tokens, the first of which is
":TOOLS," the second is a command verb (such as DISK, to select a
particular disk), and the third and subsequent are parameters. (6)
All requests will normally get a response from the service machine. If
the requester is on the same node as the service machine then immediate
messages are used if possible, otherwise mail is sent. (7) If mail is sent
then its DIST code will be the same as the DIST code of the original
request: this permits automatic correlation of requests and responses at a
remote location, though this is not done by the TOOLS package.
After checking that the requester is authorised for the command, action is
taken as described for each request in TOOLSRUN Request File Language
Reference.
(6) As an alternative, for special applications, the first token
may be ":nickname," where "nickname" is the nickname for one
of the disks being maintained. In this case, the DISK card
is not required. Note that for a disk named TOOLS the DISK
card is always required.
(7) This default action may be changed by the RESPONSE card or
request, described elsewhere.
Times in a TOOLSRUN system are handled either in local time or in GMT, as
appropriate for the action being performed. Messages that are of purely
local significance (i.e. those displayed on the TOOLSRUN console log) are
timed in local time. The majority of times, those that refer to data that
are potentially of wider interest, are stated in GMT (Greenwich Mean
Time).
GMT is therefore used for:
• Timestamps in audit files.
• Times in the various headers of appendable files.
• Times in the headers of all mail and NOTE files to users.
• The last change date and last backup date of each file (but actual
file dates remain in local time, as per CMS convention).
TOOLSRUN also uses the concept of a transaction time. At the start of
processing each request deck, the time (in GMT) is noted, and this
transaction time is then used for setting any GMT times (such as last
change dates or append headers) during the processing of that request
deck, so guaranteeing their consistency. If possible, the origin time of
the request (the time that it left the sender) is calculated from the RSCS
tag and this is used as the transaction time.
Note that audit records and mail show the time that the record is written
(or that the mail is sent), not the transaction time, so that delays can
be measured. The transaction time in use is included as part of the data
on the 'From' audit record.
When a request deck is copied to a shadow machine, the ORIGIN card
includes the transaction time used for that request. When a copied deck
is received, the transaction time for that request is set from that found
on the origin card (if any), so that the transaction time used when the
request is first received by a TOOLSRUN machine will also be used when the
request gets to all other machines copied from the initial machine. This
ensures that the same transaction (for example, an Append) will be carried
out with the same timestamp throughout a TOOLSRUN network.
Change requests that are successful may be copied to other TOOLS service
machines by simply including a COPY card in the CONTROL file for each
machine to be copied.
Once a COPY control record has been included, then any request deck that
is wholly processed (that is, without errors) and which changes the
contents of the disk will be copied to the shadows. Control files are
protected, however, so if a deck contains a request that changes a control
file it will not be copied. Control files are those whose filename is the
same as the disk nickname, and whose filetype is NAMES, $VERSION,
INFOLIST, NAMINDEX, BATCHDB, SUBSCRIB or CONTROL. Similarly, files with
filetype HISTORY or REQUESTS are designated local files, and changes to
them will not be copied.
The COPY card identifies a destination for copies of changes. The
TOOLSRUN facilities make possible a variety of configurations for sharing
and copying files.
Master-slave
A single copy of the disk acts as a master copy. All requests
go to the master, and are then copied to all the shadow slaves
using the COPY card. Each slave identifies the master with a
MASTER card.
Master-servant
A single copy of the disk acts as a master copy. Requests may
go either to the master directly, or to one of its active
shadows (servants). A servant is identified by a SERVANT card
at the master, and identifies the master with a MASTER card and
a COPY card. If the original request goes directly to the
master, operation is identical to the Master-slave case. If the
request goes to a servant, then the request is checked (and
takes effect there) and is then copied to the MASTER (only). On
arrival at the MASTER it is again checked, and if accepted it is
then copied to all the other servants and/or slaves.
Peers
Within a peer network, all the disks have equal status: there is
no single master copy. All the peers identify all the other
peers using a PEER card. When a request is accepted at any of
them, it is checked and then copied directly to all the other
PEERs (which will usually check the request again before
accepting it). The peer mechanism is described in the next
section ("Peer Networks" in topic 4.5).
The configurations just described may be used in any mixture. For
example: a MASTER may have both slave and servant shadows; a shadow may
itself be the MASTER to another level of shadows; a network of peers may
act as the masters to collections of shadows; and so on.
Two primary mechanisms are provided for receiving copies in the above
configurations. One is the "blind receiver," or slave, that just handles
all requests as being pre-checked and authorised. The other is a more
intelligent mechanism that treats the incoming file as though it came
directly from the originator. The first (MASTER) is suitable for disks
that are just slaves of some master disk, and the second (COPIER) is
useful for applications that require more checking of data, and is used
automatically when a PEER or SERVANT card is used.
For both MASTER and COPIER status, the control card indicates that the
designated machine has certain privileges for that disk, and that should
an error occur the file will not be returned and hence cause a loop. The
COPIER or MASTER card must explicitly state both node and userid, and
optionally may set the level of messages that will be sent in response to
changes. The default message level is 10, which means that the originator
of the change will not receive responses to his requests from the machine
to which the request was copied. If he is to be informed of all changes,
then message level 2 might be used. If he is only going to be informed of
disastrous errors, then message level 8 is appropriate.
For either kind of copy, a special ORIGIN card in the copy deck contains
the node and userid of the original requester, together with the
transaction time used for the request. For MASTER copiers, every user is
treated as PRIV for that disk, so no authorisation control records are
needed in the file (though there will normally be a local PRIV person, for
local maintenance). For COPIERs, the user is treated as specified by the
authorisation cards in the local control file, which therefore are
normally kept the same for all machines that are copied.
A tools machine will never send a copy of a change request to itself or to
the real origin of a request (e.g. another tools machine sending a copy to
it). As with any loosely coupled network of this type, synchronisation
errors due to network delays and so on may occur. Ultimately error
recovery is the responsibility of the users of the machines. In rare
cases, re-synchronisation in some form may be required: the COPY and
REFRESH requests are useful for this, as they permit selected files to be
directly copied from one TOOLS machine to another.
The COPY request may be used to copy all (or a subset of) the files on a
disk from one service machine to another. This is useful for initialising
or re-synchronising "shadow" disks. For large disks this may place a
considerable load on the network: it may be more appropriate to use tape
in some circumstances. REFRESH is similar, though it is sent to the slave
copy of the disk, which then generates a GET COPY request that is sent to
the master.
AUDIT files are written as usual at copied (shadow) machines. A given
disk may support both MASTERs and COPIERs, or multiple MASTERs, though in
general this is inadvisable since MASTER requests will override changes
from each other or from a COPIER. This may, however, be useful where
there is no conflict between the file names and/or file types originating
from the various sources.
Note: Control files are not copied to shadows.
Disks maintained by TOOLS may form part of peer networks (collections of disks each of which are or equal standing, with no "master" disk as such). Disks maintained this way specify themselves and their peers using the PEER control card. This is like a combination of the COPY and COPIER cards, in that it means that the service machine specified on the card is a valid source of copied requests, and should also receive a copy of any requests received locally. It is assumed that all PEER machines will send copies to all the other PEER machines, so no request received from a PEER machine will be copied to any of the other PEER machines (though it will be copied to any machines specified on COPY cards). A list processor may be used for PEER copies by placing a COPY card with the node and userid of the list processor before any of the PEER (or other COPY) cards. PEER cards may coexist with other MASTER, COPIER, SERVANT, and COPY cards. A peer network works in a way that a request sent to any of the PEER machines will take immediate effect there and will then be copied to all the other machines. As with other copying operations, the loosely coupled nature of the network may cause rare synchronisation errors, and manual intervention may occasionally be necessary. (For example, if two people at two different PEERS try and CREATE the same file, and copies from each machine pass each other in the network. This kind of event should be sufficiently rare that the need for manual intervention for correction is probably acceptable.)
Several features of TOOLS are useful for computer conferencing. The
simplest way of running a conference disk is to set it up so that certain
filetypes are appendable and creatable by the set of people wishing to use
the conference. The authorisation mechanisms may be set up (see example
below) so that anyone may create a FORUM file (for example), and then
retain ownership of it (i.e. only the original owner may replace or erase
it). By using the ADDER class, the same set of filetypes may be
designated as appendable by the conference participants: this means that
any of the participants may append to any of these files. This mechanism
allows the popular "bulletin board" style of conference (as well as more
restrictive conferences) to be managed very easily.
The entries in a control file for a conference disk might be:
* First records are just like any other disk:
DISK IBMCC TOOLS 195 CAVERS
HELP Computer conference on using IBM computers in caves
PRIV WINTON SPELEO
| * The next record indicates that INFORM is enabled (if authorized
| * by other - e.g. OWNER, see below), using a nearby list processor,
| * and also enables SUBSCRIBE.
INFORM HURGATE *LIST SUBSCRIBE
* The next record indicates that any FORUM or NOTE files may be
| * appended by anyone on the network (provided they are already
| * authorized by other - e.g. OWNER, see below).
ADDER * * ONLY FORUM NOTE
* The next record also gives anyone the ability to CREATE (and
* APPEND, GET, etc.) any FORUM, NOTE, SCRIPT, or MEMO files:
OWNER * * ONLY Forum Note Script Memo
Since different classes of files may be assigned to different groups or
even individuals, the same disk may be used for several conferences and/or
tool collections. Access may be given or restricted by any or all of
node, userid, and filetype.
When you first set up a conference disks, it is helpful to users if you
"prime" the disk with certain files. Recommended files (where "name" is
the name of the disk) are:
name RULES A file describing the purpose of the conference, and the
rules for its use.
name FORUM A place for users to append feedback on the conference
itself.
TESTER FORUM A forum for people to test out the append mechanism, to gain
confidence.
WHOSWHO FORUM A place for people to describe themselves and their
interests.
TOOLS EXEC The latest version of the TOOLS EXEC, if not readily
available elsewhere on the system.
Computer conference disks are often shadowed (copied) at locations remote
from the master (or peer network acting as the master). For a specialised
conference, the master-slave configuration described earlier is
appropriate. For large or widespread networks of shadows, the slightly
more complicated master-servant relationship has the advantage that users
local to the servants will see their appends reflected in the database
immediately, rather than having to wait for the request to reach and be
returned from the master.
Every disk maintained by TOOLSRUN has the known files listed in a
directory whose filename is the nickname of the disk and whose filetype is
"NAMES." The filemode digit may be set to any value in the range 0
through 6 (except 3!). This directory is kept in the CMS NAMES format
(and can be queried by NAMEFIND), though the following restrictions apply:
1. The entry for each file is on one line of the NAMES file.
2. The first five fields are fixed format, to allow for easy updating and
fast searching.
3. The names of the tags (except :nick.) are all kept short, to avoid
wasted space. (The file is not intended for visual inspection.)
4. Except for the :nick. tag, each tag is preceded by a single space that
is not part of the value of the previous tag.
5. No tag may contain a colon as part of its value.
For each file on the disk (except those not properly owned, for example
placed there manually) there is an entry in the NAMES file. All entries
have the following tags (with the data length as specified, plus a blank
to separate it from the next tag). The first tag is in column one of the
record.
:nick. (6)
This tag has no value. It is provided so that programs may use
NAMEFIND to retrieve data.
:fn. (8)
An eight-character name for the file. This will be used as the
CMS file name on the disk.
:ft. (8)
An eight-character description of the type (category or content)
of the file. This will be used as the CMS file type on the
disk, and is used for categorising the authorisations in the
CONTROL file.
:fm. (1)
The filemode digit of the file (for REGRESS).
:a. (17)
The network address of the owner of the file, in the format
NODE/USERID.
:d. (variable)
The description of the file.
For example (all on one line):
:nick.003741 :fn.CAVING :ft.FORUM :fm.1 :a.ASSYNT/SPELEO
:d.A discussion on computer usage in natural caves
In addition to the tags listed above, the following tags are used. These
are of variable length, and may be in any order.
:cd.
Date, time and GMT offset of last change (YYYYMMDDHHMMSS NNN).
This is the time at which the file was last changed or put on
this copy of the disk.
:fr.
Number of records (lines) in the file. May be "?" if the file
has not been created.
:fs.
Size of the file in Kilobytes (rounded up). May be "?" if the
file has not been created.
:la.
If present, the network address of the person who locked the
file. Not present when the file is unlocked.
:od.
| Date, time and GMT offset of creation, in Toolsrun form
| (YYYYMMDDHHMMSS NNN). (NNN is the GMT offset, in minutes plus
| or minus, and is present only if OPTION LOCALTIME is used.
:pl.
| If present, list of packages in which this file appears. (A
| package name in parentheses means the package was hidden or the
| current version does not reference the file, but the backup
| does.) The list is used to protect against erasure if appearing
in multiple packages, and to effect an automatic hide or erase
if the file appears only in packages that are all hidden or
erased.
:s.
If present, indicates that to the best of TOOLSRUN's knowledge,
this file was created before any of the PACKAGE files that
reference it.
Whenever an error is detected during processing, an appropriate "FAIL" or
"NOTIFY" message or mail is sent, and the original request file is
returned to the sender (with its class changed to avoid possible loops).
(The bad file may be discarded instead if the DISCARD option is specified
on a relevant RESPONSE control record or request.) Any requests in the
same request deck that follow the failing request will not be processed.
If any request in a request deck fails, no part of the deck is propagated
to any shadows.
The request file is held at the service machine instead if it did not come
directly from the original requester (i.e. it is a propagated copy of the
original request). It is held in the TOOLSRUN defer class (Class D) for
later re-try if the reason for the error might be temporary (8) and
therefore re-processing the files at a later time would be appropriate.
Other errors detected at a COPIED to node (i.e. a shadow) are held as
class "C."
(8) This includes disk full or not available (at either a master
or a shadow) and a number of circumstances at a shadow that
might be due to files racing past each other in the network -
the deferred request will work if some other request arrives
later (e.g. a CREATE waiting on an ERASE or vice versa, an
APPEND or several other requests waiting on a CREATE or a
NEWOWN, one UPDATE waiting on another).
Unfortunately, files from MVS systems cannot (in general) have their spool
class set to class M, and usually arrive as class B. It is not possible
for TOOLSRUN to wake up for both class M and class B files (without waking
up for all files), and so the class B files must have their spool classes
changed periodically.
The processing of MVS files may be done with the TOOLXMVS EXEC distributed
with the TOOLS package. This can either be renamed TOOLEXIT EXEC or
called from a TOOLEXIT EXEC. (See "User Exit Execs" in topic 4.11 for a
description of the TOOLEXIT exit.) To ensure that this Exec is invoked
periodically, it is recommended that the record
==/==/== +10 14:43:44 EXEC TOOLXMVS
is included in the TOOLEXIT TIMES file.
The HISTORY files on each disk may be REPLACEd or ERASEd by privileged
users. Therefore in order to ensure that a secure audit trail of changes
is made, and also to provide a record of errors detected by the TOOLSRUN
Exec, files of filetype AUDIT are written on the service machine "A" disk.
One AUDIT file is written for each disk (filename=disk nickname) and
contains one record for each command which alters that disk. Disk read
errors and the like are also appended to this file. The audit files for
disks may be retrieved (but not altered) by PRIV users of the disk, using
the GET request.
A file called "@SYSTEM AUDIT" contains information of a more global
nature, normally just the start time of TOOLSRUN and the spoolid and
origin of each file received. Any error which causes TOOLSRUN to
terminate will be recorded in this file (e.g. a Card Read error, or a
Syntax error in the Exec).
Each record in an AUDIT file is timestamped, and may have a flag
character:
+ Continuation line.
? Unusual condition, but not an error.
> The record indicates the use of an invalid or illegal command.
* The record indicates some kind of serious processing error (e.g. disk
is full). SYSTEM users are informed automatically.
Processing of files by TOOLSRUN may be aided by installation-provided
Execs ("user exits"). In order for the Execs to be called by TOOLSRUN,
they must be present on the A-disk of the service machine when TOOLSRUN
starts. (9) Any or none of the Execs may be used. Several Execs are
recognised by TOOLSRUN, each at different times of processing. See
Appendix A of TOOLSRUN Control File Language Reference.
(9) Failure of one of these Execs may cause failure of TOOLSRUN
itself, or compromise data integrity. The Execs must
therefore be on the A-disk so they are under the control of
the TOOLSRUN administrator(s). The TOOLDISK EXEC can call
Execs on the current disk, but this is the responsibility of
the administrator.
The internal message levels that TOOLSRUN uses are exposed on the MASTER,
COPIER, SERVANT and PEER cards, and also, except for 10, may be used on
return from any of the exits that process request files directly
(TOOLDECK, TOOLDISK, TOOLFILE, TOOLMSG). The text of the message is sent
by immediate message if the user is on the same machine and is logged on.
Otherwise a mail file is sent (except for class 0 and class 10 messages).
This behaviour may be modified by using the CLASS request card. The
levels that are available have the following characteristics:
0 Only a message is sent, and only if the user is on the same machine.
1 Any mail will have filetype MAIL. This is for informational messages
generated by TOOLSRUN.
2 Mail will have filetype WARNxxxx, otherwise the same as (1).
3 Mail will have filetype DONExxxx, otherwise the same as (1). This is
used to report the successful execution of a request that alters data
on a disk maintained by TOOLSRUN.
4 Mail will have filetype FAILxxxx, and the audit entry will be flagged
with ">." This is used to report the failure of a request.
5 Mail will have filetype NOTIxxxx, and the audit entry will be flagged
with ">." This is used to report the failure of a request, and
indicates that anyone on the NOTIFY list will also be informed of the
failure.
6 Any mail will have filetype INFORM. This is for informational
messages explicitly requested by users (QUERY responses, INFORM
informational messages, etc.).
7 (Reserved for TOOLSRUN use, indicates cause of TOOLSRUN normal
termination. Audit flag="*.")
8 Any mail will have filetype ERROR. This reports a serious error that
prevented normal processing of the request, even though the request
may have been valid. (For example, Disk Full, Disk read error, Card
read error, etc.) The audit file entry will be flagged with "*."
9 Any mail will have filetype ABEND. The TOOLSRUN EXEC itself has an
error (SYNTAX or NOVALUE), or there is an error in the CONTROL file.
The audit file entry will be flagged with "*."
10 Suppress all responses. (Not an error. May not be returned by an
exit.)
System users are automatically notified of any errors of level 7 or
higher.
Normally, all messages sent as mail will be sent as individual files.
However, if the message level is 1 (MAIL) then such messages will be
collected and either appended to a DONE mail item, or sent as a single
MAIL file when the request is complete. This behaviour reduces the number
of mail files generated, especially when PACKAGEs are created.
"Every effort has been made" to ensure good performance. For appropriate security, however, a surprising amount of checking has to be done. Despite this, performance is generally good in view of the function being achieved. Certain requests (SUMMARY and LIST, or GET of a list) are naturally relatively expensive since they require the whole NAMES file to | be read and processed. If a large number of files are to be processed (as during the initialisation of a large shadow disk), then the sheer quantity of data being moved from the spool system is necessarily expensive. As with most service machines, it is appropriate to lower the dispatching priority of the machine to a value lower than that for general (human) users, though this is only really necessary if a large number of requests are anticipated (including the servicing of a shadow disk of a heavily used conference, such as IBMPC or IBMVM). If performance or resource usage of a TOOLS service machine is a concern, the QUERY USAGE command may be used to see exactly how many requests are being processed for each disk, and how much CPU time is being spent in processing those requests. The file @SYSTEM USAGE on the service machine A-disk accumulates these statistics continuously.
┌────────────────────────────────────────────────────────────────────────┐
│ │
│ * 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.
┌────────────────────────────────────────────────────────────────────────┐
│ │
│ /* Sample TOOLEXIT (user exit from tools) Exec... */ │
│ │
│ /* This Exec just transfers any "held" files to a */ │
│ /* local user, and also allows MVS files. */ │
│ parse value diag(8,'QUERY FILES') with . rfiles . │
│ if rfiles='NO' then exit │
│ │
│ /* Discount class N and class D files */ │
│ parse value diag(8,'QUERY FILES CLASS N') with . nfiles . │
│ if nfiles='NO' then nfiles=0 │
│ parse value diag(8,'QUERY FILES CLASS D') with . dfiles . │
│ if dfiles='NO' then dfiles=0 │
│ rfiles=rfiles-nfiles-dfiles │
│ if rfiles<=0 then exit │
│ │
│ temp=diag(8,'QUERY FILES CLASS B NOHOLD') │
│ parse var temp . bfiles . │
│ if bfiles?='NO' then 'EXEC TOOLXMVS' │
│ rfiles=rfiles-bfiles │
│ if rfiles<=0 then exit │
│ │
│ local='MFC' /* Userid to transfer to */ │
│ address command │
│ │
│ 'CP MSG' local '*Toolexit:' rfiles+0 'file(s) in RDR.', │
│ translate(diag(8,'Q RDR'),' ','15'x) │
│ │
│ parse value diag(8,'QUERY FILES CLASS A') with . rfiles . │
│ if rfiles?='NO' then 'CP TRANSFER CL A TO' local │
│ parse value diag(8,'QUERY FILES CLASS C') with . rfiles . │
│ if rfiles?='NO' then 'CP TRANSFER CL C TO' local │
│ │
└────────────────────────────────────────────────────────────────────────┘
Figure 3. Sample TOOLEXIT EXEC. This example is for use without TOOLEXIT
TIMES.
┌────────────────────────────────────────────────────────────────────────┐
│ │
│ /*********************************************************************/│
│ /* */│
│ /* TOOLEXIT */│
│ /* */│
│ /* Invoked by TOOLSRUN when: */│
│ /* */│
│ /* 1. There are no more class M files to process, or */│
│ /* 2. There have been no class M files to process and the */│
│ /* INTERVAL has expired, or */│
│ /* 3. A TOOLEXIT TIMES event has expired. */│
│ /* */│
│ /* TOOLEXIT TIMES is more reliable than INTERVAL, as the interval */│
│ /* timer will be reset by each message received. In addition, */│
│ /* TOOLEXIT TIMES will work even if TOOLSRUN is inactive when the */│
│ /* event expires - TOOLSRUN will be advised of the event at the */│
│ /* first opportunity. Finally, TOOLEXIT TIMES allows staggering */│
│ /* of events much more readily than TOOLDAY or an elaborate */│
│ /* TOOLEXIT depending on INTERVAL. */│
│ /* */│
│ /* Therefore, we do nothing unless an argument is passed. If an */│
│ /* argument is passed, it is the string corresponding to a */│
│ /* TOOLEXIT TIMES event. We assume it is the name of an EXEC, */│
│ /* possibly with parms, and attempt to execute it, unless it is */│
│ /* a keyword used to trigger special events. Two such special */│
│ /* events are TOOLNOTE and TOOLXMVS - we always execute them when */│
│ /* we are done, when we got control due to INTERVAL expiration, */│
│ /* and on receipt of the special NOTEMVS token. */│
│ /* */│
│ /* For information about TOOLEXIT TIMES events, HELP WAKEUP and */│
│ /* read the TIMER FILE OVERVIEW. */│
│ /* */│
│ /*********************************************************************/│
│ Parse Upper Arg n d t r toolevent /* Event description */│
│ Select /* See what there is to do */│
│ When toolevent='' Then /* About to go idle? */│
│ Nop /* Nothing to do */│
│ When toolevent='NOTEMVS' Then /* Special invocation? */│
│ Nop /* Nothing to do here */│
│ Otherwise /* Got something to do */│
│ ''toolevent /* Do it */│
│ End /* "See what there is to do" */│
│ 'EXEC TOOLNOTE' /* Always do this */│
│ 'EXEC TOOLXMVS' /* And always do this */│
│ Return │
│ │
└────────────────────────────────────────────────────────────────────────┘
Figure 4. Sample TOOLEXIT EXEC for TOOLEXIT TIMES.. This example is for
use with a TOOLEXIT TIMES file.
┌────────────────────────────────────────────────────────────────────────┐
│ │
│ * Periodically check for requests via note or from MVS │
│ ==/==/== +10 09:02:23 NOTEMVS │
│ * Remove unknown users found during the previous day │
│ ==/==/== 00:01:00 08/22/94 EXEC RMVUSERS │
│ * Generate new lists and catalogs │
│ ==/==/== 00:02:00 08/22/94 EXEC LISTCAT │
│ * Weekly TOOLCARE functions │
│ SATURDAY 00:03:00 08/20/94 EXEC CAREFUNC │
│ * Clean up audit files │
│ ==/==/== 00:04:00 08/22/94 EXEC TOOLCARE * AUDIT SAVE USAGE │
│ * Clean up reader files │
│ ==/==/== 00:05:00 08/22/94 EXEC TOOLCARE * READER UNINFORM │
│ * Kick off shadow refreshes │
│ ==/==/== 20:00:00 08/21/94 EXEC TOOLCARE *SHADOWS REFRESH * │
│ * Release anything held in batch queues │
│ ==/==/== 23:00:00 08/21/94 TOOLSRUN BATCH * RELEASE ALL │
│ │
└────────────────────────────────────────────────────────────────────────┘
Figure 5. Sample TOOLEXIT TIMES.. This example includes automatic batch
release.
┌────────────────────────────────────────────────────────────────────────┐ │ │ │ /* Sample TOOLDECK request exit. */ │ │ │ │ /* Warn users that the IBMPC disk has moved. BC at PLKSK. */ │ │ │ │ /* The arguments passed from TOOLSRUN are: */ │ │ /* Spoolid of the request. */ │ │ /* Node that the request originated at. */ │ │ /* Userid that originated the request. */ │ │ /* System flag (1 if origin is a SYSTEM user, 0 otherwise). */ │ │ │ │ Arg spoolid orgnode orguser system . │ │ Address Command │ │ │ │ /* Set TOOLSRUN's message level definition for warnings. */ │ │ $WARNING = 2 │ │ │ │ result = '' /* Assume the request is NOT for the IBMPC disk. */ │ │ 'IOX CARD ! card' /* Could use EXECIO here */ │ │ Parse Upper Var card ':TOOLS DISK' diskname . │ │ │ │ /* If the request is a long form request */ │ │ If diskname ?= '' then │ │ Do │ │ /* If the disk name is IBMPC */ │ │ If diskname = 'IBMPC' then │ │ result = $WARNING 'The IBMPC disk has been moved', │ │ 'to IBMPC at PLKSK.' │ │ End /* of If the request is a long form request. */ │ │ Else │ │ /* If the request is a short form request */ │ │ Do │ │ Parse Upper Var card ':'diskname . │ │ /* If the disk name is IBMPC */ │ │ If diskname = 'IBMPC' then │ │ result = $WARNING 'The IBMPC disk has been moved', │ │ 'to IBMPC at PLKSK.' │ │ End /* of If the request is a short form request. */ │ │ │ │ 'CP CLOSE READER' /* This is REQUIRED. */ │ │ Return result │ │ │ └────────────────────────────────────────────────────────────────────────┘ Figure 6. Sample TOOLDECK EXEC.
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 7. 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. (10)
2. Make sure you will see the answer before you ask the question. (11)
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. (12) 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 (13) (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.
(10) 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.
(11) 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.
(12) 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.
(13) Remember the "filename filetype" that you used to subscribe
in the first place? Just do this: TOOLS SENDTO KGNVMC IBMVM
IBMVM UNSUBSCRIBE filename filetype.
[A] [C] [E] [G] [I] [M] [P] [T] [U]
| A |
Acknowledgements, 1.2 AUDIT files, 4.10
| C |
Computer Conferencing, 4.6 Conferencing, 4.6 CONTROL file description, 3.1 sample, A.0 Control record ADDER, 4.6 COPIER, 4.5 COPY, 4.5 DISK, 4.6 HELP, 4.6 INFORM, 4.6 OWNER, 4.6 PEER, 4.5 PRIV, 4.6
| E |
Example conferencing control file, 4.6 control file, A.0 TOOLDECK EXEC, C.0 TOOLEXIT EXEC, B.0 Exits, 4.11
| G |
GMT timestamps, 4.3
| I |
Interrupting TOOLSRUN, 2.2.2
| M |
Message levels, 4.12
| P |
Peer networks, 4.5 Performance, 4.13
| T |
Timestamps, 4.3
TOOLSRUN command, 2.2
TOOLSRUN EXEC
DISConnect parameter, 2.2.1
Interrupting, 2.2.2
PENDING option, 2.2.1
return codes, 2.2.3
START parameter, 2.2.1
Starting, 2.2.1
Stopping, 2.2.1
TEST option, 2.2.1
TOOLSRUN operation
initialisation, 4.1
request processing, 4.2
request
COPY, 4.4
Times
Transaction times, 4.3
| U |
User exits, 4.11