Dataminer 7.1 Z-os User Ref Guide 20121008

Transcript

DATAMINER FOR Z/OS Comprehensive Information and Data-Management System DATAMINER FOR Z/OS DATAMINER for z/OS is a collection of powerful data-mining and datamanipulation 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. User Reference Guide Release 7.1C 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/OS Information Retrieval and Reporting System Version 7 Release 1C October 2012 Published by CSI International 8120 State Route 138, Williamsport OH 43164 Phone: 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 and Technical 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-4914 Worldwide: 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 Toll Free in the USA: 800-795-4914 Worldwide: 740-420-5400 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 International i CSI International Technical Support • Telephone Toll Free in the USA: 800-795-4914 Worldwide: 740-420-5400 • E-mail Escalation: [email protected] After Hours (SEV1) 1. Call one of the following telephone numbers. Toll Free in the USA: 800-795-4914 Worldwide: 740-420-5400 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 International ii Table of Contents CSI International Technical Support and Technical Support Escalation............. i CSI Product Technical Support ..................................................................................... i Escalating Technical Issues ........................................................................................... i Chapter 1. Overview .............................................................................................. 1.1 What Is DATAMINER?.......................................................................................................1.2 Introduction.................................................................................................................1.2 Batch and Online Environments .................................................................................1.3 VSAM I/O Driver ......................................................................................................1.3 File Command Result .................................................................................................1.4 Available Functions ..........................................................................................................1.5 Supported Files ..........................................................................................................1.6 Ways to Use ...............................................................................................................1.6 Features and Capabilities ..................................................................................................1.7 Some Practical Examples............................................................................................1.8 Syntax Conventions Used in This Manual .......................................................................1.9 Chapter 2. DATAMINER Scripts .............................................................................. 2.1 Introduction to Scripts ......................................................................................................2.2 Processing Modes .......................................................................................................2.2 AUTO Command........................................................................................................2.2 BEGIN and EOF Procedures ......................................................................................2.3 Script Example with BEGIN and EOF Procedures ....................................................2.3 Difference Between BEGIN/EOF and BEFORE/AFTER Timings ...........................2.3 Multiple Input and Output Datasets............................................................................2.3 Script Components............................................................................................................2.4 Introduction.................................................................................................................2.4 Shortcut Commands....................................................................................................2.4 Input and Output Dataset Definitions .........................................................................2.4 Field Definitions .........................................................................................................2.4 Variables .....................................................................................................................2.4 Copyright © 2012 by CSI International iii DATAMINER FOR Z/OS 7.1C User Reference Guide Table of Contents Commands ..................................................................................................................2.4 Script Example............................................................................................................2.5 Notes on This Example...............................................................................................2.5 Execution Sequence ..........................................................................................................2.6 Introduction.................................................................................................................2.6 Command Sequence ...................................................................................................2.6 Effects of Command Sequences ................................................................................2.6 Execution JCL...................................................................................................................2.7 Introduction.................................................................................................................2.7 Example ......................................................................................................................2.7 Script Readability .............................................................................................................2.8 Introduction.................................................................................................................2.8 Words That Are Always Ignored................................................................................2.8 Symbols That Are Sometimes Ignored .......................................................................2.8 Examples: Ignored Symbols .......................................................................................2.8 Adding Comments ............................................................................................................2.9 Introduction.................................................................................................................2.9 Comment Indicators....................................................................................................2.9 Examples.....................................................................................................................2.9 INCLUDE Command .....................................................................................................2.10 OFFSET= Command ......................................................................................................2.11 SCRIPT Command .........................................................................................................2.12 STATS Command...........................................................................................................2.13 VALIDATE= Command ................................................................................................2.14 DATAMINER Reserved Words ........................................................................................2.15 Chapter 3. Input and Output Specification.......................................................... 3.1 DATAMINER Input and Output Datasets ...........................................................................3.2 Introduction.................................................................................................................3.2 Opening Datasets ........................................................................................................3.2 Unused Datasets..........................................................................................................3.2 INPUT= Command...........................................................................................................3.3 OUTPUT= Command .....................................................................................................3.7 DATACARDs Command ...............................................................................................3.12 Chapter 4. Record Fields ...................................................................................... 4.1 Defining Record Fields .....................................................................................................4.2 Introduction.................................................................................................................4.2 Syntax to Define a Record Field.................................................................................4.2 Example Definition.....................................................................................................4.6 Example of Creating Overlapping Record Fields ......................................................4.7 Example of Defining Five Fields................................................................................4.7 Arrays and Indexing..........................................................................................................4.8 Introduction.................................................................................................................4.8 INDEXing by Subscripted Array Member Number ...................................................4.8 INDEXing by INDEX Value ......................................................................................4.9 Copyright © 2012 by CSI International iv DATAMINER FOR Z/OS 7.1C User Reference Guide Table of Contents INDEXing by Bytes Offset.......................................................................................4.10 Chapter 5. Variables, Literals, and System Constants ...................................... 5.1 Variable Types ..................................................................................................................5.2 Introduction.................................................................................................................5.2 Defining User Variables (DEFINE Command)................................................................5.3 Arrays and Indexing..........................................................................................................5.8 Introduction.................................................................................................................5.8 INDEXing by Subscripted Array Member Number ...................................................5.8 INDEXing by INDEX Value ......................................................................................5.9 INDEXing by Bytes Offset.......................................................................................5.10 System Variables ............................................................................................................5.12 Introduction...............................................................................................................5.12 Example ...................................................................................................................5.12 Variables List ............................................................................................................5.12 Literals ............................................................................................................................5.15 Introduction...............................................................................................................5.15 Character ..................................................................................................................5.15 Packed Decimal ........................................................................................................5.15 Zoned Decimal .........................................................................................................5.16 Hexadecimal ............................................................................................................5.16 Binary .......................................................................................................................5.17 Numeric ...................................................................................................................5.17 System Constants ............................................................................................................5.18 Chapter 6. Shortcut Commands........................................................................... 6.1 Shortcut Commands Overview .........................................................................................6.2 Introduction.................................................................................................................6.2 What Makes a Shortcut Command .............................................................................6.2 Constraints .................................................................................................................6.2 COPY Shortcut Command................................................................................................6.3 UPDATE Shortcut Command ..........................................................................................6.5 EXTRACT Shortcut Command........................................................................................6.6 PRINT Shortcut Command...............................................................................................6.8 Example 1 Script.........................................................................................................6.9 Example 1 Output ....................................................................................................6.10 Narrowing What Is Printed .......................................................................................6.10 DUMP Shortcut Command.............................................................................................6.12 DELETE Shortcut Command ........................................................................................6.14 HD Subcommand ...........................................................................................................6.15 MAXLN= Subcommand.................................................................................................6.16 SELECT…[WHERE] Subcommand ............................................................................6.17 TOT Subcommand..........................................................................................................6.20 Chapter 7. Dataset Reading and Writing ............................................................. 7.1 Dataset Reading Overview ...............................................................................................7.2 Copyright © 2012 by CSI International v DATAMINER FOR Z/OS 7.1C User Reference Guide Table of Contents Introduction.................................................................................................................7.2 READ Command ..............................................................................................................7.3 POINT Command ...........................................................................................................7.5 WRITE Command ............................................................................................................7.6 Examples of READing and WRITEing Data ...................................................................7.8 INSERT INTO…VALUES Command ..........................................................................7.12 DISPLAY Command ......................................................................................................7.14 Chapter 8. Conditions and Flow Control............................................................. 8.1 Relational Operators .........................................................................................................8.2 Description..................................................................................................................8.2 IF…[ELSE]…ENDIF Statements ....................................................................................8.3 DO WHILE and ENDDO Statements ..............................................................................8.6 PROC…[GOBACK]…ENDPROC Statements (Defining Procedures)...........................8.8 PERFORM Command (Call a Procedure)......................................................................8.10 Labels and GOTO Statements ........................................................................................8.11 EXIT Command (Escape a Script) .................................................................................8.13 CALL…[USING] Command .........................................................................................8.14 Timing Commands .........................................................................................................8.15 Chapter 9. Record-Selection Commands............................................................ 9.1 Introduction.......................................................................................................................9.2 Commands Overview .................................................................................................9.2 Execution Order ..........................................................................................................9.2 Record-Selection Rules ..............................................................................................9.3 FIRSTKEY Command......................................................................................................9.4 FIRST= Command............................................................................................................9.5 LAST= Command.............................................................................................................9.6 FREQ= Command ............................................................................................................9.7 KEEP Command...............................................................................................................9.8 DROP Command ..............................................................................................................9.9 START Command ..........................................................................................................9.10 STOP Command .............................................................................................................9.12 SKIP Command ..............................................................................................................9.14 ONLY (or WHERE) Command .....................................................................................9.16 MAXRCDS= Command.................................................................................................9.18 Chapter 10. Data Manipulation Commands ...................................................... 10.1 Data Manipulation Commands .......................................................................................10.2 Introduction...............................................................................................................10.2 Constraints ................................................................................................................10.2 Special Notes ............................................................................................................10.2 MOVE Command ...........................................................................................................10.4 SET Command................................................................................................................10.6 HIDE Command .............................................................................................................10.7 CLOAK Command .........................................................................................................10.8 Copyright © 2012 by CSI International vi DATAMINER FOR Z/OS 7.1C User Reference Guide Table of Contents Arithmetic Commands ....................................................................................................10.9 Introduction...............................................................................................................10.9 Accumulators Commands.........................................................................................10.9 IF Commands............................................................................................................10.9 Input Values May Change ........................................................................................10.9 ADD Command ............................................................................................................10.10 SUBTRACT Command ................................................................................................10.11 MULTIPLY Command.................................................................................................10.12 DIVIDE Command .......................................................................................................10.13 Chapter 11. Report Writer ................................................................................... 11.1 Report Writer Overview .................................................................................................11.2 Introduction ..............................................................................................................11.2 Mailing Labels and Other Printing Tasks .................................................................11.2 Creating a Report Writer Script ......................................................................................11.3 Overview...................................................................................................................11.3 Step 1—Specify the Input.........................................................................................11.3 Step 2—Define the Fields and Variables to Use in the Report ................................11.3 Step 3—Read the Input File......................................................................................11.3 Step 4—Select Records ............................................................................................11.4 Step 5—Perform Computations................................................................................11.4 Step 6—Use PRINT to Print a Report ......................................................................11.4 Step 7—Use REPORT to Specify Fields and Report Formatting ............................11.4 Script Example..........................................................................................................11.5 Defining Field Formats and Headings in a Report .........................................................11.6 Field Masks...............................................................................................................11.6 User-Defined Masks .................................................................................................11.6 Column Headings ....................................................................................................11.6 Adding a User-Defined Mask to a Field Definition .......................................................11.7 Using the REPORT Command .......................................................................................11.8 REPORT Subcommands Summary ..............................................................................11.10 Summary Table.......................................................................................................11.10 ACROSS, WIDTH, and HEIGHT Subcommands .......................................................11.11 ADVANCE Subcommand ............................................................................................11.12 AVG Subcommand.......................................................................................................11.13 BREAK (or CONTROL) Subcommand .......................................................................11.14 GAP Subcommand .......................................................................................................11.16 HEADING Subcommand .............................................................................................11.17 LABELS Subcommand ................................................................................................11.18 LENGTH Subcommand ..............................................................................................11.19 LINE Subcommand ......................................................................................................11.20 NODATE and NOPAGE Subcommands .....................................................................11.22 ORDER (or SEQUENCE) Subcommand .....................................................................11.23 PRINTER Subcommand...............................................................................................11.26 SPACING Subcommand ..............................................................................................11.27 SUM Subcommand.......................................................................................................11.28 Copyright © 2012 by CSI International vii DATAMINER FOR Z/OS 7.1C User Reference Guide Table of Contents SUMMARY Subcommand...........................................................................................11.29 TITLE Subcommand ....................................................................................................11.30 Report Formatting—Simple to Complex......................................................................11.32 Additional Report Writer Examples .............................................................................11.41 Chapter 12. Table Fields ..................................................................................... 12.1 TABLE Command ..........................................................................................................12.2 Defining Table Fields .....................................................................................................12.4 Arrays and Indexing........................................................................................................12.9 Introduction...............................................................................................................12.9 INDEXing by Subscripted Array Member Number .................................................12.9 INDEXing by INDEX Value ..................................................................................12.10 INDEXing by Bytes Offset.....................................................................................12.11 DATA…ENDDATA Subcommands ...........................................................................12.13 FIND Subcommand (Searching Tables).......................................................................12.14 Chapter 13. SORT Command ............................................................................. 13.1 SORT Command.............................................................................................................13.2 Chapter 14. Troubleshooting Commands ......................................................... 14.1 ABEND Command .........................................................................................................14.2 CANCEL Command.......................................................................................................14.3 SHOW Command ...........................................................................................................14.4 TRACE Command..........................................................................................................14.6 Chapter 15. DB2 Commands .............................................................................. 15.1 DB2 Access.....................................................................................................................15.2 Introduction...............................................................................................................15.2 CONNECT Command ....................................................................................................15.3 INPUT= Command (DB2)..............................................................................................15.4 OUTPUT= Command (DB2)..........................................................................................15.5 EXECUTE Command.....................................................................................................15.6 CLOSE Command ..........................................................................................................15.7 COMMIT Command ......................................................................................................15.8 ROLLBACK Command .................................................................................................15.9 Host Variables...............................................................................................................15.10 Additional Information about DB2...............................................................................15.11 Field Names ............................................................................................................15.11 Cursors ....................................................................................................................15.11 System Variables ....................................................................................................15.11 DB2 Examples ..............................................................................................................15.12 Example 1: Simple Auto Print ................................................................................15.12 Example 2: Auto-Read Report................................................................................15.12 Example 3: Manual-Read Report ...........................................................................15.13 Example 4: Multiple Cursors ..................................................................................15.13 Example 5: Simple Table Update ...........................................................................15.13 Copyright © 2012 by CSI International viii DATAMINER FOR Z/OS 7.1C User Reference Guide Table of Contents Example 6: Table Update with Host Variables ......................................................15.14 Example 7: Extract from DB2 to Sequential Dataset .............................................15.15 Example 8: Extract from VSAM to DB2................................................................15.15 Chapter 16. DATAMINER Messages ..................................................................... 16.1 Summary Messages ........................................................................................................16.2 Introduction...............................................................................................................16.2 nnn RECORDS READ FROM filename datasetname .............................................16.2 nnn RECORDS WRITTEN TO FILE filename datasetname ..................................16.2 nnn RECORDS UPDATED IN FILE filename datasetname ...................................16.2 nnn RECORDS DELETED FROM FILE filename datasetname ............................16.2 nnn DATA RECORDS PRINTED ...........................................................................16.2 nnn DATA RECORDS DUMPED ...........................................................................16.2 nnn FIELD VALIDATION ERRORS......................................................................16.2 Syntax Error Messages ...................................................................................................16.3 Introduction...............................................................................................................16.3 Message Example .....................................................................................................16.3 Message Table ..........................................................................................................16.4 General Messages .........................................................................................................16.12 List of Messages ....................................................................................................16.12 Message Table ........................................................................................................16.14 Chapter 17. DATAMINER Script Examples........................................................... 17.1 Common Examples.........................................................................................................17.3 Ex. 1: COPY Subset of Records ..............................................................................17.3 Ex. 2: COPY and PRINT Specific Records..............................................................17.3 Ex. 3: DUMP Specific Records ................................................................................17.3 Ex. 4: COPY and PRINT Specific Records and Calculations ..................................17.3 Ex. 5: PRINT Specific Records, Calculations, and Totals .......................................17.4 Ex. 6: PRINT Specific Records and Totals ..............................................................17.5 Ex. 7: DELETE Specific Records.............................................................................17.6 Ex. 8: EXTRACT and PRINT Specific Records ......................................................17.6 Ex. 9: EXTRACT and PRINT Records, Calculations ..............................................17.7 Ex. 10: DUMP Specific Records ..............................................................................17.7 Ex. 11: COPY Specific Records, KSDS...................................................................17.7 Ex. 12: COPY Specific Records, Fixed Block .........................................................17.8 Ex. 13: UPDATE Variable Blocked File In Place....................................................17.8 Ex. 14: UPDATE Fixed-Length File ........................................................................17.8 Ex. 15: INSERT Records into a KSDS.....................................................................17.9 Ex. 16: UPDATE a KSDS ........................................................................................17.9 Ex. 17: COPY and PRINT Specific Records............................................................17.9 Ex. 18: DUMP the First 50 Records From a KSDS ...............................................17.10 Ex. 19: COPY VSAM File to an FL Dataset, DUMP Recs....................................17.10 Ex. 20: PRINT Column Report Showing Three Fields ..........................................17.10 Ex. 21: COPY 1000 Records from One File to Another ........................................17.11 Ex. 22: PRINT Report and DUMP Recs Using Criteria.........................................17.11 Copyright © 2012 by CSI International ix DATAMINER FOR Z/OS 7.1C User Reference Guide Table of Contents Ex. 23: PRINT Records Within a Balance Range ..................................................17.12 Ex. 24: DUMP Records and Delete Matching Records..........................................17.12 Ex. 25: Calculate Ratio, PRINT Report, EXTRACT Records ...............................17.12 Ex. 26: DUMP the First 20 Records Matching Criteria .........................................17.13 Ex. 27: Create New KSDS Records from Card Input.............................................17.13 Ex. 28: READ Two Files and SHOW ACCTNO from Both .................................17.13 Ex. 29: UPDATE a Sequential File In Place ..........................................................17.14 Ex. 30: PRINT a Column Report from a File .........................................................17.14 Ex. 31: COPY and DUMP the First 10 Records of a File ......................................17.14 Ex. 32: Create a File from Selected Fields of an Input File....................................17.15 Ex. 33: COPY a Prod File to a Test File, Changing Names ...................................17.15 Ex. 34: PRINT Report Sorted by Fields, Create Subtotals .....................................17.16 Ex. 35: PRINT Report Sorted by Fields, File/Table Input .....................................17.17 Ex. 36: PRINT Name and Address Labels .............................................................17.18 Ex. 37: Using ORDER and BREAK Commands Together....................................17.18 Ex. 38: Using ORDER, BREAK, and SUMMARY Together ...............................17.20 Chapter 18. DATAMINER Online ........................................................................... 18.1 Overview of DATAMINER Online ...................................................................................18.2 Introduction...............................................................................................................18.2 Description................................................................................................................18.2 Supported Environments...........................................................................................18.2 System Requirements ...............................................................................................18.2 CICS Temporary Storage Queues.............................................................................18.2 Security .....................................................................................................................18.2 Features and Capabilities ..........................................................................................18.3 How DATAMINER Online Works....................................................................................18.4 Introduction...............................................................................................................18.4 Access Records .........................................................................................................18.4 Browsing Files ..........................................................................................................18.4 Browsing Temporary Storage Queues ......................................................................18.4 DATAMINER Online Sample Screen ...............................................................................18.5 Introduction...............................................................................................................18.5 Example ....................................................................................................................18.5 Transaction................................................................................................................18.5 Software version .......................................................................................................18.5 RECORD NUMBER (RCD xxx OF yyy) .................................................................18.5 FILEID Field.............................................................................................................18.5 LRECL Field.............................................................................................................18.6 OPER Field ...............................................................................................................18.6 KEY ..........................................................................................................................18.9 THRU KEY ..............................................................................................................18.9 REMOTE KEYPOS ...............................................................................................18.10 DATA AREA .........................................................................................................18.10 PF KEYS.................................................................................................................18.10 DATAMINER Online Error Messages ............................................................................18.11 Copyright © 2012 by CSI International x DATAMINER FOR Z/OS 7.1C User Reference Guide Table of Contents Chapter 19. DATAMINER/VE.................................................................................. 19.1 DATAMINER/VE Benefits and Features..........................................................................19.2 Benefits .....................................................................................................................19.2 Features and Capabilities ..........................................................................................19.3 DataMiner/VE and 4GL, COBOL, and PL/I ..................................................................19.4 Introduction...............................................................................................................19.4 DATAMINER/VE and 4GL Partnership Benefits.......................................................19.4 DATAMINER/VE and COBOL and PL/I Benefits .....................................................19.4 DATAMINER/VE Access to VSAM Files........................................................................19.6 Introduction...............................................................................................................19.6 Online Access ...........................................................................................................19.6 Batch Access.............................................................................................................19.6 DATAMINER/VE Programming Overview......................................................................19.7 Introduction...............................................................................................................19.7 General Access ........................................................................................................19.7 CICS Access ............................................................................................................19.7 Batch Application Access ........................................................................................19.7 Supported Environments ..........................................................................................19.8 How DATAMINER/VE Works .........................................................................................19.9 Sequence ..................................................................................................................19.9 Programmer-Defined Components ...........................................................................19.9 Return Codes ............................................................................................................19.9 CICS and COM-PLETE Requirements ........................................................................19.10 Introduction ............................................................................................................19.10 CICS Users ............................................................................................................19.10 COM-PLETE Users ...............................................................................................19.10 Executing DATAMINER/VE ..........................................................................................19.12 Introduction.............................................................................................................19.12 COBOL Example ...................................................................................................19.12 NATURAL Example .............................................................................................19.12 Batch Assembler Example......................................................................................19.12 CICS Temporary Storage Access .................................................................................19.13 Introduction.............................................................................................................19.13 Temporary Storage Use .........................................................................................19.13 CICS—CONTROL-BLOCK........................................................................................19.14 Introduction.............................................................................................................19.14 COBOL Example....................................................................................................19.14 Assembler Example ...............................................................................................19.14 RETURN-CODE (CL3) .........................................................................................19.14 ACTION-CODE (CL3) ..........................................................................................19.15 FILE-ID (CL8)........................................................................................................19.18 RECORD-LENGTH (BL2) ....................................................................................19.19 RESERVED-AREA (BL17)...................................................................................19.20 KEY-POSITION (BL2) ..........................................................................................19.20 KEY-LENGTH (BL2) ............................................................................................19.20 KEY (Variable).......................................................................................................19.21 Copyright © 2012 by CSI International xi DATAMINER FOR Z/OS 7.1C User Reference Guide Table of Contents CICS—RECORD-AREA .............................................................................................19.22 Introduction ............................................................................................................19.22 RECORD-AREA Size ............................................................................................19.22 Batch—CONTROL-BLOCK .......................................................................................19.23 Introduction.............................................................................................................19.23 COBOL Example....................................................................................................19.23 Assembler Example ................................................................................................19.23 RETURN-CODE (CL3) .........................................................................................19.23 ACTION-CODE (CL3) ..........................................................................................19.24 FILE-ID (CL8)........................................................................................................19.28 RECORD-LENGTH (BL2) ....................................................................................19.28 RESERVED AREA (BL10) ...................................................................................19.29 PASSWORD-LENGTH (BL1)...............................................................................19.29 PASSWORD (CL8) ................................................................................................19.29 KEY-LENGTH (BL2) ............................................................................................19.29 KEY (Variable Length) ..........................................................................................19.29 Batch—RECORD-AREA.............................................................................................19.30 Introduction ............................................................................................................19.30 Important Points......................................................................................................19.30 Return Codes ................................................................................................................19.31 Program Examples ........................................................................................................19.35 Example 1: Online Command Level COBOL Program .........................................19.35 Example 2: Online NATURAL Program (Single-File Access)..............................19.36 Example 3: Online NATURAL Program (Multiple-File Access) ..........................19.37 Example 4: Online Assembler Program .................................................................19.38 Example 5: Batch NATURAL Program .................................................................19.40 Example 6: Dynamic Call to VNATB ....................................................................19.41 Example 7: Static Call to VNATB .........................................................................19.41 Example 8: Batch Assembler Program ...................................................................19.42 DATAMINER/VE Installation.........................................................................................19.43 Introduction.............................................................................................................19.43 Load Library Modules ...........................................................................................19.43 Source Library Module ...........................................................................................19.43 DATAMINER/VE Online Security ................................................................................19.44 Introduction ............................................................................................................19.44 Security Table ........................................................................................................19.44 Installed Modes ......................................................................................................19.44 Inclusive Security Mode .........................................................................................19.44 Exclusive Security Mode .......................................................................................19.44 Security Check Methodology ................................................................................19.44 Adding or Changing Security Entries ....................................................................19.45 Security Module Source..........................................................................................19.46 DATAMINER/VE Control Table ....................................................................................19.48 Introduction.............................................................................................................19.48 Control Table .........................................................................................................19.48 Copyright © 2012 by CSI International xii DATAMINER FOR Z/OS 7.1C User Reference Guide Table of Contents Chapter 20. DATAMINER/VE Support ................................................................... 20.1 DATAMINER/VE Programming Tips ..............................................................................20.2 CICS Pseudo Conversational EOT with NATURAL ..............................................20.2 Avoiding Lockouts ...................................................................................................20.2 Using CICS Temporary Storage for Scrolling..........................................................20.4 Accessing Multiple Files ..........................................................................................20.4 Alternate Indexes with Non-Unique Keys................................................................20.4 NATURAL Packed Fields in Keys...........................................................................20.5 NATURAL Calls ......................................................................................................20.5 Troubleshooting DATAMINER/VE ..................................................................................20.6 Introduction...............................................................................................................20.6 CONTROL-BLOCK Layout ....................................................................................20.6 RESERVED-AREA Handling..................................................................................20.6 0V06I Message .........................................................................................................20.6 RETURN-CODE Checking ......................................................................................20.6 RECORD-AREA Size Specification ........................................................................20.6 S080A GETMAIN Failure Errors.............................................................................20.6 Transaction Work Area Addressing .........................................................................20.7 CICS AEY9 ABEND or NATURAL 954 ABEND .................................................20.7 Differences Between VNAT and VNATB ...............................................................20.7 NATURAL 920 Abend.............................................................................................20.7 Corrupted Code in your NATURAL 2.1 Program ...................................................20.7 Incorrect Installation of New Release of VNATB / VNATB2 with NATURAL.....20.8 VSAM Basics for DATAMINER/VE................................................................................20.9 Introduction...............................................................................................................20.9 File Types .................................................................................................................20.9 Key Sequence Dataset (KSDS).................................................................................20.9 Entry Sequence Dataset (ESDS)...............................................................................20.9 Relative Record Dataset (RRDS) .............................................................................20.9 Reusable Dataset.......................................................................................................20.9 Record Retrieval .......................................................................................................20.9 KSDS (Keyed Sequence Dataset)...........................................................................20.10 ESDS (Entry Sequence Dataset).............................................................................20.10 RRDS (Relative Record Dataset) ...........................................................................20.11 Copyright © 2012 by CSI International xiii DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International xiv Table of Contents 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.2 Available Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.5 Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.7 Syntax Conventions Used in This Manual. . . . . . . . . . . . . . . . . . . . . . . 1.9 Copyright © 2012 by CSI International 1.1 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. Copyright © 2012 by CSI International 1.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Batch and Online Environments Overview DATAMINER works in both batch and online (TSO and CICS) environments. The following table compares how you use DATAMINER in these environments. DATAMINER Batch VSAM I/O Driver 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  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.  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 DATAMINER ISPF is an online VSAM editor that non-technical users can use to display or change parts of VSAM datasets. 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 Copyright © 2012 by CSI International 1.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Overview 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 threecharacter 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. Copyright © 2012 by CSI International 1.4 DATAMINER FOR Z/OS 7.1C User Reference Guide Overview 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. Copyright © 2012 by CSI International 1.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Overview 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. Copyright © 2012 by CSI International 1.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Overview 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 Copyright © 2012 by CSI International 1.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Overview — 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. Copyright © 2012 by CSI International 1.8 DATAMINER FOR Z/OS 7.1C User Reference Guide Overview 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. Copyright © 2012 by CSI International 1.9 DATAMINER FOR Z/OS 7.1C User Reference Guide Multiple Lines Overview 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']]] Copyright © 2012 by CSI International 1.10 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.2 Script Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4 Execution Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.6 Execution JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.7 Script Readability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.8 Adding Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.9 INCLUDE Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.10 OFFSET= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.11 SCRIPT Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.12 STATS Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.13 VALIDATE= Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.14 DATAMINER Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.15 Copyright © 2012 by CSI International 2.1 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts Introduction to Scripts Processing Modes AUTO Command DATAMINER has two script-processing modes: 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. 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=ddname STARTIT. READ ddname IF EOF ddname GOTO ENDIT ENDIF * Other script commands go below this line GOTO STARTIT ENDIT. Copyright © 2012 by CSI International 2.2 DATAMINER FOR Z/OS 7.1C User Reference Guide BEGIN and EOF Procedures DataMiner Scripts 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 file AUTO INPUT EMPVSAM BEGIN STARTIT EOF ENDIT * Main processing commands go here... PROC STARTIT /* This is the start-up procedure MOVE 'READY' TO FIELDA ENDPROC * PROC ENDIT /* This is the End-of-File procedure DISPLAY 'Final totals are ' TOTAL1 TOTAL2 ENDPROC 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. Copyright © 2012 by CSI International 2.3 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts 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. Copyright © 2012 by CSI International 2.4 DATAMINER FOR Z/OS 7.1C User Reference Guide Script Example DataMiner Scripts 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. //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 /* // 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. Copyright © 2012 by CSI International 2.5 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts 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 TYPE IF 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. Copyright © 2012 by CSI International 2.6 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts 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: //DMJOB //STEP01 //STEPLIB //SYSPRINT //INFILE //OUTFILE //SYSIN JOB (user),CLASS=A,MSGCLASS=A EXEC PGM=CSIDMBMD DD DSN=dataminer.loadlib,DISP=SHR DD SYSOUT=* DD DSN=input.sequential.dataset,DISP=SHR DD DSN=output.sequential.dataset,DISP=OLD DD * 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. Copyright © 2012 by CSI International 2.7 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts 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. Copyright © 2012 by CSI International 2.8 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts 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: Indicator Examples 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. Here are examples for each indicator type: 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 + TAX \ \ POINT FILE1 TO BEGIN ? ? READ FILE1 Copyright © 2012 by CSI International 2.9 /* ADD SALE TO VALUE /* ADD TAX, TOO DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts 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_name Is 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 */ Copyright © 2012 by CSI International 2.10 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts 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. Copyright © 2012 by CSI International 2.11 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts 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 ON Is the default and tells DATAMINER to list your script on the system printer as it executes. OFF Suppresses the printing of your script on the system printer. Copyright © 2012 by CSI International 2.12 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts STATS Command Description The STATS command tells DATAMINER where you want execution statistics printed, if at all. STATS [Printer | Console | Both | None] Syntax 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 35 35 40 0 RECORDS PRINTED ON PRINTER RECORDS DUMPED ON PRINTER RECORDS ADDED TO OUTFILE JM.FIXBLK.OUTPUT RECORDS READ FROM INFILE DMNR.KSDS.R10K FIELD VALIDATION ERRORS Copyright © 2012 by CSI International 2.13 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts 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 Y Specifies that DATAMINER perform all data validation checks. This is the default. N Specifies that DATAMINER perform no validation checks. L Specifies that DATAMINER perform record-length validation only. D Specifies that DATAMINER perform decimal (numeric-field) validation only. Copyright © 2012 by CSI International 2.14 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Scripts 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 Copyright © 2012 by CSI International 2.15 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International 2.16 DataMiner Scripts 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. This chapter covers the following topics: Page DATAMINER Input and Output Datasets . . . . . . . . . . . . . . . . . . . . . . . . 3.2 INPUT= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 OUTPUT= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7 DATACARDs Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.12 Copyright © 2012 by CSI International 3.1 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. Copyright © 2012 by CSI International 3.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Input and Output Specification 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=ddname Specifies 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. Copyright © 2012 by CSI International 3.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Input and Output Specification [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? Comments Optional? Disallowed? 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. Copyright © 2012 by CSI International 3.4 DATAMINER FOR Z/OS 7.1C User Reference Guide Input and Output Specification The default values used when you do not specify an LRECL are as follows: Record Type Default Value for LRECL= Card 80 Fixed-Length The input BLKSIZE, but the records are still Input unblocked. VariableLength Output The following table explains the possible default values for LRECL in the case of variable-length records: 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. 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. 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. Copyright © 2012 by CSI International 3.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Input and Output Specification The default values for BLKSIZE are as follows: 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. 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. UNDEFined This 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. VARUNB This 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 Copyright © 2012 by CSI International 3.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Input and Output Specification 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=ddname Specifies 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=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 for LRECL=. Copyright © 2012 by CSI International 3.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Input and Output Specification The following table describes when to use the LRECL= operand. Record Type LRECL= Required? Comments Optional? Disallowed? 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 DATAMINER uses the information in the VSAM catalog. Disallowed. Copyright © 2012 by CSI International 3.8 DATAMINER FOR Z/OS 7.1C User Reference Guide Input and Output Specification The default values used if you do not specify an LRECL are as follows: Record Type Default Value for LRECL= FixedLength Input The input BLKSIZE, but the records are still unblocked. Variable- The following table explains the possible default values Length for LRECL in the case of variable-length records: Output 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 The smallest length to accommodate all the EXTRACT shortcut command (see Chapter 6, selected fields and literals. “EXTRACT Shortcut Command”) 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. 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=numbytes Specifies the block size for the dataset. It is not used by VSAM output datasets. This parameter is recommended for sequential datasets. Copyright © 2012 by CSI International 3.9 DATAMINER FOR Z/OS 7.1C User Reference Guide Input and Output Specification The default values for BLKSIZE= are as follows: Is LRECL Specified Default Value for BLKSIZE= for the Output Dataset? Yes No The value of the output’s LRECL. For This Record Type The Default Is Variable Length 32K Fixed Length There is no default; an error results 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. UNDEFined This 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. VARUNB This parameter specifies that a tape or disk has a variable, unblocked dataset format. MAX=records Specifies 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. Copyright © 2012 by CSI International 3.10 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 1 Input and Output Specification 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. Copyright © 2012 by CSI International 3.11 DATAMINER FOR Z/OS 7.1C User Reference Guide Input and Output Specification 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: DATACARDS 8KA9AA8K7**33DDD3**3*33END OF RECORD 8KLSWAD6**34CCC3**3*34 8K7DEA6**35EEE3**3*35 8K7LFRA**33DDD3**3*33 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 /* Copyright © 2012 by CSI International 3.12 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. Dataset INPUT= (OUTPUT=) Record n Data Record Field Note To load multiple data fields from each record into a table that you can search, see Chapter 12, “Table Fields.” This chapter covers the following topics: Page Defining Record Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 Arrays and Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.8 Copyright © 2012 by CSI International 4.1 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. recfieldname Is 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. Copyright © 2012 by CSI International 4.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Record Fields 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. startpos Is the starting position of recfieldname. Record fields can overlap or have gaps between them. startpos is one of the following: n A 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. *+n The nth byte higher than the byte following the previous field. *-n The nth byte lower than the byte following the previous field. Copyright © 2012 by CSI International 4.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Record Fields " The same location as the first byte of the previous field. "+n The nth byte higher than the first byte of the previous field. "-n The nth byte lower than the first byte of the previous field. recfieldname2 The same location as the first byte of another field, recfieldname2. recfieldname2+n The nth byte higher than the first byte of another field, recfieldname2. recfieldname2-n The nth byte lower than the first byte of another field, recfieldname2. length Is 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. type Is a character denoting the data type of the field, as follows: Character Data Type Max Length (Bytes) A Alphanumeric 32,767 C Character 32,767 B Binary 4 P Packed 16 N or Z Zoned 16 X Hexadecimal 8 V Variable-length character N/A D Date N/A Copyright © 2012 by CSI International 4.4 Comments Treated as signed if 2 or 4 bytes long. Treated as unsigned if 1 or 3 bytes long. For DB2 only. DATAMINER FOR Z/OS 7.1C User Reference Guide Record Fields [ 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).99M3 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. Copyright © 2012 by CSI International 4.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Record Fields • 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: 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. 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 Copyright © 2012 by CSI International 4.6 DATAMINER FOR Z/OS 7.1C User Reference Guide 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 MM DD YYYY CC YY Example of Defining Five Fields Record Fields 32 " * * YYYY CC+2 8 2 2 4 2 2 Z Z Z Z Z Z The following example defines five fields in a record: ACC_NO, BALANCE, FLAGS, NEW_BAL, and ADDRESS. ACC_NO BALANCE FLAGS NEW_BAL ADDRESS 1,8,C 32,7,P,2,M5 41,1,X 50,9,P,2,M3 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. Copyright © 2012 by CSI International 4.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Record Fields 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 recfieldname Is the name of the record field that is an array. n Is 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) Copyright © 2012 by CSI International 4.8 DATAMINER FOR Z/OS 7.1C User Reference Guide Record Fields 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 SET SET SET SET SET SET SET SET SET SET SET INDEXing by INDEX Value MONTH(1) = 'JAN' MONTH(2) = 'FEB' MONTH(3) = 'MAR' MONTH(4) = 'APR' MONTH(5) = 'MAY' MONTH(6) = 'JUN' MONTH(7) = 'JUL' MONTH(8) = 'AUG' MONTH(9) = 'SEP' MONTH(10) = 'OCT' MONTH(11) = 'NOV' MONTH(12) = 'DEC' 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= 1 SET MONTH= 'JAN' SET NUM= 2 Copyright © 2012 by CSI International 4.9 DATAMINER FOR Z/OS 7.1C User Reference Guide SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET INDEXing by Bytes Offset MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= Record Fields 'FEB' 3 'MAR' 4 'APR' 5 'MAY' 6 'JUN' 7 'JUL' 8 'AUG' 9 'SEP' 10 'OCT' 11 'NOV' 12 'DEC' 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: 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 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. In the current example, you address the each member like this: MONTH(NUM) 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. Copyright © 2012 by CSI International 4.10 DATAMINER FOR Z/OS 7.1C User Reference Guide Record Fields 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 SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET NUM= 0 MONTH(NUM)='JAN' NUM= 3 MONTH(NUM)='FEB' NUM= 6 MONTH(NUM)='MAR' NUM= 9 MONTH(NUM)='APR' NUM= 12 MONTH(NUM)='MAY' NUM= 15 MONTH(NUM)='JUN' NUM= 18 MONTH(NUM)='JUL' NUM= 21 MONTH(NUM)='AUG' NUM= 24 MONTH(NUM)='SEP' NUM= 27 MONTH(NUM)='OCT' NUM= 30 MONTH(NUM)='NOV' NUM= 33 MONTH(NUM)='DEC' Copyright © 2012 by CSI International 4.11 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International 4.12 Record Fields 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. This chapter covers the following topics: Page Variable Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 Defining User Variables (DEFINE Command) . . . . . . . . . . . . . . . . . . . 5.3 Arrays and Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8 System Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.12 Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.15 System Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.18 Copyright © 2012 by CSI International 5.1 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. Copyright © 2012 by CSI International 5.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants 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'] [OCCURS n TIMES [INDEX(ixname)]] [std-mask] 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.) [MASK 'user-defined-mask'] [HEADING 'headingline1' ['headingline2' ['headingline3']]] The fields in the above syntax statements are explained below. uservarname Is 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: @ # _ - $ Copyright © 2012 by CSI International 5.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants 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. length Is 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. type Is a character that denotes the data type of the user variable, as follows: Character Data Type Max Length (Bytes) A Alphanumeric 32,767 C Character 32,767 B Binary 4 P Packed 16 N or Z Zoned 16 X Hexadecimal 8 V Variable-length character N/A D Date N/A Copyright © 2012 by CSI International 5.4 Comments Treated as signed if 2 or 4 bytes long. Treated as unsigned if 1 or 3 bytes long. DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants [ 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. [ 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 5.8). (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). [std-mask] Is one of five standard printing masks for numeric fields only (binary, packed, and zoned), as follows: 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).99M3 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. Copyright © 2012 by CSI International 5.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants • 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 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: Value Type Default Value Numeric 0 Hexadecimal 0 Character One or more spaces 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 Copyright © 2012 by CSI International 5.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 2 Variables, Literals, and System Constants This example defines COMPANY as a character field, 32 characters long. This field appears in a Report Writer report under the heading CUSTOMER NAME (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 Copyright © 2012 by CSI International 5.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants 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. 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 uservarname(n) where uservarname Is the name of the user variable that is an array. n Is 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 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 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) Copyright © 2012 by CSI International 5.8 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants 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). SET SET SET SET SET SET SET SET SET SET SET SET INDEXing by INDEX Value MONTH(1) = 'JAN' MONTH(2) = 'FEB' MONTH(3) = 'MAR' MONTH(4) = 'APR' MONTH(5) = 'MAY' MONTH(6) = 'JUN' MONTH(7) = 'JUL' MONTH(8) = 'AUG' MONTH(9) = 'SEP' MONTH(10) = 'OCT' MONTH(11) = 'NOV' MONTH(12) = 'DEC' 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) 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 user variable 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 (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= 1 SET MONTH= 'JAN' Copyright © 2012 by CSI International 5.9 DATAMINER FOR Z/OS 7.1C User Reference Guide SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET INDEXing by Bytes Offset NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= Variables, Literals, and System Constants 2 'FEB' 3 'MAR' 4 'APR' 5 'MAY' 6 'JUN' 7 'JUL' 8 'AUG' 9 'SEP' 10 'OCT' 11 'NOV' 12 '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: 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 user variable array’s name with the index name subscripted. In the current example, you address the each member like this: MONTH(NUM) 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. Copyright © 2012 by CSI International 5.10 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants 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). SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET NUM= 0 MONTH(NUM)='JAN' NUM= 3 MONTH(NUM)='FEB' NUM= 6 MONTH(NUM)='MAR' NUM= 9 MONTH(NUM)='APR' NUM= 12 MONTH(NUM)='MAY' NUM= 15 MONTH(NUM)='JUN' NUM= 18 MONTH(NUM)='JUL' NUM= 21 MONTH(NUM)='AUG' NUM= 24 MONTH(NUM)='SEP' NUM= 27 MONTH(NUM)='OCT' NUM= 30 MONTH(NUM)='NOV' NUM= 33 MONTH(NUM)='DEC' Copyright © 2012 by CSI International 5.11 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants 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. Copyright © 2012 by CSI International 5.12 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants Variable Description 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. Copyright © 2012 by CSI International 5.13 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants Variable Description 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. Copyright © 2012 by CSI International 5.14 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants 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. Copyright © 2012 by CSI International 5.15 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants 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 nnn Is 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 nnnn Is any even number of hexadecimal digits (0–9, A–F). Hexadecimal literals cannot contain decimal places. For example: X'1FA2' Copyright © 2012 by CSI International 5.16 DATAMINER FOR Z/OS 7.1C User Reference Guide Binary Variables, Literals, and System Constants Use binary literals for fixed-point binary numbers. Specify a binary literal as follows: B'nnn' where nnn Is 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 Copyright © 2012 by CSI International 5.17 DATAMINER FOR Z/OS 7.1C User Reference Guide Variables, Literals, and System Constants System Constants DATAMINER has a number of system constants that you can refer to in your script. 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 Do not modify these system constants because they are used internally by DATAMINER, and the effect of changing them is unpredictable. Copyright © 2012 by CSI International 5.18 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.” This chapter covers the following topics: Page Shortcut Commands Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 COPY Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3 UPDATE Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5 EXTRACT Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.6 PRINT Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.8 DUMP Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.12 DELETE Shortcut Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.14 HD Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.15 MAXLN= Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.16 SELECT…[WHERE] Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . 6.17 TOT Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.20 Copyright © 2012 by CSI International 6.1 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 • • • • • • • What Makes a Shortcut Command COPY it UPDATE it EXTRACT from it PRINT it DUMP it DELETE records from it Combine some of these functions 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 Constraints Except for UPDATE, the Shortcut Commands do not use parameters. 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. Copyright © 2012 by CSI International 6.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands 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. Copyright © 2012 by CSI International 6.3 DATAMINER FOR Z/OS 7.1C User Reference Guide COPY Example 1 Shortcut Commands The following example copies all records from from the EMPVSAM dataset to the EMPESDS dataset: COPY INPUT=VSAM FILENAME=EMPVSAM OUTPUT=VSAM FILENAME=EMPESDS COPY Example 2 /* Copy /* Input KSDS file /* Ouput ESDS file The following example copies only records containing employees in department D11: COPY INPUT=VSAM FILENAME=EMPVSAM WORKDEPT 35,3,C OUTPUT=VSAM FILENAME=EMPESDS WHERE WORKDEPT = 'D11' /* /* /* /* /* Copy Input KSDS file Define department field Ouput ESDS file Copy department D11 records Copyright © 2012 by CSI International 6.4 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands 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. The syntax for the UPDATE Shortcut Command is Syntax UPDATE UPDATE Example The following example increase salaries for all employees by 5 percent in department D11: UPDATE INPUT=VSAM FILENAME=EMPVSAM WORKDEPT 35,3,C SALARY 73,5,P,2 /* /* /* /* WHERE WORKDEPT = 'D11' SALARY = SALARY * 1.05 /* Update department D11 records /* Increase salary by 5% Other Requirements Update Input KSDS file Define department field Define salary field 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. Copyright © 2012 by CSI International 6.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands EXTRACT Shortcut Command 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. Description 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. The syntax for the EXTRACT Shortcut Command is Syntax 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 INPUT=VSAM FILENAME=EMPVSAM EMPNO *,6,C FIRSTNME *,12,C MIDINIT *,1,C LASTNAME *,15,C WORKDEPT *,3,C PHONENO *,4,C OUTPUT=VSAM FILENAME=EMPESDS /* /* /* /* /* /* /* /* /* Extract selected fields Input KSDS file Employee number First name Middle initial Last name Department number' Phone number Ouput ESDS file SELECT FIRSTNME,LASTNAME,PHONENO /* Extract only selected fields Copyright © 2012 by CSI International 6.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Script Example 2: Using MOVE Shortcut Commands 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 fields INPUT=VSAM FILENAME=EMPVSAM /* Input KSDS file OUTPUT=VSAM FILENAME=EMPESDS /* Ouput ESDS file EMPNO *,6,C FIRSTNME *,12,C MIDINIT *,1,C LASTNAME *,15,C WORKDEPT *,3,C PHONENO *,4,C /* /* /* /* /* /* Employee number First name Middle initial Last name Department number' Phone number MOVE EMPVSAM:FIRSTNME TO EMPESDS:FIRSTNME MOVE EMPVSAM:LASTNAME TO EMPESDS:LASTNAME MOVE EMPVSAM:PHONENO TO EMPESDS:PHONENO 00000000 0000C3C8 D9C9E2E3 C9D5C540 404000C8 C1C1E240 40404040 40404040 40400000 00F3F9F7 F8 *......CHRISTINE * ...3978 .HAAS 00000000 0000D4C9 C3C8C1C5 D3404040 404000E3 C8D6D4D7 E2D6D540 40404040 40400000 00F3F4F7 F6 *......MICHAEL * ...3476 .THOMPSON 00000000 0000E2C1 D3D3E840 40404040 404000D2 E6C1D540 40404040 40404040 40400000 00F4F7F3 F8 *......SALLY * ...4738 .KWAN 00000000 0000D1D6 C8D54040 40404040 404000C7 C5E8C5D9 40404040 40404040 40400000 00F6F7F8 F9 *......JOHN * ...6789 .GEYER Copyright © 2012 by CSI International 6.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands PRINT Shortcut Command Description The PRINT Shortcut Command prints the contents of records, as follows: Using PRINT with ... Prints from ... COPY Output datasets EXTRACT UPDATE Input datasets 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. Copyright © 2012 by CSI International 6.8 DATAMINER FOR Z/OS 7.1C User Reference Guide Syntax Shortcut Commands 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. PRINT INPUT=VSAM FILENAME=BILLING ACCT-NO 1 8 C NAME 9 32 C ADDRESS 100 55 C BALANCE 240 10 P 2 SELECT (ACCT-NO NAME ADDRESS BALANCE) Each line in this script is explained below. PRINT Tells 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. Copyright © 2012 by CSI International 6.9 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands INPUT=VSAM FILENAME=BILLING Identifies the input dataset as a VSAM dataset named BILLING. ACCT-NO 1 8 C Defines 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 C Defines 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 C Defines 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 2 Defines 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 ACCT-NO 12345678 33333333 44444444 NAME BLOGGS INC JONES LLC ALBRECHT 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: ADDRESS 47 MAIN ST 96 ANYWHERE ST 62 DURER AVE BALANCE 426.65 12,217.32 0.00 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).” Copyright © 2012 by CSI International 6.10 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands • 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. PRINT INPUT=VSAM FILENAME=EMPVSAM EMPNO *,6,C FIRSTNME *,12,C MIDINIT *,1,C LASTNAME *,15,C WORKDEPT *,3,C PHONENO *,4,C SALARY 73,5,P,2 /* /* /* /* /* /* /* /* /* SELECT FIRSTNME,LASTNAME,SALARY WHERE WORKDEPT = 'D11' /* Print only selected fields /* Print department D11 records Example 2 Output Print selected fields Input KSDS file Employee number First name Middle initial Last name Department number' Phone number Define salary field The output from the above script could look something like this: FIRSTNME LASTNAME SALARY IRVING BRUCE ELIZABETH MASATOSHI MARILYN JAMES DAVID WILLIAM JENNIFER STERN ADAMSON PIANKA YOSHIMURA SCOUTTEN WALKER BROWN JONES LUTZ 32250.00 25280.00 22250.00 24680.00 21340.00 20450.00 27740.00 18270.00 29840.00 Note You can use the MAXRCDS= command (page 9.18) to set the maximum number of records to print. Copyright © 2012 by CSI International 6.11 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands 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: Using DUMP with ... Dumps from the ... COPY Output dataset EXTRACT UPDATE Input dataset 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 Copyright © 2012 by CSI International 6.12 DATAMINER FOR Z/OS 7.1C User Reference Guide DUMP Example Shortcut Commands The following example dumps all records containing employees in department D11: DUMP INPUT=VSAM FILENAME=EMPVSAM WORKDEPT 35,3,C /* Dump /* Input KSDS file /* Define department field WHERE WORKDEPT = 'D11' /* Dump department D11 records only The output could look something like this: RECORD NUMBER - IN= 1 F0F0F0F0 33 4040C4F1 65 F4F560F0 97 00000000 RECORD NUMBER - IN= 1 F0F0F0F1 33 4040C4F1 65 F4F760F0 97 00000000 RECORD NUMBER - IN= 1 F0F0F0F1 33 4040C4F1 65 F5F560F0 97 00000000 5,OUT= 1 LRECL= 100 F6F0C9D9 E5C9D5C7 40404040 4040C6E2 E3C5D9D5 40404040 40404040 F1F6F4F2 F3F1F9F7 F360F0F9 60F1F4D4 C1D5C1C7 C5D94000 10D4F1F9 F760F0F7 00373334 1C000390 200C0002 58000C00 00000000 00000000 17,OUT= 2 LRECL= 100 F5F0C2D9 E4C3C540 40404040 404040C1 C4C1D4E2 D6D54040 40404040 F1F4F5F1 F0F1F9F7 F260F0F2 60F1F2C4 C5E2C9C7 D5C5D900 10D4F1F9 F560F1F7 00292647 6C000380 200C0002 02200C00 00000000 00000000 18,OUT= 3 LRECL= 100 F6F0C5D3 C9E9C1C2 C5E3C840 4040D9D7 C9C1D5D2 C1404040 40404040 F1F3F7F8 F2F1F9F7 F760F1F0 60F1F1C4 C5E2C9C7 D5C5D900 11C6F1F9 F460F1F2 00257571 6C000370 200C0001 78000C00 00000000 00000000 Copyright © 2012 by CSI International 6.13 *000060IRVING FSTERN * * D1164231973-09-14MANAGER .~M19* *45-07-07.~~~~.~°~~.~ì.~.........* *.... * *000150BRUCE ADAMSON * * D1145101972-02-12DESIGNER.~M19* *47-05-17.~~å%.~Ø~~.~~~~.........* *.... * *000160ELIZABETH RPIANKA * * D1137821977-10-11DESIGNER.~F19* *55-04-12.~ÍÉ%.~ø~~.~Ì.~.........* *.... * DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands DELETE Shortcut Command 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. Description Delete functions modify the input datasets and do not create output datasets, so no output dataset definition is required in the script. The syntax for the DELETE Shortcut Command is Syntax 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 INPUT=VSAM FILENAME=EMPVSAM WORKDEPT 35,3,C /* Delete /* Input KSDS file /* Define department field WHERE WORKDEPT = 'D11' /* Delete department D11 records Copyright © 2012 by CSI International 6.14 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands HD Subcommand Description The HD command changes data in the printed heading. Note Syntax This command does not apply to the DATAMINER Report Writer. 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. colnum Is 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 Copyright © 2012 by CSI International 6.15 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands 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 Syntax This command does not apply to the DATAMINER Report Writer. The syntax for the MAXLN= command is MAXLN={numlines | 60} where numlines Is 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 Copyright © 2012 by CSI International 6.16 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands 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 fieldname Is a record field name or a table field name. uservar Is a user variable. sysvar Is a system variable. sysconst Is 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. Copyright © 2012 by CSI International 6.17 DATAMINER FOR Z/OS 7.1C User Reference Guide WHERE Statement Syntax Shortcut Commands 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 fieldname4 Are names of fields in the current record. uservar, uservar2, uservar3, and uservar4 Are names of existing user variables. sysvar, sysvar2, sysvar3, and sysvar4 Are names of system variables. sysconst and sysconst2 Are names of system constants. 'literal' and 'literal2' Are literals, which must follow the rules for literals. See “Literals” (page 5.15). reloper Is 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. PREV Is 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. Copyright © 2012 by CSI International 6.18 DATAMINER FOR Z/OS 7.1C User Reference Guide 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 Example 2 Shortcut Commands < '1000' 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. EXTRACT KEY 1,8,C AMT 12,7,P NAME 30,20,C PHONE 90,10,C FLAG 130,1,C SELECT (KEY, AMT, NAME, PHONE) * the record is now 99 bytes long IF AMT LT 0 MOVE 'X' TO FLAG * THIS MAKES SOME RECORDS 130 * BYTES LONG ENDIF 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) ENDIF IF TYPE EQ 'Y' SELECT (ACCNO,TYPE,NAME) ENDIF Copyright © 2012 by CSI International 6.19 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands 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 Syntax This command does not apply to Report Writer scripts. 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. colnum Is the column number (1 through 132) where the first character of literal or fieldname goes. fieldname Is the name of a field whose total you want to print. fieldlength Is the length of the same field. [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 defined for the field. M1 9(13)M2 9(11).99- Copyright © 2012 by CSI International 6.20 DATAMINER FOR Z/OS 7.1C User Reference Guide Shortcut Commands 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. • If any significant high-order digits are truncated when using the M5 mask, the $ (dollar sign) is lost. • 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 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 TOT TOT TOT TOT TOT '+ve balance records =',10 PLUSRECS,8,30,M1 '-ve balance records =',10 NEGRECS,8,30,M1 'Zero balance records =',10 ZERORECS,8,30,M1 Copyright © 2012 by CSI International 6.21 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International 6.22 Shortcut Commands 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. This chapter covers the following topics: Page Dataset Reading Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2 READ Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.3 POINT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.5 WRITE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.6 Examples of READing and WRITEing Data. . . . . . . . . . . . . . . . . . . . . 7.8 INSERT INTO…VALUES Command. . . . . . . . . . . . . . . . . . . . . . . . . 7.12 DISPLAY Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.14 Copyright © 2012 by CSI International 7.1 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. Copyright © 2012 by CSI International 7.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Dataset Reading and Writing 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 filename Is 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. Copyright © 2012 by CSI International 7.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Dataset Reading and Writing 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: 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. Note The FILE-STATUS system variable is set to '000' for a successful read or write. Copyright © 2012 by CSI International 7.4 DATAMINER FOR Z/OS 7.1C User Reference Guide Dataset Reading and Writing 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 filename Is the ddname of a dataset specified on an INPUT= command. [ = | EQ | >= | GE] Is a relational operator, one of only the following: Symbol Alphabetic Meaning = EQ “is equal to” >= GE “is greater than or equal to” (the default) { 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. Copyright © 2012 by CSI International 7.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Dataset Reading and Writing 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 filename Is the ddname of the dataset to which data will be written. filename1 Is an optional data source. ADD Is 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. Copyright © 2012 by CSI International 7.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Dataset Reading and Writing DELETE Deletes the current record for a keyed dataset. Example The following example writes to the dataset FILE1: WRITE FILE1 Copyright © 2012 by CSI International 7.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Dataset Reading and Writing 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. COPY INPUT=VSAM FILENAME=INFILE OUTPUT=VSAM FILENAME=OUTFILE OUTPUT=DISK FILENAME=NEGFILE VARBLK BLKSIZE=16000 LRECL=1000 DETAIL 1 1000 C BALANCE 98 10 P IF BALANCE < 0 MOVE INFILE:DETAIL TO NEGFILE:DETAIL WRITE 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 FIXED ACCT-NO 1 8 C BALANCE 98 10 P OUTPUT=VSAM FILENAME=NEWFILE NEWACCT 1 8 C ADDRESS 9 300 C BALANCE 400 12 P INPUT=VSAM FILENAME=CUSTFL ADDRESS 200 300 C READNEXT. READ INFILE IF INFILE:IO-RESULT = 'EOF' GOTO FINISHED ENDIF Copyright © 2012 by CSI International 7.8 DATAMINER FOR Z/OS 7.1C User Reference Guide Dataset Reading and Writing IF INFILE:BALANCE < 0 READ CUSTFL KEY ACCT-NO IF CUSTFL:IO-RESULT = 'NFD' GOTO NOCUST ENDIF MOVE ACCT-NO TO NEWACCT MOVE INFILE:BALANCE TO NEWFILE:BALANCE MOVE CUSTFL:ADDRESS TO NEWFILE:ADDRESS WRITE NEWFILE NOCUST. ENDIF GOTO READNEXT FINISHED. 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 Copyright © 2012 by CSI International 7.9 DATAMINER FOR Z/OS 7.1C User Reference Guide Dataset Reading and Writing UPDATE-FLAG = 'N' /* Initialize update flag IF EMPVSAM:IO-RESULT = 'EOF' GOTO FINISHED ENDIF /* End script on EOF IF WORKDEPT = 'E11' SALARY = SALARY * 1.05 UPDATE-FLAG = 'Y' ENDIF /* Check for department E11 /* Bump salary by 5% /* Indicate update required IF HIREDATE-YYYY = '2011' MOVE 1000 TO BONUS UPDATE-FLAG = 'Y' ENDIF /* Check for 2011 hires /* Set bonus to 1000 /* Indicate update required IF UPDATE-FLAG = 'Y' WRITE EMPVSAM REPLACE /* Check if update required /* Update employee record /* Write out update log to printer DISPLAY 'EMPLOYEE UPDATED' EMPNO 'SALARY' SALARY 'BONUS' BONUS ENDIF GOTO READNEXT FINISHED. 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 READNEXT. READ EMPVSAM UPDATE-FLAG = 'N' /* Define a user variable /* Read employee dataset /* Init update flag IF EMPVSAM:IO-RESULT = 'EOF' Copyright © 2012 by CSI International 7.10 DATAMINER FOR Z/OS 7.1C User Reference Guide GOTO FINISHED ENDIF IF WORKDEPT = 'E11' SALARY = SALARY * 1.05 UPDATE-FLAG = 'Y' ENDIF Dataset Reading and Writing /* End script on EOF /* Check for department E11 /* Bump salary by 5% /* Indicate update required IF HIREDATE-YYYY = '2011' MOVE 1000 TO BONUS UPDATE-FLAG = 'Y' ENDIF /* Check for 2011 hires /* Set bonus to 1000 /* Indicate update required IF UPDATE-FLAG = 'Y' WRITE EMPVSAM REPLACE /* Check if update required /* Update employee record /* Write out update log to printer DISPLAY 'EMPLOYEE UPDATED' EMPNO 'SALARY' SALARY 'BONUS' BONUS ENDIF GOTO READNEXT FINISHED. Copyright © 2012 by CSI International 7.11 DATAMINER FOR Z/OS 7.1C User Reference Guide Dataset Reading and Writing 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 file Is the name of the file into which you are inserting records. recfieldname Is 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. value Is 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. Copyright © 2012 by CSI International 7.12 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 1 Dataset Reading and Writing 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=KSDSIN KEY 1,4,C CNTR 27,3,P PACKED 60,4,P,2 REST 64,10,C INSERT 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') Copyright © 2012 by CSI International 7.13 DATAMINER FOR Z/OS 7.1C User Reference Guide Dataset Reading and Writing 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 datasetname Is the ddname of the dataset to which the data is to be output. NEWPAGE Specifies to start a new page before printing the data. numlines Is the number of lines to SKIP before printing the data. controlchar Is 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). colnum Is the column number for the current field to start in. +coltoright Specifies the number of columns to the right of the previous field to start the current field in. -coltoleft Specifies the number of columns to the left of the end of the previous field to start the current field in. Copyright © 2012 by CSI International 7.14 DATAMINER FOR Z/OS 7.1C User Reference Guide Example Dataset Reading and Writing The following example displays literals plus the value of variable EMPNO: DISPLAY 'Salary for employee number ' EMPNO 'is' SALARY Copyright © 2012 by CSI International 7.15 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International 7.16 Dataset Reading and Writing 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. This chapter covers the following topics: Page Relational Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2 IF…[ELSE]…ENDIF Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.3 DO WHILE and ENDDO Statements . . . . . . . . . . . . . . . . . . . . . . . . . . 8.6 PROC…[GOBACK]…ENDPROC Statements (Defining Procedures) 8.8 PERFORM Command (Call a Procedure) . . . . . . . . . . . . . . . . . . . . . . 8.10 Labels and GOTO Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.11 EXIT Command (Escape a Script). . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.13 CALL…[USING] Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.14 Timing Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.15 Copyright © 2012 by CSI International 8.1 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: 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” In some cases, which are noted in the explanations of syntax statements, not all relational operators are permitted. Copyright © 2012 by CSI International 8.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control 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 { fieldname2 | uservar2 | sysvar2 | sysconst | 'literal' | PREV } ... [ ELSE ] ENDIF where fieldname, fieldname2 Are names of fields in the current record. uservar, uservar2 Are names of existing user variables. sysvar, sysvar2 Are names of system variables. sysconst Is the name of a system constant. 'literal' Is a literal, which must follow the rules for literals. See “Literals” (page 5.15). reloper Is 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, 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. PREV Is the keyword PREV, which signifies the value of fieldname in the previous record. Copyright © 2012 by CSI International 8.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control 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. 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 } ] ... [ ELSE ] 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 = 10 MOVE 'EXFILE' TO TEMP2 ENDIF Copyright © 2012 by CSI International 8.4 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 2 Conditions and Flow Control In this example, the script puts YES in WORD if FLDA has Y in it; otherwise, it puts NO in WORD. FLDA 3,1,C WORD 65 3 C IF FLDA = 'Y' MOVE 'YES' TO WORD ELSE MOVE "NO" TO WORD ENDIF 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' OLDFLAG GOTO DONTADD ENDIF ADD 1 TO TOTAL DONTADD. The following example is the same but uses a “not equal” condition: IF FLAG NE 'A' 'C' 'F' OLDFLAG ADD 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' Copyright © 2012 by CSI International 8.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control 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 } ENDDO where fieldname, fieldname2 Are names of fields in the current record. uservar, uservar2 Are names of existing user variables. sysvar, sysvar2 Are names system variables. sysconst, sysconst2 Are names of system constants. 'literal', 'literal2' Are literals, which must follow the rules for literals. See “Literals” (page 5.15). reloper Is 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. PREV Is the keyword PREV, which sginifies the value of fieldname in the previous record. Is one or more commands that DATAMINER performs if the condition evaluates to TRUE. Generally, the commands affect only the current Copyright © 2012 by CSI International 8.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control 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 { fieldname2 | uservar2 | sysvar2 | sysconst2 | 'literal2' | PREV } [ AND | OR { fieldname3 | uservar3 | sysvar3 | sysconst3 | 'literal3' } reloper { fieldname4 | uservar4 | sysvar4 | sysconst4 | 'literal4' | PREV } ] ... ENDDO Example This is an example of the DO WHILE and ENDDO commands: DO WHILE BALANCE >= 0 READ 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. Copyright © 2012 by CSI International 8.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control 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 [GOBACK] [] ENDPROC where procname Is 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. Copyright © 2012 by CSI International 8.8 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control Do not begin procname with any of the following strings because DATAMINER’s own field names begin with them: @#_ DMIN DMIN_ and Are each one or more DATAMINER commands. GOBACK Is the instruction to escape the procedure and go back to the line following the line that called the procedure. Example PERFORM DOCALCS PROC DOCALCS ADD AMOUNT TO TOTAL ADD SALARY TO YTD ENDPROC 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 ADDIT IF AMOUNT < 0 GOBACK ENDIF ADD AMOUNT TO TOTAL ENDPROC Copyright © 2012 by CSI International 8.9 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control 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 procname Is the name of your procedure. After the procedure is executed, control returns to the line in your script after the PERFORM. Copyright © 2012 by CSI International 8.10 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control 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 Copyright © 2012 by CSI International 8.11 DATAMINER FOR Z/OS 7.1C User Reference Guide Syntax for GOTO Conditions and Flow Control The syntax for GOTO is GOTO labelnam where labelnam Is 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 >500 GOTO ANCIENT ENDIF ANCIENT. Notice that the label in the GOTO statement and label statement are the same. Copyright © 2012 by CSI International 8.12 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control 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 > 0 EXIT 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. Copyright © 2012 by CSI International 8.13 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control 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 progname Is the name of the phase or of the load module you want to run. fieldname Is the name of a field in the current record. uservar Is the name of an existing user variable to pass to progname. sysvar Is the name of a system variable to pass to progname. sysconst Is the name of a system constant to pass to progname. 'literal' Is a literal, which must follow the rules for literals. See “Literals” (page 5.15). 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 Copyright © 2012 by CSI International 8.14 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control 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. Copyright © 2012 by CSI International 8.15 DATAMINER FOR Z/OS 7.1C User Reference Guide Conditions and Flow Control 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 NAME BEFORE INPUT READ CTLFILE KEY 'HEADER' DURING OUTPUT 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 NAME DURING INPUT SKIP AMOUNT < 0 DURING OUTPUT ADD AMOUNT TO TOTAMT AFTER OUTPUT DISPLAY '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 TIMING DURING OUTPUT SKIP AMOUNT <0 ADD AMOUNT TO TOTAMT AFTER OUTPUT DISPLAY 'TOTAL AMOUNT IS ' TOTAMT Copyright © 2012 by CSI International 8.16 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 4 (Without SORT) Conditions and Flow Control 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. COPY INPUT=VSAM FILENAME=INACCT * FIELD DEFINITIONS GO HERE OUTPUT=VSAM FILENAME=OUTACCT DURING OUTPUT IF NAME = 'MERGUTROID' ADD AMOUNT TO T1 ENDIF DURING OUTPUT SKIP AMOUNT < 0 OR NAME='FORD' AFTER OUTPUT DISPLAY 'TOTAL MERGUTROID AMOUNT IS ' T1 Copyright © 2012 by CSI International 8.17 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International 8.18 Conditions and Flow Control 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. This chapter covers the following topics: Page Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2 FIRSTKEY Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.4 FIRST= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.5 LAST= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.6 FREQ= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.7 KEEP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.8 DROP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.9 START Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.10 STOP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.12 SKIP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.14 ONLY (or WHERE) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.16 MAXRCDS= Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.18 Copyright © 2012 by CSI International 9.1 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 Execution Order If you use these commands to select entire records, you do not need to define the fields in those records. 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. Copyright © 2012 by CSI International 9.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Note Record-Selection Rules Record-Selection Commands 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. 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. Copyright © 2012 by CSI International 9.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands 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 reloper Is a relational operator. See “Relational Operators” (page 8.2). relkey Is a value according to the following table: Examples 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 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' Copyright © 2012 by CSI International 9.4 DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands 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 recnum Is 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 Copyright © 2012 by CSI International 9.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands 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 Syntax FIRST= and LAST= commands can be used in the same script together or individually, without the other command. The syntax fo the LAST= command is LAST= recnum where recnum Is the record number of the last 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 stop reading records as soon as it reads record number 200. This record is the last record that is processed. LAST=200 Copyright © 2012 by CSI International 9.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands 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. 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. 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=50 FREQ=10 Copyright © 2012 by CSI International 9.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands 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 > 50 KEEP ELSE DROP ENDIF You can change the decision to KEEP or DROP a record by using a later record-selection command. Copyright © 2012 by CSI International 9.8 DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands 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 > 50 KEEP ELSE DROP ENDIF You can change the decision to KEEP or DROP a record by using a later record-selection command. Copyright © 2012 by CSI International 9.9 DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands 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 fieldname, fieldname2 Are names of fields in the current record. uservar, uservar2 Are names of existing user variables. sysvar, sysvar2 Are names of system variables. sysconst, sysconst2 Are names of system constants. 'literal', 'literal2' Are literals, which must follow the rules for literals. See “Literals” (page 5.15). reloper Is 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. PREV Is the keyword PREV, which sginifies the value of fieldname in the previous record. Example The following example begins processing with the records whose ACCNO contains a value greater than 12345. START ACCNO > '12345' Copyright © 2012 by CSI International 9.10 DATAMINER FOR Z/OS 7.1C User Reference Guide Alternative Syntax Record-Selection Commands 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 { fieldname2 | uservar2 | sysvar2 | sysconst2 | 'literal2' | PREV } [ AND | OR { fieldname3 | uservar3 | sysvar3 | sysconst3 | 'literal3'} reloper { fieldname4 | uservar4 | sysvar4 | sysconst4 | 'literal4' | PREV } ] ... 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' Copyright © 2012 by CSI International 9.11 DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands 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 fieldname, fieldname2 Are names of fields in the current record. uservar, uservar2 Are names of existing user variables. sysvar, sysvar2 Are names system variables. sysconst, sysconst2 Are names of system constants. 'literal', 'literal2' Are literals, which must follow the rules for literals. See “Literals” (page 5.15). reloper Is 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. PREV Is the keyword PREV, which sginifies the value of fieldname in the previous record. 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 Copyright © 2012 by CSI International 9.12 DATAMINER FOR Z/OS 7.1C User Reference Guide Alternative Syntax Record-Selection Commands Alternatively, you can repeat a fieldname, relational operator, and a single condition indefinitely. This syntax is as follows: STOP { fieldname | uservar | sysvar | sysconst | 'literal'} reloper { fieldname2 | uservar2 | sysvar2 | sysconst2 | 'literal2' | PREV } [ AND | OR { fieldname3 | uservar3 | sysvar3 | sysconst3 | 'literal3'} reloper { fieldname4 | uservar4 | sysvar4 | sysconst4 | 'literal4' | PREV } ] ... 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' Copyright © 2012 by CSI International 9.13 DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands 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 fieldname, fieldname2 Are names of fields in the current record. uservar, uservar2 Are names of existing user variables. sysvar, sysvar2 Are names system variables. reloper Is 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. PREV Is the keyword PREV, which sginifies the value of fieldname in the previous record. 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. Copyright © 2012 by CSI International 9.14 DATAMINER FOR Z/OS 7.1C User Reference Guide Note Record-Selection Commands 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 ADD 1000 AMOUNT ONLY AMOUNT >500 Alternative Syntax /* /* /* /* /* /* The record is being skipped. AMOUNT is now 1000, but it is still being skipped. AMOUNT is greater than 500 so the record is no longer being skipped. Alternatively, you can repeat a fieldname, relational operator, and a single condition indefinitely. This syntax is as follows: SKIP { fieldname | uservar | sysvar | sysconst | 'literal' } reloper { fieldname2 | uservar2 | sysvar2 | sysconst2 | 'literal2' | PREV } [ AND | OR { fieldname3 | uservar3 | sysvar3 | sysconst3 | 'literal3' } reloper { fieldname4 | uservar4 | sysvar4 | sysconst4 | 'literal4' | PREV } ] ... Copyright © 2012 by CSI International 9.15 DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands 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 { fieldname2 | uservar2 | sysvar2 | sysconst | 'literal' | PREV } ... where fieldname, fieldname2 Are names of fields in the current record. uservar, uservar2 Are names of existing user variables. sysvar, sysvar2 Is the name of a system variable. sysconst, sysconst2 Are names of system constants. 'literal' Is a literal, which must follow the rules for literals. See “Literals” (page 5.15). reloper Is one of the relational operators (page 8.2). 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. PREV Is the keyword PREV, which signifies the value of fieldname in the previous record. 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 Copyright © 2012 by CSI International 9.16 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 2 Record-Selection Commands 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 { fieldname2 | uservar2 | sysvar2 | sysconst2 | 'literal2' | PREV } [ AND | OR { fieldname3 | uservar3 | sysvar3 | sysconst3 | 'literal3' } reloper { fieldname4 | uservar4 | sysvar4 | sysconst4 | 'literal4' | PREV } ] ... Copyright © 2012 by CSI International 9.17 DATAMINER FOR Z/OS 7.1C User Reference Guide Record-Selection Commands 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 numrecs Is 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 Copyright © 2012 by CSI International 9.18 10 Data Manipulation Commands You can use data manipulation commands to modify data before you write it out to the output dataset. This chapter covers the following topics: 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 Copyright © 2012 by CSI International 10.1 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. Copyright © 2012 by CSI International 10.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands • 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. Copyright © 2012 by CSI International 10.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands 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 Syntax DATAMINER does “propagating moves” when moving overlapping character or hexadecimal fields. The syntax for the MOVE command is MOVE {field | 'literal' | var} TO field2 where field Is a record field or table field. Copyright © 2012 by CSI International 10.4 DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands 'literal' Is a literal. For information about literals, see “Literals” (page 5.15). var Is a user variable or system variable. field2 Is the destination record field for the value. Copyright © 2012 by CSI International 10.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands 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, field2 Are 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# literal Is a literal, which must follow the rules for literals. See “Literals” (page 5.15). arith_expr Is 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' Copyright © 2012 by CSI International 10.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands 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 fieldname Is the name of a record field. Example The following example fills the numeric field BALANCE with zeros: HIDE BALANCE Copyright © 2012 by CSI International 10.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands 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 Copyright © 2012 by CSI International 10.8 DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands 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 PRICE MULTIPLY 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. Copyright © 2012 by CSI International 10.9 DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands 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 field Is a record field, user variable, system variable, or system constant. literal Is a literal. (See “Literals” [page 5.15].) field2 Is 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 Copyright © 2012 by CSI International 10.10 DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands 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 field Is a record field, user variable, system variable, or system constant. 'literal' Is a literal. (See “Literals” [page 5.15].) field2 Is 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 Copyright © 2012 by CSI International 10.11 DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands 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 field Is a record field or user variable. field2 Is a record field, user variable, system variable, or system constant. 'literal' Is a literal. (See “Literals” [page 5.15].) 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 Copyright © 2012 by CSI International 10.12 DATAMINER FOR Z/OS 7.1C User Reference Guide Data Manipulation Commands 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 field Is a record field or user variable. field2 Is a record field, user variable, system variable, or system constant. 'literal' Is a literal. (See “Literals” [page 5.15].) 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 Copyright © 2012 by CSI International 10.13 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International 10.14 Data Manipulation Commands 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.2 Creating a Report Writer Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 Defining Field Formats and Headings in a Report . . . . . . . . . . . . . . . . . . 11.6 Adding a User-Defined Mask to a Field Definition . . . . . . . . . . . . . . . . . 11.7 Using the REPORT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.8 REPORT Subcommands Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.10 ACROSS, WIDTH, and HEIGHT Subcommands . . . . . . . . . . . . . . . . . .11.11 ADVANCE Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.12 AVG Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.13 BREAK (or CONTROL) Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . 11.14 GAP Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.16 HEADING Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.17 LABELS Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.18 LENGTH Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.19 LINE Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.20 NODATE and NOPAGE Subcommands . . . . . . . . . . . . . . . . . . . . . . . . 11.22 ORDER (or SEQUENCE) Subcommand. . . . . . . . . . . . . . . . . . . . . . . . 11.23 PRINTER Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.26 SPACING Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.27 SUM Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.28 SUMMARY Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.29 TITLE Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.30 Report Formatting—Simple to Complex . . . . . . . . . . . . . . . . . . . . . . . . 11.32 Additional Report Writer Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.41 Copyright © 2012 by CSI International 11.1 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. Copyright © 2012 by CSI International 11.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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.” Copyright © 2012 by CSI International 11.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Step 4—Select Records Report Writer 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. Copyright © 2012 by CSI International 11.4 DATAMINER FOR Z/OS 7.1C User Reference Guide Script Example INPUT=DISK Report Writer The following script produces a sales report sorted by department. This example illustrates the steps you must follow to create a Report Writer script. 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 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. ******************************************** * Wrap PRINT in an IF statement * to select records for printing IF CUST-NO >= 50000000 DISC-VAL = VALUE SUBTRACT DISCOUNT FROM DISC-VAL 4. Add record-selection logic (optional). 5. Perform data manipulation (optional). 6. Print the report defined by PRINT SALES-REPORT ENDIF the REPORT command. ******************************************** 7. Define the report name and REPORT SALES-REPORT layout, letting DATAMINER do TITLE ("DEPARTMENTAL SALES REPORT" "WITH DISCOUNTS") most of the work. Use REPORT LINE DEPT CUST-NO VALUE DISCOUNT DISC-VAL subcommands, placing them ORDER DEPT after the REPORT command. Copyright © 2012 by CSI International 11.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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. Copyright © 2012 by CSI International 11.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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-definition Is 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-mask Is a mask string you create using the following components: Example 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 123456.” is displayed as “ * 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. 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' Copyright © 2012 by CSI International 11.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 name Is a name you assign to identify this report. You can define and print multiple reports in a single Report Writer script. output-dataset Is 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). field Is 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). Copyright © 2012 by CSI International 11.8 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer n Is 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: LINE Statements Subpage Structure LINE EMPNUM ':' DEPT LINE 4 CITY ZIP LINE 3 FIRST LAST Line 1: Line 2: Line 3: Line 4: EMPNUM : DEPT [blank line] FIRST LAST CITY ZIP subcommand Is 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. Copyright © 2012 by CSI International 11.9 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 Copyright © 2012 by CSI International 11.10 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 numlables Is the number of labels to print across a page. The default is 1. numcols Is 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. numlines Is 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 Copyright © 2012 by CSI International 11.11 HEIGHT 6 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 numlines Is 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 Copyright © 2012 by CSI International 11.12 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 field Is 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 Copyright © 2012 by CSI International 11.13 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 field Is 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. NEWPAGE Tells DATAMINER to skip to a new page whenever a break occurs and print the headers and titles you defined on each new page. RENUM Is 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. Copyright © 2012 by CSI International 11.14 DATAMINER FOR Z/OS 7.1C User Reference Guide Example Report Writer 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 Copyright © 2012 by CSI International 11.15 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 numcols Is 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 Copyright © 2012 by CSI International 11.16 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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' Copyright © 2012 by CSI International 11.17 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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. Copyright © 2012 by CSI International 11.18 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 numlines Is the number of lines to print per page. sys-default Is 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=DEPTFILE INCLUDE 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) Copyright © 2012 by CSI International 11.19 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 255 Is 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. recfieldname Is the name of a field in a record. uservar Is the name of a user variable. See “Defining User Variables (DEFINE Command)” on page 5-3. sysvar Is the name of a system variable. See “System Variables” on page 5-12. sysconst Is 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. +/-numspaces Is the number of space to add (+) or subtract (-) from the default 3 spaces between columns. Copyright © 2012 by CSI International 11.20 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer colnum Is the first column number of the next item (such as a record field or variable) specified in this LINE definition. TALLY The 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=DEPTFL FIRST 4,12,C HEADING ('FIRST' 'NAME') LAST *,16,C DEPT 48,5,C SALARY 60,8,P,2 AUTO INPUT DEPTFL PRINT STAFF REPORT STAFF PRINTER DEPTPR ORDER DEPT BREAK DEPT TITLE 'DEPARTMENTAL STAFF REPORT' LINE 1 DEPT FIRST LAST SALARY SUM SALARY Example 2 The following example prints two lines (a two-line subpage) for each employee: REPORT EMPL-REPORT LINE 1 DEPT EMPLOYEE SALARY LINE 2 COL 30 START-DATE BONUS BIRTHDAY Example 3 The following example prints four lines for each person: REPORT LINE LINE LINE LINE EMPL-ADDR-REPORT FNM LNM 2 ADDR 3 CITY 4 STATE ZIP Copyright © 2012 by CSI International 11.21 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 NODATE NOPAGE ORDER DEPT-NAME TITLE 1 ('DEPT STAFF REPORT NODATE NOPAGENBR') LINE (DEPT-NAME DEPT-FNAME DEPT-LNAME DEPT-SALARY) /* Copyright © 2012 by CSI International 11.22 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 D Is a flag to specify to sort this field in descending order. The default is ascending order. fieldname Is 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 Example 2 DEPT PERSON 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 Copyright © 2012 by CSI International 11.23 - SALES DATAMINER FOR Z/OS 7.1C User Reference Guide Example 3 Report Writer 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) /* Copyright © 2012 by CSI International 11.24 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 A00 A00 A00 A00 A00 B01 C01 C01 C01 C01 D11 D11 D11 D11 D11 D11 D11 D11 D11 D11 D11 D21 D21 D21 D21 D21 D21 D21 E01 E11 E11 E11 E11 E11 E11 E11 E21 E21 E21 E21 E21 E21 EMPNO 200120 200010 000120 000110 000010 000020 000030 000130 000140 200140 000060 000150 000160 000170 000180 000190 000200 000210 000220 200170 200220 000070 000230 000240 000250 000260 000270 200240 000050 000090 000280 000290 000300 000310 200280 200310 000100 000320 000330 000340 200330 200340 FIRSTNME GREG DIANE SEAN VINCENZO CHRISTINE MICHAEL SALLY DOLORES HEATHER KIM IRVING BRUCE ELIZABETH MASATOSHI MARILYN JAMES DAVID WILLIAM JENNIFER KIYOSHI REBA EVA JAMES SALVATORE DANIEL SYBIL MARIA ROBERT JOHN EILEEN ETHEL JOHN PHILIP MAUDE EILEEN MICHELLE THEODORE RAMLAL WING JASON HELENA ROY LASTNAME ORLANDO HEMMINGER O CONNELL LUCCHESI HAAS THOMPSON KWAN QUINTANA NICHOLLS NATZ STERN ADAMSON PIANKA YOSHIMURA SCOUTTEN WALKER BROWN JONES LUTZ YAMAMOTO JOHN PULASKI JEFFERSON MARINO SMITH JOHNSON PEREZ MONTEVERDE GEYER HENDERSON SCHNEIDER PARKER SMITH SETRIGHT SCHWARTZ SPRINGER SPENSER MEHTA LEE GOUNOT WONG ALONZO Copyright © 2012 by CSI International 11.25 SALARY 798.33 208.75 180.99 170.55 150.55 200.00 200.00 200.00 200.00 200.00 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 200.00 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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-dataset Is 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=DEPTPR INPUT=VSAM FILENAME=DEPTFL FIRST 4,12,C HEADING ('FIRST' 'NAME') LAST *,16,C HEADING ('LAST' 'NAME') DEPT 48,5,C SALARY 60,8,P,2 AUTO INPUT DEPTFL PRINT STAFF REPORT STAFF PRINTER DEPTPR LINE 1 FIRST LAST DEPT SALARY Copyright © 2012 by CSI International 11.26 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 Copyright © 2012 by CSI International 11.27 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 fieldname Is 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 Example SUM and SUMMARY are different subcommands. 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 Copyright © 2012 by CSI International 11.28 BONUS DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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. Copyright © 2012 by CSI International 11.29 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 8 Is 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. recfield Is the name of a record field. tablefield Is the name of a table field. uservar Is the name of a user variable. See “Defining User Variables (DEFINE Command)” on page 5-3. sysvar Is the name of a system variable. See “System Variables” on page 5-12. sysconst Is 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. +/-numspaces Is the number of space to add (+) or subtract (-) from the default three spaces between columns. colnum Is the first column number of the next title component (for example, recfieldname or uservar) specified in this instance of the TITLE subcommand. Copyright © 2012 by CSI International 11.30 DATAMINER FOR Z/OS 7.1C User Reference Guide Example Report Writer 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 DEPT TITLE 1 'DEPARTMENT' TITLE 2 WORKDEPT /* Use literal in title 1 /* Add dept. code to title 2 LINE EMPNO LASTNAME SALARY TALLY BREAK WORKDEPT NEWPAGE ORDER WORKDEPT Copyright © 2012 by CSI International 11.31 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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=15 EMPNO 1,6,C LASTNAME 22,13,C DEPT 35,3,C SALARY 73,5,P,2 BONUS 78,5,P,2 COMM 83,5,P,2 AUTO EMPVSAM /* This is an auto-read script PRINT EMPRPT /* Write a line to the report * DEFINE THE REPORT REPORT EMPRPT LINE 1 DEPT EMPNO LASTNAME SALARY BONUS COMM This script can produce the following report: DEPT D11 D11 D11 C01 C01 A00 A00 E21 E11 D21 E01 D11 C01 B01 A00 EMPNO 000170 000160 000150 000140 000130 000120 000110 000100 000090 000070 000050 000060 000030 000020 000010 LASTNAME YOSHIMURA PIANKA ADAMSON NICHOLLS QUINTANA O'CONNELL LUCCHESI SPENSER HENDERSON PULASKI GEYER STERN KWAN THOMPSON HAAS SALARY 46726.40 42144.29 47857.78 29946.00 25095.00 169515.15 269424.05 27562.50 31342.50 144328.18 42288.75 61000.78 40267.50 43417.50 305634.48 Copyright © 2012 by CSI International 11.32 BONUS 3802.00 3702.00 3802.00 3902.00 3802.00 3902.00 4202.00 3802.00 3902.00 4002.00 4102.00 3902.00 4102.00 4102.00 9102.00 COMM 1974.00 1780.00 2022.00 2274.00 1904.00 2340.00 3720.00 2092.00 2380.00 2893.00 3214.00 2580.00 3060.00 3300.00 4220.00 DATAMINER FOR Z/OS 7.1C User Reference Guide Example Script 2 Report Writer 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 EMPVSAM DO WHILE (EMPVSAM:IO-RESULT = 'OK ') PRINT EMPRPT READ EMPVSAM ENDDO * DEFINE THE REPORT REPORT EMPRPT LINE 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 PRINT EMPRPT * DEFINE THE REPORT REPORT EMPRPT /* This is an auto-read script /* Write line to report TITLE 1 'EMPLOYEE LIST' ORDER DEPT /* LINE 1 DEPT EMPNO LASTNAME SALARY SUM SALARY BONUS COMM /* /* Copyright © 2012 by CSI International 11.33 Order by department BONUS COMM Create summary totals DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer Example Script 3 can produce the following report: 05/03/2012 DEPT A00 A00 A00 B01 C01 C01 C01 D11 D11 D11 D11 D21 E01 E11 E21 === EMPNO 000110 000120 000010 000020 000130 000140 000030 000170 000160 000060 000150 000070 000050 000090 000100 ====== EMPLOYEE LIST LASTNAME LUCCHESI O'CONNELL HAAS THOMPSON QUINTANA NICHOLLS KWAN YOSHIMURA PIANKA STERN ADAMSON PULASKI GEYER HENDERSON SPENSER ============= SALARY 269424.05 169515.15 305634.48 43417.50 25095.00 29946.00 40267.50 46726.40 42144.29 61000.78 47857.78 144328.18 42288.75 31342.50 27562.50 =========== 1326550.86 Copyright © 2012 by CSI International 11.34 PAGE BONUS 4202.00 3902.00 9102.00 4102.00 3802.00 3902.00 4102.00 3802.00 3702.00 3902.00 3802.00 4002.00 4102.00 3902.00 3802.00 =========== 64130.00 1 COMM 3720.00 2340.00 4220.00 3300.00 1904.00 2274.00 3060.00 1974.00 1780.00 2580.00 2022.00 2893.00 3214.00 2380.00 2092.00 =========== 39753.00 DATAMINER FOR Z/OS 7.1C User Reference Guide Example Script 4 Report Writer 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 script PRINT EMPRPT /* Write line to report * DEFINE THE REPORT REPORT EMPRPT TITLE 1 'EMPLOYEE LIST' ORDER DEPT /* Order by department BREAK DEPT /* Organize by department LINE 1 DEPT EMPNO LASTNAME SALARY BONUS COMM SUM SALARY BONUS COMM /* Create summary totals Example Script 4 can produce the following report: 05/03/2012 DEPT A00 EMPLOYEE LIST PAGE 1 EMPNO 000110 000120 000010 ====== LASTNAME LUCCHESI O'CONNELL HAAS ============= SALARY 269424.05 169515.15 305634.48 =========== 744573.68 BONUS 4202.00 3902.00 9102.00 =========== 17206.00 COMM 3720.00 2340.00 4220.00 =========== 10280.00 B01 000020 === ====== B01 THOMPSON ============= 43417.50 =========== 43417.50 4102.00 =========== 4102.00 3300.00 =========== 3300.00 C01 000130 000140 000030 ====== QUINTANA NICHOLLS KWAN ============= 25095.00 29946.00 40267.50 =========== 95308.50 3802.00 3902.00 4102.00 =========== 11806.00 1904.00 2274.00 3060.00 =========== 7238.00 000170 000160 000060 000150 ====== YOSHIMURA PIANKA STERN ADAMSON ============= 46726.40 42144.29 61000.78 47857.78 =========== 197729.25 3802.00 3702.00 3902.00 3802.00 =========== 15208.00 1974.00 1780.00 2580.00 2022.00 =========== 8356.00 === A00 === C01 D11 === D11 Copyright © 2012 by CSI International 11.35 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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. Example Script 5 AUTO EMPVSAM /* This is an auto-read script PRINT EMPRPT /* Write a line to report * DEFINE THE REPORT REPORT EMPRPT TITLE 1 'EMPLOYEE LIST' TITLE 2 'FOR DEPARTMENT' DEPT ORDER DEPT -SALARY /* Order by dept, then salary BREAK DEPT NEWPAGE /* Organize by department LINE 1 DEPT EMPNO LASTNAME SALARY BONUS COMM SUM SALARY BONUS COMM /* Create summary totals Example Script 5 can produce the following report: 05/02/2012 DEPT A00 === A00 EMPNO 000010 000110 000120 ====== 05/02/2012 DEPT B01 === B01 EMPNO 000020 ====== 05/02/2012 DEPT C01 === C01 EMPNO 000030 000140 000130 ====== EMPLOYEE LIST FOR DEPARTMENT A00 LASTNAME HAAS LUCCHESI O'CONNELL ============= SALARY 305634.48 269424.05 169515.15 =========== 744573.68 BONUS 9102.00 4202.00 3902.00 =========== 17206.00 EMPLOYEE LIST FOR DEPARTMENT B01 LASTNAME THOMPSON ============= SALARY 43417.50 =========== 43417.50 BONUS 4102.00 =========== 4102.00 EMPLOYEE LIST FOR DEPARTMENT C01 LASTNAME KWAN NICHOLLS QUINTANA ============= SALARY 40267.50 29946.00 25095.00 =========== 95308.50 BONUS 4102.00 3902.00 3802.00 =========== 11806.00 Copyright © 2012 by CSI International 11.36 PAGE 1 COMM 4220.00 3720.00 2340.00 =========== 10280.00 PAGE 2 COMM 3300.00 =========== 3300.00 PAGE COMM 3060.00 2274.00 1904.00 =========== 7238.00 3 DATAMINER FOR Z/OS 7.1C User Reference Guide Example Script 6 Report Writer 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 script TOTAL_COMP = SALARY + BONUS + COMM /* Calc total compensation */ PRINT EMPRPT /* Write line to detail report PRINT EMPSUM /* Write line to summary report * DEFINE THE DETAIL REPORT REPORT EMPRPT TITLE 1 'EMPLOYEE LIST' TITLE 2 'FOR DEPARTMENT' DEPT ORDER DEPT -SALARY /* Order by dept then salary BREAK DEPT NEWPAGE /* Organize by department LINE 1 DEPT EMPNO LASTNAME TOTAL_COMP SALARY BONUS COMM /* Create summary totals SUM SALARY BONUS COMM TOTAL_COMP * DEFINE THE SUMMARY REPORT REPORT EMPSUM TITLE 2 'DEPARTMENT SUMMARY' /* Order by dept then salary ORDER DEPT BREAK DEPT /* Organize by department LINE 1 DEPT TOTAL_COMP SALARY BONUS COMM TALLY HEADING TALLY 'EMPLOYEE' 'COUNT' SUM SALARY BONUS COMM TOTAL_COMP /* Create summary totals SUMMARY /* Print summary lines only Copyright © 2012 by CSI International 11.37 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer Example Script 6 can produce the following report: 05/02/2012 DEPT EMPNO A00 000010 000110 000120 ====== === A00 EMPLOYEE LIST FOR DEPARTMENT A00 TOTAL SALARY COMPENSATION 318956.48 305634.48 HAAS 277346.05 269424.05 LUCCHESI 175757.15 169515.15 O'CONNELL ============= ============ =========== 772059.68 744573.68 EMPNO B01 === B01 000020 ====== EMPNO C01 000030 000140 000130 ====== === C01 9102.00 4202.00 3902.00 =========== 17206.00 EMPLOYEE LIST FOR DEPARTMENT B01 TOTAL SALARY COMPENSATION 50819.50 43417.50 THOMPSON ============= ============ =========== 50819.50 43417.50 COMM 4220.00 3720.00 2340.00 =========== 10280.00 BONUS 4102.00 =========== 4102.00 EMPLOYEE LIST FOR DEPARTMENT C01 TOTAL SALARY COMPENSATION 47429.50 40267.50 KWAN 36122.00 29946.00 NICHOLLS 30801.00 25095.00 QUINTANA ============= ============ =========== 114352.50 95308.50 COMM 3300.00 =========== 3300.00 BONUS LASTNAME 4102.00 3902.00 3802.00 =========== 11806.00 3060.00 2274.00 1904.00 =========== 7238.00 PAGE A00 B01 C01 D11 D21 E01 E11 E21 === SALARY 744573.68 43417.50 95308.50 197729.25 144328.18 42288.75 31342.50 27562.50 ========== 1326550.86 BONUS 17206.00 4102.00 11806.00 15208.00 4002.00 4102.00 3902.00 3802.00 ========= 64130.00 COMM 10280.00 3300.00 7238.00 8356.00 2893.00 3214.00 2380.00 2092.00 ========= 39753.00 Copyright © 2012 by CSI International 11.38 3 COMM DEPARTMENT SUMMARY TOTAL COMPENSATION 772059.68 50819.50 114352.50 221293.25 151223.18 49604.75 37624.50 33456.50 =========== 1430433.86 2 PAGE 05/02/2012 DEPT 1 PAGE LASTNAME 05/03/2012 DEPT BONUS LASTNAME 05/02/2012 DEPT PAGE EMPLOYEE COUNT 3 1 3 4 1 1 1 1 ===== 15 1 DATAMINER FOR Z/OS 7.1C User Reference Guide Example Script 7 Report Writer 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 var AUTO 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 REPORT REPORT EMPRPT TITLE 1 '50K+ EMPLOYEE LIST' TITLE 2 'FOR DEPARTMENT' DEPT ORDER DEPT -SALARY /* Order by dept, then salary BREAK 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 /* BREAK DEPT /* LINE 1 DEPT TOTAL_COMP SALARY BONUS COMM TALLY HEADING TALLY 'EMPLOYEE' 'COUNT' AVG SALARY BONUS COMM TOTAL_COMP /* SUMMARY /* Order by dept, then salary Organize by department Create summary averages Print summary lines only Copyright © 2012 by CSI International 11.39 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer Example Script 7 can produce the following report: 50K+ EMPLOYEE LIST 05/03/2012 FOR DEPARTMENT DEPT EMPNO A00 000010 TOTAL COMPENSATION SALARY COMM 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 05/03/2012 50K+ EMPLOYEE LIST FOR DEPARTMENT DEPT EMPNO LASTNAME D11 000060 STERN === ====== ============= $67,482.78 SALARY BONUS COMM 61000.78 3902.00 2580.00 =========== =========== D11 $67,482.78 61000.78 3902.00 05/03/2012 50K+ EMPLOYEE LIST FOR DEPARTMENT LASTNAME D21 000070 PULASKI === ====== ============= D21 SALARY $151,223.18 144328.18 ============== =========== =========== 2580.00 PAGE BONUS COMM 4002.00 2893.00 =========== =========== 4002.00 2893.00 144328.18 50K+ EMPLOYEE LIST 05/03/2012 PAGE DEPARTMENT SUMMARY DEPT TOTAL COMPENSATION SALARY A00 $257,353.22 D11 BONUS COMM 248191.22 5735.33 3426.66 3 $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 2 =========== 5022.00 3 D21 TOTAL COMPENSATION $151,223.18 3426.66 PAGE ============== EMPNO =========== D11 TOTAL COMPENSATION DEPT 1 A00 BONUS === LASTNAME PAGE =========== 3150.60 Copyright © 2012 by CSI International 11.40 EMPLOYEE COUNT ============= 5 1 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer 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 /* // Copyright © 2012 by CSI International 11.41 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 8 Output: Report 1 Report Writer The following two-page report is an example of Report 1 output that could result from Example Script 8: QA.DM.TEST.DMRPORDP.DB2OUT1 01/22/2012 EMPL STAFF REPORT BY WORK DEPT STARTING DEPARTMENT NUMBER FOR PAGE: WORK A00 PAGE A00 EMPNO 000010 000110 000120 200010 200120 ====== FIRSTNME CHRISTINE VINCENZO SEAN DIANE GREG ============ LASTNAME HAAS LUCCHESI O CONNELL HEMMINGER ORLANDO =============== SALARY 150.55 170.55 180.99 208.75 798.33 =========== B01 === B01 000020 ====== MICHAEL ============ THOMPSON =============== 200.00 =========== C01 000030 000130 000140 200140 ====== SALLY DOLORES HEATHER KIM ============ KWAN QUINTANA NICHOLLS NATZ =============== 200.00 200.00 200.00 200.00 =========== 000060 000150 000160 000170 000180 000190 000200 000210 000220 200170 200220 ====== IRVING BRUCE ELIZABETH MASATOSHI MARILYN JAMES DAVID WILLIAM JENNIFER KIYOSHI REBA ============ STERN ADAMSON PIANKA YOSHIMURA SCOUTTEN WALKER BROWN JONES LUTZ YAMAMOTO JOHN =============== 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 =========== === A00 === C01 D11 === D11 D21 === D21 E01 === E01 000070 000230 000240 000250 000260 000270 200240 ====== EVA JAMES SALVATORE DANIEL SYBIL MARIA ROBERT ============ PULASKI JEFFERSON MARINO SMITH JOHNSON PEREZ MONTEVERDE =============== 200.00 200.00 200.00 200.00 200.00 200.00 200.00 =========== 000050 ====== JOHN ============ GEYER =============== 200.00 =========== Copyright © 2012 by CSI International 11.42 1 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer (Report 1 continued) E11 === E11 E21 000090 000280 000290 000300 000310 200280 200310 ====== EILEEN ETHEL JOHN PHILIP MAUDE EILEEN MICHELLE ============ HENDERSON SCHNEIDER PARKER SMITH SETRIGHT SCHWARTZ SPRINGER =============== 000100 000320 000330 000340 THEODORE RAMLAL WING JASON SPENSER MEHTA LEE GOUNOT 01/22/2012 EMPL STAFF REPORT BY WORK DEPT STARTING DEPARTMENT NUMBER FOR PAGE: WORK E21 === E21 EMPNO 200330 200340 ====== FIRSTNME HELENA ROY ============ LASTNAME WONG ALONZO =============== Copyright © 2012 by CSI International 11.43 200.00 200.00 200.00 200.00 200.00 200.00 200.00 =========== 200.00 200.00 200.00 200.00 PAGE E21 SALARY 200.00 200.00 =========== 2 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 8 Output: Report 2 Report Writer 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 WORK A00 === A00 B01 === B01 C01 === C01 D11 === D11 D21 === D21 E01 === E01 EMPL STAFF REPORT WITH SUMMARY BY DEPT PAGE EMPNO 200120 200010 000120 000110 000010 ====== FIRSTNME GREG DIANE SEAN VINCENZO CHRISTINE ============ LASTNAME ORLANDO HEMMINGER O CONNELL LUCCHESI HAAS =============== SALARY 798.33 208.75 180.99 170.55 150.55 =========== 1509.17 000020 ====== MICHAEL ============ THOMPSON =============== 200.00 =========== 200.00 000030 000130 000140 200140 ====== SALLY DOLORES HEATHER KIM ============ KWAN QUINTANA NICHOLLS NATZ =============== 200.00 200.00 200.00 200.00 =========== 800.00 000060 000150 000160 000170 000180 000190 000200 000210 000220 200170 200220 ====== IRVING BRUCE ELIZABETH MASATOSHI MARILYN JAMES DAVID WILLIAM JENNIFER KIYOSHI REBA ============ STERN ADAMSON PIANKA YOSHIMURA SCOUTTEN WALKER BROWN JONES LUTZ YAMAMOTO JOHN =============== 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 905.56 =========== 9961.16 000070 000230 000240 000250 000260 000270 200240 ====== EVA JAMES SALVATORE DANIEL SYBIL MARIA ROBERT ============ PULASKI JEFFERSON MARINO SMITH JOHNSON PEREZ MONTEVERDE =============== 200.00 200.00 200.00 200.00 200.00 200.00 200.00 =========== 1400.00 000050 ====== JOHN ============ GEYER =============== 200.00 =========== 200.00 Copyright © 2012 by CSI International 11.44 1 DATAMINER FOR Z/OS 7.1C User Reference Guide Report Writer (Report 2 continued) E11 === E11 E21 000090 000280 000290 000300 000310 200280 200310 ====== EILEEN ETHEL JOHN PHILIP MAUDE EILEEN MICHELLE ============ HENDERSON SCHNEIDER PARKER SMITH SETRIGHT SCHWARTZ SPRINGER =============== 000100 000320 000330 000340 200330 THEODORE RAMLAL WING JASON HELENA SPENSER MEHTA LEE GOUNOT WONG 01/22/2012 WORK E21 === E21 === WORK FIRSTNME ROY ============ LASTNAME ALONZO =============== ====== ============ =============== EMPNO 200.00 200.00 200.00 200.00 200.00 EMPL STAFF REPORT WITH SUMMARY BY DEPT EMPNO 200340 ====== 01/22/2012 200.00 200.00 200.00 200.00 200.00 200.00 200.00 =========== 1400.00 LASTNAME Copyright © 2012 by CSI International 11.45 2 SALARY 200.00 =========== 1200.00 =========== EMPL STAFF REPORT WITH SUMMARY BY DEPT FIRSTNME PAGE PAGE SALARY 16670.33 1 DATAMINER FOR Z/OS 7.1C User Reference Guide Example Script 9: Creating Reports and a Mailing List Report Writer 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 /* Copyright © 2012 by CSI International 11.46 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 9 Output: Address Labels Report Writer 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.) CATHY O’BRIAN 908 KOHR PLACE CINCINNATI FL 44708 SUZY 3343 DREW RD MENTOR OH 44332 HILLBERG SHAUNTEE DAVIS 33445 SCENIC WAY BUFFALO NY 88993 DENVER 2238 TEST RD MIAMI FL 33455 BRONCOS 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.) Example 9 Output: Report 1 EMPL STAFF REPORT WITH SUMMARY BY DEPT DEPT-N B100 ===== B100 DEPT-FNAME CATHY ============ DEPT-LNAME O’BRIAN ================ DEPT-SALARY 190500.00 =========== 190500.00 B200 SHAUNTEE SUZY ============ DAVIS HILLBERG ================ 95300.50 75500.00 =========== 170800.50 DENVER ============ BRONCOS ================ 85000.00 =========== 85000.00 ===== B200 C400 ===== C400 ===== ============ ================ Copyright © 2012 by CSI International 11.47 =========== 446300.50 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 9 Output: Summary Report Report Writer 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 B100 B200 C400 ===== DEPT-SALARY 190500.00 170800.50 85000.00 =========== 446300.50 TALLY 1 2 1 ============= 4 Copyright © 2012 by CSI International 11.48 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. Dataset INPUT= Row n Table 1 F1 F2 F3 F4 Record n F1 F2 F3 F4 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. This chapter covers the following topics: Page TABLE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.2 Defining Table Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.4 Arrays and Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.9 DATA…ENDDATA Subcommands . . . . . . . . . . . . . . . . . . . . . . . . . 12.13 FIND Subcommand (Searching Tables) . . . . . . . . . . . . . . . . . . . . . . 12.14 Copyright © 2012 by CSI International 12.1 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 name Is the name for your table. filename Is 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. numrows Is 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 Copyright © 2012 by CSI International 12.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields • 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 * BRANCH-NO CITY RATE Example: Defining a Table Using Data In the Script FILE BRFILE 1 9 40 5 20 6 C C P 2 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 DEPTS DEPT-CODE 1 4 C DEPT-NAME 7 14 C DEPT-MANAGER 23 30 C * DATA ACCT··ACCOUNTING······Joe Bloggs SALE··SALES···········Penny Wise MAIN··MAINTENANCE·····Fred Boreham ENDDATA Copyright © 2012 by CSI International 12.3 /* Table field 1 /* Table field 2 /* Table field 3 DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields 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] [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. tablefieldname Is 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. Copyright © 2012 by CSI International 12.4 DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields 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. startpos Is the starting position of tablefieldname. Table fields can overlap or have gaps between them. startpos is one of the following: n A 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. *+n The nth byte higher than the byte following the previous field. *-n The nth byte lower than the byte following the previous field. " The same location as the first byte of the previous field. "+n The nth byte higher than the first byte of the previous field. "-n The nth byte lower than the first byte of the previous field. tablefieldname2 The same location as the first byte of another field, tablefieldname2. Copyright © 2012 by CSI International 12.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields tablefieldname2+n The nth byte higher than the first byte of another field, tablefieldname2. tablefieldname2-n The nth byte lower than the first byte of another field, tablefieldname2. length The 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. type Is a character that denotes the data type of the field: Character Data Type Max Length (Bytes) A Alphanumeric 32,767 C Character 32,767 B Binary 4 P Packed 16 Z Zoned 16 X Hexadecimal 8 V Variable-length character N/A D Date N/A Comments Treated as signed if 2 or 4 bytes long. Treated as unsigned if 1 or 3 bytes long. [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. [ 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 12.9). Copyright © 2012 by CSI International 12.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields (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). [std-mask] Is one of five standard printing masks for numeric fields only (binary, packed, and zoned), as follows: 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).99M3 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. Copyright © 2012 by CSI International 12.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields [ 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 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.” Copyright © 2012 by CSI International 12.8 DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields 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. 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 tablefieldname(n) where tablefieldname Is the name of the record field that is an array. n Is 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 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 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) Copyright © 2012 by CSI International 12.9 DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields 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). SET SET SET SET SET SET SET SET SET SET SET SET INDEXing by INDEX Value MONTH(1) = 'JAN' MONTH(2) = 'FEB' MONTH(3) = 'MAR' MONTH(4) = 'APR' MONTH(5) = 'MAY' MONTH(6) = 'JUN' MONTH(7) = 'JUL' MONTH(8) = 'AUG' MONTH(9) = 'SEP' MONTH(10) = 'OCT' MONTH(11) = 'NOV' MONTH(12) = 'DEC' 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: 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 12.9) and “INDEXing by Bytes Offset” (page 12.11). Copyright © 2012 by CSI International 12.10 DATAMINER FOR Z/OS 7.1C User Reference Guide SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= MONTH= NUM= Table Fields 1 'JAN' 2 'FEB' 3 'MAR' 4 'APR' 5 'MAY' 6 'JUN' 7 'JUL' 8 'AUG' 9 'SEP' 10 'OCT' 11 'NOV' 12 SET MONTH= 'DEC' INDEXing by Bytes Offset 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: 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 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. In the current example, you address the each member like this: MONTH(NUM) Copyright © 2012 by CSI International 12.11 DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields 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 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). SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET SET NUM= 0 MONTH(NUM)='JAN' NUM= 3 MONTH(NUM)='FEB' NUM= 6 MONTH(NUM)='MAR' NUM= 9 MONTH(NUM)='APR' NUM= 12 MONTH(NUM)='MAY' NUM= 15 MONTH(NUM)='JUN' NUM= 18 MONTH(NUM)='JUL' NUM= 21 MONTH(NUM)='AUG' NUM= 24 MONTH(NUM)='SEP' NUM= 27 MONTH(NUM)='OCT' NUM= 30 MONTH(NUM)='NOV' NUM= 33 MONTH(NUM)='DEC' Copyright © 2012 by CSI International 12.12 DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields 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 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 DEPTS DEPT-CODE 1 DEPT-NAME 7 DEPT-MANAGER 23 DATA ACCT ACCOUNTING SALE SALES MAIN MAINTENANCE ENDDATA 4 15 30 C C C Joe Bloggs Penny Wise Fred Boreham Copyright © 2012 by CSI International 12.13 DATAMINER FOR Z/OS 7.1C User Reference Guide Table Fields 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 tablename Is the name of the table you want to search. tablefieldname Is 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. Copyright © 2012 by CSI International 12.14 DATAMINER FOR Z/OS 7.1C User Reference Guide * Define an INPUT=VSAM EMPNO 1 EMPDEPT 135 SALARY 312 Table Fields employee VSAM dataset and record fields of interest FILENAME=EMPFILE 6 C 5 C 6 P 2 * Define a department sequential dataset, and load a table with * department numbers INPUT=DISK FILENAME=DEPFILE TABLE DEPTTAB FILE DEPFILE DEPNO 1 5 C * Locate and print employees with no matching department number PRINT /* Print basic report FIND DEPTTAB WHERE DEPNO = EMPDEPT ONLY DEPTTAB:IO-RESULT = 'NFD' /* Search dept table for employee dept /* Include only those employees with /* no matching department SELECT EMPNO EMPDEPT SALARY /* Select which fields to print Copyright © 2012 by CSI International 12.15 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International 12.16 Table Fields 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.2 Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.2 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.2 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.2 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.3 Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.3 Copyright © 2012 by CSI International 13.1 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-dataset Is the source dataset containing the data to sort. output-dataset Is the destination dataset for the sorted data. - Is a flag to field that specifies descending sort order. The default is ascending order. field Is 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 Copyright © 2012 by CSI International 13.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 2 SORT Command 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 NAME SKIP AMOUNT < 0 Copyright © 2012 by CSI International 13.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International 13.4 SORT Command 14 Troubleshooting Commands DATAMINER provides commands that can help you analyze records and troubleshoot problems with DATAMINER scripts. This chapter covers the following topics: Page ABEND Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.2 CANCEL Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.3 SHOW Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.4 TRACE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.6 Copyright © 2012 by CSI International 14.1 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 Copyright © 2012 by CSI International 14.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Troubleshooting Commands 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 rc Is 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 0 CANCEL ENDIF Copyright © 2012 by CSI International 14.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Troubleshooting Commands 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 fieldname Is 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. filename Is 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: RECORD NUMBER - IN= 2,OUT= 0 F2F2F3F0 F5F0F7F5 D9C5C3D5 *22305075RECNO>00000002FNM>JAMES * 20 40404040 40404040 4040D3D5 LNM>MCFARLANE * 40 40404040 40404040 40404040 BAL>.Ñçg•FLAG>úAMT* 60 F16E3539 2DC1D4E3 F26E0151 *1>¤¨•AMT2>.Òà÷q*!èBIN4>!èe* 80 2EE7E7 *–XX * Example: SHOW Fieldname 2 LRECL= 131 D66EF0F0 F0F0F0F0 F0F2C6D5 D46ED1C1 D4C5E240 D46ED4C3 C6C1D9D3 C1D5C540 40404040 40404040 * 4040C2C1 D36E1449 67872DC6 D3C1C76E FAC1D4E3 * 5977984C C2C9D5F3 6E5C5A68 C2C9D5F4 6E5A6885 The following example is output from the SHOW fieldname command: CONTENTS OF FIELD OUTFILE:FLD1 0 F0F9F3F1 F5F0F7F5 D9C5 *09315075RE * Copyright © 2012 by CSI International 14.4 DATAMINER FOR Z/OS 7.1C User Reference Guide About the Examples Troubleshooting Commands 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. Copyright © 2012 by CSI International 14.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Troubleshooting Commands 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 ON Turns on all tracing; every command you execute produces a trace line. OFF Turns tracing off for the rest of the job or until another TRACE ON or TRACE FLOW is encountered. FLOW Turns 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 14 15 16 17 TRACE ON ADD 1 TO JAMES IF K2 = '4' GOTO TYPE4 ENDIF DISPLAY JAMES /* Other statements follow Copyright © 2012 by CSI International 14.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Troubleshooting Commands The following is the corresponding TRACE output: DMIN-506 DMIN-505 DMIN-505 DMIN-505 DMIN-505 52 O DMIN-506 Explanation >>> >>> >>> >>> >>> STATEMENT STATEMENT STATEMENT STATEMENT STATEMENT AT 13 14 15 17 START OF SCRIPT ABOUT TO EXECUTE TRACE ABOUT TO EXECUTE SET ABOUT TO EXECUTE IF ABOUT TO EXECUTE DISPLAY ABOUT TO EXECUTE >>> STATEMENT AT END OF SCRIPT ABOUT TO EXECUTE 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. Copyright © 2012 by CSI International 14.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International 14.8 Troubleshooting Commands 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. This chapter covers the following topics: Page DB2 Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.2 CONNECT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.3 INPUT= Command (DB2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.4 OUTPUT= Command (DB2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.5 EXECUTE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.6 CLOSE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.7 COMMIT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.8 ROLLBACK Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.9 Host Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.10 Additional Information about DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . 15.11 DB2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.12 Copyright © 2012 by CSI International 15.1 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. Copyright © 2012 by CSI International 15.2 DATAMINER FOR Z/OS 7.1C User Reference Guide DB2 Commands 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 ssid Is the subsystem ID of the DB2 host you want to access. plan_name Is the name of the plan into which you bound the CSIDMBSQ DBRM (using BIND) when you installed DATAMINER. Copyright © 2012 by CSI International 15.3 DATAMINER FOR Z/OS 7.1C User Reference Guide DB2 Commands 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_name Is a one- to eight-character name that allows other commands (AUTO, EXECUTE) to reference it. select_statement Is 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. Copyright © 2012 by CSI International 15.4 DATAMINER FOR Z/OS 7.1C User Reference Guide DB2 Commands 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_name Is a one- to eight-character name that allows other commands (AUTO, EXECUTE) to reference it. update_statement insert_statement delete_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. Copyright © 2012 by CSI International 15.5 DATAMINER FOR Z/OS 7.1C User Reference Guide DB2 Commands 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_name Is the name of a DB2 or SQL statement defined in an INPUT= or OUTPUT= command in your DATAMINER script. statement Is a DB2 or SQL statement defined here in the EXECUTE command. Copyright © 2012 by CSI International 15.6 DATAMINER FOR Z/OS 7.1C User Reference Guide DB2 Commands 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_name Is the name of a DB2 or SQL statement defined in an INPUT= command in your DATAMINER script. Copyright © 2012 by CSI International 15.7 DATAMINER FOR Z/OS 7.1C User Reference Guide DB2 Commands 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 Copyright © 2012 by CSI International 15.8 DATAMINER FOR Z/OS 7.1C User Reference Guide DB2 Commands 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 Copyright © 2012 by CSI International 15.9 DATAMINER FOR Z/OS 7.1C User Reference Guide DB2 Commands Host Variables Description You can address host variables. Syntax The syntax for addressing host variables is :{ [dataset.]recfield | [statement_name.]column_name | uservar } where dataset Is the dataset name specified by the INPUT= command (page 3.3). recfield Is the name of a record field. statement_name Is an INPUT=SQL statement name. column_name Is a column in the DB2 table reference by statement_name. uservar Is 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 Copyright © 2012 by CSI International 15.10 DATAMINER FOR Z/OS 7.1C User Reference Guide DB2 Commands 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 Copyright © 2012 by CSI International 15.11 DATAMINER FOR Z/OS 7.1C User Reference Guide DB2 Commands DB2 Examples 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. Example 1: Simple Auto Print INPUT=SQL(SELECT * FROM EMPLOYEE WHERE SALARY > 50000) PRINT SELECT WORKDEPT,EMPNO,LASTNAME,SALARY The output looks like the following: WORKDE EMPNO LASTNAME SALARY A00 D21 A00 000010 000070 000110 HAAS PULASKI LUCCHESI 196947.05 70485.07 173605.49 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. Example 2: Auto-Read Report The AUTO command is used to auto-read the EMPSEL table. 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 The output looks like the following: WORK A00 === A00 C01 === C01 EMPNO 000100 000110 000120 ====== LASTNAME HAAS LUCCHESI O'CONNELL =============== SALARY 196947.05 173605.49 109203.32 ============= 479755.86 000030 000140 000130 ====== KWAN NICHOLLS QUINTANA =============== 38250.00 28420.00 23800.00 ============= 90470.00 Copyright © 2012 by CSI International 15.12 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 3: Manual-Read Report DB2 Commands 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 EMPLOYEE EXECUTE STATEMENT=EMPSEL WHILE (EMPSEL:SQLCODE = 0) PRINT SALRPT EXECUTE STATEMENT=EMPSEL ENDWHILE REPORT SALRPT LINE WORKDEPT,EMPNO,LASTNAME,SALARY ORDER WORKDEPT, -SALARY BREAK WORKDEPT SUM SALARY Example 4: Multiple Cursors The following example opens two cursors (EMPSEL1 and EMPSEL2) and fetches rows from them: 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 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') Copyright © 2012 by CSI International 15.13 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 6: Table Update with Host Variables DB2 Commands 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. The output looks like the following: DEPT= DEPT= A00 D21 ,RAISE= ,RAISE= 0.05 0.10 ,EMPLOYEE COUNT= ,EMPLOYEE COUNT= Copyright © 2012 by CSI International 15.14 3 6 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 7: Extract from DB2 to Sequential Dataset DB2 Commands The following example creates a sequential dataset composed of selected columns from a table: EXTRACT INPUT=SQL (SELECT * FROM EMPLOYEE) OUTPUT=DISK FILENAME=SQLEMP LRECL=100 BLKSIZE=4000 FIXBLK SELECT 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 fields INPUT=VSAM FILENAME=EMPVSAM EMPNO *,6,C FIRSTNME *,10,C LASTNAME *,13,C SALARY *,5,P,2 *Connect to DB2 and define SQL insert command CONNECT 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 added PRINT SELECT EMPNO,LASTNAME,SALARY WHERE EMPNO > '050000' Copyright © 2012 by CSI International 15.15 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International 15.16 DB2 Commands 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). This chapter covers the following topics: Page Summary Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.2 Syntax Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.3 General Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.12 Copyright © 2012 by CSI International 16.1 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. Copyright © 2012 by CSI International 16.2 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages 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 Message Example 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. Here is an example of error message output: 7 ADD FOOT TO LEG DMIN003E 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. Copyright © 2012 by CSI International 16.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Message Table DataMiner Messages 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. Copyright © 2012 by CSI International 16.4 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning 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. Copyright © 2012 by CSI International 16.5 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning 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. Copyright © 2012 by CSI International 16.6 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning 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. DMIN048E Message DMIN048E is unused. DMIN049E Message DMIN049E is unused. DMIN050E Message DMIN050E is unused. DMIN051E Message DMIN051E is unused. 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. Copyright © 2012 by CSI International 16.7 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning 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 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 DMIN066E (Not used) Equal sign is missing DMIN067E DMIN068E A table with the same name is already been defined. An equal sign was expected but was not found. (Not used) Invalid expression An invalid expression has been detected. Refer to the the documentation on the specific command for valid expressions. Copyright © 2012 by CSI International 16.8 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning 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. Copyright © 2012 by CSI International 16.9 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning DMIN082E The CALL command specified more than the maximum 256 parameters. Too many parameters on CALL 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 DMIN089E (Not used) Invalid TRACE value DMIN090E The TRACE parameter value must be ON, OFF, or FLOW. (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. Copyright © 2012 by CSI International 16.10 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning 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. Copyright © 2012 by CSI International 16.11 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages 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 Copyright © 2012 by CSI International 16.12 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages 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 Copyright © 2012 by CSI International 16.13 DATAMINER FOR Z/OS 7.1C User Reference Guide Message Table DataMiner Messages 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. Copyright © 2012 by CSI International 16.14 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning (if not obvious) 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. Copyright © 2012 by CSI International 16.15 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning (if not obvious) 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. Copyright © 2012 by CSI International 16.16 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning (if not obvious) 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. Copyright © 2012 by CSI International 16.17 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning (if not obvious) 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. Copyright © 2012 by CSI International 16.18 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning (if not obvious) 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. Copyright © 2012 by CSI International 16.19 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Messages Error Code Error Message Meaning (if not obvious) 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. Copyright © 2012 by CSI International 16.20 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.3 Ex. 1: COPY Subset of Records . . . . . . . . . . . . . . . . . . . . . . . . . . 17.3 Ex. 2: COPY and PRINT Specific Records. . . . . . . . . . . . . . . . . . 17.3 Ex. 3: DUMP Specific Records . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.3 Ex. 4: COPY and PRINT Specific Records and Calculations. . . . 17.3 Ex. 5: PRINT Specific Records, Calculations, and Totals . . . . . . 17.4 Ex. 6: PRINT Specific Records and Totals . . . . . . . . . . . . . . . . . . 17.5 Ex. 7: DELETE Specific Records . . . . . . . . . . . . . . . . . . . . . . . . . 17.6 Ex. 8: EXTRACT and PRINT Specific Records. . . . . . . . . . . . . . 17.6 Ex. 9: EXTRACT and PRINT Records, Calculations. . . . . . . . . . 17.7 Ex. 10: DUMP Specific Records . . . . . . . . . . . . . . . . . . . . . . . . . . 17.7 Ex. 11: COPY Specific Records, KSDS . . . . . . . . . . . . . . . . . . . . 17.7 Ex. 12: COPY Specific Records, Fixed Block . . . . . . . . . . . . . . . 17.8 Ex. 13: UPDATE Variable Blocked File In Place . . . . . . . . . . . . . 17.8 Ex. 14: UPDATE Fixed-Length File . . . . . . . . . . . . . . . . . . . . . . . 17.8 Ex. 15: INSERT Records into a KSDS . . . . . . . . . . . . . . . . . . . . . 17.9 Ex. 16: UPDATE a KSDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.9 Ex. 17: COPY and PRINT Specific Records. . . . . . . . . . . . . . . . . 17.9 Ex. 18: DUMP the First 50 Records From a KSDS . . . . . . . . . . 17.10 Ex. 19: COPY VSAM File to an FL Dataset, DUMP Recs . . . . 17.10 Ex. 20: PRINT Column Report Showing Three Fields . . . . . . . . 17.10 Ex. 21: COPY 1000 Records from One File to Another . . . . . . . 17.11 Ex. 22: PRINT Report and DUMP Recs Using Criteria . . . . . . . 17.11 Ex. 23: PRINT Records Within a Balance Range . . . . . . . . . . . . 17.12 Ex. 24: DUMP Records and Delete Matching Records . . . . . . . 17.12 Ex. 25: Calculate Ratio, PRINT Report, EXTRACT Records . . 17.12 Copyright © 2012 by CSI International 17.1 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Script Examples Ex. 26: DUMP the First 20 Records Matching Criteria . . . . . . . 17.13 Ex. 27: Create New KSDS Records from Card Input . . . . . . . . . 17.13 Ex. 28: READ Two Files and SHOW ACCTNO from Both . . . 17.13 Ex. 29: UPDATE a Sequential File In Place . . . . . . . . . . . . . . . . 17.14 Ex. 30: PRINT a Column Report from a File . . . . . . . . . . . . . . . 17.14 Ex. 31: COPY and DUMP the First 10 Records of a File . . . . . . 17.14 Ex. 32: Create a File from Selected Fields of an Input File . . . . 17.15 Ex. 33: COPY a Prod File to a Test File, Changing Names . . . . 17.15 Ex. 34: PRINT Report Sorted by Fields, Create Subtotals . . . . . 17.16 Ex. 35: PRINT Report Sorted by Fields, File/Table Input . . . . . 17.17 Ex. 36: PRINT Name and Address Labels . . . . . . . . . . . . . . . . . 17.18 Ex. 37: Using ORDER and BREAK Commands Together . . . . . 17.18 Ex. 38: Using ORDER, BREAK, and SUMMARY Together. . . 17.20 Copyright © 2012 by CSI International 17.2 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Script Examples 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. COPY INPUT=VSAM FILENAME=INFILE OUTPUT=DISK FILENAME=OUTFILE FIXED LRECL=200 BLKSIZE=20000 last=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. COPY PRINT INPUT=VSAM OUTPUT=VSAM FILENAME=VSMESDS Key 1,8,C BAL 83,5,P,3 SELECT (KEY,BAL) FROM INFILE * WE WANT ONLY RECORDS WITH A BALANCE * GREATER THAN ZERO ONLY 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. DUMP INPUT=VSAM FILENAME=INFILE MAX=20 AMT1 99,3,P,3 AMT2 107,6,P,5 ONLY 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 Copyright © 2012 by CSI International 17.3 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Script Examples the report, the script prints three total lines showing TOTAMT1, TOTAMT2, and TOTCALC1. COPY PRINT INPUT=VSAM FILENAME=INFILE OUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000 Key 1,8,C AMT1 99,3,P,3 AMT2 107,6,P,5 CALC1 143,8,P,2 DEFINE TOTAMT1,8,P,2 DEFINE TOTAMT2,8,P,2 DEFINE TOTCALC1,8,P,2 DEFINE WORK, 8,P,2 SELECT (KEY,AMT1,AMT2,CALC1,TOTAMT1,TOTAMT2,TOTCALC1) MOVE AMT1 TO WORK ADD AMT2 TO WORK MOVE WORK TO CALC1 ADD AMT1 TO TOTAMT1 ADD AMT2 TO TOTAMT2 ADD WORK TO TOTCALC1 MAXRCDS=100 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,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). PRINT INPUT=VSAM FILENAME=INFILE Key 1,8,C FNM 27,16,C LNM 47,32,C BAL 83,5,P,3 DEFINE TotalBalance,8,P,2 SELECT (KEY,Lnm,Fnm,bal,totalbalance) IF FNM = 'STEVE' AND BAL<1000 ADD BAL TO Total_Balance KEEP ELSE DROP ENDIF Copyright © 2012 by CSI International 17.4 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Script Examples MAXRCDS=200 TOT 'Total Balance is',5 TOTAL_BALANCE,17,35,M5 TOT '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. PRINT INPUT=VSAM FILENAME=INFILE OUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000 Key 1,8,C RECORD 15,8,c RNO 20,3,C FNM 27,16,C LNM 47,32,C BAL 83,5,P,3 FLAG 93,1,X AMT1 99,3,P,3 AMT2 107,6,P,5 BIN3 118,3,B,1 BIN4 126,4,B,2 XXX 134,3,C CALC1 143,8,P,2 CALC2 157,4,B,1 CHAR 166,32,C DEFINE Total_balance,8,P,2 DEFINE PLUS_balance,8,P,2 DEFINE MINUS_balance,8,P,2 * Filter out small balances SKIP BAL >= 0 AND BAL <1000 SKIP BAL <0 AND BAL >-1000 * Total the positive balances IF BAL > 0 ADD BAL TO PLUS_BALANCE ELSE * Total the negative balances ADD BAL TO MINUS_BALANCE ENDIF * Total all the balances ADD BAL TO TOTAL_BALANCE SELECT (KEY,fnm,lnm,bal,PLUS_BALANCE,MINUS_BALANCE) MAXRCDS=1000 * The M5 mask prints the totals as * currency amounts TOT 'Total Balance is',5 TOTAL_BALANCE,17,35,M5 TOT 'PLUS_BALANCE is',5 PLUS_BALANCE,17,35,M5 'MINUS_BALANCE is',55 MINUS_BALANCE,17,75,M5 /* Copyright © 2012 by CSI International 17.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Ex. 7: DELETE Specific Records DataMiner Script Examples 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.” DELETE INPUT=VSAM FILENAME=INFILE FNM 27,16,C LNM 47,32,C SKIP 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. EXTRACT PRINT INPUT=VSAM FILENAME=INFILE OUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000 Key 1,8,C FNM 27,16,C LNM 47,32,C BAL 83,5,P,3 DEFINE PAYMENT,8,P,2 DEFINE DISPLAY_PAYMENT,16,C * Filter out records we don't want. * This command could * have been entered as * ONLY LNM = 'Huggins' AND BAL > 0 SKIP LNM != 'Huggins' OR BAL <=0 SET PAYMENT = BAL * Make payment equal to 10% of the balance MULTIPLY PAYMENT BY 0.1 MOVE PAYMENT TO DISPLAY_PAYMENT,M5 SELECT (KEY,fnm,lnm,bal,PAYMENT,DISPLAY_PAYMENT) LAST=200 /* Copyright © 2012 by CSI International 17.6 DATAMINER FOR Z/OS 7.1C User Reference Guide Ex. 9: EXTRACT and PRINT Records, Calculations DataMiner Script Examples 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. EXTRACT PRINT INPUT=VSAM FILENAME=INFILE OUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000 Key 1,8,C AMT1 99,3,P,3 AMT2 107,6,P,5 DEFINE ratio,8,P,4 MOVE AMT2 TO RATIO DIVIDE RATIO BY AMT1 ONLY RATIO > 100 OR RATIO < -100 SELECT (AMT1,AMT2,RATIO) FROM INFILE STOP KEY > '60000000' Ex. 10: DUMP Specific Records The following example DUMPs to the printer the first 20 records where AMT1 is greater than AMT2. DUMP INPUT=VSAM FILENAME=INFILE AMT1 99,3,P,3 AMT2 107,6,P,5 MAXRCDS=20 ONLY 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. COPY DUMP INPUT=CARDS OUTPUT=VSAM FILENAME=outfile * No field definition is given because we are * copying all 80 bytes from each card to the * output dataset DATACARDS 8KA9AA8K7**33DDD3**3*33END OF RECORD 8KLSWAD6**34CCC3**3*34 8K7DEA6**35EEE3**3*35 8K7LFRA**33DDD3**3*33 9WWWDRAF**99ZZZ9**9*99 Last record /* to mark the end of the data cards Copyright © 2012 by CSI International 17.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Ex. 12: COPY Specific Records, Fixed Block DataMiner Script Examples The following example copies the first 10,000 records from a variable blocked dataset to a fixed-block dataset. COPY INPUT=DISK FILENAME=INFILE VARBLK LRECL=600 BLKSIZE=20000 OUTPUT=DISK FILENAME=OUTFILE LRECL=400 BLKSIZE=4000 LAST=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 INFILE DUMP INPUT=DISK FILENAME=INFILE VARBLK LRECL=600 BLKSIZE=20000 FNM 27,16,C BAL 83,5,P,3 BADBYTE 580,10,C LAST=100 IF FNM < 'CARSON' MOVE 0 TO BAL ENDIF IF FNM >'MARCIE' MOVE 'MISTAKE!' TO BADBYTE ENDIF /* 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 INFILE DUMP INPUT=DISK FILENAME=INFILE FIXED FNM 27,16,C LNM 47,32,C BAL 83,5,P,3 BADBYTE 398,8,C IF FNM < 'CARSON' MOVE 0 TO BAL ENDIF Copyright © 2012 by CSI International 17.8 LRECL=400 BLKSIZE=4000 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Script Examples IF FNM>'MARCIE' MOVE 'WHOOPS' TO BADBYTE ENDIF LAST=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=OUTFILE Key 1,8,C RECORD 15,8,c BAL 83,5,P,3 FLAG 93,1,X AMT1 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,3 AMT2 107,6,P,5 ONLY 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. Copyright © 2012 by CSI International 17.9 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Script Examples PRINT COPY INPUT=VSAM FILENAME=INFILE OUTPUT=DISK FILENAME=OUTFILE FIXED LRECL=200 BLKSIZE=2000 Key 1,8,C FNM 27,16,C LNM 47,32,C BAL 83,5,P,3 HEXBAL 83,5,X DEFINE TESTER 8,P,2 * Clear the error counter MOVE 0 TO VALIDATION_ERRORS MOVE 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. DUMP INPUT=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=INFILE OUTPUT=DISK FILENAME=OUTFILE FIXED BLKSIZE=9600 COPY DUMP Ex. 20: PRINT Column Report Showing Three Fields LRECL=100 The following example prints a column report showing three fields from a dataset, including only records whose QTY1 is greater than QTY2: PRINT INPUT=VSAM FILENAME=INFILE ACCTNO 1, 8, c QTY1 99, 3, P,3 QTY2 107, 6, P,2 ONLY QTY1> QTY2 SELECT (ACCTNO,QTY1,QTY2) * The SELECT could have been written * SELECT (*) Copyright © 2012 by CSI International 17.10 DATAMINER FOR Z/OS 7.1C User Reference Guide Ex. 21: COPY 1000 Records from One File to Another DataMiner Script Examples 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=INFILE OUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000 COPY PRINT ACCTNO 1,8,C AMT1 99,3,P,3 AMT2 107,6,P,5 CALC1 143,8,P,2 DEFINE WORK, 8,P,5 DEFINE TOTAMT1,8,P,2 DEFINE TOTAMT2,8,P,2 DEFINE TOTCALC1,8,P,2 MOVE AMT1 TO WORK ADD AMT2 TO WORK MOVE WORK TO CALC1 ADD AMT1 TO TOTAMT1 ADD AMT2 TO TOTAMT2 ADD WORK TO TOTCALC1 SELECT (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,M5 LAST=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=INFILE PRINT DUMP ACCTNO 1, 8, C FNM 27,16,C LNM 47,32,C BAL 83,5,P,3 DEFINE TOTAL-BALANCE,8,P,2 IF FNM ="STAN" OR BAL>1000 ADD BAL TO TOTAL-BALANCE KEEP ELSE DROP ENDIF TOT 'TOTAL BALANCE IS',5 TOTAL-BALANCE,17,35,M5 TOT 'NUMBER OF RECORDS PROCESSED=',5 INPUT_ RECORD,17,35,M3 SELECT (ACCTNO,FNM,LNM,BAL,TOTAL-BALANCE) Copyright © 2012 by CSI International 17.11 DATAMINER FOR Z/OS 7.1C User Reference Guide Ex. 23: PRINT Records Within a Balance Range DataMiner Script Examples 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=INFILE PRINT ACCTNO 1 8 C BAL 83,5,P,3 DEFINE TOTAL-BALANCE,8,P,2 DEFINE PLUS_BALANCE,8,P,2 DEFINE MINUS_BALANCE,8,P,2 SKIP BAL >= 0 AND BAL <20 SKIP BAL <0 AND BAL <-1000 IF BAL > 0 ADD BAL TO PLUS_BALANCE ELSE ADD BAL TO MINUS_BALANCE ENDIF ADD BAL TO TOTAL-BALANCE SELECT (ACCTNO,BAL,PLUS_BALANCE,MINUS_BALANCE) MAXRCDS=1000 TOT 'TOTAL BALANCE IS',5 TOTAL-BALANCE,17,35,M5 TOT '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=INFILE LNM 47,32,C SHOW INFILE DELETE 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=INFILE OUTPUT=DISK FILENAME=OUTFILE VARBLK LRECL=400 BLKSIZE=20000 PRINT EXTRACT ACCTNO 1,8,C AMT1 99,3,P,3 AMT2 107,6,P,5 DEFINE RATIO,8,P,4 DEFINE TESTER,8,P,4 MOVE AMT2 TO RATIO DIVIDE RATIO BY AMT1 * Say which records we want to extract ONLY RATIO > 100 OR RATIO < -100 SELECT (ACCTNO,AMT1,AMT2,RATIO) Copyright © 2012 by CSI International 17.12 DATAMINER FOR Z/OS 7.1C User Reference Guide Ex. 26: DUMP the First 20 Records Matching Criteria DataMiner Script Examples 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=INFILE AMT1 99,3,P,3 AMT2 107,6,P,5 DUMP MAXRCDS=20 ONLY AMT1 < 0 OR AMT1 '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. COPY DUMP OUTPUT=DISK FILENAME=OUTFILE LRECL=290 BLKSIZE=29000 FIXED INPUT=DISK FILENAME=INFILE UNDEF LRECL=4000 BLKSIZE=20000 LAST=10 Copyright © 2012 by CSI International 17.14 DATAMINER FOR Z/OS 7.1C User Reference Guide Ex. 32: Create a File from Selected Fields of an Input File DataMiner Script Examples 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=VSAM ACCTNO 1,8,C FNM 27,16,C LNM 47,32,C SELECT (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. COPY INPUT=VSAM FILENAME=PRODFL OUTPUT=VSAM FILENAME=TESTFL FNM 27,16,C FINIT ",1,C LNM 47,32,C LINIT ",1,C DEFINE NEWFST 16,C DEFINE NEWLST 32,C NEWFST = 'SUSAN' IF FINIT < 'T' NEWFST = 'SAM' ENDIF IF FINIT < 'M' NEWFST = 'MARY' ENDIF IF FINIT < 'G' NEWFST = 'GEORGE' ENDIF MOVE 'BERRY' TO NEWLST IF LINIT < 'S' NEWLST = 'CLAPTON' ENDIF IF LINIT < 'N' NEWLST = 'BREAM' ENDIF IF LINIT < 'F' NEWLST = 'TROTTER' ENDIF FNM = NEWFST LNM = NEWLST Copyright © 2012 by CSI International 17.15 DATAMINER FOR Z/OS 7.1C User Reference Guide Ex. 34: PRINT Report Sorted by Fields, Create Subtotals DataMiner Script Examples 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=SYS010 INPUT=VSAM FILENAME=DEPTFL FIRST 4,12,C HEADING ('FIRST' 'NAME') LAST *,16,C DEPT 48,5,C SALARY 60,8,P,2 AUTO INPUT DEPTFL PRINT STAFF REPORT STAFF PRINTER DEPTPR ORDER DEPT BREAK DEPT TITLE 'DEPARTMENTAL STAFF REPORT' LINE 1 DEPT FIRST LAST SALARY SUM SALARY Copyright © 2012 by CSI International 17.16 DATAMINER FOR Z/OS 7.1C User Reference Guide Ex. 35: PRINT Report Sorted by Fields, File/Table Input DataMiner Script Examples 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=SYS010 INPUT=VSAM FILENAME=ACCOUNT ACCTNO 1, 8,C HEADING ('ACCOUNT' 'NUMBER') AC-CITY 41,20,C HEADING ('HOME' 'CITY') AC-PRODUCT 70,10,C AC-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 DATA DODGE RALEIGH FORD DAYTON FENDER CHATTANOOGA GIBSON 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 = ' ' ENDIF PRINT ACCOUNT-REPORT REPORT ACCOUNT-REPORT PRINTER=CITYAC ORDER AC-CITY ACCTNO SUM AC-DEBT TITLE COL 10 'ACCOUNT STATUS BY CITY AND ACCOUNT NO' LINE AC-CITY ACCTNO OFFICE AC-DEBT MARKER Copyright © 2012 by CSI International 17.17 DATAMINER FOR Z/OS 7.1C User Reference Guide Ex. 36: PRINT Name and Address Labels DataMiner Script Examples The following Report Writer example prints name and address labels. OUTPUT=PRINTER FILENAME=ADDRLAB SYSNO=SYS050 INPUT=VSAM FILENAME=CUSTFLE ACCTNO 1,8,C FNM 27,16,C LNM 47,32,C ADDR 117,32,C CITY *,32,C STATE *,2,C ZIP *,9,C AUTO INPUT CUSTFLE PRINT ADDRESS-LABEL REPORT ADDRESS-LABEL PRINTER ADDRLAB ACROSS 3 WIDTH 40 HEIGHT 5 LABELS LINE 1 FNM LNM LINE 2 ADDR LINE 3 CITY LINE 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, -SALARY BREAK 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. Copyright © 2012 by CSI International 17.18 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Script Examples (The following output is the first page.) 01/21/2012 EMPL STAFF REPORT WITH BREAK BY DEPT STARTING DEPARTMENT NUMBER FOR PAGE: WORK A00 PAGE A00 1 EMPNO 200120 200010 000120 000110 000010 ====== FIRSTNME GREG DIANE SEAN VINCENZO CHRISTINE ============ LASTNAME ORLANDO HEMMINGER O CONNELL LUCCHESI HAAS =============== SALARY 798.33 208.75 180.99 170.55 150.55 =========== B01 === B01 000020 ====== MICHAEL ============ THOMPSON =============== 200.00 =========== C01 000030 000130 000140 200140 ====== SALLY DOLORES HEATHER KIM ============ KWAN QUINTANA NICHOLLS NATZ =============== 200.00 200.00 200.00 200.00 =========== 000060 000150 000160 000170 200170 200220 ====== IRVING BRUCE ELIZABETH MASATOSHI KIYOSHI REBA ============ STERN ADAMSON PIANKA YOSHIMURA YAMAMOTO JOHN =============== 905.56 905.56 905.56 905.56 905.56 905.56 =========== 000070 000230 000270 200240 ====== EVA JAMES MARIA ROBERT ============ PULASKI JEFFERSON PEREZ MONTEVERDE =============== 200.00 200.00 200.00 200.00 =========== E01 === E01 000050 ====== JOHN ============ GEYER =============== 200.00 =========== E11 000090 000280 000290 200280 200310 ====== EILEEN ETHEL JOHN EILEEN MICHELLE ============ HENDERSON SCHNEIDER PARKER SCHWARTZ SPRINGER =============== 200.00 200.00 200.00 200.00 200.00 =========== 000100 000320 000330 000340 THEODORE RAMLAL WING JASON SPENSER MEHTA LEE GOUNOT === A00 === C01 D11 === D11 D21 === D21 === E11 E21 Copyright © 2012 by CSI International 17.19 200.00 200.00 200.00 200.00 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Script Examples (The following output is the second page.) 01/21/2012 EMPL STAFF REPORT WITH BREAK BY DEPT STARTING DEPARTMENT NUMBER FOR PAGE: WORK E21 === E21 Ex. 38: Using ORDER, BREAK, and SUMMARY Together EMPNO 200330 200340 ====== FIRSTNME HELENA ROY ============ LASTNAME WONG ALONZO =============== PAGE E21 2 SALARY 200.00 200.00 =========== The following Report Writer example uses the ORDER, BREAK, and SUMMARY 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, -SALARY BREAK 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 /* This script can produce the following output (first page): Copyright © 2012 by CSI International 17.20 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Script Examples 01/21/2012 EMPL STAFF REPORT WITH SUMMARY BY DEPT PAGE STARTING DEPARTMENT NUMBER FOR PAGE: A00 WORK A00 === A00 B01 === B01 C01 EMPNO 200120 200010 000120 000110 000010 ====== FIRSTNME GREG DIANE SEAN VINCENZO CHRISTINE ============ LASTNAME ORLANDO HEMMINGER O CONNELL LUCCHESI HAAS =============== SALARY 798.33 208.75 180.99 170.55 150.55 =========== 1509.17 000020 ====== MICHAEL ============ THOMPSON =============== 200.00 =========== 200.00 000030 000130 000140 200140 ====== SALLY DOLORES HEATHER KIM ============ KWAN QUINTANA NICHOLLS NATZ =============== 200.00 200.00 200.00 200.00 =========== 800.00 000060 000150 000200 000210 000220 200170 200220 ====== IRVING BRUCE DAVID WILLIAM JENNIFER KIYOSHI REBA ============ STERN ADAMSON BROWN JONES LUTZ YAMAMOTO JOHN =============== 905.56 905.56 905.56 905.56 905.56 905.56 905.56 =========== 9961.16 000070 000230 000240 000270 200240 ====== EVA JAMES SALVATORE MARIA ROBERT ============ PULASKI JEFFERSON MARINO PEREZ MONTEVERDE =============== 200.00 200.00 200.00 200.00 200.00 =========== 1400.00 E01 === E01 000050 ====== JOHN ============ GEYER =============== 200.00 =========== 200.00 E11 000090 000280 200280 200310 ====== EILEEN ETHEL EILEEN MICHELLE ============ HENDERSON SCHNEIDER SCHWARTZ SPRINGER =============== === C01 D11 === D11 D21 === D21 === E11 E21 000100 000320 000330 000340 THEODORE RAMLAL WING JASON SPENSER MEHTA LEE GOUNOT Copyright © 2012 by CSI International 17.21 200.00 200.00 200.00 200.00 =========== 1400.00 200.00 200.00 200.00 200.00 1 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Script Examples (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 E21 === E21 === EMPNO 200330 200340 ====== FIRSTNME HELENA ROY ============ LASTNAME WONG ALONZO =============== ====== ============ =============== SALARY 200.00 200.00 =========== 1200.00 =========== 01/21/2012 EMPL STAFF REPORT WITH SUMMARY BY DEPT STARTING DEPARTMENT NUMBER FOR PAGE: WORK EMPNO FIRSTNME Copyright © 2012 by CSI International 17.22 LASTNAME PAGE 1 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. This chapter covers the following topics: Page Overview of DATAMINER ONLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.2 How DATAMINER ONLINE Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.4 DATAMINER ONLINE Sample Screen . . . . . . . . . . . . . . . . . . . . . . . . . . 18.5 DATAMINER ONLINE Error Messages . . . . . . . . . . . . . . . . . . . . . . . . 18.11 Copyright © 2012 by CSI International 18.1 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. Copyright © 2012 by CSI International 18.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Features and Capabilities DataMiner Online 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. Copyright © 2012 by CSI International 18.3 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online 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. Copyright © 2012 by CSI International 18.4 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online 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: MINE FILEID= BKSDSIN KEY= A072 CSI-DATAMINER 7.1 VSAM UTILITY LRECL= 00100 OPER= TEMP. RCD. 007 OF 025 STRG. RCD. UPDATED THRU KEY REMOTE KEYPOS= 1...+....10...+....20...+....30...+....40...+....50...+....60...+....70...+....+ A072......IBM/MSC010GATEWAY210WSRCNT= ..JOURNALTST........................RECEND CFFF000000CCD6DECFFFCCECECEFFFEEDCDE7400DDEDDCDEEE000000000000000000000000DCCCDC 107200000092414230107135618210629353E0001649513323000000000000000000000000953554 81..+....90...+....+ ASASASASA....127.... CECECECEC0000FFF0031 1212121210000127000C PF1=PRVREC PF2=NXTREC PF3=BWD PF4=FWD PF5=BWD1/2 PF6=FWD1/2 PF7=HEX PF8=COLS 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 Copyright © 2012 by CSI International 18.5 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online 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. Copyright © 2012 by CSI International 18.6 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online The VSAM command operators you can choose from are described in the following table: VSAM Description Operator 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. Copyright © 2012 by CSI International 18.7 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online VSAM Description Operator 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. Copyright © 2012 by CSI International 18.8 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online The Temporary Storage command operators you can choose from are described in the following table: KEY Temporary Storage Operator 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. 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). Copyright © 2012 by CSI International 18.9 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online • 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. Copyright © 2012 by CSI International 18.10 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online 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. Copyright © 2012 by CSI International 18.11 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online 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 Copyright © 2012 by CSI International 18.12 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online 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 Copyright © 2012 by CSI International 18.13 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner Online 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. Copyright © 2012 by CSI International 18.14 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. This chapter covers the following topics: Page DATAMINER/VE Benefits and Features . . . . . . . . . . . . . . . . . . . . . . . . 19.2 DATAMINER/VE and 4GL, COBOL, and PL/I . . . . . . . . . . . . . . . . . . 19.4 DATAMINER/VE Access to VSAM Files . . . . . . . . . . . . . . . . . . . . . . . 19.6 DATAMINER/VE Programming Overview . . . . . . . . . . . . . . . . . . . . . . 19.7 How DATAMINER/VE Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.9 CICS and COM-PLETE Requirements . . . . . . . . . . . . . . . . . . . . . . . 19.10 Executing DATAMINER/VE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.12 CICS Temporary Storage Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.13 CICS—CONTROL-BLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.14 CICS—RECORD-AREA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.22 Batch—CONTROL-BLOCK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.23 Batch—RECORD-AREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.30 Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.31 Program Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.35 DATAMINER/VE Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.43 DATAMINER/VE Online Security . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.44 DATAMINER/VE Control Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.48 Copyright © 2012 by CSI International 19.1 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. Copyright © 2012 by CSI International 19.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Features and Capabilities DataMiner/VE 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. Copyright © 2012 by CSI International 19.3 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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. Copyright © 2012 by CSI International 19.4 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE • 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. Copyright © 2012 by CSI International 19.5 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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. Copyright © 2012 by CSI International 19.6 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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 Copyright © 2012 by CSI International 19.7 DATAMINER FOR Z/OS 7.1C User Reference Guide 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. Copyright © 2012 by CSI International 19.8 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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 Return Codes There are two components that the programmer must create before calling DATAMINER/VE: 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. 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. Copyright © 2012 by CSI International 19.9 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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). Copyright © 2012 by CSI International 19.10 DATAMINER FOR Z/OS 7.1C User Reference Guide System Parameters DataMiner/VE 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. Copyright © 2012 by CSI International 19.11 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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 NATURAL Example VNATB can be either static or dynamic. The following example is a CALL statement for NATURAL: CALL "VNATB" #RTN-CODE #FIELD1 Note Batch Assembler Example 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. The following example is a LINK statement for Batch Assembler: LINK EP=VNATB, PARAM=(CTBLK, RECORD), VL=1 Copyright © 2012 by CSI International 19.12 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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. Copyright © 2012 by CSI International 19.13 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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 Assembler Example CONTROL-BLOCK. 02 RETURN-CODE 02 ACTION-CODE 02 FILE-ID 02 RECORD-LENGTH 02 RESERVED-AREA 02 KEY-POSITION 02 KEY-LENGTH 02 KEY XXX. XXX. X(8). S9999 COMP. X(17). S9999 COMP. S9999 COMP. X(nn). The following example shows the sequence of the fields in the CONTROL-BLOCK for assembler: CTLBLK RETCODE ACTION FILEID LRECL RESERVE KEYPOS KEYLEN KEY Note RETURN-CODE (CL3) PIC PIC PIC PIC PIC PIC PIC PIC DS DS DS DS DS DS DS DS DS 0CL37 CL3 CL3 CL8 AL2 XL17'00' AL2 AL2 CLnn RETURN CODE ACTION CODE DD NAME RECORD LENGTH RESERVED (NOT SPARE!) KEY POSITION KEY LENGTH. ACTUAL KEY Do not align the fields on halfword or other boundaries. There should be no extra slack bytes in the CONTROL-BLOCK. 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). Copyright © 2012 by CSI International 19.14 DATAMINER FOR Z/OS 7.1C User Reference Guide ACTION-CODE (CL3) DataMiner/VE 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. Copyright © 2012 by CSI International 19.15 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE Code Description 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. Copyright © 2012 by CSI International 19.16 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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. Copyright © 2012 by CSI International 19.17 DATAMINER FOR Z/OS 7.1C User Reference Guide FILE-ID (CL8) DataMiner/VE Code Description 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. 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. Copyright © 2012 by CSI International 19.18 DATAMINER FOR Z/OS 7.1C User Reference Guide RECORD-LENGTH (BL2) DataMiner/VE 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. Copyright © 2012 by CSI International 19.19 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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. Copyright © 2012 by CSI International 19.20 DATAMINER FOR Z/OS 7.1C User Reference Guide KEY (Variable) DataMiner/VE 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. Copyright © 2012 by CSI International 19.21 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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 2 #EMP-NAME 2 #EMP-ADR 2 #FILLER-1 2 #EMP-SSNO 2 #FILLER-2 2 #FILLER-3 (A6) (A30) (A30) (A5) (A9) (A200) (A120) Copyright © 2012 by CSI International 19.22 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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 Assembler Example CONTROL-BLOCK. 02 RETURN-CODE 02 ACTION-CODE 02 FILE-ID 02 RECORD-LENGTH 02 RESERVED-AREA 02 PASSWORD-LG 02 PASSWORD 02 KEY-LENGTH 02 KEY PIC PIC PIC PIC PIC PIC PIC PIC PIC XXX. XXX. X(8). S9999 COMP. X(10). X. X(8). S9999 COMP. X(nn). The following example shows the field sequence for an assembler CONTROL-BLOCK: CTLBLK RETCODE ACTION FILEID LRECL RESERVE PWDLEN PASSWD KEYLEN KEY DS DS DS DS DS DS DS DS DS DS 0CL35 CL3 CL3 CL8 AL2 XL10'00' BL1 CL8 AL2 CLnn RETURN CODE ACTION CODE DD NAME RECORD LENGTH RESERVED (NOT SPARE!) PASSWORD LENGTH KEY LENGTH. 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].) Copyright © 2012 by CSI International 19.23 DATAMINER FOR Z/OS 7.1C User Reference Guide ACTION-CODE (CL3) DataMiner/VE 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. Copyright © 2012 by CSI International 19.24 DATAMINER FOR Z/OS 7.1C User Reference Guide Code DataMiner/VE Description 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 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 LST The use of this ACTION-CODE is recommended only if the user needs to lock a Control-Interval to ensure record integrity. The use of this ACTION-CODE is recommended only if the user needs to lock a Control-Interval to ensure record integrity. Retrieve the last record on the dataset. The KEY field is ignored for retrieval and is then filled with the full key. Copyright © 2012 by CSI International 19.25 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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. Copyright © 2012 by CSI International 19.26 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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. Copyright © 2012 by CSI International 19.27 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE Code Description 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. 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. Copyright © 2012 by CSI International 19.28 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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-LENGT H (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. Copyright © 2012 by CSI International 19.29 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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 2 2 2 2 2 2 2 #EMPLOYEE-RECORD #EMP-NO (A6) #EMP-NAME (A30) #EMP-ADR (A30) #FILLER-1 (A5) #EMP-SSNO (A9) #FILLER-2 (A200) #FILLER-3 (A120) Copyright © 2012 by CSI International 19.30 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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). Copyright © 2012 by CSI International 19.31 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE Code Explanation 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. Copyright © 2012 by CSI International 19.32 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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. Copyright © 2012 by CSI International 19.33 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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. Copyright © 2012 by CSI International 19.34 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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 Copyright © 2012 by CSI International 19.35 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 2: Online NATURAL Program (Single-File Access) DataMiner/VE 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 Copyright © 2012 by CSI International 19.36 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 3: Online NATURAL Program (Multiple-File Access) DataMiner/VE 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 2 #EMP-NO (A6) 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 2 #PAY-SSNO (A9) 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 MOVE H'00' TO #EMP-NO * REPEAT MOVE 'EMPFILE ' TO #FILE-ID MOVE #EMPNO TO #KEY MOVE 'NXT` TO #ACTION-CODE CALL 'VNAT' #RETURN-CODE #EMPNO IF #RETURN-CODE EQ 'EOF' ESCAPE IF #RETURN-CODE NE '000' PERFORM SHOW-EMP-RTNCODE MOVE 'PAYROLL' TO #FILE-ID MOVE #EMP-SSNO TO #KEY MOVE 'GEQ` TO #ACTION-CODE CALL 'VNAT' #RETURN-CODE #PAY-SSNO IF #RETURN-CODE NE '000' PERFORM SHOW-GET-RTNCODE PERFORM CHANGE-PAYROLL MOVE 'RPL` TO #ACTION-CODE CALL 'VNAT' #RETURN-CODE #PAY-SSNO IF #RETURN-CODE NE '000' PERFORM SHOW-RPL-RTNCODE LOOP ...END /*EMPLOYEE RECORD - 221 BYTES /*KEY /*PAYROLL RECORD - 466 BYTES /*KEY /*SET TO BINARY ZEROS /*START AT BEGINNING OF FILE /*SET FILE-ID TO EMPLOYEE FILE /*MOVE EMPLOYEE NO. TO KEY /*GET EMPLOYEE RECORD /*GET EMPLOYEE RECORD /*END OF FILE-QUIT /*REQUEST UNSUCCESSFUL? /* YES, SHOW ERROR TO USER /*SET FILE-ID TO PAYROLL FILE /*MOVE SSNO TO KEY /*GET PAYROLL RECORD /*GET PAYROLL RECORD /*REQUEST UNSUCCESSFUL? /* YES, SHOW ERROR TO USER /*SHOW & CHANGE PAYROLL RECORD /*REPLACE PAYROLL RECORD /*REPLACE PAYROLL RECORD /*REQUEST UNSUCCESSFUL? /*YES, SHOW ERROR TO USER /*LOOP Copyright © 2012 by CSI International 19.37 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 4: Online Assembler Program DataMiner/VE 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. Copyright © 2012 by CSI International 19.38 DATAMINER FOR Z/OS 7.1C User Reference Guide CTLLEN CONTROL RETURN ACTION FILEID LENGTH RESERVE KEYPOS KEYLEN KEY RECORD CMLEN DataMiner/VE DS DS DS DS DS DS DS DS DS DS DS DS EQU H LENGTH OF CONTROL BLOCK 0H START OF CONTROL BLOCK CL3 RETURN CODE FROM DATAMINER/VE CL3 ACTION FOR VSMA/EASY TO PERFORM CL8 FCT FILENAME BL2 RECORD LENGTH XL17 "RESERVED AREA" – DO NOT TOUCH!!! AL2 KEY POSITION (PROVIDED BY DATAMINER/VE) AL2 KEY LENGTH (PROVIDED BY DATAMINER/VE) CL10 IF THE KEY IS 10 BYTES LONG 0D ALIGN RECORD (OPTIONAL – SEE NOTE ABOVE) CL500 IF THE MAXIMUM LRECL IS 500 BYTES *-CTLLEN MVC MVC MVC CTLLEN,=AL2(RECORD-CONTROL)SET CONTROL BLOCK LENGTH ACTION,C'GEQ' WHAT WE WANT DATAMINER/VE TO DO 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. 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 Copyright © 2012 by CSI International 19.39 NOT NEEDED DATAMINER FOR Z/OS 7.1C User Reference Guide Example 5: Batch NATURAL Program DataMiner/VE 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 Copyright © 2012 by CSI International 19.40 DATAMINER FOR Z/OS 7.1C User Reference Guide Example 6: Dynamic Call to VNATB DataMiner/VE 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. 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 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. Copyright © 2012 by CSI International 19.41 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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. 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 Copyright © 2012 by CSI International 19.42 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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 Load Library Modules Source Library Module Refer to the DataMiner Installation Notes for detailed installation instructions (www.csi-international.com). The Load Library Modules are: VNAT CICS VSAM interface module VNATB Batch VSAM interface stub VNATB2 Batch VSAM interface module VNATCTL DATAMINER/VE control table (mainly for future development) The Source Library Module is: VSCTYTBL Sample Online Security Table Copyright © 2012 by CSI International 19.43 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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 Copyright © 2012 by CSI International 19.44 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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. Copyright © 2012 by CSI International 19.45 DATAMINER FOR Z/OS 7.1C User Reference Guide Security Module Source DataMiner/VE 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 = UPDATE ORG SCTYTBL REDEFINE FOR ACTUAL DATA Copyright © 2012 by CSI International 19.46 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE *------------------------------------------------------------------* * 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 Copyright © 2012 by CSI International 19.47 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE 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 * * * * * VNATCTL * * * * * * * * * * * * * MXF * * * * * * * * * EMPTY 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. 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. 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 DC CL3'NOP' DEFAULT VALUE Copyright © 2012 by CSI International 19.48 20 DATAMINER/VE Support This chapter contains programming and troubleshooting information for DATAMINER/VE. This chapter covers the following topics: Page DataMiner/VE Programming Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.2 Troubleshooting DataMiner/VE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.6 VSAM Basics for DataMiner/VE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.9 Copyright © 2012 by CSI International 20.1 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. Copyright © 2012 by CSI International 20.2 DATAMINER FOR Z/OS 7.1C User Reference Guide File Sharing DataMiner/VE Support 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-PLET E 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. Copyright © 2012 by CSI International 20.3 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE Support 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. Copyright © 2012 by CSI International 20.4 DATAMINER FOR Z/OS 7.1C User Reference Guide NATURAL Packed Fields in Keys DataMiner/VE Support 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. Copyright © 2012 by CSI International 20.5 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE Support 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. Copyright © 2012 by CSI International 20.6 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE Support 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. Copyright © 2012 by CSI International 20.7 DATAMINER FOR Z/OS 7.1C User Reference Guide Incorrect Installation of New Release of VNATB / VNATB2 with NATURAL DataMiner/VE Support 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. Copyright © 2012 by CSI International 20.8 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE Support 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. Copyright © 2012 by CSI International 20.9 DATAMINER FOR Z/OS 7.1C User Reference Guide DataMiner/VE Support 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. Copyright © 2012 by CSI International 20.10 DATAMINER FOR Z/OS 7.1C User Reference Guide RRDS (Relative Record Dataset) DataMiner/VE Support 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. Copyright © 2012 by CSI International 20.11 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International 20.12 DataMiner/VE Support Commands Index Symbols @LBL, 8.11 A ABEND command, 14.2 ADD command, 10.10 ADVANCE command, 11.12 AFTER OUTPUT timing command, 8.15 arithmetic commands, 10.9–10.13 ADD, 10.10 DIVIDE, 10.13 MULTIPLY, 10.12 SUBTRACT, 10.11 AUTO command, 2.2 BEGIN, 2.3 EOF, 2.3 B BEFORE INPUT timing command, 8.15 BEGIN. See AUTO command BREAK command, 11.14 C CALL…[USING] command, 8.14 CLOAK command, 10.8 CLOSE command, 15.7 COMMIT command, 15.8 conditionals DO WHILE and ENDDO statements, 8.6 IF…[ELSE]…ENDIF statements, 8.3 SELECT…[WHERE] command, 6.17 CONNECT command, 15.3 COPY command, 6.3 COPY shortcut command, 6.3 D data manipulation commands ADD, 10.10 arithmetic commands, 10.9–10.13 CLOAK, 10.8 DIVIDE, 10.13 HIDE, 10.7 MOVE, 10.4 MULTIPLY, 10.12 SET, 10.6 SUBTRACT, 10.11 DATACARDs command, 3.12 DB2 commands CLOSE, 15.7 COMMIT, 15.8 CONNECT, 15.3 EXECUTE, 15.6 INPUT=, 15.4 OUTPUT=, 15.5 ROLLBACK, 15.9 DEFINE command, 5.3 DELETE command, 6.14 DELETE shortcut command, 6.14 DIVIDE command, 10.13 DO WHILE and ENDDO statements, 8.6 DROP command, 9.9 DUMP command, 6.12 DUMP shortcut command, 6.12 DURING INPUT timing command, 8.15 DURING OUTPUT timing command, 8.15 Copyright © 2012 by CSI International Commands Index.1 DATAMINER FOR Z/OS 7.1C User Reference Guide E EOF. See AUTO command EXECUTE command, 15.6 EXIT command, 8.13 EXTRACT command, 6.6 EXTRACT shortcut command, 6.6 F Commands Index MAXRCDS= command, 9.18 MOVE command, 10.4 MULTIPLY command, 10.12 N NODATE command, 11.22 NOPAGE command, 11.22 O FIND command OFFSET= command, 2.11 ONLY command, 9.16 ORDER command, 11.23 tables FIND command, 12.14 FIRST= command, 9.4; 9.5 FIRSTKEY command, 9.4 flow control @LBL, 8.11 CALL…[USING] command, 8.14 EXIT command, 8.13 GOTO, 8.11 labels, 8.11 PERFORM command, 8.10 PROC…[GOBACK]…ENDPROC statements, 8.8 FREQ= command, 9.7 G GAP command, 11.16 GOTO statements, 8.11 H HD command, 6.15 HEADING command, 11.17 HEIGHT command, 11.11 HIDE command, 10.7 I IF…[ELSE]…ENDIF statements, 8.3 INPUT= command, 3.3 INPUT= command (DB2), 15.4 INSERT command, 7.12 INSERT shortcut command, 7.12 K KEEP command, 9.8 L labels, 8.11 LABELS command, 11.18 LAST= command, 9.6 LENGTH command, 11.19 LINE command, 11.20 M MASK command, 11.7 output commands ABEND, 14.2 HD, 6.15 MAXRCDS=, 9.18 OFFSET=, 2.11 STATS, 2.13 TOT, 6.15; 6.16; 6.20 VALIDATE=, 2.14 OUTPUT= command, 3.7 OUTPUT= command (DB2), 15.5 P PERFORM command, 8.10 POINT command, 7.5 examples, 7.8 PRINT command, 6.8 PRINT shortcut command, 6.8 PRINTER command, 11.26 PROC…[GOBACK]…ENDPROC statements, 8.8 R READ command, 7.3 Report Writer commands ADVANCE, 11.12 BREAK, 11.14 GAP, 11.16 HEADING, 11.17 HEIGHT, 11.11 LABELS, 11.18 LENGTH, 11.19 LINE, 11.20 MASK, 11.7 NODATE, 11.22 NOPAGE, 11.22 ORDER, 11.23 PRINTER, 11.26 SUM, 11.13; 11.27; 11.28 SUMMARY, 11.29 Copyright © 2012 by CSI International Commands Index.2 DATAMINER FOR Z/OS 7.1C User Reference Guide Commands Index TITLE, 11.30 WIDTH, 11.11 ROLLBACK command, 15.9 SUMMARY command, 11.29 S tables T TABLE command, 12.2 SELECT…[WHERE] command, 6.17 SET command, 10.6 shortcut commands COPY, 6.3 DELETE, 6.14 DUMP, 6.12 EXTRACT, 6.6 INSERT, 7.12 PRINT, 6.8 UPDATE, 6.5; 6.5 SHOW command, 14.4 SKIP command, 9.14 SORT command, 13.2 START command, 9.10 STATS command, 2.13 STOP command, 9.12 SUBTRACT command, 10.11 SUM command, 11.13; 11.27; 11.28 TABLE command, 12.2 timing commands, 8.15–8.17 AFTER OUTPUT, 8.15 BEFORE INPUT, 8.15 DURING INPUT, 8.15 DURING OUTPUT, 8.15 TITLE command, 11.30 TOT command, 6.15; 6.16; 6.20 TRACE command, 14.6 U UPDATE command, 6.5 UPDATE shortcut command, 6.5 V VALIDATE= command, 2.14 W WIDTH command, 11.11 WRITE command, 7.6 examples, 7.8 Copyright © 2012 by CSI International Commands Index.3 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International Commands Index.4 Commands Index General Index Numerics 954 Abend, 20.7 A ABEND Command, 14.2 Arithmetic Commands accumulators, 10.9 and IF commands, 10.9 AUTO command, 2.2 AUTO mode, 2.4 specifying, 2.2 B browsing, 19.26 C CANCEL Command, 14.3 CICS temporary storage keys, 18.10 Commands arithmetic commands and IF commands, 10.9 Data Manipulation Commands MOVE, 10.4 SET field=literal, 10.6 SET field1=field2, 10.6 DO WHILE and ENDDO, 8.6 IF commands, 8.5; 8.11 multi-field commands, 7.13 SELECT, 6.17 WHERE, 6.18 output commands ABEND Command, 14.2 CANCEL Command, 14.3 HD Command, 6.15 MAXRCDS Command, 9.18 OFFSET= Command, 2.11 TOT Command, 6.15; 6.16; 6.20 VALIDATE Command, 2.14 POINT, 7.5 READ, 7.3 record selector commands DROP, 9.9 FIRST=, 9.5 FIRSTKEY=, 9.4 FREQ=, 9.7 KEEP, 9.8 LAST=, 9.6 SKIP, 9.14 START, 9.10 STOP, 9.12 script commands INPUT=, 3.3 OUTPUT=, 3.7 sequence, 2.6 effects of, 2.6 shortcut commands, 6.2 COPY, 6.3 DATACARDS, 3.12 DELETE, 6.14 DUMP, 6.12 EXTRACT, 6.6 Copyright © 2012 by CSI International General Index.1 DATAMINER FOR Z/OS 7.1C User Reference Guide INSERT, 7.12 PRINT, 6.8 UPDATE, 6.5 SHOW, 14.4 COMPLETE, 19.6; 19.27 COPY Command, 6.3 D Data Manipulation Commands constraints, 10.2 MOVE, 10.4 SET field=literal, 10.6 SET field1=field2, 10.6 DATACARDS Command, 3.12 Data-Miner Online access records, 18.4 browsing files, 18.4 browsing temporary storage queues, 18.4 CICS Temporary Storage Queues, 18.2 DATA-AREA, 18.10 description, 18.2 error messages, 18.11 FILEID, 18.5 KEY, 18.9 LRECL, 18.6 OPER, 18.6 PF KEYS, 18.10 RECORD NUMBER, 18.5 REMOTE KEYPOS, 18.10 sample screen, 18.5 security, 18.2 supported environments, 18.2 THRU-KEY, 18.9 DELETE Command, 6.14 DISPLAY Command, 7.14 DO WHILE and ENDDO Commands, 8.6 DUMP Command, 6.12 DUMP command, 6.12 DUMP shortcut command, 6.12 E ESDS Keys, 18.10 EXTRACT Command, 6.6 F fields General Index work fields, 2.4 File Reading errors during, 7.4 example, read randomly using POINT, 7.3 example, read randomly using READREAD Command example, 7.4 File Reading, randomly, 7.3 G General DMIN Messages, list of, 16.12 H HD Command, 6.15 I IF Commands example, 8.5 statement labels, 8.11 using with list of values, 8.5 INPUT Command Parameters BLKSIZE=, 3.5; 3.9 INPUT= Command description, 3.3 parameters FIXED, 3.6; 3.10 REUSE, 3.10 UNDEF or UNDEFINED, 3.6; 3.10 VARBLK, 3.6; 3.10 INSERT Command, 7.12 IO-RESULT, 1.4; 7.4 K KEY, 18.9 KSDS Keys, 18.9 L Literals binary, 5.17 character, 5.15 hexadecimal, 5.16 numeric, 5.17 packed decimal, 5.15 zoned decimal, 5.16 literals Copyright © 2012 by CSI International General Index.2 DATAMINER FOR Z/OS 7.1C User Reference Guide using quotation marks, 5.15 using quotes, 5.15 M main input dataset, defined, 2.2 main output dataset, defined, 2.2 MAXRCDS Command, 9.18 MOVE Commands, 10.4 MRO, 18.10 Multi-Field Commands example, 7.13 SELECT, 6.17 WHERE, 6.18 N NATURAL, 19.30 new NXT, defined, 19.20 new PRV, defined, 19.20 Nonunique records, 20.4 O OFFSET= Command, 2.11 OUTPUT Command Parameters BLKSIZE=, 3.5; 3.9 Output Commands ABEND Command, 14.2 CANCEL Command, 14.3 HD Command, 6.15 MAXRCDS Command, 9.18 OFFSET= Command, 2.11 TOT Command, 6.15; 6.16; 6.20 VALIDATE Command, 2.14 OUTPUT= Command description, 3.7 parameters FIXED=, 3.6; 3.10 REUSE, 3.10 UNDEF or UNDEFINED, 3.6; 3.10 VARBLK=, 3.6; 3.10 P POINT Command, 7.5 example, 7.3; 7.8 PRINT Command, 6.8 General Index R READ Command, 7.3 example, 7.8 Record Fields example, create, 4.7 Record Selector Commands DROP, 9.9 execution order, 9.2 FIRST=, 9.5 FIRSTKEY=, 9.4 FREQ=, 9.7 KEEP, 9.8 LAST=, 9.6 ONLY, 9.16 rules, 9.3 SKIP, 9.14 SKIP, special note, 9.14 START, 9.10 STOP, 9.12 REMOTE KEYPOS, 18.10 report, 6.8 Report Writer Additional REPORT Commands ACROSS, WIDTH, HEIIGHT, 11.11 ADVANCE, 11.12 BREAK, 11.14 GAP, 11.16 HEADING, 11.17 LABELS, 11.18 LENGTH nnn, 11.19 LINE, 11.20 NODATE and NOPAGE, 11.22 ORDER, 11.23 PRINTER, 11.26 SUM, 11.13; 11.27; 11.28 SUMMARY, 11.29 TITLE, 11.30 column heading, 11.6 description, 11.2 example create tabular report, 6.9 tabular report output, 6.10 field definition, 11.3; 11.6 REPORT Command example, 11.5; 11.8 RRDS Keys, 18.9 Copyright © 2012 by CSI International General Index.3 DATAMINER FOR Z/OS 7.1C User Reference Guide S Script Commands INPUT=, 3.3 OUTPUT=, 3.7 POINT, 7.5 READ, 7.3 script readability words that are always ignored, 2.8 SELECT Command, 6.17 SET Command field=literal, 10.6 field1=field2, 10.6 Shortcut Commands constraints, 6.2 COPY, 6.3 DATACARDS, 3.12 DELETE, 6.14 DUMP, 6.12 EXTRACT, 6.6 INSERT, 7.12 PRINT, 6.8 SHOW, 14.4 UPDATE, 6.5 shortcut commands DUMP, 6.12 SHOW Command, 14.4 SHOW Fieldname Command example, 14.4 SHOW File Command example, 14.4 skip sequential processing, 19.16; 19.26 Statement Labels and IF command, 8.11 System Work Fields example, 5.12 FIRST_RECORD, 5.13 INPUT_RECORD, 5.13 LAST_RECORD, 5.13 MAX_RECORDS, 5.13 OUTPUT_RECORD, 5.13 RETURN_CODE, 5.13 system constants, 5.18 T0-T9, 5.14 VALIDATION_ERRORS, 5.14 General Index T T0 through T9, 10.9 TABLE Command example, data from file, 12.3 example, data in script, 12.3 filling a table, 12.2 temporary storage online commands, 18.6 Temporary Storage Queue, 18.9 Temporary Storage Queues, 18.2 THRU KEY, 18.9 TOT Command, 6.15; 6.16; 6.20 U UPDATE, 2.5 UPDATE Command, 6.5 V VALIDATE Command, 2.14 VSAM/Easy batch application access, 19.7 Batch Assembler example, 19.12 CICS access, 19.7 CICS users, 19.10 COBOL example, 19.12 COM-PLETE users, 19.10 control table source, 19.48 environments, 19.8 general access, 19.7 Installation library modules, 19.43 NATURAL example, 19.12 online security adding or changing security entries, 19.45 exclusive, 19.44 inclusive, 19.44 installed modes, 19.44 methodology, 19.44 security table, 19.44 RECORDAREA and CONTROL-BLOCK, 19.9 return codes, 19.9 sequence, 19.9 system requirements, 19.10 temporary storage, 19.13 Copyright © 2012 by CSI International General Index.4 DATAMINER FOR Z/OS 7.1C User Reference Guide VSAM/EASY Batch CONTROL-BLOCK ACTION-CODE, 19.24 Assembler example, 19.23 COBOL example, 19.23 FILE-ID, 19.28 KEY, 19.29 KEY-LENGTH, 19.29 PASSWORD, 19.29 PASSWORD-LENGTH, 19.29 RECORD-LENGTH, 19.28 RESERVED-AREA, 19.29 RETURN-CODE, 19.23 VSAM/EASY Batch RECORD-AREA, 19.30 VSAM/Easy CICS CONTROL-BLOCK ACTION-CODE, 19.15 Assembler example, 19.14 COBOL example, 19.14 FILE-ID, 19.18 KEY, 19.21 KEY-LENGTH, 19.20 KEY-POSITION, 19.20 General Index RECORD-LENGTH, 19.19 RESERVED-AREA, 19.20 RETURN-CODE, 19.14 VSAM/Easy CICS RECORD-AREA, 19.22 VSAM/Easy Examples of Use Batch Assembler Program, 19.42 Batch NATURAL Program, 19.40 Dynamic Call to VNATB, 19.41 Online Assembler Program, 19.38 Online Command Level COBOL Program, 19.35 Online NATURAL Program (Multiple File Access), 19.37 Online NATURAL Program (Single File Access), 19.36 Static Call to VNATB, 19.41 W WHERE Command, 6.18 work fields, 2.4 WRITE Command example, 7.8 Copyright © 2012 by CSI International General Index.5 DATAMINER FOR Z/OS 7.1C User Reference Guide Copyright © 2012 by CSI International General Index.6 General Index