Description of DR_DRCT

Download count: 13 this month, 2510 altogether.
Downloads for DR_DRCT :
  VMARC archive: v-66K

These are a collection of tools created to deal with little VM directory-related emergencies, plus some other directory-related tools. While MAPADASD and VDIRCMD provide novel function, most of the programs are intended as efficiency aids. They allow you to do things you could do manually, but using the programs will be quicker and less error-prone.

  • MOVEDRCT EXEC lets you move and change the size of the DRCT area.
  • MAPADASD EXEC finds CMS-formatted areas on a DASD pack.
  • EXAMDASD EXEC displays CPFMTXA info for a range of DASD.
  • DIRSUB EXEC creates a subset of a specified USER DIRECTory.
  • RDIRSUB EXEC creates a subset of a specified USER DIRECTory. (RDIRSUB is kind of the complement of DIRSUB.)
  • VM2EAV EXEC copies a VM system to a single volume, including creating and applying the new USER DIRECTory.
  • VDIRCMD ASSEMBLE makes possible a conditional CMD statement in a directory entry.
  • 8DIR EXEC converts a 4-member SSI source directory to that of an 8-member.
  • USSISOU and USSITARG EXECs are a matched pair, a CPIC-based application for issuing DIRECTXA and other commands on each member of an SSI.
  • 8MEM INSTALL is included for use with 8DIR EXEC. It is an unofficial procedure for a fresh install of an 8-member SSI.

MOVEDRCT EXEC was the original reason for this package. Mostly you are expected to use it when you issue DIRECTXA and get the message

  HCPDIR760E NOT ENOUGH SPACE ALLOCATED FOR DIRECTORY
  EOJ DIRECTORY NOT UPDATED
Now what do you do? One trick to know is that DIRECTXA avoids writing over the old directory, so when you make little modifications to the USER DIRECTory and apply them by issuing DIRECTXA, you are effectively able to use only half the DRCT space. So you can create a temporary tiny USER DIRECT and DIRECTXA it -- there will be plenty of room -- and then do a DIRECTXA for your too-big USER DIRECT. Obviously this works only to a point, and there is some risk (see history below).

The desirable solution is to increase the size of the DRCT allocation. This involves some work with CPFMTXA, and while the steps are not difficult, you likely would need to do some research to figure out what those steps are, and it is easy to make a mistake. With MOVEDRCT EXEC, you simply create the DIRECTory you want, specify the size and location of the DRCT space as minidisk A01 of user $DIRECT$, and run the program. System administrators commonly include special NOLOGged UserIDs such as $DIRECT$ to delineate special areas on DASD, so there is likely to be such a UserID and "minidisk" already. You will have to figure out where you want your new DRCT area to be, though, and it needs to be on the same DASD as before. In the standard VM install, there is no significant unused space on the DASD with the DRCT area; you will have to identify some minidisk(s) that are not being used or that can be moved somewhere else.

MAPADASD EXEC is a tool to attempt to recover diskmap information from a DASD. It identifies areas allocated as PERM and tests for regions formatted as CMS minidisks. The output is a file with a list of such areas, presented as a disk mapping by PERM area.

EXAMDASD is useful when trying to guess the use of unknown DASD which you find yourself owning.

DIRSUB creates a subset of a directory. The subset includes just the UserIDs you specify, plus any PROFILEs those UserIDs INCLUDE. RDIRSUB does the same thing, except the subset created is of all the UserIDs except those you specified. RDIRSUB works by running DIRSUB with the complement (relative to the entire directory) of the list of UserIDs specified.

VM2EAV is likely to be useful only to those wanting a test system that is trivial to copy but has the full capabilities of a VM system installed with recommended procedures. One might think of it as for profligate consumers of DASD, the opposite of setting up a VM system using entirely VDISK, a technique used in HOMUNC.

VDIRCMD is an extension of the capability of the highly useful CMD (or COMMAND) directory statement. Making execution of a CMD statement conditional opens a variety of possibilities. Because CMD statements are executed as if the user has all privilege classes, a lot of power is available, and it is handy to have controls beyond the simple decision to include a statement or not.

8DIR EXEC and 8MEM INSTALL are provided for those setting up an 8-member SSI. Both are intended to enable you to avoid considerable dull and error-prone work (although a fair amount remains in setting up SYSTEM CONFIG). 8DIR EXEC requires some customization before use, but properly used should produce the source directory for your 8-member SSI with little if any further modification needed. It should be useful whether expanding an existing 4-member SSI or doing a fresh install. And if doing a fresh install, it is useful whether or not the procedure in 8MEM INSTALL is used.

USSISOU and USSITARG don't really have much to do with directories other than they make it easy to issue DIRECTXA on all SSI members quickly. Being able to issue the same command on all SSI members without needing to log on to each individually becomes considerably more craved in an 8-member SSI environment. The AT command takes care of this for (most) CP commands; one might think of USSISOU as the AT command extended to CMS commands (such as invoking the DIRECTXA program).

-- Using MOVEDRCT EXEC --

Presumably you have the USER DIRECTory you desire, which will tell you the address and label of the DASD holding your DRCT area (on the first non-comment line). Another way of discovering the DASD holding your DRCT area is to use the CP command QUERY ALLOC DRCT. Using this directory, e.g. with the help of the DISKMAP tool, determine where you would like your DRCT are to be on that DASD. Typically you will be making the new DRCT area larger than the existing area, so you will need to sacrifice some existing minidisks. Be sure to move these minidisks elsewhere or decide there is nothing there you want, because the new DRCT area will be CPFMTXA formatted, thus wiping out any previous contents of the sacrificed minidisks. Once you have chosen the new place for the DRCT area, indicate it in the directory file by adding or modifying the entry for user $DIRECT$, using that user's A01 minidisk to reserve the area. For example, if you have decided to use the 150 cylinders starting at cylinder 2345, and the disk label is "COWBOY", the entry would be
 USER $DIRECT$ NOLOG
 MDISK A01 3390 2345 150 COWBOY  R
Having prepared the new directory, invoke MOVEDRCT with
 MOVEDRCT targetdasd dirfilename <dirfiletype <dirfilemode>>

-- Using MAPADASD EXEC --

Determine the real address of the DASD you wish to inspect. Make sure you have the necessary privileges (A, B, G) and access to CPFMTXA. Then simply invoke the EXEC:
 MAPADASD targetdasd
There are some conditions, e.g. if the target DASD is attached to another user, when the program will be unable to proceed. Fix the problem and try again, or use the program on some other system where the DASD is available and not in use. Note that MAPADASD EXEC does not modify the DASD it is examining, so it is safe to use from another system in order to circumvent access inconveniences. The program produces an output file with filename MAPADASD and filetype the DASD address.

-- Using EXAMDASD EXEC --

This simple EXEC is handy for quickly looking at the CP formatting information for DASD over a range of addresses, which helps you discover which are set up for use as paging space, minidisks, etc. SSI ownership information, if present, is also displayed. Invoke as
 EXAMDASD 1staddr lastaddr

-- Using DIRSUB EXEC and RDIRSUB EXEC --

DIRSUB EXEC creates a file consisting of the directory entries of a specified list of UserIDs, plus any PROFILEs they INCLUDE. It is a subset of the directory specified as the input parameter, consisting of only those UserIDs' entries and the PROFILEs they reference. This is useful in creating or adding to directories when you wish to copy only some subset of the entries in an existing directory. To use, modify the EXEC by listing at the end of the program the UserIDs you want (replacing the existing list, which serves as an example). More detailed instructions are in comments at the beginning of the EXEC. RDIRSUB EXEC works the same way (actually building a new DIRSUB EXEC), except you list the UserIDs you don't want. One use for RDIRSUB is for extraction of all the user entries added since install, and the EXEC as supplied includes exactly the UserIDs from a z/VM 6.4.0 install. Note that RDIRSUB re-writes the list of UserIDs in DIRSUB EXEC, so if you have a version of DIRSUB EXEC that you want to keep, be sure to make a copy before running RDIRSUB EXEC.

-- Using VM2EAV EXEC --

VM2EAV EXEC copies a multiple-volume VM system to a single volume. The single volume is expected to be big, EAV DASD, hence the name. Now that DASD sizes are large enough, it is practical to put your entire VM system on one volume. But the VM install does not (at the time of writing) give you this option. VM2EAV EXEC takes care of the moving. It creates a new USER DIRECTory, does CPFMTXA, SALIPL, and DIRECTXA as well as DDRing minidisks. PAGE and SPOL (and optionally TDSK) space are also allocated, so you can have a complete one-pack system if you so choose. See the EXEC for more detail. Also included is VM2EAV DATA, an example of the data file you will need to supply so that the EXEC knows what to do. (Note that due to contention, performance with a one-pack system is not going to be as good as if I/O can be spread over multiple volumes. If you expect to be performance limited, a one-pack system is probably not a great idea.)

-- Using VDIRCMD ASSEMBLE --

The purpose of VDIRCMD is to allow you to make CMD/COMMAND statements in a directory entry conditional. VDIRCMD is a CP exit, so it must be compiled, CPXLOADed, and a new command defined to invoke it. What it does is invoke another CP command if the specified condition is satisfied, otherwise it does nothing. So you can put a statement like
 CMD VDIR CELLOMAN E FORCE BANJO
in a directory entry, and have the command FORCE BANJO issued if and only if the condition CELLOMAN E -- meaning product CELLOMAN is enabled -- is satisfied. Having a conditional directory statement is useful, for example, to ensure certain users are allowed to log on only at specific times. VDIRCMD ASSEMBLE includes instructions for setting up the CP exit and using the newly-defined command.

-- Using 8DIR EXEC --

8DIR EXEC converts the source directory of a 4-member SSI to a source directory for an 8-member SSI by adding BUILD ON and SUBCONFIG statements for the additional members. It uses member 1's SUBCONFIGs as the model for the additional SUBCONFIGs, using label information which the user must fill in before running the EXEC. The EXEC also knows to make a few other updates, such as adding a DIRECTORY line for the additional members. The EXEC was originally designed for converting a freshly-installed 4-member to 8-member, but provision is made for other DASD labels in addition to those from an original install. If the input directory is substantially different in form from that of an original install, e.g. with SUBCONFIGs of a single IDENTITY having unequal numbers of lines, 8DIR EXEC will struggle and worry. It may still produce the output directory you want, but be sure to verify.

8MEM INSTALL documents a procedure for installing an 8-member SSI by installing two 4-member SSIs and then combining them with the help of 8DIR EXEC. It parallels the procedure for adding a single member to an SSI, which is documented in CP Planning and Administration, but does all four additional members at once and lets the install and 8DIR EXEC do much of the work. Steps are included for when to use MOVEDRCT EXEC if that will be part of your process.

-- Using USSISOU and USSITARG EXECs --

Detailed instructions for setting up and using this pair of EXECs are included in comments within the EXECs. You will create a new IDENTITY YAKSSI with a small minidisk on which to put USSITARG EXEC, and then run USSISOU EXEC from any suitably enabled user in the SSI. Input to USSISOU is executed as commands on YAKSSI, either on just one member of the SSI or on all JOINed members. Particular provision is made for DIRECTXA, so that one can successfully issue DIRECTXA on all members with the single command USSISOU DIRECTXA. Security for the connection is through APPCPASS statements in the USER DIRECTory; no passwords are handled by the EXECs themselves.

-- History --

The first two EXECs were written in connection with a problem we were having during testing: the DRCT area filled up so that we could not add anything to the directory without removing something else. MOVEDRCT EXEC is the straightforward fix for this problem -- just make the DRCT area bigger. But before we got around to creating it, we were using two directories alternately -- the big one we wanted, and a tiny one to temporarily allow more room. We made the mistake of not including in the tiny directory the UserID on whose minidisk the directory copies were stored. So having issued DIRECTXA and accidentally logged off, we had no way to go back. The files were still out there somewhere, but we needed to do a DEFINE MDISK to access them, and we didn't know where the minidisk was. MAPADASD EXEC is useful for this situation, narrowing down the possibilities to a practical number.

Who is "we"? Well, the one with a VM web page is Tim Greer.