SPI Release 4.3 User's Guide and Reference

Copyright © 2001 by Software Pursuits, Inc. All Rights Reserved. Except as noted below, no part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise without the prior written permission of Software Pursuits, Inc.

Table of Contents

• Installation on VSE/SP and VSE/ESA Systems
  • Overview
    • Direct Interface vs. PSW Swapping
    • Forcing PSW Swapping
    • VSE/ESA Version 2.1 and Later
    • SPI Product Considerations
  • Installation Steps
    • Step 1. Backup Your System
    • Step 2. Define the SPI Product Libraries
    • Step 3: Mount the Installation Tape
    • Step 4. Restore SPI Common Interface Sub-library
    • Step 5. Update BG ASI PROC
    • Step 6. Copy SPIINIT Procedure into IJSYSRS.SYSLIB
    • Step 7. Activate the SPI Common Interface
    • Step 8. Run SPICPUID
    • Step 9. Load SPI Messages into OME File (Optional)
  • JCL Exit Considerations
• Installation on MVT/VSE Systems
  • Overview
  • MVT/VSE Requirements
  • Installation Steps
  • Step 1. Mount The Installation Tape
  • Step 2. Catalog SPIINSTL PROC
  • Step 3. Run the SPIINSTL Procedure
    • SPIINSTL Prompting Process
    • SPIINSTL Processing
  • Step 4. IPL The Updated System

• Commands
• Examples

• Overview
• Performing an Expiration Update
• VM Requirements
• SPIEXPIR Control Statements
• Summary of SPIEXPIR Control Statements
• CPU
  • Operands/Options
• NEWCUST
  • Operands/Options
• OVERRIDE
  • Operands/Options
• UPDATE
  • Operands/Options
• SPIEXPIR Example

• Overview
• SPIZAPCK Utility
  • Executing SPIZAPCK
  • Information Displays
• SPICPUID Utility - Display CPU Serial Number
  • VM Requirements
  • SPICPUID Example
• SPIEXPRT Utility
  • OPTION
  • TEST
  • Example
• SPIDATE Subroutine
  • SPIDATEP Macro

The Software Pursuits Common Interface provides a set of utility programs and subroutines that are common to all SPI products. Also part of the Common Interface is a common API for frequently used programs and routines. This API is used by all SPI products and provides common access for such things as:

• Standard interface to operating system routines
• Parameter parsing routines
• Expiration and license management
• Date and time routines
• Problem determination aids

The Common Interface must be activated prior to running any SPI product. The Common Interface phases are distributed in a separate file on the SPI product tape that you received. Installation of the SPI Common Interface is described later in this document.

This publication is divided into several chapters. The items covered in these chapters are:

• Chapter 2 - Installation: This chapter describes the steps necessary to install the SPI Common Interface for VSE/ESA, VSE/SP, and MVT/VSE systems.
• Chapter 3 - SPI AR Commands: This chapter outlines the AR commands supported by the SPI Common Interface
• Chapter 4 - Expiration Control System: This chapter describes the use of the SPI license management and expiration control system.
• Chapter 5 - Subroutines and Utilities: This chapter describes the subroutines and utilities available for use by the customer.

This chapter describes the installation of the SPI Common Interface. The installation process is described separately for VSE/SP & VSE/ESA systems and MVT/VSE systems. To install the SPI Common Interface on your system please refer to the appropriate section of this chapter as indicated below:

• If you are running VSE/SP or VSE/ESA, please refer to " Installation on VSE/SP and VSE/ESA Systems" section in Chapter 2 - Installation for information in installing the Common Interface on your system.
• If you are running MVT/VSE, please refer to "Installation on MVT/VSE Systems" section in Chapter 2 - Installation for information on installing the Common Interface on MVT/VSE systems.

Installing the SPI Common Interface is a simple and straightforward process. The Common Interface is designed to be used on any VSE/SP or VSE/ESA operating system. The install process involves:

1. Restoring the Common Interface from the SPI product tape
2. Updating the ASI procedure for the BG partition to add the required SPI Common Interface phases to the SVA
3. Executing the Common Interface initialization program.

Before proceeding with the installation process, you need to decide in which VSE sub-library will be used for the install of the Common Interface components. The Common Interface components must be in the VSE library search chain at all times. It is not recommended to install the Common Interface components into IJSYSRS.SYSLIB. This is because you will loose the Common Interface phases and license information whenever you perform a VSE fast Service Upgrade

When the interface is activated, it attempts to hook directly into the necessary system routines. If other vendor products alter any of the system's new PSWs, it is possible that these direct interfaces cannot be used. The Common Interface will then use PSW swaps to implement its functions. Should any problems occur simply rearrange the startup order moving the troubled product initialization in front of the Common Interface startup. Messages will notify the operator if PSW swaps are being used by the Common Interface. The PSW swaps, however, will be delayed until actually needed.

It is recommended that the direct interface method be used.

PSW swapping must not be used on VSE/ESA systems at release 2.1 or above.

The use of PSW swaps in no way reduces the effectiveness of the Common Interface.

If you wish to force the Common Interface to use PSW swaps rather than its direct interface technique, specify:

UPSI xxxxxx1x

Before executing SPIIFACT to activate the Common Interface.

PSW swapping must not be used on VSE/ESA systems at release 2.1 or above.

When running the common interface on VSE/ESA version 2.1 and later, the common interface uses the VSE/ESA vendor exits provided by IBM.

In this environment, the common interface requires an additional 80K of system GETVIS space. This space may be in the 31-bit or 24-bit system GETVIS area.

Also available on VSE/ESA version 2.1, and later, is the ability to load the SPI Common Interface messages into the IBM Online Message Explanation file so that the operators may view message descriptions and suggested actions from the Operator console. A PROC, SPIMSGS, is supplied in the product distribution library to load the SPI messages into your OME file.

When running the SPRI spooling system, you should be using SPRI release 3.6 or higher when running SPI 4.2 or above on VSE/ESA systems that support 31 bit addressing.

Before proceeding you should be sure that you have a current SYSRES backup. If you do not have a current backup, you may use the following JCL to take a backup now:

* $$ JOB JNM=BACKUP,CLASS=0
// JOB BACKUP
// ASSGN SYS006,cuu      Output tape drive CUU
// MTC REW,SYS006
// MTC WTM,SYS006,5
// MTC REW,SYS006
// EXEC LIBR
BACKUP L=IJSYSRS                -
       TAPE=SYS006              -
       RESTORE=STANDALONE       -
       INCLUDE=HISTORYFILE
/*
/&
* $$ EOJ

This step creates the VSE libraries where the SPI Common Interface will reside. If you will be:

1. Using IJSYSRS.SYSLIB, or
2. A new sub-library of an existing library

for the installation, skip this step and go to Step 3: Mount the Installation Tape.

The SPI Common Interface will require 300 1K blocks.

The following JCL may be used to define the library:

// JOB DEFINE               DEFINE LIBRARIES FOR SPI PRODUCTS
// DLBL lib1,'....',99/366  DLBL information for library
// EXTENT ....              Extent information for library
// EXEC LIBR
DEFINE LIBRARY=lib1
/*
/&

Mount and ready the SPI installation tape. Please verify that the tape is Write Protected (read only).

The following JCL should be used for the installation of the SPI Common Interface.

// JOB PRODINST            INSTALL SPI TAPE ON VSE
// DLBL   lib1             DLBL information for library
// EXTENT ....             Extent information for library
// PAUSE *** ASSIGN SYS006 TO THE INPUT TAPE ***
// MTC REW,SYS006
// EXEC MSHP,SIZE=800K
INSTALL PRODUCT FROMTAPE ID='SPInn'  PROD INTO=lib1.sublib1  **
/*
// MTC RUN,SYS006
// SETPFIX LIMIT=32K                   *** For VSE/ESA ***
// LIBDEF *,SEARCH=lib1.sublib1
// EXEC PROC=SPIPRODC,LIBRARY='lib1.sublib1'
/&

** For installation in SYSRES, code: INTO=IJSYSRS.SYSLIB

Note: Please check this processing to be sure that the SPIPRODC procedure completes properly. This procedure performs a rename of phases and must complete properly for the SPI Common Interface to operate correctly.

If any SPI PTF's were included with this package, please apply the maintenance at this time. You may also call SPI Technical Support to confirm any new maintenance for this product.

Update your BG ASI procedure ($0JCLxxxx PROC) to load the required Common Interface phases in the SVA and activate the SPI Common Interface. Adding the SPIINIT procedure to your $0JCLxxxx PROC early in the initialization process does this. The following phases will be loaded into the SVA by the SPIINIT PROC:

• SPIIFSVA
• SPIDATE - 31 bit enabled
• SPIDATET
• SPISPARM - 31 bit enabled
• SPILBSVA

A sample portion of a BG ASI PROC is shown below for your reference:

CATALOG $0JCLSPI.PROC            DATA=YES REPLACE=YES    
STDOPT ACANCEL=NO,DECK=NO,DUMP=PART,SYSDMP=YES,SXREF=YES  
// EXEC PROC=STDLABEL                  LOAD LABEL AREA 
// EXEC PROC=SETSDL                    SET SDL         
   ...
   ...
ASSGN SYSLST,IGN                                          
// JOB BGINIT                                            
       < Insert the following lines >
// LIBDEF PHASE,SEARCH=lib.sublib      Sublibrary for SPI I/F
// SETPFIX LIMIT=32K                   *** For VSE/ESA ***
// EXEC PROC=SPIINIT                   Activate SPI Common I/F
       < End of inserted lines > 
 ...
 ...

Note: As stated in the OVERVIEW section of this document, the Common Interface components must be in the permanent VSE library search chain at all times for all partitions. This can be accomplished by updating your standard permanent LIBDEF procedure. This is typically the LIBDEF.PROC residing in IJSYSRS.SYSLIB.

If you use the single-phase $JOBEXIT routine, You may continue with the next step.

If you use the $JOBEXIT table for multiple Job Control exits, the SPI Common Interface requires dummy phase $JOBEX01 to be cataloged in IJSYSRS.SYSLIB and included in an SVA load list that is loaded during IPL. This is typically done in $SVA0000.PHASE. See IBM manual VSE/ESA Guide to System Functions under section Multiple Job Control Exit Routines for samples of how to code $JOBRXIT table, $JOBEXnn routines, and $SVA0000 load list.

In order for the updated BG ASI procedure to function properly, you must copy the SPIINIT procedure from the sub-library used for the installation of the SPI Common Interface to the IJSYSRS.SYSLIB sub-library. The LIBR JCL to perform this task follows:

* $$ JOB JNM=COPY,CLASS=0,DISP=D
// JOB COPY
// EXEC LIBR
CONN S=lib.sublib:IJSYSRS.SYSLIB
COPY SPIINIT.PROC R=Y
/*
/&
* $$ EOJ

You should now activate the SPI Common Interface. You may do this one of two ways:

1. IPL your system using the new $0JCLxxxx procedure (See Step 5. Update BG ASI PROC)
2. Run the following job stream in the BG partition:

   * $$ JOB JNM=SPIINIT,CLASS=0
   // JOB SPIINIT
   // SETPFIX LIMIT=32K               *** For VSE/ESA ***
   // LIBDEF *,SEARCH=lib.sublib
   // EXEC PROC=SPIINIT
   /&
   * $$ EOJ
   

Note: If attempt is made to activate the Common Interface after it is already active, the operator is notified that the interface is already active and normal operations continue.

You should now run the SPICPUID program to obtain the CPU serial number of the processor that you are currently running. You should save the output information obtained from SPICPUID to give to the SPI license coordinator so that an expiration update may be provided for your CPU.

The following shows a sample processing for SPICPUID. The processing is being done from the operator console.

1. Start a job using the BG partition:

   0 // job spicpuid
   

   The system will respond with:

   BG+// JOB SPICPUID
   BG DATE mm/dd/yy,CLOCK hh/mm/ss
   

2. Enter a LIBDEF command for the SPI distribution library:

   0 libdef phase,search=lib.sublib
   

   The system will respond with:

   BG+// LIBDEF PHASE,SEARCH=lib.sublib
   

3. Execute the SPICPUID program:

   0 exec spicpuid
   

   The system will respond with:

   BG+EXEC SPICPUID
   BG CPUID Version=nn,Serial=nnnnnn,Model=nnnn,MCEL=nnnn
   BG 1I00D  READY FOR COMMUNICATIONS.
   

   Note the items under: Version, Serial, Model, and MCEL. These are the items that should be provided to the SPI license coordinator.

   You may also take the console output from this run and FAX it to the SPI license coordinator.

4. Indicate that the job is complete:

   0 /&
   

   The system will respond with:

   BG+/&
   BG EOJ SPICPUID
   BG DATE mm/dd/yy,CLOCK hh/mm/ss,DURATION   nn/nn/nn
   

The installation of the SPI Common Interface is now complete.

If there are additional SPI products that are to be installed, you may proceed with these installations.

If you are running VSE/ESA version 2.1 or higher, you may (at your option) load the SPI messages & codes information into the VSE Online Message Explanation file. This affords console users the ability to display the message text and explanation straight from the console.

To load the SPI messages and codes into your OME file perform the following:

1. Start a job using the BG partition:

   0 // job spiomeld
   

   The system will respond with:

   BG+// JOB SPIOMELD
   BG DATE mm/dd/yy,CLOCK hh/mm/ss
   

2. Enter a LIBDEF command for the SPI distribution library:

   0 libdef phase,search=spidist.spinn
   

   The system will respond with:

   BG+// LIBDEF PHASE,SEARCH=SPIDST.SPInn
   

3. Execute the SPIMSGS PROC:

   0 exec proc=spimsgs
   

   The system will respond with:

   BG+EXEC PROC=SPIMSGS
   BG ...Messages from the SPIMSGS PROC
   

   Follow the instructions displayed on the console, when done:

4. Indicate that the job is complete:

   0 /&
   

   The system will respond with:

   BG+/&
   BG EOJ SPIOMELD
   BG DATE mm/dd/yy,CLOCK hh/mm/ss,DURATION   nn/nn/nn
   

The installation of the SPI Common Interface is now complete.

If there are additional SPI products that are to be installed, you may proceed with these installations.

When VSE/ESA Release 1.2 was released, IBM introduced a new feature of the Job Control exit. Beginning with this release, users are allowed to have multiple Job Control exits and may make changes and modifications to these exits "on the fly". This new capability creates a potential for the SPI Common Interface's JCL exit to become removed from the chain of Job Exits.

If you suspect a Job exit problem, or if you see message SPI141W enter the following command in the BG partition:

JCLEXIT SPI

This is an extension SPI has added to the VSE/ESA JCLEXIT JCL statement.

Note: The JCLEXIT SPI statement should only be issued when the VSE JOB Control exits are enabled.

1. If an invalid statement message is issued from JOB Control, the SPI JCL exit has become disabled. The SPI JCL exit may be re-enabled with the following SPI AR command:

   SPI JCLEXIT=RELOAD
   

   This will cause the SPI JCL exit to be placed back on the JCL exit chain.

   After a:

   JCLEXIT DISABLE,...
   

   command has been issued the SPI JCL exit will not receive control until a:

   JCLEXIT ENABLE,...
   

   command has been issued.

   For more information on multiple job exits, refer to the IBM VSE/ESA System Control Statements or Release Guide for your release of VSE/ESA.

2. If message SPI142I is displayed, then the SPI JCL exit is still in the chain of JCL exits and no additional actions are needed.

Installing the SPI Common Interface is a simple and straightforward process. The J.SPIINSTL procedure is used for the installation. This automates many of the installation steps.

The Common Interface will run on MVT/VSE Releases 9.3 and higher. If you are not running MVT/VSE Release 9.5 or higher, contact Software Pursuits Technical Support for information on upgrading your MVT/VSE system.

Mount and ready the SPI installation tape. Please verify that the tape is write protected (read only).

Note: The first file of the SPI product tape for MVT/VSE systems contains the SPIINSTL procedure. This procedure is used to perform all of the necessary steps required to install the SPI Common Interface. You should always catalog the SPIINSTL procedure from the tape that you are using for the installation. This is important because changes to the procedure are made from time to time and the procedure must know the format of the product tape in order to function properly.

The following is an example of the procedure used to catalog the SPIINSTL procedure:

1. Start a region:

   start r2
   

2. When the region is ready, assign the input tape to SYSIN:

   r2 assgn sysin,cuu
   

3. When the region responds with a read

   R2
   

   Press the ENTER key and the catalog process will begin. The system will respond with:

   R2 *  SPI PRODUCT TAPE
   R2 *  ENTER A JOB STATEMENT VALID FOR YOUR INSTALLATION
   R2 // PAUSE ** ENTER A JOB CARD.
   

4. Enter a JOB statement:

   r2 // job catals
   

   The system will respond with:

   R2  --JOB-- nnnn -- CATALS   -- mm/dd/yy hh.mm.ss
   R2  // OPTION LOG
   R2  *  ****  THE NEXT STEP IS MAINT WHICH WILL
   R2  *        CATALOG BOOKS TO YOUR SOURCE STATEMENT LIBRARY
   R2  // ASSGN SYSSLB,UA    OR LIBDEF SL,TO=IJSYSRS
   R2  *  ****  IF YOU DO NOT WISH TO USE SYSTEM LIBRARIES,
   R2  *        ENTER ASSGNS FOR SYSSLB/SYSRLB
   R2  *        AND DLBL'S FOR IJSYSRL AND IJSYSSL
   R2  *        OR ENTER LIBDEF COMMANDS.
   R2  // PAUSE - TO ENTER ASSGNS, LABELS, AND/OR LIBDEF STATEMENTS
   

5. Press the ENTER key to use the system libraries. When the catalog procedure is complete, the SPIINSTL procedure is ready to use.

After the SPIINSTL procedure has been cataloged, you should run the newly cataloged procedure. This procedure will allow you to backup your system before starting the install process. The following is an example of this installation:

1. Mount a scratch tape on a free drive. This tape will be used for the backup process when the SPIINSTL procedure is run. The tape should be enabled for writing.

   Note: The drive used for the backup process will also be used, after the backup, for the SPI product tape.

2. Start a Region:

   start R2
   

   All of the following examples will show R2 as the processing region.

3. Start the SPIINSTL procedure by entering:

   r2 // proc i.spiinstl
   

   The system will respond with:

   R2 SPIINSTL(n.n) PROCEDURE TO ASSIST IN THE
   R2 INSTALLATION OF PRODUCTS DISTRIBUTED IN MSHP FORMAT.
   R2 EACH USE OF THIS PROCEDURE WILL INSTALL A SINGLE
   R2 SOFTWARE PURSUITS PRODUCT.
   R2 Copyright © yyyy-yyyy BY SOFTWARE PURSUITS, INC.
   R2 -----------------------------------------------------
   R2 YOU ARE OPERATING UNDER MVT/VSE RELEASE n.n
   R2 YOU MAY ABORT THIS PROCEDURE AT ANY TIME BY ENTERING
   R2 "HX" OR "ABORT" AS A REPLY TO ANY PROMPT. 
   R2 -----------------------------------------------------
   R2 PLEASE ENTER THE DATE CODE FROM THE SPI PRODUCT TAPE YYMMDD
   R2 PLF-
   

4. Enter the date code as printed on the label of the product tape. The date format is:

   r2 yymmdd
   

   The system will respond with:

   R2 =====================================================
   R2 -----------------------------------------------------
   R2 VALID PRODUCT NAMES TO INSTALL: 
   R2 OTHER    - YOU WILL BE PROMPTED FOR INFORMATION
   R2 .          TO ALLOW AN INSTALL OF ANY SYSTEM IN
   R2 .          SPI DISTRIBUTION TAPE FORMAT.
   R2 SPRIPREP - RESTORES SPRI SOURCE LIBRARY FOR
   R2 .          INSTALLATION PLANNING ONLY.
   R2 MVT93PREP- RESTORES MVT 9.3 LIBRARIES FOR
   R2 .          INSTALLATION PLANNING ONLY.
   R2 SPI      - SPI COMMON INTERFACE.  REQUIRED BY
   R2 .          ALL PRODUCTS ON THIS TAPE. 
   R2 PLF      - PROCEDURE LANGUAGE FACILITY. 
   R2 .          PERMITS USE OF EXEC=DISKJCL TO RUN THIS
   R2 .          INSTALLATION PROCEDURE. 
   R2 SPRI     - SPRI SPOOLING SYSTEM.  INCLUDES
   R2 .          RJE AND SPRI/EXPRESS. 
   R2 QVIEW    - ONLINE REPORT VIEWING AND PRINTING. 
   R2 MVT93    - MVT/VSE 9.3 PROGRAM UPDATE LIBRARIES. 
   R2 .          YOU MUST ALREADY BE RUNNING MVT/VSE
   R2 .          RELEASE 9 TO USE THIS SELECTION. 
   R2 SOFTWARE PURSUITS PRODUCTS MUST BE INSTALLED IN THE
   R2 SEQUENCE LISTED ABOVE. 
   R2 ENTER THE NAME OF THE PRODUCT YOU WISH TO INSTALL. 
   R2 PLF-
   

5. Indicate that the SPI Common Interface is to be loaded by entering:

   r2 spi
   

   The system will respond with

   R2 IF YOU ARE PERFORMING A RESTART OF THE INSTALL, 
   R2 ENTER THE RESTART POINT: BACKUP, RESTORE, DELETE, 
   R2 CONDENSE, CORGZ, CORGZR, CORGZS, HISTORY, 
   R2 OR WRITEIPL. 
   R2 PRESS ENTER TO BEGIN WITH BACKUP
   R2 PLF-
   

6. Reply to the region with a null reply to indicate that the backup should be started

   r2 <ENTER>
   

   The system will respond with:

   R2 ENTER CUU LOCATION OF OUTPUT TAPE. 
   R2+PLF-
   

7. Enter the address of the scratch tape. The backup process will use this tape. The tape should be saved for at least seven days.

   r2 tcuu
   

   The system will respond with:

   R2 PRESS ENTER TO VERIFY WORK DISK AS type DISK, 
   R2 OR ENTER ANYTHING ELSE FOR A DEVICE PROMPT.
   R22PLF-
   

8. Enter a null reply to the region to verify that the device type shown is correct:

   r2 <ENTER>
   

   The system will respond with:

   R2 -----------------------------------------------------
   R2 *****************************************************
   R2 * WARNING *** WARNING *** WARNING ***
   R2 *****************************************************  
   R2 * THE SPI (n.n) CORE-IMAGE LIBRARY
   R2 * WILL BE MERGED TO SYSRES BY THIS JOB.
   R2 *****************************************************
   R2 DO YOU WANT THE SPI (n.n) RELOCATABLE LIBRARY
   R2 MERGED INTO SYSRES?  REPLY Y OR N.
   R22PLF-
   

9. Reply:

   r2 y
   

   The system will respond with:

   R2 DO YOU WANT TO DELETE THE OLD VERSIONS OF THE
   R2 RELOCATABLE MODULES TO BE COPIED TO SYSRES AND
   R2 PERFORM A CONDENSE TO ENSURE ROOM FOR THE MERGE? 
   R2 nn LIBRARY BLOCKS WILL BE REQUIRED. 
   R2 REPLY WITH Y OR N. 
   R22PLF-
   

10. Reply:

    r2 n
    

    The system will respond with:

    R2 DO YOU WANT THE SPI (n.n) SOURCE LIBRARY
    R2 MERGED INTO SYSRES?  REPLY Y OR N. 
    R22PLF-
    

11. Reply:

    r2 y
    

    The system will respond with:

    R2 DO YOU WANT TO DELETE THE OLD VERSIONS OF THE
    R2 SOURCE BOOKS TO BE COPIED TO SYSRES AND
    R2 PERFORM A CONDENSE TO ENSURE ROOM FOR THE MERGE? 
    R2 nnnn LIBRARY BLOCKS WILL BE REQUIRED. 
    R2 REPLY WITH Y OR N.
    R22PLF-
    

12. Reply:

    r2 n
    

    The system will respond with:

    R2 --------------------------------------------------
    R2 ENTER THE DATA SET NAME OF YOUR SYSRES SO THE
    R2 SYSTEM HISTORY FILE CAN REFLECT THE LOCATION OF
    R2 COMPONENTS MERGED TO SYSRES. 
    R2 PRESS ENTER TO ACCEPT THE NAME: 
    R2   MVT/VSE.SYSRES.FILE
    R22PLF-
    

13. Enter a null reply to accept the default:

    r2 <ENTER>
    

    The system will respond with:

    R2 ---------------------------------------------
    R2 nnn TRACKS OF CYLINDER ALIGNED WORK SPACE
    R2 ARE NEEDED FOR LIBRARIES AND HISTORY FILE. 
    R2 ---------------------------------------------
    R2 ENTER WORK DISK CUU ADDRESS. 
    R22PLF-
    

14. Enter the address of the DASD to be used for the work disk:

    r2 dcuu
    

    The system will respond with:

    R2 ENTER STARTING TRACK OR FBA BLOCK FOR WORK AREA. 
    R2 PLF-
    

15. Enter the starting track/block address to be used for the work area:

    r2 nnnn
    

    The prompting process for SPIINSTL is now complete.

After the SPIINSTL procedure has completed the prompting process, it will submit a job stream to perform all of the necessary backup and installation steps. An example of this is shown below:

1. All replies have been completed and the batch job is submitted. The system will display:

   R2 --JOB-- nnnn -- SPIINSTL -- mm/dd/yy hh.mm.ss
   R2 * --------------------------------------------------------------
   R2 * INSTALLING SPI (n.n)
   R2 *
   R2 * THE INSTALLATION CONSISTS OF THE FOLLOWING STEPS:
   R2 *
   R2 * 1 - THE BACKUP OF THE CURRENT SYSRES TO TAPE
   R2 * 2 - THE MSHP RESTORE OF THE LIBRARIES AND HISTORY FILE
   R2 *     TO A WORK AREA.
   R2 * 3 - THE MAINT DELETION OF OBSOLETE COMPONENTS AND AN OPTIONAL
   R2 *     CONDENSE OF SYSRES, IF LIBRARIES WILL BE MERGED TO SYSRES.
   R2 * 5 - THE CORGZ COPYING OF NEW AND CHANGED COMPONENTS
   R2 *     TO SYSRES
   R2 * 4 - THE MSHP UPDATING OF THE SYSTEM HISTORY FILE
   R2 *
   R2 * PLEASE MAKE SURE YOU UNDERSTAND THE INSTALLATION PROCESS
   R2 * BEFORE YOU BEGIN.  IF YOUR LIBRARIES FILL ON SYSRES DURING THE
   R2 * INSTALL YOU MAY BE LEFT WITH AN UNUSABLE SYSTEM AND NEED TO
   R2 * RESTORE SYSRES.  THIS IS WHY A SYSRES BACKUP IS PERFORMED BY
   R2 * THIS JOB.
   R2 * ------------------------------------------------------------
   R2 * SYSSLB AND SYSRLB MUST NOT BE PERMANENTLY ASSIGNED
   R2 * OR THE LIBDEF STATEMENTS IN THIS PROCEDURE WILL
   R2 * CAUSE THE JOB TO CANCEL.  IF THEY ARE PERMANENTLY
   R2 * ASSIGNED, ENTER "ASSGN SYSSLB,UA" AND "ASSGN SYSRLB,UA"
   R2 * AT THE PAUSE BELOW, THEN RESTORE YOUR ASSIGNMENTS
   R2 * AFTER ALL PRODUCT INSTALLATIONS ARE COMPLETE.
   R2 * --------------------------------------------------
   R2 * --------------------------------------------------
   R2 * BACKUP SYSRES LIBRARIES AND HISTORY FILE.
   R2 * YOU WILL BE ABLE TO IPL THIS BACKUP TAPE TO RESTORE
   R2 * YOUR SYSRES LATER, IF NECESSARY.
   R2 * SCRATCH TAPE SHOULD BE ON SYS006=tcuu
   R2 * --------------------------------------------------
   R2 // PAUSE - VERIFY SCRATCH TAPE ON SYS006=tcuu FOR BACKUP
   R2+
   

2. Enter a null reply to verify the backup tape address:

   r2 <ENTER>
   

   The system will then respond with:

   R2    SA,NOSORT
   R2         nnnnnnnn
   R2 8B02I  BACKUP OF SC LIBRARY IN PROGRESS
   R2 8B03I  LIBRARY HAS BEEN DUMPED
   R2 8B02I  BACKUP OF SR LIBRARY IN PROGRESS
   R2 8B03I  LIBRARY HAS BEEN DUMPED
   R2 8B02I  BACKUP OF SS LIBRARY IN PROGRESS
   R2 8B03I  LIBRARY HAS BEEN DUMPED
   R2 8B02I  BACKUP OF SP LIBRARY IN PROGRESS
   R2 8B03I  LIBRARY HAS BEEN DUMPED
   R2 8B04I  BACKUP COMPLETE, HISTORY FILE DUMP IN PROGRESS
   R2 * REMOVE BACKUP TAPE FROM tcuu AND SAVE
   R2 * --------------------------------------------------
   R2 * PRODUCT TAPE SHOULD BE ON tcuu
   R2 * RESTORES TO BE MADE TO A type DISK ON dcuu
   R2 * USING WORK EXTENT OF nnnn,nnn
   R2 * --------------------------------------------------
   R2 // PAUSE *** VERIFY INPUT TAPE ON SYS006=tcuu ***
   R2
   

3. Remove the tape used for the backup. The tape should be saved for a minimum of seven (7) days. This tape ensures that a restart point for your SYSRES is available in the event of problems.

   Mount the SPI product tape on the drive. When the tape is loaded and ready, enter a null reply to start:

   r2 <ENTER>
   

   The system will respond with:

   R2 * RESTORING SPI (n.n) LIBRARIES AND HISTORY FILE
   R2  ALLOC PC=nnnnnnnnnn(nnnnnnnnnn),
   R2        X
   R2        PR=nnnnnnnnnn(nnnnnnnnnn),
   R2        X
   R2        PS=nnnnnnnnnn(nnnnnnnnnn)
   R2 4433D EQUAL FILE ID IN VTOC IJSYSCL SYS007=dcuu volid
   R2  SPI.COMMON.n.n.SYSCLB.FILE
   

4. Reply:

   r2 delete.
   

   The system will then respond with:

   R2 8R35I  RESTORE OF PC LIBRARY IN PROGRESS
   R2 8R36I  RESTORE HAS BEEN SUCCESSFUL
   R2 4433D EQUAL FILE ID IN VTOC IJSYSRL SYS008=dcuu volid
   R2  SPI.COMMON.n.n.SYSRLB.FILE
   

5. Reply:

   r2 delete
   

   The system will then respond with:

   R2 8R35I  RESTORE OF PR LIBRARY IN PROGRESS
   R2 8R36I  RESTORE HAS BEEN SUCCESSFUL
   R2 4433D EQUAL FILE ID IN VTOC IJSYSSL SYS009=dcuu volid
   R2  SPI.COMMON.n.n.SYSSLB.FILE
   

6. Reply:

   r2 delete
   

   The system will then respond with:

   R2 8R35I  RESTORE OF PS LIBRARY IN PROGRESS
   R2 8R36I  RESTORE HAS BEEN SUCCESSFUL
   R2 8R38I  ***  RESTORE COMPLETE  ***
   R2 * -----------------------------------------------------------
   R2 * UPDATING SYSTEM HISTORY FILE TO REMOVE ANY PRIOR VERSION
   R2 * OF THIS PRODUCT.
   R2 M102I SPECIFIED COMPONENT RELEASE NOT ON SYSTEM
   R2 * DELETING OBSOLETE SPI COMPONENTS FROM SYSRES
   R2 * -----------------------------------------------------------
   R2 * MERGING SPI (n.n) LIBRARIES TO SYSRES
   R2 * -----------------------------------------------------------
   R2 * UPDATING SYSTEM HISTORY FILE TO INDICATE THE NEW LOCATION  
   R2 * OF COMPONENTS MERGED TO SYSRES.
   R2 SPIEXPIR n.n nnnnnnnn
   R2 // PAUSE  APPLY ANY OPTIONAL APARS AT THIS TIME
   R2-
   R2 * ----------------------------------------------------------
   R2 *  PRODUCT INSTALLATION COMPLETE
   

   The application of the SPI Common Interface is now complete.

The installation of the SPI Common Interface is now complete. You must re-IPL your system to activate the new version of the Common Interface. After the system is re-IPLed, you may continue with the installation of any additional SPI products.

The SPI Common Interface has several AR commands that aid in problem determination and resolution. The SPI Common Interface must be active for these AR command to be used.

The format of the Common Interface AR commands is:

SPI command
command    [? | HELP]    APARS    JCLEXIT=RELOAD    STATUS	Display valid commands    Display current APAR level    Reload the SPI JCL exit    Display current status

? | HELP	Displays a list of valid SPI AR commands.
APARS	Displays the current APAR level of the SPI Common Interface. This is an easy way to determine what APARs have been applied to the SPI Common Interface.
JCLEXIT=RELOAD	This applies to VSE/ESA Release 1.2 (or later) systems only. It reloads the SPI JCL exit after a new $JOBEXIT program has been loaded into the SVA. Extreme care must be exercised when using this command. See "JCL Exit Considerations" for more information on the use of this command.
STATUS	This command displays the current status of the SPI Common Interface.

Note: An asterisk (*) at the end of message SPI209W, when PSW SWAPS are in use, indicates that the SPI PSW first level interrupt handler is first in line.

To request a display of the current APAR level of the SPI Common Interface, enter the following to AR:

spi status

The system will then respond with:

AR SPI135I SPI installed at level: 4.3.nnn 
AR SPI139I Request complete

To request a display of the current status of the SPI Common Interface you would enter the following to AR:

spi status

The system will then respond with:

AR SPI130I SPI Common Interface status:                 
AR SPI131I SPI Release: r.l.ptf                         
AR SPI132I Operating system is: VSE/AF  Release: v.r.l 
AR SPI138I Operating mode is: ESA-MODE                  
AR SPI134I R.IFDCT=X'nnnnnnnn' V.IFDCT=X'nnnnnnnn'      
AR SPI307I SPI$ESAX loaded at X'nnnnnnnn'.              
AR SPI308I SPI Savearea is at X'nnnnnnnn'.              
AR SPI309I SPISPARM loaded at X'nnnnnnnn'.              
AR SPI310I SPIDATE  loaded at X'nnnnnnnn'.              
AR SPI311I SPILBSVA loaded at X'nnnnnnnn'.              
AR SPI312I DOCSMAIN loaded at X'nnnnnnnn'.              
AR SPI313I SPRI CAT loaded at X'nnnnnnnn'.              
AR SPI314I SPIPLFRT loaded at X'nnnnnnnn'.              
AR SPI129I SPI JCLEXIT is on                            
AR SPI139I Request complete

The Software Pursuits Product Expiration Control System was developed to prevent unlicensed use of software products developed by Software Pursuits. Products must be licensed for specific CPUs, although the system permits temporary use on backup or new machines.

S ome of the features and peculiarities of the expiration system include:

1. Expiration updates may be applied quickly without the need to install any new release or APARs. A customized printout of directions is prepared for each customer.
2. A single expiration date, which affects all Software Pursuits products, is used.
3. CPU serial numbers are verified.
4. Each CPU may be licensed for different products.
5. New products may be added to the expiration system as they are developed. This system is expected to control all future product releases.
6. A product will function on an unlicensed CPU up to a maximum of 25 different days. This permits a customer to use an alternate site after failure of the licensed CPU, permits testing, and allows the user to install a new CPU without having to first obtain a new expiration update.
7. Users of VM/ESA release 2 and higher have no special VM requirements. Users of VM that are running releases earlier than VM/ESA 2 (This includes all users of VM/SP, VM/HPO, VM/XA, VM/ESA 370 feature, and all VM/ESA releases prior to release 2) must have the guest machine where any SPI product is to run authorized for VM class C or E privilege. If it does not, the real CPU serial number cannot be checked and the CPU is treated as unlicensed.

The SPIEXPIR program is used to update the expiration date of all Software Pursuits products and may add CPU and product license information.

Input to SPIEXPIR consists of an UPDATE statement (required), a NEWCUST statement (optional), an OVERRIDE statement (optional), and one CPU statement per CPU (optional). Control statements include check digits to insure that information is not mis-miskeyed> If the EXEC statement is read on SYSRDR, control statements are processed from SYSIPT, otherwise the console operator is prompted to enter the control statements from the console. A null response terminates the console input.

Messages are output on the console to indicate the action performed by the SPIEXPIR program. If there are any errors in the control statements, no updating is performed.

Please note that if:

1. Your system is expired, or
2. Has exhausted its unlicensed usage.

It will be necessary to execute SPIEXPIR before the needed product is first used. For the MVT/VSE operating system, it is necessary to execute the SPIEXPIR program before the first JOB statement is processed.

It is necessary to run SPIEXPIR only once on each SYSRES volume used on each CPU. When SYSRES is shared between CPUs, the new expiration date will not be recognized on other CPUs until the products affected are terminated and reactivated or until 24 hours has passed.

The expiration system is distributed as part of the SPI Common Interface and some phases are updated by the expiration system. If duplicate copies of the Common Interface library exists you must apply expiration updates to each library.

You can check on your licensing and expiration status at any time by simply executing SPIEXPIR without any control statements.

1. VM/ESA Version 1 or later: No special requirements.
2. VM/SP, VM/SP-HPO, and VM/ESA-370 Feature (all releases), and VM/ESA Release 1: The guest machine using any SPI product must be authorized for VM class C or E. This is specified on the USER statement of the VM directory. If this is not done, the real CPU serial number (CPUID) cannot be checked and the CPU is treated as unlicensed.

Expiration updates are provided in written form to each Software Pursuits customer and should be entered exactly as provided on the document. Expiration updates may be sent to the customer via regular mail or by Fax. Expiration updates may also be obtained from the Software Pursuits bulletin board. If you would like to use the SPI bulletin board but have no userid and password, contact SPI technical support for information on obtaining a userid and password.

Since your instructions for applying an expiration update will always be customized for you, this section is merely to help explain the customized information that has been provided.

Control statements follow standard Software Pursuits coding conventions. Command and keyword abbreviations are allowed along with continuations. The command name can begin in any column. Statements which start with an asterisk (*) are treated as comments.

STATEMENT	USE
CPU	Add, replace or delete a CPU
NEWCUST	Change a customer number or name
OVERRIDE	Force acceptance of an UPDATE or CPU statement
UPDATE	Expiration date update

This control statement is needed when adding, replacing or deleting a CPU. If your system was previously configured for all of your CPUs, this statement will not be required. If an expiration update provided by SPI contains this statement you must enter it exactly as provided.

The format of the SPIRXPIR CPU control statement is:

Cpu Serial=(xx-yyyyyy-zzzz)[,Prodmask=(val1,...val5)[,Replace=xx-yyyyyy-zzzz]]
Serial=xx-yyyyyy-zzzz Prodmask=(...) Replace=xx-yyyyyy-zzzz	CPU serial number A sequence of 5 numeric values Serial number replacement

Prodmask=(...)	This operand specifies a sequence of 5 decimal numbers enclosed in parentheses and separated with commas. The numbers contain embedded check digits to protect against mis-miskeyingthe information. The numbers also decode a lengthy bit mask used to identify licensed products. The size of this operand reflects the large number of products supported by the expiration system.
Replace=	This operand is only used when one CPU serial number is going to replace a different serial number. The serial number should be coded in the format: xx-yyyyyy-zzzz The start of the serial number, "xx", cannot be "FF", since this would indicate a VM "virtual" serial number, not the true CPU serial number. The first digit of "yyyyyy" will be ignored when actually testing the serial number (to support multi-processor configurations), however you must code the digits exactly as provided by Software Pursuits.
Serial=	This operand is required to specify the CPU serial number being added. The serial number should be coded in the format: xx-yyyyyy-zzzz The start of the serial number, "xx", cannot be "FF", since this would indicate a VM "virtual" serial number, not the true CPU serial number. The first digit of "yyyyyy" will be ignored when configurations), however you must code the digits exactly as provided by Software Pursuits.

Use this statement to change your SPI Customer Number or your company name. This is normally only required at install time. If the customer number is to be changed, a valid OVERRIDE statement is required. If only the customer name is to be changed, no override is required. The initial distribution system does not require an OVERRIDE statement when first installed at a customer site.

If present, the NEWCUST statement:

• Must precede the UPDATE statement and
• Follow any OVERRIDE statement.

The format of the SPIEXPIR NEWCUST control statement is:

Newcust Account=cust-number[,Name='cust-name']
Account= Name=	SPI customer number Customer name

Account=	This operand is required to indicate the SPI Customer Number.
Name=	This operand is required to indicate your company name. If your company name includes any special characters or has more than one word, be sure to place the name within single quote marks.

An OVERRIDE statement is not normally required. When an OVERRIDE statement is required, the SPI expiration coordinator will provide it.

The OVERRIDE statement is required when the customer number needs to be changed or to force the acceptance of an UPDATE or CPU statement.

The password varies daily and is only valid for one day. In addition, any given customer may only use a given OVERRIDE password once on that day. If it is necessary to do an additional update on the same day (after a successful update), a new OVERRIDE password must be used which is the next one for that date.

The OVERRIDE statement is not necessary when changing the customer number if the old customer number was 00001 (as on the distribution system).

If the OVERRIDE statement is used, it must be the first statement input.

The format of the SPIEXPIR OVERRIDE control statement is:

Override password
password	16 character override password (Hex digits)

password

This is a 16 character password, which must be coded without any blanks or punctuation. The characters are actually hexadecimal digits; each character must be in the rage of 0 to 9, or A to F. The password varies daily and is only valid for one day. In addition, any given customer may only use a given OVERRIDE password once on that day. If it is necessary to do an additional update on the same day (after a successful update), a new OVERRIDE password must be used which is the next one for that date.

An UPDATE statement is required if the expiration date is to be updated.

The format of the SPIEXPIR UPDATE control statement is:

Update DATE=yyyy/mm/dd,Passwords=(pword1,pword2)
Date=yyyy/mm/dd Passwords=(...)	Indicate expiration date Two numeric passwords

Date=	Specify the expiration date in the format "yyyy/mm/dd" or "yyyy-mm-dd", where "yyyy" is the expiration year, "mm" is the month number, and "dd" is the day number within the month.
Password=(...)	Specify two numeric passwords within parentheses and separated by a comma. The passwords contain encoded check digits to protect against miskeying of any value on the UPDATE statement.

The following is an example of the JCL used for SPIEXPIR processing. The statements could be entered from the console or a reader. Statements and messages are always listed on SYSLST. If SPIEXPIR is executed from the console, all messages will also appear on SYSLOG.

Please note that in the example below the OVERRIDE statement is shown for completeness only. The OVERRIDE statement is not required under normal circumstances.

// JOB SPIEXPIR
// EXEC SPIEXPIR
OVERRIDE 0123456789ABCDEF
NEWCUST  ACCOUNT=12345,NAME='ABC COMPANY'
UPDATE   DATE=1994/02/07,PASS=(12345,67890)
CPU      SERIAL=00-111111-2222,PROD=(1111,22222,3333,44444,55555)
CPU      SERIAL=33-444444-5555,PROD=(6666,77777,8888,99999,11111),
         REPLACE=66-777777-8888
/*
/&

Distributed with the Common Interface are several utility programs and subroutines. This chapter contains description and use information regarding these utilities and subroutines.

SPIZAPCK is a batch program used for determining which PTFs have been applied to different Software Pursuits products. In addition to the batch program, internal calls are used by systems To map a PTF history within storage dumps that might occur for a product. This information is useful when diagnosing new problems reported by a user.

The SPIZAPCK program requires no special JCL or partition size. It is executed by:

1. Starting a Region/Partition
2. Executing the SPIZAPCK program as follows:

   // EXEC SPIZAPCK
   

If you are executing SPI products out of private libraries instead of SYSRES, make sure all the SPI product libraries are available by the SPIZAPCK program. Use a LIBDEF PHASE or LIBDEF CL statement.

The default is to display summary information (i.e., product, library, install level, highest APAR applied and number of APARS not applied below the highest). Additional displays are controlled via the use of UPSI switches. The UPSI switches allowed are:

UPSI	USE
1xxxxxxx	Display information in mixed case
x1xxxxxx	Suppress SYSLOG display
xx1xxxxx	Suppress SYSRES inspection
xxx1xxxx	Display ZAP detail

This program is used to determine the version number, serial number, and model number of a processor. This program requires no JCL or control statements. When executed its types out a single line on the console. The information printed out is required by the expiration control system. Customers should execute this program and relay the information to Software Pursuits.

1. VM/ESA Release 2: No special requirements.
2. VM/SP, VM/SP-HPO, and VM/ESA-370 Feature (all releases), and VM/ESA Release 1: The guest machine using any SPI product must be authorized for VM class C or E. This is specified on the USER statement of the VM directory. If this is not done, the real CPU serial number (CPUID) cannot be checked and the CPU is treated as unlicensed

The following is an example of executing SPICPUID when keyed in from the operator's console:

1. Start a job in the BG partition:

   // job spicpuid
   

   The system will respond with:

   BG // JOB SPICPUID
   BG DATE mm/dd/yy,CLOCK hh/mm/ss
   

2. Enter the LIBDEF command to define the search criteria:

   // libdef phase,search=lib.sublib
   

   The system will respond with:

   BG+// LIBDEF PHASE,SEARCH=lib.sublib
   

3. Execute the SPICPUID program:

   exec spicpuid
   

   The system will respond with:

   BG+// EXEC SPICPUID
   BG CPUID Version=nn,Serial=ssssss,Model=mmmm,MCEL=nnnn
   BG 1I00D  READY FOR COMMUNICATIONS.                  
   

4. Enter a /& to indicate that the job is complete. The system will respond with:

   BG+/&                                                
   BG EOJ SPICPUID                                      
   BG DATE mm/dd/yy,CLOCK hh/mm/ss,DURATION   nn/nn/nn
   

The SPIEXPRT program is used to help solve expire problems. It should only be used at the request of Software Pursuits Technical support.

IMPROPER USE MAY CAUSE EXPIRATION PROBLEMS!

This control statement is used to specify various processing options for the SPIEXPRT utility

The format of the SPIRXPRT OPTION control statement is:

Option [Case={Mixed | Upper}[,Dumpccb={No|Yes} ]]
Case={Mixed|Upper} Dumpccb={No|Yes}	Indicates output should be mixed case or all uppercase Yes specifies that a storage dump of the expire control block is desired

This control statement is used to specify what part of the expire system is to be tested.

The format of the SPIRXPRT TEST control statement is:

Test Product=(prod,prod,...,prod),[Date=mm/dd/yy]
Test Product= Date=mm/dd/yy	Specifies the SPI products to be tested Date to be tested (optional)

The following is an example of executing SPIEXPRT when keyed in from the operator's console:

1. Start a job in the BG partition:

   // job spiexprt
   

   The system will respond with:

   BG // JOB SPIEXPRT
   BG DATE mm/dd/yy,CLOCK hh/mm/ss
   

2. 2Enter the LIBDEF command to define the search criteria:

   // libdef phase,search=lib.sublib
   

   The system will respond with:

   BG+// LIBDEF PHASE,SEARCH=lib.sublib
   

3. Execute the SPIEXPRT program:

   exec spiexprt
   

   The system will respond with:

   BG+// EXEC SPIEXPRT
   BG SPIEXPRT Enter Control Statement
   BG
   BG 1I00D  READY FOR COMMUNICATIONS.                  
   

4. Enter a /& to indicate that the job is complete. The system will respond with:

   BG+/&                                                
   BG EOJ SPIEXPRT                                      
   BG DATE mm/dd/yy,CLOCK hh/mm/ss,DURATION   nn/nn/nn
   

   The output will be printed on SYSLST.

SPIDATE is a subroutine designed to operate out of the SVA and perform calculations and conversions related to dates. The address of SPIDATE is normally obtained via a CDLOAD or LOAD macro. The SPI Common Interface Requires SPIDATE to be in the SVA. Various SPI products also use SPIDATE for date conversions.

One, two, or three arguments may be passed to SPIDATE, each operand defined with the SPIDATEP macro. The first two arguments are used to provide input dates and/or times or intervals for processing. The third operand represents an output value only. Since a conversion is performed on the two inputs, sometimes only one input value is needed or the output parameter is not needed.

Currently (SPI 4.3), only date conversions are supported and calendar date intervals can be calculated.

A Date Definition Phase is used to define holidays and spellings for dates. The start of the phase is defined with the SPIDATEP macro. A model phase, used as a default, is called SPIDATET.

SPIDATEP op1[,...,opn]

DEFN=    DSECT=       NO       YES IN1=    DSECT=       NO       YES IN2=    DSECT=       NO       YES OUT=    DSECT=       NO       YES PREFIX=

Date definition phase    Generate a DSECT of phase start       Default, Ignore this section       Generate date definition phase header First SPIUPDATE operand    Generate a DSECT       Ignore this section       Default, Generate an inline control block Second SPIUPDATE operand    Generate a DSECT       Ignore this section       Default, Generate an inline control block SPIDATE output operand    Generate a DSECT       Ignore this section       Default, Generate an inline control block Three character label prefix