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