zDIAG Stable 3.2 - Installation Guide
=====================================

OVERVIEW
--------
For the current site the package is preconfigured for:

  OEMDS.RUN.EXEC
  OEMDS.RUN.PANEL

If your site uses another base HLQ, edit ONE line near the top of the
supplied SYSPROC member ZDIAG before installing it:

  zdSiteHlq = 'OEMDS.RUN'

Example for SITEA.RUN:
  zdSiteHlq = 'SITEA.RUN'

The defaults then become:
  SITEA.RUN.EXEC
  SITEA.RUN.PANEL

No ZDINSTAL or source-patching step is required.

STEP 1 - EXTRACT THE ZIP
------------------------
Extract the package on the workstation.

The important directories are:

  SYSPROC
  EXEC
  PANEL

Files are already named exactly as their intended mainframe member names.

STEP 2 - CREATE THE EXEC LIBRARY
--------------------------------
Create:

  OEMDS.RUN.EXEC

or:
  <SITEHLQ>.EXEC

Recommended attributes:
  Data set organization : PO or PDSE
  Record format         : FB
  Record length         : 80
  Block size            : 0

A reasonable initial allocation is:
  Primary   : 20 tracks
  Secondary : 10 tracks
  Directory : 30+ blocks if using PDS

STEP 3 - CREATE THE PANEL LIBRARY
---------------------------------
Create:

  OEMDS.RUN.PANEL

or:
  <SITEHLQ>.PANEL

Recommended attributes:
  Data set organization : PO or PDSE
  Record format         : FB
  Record length         : 80
  Block size            : 0

A small allocation such as 5 primary / 2 secondary tracks is sufficient.

STEP 4 - COPY THE EXEC MEMBERS
------------------------------
Transfer every member from the package EXEC directory to:

  OEMDS.RUN.EXEC

Transfer in TEXT / ASCII mode.

The target library must contain:

  ASIDDIAG
  CPUDIAG
  ENQDIAG
  JES2DIAG
  JOBDIAG
  LOGRDIAG
  LONGDIAG
  STORDIAG
  XCFDIAG
  ZDBATCH
  ZFSDIAG

No ZDPATCHD member is needed.

STEP 5 - COPY THE PANEL MEMBERS
-------------------------------
Transfer every member from the package PANEL directory to:

  OEMDS.RUN.PANEL

Transfer in TEXT / ASCII mode.

Members:

  ZDIAGP
  ZDIAGSET
  ZDIAGH
  ZDIAGC

The panel library does NOT need to be permanently added to ISPPLIB.
ZDIAG dynamically uses LIBDEF.

STEP 6 - INSTALL THE TSO COMMAND
--------------------------------
Copy:

  SYSPROC/ZDIAG

into one normal site SYSPROC or SYSEXEC concatenated library as member:

  ZDIAG

If your site HLQ is not OEMDS.RUN, update the single zdSiteHlq line in
ZDIAG before copying it.

Do not place the entire diagnostic EXEC library in SYSPROC merely to run
zDIAG.

Do not ALTLIB-activate OEMDS.RUN.EXEC for normal zDIAG use.

STEP 7 - FIRST INVOCATION
-------------------------
From ISPF issue:

  TSO ZDIAG

If invoked outside an active ISPF dialog, ZDIAG starts ISPF itself.

On first use the Job Card / Libraries panel is displayed.

Default values should be:

  REXX library  ===> OEMDS.RUN.EXEC
  Panel library ===> OEMDS.RUN.PANEL

The user may change these values if required.

JOB/JES input can use one, two, three or four records.

Example:

  //TSSSKJOB JOB (ACCT),'SARATH',CLASS=A,MSGCLASS=H,
  //             NOTIFY=&SYSUID
  /*JOBPARM SYSAFF=MF1T

Only the first nonblank record has to be the //... JOB statement.
Later records may contain continuation JCL, /*JOBPARM, /*ROUTE or other
valid JES control records.

The user may also leave the JOB card blank on first entry. zDIAG will
request it when a diagnostic is actually submitted.

STEP 8 - MAIN PANEL
-------------------
The user can select a utility with S or enter its number/full name.

Aliases:
  JOB
  JES2
  CPU
  LONG
  STOR
  ENQ
  ASID
  XCF
  ZFS
  LOGR

Commands:
  HELP
  JOBCARD

JOBCARD reopens the Job Card / Libraries panel at any time.

STEP 9 - FIRST TEST
-------------------
Use:

  CPUDIAG

Parameters:
  SAMPLE

Submit the job.

Expected spool DDs:

  ZREPORT
  ZLOG
  SYSTSPRT

The main panel displays "Job submitted" once. The old status clears on
the next Enter, command or selection.

STEP 10 - LIVE TEST
-------------------
After SAMPLE passes, test a low-risk live run such as:

  CPUDIAG
    10 3 5

or:

  ZFSDIAG
    /oem

The runtime utility is fetched from OEMDS.RUN.EXEC through the submitted
job's SYSEXEC DD. The foreground user does not hold this library through
ALTLIB.

STEP 11 - RETURN CODE POLICY
----------------------------
RC 00:
  The utility successfully created a usable diagnostic report.

This remains RC 00 even when the report finds HIGH/CRITICAL conditions.

Non-zero RC:
  Invalid invocation, required collection failure, internal utility
  failure, or no usable report produced.
