Logical Volume Mapping

Preserving usage trends across platform upgrades

Program libraries are identified by their data set name and the volume serial number of the disk on which they reside. Program usage is attributed to these libraries in the data base. Historical usage trends can be built up over time for these software libraries. However, when a software maintenance cycle causes a program library to be replaced by a newer version of the library on a different volume, or when DFHSM processing causes a program library to be relocated to another volume, the historical connection with the usage of the library on the original volume is lost.

For example, upgrading the system platform with a new set of volumes would mean that reporting the long-term usage trend for a particular program such as IDCAMS from the SYS1.LINKLIB library requires generating several reports instead of one, even though the active SYS1.LINKLIB data set may have always resided on the IPL volume.

To counteract this, an optional facility is available where physical DASD volumes as seen by z/OS can be mapped to logical volume sets which persist beyond the time individual physical volumes are part of that logical set. With this approach, historical connections are maintained for functional program libraries which are relocated as DASD is reorganized and renewed.

The volume mapping process

The mapping is achieved by supplying simple assignment statements in a sequential file allocated using the HZADAMAP file name. This file is processed by the HZAPVMAP program. HZAPVMAP is called by the Inquisitor and by the Usage Monitor writer task to translate the selected real volume serial numbers to specified 6-character strings to be considered as the volume serial numbers in data base and report processing.

The assignment statements consist of a left side, an equals sign, and a right side. Volume serial numbers encountered in the collected data which match the left side are converted to the string on the right side. The statements are processed in the order they exist in the HZADAMAP file, and so the earliest matching statement will be used.

It is important that both the Inquisitor and the Usage Monitor process that same volume logical mapping assignments so that usage can be attributed to discovered inventory. The Usage Monitor writer task will process the HZADAMAP file at the end of each collection cycle, so there is no need to recycle or refresh the Usage Monitor to activate updates to the file.

Real volume serial numbers are selected based on the left side of the assignment statement, and replaced in the data with the value specified on the right side of the assignment statement. Generic masking characters and system symbols may be used to generalize the mapping process so that the statements do not have to always be updated as scheduled volume reconfigurations occur.

Historical note: Users of older releases may recall the SYMVOL operand of SCANDIR, and the SYM(Y) setting of the Usage Monitor, both of which are now defunct. These allowed volume serial numbers to be represented by their symbol names. This function can be replicated using volume mapping by specifying the symbol name with two leading ampersands on the right side of an assignment statement. However, such usage of logical volume mapping is not supported unless the symbol represents the same physical volume on all relevant systems. This last restriction points to why SYMVOL and SYM(Y) were removed.

Implications for the PLX setting

The Inquisitor program HZAPINQ allows PLX=Y to be specified in its program parameter. This setting instructs Usage Import to match usage to inventory using the SYSPLEX name instead of the system identifier. This feature provides for eliminating regular Inquisitor scans on multiple systems which share the same DASD configuration. That is, after initial scans from all systems, PLX=Y allows future scans from a single system to keep the inventory up to date for all systems in the same SYSPLEX with a DASD configuration exactly matching (or entirely contained within) the DASD configuration of the primary system on which the DASD scans are to be performed on an ongoing basis.

The use of the logical volume mapping facility does not alter PLX setting requirements since PLX=Y is still permissible if all volumes are mapped to the same logical volume set on all relevant systems.

However, in cases where volume mapping depends on specific volume uses (such as IPL volume) and those uses are not the same across all relevant systems (such as the IPL volume is not shared by all relevant systems), the use of PLX=Y is not supported.

Implications of changing the volume mapping

If you add new volume mapping statements which apply only to volumes not yet processed, then this is equivalent to setting up the statements before performing any DASD scan or usage data collection, and so there is no data inconsistency. Similarly, it is safe to remove statements which apply only to volumes which have been permanently removed from the DASD subsystem.

However, introducing logical volume mapping assignment statements which change the mapping for volumes which have already been processed is equivalent to relocating the libraries on those volumes to new volumes. That is, the historical connection with previous usage of those libraries will be broken.

In such a case, usage already assigned to previously unmapped volumes will be lost. There is currently no mechanism to transfer previously accumulated usage across to the new mappings.

A data set name is unique within the scope of a single DASD volume. Logical volume mapping allows multiple data sets with the same name to appear to reside on the same DASD volume. Many-to-one mappings result in a loss of detail that cannot be exposed by subsequent reporting. This information loss may be acceptable if it improves the reportability of other information such as trends over time which may be requested by local management. Make sure you have thought out all the consequences of this before implementing such a mapping scheme.

For example, consider the scheme where all z/OS IPL volumes were labelled as RESvri where v is the version, r is the release, and i is the iteration. So, the ninth iteration of the z/OS 2.3 IPL volume is labelled RES239, and RES1DG would be the label of the sixteenth iteration of the z/OS 1.13 IPL volume.

The mapping RES*=<Z/OS> might be intended to preserve usage data for libraries such as SYS1.LINKLIB, but what else flows from this? For a start, data sets from all IPL volumes will appear to contain software from the latest z/OS release that is found on DASD, even though much of it will be from a different release, and possibly from a different version. This is because the latest level is always assigned when there are multiple levels that fit the data.

Mappings of RES1*=Z/OSV1 and RES2*=Z/OSV2 will at least allow identifying the correct program product or version, but accurate tracking of specific releases is still not possible.

Consider the following set of logical volume mapping assignments:
RES1D%=Z/OS1D
RES21%=Z/OS21 
RES22%=Z/OS22
RES23%=Z/OS23
RES24%=z/OS24

This mapping set would allow each release of z/OS to be separately identified with each release’s software usage being tracked. Volumes at different maintenance levels of the same release would be treated as a single volume, but this may be an acceptable loss of detail to make longer usage trends available for reporting.

Now consider grouping the usage by system rather than by OS release. The mapping &SYSR1.=<&SMF.> will preserve usage history for the data sets on each system’s IPL volume no matter how frequently the IPL volume is cycled to a new maintenance level. As IPL volumes are switched and a new DASD scan is imported, the software levels recorded in the data base will be updated, but usage trend reports can still include data from older software levels. Such a mapping scheme could be extended to platform volumes if local volume serial naming conventions are suitable.

Bear in mind that if a program is used via a STEPLIB to a data set on an IPL volume which is not the system’s current IPL volume, then that usage will be recorded against the real volume serial (assuming no other active mappings applied), but that will be correctly attributed to the software inventory from the DASD scan performed on the same system with the same set of logical volume mappings. In this scenario, each system would require a DASD scan on an ongoing basis (that is, PLX=Y would never be used) because the systems sharing the DASD would not have identical mappings.

Volume symbol mapping file

When called by the Inquisitor or the Usage Monitor, the HZAPVMAP program accesses the logical volume mapping file via the HZADAMAP data definition (DD). The logical volume mapping facility is only used if the HZADAMAP file allocation is present, and if the file contains valid volume symbol mapping assignment statements, and if any of these statements apply to volumes being processed. There are no specific Inquisitor or Usage Monitor parameters, settings or statement keywords which control this facility.

The assignment statements in the HZADAMAP file consist of a left side character string specifying the volume serial numbers which will be replaced by the statement's operation, an equals sign, and a right side character string specifying the volume serial number to be imported into the data base.

Syntax requirements of the HZADAMAP file are:

  • Data from a record located after a blank or after column 72 (whichever comes first) is discarded before validation. The remaining data is referred to as active text in the points below.
  • Because of the first point, all statements must start in column 1.
  • No continuations across record boundaries are allowed.
  • Active text without an equals sign is treated as a comment.
  • All active text non-display characters are translated to periods. (EBCDIC code points in the x'40' to x'FE' range deemed to be display characters.)
  • DBCS is not supported. DBCS characters cannot be used in volume serial numbers.
  • If an ampersand is present in the active text then the system symbol substitution routine is called to perform symbol resolution.
  • If the left side and/or the right side evaluate to a string longer than 6 characters then the first 6 characters will be used.
  • If the left side and/or the right side evaluate to a string shorter than 6 characters then the string will be extended with blanks to a length of 6 characters.
  • The first or only equals sign must be followed by a non-blank. (There is nothing to stop the use of an equals sign in the right side character string.) That is, the right side cannot be a null string.
  • Generic masking characters can only be used on the left side. These characters are treated as literals if used on the right side.
  • The generic masking characters are a percent sign for any single character and an asterisk for any group of zero or more characters.
  • If the left side evaluates to six asterisks, it will be replaced by the current IPL volume serial number.
  • Symbols are allowed in the left side and the right side character strings.
  • System symbols plus the symbols &SMF (SMF system identifier) and &SYSLPAR (LPAR name) can be used. Note that &SYSLPAR may resolve to a null string if z/OS is running in a virtual machine.

Further recommendations for HZADAMAP statements are:

  • Do not use an ampersand character unless it is to denote the start of a symbol name.
  • Do not use system dynamic symbols.
  • Exploit system static symbols where appropriate so that the same set of statements can be used on multiple systems.
  • Do not attempt to convert a statement into a comment by simply inserting an asterisk in column 1. Inserting a blank, or an asterisk and a blank at the start of the statement will convert it to a comment.
  • Consider using a character in the right side string which is not a valid volume serial number character. This will prevent name space clashes between logical volume set names and real volume serial numbers, and also make it plain to report readers that the displayed volume is the result of a logical mapping.
  • Only use EBCDIC characters in the right side string which reliably translate to invariant ASCII characters so that the string can be reliably rendered by the Analyzer in reports without any dependence on web browser language and code page settings.

The HZADADYM file may contain either fixed-length or variable-length records. Sequential concatenations of unlike data sets are supported. If you decide to use this facility, you might find it convenient to store the volume symbol mapping statements in a member of your customized PARMLIB library which was created by the HZASCUST process.

Because invalid statements are ignored, you may want to test the statements before using them in production. To do this, run the HZAPINQ program with SYSPRINT allocated to SYSOUT, SYSIN allocated to DUMMY and HZADAMAP allocated to your volume mapping statement file. The absence of any output files will cause a condition code of 16, but the active mapping status will still be reported.

Volume mapping statement examples

Consider some sample statements.

TSO=+TSO+    /* this is a valid statement followed by a comment */
*TSO=+TSO+   so is this – text after a blank is a comment
* TSO=+TSO+  this whole line is a comment

The first statement would rename volume TSO to volume +TSO+ in the collected data. The second statement would rename volume serial numbers ending in TSO (such as TSO, 9TSO, 99TSO and 999TSO) to +TSO+. The third statement is a comment due to the blank in column 2 being situated before the assignment statement.

******=SYSRES    (6 asterisks on left treated as a special case)
*********=SYSRES (only the first 6 chars are used)
&SYSR1=SYSRES    (= and e-o-r also flag end of symbol name)
&SYSR1.=SYSRES

These four statements are functionally equivalent, and would cause the IPL volume serial number to be replaced by the literal SYSRES.

WORK*=WORK*   <--- lump WORK volumes together
PUB%%%=PUB%%% <--- lump PUBLIC volumes together

The first statement would rename any volume serial starting with WORK to WORK* in the collected data. The second statement would rename any 6-character volume serial starting with PUB to PUB%%% in the collected data.

&SYSCLONEDISK=<CLON>
&SYSCLONE.DISK=<CLON>

where &SYSCLONE is a symbol resolving to S1.

The first statement has no effect because the literal &SYSCL cannot match any real volume serial number. The absence of a period to flag the end of the symbol name prevented any symbol substitution because the symbol &SYSCLONEDISK does not exist. The second statement will cause volume S1DISK to be reported as volume <CLON>.

&SYSR1=**&SMF  <--- Home system residence volume
%%%RES=*OTHRS  <--- Did we STEPLIB or JOBLIB to inactive SYSRES?

where all systems' IPL volumes have volume serial numbers with the fourth to sixth characters being equal to RES.

The first statement would cause the IPL volume to be reported as a volume serial number made up of two asterisks concatenated with the system identifier. Programs found to be on the IPL volumes of other systems, or perhaps on residence volumes not even in active use, would be reported as residing on volume *OTHRS (other residence volume).

&IMSVS=&&IMSVS  <--- Show current IMS volume as its symbol name
&DB2DA=&&DB2DA  <--- Show current DB2 volume as its symbol name

These two statements would cause the volumes with serial numbers which match the values of the system symbols &IMSVS and &DB2DA to be reported as &IMSVS and &DB2DA respectively.