DIRMAP

Options

Notes:

¹ You can enter Options in any order between the parentheses.
² The default is to sort by volume serial number only.
³ EXCLUDE overrides the volume serial numbers specified by INCLUDE.

Authorization

Systems Programmer

Purpose

Use the DIRMAP utility to do MDISK/LINK mapping for the user directory. Also see the DISKMAP command in z/VM: CP Commands and Utilities Reference.

Operands

fn ft fm: specifies the file name, file type, and file mode of the z/VM® directory DIRMAP processes. The defaults are USER DIRECT *.
outfm: is the file mode for all the output files. The default is A1.

Options

DEVSORT: specifies the MDISKMAP is to be sorted by device type first, then by volume serial number (volser). The default is to sort by volume serial number only.
DUPOK: specifies duplicate MDISKs are acceptable and are not to be treated as overlaps. A flag of 'DUP' is placed in the MDISKMAP and a message is typed on the terminal. Fullpack MDISKs are ignored for the purposes of overlap detection.
EXCLUDE: specifies volume serial numbers found in file EXCLUDE VOLSERS * are not to appear in the MDISKMAP. If the input file is not found, a message is issued and no volume serial numbers are excluded. If EXCLUDE is used with the INCLUDE option, EXCLUDE overrides the volume serial numbers specified by INCLUDE. See the sections on input and output files for descriptions of the file formats.
FULLPACK: specifies fullpack minidisk definitions are found in FULLPACK DEFINES. If the input file is not found, a message is issued and the default fullpack minidisk sizes are used. If the file is found, it lists new fullpack minidisk sizes for device type 3380, 3390, 9336, and FB-512 DASD. These new sizes are added to the existing fullpack minidisk sizes. Only numerics are valid for the size.
GAPFILE: specifies all gaps found are to be written in a special format to file fn GAPFILE. If the input file GAPFILE VOLSERS is found, it is scanned for volume serial numbers to be selected for the GAPFILE. See the sections on input and output files for descriptions of the file formats.
Volume serial numbers selected by other options (such as EXCLUDE and INCLUDE) affect this option. To select the same volume serial numbers as those selected by other options, just put the keyword ALL in the GAPFILE VOLSERS file.
INCLUDE: specifies only volume serial numbers found in the INCLUDE VOLSERS file appear in the MDISKMAP. If the input file is not found, a message is issued and all volume serial numbers are included. If INCLUDE is used with the EXCLUDE option, EXCLUDE overrides the volume serial numbers specified by INCLUDE. See the sections "DIRMAP Input Files" and "DIRMAP Output Files" below for descriptions of the file formats.
LINKS: specifies fn LINKMAP is to be produced. This file contains a map of all LINKs to MDISKs on the volume serial numbers processed. Any LINKs to nonexistent MDISKs produce a message on the terminal and are indicated by *** Minidisk does not exist *** in the LINKMAP.
NOCYL0: is for use with the GAPFILE option. It specifies any gap that starts on cylinder 0 is to be recomputed to start at cylinder 1, before being written to the GAPFILE. This is intended to prevent the allocation of MDISKs on cylinder 0, which would change the real volume serial number of the disk.
NOCYL0 can also be specified by including the NOCYL0 keyword in the GAPFILE VOLSERS file.
UNSORT: specifies the utility file DIRECT UNSORT is to be created.

DIRMAP Input Files

There are four optional input files that can be used by DIRMAP to change the content of some of the output files. Input files can reside on any accessed minidisk or any accessed shared file system (SFS) directory.

All four files follow the same format and are scanned in the same manner. The files must be fixed-block format with a logical record length of 80 and conform to the following standards:

Comments can be included in the files. These are indicated by an asterisk in column 1.
Fields to be scanned must be contained within columns 1–71 inclusive, and must be separated from one another by at least one blank.
If all the required fields do not fit on a line, multiple lines can be used. However, a single field cannot span two lines.

INCLUDE VOLSERS

is used by DIRMAP to select certain MDISKs to be included in the MDISKMAP. This file is used only if the INCLUDE option is specified. Fields containing more than seven characters are ignored. However, the only seven-character volid allowed is &SYSRES, which represents the VM system residence volume. If the keyword ALL is found, all volume serial numbers are included in MDISKMAP.

An example of an INCLUDE VOLSERS file might be the following:

* This file contains a list of the packs to be included in the
* MDISKMAP report created by DIRMAP
VMRES VMTOOL
MYPACK

With the above input, the MDISKMAP file created only reports on volumes VMRES, VMTOOL, and MYPACK.

EXCLUDE VOLSERS

is used by DIRMAP to select certain MDISKs to be excluded from the MDISKMAP. This file is used only if the EXCLUDE option is specified. Fields containing more than seven characters are ignored. However, the only seven-character volid allowed is &SYSRES, which represents the VM system residence volume. If the keyword ALL is found, no volume serial numbers are included in MDISKMAP.

An example of an EXCLUDE VOLSERS file might be the following:

* This file contains a list of the packs to be excluded from the
* MDISKMAP report caused by DIRMAP
VMAUX TOOLS1
VMUSER

With the above input, the MDISKMAP file created does not report on volumes VMAUX TOOLS1 and VMUSER.

GAPFILE VOLSERS

is used by DIRMAP to select certain MDISKs whose GAPs are to be included in the GAPFILE. This file is used only if the GAPFILE option is specified. Fields containing more than seven characters are ignored. However, the only seven-character volid allowed is &SYSRES, which represents the VM system residence volume.

If the keyword ALL is found, all the GAPs contained on volume serial numbers are included in the GAPFILE. The EXCLUDE, INCLUDE, and NOCYL0 options also affect GAPFILE reporting, so ALL can be used to report GAPs for just the volume serial numbers specified by EXCLUDE, INCLUDE, or NOCYL0.

If the keyword NOCYL0 is found, gaps starting on cylinder 0 are recomputed to start at cylinder 1.

An example of an GAPFILE VOLSERS file might be the following:

* This file contains a list of the packs that need to have GAPS
* reported on separately by DIRMA
VMAUX TOOLS1 VMRES

With the above input, the DIRMAP creates a file called fn GAPFILE that contains a list of the gaps found on the above volumes.

FULLPACK DEFINES

is used by DIRMAP to list new fullpack minidisk definitions for device type 3380, 3390, 9336, and FB-512. DASD. The first word is either 3380, 3390, 9336, and FB-512. The second word is the ending minidisk cylinder number. The ending minidisk cylinder cannot be more than 8 numeric characters. All other words on the record are ignored.

Therefore, if you wanted to define a fullpack of 1000 cylinders and one of 1500 cylinders on your device type 3380, a fullpack of 2000 cylinders and one of 2500 cylinders on your device type 3390, and a fullpack of 4280287224 blocks on both your device types FB-512 and 9336, your FULLPACK DEFINES looks similar to the following:

3380 999
3380 1499
3390 1999
3390 2499
9336 4280287224
FB-512 4280287224

Your corresponding directory statements looks similar to the following:

MDISK 123 3380 000000 1000 VMSRES RR
MDISK 124 3380 000000 1500 VMSPKK RR
MDISK 125 3390 000000 2000 MYPACK RR
MDISK 126 3390 000000 1500 YOURPK RR
MDISK A00 9336 14680064 4280287224 MYTEST
MDISK A01 FB-512 14680064 4280287224 YOURTS

DIRMAP Output Files

There are four output files that can be produced from a single run of DIRMAP. All the output files are written to the minidisk or SFS directory accessed as A, unless you specify outfm (see the operand outfm ). In that case, they are written to the minidisk or SFS directory accessed at the file mode specified. If the output files are written to an SFS directory, they retain any authorities or aliases held by previous files of the same file ID.

fn MDISKMAP

is the map of all the MDISKs. This file is always produced (unless an error occurs). It should be printed with the CC option.

The format of MDISKMAP is:

Volser:     Volume serial number of disk         
Devtype:    Device type of disk                  
Ownerid:    User ID of the minidisk owner        
Vaddr:      Virtual address of the minidisk      
Mode:       Access mode from MDISK statement     
Start:      Start cylinder of minidisk or gap    
End:        End cylinder of minidisk or gap      
Len:        Size of minidisk in cylinders        
Flags:      Identifies gaps and overlaps         
Subconfig:  ID from SUBCONFIG statement or blank 
Member:     System identifier from associated BUILD statement or *

fn LINKMAP

is the cross-reference map of all LINK statements in the user directory. This file is produced in response to the LINKS option, and should be printed with the CC option.

The format of the LINKMAP is:

Ownerid:    User ID of the minidisk owner
Vaddr:      Virtual address of the minidisk of Ownerid
Linkid:     Volume serial number of disk
Vaddr:      Virtual address of the linked disk for Linkid
Mode:       Access mode from LINK statement
Volser:     Volume serial number of disk
Devtype:    Device type of disk
Start:      Start cylinder of minidisk or gap
End:        End cylinder of minidisk or gap
Len:        Size of minidisk in cylinders
Subconfig:  ID from SUBCONFIG statement or blank
Member:     System identifier from associated BUILD statement or *

fn GAPFILE

is a list of all the gaps detected in response to the GAPFILE option.

The format of the GAPFILE is:

Field 1:    Volume serial number of disk
Field 2:    Device type of disk
Field 3:    Start cylinder of gap
Field 4:    End cylinder of gap
Field 5:    Number of cylinders in gap

This file is produced in response to the GAPFILE option.

DIRECT UNSORT

is a file produced in response to the UNSORT option.

The format of the DIRECT UNSORT file is:

Field 1:    Owner of minidisk
Field 2:    Virtual address of the minidisk
Field 3:    Volume serial number of disk
Field 4:    Start cylinder of minidisk
Field 5:    End cylinder of minidisk
Field 6:    Number of cylinders in minidisk
Field 7:    Device type of disk
Field 8:    ID from SUBCONFIG statement or blank
Field 9:    Member system name from associated BUILD statement or *

Usage Notes

By default, the DIRMAP utility is located on the cross release utilities disk (PMAINT 551).
Input files must be fixed 80-byte (F 80) format on any accessed minidisk or any accessed shared file system (SFS) directory. DIRMAP does not operate on cluster directories. It only operates on a monolithic directory file such as the USER DIRECT file or USER BACKUP file created by the Directory Maintenance Facility (DirMaint™).
There must be a read/write (R/W) minidisk or directory available for output files, indicated by the output file mode parameter (default A1).
A disk that has only fullpack minidisks is not considered to have any gaps, unless its volume serial number is in the GAPFILE VOLSERS file and the GAPFILE option is specified. When these conditions are satisfied, the complete disk is considered to be a GAP (less cylinder 0 if the NOCYL0 option was also specified). The use of the ALL keyword in the GAPFILE does not simulate the above condition, and the volume serial number is still required.
DIRMAP determines the size of a disk from the information it finds in the z/VM directory (device type and highest minidisk extent). If the highest minidisk extent would fit on a smaller model of the disk, DIRMAP assumes the disk is smaller than it actually is. For example, if a 3380-2 (1769 cylinders) does not have a minidisk extent higher than cylinder 884, DIRMAP assumes it is a 3380-1 (884 cylinders). To overcome this problem, just define a fullpack minidisk for the disk. If END is specified as the length of a minidisk, the ending cylinder for that disk will be determined by the other minidisks defined for that device. If END is the only length used for that device, DIRMAP will use the lowest defined cylinder length for that device type.

DIRMAP does not support the use of alternate tracks in the user directory. If the directory contains MDISK statements that use alternate tracks, those minidisks are flagged OVERLAP.

The following table shows the values DIRMAP supports for fullpack minidisks:

Table 1. Fullpack Minidisk Values
DASD Type and Model	Beginning Block or Cylinder	Total Blocks or Cylinders
3380	000	885
3380	000	1459
3380-2	000	1770
3380-3	000	2655
3390	000	455
3390	000	1084
3390-1	000	1113 See note 1 below.
3390-2	000	2226 See note 1 below.
3390-3	000	3339 See note 1 below.
3390	000	4365
3390–9	000	65520
3390–A	000	See note 2 below.
9336	000	2147483640 See note 3 below.
FB-512	000	2147483640 See note 3 below.
Note: This value also applies in 3380 emulation mode. The maximum size of a CMS-formatted minidisk is 65520 cylinders. The maximum size of a minidisk on a CP-formatted extended address volume (EAV) device is 1182006 cylinders. VM supports a SCSI disk, which is emulated as a 9336-020, up to a capacity of 2147483640 512-byte blocks (1 TB). Note, however, that directory, paging, and spooling allocations must reside within the first 16777216 blocks (blocks 0 to 16777215) of a CP-formatted disk.

Using the above table can help you define fullpack minidisk MDISK statements. For example, a fullpack minidisk for a 3380-2 is defined as:

MDISK 123 3380 000000 1770 VMSRES RR

If profile statements appear in the z/VM directory DIRMAP is processing, the profile names also appear in the fn MDISKMAP report under OWNERID and in the fn LINKMAP report under LINKID. The profile names are prefixed with a ":" to distinguish them from user IDs.
MDISK statements containing the DEVNO, T-DISK, or V-DISK option are not taken into account during DIRMAP processing.
For a given volser in the directory, if there is a mixture of device types (for example: FB-512 and 9336), the real device number is used in calculations and in the reports. For example:
```
 MDISK 123 FB-512 0000 100 FBARES RR 
 MDISK 124 9336   0200 150 FBARES RR 
```
In the above example, 9336 would be used as the device type instead of FB-512.
If you add a fullpack minidisk extent of 999 for a 3380 DASD in your FULLPACK DEFINES file your corresponding fullpack minidisk statement in your directory can look similar to the following:
```
MDISK 123 3380 000000 1000 VMSRES RR
```
This support is intended for any DASD that emulates IBM® DASD but has a different number of cylinders.
The special volid "&SYSRES" is allowed in a directory, but the output files will be truncated to six characters ("&SYSRE").
From an authorization perspective, the Ownerid value specifies the user ID to which the MDISK belongs. For multiconfiguration virtual machine instances, the MDISKs can be defined within either the identity or subconfiguration entries. In both cases the Ownerid value specifies the name from the IDENTITY statement. If the SUBCONFIG statement is not referenced by any BUILD statement, the Ownerid value contains the value *NOUSER!.
The SUBCONFIG value in the output is blank unless the MDISK was defined within a subconfiguration entry.
The MEMBER value in the output is * unless the MDISK was defined within a subconfiguration entry, in which case the value displayed is the system identifier from the BUILD statement. If there is no corresponding BUILD statement, the value is blank.
If a LINK statement specifies a user ID from an IDENTITY statement and a Vaddr that is defined in multiple subconfiguration entries referenced by that identity entry's BUILD statements, then the LINK is shown for every possible match.
If the LINK statement is defined within a subconfiguration entry, then the link is not associated with MDISKs or LINKs that are defined in subconfiguration entries for other SSI cluster members.
If a LINK is defined after an MDISK with the same Vaddr, the LINK is ignored. Likewise, duplicate MDISK or duplicate LINK entries are ignored.
DIRMAP does not perform stringent directory verification. It is assumed that all input directories are verified using DIRECTXA to be valid directories.

Examples

If the directory contains the following statements:

DIRECTORY SSI 123 3390 M01RES M02RES M03RES                      
 *                                                                
 ***************************************************************  
 *                                                                
 USER $DIRECT$ NOLOG                                              
  MDISK A01 3390 001 020 M01RES R                                 
  MDISK A02 3390 001 020 M02RES R                                 
 *                                                                
 ******************************                                   
 *                                                                
 *                                                                
 IDENTITY MAINT    MAINT     128M 1000M ABCDEFG                   
  BUILD ON TAPE1 USING SUBCONFIG MAINT-1                          
  BUILD ON TAPE2 USING SUBCONFIG MAINT-2                          
                                                                  
 SUBCONFIG MAINT-1                                                
  MDISK CF1 3390 039 120 M01RES RR READ     WRITE    MULTIPLE     
  MDISK CFD 3390 159 001 M01RES RR READ     WRITE    MULTIPLE     
 * END OF MAINT-1                                                 
                                                                  
 SUBCONFIG MAINT-2                                                
  MDISK CF1 3390 039 120 M02RES RR READ     WRITE    MULTIPLE     
  MDISK CFD 3390 159 001 M02RES RR READ     WRITE    MULTIPLE     
 * END OF MAINT-2

DIRMAP will provide the following MDISK map in the MDISKMAP output file:

 1INSTALL  DIRECT      Map of Minidisks    14:23:24   29Sep2011 Page    1                               
 +_______  ______      ___ __ _________    ________   _________ ____    _                               
 0Volser Devtype  Ownerid  Vaddr Mode     Start        End        Len     Flags    Subconfig Member     
 +______ _______  _______  _____ ____     _____        ___        ___     _____    _________ ______     
                                                                                                        
  ---------------------------------------------------------------------------------------------------   
  M01RES 3390                               000        000        001     Gap                           
                  $DIRECT$  0A01 R          001        020        020                        *          
                                            021        038        018     Gap                           
                  MAINT     0CF1 RR         039        158        120              MAINT-1   TAPE1      
                  MAINT     0CFD RR         159        159        001              MAINT-1   TAPE1      
                                            160        454        295     Gap                           
  ---------------------------------------------------------------------------------------------------   
  M02RES 3390                               000        000        001     Gap                           
                  $DIRECT$  0A02 R          001        020        020                        *          
                                            021        038        018     Gap                           
                  MAINT     0CF1 RR         039        158        120              MAINT-2   TAPE2      
                  MAINT     0CFD RR         159        159        001              MAINT-2   TAPE2      
                                            160        454        295     Gap                           
  ---------------------------------------------------------------------------------------------------

Messages and Return Codes

DMS002E File fn ft fm not found [RC=xx]
DMS003E Invalid option: option [RC=112]
DMS007E File fn ft fm is not fixed, 80-character records [RC=112]
DMS104S Error nn reading file fn ft fm from disk or directory [RC=xx]
DMS105S Error nn writing file fn ft fm on disk or directory [RC=xx]
DMS109S Virtual storage capacity exceeded [RC=112]
DMS2230I Fileid not found, fileid will contain all volsers.
DMS2230I Fileid not found, fileid will not introduce any new FULLPACK definitions
DMS2231I Fileid read.
DMS2232I Fileid written [- no errors].
DMS2233E No corresponding MDISK for userid link addr. [RC=104]
DMS2234W Warning: volume device type type undefined, length unknown. [RC=104]
DMS2235E Duplicate MDISKS on volume.
DMS2236E MDISK overlap on volume [- end of disk overlapped]. [RC=108]
DMS2237E No {MDISK|LINK} statement found. [RC=108]
DMS2238E No MDISKS passed filtering - no MDISKMAP produced. [RC=108]
DMS2239E Error detected in above statement. [RC=104]
DMS2244W The above MDISK statement will not be processed. [RC=104]

Return codes:

RC

Meaning

0

Command complete—no errors

xx

Return code xx from FSOPEN, FSREAD, or FSWRITE

100

Explanation complete (when ‘?’ specified)

104

Processing complete—minor errors

Minor errors might be one or more of the following:

Undefined device type found
Invalid directory statement
LINK found without corresponding MDISK

108

Processing complete—serious errors

Serious errors might be one or more of the following:

Overlap found
No MDISK statements found
LINKMAP requested but no LINK statements found

112

Processing incomplete

Reasons why processing stopped might be one of the following:

Invalid option supplied
Insufficient free storage
Format of input file not fixed 80