How to Install Spectrum Writer OS/390

Description

At this point you have downloaded the 30-day trial version of Spectrum Writer from the Web. This document explains what to do next to complete the installation of Spectrum Writer OS/390 on your mainframe. It also explains how to license Spectrum Writer during your 30-day trial period so you can keep right on enjoying it without any interruption.

Overview

To install Spectrum Writer and run it on your mainframe, you will perform the following steps:
  1. Upload the object code to your mainframe.
  2. Link-edit the object code on your mainframe
  3. Perform some DB2 setup (Optional)
  4. Set up a Spectrum Writer Copy Library containing file definitions (of your non-DB2 files)
  5. Execute Spectrum Writer
Each of these steps is discussed in detail in the following sections.

Step 1. Upload Object Code to the Mainframe.

Upload the following files from your PC to your OS/390 mainframe.

SWMVS300.OBJ (required, this is the main object code file)
SWDB2300.OBJ (optional, this is the object code for the DB2 option)
DBRM300A.BIN and DBRM300B.BIN (optional, these are the DBRM modules needed for the DB2 "bind")

Use the file transfer function of your PC's 3270 terminal emulator software, or any other method that you like. Be sure to perform a binary (not ASCII) upload. Upload the files into members of a pre-allocated, 80-byte PDS on your mainframe. Name the members SWMVS300, SWDB2300, DBRM300A and DBRM300B.

When correctly uploaded to your OS/390 mainframe, the SWMVS300 member will contain roughly 5500 object code records similar in format to (but not necessarily identical to) these sample object code records:

....5...10...15...20...25...30...35...40...45...50...55...60...65...70...75...80
ESD            SWINIT         .íPROCCC           PRTERRDT               SWINIT01
ESD            PRTCHAIN         SORTIN2          SORTIN                 SWINIT02
ESD            SORTOUT  @       OSUTIL2          OSUTIL                 SWINIT03
ESD            SWFLOAT          TRTNUMOK         TRTPK1OK ?n            SWINIT04
...
TXT h          0vm   ] 0A       0vq    ] h  &  0V    ] I4  0      Q     SWINIT12
TXT           K  vQK uv K   v\K  vUK  vYK  v K   {vOK Dv4K     Hv8K     SWINIT13

The SWDB2300 member will contain a much smaller number of similar-looking records. Do not proceed to the next step until your object code members look similar in format to the above.

Step 2. Link-Edit the Object Code.

Next, run a job on your OS/390 machine to link-edit the object code files and produce an executable load module. Use the sample JCL below as a guide and modify it for your shop.

The OBJLIB DD should point to the PDS containing the Spectrum Writer object code that you just uploaded from your PC.

The SYSLMOD DD should point to an existing load library where you want the SPECTWTR load module to be placed. Note that the "(R)" parm in the SYSLIN control cards means that any existing module named SPECTWTR in that library will be overwritten.

The SYSLIB DD should point to your shop's DB2 load library (which contains modules such as DSNALI.) (Not required if you are not installing the DB2 Option.)

Link-Edit JCL

//** JOBCARD                                   <-- Modify this line
//*
//*=================================================================
//*  LINK EDIT SPECTRUM WRITER OBJECT CODE (WITH THE DB2 OPTION)   =
//*=================================================================
//LKEDSW EXEC PGM=IEWL,REGION=1024K,  
// PARM=(LIST,LET)
//SYSUT1   DD UNIT=SYSDA,SPACE=(TRK,(30))                             
//SYSPRINT DD SYSOUT=*
//OBJLIB   DD DSN=XXXXXX.OBJLIB,DISP=SHR       <-- Modify this line
//SYSLMOD  DD DSN=XXXXXX.LOADLIB,DISP=SHR      <-- Modify this line
//SYSLIB   DD DSN=XXXXXX.DB2.DSNLOAD,DISP=SHR  <-- Omit/Modify this line
//SYSLIN   DD *
 ENTRY SWINIT
 ORDER SWINIT
 INCLUDE SYSLIB(DSNALI)                        <-- Omit line if not a DB2 install
 INCLUDE OBJLIB(SWDB2300)                      <-- Omit line if not a DB2 install
 INCLUDE OBJLIB(SWMVS300)
 NAME SPECTWTR(R)
//

If you get a return code of 0 from these steps, you have successfully link-edited Spectrum Writer.

If you get a non-zero return code, it probably means that something went wrong in moving the object code from your PC to your mainframe. Here are some possible causes of the problem:

The upload from the PC to the mainframe was not binary (and the object code was "translated" into EBCDIC.)
The CRLF option was invoked for the upload. This causes what should be 80-byte object code records to be "broken" only where an imbedded X'0D0A' (CRLF) happens to occur in the code.

Another possibility is that there is some mistake in the link-edit JCL. (For example, the SYSLIB DD may be pointing to the wrong library.) Repeat steps 1 and 2 carefully. Make sure that your mainframe object code members have the same basic format as the sample object code records shown above in Step 1. When those steps are done successfully, the object code files will linkedit with a zero return code.

Step 3. DB2 Setup

You have now successfully installed Spectrum Writer OS/390 on your mainframe. It exists as a load module named SPECTWTR in the load library that you specified in your link-edit JCL. (If you do not plan to access DB2 data during your trial, you can skip this DB2 setup.)

In order to use Spectrum Writer to access DB2 data, you will need to perform the following DB2 setup steps:

A DB2 "plan" must be "bound." This plan identifies Spectrum Writer to your DB2 system.
Authority to execute this plan must be "granted" to your users.

Note: if Spectrum Writer will be used on multiple DB2 subsystems, these two steps must be performed for each subsystem.

Step 3A. Creating the DB2 Plan. The first step is to create a new DB2 plan. (In most shops, this is done by the Database Administrator.) The plan name should be "SPECT300." This is the plan that Spectrum Writer assumes you will use.

Note: if necessary, you can use a different plan name. But you will have to tell Spectrum Writer that plan name in every job you run. That is done with the DB2PLAN option:

OPTION: DB2PLAN('OURNAME')

If you use SPECT300 as your plan name, you will not need to use the above statement.

After creating the SPECT300 plan, you must "bind" the two Spectrum Writer "DBRM" modules (that you uploaded earlier) into that plan. You can perform the bind with ISPF, or any other way that your shop prefers.

Step 3B. Granting DB2 Execute Authority. After you have created and bound the DB2 plan, you must grant "execute authority" for that plan. Generally, you will grant execute authority for this plan to PUBLIC. That allows anyone in your shop to execute Spectrum Writer. (Of course, each user's access will still be limited to those DB2 tables they are authorized for.)

Step 4. Copy Library Setup

Before using Spectrum Writer to access non-DB2 data (such as VSAM files, QSAM flat files, etc.) some one-time setup is required. This setup consists of creating a Spectrum Writer copy library PDS, and then storing descriptions of your company's files in it. This is necessary before Spectrum Writer can produce reports from those non-DB2 files.

Note: if you plan to use Spectrum Writer only with DB2 tables, you can skip this Step 4. No copy library is required for accessing DB2 tables.

The following steps are needed to set up your Spectrum Writer copy library:

Step 4A. Allocate a new PDS to be used as your Spectrum Writer copy library. The purpose of this PDS is to store definition statements about the files in your shop. The PDS's LRECL should be 80 bytes. The blocksize may be any multiple of 80. The amount of space required will depend on how many files you expect to define to Spectrum Writer. Try allocating 20 tracks, with 20 directory blocks to start with. If you prefer, you can use an existing 80-byte PDS (such as a COBOL copy library, etc.) However, it is recommended that a new PDS be created to serve exclusively as the Spectrum Writer copy library.

Step 4B. Create a new member in the copy library for the first file that you want to define to Spectrum Writer. For example, if you want to define your company's payroll file, you might create a new member named PAYROLL. Within this member, type a FILE statement defining the payroll file. For example, if the payroll file is a sequential disk or tape file, you might enter the following:

FILE: PAYROLL DDNAME(PAYROLL) LRECL(1500)

The above statement defines a sequential file that will be referred to as "PAYROLL" in Spectrum Writer control statements. The DDNAME associated with this file will also be PAYROLL. Be sure to specify an LRECL value that's at least as big as the biggest record in your file. In our PAYROLL example, we specified 1500 as the largest record length.

As another example, if our PAYROLL file was a VSAM file (either ESDS or KSDS) we would use this statement:

FILE: PAYROLL DDNAME(PAYROLL) LRECL(1500) TYPE(VSAM)

For more information on the FILE statement, see Chapter 6, "How to Define Your Input Files" in the manual that was included in your download.

Next, type one FIELD statement for each field in the payroll file. For example, if the first two fields in the payroll file are a 20-byte last name and a 15-byte first name, you would enter the following:

FIELD: LAST-NAME LENGTH(20)
FIELD: FIRST-NAME LENGTH(15)

(Chapter 6 explains how to write FIELD statements.)

It isn't necessary to define all of the fields in the file right away. If the file contains fields that you don't care about using with Spectrum Writer, you do not need to define those fields. When skipping over fields, use the COLUMNS parm as needed to tell Spectrum Writer exactly which column a particular field begins in. For example:

FIELD: SALARY   COLUMN(20) LENGTH(6) TYPE(NUM)    DECIMAL(2)
FIELD: QUANTITY COLUMN(31) LENGTH(3) TYPE(COMP-3) DECIMAL(1)
FIELD: NUM-SOLD COLUMN(55) LENGTH(2) TYPE(COMP)

When you are finished, the copy library member should contain a single FILE statement followed by any number of FIELD statements. Save this copy library member when you are done. Here is a complete, sample file definition. It defines the SALES-FILE used in many of the examples in the manual.

Sample File Definition

FILE: SALES-FILE DDNAME(SALEFILE) LRECL(80)
FIELD: EMPL-NAME LENGTH(10)
FIELD: EMPL-NUM LENGTH(3)
FIELD: BACKUP-EMPL-NUM LENGTH(3)
FIELD: REGION LENGTH(5)
FIELD: AMOUNT LENGTH(6) TYPE(NUM) DECIMAL(2)
FIELD: TAX LENGTH(4) TYPE(NUM) DECIMAL(2)
FIELD: COMMISSION-RATE LENGTH(4) TYPE(NUM) DECIMAL(3)
FIELD: SALES-DATE TYPE(YYMMDD)
FIELD: SALES-TIME TYPE(HHMMSS)
FIELD: CUSTOMER LENGTH(15)
FIELD: TELEPHONE LENGTH(10) TYPE(NUM)
FIELD: TIME-ON-PHONE LENGTH(4) TYPE(SECONDS) DECIMAL(1)
FIELD: PRODUCT-CODE LENGTH(3)

Note: if you have a COBOL or Assembler record layout for the file you are defining, you can use Spectrum Writer to convert that layout into FIELD statements for you. Or, you can even produce a report directly from the record layout, without using FIELD statements at all. Both of these options are described in the latter part of Chapter 6 in the manual. To begin with, though, we suggest that you define one or two small files manually (as described above) to get a clear idea of how Spectrum Writer works. That will make it easier for you to later see how Spectrum Writer's COBOL and Assembler interpreter fits into the picture.

Step 4C. Repeat step 4B for each file that you wish to define to Spectrum Writer. Your Spectrum Writer setup is now complete!

Step 5. Spectrum Writer Execution JCL

You can now request all of the custom reports and output files that you want from your DB2 tables and from the input files that you defined. Following are two examples of execution JCL for Spectrum Writer. Use these as guides and modify them as necessary for your shop. (See the notes following the sample JCL.)

JCL for Creating Spectrum Writer Reports

//** JOBCARD                                         <-- Modify this line
//*
//*=================================================================
//* PRINT A SPECTRUM WRITER REPORT =
//*=================================================================
//STEP1 EXEC PGM=SPECTWTR
//STEPLIB DD DSN=XXXXXX.LOADLIB,DISP=SHR             <-- Modify this line
//SWCOPY DD DSN=XXXXXX.COPYLIB,DISP=SHR COPY LIBRARY <-- Modify this line
//SWLIST DD SYSOUT=* CONTROL LISTING
//SWOUTPUT DD SYSOUT=* REPORT
//SYSOUT DD SYSOUT=* SORT CONTROL LISTING
//SYSUDUMP DD SYSOUT=*
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,(5,1)) SORT WORK FILES
//SORTWK02 DD UNIT=SYSDA,SPACE=(CYL,(5,1))
//SORTWK03 DD UNIT=SYSDA,SPACE=(CYL,(5,1))
//XXXXXXXX DD DSN=XXXXXX.XXXXXX,DISP=SHR INPUT FILE <-- Modify this line
//SYSIN DD * CONTROL STATEMENTS
INPUT: filename
TITLE: ‘your title’
COLUMNS: fieldname fieldname fieldname ...
//

JCL for Creating Spectrum Writer Output Files (for Excel, HTML, etc)

//** JOBCARD                                         <-- Modify this line
//*
//*=================================================================
//* PRODUCE A FILE USING SPECTRUM WRITER =
//*=================================================================
//STEP1 EXEC PGM=SPECTWTR
//STEPLIB DD DSN=XXXXXX.LOADLIB,DISP=SHR             <-- Modify this line
//SWCOPY DD DSN=XXXXXX.COPYLIB,DISP=SHR COPY LIBRARY <-- Modify this line
//SWLIST DD SYSOUT=* CONTROL LISTING
//SWOUTPUT DD DSN=XXXXXX.HTML.FILE, OUTPUT FILE      <-- Modify this line
// DISP=(NEW,CATLG),UNIT=SYSDA,SPACE=(TRK,(20,20)),
// DCB=(RECFM=FB,LRECL=200,BLKSIZE=2000)             <-- Modify this line
//SYSOUT DD SYSOUT= SORT CONTROL LISTING*
//SYSUDUMP DD SYSOUT=*
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,(5,1)) SORT WORK FILES
//SORTWK02 DD UNIT=SYSDA,SPACE=(CYL,(5,1))
//SORTWK03 DD UNIT=SYSDA,SPACE=(CYL,(5,1))
//XXXXXXXX DD DSN=XXXXXX.XXXXXX,DISP=SHR INPUT FILE  <-- Modify this line
//SYSIN DD * CONTROL STATEMENTS
OPTION: HTML
INPUT: filename
COLUMNS: fieldname fieldname fieldname ...
//

You may also want to create a PROC based on this JCL to make it easier for end-users to run Spectrum Writer jobs. Chapter 8, "Operating System Considerations" goes into more detail on the various DD statements and options available. Here are a few things you should make sure of:

The STEPLIB DD must point to the load library where you link-edited the SPECTWTR module. An additional STEPLIB may also be needed to point to the library containing your shop's run-time DB2 modules (such as DSNTIAR), if it is not included in a default steplib.
The SWCOPY DD must point to the copy library that you set up in Step 4 (containing each file's definition statements.)
For runs that use non-DB2 input files, the execution JCL must include one DD statement for each such file. The DDNAME to use is the one specified in the DDNAME parm of the FILE statement that defines the file. In our example earlier, we used PAYROLL as the DDNAME for our PAYROLL file. So, to run a report using the PAYROLL file as input, we would need the following DD in the execution JCL:
```
//PAYROLL DD DSN=...
```
Use the SYSIN DD for the Spectrum Writer control statements (which are used to request reports.) Requestors can type these statements directly into the JCL (as in the examples above.) Or, you could point the SYSIN DD to another dataset, and have the requestors enter their control statements there. This would reduce the chances of the JCL being accidentally modified by an inexperienced user.
When creating an output file (rather than a report), use the SWOUTPUT DD to route the output file records wherever you want them. If the DD specifies a new dataset, you can specify any LRECL you like in the DD. (Pick a length large enough for all the fields you want in your output records.) If you write your output file to an existing dataset, Spectrum Writer will recognize that dataset's existing LRECL and will truncate any output columns that attempt to go beyond that length.
Many shops use “dynamic allocation” of sort work files (which is usually more efficient than hard-coding DD statements). If your shop’s Sort program performs such dynamic allocation, then you should omit the SORTWK01, SORTWK02 and SORTWK03 DDs from your JCL.

Keep Right On Using Spectrum Writer without Interruption!

Once you start solving your custom reporting and file formatting needs with Spectrum Writer, you won't want to stop using it. If you purchase a license for Spectrum Writer before your 30-day trial ends, we can provide you with a new authorization code that will allow you to continue using this same, downloaded copy of Spectrum Writer without any interruption. There won't be anything else to install!

Enjoy Using Spectrum Writer!