Inquisitor program command syntax

The Inquisitor program includes SYSIN commands and optional command operands.

SYSIN commands

The Inquisitor program uses the SCANCMD, SCANDIR, and SCANPGM SYSIN commands that are described in the following table.

Table 1. SYSIN commands
Command	Description
SCANCMD	Allows command syntax and operand consistency to be checked by the Inquisitor without initiating an actual scan for program libraries. It performs a parse only operation, although output files are opened. Error messages relating to syntax and operand errors are produced as usual. This verb is useful if you are formulating the best request combination when implementing on any given system.
SCANDIR	Collects data from program library directory entries. Contents of program members are not accessed. Compared to SCANPGM, its reduced data collection allows it to run faster. Although all syntactically correct operands are allowed, some operands relating to data from member contents are ignored during processing. SCANDIR collects all of the information needed for automated software identification, and is the command of choice for a production environment.
SCANPGM	Collects all data collected by SCANDIR, and information from member contents. Such information relates to program structure and history. HCL support might request SCANPGM output data to assist with problem diagnosis and resolution.
SCANDEV	Collects information about the input and output (I/O) configuration of the z/OS system including online I/O devices, control units, and related channel path connectivity. The SCANDEV command has no operands.

The Inquisitor can process multiple requests in a single program run. The output of these requests is contained in the same file.

This syntax diagram shows the SYSIN commands and their operands.

Operand defaults are:

DSNAME(*) VOLUME(*) DEVICE(*) PROGRAM(*)

All operands are optional. They are:

DATASET Alias: DSNAME

This operand specifies one or more 1 to 44-byte data set name masks. Only data sets with names matching any masks specified here are processed.

Data sets with names not matching any masks specified here are not processed. Multiple masks must be separated by one or more delimiters. This operand can be specified more than once in a request, whereupon all masks specified in all occurrencesof this operand are checked for selection matching. The precise treatment of asterisks in these masks is altered by the presence of the CATALOG keyword in the request. When CATALOG is specified, mask matching becomes qualifier aware and a single asterisk represents one, or part of, one qualifier only. When CATALOG is specified, use a double asterisk to specify any number of qualifiers. The data set name selection mask is the only mask affected by the CATALOG keyword. When the CATALOG keyword is present, exactly one DSNAME mask must be specified.

XDATASET Alias: XDSNAME

This operand specifies one or more 1 to 44-byte data set name masks. Data sets with names matching any mask specified here are not processed. Multiple masks must be separated by one or more delimiters. This operand can be specified more than once in a request, whereupon all masks specified in all occurrences of this operand are checked for exclusion matching. If this operand is used, each mask must specify a subset of a DATASET mask

VOLUME

This operand specifies one or more 1 to 6 byte volume serial number masks. Only volumes with serial numbers matching any mask specified here are processed.

Volumes with serial numbers not matching any mask specified here, are not processed. Multiple masks must be separated by one or more delimiters. This operand can be specified more than once in a request, whereupon all masks specified in all occurrences of this operand are checked for selection matching. A volume serial number mask of six asterisks specifies the current IPL volume, which is ascertained during execution.

XVOLUME

This operand specifies one or more 1 to 6 byte volume serial number masks. Volumes with serial numbers matching any mask specified here are not processed. Multiple masks must be separated by one or more delimiters. This operand can be specified more than once in a request, whereupon all masks specified in all occurrences of this operand are checked for exclusion matching. If this operand is used, each mask must specify a subset of a VOLUME mask. A volume serial number mask of six asterisks specifies the current IPL volume, which is ascertained during execution.

DEVICE

This operand specifies one or more 1 to 4 byte device number masks. Only volumes with device numbers matching any mask specified here are processed. Volumes with device numbers not matching any mask specified here, are not processed.

Multiple masks must be separated by one or more delimiters. This operand can be specified more than once in a request, whereupon all masks specified in all occurrences of this operand are checked for selection matching. Standard character string mask matching is used. The use of characters which are not hexadecimal digits will not be detected by the program.

XDEVICE

This operand specifies one or more 1 to 4 byte device number masks. Volumes with device numbers matching any mask specified here are not processed. Multiple masks must be separated by one or more delimiters. This operand can be specified more than once in a request, whereupon all masks specified in all occurrences of this operand are checked for exclusion matching. If this operand is used, each mask must specify a subset of a DEVICE mask. Standard character string mask matching is used. The use of characters which are not hexadecimal digits will not be detected by the program.

PROGRAM Alias: PGM

This operand specifies one or more 1 to 8 byte program name masks. Only programs with names matching any mask specified here areprocessed.

Programs with names not matching any mask specified here, are not processed. Multiple masks must be separated by one or moredelimiters.

This operand can be specified more than once in a request, whereupon all masks specified in all occurrences of this operand are checked for selection matching.

XPROGRAM Alias: XPGM

This operand specifies one or more 1 to 8 byte program name masks. Programs with names matching any mask specified here are not processed. Multiple masks must be separated by one or more delimiters. This operand can be specified more than once in a request, whereupon all masks specified in all occurrences of this operand are checked for exclusion matching. If this operand is used, each mask must specify a subset of a PROGRAM mask.

STOGROUP Alias: SG

This operand specifies one or more 1 to 8 byte storage group name masks. SMS- managed volumes in a storage group with a name matching any mask specified here are processed.

SMS-managed volumes in a storage group with a name that does not match any mask specified here, are not processed. Multiple masks must be separated by one or more delimiters.

This operand can be specified more than once in a request, whereupon all masks specified in all occurrences of this operand are checked for selection matching.

Volumes which are not SMS-managed are not processed unless the NONSMS keyword operand is specified.

XSTOGROUP Alias: XSG

This operand specifies one or more 1 to 8 byte storage group name masks. SMS- managed volumes in a storage group with a name matching any mask specified here are not processed. Multiple masks must be separated by one or more delimiters.This operand can be specified more than once in a request, whereupon all masks specified in all occurrences of this operand are checked for exclusion matching. If both this mask and a STOGROUP mask are used, then each mask must specify a subset of a STOGROUP mask.

NONSMS

This keyword operand specifies that volumes which are not SMS-managed are eligible for processing. The presence of this operand means that SMS-managed volumes are not processed unless the STOGROUP operand was used to supply a storage group name mask.

LINKLIST

This keyword operand specifies that all link list data sets are to be unconditionally included for processing.

AUTHLIBS

This keyword operand specifies that all APF authorized data sets are to be unconditionally included for processing.

NOALIAS

This keyword operand specifies that any program member marked as an alias is to be excluded from processing.

CATALOG

This keyword operand specifies that data sets to be processed are located from a catalog search rather than VTOC searches. Data set alias names are not processed. The Inquisitor triggers and waits for a RECALL operation for each migrated data set which passes data set name mask processing, unless NORECALL is also specified.

NORECALL

This keyword specifies that migrated data sets are not to be recalled and are excluded from processing. This operand only has effect when the CATALOG operand is also specified. Data sets with a catalog entry indicating a volume serial number of MIGRAT, or ARCIVE, are deemed to be migrated.

FULLIDR

This keyword operand specifies that a full scan of CESD and IDR records is to be performed, even when a module would not have been selected for such processing. Depending upon the exact nature of the request being run, this operand can significantly elongate the elapsed time of Inquisitor runtime.

This operand is ignored for a SCANDIR request.

REMIGRATE

This keyword operand specifies that when a data set which had to be recalled has been processed, DFHSM is requested to migrate the data set again asynchronously. Migrated data sets can only be processed when the CATALOG operand is also specified. Only data sets with a catalog entry indicating a volume of MIGRAT are remigrated.

The presence of this operand requires that the MCDS file is allocated to the DFHSM MCDS. Access to the MCDS allows the Inquisitor to avoid recalls for data sets which are not partitioned, do not have an undefined record format, and do not have a block size of at least 1024.

NOML2

This keyword operand specifies that data sets migrated to level two are not to be recalled and are excluded from processing. Migrated data sets can only be processed when the CATALOG operand is also specified. Only data sets with a catalog entry indicating a volume of MIGRAT are checked for level two status.

ABRMIG

This keyword operand indicates that when a catalog entry with a volume of MIGRAT is encountered, the FDRABR product is to be invoked to determine whether a recallable archived copy of the data sets is available or not. If it is, then the data set is processed. If not, then the data set is not processed.

The NORECALL operand takes precedence over this operand. The effect of ABRMIG is not affected by the ABRARC operand.

The presence of this operand requires that the ABRIN and ABRPRINT filesare allocated.

ABRARC

This keyword indicates that, when a cataloged data set cannot be found on the volume, the FDRABR product is to be invoked in order to determine whether a recallable archived copy of the data set is available. If it is, then the data set is processed. If not, the data set is not processed.

The NORECALL operand takes precedence over this operand. The effect of ABRARC is not affected by the ABRMIG operand.

The presence of this operand requires that the ABRIN and ABRPRINT files are allocated.

NOTAGDATA

This keyword indicates that data written to program libraries by the Product Tagger is not to be collected and written to the Inquisitor output file. Use this operand only when you do not want to update the Local Knowledge Base during the import process with the latest Tagger data that could be found by the Inquisitor.

MAXTASKS

This operand specifies the maximum number of VTOC-scanning subtasks to be activated by the Inquisitor. These subtasks reduce the elapsed time of an Inquisitor scan by enabling the concurrent processing of multiple volumes. Reducing the number of subtasks reduces the demand on storage in the region and does not impact performance unless the main task has to wait longer for VTOC scan results. The operand value is a single decimal number in the 1 to 200 range. The default value is 10. The actual number of subtasks used does not exceed the number of volumes to be scanned.

VTOC-scanning subtasks are not used for CATALOG requests.

SYSIN syntax rules for the Inquisitor

Syntax rules are as follows:

Only the first 72 bytes of an input record are everscanned.
Short records are extended to 72 bytes withblanks.
Blanks and commas are equivalent.
Sub parameters of value operands are specified inparentheses.
A continuation to the next record is requested by a plus or a hyphen whenit follows a delimiter, or is at the start of a record.
A continuation cannot be requested in the middle of a word orvalue.
The part of the record following a continuation character is ignored andcan be used for comments.
Records beginning with an asterisk are commentrecords.
Records containing only blanks or commas are commentrecords.
Comment records are ignored by syntax parsing logic, and do not alter continuationstatus.
TSO conventions apply to abbreviations. That is, operands can beabbreviated to the minimum unambiguous length. Verbs cannot be abbreviated.
If the input record contains an ampersand, the system symbolsubstitution routine ASASYMBM is called to perform symbol substitution processing.
All input requests are parsed and stored before the first request is processed. If a syntax error is encountered, no requests are processed. This is to reduce the instance of incorrect or unproductive requests triggering lengthy DASD subsystem scans. The error is in the last record echoed inSYSPRINT.
Value masks are character strings which are compared to data found at run time. Comparison is performed one byte at a time, from left to right. For a match, the characters must compare equal, unless a generic mask character is found.
System static symbols, system dynamic symbols, and &SMF (SMF system identifier) and &SYSLPAR (LPAR name), can be used to construct value masks. &SYSLPAR may resolve to a null string if z/OS is running in avirtual machine.
Valid generic mask characters are a percent (%), to flag a match for anysingle character, and an asterisk (*), to flag a match for any character string segment of zero or greater length.

Inquisitor examples

These examples show some possible scenarios where you can customize the scope and type of processing when you run the Inquisitor program.

Example 1

These three statements are equivalent, and request data collection for all programs on all online DASD volumes.

SCANDIR
SCANDIR DA(*) PGM(*) SCANDIR VOL(*) DS(*)

Example 2

To scan all SMS-managed volumes except volumes in storage group SGWORK use:

SCANDIR STOGROUP(*) XSTOGROUP(SGWORK)

Example 3

To scan all volumes except volumes in storage groups with names beginning with SGW use:

SCANDIR XSTOGROUP(SGW*) NONSMS

Example 4

To scan all volumes with serial numbers beginning with TSO and WRK, these two requests are used in a single program run:

SCANDIR VOLUME(TSO*) SCANDIR VOLUME(WRK*)

Note that these 2 statements could be reduced to a single statement as follows:

SCANDIR VOLUME(TSO* WRK*)

Example 5

To scan all volumes except those with serial numbers beginning with TSO and WRK use:

SCANDIR XVOLUME(TSO* WRK*)

Example 6

To scan all volumes with serial numbers beginning with USR which are also in SMS storage groups with names beginning with SG for programs with names beginning with UTIL, use:

SCANDIR VOLUME(USR*) STOGROUP(SG*) PROGRAM(UTIL*)

Example 7

To scan all data sets with high level qualifiers of SYS1, SYS2, SYS3, except z/OS distribution libraries, use:

SCANDIR DSNAME(SYS%.*) XDSNAME(SYS1.A*)

Example 8

To restrict the data in the previous example to cataloged data sets, use:

SCANDIR DSNAME(SYS.**) XDSNAME(SYS1.A*) CATALOG

Note: The extra asterisk in the data set name selection mask. Without this, only data set names with two qualifiers are selected. Data set name exclusion processing is not changed by the CATALOG operand.

Example 9

To scan the current IPL volume, and any other link, list, and APF authorized libraries use:

SCANDIR VOLUME(******) LINKLIST AUTHLIBS

Example 10

To scan the single cataloged data set SYS1.PPLIB without a lengthy DASD subsystem scan use:

SCANDIR DATASET(SYS1.PPLIB) CATALOG

Example 11

To scan all cataloged SYS1 and SYS2 data sets use (a) two requests in a single program run, or (b) a single request. The two approaches exhibit similar resource consumption:

(a)

SCANDIR DA(SYS1.**) CAT
SCANDIR DA(SYS2.**) CAT

(b)

 SCANDIR DS(SYS.**)CAT XDSN(SYS3.*,SYS4.*,SYSA.*)

The XDSN values are coded as shown under the assumption that SYS1, SYS2, SYS3, SYS4 and SYSA are the only 4-character high-level qualifiers beginning with SYS on the system being scanned.

Note: SCANDIR DS(SYS1.**,SYS2.**) CAT is not allowed.

Example 12

These examples are all equivalent. They scan the entire DASD subsystem for all data sets with a first qualifier of SYS1 or SYS2, excluding those with a second qualifier beginning with A.

(a)

SCANDIR DA(SYS1.*,SYS2.*) XDA(SYS1.A*,SYS2.A*)

(b)

SCANDIRDA(SYS1.* + SYS2.*) + XDA(SYS1.A* + SYS2.A*)

(c)

SCANDIRDA(SYS1.*) + DA(SYS2.*) + XDA(SYS1.A*) + XDA(SYS2.A*)

(d)

SCANDIR DA(SYS1.*) XDA(SYS1.A*) + DA(SYS2.*) XDA(SYS2.A*)

(e)

SCANDIR DA(SYS1.*) XDSN(SYS1.A* SYS2.A*)DS(SYS2.*)

Designing Inquisitor requests

When constructing statements for the Inquisitor SYSIN file, try to combine all selection and exclusion criteria to form a single SCANDIR request. A single Inquisitor request will not scan a VTOC or a library more than once.

It can be difficult to formulate a system scan into a single CATALOG request, meaning that when the CATALOG operand is used, multiple requests are coded. Ensure that no data set will be scanned by more than one SCANDIR CATALOG request by excluding as many data set name patterns from each request as necessary. Data set name exclusions may not be necessary if all CATALOG search selection masks represent disjoint parts of the name space.

The example shown here uses the XDA operand to prevent SYS1.LINKLIB from being scanned more than once:

SCANDIR DA(SYS1.**) CATALOG
SCANDIR DA(SYS .LINKLIB) XDA(SYS1.LINKLIB) CATALOG

As well as using the selection and exclusion facilities to ensure completeness, they can also be used to improve performance and efficiency by excluding DASD volumes which do not contain program libraries. Although a volume with no program libraries can be scanned quickly, processing duration might be reduced if such volumes can be excluded from an Inquisitor scan.

For example, volumes that only contain databases, or temporary data sets, do not have any files suitable for Inquisitor processing, but the VTOCs of those volumes are still read unless excluded by the appropriate selection criteria.

To illustrate this further, consider a system with these DASD subsystem usage elements:

System platform

Non-SMS and storage group SYSTEM.

Work pool

Storage group TEMP containing temporary and short-lived (two days)permanent files.

TSO

Storage groups TSOONE and TSOTWO

Non-DB application

Non-SMS and storage groups BATCH1 and BATCH2.

Databases

Non-SMS volumes DBA001 to DBA099 and SMS storage groups DB01, DB02, and DB03.

The scanning of this configuration is to be carried out with the following assumptions:

No need for data from libraries that do not exist for more than two days.
No program libraries on database volumes.
Applications combine their program libraries and non-database files.
TSO users can have program libraries.
Management requires information regarding all potentiallypermanent executable software.

To acquire Inquisitor data from all useful sources without processing volumes more than once, and without processing irrelevant volumes, you can specify multiple requests in a single Inquisitor run. For example:

SCANDIR 
SG(SYSTEM) 
SCANDIR SG(TSO*) 
SCANDIR 
SG(BATCH*)
SCANDIR NONSMS XVOL(DB*)

This can be consolidated into a single request giving the same result. For example:

SCANDIR SG(SYSTEM TSO* BATCH*) NONSMS XVOL (DB*)

Controlling the data extraction level

When performing a system scan, the SCANDIR verb is usually sufficient. For most libraries, SCANDIR is able to collect all the necessary information from the directory entries without the need to access member contents. For PDSE libraries, this includes collecting the bind (or link edit) date. For some specific system modules, SCANDIR will also analyze the member contents to extract additional data necessary to determine the software level of those modules.

If it is important to collect the bind dates of PDS load modules, then the SCANPGM verb can be used instead of SCANDIR. However, because SCANPGM reads multiple blocks for every member, the elapsed time required to scan each PDS library will increase by several hundred percent.

To perform maximum data extraction from every scanned program, use the SCANPGM verb with the FULLIDR keyword. This combination will greatly increase the elapsed time it takes to scan PDSE libraries as well as PDS libraries, so it is not normally expected to be used.

Extracting LE compile unit information

Specifying the FULLIDR keyword on a SCANPGM request will also allow the Inquisitor to extract information about LE compile units. Such information is stored within the program object code when a program is compiled by an

LE-family compiler such as current COBOL and PL/I compilers. The data that can be tracked for each compile unit within a scanned program includes:

The compile date.
The compiler level.
The ARCH (architecture level) setting.
The OPT (optimization level) setting.
The DATA DIVISION statement count (for COBOL only).
The PROCEDURE DIVISION statement count (for COBOL only).

Because of the additional resource consumption of a SCANPGM FULLIDR request over the usual SCANDIR request, it is not anticipated that a full system scan would be performed to collect this data, but rather a scan targeted to relevant application program libraries. The data from this limited scan would be used to form a purpose- built repository where data base queries can be used to extract information of interest.

When the time comes to update the system’s LE compile application status, the repository would be deleted and recreated from a new targeted scan. To ascertain usage history data for these application programs, relevant queries would be directed to the main system repository where the usage data is imported.

Scanning migrated libraries

The Inquisitor locates load libraries by either scanning the VTOC of online volumes, or by searching the system catalog (CATALOG) for relevant data sets. When youuse the Catalog Search Interface, you can return data sets for migrated libraries. VTOC scans do not find migrated data sets.

When the keyword CATALOG is specified in a request statement, the Inquisitor passes the data set name selection mask to the Catalog Search Interface (CSI) to search for the catalog entries. It is possible that one or more of the catalogentries returned by the CSI are for a data set that has been migrated. In contrast, VTOC scans do not find migrated data sets.

Inquisitor processing of migrated data sets found by the CSI involves dynamic allocation which then triggers the recall of the data set. Recalls increase Inquisitor processing time. The processing leaves the data set in a recalled status.

The Inquisitor looks at the volume serial number in the catalog entry to determine if a data set is migrated or not. A data set is considered to have been migrated if its catalog entry indicates a volume serial number of either MIGRAT or ARCIVE.

To suppress the processing of all migrated data sets, specify the NORECALL keyword on each Inquisitor request.

Integration with DFHSM

If you are using the MCDS file allocation, and a data set cataloged on volume MIGRAT is encountered, the Inquisitor can read the data set record from the DFHSM Migration Control Data Set (MCDS) to verify that the data has the attributes of a program library. If the MCDS record is not found, the data set is ignored and processing is bypassed, avoiding a DFHSM error condition. If the data set does not have partitioned organization, an undefined record format, and a block size of at least 1024, the Inquisitor ignores the data set, avoiding the recall of many data sets which are not program libraries.

For systems with DFHSM space management functions, you can use the request keywords NOML2 and REMIG. The MCDS file allocation is a prerequisite for using the following keywords:

NOML2: Specifies that data sets migrated to level 2 are excluded from the scan.
REMIG: Specifies that after a recalled data set is processed by the Inquisitor, the Inquisitor requests DFHSM to remigrate the data set. The Inquisitor does not wait for the migration to complete, but begins to process the next data set immediately after making the request to DFHSM. Migration level 2 is never specified by the Inquisitor for the migration, even if the data set was recalled from ML2. (However, it might be selected by DFHSM as a result of SMS management class settings.)

Note:

Any combination of REMIGRATE, NOML2, and NORECALL is valid. Specifying NORECALL means NOML2 and REMIGRATE have noeffect.
In the case where you want to scan all relevant migrated program libraries and do not want any such libraries explicitly remigrated afterward, you would not code any of the NORECALL, NOML2 and REMIGRATE keywords. In this instance, the MCDS file allocation, though optional, can still be used to great advantage.