Here is the (long-awaited? :-) ) documentation on the dynamic disk access
feature of release 1.5o. It explains how to configure SYSVARS files,
lists and filelists to use dynamically accessed disks. If you do not plan
to use dynamic disks, you do not read to read any of this, since full
compatibility is provided with the previous setup.
What is a dynamic disk?
-----------------------
In the following discussion, the term "disk" will refer to a CMS format
minidisk to which LISTSERV has R/O or R/W access at startup time, ie a
virtual DASD defined or LINKed in the directory or PROFILE EXEC.
There are two types of disks, static ones and dynamic ones. Release 1.5n
and below supported only static disks. These are disks which are already
and permanently ACCESSed once LISTSERV has started up (probably from the
PROFILE EXEC, but see the description of the 'CHECKMDISK'/'MDISK.'
definitions below). LISTSERV will never ACCESS nor RELEASE them, nor will
it check that they are accessed properly (eg proper cuu, R/W or R/O
access). It will, of course, produce an error if the disk is not properly
accessed when a reference is made to it, eg when a user tries to GET a
file that is supposed to be on disk L and there is no disk accessed as L.
In any case, a static disk is uniquely identified to LISTSERV by its
filemode.
A dynamic disk is one that is LINKed at startup time, but not ACCESSed.
LISTSERV will automatically ACCESS it when it needs to use it, and
RELEASE it when it is no longer needed and the filemode 'slot' is
required by another dynamic disk. During a single LISTSERV session, a
dynamic disk can be accessed several times, and under different
filemodes. A dynamic disk is uniquely identified by its virtual address.
The "modes pool"
----------------
When LISTSERV starts up, it needs to determine what filemodes will be
available to ACCESS dynamic disks. To do this, it issues a QUERY DISK
command at startup time and marks "reserved" any disk which is presently
accessed, as well as modes A,D,S and Z. That is, the modes under which
static disks are accessed are automatically reserved. All modes that are
not reserved are considered as being available for dynamic ACCESS.
You might, however, wish to reserve a number of modes for your own
applications, eg an EXEC invoked every day from WAKEPARM FILE which needs
to ACCESS a few non-LISTSERV minidisks in R/W mode for a limited period
of time. You can do this by inserting an entry in LOCAL SYSVARS for the
RESMODES variable, whose default value is defined in LISTSERV SYSVARS
(reminder: you should NEVER modify LISTSERV or BITEARN SYSVARS itself;
pick up the variable you need to change, and copy it into LOCAL SYSVARS).
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
*
* RESMODES
*
* This variable defines a list of filemodes which are to be considered as
* "reserved" and never available for dynamic ACCESS. That is, LISTSERV
* will never ACCESS a library minidisk by itself under one of these
* filesmodes. You may of course use them to ACCESS minidisks from the
* PROFILE EXEC or from any local command/exec you may have written. Note
* that A,D,S and Z are always reserved, regardless of what you put in the
* RESMODES variable. Also, any filemode which happens to be in use at the
* time LISTSERV is started will be marked as reserved, so that LISTSERV
* will never release minidisks which were ACCESSed when it was started.
*
RESMODES = 'BC'
RESMODES is upcased.
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
Defining library minidisks
--------------------------
For each disk, dynamic or static, there are a number of parameters (for
which a default value is provided) which tell LISTSERV how to "handle"
the disk. These parameters are kept in a 'MDISK.cuu' stem, and are
described below.
In addition, there is a 'CHECKMDISK' variable, which lists the virtual
addresses of those disks you wish to have checked during LISTSERV
startup. For each disk checked in this fashion, you can decide what
LISTSERV should do if it finds something wrong with the disk, as
explained below. Provision has been made to request LISTSERV to access
static disks itself, instead of doing it from the PROFILE EXEC, so that
you do not have to write code to test the return code and send error
notification in PROFILE EXEC. You can still ACCESS them from PROFILE EXEC
if you so desire, provided you do not explicitly configure LOCAL SYSVARS
to have them ACCESSed by LISTSERV.
Please note that the CHECKDISK variable has been obsoleted by this new
function. However, LISTSERV will map it into 'CHECKMDISK'/'MDISK.'
definition statements as accurately as possible, for compatibility
reasons.
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
*
* CHECKMDISK - List of library minidisks to be checked at startup
* MDISK.cuu - Information about library minidisks
*
* The 'MDISK.' stem defines various parameters associated with LISTSERV
* "library" minidisks, ie minidisks on which LISTSERV might have to read
* or write list archives or library files (as opposed to "system" files
* like PROFILE EXEC or DATABASE FILE which are manipulated by LISTSERV
* but are not apparent to the users). The syntax of the assignment is the
* following:
*
* MDISK.cuu = 'acc rw ro nl th1 th2 / wlist / wmsg'
*
* The slash signs are used as separators. They allow for more parameters
* to be specified in future releases while ensuring compatibility.
*
* - CUU is the minidisk address (*three* hexadecimal digits).
*
* - ACC indicates how the minidisk should be accessed. If it should be
* accessed permanently at a fixed filemode, just specify its filemode
* letter (eg 'F') and LISTSERV will access it during startup. If the
* disk has already been accessed by the PROFILE, append a dash to the
* filemode letter (as in 'A-') to bypass the ACCESS command. If the
* disk should be accessed dynamically (ie as the needs arise), specify
* '*' to let LISTSERV choose the filemode, '*S' to force the filemode
* to be in the T-Y range (for security reasons) or '*fm' to force a
* given filemode to be used for the disk (note that A,D and Z are
* reserved and cannot be specified in this fashion).
*
* - RW indicates what LISTSERV should do if the minidisk is found to be
* accessed in R/W status. 'N' means that this is a normal condition,
* 'W' means that a warning message should be issued (see below) and 'L'
* means that this is a fatal error and LISTSERV should log off.
*
* - RO is similar to RW and describes what happens if the minidisk is
* R/O; NL specifies what should be done if the minidisk is not linked.
*
* - TH1 is the %utilization threshold above which a warning message will
* be generated during startup. Specify 100 to bypass the test.
*
* - TH2 is the %utilization threshold above which LISTSERV will log off.
* Specify 100 to bypass the test.
*
* - WLIST is a blank-separated list of RFC822 addresses to be notified if
* something is wrong with the minidisk. Note that the postmasters are
* always notified, so that the default setting of WLIST (null string)
* actually means that the notification will be sent only to the
* postmasters.
*
* - MSG is an optional message to be appended to the standard error or
* warning messages generated by LISTSERV. This could, for example,
* contain some description of the contents of the minidisk.
*
* Please note that only those CUUs listed in the CHECKMDISK variable will
* be verified at startup time. However, some of the information in the
* MDISK stem will be used when dynamically accessing libraries. The
* default settings for library minidisks which have not been described
* here is as follows:
*
* MDISK.cuu = '*S N N N 100 100//'
*
MDISK.191 = 'A- N L L 85 95 //A(191) is the LISTSERV system minidisk.'
MDISK.192 = 'D- N L L 100 100 //D(192) is LISTSERV''s scratch work disk.'
CHECKMDISK = '191 192'
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
How does one refer to a dynamic disk?
-------------------------------------
LISTSERV "library files" are externally identified by a filename,
filetype and filelist-name, and internally mapped into a CMS filename,
filetype and filemode. This CMS filemode, which we will call "static
filemode", is usually specified by the person setting up the list of
filelist, and defines both a disk-mode letter and an (optional)
filemode-number, which defaults to 1. For a static disk, this is all the
information that LISTSERV needs to store the file. For example, you could
have a filemode of 'L2', meaning static disk L, mode 2.
For a dynamic disk, the mode letter will not be constant and LISTSERV
will need to know the virtual address of the disk. It must be appended to
the static filemode, after a slash sign, to form the "dynamic filemode".
For example, 'L2/201' means dynamic disk 201, mode 2. In the case of a
dynamic disk, the mode letter is irrelevant, but still has to be valid:
'!2/201' would be invalid, but 'X2/201' and 'L2/201' mean exactly the
same thing.
To refer to a dynamic disk, you simply substitute a dynamic filemode to
the static filemode that you would have used for a static disk. For
example, to put the archives of list XYZ on the 205 minidisk, instead of
the G-disk, you would change from "Notebook= Yes,G1,..." to "Notebook=
Yes,G1/205,..."; to change the default filemode for the ABC filelist, you
would modify ABC FILEID and change from "*DEFAULT* G2 ..." to "*DEFAULT*
G2/205 ..." (where '...' means the following parameters, if any, need not
be changed).
Migration of static disks to dynamic ones
-----------------------------------------
You might want to change a static disk into a dynamic one, ie decide
that, from now on, the 'Public local lists' disk will be known as cuu 202
instead of mode L. In order to make this change, you must perform the
following steps:
1. Modify PROFILE EXEC to remove the 'ACCESS 202 L' command.
2. Add a 'MDISK.202' statement to LOCAL SYSVARS, and modify the
'CHECKMDISK' variable to include '202', unless of course you do not
want to disk tested at startup time. You should do this by adding the
following lines to LOCAL SYSVARS:
MDISK.202 = '<fill-in as desired>'
CHECKMDISK = CHECKMDISK '202'
Do NOT copy the MDISK.191/192 statements from LISTSERV SYSVARS if you
do not plan to change them. This will make sure that, if the default
CHECKMDISK and MDISK.191/192 variables are modified in the future,
this modification will not be lost.
3. For all the lists that were archived on this minidisk, change
"Notebook= Yes,Ln,..." to "Notebook= Yes,Ln/202,...", where 'n' is the
filemode number that was there before, not the constant 'n'.
4. For each filelist which had files on this disk, modify the
'filelist-name FILEID' file on LISTSERV 191 to replace all occurences
of 'Ln' into 'Ln/202'. Be sure to modify the *DEFAULT* line if there
is one and it points to this disk, and that your PROFILE XEDIT does
not change the file into RECFM V.
5. Release the disk if it was accessed, and start LISTSERV.
6. For each list that was archived on this disk, issue a 'DATABASE
REFRESH listname' command.
Only steps 2-4 are required if you are creating a new dynamic disk,
rather than converting a static one to dynamic.
Usage notes
-----------
1. Filemode number '3' is no longer allowed, even on static disks. An
error message will be generated if you attempt to use it, and no
operation will take place.
2. If you write programs that run in the LISTSERV virtual machine, such
as local commands, File Access Validation Exits, programs called from
WAKEPARM FILE, etc, you should never ACCESS nor RELEASE anything from
these programs that is not defined as a RESERVED filemode in LOCAL
SYSVARS.
3. Programs that run in the LISTSERV virtual machine and need to
temporarily ACCESS a minidisk can do so through the use of the
following documented calling sequence (which will work only if
LISTSERV has been started, ie not from PROFILE EXEC):
Parse Value LSVDACC('FILE' fm rw) with rc more
Select
When rc == 0 Then Parse var more fm . /* Actual CMS filemode */
When rc == 24 Then (...)
/* Syntax error in 'fm', 'more' contains an error message */
Otherwise (...)
/* Other type of error, 'more' contains an error message */
End
Where 'fm' is the static (eg "L5") or dynamic ("X2/314") filemode and
'rw' is either "R/W" or "R/O", depending on whether R/W access is
required or not. The disk may or may not be released by a subsequent
call to LSVDACC for another virtual address; it is acceptable, but not
mandatory, for the user program to explicitly release it when it is no
longer needed.
Please note that there are other types of LSVDACC calls, some of which
allow minidisks slots to be "locked", but they are not presently
documented and the calling sequence may change without notice.
Eric
|
