· 10/8/2012 · DATAMINER FOR Z/OS Comprehensive Information and Data-Management System User...

DATAMINER FOR Z/OS Comprehensive Information and Data-Management System

User Reference GuideRelease 7.1C

DATAMINER for z/OS is a collection of powerful data-mining and data-manipulation tools. These tools allow non-programmers to easily access information in datasets. Using DATAMINER, you can:

• Browse, change, copy, or print datasets.

• Move data from one type of dataset to another, and

• Reformat the data at the same time.

You can access VSAM and sequential datasets in batch mode, and you can retrieve, view, and update VSAM and temporary storage queues in online mode.

DATAMINER is useful for reporting on and extracting information based on parameters that you specify, and DATAMINER has a report-writing tool that you can use to create custom reports and labels.

DATAMINER FOR Z/OS

Copyright © 2012 by CSI International

All Rights Reserved

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the Government is subject to the restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.

This material contains confidential and proprietary material of CSI International (hereafter also referred to as CSI) and may not be used in any way without written authorization from CSI International. This material may not be reproduced, in whole or in part, in any way, without prior written permission from CSI International.

Permission is hereby granted to copy and distribute this document as follows:

• Each copy must be a complete and accurate copy.• All copyright notices must be retained.• No modifications may be made.• Use of each copy is restricted to the evaluation and/or promotion of CSI International’s

DATAMINER FOR Z/OS product or in accordance with a license agreement.

DATAMINER FOR Z/OSInformation Retrieval and Reporting SystemVersion 7 Release 1C

October 2012

Published by CSI International8120 State Route 138, Williamsport OH 43164Phone: 800-795-4914

Fax: 740-986-6022

E-Mail: [email protected]

Internet: http://www.csi-international.com

Documentation comments: [email protected]

CSI International Technical Support andTechnical Support Escalation

CSI Product Technical Support

During Business Hours Monday through Friday, 9:00 A.M. through 5:00 P.M. EST/EDT

• Telephone

Toll Free in the USA: 800-795-4914Worldwide: 740-420-5400

• E-mail

Questions: [email protected]

• Web

http://csi-international.com/problemreport_zos.htm

Emergency Service(24/7)

After business hours, and 24 hours on Saturday and Sunday

• Telephone1


Escalating Technical Issues

Business Hours Monday through Friday, 9:00 A.M. through 5:00 P.M. EST/EDT

Request support escalation by the telephone numbers or e-mail address listed below:

1. Calls are automatically transferred to a 24/7 answering service that forwards all calls based on severity.

Copyright © 2012 by CSI Internationali

mailto:[email protected]

CSI International Technical Support

• Telephone


• E-mail

Escalation: [email protected]

After Hours (SEV1) 1. Call one of the following telephone numbers.


2. Tell the operator that you have a “SEV1” issue.

The answering service will follow the following chain:

a. Technical Support Rep(s)

b. Product Developer (if necessary)

c. Technical Support Manager (if necessary)

d. Development Manager (if necessary)

e. Chief Operating Officer (if necessary)

f. Chief Executive Officer (if necessary)

3. Calls continue until the best person to resolve your issue is contacted.

Copyright © 2012 by CSI Internationalii

mailto:[email protected]

Table of Contents

CSI International Technical Support and Technical Support Escalation............. iCSI Product Technical Support ..................................................................................... iEscalating Technical Issues ........................................................................................... i

Chapter 1. Overview.............................................................................................. 1.1What Is DATAMINER?.......................................................................................................1.2

Introduction.................................................................................................................1.2Batch and Online Environments .................................................................................1.3VSAM I/O Driver ......................................................................................................1.3File Command Result .................................................................................................1.4

Available Functions ..........................................................................................................1.5Supported Files ..........................................................................................................1.6Ways to Use ...............................................................................................................1.6

Features and Capabilities ..................................................................................................1.7Some Practical Examples............................................................................................1.8

Syntax Conventions Used in This Manual .......................................................................1.9

Chapter 2. DATAMINER Scripts .............................................................................. 2.1Introduction to Scripts ......................................................................................................2.2

Processing Modes .......................................................................................................2.2AUTO Command........................................................................................................2.2BEGIN and EOF Procedures ......................................................................................2.3Script Example with BEGIN and EOF Procedures ....................................................2.3Difference Between BEGIN/EOF and BEFORE/AFTER Timings ...........................2.3Multiple Input and Output Datasets............................................................................2.3

Script Components............................................................................................................2.4Introduction.................................................................................................................2.4Shortcut Commands....................................................................................................2.4Input and Output Dataset Definitions .........................................................................2.4Field Definitions .........................................................................................................2.4Variables .....................................................................................................................2.4

Copyright © 2012 by CSI Internationaliii

DATAMINER FOR Z/OS 7.1C User Reference Guide Table of Contents

Commands ..................................................................................................................2.4Script Example............................................................................................................2.5Notes on This Example...............................................................................................2.5

Execution Sequence ..........................................................................................................2.6Introduction.................................................................................................................2.6Command Sequence ...................................................................................................2.6Effects of Command Sequences ................................................................................2.6

Execution JCL...................................................................................................................2.7Introduction.................................................................................................................2.7Example ......................................................................................................................2.7

Script Readability .............................................................................................................2.8Introduction.................................................................................................................2.8Words That Are Always Ignored................................................................................2.8Symbols That Are Sometimes Ignored.......................................................................2.8Examples: Ignored Symbols .......................................................................................2.8

Adding Comments ............................................................................................................2.9Introduction.................................................................................................................2.9Comment Indicators....................................................................................................2.9Examples.....................................................................................................................2.9

INCLUDE Command .....................................................................................................2.10OFFSET= Command ......................................................................................................2.11SCRIPT Command .........................................................................................................2.12STATS Command...........................................................................................................2.13VALIDATE= Command ................................................................................................2.14DATAMINER Reserved Words ........................................................................................2.15

Chapter 3. Input and Output Specification.......................................................... 3.1DATAMINER Input and Output Datasets ...........................................................................3.2

Introduction.................................................................................................................3.2Opening Datasets ........................................................................................................3.2Unused Datasets..........................................................................................................3.2

INPUT= Command...........................................................................................................3.3OUTPUT= Command .....................................................................................................3.7DATACARDs Command ...............................................................................................3.12

Chapter 4. Record Fields ...................................................................................... 4.1Defining Record Fields .....................................................................................................4.2

Introduction.................................................................................................................4.2Syntax to Define a Record Field.................................................................................4.2Example Definition.....................................................................................................4.6Example of Creating Overlapping Record Fields ......................................................4.7Example of Defining Five Fields................................................................................4.7

Arrays and Indexing..........................................................................................................4.8Introduction.................................................................................................................4.8INDEXing by Subscripted Array Member Number ...................................................4.8INDEXing by INDEX Value ......................................................................................4.9

Copyright © 2012 by CSI Internationaliv


INDEXing by Bytes Offset.......................................................................................4.10

Chapter 5. Variables, Literals, and System Constants ...................................... 5.1Variable Types ..................................................................................................................5.2

Introduction.................................................................................................................5.2Defining User Variables (DEFINE Command)................................................................5.3Arrays and Indexing..........................................................................................................5.8

Introduction.................................................................................................................5.8INDEXing by Subscripted Array Member Number ...................................................5.8INDEXing by INDEX Value ......................................................................................5.9INDEXing by Bytes Offset.......................................................................................5.10

System Variables ............................................................................................................5.12Introduction...............................................................................................................5.12Example ...................................................................................................................5.12Variables List ............................................................................................................5.12

Literals ............................................................................................................................5.15Introduction...............................................................................................................5.15Character ..................................................................................................................5.15Packed Decimal ........................................................................................................5.15Zoned Decimal .........................................................................................................5.16Hexadecimal ............................................................................................................5.16Binary .......................................................................................................................5.17Numeric ...................................................................................................................5.17

System Constants ............................................................................................................5.18

Chapter 6. Shortcut Commands........................................................................... 6.1Shortcut Commands Overview.........................................................................................6.2

Introduction.................................................................................................................6.2What Makes a Shortcut Command .............................................................................6.2Constraints .................................................................................................................6.2

COPY Shortcut Command................................................................................................6.3UPDATE Shortcut Command ..........................................................................................6.5EXTRACT Shortcut Command........................................................................................6.6PRINT Shortcut Command...............................................................................................6.8

Example 1 Script.........................................................................................................6.9Example 1 Output ....................................................................................................6.10Narrowing What Is Printed .......................................................................................6.10

DUMP Shortcut Command.............................................................................................6.12DELETE Shortcut Command ........................................................................................6.14HD Subcommand ...........................................................................................................6.15MAXLN= Subcommand.................................................................................................6.16SELECT…[WHERE] Subcommand ............................................................................6.17TOT Subcommand..........................................................................................................6.20

Chapter 7. Dataset Reading and Writing ............................................................. 7.1Dataset Reading Overview ...............................................................................................7.2

Copyright © 2012 by CSI Internationalv


Introduction.................................................................................................................7.2READ Command..............................................................................................................7.3POINT Command ...........................................................................................................7.5WRITE Command ............................................................................................................7.6Examples of READing and WRITEing Data ...................................................................7.8INSERT INTO…VALUES Command ..........................................................................7.12DISPLAY Command......................................................................................................7.14

Chapter 8. Conditions and Flow Control............................................................. 8.1Relational Operators .........................................................................................................8.2

Description..................................................................................................................8.2IF…[ELSE]…ENDIF Statements ....................................................................................8.3DO WHILE and ENDDO Statements ..............................................................................8.6PROC…[GOBACK]…ENDPROC Statements (Defining Procedures)...........................8.8PERFORM Command (Call a Procedure)......................................................................8.10Labels and GOTO Statements ........................................................................................8.11EXIT Command (Escape a Script) .................................................................................8.13CALL…[USING] Command .........................................................................................8.14Timing Commands .........................................................................................................8.15

Chapter 9. Record-Selection Commands............................................................ 9.1Introduction.......................................................................................................................9.2

Commands Overview .................................................................................................9.2Execution Order ..........................................................................................................9.2Record-Selection Rules ..............................................................................................9.3

FIRSTKEY Command......................................................................................................9.4FIRST= Command............................................................................................................9.5LAST= Command.............................................................................................................9.6FREQ= Command ............................................................................................................9.7KEEP Command...............................................................................................................9.8DROP Command ..............................................................................................................9.9START Command ..........................................................................................................9.10STOP Command .............................................................................................................9.12SKIP Command ..............................................................................................................9.14ONLY (or WHERE) Command .....................................................................................9.16MAXRCDS= Command.................................................................................................9.18

Chapter 10. Data Manipulation Commands ...................................................... 10.1Data Manipulation Commands .......................................................................................10.2

Introduction...............................................................................................................10.2Constraints ................................................................................................................10.2Special Notes ............................................................................................................10.2

MOVE Command ...........................................................................................................10.4SET Command................................................................................................................10.6HIDE Command .............................................................................................................10.7CLOAK Command .........................................................................................................10.8

Copyright © 2012 by CSI Internationalvi


Arithmetic Commands ....................................................................................................10.9Introduction...............................................................................................................10.9Accumulators Commands.........................................................................................10.9IF Commands............................................................................................................10.9Input Values May Change ........................................................................................10.9

ADD Command ............................................................................................................10.10SUBTRACT Command................................................................................................10.11MULTIPLY Command.................................................................................................10.12DIVIDE Command .......................................................................................................10.13

Chapter 11. Report Writer ................................................................................... 11.1Report Writer Overview .................................................................................................11.2

Introduction ..............................................................................................................11.2Mailing Labels and Other Printing Tasks .................................................................11.2

Creating a Report Writer Script ......................................................................................11.3Overview...................................................................................................................11.3Step 1—Specify the Input.........................................................................................11.3Step 2—Define the Fields and Variables to Use in the Report ................................11.3Step 3—Read the Input File......................................................................................11.3Step 4—Select Records ............................................................................................11.4Step 5—Perform Computations................................................................................11.4Step 6—Use PRINT to Print a Report ......................................................................11.4Step 7—Use REPORT to Specify Fields and Report Formatting ............................11.4Script Example..........................................................................................................11.5

Defining Field Formats and Headings in a Report .........................................................11.6Field Masks...............................................................................................................11.6User-Defined Masks .................................................................................................11.6Column Headings ....................................................................................................11.6

Adding a User-Defined Mask to a Field Definition .......................................................11.7Using the REPORT Command .......................................................................................11.8REPORT Subcommands Summary ..............................................................................11.10

Summary Table.......................................................................................................11.10ACROSS, WIDTH, and HEIGHT Subcommands .......................................................11.11ADVANCE Subcommand............................................................................................11.12AVG Subcommand.......................................................................................................11.13BREAK (or CONTROL) Subcommand .......................................................................11.14GAP Subcommand .......................................................................................................11.16HEADING Subcommand .............................................................................................11.17LABELS Subcommand ................................................................................................11.18LENGTH Subcommand ..............................................................................................11.19LINE Subcommand ......................................................................................................11.20NODATE and NOPAGE Subcommands .....................................................................11.22ORDER (or SEQUENCE) Subcommand .....................................................................11.23PRINTER Subcommand...............................................................................................11.26SPACING Subcommand ..............................................................................................11.27SUM Subcommand.......................................................................................................11.28

Copyright © 2012 by CSI Internationalvii


SUMMARY Subcommand...........................................................................................11.29TITLE Subcommand ....................................................................................................11.30Report Formatting—Simple to Complex......................................................................11.32Additional Report Writer Examples .............................................................................11.41

Chapter 12. Table Fields ..................................................................................... 12.1TABLE Command..........................................................................................................12.2Defining Table Fields .....................................................................................................12.4Arrays and Indexing........................................................................................................12.9

Introduction...............................................................................................................12.9INDEXing by Subscripted Array Member Number .................................................12.9INDEXing by INDEX Value ..................................................................................12.10INDEXing by Bytes Offset.....................................................................................12.11

DATA…ENDDATA Subcommands ...........................................................................12.13FIND Subcommand (Searching Tables).......................................................................12.14

Chapter 13. SORT Command ............................................................................. 13.1SORT Command.............................................................................................................13.2

Chapter 14. Troubleshooting Commands......................................................... 14.1ABEND Command .........................................................................................................14.2CANCEL Command.......................................................................................................14.3SHOW Command ...........................................................................................................14.4TRACE Command..........................................................................................................14.6

Chapter 15. DB2 Commands .............................................................................. 15.1DB2 Access.....................................................................................................................15.2

Introduction...............................................................................................................15.2CONNECT Command....................................................................................................15.3INPUT= Command (DB2)..............................................................................................15.4OUTPUT= Command (DB2)..........................................................................................15.5EXECUTE Command.....................................................................................................15.6CLOSE Command ..........................................................................................................15.7COMMIT Command ......................................................................................................15.8ROLLBACK Command .................................................................................................15.9Host Variables...............................................................................................................15.10Additional Information about DB2...............................................................................15.11

Field Names ............................................................................................................15.11Cursors ....................................................................................................................15.11System Variables ....................................................................................................15.11

DB2 Examples ..............................................................................................................15.12Example 1: Simple Auto Print ................................................................................15.12Example 2: Auto-Read Report................................................................................15.12Example 3: Manual-Read Report ...........................................................................15.13Example 4: Multiple Cursors ..................................................................................15.13Example 5: Simple Table Update ...........................................................................15.13

Copyright © 2012 by CSI Internationalviii


Example 6: Table Update with Host Variables ......................................................15.14Example 7: Extract from DB2 to Sequential Dataset .............................................15.15Example 8: Extract from VSAM to DB2................................................................15.15

Chapter 16. DATAMINER Messages ..................................................................... 16.1Summary Messages ........................................................................................................16.2

Introduction...............................................................................................................16.2nnn RECORDS READ FROM filename datasetname .............................................16.2nnn RECORDS WRITTEN TO FILE filename datasetname ..................................16.2nnn RECORDS UPDATED IN FILE filename datasetname...................................16.2nnn RECORDS DELETED FROM FILE filename datasetname ............................16.2nnn DATA RECORDS PRINTED ...........................................................................16.2nnn DATA RECORDS DUMPED ...........................................................................16.2nnn FIELD VALIDATION ERRORS......................................................................16.2

Syntax Error Messages ...................................................................................................16.3Introduction...............................................................................................................16.3Message Example .....................................................................................................16.3Message Table ..........................................................................................................16.4

General Messages .........................................................................................................16.12List of Messages ....................................................................................................16.12Message Table ........................................................................................................16.14

Chapter 17. DATAMINER Script Examples........................................................... 17.1Common Examples.........................................................................................................17.3

Ex. 1: COPY Subset of Records ..............................................................................17.3Ex. 2: COPY and PRINT Specific Records..............................................................17.3Ex. 3: DUMP Specific Records ................................................................................17.3Ex. 4: COPY and PRINT Specific Records and Calculations ..................................17.3Ex. 5: PRINT Specific Records, Calculations, and Totals .......................................17.4Ex. 6: PRINT Specific Records and Totals ..............................................................17.5Ex. 7: DELETE Specific Records.............................................................................17.6Ex. 8: EXTRACT and PRINT Specific Records ......................................................17.6Ex. 9: EXTRACT and PRINT Records, Calculations ..............................................17.7Ex. 10: DUMP Specific Records ..............................................................................17.7Ex. 11: COPY Specific Records, KSDS...................................................................17.7Ex. 12: COPY Specific Records, Fixed Block .........................................................17.8Ex. 13: UPDATE Variable Blocked File In Place....................................................17.8Ex. 14: UPDATE Fixed-Length File ........................................................................17.8Ex. 15: INSERT Records into a KSDS.....................................................................17.9Ex. 16: UPDATE a KSDS ........................................................................................17.9Ex. 17: COPY and PRINT Specific Records............................................................17.9Ex. 18: DUMP the First 50 Records From a KSDS ...............................................17.10Ex. 19: COPY VSAM File to an FL Dataset, DUMP Recs....................................17.10Ex. 20: PRINT Column Report Showing Three Fields ..........................................17.10Ex. 21: COPY 1000 Records from One File to Another ........................................17.11Ex. 22: PRINT Report and DUMP Recs Using Criteria.........................................17.11

Copyright © 2012 by CSI Internationalix


Ex. 23: PRINT Records Within a Balance Range ..................................................17.12Ex. 24: DUMP Records and Delete Matching Records..........................................17.12Ex. 25: Calculate Ratio, PRINT Report, EXTRACT Records ...............................17.12Ex. 26: DUMP the First 20 Records Matching Criteria .........................................17.13Ex. 27: Create New KSDS Records from Card Input.............................................17.13Ex. 28: READ Two Files and SHOW ACCTNO from Both .................................17.13Ex. 29: UPDATE a Sequential File In Place ..........................................................17.14Ex. 30: PRINT a Column Report from a File .........................................................17.14Ex. 31: COPY and DUMP the First 10 Records of a File ......................................17.14Ex. 32: Create a File from Selected Fields of an Input File....................................17.15Ex. 33: COPY a Prod File to a Test File, Changing Names ...................................17.15Ex. 34: PRINT Report Sorted by Fields, Create Subtotals .....................................17.16Ex. 35: PRINT Report Sorted by Fields, File/Table Input .....................................17.17Ex. 36: PRINT Name and Address Labels .............................................................17.18Ex. 37: Using ORDER and BREAK Commands Together....................................17.18Ex. 38: Using ORDER, BREAK, and SUMMARY Together ...............................17.20

Chapter 18. DATAMINER Online ........................................................................... 18.1Overview of DATAMINER Online ...................................................................................18.2

Introduction...............................................................................................................18.2Description................................................................................................................18.2Supported Environments...........................................................................................18.2System Requirements ...............................................................................................18.2CICS Temporary Storage Queues.............................................................................18.2Security .....................................................................................................................18.2Features and Capabilities ..........................................................................................18.3

How DATAMINER Online Works....................................................................................18.4Introduction...............................................................................................................18.4Access Records .........................................................................................................18.4Browsing Files ..........................................................................................................18.4Browsing Temporary Storage Queues ......................................................................18.4

DATAMINER Online Sample Screen ...............................................................................18.5Introduction...............................................................................................................18.5Example ....................................................................................................................18.5Transaction................................................................................................................18.5Software version .......................................................................................................18.5RECORD NUMBER (RCD xxx OF yyy) .................................................................18.5FILEID Field.............................................................................................................18.5LRECL Field.............................................................................................................18.6OPER Field ...............................................................................................................18.6KEY ..........................................................................................................................18.9THRU KEY ..............................................................................................................18.9REMOTE KEYPOS ...............................................................................................18.10DATA AREA .........................................................................................................18.10PF KEYS.................................................................................................................18.10

DATAMINER Online Error Messages ............................................................................18.11

Copyright © 2012 by CSI Internationalx


Chapter 19. DATAMINER/VE.................................................................................. 19.1DATAMINER/VE Benefits and Features..........................................................................19.2

Benefits .....................................................................................................................19.2Features and Capabilities ..........................................................................................19.3

DataMiner/VE and 4GL, COBOL, and PL/I ..................................................................19.4Introduction...............................................................................................................19.4DATAMINER/VE and 4GL Partnership Benefits .......................................................19.4DATAMINER/VE and COBOL and PL/I Benefits .....................................................19.4

DATAMINER/VE Access to VSAM Files........................................................................19.6Introduction...............................................................................................................19.6Online Access ...........................................................................................................19.6Batch Access.............................................................................................................19.6

DATAMINER/VE Programming Overview......................................................................19.7Introduction...............................................................................................................19.7General Access ........................................................................................................19.7CICS Access ............................................................................................................19.7Batch Application Access ........................................................................................19.7Supported Environments ..........................................................................................19.8

How DATAMINER/VE Works .........................................................................................19.9Sequence ..................................................................................................................19.9Programmer-Defined Components ...........................................................................19.9Return Codes ............................................................................................................19.9

CICS and COM-PLETE Requirements ........................................................................19.10Introduction ............................................................................................................19.10CICS Users ............................................................................................................19.10COM-PLETE Users ...............................................................................................19.10

Executing DATAMINER/VE ..........................................................................................19.12Introduction.............................................................................................................19.12COBOL Example ...................................................................................................19.12NATURAL Example .............................................................................................19.12Batch Assembler Example......................................................................................19.12

CICS Temporary Storage Access .................................................................................19.13Introduction.............................................................................................................19.13Temporary Storage Use .........................................................................................19.13

CICS—CONTROL-BLOCK........................................................................................19.14Introduction.............................................................................................................19.14COBOL Example....................................................................................................19.14Assembler Example ...............................................................................................19.14RETURN-CODE (CL3) .........................................................................................19.14ACTION-CODE (CL3) ..........................................................................................19.15FILE-ID (CL8)........................................................................................................19.18RECORD-LENGTH (BL2) ....................................................................................19.19RESERVED-AREA (BL17)...................................................................................19.20KEY-POSITION (BL2) ..........................................................................................19.20KEY-LENGTH (BL2) ............................................................................................19.20KEY (Variable).......................................................................................................19.21

Copyright © 2012 by CSI Internationalxi


CICS—RECORD-AREA .............................................................................................19.22Introduction ............................................................................................................19.22RECORD-AREA Size ............................................................................................19.22

Batch—CONTROL-BLOCK .......................................................................................19.23Introduction.............................................................................................................19.23COBOL Example....................................................................................................19.23Assembler Example ................................................................................................19.23RETURN-CODE (CL3) .........................................................................................19.23ACTION-CODE (CL3) ..........................................................................................19.24FILE-ID (CL8)........................................................................................................19.28RECORD-LENGTH (BL2) ....................................................................................19.28RESERVED AREA (BL10) ...................................................................................19.29PASSWORD-LENGTH (BL1)...............................................................................19.29PASSWORD (CL8) ................................................................................................19.29KEY-LENGTH (BL2) ............................................................................................19.29KEY (Variable Length) ..........................................................................................19.29

Batch—RECORD-AREA.............................................................................................19.30Introduction ............................................................................................................19.30Important Points......................................................................................................19.30

Return Codes ................................................................................................................19.31Program Examples ........................................................................................................19.35

Example 1: Online Command Level COBOL Program .........................................19.35Example 2: Online NATURAL Program (Single-File Access)..............................19.36Example 3: Online NATURAL Program (Multiple-File Access) ..........................19.37Example 4: Online Assembler Program .................................................................19.38Example 5: Batch NATURAL Program.................................................................19.40Example 6: Dynamic Call to VNATB....................................................................19.41Example 7: Static Call to VNATB .........................................................................19.41Example 8: Batch Assembler Program...................................................................19.42

DATAMINER/VE Installation.........................................................................................19.43Introduction.............................................................................................................19.43Load Library Modules ...........................................................................................19.43Source Library Module ...........................................................................................19.43

DATAMINER/VE Online Security ................................................................................19.44Introduction ............................................................................................................19.44Security Table ........................................................................................................19.44Installed Modes ......................................................................................................19.44Inclusive Security Mode .........................................................................................19.44Exclusive Security Mode .......................................................................................19.44Security Check Methodology ................................................................................19.44Adding or Changing Security Entries ....................................................................19.45Security Module Source..........................................................................................19.46

DATAMINER/VE Control Table ....................................................................................19.48Introduction.............................................................................................................19.48Control Table .........................................................................................................19.48

Copyright © 2012 by CSI Internationalxii


Chapter 20. DATAMINER/VE Support ................................................................... 20.1DATAMINER/VE Programming Tips ..............................................................................20.2

CICS Pseudo Conversational EOT with NATURAL ..............................................20.2Avoiding Lockouts ...................................................................................................20.2Using CICS Temporary Storage for Scrolling..........................................................20.4Accessing Multiple Files ..........................................................................................20.4Alternate Indexes with Non-Unique Keys................................................................20.4NATURAL Packed Fields in Keys...........................................................................20.5NATURAL Calls ......................................................................................................20.5

Troubleshooting DATAMINER/VE ..................................................................................20.6Introduction...............................................................................................................20.6CONTROL-BLOCK Layout ....................................................................................20.6RESERVED-AREA Handling..................................................................................20.60V06I Message .........................................................................................................20.6RETURN-CODE Checking ......................................................................................20.6RECORD-AREA Size Specification ........................................................................20.6S080A GETMAIN Failure Errors.............................................................................20.6Transaction Work Area Addressing .........................................................................20.7CICS AEY9 ABEND or NATURAL 954 ABEND .................................................20.7Differences Between VNAT and VNATB ...............................................................20.7NATURAL 920 Abend.............................................................................................20.7Corrupted Code in your NATURAL 2.1 Program ...................................................20.7Incorrect Installation of New Release of VNATB / VNATB2 with NATURAL.....20.8

VSAM Basics for DATAMINER/VE................................................................................20.9Introduction...............................................................................................................20.9File Types .................................................................................................................20.9Key Sequence Dataset (KSDS).................................................................................20.9Entry Sequence Dataset (ESDS)...............................................................................20.9Relative Record Dataset (RRDS) .............................................................................20.9Reusable Dataset.......................................................................................................20.9Record Retrieval .......................................................................................................20.9KSDS (Keyed Sequence Dataset)...........................................................................20.10ESDS (Entry Sequence Dataset).............................................................................20.10RRDS (Relative Record Dataset) ...........................................................................20.11

Copyright © 2012 by CSI Internationalxiii

Copyright © 2012 by CSI International1.1

1
Overview
DATAMINER for z/OS (hereafter “DATAMINER”) is a collection of powerful data-mining and data-manipulation tools. These tools allow non-programmers to easily access the information in your datasets. Using DATAMINER, you can:

• Browse, change, copy, or print datasets.

• Move data from one type of dataset to another type of dataset, and

• Reformat the data at the same time.

You can access VSAM and sequential datasets in batch mode, and you can retrieve, view, and update VSAM and temporary storage queues in online mode.

This chapter covers the following topics:Page

What Is DataMiner? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2Available Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.5Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.7Syntax Conventions Used in This Manual. . . . . . . . . . . . . . . . . . . . . . . 1.9

DATAMINER FOR Z/OS 7.1C User Reference Guide Overview

What Is DATAMINER?

Introduction DATAMINER is a software utility package that permits quick, easy access to SAM and VSAM datasets for selective searching, printing, extracting, updating, and copying of dataset data. Using DATAMINER requires no special programming skills.

DATAMINER is useful for reporting on and extracting data based on data that you specify. DATAMINER has a report-writing tool that you can use to create reports and labels. Another use for DATAMINER is to fix corrupted records.

DATAMINER is powerful enough to do things that programmers and operations staff want to do, but it is simple enough for business users to use.

DATAMINER reduces costs associated with learning and using many complex and unrelated utilities. DATAMINER consolidates many functions into one simple system, giving you one common method of accomplishing most of your day-to-day data handling and reporting tasks.



Batch and Online Environments

DATAMINER works in both batch and online (TSO and CICS) environments. The following table compares how you use DATAMINER in these environments.

VSAM I/O Driver DATAMINER uses its own highly efficient VSAM I/O driver called DATAMINER/VE.

You can use DATAMINER/VE in your own online and batch programs to access VSAM datasets and CICS. Complete details on how to use DATAMINER/VE with your own COBOL, Assembler, PL/I, and 4GL (such as NATURAL) programs are covered in Chapter 19, “DataMiner/VE.” DATAMINER/VE allows programs written for 4GLs to

DATAMINER Batch DATAMINER ONLINE

Uses Making a copy of a dataset

Making large numbers of alterations

Printing results

Changing record values in a large dataset

Changing, copying, and printing records using just a few commands

Creating selection criteria and data manipulation commands using IF, AND, OR, and NOT

Producing simple or sophisticated reports and lists in minutes

Accomplishing dataset conversions and mass changes quickly and accurately

Correcting corrupted records

Making changes to a small number of easily identified records

Making changes in a small dataset or with a dataset in which you know the keys of the records you want to change

Debugging and testing VSAM programs

Looking at and modifying temporary storage queues

Correcting corrupted records

How It Works

DATAMINER BATCH allows you to set a long-running script in progress and then let the script run by itself.

DATAMINER BATCH lets you selectively search and retrieve records by record key, record location, or record content.

DATAMINER ISPF is an online VSAM editor that non-technical users can use to display or change parts of VSAM datasets.



access VSAM datasets without having to convert those datasets to a different format.

File Command Result The result of the last I/O command issued to a dataset is kept as a three- character alphabetic return code in a field called filename:IO-RESULT, where filename is the ddname of the dataset. Some of the more commonly encountered dataset results include

• EOF (end of file)

• NFD (keyed record not found)

• DPK (duplicate key when trying to add a keyed record)

DATAMINER also has a general IO-RESULT value that is set to the result of the last I/O operation performed by any dataset.

The FILE-STATUS system variable may be used in place of IO-RESULT.



Available Functions

Introduction DATAMINER has several main functions. You use these functions to manipulate and modify the data in your datasets.

Copy Copy one dataset to another. The output dataset can be a different format from the input dataset. For example, you can change the block size or copy a VSAM dataset to a sequential dataset on disk or tape. You can also make modifications to the records in the new dataset, such as setting the account balance in every record to zero.

Update Update one or more records in a VSAM KSDS or sequential dataset. You can choose which records to change by matching, or not matching, criteria that you specify. You do not need to know the key of a record or anything about the dataset’s internal characteristics other than the record layout. For example, you can change the account balance of every overdrawn account to zero, change the surname of customer 12345 from Jones to Brown, or correct a spelling mistake and change Simth to Smith.

Dump Dump a dataset in hexadecimal to list the internal contents of a dataset. This function is primarily for programmers. You can select which records to dump. For example, you can dump every record where the zip code is less than 28800. Dump is a very useful function for problem solving.

You can display the contents of selected fields rather than displaying the entire record.

Print Print one or more records from a dataset. Print is easier to read than Dump because it formats the data to make it readable and understandable. For example, you can quickly produce a report that shows every overdrawn account and ignores all those that are in credit.

Print can produce a formatted report with headers, formatted data elements, literals, and accumulated counts and totals.

You can use the report writer to create more sophisticated reports that are SORTed, broken down into groups, summarized, and so on.

Extract Extract parts of records from a dataset into another dataset. For example, you can create a new dataset from your customer detail dataset that contains only account numbers, names, and addresses.

Insert Insert new records into a VSAM dataset. For example, you can insert a description of a new company branch into a VSAM dataset.

Delete Delete records from a VSAM dataset that meet a criterion that you specify. For example, you can delete all records in a VSAM dataset that have not been active in five years.



Environments You can use DATAMINER both in production and in development environments.

Supported Files DATAMINER supports both sequential (QSAM) and VSAM datasets for both input and output. DATAMINER supports all types of VSAM datasets:

• Keyed sequence (KSDS)

• Relative record (RRDS)

• Entry sequence (ESDS)

• Variable relative record (VRRDS)

DATAMINER also supports compressed and non-compressed VSAM datasets.

Ways to Use Some ways to use DATAMINER are to

• Copy, dump, or print all or part of a dataset.

• Retrieve records by full key, generic key, relative record number, or record number. DATAMINER accesses a VSAM dataset’s catalog to establish whether it is KSDS, RRDS, or ESDS and to retrieve its record size.

• Retrieve specific records or groups of records based on where the records are in the dataset, on the contents of a record, or a combination of both. For example, records can be selected if they are in the first 1,000 records on dataset or if a given field or combination of fields in a record contains a specific value or values. Logical AND and OR commands can be used with all filtering arguments to allow the most complex filtering criteria.

• Modify specific records that you have selected. DATAMINER can modify all or some of the selected records. You can select the records to modify the same way you select records for retrieval.



Features and Capabilities

This section lists the features and capabilities of DATAMINER.

DATAMINER

• Is command driven. You can accomplish all functions without program coding, testing, or cataloging. DATAMINER carries out commands in the same order that you give them to DATAMINER. For more information on command execution order, see “Execution Sequence” (page 2.6).

• Lets you easily access SAM and VSAM datasets of any organization or record type. VSAM datasets are accessed through either primary or alternate index.

• Examines the VSAM catalog to determine dataset attributes automatically.

• Can select every nth record so that you can create a smaller version of a production dataset for testing. For example, you can tell it to pick every

20th record.

• Has free-form commands that you can enter anywhere from position 1 to 80, with no limit to the number of commands entered.

• Automatically calculates field lengths and aligns decimal points.

• Can examine and select records based on position within the dataset or on record contents. Additionally, DATAMINER can scan and select records based on a “global” examination of their contents.

• Provides flexible report generation capabilities including headers, data formatting, literal insertion, hexadecimal data display, data conversion, control breaks, SORTing, summarizing, and totaling.

• Can be run in either auto mode, allowing DATAMINER to control reading and writing of datasets or in task mode where the script controls all the dataset I/O. An auto mode script can do its own additional I/O.

• Allows scripts that can include any number of input and output datasets.

• Can be used to accomplish many useful tasks:

— Search datasets for specified character strings

— Change or delete records on a dataset

— Selectively change or reformat SAM or VSAM datasets

— Copy or back up datasets with or without changes

— Create representative samples of production datasets



— Create a selective backup of a dataset (for example, including only active accounts)

— Create a copy of a production dataset with sensitive information blanked out

— Create and modify comprehensive test datasets

— Verify test results

— Print selected records from any dataset

— Print formatted reports with headers and totals

— Print edited hexadecimal and/or character dumps

— Accumulate and print totals and record counts

— Sequence check datasets

— Mask production data, insert random values, and select random records so you can securely create test files from production data

• Includes DATAMINER/VE for making access to VSAM datasets and CICS temporary storage queues much simpler and faster.

In addition, DATAMINER/VE lets all application programs, including those written in 4GLs, have full access to VSAM datasets.

Some Practical Examples

Here are just a few things you can do with DATAMINER:

• Create a test data dataset containing every 100th record from a production dataset.

• Create a test data dataset from a production dataset but set every customer name to XXX.

• Remove every record with a negative balance from a dataset.

• Create a report showing every customer who owes more than $20,000.

• Print a hexadecimal dump of every record in a dataset with a negative balance. This is primarily for programmers’ use.

• Increase the length of a field in a dataset to allow for larger numbers.

• Print a report summarizing sales by company branch number.



Syntax Conventions Used in This Manual

The following conventions are used in syntax statements for commands in this manual.

Type Style Syntax statements generally are in boldfaced monospaced type.

Value Labels Words that you are to replace with a value (“variables”) are in slanted monospaced type. For example, recfieldname.

Alternative Required Elements

Alternative required elements are enclosed in braces and separated by vertical bars. This syntax means you must enter one of the values.

{ VALUE_1 | VALUE_2 | VALUE_3 }

Optional Elements Optional elements are enclosed in brackets and separated by vertical bars:

[VALUE_4 | VALUE_5]

Depending on the length of the syntax statement, an options list may continue to the next line:

[ VALUE1 | VALUE2 | VALUE3 | VALUE5 | VALUE4 | VALUE5 ]

Default Values If there is a default value among alternatives, the default is underscored:

[ VALUE1 | VALUE2 | VALUE3 ]

Required Elements Anything not enclosed in brackets is required; enter in the order given.

Repeatable Elements A set of three periods after a portion of syntax, such as

{ recfieldname | uservar | sysvar } ...

signifies that you can repeat that portion.

So in this example, any of the options between the braces can be repeated any number of times. The syntax explanation for a command will indicate how many times the element can be repeated if there is a limit.

Uppercase and Lowercase Letters

A combination of upper- and lowercase letters in a command, parameter, or other element indicates the portion required for the keyword.

For example, the INPUT= command syntax looks partly like this:

INPUT={CARDs | TAPE | VSAM | DISK}

In this statement, the value CARDs means that you must specify at least CARD for this value—the ‘s’ is optional.



Multiple Lines Multiple lines in syntax that are not enclosed in brackets or braces indicate only that the line is very long and would not fit on a single line across a column or page. DATAMINER does not care how lines are split.

The syntax statement below for defining a record field is an example of a very long syntax statement. The number of lines are not significant; multiple lines do not signify that the different lines are alternatives.

recfieldname startpos length type [decimalplaces] [OCCURS n TIMES [INDEX(ixname)]] [std-mask] [HEADING 'headingline1' ['headingline2'

['headingline3']]]



2
DATAMINER Scripts
You accomplish tasks in DATAMINER with scripts. A script is a group of commands that tell DATAMINER what to do to the data records that you specify. These scripts have specific components that tell DATAMINER what functions to perform, what datasets to use, which record fields to select, and what calculations or data modifications you want to perform.

This chapter covers the following topics:

Page

Introduction to Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2Script Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4Execution Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.6Execution JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.7Script Readability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.8Adding Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.9INCLUDE Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.10OFFSET= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.11SCRIPT Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.12STATS Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.13VALIDATE= Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.14DATAMINER Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.15

DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts

Introduction to Scripts

Processing Modes DATAMINER has two script-processing modes:

AUTO Command There are two ways to specify the auto mode for your script:

• Use one of the shortcut commands, which automatically invoke the auto mode to control looping and dataset reading for you. These commands are described in Chapter 6, “Shortcut Commands.”

• Add the AUTO command to your script immediately after the INPUT= command, which defines the input dataset to DATAMINER. The INPUT= command is described in Chapter 3, “Input and Output Specification.”

The syntax for the AUTO command is

AUTO INPUT filename [BEGIN procname] [EOF procname]

where

filename is the ddname of the dataset specified by the INPUT= command.

The AUTO command tells DATAMINER to automatically process the input dataset. Functionally, using AUTO is the same as using the following task-mode script, which controls looping and record reading.

INPUT=dataset-type FILENAME=ddnameSTARTIT.

READ ddnameIF EOF ddname

GOTO ENDITENDIF

* Other script commands go below this line

GOTO STARTITENDIT.

Mode Description

Auto DATAMINER automatically reads the main input dataset (the one defined with the first INPUT= command) at the start of the script and writes to the main output dataset (the one defined with the first OUTPUT= command) at the end of the script. The script automatically loops back to the start to retrieve the next record and process the commands within the script.

Task You manually control I/O, specifying the reading and writing with commands in the script. You must direct the script to loop back to the start to retrieve each record and act on it.

This is the default operating mode.



BEGIN and EOF Procedures

As an option, you can use the BEGIN and EOF operands on AUTO to specify

• A procedure to execute before the main input dataset is opened (BEGIN)

• A procedure to execute when the end of the main input dataset is reached (EOF)

You use the PROC command to define these procedures. For details, see “PROC…[GOBACK]…ENDPROC Statements (Defining Procedures)” (page 8.8).

Script Example with BEGIN and EOF Procedures

The following example shows how to use the AUTO command’s BEGIN and EOF operands:

INPUT=VSAM FILENAME=EMPVSAM /* Input KSDS fileAUTO INPUT EMPVSAM BEGIN STARTIT EOF ENDIT* Main processing commands go here...

PROC STARTIT /* This is the start-up procedureMOVE 'READY' TO FIELDAENDPROC*PROC ENDIT /* This is the End-of-File procedureDISPLAY 'Final totals are ' TOTAL1 TOTAL2ENDPROC

Difference Between BEGIN/EOF and BEFORE/AFTER Timings

BEFORE INPUT and AFTER OUTPUT are timing commands. (See “Timing Commands,” page 8.15.) There is no difference between using these commands and the BEGIN/EOF procedures. They simply give you a choice of how to do a job. Of the two, BEFORE INPUT is probably quicker and easier to write than a BEGIN procedure, but the difference is minimal.

Multiple Input and Output Datasets

A DATAMINER script, including AUTO mode scripts, can include any number of input and output datasets. DATAMINER can read and write datasets sequentially or by key (including “skip-sequential” processing).

You normally place record and table field definitions directly after the INPUT= or OUTPUT= definitions to which they refer. See the section “Script Components” (page 2.4) for an example. An exception is if you define multiple datasets that have a common record field definition. In such cases, the record field needs to be defined only once, and you can prefix the field name with ddname: to specify the dataset when the field is referenced in the script.



Script Components

Introduction DATAMINER scripts have the following components:

• JCL statements. See “Script Example” (page 2.5) and “Execution JCL” (page 2.7).

• Shortcut commands

• Input and output dataset definitions

• Field (record, variable, table) definitions

• Commands

Shortcut Commands Each script optionally can have one or more shortcut commands, such as DUMP or COPY, which tell DATAMINER the primary purpose of the script. Scripts can copy, extract, delete, insert, and update information. The print and dump functions can be used with other functions or on their own. If the script does not have any shortcut commands in it, you must tell DATAMINER how to process each record.

Shortcut commands put DATAMINER into auto mode; therefore, you do not need, for example, to issue READ and WRITE commands to COPY a file.

Input and Output Dataset Definitions

DATAMINER needs to know which input datasets to use and which output datasets, if any, to produce. The input and output dataset statements may include parameters that define dataset type, block size, record length, limits on file size, and other dataset information.

Field Definitions You can specify record fields in (or table fields from) a dataset to use for the commands in the script. Each record field you define maps to a data field in the records of an input or output dataset. You can use the script to select specific fields in records or entire records. You do not need to define every field in the record—only those that your script uses. Record layouts can be INCLUDEd from a source library or from a COBOL copybook.You can label a record field using any name other than a reserved word. (A list of DATAMINER reserved words is on page 2.15.)

If you are processing complete records from the input dataset, you do not need to define individual record fields. DATAMINER has commands for selecting the records you need to process from the input dataset.

Variables You can also create user variables for storing values you assign, for example, the running total for a field. As with record fields, you cannot use a DATAMINER reserved word for a variable name.

Commands DATAMINER has several types of script commands that can be used to select records from the input dataset and to perform calculations and other data manipulations on fields in an output dataset.



Script Example The following lines comprise a basic example of a DATAMINER script. The lines starting with a slash (/) are typical JCL statements needed to run DATAMINER.

Notes on This Example

Each script component, such the COPY shortcut command and the INPUT= statement, are described in other chapters in this manual. The following notes are key points for you to remember:

• The lines starting with a slash (/) are typical JCL statements needed to run DATAMINER. The line starting with an asterisk (*) is a comment.

• The commands in the example starting with COPY tell DATAMINER what you want to do and what datasets you want to use. In this case, the script copies VSAMFILE to SEQFILE, creating a sequential dataset from a VSAM input dataset.

• The input dataset (VSAMFILE) and the output dataset (SEQFILE) are defined in DD statements in the JCL portion of the script. All the datasets used in the script must have a DD statement in the JCL. The dataset (ddname) in the DD statement must be specified by the FILENAME= operand on the INPUT= or OUTPUT= command. Also, the OUTPUT= statement must be placed after the INPUT= statement.

• After a record field named STATUS is defined, the script moves a literal value (1234)to this field in the output dataset. The input is unchanged.

• The first position in each record is referred to as position 1 unless you override that with an OFFSET= command. See “OFFSET= Command” (page 2.11) for details.

If you are doing an UPDATE, you only need to specify an input dataset because DATAMINER writes the updated record back to the input dataset. UPDATE does not create an output dataset.

//DMCOPY JOB (user),CLASS=A,MSGCLASS=A //COPY EXEC PGM=CSIDMBMD //STEPLIB DD DSN=dataminer.loadlib,DISP=SHR //SYSPRINT DD SYSOUT=* //VSAMFILE DD DSN=input.vsam.dataset,DISP=SHR //SEQFILE DD DSN=output.sequential.dataset,DISP=OLD //SYSIN DD * *

COPY INPUT=VSAM FILENAME=VSAMFILE OUTPUT=DISK FILENAME=SEQFILE STATUS 12,4,C MOVE '1234' TO STATUS /* //



Execution Sequence

Introduction DATAMINER analyzes the commands and automatically executes them in the same order as you enter them. Some commands such as MAXRCDS and FIRSTKEY can be entered anywhere in the script, while the position of other commands is important.

Command Sequence The sequence of elements in a script should be as follows:

• It is usual but not essential that any shortcut commands like COPY and EXTRACT appear near the start of the script.

• Datasets and fields must be defined before you use them. Each dataset definition (whether input or output) normally is followed by the field definitions for that dataset. For example, the MOVE operation in the previous script example sets a value in a field in the output dataset because the field’s definition immediately follows the OUTPUT= statement.

Effects of Command Sequences

Commands that act on your files are executed in the order that they appear in the script unless the execution order is changed by a command such as GOTO or PERFORM. (A GOTO command causes execution to skip to the command whose name is in the GOTO command, ignoring any intervening commands. PERFORM calls a procedure you defined in another part of the script.)

For example, the following code

IF FLAG EQ 'X'MOVE "ABC" TO TYPE

ENDIF

produces a different result from

MOVE "ABC" TO TYPEIF FLAG EQ 'X'ENDIF

Also, the command

MOVE '123' TO FLDA

followed by

MOVE '999' TO FLDA

produces results that are different from when these commands are reversed. The second command changes the value that is set by the first command.



Execution JCL

Introduction DATAMINER runs as an ordinary batch job. You need JCL to execute DATAMINER commands. The JCL statements you use provide information about the input and output datasets and printers you are using.

Example This example shows a standard set of JCL statements that you can modify and use in DATAMINER scripts.

The following is a typical JCL stream for z/OS:

Use the typical JCL above, suitably modified for your own dataset names and dataset types, to precede the command scripts shown below. You do not need an OUTFILE= DD statement if your script does not produce an output dataset (for example, if the script is only a PRINT, DUMP, or UPDATE run).

You need more DD statements if your script handles more datasets or produces more reports.

//DMJOB JOB (user),CLASS=A,MSGCLASS=A //STEP01 EXEC PGM=CSIDMBMD //STEPLIB DD DSN=dataminer.loadlib,DISP=SHR //SYSPRINT DD SYSOUT=* //INFILE DD DSN=input.sequential.dataset,DISP=SHR //OUTFILE DD DSN=output.sequential.dataset,DISP=OLD //SYSIN DD *



Script Readability

Introduction DATAMINER lets you use several words and symbols to make your script easy to read. DATAMINER generally ignores these words and symbols, so they do not affect your script.

Extra spaces (blanks) are always ignored.

Words That Are Always Ignored

DATAMINER always ignores these words:

• TO

• FROM

• BY

Symbols That Are Sometimes Ignored

DATAMINER ignores these symbols if they are not a required part of the command using them:

• ( )

• +

• -

• ,

• .

Examples: Ignored Symbols

You can define a field:

FLDA 20, 10, C

and DATAMINER ignores the commas.

You can specify fields to be selected for a basic report as

SELECT (NAME, ADDRESS, PHONE)

and DATAMINER ignores the parentheses.

Some older languages use “+” and “-” to denote a continuation of one command over several lines, and they use “.” to denote the end of a command. DATAMINER does not need any of these symbols and ignores them except where they are used in an arithmetic command such as TOTAL = AMOUNT + TAX.



Adding Comments

Introduction You can enter comments in a DATAMINER script, and comment out code, in several ways.

Comment Indicators The following table describes the indicators you can use to add comments in a DATAMINER script:

Examples Here are examples for each indicator type:

Indicator Description

* Type * as the first non-blank character on a line. It does not have to be in the first column. DATAMINER treats everything after the * on a line as a comment.

/* DATAMINER treats everything after /* on a line as a comment.

\ Type \ in the first column of a line. DATAMINER ignores the whole line completely, not even printing it on the script listing.

To ignore a multiline command, put a \ in the first column of every line.

? Type ? in the first column of a line. It suppresses the printing of the line in the script listing, but DATAMINER still executes the line.

To suppress a multiline command, put a ? in the first column of every line.

Indicator Example

* * UPDATE TOTAL AMT

/* The following example separates code from a comment:

ADD 1 TO COUNT /* INCREASE RECORD COUNTER

The next example inserts a comment in a command, which is continued on the following line and followed by another comment:

NEWVAL = OLDVAL + SALE /* ADD SALE TO VALUE+ TAX /* ADD TAX, TOO

\ \ POINT FILE1 TO BEGIN

? ? READ FILE1



INCLUDE Command

Description The INCLUDE command includes a DATAMINER script from another source member. It typically is used to include dataset definitions, but you can use it to include any valid DATAMINER input cards. You can use it to incorporate a COBOL copybook into a DATAMINER script.

Syntax The syntax for the INCLUDE command is

INCLUDE source_name

where

source_nameIs the name of the member or COBOL copybook that is to be included. The SYSLIB DD statement must specify the dataset from which the source is to be included.

Example The following example shows how to use the INCLUDE command:

INPUT=VSAM FILENAME=EMPFILE INCLUDE EMPLOYEE /* include employee COBOL copybook */



OFFSET= Command

Description The OFFSET command lets you change the “name” of the first byte of a record from the default of 1 to anything you want. By default, DATAMINER calls the first byte of a record “byte number 1” and counts from there.

The value you specify with the OFFSET command applies to all the field positions you refer to in your script, both before and after the OFFSET command statement.

Syntax The syntax for the OFFSET= command is

OFFSET={n | 1}

Examples The following example numbers the bytes starting from zero:

OFFSET=0

You can also use the OFFSET command when the record layout chart includes a four-byte record descriptor word at the beginning. DATAMINER ignores record descriptor words in its field definitions, so you can enter

OFFSET=5

Your DATAMINER field locations match those in your record layout chart.

The only validation that DATAMINER does on your OFFSET setting is to make sure it is numeric, so you can specify whatever positive number you want. You can put an OFFSET command in your script anywhere before the first SELECT command.



SCRIPT Command

Description The SCRIPT command turns the printing of your script at the system printer on and off. If the first command of your script is SCRIPT OFF, no script headings or script listing is printed.

Syntax The syntax of the SCRIPT command is

SCRIPT [ON | OFF]

where

ONIs the default and tells DATAMINER to list your script on the system printer as it executes.

OFFSuppresses the printing of your script on the system printer.



STATS Command

Description The STATS command tells DATAMINER where you want execution statistics printed, if at all.

Syntax STATS [Printer | Console | Both | None]

Only the first character of the argument needs to be entered. “Printer” turns off “Console,” and vice versa.

Example The file I/O statistics displayed at end-of-job include extra information such as the dataset ID from the DD statement (for example, ACCOUNT) and the dataset name (for example, XYZCO.ACCOUNTS.MASTER). Statistics are broken down by the type of I/O done for each dataset. For example,

35 RECORDS PRINTED ON PRINTER35 RECORDS DUMPED ON PRINTER35 RECORDS ADDED TO OUTFILE JM.FIXBLK.OUTPUT40 RECORDS READ FROM INFILE DMNR.KSDS.R10K0 FIELD VALIDATION ERRORS



VALIDATE= Command

Description The VALIDATE= command allows you to control how DATAMINER validates numeric fields during script processing. By default, DATAMINER validates all numeric fields before performing any operations such as IF, ONLY, or ADD on them.

Caution While a small performance improvement is gained by skipping validation with VALIDATE=N, any invalid data causes a program check, and any invalid change to the length of a record (for example, making a record larger during an update-in-place operation) could lead to either an operating system ABEND of the job or a corrupt output dataset. For this reason, setting VALIDATE= to anything other than Y should be done with great care. Example script 17 shows a better way of isolating records containing invalid data than setting VALIDATE=N. See “Ex. 17: COPY and PRINT Specific Records” (page 17.9).

Syntax The syntax for the VALIDATE= command is

VALIDATE={Y | N | L | D}

where

YSpecifies that DATAMINER perform all data validation checks. This is the default.

NSpecifies that DATAMINER perform no validation checks.

LSpecifies that DATAMINER perform record-length validation only.

DSpecifies that DATAMINER perform decimal (numeric-field) validation only.



DATAMINER Reserved Words

The following words are reserved by DATAMINER and must not be used as field names (record fields, user variables, table fields). Some words are used only within DATAMINER.

• @LBL • ABEND • ADD

• AND • BGNFIELD• BOTH

• CANCEL • CHUNDER • COPY

• DATACARDs

• DEFINE

• DELETE • DIVIDE • DROP

• DUMP • ELSE

• ENDFIELD• ENDIF • EXIT

• EXTRACT • FIRST • FIRST_RECORD

• FIRSTKEY• FREQ • FROM

• GOTO • HD • IF

• INPUT• INPUT_RECORD• INSERT

• INTO • KEEP • LAST

• LAST_RECORD• MAX_RECORDS

• MAXLNs• MAXRCDS• MAXRECDS

• MOVE • MULTIPLY• MXRCDS

• MXRECDS• NOHDR • NONUM

• NULLS• OFFSET• ONLY

• OR • OUTPUT• OUTPUT_RECORD

• PACK• PRINT

• PRTMV• RETURN_CODE• SELECT

• SET• SKIP• SPACE

• SPACES• START • STOP

• SUBTRACT• SUM• T0–T9

• TOT

• UNPACK

• UPDATE • VALIDATE• VALIDATION_ERRORS

• VALUES• WHERE



3
Input and Output Specification
You use script commands to tell DATAMINER what input and output datasets to use. These datasets must be defined before DATAMINER can process the data in them.


Page

DATAMINER Input and Output Datasets . . . . . . . . . . . . . . . . . . . . . . . . 3.2

INPUT= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3

OUTPUT= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7

DATACARDs Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.12

DATAMINER FOR Z/OS 7.1C User Reference Guide Input and Output Specification

DATAMINER Input and Output Datasets

Introduction DATAMINER needs information about the input and output datasets you want to use, such as what they are called, what type of device the datasets are on, and how big the records are. Once you specify a dataset, you can define record fields and table fields that map to data in the dataset’s records.

You specify datasets using the INPUT= command for input datasets and the OUTPUT= command for output datasets.

Both commands use the same parameters. The parameters are described after the commands.

Opening Datasets DATAMINER opens all referenced datasets at the start of a script. A referenced dataset is one that has an associated READ, WRITE, or DELETE command or that is included in a COPY, EXTRACT, or DELETE run as one of the main datasets.

Unused Datasets Unused datasets are datasets that are not referenced with the READ, WRITE, DELETE, POINT, AUTO, TABLE, COPY, or EXTRACT commands. This makes it easier to set up general-purpose scripts. If your script contains a WRITE for an output dataset but no write actually takes place, the script creates an empty output dataset. This means there are no obsolete versions of older output datasets left behind.



INPUT= Command

Description The INPUT= command defines an input dataset to DATAMINER. It gives DATAMINER as much information as it can from other places in your system, such as the VSAM catalog.

Additional parameters are available for the INPUT= command when you are using DB2. These parameters are explained in “INPUT= Command (DB2)” (page 15.4).

See “Special Note” (page 3.11) for additional information on how the record format, LRECL, and BLKSIZE parameters are set.

Syntax The syntax for the INPUT= command (except for use with DB2) is

INPUT={CARDs | TAPE | VSAM | DISK} FILENAME=ddname [LRECL=maxbytes] [BLKSIZE=numbytes]

[VARBLK | VARUNB | FIXED | UNDEF] [MAX=records]

where

{CARDs | TAPE | VSAM | DISK}Specifies the input dataset type and is mandatory.

Note: If you use INPUT=CARD, do not set the remaining operands. Also, you must include the DATACARD command in your script. See “DATACARDs Command” (page 3.12) for a script example.

FILENAME=ddnameSpecifies a ddname for the dataset. The ddname can be from one to eight characters long and must be defined on your system. The default name is INFILE.



[LRECL=maxbytes]Specifies the maximum record length (in bytes) for the dataset. See the following two tables for whether LRECL is required, optional, or disallowed, and for the default value.

Record Type LRECL= Required? Optional? Disallowed?

Comments

Fixed Required. Must be exact.

Variable Optional, but it is advisable to specify a number somewhat larger than the number of data bytes in longest record in the dataset.

If you specify an LRECL that is less than the longest record in your dataset, DATAMINER truncates long output records to this size. Any input records longer than this size will either cause the operating system to ABEND your job, or under certain conditions cause the operating system to overlay some of DATAMINER’s working storage.

When you specify an LRECL much larger than the actual longest record, there is a minor increase in CPU time.

VSAM Disallowed. DATAMINER uses the information in the VSAM catalog.



The default values used when you do not specify an LRECL are as follows:

Caution If BLKSIZE is not an exact multiple of LRECL, DATAMINER flags the mismatch as a serious error and terminates the job.

[BLKSIZE=numbytes]Specifies the block size for the dataset. It is not used by VSAM input datasets. We strongly recommend that you specify BLKSIZE for input datasets because doing so reduces the amount of memory and the amount of CPU time DATAMINER uses.

This parameter is recommended for sequential datasets.

Record Type Default Value for LRECL=

Card 80

Fixed-Length Input

The input BLKSIZE, but the records are still unblocked.

Variable-Length Output

The following table explains the possible default values for LRECL in the case of variable-length records:

DATAMINER pads variable-length input records with binary zeros to the maximum LRECL. DATAMINER treats any reference to a field outside the actual record that it read as though a record containing binary zeros in that field were read.

If... DATAMINER Creates a Variable-Length Record of This Length

Any Data Manipulation Command makes the record longer

The length generated by any Data Manipulation Command. See Chapter 10, “Data Manipulation Commands.”

No Data Manipulation Command makes the record longer

The input record’s LRECL value.

The script uses the EXTRACT shortcut command (see Chapter 6, “EXTRACT Shortcut Command”)

The smallest length to accommodate all the selected fields and literals.



The default values for BLKSIZE are as follows:

Caution If the BLKSIZE is not an exact multiple of LRECL, DATAMINER flags the mismatch as a serious error and terminates the job.

[VARBLK | FIXED | UNDEFined | VARUNB]Specifies the blocking of the dataset. The meaning of each follows:

VARBLK This parameter specifies that a tape or disk is a variable blocked dataset. DATAMINER automatically detects and processes spanned records.

FIXED This parameter specifies that the tape or disk dataset contains fixed length blocked or unblocked records. This is the default for CARD, TAPE, or DISK type datasets.

UNDEFinedThis parameter specifies that a tape or disk has an undefined dataset format. DATAMINER processes each physical block in the dataset as if it were a single logical record.

VARUNBThis parameter specifies that a tape or disk has a variable, unblocked dataset format.

[MAX=records]Specifies the maximum number of records to READ from the file. After DATAMINER READs the records number of records in the input dataset, DATAMINER reacts as if it reached the dataset’s end-of-file. MAX=50 means that only 50 records are read.

Example In the following example, the input is from a dataset called TAPEIN on tape, block size 3000 with records that have a maximum length of 100 fields.

INPUT=TAPE FILENAME=TAPEIN BLKSIZE=3000 VARBLK LRECL=100

If Value with INPUT= Is

Default Value for BLKSIZE=

CARDs 80

All other values 32K because DATAMINER cannot determine the blocksize of an input file without pre-reading it.

The dataset is processed properly even if the actual blocksize is not 32K.



OUTPUT= Command

Description The OUTPUT= command specifies an output dataset.

Additional parameters are available for the OUTPUT= command when you are using DB2. The additions are explained in “OUTPUT= Command (DB2)” (page 15.5).

Syntax The syntax for the OUTPUT= command is:

OUTPUT={TAPE | VSAM | DISK | PRINTER} FILENAME=ddname [LRECL=maxbytes] [BLKSIZE=numbytes]

[VARBLK | VARUNB | FIXED | UNDEF] [MAX=records] [REUSE]

where

{TAPE | VSAM | DISK | PRINTER }Specifies the type of output dataset and is mandatory for the OUTPUT= command.

Note: PRINTER applies only to Report Writer scripts.

FILENAME=ddnameSpecifies a ddname for the dataset. The ddname can be from one to eight characters long and must be defined on your system. The default name is OUTFILE.

LRECL=maxbytesSpecifies the maximum record length (in bytes) for the dataset. See the following two tables for whether LRECL= is required, optional, or disallowed, and for the default value for LRECL=.



The following table describes when to use the LRECL= operand.

Record Type

LRECL= Required? Optional? Disallowed?

Comments

Fixed Required. Must be exact.

Variable Optional but advisable to specify a number somewhat larger than the number of data bytes in longest record in the dataset.

If you specify an LRECL that is less than the longest record in your dataset, DATAMINER truncates long output records to this size. Any input records longer than this size will either cause the operating system to ABEND your job, or under certain conditions cause the operating system to overlay some of DATAMINER’s working storage.

When you specify an LRECL much larger than the actual longest record, there is a minor increase in CPU time.

VSAM Disallowed. DATAMINER uses the information in the VSAM catalog.



The default values used if you do not specify an LRECL are as follows:

Caution If the BLKSIZE is not an exact multiple of the LRECL, DATAMINER flags the mismatch as a serious error and terminates the job.

BLKSIZE=numbytesSpecifies the block size for the dataset. It is not used by VSAM output datasets.

This parameter is recommended for sequential datasets.

Record Type

Default Value for LRECL=

Fixed-Length Input

The input BLKSIZE, but the records are still unblocked.

Variable-Length Output

The following table explains the possible default values for LRECL in the case of variable-length records:

DATAMINER pads variable-length input records with binary zeros to the maximum LRECL. DATAMINER treats any reference to a field outside the actual record that it read as though a record containing binary zeros in that field were read.

If DATAMINER Creates a Variable-Length Record of This Length

Any Data Manipulation Command makes the record longer

The length generated by any Data Manipulation Commands. See Chapter 10, “Data Manipulation Commands.”

No Data Manipulation Command makes the record longer

The input record’s LRECL value.

The script uses the EXTRACT shortcut command (see Chapter 6, “EXTRACT Shortcut Command”)

The smallest length to accommodate all the selected fields and literals.



The default values for BLKSIZE= are as follows:

Caution If the BLKSIZE is not an exact multiple of the LRECL, DATAMINER flags the mismatch as a serious error and terminates the job.

[VARBLK | FIXED | UNDEFined | VARUNB]Specifies the blocking of the dataset. The meaning of each follows:

VARBLK This parameter specifies that a tape or disk is a variable blocked dataset. DATAMINER automatically detects and processes spanned records.

FIXED This parameter specifies that the tape or disk dataset contains fixed length blocked or unblocked records. This is the default for CARD, TAPE, or DISK type datasets.

UNDEFinedThis parameter specifies that a tape or disk has an undefined dataset format. DATAMINER processes each physical block in the dataset as if it were a single logical record.

VARUNBThis parameter specifies that a tape or disk has a variable, unblocked dataset format.

MAX=recordsSpecifies the maximum number of records to WRITE to the file. DATAMINER ignores any WRITEs issued to the file after the records number of records is written, although any other processing continues.

REUSE Resets the end pointer to zero for VSAM output datasets only. To use this parameter, the dataset must have been defined as reusable.

Is LRECL Specifiedfor the Output Dataset?

Default Value for BLKSIZE=

Yes The value of the output’s LRECL.

NoFor This Record Type The Default Is

Variable Length 32K

Fixed Length There is no default; an error results



Example 1 In the following example, the output dataset is a VSAM dataset named MYKSDS.

OUTPUT=VSAM FILENAME=MYKSDS

Example 2 In the following example, the output dataset is a variable-blocked dataset on a disk. It is called OUTDISK, and it has block size of 6000. LRECL defaults to 6000, and no more than 1000 records will be written to the file.

OUTPUT=DISK FILENAME=OUTDISK BLKSIZE=6000 VARBLK MAX=1000

Special Note If the record format (VARBLK | VARUNB | FIXED | UNDEF), LRECL, or BLKSIZE parameters are not specified on the INPUT= or OUTPUT= command, they will be augmented from the system catalog (if the dataset is cataloged) or from the DCB parameter (if specified) on the DD statement.



DATACARDs Command

Description The DATACARDs command comes after all the other commands in a script that is using card data input (INPUT=CARD). It is followed by the data cards, which in turn are followed by the script’s final /*.

Syntax The syntax for the DATACARD command is

DATACARDs

The lowercase ‘s’ is optional in the command.

Example 1 The following example show how to use the DATACARD command with data cards:

DATACARDS8KA9AA8K7**33DDD3**3*33END OF RECORD8KLSWAD6**34CCC3**3*348K7DEA6**35EEE3**3*358K7LFRA**33DDD3**3*33<other records>9WWWDRAF**99ZZZ9**9*99 /* Last record to mark the/* end of the data cards

The /* on the last line is written to the file if it is included for the DATACARD. The last line needs to be the last record to load, where it has Last record.

Example 2 The following example is a complete script:

INPUT=CARD EMPNO 1,6,C WORKDEPT 7,3,C PRINT SELECT EMPNO WORKDEPT*DATACARDS 123456ABC 777777ABC 888888XYZ 999999XYZ 000000ZZZ /*



4
Record Fields
DATAMINER scripts use record fields you define to contain data from records in an input dataset or datacard. The data in a record field can be inspected, changed, printed, or written to a record in an output dataset.

The following diagram shows how a record field is populated in a DATAMINER script. An INPUT= or OUTPUT= command defines the dataset to DATAMINER, and data in a record is mapped to the field in the script.

Note To load multiple data fields from each record into a table that you can search, see Chapter 12, “Table Fields.”


Page

Defining Record Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2

Arrays and Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.8

INPUT=

Record n

(OUTPUT=)

Data

Record Field

Dataset

DATAMINER FOR Z/OS 7.1C User Reference Guide Record Fields

Defining Record Fields

Introduction Record fields contain data from records in your datasets.

When specifying record fields, you do not need to provide definitions for any fields in your dataset’s records that your script does not use. In the case of a COPY or DUMP script, it is possible to process the datasets without needing any field definitions at all—all record fields are processed.

You can specify the records you want to use with record-selection commands. See “Record-Selection Commands” on page 9.1.

You can combine several fields into a single field. For example, you could combine the NAME, ADDRESS, and CITY fields into one field in your script called ADDRESS_ALL.

Syntax to Define a Record Field

You must define record fields immediately after the INPUT= or OUTPUT= statement that defines the dataset containing the fields.

The syntax for defining a record field is

recfieldname startpos length type [decimalplaces]

[OCCURS n TIMES [INDEX(ixname)]] [std-mask]

If the field will be used with the REPORT command, you can add the following operands to the field definition. (MASK is an alternative to std-mask.)

[MASK 'user-defined-mask']

[HEADING 'headingline1' ['headingline2' ['headingline3']]]

The fields in the above syntax statements are explained below.

recfieldnameIs the name you assign to the record field:

• It can be up to 32 characters long.

• It must begin with a letter or one of the following characters:

@ # _ $

• It can include letters, numerals, and the following characters:

@ # _ - $

• It is not case sensitive; for example, BALANCE, Balance, bAlAnCe, and balance refer to the same field.



Do not define recfieldname with the name of a DATAMINER command, parameter, system variable, or system constant. See “DataMiner Reserved Words” (page 2.15) for a list of reserved words.

Do not begin recfieldname with a hyphen.

Do not begin recfieldname with any of the following strings because DATAMINER’s own field names begin with them:

@#_

DMIN

DMIN_

If your script has multiple datasets, you can use the same fieldname for each dataset. To distinguish record fields with the same name in different datasets, use this syntax to refer to them (not to define them):

filename:recfieldname

where filename is the ddname for a dataset you specified using the FILENAME= operand on an INPUT= or OUTPUT= command.

For example

EMPRECS:EMPLOYEE#

Do not try to define the same fieldname twice for the same dataset.

startposIs the starting position of recfieldname. Record fields can overlap or have gaps between them. startpos is one of the following:

nA number for the nth byte of the record. For example, 32 specifies the 32nd byte of the record. The first byte’s position is 1 unless you have changed the offset; see “OFFSET= Command” (page 2.11).

* (asterisk)The byte following the previous field.

*+nThe nth byte higher than the byte following the previous field.

*-nThe nth byte lower than the byte following the previous field.



"The same location as the first byte of the previous field.

"+nThe nth byte higher than the first byte of the previous field.

"-nThe nth byte lower than the first byte of the previous field.

recfieldname2The same location as the first byte of another field, recfieldname2.

recfieldname2+nThe nth byte higher than the first byte of another field, recfieldname2.

recfieldname2-nThe nth byte lower than the first byte of another field, recfieldname2.

lengthIs the length of the field in bytes. Record fields can overlap or have gaps between them. See the table under the next argument for allowable lengths according to the field’s data type.

typeIs a character denoting the data type of the field, as follows:

Character Data Type Max Length (Bytes)

Comments

A Alphanumeric 32,767

C Character 32,767

B Binary 4 Treated as signed if 2 or 4 bytes long.

Treated as unsigned if 1 or 3 bytes long.

P Packed 16

N or Z Zoned 16

X Hexadecimal 8

V Variable-length character

N/A

D Date N/A For DB2 only.



[ decimalplaces ]Is the number of decimal places and is valid only for the numeric fields binary, packed, and zoned. The default is 0. If you specify a value, it must immediately follow the type operand.

[ OCCURS n TIMES ]Is the specification for a repeating record field that occurs n times per record file. The OCCURS keyword creates an array with n members. Be sure to see the INDEX (next), which is a sub-argument of OCCURS.

[ INDEX(ixname) ]Is the index to the array created with the OCCURS keyword, of which INDEX is a sub-argument. For information on using an array’s index, see “Arrays and Indexing” (page 4.8).

(ixname)Is the name of of the index, and it has the same naming requirements as recfieldname. For information on using an array’s index, see “Arrays and Indexing” (page 4.8).

[std-mask]Is one of five standard printing masks for numeric fields only (binary, packed, and zoned), as follows:

M0 The field is printed with leading zeroes suppressed and with the same number of decimal places you specified for the field.

M1 9(13)-

M2 9(11).99-

M3 Z,ZZZ,ZZZ,ZZZ,ZZ9- (Zero Suppress)

M4 ZZ,ZZZ,ZZZ,ZZZ.99- (Zero Suppress)

M5 $$$,$$$,$$$,$$$.99- (Floating $)

Formatting notes:

• A “9” in a mask is replaced with a number from the field. A “Z” in a mask is replaced with a number from the field unless the number in the field is a leading zero, in which case the Z is replaced with a space.

• If you request only two input digits by selecting masks M2, M4, or M5, the decimal point is output.

• The minus sign (-) prints only if the field is negative.

• If the number of decimal places in the field does not match the number of decimal places in the mask, DATAMINER aligns the field so that the decimal point in the field and the decimal point in the mask are in the right place. Extra decimal places are lost.



• You can calculate the field’s length on a printed report line as follows:

1. Start with the number of digits in the field

2. Add 1 for each comma (,) or period (.) that will appear in the line

3. Add 1 for the minus sign

4. Add 1 for the $ sign if you are using M5.

[ MASK 'user-defined-mask']Allows you to specify your own printing mask for this field instead of one of the standard masks. This operand is valid only when the field is used with the REPORT command in a Report Writer script. For details on defining a mask, see “Adding a User-Defined Mask to a Field Definition” (page 11.7).

[ HEADING 'headingline1' ['headingline2' ['headingline3' ]] ]Specifies up to three lines of a column heading to be used for this field with the REPORT command. (By default, the REPORT command uses recfieldname as the field’s column heading.) Alternatively, you can use the HEADING subcommand after the REPORT command to define a heading for this field. See Chapter 11, “Report Writer.”

Example Definition For each record field you use, you need to specify a name, a starting location in the record, a length, and a format. You can also specify a number of decimal places and a report formatting option. For example, the statement

BALANCE 32 7 P 2 M5

specifies the following values:

Parameters can be separated by commas or blanks; that is, the previous definition could also be entered as follows:

BALANCE 32, 7, P, 2, M5

Value Description

BALANCE The field name

32 The starting location of the field

7 The length of the field

P The field is a packed decimal

2 There are 2 decimal places

M5 Specifies formatting mask M5, which formats the number as U.S. dollars.



Example of Creating Overlapping Record Fields

The following example creates an eight-digit date field and then breaks it down into month, date, and year fields. There are many other ways the job could have been done.

DATE 32 8 ZMM " 2 ZDD * 2 ZYYYY * 4 ZCC YYYY 2 ZYY CC+2 2 Z

Example of Defining Five Fields

The following example defines five fields in a record: ACC_NO, BALANCE, FLAGS, NEW_BAL, and ADDRESS.

ACC_NO 1,8,CBALANCE 32,7,P,2,M5FLAGS 41,1,XNEW_BAL 50,9,P,2,M3ADDRESS 120,400,C

Here is an explanation of each field:

Field Description

ACC_NO Starts at position 1, has a length of 8, is for character data.

BALANCE Starts at position 32, has a length of 7, contains packed numeric data with two decimal spaces, and uses formatting mask M5 to format the number as U.S. dollars.

FLAGS Starts at position 41, has a length of one, and contains hexadecimal data.

NEW_BAL Starts at position 50, has a length of 9, contains packed numeric data with two decimal spaces, and uses formatting mask M3.

ADDRESS Starts at position 120, has a length of 400, and contains character data.



Arrays and Indexing

Introduction An optional argument (OCCURS) in a record field definition (page 4.2) allows you to create arrays. A sub-argument of OCCURS is INDEX, and it gives you more flexibility in referencing an array’s contents.

This section explains how to address the contents of arrays.

INDEXing by Subscripted Array Member Number

Whether or not you define an array with the INDEX sub-argument, you can always address the contents of an array by subscripting the number of the member.

The syntax for addressing an array member is

recfieldname(n)

where

recfieldnameIs the name of the record field that is an array.

nIs the number of the member of the array, from 1 to the number of members. That is, if you defined the array with

OCCURS 5 TIMES

n can be integers 1 through 5.

The following example creates a record field array named MONTH and that is three bytes long, is character data type, and OCCURS 12 times (that is, it has twelve members):

MONTH 3 C OCCURS 12 TIMES

You can address each member as follows:

MONTH(1)MONTH(2)MONTH(3)MONTH(4)MONTH(5)MONTH(6)MONTH(7)MONTH(8)MONTH(9)MONTH(10)MONTH(11)MONTH(12)



You could therefore assign values to the members of the array with the SET command. The results of these lines is exactly the same as the samples under “INDEXing by INDEX Value” (page 4.9) and “INDEXing by Bytes Offset” (page 4.10).

SET MONTH(1) = 'JAN' SET MONTH(2) = 'FEB' SET MONTH(3) = 'MAR' SET MONTH(4) = 'APR' SET MONTH(5) = 'MAY' SET MONTH(6) = 'JUN' SET MONTH(7) = 'JUL' SET MONTH(8) = 'AUG' SET MONTH(9) = 'SEP' SET MONTH(10) = 'OCT' SET MONTH(11) = 'NOV' SET MONTH(12) = 'DEC'

INDEXing by INDEX Value

The following example also creates a record field array named MONTH and that is three bytes long, is character data type, and OCCURS 12 times (that is, has 12 members): It also is INDEXed with an index named NUM:

MONTH 3 C OCCURS 12 TIMES INDEX(NUM)

To address the different members of the array in this method, set the value of NUM to the number (1 through 12) of the member to address. That is, to address an array member, there are two steps:

1. Set the value of the index to the number of the array member.

In the current example, the following line sets the index to the first member of the array:

SET NUM = 1

2. Address the record field array’s name without a subscript.

In the current example, you address the each member like this:

MONTH

The member of MONTH that is addressed depends on the value of NUM. Or generally, the member of the array that is addressed depends on the value of the index.

You could therefore assign values to the members of the array with the SET command. The results of these lines is exactly the same as the examples under “INDEXing by Subscripted Array Member Number” (page 4.8) and “INDEXing by Bytes Offset” (page 4.10).

SET NUM= 1SET MONTH= 'JAN' SET NUM= 2



SET MONTH= 'FEB' SET NUM= 3SET MONTH= 'MAR' SET NUM= 4SET MONTH= 'APR' SET NUM= 5SET MONTH= 'MAY' SET NUM= 6SET MONTH= 'JUN' SET NUM= 7SET MONTH= 'JUL' SET NUM= 8SET MONTH= 'AUG' SET NUM= 9SET MONTH= 'SEP' SET NUM= 10SET MONTH= 'OCT' SET NUM= 11SET MONTH= 'NOV' SET NUM= 12SET MONTH= 'DEC'

INDEXing by Bytes Offset

The following example also creates a record field array named MONTH and that is three bytes long, is character data type, and OCCURS 12 times (that is, has 12 members). It is also INDEXed with an index named NUM:


To address the different members of the array in this method, set the value of NUM to the zero-based offset of each member, and then subscript the index name to the record field name. That is, to address an array member, there are two steps:

1. Set the value of the index to the offset of the array member.

The first member of an array always has an offset of 0. Each additional member is offset by the length of each member of the array; in this example, that is 3 bytes.

In the current example, the 12 members start at the following offsets: 0, 3, 6, 9, 12, 15, 18, 21, 24, 27, 30, and 33.

2. Address the record field array’s name with the index name subscripted.


MONTH(NUM)




You could therefore assign values to the members of the array with the SET command. The results of theses lines is exactly the same as the the examples under “INDEXing by Subscripted Array Member Number” (page 4.8) and “INDEXing by INDEX Value” (page 4.9).

SET NUM= 0SET MONTH(NUM)='JAN' SET NUM= 3SET MONTH(NUM)='FEB' SET NUM= 6SET MONTH(NUM)='MAR' SET NUM= 9SET MONTH(NUM)='APR' SET NUM= 12SET MONTH(NUM)='MAY' SET NUM= 15SET MONTH(NUM)='JUN' SET NUM= 18SET MONTH(NUM)='JUL' SET NUM= 21SET MONTH(NUM)='AUG' SET NUM= 24SET MONTH(NUM)='SEP' SET NUM= 27SET MONTH(NUM)='OCT' SET NUM= 30SET MONTH(NUM)='NOV' SET NUM= 33SET MONTH(NUM)='DEC'



5
Variables, Literals, and System
Constants

DATAMINER scripts use variables to process data and create output. User variables are fields you define to store values needed by the script, such as constants, running totals, and the results of calculations. System variables are counters provided by DATAMINER. Their values are set programmatically by DATAMINER.


Page

Variable Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2Defining User Variables (DEFINE Command) . . . . . . . . . . . . . . . . . . . 5.3Arrays and Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8System Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.12Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.15System Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.18

DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants

Variable Types

Introduction Variables provide workspaces in memory to hold and manipulate data without altering it on a dataset. DATAMINER uses the following types of variables:

User Variables

User variables are ones that you create and assign values to in your DATAMINER scripts.

System Variables

System variable are ones that DATAMINER creates for you. They keep track of information that is especially helpful in conditional statements.



Defining User Variables (DEFINE Command)

Introduction User variables are one of the field types used in DATAMINER. A user variable can be used anywhere that a record field can be used. For example, you can add to it, add it to another field, move it, and compare it to another field. You can create a user variable to contain such things as running totals and a value from a header record to compare with a value from a trailer record.

You use the DEFINE command to create a user variable. Each variable is defined separately. Variables can be defined anywhere in the script before they are first used, although where they are defined makes no difference to how the script runs.

DATAMINER gives each user variable an “empty” value when it is defined, so there is no need for you to set a zero value before you use it. For example, a numeric user variable is set to zero.

Syntax The syntax for the DEFINE command is

DEFINE uservarname length type [decimalplaces]

[VALUE 'literal']


If the variable will be used with the REPORT command, you can add the following operands to the DEFINE statement. (MASK is an alternative to std-mask.)




uservarnameIs the name of the user variable you are defining.

uservarname can be up to 32 characters long.

uservarname must begin with a letter or one of the following characters:

@ # _ $

uservarname can include letters, numerals, and the following characters:

@ # _ - $



uservarname (the name itself) is not case sensitive; for example, BALANCE, Balance, bAlAnCe, and balance refer to the same field.

Do not define uservarname with the name of a DATAMINER command, parameter, system variable, or system constant. See “DataMiner Reserved Words” (page 2.15) for a list of reserved words.

Do not begin uservarname with a hyphen.

Do not begin uservarname with any of the following strings because DATAMINER’s own field names begin with them:

@#_

DMIN

DMIN_

Note: It is bad practice, and the result is unpredictable, to name a user variable with the same name as a record field or a table field.

lengthIs the length of the user variable in bytes. User variables can overlap or have gaps between them. See the table under the next argument for allowable lengths according to the variable’s data type.

typeIs a character that denotes the data type of the user variable, as follows:


Comments


C Character 32,767



P Packed 16

N or Z Zoned 16

X Hexadecimal 8


N/A

D Date N/A



[ decimalplaces ]Is the number of decimal places and is valid only for packed, binary, and zoned fields. The default is 0. It must directly follow the type.

[ VALUE 'literal' ]Is the specification of a literal value for the uservarname (the user variable being DEFINEd). literal must follow the rules for literals. See “Literals” (page 5.15). This value becomes the default for this value type.

[ OCCURS n TIMES ]Is the specification for a repeating variable that occurs n times per variable. The OCCUR keyword creates an array with n members. Be sure to see the INDEX (next), which is a sub-argument of OCCURS.


(ixname)Is the name of of the index, and it has the same naming requirements as uservarname. For information on using an array’s index, see “Arrays and Indexing” (page 5.8).


M0 (Default) The field is printed with leading zeroes suppressed and with the same number of decimal places for which the field is defined.

M1 9(13)-

M2 9(11).99-



M5 $$$,$$$,$$$,$$$.99- (Floating $)

Formatting notes:













[ HEADING 'headingline1' ['headingline2' ['headingline3' ]] ]Specifies up to three lines of a column heading to be used for this field with the REPORT command. (By default, the REPORT command uses uservarname as the field’s column heading.) Alternatively, you can use the HEADING subcommand after the REPORT command to define a heading for this field. See Chapter 11, “Report Writer.”

Initial Value User variables have the following initial values when the VALUE operand is not specified in a variable’s definition:

User variables hold their definition for the duration of the script. This means you can use them to keep running totals or to remember the contents of fields from one record to another.

Example 1 The following example defines Counter as a packed number, 8 bytes long, no decimal places.

DEFINE Counter,8,P

Value Type Default Value

Numeric 0

Hexadecimal 0

Character One or more spaces



Example 2 This example defines COMPANY as a character field, 32 characters long. This field appears in a Report Writer report under the heading

CUSTOMERNAME

(with CUSTOMER on the first heading line and NAME on the second).

DEFINE COMPANY,32,C HEADING=('CUSTOMER' 'NAME')

Example 3 The following example defines Difference as a four-byte binary number with five decimal places, printed as a currency amount, with two decimal places.

DEFINE Difference, 4,B,5,M5

Example 4 The following example defines LASTNAME as a 20-byte character user variable and assigns the literal value SMITH to it.

DEFINE LASTNAME 20 C VALUE 'SMITH'

Example 5 The following example defines NUMBER as a four-byte packed decimal user variable and assigns the literal value 100 to it.

DEFINE NUMBER 4 P VALUE 100



Arrays and Indexing

Introduction An optional argument (OCCURS) of the DEFINE command (page 5.3) allows you to create arrays. A sub-argument of OCCURS is INDEX, and it gives you more flexibility in referencing an array’s contents.





uservarname(n)

where

uservarnameIs the name of the user variable that is an array.


OCCURS 5 TIMES


The following example creates a user variable array named MONTH that is three bytes long, is character data type, and OCCURS 12 times (that is, it has 12 members):

DEFINE MONTH 3 C OCCURS 12 TIMES





You could therefore assign values to the members of the array with the SET command. The results of these lines is exactly the same as the examples under “INDEXing by INDEX Value” (page 5.9) and “INDEXing by Bytes Offset” (page 5.10).



The following example also creates a user variable array named MONTH that is three bytes long, is character data type, and OCCURS 12 times (that is, it has 12 members). It also is INDEXed with an index named NUM:

DEFINE MONTH 3 C OCCURS 12 TIMES INDEX(NUM)




SET NUM = 1

2. Address the user variable array’s name without a subscript.


MONTH


You could therefore assign values to the members of the array with the SET command (see below). The results of these lines is exactly the same as the examples under “INDEXing by Subscripted Array Member Number” (page 5.8) and “INDEXing by Bytes Offset” (page 5.10).

SET NUM= 1SET MONTH= 'JAN'



SET NUM= 2SET MONTH= 'FEB' SET NUM= 3SET MONTH= 'MAR' SET NUM= 4SET MONTH= 'APR' SET NUM= 5SET MONTH= 'MAY' SET NUM= 6SET MONTH= 'JUN' SET NUM= 7SET MONTH= 'JUL' SET NUM= 8SET MONTH= 'AUG' SET NUM= 9SET MONTH= 'SEP' SET NUM= 10SET MONTH= 'OCT' SET NUM= 11SET MONTH= 'NOV' SET NUM= 12SET MONTH= 'DEC'


The following example also creates a user variable array named MONTH and that is three bytes long, is character data type, and OCCURS 12 times (that is, it has 12 members). It also is INDEXed with an index named NUM:

DEFINE MONTH 3 C OCCURS 12 TIMES INDEX(NUM)

To address the different members of the array in this method, set the value of NUM to the zero-based offset of each member and subscript the index name to the user variable name. That is, to address an array member, there are two steps:




2. Address the user variable array’s name with the index name subscripted. In the current example, you address the each member like this:

MONTH(NUM)




You could therefore assign values to the members of the array with the SET command. The results of theses lines is exactly the same as the the examples under “INDEXing by Subscripted Array Member Number” (page 5.8) and “INDEXing by INDEX Value” (page 5.9).




System Variables

Introduction System variables are one of the field types used by DATAMINER. These fields are DATAMINER internal counters and can be used in any way in your script. You can query them and update them (although updating some of them may not be a meaningful thing to do).

Some system variables have commands to set their initial value (for example, MAXRCDS=200 sets the value of MAX_RECORDS). If you want to change the value of these variables as your script is running, you should use the Data Manipulation Commands to change them. See Chapter 10, “Data Manipulation Commands.”

There are also system constants that can be referred to in your script.

Many of the system variables are used only with the main input and output datasets. For example, in a COPY operation, the main input dataset is the dataset being copied from, and the main output dataset is the dataset being copied to.

Example The following example uses the INPUT_RECORD system variable:

IF INPUT_RECORD > 500 …

This example indicates that the commands in the IF statement are to be run only on the 501st and later input records.

Variables List The DATAMINER system variables are described in the following table.

Variable Description

DMIN-01 DMIN-01 is a halfword binary field that is randomly set to 0 or 1. It is set every time your script returns to the top to retrieve another record or whenever you execute the RANDOMIZE command.

DMIN-RANDOM DMIN-RANDOM is a four-byte signed binary field that contains a random number between roughly -2,000,000,000 and +2,000,000,000. You can use it anywhere in your script. It is calculated every time your script returns to the top of the script to retrieve another record or whenever the RANDOMIZE command is executed. DMIN-RANDOM does not contain the same value if you rerun your script. It provides a useful way to generate random data to put in a test file. The HIDE and CLOAK commands provide the same capability.



DMIN-YN DMIN-YN is a one-byte character field that is randomly set to Y or N. It is set every time your script returns to the top to retrieve another record or whenever you execute the RANDOMIZE command.

FIRST_RECORD The first record from the main input dataset that you want to process, set by the FIRST command

INPUT_RECORD The number of the currently processed record from the main input dataset. The first record is record number 1. Skipping records in your script does not stop INPUT_RECORD from being updated. For example, if you skip record number 1000, the next record you read is record number 1001.

LAST_RECORD The last record from the main input dataset that you want to process, set by the LAST command

MAX_RECORDS The maximum number of records you want to write to the main output dataset, set by the MAXRCDS command.

OUTPUT_RECORD The number of the next record that is written to the main output dataset. If you skip writing a record to the main output dataset, OUTPUT_RECORD is not updated. For example, if you skip writing record number 1000, the next record is also record 1000. For this reason, OUTPUT_RECORD may not be the best system variable to use to decide on which records to skip.

PARM-DATA A variable used to pass the EXEC PARM information into your script. It is 100 characters long and padded with spaces.

PARM-LENGTH A four-byte binary variable set to the length of the data passed into DATAMINER on the EXEC PARM parameter.

PARM-REGISTER A four-byte binary variable set to the address of the parameter list passed into DATAMINER through R1 at the start of execution.

RETURN_CODE Allows you to set your own return code from your script. That means you can identify your own errors or suppress non-zero return codes that DATAMINER generates.

SYSDATE The date in MM/DD/YY format. All date/time system variables are set at the start of the script.

SYSDATE-JULIAN The date in YYYYDDD format. All date/time system variables are set at the start of the script.

SYSDATE-LONG The date in MM/DD/YYYY format. All date/time system variables are set at the start of the script.

SYSTIME Local time in HH.MM.SS format. All date/time system variables are set at the start of the script.




T0–T9 The internal total (accumulator) fields are eight-byte, packed decimal fields with no decimal places. You can use them to keep running totals of whatever you want.

VALIDATION_ERRORS This is a count of field validation errors that have occurred in your script. DATAMINER validates every numeric field it uses (unless you tell it not to with the VALIDATE=NO command) and keeps a total of how many errors it finds. It may find multiple errors in any given record, and so the count may exceed the number of records in a dataset.




Literals

Introduction This section lists and describes the literals used in scripts.

A literal is a group of characters or a number that you want to move into a record or compare with a field in a record. You can use either single quotation marks (') or double quotation marks (") to enclose a character literal. Numeric literals can be specified simply as numbers without quotes, such as 12 or -15 or 27.65. They do not need to have the same number of decimal places as the field with which they are being used. A non-numeric literal must start and end with the same type of mark.

There are several types of literals. In this manual, wherever a reference is made to “literal,” it means that you can use any type of literal.

Literals cannot be split across lines.

Character Use character literals for words, names, and account numbers for example. Specify a character literal by putting its value in quotation marks such as 'ABC'. The literal can contain any characters you want. You can put a quotation mark inside a literal by enclosing the literal in the other kind of quotation mark. For example, "SUZIE'S DINER" or 'LOUIS "SATCHMO" ARMSTRONG'.

Packed Decimal Use packed-decimal literals to keep numeric data on a dataset. You specify a packed-decimal literal as nnn or P'nnn', where nnn is any decimal number up to 31 digits long.

For example:

34343434

or

P'1234.54'

or

-126.375

The literal does not need to be the same length or have the same number of decimal places as the other fields or variables with which it is being used. If you move a 3-digit number into an 8-byte field, it arrives with all the leading zeroes and decimal places in place.

Packed-decimal literals can have a plus or minus sign in front of them, such as -23. If you put in a “-” sign, DATAMINER puts the sign X'D' on the end of the number. If you put in a “+” sign DATAMINER makes the number positive with a X'C' on the end of the number. If you do not put in a “+” sign, DATAMINER puts an X'F' on the end of the number.



You can put a decimal point in a numeric literal. The decimal point in the literal is aligned with the decimal point in the field definition. For example, if you define WEIGHT to have three decimal places and MOVE 12.5 to WEIGHT, the value of WEIGHT is set to 12.500.

If you try to compare a packed-decimal literal with a field that does not contain a valid packed decimal number, DATAMINER treats the comparison as FALSE.

The hardware regards any string of numeric digits with A, B, C, D, E or F in the low order half-byte as valid. Even though A, B, and E signs cannot occur as the result of an arithmetic instruction, DATAMINER also regards them as valid. DATAMINER, however, does not generate A, B, or E signs itself.

Zoned Decimal Use zoned decimal literals for numbers that never, or rarely, change, such as account numbers. Zoned decimal literals are similar to packed decimal literals except for the way the number is stored in the dataset. Specify a zoned decimal literal as follows:

Z'nnn'

where

nnnIs any decimal number up to 15 digits long.

For example:

Z'567123'

All notes about packed decimal literals apply to zoned decimal literals, too.

Hexadecimal Use hexadecimal literals for flags and other technical pieces in records. Specify a hexadecimal as follows:

X'nnnn'

where

nnnnIs any even number of hexadecimal digits (0–9, A–F). Hexadecimal literals cannot contain decimal places.

For example:

X'1FA2'



Binary Use binary literals for fixed-point binary numbers. Specify a binary literal as follows:

B'nnn'

where

nnnIs any decimal number that DATAMINER converts to binary for you. Binary literals can contain signs and/or decimal places. Two- and four-byte binary numbers are treated as signed; one- and three-byte binary numbers are treated as unsigned.

For example:

B'3214'

or

B'-23.8999'

Numeric Use numeric literals to specify numbers, with or without signs or decimal places. They are created in the same format as the field with which they are being used. For example, if the numeric literal is being moved to a packed decimal record field or user variable, the literal is created as a packed decimal. A numeric literal can be between minus and plus 2,000,000,000.

For example:

MULTIPLY PRICE BY 1.075

When you use a literal with a binary, zoned, or packed field or variable, you do not need to specify the type of literal you are moving. Simply specify the number and DATAMINER creates the right type.

For example:

MOVE 0 TO BALANCE

is the same as

MOVE P'0' TO BALANCE



System Constants

DATAMINER has a number of system constants that you can refer to in your script.

Do not modify these system constants because they are used internally by DATAMINER, and the effect of changing them is unpredictable.

Constant Description

SPACES

or

BLANKS

A string of 256 spaces that you can use in MOVE, IF, and Record-Selection Commands.

LOW-VALUES

or

NULLS

A string of 256 nulls (X'00') that you can use in MOVE, IF, and Record-Selection Commands.

EOF A constant value of EOF (end of file).

HIGH-VALUES 16 bytes of X'FF'.

NUMERIC For use in IF commands, as in

IF A IS NUMERIC



6
Shortcut Commands
Shortcut commands are the usual way to perform most tasks with DATAMINER. Shortcut commands put DATAMINER into auto mode, which causes your script to loop for each record to be processed.

The HD, MAXLN=, and TOT subcommands modify printing when the SELECT subcommand is used with the PRINT command for standard printing. With standard printing, DATAMINER controls the formatting of column headings.

Note To fully control report formatting, use the DATAMINER Report Writer, which is invoked when you use the REPORT command instead of the SELECT command to specify fields to be printed. See Chapter 11, “Report Writer.”


Page

Shortcut Commands Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2COPY Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3UPDATE Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5EXTRACT Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.6PRINT Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.8DUMP Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.12DELETE Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.14HD Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.15MAXLN= Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.16SELECT…[WHERE] Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . 6.17TOT Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.20

DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands

Shortcut Commands Overview

Introduction Shortcut Commands provide the simplest way to use DATAMINER. They are a shorthand way to tell DATAMINER the main purpose of what your script will do with the input dataset. You can

• COPY it

• UPDATE it

• EXTRACT from it

• PRINT it

• DUMP it

• DELETE records from it

• Combine some of these functions

What Makes a Shortcut Command

A Shortcut Command puts DATAMINER into auto mode to loop through a script for each record in the input dataset. Each record is read automatically. See “Processing Modes” (page 2.2).

Note Except for UPDATE, the Shortcut Commands do not use parameters.

Constraints You can do only one of COPY, UPDATE, and EXTRACT. If you do not specify any of these, DATAMINER does not automatically produce an output dataset (although you can use WRITE commands to create output records yourself). If you have entered a PRINT or DUMP command, DATAMINER prints or dumps the output dataset or, if there is no output dataset, it prints or dumps the input dataset.

If you specify both PRINT and DUMP, the print report line prints, followed by the dump of the record. Because the report and the dump are intermingled, this is a useful function for problem solving but not suitable for production work.



COPY Shortcut Command

Description The COPY Shortcut Command copies the input dataset to the output dataset. You use the INPUT= command (page 3.3) to specify which dataset is the source, and you use the OUTPUT= command (page 3.7) to specify which dataset is the destination. You can select which records to copy or not to copy using the record-selection commands described in Chapter 9, “Record-Selection Commands.”

You can use the MAXRCDS= command (page 9.18) to set the maximum number of records to COPY.

You also specify dataset format or recording medium during the copy. For example, you can change the records as they are copied and the changes are applied to the output dataset.

You can also change the dataset format or recording medium during a copy. For example, you can copy a VSAM KSDS to a variable blocked tape dataset.

Each record in the output dataset is a replica of the matching record of the input dataset unless you make changes to the record in the input dataset.

Syntax The syntax for the COPY Shortcut Command is

COPY

Other Requirements Copy functions create output datasets and require that an output dataset be defined in the JCL and in the script. See “OUTPUT= Command” (page 3.7).

If your output dataset is VSAM, the dataset must exist (even if it is empty) before you copy something into it.

If you use COPY to change the format of records from variable length to fixed length, every record in the output dataset becomes the same size and is either truncated or extended with low values to make it the right size as specified in the LRECL of the output dataset. If the output record is longer than the LRECL of the output dataset defined in the OUTPUT= command, DATAMINER truncates the record to match the LRECL parameter.

Alternative Commands

DATAMINER copies the entire input record to the output record before applying any updates, so there is no need for MOVE commands to move individual fields to the output record. If you want to copy only selected fields, use EXTRACT instead of COPY.



COPY Example 1 The following example copies all records from from the EMPVSAM dataset to the EMPESDS dataset:

COPY Example 2 The following example copies only records containing employees in department D11:

COPY /* Copy INPUT=VSAM FILENAME=EMPVSAM /* Input KSDS file OUTPUT=VSAM FILENAME=EMPESDS /* Ouput ESDS file

COPY /* Copy INPUT=VSAM FILENAME=EMPVSAM /* Input KSDS file WORKDEPT 35,3,C /* Define department field OUTPUT=VSAM FILENAME=EMPESDS /* Ouput ESDS file WHERE WORKDEPT = 'D11' /* Copy department D11 records



UPDATE Shortcut Command

Description The UPDATE Shortcut Command changes records in their original location on a VSAM KSDS or in a sequential input dataset. You can change fields or put extra fields on the end of a KSDS record, for example.

You can update as many records as you want, and you can use commands and conditional statements to select particular records. (See Chapter 9, “Record-Selection Commands,” and Chapter 8, “Conditions and Flow Control.”) For example, you can select only records with an account balance of $10,000 or more and leave all the other records alone.

Update functions make changes to the input dataset and do not create output datasets, so you must define only the input dataset in the script.

Only records that DATAMINER updates are rewritten; if no changes are made to a record, it is not rewritten.

Syntax The syntax for the UPDATE Shortcut Command is

UPDATE

UPDATE Example The following example increase salaries for all employees by 5 percent in department D11:

Other Requirements You are not allowed to change the length of a record being updated in place in a sequential dataset. This is a restriction imposed by the operating system. If you try to change the length of a record in a sequential dataset, DATAMINER issues an error message telling you which record it has not updated. It applies any updates that do fit inside the original record length and continues processing the remainder of the dataset.

UPDATE /* Update INPUT=VSAM FILENAME=EMPVSAM /* Input KSDS file WORKDEPT 35,3,C /* Define department field SALARY 73,5,P,2 /* Define salary field

WHERE WORKDEPT = 'D11' /* Update department D11 recordsSALARY = SALARY * 1.05 /* Increase salary by 5%



EXTRACT Shortcut Command

Description The EXTRACT Shortcut Command is similar to COPY except that the output dataset contains only fields that you specify with the SELECT (page 6.17) or MOVE (page 10.4) commands. The fields you specify with SELECT are added to the output record beginning at byte 1 regardless of where they are located in the input dataset. They are processed in the order you specify with SELECT, and they are appended to one another in the output record. (Space is not inserted between the extracted fields.) Field definitions are not needed for the output dataset.

Alternatively, the MOVE command can be used if the field definitions are included below the OUTPUT= command. In this case, you move fields from the input dataset to the output dataset, and their original positions are maintained in the output.

You can use the MAXRCDS= command (page 9.18) to set the maximum number of records to process.

Syntax The syntax for the EXTRACT Shortcut Command is

EXTRACT

Other Requirements Extract functions create output datasets and require an OUTPUT= dataset definition in the script.

General Examples EXTRACT is useful for creating datasets to send to external service providers without sending them all the information about your customers. For example, a credit card company can use EXTRACT to create a dataset containing customer name, card number, and expiry date to send to the company that embosses the credit cards.

You can also use EXTRACT to change the order of fields in a record, insert a new field, insert a literal into a record, or extend a field.

Script Example 1: Using SELECT

The following script uses EXTRACT with SELECT to extract each employee’s first name, last name, and phone number to a new dataset:

EXTRACT /* Extract selected fieldsINPUT=VSAM FILENAME=EMPVSAM /* Input KSDS file EMPNO *,6,C /* Employee number FIRSTNME *,12,C /* First name MIDINIT *,1,C /* Middle initial LASTNAME *,15,C /* Last name WORKDEPT *,3,C /* Department number'PHONENO *,4,C /* Phone number OUTPUT=VSAM FILENAME=EMPESDS /* Ouput ESDS file

SELECT FIRSTNME,LASTNAME,PHONENO /* Extract only selected fields



00000000 40400000

00000000 40400000

00000000 40400000

00000000 40400000

Script Example 2: Using MOVE

The following script uses EXTRACT with MOVE to extract each employee’s first name, last name, and phone number to the same fields in a new dataset.

In the associated dump, notice how null hex values were left in the place of the EMPNO, MIDINIT, and WORKDEPT fields in the input dataset.

EXTRACT /* Extract selected fieldsINPUT=VSAM FILENAME=EMPVSAM /* Input KSDS fileOUTPUT=VSAM FILENAME=EMPESDS /* Ouput ESDS file

EMPNO *,6,C /* Employee numberFIRSTNME *,12,C /* First nameMIDINIT *,1,C /* Middle initialLASTNAME *,15,C /* Last nameWORKDEPT *,3,C /* Department number'PHONENO *,4,C /* Phone number

MOVE EMPVSAM:FIRSTNME TO EMPESDS:FIRSTNMEMOVE EMPVSAM:LASTNAME TO EMPESDS:LASTNAMEMOVE EMPVSAM:PHONENO TO EMPESDS:PHONENO

0000C3C8 D9C9E2E3 C9D5C540 404000C8 C1C1E240 40404040 40404040 *......CHRISTINE .HAAS 00F3F9F7 F8 * ...3978

0000D4C9 C3C8C1C5 D3404040 404000E3 C8D6D4D7 E2D6D540 40404040 *......MICHAEL .THOMPSON 00F3F4F7 F6 * ...3476

0000E2C1 D3D3E840 40404040 404000D2 E6C1D540 40404040 40404040 *......SALLY .KWAN 00F4F7F3 F8 * ...4738

0000D1D6 C8D54040 40404040 404000C7 C5E8C5D9 40404040 40404040 *......JOHN .GEYER 00F6F7F8 F9 * ...6789



PRINT Shortcut Command

Description The PRINT Shortcut Command prints the contents of records, as follows:

The length of the print line depends entirely on the fields that you select to print. DATAMINER automatically spaces the fields across the print line and, if you do not create your own headings, it puts a heading at the top of each page containing the names of the fields in the report.

If you ask to have more fields printed than can fit in the print line, DATAMINER prints only the fields that do fit. DATAMINER prints as much of the last field as will fit on the line.

PRINT Shortcut Commands by themselves do not create output datasets—they only print results of the script to the printer.

If you use PRINT with the UPDATE command, only the updated records are printed. When used with the INSERT command, all records are printed.

PRINT and DUMP can be used in the same script and a print line and a dump of the output record will be produced for each record in the dataset. The PRINT and DUMP output is mixed together, so this option is used mainly for program testing. More sophisticated reports can be printed using the DATAMINER Report Writer.

Standard, unmodified printouts have the following features:

• A heading and one blank line printed at the top of each sheet.

• Up to 58 data lines (assuming 60 lines per page). A data line consists of up to 132 bytes of data starting in column 1 and continuing to as many lines as necessary. All unreferenced positions are space filled. The MAXLN= and HD subcommands can be used to modify printing.

• At end of data, the trailers print after one blank line.

• If no PRINT is requested, the trailers still print.

• If a TOT (total) line is requested, the total line prints two lines below the last data line, then the trailers print two lines below the total line.

Using PRINT with ... Prints from ...

COPY Output datasets

EXTRACT

UPDATE Input datasets



Syntax The syntax for the PRINT Shortcut Command is

PRINT

Other Requirements You must use one or more SELECT subcommands (page 6.17) to specify the fields that you want to print. You can include literals in your print line.

Note To use the DATAMINER Report Writer, you must use the REPORT command instead of the SELECT command to specify fields for printing. See Chapter 11, “Report Writer,” for details.

Also, the HD, MAXLN=, and TOT subcommands modify printing output only when SELECT is used with PRINT. These subcommands do not apply to Report Writer scripts.

Using the PRINT and SELECT commands together is the simplest way to create a basic report. DATAMINER lays out the report for you using field names as the column headings for your data.

DATAMINER can automatically print reports from just the following elements:

• The PRINT Shortcut command

• The INPUT= command to define the input dataset (page 3.3)

• Field definitions (page 4.1)

• The SELECT command (page 6.17) to specify which fields to print

DATAMINER responds by printing values of the SELECTed fields in columns headed by the field names. Examples of a script and its output follow.

Example 1 Script The following example script creates a report showing the outstanding balance of all the accounts in your BILLING dataset.

PRINTINPUT=VSAM FILENAME=BILLINGACCT-NO 1 8 CNAME 9 32 CADDRESS 100 55 CBALANCE 240 10 P 2SELECT (ACCT-NO NAME ADDRESS BALANCE)

Each line in this script is explained below.

PRINTTells DATAMINER that the purpose of the script is to print. PRINT also puts DATAMINER into AUTO mode, which makes DATAMINER loop through the script for each record in the dataset.



INPUT=VSAM FILENAME=BILLINGIdentifies the input dataset as a VSAM dataset named BILLING.

ACCT-NO 1 8 CDefines a field in the input dataset named ACCT-NO. This field starts in the first byte of the record (1), is eight bytes long (8), and is a character data type (C).

NAME 9 32 CDefines a field in the input dataset named NAME. This field starts in the ninth byte of the record (9), is thirty-two bytes long (32), and is a character data type (C).

ADDRESS 100 55 CDefines a field in the input dataset named ADDRESS. This field starts in the 100th byte of the record (100), is fifty-five bytes long (55), and is a character data type (C).

BALANCE 240 10 P 2Defines a field in the input dataset named BALANCE. This field starts in the 240th byte of the record (240), is 10 bytes long (10), is a packed-decimal data type (P), and has two decimal places (2).

SELECT (ACCT-NO NAME ADDRESS BALANCE)Tells DATAMINER that the fields to print are ACCT-NO, NAME, ADDRESS, and BALANCE.

Example 1 Output In the above example script, DATAMINER reads the BILLING dataset sequentially and prints a tabular report with each line containing the required fields. The report created by the above script looks like this:

DATAMINER automatically does the following:

• Prints the field names as headings across the page, each heading as long as the length of its field and separated by three spaces.

• Prints the field values under the headings.

• Reprints headings at the top of subsequent pages.

Narrowing What Is Printed

You can create a report of records that meet certain criteria very easily using the ONLY and/or SKIP commands (pages 9.16 and 9.14, respectively).

• ONLY (or WHERE) means “Print only records that meet this (these) condition(s).”

ACCT-NO NAME ADDRESS BALANCE12345678 BLOGGS INC 47 MAIN ST 426.6533333333 JONES LLC 96 ANYWHERE ST 12,217.3244444444 ALBRECHT 62 DURER AVE 0.00



• SKIP means “Do not print records that meet this (these) condition(s)”

In the example script above, either of the following commands added will cause DATAMINER to print just the records whose balance is greater than $1,000.00:

ONLY BALANCE > 1000

or

SKIP BALANCE <= 1000

Example 2 Script The following example prints the first name, last name, and salary for each employee in department D11. The SELECT command (page 6.17) specifies the fields to be printed.

Example 2 Output The output from the above script could look something like this:

Note You can use the MAXRCDS= command (page 9.18) to set the maximum number of records to print.

PRINT /* Print selected fields INPUT=VSAM FILENAME=EMPVSAM /* Input KSDS file EMPNO *,6,C /* Employee number FIRSTNME *,12,C /* First name MIDINIT *,1,C /* Middle initial LASTNAME *,15,C /* Last name WORKDEPT *,3,C /* Department number'PHONENO *,4,C /* Phone number SALARY 73,5,P,2 /* Define salary field

SELECT FIRSTNME,LASTNAME,SALARY /* Print only selected fields WHERE WORKDEPT = 'D11' /* Print department D11 records

FIRSTNME LASTNAME SALARY IRVING STERN 32250.00 BRUCE ADAMSON 25280.00 ELIZABETH PIANKA 22250.00 MASATOSHI YOSHIMURA 24680.00 MARILYN SCOUTTEN 21340.00 JAMES WALKER 20450.00 DAVID BROWN 27740.00 WILLIAM JONES 18270.00 JENNIFER LUTZ 29840.00



DUMP Shortcut Command

Description The DUMP Shortcut Command is for programmers and other computer staff. It allows you to analyze the contents of records in a dataset. It dumps the contents of the main input or output dataset as follows:

The dataset is dumped both in hexadecimal and in character formats. The dump is formatted in the same way as a program dump with an offset in the lefthand column, then 32 bytes (X'20') of hexadecimal data, and then a character translation of the data.

A heading line that shows its length, its position in the input dataset, and its position in the output dataset precedes each dumped record.

Note Even if there is no output dataset, you can use PRINT or DUMP and modify the input records with MOVE and other field manipulation commands. This lets you see what a dataset will look like if certain changes are made to it.

DUMP commands by themselves do not create output datasets; they only dump results to the printer.

PRINT and DUMP can be used in the same script, and a print line and a dump of the output record are produced for each record in the dataset. The PRINT and DUMP output is mixed together so this option is used mainly for program testing.

If you are interested in what is in only a few fields, the SHOW Shortcut Command may be more useful. See Chapter 14, “Troubleshooting Commands,” for information on SHOW and other commands you can use to analyze scripts.

Syntax The syntax for the DUMP Shortcut Command is

DUMP

Using DUMP with ... Dumps from the ...

COPY Output dataset

EXTRACT

UPDATE Input dataset



RECORD NUMBER -

3 6 9RECORD NUMBER - 3 6 9RECORD NUMBER - 3 6 9

DUMP Example The following example dumps all records containing employees in department D11:

The output could look something like this:

DUMP /* Dump INPUT=VSAM FILENAME=EMPVSAM /* Input KSDS file WORKDEPT 35,3,C /* Define department field

WHERE WORKDEPT = 'D11' /* Dump department D11 records only

IN= 5,OUT= 1 LRECL= 100 1 F0F0F0F0 F6F0C9D9 E5C9D5C7 40404040 4040C6E2 E3C5D9D5 40404040 40404040 *000060IRVING FSTERN *3 4040C4F1 F1F6F4F2 F3F1F9F7 F360F0F9 60F1F4D4 C1D5C1C7 C5D94000 10D4F1F9 * D1164231973-09-14MANAGER .~M19*5 F4F560F0 F760F0F7 00373334 1C000390 200C0002 58000C00 00000000 00000000 *45-07-07.~~~~.~°~~.~ì.~.........*7 00000000 *.... * IN= 17,OUT= 2 LRECL= 100 1 F0F0F0F1 F5F0C2D9 E4C3C540 40404040 404040C1 C4C1D4E2 D6D54040 40404040 *000150BRUCE ADAMSON *3 4040C4F1 F1F4F5F1 F0F1F9F7 F260F0F2 60F1F2C4 C5E2C9C7 D5C5D900 10D4F1F9 * D1145101972-02-12DESIGNER.~M19*5 F4F760F0 F560F1F7 00292647 6C000380 200C0002 02200C00 00000000 00000000 *47-05-17.~~å%.~Ø~~.~~~~.........*7 00000000 *.... * IN= 18,OUT= 3 LRECL= 100 1 F0F0F0F1 F6F0C5D3 C9E9C1C2 C5E3C840 4040D9D7 C9C1D5D2 C1404040 40404040 *000160ELIZABETH RPIANKA *3 4040C4F1 F1F3F7F8 F2F1F9F7 F760F1F0 60F1F1C4 C5E2C9C7 D5C5D900 11C6F1F9 * D1137821977-10-11DESIGNER.~F19*5 F5F560F0 F460F1F2 00257571 6C000370 200C0001 78000C00 00000000 00000000 *55-04-12.~ÍÉ%.~ø~~.~Ì.~.........*7 00000000 *.... *



DELETE Shortcut Command

Description The DELETE Shortcut Command deletes one or more records from a KSDS. DATAMINER selects records according to the contents of any field or fields in the record, not just the key. For example, you can use the DELETE command to delete all records that have not been active in five years.

Delete functions modify the input datasets and do not create output datasets, so no output dataset definition is required in the script.

Syntax The syntax for the DELETE Shortcut Command is

DELETE

Other Requirements As a safety precaution, DATAMINER requires that you provide a range or some selection parameters to limit the scope of a DELETE script. This requirement reduces the likelihood that you will delete more records than you intend. DELETE deletes records one at a time. For a large dataset, it is far slower to delete records one at a time than using IDCAMS to clear a dataset by deleting and defining it.

DELETE Example The folowing exmaple deletes records for all employees in department D11:

DELETE /* Delete INPUT=VSAM FILENAME=EMPVSAM /* Input KSDS file WORKDEPT 35,3,C /* Define department field

WHERE WORKDEPT = 'D11' /* Delete department D11 records



HD Subcommand

Description The HD command changes data in the printed heading.

Note This command does not apply to the DATAMINER Report Writer.

Syntax The syntax for the HD command is

HD, 'literal', colnum

where

'literal'Is a literal, which must follow the rules for literals. See “Literals” (page 5.15). It is the information to print as a heading.

colnumIs the column number (1 through 132) where the first character of 'literal' goes.

You can repeat the HD command as many times as desired.

Example The following example causes MY REPORT to print in positions 1–9 (because it is nine characters long) of the output report header line.

HD,'MY REPORT',1



MAXLN= Subcommand

Description The MAXLN= command specifies the maximum number of print lines per page. After MAXLN= is reached on a page, DATAMINER skips to a new page and prints page headings. The default is 60 lines. The maximum is 999 lines.

Note This command does not apply to the DATAMINER Report Writer.

Syntax The syntax for the MAXLN= command is

MAXLN={numlines | 60}

where

numlinesIs the maximum number of lines to PRINT per page, up to 999.

Example The following example sets the number of lines to be printed on a page to 66 lines:

MAXLN=66



SELECT…[WHERE] Subcommand

Description The SELECT…[WHERE] subcommand lets you choose which fields to use for standard printing (PRINT command, page 6.8) or extracting data (EXTRACT command, page 6.6). It is not used with the REPORT command.

The SELECT command is executed when it is encountered in the script. So if you change a field before selecting it, the changed value is used.

SELECT can tell DATAMINER which fields you want to appear in a report. DATAMINER spaces them out automatically and builds a heading line containing the field names. Any literals you put in the report lines are converted to display format for printing. If you SELECT more fields than will fit across a print line, DATAMINER does not print the extras but it still copies them to the output dataset if you are creating an output dataset.

WHERE (or ONLY) is an optional argument to the SELECT command. It allows you to further narrow your selection with conditional statements.

Syntax The syntax for the SELECT command is

SELECT { fieldname | uservar | sysvar | sysconst | 'literal' } ... | *

[ WHERE conditional_statement ]

where

fieldnameIs a record field name or a table field name.

uservarIs a user variable.

sysvarIs a system variable.

sysconstIs a system constant.

'literal'Is a literal, which must follow the rules for literals. See “Literals” (page 5.15).

* (asterisk)Specifies all fields from each record in the primary input dataset. A SELECT * command, however, selects only the fields that you have defined for the main input dataset in your script. If you have left out any fields from your field definitions, they are not selected. Also, if you have defined a field twice in different ways, both versions of it are selected.



WHERE Statement Syntax

The syntax for WHERE is similar to the syntax for IF (page 8.3). Multiple conditions can be joined using AND or OR.

WHERE { fieldname | uservar | sysvar }

reloper

{ fieldname2 | uservar2 | sysvar2 |sysconst | 'literal' | PREV } ...

[ AND | OR

{ fieldname3 | uservar3 | sysvar3 }

reloper

{ fieldname4 | uservar4 | sysvar4 |sysconst2 | 'literal2' | PREV } ... ]...

where

fieldname, fieldname2, fieldname3, and fieldname4Are names of fields in the current record.

uservar, uservar2, uservar3, and uservar4Are names of existing user variables.

sysvar, sysvar2, sysvar3, and sysvar4Are names of system variables.

sysconst and sysconst2Are names of system constants.

'literal' and 'literal2'Are literals, which must follow the rules for literals. See “Literals” (page 5.15).

reloperIs one of the relational operators (page 8.2).

If, however, you specify the operand after reloper more than once, reloper can be only =, EQ, !=, or NE, and the values of the operands to the right of reloper are ORed together.

PREVIs the keyword PREV, which signifies the value of fieldname in the previous record.

Only one WHERE is allowed per SELECT. To select different groups of fields under different circumstances, you can use multiple SELECT commands inside IF groups.



Example 1 The following example copies all the fields from the main input dataset to the main output dataset for all those records that have a KEY greater than A01 and a BALANCE less than 1000.

SELECT * WHERE KEY > X'A01' AND BALANCE < '1000'

Example 2 The following example selects four fields from in the input dataset, and then moves an X into the flag byte of each record whose AMT field is less than zero.

EXTRACTKEY 1,8,CAMT 12,7,PNAME 30,20,CPHONE 90,10,CFLAG 130,1,CSELECT (KEY, AMT, NAME, PHONE) * the record is now 99 bytes longIF AMT LT 0

MOVE 'X' TO FLAG* THIS MAKES SOME RECORDS 130* BYTES LONGENDIF

Example 3 The following example examines records from the input dataset. If the value of the TYPE field is X, DATAMINER selects four fields to act on. But if the value of the TYPE field is Y, DATAMINER selects only three fields to act on. The action DATAMINER takes depends on the larger context of your script.

IF TYPE EQ 'X'SELECT (ACCNO,TYPE,BALANCE,NAME)

ENDIFIF TYPE EQ 'Y'

SELECT (ACCNO,TYPE,NAME)ENDIF



TOT Subcommand

Description The TOT subcommand prints the totals from the predefined accumulators (T0 – T9), user variables, or other system variables. This command is needed to trigger printing totals because the PRINT command is auto looping, and the script ends when all records have printed. The TOT command can be located anywhere within the script, but the total is not printed until the system reaches the end of the report.

If DATAMINER does not print any reports, it also does not print any totals.

The presence of a TOT command causes the total line to print on one or more lines, normally two lines below the last data line. Totals are split over multiple lines if a TOT command is entered whose fields overlap the fields defined in the previous TOT command. Unreferenced bytes are space filled.

Note This command does not apply to Report Writer scripts.

Syntax The syntax for the TOT command is

TOT 'literal' colnum

or

TOT fieldname fieldlength colnum [std-mask]

where

'literal'is a literal, which must follow the rules for literals. See “Literals” (page 5.15). It is the information to print as a heading for the totals.

colnumIs the column number (1 through 132) where the first character of literal or fieldname goes.

fieldnameIs the name of a field whose total you want to print.

fieldlengthIs the length of the same field.


M0 The field is printed with leading zeroes suppressed and with the same number of decimal places you defined for the field.

M1 9(13)-

M2 9(11).99-





M5 $$$,$$$,$$$,$$$.99- (Floating $)

Formatting notes:



• If any significant high-order digits are truncated when using the M5 mask, the $ (dollar sign) is lost.







4. Add 1 for the $ sign if you are using the M5 mask.

Example 1 The following example prints the heading for the total and the number of zero balance records that have been counted in ZERORECS.

TOT, 'Number of zero balance records is ',10 TOT, ZERORECS,8,50,M1

Example 2 The following example prints three headings and totals on three separate lines. When the starting position of the TOT field is less than the ending position of the previous TOT field, the total is started on a new line.

TOT '+ve balance records =',10TOT PLUSRECS,8,30,M1TOT '-ve balance records =',10TOT NEGRECS,8,30,M1TOT 'Zero balance records =',10TOT ZERORECS,8,30,M1



7
Dataset Reading and Writing
For some scripts, you must use commands to tell DATAMINER how to read and write records to a dataset. The INSERT command adds a record to a KSDS. You can use the DISPLAY script command to output a script’s contents or other data to the system printer or another dataset.

See Chapter 9, “Record-Selection Commands,” for information on commands that tell DATAMINER where to start reading in an input dataset, and for including or excluding records for processing.


Page

Dataset Reading Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2READ Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.3POINT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.5WRITE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.6Examples of READing and WRITEing Data. . . . . . . . . . . . . . . . . . . . . 7.8INSERT INTO…VALUES Command. . . . . . . . . . . . . . . . . . . . . . . . . 7.12DISPLAY Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.14

DATAMINER FOR Z/OS 7.1C User Reference Guide Dataset Reading and Writing

Dataset Reading Overview

Introduction There are a number of ways to read a dataset. All datasets that are to be read must be defined with an INPUT= command.

DATAMINER uses the first input dataset defined with an INPUT= command as the “main input dataset.”

Note If you are running a COPY, DUMP, PRINT, EXTRACT, or DELETE script, you do not need to tell DATAMINER to read or write the main dataset because it reads a record at the start of the script, writes (or PRINTs or DUMPs or DELETEs) the record at the end of the script, and then goes back to read another record, continuing until there are no more records to read. See Chapter 6, “Shortcut Commands,” for more information on these commands.



READ Command

Description The READ command reads the next record from a sequential dataset, from a keyed dataset that is being read sequentially, or by key from a keyed dataset.

The record is read into the record area that is defined following the definition of the dataset.

Syntax The syntax for the READ command is

READ filename [KEY {uservaar | sysvar | 'literal'}]

where

filenameIs the ddname of the dataset specified by an INPUT= command.

KEY { uservar | sysvar | 'literal' }Is a user variable, system variable, or literal whose value matches the key of the record that you want to READ first. If you do not specify KEY and this value, READ depends on the pointer. See “POINT Command ” (page 7.5).

Example The following example reads the next record from FILE1:

READ FILE1

Reading Randomly To read a keyed dataset randomly using a key, you have two options:

• You can POINT at the record you want to read and then read it,

or

• You can read directly by putting the key in the READ command.

Example: Reading Randomly using POINT

This is an example of reading randomly by pointing at the record to be read:

POINT FILE1 "999000"READ FILE1

This example points FILE1 at the record with a key of 999000 and then reads that record (the POINT command does not read a record but merely points the dataset to the right place). If the key that you point at is shorter than the actual key of the dataset, then the next READ retrieves the first record whose key starts with the partial key you have given.



The following example supposes FILE1 has a six-byte key, and the result is that DATAMINER returns the first record whose key starts with 123.

POINT FILE1 “123"READ FILE1

Example: Reading Randomly using READ

The other way to read a dataset randomly is to put the key on the READ command.

The following example reads the first record whose key is 456789:

READ FILE1 KEY "456789"

Errors During Reading—Return Codes

A number of things, other than getting a record, can happen as a result of trying to read a record. Most of these error conditions are normal, indicating that you have, for example, reached end of the dataset or tried to read a record that doesn’t exist.

Following every read or write to a dataset, DATAMINER places a result code in a field called filename:IO-RESULT, where filename is the ddname of the dataset specified on the INPUT= command. The code remains there until you next read or write for that dataset. The POINT command does not change this result field.

The result field is three characters long. The most common values are as follows:

Note The FILE-STATUS system variable is set to '000' for a successful read or write.

Result Code

Description

OK The read or write was successful.

EOF There are no more records in the input dataset. The last read issued by your script did not get a record from the dataset: it only got the EOF indication.

DPK Duplicate key. You tried to write a record to a keyed dataset, but a record of that key already exists.

NFD No record found. You issued a read for a record by key, but no record with that key exists.



POINT Command

Description For KSDS datasets only, the POINT command lets you point at the first record in the dataset, the last record in the dataset, the previous record, the next record, a record with a specific key, or a record with a key greater than or equal to the one you specify.

Syntax The syntax for the POINT command is

POINT filename [ = | EQ | >= | GE ]{fieldname | uservar | sysvar | 'literal'}

where

filenameIs the ddname of a dataset specified on an INPUT= command.

[ = | EQ | >= | GE]Is a relational operator, one of only the following:

{ fieldname | uservar | sysvar | 'literal' }Is the name of a field, user variable, system variable, or literal.

Examples The following example reads the record whose key is 789:

POINT FILEA EQ '789'READ FILEA

Following the next READ command, the VSAM dataset is set to read the next record unless you issue another POINT command to point to a different place. You can change your mind about which record you want to read next.

The following example reads the record whose key is 456:

POINT FILEA EQ '789' POINT FILEA EQ '456' READ FILEA

The POINT command does not read a record from a dataset; it only tells DATAMINER which record you want to read the next time you issue a READ command.

Symbol Alphabetic Meaning

= EQ “is equal to”

>= GE “is greater than or equal to” (the default)



WRITE Command

Description There are a number of ways to write to a dataset. All datasets to which you write must be defined with an OUTPUT= command, except for any dataset that is to be updated, which must be defined with an INPUT= command.

DATAMINER uses the first output dataset defined with an OUTPUT= command as the “main output dataset.”

Note If you are running a COPY, DUMP, PRINT, EXTRACT, or DELETE script, you do not need to tell DATAMINER to read or write the main datasets because it reads a record at the start of the script, writes (or prints or dumps or deletes) the record at the end of the script, and then goes back to read another record, continuing until there are no more records to read.

The WRITE command writes a record to a dataset. If the dataset is being written sequentially, WRITE writes the next record to the dataset. If the dataset is being written by key, the record you write is either inserted into the dataset or added on the end of the dataset, depending on the key value.

There is no need to tell DATAMINER what the key of the record is because DATAMINER finds it in the record that it is writing. If a record with that key already exists, the dataset’s result field is set to “DPK” (duplicate key), and the record is not written. To update an existing keyed record, you must specify the REPLACE operand.

Syntax The syntax for the WRITE command is

WRITE filename [ADD [FROM filename1] | REPLACE | DELETE]

where

filenameIs the ddname of the dataset to which data will be written.

filename1Is an optional data source.

ADDIs the default function and either writes the next record if the dataset is being written to sequentially, or inserts the record into the dataset if it is keyed.

REPLACE Updates the current record for a keyed dataset. UPDATE is a synonym for REPLACE.



DELETEDeletes the current record for a keyed dataset.

Example The following example writes to the dataset FILE1:

WRITE FILE1



Examples of READing and WRITEing Data

Example 1 The following example copies a dataset and writes every record with a negative balance to another dataset. READ and WRITE commands are not needed in this example because COPY is a shortcut command and automatically processes record looping, reading, and writing.

COPYINPUT=VSAM FILENAME=INFILEOUTPUT=VSAM FILENAME=OUTFILEOUTPUT=DISK FILENAME=NEGFILE VARBLK BLKSIZE=16000 LRECL=1000DETAIL 1 1000 CBALANCE 98 10 PIF BALANCE < 0

MOVE INFILE:DETAIL TO NEGFILE:DETAILWRITE NEGFILE

ENDIF

There is no need to read from or write to INFILE and OUTFILE, respectively. Because these datasets are the first input and output datasets defined, DATAMINER uses them as the input and output datasets for the COPY operation. Because separate field names have not been defined for the datasets, DETAIL can be used as a field name for all the datasets. Records for the datasets, however, are kept in separate areas, so DETAIL must be moved from the input area to the output area for NEGFILE before NEGFILE can be written.

Example 2 This example reads a dataset sequentially, gets some information from a keyed dataset using data from the input record, and writes a record containing some fields from both the main input dataset and the keyed dataset. This script uses the MOVE command to move fields.

INPUT=DISK FILENAME=INFILE LRECL=800 BLKSIZE=800 FIXEDACCT-NO 1 8 CBALANCE 98 10 POUTPUT=VSAM FILENAME=NEWFILENEWACCT 1 8 CADDRESS 9 300 CBALANCE 400 12 PINPUT=VSAM FILENAME=CUSTFLADDRESS 200 300 C

READNEXT.READ INFILEIF INFILE:IO-RESULT = 'EOF' GOTO FINISHEDENDIF



IF INFILE:BALANCE < 0 READ CUSTFL KEY ACCT-NO IF CUSTFL:IO-RESULT = 'NFD' GOTO NOCUST

ENDIFMOVE ACCT-NO TO NEWACCTMOVE INFILE:BALANCE TO NEWFILE:BALANCEMOVE CUSTFL:ADDRESS TO NEWFILE:ADDRESSWRITE NEWFILENOCUST.

ENDIFGOTO READNEXTFINISHED.

In the above example, the script runs in TASK mode, and the script does all the reading and writing using a GOTO loop. The script checks the dataset result after each read to see whether it has reached end-of-file on the main input dataset or has tried to read a non-existent record from the keyed dataset, CUSTFL.

The script uses the same field names for the various datasets. For MOVE commands, the script prefixes the fieldname with the dataset name to indicate the correct source and target dataset.

In the example, the field BALANCE is used from the INFILE dataset and sent to the NEWFILE dataset. The MOVE command moves the INFILE:BALANCE field value to NEWFILE:BALANCE.

Example 3 This example reads a VSAM dataset in TASK mode. The script loops through reading the EMPVSAM dataset and exits the script when End of File is detected. The SALARY and BONUS fields are updated in certain cases and then rewritten back to the EMPVSAM dataset. The DISPLAY command (page 7.14) is used to log a message to the system printer whenever an employee record is updated.

INPUT=VSAM FILENAME=EMPVSAM EMPNO 1 6 C FIRSTNME 7 12 C MIDINIT 19 1 C LASTNAME 20 15 C WORKDEPT 35 3 C PHONENO 38 4 C HIREDATE 42 10 C HIREDATE-YYYY " 4 C SALARY 73 5 P 2 BONUS * 5 P 2 COMM * 5 P 2

DEFINE UPDATE-FLAG 1 C /* Define a user variable

READNEXT. READ EMPVSAM /* Read employee dataset



UPDATE-FLAG = 'N' /* Initialize update flag

IF EMPVSAM:IO-RESULT = 'EOF' GOTO FINISHED /* End script on EOFENDIF

IF WORKDEPT = 'E11' /* Check for department E11 SALARY = SALARY * 1.05 /* Bump salary by 5% UPDATE-FLAG = 'Y' /* Indicate update requiredENDIF IF HIREDATE-YYYY = '2011' /* Check for 2011 hires MOVE 1000 TO BONUS /* Set bonus to 1000 UPDATE-FLAG = 'Y' /* Indicate update required ENDIF IF UPDATE-FLAG = 'Y' /* Check if update required WRITE EMPVSAM REPLACE /* Update employee record

/* Write out update log to printer DISPLAY 'EMPLOYEE UPDATED' EMPNO 'SALARY' SALARY 'BONUS'

BONUSENDIF GOTO READNEXTFINISHED.

Example 4 In this example, an employee VSAM dataset is read in TASK mode. The script loops through reading the EMPVSAM dataset, exiting the script when End of File is detected. The SALARY and BONUS fields are updated in certain cases and then written back to the EMPVSAM dataset. The DISPLAY command (page 7.14) is used to log a message to the system printer whenever an employee record is updated.

INPUT=VSAM FILENAME=EMPVSAM EMPNO 1 6 C FIRSTNME 7 12 C MIDINIT 19 1 C LASTNAME 20 15 C WORKDEPT 35 3 C PHONENO 38 4 C HIREDATE 42 10 C HIREDATE-YYYY " 4 C SALARY 73 5 P 2 BONUS * 5 P 2 COMM * 5 P 2 DEFINE UPDATE-FLAG 1 C /* Define a user variableREADNEXT. READ EMPVSAM /* Read employee dataset UPDATE-FLAG = 'N' /* Init update flag

IF EMPVSAM:IO-RESULT = 'EOF'



GOTO FINISHED /* End script on EOF ENDIFIF WORKDEPT = 'E11' /* Check for department E11 SALARY = SALARY * 1.05 /* Bump salary by 5% UPDATE-FLAG = 'Y' /* Indicate update required ENDIF IF HIREDATE-YYYY = '2011' /* Check for 2011 hires MOVE 1000 TO BONUS /* Set bonus to 1000 UPDATE-FLAG = 'Y' /* Indicate update required ENDIF

IF UPDATE-FLAG = 'Y' /* Check if update required WRITE EMPVSAM REPLACE /* Update employee record

/* Write out update log to printer DISPLAY 'EMPLOYEE UPDATED' EMPNO 'SALARY' SALARY 'BONUS'

BONUSENDIF

GOTO READNEXTFINISHED.



INSERT INTO…VALUES Command

Description The INSERT command, along with the VALUES command, inserts one record into a KSDS. For example, you can use the INSERT command to insert a new record describing a new company branch.

VALUES works as a companion to INSERT. For each field named on the INSERT command, there is a corresponding literal in the VALUES command. There must be the same number of fields in the INSERT command as literals in the VALUES command. DATAMINER adjusts the length of the literals to match the fields into which you want to insert them. DATAMINER pads short character literals with spaces and puts as many leading zeros onto numeric fields as are needed. Hexadecimal fields are padded on the right with zeros.

Insert functions modify the input datasets and do not create output datasets, so no output dataset definition is required in the script.

Syntax The syntax for the INSERT INTO…VALUES commands is

INSERT INTO file (recfieldname ...) VALUES (value ...)

where

fileIs the name of the file into which you are inserting records.

recfieldnameIs the name of a record field (or the names of record fields) to insert into file. Repeated occurrences of recfieldname can be separated by commas (which DATAMINER ignores) or spaces.

valueIs the value or values with which to populate the occurrences of recfieldname in file. Each instance of value must correspond in order with each instance of recfieldname. Repeated occurrences of value can be separated by commas (which DATAMINER ignores) or spaces. Each value can be a literal, a fieldname, or a user variable.

Because an INSERT command can contain many values, it can continue over as many lines as you like. There is no need for a continuation character anywhere to show that you intend to continue. DATAMINER keeps reading more script lines until it finds the word VALUES.

Note You must issue one INSERT/VALUE pair for each record you want to insert.



Example 1 The following example

• Defines the dataset BILLFILE.

• Defines four record fields (BILL-ACCT-NO, BILL-NAME, BILL-ADDRESS, and BILL-BALANCE). See “Defining Record Fields” (page 4.2).

• Inserts the specified values into the record fields of the first record addressed.

INPUT=VSAM FILENAME=BILLFILE *BILL-ACCT-NO 1,8,C BILL-NAME 9,32,C BILL-ADDRESS 100,55,C BILL-BALANCE 240,6,P,2 * INSERT INTO BILLFILE (BILL-ACCT-NO, BILL-NAME, BILL-ADDRESS, BILL-BALANCE)VALUES ('00000999', "TST INSERT", "100 3RD ST.", 7900.43)

* /*

Example 2 The following shows how you can easily insert a record into a KSDS (KSDSIN in this case) and enter field values as literals.

INPUT=VSAM FILENAME=KSDSINKEY 1,4,C CNTR 27,3,P PACKED 60,4,P,2 REST 64,10,CINSERT INTO KSDSIN (KEY, CNTR, PACKED, REST) VALUES ('ABCD','005',1000.75,'ORDERED')

Example 3 The following tells DATAMINER that you want to insert a record containing the four fields named in the INSERT command. The character string 'XYZ' is inserted between PACKED and REST in the output dataset. The dataset that the record is to be inserted into is given by the INTO parameter, TKSDSIN in this case.

INSERT INTO TKSDSIN (KEY, CNTR, PACKED,'XYZ',REST) VALUES ('X000',50,91.5,'CLOSED')



DISPLAY Command

Description The DISPLAY command outputs data to the system printer or a specified dataset. DISPLAY formats the data according to specified parameters.

Syntax The syntax for the DISPLAY command is

DISPLAY [datasetname] [NEWPAGE] [SKIP numlines][CONTROL controlchar]

[recfieldname | tblfieldname | uservar |sysvar | sysconst | 'literal' |

COL colnum | +coltoright | -coltoleft] ...

where

datasetnameIs the ddname of the dataset to which the data is to be output.

NEWPAGESpecifies to start a new page before printing the data.

numlinesIs the number of lines to SKIP before printing the data.

controlcharIs the printer carriage control character for the print line.

recfieldname, tblfieldname, uservar, sysvar, sysconst, ‘literal’Are the following, respectively:

• Record field name

• Table field name

• User variable

• System variable

• System constant

• Literal, which must follow the rules for literals. See “Literals” (page 5.15).

colnumIs the column number for the current field to start in.

+coltorightSpecifies the number of columns to the right of the previous field to start the current field in.

-coltoleftSpecifies the number of columns to the left of the end of the previous field to start the current field in.



Example The following example displays literals plus the value of variable EMPNO:

DISPLAY 'Salary for employee number ' EMPNO 'is' SALARY



8
Conditions and Flow Control
Conditions, relational operators, and flow-control statements allow you to control your script’s flow, depending on conditions evaluated during the execution of your script.


Page

Relational Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2IF…[ELSE]…ENDIF Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.3DO WHILE and ENDDO Statements . . . . . . . . . . . . . . . . . . . . . . . . . . 8.6PROC…[GOBACK]…ENDPROC Statements (Defining Procedures) 8.8PERFORM Command (Call a Procedure) . . . . . . . . . . . . . . . . . . . . . . 8.10Labels and GOTO Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.11EXIT Command (Escape a Script). . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.13CALL…[USING] Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.14Timing Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.15

DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control

Relational Operators

Description Relational operators test values between two expressions. In DATAMINER, you use them in IF, SKIP, ONLY, WHERE, and similar statements. Valid logical relational operators are as follows:

In some cases, which are noted in the explanations of syntax statements, not all relational operators are permitted.

Symbol Alphabetic Meaning

= EQ “is equal to”

!= NE “is not equal to”

< LT “is less than”

>= GE

–or–

NLT

“is greater than or equal to”

–or–

“is not less than”

> GT “is greater than”

<= LE–or–NGT

“is less than or equal to”

–or–

“is not greater than”



IF…[ELSE]…ENDIF Statements

Introduction Use the IF command to check whether a condition is true.

Syntax The syntax for the IF command is

IF { fieldname | uservar | sysvar }

reloper


<commands>

[ ELSE

<commands2> ]

ENDIF

where

fieldname, fieldname2Are names of fields in the current record.

uservar, uservar2Are names of existing user variables.

sysvar, sysvar2Are names of system variables.

sysconstIs the name of a system constant.


reloperIs one of the relational operators. (See the list on page 8.2.) A relational operator compares the first operand’s value to the second operand’s value. If the condition is TRUE, <commands> execute.

If you specify the operand after reloper more than once, reloper can be only =, EQ, !=, or NE, and the values of the operands to the right of reloper are ORed together.




<commands>Is one or more commands that DATAMINER performs if the condition evaluates to TRUE. Generally, the commands affect only the current record, but they may change one or more system variables that apply to other records.

<commands2>Is one or more commands that DATAMINER performs if the condition evaluates to FALSE. Generally, the commands affect only the current record, but they may change one or more system variables that apply to other records.

If you specify two or more values to the right of the relational operator (reloper), the values are ORed together.

Adding Conditional Tests

You can create a more complex condition expression by ANDing or ORing any number of conditional tests. (A single conditional test consists of two fields separated by a relational operator. The operator reloper compares the first field’s value to the second field’s value.)

The syntax below shows two conditional tests joined with AND or OR.

IF { fieldname | uservar | sysvar }

reloper

{ fieldname2 | uservar2 | sysvar2 |sysconst | 'literal' | PREV }

[ AND | OR

{ fieldname3 | uservar3 | sysvar3 }

reloper

{ fieldname4 | uservar4 | sysvar4 |sysconst2 | 'literal2' | PREV } ] ...

<commands>

[ ELSE

<commands2> ]

ENDIF

Example 1 In the following example, two conditional tests (GE and =) are ANDed. If both tests evaluate to TRUE, then the MOVE command executes.

IF VAR1 GE 5 AND VAR2 = 10MOVE 'EXFILE' TO TEMP2

ENDIF



Example 2 In this example, the script puts YES in WORD if FLDA has Y in it; otherwise, it puts NO in WORD.

FLDA 3,1,CWORD 65 3 CIF FLDA = 'Y'

MOVE 'YES' TO WORDELSE

MOVE "NO" TO WORDENDIF

Using IF With a List of Values

To check a record field, user variable, system variable, system constant, or literal for one of a number of values, you can use the list form of the IF command. This lets you check for a value that is in a list or a value that is not in a list. The values can be any mixture of literals and fields, including fields of different lengths and types. You can use parentheses to make your scripts easier to read.

The format of the command is to check whether the value of flda is the same as the value of any of the other fields:

IF flda = fldb fldc fldd ...

or to check if flda is not the same as any of the other fields

IF flda NE fldb fldc fldd ...

Remember: the only operators allowed are =, EQ, !=, and NE.

The next example checks a field called FLAG, and if it contains ‘A’, ‘C’, ‘F’, or the same value as OLDFLAG, it skips the following ADD command:

IF FLAG EQ 'A' 'C' 'F' OLDFLAGGOTO DONTADD

ENDIFADD 1 TO TOTALDONTADD.

The following example is the same but uses a “not equal” condition:

IF FLAG NE 'A' 'C' 'F' OLDFLAGADD 1 TO TOTAL

ENDIF

Using IF To Test for EOF

To test for EOF following a READ statement, you can use this syntax:

IF EOF ddname

The argument to IF evaluates to TRUE when EOF is reached. This statement is equivalent to

IF ddname:IO-RESULT = 'EOF'



DO WHILE and ENDDO Statements

Introduction Use the DO WHILE and ENDDO statements to set up a loop that is executed as long as the condition is met.

Syntax The syntax for the DO WHILE and ENDDO statements is

DO WHILE { fieldname | uservar | sysvar |sysconst | 'literal' }

reloper

{ fieldname2 | uservar2 | sysvar2 |sysconst2 | 'literal2' | PREV }

<commands>

ENDDO

where



sysvar, sysvar2Are names system variables.

sysconst, sysconst2Are names of system constants.

'literal', 'literal2'Are literals, which must follow the rules for literals. See “Literals” (page 5.15).



PREVIs the keyword PREV, which sginifies the value of fieldname in the previous record.

<commands>Is one or more commands that DATAMINER performs if the condition evaluates to TRUE. Generally, the commands affect only the current



record, but they may change one or more system variables that apply to other records.

If you specify two or more values to the right of the relational operator (reloper), the values are ORed together.

Adding Conditional Tests

You can create a more complex condition expression by repeating the fieldname, relational operator, and first condition indefinitely. This syntax is as follows:

DO WHILE { fieldname | uservar | sysvar |sysconst | 'literal' }

reloper


[ AND | OR

{ fieldname3 | uservar3 | sysvar3 |sysconst3 | 'literal3' }

reloper

{ fieldname4 | uservar4 | sysvar4 | sysconst4 | 'literal4' | PREV } ] ...

<commands>

ENDDO

Example This is an example of the DO WHILE and ENDDO commands:

DO WHILE BALANCE >= 0READ INFILE

ENDDO

Condition and Execution

If the condition is not met when the DO WHILE is executed, the commands between the DO WHILE and the ENDDO are not executed.

If the condition is always met, your script runs continuously.



PROC…[GOBACK]…ENDPROC Statements (Defining Procedures)

Description Procedures or subroutines let you create sections of your script that can be executed from several places in the script without having to enter the commands multiple times. They also let you write a script where the general flow is at the top of the script—read a record, do some calculations, print a report—and the details are in procedures at the bottom of the script. You create BEGIN and EOF procedures using the PROC command.

Syntax to Create a Procedure

The syntax to create a procedure is as follows:

PROC procname

<commands>

[GOBACK]

[<commands2>]

ENDPROC

where

procnameIs the name to assign to the procedure.

procname can be up to 32 characters long.

procname must begin with a letter or one of the following characters:

@ # _ $

procname can include letters, numerals, and the following characters:

@ # _ - $

procname (the name itself) is not case sensitive; for example, CORRECTION, Correction, cOrReCtIoN, and correction refer to the same procedure.

Do not define a procname that is the same name as a DATAMINER command, parameter, or System Variable. See “DataMiner Reserved Words” (page 2.15).

Do not begin procname with a hyphen.



Do not begin procname with any of the following strings because DATAMINER’s own field names begin with them:

@#_

DMIN

DMIN_

<commands> and <commands2>Are each one or more DATAMINER commands.

GOBACKIs the instruction to escape the procedure and go back to the line following the line that called the procedure.

Example PERFORM DOCALCS<commands>PROC DOCALCSADD AMOUNT TO TOTALADD SALARY TO YTDENDPROC

GOBACK Statement (Escaping a Procedure)

To escape a procedure (that is, to leave a procedure before reaching the ENDPROC statement), use the GOBACK command. Here is an example:

PROC ADDITIF AMOUNT < 0

GOBACKENDIFADD AMOUNT TO TOTALENDPROC



PERFORM Command (Call a Procedure)

Description Use the PERFORM command to call a procedure you have created.

You use the PROC command to create a procedure. See “PROC…[GOBACK]…ENDPROC Statements (Defining Procedures)” (page 8.8).

Syntax to Call a Procedure

The syntax to call a procedure is

PERFORM procname

where

procnameIs the name of your procedure.

After the procedure is executed, control returns to the line in your script after the PERFORM.



Labels and GOTO Statements

Description Labels and GOTO statements allow program flow to jump from one line in your script to another. GOTO lets you jump to a different place in your script without executing the intervening commands. It is often used with IF. Each GOTO needs a corresponding label command to tell it where to go.

Syntax for Creating Labels

The syntax for creating a label is as follows:

labelnam. | @LBL labelnam

where

labelnam• Is a label name up to 32 characters long.

• Must begin with a letter or one of the following characters: @ # _ $

• Can include letters, numerals, and the following characters: @ # _ - $

• Is not case sensitive; for example, CLEANUP, Cleanup, cLeAnUp, and cleanup are the same to DATAMINER.

Do not define a labelnam that is the same name as a DATAMINER command, parameter, system variable, or system constant. See “DataMiner Reserved Words” (page 2.15).

Do not begin labelnam with a hyphen.

Do not begin labelnam with any of the following strings because DATAMINER’s own field names begin with them:

@#_

DMIN

DMIN_

Labels must be unique and must not be the same as any fieldname.

Be sure to observe the presence of the period in one form of the label syntax and its absence in the other form.

Label Examples For example, the two ways to specify a label called THERE are

THERE.

and

@LBL THERE



Syntax for GOTO The syntax for GOTO is

GOTO labelnam

where

labelnamIs the name of a label that exists in your script.

Example of GOTO and Label Statements

The following example skips a group of commands if AGE is greater than 500.

IF AGE >500GOTO ANCIENT

ENDIF<commands1>ANCIENT.<commands2>

Notice that the label in the GOTO statement and label statement are the same.



EXIT Command (Escape a Script)

Description The EXIT command lets you leave the script immediately for the current record.

Syntax The syntax for EXIT is

EXIT

Example The following example exits the script when it finds a record whose BALANCE field is positive:

IF BALANCE > 0EXIT

ENDIF

No commands are executed after the EXIT command for any record with a positive balance. If the script is an auto-mode script, the record is PRINTed, DUMPed, or written to the output dataset, and processing continues with the next record.



CALL…[USING] Command

Description The CALL…[USING] command lets you call a phase or load module from your script, perhaps to do something that DATAMINER is not equipped to do, or to do some processing using a program that you have already written in another language.

Syntax The syntax for CALL is

CALL progname [ USING { fieldname | uservar | sysvar | sysconst | 'literal' } ... ]

where

prognameIs the name of the phase or of the load module you want to run.

fieldnameIs the name of a field in the current record.

uservarIs the name of an existing user variable to pass to progname.

sysvarIs the name of a system variable to pass to progname.

sysconstIs the name of a system constant to pass to progname.


Any number of parameters (field names, variables, constants, and literals) can be passed to the called program. Data can be sent to the called program, and the called program can return values in the variables passed to it.

Example The following example calls the program CHEKDIG and passes the values of ACCTNO and VALSW to it:

CALL CHEKDIG USING ACCTNO VALSW



Timing Commands

Description DATAMINER’s timing commands lets you control when you want a command or set of commands to be executed. Timing commands are meant to be used mainly with the SORT command (Chapter 13, “SORT Command”) but can also be used with any DATAMINER script.

They save you the time of setting up switches, creating “first time” code, and creating other flow-control code.

BEFORE INPUT Commands in this timing are executed before the main dataset is read (the “main dataset” being the first one defined with the INPUT= command). The most common use is to execute first-time commands. This may be useful, for example, for reading a control record from a dataset before processing the main dataset.

DURING INPUT Commands in this timing are executed for every record read from the main dataset. This can be used to accumulate totals, to make decisions about whether to keep or skip records, and so on. DURING INPUT and DURING OUTPUT commands are executed at the same time in a non-SORT script.

In a SORT script, DURING INPUT commands are run on the records from the unSORTed input dataset. If you are familiar with SORT exits, this is similar to E15 processing or the COBOL INPUT-PROCEDURE. clause.

DURING OUTPUT Commands in this timing are executed for every record read from the main dataset. This is the default timing and is used to specify commands to execute during the output stage of a script.

In a SORT script, DURING OUTPUT commands are run on the records being written to the SORTed output dataset. If you are familiar with SORT exits, this is similar to E35 processing or the COBOL OUTPUT-PROCEDURE. clause. If you DELETE a record DURING INPUT, that record is not processed by DURING OUTPUT.

AFTER OUTPUT This is the timing where you set up end-of-job commands. For example you could print totals, update a control dataset, and so on.

Scope of Timing Commands

The default timing is DURING OUTPUT, meaning that if you do not enter a timing command in your script or if one or more commands are entered before the first timing command, the command is executed during the output stage.

A timing command stays in effect until the next timing command or until the end of the script is encountered.



You can enter more than one timing command of any type—you may want to do that to improve readability.

You cannot enter a timing command in the middle of an IF group or in the middle of a PROC.

Example 1 The following example reads a record from a control dataset before SORTing a dataset.:

SORT ACCOUNT INTO NEWACCT BY NAMEBEFORE INPUTREAD CTLFILE KEY 'HEADER'DURING OUTPUT<Remainder of commands>

Example 2 The following example SORTs the ACCOUNT dataset, leaving out any records with a negative amount. It displays the total amount (TOTAMT) at the end of the job.

SORT ACCOUNT INTO NEWACCT BY NAMEDURING INPUTSKIP AMOUNT < 0DURING OUTPUTADD AMOUNT TO TOTAMTAFTER OUTPUTDISPLAY 'TOTAL AMOUNT IS ' TOTAMT

Example 3 The following example is similar to Example 2. It differs in that the SORTing occurs DURING OUTPUT, which is less efficient because even the records to be SKIPped take part in the SORT.

The SKIP command tells DATAMINER not to write the record or perform arithmetic on it—it does NOT tell it to ignore the record in conditional tests (IF, SKIP, or ONLY).

SORT ACCOUNT INTO NEWACCT BY NAME* THE NEXT COMMAND IS NOT REALLY NEEDED * BECAUSE IT IS THE DEFAULT TIMINGDURING OUTPUTSKIP AMOUNT <0ADD AMOUNT TO TOTAMTAFTER OUTPUTDISPLAY 'TOTAL AMOUNT IS ' TOTAMT



Example 4 (Without SORT)

The following example copies the dataset INACCT to OUTACCT. It SKIPs all the records for negative amounts or with a name FORD. At the end of the output, it DISPLAYs the total AMOUNT from the MERGUTROID records. (There are many ways to do this.) All the DURING OUTPUT commands are unnecessary but have been put in to show that you can put them in if you like.

COPYINPUT=VSAM FILENAME=INACCT* FIELD DEFINITIONS GO HEREOUTPUT=VSAM FILENAME=OUTACCT DURING OUTPUTIF NAME = 'MERGUTROID'

ADD AMOUNT TO T1ENDIFDURING OUTPUTSKIP AMOUNT < 0 OR NAME='FORD'AFTER OUTPUTDISPLAY 'TOTAL MERGUTROID AMOUNT IS ' T1



9
Record-Selection Commands
Record-selection commands tell DATAMINER where to start reading in an input dataset, and they give criteria for including or excluding records and fields for processing. The MAXRCDS= command specifies the maximum number of records to PRINT, COPY, or EXTRACT.

Record-selection commands apply only to the main input and output datasets.


Page

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2FIRSTKEY Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.4FIRST= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.5LAST= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.6FREQ= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.7KEEP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.8DROP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.9START Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.10STOP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.12SKIP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.14ONLY (or WHERE) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.16MAXRCDS= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.18

DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands

Introduction

Commands Overview When you need to select records in a dataset, the record-selection commands let you control

• Where in the dataset a record search starts

• Where a record search ends

• Which records to act on

You can specify that a search is to begin at a specific key, or is to start at a specific record, based on either relative record number or specific record content. You can likewise end a search based on either relative record number or specific record content. See “Data Manipulation Commands” (page 10.1).

Each type of record-selection command can be used any number of times in a script and must be followed by one or more selection parameters. You can use several record-selection commands of different types in your script. See “Record-Selection Rules ” (page 9.3).

Note If you use these commands to select entire records, you do not need to define the fields in those records.

Execution Order Record-Selection Commands are executed in the order they appear in your script. A SKIP or ONLY command executed before a START or STOP command causes some records to skip the START or STOP compares. After a record is skipped by a record-selection command, it can be not skipped by a later record-selection command.

In this example, the script says:

SKIP BALANCE < 0 ONLY SURNAME EQ 'MOYLE'

All the records for people named Moyle are selected, even those with a negative balance.

On the other hand, in this example the script says:

ONLY SURNAME EQ 'MOYLE'SKIP BALANCE < 0

This script selects only people named Moyle who have a positive balance.

Variable length input records are padded on the right with binary zeros to assure predictable record selection.



Note If a field in an input field is changed after the record is read, any check of that field is done against the new value of it, not against the value that was originally in the record.

Record-Selection Rules

You generally use only one record-selection command in your script. There are occasions, however, when you will want more than one. Either a record is skipped, in which case it is not present in the output dataset, or it is selected, in which case it is present in the output dataset.

Here are the rules that DATAMINER follows:

• Multiple record-selection commands are permitted in your script.

• DATAMINER executes record-selection commands in the order it encounters them in the processing of your script.

That is, a record-selection command near the top of your script could be processed later than a record-selection command near the bottom of your script, depending on conditions and your script’s flow control.

• DATAMINER selects or skips the current record according to the last record-selection command it encounters in the processing of your script.

• START and STOP commands ignore skipped records.

• Any record-selection command that appears as part of an IF group affects a given record only if that record satisfies the IF condition.

For example:

IF TYPE EQ "A"SKIP TYPE EQ "B"

ENDIF

In particular, if you put a START or STOP inside an IF group and the IF condition is not met, it is possible that your script will fail to START or STOP.



FIRSTKEY Command

Description The FIRSTKEY command positions a VSAM main input dataset to the first record that you want to read. The relative record number of all records read is relative to the record selected by FIRSTKEY.

Syntax The format for the FIRSTKEY command is

FIRSTKEY reloper relkey

where

reloperIs a relational operator. See “Relational Operators” (page 8.2).

relkeyIs a value according to the following table:

Examples The following example matches the first record whose whole five-byte key is ABCDE:

FIRSTKEY = 'ABCDE'

The following example matches the first record whose key does not start ABC:

FIRSTKEY != 'ABC'

The following example matches the first record whose key starts with ABC:

FIRSTKEY EQ 'ABC'

For This Dataset Type

relkey Must Be

KSDS A character literal (page 5.15) or a hexadecimal literal (page 5.16).

It can be either a full key or a generic key (short). See the examples below.

ESDS A relative byte address (RBA): nnnn

RRDS A relative record number (RRN): nnnn



FIRST= Command

Description The FIRST= command:

• Specifies the first record from the main input dataset to run your script against

• Sets the initial value of the FIRST_RECORD system variable

Syntax The syntax for the FIRST= command is

FIRST= recnum

where

recnumIs the record number of the first record to run your script against (whether or not that record is selected by your script).

The equal sign (=) is part of the command’s name and cannot be separated from it. The space after the equal sign, however, is optional.

Example The following example causes DATAMINER to ignore the first 24 records

in the dataset and start from the 25th.

FIRST=25



LAST= Command

Description The LAST= command

• Specifies the number of the last record from the main input dataset to run your script against; in other words, it specifies the last record for your script to run against

• Sets the initial value of the LAST_RECORD system variable

After DATAMINER reaches the LAST value, any further attempt to read from the main input dataset gets an EOF result returned.

Note FIRST= and LAST= commands can be used in the same script together or individually, without the other command.

Syntax The syntax fo the LAST= command is

LAST= recnum

where

recnumIs the record number of the last record to run your script against (whether or not that record is selected by your script).


Example The following example causes DATAMINER to stop reading records as soon as it reads record number 200. This record is the last record that is processed.

LAST=200



FREQ= Command

Description The FREQ= record-selection command selects every nnnnth input record. The FREQ= record-selection command can occur in processing order only after any of the following record-selection commands:

• START

• SKIP

• ONLY

Syntax The syntax for the FREQ= command is

FREQ= nnnn

where

nnnn Is the frequency of occurrence of records to selected. If FREQ is used with START or FIRST, the counting starts with the START / FIRST record as record number 1. The START / FIRST record is selected and

then every nth one after that.


Examples In the following example, only every tenth record is selected:

FREQ=10

Records 50, 60, 70, and every tenth record, to the end of the dataset, are selected:

FIRST=50FREQ=10



KEEP Command

Description The KEEP record-selection command keeps the current record; that is, the current record is marked to be written to the main output dataset.

The KEEP record-selection command provides an alternative to SKIP and ONLY. It often is used in conjunction with the DROP command. It usually is used with conditional processing. All the records in a dataset are kept unless they are specifically dropped by a DROP, ONLY, or SKIP command.

Syntax The syntax for the KEEP record-selection command is

KEEP

Example The following example creates an output dataset containing only people older than 50:

IF AGE > 50KEEP

ELSEDROP

ENDIF

You can change the decision to KEEP or DROP a record by using a later record-selection command.



DROP Command

Description The DROP command drops the current input record from the main output dataset.

Syntax The syntax for the DROP command is

DROP

Example The following example creates an output dataset containing only people older than 50:

IF AGE > 50KEEP

ELSEDROP

ENDIF

You can change the decision to KEEP or DROP a record by using a later record-selection command.



START Command

Description A matching record causes further selection to start. This record is selected. All preceding records are ignored. The field or fields that you use in a START command do not have to be part of the dataset’s key.

More precisely, DATAMINER selects the first record in the dataset when the condition in the START command is TRUE.

Syntax The syntax for the START command is

START { fieldname | uservar | sysvar | sysconst | 'literal' }

reloper{ fieldname2 | uservar2 | sysvar2 | sysconst2 | 'literal2' | PREV } ...

where



sysvar, sysvar2Are names of system variables.






Example The following example begins processing with the records whose ACCNO contains a value greater than 12345.

START ACCNO > '12345'



Alternative Syntax Alternatively, you can repeat a fieldname, relational operator, and a single condition indefinitely. This syntax is as follows:

START { fieldname | uservar | sysvar | sysconst | 'literal'}

reloper


[ AND | OR

{ fieldname3 | uservar3 | sysvar3 |sysconst3 | 'literal3'}

reloper


Example In the following example, the starting record is the one whose TYPE field contains either the value A or the value B:

START TYPE = 'A' or TYPE = 'B'



STOP Command

Description A matching record causes execution of the script to end. DATAMINER does not select this record. This is the typical way of copying a limited number of records between datasets.

Syntax The syntax for the STOP command is

STOP { fieldname | uservar | sysvar | sysconst | 'literal' }

reloper

{ fieldname2 | uservar2 | sysvar2 | sysconst2 | 'literal2' | PREV } ...

where









Example The following example usies the DATAMINER internal variable INPUT_RECORD, which contains the current input record number. DATAMINER ends its selection process when it has finished processing record number 499:

STOP INPUT_RECORD EQ 500




STOP { fieldname | uservar | sysvar | sysconst | 'literal'}

reloper


[ AND | OR

{ fieldname3 | uservar3 | sysvar3 |sysconst3 | 'literal3'}

reloper


Example In the following example, the last record processed is the one before the record whose TYPE field contains either the value A or the value B:

STOP TYPE = 'A' OR TYPE = 'B'



SKIP Command

Description Matching records are skipped (that is, they are not written to the main output dataset). DATAMINER selects the rest of the records.

Syntax The syntax for the SKIP command is

SKIP { fieldname | uservar | sysvar }

reloper

{ fieldname2 | uservar2 | sysvar2 | PREV } ...

where







Example In the following example, DATAMINER skips any record that has a value greater than 0 in the field BALANCE.

SKIP BALANCE > 0

Important note about SKIP

The following example results in no records being skipped because they would need to have both an A and a B in TYPE.

IF TYPE EQ "A"SKIP TYPE EQ "B"

ENDIF

The easy solution is to not put record-selection commands inside an IF group unless you are very careful when writing your script.



Note SKIP, ONLY, KEEP and DROP refer only to what is to happen to a record when it comes time to write it in an auto script. They do not affect any arithmetic or IF commands that are executed against the record.

For example, suppose we are doing a COPY job and that a record is read in which AMOUNT=0. The following commands will cause DATAMINER to write the record, despite the original value of AMOUNT:

SKIP AMOUNT <100 /* The record is being skipped.ADD 1000 AMOUNT /* AMOUNT is now 1000, but it is

/* still being skipped.ONLY AMOUNT >500 /* AMOUNT is greater than 500

/* so the record is no longer/* being skipped.


SKIP { fieldname | uservar | sysvar | sysconst | 'literal' }

reloper


[ AND | OR


reloper




ONLY (or WHERE) Command

Description DATAMINER selects only records that match selection criteria. DATAMINER skips the rest. ONLY and WHERE are synonyms.

After a record is selected, it is presented to the next (if any) selector parameter. After a record is skipped, it is ignored from then on unless another selector causes it to be selected.

Syntax The syntax for the ONLY command is

ONLY { fieldname | uservar | sysvar }reloper


where



sysvar, sysvar2Is the name of a system variable.




If, however, you specify a list of operands after reloper, reloper can be only =, EQ, !=, or NE, and the values of these operands are ORed together.


Example 1 In the following example, DATAMINER limits its selection to records containing 500 in the field called LIMIT. DATAMINER skips all other records.

ONLY LIMIT EQ 500



Example 2 In the following example, DATAMINER selects all records except those that contain 200, 250, or 500 in the field called LIMIT. (DATAMINER ignores the parentheses; they are used here for readability.)

ONLY LIMIT NE (200 250 500)

Alternative Syntax Alternatively, you can repeat the fieldname, relational operator, and first condition indefinitely. This syntax is as follows:

ONLY { fieldname | uservar | sysvar | sysconst | 'literal' }

reloper


[ AND | OR


reloper




MAXRCDS= Command

Description The MAXRCDS= command specifies the maximum number of records to PRINT, COPY, or EXTRACT. The maximum number of records is 9999999.

This command is useful in limiting users to a specific number of print or copy records, and preventing runaway EXTRACT/PRINT/COPY scripts. It is also useful for a trial run of a script to make sure you have set up your commands correctly. If you do not enter a MAXRCDS= command, DATAMINER prints, copies, or extracts the whole dataset.

Syntax The syntax for the MAXRCDS= command is

MAXRCDS=numrecs

where

numrecsIs the maximum number of records to PRINT, COPY, or EXTRACT.

Example The following example limits the number of lines to be PRINTed, COPYed, or EXTRACTed to 1000 lines.

MAXRCDS=1000



10
Data Manipulation Commands
You can use data manipulation commands to modify data before you write it out to the output dataset.


Page

Data Manipulation Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.2

MOVE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.4

SET Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.6

HIDE Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.7

CLOAK Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.8

Arithmetic Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.9

ADD Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.10

SUBTRACT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.11

MULTIPLY Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.12

DIVIDE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.13

DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands

Data Manipulation Commands

Introduction When you print a report with either PRINT or DUMP, it reflects changes made to the records with the Data Manipulator Commands. For a COPY or UPDATE script, all the fields from the input record are automatically moved to the output record so that you only need to include manipulators for fields that are to be different in the output or updated record.

If you write records to a dataset other than the main output dataset then you need to move the data into the record area for the dataset before writing it.

For an EXTRACT script, you need either a MOVE command for each field that you want to copy from the input record to the output record or a SELECT command that names all the fields you want to copy. If you use the SELECT command, you do not need to create field definitions for the fields in the output dataset.

Constraints Data Manipulation Commands have the following constraints:

• There can be any number of Data Manipulation Commands in a script.

• Data Manipulation Commands must contain one or more parameters.

• Data can be placed on top of data from a previous MOVE, SELECT, or arithmetic command.

• Execution is in the order that the commands appear in the script.

• When coded outside the scope of an IF command, movement is to all selected records.

• When coded after an IF command, movement is to only the records selected by that IF selector.

Special Notes The following notes apply:

• Each of the data manipulation commands can have several sets of parameters in one command. Sets of parameters are separated by one or more blanks. For example,

MOVE AMOUNT TO AMT2 BALANCE TO BAL2

• In a COPY script, the entire input record is copied to the output record before any data manipulation changes, such as MOVEs, are made.

• The PACK and UNPACK commands, used in earlier versions of DATAMINER, have been deprecated. These commands can be replaced with MOVE commands because DATAMINER automatically converts the data as it moves it between fields of different types.



• Previous versions of DATAMINER used a comma in place of the TO and FROM in commands. DATAMINER still supports using commas to separate parameters, but CSI recommends that you use TO and FROM rather than commas for the sake of readability.



MOVE Command

Description The MOVE commands move data from one field to another, usually (but not necessarily) from the input record to the output record. DATAMINER

automatically performs any conversion on the data that is necessary. For example, if you move a character field to a packed decimal field, DATAMINER packs the data.

DATAMINER adjusts the length of the data it is moving to match the length of the field into which it was moved.

For example, if the 16-character field called NAME currently has ROBINSON in it, the command:

MOVE 'JONES' TO NAME

leaves NAME with just the word JONES in it, the rest of the field being padded with spaces.

If the fields have a different number of decimal places, DATAMINER aligns the “from” field in step with the decimal point of the “to” field. For example, if you move a value of 12.5 to a numeric field with three decimal places, the value in the field will be 12.500.

Note 1 You do not need to enter all the trailing spaces for character fields or all the leading zeros and decimal places for numeric fields. DATAMINER knows how big the receiving field is and automatically pads it to make it the correct length.

Note 2 If field1 is a packed field and field2 is an unpacked (zoned) field, MOVE field1 TO field2 also unpacks it. MOVE validates the data before unpacking it, as well as setting the sign of the result to "F" if the result is positive. For more information on the meaning of “F” and other letters, see “Packed Decimal” (page 5.15).

Technical Note DATAMINER does “propagating moves” when moving overlapping character or hexadecimal fields.

Syntax The syntax for the MOVE command is

MOVE {field | 'literal' | var} TO field2

where

fieldIs a record field or table field.



'literal'Is a literal. For information about literals, see “Literals” (page 5.15).

varIs a user variable or system variable.

field2Is the destination record field for the value.



SET Command

Description The SET command lets you assign values to record fields, user variables, or table fields.

Syntax The syntax for the SET command is

[SET] field = {field2 | 'literal' | arith_expr}

where

field, field2Are record fields, user variables, or table fields. If you have record fields or table fields with the same names (in different datasets or tables), specify them as follows:

{filename | tblname}:{recfieldname | tblfieldname}

For example

OLDRECS:EMPLOYEE#

literalIs a literal, which must follow the rules for literals. See “Literals” (page 5.15).

arith_exprIs an arithmetic expression. Here are two examples:

• The arithmetic expression in the following statement increments the COUNTER field. Notice that the “SET” label is not needed.

COUNTER = COUNTER + 1

• The arithmetic expression in the following statement sums the values of the SALARY, COMM, and BONUS fields. This sum is then assigned to the TOTAL_COMPENSATION field.

TOTAL_COMPENSATION = SALARY + COMM + BONUS

Example 1 The following example sets the BALANCE field to the value in OLDBAL.

SET BALANCE = OLDBAL

Example 2 The following example sets the field BINARY to the literal value 302. :

SET BINARY = '302'



HIDE Command

Description The HIDE command fills character fields with lowercase xxx and numeric fields with zeros. HIDE gives you a useful way to hide the contents of a field that you do not want to be in an output file. For example, you may want to create a test data file from production data but hide customer addresses and balances. Also see CLOAK (page 10.8).

Syntax The syntax of the HIDE command is

HIDE fieldname

where

fieldnameIs the name of a record field.

Example The following example fills the numeric field BALANCE with zeros:

HIDE BALANCE



CLOAK Command

Description The CLOAK command replaces the contents of a field with a random value of the same type. CLOAK does not try to make sure that the cloaked value makes sense, but it does make sure that any blanks in the original field are blanks in the cloaked version. So “JOE BLOGGS” may end up as “XRT FBRKKW.” A different cloaking algorithm is used every time a field is cloaked, but do not regard CLOAK as secure as fully encrypting a record. Numeric fields are replaced with a random number of the same field type. Also see HIDE (page 10.7).

Syntax The syntax for the CLOKE command is

CLOKE fieldname

Example The following example replaces the characters of the field NAME with random characters:

CLOKE NAME



Arithmetic Commands

Introduction DATAMINER lets you do arithmetic on record fields, on your own user variables, and on system variables. These commands, however (ADD, SUBTRACT, MULTIPLY, and DIVIDE), are very limited. For complex arithmetic expressions, use the SET command (page 10.6).

Accumulators Commands

In addition to your user variables, 10 accumulators are provided for totaling. Each is 15 digits long with no decimal places and is referred to as T0 through T9. You can use the accumulators in any arithmetic operations in your script, and you can print them on report lines or, by using the TOT command, in the total lines of your script. You can use accumulators in the same way as any other numeric fields with the added minor advantage that you do not need to DEFINE them. See “T0–T9 ” under “System Variables” (page 5.12).

IF Commands Arithmetic commands are affected by the use of IF commands in your script. That is, an arithmetic command that appears inside the scope of an IF command is executed only if the IF condition is met.

Input Values May Change

All the arithmetic commands take their input values from the current value of the fields to which they refer. This means that, if you put a value into a field from the input field with an arithmetic command or MOVE command, the new value is used in any later arithmetic commands.

For example, suppose PRICE has 20 in it when a record is read. After executing

ADD 10 TO PRICEMULTIPLY PRICE BY 2

PRICE has 60 in it.

If you want to retain the original value of an input field, store it in a user variable.



ADD Command

Description The ADD command adds a value to a record field or user variable.

Syntax The syntax for the ADD command is

ADD {field | literal} TO field2

where

fieldIs a record field, user variable, system variable, or system constant.

literalIs a literal. (See “Literals” [page 5.15].)

field2Is a record field or user variable.

Examples The following example adds 25 to the accumulator T1:

ADD 25 TO T1

The following example adds 23.7 to the field called CHARGES:

ADD 23.7 TO CHARGES

The following example adds the value contained in AMTIN from the input record to the field TOTAL_AMOUNT and puts the result in TOTAL_AMOUNT:

ADD AMTIN TO TOTAL_AMOUNT

The following example doubles the value of FREIGHT:

ADD FREIGHT TO FREIGHT



SUBTRACT Command

Description The SUBTRACT command subtracts a value from a record field or user variable.

Syntax The syntax for the SUBTRACT command is

SUBTRACT {field | 'literal'} FROM field2

where

fieldIs a record field, user variable, system variable, or system constant.

'literal'Is a literal. (See “Literals” [page 5.15].)

field2Is a record field or user variable.

Examples The following example subtracts a literal (25) from a field (the T1 accumulator):

SUBTRACT 25 FROM T1

The following example subtracts a literal (23.7) from a field (CHARGES):

SUBTRACT 23.7 FROM CHARGES

The following example subtracts one field (AMTIN) from another field (TOTAL_AMOUNT):

SUBTRACT AMTIN FROM TOTAL_AMOUNT



MULTIPLY Command

Description The MULTIPLY command multiplies a record field or user variable by a value.

Syntax The syntax for the MULTIPLY command is

MULTIPLY field BY {field2 | 'literal'}

where

fieldIs a record field or user variable.

field2Is a record field, user variable, system variable, or system constant.


Examples The following example multiplies COST by 0.25:

MULTIPLY COST BY 0.25

The following example multiplies AMOUNT by PRICE:

MULTIPLY AMOUNT BY PRICE



DIVIDE Command

Description The DIVIDE command divides a record field or user variable by a value. DATAMINER ignores attempts to divide by zero.

Syntax The syntax for the DIVIDE command is

DIVIDE field BY { field2 | 'literal' }

where

fieldIs a record field or user variable.

field2Is a record field, user variable, system variable, or system constant.


Examples The following example divides the number in SALARY by 365.25:

DIVIDE SALARY BY 365.25

The following example divides the number in PAY by the number in HOURS:

DIVIDE PAY BY HOURS



11
Report Writer
DATAMINER provides a Report Writer function that allows you to fully control the layout and contents of your report. This function is invoked when you use the REPORT command along with the PRINT command.

Page

Report Writer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2Creating a Report Writer Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3Defining Field Formats and Headings in a Report . . . . . . . . . . . . . . . . . . 11.6Adding a User-Defined Mask to a Field Definition . . . . . . . . . . . . . . . . . 11.7Using the REPORT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.8REPORT Subcommands Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.10ACROSS, WIDTH, and HEIGHT Subcommands . . . . . . . . . . . . . . . . . .11.11ADVANCE Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.12AVG Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.13BREAK (or CONTROL) Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . 11.14GAP Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.16HEADING Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.17LABELS Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.18LENGTH Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.19LINE Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.20NODATE and NOPAGE Subcommands . . . . . . . . . . . . . . . . . . . . . . . . 11.22ORDER (or SEQUENCE) Subcommand. . . . . . . . . . . . . . . . . . . . . . . . 11.23PRINTER Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.26SPACING Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.27SUM Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.28SUMMARY Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.29TITLE Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.30Report Formatting—Simple to Complex . . . . . . . . . . . . . . . . . . . . . . . . 11.32Additional Report Writer Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.41

DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer

Report Writer Overview

Introduction When you use the combination of the PRINT and SELECT commands, DATAMINER lays out your report out for you. For example, field names are always used as column headings. Alternatively, you can format a report exactly as you want by using the DATAMINER Report Writer.

The Report Writer, a combination of the PRINT and REPORT commands (pages 6.8, and 11.8, respectively), provides many report options. It allows you to define a report layout and print a line or group of lines to the report using the PRINT command. A report definition allows you to lay out a report with up to

• 255 lines per page

• 133 characters per line

• 32,000 bytes of information per page

You can SORT the report by any of the report fields, with headings and subtotals inserted when necessary. SORTing can be in ascending or descending order. You can create summary reports consisting solely of counts and totals.

You can create any number of reports in a single execution of DATAMINER and with a single pass of the input dataset. You can combine data from several datasets and/or user variables and/or system variables to create values for a report.

Mailing Labels and Other Printing Tasks

Using Report Writer’s more flexible formatting capabilities, you can create not only reports but mailing or shipping labels, as well.

DATAMINER can print several labels across the page. You can use this facility to print any kind of multi-column output you require, such as side-by-side packing slips. Anything that you can print in a report you can print on a label.



Creating a Report Writer Script

Overview The general steps to creating a Report Writer script are as follows:

1. Specify the input data for the report.

2. Define the data fields you want to use.

3. Instruct the script to read the input file.

4. Perform record selection.

5. Perform any data manipulation needed.

6. Specify a report to print.

7. Specify the report’s format using REPORT subcommands.

Each of these steps is explained below. An example follows these steps.

Step 1—Specify the Input

The report’s input is specified using the INPUT= command. You use one or more INPUT= commands to tell DATAMINER which data source(s) to read for the report.

Design tip: You can use the INPUT= command’s MAX=records operand to limit the input to a small number of records while you test your report.

For more information, see “INPUT= Command” (page 3.3).

Step 2—Define the Fields and Variables to Use in the Report

You can define all the record fields that are in each data source or only the fields needed for the report. Any user variables must be defined as well. User variables hold information that is to be manipulated before values are written to a line in the report. The fields and variables you may need to define include

• Record fields—see Chapter 4, “Record Fields.”

• User variables—see Chapter 5, “Variables, Literals, and System Constants.”

• Table fields—see Chapter 12, “Table Fields.”

When you define a field, you can specify a custom format (mask) for the field’s values in the report. You can also specify a custom field heading. See “Defining Field Formats and Headings in a Report” (page 11.6).

Step 3—Read the Input File

If only one input file is required, the AUTO command can be used to put DATAMINER into auto-read mode. Alternatively, you can manage record reading within your script by using the READ command and constructing a loop to perform each read.

Note The PRINT command does not function as a shortcut command in a Report Writer script. You must use either the AUTO command or a read loop that tests for the end of file (EOF).

For more information, see Chapter 2, “DataMiner Scripts.”



Step 4—Select Records

Many methods are available to limit the data written to each report. One method is to use record-selection commands. Another is to wrap the PRINT command with an IF statement that selects the records used for input.

For more information, see Chapter 9, “Record-Selection Commands.”

Step 5—Perform Computations

Any number of computations can be performed before writing a line to the report. You can define user variables to hold computed values, and the variables are passed to the report.

For more information, see Chapter 10, “Data Manipulation Commands.”

Step 6—Use PRINT to Print a Report

You must use a PRINT statement to specify the report to which each line is written. (The report name is defined by a REPORT command, which typically is placed after the PRINT statement in a script.) All record field names and variables are available to the report. A PRINT statement writes one or more lines to the report only if the PRINT statement is executed. If the statement is bypassed by some flow-control logic (in an IF statement, for example), no write is performed. You can include multiple PRINT statements in a script to print multiple reports.

Step 7—Use REPORT to Specify Fields and Report Formatting

The REPORT command (using one or more LINE subcommands) selects the fields you want to print. REPORT has many formatting subcommands. See “REPORT Subcommands Summary” (page 11.10) for a list. You can include multiple REPORT commands in a script to define multiple reports.



INPUT=DISK FILENAME=SALES

********************************************CUST-NO 1 8 C HEADING ('CUSTOMER' 'NUMBER')

DEPT 64 12 C HEADING ('SALES' 'DEPARTMENT')

VALUE 90 9 P 2 HEADING ('INVOICE' 'AMOUNT')DISCOUNT 135 9 P 2

DEFINE DISC-VAL 9 P 2 HEADING('DISCOUNTED' 'VALUE')

********************************************AUTO INPUT SALES

********************************************* Wrap PRINT in an IF statement* to select records for printingIF CUST-NO >= 50000000

DISC-VAL = VALUESUBTRACT DISCOUNT FROM DISC-VAL

PRINT SALES-REPORT ENDIF

******************************************** REPORT SALES-REPORTTITLE ("DEPARTMENTAL SALES REPORT" "WITH DISCOUNTS")LINE DEPT CUST-NO VALUE DISCOUNT DISC-VALORDER DEPT

Script Example The following script produces a sales report sorted by department. This example illustrates the steps you must follow to create a Report Writer script.

1. Define the input dataset.

2. Define record fields for the dataset. If needed, define a user variable for a calculation. As an option, add your own column headings to field definitions, or use the HEADING subcommand under the REPORT command below.

3. Set up automatic reading of the dataset. As an option, use a READ loop instead of AUTO.

4. Add record-selection logic (optional).

5. Perform data manipulation (optional).

6. Print the report defined by the REPORT command.

7. Define the report name and layout, letting DATAMINER do most of the work. Use REPORT subcommands, placing them after the REPORT command.



Defining Field Formats and Headings in a Report

Field Masks DATAMINER formats a field for printing based on how you define the field in your record layout. For example, if you say it is a number with two decimal places, DATAMINER inserts commas between groups of three digits and prints the number with two decimals places. Also, the field name is used as the heading. You can override these defaults by specifying a field layout, called a mask, and a column heading in a field’s definition.

DATAMINER provides five standard masks (M1–M5). To use one, you add its name to the field definition. For example,

BALANCE 60 8 P 4 M5

tells DATAMINER that BALANCE is an 8-byte packed record field starting at byte 60, with 4 decimal places, and is to be printed using mask M5. Because mask M5 has only two decimal places, BALANCE is rounded to two decimal places before being printed. The last two decimal places are not printed.

A standard mask can be added to any record field, table field, or user variable definition. See “Step 2—Define the Fields and Variables to Use in the Report” (page 11.3) for a list of chapters that provide more information on these field types. The standard masks are described in these chapters.

User-Defined Masks The Report Writer allows you to define your own printing mask for a field by using the MASK operand instead of one of the standard masks. See “Adding a User-Defined Mask to a Field Definition” (page 11.7).

Column Headings By default, DATAMINER uses a field’s name as the field’s column heading in a report. In a Report Writer script, you can define a column heading for a field by adding the HEADING operand to the field’s definition. A column heading can consist of one to three lines with each line specified as a literal in quotation marks. For example,

BALANCE 60 8 P 4 M5 HEADING ('CURRENT' 'BALANCE')

puts “CURRENT” on heading line one and “BALANCE” on heading line two over the column in which the BALANCE field is printed. The HEADING operand applies only to field definitions in a Report Writer script.

Alternatively, you can use the HEADING subcommand after the REPORT command to define a heading for that report only. See “HEADING Subcommand” (page 11.17) for details.



Adding a User-Defined Mask to a Field Definition

Description Report Writer allows you to define a mask for printing a field’s data if the predefined masks in DATAMINER do not suit your needs. To define your own mask for a field, you add a MASK operand to the end of the field definition. This applies to record fields, table fields, and user variables. The characters you put in your mask control how the field appears.

Syntax The syntax for a user-defined mask statement is

field-definition MASK 'user-defined-mask'

where

field-definitionIs a record field, table field, or user-variable definition. Do not include a standard mask (such as M1 or M5) in this definition.

user-defined-maskIs a mask string you create using the following components:

Example The following example adds a mask to the field BALANCE that includes

• Places for eight digits

• Two decimal places

• The period as the decimal marker

• The comma as the thousands marker

BALANCE 60 8 P 4 MASK '999,999.99'

Character Meaning

9 Holds a place for any digit, adding leading zeros.

Z Holds a place for any digit, but leading zeros are replaced by blanks. For example, if the field contains “000123456” and the mask is ZZZZ99999, the field is displayed as “ 123456.”

* Holds a place for any digit, but leading zeros are replaced by asterisks (*).

- Prints a minus sign before or after a negative number, depending on the placement of this mask character (before the first digit or after the last digit in the mask).

$ Prints a dollar sign immediately before the number.

, Specifies where to print a comma in the number.

. Specifies where to print a period in the number.



Using the REPORT Command

Description The REPORT command defines the name and layout of reports produced by a Report Writer script. You control formatting by adding one or more REPORT subcommands. Using these subcommands, you can do a variety of things to a report, including sorting fields, printing in “2-up” format (or any number up—mostly for address labels), adding totals, and adding a break by control value to print subtotals within the report.

You use the PRINT command to tell DATAMINER to print a “subpage” of the report. A report definition can specify that multiple lines be printed as a group. These groups of lines are called subpages. You use the LINE subcommand to specify a line in the subpage. The PRINT command prints the entire subpage.

For example, the first line of a subpage may contain the name of a person, the second line may have details of their department and location, and a third line may have details of their current position and salary. This group of three lines makes up a subpage. Many reports probably use only a single LINE statement; in that case, a line and a subpage are the same thing.

Syntax The syntax for the REPORT command is

REPORT name [PRINTER {output-dataset | SYSPRINT}]LINE 1 field ...[LINE n field ...] ...

[subcommand] ...

where

nameIs a name you assign to identify this report. You can define and print multiple reports in a single Report Writer script.

output-datasetIs an output dataset to use for this report. This dataset must defined with an OUTPUT= command above the REPORT command, as follows:

OUTPUT=PRINTER FILENAME=ddname

If you do not use the PRINTER subcommand after REPORT, the report output is sent to the system printer (SYSPRINT).

fieldIs a field or a value to print on this line. field is repeated as needed. For a list of the items that you can include in a LINE statement, see “LINE Subcommand” (page 11.20).



nIs the line number (2 through 255) in the subpage if you specify multiple LINE statements. Gaps between nonconsecutive line numbers are represented by one or more blank lines in the subpage. For example, for one REPORT command, three LINE statements for line numbers 1, 3, and 4 are specified. The resulting subpage structure is shown in the following table:

subcommandIs a formatting subcommand. Multiple subcommands can be added as needed. See “REPORT Subcommands Summary” (page 11.10) for a list of available subcommands. See “Report Formatting—Simple to Complex” (page 11.32) for examples that show how to use subcommands to control report formatting.

LINE Statements Subpage Structure

LINE EMPNUM ':' DEPTLINE 4 CITY ZIPLINE 3 FIRST LAST

Line 1: EMPNUM : DEPT

Line 2: [blank line]

Line 3: FIRST LAST

Line 4: CITY ZIP



REPORT Subcommands Summary

Summary Table The following table lists the subcommands you can use with the REPORT command to format your reports.

Subcommand Description Page

ACROSS, WIDTH,HEIGHT

Used with the LABELS subcommand; the number of labels to print across the page (ACROSS), and each label’s width (WIDTH) and height (HEIGHT)

11.11

ADVANCE Number of lines to skip after a control break

11.12

AVG Tells DATAMINER to keep running averages of specified fields

11.13

BREAK or CONTROL Inserts a control break in the report 11.14

GAP Number of blank columns between fields in a report

11.16

HEADING Defines a custom heading for a field 11.17

LABELS Tells DATAMINER to print the report as labels (suppresses headings and page numbers)

11.18

LENGTH Number of lines to print per page 11.19

LINE Selects the fields and strings to print on each line, and their position

11.20

NODATE, NOPAGEs

Suppresses printing the report-run date (NODATE); suppresses printing the page number (NOPAGE)

11.22

ORDER or SEQUENCE

The order in which to sort and print the data

11.23

PRINTER The printer dataset, previously defined with an OUTPUT= command, to use for the report

11.26

SPACING The line spacing to use in the report: single, double, or triple space

11.27

SUM Tells DATAMINER to keep running subtotals of specified fields (not specified by the AVG subcommand)

11.28

SUMMARY Tells DATAMINER to produce a summary report where the totals for each control break are printed

11.29

TITLE Specifies a title line (lines 1–8) to be printed at the top of each page

11.30



ACROSS, WIDTH, and HEIGHT Subcommands

Description Used with the LABELS subcommand (see page 11.18), these commands specify how many labels you want to print across the page (ACROSS), how wide each label is in columns (WIDTH), and how many lines high they are (HEIGHT). You can also use ACROSS and WIDTH to lay out a “2-up” report of invoices, packing slips, and other documents.

Syntax The syntax for the ACROSS, WIDTH, and HEIGHT subcommands is

ACROSS {numlabels | 1} WIDTH numcols HEIGHT numlines

where

numlablesIs the number of labels to print across a page. The default is 1.

numcolsIs the width of each label measured in number of columns. The default is the number of columns required to print the longest line in the label.

numlinesIs the height of each label measured in number of lines. The default is the largest line number specified by a LINE subcommand for this report. For example, if LINE 3 BALANCE defines the largest line number in the subpage for a report, then the default is 3. There is no minimum line spacing between labels.

Example The following example prints three labels across the page, each label 30 columns wide and 6 lines high:

ACROSS 3 WIDTH 30 HEIGHT 6



ADVANCE Subcommand

Description The ADVANCE subcommand specifies how many lines to skip after either of the following:

• A control break (see “BREAK (or CONTROL) Subcommand” on page 11.14)

• A group of lines (the subpage) defined by LINE subcommands (see “LINE Subcommand,” page 11.20). Reports are usually single-spaced.

The ADVANCE subcommand differs from the SPACING subcommand, which specifies how many lines to skip after each report line. ADVANCE determines how many lines are skipped after each subpage.

See “Using the REPORT Command” (page 11.8) for more information on subpage structure.

Syntax The syntax for the ADVANCE subcommand is

ADVANCE { 1 | numlines }

where

numlinesIs the number of lines to skip after a control break or a subpage.

Example The following example sets the ADVANCE value to 2:

ADVANCE 2



AVG Subcommand

Description The AVG subcommand tells DATAMINER to keep running averages of the specified fields. When a control break occurs (see “BREAK (or CONTROL) Subcommand” on page 11.14), the averages are printed. The weighted average is printed at the end of the report.

Syntax The syntax for the AVG subcommand is

AVG field ...

where

fieldIs any field or variable in the report. Multiple fields can be specified.

Note Do not specify the same field names that you specify on the SUM subcommand.

Example The following example keeps running averages of the SALARY, SALES, and BONUS fields, and it prints their averages at every control break. At the end of the report, DATAMINER prints the weighted average:

AVG SALARY SALES BONUS



BREAK (or CONTROL) Subcommand

Description The BREAK (or CONTROL) subcommand tells DATAMINER which fields to use as control breaks in your report. That is, when the value of one of the specified fields changes, DATAMINER prints subtotals for all the fields you are summing (with the SUM subcommand, page 11.28).

For example, if your script includes

BREAK DEPT

then every time the value for the field DEPT changes DataMiner prints subtotals for all the fields you are SUMming.

Additional operands each specify a further subdivision in the break previously specified in the BREAK statement.

Syntax The syntax for the BREAK subcommand is

BREAK { field [ NEWPAGE | RENUM ] } ...

where

fieldIs the name of a record field, table field, user variable, or system variable.

Each time you repeat this operand is a further division of the break previously specified in the BREAK statement. See example below.

DATAMINER does not limit the number of operands for BREAK.

NEWPAGETells DATAMINER to skip to a new page whenever a break occurs and print the headers and titles you defined on each new page.

RENUMIs the same as NEWPAGE, but it also resets the page number whenever a break occurs.

Your script must also specify with the SUM subcommand (page 11.28) which fields you want summed at each break.

Finally, consider how using or not using the ORDER subcommand on a record field, table field, user variable, or system variable may affect the order of records. If you specify a field with the BREAK subcommand, for example, that is not also specified by the ORDER subcommand, your report could break at unexpected places.



Example The following example causes a break and the printing of SUMmed fields whenever the DEPT field changes. Also, within any set of records printed for a DEPT, records are further subdivided by WORKGROUP, where SUMmed fields are also printed.

BREAK DEPT WORKGROUP



GAP Subcommand

Description The GAP subcommand specifies the number of blank columns between fields in a report. Fields are printed across the page in the order you specify them in the LINE subcommand, and by default there are three blank columns between the fields.

Syntax The syntax for the GAP subcommand is

GAP { 3 | numcols }

where

numcolsIs the number of blank columns to print between fields in the report. The default is 3.

Example The following example sets the number of blank columns between the fields in a report to 6:

GAP 6



HEADING Subcommand

Description The HEADING subcommand lets you customize the printed heading for a field specified by the LINE command. (By default, DATAMINER uses a field’s name as the column heading in a report.) HEADING is particularly helpful when you want to

• Use headings that are longer or less cryptic than the field names or that require multiple lines

• Represent long field names with shorter strings if many fields are used in the report

• Give the TALLY field a more meaningful heading

You can define up to three heading lines (stacked vertically) for a field for any report. Because you can define several reports in a single script, the HEADING subcommand affects only the report in which it is used. Also, this subcommand overrides the HEADING operand in a field’s definition.

Syntax The syntax for the HEADING subcommand is

HEADING { recfieldname | tblfieldname | uservar | sysvar | sysconst } 'literal1' [ 'literal2' [ 'literal3' ]]

where

recfieldname, tblfieldname, uservar, sysvar, and sysconst

Are the following, respectively:

• Record field name

• Table field name

• User variable

• System variable

• System constant

The system constant must correspond to an argument in the LINE subcommand.

'literal1', 'literal2', 'literal3'Are the first, second, and third lines of a heading. Each heading line is a literal, which must follow the rules for literals. See “Literals” (page 5.15).

Example The following example is a two-line heading for the TALLY system variable (which is an operand of the LINE subcommand):

HEADING TALLY 'COUNT OF' 'PEOPLE'



LABELS Subcommand

Description The LABELS subcommand tells DATAMINER that the report is to be printed as labels (perhaps on label stationery). LABELS suppresses the automatic page headings (that is, page number and date) and column headings.

The ACROSS, WIDTH, and HEIGHT subcommands normally are used with LABELS to control how labels are printed on a page.

Syntax The syntax for the LABELS subcommand is

LABELS

The LABELS subcommand takes no parameters.



LENGTH Subcommand

Description The LENGTH subcommand tells DATAMINER how many lines you want to print per page. When DATAMINER prints the report, all report lines including headings and blank lines are counted. When DATAMINER finds that the next subpage (consisting of one or more lines) cannot fit onto the current page, it skips to the top of the next page, resets the line counter, and prints the headings. If you do not specify a LENGTH, DATAMINER uses the system default line counter.

Syntax The syntax for the LENGTH subcommand is

LENGTH [numlines | sys-default ]

where

numlinesIs the number of lines to print per page.

sys-defaultIs the system default for lines per page.

Example The following example prints the report “STAFF” with five lines of data to a page (LENGTH 5).

INPUT=VSAM FILENAME=DEPTFILEINCLUDE DEPTRECD*OUTPUT=PRINTER FILENAME=OUTFILE* * READ THE INPUT FILE * AUTO INPUT DEPTFILE * * DEFINE THE REPORT * PRINT STAFF REPORT STAFF PRINTER OUTFILE ORDER DEPT-NAME LENGTH 5 TITLE 1 ('DEPT STAFF REPORT USING LENGTH COMMAND')LINE (DEPT-NAME DEPT-FNAME DEPT-LNAME DEPT-SALARY)



LINE Subcommand

Description The LINE subcommand tells DATAMINER which fields and strings to print on a line, and where to print them. If you want to print a group of lines together (such as for a label), you must add a LINE statement to define each printed line in the subpage. You must specify the line number as the first argument to each additional LINE statement you use. The PRINT command prints the entire subpage.

The LINE subcommand can contain field names, user variables, literals, and COL values to specify which column the next field is to start in.

Syntax The syntax for the LINE subcommand is

LINE [ 1 | 2 | 3 | ... | 255 ] { recfieldname | uservar | sysvar | sysconst |

'literal' | +numspaces | -numspaces | COL colnum | TALLY } ...

where

1 through 255Is the position of this line in the subpage. No number is necessary for line 1. If the line numbers of subsequent LINE statements are not consecutive, the missing LINE statements are represented by blank lines in the subpage. See “Using the REPORT Command” (page 11.8) for an example.

recfieldnameIs the name of a field in a record.

uservarIs the name of a user variable. See “Defining User Variables (DEFINE Command)” on page 5-3.

sysvarIs the name of a system variable. See “System Variables” on page 5-12.

sysconstIs the name of a system constant. See “System Constants” on page 5-18.

'literal'Is a literal. See “Literals” on page 5-15 for rules concerning literals.

+/-numspacesIs the number of space to add (+) or subtract (-) from the default 3 spaces between columns.



colnumIs the first column number of the next item (such as a record field or variable) specified in this LINE definition.

TALLYThe special system variable TALLY is used only in reports to print a count of the items in a report. A tally is kept at each break level so that you can, for example, print tallies of how many items of a particular type were sold by each office of each division of your company. “TALLY” is the default field heading; it can be changed by using the HEADING subcommand.

Example 1 The following example prints the fields DEPT, FIRST, LAST, and SALARY across the page. The LINE subcommand is in bold type. Only one LINE is specified, so PRINT prints a one-line subpage to the report.

INPUT=VSAM FILENAME=DEPTFLFIRST 4,12,C HEADING ('FIRST' 'NAME')LAST *,16,CDEPT 48,5,CSALARY 60,8,P,2AUTO INPUT DEPTFLPRINT STAFFREPORT STAFF PRINTER DEPTPRORDER DEPTBREAK DEPTTITLE 'DEPARTMENTAL STAFF REPORT'LINE 1 DEPT FIRST LAST SALARYSUM SALARY

Example 2 The following example prints two lines (a two-line subpage) for each employee:

REPORT EMPL-REPORTLINE 1 DEPT EMPLOYEE SALARY LINE 2 COL 30 START-DATE BONUS BIRTHDAY

Example 3 The following example prints four lines for each person:

REPORT EMPL-ADDR-REPORTLINE FNM LNMLINE 2 ADDRLINE 3 CITYLINE 4 STATE ZIP



NODATE and NOPAGE Subcommands

Description Normally, the date (of the report run) and the page number are printed at the top of each page for every report (except labels). The NODATE and NOPAGE subcommands suppress printing these values.

Syntax The syntax for the NODATE subcommand is

NODATE

The syntax for the NOPAGE subcommand is

NOPAGE

Neither subcommand takes parameters.

Example The following example creates a report “Staff” that does not have the date or page numbers. The NODATE and NOPAGE commands are in bold type.

* INPUT=VSAM FILENAME=DEPTFILE*DEPT-KEY 1,3,C DEPT-FNAME 4,12,C DEPT-LNAME *,16,C DEPT-NAME 48,5,C DEPT-SALARY 60,5,P,2 DEPT-BONUS 65,5,P,2 DEPT-COMM 70,5,P,2 DEPT-STARTDATE 75,10,C DEPT-BIRTHDATE 85,10,C DEPT-ADDR 95,20,C DEPT-CITY 115,20,C DEPT-STATE 135,2,C DEPT-ZIP 137,5,C * OUTPUT=PRINTER FILENAME=OUTFILE * * READ THE INPUT FILE * AUTO INPUT DEPTFILE * * DEFINE THE REPORT * PRINT STAFF REPORT STAFF PRINTER OUTFILE

NODATENOPAGEORDER DEPT-NAMETITLE 1 ('DEPT STAFF REPORT NODATE NOPAGENBR') LINE (DEPT-NAME DEPT-FNAME DEPT-LNAME DEPT-SALARY)

/*



ORDER (or SEQUENCE) Subcommand

Description The ORDER (or SEQUENCE) subcommand tells DATAMINER the order in which to sort and print the data. Fields can be sorted in ascending or descending order, and each field can be sorted differently. To specify descending order, precede the field name with a minus sign (-) or the letter “D” followed by a space.

Up to 32 fields can be sorted.

Syntax The syntax for the ORDER subcommand is

ORDER { [- | D] fieldname } ...

where

- or DIs a flag to specify to sort this field in descending order. The default is ascending order.

fieldnameIs the name of any field in the report.

Each subsequent specification of fieldname (with or without the “descending” flag) sorts the records by fieldname within the sort results of the previously specified sort field.

Example 1 The following example sorts records in ascending order by the DEPT field, and then sorts in ascending order by the PERSON field within records with matching DEPT fields:

ORDER DEPT PERSON

Example 2 The following example sorts records in ascending order by the OFFICE field, and then sorts in descending order by the SALES field within records with matching OFFICE fields:

ORDER OFFICE - SALES



Example 3 The following example first ORDERs the report by the field WORKDEPT in ascending order, and then by the field SALARY in descending order. The ORDER subcommand is shown in bold type.

* * CONNECT TO DB2 AND READ EMPLOYEE TABLE * CONNECT SSID(DB9G) PLAN(DATAM71C) * INPUT=SQL STATEMENT=EMPSEL(SELECT * FROM ZOS111.DSN8910.EMPQA)* OUTPUT=PRINTER FILENAME=DB2OUT * * READ THE INPUT FILE * AUTO INPUT EMPSEL * * PRINT THE REPORT * PRINT SALRPT REPORT SALRPT PRINTER DB2OUT

ORDER WORKDEPT -SALARY TITLE 1 ('EMPL STAFF REPORT WITH ORDER BY DEPT SALARY(DESC)')LINE (WORKDEPT, EMPNO, FIRSTNME, LASTNAME, SALARY)

/*



The following report is possible output from the preceding script, which ORDERed the data by the the WORKDEPT field in ascending order, and then by the SALARY field in descending order:

1 EMPL STAFF REPORT WITH ORDER BY DEPT SALARY(DESC)

WORK EMPNO FIRSTNME LASTNAME SALARY A00 200120 GREG ORLANDO 798.33 A00 200010 DIANE HEMMINGER 208.75 A00 000120 SEAN O CONNELL 180.99 A00 000110 VINCENZO LUCCHESI 170.55 A00 000010 CHRISTINE HAAS 150.55 B01 000020 MICHAEL THOMPSON 200.00 C01 000030 SALLY KWAN 200.00 C01 000130 DOLORES QUINTANA 200.00 C01 000140 HEATHER NICHOLLS 200.00 C01 200140 KIM NATZ 200.00 D11 000060 IRVING STERN 905.56 D11 000150 BRUCE ADAMSON 905.56 D11 000160 ELIZABETH PIANKA 905.56 D11 000170 MASATOSHI YOSHIMURA 905.56 D11 000180 MARILYN SCOUTTEN 905.56 D11 000190 JAMES WALKER 905.56 D11 000200 DAVID BROWN 905.56 D11 000210 WILLIAM JONES 905.56 D11 000220 JENNIFER LUTZ 905.56 D11 200170 KIYOSHI YAMAMOTO 905.56 D11 200220 REBA JOHN 905.56 D21 000070 EVA PULASKI 200.00 D21 000230 JAMES JEFFERSON 200.00 D21 000240 SALVATORE MARINO 200.00 D21 000250 DANIEL SMITH 200.00 D21 000260 SYBIL JOHNSON 200.00 D21 000270 MARIA PEREZ 200.00 D21 200240 ROBERT MONTEVERDE 200.00 E01 000050 JOHN GEYER 200.00 E11 000090 EILEEN HENDERSON 200.00 E11 000280 ETHEL SCHNEIDER 200.00 E11 000290 JOHN PARKER 200.00 E11 000300 PHILIP SMITH 200.00 E11 000310 MAUDE SETRIGHT 200.00 E11 200280 EILEEN SCHWARTZ 200.00 E11 200310 MICHELLE SPRINGER 200.00 E21 000100 THEODORE SPENSER 200.00 E21 000320 RAMLAL MEHTA 200.00 E21 000330 WING LEE 200.00 E21 000340 JASON GOUNOT 200.00 E21 200330 HELENA WONG 200.00 E21 200340 ROY ALONZO 200.00



PRINTER Subcommand

Description The PRINTER subcommand tells DATAMINER which printer dataset, previously defined with an OUTPUT= command, to use for the report.

Note If you use this subcommand, you must specify PRINTER as the the dataset type on the OUTPUT= command. See example below.

If you do not specify the PRINTER subcommand, the report output is sent to the system printer (SYSPRINT).

Syntax The syntax for the PRINTER subcommand is

PRINTER { output-dataset | SYSPRINT }

where

output-datasetIs the value of the FILENAME= parameter (ddname) assigned to the printer in the OUTPUT= Command (page 3.7).

Example In the following script example, a printer is defined with the file name DEPTPR. In a subsequent line, the REPORT command specifies that the printer DEPTPR be used as the output for the report:

OUTPUT=PRINTER FILENAME=DEPTPRINPUT=VSAM FILENAME=DEPTFLFIRST 4,12,C HEADING ('FIRST' 'NAME')LAST *,16,C HEADING ('LAST' 'NAME')DEPT 48,5,CSALARY 60,8,P,2AUTO INPUT DEPTFLPRINT STAFFREPORT STAFF PRINTER DEPTPRLINE 1 FIRST LAST DEPT SALARY



SPACING Subcommand

Description The SPACING subcommand tells DATAMINER to single-, double-, or triple-space the lines in your report.

Syntax The syntax for the SPACING subcommand is

SPACING [ 1 | 2 | 3 ]

Example The following example doubles the line spacing in the report:

SPACING 2



SUM Subcommand

Description The SUM subcommand tells DATAMINER to keep running subtotals of the specified fields. When a control break occurs (see “BREAK (or CONTROL) Subcommand” on page 11.14), the subtotals are printed. The grand total is printed at the end of the report.

Syntax The syntax for the SUM subcommand is

SUM fieldname ...

where

fieldnameIs the name of any field in the report. Multiple fields can be specified. Do not specify any field that is specified by the AVG subcommand.

Note SUM and SUMMARY are different subcommands.

Example The following example keeps running totals of the SALARY, SALES, and BONUS fields, and it prints their subtotals at every control break. At the end of the report, DATAMINER prints their grand totals:

SUM SALARY SALES BONUS



SUMMARY Subcommand

Description The SUMMARY subcommand produces a summary report. A summary report is one in which only the totals for each control break are printed. Totals are kept for each control break level.

Syntax The syntax for the SUMMARY subcommand is

SUMMARY

The SUMMARY subcommand takes no parameters.

Note SUMMARY and SUM are different subcommands.

You must use the SUM subcommand (page 11.28) to specify the fields for which a running total will be kept.



TITLE Subcommand

Description The TITLE subcommand can be repeated to specify up to eight title lines to be printed at the top of each page. The TITLE subcommand is ignored for labels (that is, when the LABELS subcommand [page 11.18] is specified in the same report).

Syntax The syntax for the TITLE subcommand is

TITLE [ 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 ]{ recfield | tablefield | uservar | sysvar | sysconst |

'literal' | +numspaces | -numspaces | COL colnum }

where

1 through 8Is the line number for this title line. No number is necessary for the first TITLE subcommand (the default is line 1), but subsequent TITLE subcommands must be numbered in consecutive order.

recfieldIs the name of a record field.

tablefieldIs the name of a table field.

uservarIs the name of a user variable. See “Defining User Variables (DEFINE Command)” on page 5-3.

sysvarIs the name of a system variable. See “System Variables” on page 5-12.

sysconstIs the name of a system constant. See “System Constants” on page 5-18.

'literal'Is a literal. See “Literals” on page 5-15 for rules concerning literals.

+/-numspacesIs the number of space to add (+) or subtract (-) from the default three spaces between columns.

colnumIs the first column number of the next title component (for example, recfieldname or uservar) specified in this instance of the TITLE subcommand.



Example In the following example, the TITLE command is used twice to specify two title lines in the report. The first line contains a literal, and the second line contains a variable.

REPORT DEPTTITLE 1 'DEPARTMENT' /* Use literal in title 1TITLE 2 WORKDEPT /* Add dept. code to title 2LINE EMPNO LASTNAME SALARY TALLYBREAK WORKDEPT NEWPAGEORDER WORKDEPT



Report Formatting—Simple to Complex

Introduction This section presents seven increasingly complex examples that show how reports can be designed using REPORT subcommands. The first script creates a basic report. Subsequent examples show the effect of adding formatting subcommands to the first script. In Example Script 1, the MAX operand on the INPUT= command is set to 15. For these examples, we use this operand to limit processing to 15 input records. The INPUT= command and the record field definitions are shown in the first script only.

Each example includes a sample report. The complete output may not be shown in each case.

Example Script 1 This example is a simple auto-read script that writes each record read in from an employee VSAM file to the report. The report is defined with one line for each employee, printed in the order lines are read.

INPUT=VSAM FILENAME=EMPVSAM MAX=15EMPNO 1,6,C LASTNAME 22,13,CDEPT 35,3,CSALARY 73,5,P,2BONUS 78,5,P,2COMM 83,5,P,2

AUTO EMPVSAM /* This is an auto-read scriptPRINT EMPRPT /* Write a line to the report* DEFINE THE REPORT REPORT EMPRPTLINE 1 DEPT EMPNO LASTNAME SALARY BONUS COMM

This script can produce the following report:

DEPT EMPNO LASTNAME SALARY BONUS COMM D11 000170 YOSHIMURA 46726.40 3802.00 1974.00D11 000160 PIANKA 42144.29 3702.00 1780.00D11 000150 ADAMSON 47857.78 3802.00 2022.00C01 000140 NICHOLLS 29946.00 3902.00 2274.00C01 000130 QUINTANA 25095.00 3802.00 1904.00A00 000120 O'CONNELL 169515.15 3902.00 2340.00A00 000110 LUCCHESI 269424.05 4202.00 3720.00E21 000100 SPENSER 27562.50 3802.00 2092.00E11 000090 HENDERSON 31342.50 3902.00 2380.00D21 000070 PULASKI 144328.18 4002.00 2893.00E01 000050 GEYER 42288.75 4102.00 3214.00D11 000060 STERN 61000.78 3902.00 2580.00C01 000030 KWAN 40267.50 4102.00 3060.00B01 000020 THOMPSON 43417.50 4102.00 3300.00A00 000010 HAAS 305634.48 9102.00 4220.00



Example Script 2 The following script creates the same report as Example Script 1. It uses task mode rather than AUTO mode, which means the script contains a loop to control the READing of input records. The AUTO command is not used. In this case, a DO loop tests the result of each read and ends the report if the result is not “OK.” This condition occurs when the end of file (EOF) is reached.

READ EMPVSAMDO WHILE (EMPVSAM:IO-RESULT = 'OK ') PRINT EMPRPT READ EMPVSAMENDDO* DEFINE THE REPORTREPORT EMPRPTLINE 1 DEPT EMPNO LASTNAME SALARY BONUS COMM

Example Script 3 The following script uses the auto-read mode. This mode is used in the subsequent examples as well. A report title was added; the report was sorted by department number; and a summary was requested.

Note Operands or subcommands that have been added to the basic script in this and subsequent examples are shown in bold type. These operands can be placed in any order. The modified output in the resulting report is also shown in bold type.

AUTO EMPVSAM /* This is an auto-read scriptPRINT EMPRPT /* Write line to report * DEFINE THE REPORT REPORT EMPRPT

TITLE 1 'EMPLOYEE LIST'ORDER DEPT /* Order by departmentLINE 1 DEPT EMPNO LASTNAME SALARY BONUS COMMSUM SALARY BONUS COMM /* Create summary

/* totals



Example Script 3 can produce the following report:

05/03/2012 EMPLOYEE LIST PAGE 1

DEPT EMPNO LASTNAME SALARY BONUS COMM A00 000110 LUCCHESI 269424.05 4202.00 3720.00 A00 000120 O'CONNELL 169515.15 3902.00 2340.00 A00 000010 HAAS 305634.48 9102.00 4220.00 B01 000020 THOMPSON 43417.50 4102.00 3300.00 C01 000130 QUINTANA 25095.00 3802.00 1904.00 C01 000140 NICHOLLS 29946.00 3902.00 2274.00 C01 000030 KWAN 40267.50 4102.00 3060.00 D11 000170 YOSHIMURA 46726.40 3802.00 1974.00 D11 000160 PIANKA 42144.29 3702.00 1780.00 D11 000060 STERN 61000.78 3902.00 2580.00 D11 000150 ADAMSON 47857.78 3802.00 2022.00 D21 000070 PULASKI 144328.18 4002.00 2893.00 E01 000050 GEYER 42288.75 4102.00 3214.00 E11 000090 HENDERSON 31342.50 3902.00 2380.00 E21 000100 SPENSER 27562.50 3802.00 2092.00 === ====== ============= =========== =========== ===========

1326550.86 64130.00 39753.00



Example Script 4 The BREAK subcommand was added to the following script to organize the report by department. Each department now displays a subtotal.

AUTO EMPVSAM /* This is an auto-read scriptPRINT EMPRPT /* Write line to report * DEFINE THE REPORTREPORT EMPRPTTITLE 1 'EMPLOYEE LIST'ORDER DEPT /* Order by departmentBREAK DEPT /* Organize by departmentLINE 1 DEPT EMPNO LASTNAME SALARY BONUS COMM SUM SALARY BONUS COMM /* Create summary totals


05/03/2012 EMPLOYEE LIST PAGE 1

DEPT EMPNO LASTNAME SALARY BONUS COMM A00 000110 LUCCHESI 269424.05 4202.00 3720.00 000120 O'CONNELL 169515.15 3902.00 2340.00 000010 HAAS 305634.48 9102.00 4220.00 === ====== ============= =========== =========== ===========A00 744573.68 17206.00 10280.00

B01 000020 THOMPSON 43417.50 4102.00 3300.00 === ====== ============= =========== =========== ===========B01 43417.50 4102.00 3300.00

C01 000130 QUINTANA 25095.00 3802.00 1904.00 000140 NICHOLLS 29946.00 3902.00 2274.00 000030 KWAN 40267.50 4102.00 3060.00 === ====== ============= =========== =========== ===========C01 95308.50 11806.00 7238.00

D11 000170 YOSHIMURA 46726.40 3802.00 1974.00 000160 PIANKA 42144.29 3702.00 1780.00 000060 STERN 61000.78 3902.00 2580.00 000150 ADAMSON 47857.78 3802.00 2022.00 === ====== ============= =========== =========== ===========D11 197729.25 15208.00 8356.00



Example Script 5 In the following script, the NEWPAGE operand is used to force a page break after each department summary is printed. The department number is added to a second TITLE subcommand, and the employees within each department are now sorted in descending-salary order.

AUTO EMPVSAM /* This is an auto-read scriptPRINT EMPRPT /* Write a line to report * DEFINE THE REPORT REPORT EMPRPT TITLE 1 'EMPLOYEE LIST'TITLE 2 'FOR DEPARTMENT' DEPTORDER DEPT -SALARY /* Order by dept, then salaryBREAK DEPT NEWPAGE /* Organize by departmentLINE 1 DEPT EMPNO LASTNAME SALARY BONUS COMM SUM SALARY BONUS COMM /* Create summary totals


05/02/2012 EMPLOYEE LIST PAGE 1FOR DEPARTMENT A00

DEPT EMPNO LASTNAME SALARY BONUS COMMA00 000010 HAAS 305634.48 9102.00 4220.00 000110 LUCCHESI 269424.05 4202.00 3720.00 000120 O'CONNELL 169515.15 3902.00 2340.00=== ====== ============= =========== =========== ===========A00 744573.68 17206.00 10280.00

05/02/2012 EMPLOYEE LIST PAGE 2FOR DEPARTMENT B01

DEPT EMPNO LASTNAME SALARY BONUS COMM B01 000020 THOMPSON 43417.50 4102.00 3300.00=== ====== ============= =========== =========== ===========B01 43417.50 4102.00 3300.00

05/02/2012 EMPLOYEE LIST PAGE 3FOR DEPARTMENT C01

DEPT EMPNO LASTNAME SALARY BONUS COMMC01 000030 KWAN 40267.50 4102.00 3060.00 000140 NICHOLLS 29946.00 3902.00 2274.00 000130 QUINTANA 25095.00 3802.00 1904.00=== ====== ============= =========== =========== ===========C01 95308.50 11806.00 7238.00



Example Script 6 In the following script, the user variable TOTAL_COMP is defined to calculate total compensation. This statement is inserted near the top of the script. Then, within the auto-read loop, the variable’s value is calculated by adding salary, bonus, and commissions. The variable is added to the EMPRPT report as the fourth field; the field heading is specified by the HEADING operand in the variable’s definition.

A second report, EMPSUM, is also defined and generated. It is a summary report by department (produced by SUMMARY) and includes the employee count for each department (produced by the TALLY operand on the LINE subcommand). A two-line heading for the TALLY field is defined using the HEADING subcommand.

DEFINE TOTAL_COMP 5,P,2 HEADING ('TOTAL' 'COMPENSATION') /* define total var

AUTO EMPVSAM /* This is an auto-read scriptTOTAL_COMP = SALARY + BONUS + COMM /* Calc total compensation */PRINT EMPRPT /* Write line to detail reportPRINT EMPSUM /* Write line to summary report

* DEFINE THE DETAIL REPORT REPORT EMPRPTTITLE 1 'EMPLOYEE LIST'TITLE 2 'FOR DEPARTMENT' DEPTORDER DEPT -SALARY /* Order by dept then salary BREAK DEPT NEWPAGE /* Organize by departmentLINE 1 DEPT EMPNO LASTNAME TOTAL_COMP SALARY BONUS COMMSUM SALARY BONUS COMM TOTAL_COMP /* Create summary totals

* DEFINE THE SUMMARY REPORTREPORT EMPSUM TITLE 2 'DEPARTMENT SUMMARY'ORDER DEPT /* Order by dept then salaryBREAK DEPT /* Organize by department LINE 1 DEPT TOTAL_COMP SALARY BONUS COMM TALLYHEADING TALLY 'EMPLOYEE' 'COUNT' SUM SALARY BONUS COMM TOTAL_COMP /* Create summary totalsSUMMARY /* Print summary lines only




05/02/2012 EMPLOYEE LIST PAGE 1 FOR DEPARTMENT A00

DEPT EMPNO LASTNAME TOTAL SALARY BONUS COMMCOMPENSATION

A00 000010 HAAS 318956.48 305634.48 9102.00 4220.00 000110 LUCCHESI 277346.05 269424.05 4202.00 3720.00 000120 O'CONNELL 175757.15 169515.15 3902.00 2340.00=== ====== ============= ============ =========== =========== ===========A00 772059.68 744573.68 17206.00 10280.00

05/02/2012 EMPLOYEE LIST PAGE 2 FOR DEPARTMENT B01

DEPT EMPNO LASTNAME TOTAL SALARY BONUS COMMCOMPENSATION

B01 000020 THOMPSON 50819.50 43417.50 4102.00 3300.00=== ====== ============= ============ =========== =========== ===========B01 50819.50 43417.50 4102.00 3300.00

05/03/2012 EMPLOYEE LIST PAGE 3 FOR DEPARTMENT C01

DEPT EMPNO LASTNAME TOTAL SALARY BONUS COMM COMPENSATION

C01 000030 KWAN 47429.50 40267.50 4102.00 3060.00 000140 NICHOLLS 36122.00 29946.00 3902.00 2274.00 000130 QUINTANA 30801.00 25095.00 3802.00 1904.00=== ====== ============= ============ =========== =========== ===========C01 114352.50 95308.50 11806.00 7238.00

05/02/2012 PAGE 1DEPARTMENT SUMMARY

DEPT TOTAL SALARY BONUS COMM EMPLOYEECOMPENSATION COUNT

A00 772059.68 744573.68 17206.00 10280.00 3 B01 50819.50 43417.50 4102.00 3300.00 1 C01 114352.50 95308.50 11806.00 7238.00 3 D11 221293.25 197729.25 15208.00 8356.00 4 D21 151223.18 144328.18 4002.00 2893.00 1 E01 49604.75 42288.75 4102.00 3214.00 1 E11 37624.50 31342.50 3902.00 2380.00 1 E21 33456.50 27562.50 3802.00 2092.00 1 === =========== ========== ========= ========= =====

1430433.86 1326550.86 64130.00 39753.00 15



Example Script 7 In this example, record selection is added to restrict the report to only employees earning a salary of at least $50,000. New a title is defined as well. The M5 mask was added to the total compensation variable to print the leading dollar sign. Also, the summary line is now replaced with average values, using the AVG subcommand.

DEFINE TOTAL_COMP 5,P,2 HEADING('TOTAL' 'COMPENSATION') M5 /*Define total varAUTO EMPVSAM /* This is an auto-read script IF SALARY >= 50000.00 /* Only include 50K+ employees TOTAL_COMP = SALARY + BONUS + COMM /* Calc total compensation PRINT EMPRPT /* Write line to detail report PRINT EMPSUM /* Write line to summary report ENDIF

* DEFINE THE DETAIL REPORTREPORT EMPRPTTITLE 1 '50K+ EMPLOYEE LIST'TITLE 2 'FOR DEPARTMENT' DEPTORDER DEPT -SALARY /* Order by dept, then salaryBREAK DEPT NEWPAGE /* Organize by department LINE 1 DEPT EMPNO LASTNAME TOTAL_COMP SALARY BONUS COMM AVG SALARY BONUS COMM TOTAL_COMP /* Create summary averages

* DEFINE THE SUMMARY REPORT REPORT EMPSUM TITLE 1 '50K+ EMPLOYEE LIST'TITLE 2 'DEPARTMENT SUMMARY'ORDER DEPT /* Order by dept, then salaryBREAK DEPT /* Organize by department LINE 1 DEPT TOTAL_COMP SALARY BONUS COMM TALLYHEADING TALLY 'EMPLOYEE' 'COUNT' AVG SALARY BONUS COMM TOTAL_COMP /* Create summary averagesSUMMARY /* Print summary lines only




05/03/2012 50K+ EMPLOYEE LIST PAGE 1

FOR DEPARTMENT A00


A00 000010 HAAS $318,956.48 305634.48 9102.00 4220.00

000110 LUCCHESI $277,346.05 269424.05 4202.00 3720.00

000120 O'CONNELL $175,757.15 169515.15 3902.00 2340.00

=== ====== ============= ============== =========== =========== ===========

A00 $257,353.22 248191.22 5735.33 3426.66


FOR DEPARTMENT D11


D11 000060 STERN $67,482.78 61000.78 3902.00 2580.00

=== ====== ============= ============== =========== =========== ===========

D11 $67,482.78 61000.78 3902.00 2580.00


FOR DEPARTMENT D21


D21 000070 PULASKI $151,223.18 144328.18 4002.00 2893.00

=== ====== ============= ============== =========== =========== ===========

D21 $151,223.18 144328.18 4002.00 2893.00


DEPARTMENT SUMMARY

DEPT TOTAL SALARY BONUS COMM EMPLOYEE COMPENSATION COUNT

A00 $257,353.22 248191.22 5735.33 3426.66 3

D11 $67,482.78 61000.78 3902.00 2580.00 1

D21 $151,223.18 144328.18 4002.00 2893.00 1

=== ============== =========== =========== =========== =============

$198,153.12 189980.52 5022.00 3150.60 5



Additional Report Writer Examples

Introduction This section contains additional Report Writer script examples with sample reports.

See also these examples in Chapter 17, “DataMiner Script Examples”:

• “Ex. 34: PRINT Report Sorted by Fields, Create Subtotals,” page 17.16

• “Ex. 35: PRINT Report Sorted by Fields, File/Table Input,” page 17.17

• “Ex. 36: PRINT Name and Address Labels,” page 17.18

• “Ex. 37: Using ORDER and BREAK Commands Together,” page 17.18

• “Ex. 38: Using ORDER, BREAK, and SUMMARY Together,” page 17.20

Example Script 8: Using DB2, and Creating Multiple Reports

The following script connects to a database and creates two reports:

* CONNECT TO DB2 AND READ EMPLOYEE TABLE * CONNECT SSID(DB9G) PLAN(DATAM71C) * * PRINT A SALARY REPORT INPUT=SQL STATEMENT=EMPSEL(SELECT * FROM ZOS111.DSN8910.EMPQA)* OUTPUT=PRINTER FILENAME=DB2OUT1 OUTPUT=PRINTER FILENAME=DB2OUT2 * AUTO INPUT EMPSEL PRINT SALRPT1 PRINT SALRPT2 * CREATE THE FIRST REPORT * REPORT SALRPT1 PRINTER DB2OUT1 ORDER WORKDEPT BREAK WORKDEPT TITLE 1 ('EMPL STAFF REPORT BY WORK DEPT ') TITLE 2 ('STARTING DEPARTMENT NUMBER FOR PAGE: ', WORKDEPT)LINE WORKDEPT, EMPNO, FIRSTNME, LASTNAME, SALARY

* CREATE THE SECOND REPORT * REPORT SALRPT2 PRINTER DB2OUT2 ORDER WORKDEPT -SALARY BREAK WORKDEPT TITLE 1 ('EMPL STAFF REPORT WITH SUMMARY BY DEPT ') LINE WORKDEPT, EMPNO, FIRSTNME, LASTNAME, SALARY SUM SALARY

/* //



Example 8 Output: Report 1

The following two-page report is an example of Report 1 output that could result from Example Script 8:

QA.DM.TEST.DMRPORDP.DB2OUT101/22/2012 EMPL STAFF REPORT BY WORK DEPT PAGE 1 STARTING DEPARTMENT NUMBER FOR PAGE: A00

WORK EMPNO FIRSTNME LASTNAME SALARY A00 000010 CHRISTINE HAAS 150.55 000110 VINCENZO LUCCHESI 170.55 000120 SEAN O CONNELL 180.99 200010 DIANE HEMMINGER 208.75 200120 GREG ORLANDO 798.33 === ====== ============ =============== =========== A00

B01 000020 MICHAEL THOMPSON 200.00 === ====== ============ =============== =========== B01

C01 000030 SALLY KWAN 200.00 000130 DOLORES QUINTANA 200.00 000140 HEATHER NICHOLLS 200.00 200140 KIM NATZ 200.00 === ====== ============ =============== =========== C01

D11 000060 IRVING STERN 905.56 000150 BRUCE ADAMSON 905.56 000160 ELIZABETH PIANKA 905.56 000170 MASATOSHI YOSHIMURA 905.56 000180 MARILYN SCOUTTEN 905.56 000190 JAMES WALKER 905.56 000200 DAVID BROWN 905.56 000210 WILLIAM JONES 905.56 000220 JENNIFER LUTZ 905.56 200170 KIYOSHI YAMAMOTO 905.56 200220 REBA JOHN 905.56 === ====== ============ =============== =========== D11 D21 000070 EVA PULASKI 200.00 000230 JAMES JEFFERSON 200.00 000240 SALVATORE MARINO 200.00 000250 DANIEL SMITH 200.00 000260 SYBIL JOHNSON 200.00 000270 MARIA PEREZ 200.00 200240 ROBERT MONTEVERDE 200.00 === ====== ============ =============== =========== D21

E01 000050 JOHN GEYER 200.00 === ====== ============ =============== =========== E01



(Report 1 continued)

E11 000090 EILEEN HENDERSON 200.00 000280 ETHEL SCHNEIDER 200.00 000290 JOHN PARKER 200.00 000300 PHILIP SMITH 200.00 000310 MAUDE SETRIGHT 200.00 200280 EILEEN SCHWARTZ 200.00 200310 MICHELLE SPRINGER 200.00 === ====== ============ =============== =========== E11

E21 000100 THEODORE SPENSER 200.00 000320 RAMLAL MEHTA 200.00 000330 WING LEE 200.00 000340 JASON GOUNOT 200.00

01/22/2012 EMPL STAFF REPORT BY WORK DEPT PAGE 2 STARTING DEPARTMENT NUMBER FOR PAGE: E21

WORK EMPNO FIRSTNME LASTNAME SALARY E21 200330 HELENA WONG 200.00 200340 ROY ALONZO 200.00 === ====== ============ =============== =========== E21



Example 8 Output: Report 2

The following two-page report is an example of Report 2 output that could result from Example Script 8:

Example Report 2:QA.DM.TEST.DMRPORDP.DB2OUT2

01/22/2012 EMPL STAFF REPORT WITH SUMMARY BY DEPT PAGE 1 WORK EMPNO FIRSTNME LASTNAME SALARY A00 200120 GREG ORLANDO 798.33 200010 DIANE HEMMINGER 208.75 000120 SEAN O CONNELL 180.99 000110 VINCENZO LUCCHESI 170.55 000010 CHRISTINE HAAS 150.55 === ====== ============ =============== =========== A00 1509.17 B01 000020 MICHAEL THOMPSON 200.00 === ====== ============ =============== =========== B01 200.00 C01 000030 SALLY KWAN 200.00 000130 DOLORES QUINTANA 200.00 000140 HEATHER NICHOLLS 200.00 200140 KIM NATZ 200.00 === ====== ============ =============== =========== C01 800.00 D11 000060 IRVING STERN 905.56 000150 BRUCE ADAMSON 905.56 000160 ELIZABETH PIANKA 905.56 000170 MASATOSHI YOSHIMURA 905.56 000180 MARILYN SCOUTTEN 905.56 000190 JAMES WALKER 905.56 000200 DAVID BROWN 905.56 000210 WILLIAM JONES 905.56 000220 JENNIFER LUTZ 905.56 200170 KIYOSHI YAMAMOTO 905.56 200220 REBA JOHN 905.56 === ====== ============ =============== =========== D11 9961.16

D21 000070 EVA PULASKI 200.00 000230 JAMES JEFFERSON 200.00 000240 SALVATORE MARINO 200.00 000250 DANIEL SMITH 200.00 000260 SYBIL JOHNSON 200.00 000270 MARIA PEREZ 200.00 200240 ROBERT MONTEVERDE 200.00 === ====== ============ =============== =========== D21 1400.00 E01 000050 JOHN GEYER 200.00 === ====== ============ =============== =========== E01 200.00



(Report 2 continued)

E11 000090 EILEEN HENDERSON 200.00 000280 ETHEL SCHNEIDER 200.00 000290 JOHN PARKER 200.00 000300 PHILIP SMITH 200.00 000310 MAUDE SETRIGHT 200.00 200280 EILEEN SCHWARTZ 200.00 200310 MICHELLE SPRINGER 200.00 === ====== ============ =============== =========== E11 1400.00

E21 000100 THEODORE SPENSER 200.00 000320 RAMLAL MEHTA 200.00 000330 WING LEE 200.00 000340 JASON GOUNOT 200.00 200330 HELENA WONG 200.00

01/22/2012 EMPL STAFF REPORT WITH SUMMARY BY DEPT PAGE 2

WORK EMPNO FIRSTNME LASTNAME SALARY E21 200340 ROY ALONZO 200.00 === ====== ============ =============== =========== E21 1200.00 === ====== ============ =============== ===========

01/22/2012 EMPL STAFF REPORT WITH SUMMARY BY DEPT PAGE 1

WORK EMPNO FIRSTNME LASTNAME SALARY 16670.33



Example Script 9: Creating Reports and a Mailing List

The following script creates a report, a mailing list, and summary report of personnel whose salary is greater than $75,000.00.

* INPUT=VSAM FILENAME=DEPTFILE * DEPT-KEY 1,3,C DEPT-FNAME 4,12,C DEPT-LNAME *,16,C DEPT-NAME 48,5,C DEPT-SALARY 60,5,P,2 DEPT-BONUS 65,5,P,2 DEPT-COMM 70,5,P,2 DEPT-STARTDATE 75,10,C DEPT-BIRTHDATE 85,10,C DEPT-ADDR 95,20,C DEPT-CITY 115,20,C DEPT-STATE 135,2,C DEPT-ZIP 137,5,C * * READ THE INPUT FILE AUTO INPUT DEPTFILE * * PRINT THE REPORT * IF DEPT-SALARY > 75000.00 PRINT ADDRESS-LABEL REPORT ADDRESS-LABEL

ACROSS 2 WIDTH 40 HEIGHT 7 LABELS

LINE 1 (DEPT-FNAME DEPT-LNAME) LINE 2 (DEPT-ADDR) LINE 3 (DEPT-CITY) LINE 4 (DEPT-STATE DEPT-ZIP) * PRINT SALRPT REPORT SALRPT

ORDER DEPT-NAME -DEPT-SALARY BREAK DEPT-NAME

TITLE 1 ('EMPL STAFF REPORT WITH SUMMARY BY DEPT ') LINE (DEPT-NAME, DEPT-FNAME, DEPT-LNAME, DEPT-SALARY) SUM DEPT-SALARY * PRINT SALSUM REPORT SALSUM

SUMMARY ORDER DEPT-NAME BREAK DEPT-NAME

TITLE 1 ('EMPL STAFF REPORT WITH SUMMARY ONLY ') LINE 1 (DEPT-NAME, DEPT-SALARY, TALLY) SUM DEPT-SALARY ENDIF /*



Example 9 Output: Address Labels

The following is an example address label (the report called ADDRESS-LABEL) that could result from the Example Script 9. (This script creates a mailing list, a report, and a summary report of personnel whose salary is greater than $75,000.00.)

Example 9 Output: Report

The following output is a report (the report called SALRPT) that could result from the Example Script 9. (This script creates a mailing list, a report, and a summary report of personnel whose salary is greater than $75,000.00.)

CATHY O’BRIAN SUZY HILLBERG 908 KOHR PLACE 3343 DREW RD CINCINNATI MENTOR FL 44708 OH 44332

SHAUNTEE DAVIS DENVER BRONCOS 33445 SCENIC WAY 2238 TEST RD BUFFALO MIAMI NY 88993 FL 33455

1 EMPL STAFF REPORT WITH SUMMARY BY DEPT DEPT-N DEPT-FNAME DEPT-LNAME DEPT-SALARY B100 CATHY O’BRIAN 190500.00 ===== ============ ================ =========== B100 190500.00 B200 SHAUNTEE DAVIS 95300.50 SUZY HILLBERG 75500.00 ===== ============ ================ =========== B200 170800.50 C400 DENVER BRONCOS 85000.00 ===== ============ ================ =========== C400 85000.00 ===== ============ ================ =========== 446300.50



Example 9 Output: Summary Report

The following is an example summary report (the report called SALSUM) that could result from Example Script 9, which creates a mailing list, a report, and a summary report of personnel whose salary is greater than $75,000.00:

EMPL STAFF REPORT WITH SUMMARY ONLY DEPT-N DEPT-SALARY TALLY B100 190500.00 1 B200 170800.50 2 C400 85000.00 1 ===== =========== ============= 446300.50 4



12
Table Fields
DATAMINER can use data that is in tables, that is, in rows and columns. You can dynamically build data tables that you can search. Tables are useful for storing data from one dataset when you need to match records in another dataset. A table’s data can be imported from a dataset or reside in a data stream in your DATAMINER script.

The following diagram shows how table fields can be populated from multiple record fields.

The FIND subcommand allows you to retrieve a row in a table by finding a match for any specified table field. This command allows you to search for data in tables the same way you search for data in a database. Example 3 (page 12.14) shows how two unconnected datasets can be used together when using FIND to search for information.


Page

TABLE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.2Defining Table Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.4Arrays and Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.9DATA…ENDDATA Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . 12.13FIND Subcommand (Searching Tables) . . . . . . . . . . . . . . . . . . . . . . 12.14

INPUT=

Record n

F1 F2 F3 F4

Dataset

F1 F2 F3 F4Table 1Row n

DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields

TABLE Command

Description DATAMINER supports two sources of table data:

• A dataset specified at the start of the script.

• Part of the script containing the data.

The total size of all tables is limited to a little less than 2 gigabytes, and each row of a table can be up to 8 kilobytes long. (It can be loaded from a dataset with any size of record.) Within these limits, tables can have any number of rows and columns.

You define a table with the TABLE command. You then define its fields the same way you define the layout of record fields in a dataset.

Syntax The syntax for the TABLE command is

TABLE name [[FILE] filename] [[SIZE] [numrows | 1000]]

where

nameIs the name for your table.

filenameIs the ddname of a dataset that you defined with an INPUT= command prior to the TABLE statement. This dataset contains the data for the table. If you do not specify filename, use DATA and ENDDATA (page 12.13) to supply the information in your script.

[SIZE]Indicates that the following number specifies the number of rows you expect your table to contain.

numrowsIs the number of rows you expect your table to contain.

If numrows is not large enough to contain the entire table, DATAMINER acquires enough storage for further rows and continues to do so until it has enough memory. The default value is 1000.

Filling a Table You can fill table entries in two ways:

• If you define the table as being associated with a dataset, DATAMINER reads the specified fields from the entire dataset into the table before doing any processing

or



• If you do not associate a dataset with the table, you must provide the data for the table as part of your script. You use the DATA and ENDDATA subcommands (page 12.13) to mark the beginning and the ending of the data to be loaded into the table.

You do not need to tell DATAMINER how many rows there are in the table. Tables that are loaded with data in the script generally contain character or zoned numeric data because this is all that you can enter with a keyboard. Instream data, however, can contain any characters other than X'FE' and X'FF'.

Data does not have to be in any particular order. DATAMINER treats the first field you define as the key field for the table, but that does not need to be in any particular order, either.

Example: Defining a Table Using Data in a Dataset

The following example defines a table called BRANCHES; loads it with information from a dataset called BRFILE; and then defines the table fields BRANCH-NO, CITY, and RATE. Only the fields that the script references need be included in the table, as each field consumes storage. The fields may be added to the table in any order and not necessarily in the same order as the imported record.

TABLE BRANCHES FILE BRFILE*BRANCH-NO 1 5 CCITY 9 20 CRATE 40 6 P 2

Example: Defining a Table Using Data In the Script

The following example defines a table called DEPTS. It defines the table fields DEPT-CODE, DEPT-NAME, and DEPT-MANAGER; and then it loads the table with information contained in the script between DATA and ENDDATA. The arrows in this example show how field names are mapped to data fields. The dots (·) in each data line represent spaces. When DATA is used, it must be the first command following the field definitions.

TABLE DEPTSDEPT-CODE 1 4 C /* Table field 1DEPT-NAME 7 14 C /* Table field 2DEPT-MANAGER 23 30 C /* Table field 3*DATAACCT··ACCOUNTING······Joe BloggsSALE··SALES···········Penny WiseMAIN··MAINTENANCE·····Fred BorehamENDDATA



Defining Table Fields

Description Defining table fields is very similar to defining record fields. A table can have as many fields as you want. DATAMINER squeezes fields together in the table to remove any unused space.

Syntax The syntax for defining a table field is

tablefieldname startpos length type [decimalplaces]


If the field will be used with the REPORT command, you can add the following operands to the field definition. (MASK is an alternative to std-mask.)




tablefieldnameIs the name to assign to the table field.

tablefieldname can be up to 32 characters long.

tablefieldname must begin with a letter or one of the following characters:

@ # _ $

tablefieldname can include letters, numerals, and the following characters:

@ # _ - $

tablefieldname (the name itself) is not case sensitive; for example, BALANCE, Balance, bAlAnCe, and balance refer to the same field.

Do not define tablefieldname with the name of a DATAMINER command, parameter, system variable, or system constant. See “DataMiner Reserved Words” (page 2.15) for a list of reserved words.

Do not begin tablefieldname with a hyphen.



Do not begin tablefieldname with any of the following strings because DATAMINER’s own field names begin with them:

@#_

DMIN

DMIN_

You can use the same fieldname in multiple tables. To distinguish fields with the same name in different tables, use this syntax to refer to them (not to define them):

tblname:tblfieldname

For example,

EMPRECS:EMPLOYEE#

Do not try to define the same fieldname twice for the same table.

startposIs the starting position of tablefieldname. Table fields can overlap or have gaps between them. startpos is one of the following:

nA number for the nth byte of the record. For example, 32 specifies the 32nd byte of the record. The first byte’s position is 1 unless you have changed the offset. (See the “STATS Command,” page 2.13.)

* (asterisk)The byte following the previous field.

*+nThe nth byte higher than the byte following the previous field.

*-nThe nth byte lower than the byte following the previous field.

"The same location as the first byte of the previous field.

"+nThe nth byte higher than the first byte of the previous field.

"-nThe nth byte lower than the first byte of the previous field.

tablefieldname2The same location as the first byte of another field, tablefieldname2.



tablefieldname2+nThe nth byte higher than the first byte of another field, tablefieldname2.

tablefieldname2-nThe nth byte lower than the first byte of another field, tablefieldname2.

lengthThe length of the field in bytes. Table fields can overlap or have gaps between them. See the table under the next argument for allowable lengths according to the field’s data type.

typeIs a character that denotes the data type of the field:

[decimalplaces]Is the number of decimal places for the field. This operand is for numeric fields only (binary, packed, and zoned). The default is 0. If you specify a value, it must immediately follow the type operand.

[ OCCURS n TIMES ]Is the specification for a repeating table field that occurs n times per variable. The OCCUR keyword creates an array with n members. Be sure to see the INDEX (next), which is a sub-argument of OCCURS.



Comments


C Character 32,767



P Packed 16

Z Zoned 16

X Hexadecimal 8


N/A

D Date N/A



(ixname)Is the name of of the index, and it has the same naming requirements as recfieldname. For information on using an array’s index, see “Arrays and Indexing” (page 12.9).


M0 (The default) The field is printed with leading zeroes suppressed and with the same number of decimal places you specified for the field.

M1 9(13)-

M2 9(11).99-



M5 $$$,$$$,$$$,$$$.99- (Floating $)

Formatting notes:













[ HEADING ('headingline1' ['headingline2' ['headingline3' ]]) ]Specifies up to three lines of a column heading to be used for this field with the REPORT command. (By default, the REPORT command uses tablefieldname as the field’s column heading.) Alternatively, you can use the HEADING subcommand after the REPORT command to define a heading for this field. See Chapter 11, “Report Writer.”



Arrays and Indexing

Introduction An optional argument (OCCURS) in a table field definition (page 12.4) allows you to create arrays. A sub-argument of OCCURS is INDEX, and it gives you more flexibility in referencing an array’s contents.





tablefieldname(n)

where

tablefieldnameIs the name of the record field that is an array.


OCCURS 5 TIMES


The following example creates a table field array named MONTH that is three bytes long, is character data type, and OCCURS 12 times (that is, it has 12 members):

MONTH 3 C OCCURS 12 TIMES





You could therefore assign values to the members of the array with the SET command. The results of these lines is exactly the same as the examples under “INDEXing by INDEX Value” (page 12.10) and “INDEXing by Bytes Offset” (page 12.11).



The following example also creates a table field array named MONTH that is three bytes long, is character data type, and OCCURS 12 times (that is, has 12 members). It also is INDEXed with an index named NUM:





SET NUM = 1

2. Address the record field array’s name without a subscript.


MONTH


You could therefore assign values to the members of the array with the SET command. The results of these lines is exactly the same as the examples under “INDEXing by Subscripted Array Member Number” (page 12.9) and “INDEXing by Bytes Offset” (page 12.11).



SET NUM= 1SET MONTH= 'JAN' SET NUM= 2SET MONTH= 'FEB' SET NUM= 3SET MONTH= 'MAR' SET NUM= 4SET MONTH= 'APR' SET NUM= 5SET MONTH= 'MAY' SET NUM= 6SET MONTH= 'JUN' SET NUM= 7SET MONTH= 'JUL' SET NUM= 8SET MONTH= 'AUG' SET NUM= 9SET MONTH= 'SEP' SET NUM= 10SET MONTH= 'OCT' SET NUM= 11SET MONTH= 'NOV' SET NUM= 12

SET MONTH= 'DEC'


The following example also creates a record field array named MONTH that is three bytes long, is character data type, and OCCURS 12 times (that is, has 12 members). It also is INDEXed with an index named NUM:


To address the different members of the array in this method, set the value of NUM to the zero-based offset of each member and subscript the index name to the record field name. That is, to address an array member, there are two steps:




2. Address the record field array’s name with the index name subscripted.


MONTH(NUM)




You could therefore assign values to the members of the array with the SET command. The results of theses lines is exactly the same as the examples under “INDEXing by Subscripted Array Member Number” (page 12.9) and “INDEXing by INDEX Value” (page 12.10).




DATA…ENDDATA Subcommands

Description This pair of commands lets you provide table data in your script.

Syntax The syntax for the DATA…ENDDATA commands is

DATA<consistently laid-out table records>

ENDDATA

Example The following example loads the table DEPTS with information contained in the script. The data fields in each row must start in the same columns.

TABLE DEPTSDEPT-CODE 1 4 CDEPT-NAME 7 15 CDEPT-MANAGER 23 30 CDATAACCT ACCOUNTING Joe BloggsSALE SALES Penny WiseMAIN MAINTENANCE Fred BorehamENDDATA



FIND Subcommand (Searching Tables)

Description Finding data in a table is very similar to reading a record by key from a keyed dataset. The FIND command retrieves a row in a table by finding a match for any specified table field.

After you have found the row you are looking for, any reference to a field name in the table returns the data from the found row. There is no need for indexes or subscripts.

Syntax The syntax for the FIND command is

FIND tablename [ WHERE | MATCHING ] tablefieldname =

{ recfieldname | tablefieldname2 | uservar | sysvar | sysconst | 'literal' }

where

tablenameIs the name of the table you want to search.

tablefieldnameIs the name of the table field you want to search.

recfieldname, tablefieldname2, uservar, sysvar, sysconst, or 'literal'

Is the value you are searching for in tablefieldname. It is a record fieldname, table fieldname, user variable, system variable, system constant, or literal.

Examples 1. The following FIND example searches the DEPTS table for records whose DEPT-CODE fields contain the literal string SALE:

FIND DEPTS DEPT-CODE = 'SALE'

2. The following FIND example searches the BRANCHES table for records whose CITY fields contain the value of the TOWN record field in the INFILE dataset:

FIND BRANCHES MATCHING CITY=INFILE:TOWN

3. The following script example shows how two unconnected datasets can be used together when searching for information.



* Define an employee VSAM dataset and record fields of interestINPUT=VSAM FILENAME=EMPFILEEMPNO 1 6 CEMPDEPT 135 5 CSALARY 312 6 P 2

* Define a department sequential dataset, and load a table with * department numbers INPUT=DISK FILENAME=DEPFILETABLE DEPTTAB FILE DEPFILEDEPNO 1 5 C

* Locate and print employees with no matching department numberPRINT /* Print basic report

FIND DEPTTAB WHERE DEPNO = EMPDEPT /* Search dept table for employee deptONLY DEPTTAB:IO-RESULT = 'NFD' /* Include only those employees with

/* no matching department

SELECT EMPNO EMPDEPT SALARY /* Select which fields to print



13
SORT Command
DATAMINER has its own SORT command and several timing commands to control when the SORTing occurs in your processing.

This chapter includes the following sections:

Page

SORT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.2Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.2Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.2Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.2Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.3Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.3

DATAMINER FOR Z/OS 7.1C User Reference Guide SORT Command

SORT Command

Description DATAMINER can SORT a dataset into any order using any field types recognized by your SORT program. The SORT command can use one or multiple keys in any combination of ascending and descending order. All fields and datasets used by DATAMINER’s SORT command are defined the same way as any other field and can be used in any other DATAMINER commands executed at the same time. DATAMINER’s syntax is simpler than the syntax used by separate SORT programs.

Besides simply SORTing a dataset, you can add extra processing to your SORTing script by using the timing commands (“Timing Commands” on page 8.15) to tell DATAMINER when the processing is to be performed.

The SORT command is not allowed to run with other shortcut commands in the same script, or even another SORT command. All other processes must be run in another job step.

Syntax The syntax for the SORT command is

SORT input-dataset [INTO] output-dataset BY [-]field ...

where

input-datasetIs the source dataset containing the data to sort.

output-datasetIs the destination dataset for the sorted data.

-Is a flag to field that specifies descending sort order. The default is ascending order.

fieldIs the field by which to sort the data.

Each subsequent specification of a field (with or without the descending-order flag) is sorted subordinately to the previously specified field.

Example 1 The following example sorts the dataset ACCOUNT in ascending NAME order, creating a new dataset called NEWACCT.

SORT ACCOUNT INTO NEWACCT BY NAME



Example 2 The following example sorts the dataset ACCOUNT first in ascending NAME order and then in descending AMOUNT order, creating a dataset called NEWACCT.

SORT ACCOUNT INTO NEWACCT BY NAME -AMOUNT

Example 3 The following example sorts the ACCOUNT dataset in ascending NAME order, omitting all the records whose AMOUNT field is negative and creating a new dataset called NEWACCT.

In this example, the SKIP command is the usual DATAMINER SKIP command (page 9.14).

SORT ACCOUNT INTO NEWACCT BY NAMESKIP AMOUNT < 0



14
Troubleshooting Commands
DATAMINER provides commands that can help you analyze records and troubleshoot problems with DATAMINER scripts.


Page

ABEND Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.2CANCEL Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.3SHOW Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.4TRACE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.6

DATAMINER FOR Z/OS 7.1C User Reference Guide Troubleshooting Commands

ABEND Command

Description The ABEND command is a debugging tool. It immediately causes a program check when the required condition is met, which gives a dump of the DATAMINER region.

See also “DUMP Shortcut Command,” page 6.12.

Syntax The syntax for the ABEND command is

ABEND



CANCEL Command

Description The CANCEL command causes the script to cancel. Any following jobsteps are discarded. A cancel can only follow an IF selector (see “IF…[ELSE]…ENDIF Statements,” page 8.3).

Syntax The syntax for the CANCEL command is

CANCEL [rc | 16 ]

where

rcIs the return code DATAMINER returns to the system. The default is 16.

Example The following example terminates the job if a record is found with a zero BALANCE field:

IF BALANCE EQ 0CANCEL

ENDIF



SHOW Command

Description The SHOW command is intended mainly for use by computer support staff who want to see a hexadecimal and character snapshot of a dataset, part of a dataset, or individual records and fields.

Syntax The syntax for the SHOW command is

SHOW {fieldname | filename}

where

fieldnameIs the name of a record field, table field, user variable, or system variable.

SHOW fieldname displays the whole of the named field as it would be displayed in a program dump, with hexadecimal on the left and a character version on the right. It shows what is in the field when the SHOW command is executed, which is not necessarily what was in the field when the record was read.

filenameIs the name of a dataset named in an INPUT= or OUTPUT= command.

SHOW filename displays the entire current record for a dataset. It can be used for both input and output datasets to show exactly what the current record looks like when the SHOW is issued. If your script has changed some fields in the input record, you see the modified version. If your script built only part of the output record, that is all you see.

Example: SHOW Filename

The following example is output from the SHOW filename command:

Example: SHOW Fieldname

The following example is output from the SHOW fieldname command:

RECORD NUMBER - IN= 2,OUT= 2 LRECL= 131 0 F2F2F3F0 F5F0F7F5 D9C5C3D5 D66EF0F0 F0F0F0F0 F0F2C6D5 D46ED1C1 D4C5E240

*22305075RECNO>00000002FNM>JAMES * 20 40404040 40404040 4040D3D5 D46ED4C3 C6C1D9D3 C1D5C540 40404040 40404040 *

LNM>MCFARLANE * 40 40404040 40404040 40404040 4040C2C1 D36E1449 67872DC6 D3C1C76E FAC1D4E3 *

BAL>.Ñçg•FLAG>úAMT* 60 F16E3539 2DC1D4E3 F26E0151 5977984C C2C9D5F3 6E5C5A68 C2C9D5F4 6E5A6885

*1>¤¨•AMT2>.Òà÷q<BIN3>*!èBIN4>!èe* 80 2EE7E7

*–XX *

CONTENTS OF FIELD OUTFILE:FLD1 0 F0F9F3F1 F5F0F7F5 D9C5

*09315075RE *



About the Examples Be aware of the following for the SHOW command:

• The headings are very different for SHOW fieldname and SHOW filename.

• The offset into the record shown down the left hand side is in hexadecimal.

• No character translation takes place on the character display at the right-hand end of the line.



TRACE Command

Description The TRACE command helps you debug your script. The DISPLAY command (page 7.14) and SHOW commands are also helpful for this purpose. TRACE prints messages that show what commands your script is executing.

TRACE can be turned on and off during the execution of your script, allowing you, for example, to trace only for record 12345678.

Syntax The syntax for the TRACE command is

TRACE { ON | OFF | FLOW }

where

ONTurns on all tracing; every command you execute produces a trace line.

OFFTurns tracing off for the rest of the job or until another TRACE ON or TRACE FLOW is encountered.

FLOWTurns on tracing only for commands that control the logic flow through your script such as IF, GOTO, and PERFORM.

ENDIF is never actually executed and so is not traced. Also, the command shown in the trace may not be the command that you wrote if DATAMINER has decided to translate your command to one that it considers better. This may happen if you enter a command in a non-DATAMINER language that DATAMINER recognizes.

There is no default value for the operand; you must specify a value.

TRACE Example The line numbers in this example are created by DATAMINER when it reads your script. Line 13 turns on tracing. Line 14 displays in the trace as a SET command because DATAMINER changes all ADD, SUBTRACT, and other instructions to arithmetic expressions.

13 TRACE ON14 ADD 1 TO JAMES15 IF K2 = '4' GOTO TYPE416 ENDIF17 DISPLAY JAMES /* Other statements follow



The following is the corresponding TRACE output:

Explanation The ADD in line 14 of the script displays in the trace as a SET command because DATAMINER changes all ADD, SUBTRACT, and other instructions to the SET command with arithmetic expressions.

ENDIF does not display in the trace because DATAMINER does not execute any code for an ENDIF.

The data displayed by line 17 of the script (“52 O”) is displayed on the same print file as the trace because TRACE and DISPLAY both use the system print file for their output.

DMIN-506 >>> STATEMENT AT START OF SCRIPT ABOUT TO EXECUTEDMIN-505 >>> STATEMENT 13 TRACE ABOUT TO EXECUTEDMIN-505 >>> STATEMENT 14 SET ABOUT TO EXECUTEDMIN-505 >>> STATEMENT 15 IF ABOUT TO EXECUTEDMIN-505 >>> STATEMENT 17 DISPLAY ABOUT TO EXECUTE52 ODMIN-506 >>> STATEMENT AT END OF SCRIPT ABOUT TO EXECUTE



15
DB2 Commands
DATAMINER works with DB2. This chapter describes the commands that provide this support. The information in this chapter assumes you already know how to use DB2.


Page

DB2 Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.2CONNECT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.3INPUT= Command (DB2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.4OUTPUT= Command (DB2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.5EXECUTE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.6CLOSE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.7COMMIT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.8ROLLBACK Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.9Host Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.10Additional Information about DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . 15.11DB2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.12

DATAMINER FOR Z/OS 7.1C User Reference Guide DB2 Commands

DB2 Access

Introduction DATAMINER can access DB2 for z/OS. DATAMINER uses a dynamic SQL interface, so your script does not require a precompile or BIND.

All DATAMINER input functions are supported; for example, you can create reports or extract data from your DB2 tables. DB2 update is accomplished with the DATAMINER EXECUTE command.



CONNECT Command

Description The CONNECT command connects DATAMINER to a DB2 for z/OS application server.

Syntax The syntax for the CONNECT command is

CONNECT SSID(ssid) PLAN(plan_name)

where

ssidIs the subsystem ID of the DB2 host you want to access.

plan_nameIs the name of the plan into which you bound the CSIDMBSQ DBRM (using BIND) when you installed DATAMINER.



INPUT= Command (DB2)

Description In addition to the parameters already documented for the INPUT= command (page 3.3), the INPUT= command has parameters that apply to DB2 only.

Syntax The syntax for the INPUT= command is

INPUT={SQL|DB2} [STATEMENT=statement_name](select_statement)

where

statement_nameIs a one- to eight-character name that allows other commands (AUTO, EXECUTE) to reference it.

select_statementIs any valid SQL select statement. The statement can include host variables as discussed below. The select statement is prepared when the INPUT= command is encountered. Use the EXECUTE command to actually fetch a row from the table.



OUTPUT= Command (DB2)

Description In addition to the parameters already documented for the OUTPUT= command (page 3.3), the OUTPUT= command has parameters that apply to DB2 only.

Syntax The syntax for the OUTPUT= command is

OUTPUT={SQL|DB2} [STATEMENT] statement_name (select_statement | insert_statement | delete_statement)

where

statement_nameIs a one- to eight-character name that allows other commands (AUTO, EXECUTE) to reference it.

update_statementinsert_statementdelete_statement

Is any valid SQL update, insert, or delete statement. The statement can include host variables as discussed in “Host Variables” (page 15.10). The statement is prepared when the OUTPUT= command is encountered. Use the EXECUTE command (page 15.6) to actually execute the command.



EXECUTE Command

Description The EXECUTE command executes

• A DB2 or SQL statement defined in an INPUT= or OUTPUT= command in your DATAMINER script

• A DB2 or SQL statement defined in-line in the EXECUTE command

In either case, any DB2 or SQL statement that can be dynamically executed is allowed.

Syntax The syntax for the EXECUTE command is

EXECUTE {[STATEMENT] statement_name | SQL(statement) | SQL(statement)}

where

statement_nameIs the name of a DB2 or SQL statement defined in an INPUT= or OUTPUT= command in your DATAMINER script.

statementIs a DB2 or SQL statement defined here in the EXECUTE command.



CLOSE Command

Description The CLOSE command closes a DB2 cursor.

Syntax The syntax for the CLOSE command is

CLOSE [STATEMENT] input_statement_name

where

input_statement_nameIs the name of a DB2 or SQL statement defined in an INPUT= command in your DATAMINER script.



COMMIT Command

Description The COMMIT command terminates the current logical unit of work and commits the database changes that were made by that logical unit of work.

Syntax The syntax for the COMMIT command is

COMMIT



ROLLBACK Command

Description The ROLLBACK command ends a logical unit of work and backs out the database changes that were made by that logical unit of work without committing (saving) the work. Compare this command to the COMMIT command (page 15.8).

Syntax The syntax for the ROLLBACK command is

ROLLBACK



Host Variables

Description You can address host variables.

Syntax The syntax for addressing host variables is

:{ [dataset.]recfield | [statement_name.]column_name | uservar }

where

datasetIs the dataset name specified by the INPUT= command (page 3.3).

recfield Is the name of a record field.

statement_nameIs an INPUT=SQL statement name.

column_nameIs a column in the DB2 table reference by statement_name.

uservarIs a user variable.

SQL host variables begin with a colon. DATAMINER’s dataset-specific variables are prefixed with the dataset name or statement_name and a colon. Because of this conflict, when you specify a dataset name or a statement name with a host variable, prefix the fieldname/column_name with a period.

Example The following example refers to record field EMPNO in the statement SQLEMP:

:SQLEMP.EMPNO



Additional Information about DB2

Field Names Unlike VSAM or sequential datasets, where field names must be specified following the INPUT= or OUTPUT= commands (or optionally by including a copybook), DB2 field names are automatically defined by DATAMINER when the statement is prepared.

Cursors Each INPUT= statement opens and fetches from its own cursor. When the EXECUTE command specifies a SQL statement (opposed to referencing an INPUT= command) it opens and fetches from its own cursor also. A maximum of 10 cursors can be opened concurrently.

System Variables These fields correspond to the first SQL statement defined in the DATAMINER script. To explicitly refer to a corresponding SQL statement, specify the SQLCA field in the following format:

statement_name:fieldname

For example, SQLEMP:SQLCODE refers to the SQLCODE for the SQLEMP statement.

The following SQLCA fields are automatically defined. Refer to the SQL reference guide for a description of each field.

• SQLCODE

• SQLERRM

• SQLERRP

• SQLERRD1-6

• SQLWARN0-A

• SQLSTATE



DB2 Examples

Example 1: Simple Auto Print

The following example prints one line for each row in the EMPLOYEE table in which the salary is greater than 50000. No reference to the INPUT= statement is required because the PRINT command automatically loops through the script and fetches each row from the table.

The output looks like the following:

WORKDE EMPNO LASTNAME SALARY A00 000010 HAAS 196947.05 D21 000070 PULASKI 70485.07 A00 000110 LUCCHESI 173605.49

Example 2: Auto-Read Report

The following example prints one line for each row in the EMPLOYEE table, organized by department, sorted in descending order by salary, and with a summary total for salary.

The AUTO command is used to auto-read the EMPSEL table.


INPUT=SQL(SELECT * FROM EMPLOYEE WHERE SALARY > 50000) PRINT SELECT WORKDEPT,EMPNO,LASTNAME,SALARY

INPUT=SQL STATEMENT=EMPSEL(SELECT * FROM EMPLOYEE) AUTO EMPSEL PRINT SALRPT

REPORT SALRPT LINE WORKDEPT,EMPNO,LASTNAME,SALARY ORDER WORKDEPT, -SALARY BREAK WORKDEPT SUM SALARY

WORK EMPNO LASTNAME SALARY A00 000100 HAAS 196947.05 000110 LUCCHESI 173605.49 000120 O'CONNELL 109203.32 === ====== =============== ============= A00 479755.86

C01 000030 KWAN 38250.00 000140 NICHOLLS 28420.00 000130 QUINTANA 23800.00 === ====== =============== ============= C01 90470.00



Example 3: Manual-Read Report

The following example shows how a script can control the row fetch process. The output is identical to the output in Example 2. It prints one line for each row in the EMPLOYEE table, organized by department, sorted in descending order by salary, and with a summary total for salary.

INPUT=SQL STATEMENT=EMPSEL(SELECT * FROM EMPLOYEEEXECUTE STATEMENT=EMPSELWHILE (EMPSEL:SQLCODE = 0) PRINT SALRPT EXECUTE STATEMENT=EMPSELENDWHILE

REPORT SALRPTLINE WORKDEPT,EMPNO,LASTNAME,SALARYORDER WORKDEPT, -SALARYBREAK WORKDEPTSUM SALARY

Example 4: Multiple Cursors

The following example opens two cursors (EMPSEL1 and EMPSEL2) and fetches rows from them:

Example 5: Simple Table Update

The following example increases employees’ salaries by 5 percent in department A00.

EXECUTE SQL(UPDATE EMPLOYEE SET SALARY=SALARY+SALARY*0.05 WHERE WORKDEPT='A00')

INPUT=SQL STATEMENT=EMPSEL1(SELECT * FROM EMPLOYEE WHERE SALARY > 50000) INPUT=SQL STATEMENT=EMPSEL2(SELECT * FROM EMPLOYEE WHERE SALARY < 50000) EXECUTE STATEMENT=EMPSEL1 EXECUTE STATEMENT=EMPSEL2 WHILE (EMPSEL1:SQLCODE = 0 AND EMPSEL2:SQLCODE = 0) DISPLAY 'EMPSEL1' EMPSEL1:EMPNO EMPSEL1:SALARY DISPLAY 'EMPSEL2' EMPSEL2:EMPNO EMPSEL2:SALARY EXECUTE STATEMENT=EMPSEL1 EXECUTE STATEMENT=EMPSEL2 ENDWHILE



Example 6: Table Update with Host Variables

The following example updates employees’ salaries based on department. User variables RAISE and DEPT are defined and specified as host variables in the SQL update statement. A procedure named UPDSAL is called to perform the update.

The SQLCA field SQLERRD3 is displayed to show how many employees in each department were given raises. If any update fails along the way, a ROLLBACK is issued and the script terminates.


DEFINE RAISE 2,P,2 DEFINE DEPT 3,C OUTPUT=SQL EMPUPD (UPDATE EMPLOYEE SET SALARY=SALARY+SALARY*:RAISE WHERE WORKDEPT=:DEPT) DEPT = 'A00' RAISE = 0.05 PERFORM UPDSAL DEPT = 'D21' RAISE = 0.10 PERFORM UPDSAL PROC UPDSAL EXECUTE STATEMENT=EMPUPD IF (SQLUPD:SQLCODE = 0) DISPLAY 'DEPT=' DEPT ',RAISE=' RAISE ',EMPLOYEE COUNT=' SQLUPD:SQLERRD3 ELSE DISPLAY 'ERROR ENCOUNTERED' SQLUPD:SQLCODE ROLLBACK GOTO EXIT ENDIF ENDPROC EXIT.

DEPT= A00 ,RAISE= 0.05 ,EMPLOYEE COUNT= 3DEPT= D21 ,RAISE= 0.10 ,EMPLOYEE COUNT= 6



Example 7: Extract from DB2 to Sequential Dataset

The following example creates a sequential dataset composed of selected columns from a table:

EXTRACTINPUT=SQL (SELECT * FROM EMPLOYEE) OUTPUT=DISK FILENAME=SQLEMP LRECL=100BLKSIZE=4000 FIXBLKSELECT WORKDEPT,EMPNO,LASTNAME,SALARY

Example 8: Extract from VSAM to DB2

The following example uses EXTRACT to insert rows into a DB2 table. The script selects certain employee records and fields from a VSAM dataset. Then it PRINTs each new employee added:

EXTRACT* Define input VSAM dataset and record fieldsINPUT=VSAM FILENAME=EMPVSAMEMPNO *,6,CFIRSTNME *,10,CLASTNAME *,13,CSALARY *,5,P,2*Connect to DB2 and define SQL insert commandCONNECT SSID(ssid) PLAN(plan-name)OUTPUT=DB2 STATEMENT=SQLOUT (INSERT INTO EMPLOYEE (EMPNO,FIRSTNME,LASTNAME,SALARY) VALUES(:EMPNO,:FIRSTNME,:LASTNAME,:SALARY)) *Print list of each employee record addedPRINTSELECT EMPNO,LASTNAME,SALARYWHERE EMPNO > '050000'



16
DATAMINER Messages
DATAMINER produces most of its messages on the printer, and a few critical messages are also sent to the console. DATAMINER does not expect any replies from the console. Besides printing all of the control statements you enter, it also prints a summary of what it has completed and error messages describing any errors it found in your input.

DATAMINER messages have one of the following formats:

• DMINnnnE (for error messages)

• DMINnnnW (for warning messages)

• DMINnnnI (for informational messages).


Page

Summary Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.2Syntax Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.3General Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.12

DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages

Summary Messages

Introduction Summary messages are produced at the end of a run to tell you how many records have been processed. If any of the system variables, such as INPUT_RECORD, have been updated by your script, the numbers printed in the summary messages reflect the changes you made. You can control printing of statistics with the STATS command.

Some summary messages follow. In the following information, filename means the name of the file from the INPUT= command (for example, INFILE=); datasetname means the 44-character name of the file on disk (for example, XYZCO.MASTER.ACCOUNTS).

nnn RECORDS READ FROM filename datasetname

The total number of records that were read from the input datasets. The total includes any records skipped, ignored, or processed in this run. If you ended the run early, with a STOP or LAST command, for example, the number in this message may be less than the number of records in the input dataset.

nnn RECORDS WRITTEN TO FILE filename datasetname

The total number of records that were written to the output dataset.

nnn RECORDS UPDATED IN FILE filename datasetname

The number of records in the main input dataset that were changed in this run.

nnn RECORDS DELETED FROM FILE filename datasetname

The number of records deleted from the main input dataset.

nnn DATA RECORDS PRINTED

The number of detail lines that were printed. The number does not include heading or summary lines. If the message says, “500 LINES PRINTED,” DATAMINER printed a line for each of 500 records from the dataset.

nnn DATA RECORDS DUMPED

The number of records dumped to the printer, not the actual number of printed lines that is usually greater than the number of records.

nnn FIELD VALIDATION ERRORS

The number of invalid numeric fields that were found in the dataset. This number includes only the numeric fields used in DATAMINER commands.



Syntax Error Messages

Introduction Syntax errors are generally detected as each input statement is processed. Therefore, these messages usually print immediately below the input statement that caused the error. DATAMINER also prints the word it was working on when it detected the error. The word DATAMINER is working on may actually be a little later in the script than the actual error (possibly even on the next command), depending on the nature of the error.

Note DATAMINER does not allow you to use command words (such as PRINT, COPY, and INPUT) as field names. Any attempt to do so is likely to lead to an error message whose exact cause is not immediately obvious. See “DataMiner Reserved Words” (page 2.15) for a list of reserved words.

Message Example Here is an example of error message output:

7 ADD FOOT TO LEGDMIN003E First parameter is invalid FOOT

The first line of the message is the user’s command, and the second line is the error message.

The word on the end of the message is what DATAMINER was looking at when it discovered the error. In this example, the last word is FOOT; however, DATAMINER reads ahead through the script so that the word on the end of the message may not be the one that actually caused the error to be identified.



Message Table The following table lists the error codes, messages, and their meanings.

Error Code Error Message Meaning

DMIN001E Fieldname is too long The length of a field name is too long. The name of a field must be no more than 32 characters long. It can be less than 32 characters long.

DMIN002E Invalid fieldname or literal

You entered a literal that breaks the syntax rules, such as '290, or a field name with an invalid character in it, such as PAY?AMT

DATAMINER expects either a field name or a literal, but the word it is looking at is neither. Either the filename contains an invalid character, the fieldname has not been declared, or the literal is neither a valid number nor enclosed in quotes.

DMIN003E First parameter is invalid

The first parameter in the current command has an invalid value.

DMIN004E Second parameter is invalid

The second parameter in the current command has an invalid value.

DMIN005E Invalid fieldname DATAMINER expects a fieldname and does not recognize the value specified as a fieldname.

DMIN006E Field start position is invalid

The start position of the field is not numeric or refers to a field that has not been defined.

DMIN007E Field length is invalid

In a field definition, the field length is too big or not numeric.

DMIN008E Field type is unrecognized

In a field definition, the type is not B, C, D, P, S, T, V, X, or Z.

DMIN009E Decimal places value is invalid

In a field definition, the decimal places value for a numeric field is larger than the field or not numeric.

DMIN010E Invalid SELECT parameter

In a SELECT command, you have not defined the field named in the command or you have included an invalid literal.



DMIN011E Field already defined/reserved

In a field definition, you are using a field name that has already been defined or is a system variable, such as T1.

DMIN012E Invalid literal There is no closing quote on a literal, or the literal is too long.

DMIN013E Wrong number of parameters

DATAMINER expects more or fewer parameters in the command than you have given it.

DMIN014E Invalid operator DATAMINER expects a relational or arithmetic operator but the operator used is not valid. Examples of relational operators are =, >, <, EQ, LT, NGT.

DMIN015E VALIDATE must be Y, N, L, or D

Y, N, L, and D are the only acceptable values for VALIDATE.

DMIN016E Invalid mask value The mask value must be M1, M2, M3, M4, or M5.

DMIN017E Too many VALUEs given In an INSERT command, more values are given than there are fields into which to put them.

DMIN018E Not enough VALUEs given

In an INSERT command, more fields are given than there are values to put into them.

DMIN019E (Not used)

DMIN020E Unrecognized file type You are trying to do an operation that is not valid for the type of dataset you are using.

DMIN021E BLKSIZE not a multiple of LRECL

You defined a dataset as fixed block but the block size is not a multiple of the record size.

DMIN022E Invalid LRECL The LRECL given for a dataset is invalid, such as not numeric or larger than the blocksize.

DMIN023E Invalid blocksize The blocksize is not numeric or is too large.

DMIN024E Invalid FSF value Number of datasets to forward space is not numeric.




DMIN025E Unknown device type Device type on an INPUT or OUPUT command is not CARD, DISK, TAPE, VSAM, DB2, or SQL.

DMIN026E Invalid file definition

Invalid option specified in a dataset definition, such as variable-length cards.

DMIN027E No file info in JCL or catalog

Either there is no JCL statement for the dataset or, for a VSAM dataset, there is no entry in the catalog.

DMIN028E Invalid SYSnnn number The SYS number used must be a valid one for the current system and no greater than the highest SYS number allowed in the current partition.

DMIN029E Invalid system SYS number

An alphabetic SYS number has been given but it is not one of the following: SYSPCH, SYSLST, SYSLNK, SYSRES, SYSREC, SYSVIS, or SYSCAT.

DMIN030E "LABELS" must be STD or NO

The LABEL value must be STD (standard label) or NO (no label).

DMIN031E Update in place needs VSAM file

Update in place to sequential datasets requires that a special patch be obtained from CSI. Contact Technical Support.

DMIN032E Invalid command DATAMINER does not recognize the first word of the command. This message can be caused by an error in the previous command so that DATAMINER does not know where the next command starts.

DMIN033E No matching "IF" or "DO" command

An ENDIF or ENDDO was found for which there is no matching IF or DO command. Can also be caused by there being an error in the IF command that this ENDIF finishes.

DMIN034E Invalid file operation A READ, WRITE, etc., specifies an option that is not valid for this operation.




DMIN035E File has not been defined

There is no valid INPUT or OUTPUT command for this dataset.

DMIN036E Invalid field/file name for SHOW

A SHOW command refers to a field or dataset that has not been defined.

DMIN037E RETURN has no matching PROC

A RETURN command has been encountered outside a procedure.

DMIN038E PROC has no matching RETURN

There must be just one RETURN command at the end of a PROC to show where the PROC ends.

DMIN039E Message DMIN039E is unused.

DMIN040E Invalid TITLE for report

The title is too long or not enclosed in quotation marks.

DMIN041E Premature end of script

The end of the script has been found in the middle of a command or before a required RETURN or ENDIF was found.

DMIN042E Invalid DISPLAY parameter encountered

An invalid DISPLAY parameter was encountered.

DMIN043E BREAK set already for this field

A field can be used to break a report only once.

DMIN044E Report has not been defined

PRINT command issued for an unknown report name.

DMIN045E Too many ORDER fields A report can be ORDERed by no more than eight fields.

DMIN046E The file is not a KSDS POINT can be issued only to a VSAM KSDS.

DMIN047E REPORT subcommand subcmdname encountered a invalid value

subcmdname is a REPORT subcommand, such as ACROSS, WIDTH, or HEIGHT.





DMIN052E Table file has not been defined

A table needs to be loaded from a dataset but there is no INPUT command for the dataset.




DMIN053E Table has not been defined

A FIND command refers to a table that has not been defined with a TABLE command.

DMIN054E Field not in this table

A FIND command refers to a field that is not in the named table.

055E (Not used)

056E Invalid AUTO command.

DMIN057E Table already defined A table with the same name is already been defined.

58E Table SIZE must be numeric.

DMIN059E Invalid table name A table name can be up to eight alphanumeric characters, beginning with a letter.

DMIN060E Expecting AND, OR or field

DATAMINER has encountered invalid IF command syntax.

DMIN061E ORDER/BREAK field not in report

Fields named in an ORDER or BREAK command must also appear in the report.

DMIN062E SQL statement has not been defined

An EXECUTE command cannot locate a corresponding INPUT or OUTPUT statement.

DMIN063E DB2 OUTPUT is not allowed with COPY

The COPY shortcut command is not allowed to specify DB2 for OUTPUT.

DMIN064E Field is too long for record

A field is being defined that goes beyond the maximum record length for the dataset.

DMIN065E (Not used)

DMIN066E Equal sign is missing An equal sign was expected but was not found.

DMIN067E (Not used)

DMIN068E Invalid expression An invalid expression has been detected. Refer to the the documentation on the specific command for valid expressions.




DMIN069E Invalid initial value An invalid VALUE has been specified for the DEFINEd user varaible. For example, you cannot specify a character string for a packed decimal user variable.

DMIN070E VALUE is only for user variables

The VALUE parameter is allowed with only user variables DEFINEs and not with record field definitions.

DMIN071E INCLUDED member not found

The member specified on the COPY statement is not found.

DMIN072E (Not used)

DMIN073E (Not used)

DMIN074E Unrecognized date format

While processing a COBOL copybook, DATAMINER encountered an invalid DATE statement.

DMIN075E Invalid OCCURS clause statement.

While processing a COBOL copybook, DATAMINER encountered an invalid OCCURS

DMIN076E Invalid or missing subscript

A fieldname or user variable that expected a subscript was specified with an invalid subscript value or none at all.

DMIN077E REDEFINED field not found

While processing a COBOL copybook, DATAMINER encountered a REDEFINES statement that referred to a unknown field.

DMIN078E Unable to open SYSLIB for COPY

A failure occurred during an attempt to open the SYSLIB dataset.

DMIN079E SYSLIB must be fixed length PDS

The SYSLIB dataset is not a fixed-length PDS.

DMIN080E Value must be ON or OFF

The SCRIPT command had a value other than ON, YES, OFF, or NO.

DMIN081E Cannot load CALLed program

Either the name specified on the CALL command is invalid or the program load failed.




DMIN082E Too many parameters on CALL

The CALL command specified more than the maximum 256 parameters.

DMIN083E (Not used)

DMIN084E (Not used)

DMIN085E Unknown or unsupported SQL command

DATAMINER encountered an invalid parameter while processing an SQL statement.

DMIN086E VALUE must be a field or literal

DATAMINER encountered an invalid parameter while processing the VALUES subcommand of the INSERT shortcut command.

DMIN087E Invalid displacement on redefine

The displacement specified on a field redefinition must be + followed by an integer.

DMIN088E (Not used)

DMIN089E Invalid TRACE value The TRACE parameter value must be ON, OFF, or FLOW.

DMIN090E (Not used)

DMIN091E Invalid SORT file The SORT dataset must first be defined with the INPUT or OUTPUT command.

DMIN092E Field type not supported by SORT

SORT fields must be character, zoned, packed, binary, or hexidecimal.

DMIN093E Invalid BEFORE, DURING or AFTER option

Refer to “Timing Commands” (page 8.15) for valid syntax.

DMIN094E DEPENDING ON field not defined

While processing COBOL copybook, DATAMINER encountered a DEPENDING ON statement that referred to a unknown field.

DMIN095E INDEXED BY field must be 4 byte binary

The INDEXED BY field referenced a field or user variable which was not binary length 4.




DMIN096E SORT command must run in own script

The SORT command cannot be combined with other shortcut commands such as COPY or PRINT.

It also is not allowed to be combined with other SORT commands. Run the SORT command in a separate script in its own jobstep.

DMIN097E Duplicate report name definition

The same report name was already encountered in this script. Choose a different name.

DMIN098E Only one auto-input file allowed

More than one input file has been detected. Remove all but one of the AUTO INPUT commands.




General Messages

List of Messages DATAMINER generates the following general DMIN messages:

DMIN-102 NOT ENOUGH WORKING STORAGE AVAILABLE AT location

DMIN-103 DDNAME xxxx IS EITHER NOT IN JCL OR NOT IN CATALOG

DMIN-104 DDNAME xxxx FAILED OPEN, RC=nnnn,RSN=nnnn

DMIN-105 MORE INFO NEEDED ABOUT RECFM & SIZE FOR filename

DMIN-106 filename NOT DEFINED AS REUSABLE

DMIN-107 NO BLOCKSIZE DEFINED FOR filename - SET TO nnnnn

DMIN-108 NO LRECL DEFINED FOR filename - SET TO nnnn

DMIN-109 NO BLOCKSIZE OR LRECL FOR filename - CANNOT CONTINUE

DMIN-110 BLOCKSIZE IS NOT A MULTIPLE OF LRECL FOR filename

DMIN-111 filename MUST BE ASSIGNED TO A PRINTER

DMIN-201 DDNAME filename NOT FOUND IN JCL STATEMENTS

DMIN-202 DDNAME filename FAILED OPEN, RC=nnnn,RSN=nnnn

DMIN-203 error ON filename, KEY=kkkkkk

DMIN-205 MORE INFO NEEDED ABOUT RECFM & SIZE FOR filename

DMIN-206 VSAM xxxx CB ERROR R15= nnn, RSN= nnn, TERMINATING

DMIN-207 OPC=xxxx, RSVA=xxxx, UCB=xxxx, RCA=xxxx

DMIN-208 NOT ENOUGH WORKING STORAGE AVAILABLE

DMIN-209 INVALID I/O REQUEST (xxx)

DMIN-210 INPUT FILE filename NOT FOUND IN CONTROL BLOCKS



DMIN-301 "COPY" NEEDS INPUT & OUTPUT FILES. SCRIPT TERMINATED

DMIN-302 NO OUTPUT FILE NAME FOUND. SCRIPT WILL NOT BE RUN

DMIN-303 "PRINT" WAS REQUESTED BUT NO FIELDS WERE SELECTED

DMIN-305 NOT ENOUGH WORKING STORAGE AVAILABLE

DMIN-306 "DELETE" NEEDS BOTH A START AND END POINT

DMIN-307 ONE OR MORE FIELDS TOO LONG TO FIT ON PRINT LINE

DMIN-308 PROC OR LABEL NOT DEFINED AT LINE NNN

DMIN-309 REPORT reportname NOT DEFINED AT LINE nnn

DMIN-310 Unable to load "SORT" program - job terminated

DMIN-400 NOT ENOUGH PARTITON GETVIS'

DMIN-432 CURRENT RECORD DATA IS: xxxxxxxxxxxx

DMIN-433 TABLE tablename HAS NO FIELDS

DMIN-501 SCRIPT CONTAINS GARBAGE AT LINE nnn

DMIN-502 OUTPUT LENGTH NOT AVAILABLE FOR PROCESSING—ABORTED

DMIN-503 RECORD LENGTH IS GREATER THAN MAXIMUM FOR THE FILE

DMIN-504 ATTEMPT TO ENLARGE RECORD n TO nn BYTES IS NOT ALLOWED

DMIN-606 NOT ENOUGH STORAGE TO CREATE REPORT reportname

DMIN-606 NOT ENOUGH AVAILABLE STORAGE

DMIN-607 LARGER SORTWK EXTENTS NEEDED

DMIN-611 SORTWK1 MUST BE ASSIGNED TO AN ECKD DEVICE

DMIN-801 INSUFFICIENT WORKING STORAGE

DMIN-802 INVALID REQUEST CODE(xxx) RECEIVED



Message Table For general messages, this table lists the message codes, messages, and their meanings:

Error Code Error Message Meaning(if not obvious)

DMIN102E Not enough working storage available in module nnnnnnnn, program mmmmmmmm +offset

DATAMINER attempted to allocate more storage but was unable to. The GETMAIN failed in DATAMINER module nnnnnnnn. The exact program name and offset are provided. The solution may be as simple as running the DATAMINER job in a larger region. It is also possible that the script is in error and is causing the storage shortage.

DMIN103E ddname filename unknown record format - job terminated

An unknown record format for filename has been specified or inquired from the system. Refer to the INPUT and OUTPUT commands for more information.

DMIN105E More info needed about recfm & size for filename

DATAMINER does not have enough information for filename. Review the INPUT or OUTPUT command for filename and possibly the corresponding JCL and catalog information for filename.

DMIN106E filename not defined as reusable

The INPUT or OUTPUT command for filename has specified the REUSE parameter but the VSAM dataset is not defined as reusable.

DMIN107I No blocksize defined for name - set to default_blksize

The block size for the variable length record dataset filename is unknown to DATAMINER. A maximum block size is assumed.

DMIN108I No lrecl defined for filename - set to defaut_lrecl

The record length for filename is unknown to DATAMINER. The record length is determined from the block size.



DMIN109E No blocksize or lrecl for filename - cannot continue

DATAMINER cannot ascertain the block size or record length for the fixed-length dataset filename.

DMIN110E blocksize is not a multiple of lrecl for filename - can not continue

The block size and/or record length for filename are incorrect. filename is a fixed-length record dataset, and therefore the record length must be a multiple of the block size.

DMIN111E filename must be assigned to a printer

The OUTPUT command for filename has specified it as a printer, but DATAMINER has determined that it is not a printer device.

DMIN201E File filename not found in JCL statements - terminating

The DDNAME filename specified on the INPUT or OUTPUT command is not found. Include the DDNAME in your JCL and rerun the job.

DMIN202E ddname filename failed open, RC=rc,RSN=rsn - aborting

DATAMINER encountered an error when attempting to open the dataset filename. The failure return code is rc and the reason code is in rsn.

DMIN203E reason on filename, key=value

DATAMINER encountered an I/O failure while processing a request for dataset filename. The failure reason code is displayed in reason, and the requested key is displayed for any VSAM KSDS dataset.

DMIN209E Invalid I/O request (action-code)

DATAMINER encountered an invalid I/O function request. The request is displayed in action-code.

DMIN211E File filename not found in catalog - terminating

The dataset filename was not found the the specified VSAM catalog.




DMIN301E "command" needs INPUT and OUTPUT files

Some DATAMINER commands require both an INPUT and OUTPUT command in the script. COPY and EXTRACT are two shortcut commands that do.

DMIN303E "PRINT" was requested but no fields were selected

The DATAMINER PRINT command was encountered, but no fields where selected. Use the SELECT command to choose the fieldnames you want to print.

DMIN306E "DELETE" requires at least one record selector command

DATAMINER forces any script using the DELETE shortcut command to specify at least one record selector command. This ensures the script does not inadvertently delete more than expected.

DMIN307E One or more fields too long to fit on print line have been truncated

The length of all fieldnames selected for a print report exceeds the length of the print line. One or more fields have been truncated or excluded.

DMIN308E PROC or LABEL not defined at line nnn

The PROC or LABEL referenced by the command at line nnn is not found in the script.

DMIN309E Report name not defined at line nnn

The report referenced at line nnn is not found in the script. If the PRINT command specifies a parameter, it must be a report name. This report name must correspond to a REPORT command somewhere in the script.

DMIN310E Unable to load "SORT" program, rc return-code, reason error description

The DATAMINER REPORT and SORT commands require the system sort program, but the load has failed.




DMIN311E Unmatched IF / ENDIF or PROC / ENDPROC. Job terminated

Every IF command requires a corresponding ENDIF command. Every PROC command requires an ENDPROC command. DATAMINER has detected a violation of this rule.

DMIN312W ORDER fields for reports are too long. Truncated to 256 bytes

The DATAMINER Report Writer allows any report to be sorted by up to 32 different fields. However, the total length of all these fields combined has exceeded the maximum length of 256 bytes. The sort key has been truncated to 256 bytes.

DMIN313W Label fields are wider than WIDTH value

The label fields are wider than the REPORT subcommand WIDTH has specified. The width is overridden.

DMIN314E COPY command is not allowed with DB2

The COPY shortcut command is not allowed in conjunction with DB2. Refer to the EXTRACT command for use with DB2 tables.

DMIN315E Report name contains no LINE field definitions

DATAMINER has detected that report name has no associated LINE subcommand(s). At least one LINE subcommand is required.

DMIN316E Report name references field fieldname but has not included it in a LINE (or comparable) sub command

In report name, the field fieldname has been used in one or more REPORT subcommands but it has not been included in the report. It must be specified in either a LINE or TITLE subcommand.

DMIN317W Report name contains a HEADING and no LINE for field fieldname

In report name, a HEADING subcommand has referenced a the field fieldname, but the field has not been included in a LINE subcommand. The script is allowed to execute.




DMIN433E Table name has no fields

The DATAMINER process manager has detected the table name has no fields defined in it. Refer to the TABLE command in the script and the TABLE chapter in this document. If the TABLE definition does indeed have fields defined, call technical support.

DMIN501E Script contains invalid command(s) at line nnn

The DATAMINER script command processor detected an invalid script command code. Call technical support.

DMIN503W Record length is greater than maximum for the file, record truncated

An output record to be written has a length greater then the maximum allowed for this dataset. The record is truncated.

DMIN504W Attempt to enlarge record n to nn bytes is not allowed

The script attempted to create a record larger than the dataset allows. The record is not enlarged but the script is allowed to continue.

DMIN505I >>> Statement line-number command about to execute

This informational message is produced when the TRACE ON command is specified. The script line number and command name are displayed. This message is printed just before the command executes.

DMIN506I >>> Statement line-number trace-information about to execute

This informational message is produced when the TRACE FLOW command is specified. It displays a line when script flow control occurs; for example, calling into and returning from a procedure.

DMIN612E SORT return code rc on REPORT name. Possibly too many fields or fields too long.

Check the SORT return code and make appropriate changes. Possibly too many fields specified on the ORDER subcommand of the report name.




DMIN701E Error on SQL command sql-command

An occurred while DATAMINER was issuing the SQL command. DATAMINER uses dynamic SQL. Refer to the informational message that will follow.

DMIN702I 'sql-statement', Failing command

This message displays the SQL statement that was being processed at the time of the error.

DMIN703I SQLCODE = sqlcode, SQLSTATE = sqlstate

This message displays the SQLCODE and SQLSTATE returned by DB2. Refer to your DB2 reference guide.

DMIN703I Related to SQLCA-error-message

This message displays the SQLCA error message returned by DB2. Refer to your DB2 reference guide.

DMIN704E Error RC=rc loading program pgmname

The CAF service program failed to load. Refer to return code rc, to resolve the error.

DMIN705E CAF function error, RC=rc, reason=reason-code

The CAF function has failed. The return code and reason code are displayed. Refer to your DB2 reference guide.

DMIN706E Maximum of 10 cursors exceeded

DATAMINER allows a maximum of 10 cursors opened concurrently. Check you script for logic errors.

DMIN707I SQL-trace-information This message is produced only when DATAMINER has the DB2 interface trace activated. This is usually only at the request CSI technical support.




DMIN802E Invalid request code(request-code) received

The DATAMINER VSAM interface program detected an invalid request code. Check for errors in the script and/or call technical support.

DMIN901I Field fieldname defined as type field-type length bytes

DATAMINER automatically defines fieldnames for all INPUT commands that specify a type of DB2 or SQL. These messages display each column referenced in the SQL statement parameter of the INPUT command.




17
DATAMINER Script Examples
DATAMINER can accomplish tasks that range from simple to complex. The examples included in this chapter are typical jobs you can easily accomplish with DATAMINER.

This chapter contains the following examples:

Page

Common Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.3Ex. 1: COPY Subset of Records . . . . . . . . . . . . . . . . . . . . . . . . . . 17.3Ex. 2: COPY and PRINT Specific Records. . . . . . . . . . . . . . . . . . 17.3Ex. 3: DUMP Specific Records . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.3Ex. 4: COPY and PRINT Specific Records and Calculations. . . . 17.3Ex. 5: PRINT Specific Records, Calculations, and Totals . . . . . . 17.4Ex. 6: PRINT Specific Records and Totals . . . . . . . . . . . . . . . . . . 17.5Ex. 7: DELETE Specific Records . . . . . . . . . . . . . . . . . . . . . . . . . 17.6Ex. 8: EXTRACT and PRINT Specific Records. . . . . . . . . . . . . . 17.6Ex. 9: EXTRACT and PRINT Records, Calculations. . . . . . . . . . 17.7Ex. 10: DUMP Specific Records . . . . . . . . . . . . . . . . . . . . . . . . . . 17.7Ex. 11: COPY Specific Records, KSDS . . . . . . . . . . . . . . . . . . . . 17.7Ex. 12: COPY Specific Records, Fixed Block . . . . . . . . . . . . . . . 17.8Ex. 13: UPDATE Variable Blocked File In Place . . . . . . . . . . . . . 17.8Ex. 14: UPDATE Fixed-Length File . . . . . . . . . . . . . . . . . . . . . . . 17.8Ex. 15: INSERT Records into a KSDS . . . . . . . . . . . . . . . . . . . . . 17.9Ex. 16: UPDATE a KSDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.9Ex. 17: COPY and PRINT Specific Records. . . . . . . . . . . . . . . . . 17.9Ex. 18: DUMP the First 50 Records From a KSDS . . . . . . . . . . 17.10Ex. 19: COPY VSAM File to an FL Dataset, DUMP Recs . . . . 17.10Ex. 20: PRINT Column Report Showing Three Fields . . . . . . . . 17.10Ex. 21: COPY 1000 Records from One File to Another . . . . . . . 17.11Ex. 22: PRINT Report and DUMP Recs Using Criteria . . . . . . . 17.11Ex. 23: PRINT Records Within a Balance Range . . . . . . . . . . . . 17.12Ex. 24: DUMP Records and Delete Matching Records . . . . . . . 17.12Ex. 25: Calculate Ratio, PRINT Report, EXTRACT Records . . 17.12

DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Script Examples

Ex. 26: DUMP the First 20 Records Matching Criteria . . . . . . . 17.13Ex. 27: Create New KSDS Records from Card Input . . . . . . . . . 17.13Ex. 28: READ Two Files and SHOW ACCTNO from Both . . . 17.13Ex. 29: UPDATE a Sequential File In Place . . . . . . . . . . . . . . . . 17.14Ex. 30: PRINT a Column Report from a File . . . . . . . . . . . . . . . 17.14Ex. 31: COPY and DUMP the First 10 Records of a File . . . . . . 17.14Ex. 32: Create a File from Selected Fields of an Input File . . . . 17.15Ex. 33: COPY a Prod File to a Test File, Changing Names . . . . 17.15Ex. 34: PRINT Report Sorted by Fields, Create Subtotals . . . . . 17.16Ex. 35: PRINT Report Sorted by Fields, File/Table Input . . . . . 17.17Ex. 36: PRINT Name and Address Labels . . . . . . . . . . . . . . . . . 17.18Ex. 37: Using ORDER and BREAK Commands Together . . . . . 17.18Ex. 38: Using ORDER, BREAK, and SUMMARY Together. . . 17.20



Common Examples

Ex. 1: COPY Subset of Records

The following example copies 500 records from a KSDS to a sequential dataset containing fixed length 200 byte records in 20,000 byte blocks. Short records are padded with X'00', and records longer than 200 bytes are truncated to 200 bytes.

COPYINPUT=VSAM FILENAME=INFILEOUTPUT=DISK FILENAME=OUTFILE FIXED LRECL=200 BLKSIZE=20000last=500/*

Ex. 2: COPY and PRINT Specific Records

The following example copies a KSDS to an ESDS, selecting only the KEY and BAL fields from each record. It copies only records where BAL is greater than zero and prints a basic report of all the KEYs and BALs that are copied. The field named in the ONLY command does not necessarily have to be one of the fields that is copied, although, in this case, it is.

COPYPRINTINPUT=VSAMOUTPUT=VSAM FILENAME=VSMESDSKey 1,8,CBAL 83,5,P,3SELECT (KEY,BAL) FROM INFILE* WE WANT ONLY RECORDS WITH A BALANCE* GREATER THAN ZEROONLY BAL > 0/*

Ex. 3: DUMP Specific Records

The following example dumps the first 20 records from INFILE where the field AMT1 is greater than the field AMT2. This job may read more than 20 records if some records do not meet the selection criterion.

DUMPINPUT=VSAM FILENAME=INFILE MAX=20AMT1 99,3,P,3AMT2 107,6,P,5ONLY AMT1 >AMT2/*

Ex. 4: COPY and PRINT Specific Records and Calculations

The following example copies a KSDS to a variable blocked sequential dataset and prints a report from the output dataset. The script processes only the first 100 records. In addition to copying the KEY, AMT1, and AMT2 fields from the input dataset, the script does some calculations. It puts the sum of AMT1 and AMT2 into CALC1. Running totals kept in TOTAMT1, TOTAMT2, and TOTCALC1 are put into the record. At the end of



the report, the script prints three total lines showing TOTAMT1, TOTAMT2, and TOTCALC1.

COPYPRINTINPUT=VSAM FILENAME=INFILEOUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000Key 1,8,CAMT1 99,3,P,3AMT2 107,6,P,5CALC1 143,8,P,2DEFINE TOTAMT1,8,P,2DEFINE TOTAMT2,8,P,2DEFINE TOTCALC1,8,P,2 DEFINE WORK, 8,P,2SELECT (KEY,AMT1,AMT2,CALC1,TOTAMT1,TOTAMT2,TOTCALC1) MOVE AMT1 TO WORK ADD AMT2 TO WORK MOVE WORK TO CALC1ADD AMT1 TO TOTAMT1ADD AMT2 TO TOTAMT2ADD WORK TO TOTCALC1MAXRCDS=100TOT 'TOTAL OF AMOUNT 1 IS ',5 TOTAMT1,15,29,M5TOT 'TOTAL OF AMOUNT 2 IS ',5 TOTAMT2,15,29,M5TOT 'TOTAL OF CALCULATED IS',5 TOTCALC1,15,29,M5/*

Ex. 5: PRINT Specific Records, Calculations, and Totals

The following example prints a report from a VSAM dataset showing four fields from the record and a calculated running total. Only records where the FNM field contains “STEVE” and where the balance is less than 1000 are required. A maximum of 200 records are to be printed. Totals are printed at the end showing the total balance owed by people called Steve and how many records were processed (including those not for people called Steve).

PRINTINPUT=VSAM FILENAME=INFILEKey 1,8,CFNM 27,16,CLNM 47,32,CBAL 83,5,P,3DEFINE TotalBalance,8,P,2SELECT (KEY,Lnm,Fnm,bal,totalbalance) IF FNM = 'STEVE' AND BAL<1000

ADD BAL TO Total_BalanceKEEP

ELSE DROP

ENDIF



MAXRCDS=200TOT 'Total Balance is',5 TOTAL_BALANCE,17,35,M5TOT 'Number of records processed=',5 INPUT_RECORD,17,35,M3/*

Ex. 6: PRINT Specific Records and Totals

The following example prints a report showing all negative and positive balances that are more than $1,000.00. It keeps a total of the negative balances, a total of the positive balances, and a total of all balances that are over $1,000.00.

PRINTINPUT=VSAM FILENAME=INFILEOUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000Key 1,8,CRECORD 15,8,cRNO 20,3,CFNM 27,16,CLNM 47,32,CBAL 83,5,P,3FLAG 93,1,XAMT1 99,3,P,3AMT2 107,6,P,5BIN3 118,3,B,1BIN4 126,4,B,2XXX 134,3,CCALC1 143,8,P,2CALC2 157,4,B,1CHAR 166,32,CDEFINE Total_balance,8,P,2DEFINE PLUS_balance,8,P,2DEFINE MINUS_balance,8,P,2* Filter out small balancesSKIP BAL >= 0 AND BAL <1000SKIP BAL <0 AND BAL >-1000* Total the positive balancesIF BAL > 0 ADD BAL TO PLUS_BALANCEELSE* Total the negative balances ADD BAL TO MINUS_BALANCEENDIF* Total all the balancesADD BAL TO TOTAL_BALANCESELECT (KEY,fnm,lnm,bal,PLUS_BALANCE,MINUS_BALANCE) MAXRCDS=1000* The M5 mask prints the totals as * currency amountsTOT 'Total Balance is',5 TOTAL_BALANCE,17,35,M5TOT 'PLUS_BALANCE is',5 PLUS_BALANCE,17,35,M5 'MINUS_BALANCE is',55 MINUS_BALANCE,17,75,M5/*



Ex. 7: DELETE Specific Records

The following example deletes every record from a KSDS except where (1) the first name is less than “WILBERT” and the last name is greater than “MYCROFT,” or (2) the first name is “CHERYL.”

DELETEINPUT=VSAM FILENAME=INFILEFNM 27,16,CLNM 47,32,CSKIP FNM < 'WILBERT' AND LNM > 'MYCROFT'

OR FNM = 'CHERYL'/*

Ex. 8: EXTRACT and PRINT Specific Records

The following example extracts records from a KSDS to a sequential variable blocked dataset. The only information to copy is the KEY, the first and last names, the payment now due (10% of the balance) and the payment in a displayable format. The script will process only the first 200 people whose last name is Huggins and whose balance is greater than zero.

EXTRACTPRINTINPUT=VSAM FILENAME=INFILEOUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000Key 1,8,CFNM 27,16,CLNM 47,32,CBAL 83,5,P,3DEFINE PAYMENT,8,P,2DEFINE DISPLAY_PAYMENT,16,C* Filter out records we don't want. * This command could* have been entered as * ONLY LNM = 'Huggins' AND BAL > 0SKIP LNM != 'Huggins' OR BAL <=0SET PAYMENT = BAL* Make payment equal to 10% of the balanceMULTIPLY PAYMENT BY 0.1MOVE PAYMENT TO DISPLAY_PAYMENT,M5SELECT (KEY,fnm,lnm,bal,PAYMENT,DISPLAY_PAYMENT)LAST=200/*



Ex. 9: EXTRACT and PRINT Records, Calculations

The following example extracts a sequential dataset from a VSAM dataset and produces a report of the extracted records. Each record is to contain AMT1, AMT2, and the calculated ratio of AMT2 divided by AMT1. The script EXTRACTs and PRINTs only records whose ratio is greater than ±100. The extract stops when a record with a key greater than 60000000 is read.

EXTRACTPRINTINPUT=VSAM FILENAME=INFILEOUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000Key 1,8,CAMT1 99,3,P,3AMT2 107,6,P,5DEFINE ratio,8,P,4MOVE AMT2 TO RATIODIVIDE RATIO BY AMT1 ONLY RATIO > 100 OR RATIO < -100SELECT (AMT1,AMT2,RATIO) FROM INFILESTOP KEY > '60000000'

Ex. 10: DUMP Specific Records

The following example DUMPs to the printer the first 20 records where AMT1 is greater than AMT2.

DUMPINPUT=VSAM FILENAME=INFILEAMT1 99,3,P,3AMT2 107,6,P,5MAXRCDS=20ONLY AMT1 > AMT2/*

Ex. 11: COPY Specific Records, KSDS

The following example copies some data from cards to a KSDS. The records are inserted into the KSDS if it already contains records. Any duplicates are rejected.

COPYDUMPINPUT=CARDSOUTPUT=VSAM FILENAME=outfile* No field definition is given because we are * copying all 80 bytes from each card to the* output datasetDATACARDS8KA9AA8K7**33DDD3**3*33END OF RECORD8KLSWAD6**34CCC3**3*348K7DEA6**35EEE3**3*358K7LFRA**33DDD3**3*33<etc>9WWWDRAF**99ZZZ9**9*99 Last record/* to mark the end of the data cards



Ex. 12: COPY Specific Records, Fixed Block

The following example copies the first 10,000 records from a variable blocked dataset to a fixed-block dataset.

COPYINPUT=DISK FILENAME=INFILE VARBLK LRECL=600 BLKSIZE=20000OUTPUT=DISK FILENAME=OUTFILE LRECL=400 BLKSIZE=4000LAST=100000/*

Ex. 13: UPDATE Variable Blocked File In Place

The following example UPDATEs a variable blocked dataset in place. The UPDATE is done to the INPUT dataset—no OUTPUT dataset is needed. If the first name is less than “CARSON,” the script sets the balance to zero. If the first name is greater than “MARCIE,” the script moves the literal “MISTAKE!” to the field BADBYTE.

The dataset is variable-length records. If either of the UPDATEs falls outside the length of the original record (for example, if the record for NEIL was only 500 bytes long), that UPDATE is not done.

UPDATE INFILEDUMPINPUT=DISK FILENAME=INFILE VARBLK LRECL=600 BLKSIZE=20000FNM 27,16,CBAL 83,5,P,3BADBYTE 580,10,CLAST=100IF FNM < 'CARSON' MOVE 0 TO BALENDIFIF FNM >'MARCIE' MOVE 'MISTAKE!' TO BADBYTEENDIF/*

Ex. 14: UPDATE Fixed-Length File

The following example UPDATEs a fixed-length record dataset the same way as in example 13; however, in this case, the dataset is fixed-length 400-byte records, so every attempt to put the literal “WHOOPS” into BADBYTE will fail because it is outside the record length.

UPDATE INFILEDUMPINPUT=DISK FILENAME=INFILE FIXED LRECL=400 BLKSIZE=4000FNM 27,16,CLNM 47,32,CBAL 83,5,P,3BADBYTE 398,8,CIF FNM < 'CARSON' MOVE 0 TO BALENDIF



IF FNM>'MARCIE' MOVE 'WHOOPS' TO BADBYTEENDIFLAST=100/*

Ex. 15: INSERT Records into a KSDS

The following example inserts some new records into a KSDS using the INSERT command. Fields that are not set specifically are filled with X'00'. The record length of each record is determined by the end position of the rightmost field added to the record. So the first record in this example is 93 bytes long and the others are 101 bytes long.

OUTPUT=VSAM FILENAME=OUTFILEKey 1,8,CRECORD 15,8,cBAL 83,5,P,3FLAG 93,1,XAMT1 99,3,P,3 INSERT INTO OUTFILE (KEY,RECORD,BAL,FLAG) VALUES ('A1101001','40404040',P'233',X'CE') INSERT INTO OUTFILE (KEY,RECORD,BAL,AMT1) VALUES ('A1201001','40404040',P'233',42.6) INSERT INTO OUTFILE (KEY,RECORD,AMT1,BAL) VALUES ('A1131001','40404040',-32.56,19.0)/*

Ex. 16: UPDATE a KSDS

The following example updates a KSDS. For every record where the KEY is in the range 20000000 to 29999999, the script sets AMT1 to the same value as in AMT2.

UPDATE INFILE DUMP INPUT=VSAM FILENAME=INFILE Key 1,8,C AMT1 99,3,P,3AMT2 107,6,P,5ONLY KEY > '20000000' and key < '30000000'SET AMT1 = AMT2/*

Ex. 17: COPY and PRINT Specific Records

The following example uses a dataset in which the BAL field in some records contains garbage. The script creates a sequential dataset containing only the garbage records and PRINTs a report identifying the garbage records. The report will show the hexadecimal value of the BAL field.

The command MOVE BAL TO TESTER forces DATAMINER to validate BAL before moving it to TESTER. Because TESTER is never used for anything else, it does not matter how it is defined as long as it is defined as packed. If BAL is invalid, DATAMINER adds 1 to the VALIDATION_ERRORS system variable.



PRINTCOPYINPUT=VSAM FILENAME=INFILEOUTPUT=DISK FILENAME=OUTFILE FIXED LRECL=200 BLKSIZE=2000Key 1,8,CFNM 27,16,CLNM 47,32,CBAL 83,5,P,3HEXBAL 83,5,XDEFINE TESTER 8,P,2* Clear the error counterMOVE 0 TO VALIDATION_ERRORSMOVE BAL TO TESTER SELECT (KEY,FNM,LNM,HEXBAL) FROM INFILE* We want only records with an error in ONLY VALIDATION_ERRORS >0/&* $$EOJ

Ex. 18: DUMP the First 50 Records From a KSDS

The following example DUMPs the first 50 records from a KSDS. The input filename defaults to INFILE. The maximum number of records to DUMP is specified on the INPUT command. It could also have been set using the MAXRCDS or LAST commands.

DUMPINPUT=VSAM MAX=50

Ex. 19: COPY VSAM File to an FL Dataset, DUMP Recs

The following example copies a VSAM dataset to a fixed-length (FL) sequential dataset and DUMPs records. The DUMP command DUMPs the output records so that if any changes were made to the records, the DUMP shows the changed record.

INPUT=VSAM FILENAME=INFILEOUTPUT=DISK FILENAME=OUTFILE FIXED LRECL=100 BLKSIZE=9600COPYDUMP

Ex. 20: PRINT Column Report Showing Three Fields

The following example prints a column report showing three fields from a dataset, including only records whose QTY1 is greater than QTY2:

PRINTINPUT=VSAM FILENAME=INFILEACCTNO 1, 8, cQTY1 99, 3, P,3QTY2 107, 6, P,2ONLY QTY1> QTY2SELECT (ACCTNO,QTY1,QTY2) * The SELECT could have been written * SELECT (*)



Ex. 21: COPY 1000 Records from One File to Another

The following example copies the first 1,000 records from one dataset to another and produces a column report with calculated totals. You do not need to do anything to adjust for the different number of decimal places in the various fields.

INPUT=VSAM FILENAME=INFILEOUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000COPYPRINTACCTNO 1,8,CAMT1 99,3,P,3AMT2 107,6,P,5CALC1 143,8,P,2DEFINE WORK, 8,P,5DEFINE TOTAMT1,8,P,2DEFINE TOTAMT2,8,P,2DEFINE TOTCALC1,8,P,2 MOVE AMT1 TO WORK ADD AMT2 TO WORK MOVE WORK TO CALC1ADD AMT1 TO TOTAMT1ADD AMT2 TO TOTAMT2ADD WORK TO TOTCALC1SELECT (ACCTNO,AMT1) TOT 'TOTAL OF AMOUNT 1 IS ',5 TOTAMT1,15,29,M5 TOT 'TOTAL OF AMOUNT 2 IS ',5 TOTAMT2,15,29,M5 TOT 'TOTAL OF CALCULATED IS',5 TOTCALC1,15,29,M5LAST=1000

Ex. 22: PRINT Report and DUMP Recs Using Criteria

The following example PRINTs a report and DUMPs all records where the FNM (first name) is “STAN” or the BALANCE is more than 1000. Use PRINT and DUMP together in resolving problems in datasets or application programs.

INPUT=VSAM FILENAME=INFILEPRINTDUMPACCTNO 1, 8, CFNM 27,16,CLNM 47,32,CBAL 83,5,P,3DEFINE TOTAL-BALANCE,8,P,2IF FNM ="STAN" OR BAL>1000

ADD BAL TO TOTAL-BALANCEKEEP

ELSE DROPENDIFTOT 'TOTAL BALANCE IS',5 TOTAL-BALANCE,17,35,M5TOT 'NUMBER OF RECORDS PROCESSED=',5 INPUT_RECORD,17,35,M3SELECT (ACCTNO,FNM,LNM,BAL,TOTAL-BALANCE)



Ex. 23: PRINT Records Within a Balance Range

The following example PRINTs a report of records where BALANCE is within a required range, and PRINTs total negative and positive balances.

INPUT=VSAM FILENAME=INFILEPRINTACCTNO 1 8 CBAL 83,5,P,3DEFINE TOTAL-BALANCE,8,P,2DEFINE PLUS_BALANCE,8,P,2DEFINE MINUS_BALANCE,8,P,2 SKIP BAL >= 0 AND BAL <20 SKIP BAL <0 AND BAL <-1000IF BAL > 0 ADD BAL TO PLUS_BALANCEELSE ADD BAL TO MINUS_BALANCEENDIFADD BAL TO TOTAL-BALANCESELECT (ACCTNO,BAL,PLUS_BALANCE,MINUS_BALANCE) MAXRCDS=1000TOT 'TOTAL BALANCE IS',5 TOTAL-BALANCE,17,35,M5TOT 'PLUS_BALANCE IS',5 PLUS_BALANCE,17,35,M5 'MINUS_BALANCE IS',55 MINUS_BALANCE,17,75,M5

Ex. 24: DUMP Records and Delete Matching Records

The following example dumps all the records from a dataset and DELETEs records where LNM (the customer's last name) is JENKINS.

INPUT=VSAM FILENAME=INFILELNM 47,32,CSHOW INFILEDELETE ONLY LNM = 'JENKINS'

Ex. 25: Calculate Ratio, PRINT Report, EXTRACT Records

The following example calculates a ratio and PRINTs a column report of records where the user variable RATIO is more than 100 or less than -100. It then EXTRACTs some fields from those records into another dataset.

INPUT=VSAM FILENAME=INFILEOUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000PRINTEXTRACTACCTNO 1,8,CAMT1 99,3,P,3AMT2 107,6,P,5DEFINE RATIO,8,P,4DEFINE TESTER,8,P,4MOVE AMT2 TO RATIODIVIDE RATIO BY AMT1* Say which records we want to extract ONLY RATIO > 100 OR RATIO < -100SELECT (ACCTNO,AMT1,AMT2,RATIO)



Ex. 26: DUMP the First 20 Records Matching Criteria

The following example DUMPs the first 20 records from a dataset where AMT1 is less than zero or AMT1 is less than AMT2.

MAXRCDS sets the maximum number of records to write to the output dataset. More than this number of records may be read from the input dataset.

INPUT=VSAM FILENAME=INFILEAMT1 99,3,P,3AMT2 107,6,P,5DUMPMAXRCDS=20ONLY AMT1 < 0 OR AMT1 <AMT2

Ex. 27: Create New KSDS Records from Card Input

The following example creates new KSDS records from card input, one record per card.

No field definitions are needed because the entire contents of each card is copied without change to the output dataset.

COPY DUMP INPUT=CARDS OUTPUT=VSAM FILENAME=OUTFILEDATACARDS00000001 JOE BLOGGS CHICAGO02345677 SID JAMES ASHEVILLE00033333 MARY STEWART EDINBURGH

Ex. 28: READ Two Files and SHOW ACCTNO from Both

The following example reads two datasets and SHOWs the field ACCTNO from both. DATAMINER reads the first dataset automatically because of the AUTO INPUT MASTER command. Because both datasets have a field called ACCTNO, you need to tell DATAMINER which dataset you are referring to when you refer to ACCTNO.

INPUT=DISK FILENAME=MASTER VARBLK LRECL=4000 BLKSIZE=20000 ACCTNO 1,8,CINPUT=DISK FILENAME=WRKFILE LRECL=100 BLKSIZE=2000 FIXED ACCTNO 1,8,CAUTO INPUT MASTERREAD WRKFILESHOW MASTER:ACCTNOSHOW WRKFILE:ACCTNO



Ex. 29: UPDATE a Sequential File In Place

The following example UPDATEs a sequential dataset in place and flags every record that has a negative balance as being in error. Then it DUMPs the updated records on the printer.

INPUT=DISK FILENAME=INFILE VARBLK LRECL=600 BLKSIZE=20000UPDATE INFILEBAL 83,5,P,3ERRMSG 580,10,CIF BAL<0

MOVE 'NEGATIVE' TO ERRMSGDUMP INFILE

ENDIF

Ex. 30: PRINT a Column Report from a File

The following example prints a column report from a dataset starting at key A0000200, selecting only records where AMT1 is greater than AMT2, and limiting the report to the first 600 records where AMT1 greater than AMT2.

PRINTINPUT=VSAM FILENAME=INFILEACCTNO 1,8,CLNM 47,32,CBAL 83,5,P,3,M5AMT1 99,3,P,3AMT2 107,6,P,5 START ACCTNO > 'A0000200' ONLY AMT1 > AMT2 SELECT (ACCTNO,LNM,BAL,AMT1) LAST=600

Ex. 31: COPY and DUMP the First 10 Records of a File

The following example copies and DUMPs the first 10 records of a dataset.

COPYDUMPOUTPUT=DISK FILENAME=OUTFILE LRECL=290 BLKSIZE=29000 FIXED INPUT=DISK FILENAME=INFILE UNDEF LRECL=4000 BLKSIZE=20000LAST=10



Ex. 32: Create a File from Selected Fields of an Input File

The following example creates a dataset from selected fields in an input dataset. The new dataset has TEST DATA ONLY on the end of the record. DATAMINER DUMPs the new records to the printer.

DUMP EXTRACT INPUT=VSAM OUTPUT=VSAMACCTNO 1,8,CFNM 27,16,CLNM 47,32,CSELECT (ACCTNO,FNM,LNM,'TEST DATA ONLY')

Ex. 33: COPY a Prod File to a Test File, Changing Names

The following example copies a production dataset to a test dataset, changing the names of all the customers for the sake of privacy.

COPYINPUT=VSAM FILENAME=PRODFLOUTPUT=VSAM FILENAME=TESTFLFNM 27,16,CFINIT ",1,CLNM 47,32,CLINIT ",1,CDEFINE NEWFST 16,CDEFINE NEWLST 32,CNEWFST = 'SUSAN'IF FINIT < 'T'

NEWFST = 'SAM'ENDIFIF FINIT < 'M'

NEWFST = 'MARY'ENDIFIF FINIT < 'G'

NEWFST = 'GEORGE'ENDIFMOVE 'BERRY' TO NEWLSTIF LINIT < 'S'

NEWLST = 'CLAPTON'ENDIFIF LINIT < 'N'

NEWLST = 'BREAM'ENDIFIF LINIT < 'F'

NEWLST = 'TROTTER'ENDIFFNM = NEWFSTLNM = NEWLST



Ex. 34: PRINT Report Sorted by Fields, Create Subtotals

The following Report Writer example prints a report from a dataset, sorts (ORDERs) the report by department and last name, and creates subtotals by department.

OUTPUT=PRINTER FILENAME=DEPTPR SYSNO=SYS010INPUT=VSAM FILENAME=DEPTFLFIRST 4,12,C HEADING ('FIRST' 'NAME')LAST *,16,CDEPT 48,5,CSALARY 60,8,P,2AUTO INPUT DEPTFLPRINT STAFFREPORT STAFF PRINTER DEPTPR

ORDER DEPTBREAK DEPTTITLE 'DEPARTMENTAL STAFF REPORT'LINE 1 DEPT FIRST LAST SALARYSUM SALARY



Ex. 35: PRINT Report Sorted by Fields, File/Table Input

The following Report Writer example prints a report sorted (ORDERed) by city and account number with totals by city. Information for the report comes from a dataset and two tables.

OUTPUT=PRINTER FILENAME=CITYAC SYSNO=SYS010INPUT=VSAM FILENAME=ACCOUNTACCTNO 1, 8,C HEADING ('ACCOUNT' 'NUMBER')AC-CITY 41,20,C HEADING ('HOME' 'CITY')AC-PRODUCT 70,10,CAC-DEBT 83,05,P,3 HEADING ('UNIT' 'COST')INPUT=DISK FILENAME=TBFILE VARBLK LRECL=1800 BLKSIZE=32760* TABLE OF PRODUCTS TABLE PRODTAB PRODNO 1,10,C OFFICE 25,20,C DATADODGE RALEIGHFORD DAYTONFENDER CHATTANOOGAGIBSON KALAMAZOO ENDDATA TABLE STATTAB TBFILE ACCTNO 1,8,C MARKER 20,10,C AUTO INPUT ACCOUNT FIND PRODTAB WHERE PRODNO = PRODUCT IF PRODUCT:IO-RESULT = 'NFD' OFFICE = 'UNKNOWN' ENDIF FIND STATTAB WHERE STATTAB:ACCTNO = ACCOUNT:ACCTNO IF STATTAB:IO-RESULT = 'NFD' MARKER = ' ' ENDIFPRINT ACCOUNT-REPORTREPORT ACCOUNT-REPORT PRINTER=CITYAC

ORDER AC-CITY ACCTNOSUM AC-DEBTTITLE COL 10 'ACCOUNT STATUS BY CITY AND ACCOUNT NO'LINE AC-CITY ACCTNO OFFICE AC-DEBT MARKER



Ex. 36: PRINT Name and Address Labels

The following Report Writer example prints name and address labels.

OUTPUT=PRINTER FILENAME=ADDRLAB SYSNO=SYS050INPUT=VSAM FILENAME=CUSTFLEACCTNO 1,8,CFNM 27,16,CLNM 47,32,CADDR 117,32,CCITY *,32,CSTATE *,2,CZIP *,9,CAUTO INPUT CUSTFLEPRINT ADDRESS-LABELREPORT ADDRESS-LABEL PRINTER ADDRLAB

ACROSS 3 WIDTH 40 HEIGHT 5 LABELSLINE 1 FNM LNMLINE 2 ADDRLINE 3 CITYLINE 4 STATE ZIP

Ex. 37: Using ORDER and BREAK Commands Together

The following Report Writer example uses both the ORDER and the BREAK commands together:

* * CONNECT TO DB2 AND READ EMPLOYEE TABLE * CONNECT SSID(DB9G) PLAN(DATAM71C) * INPUT=SQL STATEMENT=EMPSEL(SELECT * FROM ZOS111.DSN8910.EMPQA) * OUTPUT=PRINTER FILENAME=DB2OUT * * READ THE INPUT FILE * AUTO INPUT EMPSEL * * PRINT THE REPORT * PRINT SALRPT REPORT SALRPT PRINTER DB2OUT

ORDER WORKDEPT, -SALARYBREAK WORKDEPT TITLE 1 ('EMPL STAFF REPORT WITH BREAK BY DEPT

SALARY(DESC)')TITLE 2 ('STARTING DEPARTMENT NUMBER FOR PAGE: ',

WORKDEPT) LINE (WORKDEPT, EMPNO, FIRSTNME, LASTNAME, SALARY)

/*

This script can produce the following output.



(The following output is the first page.)

01/21/2012 EMPL STAFF REPORT WITH BREAK BY DEPT PAGE 1 STARTING DEPARTMENT NUMBER FOR PAGE: A00

WORK EMPNO FIRSTNME LASTNAME SALARY A00 200120 GREG ORLANDO 798.33 200010 DIANE HEMMINGER 208.75 000120 SEAN O CONNELL 180.99 000110 VINCENZO LUCCHESI 170.55 000010 CHRISTINE HAAS 150.55 === ====== ============ =============== =========== A00

B01 000020 MICHAEL THOMPSON 200.00 === ====== ============ =============== =========== B01

C01 000030 SALLY KWAN 200.00 000130 DOLORES QUINTANA 200.00 000140 HEATHER NICHOLLS 200.00 200140 KIM NATZ 200.00 === ====== ============ =============== =========== C01 D11 000060 IRVING STERN 905.56 000150 BRUCE ADAMSON 905.56 000160 ELIZABETH PIANKA 905.56 000170 MASATOSHI YOSHIMURA 905.56

200170 KIYOSHI YAMAMOTO 905.56 200220 REBA JOHN 905.56 === ====== ============ =============== =========== D11 D21 000070 EVA PULASKI 200.00 000230 JAMES JEFFERSON 200.00

000270 MARIA PEREZ 200.00 200240 ROBERT MONTEVERDE 200.00 === ====== ============ =============== =========== D21 E01 000050 JOHN GEYER 200.00 === ====== ============ =============== =========== E01 E11 000090 EILEEN HENDERSON 200.00 000280 ETHEL SCHNEIDER 200.00 000290 JOHN PARKER 200.00

200280 EILEEN SCHWARTZ 200.00 200310 MICHELLE SPRINGER 200.00 === ====== ============ =============== =========== E11

E21 000100 THEODORE SPENSER 200.00 000320 RAMLAL MEHTA 200.00 000330 WING LEE 200.00 000340 JASON GOUNOT 200.00



(The following output is the second page.)

Ex. 38: Using ORDER, BREAK, and SUMMARY Together

The following Report Writer example uses the ORDER, BREAK, and SUMMARY commands together:

This script can produce the following output (first page):

01/21/2012 EMPL STAFF REPORT WITH BREAK BY DEPT PAGE 2 STARTING DEPARTMENT NUMBER FOR PAGE: E21

WORK EMPNO FIRSTNME LASTNAME SALARY E21 200330 HELENA WONG 200.00 200340 ROY ALONZO 200.00 === ====== ============ =============== =========== E21

* * CONNECT TO DB2 AND READ EMPLOYEE TABLE * CONNECT SSID(DB9G) PLAN(DATAM71C) * INPUT=SQL STATEMENT=EMPSEL(SELECT * FROM ZOS111.DSN8910.EMPQA)* OUTPUT=PRINTER FILENAME=DB2OUT * * READ THE INPUT FILE * AUTO INPUT EMPSEL * * PRINT THE REPORT * PRINT SALRPT REPORT SALRPT PRINTER DB2OUT ORDER WORKDEPT, -SALARYBREAK WORKDEPT TITLE 1 ('EMPL STAFF REPORT WITH SUMMARY BY DEPT SALARY(DESC)')TITLE 2 ('STARTING DEPARTMENT NUMBER FOR PAGE: ', WORKDEPT) LINE (WORKDEPT, EMPNO, FIRSTNME, LASTNAME, SALARY) SUM SALARY /*



01/21/2012 EMPL STAFF REPORT WITH SUMMARY BY DEPT PAGE 1 STARTING DEPARTMENT NUMBER FOR PAGE: A00

WORK EMPNO FIRSTNME LASTNAME SALARY A00 200120 GREG ORLANDO 798.33 200010 DIANE HEMMINGER 208.75 000120 SEAN O CONNELL 180.99 000110 VINCENZO LUCCHESI 170.55 000010 CHRISTINE HAAS 150.55 === ====== ============ =============== =========== A00 1509.17

B01 000020 MICHAEL THOMPSON 200.00 === ====== ============ =============== =========== B01 200.00

C01 000030 SALLY KWAN 200.00 000130 DOLORES QUINTANA 200.00 000140 HEATHER NICHOLLS 200.00 200140 KIM NATZ 200.00 === ====== ============ =============== =========== C01 800.00 D11 000060 IRVING STERN 905.56 000150 BRUCE ADAMSON 905.56

000200 DAVID BROWN 905.56 000210 WILLIAM JONES 905.56 000220 JENNIFER LUTZ 905.56 200170 KIYOSHI YAMAMOTO 905.56 200220 REBA JOHN 905.56 === ====== ============ =============== =========== D11 9961.16 D21 000070 EVA PULASKI 200.00 000230 JAMES JEFFERSON 200.00 000240 SALVATORE MARINO 200.00

000270 MARIA PEREZ 200.00 200240 ROBERT MONTEVERDE 200.00 === ====== ============ =============== ===========D21 1400.00 E01 000050 JOHN GEYER 200.00 === ====== ============ =============== ===========E01 200.00 E11 000090 EILEEN HENDERSON 200.00 000280 ETHEL SCHNEIDER 200.00

200280 EILEEN SCHWARTZ 200.00 200310 MICHELLE SPRINGER 200.00 === ====== ============ =============== =========== E11 1400.00 E21 000100 THEODORE SPENSER 200.00 000320 RAMLAL MEHTA 200.00 000330 WING LEE 200.00 000340 JASON GOUNOT 200.00



(The following output is the second page.)

01/21/2012 EMPL STAFF REPORT WITH SUMMARY BY DEPT PAGE 2 STARTING DEPARTMENT NUMBER FOR PAGE: E21 WORK EMPNO FIRSTNME LASTNAME SALARY E21 200330 HELENA WONG 200.00 200340 ROY ALONZO 200.00 === ====== ============ =============== =========== E21 1200.00 === ====== ============ =============== ===========

01/21/2012 EMPL STAFF REPORT WITH SUMMARY BY DEPT PAGE 1 STARTING DEPARTMENT NUMBER FOR PAGE:

WORK EMPNO FIRSTNME LASTNAME SALARY 16670.33



18
DATAMINER ONLINE
DATAMINER ONLINE can be used to generate VSAM test data, display the contents of specific records, perform full-screen editing functions, and repair damaged datasets. You can use DATAMINER ONLINE to perform these tasks without writing a program and without bringing CICS down.


Page

Overview of DATAMINER ONLINE. . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.2How DATAMINER ONLINE Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.4DATAMINER ONLINE Sample Screen . . . . . . . . . . . . . . . . . . . . . . . . . . 18.5DATAMINER ONLINE Error Messages . . . . . . . . . . . . . . . . . . . . . . . . 18.11

DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online

Overview of DATAMINER ONLINE

Introduction DATAMINER ONLINE gives you simple access to VSAM datasets and temporary storage queues under the control of CICS. You can use it to inquire on production data or (if you are a programmer) as a development and testing aid.

Description DATAMINER ONLINE gives you a full-screen display of the data in a record. By default, it displays the data in character format; that is, packed decimal and binary fields are not readable. Additionally, you can display the information in hexadecimal format, as well as character. You can display, add, change, or delete records from a dataset.

DATAMINER ONLINE keeps the changes you want to make in a scratchpad until you are certain that these are the changes you want to make. This lets you look at several similar records before deciding which of them you really want to change. You can make changes to the scratchpad records, but the changes are not applied until you issue the RPL (replace) command.

Supported Environments

DATAMINER ONLINE supports the following environments:

• DATAMINER ONLINE runs under all releases of z/OS.

• DATAMINER ONLINE supports CICS releases 2.1 and above.

DATAMINER ONLINE does not use CICS Basic Mapping Support (BMS).

System Requirements

The datasets you access must be defined in the CICS File Control Table.

CICS Temporary Storage Queues

Besides working with VSAM datasets, DATAMINER ONLINE also lets you look at and modify CICS Temporary Storage Queues. These queues can belong to you or to another user. It makes no difference to DATAMINER ONLINE whether the queue is on disk (“Auxiliary Temporary Storage”) or in main storage. DATAMINER ONLINE also uses its own scratchpad temporary storage queue to keep a copy of any VSAM records that you read. When you scroll backwards and forwards through a VSAM dataset, you are actually scrolling through the scratchpad so that your browsing does not affect anyone else using the dataset.

Security The Security Module provides VSAM dataset security for CICS access. The Security Module is accessed when the Security Option is enabled. The Security Module contains entries identifying the VSAM datasets to be secured, the user IDs of the individuals authorized to access the datasets, and the level of access permitted. The CICS Security Module is designed for companies that do not have any other system to secure their VSAM datasets. If you have a CICS dataset security product, there is no need to install the DATAMINER ONLINE Security System.




DATAMINER ONLINE lets you

• Easily retrieve, add, modify, or delete VSAM records.

• Access VSAM records online under CICS.

• Handle fixed and variable length records.

• Access records by either full or generic key.

• Read and browse records in both forward and backward directions.

• Load records into empty datasets.

DATAMINER ONLINE

• Supports full access to all CICS Temporary Storage queues. You can work with existing TS queues or use DATAMINER ONLINE to create new TS queues.

• Handles all conventional VSAM functions.

• Automatically determines VSAM dataset and record characteristics.



How DATAMINER ONLINE Works

Introduction DATAMINER ONLINE interactively accesses VSAM datasets and temporary storage queues without needing any programming. It can retrieve up to 500 records at a time. DATAMINER ONLINE holds both VSAM and temporary storage records in a scratchpad for the duration of the transaction so that you can browse them quickly. In the case of VSAM records, it also means that you can make changes to several records before committing your changes permanently.

Access Records To access VSAM records under CICS, use the following procedure:

1. Sign on to the CICS system.

2. Invoke transaction MINE (or whatever name your CICS administrator has chosen).

3. Enter the name of the dataset or the temporary storage queue to be accessed.

4. Enter an OPERATOR in the OPER field to tell DATAMINER ONLINE what you want to do to the record.

5. Enter the key(s) of the record(s), or the item number in the temporary storage queue, that you want to work with.

Browsing Files Browsing involves starting at some record in a dataset and then reading forward one record at a time from that point. The usual way to start browsing is entering an operator and a key that tell DATAMINER ONLINE where to start. For example, GET 1234 tells DATAMINER ONLINE to start with the first record with a key of 1234 or greater. You then browse forward (for example, to record 1235) using the PF2 key. You can keep browsing forward until you have read 500 records or until you run out of records in the dataset, at which point DATAMINER ONLINE tells you there are no more records.

You can also browse backwards but, for a VSAM dataset, you cannot browse back past the first record you started at (record 1234 in our example). If you try, DATAMINER ONLINE tells you there are no more records, meaning there are no more in the scratchpad that DATAMINER ONLINE uses for browsing.

Browsing Temporary Storage Queues

You browse temporary storage queues somewhat differently. TS queue records do not have keys and they are often added in seemingly random order. DATAMINER ONLINE does not care if you page forwards or backwards. After you have browsed the entire temporary storage queue, the browse wraps around back to the beginning of the dataset. DATAMINER ONLINE indicates this by putting an item number of 0000 in the key field on the screen. You can continue browsing forward and backward and the item number will show the correct value.



DATAMINER ONLINE Sample Screen

Introduction This section describes the layout, fields, and commands used on the DATAMINER ONLINE screen.

Example This is an example of the DATAMINER ONLINE screen:

The DATAMINER ONLINE display screen fields are described as they appear on the screen, left to right, top to bottom.

Transaction The transaction field shows the name of the transaction that starts DATAMINER ONLINE. In the example, the filename is “MINE.” The CICS administrator can change the transaction name. Check with the CICS administrator for the correct transaction.

Software version This field shows the version of the DATAMINER ONLINE software you are using.

RECORD NUMBER (RCD xxx OF yyy)

This field shows the number of the record in DATAMINER ONLINE’s scratchpad. For example, RCD 007 OF 025 means you are looking at the

7th record of the 25 records you have looked at so far in this session.

The RECORD NUMBER field is also used to display error messages.

FILEID Field This field contains the File Identification of a VSAM dataset or the Queue-ID of a Temporary Storage Queue. The FILEID must be in the CICS File Control Table and the dataset must currently be open. FILEID or Queue-ID must be one to eight characters in length. If you need a Queue-ID with hexadecimal characters, leave the FILEID field blank and enter the Queue-ID in the KEY field in hexadecimal format (for example, X'0127'). For commands that usually need an item number in the KEY

MINE CSI-DATAMINER 7.1 VSAM UTILITY RCD. 007 OF 025FILEID= BKSDSIN LRECL= 00100 OPER= TEMP. STRG. RCD. UPDATEDKEY= A072

THRU KEY

REMOTE KEYPOS=1...+....10...+....20...+....30...+....40...+....50...+....60...+....70...+....+A072......IBM/MSC010GATEWAY210WSRCNT= ..JOURNALTST........................RECENDCFFF000000CCD6DECFFFCCECECEFFFEEDCDE7400DDEDDCDEEE000000000000000000000000DCCCDC107200000092414230107135618210629353E000164951332300000000000000000000000095355481..+....90...+....+ASASASASA....127....CECECECEC0000FFF00311212121210000127000C

PF1=PRVREC PF2=NXTREC PF3=BWD PF4=FWD PF5=BWD1/2 PF6=FWD1/2 PF7=HEX PF8=COLS



field, such as the TSG command, follow the Queue-ID with a space and then enter the Item-number. For example, to retrieve item number 23 from the queue called X'10FE', in the OPER field, you would enter TSG, and in the KEY field, you would enter X'10FE' 23 or X'10FE' 0023.

LRECL Field This field tells DATAMINER ONLINE how long you want the record to be. It must be filled with the record length before all output and update operations. There is no need for leading zeros. You do not need to give DATAMINER ONLINE an LRECL for any read operation; DATAMINER ONLINE fills the right record length in itself. It is not used for delete operations. The maximum size for temporary storage records is 32767 bytes, while for VSAM records, the maximum size is determined by the DEFINE that created the dataset originally. DATAMINER ONLINE does not let you create or modify a record so that it has a length greater than the defined maximum. If you give DATAMINER ONLINE a record length that is longer than the data you enter, the rest of the record is padded with X'00'. If you give DATAMINER ONLINE a record length that is less than the number of bytes you enter into the record, DATAMINER ONLINE discards the excess bytes.

OPER Field This is the command or OPERATOR that tells DATAMINER ONLINE what you want to do to the VSAM record(s) or Temporary Storage. Allowable OPERATORS are

ADD, DEL, FST, GET, GEQ, GGE, LST, NXT, PRV, RPL, TSA, TSD, TSG, TSN, TSP, TSR.

Use the TSx commands for working with temporary storage queues. Use the other commands for working with VSAM datasets. If you do not enter an operator, DATAMINER ONLINE fills this field in with the operator from your previous command. This makes it easy to scroll through a dataset by entering a command of NXT and repeatedly pressing ENTER.



The VSAM command operators you can choose from are described in the following table:

VSAM Operator

Description

ADD Adds a record to the dataset.

For KSDS, DATAMINER ONLINE adds the record using the key in the record.

For ESDS, DATAMINER ONLINE adds the record to the end of the file.

For RRDS, DATAMINER ONLINE adds the record if the Relative Record Number in the KEYfield points to an empty slot, or returns an error code of DPR.

If the record was added successfully, DATAMINER ONLINE adds the new record to both the VSAM dataset and the end of the current records in the Scratchpad Area. After you have added a record to the dataset, you can change it by overtyping its data and using the RPL command to replace it.

DEL Deletes a record from a KSDS or RRDS dataset.

If you specify a full key, one record with a key equal to KEY is deleted.

If you specify a KEY and a THRU KEY, all the records with keys in the range starting with KEY and ending with THRU KEY are deleted. THRU KEY can be full or generic. A generic key delete is valid for KSDS datasets only. You cannot generically delete records on logged datasets under CICS 1.6.

If the record delete is successful, DATAMINER ONLINE also deletes any corresponding records in the scratchpad.

FST Retrieves the first record for the dataset. LRECL and KEY are ignored.

GEQ Gets a record with a key equal to KEY.

Warning: You can update this record; however, another user can update it while you are working on it. The last updated version replaces everything in the record. If you want to be certain that no one changes the record while you are working on it, use GEU rather than GEQ.

GEU Gets a record for update with a key equal to KEY. GEU locks the entire VSAM control interval until the next OPERATOR is executed or until the transaction ends. Use this only if you want to be sure that another user cannot update this record while you are updating it.



GGE Retrieves a record starting with a key greater than or equal to KEY. DATAMINER ONLINE executes a GGE against an RRDS or ESDS dataset with a full key equal. DATAMINER ONLINE executes a GGE against a KSDS dataset with a full key or generic key greater or equal.

Warning: You can update this record; however, another user could update it while you are working on it. The last updated version replaces everything in the record. If you want to be certain that no one changes the record while you are working on it, use GGU rather than GGE.

GGU Gets a record for update with a key greater than or equal to KEY. GGU locks the entire VSAM control interval until the next OPERATOR is executed or until the transaction ends. Use this only if you want to be sure that another user cannot update this record while you are updating it.

LST Retrieves the last record in the dataset. LRECL and KEY are ignored.

NXT Retrieves the next sequential record. DATAMINER ONLINE executes a NXT against an RRDS or ESDS dataset with a full key equal. DATAMINER ONLINE executes a NXT against a KSDS dataset with a full key or generic key greater or equal.

PRV Retrieves the previous record from the dataset. DATAMINER ONLINE executes a PRV against an RRDS or ESDS dataset with a full key equal. DATAMINER ONLINE executes a PRV against a KSDS dataset with a full key or generic key greater or equal.

RPL Replaces a record in the dataset with the information contained in the Data Area. For KSDS datasets, DATAMINER ONLINE uses the key in the record area as the key for the record written to disk.

Note When you are modifying records, nothing is written to the dataset until you issue a RPL command.

VSAM Operator

Description



The Temporary Storage command operators you can choose from are described in the following table:

KEY This field is the key of the first or only record you want to select or the Temporary Storage Item-number of the first or only Temporary Storage Record. The KEY field is mandatory. For KSDS datasets, the KEY field can be either full or generic. For example, to see the record for “BLOGGS,” you can enter a key of either BLOGGS or BLO.

BLO displays all the records whose keys start with BLO.

THRU KEY This is the key of the last record or the Temporary Storage Item-number of the last Temporary Storage Record you want to select. The THRU KEY field is always optional. You do not use this field for output operations.

Keys must be one of the following types:

• KSDS Keys must be a 1- to 255-byte alphanumeric key.

• RRDS Keys must be a 1- to 15-byte numeric Relative Record Number (RRN).

TemporaryStorageOperator

Description

TSA Adds a record to the end of the records in a Temporary Storage Queue. The new record is added both to the Temporary Storage Queue and to the end of the current records in the Scratchpad Area

TSR Replaces a record in the Temporary Storage Queue. Use this command after you have made changes to the data display for the record. You can also increase or decrease the length of the temporary storage record by keying a new record length in the LRECL field along with TSR in the OPER field.

TSD Delete the entire Temporary Storage Queue.

Warning: When you execute this command, there is no “Are you sure?” message.

TSG Gets a record from the Temporary Storage Queue. Puts the record number in the KEY field.

TSN Gets a record, reading forward starting with the next sequential record, from the Temporary Storage Queue.

TSP Gets a record, reading backward, from the Temporary Storage Queue

END Ends the session. You can also press the CLEAR key.



• ESDS Keys must be a 1- to 15-byte numeric Relative Byte Address (RBA).

• CICS Temporary Storage Keys must be a 1- to 15-byte numeric Item-number.

You can enter keys in either of two forms:

1. Character form. This is the more common way of specifying keys. You can enter any character on the keyboard.

2. Hexadecimal form. Only 0–9 and A–F are allowed. This key must be preceded by an X and must be enclosed in quotation marks. The length of the key must be an even number, 2 through 252. For example, X'12A1E4'.

REMOTE KEYPOS This field is the position of the key in a VSAM record for MRO (Multi-Region Operation) datasets only.

DATA AREA The Data Area contains the data you want to add with an ADD function, replace with a RPL function, or retrieve with an input function. The delete function does not use the Data Area. You can retrieve data into, enter data into, or change data within the Data Area. Data can be in character and/or hexadecimal form. The maximum length is 1120 characters starting on line 10 of the screen. Whenever this area is changed, any corresponding record in the Scratchpad Area is also changed.

When the hexadecimal display is turned on and a byte is changed in both the character line and the hexadecimal lines, the change to the character line overrides the hexadecimal change for that byte.

PF KEYS The PF key value definitions are as follows:

• PF1—Get the previous record from the Scratchpad Area

• PF2—Get next record from the Scratchpad Area

• PF3—Full page backward within the current record

• PF4—Full page forward

• PF5—Half page backward within the current record

• PF6—Half page forward

• PF7—Switch between character and hexadecimal format display

• PF8—Toggle the position indicator line display

In the event that PF keys are not available, you can enter PFn into the OPER field. This has the same effect as pressing the corresponding PF key.

PF19 has the same effect as PF1; PF20 has the same effect as PF2; PF22 has the same effect as PF5; and PF23 has the same effect as PF6.



DATAMINER ONLINE Error Messages

Introduction When an error occurs, DATAMINER ONLINE displays error messages in REC xxx OF yyy field in the upper right of the screen.

In addition to the following messages, there are a number of “You should never see this message” messages built into DATAMINER ONLINE. They usually mean that that you are running DATAMINER ONLINE on a release of CICS or the operating system that DATAMINER ONLINE does not support. If you get any of these messages, especially if you get them repeatedly, please CSI Tech Support.

CONTROL INTERVAL HOLD

You have tried to retrieve a record, but another job or another CICS user is exclusively holding the control interval the record is in. If you retry the operation, it may or may not work, depending on how long the other job plans to hold the control interval. This message does not necessarily mean that somebody else is modifying the same record as you; it means that somebody is modifying a record that is close to, or the same as, the one you want.

CPU SERNO NOMATCH

DATAMINER ONLINE is not licensed to run on your CPU. Have your systems programmer contact CSI for a product key that will run on your CPU.

DATAMINER HAS EXPIRED

The DATAMINER product key has expired. Tell your systems programmer or administrator to contact CSI to receive a new product key.

DUPLICATE KEY You have tried to ADD a record to a dataset, but a record with the same key already exists, or you have tried to read a dataset through an alternate index where a duplicate key exists. If you are using a GET, switch to NXT to retrieve the rest of the records with the same key. For NXT, DATAMINER returns the DPK return code until the last record with the same key is retrieved.

DUPLICATE RECRD DATAMINER has found a duplicate record (for example, a record with the same key) in a dataset during an ADD operation. There is no difference between DUPLICATE KEY and DUPLICATE RECORD.

EMPTY FILE The dataset is empty. Either the dataset was opened as input and there was nothing in it, or it was opened for output (load) and the string number (STRNO) was greater than one.

END OF FILE The end of the file has been detected on a NXT, or the beginning of the file has been detected on a PRV.

FILE IS NOT OPEN The system operator has told CICS not to allow anyone to use the dataset, or CICS has been told not to make this dataset available unless the system operator tells it otherwise. You can call an administrator to see if they will enable the dataset for you, or you can retry the operation later.



FILE IS NOT VSAM The requested dataset is not a VSAM dataset, or it is not defined in the CICS File Control Table as a VSAM dataset.

FILE NOT AVAILABLE

The requested dataset is unavailable or in use. This error involves the restricted use of the dataset or index by someone else. One of three situations caused this error:

• Another user has the dataset open with DISP=OLD.

• The dataset is open in another CICS that has asked for exclusive control, in which case no one else can use the dataset.

• The SHAREOPTION is set up as 1,3, indicating that any user can open the dataset for read only, but only one user can use the dataset for read/write, In this case, if CICS has the dataset open for output, access to the dataset by any other user is disallowed.

FILE NOT CLOSED The requested dataset was not closed properly last time it was used. Either the job processing the dataset failed, or the machine went down in the middle of a job. You must use the IDCAMS program to verify the dataset or rebuild the dataset from a backup before it can be used again.

GETMAIN FAILED Your CICS system is short on memory, and DATAMINER ONLINE was unable to get the storage it needed to hold your dataset records. To resolve this problem, try your operation when the system memory is in less demand. Do not immediately continue to try your operation because it will continue to fail.

ILLOGICAL REQUEST

The current operation has failed beause of an undetermined reason. This message can occur for any number of reasons. Two possible reasons are

• The key is not in the correct format

• The key is not a valid RBA or RRN

INVALID OPERATION The requested operation is invalid. Make sure that the dataset is correctly specified in the CICS File Control Table if the transaction is using a CICS VSAM dataset. Also check to make sure that a temporary storage retrieval is not being issued against temporary storage created with a DFHTS TYPE=PUT macro. The most common cause of this message is issuing a VSAM command, such as GET, against a Temporary Storage Queue.

I/O ERROR A physical I/O error has occurred.

ISC INV. REQ. DATAMINER ONLINE has issued an invalid system request. Please contact CSI Technical Support to resolve this issue.

ITEM NUMBER ERROR

The requested item number is not in the specified Temporary Storage Queue. This appears if, for example, you issue a TSG command to



display the 50th record of a Temporary Storage Queue that has only 40 records in it.

KEY LENGTH ERROR The key length is not in the CICS File Control Table.

KEY POSITION ERROR

The key position is not in the CICS File Control Table.

KEYS ARE OUT OF SEQUENCE

The THRU KEY you entered is less than the main key.

LRECL ERROR The logical record length in the LRECL field is not valid. It cannot be more than 32K or greater than the dataset’s CISIZE.

NO MORE RCDS You have scrolled past the end of the dataset.

NOT IN FCT The filename specified is not in the CICS File Control Table. Either you are entering it incorrectly or you are trying to access a Temporary Storage Queue using a VSAM command.

NOT OPEN The requested dataset was not opened for some reason other than the reasons above.

OUT OF SPACE There is no more space left in the dataset or in the main temporary storage area. You cannot add any more records. You might be able to add more records if you delete some records first.

PF KEY UNASSIGNED

You have pressed a PF key that does not have a function associated with it. The valid PF keys are listed across the bottom of the screen.

QUEUE ID ERROR The specified Temporary Storage Queue name does not exist. Either it does not exist, or it was purged from the system.

Note If you enter a TSA command to add a new record to a Temporary Storage Queue, DATAMINER ONLINE creates a new queue of that name, if one does not already exist.

RBA The RBA you have entered is not a valid RBA for the dataset.

RECORD NOT FOUND

The requested record was not found on a GET, GTU, RPL, DEL, NXT, or PRV operation. Check that you have entered the correct key.

REMOTE SYSTEM ERROR

You tried to access a dataset in a remote system but the remote system did not allow it. Possible reasons for the remote system to deny your access request are

• The remote system is not running

• There is no connection to the remote system

• The dataset you want is not in the remote system or is not available



SCTY TBL LOAD ERROR

DATAMINER turned on the Security feature, but the Security Module is not available to the script. The name of the Security Module is in the FILEID field.

SECURITY VIOLATION

You do not have the proper security to request this operation on this dataset. If you think you should have the authority, contact your system administrator about upgrading your entry in the Security Module.

SEQUENCE ERROR DATAMINER is trying to write a record out of sequence.

SYSTEM ID ERROR DATAMINER is not licensed to run on your CPU. Have your systems programmer contact CSI Technical Support for a product key that will run on your CPU.

EXP. DATE HAS EXPIRED

DATAMINER uses another product, DATAMINER/VE, and it has expired. Your systems programmer needs to get a new product key from CSI Technical Support.

CSI-DATAMINER 30 DAY WARNING

The CSI-DATAMINER CICS module will expire within 30 days. Your systems programmer needs to get a new product key from CSI Technical Support. Tell your systems programmer immediately.



19
DATAMINER/VE
CSI International’s DATAMINER/VE (hereafter referred to as DATAMINER/VE) is an easy-to-use, general purpose VSAM I/O interface utility that simplifies and standardizes access to VSAM datasets. It is used by and included with DATAMINER. DATAMINER/VE provides full VSAM access from programs written in many fourth-generation languages (4GL) such as NATURAL and Focus. DATAMINER/VE also provides a more powerful, easier, and more efficient way of accessing VSAM from programs written in third-generation languages such as COBOL and PL/I.


Page

DATAMINER/VE Benefits and Features . . . . . . . . . . . . . . . . . . . . . . . . 19.2DATAMINER/VE and 4GL, COBOL, and PL/I . . . . . . . . . . . . . . . . . . 19.4DATAMINER/VE Access to VSAM Files . . . . . . . . . . . . . . . . . . . . . . . 19.6DATAMINER/VE Programming Overview . . . . . . . . . . . . . . . . . . . . . . 19.7How DATAMINER/VE Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.9CICS and COM-PLETE Requirements . . . . . . . . . . . . . . . . . . . . . . . 19.10Executing DATAMINER/VE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.12CICS Temporary Storage Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.13CICS—CONTROL-BLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.14CICS—RECORD-AREA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.22Batch—CONTROL-BLOCK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.23Batch—RECORD-AREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.30Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.31Program Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.35DATAMINER/VE Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.43DATAMINER/VE Online Security . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.44DATAMINER/VE Control Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.48

DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE

DATAMINER/VE Benefits and Features

Benefits DATAMINER/VE provides many benefits:

• DATAMINER/VE is a standardized VSAM interface. DATAMINER/VE simplifies and standardizes VSAM access procedures for all languages, provides consistent VSAM access across applications and processing environments, and reduces VSAM training requirements for your programming staff.

• VSAM expertise is no longer required to access VSAM datasets.

• DATAMINER/VE is based on the premise that VSAM users should be able to use VSAM without extensive VSAM training.

• DATAMINER/VE increases VSAM functionality. DATAMINER/VE adds additional VSAM commands and functions to programs that access VSAM while simplifying VSAM coding.

• DATAMINER/VE improves programmer VSAM productivity. DATAMINER/VE permits programmers to easily access VSAM datasets from any program written in almost any language, including COBOL, PL/I, NATURAL, assembler, and most 4GLs.

• DATAMINER/VE enhances your programmers’ VSAM proficiency. DATAMINER/VE reduces the frequency of VSAM programming errors, simplifies VSAM request processing, and provides consistent VSAM error code analysis and handling. DATAMINER/VE ensures that correct VSAM command protocol is implemented.

• DATAMINER/VE makes COBOL and PL/I easier to use. DATAMINER/VE manages all the complexities involved with accessing VSAM datasets. Inexperienced and proficient programmers alike are freed from considering most technical aspects of using VSAM. Programmers need to know fewer commands and handle fewer errors when they access their VSAM datasets with DATAMINER/VE.

• DATAMINER/VE makes VSAM access more efficient. Benchmarks against native COBOL have demonstrated that DATAMINER/VE executes VSAM I/Os significantly faster than performing the same I/Os under COBOL.

• DATAMINER/VE extends your capabilities. DATAMINER/VE makes it possible for your programs to use VSAM facilities that are not supported by the compiler.

• DATAMINER/VE makes VSAM more logical. Rather than allowing your program to ABEND because something slightly out of the ordinary has happened, DATAMINER/VE takes sensible recovery steps.




DATAMINER/VE permits users to easily retrieve, add, modify, or delete VSAM records without knowing anything about VSAM. DATAMINER/VE automatically determines VSAM dataset and record characteristics, and it automatically handles all conventional VSAM functions.

DATAMINER/VE’s features and capabilities include the following:

• Online and batch VSAM access modes are provided.

• Fixed- or variable-length records are handled.

• Records are accessed by full or generic key.

• Records can be browsed forward or backward.

• Record positioning is handled automatically.

• Records can be loaded automatically into empty datasets.

• Full access to CICS temporary storage is supported.

• CICS sync points are taken automatically on logged datasets.

• Up to 45 datasets can be accessed simultaneously. This is a default value and can be changed either for an individual job or for the site.



DATAMINER/VE and 4GL, COBOL, and PL/I

Introduction Many fourth-generation languages (4GL) only read (and not write) VSAM. Only a few allow users to both read and write VSAM. Over 100 users of Software AG’s fourth-generation language (NATURAL) have used DATAMINER/VE to access VSAM datasets with full power and exceptional reliability. Users can bring all the power and productivity of their 4GL programming language to the VSAM world, making VSAM a full partner to their Data Base Management System (DBMS).

DATAMINER/VE also provides easy VSAM access from other languages that do have native access to VSAM, such as COBOL and PL/I. DATAMINER/VE makes VSAM access easier and more flexible in COBOL and PL/I programs.

DATAMINER/VE and 4GL Partnership Benefits

Using DATAMINER/VE and a 4GL together optimizes development efforts by

• Requiring only one programming language for all application development and increasing programmer productivity by 10:1 over COBOL and PL/I

• Coupling the productivity of your 4GL with the efficiency of VSAM and permitting users to quickly satisfy report requests and requests for VSAM information

• Accessing VSAM and DBMS datasets at the same time in the same program, eliminating the need to maintain redundant copies of VSAM datasets in your DBMS

• Delaying or avoiding unneeded conversion of VSAM datasets to DBMS, allowing users to easily handle VSAM datasets that they do not want to migrate to the DBMS.

DATAMINER/VE and COBOL and PL/I Benefits

DATAMINER/VE provides the following benefits when working with COBOL and PL/I:

• DATAMINER/VE offers an extremely simple syntax and standard assembler calls. COBOL and PL/I users no longer have to concern themselves with complex VSAM protocol or with knowing anything about VSAM. In fact, they do not even need to write a COBOL FD statement to define a dataset.

• In addition to being simpler to use, DATAMINER/VE allows users to perform operations that are either difficult or impossible in COBOL. Some of these functions include automatic loading to empty datasets, backward browsing in the middle of a dataset, reset to empty on the fly, and automatic retrieval of record lengths for variable-length records.



• DATAMINER/VE avoids many of the more annoying ABENDs caused by VSAM. For example, if you want DATAMINER/VE to treat an empty ESDS as if it were just a dataset that hits immediate end-of-file, it can be done with one COBOL statement or set as an installation-wide default.

• DATAMINER/VE makes COBOL/VSAM access faster and more efficient. Benchmarks have shown that accessing VSAM through DATAMINER/VE from COBOL programs can be faster than using native COBOL code. DATAMINER/VE also makes it possible to do things to VSAM datasets that high-level languages do not provide.



DATAMINER/VE Access to VSAM Files

Introduction DATAMINER/VE provides a common interface into your VSAM datasets, whether that access originates within CICS, COM-PLETE, or from any concurrently executing program(s) written in any language and running online or in batch mode.

Online Access Application programs access VSAM datasets through a standard program CALL with associated parameter values. All programming languages that can call assembler subroutines are supported.

DATAMINER/VE can access VSAM data in the following online environments:

• CICS Application Program Calls.

• COM-PLETE Application Program Calls.

Batch Access DATAMINER/VE supports VSAM access for batch environments. All programming languages that can call assembler subroutines are supported. The batch facilities provide easy access to VSAM datasets from any program written in any language and executed in a batch mode. Batch programs access VSAM datasets through a standard program CALL with associated parameter values to the module VNATB.



DATAMINER/VE Programming Overview

Introduction DATAMINER/VE consists of two programs, VNAT for CICS and VNATB for batch and COM-PLETE.

Execution is via the standard IBM LINK or CALL passing two parameters: the address of the CONTROL-BLOCK and the address of the RECORD-AREA.

All standard functions, datasets, records, and key types are supported. DATAMINER/VE permits users to easily retrieve, add, replace, modify, or delete records on any type of VSAM dataset.

All commands are easy-to-understand, three-character mnemonics. Commands such as GET for get a record, RPL for replace, ADD for add, and NXT for browse forward, make DATAMINER/VE simple to learn and understand. All VSAM errors are translated into easy to understand English language messages.

General Access To access VSAM data, a programmer needs to know:

• The name of the VSAM dataset

• How long and where the key is in the record

• How the data in the record is laid out

• How to use DATAMINER/VE

CICS Access To access VSAM records or temporary storage, the user must:

1. Define the CONTROL-BLOCK that contains the DATAMINER/VE processing options

2. Define the RECORD-AREA or Temporary Storage Queue that contains the data to be read or written

3. Fill the CONTROL-BLOCK with the DATAMINER/VE processing commands, and

4. Issue the call or link to VNAT using the CONTROL-BLOCK.

Batch Application Access

Batch application programs or programs running under COM-PLETE may access VSAM datasets through a standard program CALL to DATAMINER/VE’s VNATB I/O module, with associated parameter values. To access VSAM records, the user must do four things:

1. Define the CONTROL-BLOCK that contains the DATAMINER/VE processing options

2. Define the RECORD-AREA that contains the data received from or to be passed to DATAMINER/VE



3. Fill the CONTROL-BLOCK with the DATAMINER/VE processing ACTION-CODEs, and

4. Issue the call to VNATB using the CONTROL-BLOCK.

Supported Environments

DATAMINER/VE supports the following environments:

• DATAMINER/VE runs under all releases of z/OS.

• DATAMINER/VE supports CICS releases 1.6 and later.

• DATAMINER/VE supports Multi-Region Option (MRO) for CICS release 1.7 and above.

• DATAMINER/VE supports but does not require the use of the CICS TWA.



How DATAMINER/VE Works

Sequence This is the processing sequence for DATAMINER/VE:

1. A program uses DATAMINER/VE through a standard CALL or LINK to one of its two I/O modules (VNAT for CICS, or VNATB for batch), with associated parameter values that are defined in the CONTROL-BLOCK. Most dataset attributes are automatically determined by examining the VSAM catalog and/or the CICS File Control Table.

2. After the CALL has been successfully completed, a VSAM record will have been read, added, modified, or deleted, depending on the parameters supplied in the CONTROL-BLOCK.

3. If a record write operation was requested and successfully completed, a VSAM record will have been written to the VSAM dataset.

4. If a record retrieval was requested and successfully completed, the retrieved record will be contained in the RECORD-AREA.

Programmer-Defined Components

There are two components that the programmer must create before calling DATAMINER/VE:

Return Codes Regardless of the success or failure of any requested operation, a three-character RETURN-CODE indicating the exact results of the operation returned to the program in the RETURN-CODE field of the CONTROL-BLOCK. This code may be interrogated by the calling program for conditions specified in the list of DATAMINER/VE RETURN-CODEs. (See “Return Codes ” [page 19.31].)

Depending upon the results of an operation and the analysis of the resulting RETURN-CODEs, appropriate actions may be taken under program control.

CONTROL-BLOCK The CONTROL-BLOCK tells DATAMINER/VE what to do. Parameter values are defined in the CONTROL-BLOCK. There is only one CONTROL-BLOCK per program regardless of the number of datasets being handled.

RECORD-AREA The RECORD-AREA must be large enough to hold the longest record anticipated to be returned from a record retrieval. This area is where data to be written to VSAM or data received from VSAM will be contained.



CICS and COM-PLETE Requirements

Introduction For CICS and COM-PLETE users, datasets and share options must be defined for DATAMINER/VE.

CICS Users For DATAMINER/VE to work with CICS

• Files to be accessed by DATAMINER/VE must be defined in the CICS File Control Table.

• The INQUIRE/SET commands must be defined in the PPT and available to the user in order to use DATAMINER/VE under CICS 1.7 and up.

COM-PLETE Users For DATAMINER/VE to work with COM-PLETE:

Defining the datasets

Files to be accessed by DATAMINER/VE under COM-PLETE control must be defined to COM-PLETE. Defining the dataset to COM-PLETE associates the dataset name with the FILE-ID used in DATAMINER/VE calls. To make the name usable in COM-PLETE, the FILE-ID must be cataloged using the ULIB-CAT utility.

The following is a sample of the ULIB-CAT parameters required to define a dataset to COM-PLETE:

ULIBCAT DDN="ddname"

ONLN,VS,RETRIEVR,UPDATE,ADD BSTR=0,STRN=0,MRPL=0 MACR=KEY,SEQ,DIR,OUT,NUB,DDN, NRM,NSR,NCI,NDF,NIS,NFX,NRS

Shareoptions For Shareoptions:

COM-PLETE automatically opens datasets defined to COM-PLETE for update by online users. To allow concurrent access by multiple copies of COM-PLETE, or by concurrent online and batch users, Shareoptions must be set to “3,3”.

The normal default value is LSR (local-shared resource). To access a dataset under DATAMINER/VE, the option must be set to NSR (non-shared resource).



System Parameters

In addition to the things that must be done to the dataset tables in COM-PLETE, the following system parameters in COM-PLETE must be properly set:

VSAM Buffers—(Number of threads in COM-PLETE) * (Number of VSAM datasets).

VSAM DS—Number of VSAM datasets you want to access.

VSAM RPL—Maximum number of active users.

For information on the VSAM Systems Parameters, reference the COM-PLETE Systems Programmers Manual.



Executing DATAMINER/VE

Introduction DATAMINER/VE is executed through a standard CALL or LINK to one of its I/O modules (VNAT for CICS, and VNATB for batch, TSO, and COM-PLETE.

COBOL Example This is an example of a CALL statement for COBOL:

CALL VNATB using CONTROL-BLOCK RECORD-AREA

Note VNATB can be either static or dynamic.

NATURAL Example The following example is a CALL statement for NATURAL:

CALL "VNATB" #RTN-CODE #FIELD1

Note Do not use group-level names as parameter names. NATURAL expands the passed parameter list to include all of the subordinate elementary field names. Always use the name of the first elementary field in the CONTROL-BLOCK (RETURN-CODE) and the name of the first elementary field in the RECORD-AREA.

Batch Assembler Example

The following example is a LINK statement for Batch Assembler:

LINK EP=VNATB, PARAM=(CTBLK, RECORD), VL=1



CICS Temporary Storage Access

Introduction CICS application programs access VSAM datasets through a standard program CALL to DATAMINER/VE’s VNAT I/O module, with associated parameter values.

In addition to VSAM access, DATAMINER/VE accesses CICS temporary storage with full read and write capability. This is a very efficient storage medium that is completely managed by CICS. Its usage requires very little effort on the part of the programmer. Storage is managed in queues.

Temporary Storage Use

Some typical ways you can use temporary storage include the following:

Data Collection You can interrupt, resume, and verify during data collection. The user can collect application data (either VSAM or ADABAS or both), store it in temporary storage, and postpone actual update until a transaction has been accepted.

Data Transfer You can pass data between tasks, even to multiple languages.

Data Storage You can store data for repositioning after a display.

You can accumulate records before updating a dataset. This allows you to accept or reject a batch of records before a dataset is updated. You can also accumulate records from different datasets to allow for synchronized writes.

Data Paging Temporary storage can be used to hold information to be used for paging forward, backward, or to a specific page of data.

• You can store data for repositioning in a dataset.

• You can store excess data in temporary storage when the requested data will not fit on one screen.

• You can store records in temporary storage for fast browsing without having to reread the records.



CICS—CONTROL-BLOCK

Introduction You set up one CONTROL-BLOCK for your program to use, regardless of the number of datasets you intend to access. The name of the CONTROL-BLOCK or the name of the first elementary field of the CONTROL-BLOCK is specified as the first operand in the CALL or LINK to DATAMINER/VE and is mandatory for all operations. The transaction COMMAREA is a good place to keep the CONTROL-BLOCK.

This section gives examples of the CONTROL-BLOCK field sequence and lists and describes the fields.

COBOL Example The following example shows the sequence of the fields in the CONTROL-BLOCK for COBOL:

01 CONTROL-BLOCK. 02 RETURN-CODE PIC XXX. 02 ACTION-CODE PIC XXX. 02 FILE-ID PIC X(8). 02 RECORD-LENGTH PIC S9999 COMP. 02 RESERVED-AREA PIC X(17). 02 KEY-POSITION PIC S9999 COMP. 02 KEY-LENGTH PIC S9999 COMP. 02 KEY PIC X(nn).

Assembler Example The following example shows the sequence of the fields in the CONTROL-BLOCK for assembler:

CTLBLK DS 0CL37 RETCODE DS CL3 RETURN CODEACTION DS CL3 ACTION CODEFILEID DS CL8 DD NAMELRECL DS AL2 RECORD LENGTHRESERVE DS XL17'00' RESERVED (NOT SPARE!) KEYPOS DS AL2 KEY POSITIONKEYLEN DS AL2 KEY LENGTH. KEY DS CLnn ACTUAL KEY

Note Do not align the fields on halfword or other boundaries. There should be no extra slack bytes in the CONTROL-BLOCK.

RETURN-CODE (CL3) DATAMINER/VE puts a three-character completion code here after it has processed each call. This field contains either 000, which indicates successful completion, or a three-letter return code. See “Return Codes ” (page 19.9).



ACTION-CODE (CL3) This field specifies the type of function to be performed on the dataset specified in FILE-ID. ACTION-CODE can be any one of the following three-letter codes:

Code Description

ADD Add a record to the dataset with the information contained in the record area. For KSDS datasets, the key in the RECORD-AREA is used, and KEY in the CONTROL-BLOCK is filled by DATAMINER/VE.

DEL Delete one or more records with a key equal to KEY from the KSDS or RRDS dataset named in FILE-ID. DEL is not allowed for ESDS datasets. The RECORD-AREA is not used. A DEL ACTION-CODE automatically releases its dataset work areas and outstanding held strings before returning to the caller. A DEL does not have to be preceded by a Get For Update ACTION-CODE (GTU).

If a full key is specified, DATAMINER/VE deletes one record with a key equal to KEY.

If a generic key is specified, DATAMINER/VE deletes all records with a key equal to KEY. Valid for KSDS datasets only.

FST Retrieve the first record on the dataset. The KEY field is ignored for retrieval and filled by DATAMINER/VE with the key of the first record in the dataset.

GET/GGE Retrieve one record into the RECORD-AREA with a key greater than or equal to KEY. A GET or GGE ACTION-CODE automatically releases its dataset work areas and outstanding held strings before returning to the caller.

A GET or GGE against an RRDS or ESDS dataset is executed as full key equal.

A GET or GGE against a KSDS dataset is executed as full or generic key equal to or greater than.

GEQ Retrieve one record into the RECORD-AREA with a key equal to KEY. A GEQ ACTION-CODE automatically releases its dataset work areas and outstanding held strings before returning to the caller.

GTU/GGU Retrieve one record (for update) into the RECORD-AREA with a key greater than or equal to KEY. A GTU or GGU ACTION-CODE locks the entire VSAM Control-Interval until the next ACTION-CODE is executed or until the CICS transaction ends.

Warning: The use of this ACTION-CODE is recommended only if the user needs to lock a Control-Interval to ensure record integrity.



GEU Retrieve one record (for update) into the RECORD-AREA with a key equal to KEY. A GEU ACTION-CODE locks the entire VSAM Control-Interval until the next ACTION-CODE is executed or until the CICS transaction ends.

Warning: The use of this ACTION-CODE is recommended only if the user needs to lock a Control-Interval to ensure record integrity.

LST Retrieve the last record on the dataset. The KEY field is ignored for retrieval and filled by DATAMINER/VE with the key of the last record in the dataset.

NXT Retrieve the next sequential record into the RECORD-AREA. This ACTION-CODE ties up a CICS dataset string, so use the NXT ACTION-CODE only when browsing is needed.

NXT against RRDS and ESDS datasets are executed as full key equal. NXT against KSDS datasets are executed as full key or generic key equal to or greater than.

When using a NXT against KSDS datasets, skip sequential processing is accomplished by changing the KEY field. DATAMINER/VE compares the value in the KEY field to the previous key to determine whether the user is skipping. If the KEY has changed, a new NXT operation is created. If the KEY has not changed, the program continuez to browse.

When processing records with duplicate keys through an alternate index, VSAM does not allow interrupted browsing. An interrupted NXT ACTION-CODE always retrieves a non-unique key group by starting at the beginning record within the group.

Code Description



PRV Retrieve the previous record, reading sequentially backward, and move it to the RECORD-AREA. This ACTION-CODE ties up a CICS dataset string, so use the PRV ACTION-CODE only when browsing is needed.

PRV against RRDS and ESDS datasets are executed as full key equal. PRV against KSDS datasets are executed as full key or generic key equal to or greater than.

When using a PRV against KSDS datasets, skip sequential processing is accomplished by changing the KEY field. DATAMINER/VE compares the value in the KEY field to the previous key to determine whether the user is skipping. If the KEY has changed, a new PRV operation is created. If the KEY has not changed, the program can continue to browse.

Warning: When processing records with duplicate keys through an alternate index, VSAM does not allow backward browsing.

REL Terminate any outstanding request against a dataset. Release positioning or exclusive control against a Control-Interval.

REL releases any CICS strings held by GTU, NXT, or PRV, and releases any locked Control-Intervals held by a GTU ACTION-CODE that was not followed by a DEL or RPL. A release of any locked Control-Intervals (REL) is done automatically, if needed, at the start of a DEL, GET, GGE, GEQ, NXT, PRV, or RPL. DATAMINER/VE does not object if you issue a REL for a dataset that has no outstanding requests.

In a pseudo-conversational environment, a REL is automatic whenever a transaction ends.

RPL Replace a record in the dataset with the information contained in the RECORD-AREA. For KSDS datasets, the key in the RECORD-AREA is used, and KEY is filled by DATAMINER/VE. The length of a variable-length record can be changed by putting the new value in the RECORD-LENGTH field in the CONTROL-BLOCK.

TSA Add a record to the end of a Temporary Storage Queue. This ACTION-CODE uses FILE-ID, RECORD-LENGTH, and RECORD-AREA. A TSA returns the Item-Number in the KEY field as a four-byte binary number (BL4). If the named queue does not exist, it is created.

Code Description



FILE-ID (CL8) This is the dataset identification of a VSAM dataset or a VSAM alternate index path (DD or CICS File Control Table entry), or the Queue-ID of a Temporary Storage Area.

For VSAM, FILE-ID must match a File-ID in the File Control Table.

For temporary storage, FILE-ID can be any alphanumeric value except that it cannot start with a hexadecimal value of X'FA' through X'FF', and it must be unique within CICS. FILE-ID is mandatory for all temporary storage operations.

TSR Replace a record in the Temporary Storage Queue. This ACTION-CODE uses FILE-ID, RECORD-LENGTH, KEY, and RECORD-AREA. A TSR can change the data and/or the record length.

TSD Delete the entire Temporary Storage Queue that matches the Queue-ID in the FILE-ID field. This ACTION-CODE uses only the FILE-ID field.

TSG Get a record from the Temporary Storage Queue with an Item-Number equal to the Item-Number contained in the KEY field.

TSN Get the next record from the Temporary Storage Queue with an Item-Number greater than the Item-Number contained in the KEY field. If the KEY has been changed since the last retrieval, skip to the record with a KEY equal to the new Item-Number. This ACTION-CODE uses the FILE-ID and KEY, returns the new Item-Number in the KEY field, and fills RECORD-LENGTH and the RECORD-AREA.

TSP Get the previous record from the Temporary Storage Queue with an Item-Number less than the Item-Number contained in the KEY field. If the KEY has been changed since the last retrieval, skip to the previous record with a key equal to the new Item-Number. This ACTION-CODE uses the FILE-ID and KEY, returns the new Item-Number in the KEY field, and fills RECORD-LENGTH and the RECORD-AREA.

Code Description



RECORD-LENGTH (BL2)

This is the logical VSAM record length or the logical record length of a temporary storage record.

VSAM Records

If ACTION-CODE is ADD or RPL, RECORD-LENGTH must be set to the actual record length. If dataset is variable length, RECORD-LENGTH must be large enough to contain the entire key but not larger than maximum record length.

If ACTION-CODE is GET, GGE, GEQ, GTU, FST, LST, NXT, or PRV, one of two things happens:

• DATAMINER/VE fills the RECORD-LENGTH field with the length of the record retrieved if you place zero in RECORD-LENGTH before you call VNAT.

or

• The first n bytes of the record is returned in RECORD-AREA if you put a non-zero value (n) in RECORD-LENGTH before you call VNAT.

If you always want to retrieve the entire record, always set RECORD-LENGTH to zero before issuing each CALL to read a record.

If ACTION-CODE is DEL, the RECORD-LENGTH field is ignored.

Temporary Storage Operations

For temporary storage operations, the RECORD-LENGTH field contains the logical record length of the temporary storage record. It is mandatory for all output temporary storage operations. For TSG, TSN, and TSP, one of two things happens:

• The RECORD-LENGTH field is filled with the length of the record retrieved if you place zero in RECORD-LENGTH before you call VNAT.

or

• The first n bytes of the record are retuned to you in RECORD-AREA if you put a non-zero value (n) in RECORD-LENGTH before you call VNAT.

If you always want to retrieve the entire record, always set RECORD-LENGTH to zero before issuing each CALL to read a record.

Maximum record length is 32,700.



RESERVED-AREA (BL17)

This area is reserved for use by DATAMINER/VE. It must be set to binary zeros at the start of the program and must never be altered between calls to DATAMINER/VE. DATAMINER/VE uses this field itself to remember what it was doing the last time it was called.

KEY-POSITION (BL2) This is the position of the key in a remote KSDS VSAM dataset. It is required for remote users of KSDS datasets. If this field is filled, it must be the key position relative to 1. This field is ignored if the key position is available from the File Control Table.

KEY-LENGTH (BL2) This is the length of the KSDS and alternate index key to use for retrievals and deletes. If the field equals zero, full key is assumed. This field is ignored for temporary storage.

For ESDS and RRDS, this field value must be zero. For KSDS and alternate indexes, this field value must be zero through full-key-length. If the value is greater than zero and less than full-key-length, a generic key is assumed, and only a key of the specified length is used for retrieval.

DEL, GET, GGE, GEQ, GTU, GGU, GEU, a new NXT, or a new PRV ACTION-CODE issued against a KSDS dataset or alternate index uses KEY-LENGTH.

New NXT and new PRV refer to starting a browse after the KEY field has been changed to a new value.



KEY (Variable) The KEY field is different for VSAM operations and Temporary Storage operations:

VSAM Operations

This is the key of the record for VSAM record operations and may contain a 4-byte binary Relative Record Number (RRN) or Relative Byte Address (RBA), or a 1- to 253-byte alphanumeric KSDS or alternate index full or generic key.

The KEY field must be filled before a GET, GGE, GEQ, GTU, GGU, GEU, a new NXT, a new PRV, or DEL ACTION-CODE. DATAMINER/VE returns the full key of the current record in this field following a FST, LST, NXT or PRV ACTION-CODE issued against an RRDS or ESDS dataset or a FST, LST, GET, GGE, GEQ, GTU, GGU, GEU, NXT, PRV, RPL or ADD ACTION-CODE issued against a KSDS dataset or alternate index.

The KEY field must be large enough to accept the full key.

Temporary Storage Operations

For temporary storage operations, the KEY field contains the binary Item-Number in bytes 2 and 3 of the field. The KEY field must be defined as being at least four bytes long. The KEY field is mandatory for TSR and TSG ACTION-CODEs. It is optional for TSN and TSP ACTION-CODEs. It is automatically filled by the TSA, TSN, and TSP ACTION-CODEs. The KEY field is ignored by a TSD ACTION-CODE.



CICS—RECORD-AREA

Introduction The name of the RECORD-AREA or the name of the first elementary field of the RECORD-AREA is specified as the second operand in the CALL. It is mandatory for all operations except DEL, REL, and TSD ACTION-CODEs.

The calling program puts a record to be written to a dataset in the RECORD-AREA before each ADD, RPL, TSA, or TSR. It is filled by DATAMINER/VE for any input operation, such as GET or NXT.

RECORD-AREA Size The RECORD-AREA must be as large as the largest record expected to be returned from the DATAMINER/VE call or to be used during the temporary storage operation. Because of field size limitations in NATURAL programs, the RECORD-AREA must be defined in segments smaller than 253 bytes. For example, if you want to define a RECORD-AREA long enough to hold a 400-byte record, you need to set up the RECORD-AREA in the following manner:

1 #EMPLOYEE-RECORD 2 #EMP-NO (A6) 2 #EMP-NAME (A30) 2 #EMP-ADR (A30) 2 #FILLER-1 (A5) 2 #EMP-SSNO (A9) 2 #FILLER-2 (A200) 2 #FILLER-3 (A120)



Batch—CONTROL-BLOCK

Introduction The name of the CONTROL-BLOCK or the name of the first elementary field of the CONTROL-BLOCK is specified as the first operand in the CALL. It is mandatory for all operations.

This section shows examples of CONTROL-BLOCK field sequences and lists, and it defines the fields in the CONTROL-BLOCK.

COBOL Example This example shows the field sequence for a Cobol CONTROL-BLOCK:

01 CONTROL-BLOCK. 02 RETURN-CODE PIC XXX. 02 ACTION-CODE PIC XXX. 02 FILE-ID PIC X(8). 02 RECORD-LENGTH PIC S9999 COMP. 02 RESERVED-AREA PIC X(10). 02 PASSWORD-LG PIC X. 02 PASSWORD PIC X(8). 02 KEY-LENGTH PIC S9999 COMP. 02 KEY PIC X(nn).

Assembler Example The following example shows the field sequence for an assembler CONTROL-BLOCK:

CTLBLK DS 0CL35 RETCODE DS CL3 RETURN CODE ACTION DS CL3 ACTION CODE FILEID DS CL8 DD NAME LRECL DS AL2 RECORD LENGTH RESERVE DS XL10'00' RESERVED (NOT SPARE!) PWDLEN DS BL1 PASSWORD LENGTH PASSWD DS CL8 KEYLEN DS AL2 KEY LENGTH. KEY DS CLnn ACTUAL KEY

Note 1 Do not align the fields on half-word or other boundaries—there should be no extra slack bytes in the CONTROL-BLOCK.

Note 2 The formats of the CONTROL-BLOCK used for CICS and batch are not exactly the same.

RETURN-CODE (CL3) This area is filled by DATAMINER/VE. (See “Return Codes ” [page 19.31].)



ACTION-CODE (CL3) This field specifies the type of function to be performed on the dataset specified in FILE-ID. The function may be any one of the following ACTION-CODEs.

Code Description

ADD When an ADD is executed, DATAMINER/VE senses when a dataset is empty and needs to be loaded. This condition exists after a DATAMINER/VE Reset (RST) ACTION-CODE has been issued or immediately after a dataset has been defined. VNATB opens the dataset as output sequential and adds records until an out-of-sequence condition occurs or until a non-ADD request. It then closes the dataset and opens it for random access. This is transparent to the user.

The dataset must be allocated with STRNO=1 or else a RETURN-CODE of EMP (dataset is empty) is returned.

CLS Close one or more open datasets. All datasets open to DATAMINER/VE should be closed before the job ends. If the first byte of FILE-ID is a space or binary zeros, all open datasets are closed; otherwise, only FILE-ID is closed.

Up to 45 VSAM datasets may be opened and accessed at one time by DATAMINER/VE. If more than 45 are needed, a previously opened dataset must first be closed. See INV RETURN-CODE in “Return Codes ” (page 19.9).

DEL Delete one record with a key equal to KEY on any KSDS or RRDS dataset. DEL is not allowed for ESDS datasets. The RECORD-AREA is not used.

A DEL does not have to be preceded by a GTU.

FST Retrieve the first record on the dataset. The KEY field is ignored for retrieval and then filled with the full key.

GET/GGE Retrieve one record into the RECORD-AREA with a key greater than or equal to KEY. A GET or GGE automatically releases its dataset work areas and outstanding held strings before returning to the caller.

A GET or GGE against an RRDS or ESDS dataset is executed as full key equal.

A GET or GGE against a KSDS dataset is executed as full or generic key equal to or greater than.

GEQ Retrieve one record into the RECORD-AREA with a key equal to KEY.



GTU/GGU Retrieve one record (for update) into the RECORD-AREA with a key greater than or equal to KEY. A GTU or GGU locks the entire VSAM Control-Interval until the next ACTION-CODE is executed.

Note The use of this ACTION-CODE is recommended only if the user needs to lock a Control-Interval to ensure record integrity.

GEU Retrieve one record (for update) into the RECORD-AREA with a key equal to KEY. A GEU locks the entire VSAM Control-Interval until the next ACTION-CODE is executed.

Note The use of this ACTION-CODE is recommended only if the user needs to lock a Control-Interval to ensure record integrity.

LST Retrieve the last record on the dataset. The KEY field is ignored for retrieval and is then filled with the full key.

Code Description



NXT Retrieve the next sequential record into the RECORD-AREA. The NXT ACTION-CODE should be used when forward browsing is needed. When running in an online environment, do not leave a NXT active while waiting for a response from a user. This could cause a dataset lockout of another user.

The first NXT against RRDS and ESDS datasets is executed as full key equal, (FKEQ).

The first NXT against a new KSDS or alternate-index key is executed as (FKGE) or (GKGE). Subsequent NXT ACTION-CODEs browse through the records.

Although REL terminates an active browse, a NXT/REL/NXT works the same as a NXT/NXT, as long as the KEY field is not altered. DATAMINER/VE recognizes the need and automatically restarts the browse at the next record.

When a users uses NXT against KSDS datasets or alternate indexes, skip sequential processing is accomplished by changing the KEY field. DATAMINER/VE compares the value in the KEY field to the previous key to determine whether the user is skipping. If the Key has changed, a new NXT operation is created. If KEY has not changed, the program continues to browse.

When processing records with duplicate-keys through an Alternate-index, VSAM does not allow interrupted browsing. A NXT issued after a different ACTION-CODE always retrieves a non-unique key group by starting at the beginning record within the group. See “DataMiner/VE Programming Tips” on page 20-2 for an exception to this rule when updating and deleting records.

Code Description



PRV Retrieve the previous record, reading sequentially backward, and move it to the RECORD-AREA.

PRV ACTION-CODEs against RRDS and ESDS datasets are executed as full key equal (FKEQ).

PRV ACTION-CODEs against KSDS datasets are executed as full key or generic key equal to or greater than, (FKGE/GKGE).

When using PRV against KSDS datasets and Alternate-Indexes, skip sequential processing is accomplished by changing the KEY field. DATAMINER/VE compares the value in the KEY field to the previous key to determine if the user is skipping. If KEY has changed, a new PRV operation is created. If KEY has not changed, the program will continue to browse.

When processing records with duplicate keys through an Alternate-Index, VSAM will not allow backward browsing.

REL Terminate any outstanding request against this dataset. Release positioning or exclusive control against a Control-Interval. The REL ACTION-CODE is of particular value when operating within a large dataset under COM-PLETE

When multiple users are doing updates and inquiries, the REL ACTION-CODE prevents interlocks by releasing Control-Intervals.

When running under COM-PLETE, do not leave a GTU, NXT, or PRV ACTION-CODE active while waiting for a response from a user. This could cause another user to be (RST) locked out of a dataset.

Although REL terminates an active browse, a NXT/REL/NXT works the same as a NXT/NXT, as long as the KEY field is not altered. DATAMINER/VE recognizes the need and automatically restarts the browse at the next record.

Code Description



Special Notes Relating to Generic Key Browse Handling:

• On completion of an input operation, VNATB fills the KEY field in the CONTROL-BLOCK with the full key of the record just retrieved.

• VNATB sets the KEY-LENGTH field to binary zeros to reflect that KEY is now a full key. This allows recognition of any user entered generic KEY-LENGTH on following calls. VNATB treats a generic KEY-LENGTH as a changed key and reposition the dataset on the generic key, even if the KEY field has not been changed. This makes skip sequential processing more flexible and easier to use.

FILE-ID (CL8) This is the DDNAME of the dataset (dataset identification of a VSAM dataset or a VSAM alternate index path).

RECORD-LENGTH (BL2)

This is the logical VSAM record length.

If ACTION-CODE is ADD or RPL, RECORD-LENGTH must be set to the actual record length. If dataset is variable length, RECORD-LENGTH must be greater than zero and not greater than maximum record length.

If ACTION-CODE is GET, GGE, GEQ, GTU, FST, LST, NXT, or PRV, one of two things happens:

• DATAMINER/VE fills the RECORD-LENGTH field with the length of the record retrieved if you place zero in RECORD-LENGTH before you call VNAT.

RPL Replace a record in the dataset with the information contained in the RECORD-AREA. For KSDS datasets, the key in the RECORD-AREA is used, and KEY is filled by DATAMINER/VE. For variable length records, the length may be changed.

RST Reset a dataset to (RST) EMPTY status. Records can then be LOADED. The dataset must have been defined with the REUSE option.

When an ADD is executed in batch mode, DATAMINER/VE can sense when a dataset is empty and needs to be loaded. This condition exists after a Reset (RST) ACTION-CODE has been issued or immediately after a dataset has been defined. VNATB then opens the dataset as output sequential and adds records until an out-of-sequence condition or a non-ADD is executed. The dataset is then returned to random mode. This process is transparent to the user.

The dataset must be allocated with STRNO=1, or else a RETURN-CODE of EMP (dataset is empty) is returned.

Code Description



or

• The first n bytes of the record are returned to you in RECORD-AREA if you put a non-zero value (n) in RECORD-LENGTH before you call VNAT. If you always want to retrieve the entire record, always set RECORD-LENGTH to zero before issuing each CALL to read a record.

If ACTION-CODE is CLS, RST, or DEL, the RECORD-LENGTH field is ignored.

RESERVED AREA (BL10)

This area is reserved for use by DATAMINER/VE.

Note This area must be set to binary zeros at the start of the program and must never be altered between calls to DATAMINER/VE.

PASSWORD-LENGTH (BL1)

This binary field contains the length of the VSAM password. Set length to binary zeros if the dataset does not need a password.

PASSWORD (CL8) This field contains a one- to eight-byte password if it is needed at open time.

KEY-LENGTH (BL2) This is the length of the KSDS or alternate-index KEY to use for retrievals and deletes. If KEY-LENGTH is zero, a full key is assumed; otherwise, a generic key is used.

For RRDS or ESDS datasets, KEY-LENGTH must always be zero.

For KSDS datasets and alternate indexes, KEY-LENGTH is used by DEL, GET, GGE, GEQ, GTU, GGU, GEU, NXT, and PRV ACTION-CODEs.

For KSDS DEL ACTION-CODE, KEY-LENGTH must be 0 or full key length.

KEY (Variable Length)

This is the record’s key. It can contain a four-byte binary RRDS Relative Record Number (RRN), ESDS Relative Byte Address (RBA), a 1- to 255-byte alphanumeric KSDS, or an alternate index full or generic key.

The KEY field must be filled before a GET, GGE, GEQ, GTU, GGU, GEU, NEW NXT, NEW PRV, or DEL, ACTION-CODE is issued. DATAMINER/VE returns the full key of the current record in this field after any of the following:

• An ADD ACTION-CODE is issued against an ESDS dataset,

• A FST, LST, NXT, or PRV ACTION-CODE is issued against any VSAM dataset,

• A GET, GGE, GEQ, GTU, GGU, GEU, RPL, or ADD ACTION-CODE is issued against KSDS datasets and Alternate-indexes.

The KEY field must be long enough to accept the full key.



Batch—RECORD-AREA

Introduction The name of the RECORD-AREA or the name of the first elementary field of the RECORD-AREA is specified as the second operand in the CALL. It is mandatory for all operations except DEL, REL, RST, and CLS ACTION-CODEs.

It must be filled by the calling program before each ADD or RPL. It is filled by DATAMINER/VE for any input operation.

Important Points 1. The RECORD-AREA must be as large as the largest record that you expect to be returned from the DATAMINER/VE call.

2. Because of field size limitations in NATURAL programs, the RECORD-AREA must be defined in segments smaller than 253 bytes. For example, if you want to define a RECORD-AREA long enough to hold a 400-byte record, you need to set up the RECORD-AREA in the following manner:

1 #EMPLOYEE-RECORD 2 #EMP-NO (A6) 2 #EMP-NAME (A30) 2 #EMP-ADR (A30) 2 #FILLER-1 (A5) 2 #EMP-SSNO (A9) 2 #FILLER-2 (A200) 2 #FILLER-3 (A120)



Return Codes

DATAMINER/VE fills the RETURN-CODE field in the CONTROL-BLOCK with one of the following three character codes after an execution of DATAMINER/VE.

Code Explanation

000 NORMAL COMPLETION.

CPU UNAUTHORIZED CPU. An attempt has been made to run the program on an unauthorized CPU.

DIS DISABLED. File is disabled in the File Control Table. (CICS only).

DPK DUPLICATE KEY. A duplicate key has been detected on the dataset during a batch ADD operation, or when retrieving non-unique records through an alternate index. If you used a GET or GGE ACTION-CODE, switch to NXT to retrieve the rest of the records with the same key. For NXT ACTION-CODEs, a return code of DPK is returned until the last record with the same key is retrieved.

DPR DUPLICATE RECORD. A duplicate record has been detected on the dataset during an ADD operation (CICS only).

EDT PROGRAM EXPIRED. The program’s expiration date has been exceeded.

EMP EMPTY FILE. File is empty. Either the dataset was opened as input or it was opened for output (load), and the string number (STRNO) was greater than one (BATCH only).

EOF END OF FILE. The end of the dataset has been detected on a NXT ACTION-CODE, or the beginning of the dataset has been detected on a PRV ACTION-CODE. (See NOP.)

HLD Control-Interval HOLD. The requested Control-Interval is being held in exclusive control by another job or user (BATCH only).



ILL ILLOGICAL REQUEST. The current operation failed because the request was illogical. This return code may occur for any number of reasons. The Key may not be in the correct format, the Key may not be a valid RBA or RRN, or the Reserved Area may have been incorrectly altered.

CICS

When an ILL error occurs, the second and third bytes of the EIBRCODE are moved to the RECORD-LENGTH field. An explanation of EIBRCODE(s) can be found in the appendix of the CICS Application Programmers Reference Manual under section “Exec Interface Block.”

BATCH

VSAM Feedback Code (FDBK) is in the RECORD-LENGTH field.

INV INVALID OPERATION. The requested operation is invalid. Make sure that the dataset is correctly specified on the File Control Table if the transaction is using a CICS VSAM dataset. Check for correct handling of the Reserved Area. Also check to make sure that a temporary storage retrieval is not being issued against temporary storage created with a DFHTS TYPE=PUT macro. A batch program may be trying to open more than 45 datasets. See CLS ACTION-CODE.

CICS

The fourth byte of the EIBRCODE is moved to the RECORD-LENGTH field.

BATCH

The VSAM Feedback Code (FDBK) is in the RECORD-LENGTH field.

IOE I/O ERROR. A physical I/O error has occurred.

CICS

When an IOE error occurs, the second and third bytes of the EIBRCODE are moved to the RECORD-LENGTH field. An explanation of EIBRCODE(s) can be found in the Appendix of the CICS Application Programmers Reference Manual under the section “Exec Interface Block.”

BATCH

The VSAM feedback code in the RECORD-LENGTH field.

ISC REMOTE SYSTEM ERROR (CICS only).

ITM Item-Number NOT FOUND. The requested item number is not in the specified Temporary Storage Queue (CICS only).

KLG KEY LENGTH ERROR. The length specified in the KEY-LENGTH field is not valid, or the key length was not found in the CICS File Control Table.

Code Explanation



KPS KEY POSITION ERROR. The key position was not found in the CICS File Control Table. If Remote, fill KPOS in the CONTROL-BLOCK (CICS only).

LRL LOGICAL RECORD LENGTH ERROR. The logical record length specified in the RECORD-LENGTH field is not valid. Remote users must be sure that the maximum record length is specified in the CICS File Control Table.

NAU TASK NOT AUTHORIZED. The task is not authorized for the ACTION-CODE requested. The ACTION-CODE shows the type of operation requested (CICS only).

NAV FILE NOT AVAILABLE. The requested dataset is not available or is in use. This error may involve the restricted use of the dataset or index by someone else. Another user may have the dataset open with DISP=OLD, or the dataset may have been opened in CICS with a DISP=OLD, in which case no one else can use the dataset. Additionally, the SHAREOPTION may have been set up as 1,3, indicating that any user can open the dataset for read only, but only one user can use the dataset for read/write, in which case if CICS has the dataset open for output, write access to the dataset by any other user is disallowed.

NCL FILE NOT CLOSED. The requested dataset was not closed at last usage. Verify before using. (BATCH only)

NDD NO DD STATEMENT SPECIFIED. No JCL statement for File-ID was provided (BATCH only).

NFD RECORD NOT FOUND. The requested record was not found on a GET, GGE, GEQ, GTU, GGU, GEU, RPL, DEL, NXT, or PRV ACTION-CODE.

NFT NOT IN FCT (File Control Table). The filename specified is not in the File Control Table (CICS only).

NOP NOT OPEN. The requested dataset was not opened for some reason other than NVS, NCL, NDD, PSW, EMP, NAV, or RST. NOP is the default value returned when a GET is issued against an empty ESDS. You can change this default value either with the DATAMINER/VE control table or with the EMP command.

Note 1 There is usually only one control table that is used system wide and applies to all datasets. However, the EMP command works at the program level.

Note 2 The VSAM Feedback Code (FDBK) is in the RECORD-LENGTH field (BATCH only).

NSP OUT OF SPACE. The dataset is out of space.

Code Explanation



NVS NOT A VSAM FILE. The requested dataset is not a VSAM dataset.

OPR INVALID OPERATION. The operation requested in the ACTION-CODE field is not valid.

PSW PASSWORD ERROR. The password entered does not match the password set up for access to this dataset (BATCH only).

QID QUEUE ID ERROR. The specified Temporary Storage Queue name does not exist (CICS only).

RBA RELATIVE BYTE ADDRESS. KEY is not a valid RBA.

RCD NO RECORD-AREA SPECIFIED. A RECORD-AREA is not specified in the CALL for an operation other than REL, RST, DEL, TSD, or CLS.

RST RESET NOT VALID. REUSE must be specified in the DEFINE.

SCY SECURITY VIOLATION. The user does not have the proper security for this ACTION-CODE on this dataset when using the Security Modules (CICS only).

SEG SEGMENT ERROR. VSAM reason code is 140 (BATCH only).

SEQ SEQUENCE ERROR. VSAM reason code is 12 (BATCH only).

SID SYSTEM IDENTIFICATION ERROR. When a SID error occurs, the second and third bytes of the EIBRCODE are moved to the RECORD-LENGTH field. An explanation of EIBRCODE(s) can be found in the appendix of the CICS Application Programmers Reference Manual under the section “Exec Interface Block” (CICS only).

SLD SECURITY TABLE LOAD ERROR. The Security feature has been turned on, but the Security Module is not available to the program. The name of the Security Module is in the FILE-ID field (CICS only).

STG OUT OF STORAGE. VSAM is out of storage space.

Code Explanation



Program Examples

Example 1: Online Command Level COBOL Program

The CONTROL-BLOCK and RECORD-AREA are defined in Working Storage. The length of the CONTROL-BLOCK must precede the CONTROL-BLOCK and must be a two byte binary number containing the total length of all fields including RETURN-CODE through Key. For KSDS datasets, KEY must be long enough to hold a full key.

The following example uses a 10-byte key and a 200-byte record:

WORKING-STORAGE SECTION.

01 COMMUNICATION-AREA. 02 CONTROL-BLOCK-LENGTH PIC S9999 COMP VALUE +47. 02 CONTROL-BLOCK. 05 RETURN-CODE PIC XXX. 05 ACTION-CODE PIC XXX. 05 FILE-ID PIC X(8). 05 RECORD-LENGTH PIC S9999 COMP. 05 RESERVED PIC X(17). 05 KEY-POSITION PIC S9999 COMP. 05 KEY-LENGTH PIC S9999 COMP. 05 KEY PIC X(10). 02 RECORD-AREA PIC X(200). PROCEDURE DIVISION. MOVE LOW-VALUES TO RESERVED. MOVE 1 TO KEY-POSITION. (REQUIRED ONLY FOR MRO/REMOTE USERS) MOVE 'GET' TO ACTION-CODE. * SETTING RECORD-LENGTH = 0 RETURNS THE ENTIRE RECORD MOVE 0 TO RECORD-LENGTH MOVE '1234567890' TO KEY. EXEC CICS LINK PROGRAM('VNAT') COMMAREA(COMMUNICATION-AREA) LENGTH(249) END EXEC



Example 2: Online NATURAL Program (Single-File Access)

Online NATURAL program updating employee name, address, etc., using a 6-byte key and a 250-byte record.

*DEFINE THE CONTROL-BLOCK AND THE RECORD-AREA DEFINE DATA LOCAL 1 #CONTROL-BLOCK 2 #RETURN-CODE (A3) 2 #ACTION-CODE (A3) 2 #FILE-ID (A8) 2 #RECORD-LENGTH (B2) 2 #RESERVED (B17) 2 #KEY-POSITION (B2) 2 #KEY-LENGTH (B2) 2 #KEY (A6) 1 #RECORD-AREA 2 #EMPNO (A6) 2 #EMP-NAME (A30) 2 #EMP-ADR (A30) 2 #FILLER (A184) END-DEFINE ** RESET #RESERVED /*SET TO BINARY ZEROS RESET #RECORD-LENGTH /*SET TO BINARY ZEROS MOVE 'EMPFILE ' TO #FILE-ID /*SET FCT NAME OF FILE * REPEAT PERFORM INPUT-SCREEN1 /*INPUT EMPLOYEE NUMBER IF #X = 'END' /*DO YOU WANT TO QUIT? ESCAPE /*YES, QUIT MOVE #EMPNO TO #KEY /*MOVE EMPLOYEE NO. TO KEY MOVE 'GEQ` TO #ACTION-CODE /*SET ACTION-CODE TO GET RECORD CALL 'VNAT' #RETURN-CODE #EMPNO /*CALL VNAT TO GET RECORD IF #RETURN-CODE NE '000' /*IS REQUEST UNSUCCESSFUL? PERFORM ERR-CHECK /*YES, SHOW ERROR TO USER PERFORM CHANGE-EMP-DATA /*PERFORM CHANGE RECORD ROUTINE MOVE 'RPL' TO #ACTION-CODE /*SET ACTION-CODE TO REPLACE CALL 'VNAT' #RETURN-CODE #EMPNO /*CALL VNAT TO EXECUTE REPLACE IF #RETURN-CODE NE '000' /*IS REPLACE UNSUCCESSFUL? PERFORM ERR-CHECK /*YES, SHOW ERROR TO USER LOOP /*LOOP ........... END



Example 3: Online NATURAL Program (Multiple-File Access)

The following example is an online NATURAL program updating a payroll file for each record in an employee file:

*DEFINE THE CONTROL-BLOCK AND THE RECORD-AREA DEFINE DATA LOCAL 1 #CONTROL-BLOCK 2 #RETURN-CODE (A3) 2 #ACTION-CODE (A3) 2 #FILE-ID (A8) 2 #RECORD-LENGTH (B2) 2 #RESERVED (B17) 2 #KEY-POSITION (B2) 2 #KEY-LENGTH (B2) 2 #KEY (A9) 1 #EMPLOYEE-RECORD-AREA /*EMPLOYEE RECORD - 221 BYTES 2 #EMP-NO (A6) /*KEY 2 #EMP-NAME (A30) 2 #EMP-ADR (A30) 2 #EMP-CITY (A30) 2 #EMP-STATE (A2) 2 #EMP-ZIP (A9) 2 #END-#SSNO (A9) 2 #FILLER-1 (A105) 1 #PAYROLL-RECORD-AREA /*PAYROLL RECORD - 466 BYTES 2 #PAY-SSNO (A9) /*KEY 2 #PAY-NAME (A30) 2 #PAY-ADR (A30) 2 #PAY-CITY (A30) 2 #PAY-STATE (A2) 2 #PAY-ZIP (A9) 2 #FILLER-2 (A200) 2 #FILLER-3 (A156) END-DEFINE ** RESET #RESERVED #KEY-LENGTH /*SET TO BINARY ZEROS MOVE H'00' TO #EMP-NO /*START AT BEGINNING OF FILE * REPEAT MOVE 'EMPFILE ' TO #FILE-ID /*SET FILE-ID TO EMPLOYEE FILE MOVE #EMPNO TO #KEY /*MOVE EMPLOYEE NO. TO KEY MOVE 'NXT` TO #ACTION-CODE /*GET EMPLOYEE RECORD CALL 'VNAT' #RETURN-CODE #EMPNO /*GET EMPLOYEE RECORD IF #RETURN-CODE EQ 'EOF' ESCAPE /*END OF FILE-QUIT IF #RETURN-CODE NE '000' /*REQUEST UNSUCCESSFUL? PERFORM SHOW-EMP-RTNCODE /* YES, SHOW ERROR TO USER MOVE 'PAYROLL' TO #FILE-ID /*SET FILE-ID TO PAYROLL FILE MOVE #EMP-SSNO TO #KEY /*MOVE SSNO TO KEY MOVE 'GEQ` TO #ACTION-CODE /*GET PAYROLL RECORD CALL 'VNAT' #RETURN-CODE #PAY-SSNO /*GET PAYROLL RECORD IF #RETURN-CODE NE '000' /*REQUEST UNSUCCESSFUL? PERFORM SHOW-GET-RTNCODE /* YES, SHOW ERROR TO USER PERFORM CHANGE-PAYROLL /*SHOW & CHANGE PAYROLL RECORD MOVE 'RPL` TO #ACTION-CODE /*REPLACE PAYROLL RECORD CALL 'VNAT' #RETURN-CODE #PAY-SSNO /*REPLACE PAYROLL RECORD IF #RETURN-CODE NE '000' /*REQUEST UNSUCCESSFUL? PERFORM SHOW-RPL-RTNCODE /*YES, SHOW ERROR TO USER LOOP /*LOOP ...END



Example 4: Online Assembler Program

In an online assembler program, it is necessary only to set up an area of storage that contains

• A half-word length field containing 47 (the length of the CONTROL-BLOCK).

• The DATAMINER/VE CONTROL-BLOCK.

• A field into which the record key is placed by your program (for a write operation) or by DATAMINER/VE (for a read operation). The key field can be any length, provided it is at least as long as the key of your dataset. If you are using the CONTROL-BLOCK to access several datasets, make the key field as long as the longest key used by any of those datasets.

• An area of storage into which a record is to be read or from which a record is to be written. This must be at least as long as the longest record in your dataset.

The entire storage block is treated as a single parameter by DATAMINER/VE.

In the following example, it is the program’s responsibility to ensure that the record area is long enough to receive any record that will be read; otherwise, a storage overlay may occur.

Note 1 All the fields must be contiguous although you can start the RECORD field on, for example, a double-word boundary. This may result in slack bytes between the key field and the RECORD field. The first MVC in the example below adds those slack bytes to the end of the key field, which causes no problems.

Note 2 Previous versions of DATAMINER/VE required using the CICS TWA. Because IBM discourages the use of the TWA, it is better to set up the parameter list and pass it as a COMMAREA. DATAMINER/VE still supports user programs that use the TWA method.



CTLLEN DS H LENGTH OF CONTROL BLOCK CONTROL DS 0H START OF CONTROL BLOCK RETURN DS CL3 RETURN CODE FROM DATAMINER/VE ACTION DS CL3 ACTION FOR VSMA/EASY TO PERFORM FILEID DS CL8 FCT FILENAME LENGTH DS BL2 RECORD LENGTH RESERVE DS XL17 "RESERVED AREA" – DO NOT TOUCH!!! KEYPOS DS AL2 KEY POSITION (PROVIDED BY DATAMINER/VE) KEYLEN DS AL2 KEY LENGTH (PROVIDED BY DATAMINER/VE) KEY DS CL10 IF THE KEY IS 10 BYTES LONG DS 0D ALIGN RECORD (OPTIONAL – SEE NOTE ABOVE) RECORD DS CL500 IF THE MAXIMUM LRECL IS 500 BYTES CMLEN EQU *-CTLLEN MVC CTLLEN,=AL2(RECORD-CONTROL)SET CONTROL BLOCK LENGTH MVC ACTION,C'GEQ' WHAT WE WANT DATAMINER/VE TO DO MVC FILEID,=CL8'ACCTS'FILENAME TO READ * DATAMINER/VE WILL FILL IN "LENGTH" * LEAVE THE RESERVE AREA ALONE * DATAMINER/VE WILL FILL IN KEYPOS & KEYLEN * NEED TO SET THE KEY FOR KEYED READS AND WRITES. NOT NEEDED * FOR BROWSING (E.G. NXT, PRV, FST, LST) MVC KEY,ACCTNO SET KEY WE WANT EXEC CICS LINK PROGRAM('VNAT') CALL DATAMINER/VE COMMAREA(CTLLEN)COMMUNICATION AREA LENGTH(CMLEN) LENGTH OF COMMAREA RESP(CICSRESP) CICS'S RESPONSE TO THE LINK CLC RETURN,=C'000' EVERYTHING OK? BNE CHKCOND NO – SEE WHAT HAPPENED * PROCESS THE RECORD



Example 5: Batch NATURAL Program

The following example is a batch NATURAL program printing a report of year-to-date information for all type-2 employees on the payroll file. Notice that the keys (SSNO) are the same in both datasets.

*DEFINE THE CONTROL-BLOCK AND THE RECORD-AREA DEFINE DATA LOCAL 1 #CONTROL-BLOCK 2 #RETURN-CODE (A3) 2 #ACTION-CODE (A3) 2 #FILE-ID (A8) 2 #RECORD-LENGTH (B2) 2 #RESERVED (B17) 2 #KEY-POSITION (B2) 2 #KEY-LENGTH (B2) 2 #KEY (A9) 1 #PAYROLL-RECORD-AREA /*PAYROLL RECORD - 467 BYTES 2 #PAY-SSNO (A9) /*KEY 2 #PAY-NAME (A30) 2 #PAY-ADR (A30) 2 #PAY-TYPE (N1) 2 #FILLER-2 (A21) 2 #PAY-YTD (P7.2) 2 #FILLER-1 (A200) 2 #FILLER-2 (A171) 1 #RETIREMENT-RECORD-AREA /*RETIREMENT RECORD - 79 BYTES 2 #RET-SSNO (A9) /*KEY 2 #FILLER-3 (A30) 2 #RET-YTD (P7.2) 2 #FILLER-4 (A35) END-DEFINE * RESET #RESERVED #KEY-LENGTH /*SET TO BINARY ZEROS MOVE H'00' TO #KEY /*START AT BEGINNING OF FILE * REPEAT MOVE 'PAYROLL' TO #FILE-ID /*SET FILE-ID TO PAYROLL FILE MOVE 'NXT` TO #ACTION-CODE /*GET EACH PAYROLL RECORD CALL 'VNATB' #RETURN-CODE #PAY-SSNO /*GET EACH PAYROLL RECORD IF #RETURN-CODE EQ 'EOF' ESCAPE /*END OF FILE- QUIT IF #RETURN-CODE NE '000' /*REQUEST UNSUCCESSFUL? PERFORM PAY-GET-ABEND /*YES, PERFORM ERROR ROUTINE IF #PAY-TYPE NE 2 ESCAPE TOP /*SKIP RCD MOVE 'RETFILE' TO #FILE-ID /*SET FILE-ID TO RETIREMENT FILE MOVE 'GEQ` TO #ACTION-CODE /*GET MATCHING RETIREMENT RECORD CALL 'VNATB' #RETURN-CODE #RET#SSNO /*GET MATCHING RETIREMENT RECORD IF #RETURN-CODE NE '000' /*REQUEST UNSUCCESSFUL? PERFORM RET-GET-ABEND /* YES, PERFORM ERROR ROUTINE PERFORM WRITE-REPORT /*WRITE YTD REPORT LOOP /*LOOP ........... END



Example 6: Dynamic Call to VNATB

You can link to module VNATB either statically or dynamically. It makes little difference which you choose because VNATB’s sole job is to link dynamically to VNATB2, and VNATB2 is the module that does the vast majority of the work in DATAMINER/VE. VNATB’s function is to provide a way for new releases of DATAMINER/VE to be installed without requiring any application programs to be re-compiled or re-linked.

The following example is a dynamic call of program VNATB using a 10-byte key and a 200-byte record.

Note This type of call does not require a re-link of the COBOL program on installation of a new VNATB module.

Example 7: Static Call to VNATB

You can link to module VNATB either statically or dynamically. It makes little difference which you choose because VNATB’s sole job is to link dynamically to VNATB2, and VNATB2 is the module that does the vast majority of the work in DATAMINER/VE. In fact, VNATB’s only function is to provide a way for new releases of DATAMINER/VE to be installed without requiring any application programs to be re-compiled or re-linked.

The following example is a static call for program VNATB using a 10-byte key and a 200-byte record. This type of call requires a re-link of the COBOL program on installation of a new VNATB module, and so it is not recommended.

WORKING-STORAGE SECTION. 77 VNATB PIC X(8) VALUE 'VNATB'. 01 CONTROL-BLOCK. 02 RETURN-CODE PIC XXX. 02 ACTION-CODE PIC XXX. 02 FILE-ID PIC X(8) VALUE 'FILE1'. 02 RECORD-LENGTH PIC S9999 COMP. 02 RESERVED-AREA PIC X(10) VALUE LOW-VALUE. 02 PASSWORD-LG PIC X VALUE LOW-VALUE. 02 PASSWORD PIC X(8). 02 KEY-LENGTH PIC S9999 COMP VALUE ZERO. 02 KEY PIC X(10). 01 RECORD-AREA. 02 FILLER PIC X(200). PROCEDURE DIVISION. MOVE 'GET' TO ACTION-CODE. * SETTING RECORD-LENGTH = 0 RETURN THE ENTIRE RECORD MOVE 0 TO RECORD LENGTH MOVE '1234567890' TO KEY. CALL VNATB USING CONTROL-BLOCK, RECORD-AREA.



Example 8: Batch Assembler Program

The following example uses a 10-byte key and a 400-byte record:

/* Define the following to working storage /* in the Assembler program. READER CSECT CTLBLK EQU * RETURN DS CL3 ACTION DS CL3 FILEID DS CL8 LENGTH DC BL2'00' RESERVE DC XL10'00' PASS#LG DC XL1'00' PASSWORD DS CL8 KEY#LG DC BL2'00' KEY DS CL10 RECORD DS CL400 /* Fill necessary fields in the Control-Block. LINK EP=VNATB,PARAM=(CTLBLK,RECORD),VL=1

WORKING-STORAGE SECTION. 01 CONTROL-BLOCK. 02 RETURN-CODE PIC XXX. 02 ACTION-CODE PIC XXX. 02 FILE-ID PIC X(8) VALUE 'FILE1'. 02 RECORD-LENGTH PIC S9999 COMP. 02 RESERVED-AREA PIC X(10) VALUE LOW-VALUE. 02 PASSWORD-LG PIC X VALUE LOW-VALUE. 02 PASSWORD PIC X(8). 02 KEY-LENGTH PIC S9999 COMP VALUE ZERO. 02 KEY PIC X(10). 01 RECORD-AREA. 02 FILLER PIC X(200). PROCEDURE DIVISION. MOVE 'GET' TO ACTION-CODE. * SETTING RECORD-LENGTH = 0 RETURN THE ENTIRE RECORD MOVE 0 TO RECORD LENGTH MOVE '1234567890' TO KEY. CALL 'VNATB' USING CONTROL-BLOCK, RECORD-AREA.



DATAMINER/VE Installation

Introduction DATAMINER/VE is installed as part of DATAMINER. It consists of a number of load modules, a module that can be relocated, and some source examples.

Note Refer to the DataMiner Installation Notes for detailed installation instructions (www.csi-international.com).

Load Library Modules

The Load Library Modules are:

Source Library Module

The Source Library Module is:

VNAT CICS VSAM interface module

VNATB Batch VSAM interface stub

VNATB2 Batch VSAM interface module

VNATCTL DATAMINER/VE control table (mainly for future development)

VSCTYTBL Sample Online Security Table



DATAMINER/VE Online Security

Introduction CICS security for DATAMINER/VE is provided by VSCTYTBL. This module contains the security table used when the security option is enabled in the CICS I/O Module (VNAT).

Installation of the Security Module is not required. The module is made available to the user in the event that the user has no other means of securing VSAM datasets, and wants to secure VSAM datasets from unauthorized or improper access by DATAMINER/VE users under CICS control.

Security Table The security table contains entries identifying the VSAM datasets to be secured, the user IDs of the individuals authorized to access the VSAM datasets and the type of access allowed. Source code is supplied, ready to be assembled, and linked.

Installed Modes Security checking may be installed in either of two ways:

• Inclusive security

• Exclusive security

In either mode, security checking is performed on all datasets specified in the security table. The difference between the two modes is in the manner in which datasets not specified in the security table are handled.

Inclusive Security Mode

In the inclusive security mode, security checking is performed only on datasets specified in the security table. Access to datasets not specified in the security table is allowed without performing any security checks. There is no limit to the number of dataset entries. This is the default mode for installation of security, so no special installation steps are required.

Exclusive Security Mode

In the exclusive security mode, as in the inclusive mode, security checking is performed only on datasets specified in the security table. The difference is that access to datasets not specified in the security table is not allowed. In order to install the exclusive security mode, VNAT must be altered to disallow access to datasets not in the security table.

Security Check Methodology

The security check methodology is as follows:

1. Any number of user checks can be associated with a filename in the security table. A user check comprises a three-character operator-ID and a one-character security code. The three-character operator-ID is the same as the CICS Operator-ID. The security code may either be I for Inquiry Only or U for Inquiry and Update.

2. Each time a file is accessed, the filename specified is checked against the security table. If the requested filename is not found, no security checking is performed, and access to the dataset is either allowed or



disallowed depending on whether exclusive or inclusive security mode has been installed. If the filename is found in the security table, the CICS operator-ID from the TCTTEOI module is checked against all of the operator-IDs in that line of the security table. If a matching operator-ID is found and the security code of the user is a U, all operations are allowed. If the security code of the user is an I, only inquiry operations are allowed. Operator-ID checking continues until x'FF' or the end of the filename entry is encountered.

3. If a matching operator-ID is not located or the type of operation requested is not allowed, a return code of SCY is returned to the user in the Return-Code field, and the operation is suppressed.

4. If exclusive security mode has been installed and a dataset has been requested that is not in the security table, the operation is suppressed and a security error message is returned to the user.

Adding or Changing Security Entries

To add or change security entries:

1. Alter the security module (VSCTYTBL) source code as follows:

a. Change NOFILES (number of datasets) to be at least as large as the number of datasets for which the installation requires security checking.

b. Change NOCKS (number of user checks) to be at least as large as the number of user Operator-ID checks that are required per dataset.

c. Add a dataset entry for each dataset that requires security checking. Each dataset entry starts with a File-ID (CL8) followed by one to NOCKS data entries (CL4) with the remaining positions filled with X'FF' characters. There is no limit to the number of dataset entries, but they must be entered between USERDTA and TBLEND in the program.

d. Add user Operator-IDs and security codes (I=inquiry only and U=inquiry and update) for each user allowed access to the dataset in this dataset entry.

e. If security is desired, patch an I (X'C9') into location X'47' of VNAT for inclusive mode or an E (X'C5') into location X'47' of VNAT for exclusive mode. Either patch enables security checking and causes VNAT to load.

2. Assemble and link program VSCTYTBL.

3. Enter program VSCTYTBL into the CICS PPT or RDO.



Security Module Source

The following is the source of the Assembler module supplied to perform CICS security checking for the program VNAT.

VSCTYTBL CSECT , *------------------------------------------------------------------** SECURITY TABLE VSCTYTBL(3.7A) *------------------------------------------------------------------** * EACH FILE ENTRY NEEDS X'FF' FILL AND STARTS WITH A FILENAME(CL8) * FOLLOWED BY 1 TO (NOCKS) DATA ENTRIES(CL4). * * EACH DATA ENTRY IS A CICS OPER-ID(CL3) AND A SCTY-CODE(CL1). * * THE SCTY-CODE IS AN 'I' FOR INQUIRY ONLY OR A 'U' FOR INQUIRY AND * UPDATE. THIS ALLOWS SECURITY CHECKS FOR UP TO (NOCKS) USERS PER * FILE. * * THERE IS NO LIMIT TO THE NUMBER OF FILE ENTRIES, BUT THEY MUST BE * ENTERED BETWEEN (USERDTA) AND (TBLEND),AND MUST BE X'FF' FILLED. * NO X'FF' FILENMS CAN INTERVIENE. * * IF THE REQUESTED FILENM IS NOT IN THE TABLE, NO SECURITY CHECK IS * MADE. IF THE FILENM IS IN THE TABLE,THE CICS OPER-ID IS CHECKED * AGAINST ALL THE OPER-ID ENTRIES IN THAT FILE ENTRY UNTIL X'FF' * OR END OF ENTRY. IF THE OP-ID IS NOT IN THE TBL OR THE TYPE * OF OPERATION REQUESTED IS NOT ALLOWED, A RETURN-CODE OF 'SCY' IS * RETURNED AND THE OPERATION IS SUPPRESED.* *------------------------------------------------------------------** EQUATES *------------------------------------------------------------------** (NOFILES) AND (NOCKS) MAY BE ALTERED TO SUIT NOFILES EQU 10 MAX. NO. OF FILES IN TBL NOCKS EQU 50 MAX. NO. OF USER CHECKS PER FILE LINELG EQU (8+(NOCKS*4)) LG. OF ONE FILE LINE TBLLG EQU NOFILES*LINELG LG OF TABLE LNLG DC A(LINELG) KEEP FIRST-USED BY LOADER PROGRAM *------------------------------------------------------------------** SECURITY TABLE DEFINITION *------------------------------------------------------------------*SCTYTBL DC (TBLLG)X'FF' SECURITY TABLE INITIAL FILL ORG SCTYTBL POINT TO TABLE BEGIN FILELIN DS 0CL(LINELG) FILE LINE - ONE FOR EACH FILE FILENAME DS CL8 FILE NAME (AS IN FCT) SCTYDTA DS (NOCKS)CL4 INFO FOR 1 TO (NOCKS) PER FILE LINEEND EQU * ORG SCTYDTA REDEFINE SECURITY CHECKS OPERID DS CL3 CICS OPERATOR-ID SCTYCD DS CL1 SECURITY-CODE * - I = INQUIRY ONLY * - U = UPDATEORG SCTYTBL REDEFINE FOR ACTUAL DATA



*------------------------------------------------------------------** START OF USER DATA AREA *------------------------------------------------------------------** '1...5...10...15...20...25...' *EXAMPLE: 'FILENAM ID ID ID ID ID ' * ¦ ¦ C C¦ C¦ C¦ C * ¦ ¦ O O¦ O¦ O¦ O * ¦ ¦ D D¦ D¦ D¦ D * ¦ ¦ E E¦ E¦ E¦ E * ¦ ¦ ¦ ¦¦ ¦¦ ¦¦ ¦ * V V V VV VV VV V *FILE1 DC C'FILE1 AAAIBBBUCCCIDDDIEEEU' * '1...5...10...15...20...25...' * ORG FILE1+LINELG POINT TO NEXT ENTRY *FILE2 DC C'FILE2 BBBIEEEIFFFU' * ORG FILE2+LINELG POINT TO NEXT ENTRY USERDTA EQU * *------------------------------------------------------------------** END OF USER DATA AREA *------------------------------------------------------------------* ORG , CONTINUE TBLEND DC 8X'FF' END OF TABLE INDICATOR - KEEP LAST *------------------------------------------------------------------** THE FOLLOWING ORG MUST COME UP WITH A VALUE OF ZERO. * A NON-ZERO VALUE MEANS THAT THERE IS TOO MUCH USER DATA * AND THE (NOFILES) OR (NOCKS) EQUATES WILL HAVE TO BE ENLARGED. * A NON-ZERO VALUE WILL CAUSE AN ASSEMBLY ERROR. *------------------------------------------------------------------*ERRCKR ORG LNLG+((TBLLG+8)-(*-SCTYTBL)) ORG , CONTINUE *------------------------------------------------------------------* DC C'VSCTYTBL(3.7A)',CL9'&SYSDATE',CL9'&SYSTIME' *------------------------------------------------------------------* END



DATAMINER/VE Control Table

Introduction DATAMINER/VE uses a control table to allow you to modify some of its default settings. More entries are likely to be added to the table in the future. The following example is what the table looks like at present. You can change any or all of the entries, but keep in mind that the table is available system wide. The best place for it to reside is in the LPA. It uses very little memory.

To modify the control table, make the changes you want and then re-assemble and link it.

Control Table The following is the source for the control table:

* VSAM-EASY CONTROL TABLE. * THIS TABLE CONTAINS SITE-DEFINABLE DEFAULTS FOR VSAM-EASY * ITS LAYOUT MUST NOT BE CHANGED BUT THE CONTENTS OF INDIVIDUAL * FIELDS MAY BE. * VNATCTL CSECT * * MXF * === * MAXIMUM NUMBER OF FILES THAT A PROGRAM CAN USE SIMULTANEOUSLY. DEFAULT IS * 45. YOU CAN SPECIFY ANY NUMBER FROM 1 - 32767. VSAM-EASY * REQUIRES ROUGHLY 40 BYTES TIMES THE NUMBER YOU SPECIFY HERE * OF GETMAIN, EVEN IF YOU DO NOT ACTUALLY USE THAT MANY FILES. * SPECIFYING A NUMBER MUCH GREATER THAN YOU NEED WILL NOT HAVE A * MAJOR EFFECT ON PERFORMANCE OTHER THAN A ONE-TIME CLEARING OF * THE AREA TO X'00'. SPECIFYING A NUMBER SMALLER THAN THE * NUMBER YOU NEED WILL LEAD TO SOME IO OPERATIONS BEING REJECTED * BY VSAM-EASY SO IT IS BETTER TO SET THIS NUMBER TOO HIGH THAN * TO SET IT TOO LOW. MXF DC H'45' DEFAULT VALUE * * EMPTY * ===== * DEFAULT RETURN CODE FOR A PROGRAM TRYING TO READ FROM * AN EMPTY ESDS. 'NOP' IS THE SUPPLIED DEFAULT FOR * COMPATIBILITY WITH EARLIER VERSIONS OF VSAM-EASY. * YOU MAY PREFER "EOF" WHICH WILL TELL VSAM-EASY TO SIGNAL * IMMEDIATE END OF FILE TO THE CALLER IF HE TRIES TO READ * FROM AN EMPTY ESDS EMPTY DC CL3'NOP' DEFAULT VALUE



20
DATAMINER/VE Support
This chapter contains programming and troubleshooting information for DATAMINER/VE.


Page

DataMiner/VE Programming Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.2Troubleshooting DataMiner/VE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.6VSAM Basics for DataMiner/VE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.9

DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE Support

DATAMINER/VE Programming Tips

CICS Pseudo Conversational EOT with NATURAL

An END OF TRANSACTION occurs whenever a NATURAL program displays data on the user's screen. This causes the termination of any active browse, the release of any held records, and the release of any used strings. This does not mean that browse positioning (NXT/PRV) is lost since VNAT maintains positioning information on up to 45 datasets and automatically restarts the browse at the proper location in the dataset.

Avoiding Lockouts A user can be locked out of accessing a dataset or a record for the following reasons:

STRINGS CICS and COM-PLETE define STRINGS, which controls the number of concurrent accesses to a dataset. If a string is not available, the program waits. If a string never becomes available, the CICS task hangs until the stall interval expires and the task is terminated, or it never recovers. Be sure that the number of strings matches the usage of the dataset. See also “Exclusive Control.”

Exclusive Control

When a Control-Interval is being held in exclusive control by another user, it usually is not available for update. In CICS, the program waits. In batch, a return code of HLD is returned. GTU, GGU and GEU all hold Control-Intervals until an ADD, DEL, RPL, REL or a CICS end of transaction.

A REL command can be used to release any held strings or Control-Intervals. This is hardly ever necessary under CICS because everything is released when a transaction ends. COM-PLETE users should issue a REL before displaying a screen if a user reply is necessary before continuing.



File Sharing

Several factors influence the ability to share a VSAM dataset or Control-Interval. If you are receiving a NAV (not available) return code, look into the following:

Share options Check the dataset’s share options by running a LISTCAT. A full description of Share options is in the VSAM manual, but briefly the choices are

1. Any number of programs can have the dataset open for reading or one program can have it open for read/write at any time.

2. Any number of programs can have the dataset open for reading and one program can have it open for read/write at any time.

3. The dataset can be opened by any number of programs for both read and write. It is up to you to ensure dataset integrity.

4. The first program to open the dataset read/write is allowed read/write access but all others are restricted to read-only.

CSI-VSHARE provides an excellent way of allowing a dataset to be accessed simultaneously in read/write by multiple programs.

CICS open type

If the File Control Table for a dataset allows updates, CICS opens the dataset for output. This may affect its availability to non-CICS jobs. CICS datasets may need to be closed and disabled in order to update them outside CICS.

COM-PLETE open type

Like CICS, COM-PLETE has parameters that affect its open type.

Batch open type

If a batch program opens a VSAM dataset for output, it may affect its availability to other programs. VNATB opens a dataset for output only when an output type command is requested. (ADD, RPL, DEL, GTU).

JCL disposition

If a dataset is allocated with DISP=OLD, it may not be shareable.



Using CICS Temporary Storage for Scrolling

Record data can be quickly stored in temporary storage using the TSA command. It can then be quickly retrieved, a screen-full at a time, starting at the appropriate item number. This allows speedy forward and backward scrolling.

Accessing Multiple Files

VNAT and VNATB maintain information for up to 45 datasets. To change to another dataset, just change the information in the CONTROL-BLOCK. If you need to return to the same position in the current file, be sure to save the KEY and restore it later. The new RECORD-AREA can either be defined as a new area or redefined over the same area as the previously used definition. Be sure to define the largest record-area first if you are redefining records in the same area.

Alternate Indexes with Non-Unique Keys

When reading through an Alt-Index Path, a DPK is returned when the record retrieved is the first of a non-unique key group. To retrieve the rest of the group, switch to a NXT if you are not already using NXT. This allows you to browse through the group. A DPK is returned until the last record in the group is retrieved, and then the RETURN-CODE returns to 000.

CICS If a non-NXT command is issued or the current transaction ends, the browse is terminated. The next retrieval starts over at the beginning of the non-unique key group.

BATCH Non-unique records can be updated without losing position if the retrieval command was a NXT and the file is open as output; otherwise, an ILL (Illogic Request) is returned. An operator other than NXT, DEL, or RPL ends the browse, and the next retrieval starts over at the beginning of the non-unique group.

VNATB opens files as follows:

• If the first operation is an input operation, the file is opened as input.

• When an output operation is requested, the file is closed, if necessary, and opened as output.

If you anticipate updating records with duplicate keys, you must have first issued an output command such as GTU, ADD, RPL, or DEL before starting the browse. This forces the file to be opened for output. Then while browsing records with duplicate keys, a record can be deleted (DEL) or updated (RPL) without losing the position of the browse.



NATURAL Packed Fields in Keys

NATURAL handles packed/signed fields as follows:

• All negative packed fields in NATURAL carry a D in the right-most half byte of the packed field.

• All positive packed fields in NATURAL carry an F in the right-most half byte of the packed field.

• NATURAL recognizes both C and F as positive signs, but always changes the C to an F when the field is used as a packed field.

• VSAM/KSDS keys are alphanumeric not numeric.

• If a language such as COBOL or assembler is treating the key as a packed/signed field, the right-most half byte of the field could be 'C', 'D' or 'F'.

This last point is risky since the two records with the same numeric value could reside on the same file without being identified as having duplicate keys. For example: Packed '12345C' and '12345F' have the same numeric value, but have different alphanumeric values.

When you access a KSDS file with a packed key in a NATURAL program, you could use the following code if the key needs a 'C' in the sign:

RESET KEY(P5) REDEFINE KEY(KEY2(B2) SIGN(B1))

This redefines a 3-byte packed field into two binary fields.

After filling the key, but before accessing the file, execute the following instructions:

IF SIGN = H'0F', MOVE H'0C' TO SIGN IF SIGN = H'1F', MOVE H'1C' TO SIGN IF SIGN = H'2F', MOVE H'2C' TO SIGN

This example permits compatibility with other languages.

NATURAL Calls If the CONTROL-BLOCK or the RECORD-AREA have been defined with a group-level name as the first name, use the name of the first elementary field as the CALL parameters. For example

CALL "VNAT" #RETURN-CODE #RCD-FLD-1

NATURAL expands group items used in a CALL to include an address for each subordinate name. DATAMINER/VE uses the second address as the RECORD-AREA.



Troubleshooting DATAMINER/VE

Introduction The following are the most common reasons for DATAMINER/VE problems. If you have a problem with DATAMINER/VE that you cannot correct, please feel free to call us. Before you do, please check the following possibilities.

CONTROL-BLOCK Layout

Check the layout of the CONTROL-BLOCK in your program. Make sure that the compiler or assembler has not inserted any slack bytes for you. Be aware that the CICS and batch control blocks have different formats.

RESERVED-AREA Handling

This is the reason for nearly all problems encountered with DATAMINER/VE. The first thing to do in the event of an unexplained failure of DATAMINER/VE is to make sure that you are not changing the RESERVED-AREA. This area is reserved for use by DATAMINER/VE. It must be set to binary zeros at the start of the program and must never be altered between calls to DATAMINER/VE. If you inadvertently change this field, DATAMINER/VE can get very confused, and the result is often an “ILL” RETURN-CODE.

0V06I Message Programs using VSAM (with or without DATAMINER/VE) can cancel with a 0V06I message, usually either during start-up or during the close of a file. The VSAM messages manual tells you that the way to fix it is to re-IPL the system with a larger BUFSIZE parameter. While that is true, an easier way to fix the problem is to redefine the file with a larger data CISIZE and re-run the job. A minimum of a 4K CISIZE is recommended.

RETURN-CODE Checking

If you are not checking RETURN-CODEs, you may encounter an error and not detect it.

You should always check the RETURN-CODE after each call at least to the extent of checking for a successful completion (RETURN-CODE equals 000). This is always a good idea necause normal errors are trapped by DATAMINER/VE and are explained in the RETURN-CODE list in simple terms. There is no need to check for absolutely every possible return code—your program could check, say, for successful completion, for end of file, and regard anything else as an error worthy of an ABEND.

RECORD-AREA Size Specification

Check to make sure that you have specified enough space in your RECORD-AREA. The RECORD-AREA must be as large as the largest record that could be returned from a DATAMINER/VE call. If you do not have sufficient space allocated in this area, reading a longer record causes whatever follows your record area to be overlaid with record information. This can cause unpredictable results. This is also true for the KEY field.

S080A GETMAIN Failure Errors

These may occur after a variable number of successful DATAMINER/VE retrievals and/or updates when DATAMINER/VE tries unsuccessfully to perform a GETMAIN. The most common reason for this is that the RESERVED-AREA was changed between calls.



If you are using more than one CONTROL-BLOCK, check to make sure that you are using just one RESERVED-AREA. If you must use multiple CONTROL-BLOCKs for some reason, you must save the RESERVED-AREA after each call and move it into the CONTROL-BLOCK before each call. If you do not, DATAMINER/VE may generate unnecessary GETMAINs and ultimately fail.

Transaction Work Area Addressing

If you are using the TWA to pass the address of the parameter list, that address must be in the first four positions of the TWA. If you cannot put the address in the first four bytes of the TWA then you should set up your parameter list in the COMMAREA, which is the preferred location anyway.

CICS AEY9 ABEND or NATURAL 954 ABEND

The INQUIRE/SET commands cannot be set up in the CICS PPT in CICS 1.7 or greater. You can very quickly verify the availability of the INQUIRE command as follows:

1. Go to a blank screen CICS.

2. Execute the CECI utility.

3. Execute “INQUIRE dataset(fileid).”

4. If the transaction returns an AEY9 error, the INQUIRE command has not been enabled.

Check with your system administrator to enable these commands.

Differences Between VNAT and VNATB

A program using VNAT may not work exactly the same as a similar request using VNATB because of differences between the way that the two modules operate. VNAT is a CICS pseudo-conversational transaction that completely ends whenever input is requested from the screen. Therefore, care should be taken when transporting programs between CICS and any other TP Monitor.

NATURAL 920 Abend This means that NATURAL cannot find the VNAT or VNATB module. This is probably a STEPLIB problem.

Corrupted Code in your NATURAL 2.1 Program

Do not use group-level names in the call to VNAT or VNATB. NATURAL 2.1 will convert a group level to all its elementary level items in the Parm-list and cause code in your NATURAL program to be overwritten. Instead, use the first elementary-level item name of each group in your call.

Note If you have checked all of the above and still cannot get your DATAMINER/VE request to work, call CSI Technical Support. If possible, please print or display the RESERVED-AREA in the CONTROL-BLOCK before and after your VNAT or VNATB CALL.



Incorrect Installation of New Release of VNATB / VNATB2 with NATURAL

NATURAL has a phase control table that it maintains across IPLs. If you load a new version of VNATB and VNATB2, be sure to refresh this table.



VSAM Basics for DATAMINER/VE

Introduction This section provides an overview of basic VSAM concepts that are relevant to using DATAMINER/VE. This section is not a definitive reference guide, and users should refer to the appropriate VSAM documentation for further information.

File Types The VSAM access method provides both direct access to records in any order and sequential access to records that follow one another. VSAM provides support for online transactions and batch users. VSAM supports three types of dataset organizations including key-sequenced, entry-sequenced, and relative record. The main difference among these organizations are the sequences in which the records are loaded into the file.

Key Sequence Dataset (KSDS)

Records are loaded into a KSDS in key sequence. Each record has a unique value, such as a social security number, in the key field. VSAM uses an index that relates the key of a record with its physical location.

Entry Sequence Dataset (ESDS)

The records in an ESDS are stored in the order they are stored in time and without respect to the contents of the records. Each new record is stored after the last record in the file. ESDS records cannot be deleted, although they can be replaced with records of the same length. ESDS records are located through their relative byte address (RBA).

Relative Record Dataset (RRDS)

Records are loaded into an RRDS in relative record number sequence. An RRDS is essentially a string of fixed-length slots, each of which is identified by a relative record number that is supplied by the programmer when the record is added. RRDS records are accessed by their relative record number (RRN).

Reusable Dataset VSAM allows you to create reusable datasets that you can use as work files. To do this you can define the dataset as reusable and specify that it be reset when you open it. The REUSE parameter allows you to treat a filled dataset as if it were empty and load it again and again, regardless of its previous contents. The dataset can be a KSDS, an ESDS, or an RRDS.

Record Retrieval VSAM record storage and retrieval is managed through Control-Intervals. A Control-Interval (CI) is a continuous area of direct access storage that VSAM uses to store data records and control information that describes the records. Whenever a record is retrieved from direct access storage, the entire Control-Interval containing the requested record is read into virtual storage.

The Control-Intervals in a VSAM dataset are grouped together into fixed-length contiguous areas of direct access storage called Control Areas. (CAs). A VSAM dataset is composed of one or more Control Areas. The number of Control-intervals in a Control Area is fixed by VSAM.



VSAM allows both sequential and direct access for each of its three types of datasets. Sequential access of a record depends on the position, with respect to the key, the relative byte address of the previously processed record, or the relative record number; direct access does not. With direct processing records are retrieved by the search argument (key or relative record number) that you supply.

VSAM records can be retrieved sequentially from the beginning of a dataset or from any specified record in the dataset. Records can be browsed (that is, read sequentially) forward or backward.

During skip sequential processing, you can retrieve a group of records sequentially, and then skip to a different part of the dataset and process another group of records sequentially. The entire dataset does not have to be read sequentially to process a relatively small percentage of the total number of records.

A VSAM record can be retrieved a number of ways, based on the dataset's organization (KSDS, ESDS, or RRDS).

KSDS (Keyed Sequence Dataset)

A record can be retrieved by its primary key, which is a unique alphanumeric value in a predefined field within the record. The employee number in a payroll file could be a primary key. The key specified can be a full key (the exact alphanumeric key as defined in the VSAM catalog) or a generic key (a partial key with the high-order portion of the key containing characters that are significant for a particular application).

An alternate index provides a way to access KSDS records by more than one key field. An alternate index is a collection of index entries organized by the alternate keys of its associated base data records. These keys are made up of one or more consecutive characters taken from a data record.

The alternate key is a predefined field within the record that can be non-unique, as in the case of employee last name in a payroll file. When processing records through an alternate index, duplicate keys may be encountered.

ESDS (Entry Sequence Dataset)

A record in an ESDS dataset is accessed by its relative byte address (RBA). The RBA is a four-byte binary address that describes a record’s displacement, in bytes, from the beginning of the dataset (zero).

An alternate index provides a way to access ESDS records by more than one key field. An alternate index is a collection of index entries organized by the alternate keys of its associated base data records. These keys are made up of one or more consecutive characters taken from a data record.

An alternate key is a predefined field within the record that can be non-unique, as in the case of employee last name in a payroll file. When processing records through an alternate index, duplicate keys may be encountered.



RRDS (Relative Record Dataset)

RRDS records are accessed by their relative record number (RRN). Each record occupies a fixed-length slot and is stored and retrieved by the RRN of the slot. The RRN is a four byte binary relative record number from 1 to n, where n is the maximum number of records that can be stored on the dataset. The beginning RRN on a file has a value of 1.


Commands Index

Symbols@LBL, 8.11AABEND command, 14.2ADD command, 10.10ADVANCE command, 11.12AFTER OUTPUT timing command, 8.15arithmetic commands, 10.9–10.13

ADD, 10.10DIVIDE, 10.13MULTIPLY, 10.12SUBTRACT, 10.11

AUTO command, 2.2BEGIN, 2.3EOF, 2.3

BBEFORE INPUT timing command, 8.15BEGIN. See AUTO commandBREAK command, 11.14CCALL…[USING] command, 8.14CLOAK command, 10.8CLOSE command, 15.7COMMIT command, 15.8conditionals

DO WHILE and ENDDO statements, 8.6IF…[ELSE]…ENDIF statements, 8.3SELECT…[WHERE] command, 6.17

CONNECT command, 15.3COPY command, 6.3COPY shortcut command, 6.3

Ddata manipulation commands

ADD, 10.10arithmetic commands, 10.9–10.13CLOAK, 10.8DIVIDE, 10.13HIDE, 10.7MOVE, 10.4MULTIPLY, 10.12SET, 10.6SUBTRACT, 10.11

DATACARDs command, 3.12DB2 commands

CLOSE, 15.7COMMIT, 15.8CONNECT, 15.3EXECUTE, 15.6INPUT=, 15.4OUTPUT=, 15.5ROLLBACK, 15.9

DEFINE command, 5.3DELETE command, 6.14DELETE shortcut command, 6.14DIVIDE command, 10.13DO WHILE and ENDDO statements, 8.6DROP command, 9.9DUMP command, 6.12DUMP shortcut command, 6.12DURING INPUT timing command, 8.15DURING OUTPUT timing command, 8.15

Copyright © 2012 by CSI InternationalCommands Index.1

DATAMINER FOR Z/OS 7.1C User Reference Guide Commands Index

EEOF. See AUTO commandEXECUTE command, 15.6EXIT command, 8.13EXTRACT command, 6.6EXTRACT shortcut command, 6.6FFIND command

tablesFIND command, 12.14

FIRST= command, 9.4; 9.5FIRSTKEY command, 9.4flow control

@LBL, 8.11CALL…[USING] command, 8.14EXIT command, 8.13GOTO, 8.11labels, 8.11PERFORM command, 8.10PROC…[GOBACK]…ENDPROC statements,

8.8FREQ= command, 9.7GGAP command, 11.16GOTO statements, 8.11HHD command, 6.15HEADING command, 11.17HEIGHT command, 11.11HIDE command, 10.7IIF…[ELSE]…ENDIF statements, 8.3INPUT= command, 3.3INPUT= command (DB2), 15.4INSERT command, 7.12INSERT shortcut command, 7.12KKEEP command, 9.8Llabels, 8.11LABELS command, 11.18LAST= command, 9.6LENGTH command, 11.19LINE command, 11.20MMASK command, 11.7

MAXRCDS= command, 9.18MOVE command, 10.4MULTIPLY command, 10.12NNODATE command, 11.22NOPAGE command, 11.22OOFFSET= command, 2.11ONLY command, 9.16ORDER command, 11.23output commands

ABEND, 14.2HD, 6.15MAXRCDS=, 9.18OFFSET=, 2.11STATS, 2.13TOT, 6.15; 6.16; 6.20VALIDATE=, 2.14

OUTPUT= command, 3.7OUTPUT= command (DB2), 15.5PPERFORM command, 8.10POINT command, 7.5

examples, 7.8PRINT command, 6.8PRINT shortcut command, 6.8PRINTER command, 11.26PROC…[GOBACK]…ENDPROC statements, 8.8RREAD command, 7.3Report Writer commands

ADVANCE, 11.12BREAK, 11.14GAP, 11.16HEADING, 11.17HEIGHT, 11.11LABELS, 11.18LENGTH, 11.19LINE, 11.20MASK, 11.7NODATE, 11.22NOPAGE, 11.22ORDER, 11.23PRINTER, 11.26SUM, 11.13; 11.27; 11.28SUMMARY, 11.29



TITLE, 11.30WIDTH, 11.11

ROLLBACK command, 15.9SSELECT…[WHERE] command, 6.17SET command, 10.6shortcut commands

COPY, 6.3DELETE, 6.14DUMP, 6.12EXTRACT, 6.6INSERT, 7.12PRINT, 6.8UPDATE, 6.5; 6.5

SHOW command, 14.4SKIP command, 9.14SORT command, 13.2START command, 9.10STATS command, 2.13STOP command, 9.12SUBTRACT command, 10.11SUM command, 11.13; 11.27; 11.28

SUMMARY command, 11.29TTABLE command, 12.2tables

TABLE command, 12.2timing commands, 8.15–8.17

AFTER OUTPUT, 8.15BEFORE INPUT, 8.15DURING INPUT, 8.15DURING OUTPUT, 8.15

TITLE command, 11.30TOT command, 6.15; 6.16; 6.20TRACE command, 14.6UUPDATE command, 6.5UPDATE shortcut command, 6.5VVALIDATE= command, 2.14WWIDTH command, 11.11WRITE command, 7.6

examples, 7.8


General Index

Numerics954 Abend, 20.7

AABEND Command, 14.2Arithmetic Commands

accumulators, 10.9and IF commands, 10.9

AUTO command, 2.2AUTO mode, 2.4

specifying, 2.2

Bbrowsing, 19.26

CCANCEL Command, 14.3CICS

temporary storage keys, 18.10Commands

arithmetic commandsand IF commands, 10.9

Data Manipulation CommandsMOVE, 10.4SET field=literal, 10.6SET field1=field2, 10.6

DO WHILE and ENDDO, 8.6IF commands, 8.5; 8.11multi-field commands, 7.13

SELECT, 6.17WHERE, 6.18

output commandsABEND Command, 14.2CANCEL Command, 14.3HD Command, 6.15MAXRCDS Command, 9.18OFFSET= Command, 2.11TOT Command, 6.15; 6.16; 6.20VALIDATE Command, 2.14

POINT, 7.5READ, 7.3record selector commands

DROP, 9.9FIRST=, 9.5FIRSTKEY=, 9.4FREQ=, 9.7KEEP, 9.8LAST=, 9.6SKIP, 9.14START, 9.10STOP, 9.12

script commandsINPUT=, 3.3OUTPUT=, 3.7

sequence, 2.6effects of, 2.6

shortcut commands, 6.2COPY, 6.3DATACARDS, 3.12DELETE, 6.14DUMP, 6.12EXTRACT, 6.6

Copyright © 2012 by CSI InternationalGeneral Index.1

DATAMINER FOR Z/OS 7.1C User Reference Guide General Index

INSERT, 7.12PRINT, 6.8UPDATE, 6.5

SHOW, 14.4COMPLETE, 19.6; 19.27COPY Command, 6.3

DData Manipulation Commands

constraints, 10.2MOVE, 10.4SET field=literal, 10.6SET field1=field2, 10.6

DATACARDS Command, 3.12Data-Miner Online

access records, 18.4browsing files, 18.4browsing temporary storage queues, 18.4CICS Temporary Storage Queues, 18.2DATA-AREA, 18.10description, 18.2error messages, 18.11FILEID, 18.5KEY, 18.9LRECL, 18.6OPER, 18.6PF KEYS, 18.10RECORD NUMBER, 18.5REMOTE KEYPOS, 18.10sample screen, 18.5security, 18.2supported environments, 18.2THRU-KEY, 18.9

DELETE Command, 6.14DISPLAY Command, 7.14DO WHILE and ENDDO Commands, 8.6DUMP Command, 6.12DUMP command, 6.12DUMP shortcut command, 6.12

EESDS Keys, 18.10EXTRACT Command, 6.6

Ffields

work fields, 2.4File Reading

errors during, 7.4example, read randomly using POINT,

7.3example, read randomly using READ-

READ Commandexample, 7.4

File Reading, randomly, 7.3

GGeneral DMIN Messages, list of, 16.12

HHD Command, 6.15

IIF Commands

example, 8.5statement labels, 8.11using with list of values, 8.5

INPUT Command ParametersBLKSIZE=, 3.5; 3.9

INPUT= Commanddescription, 3.3parameters

FIXED, 3.6; 3.10REUSE, 3.10UNDEF or UNDEFINED, 3.6; 3.10VARBLK, 3.6; 3.10

INSERT Command, 7.12IO-RESULT, 1.4; 7.4

KKEY, 18.9KSDS Keys, 18.9

LLiterals

binary, 5.17character, 5.15hexadecimal, 5.16numeric, 5.17packed decimal, 5.15zoned decimal, 5.16

literals



using quotation marks, 5.15using quotes, 5.15

Mmain input dataset, defined, 2.2main output dataset, defined, 2.2MAXRCDS Command, 9.18MOVE Commands, 10.4MRO, 18.10Multi-Field Commands

example, 7.13SELECT, 6.17WHERE, 6.18

NNATURAL, 19.30new NXT, defined, 19.20new PRV, defined, 19.20Nonunique records, 20.4

OOFFSET= Command, 2.11OUTPUT Command Parameters

BLKSIZE=, 3.5; 3.9Output Commands

ABEND Command, 14.2CANCEL Command, 14.3HD Command, 6.15MAXRCDS Command, 9.18OFFSET= Command, 2.11TOT Command, 6.15; 6.16; 6.20VALIDATE Command, 2.14

OUTPUT= Commanddescription, 3.7parameters

FIXED=, 3.6; 3.10REUSE, 3.10UNDEF or UNDEFINED, 3.6; 3.10VARBLK=, 3.6; 3.10

PPOINT Command, 7.5

example, 7.3; 7.8PRINT Command, 6.8

RREAD Command, 7.3

example, 7.8Record Fields

example, create, 4.7Record Selector Commands

DROP, 9.9execution order, 9.2FIRST=, 9.5FIRSTKEY=, 9.4FREQ=, 9.7KEEP, 9.8LAST=, 9.6ONLY, 9.16rules, 9.3SKIP, 9.14SKIP, special note, 9.14START, 9.10STOP, 9.12

REMOTE KEYPOS, 18.10report, 6.8Report Writer

Additional REPORT CommandsACROSS, WIDTH, HEIIGHT, 11.11ADVANCE, 11.12BREAK, 11.14GAP, 11.16HEADING, 11.17LABELS, 11.18LENGTH nnn, 11.19LINE, 11.20NODATE and NOPAGE, 11.22ORDER, 11.23PRINTER, 11.26SUM, 11.13; 11.27; 11.28SUMMARY, 11.29TITLE, 11.30

column heading, 11.6description, 11.2example

create tabular report, 6.9tabular report output, 6.10

field definition, 11.3; 11.6REPORT Command

example, 11.5; 11.8RRDS Keys, 18.9



SScript Commands

INPUT=, 3.3OUTPUT=, 3.7POINT, 7.5READ, 7.3

script readabilitywords that are always ignored, 2.8

SELECT Command, 6.17SET Command

field=literal, 10.6field1=field2, 10.6

Shortcut Commandsconstraints, 6.2COPY, 6.3DATACARDS, 3.12DELETE, 6.14DUMP, 6.12EXTRACT, 6.6INSERT, 7.12PRINT, 6.8SHOW, 14.4UPDATE, 6.5

shortcut commandsDUMP, 6.12

SHOW Command, 14.4SHOW Fieldname Command

example, 14.4SHOW File Command

example, 14.4skip sequential processing, 19.16; 19.26Statement Labels

and IF command, 8.11System Work Fields

example, 5.12FIRST_RECORD, 5.13INPUT_RECORD, 5.13LAST_RECORD, 5.13MAX_RECORDS, 5.13OUTPUT_RECORD, 5.13RETURN_CODE, 5.13system constants, 5.18T0-T9, 5.14VALIDATION_ERRORS, 5.14

TT0 through T9, 10.9TABLE Command

example, data from file, 12.3example, data in script, 12.3filling a table, 12.2

temporary storageonline commands, 18.6

Temporary Storage Queue, 18.9Temporary Storage Queues, 18.2THRU KEY, 18.9TOT Command, 6.15; 6.16; 6.20

UUPDATE, 2.5UPDATE Command, 6.5

VVALIDATE Command, 2.14VSAM/Easy

batch application access, 19.7Batch Assembler example, 19.12CICS access, 19.7CICS users, 19.10COBOL example, 19.12COM-PLETE users, 19.10control table source, 19.48environments, 19.8general access, 19.7Installation

library modules, 19.43NATURAL example, 19.12online security

adding or changing security entries, 19.45

exclusive, 19.44inclusive, 19.44installed modes, 19.44methodology, 19.44security table, 19.44

RECORDAREA and CON-TROL-BLOCK, 19.9

return codes, 19.9sequence, 19.9system requirements, 19.10temporary storage, 19.13



VSAM/EASY Batch CONTROL-BLOCKACTION-CODE, 19.24Assembler example, 19.23COBOL example, 19.23FILE-ID, 19.28KEY, 19.29KEY-LENGTH, 19.29PASSWORD, 19.29PASSWORD-LENGTH, 19.29RECORD-LENGTH, 19.28RESERVED-AREA, 19.29RETURN-CODE, 19.23

VSAM/EASY Batch RECORD-AREA, 19.30VSAM/Easy CICS CONTROL-BLOCK

ACTION-CODE, 19.15Assembler example, 19.14COBOL example, 19.14FILE-ID, 19.18KEY, 19.21KEY-LENGTH, 19.20KEY-POSITION, 19.20

RECORD-LENGTH, 19.19RESERVED-AREA, 19.20RETURN-CODE, 19.14

VSAM/Easy CICS RECORD-AREA, 19.22VSAM/Easy Examples of Use

Batch Assembler Program, 19.42Batch NATURAL Program, 19.40Dynamic Call to VNATB, 19.41Online Assembler Program, 19.38Online Command Level COBOL Pro-

gram, 19.35Online NATURAL Program (Multiple

File Access), 19.37Online NATURAL Program (Single File

Access), 19.36Static Call to VNATB, 19.41

WWHERE Command, 6.18work fields, 2.4WRITE Command

example, 7.8


· 10/8/2012 · DATAMINER FOR Z/OS Comprehensive Information and Data-Management System User...

Documents

Transcript of · 10/8/2012 · DATAMINER FOR Z/OS Comprehensive Information and Data-Management System User...