CA Easytrieve Report Generator 11 6
Uploaded by
GirishCA Easytrieve Report Generator 11 6
Uploaded by
GirishCA Easytrieve® Report Generator 11.
6
CA Easytrieve® Report Generator 11.6
Table of Contents
Announcements and News............................................................................................................... 21
Release Notes.....................................................................................................................................22
New Features.................................................................................................................................................................. 22
New Features Since Release 6.4.................................................................................................................................. 24
Differences Between Releases..................................................................................................................................... 30
Release Comparison...................................................................................................................................................... 45
Migration Guidelines...................................................................................................................................................... 46
CA SMP/E Internet Service Retrieval........................................................................................................................... 47
Portfolio Simplification.................................................................................................................................................. 48
Simplified Design System............................................................................................................................................. 50
Documentation Changes............................................................................................................................................... 50
Installing.............................................................................................................................................. 52
Installation Best Practices............................................................................................................................................ 52
Install CA Easytrieve for Windows.............................................................................................................................. 53
Install CA Easytrieve for UNIX and Linux for zSeries................................................................................................54
Install CA Easytrieve for Linux PC.............................................................................................................................. 57
Install CA Easytrieve for z/OS...................................................................................................................................... 62
How the Installation Process Works......................................................................................................................... 64
Preparing for Installation........................................................................................................................................... 65
Install Your Product Using CA CSM.........................................................................................................................66
Acquire Products Using CA CSM......................................................................................................................67
Install Products Using CA CSM........................................................................................................................ 72
Maintain Products Using CA CSM.................................................................................................................... 87
Configure Your Product Using CA CSM..........................................................................................................102
Installing Your Product Using Pax ESD or DVD.................................................................................................... 110
Allocate and Mount a File System.................................................................................................................. 112
Acquire the Product Pax Files.........................................................................................................................113
Create a Product Directory from the Pax File.................................................................................................117
Copy Installation Files to zOS Data Sets........................................................................................................118
Prepare the SMPE Environment for a Pax Installation................................................................................... 119
Run the Installation Jobs for a Pax Installation...............................................................................................120
Clean Up the USS Directory........................................................................................................................... 121
Apply Preventive Maintenance........................................................................................................................ 121
SAMPJCL and CBAAJCL Contents........................................................................................................................125
Upgrade CA Easytrieve for z/OS................................................................................................................................ 128
Install CA Easytrieve Packaged with CCS................................................................................................................ 129
2
CA Easytrieve® Report Generator 11.6
Install CA Easytrieve SDS........................................................................................................................................... 129
Install the License Key................................................................................................................................................ 130
Maintain Your Product................................................................................................................................................. 131
Configuring........................................................................................................................................132
Configuration Best Practices...................................................................................................................................... 132
Configure Your Product...............................................................................................................................................134
Configure With CA CSM......................................................................................................................................... 134
Configure Without CA CSM.................................................................................................................................... 134
Create the Options File and Update Its Settings............................................................................................ 134
Migrate Options Table Settings (from 6.4)...................................................................................................... 135
Migrate Options Table Settings (within 11 versions)....................................................................................... 135
Printer Set Definition........................................................................................................................................135
Activate the 6.4 Compatibility IDMS and IMS Interface Option...................................................................... 136
Create the DBCS Options Module.................................................................................................................. 137
Activate the Oracle Interface Option............................................................................................................... 137
Activate the SUPRA Interface Option............................................................................................................. 137
Activate the TOTAL Interface Option...............................................................................................................138
Assemble a User Requirements Table for the CA Datacom/DB Option......................................................... 139
Language Environment (LE) Considerations...................................................................................................139
Macro Libraries................................................................................................................................................ 139
Unit Record Exits............................................................................................................................................. 140
Configure Your System................................................................................................................................................142
Setting Environment Variables................................................................................................................................ 142
Updating the Table.................................................................................................................................................. 145
Compiler Options............................................................................................................................................. 151
Execution Options............................................................................................................................................ 159
Environmental Options.....................................................................................................................................163
Sort Options..................................................................................................................................................... 166
SQL Options.....................................................................................................................................................169
IDMS Options...................................................................................................................................................171
Report Options................................................................................................................................................. 173
Mask Options................................................................................................................................................... 177
International Options........................................................................................................................................ 178
Printer Profile Definition................................................................................................................................... 179
Getting Started................................................................................................................................. 182
Programming Lessons.................................................................................................................................................186
Lesson 1 - Library Section, FILE and DEFINE Statements................................................................................... 186
Lesson 2 - Activity Section, JOB and IF Statements............................................................................................. 189
Lesson 3 - Activity Section, Report Output with PRINT Statement........................................................................192
3
CA Easytrieve® Report Generator 11.6
Lesson 4 - Activity Section, REPORT Statement and Report Definition Statements............................................. 197
Library Section - Describe and Define Data............................................................................................................. 203
Describe Files and Fields....................................................................................................................................... 206
Activity Section - Processing and Logic................................................................................................................... 217
JOB Activities.......................................................................................................................................................... 217
SORT Activities....................................................................................................................................................... 233
PROGRAM Activities...............................................................................................................................................235
Activity Section - Input and Output........................................................................................................................... 236
Activity Section - Reporting........................................................................................................................................246
Processing of Reports.............................................................................................................................................250
Label Report............................................................................................................................................................257
Testing Aid Parameters...........................................................................................................................................259
Format Determination Parameters..........................................................................................................................260
Multiple Reports...................................................................................................................................................... 262
Report Procedures (PROCs).................................................................................................................................. 264
System-Defined Fields................................................................................................................................................. 274
General Purpose Fields.......................................................................................................................................... 274
File Processing Fields.............................................................................................................................................275
Report Processing Fields........................................................................................................................................277
Using.................................................................................................................................................. 279
Using Best Practices................................................................................................................................................... 279
Create and Format a Report....................................................................................................................................... 281
Compile and Link Your Program................................................................................................................................ 286
Controlling Compilation........................................................................................................................................... 286
Results of the Compilation......................................................................................................................................288
Program Compilation and Link-Editing Using JCL................................................................................................. 291
Submitting Your Program for Non-Mainframe Compilation.................................................................................... 301
Link-Editing Non-Mainframe Programs................................................................................................................... 305
Execute a Program.......................................................................................................................................................310
Execute a Program in UNIX and Linux for zSeries................................................................................................310
Execute a Program in Windows............................................................................................................................. 311
Execute a Program in z/OS....................................................................................................................................311
File Description String (Non-Mainframe Only)........................................................................................................312
Execute a Windows Indexed File Program............................................................................................................ 313
Execute a Btrieve Program.....................................................................................................................................315
Execute a C-ISAM Program................................................................................................................................... 316
Report Display Facility (z/OS Only)........................................................................................................................ 317
Error Analysis Report..............................................................................................................................................322
Execute a Program on a Web Server.................................................................................................................... 323
Alternate Collating Sequence Table........................................................................................................................... 329
4
CA Easytrieve® Report Generator 11.6
Extended Reporting..................................................................................................................................................... 332
Printing Concepts.................................................................................................................................................... 334
Printer Characteristics............................................................................................................................................. 350
Font Characteristics................................................................................................................................................ 367
Set Up Source Control Supports............................................................................................................................... 373
Workbench.....................................................................................................................................................................377
Main Window...........................................................................................................................................................377
Opening Windows................................................................................................................................................... 381
Manage Files and Applications...............................................................................................................................382
Edit Source or Text Files........................................................................................................................................ 387
Build and Run Programs........................................................................................................................................ 391
Debug Programs..................................................................................................................................................... 393
Set Preferences.......................................................................................................................................................403
Configuration Manager............................................................................................................................................406
Create or Modify an Options Table................................................................................................................. 407
Create or Modify a Printer Set Definition........................................................................................................ 411
Workbench Tools and Utilities.................................................................................................................................421
Workbench Explore..........................................................................................................................................421
Host Profile Manager....................................................................................................................................... 426
Program Profile Manager.................................................................................................................................428
Workbench Utilities.......................................................................................................................................... 433
Creating Toolkit and Writing Scripts........................................................................................................................439
Defining a Tools Menu.....................................................................................................................................439
Using the R2SCRIPT Processor..................................................................................................................... 444
Workbench Help...................................................................................................................................................... 453
CA Easytrieve/Earl Usage........................................................................................................................................... 453
CA Easytrieve SDS.......................................................................................................................................................454
Create a JCL/Submit Prolog Source File............................................................................................................... 455
Create a Project and Host Profile.......................................................................................................................... 456
Import File and Field Definitions.............................................................................................................................457
Design and Run a Report.......................................................................................................................................457
Programming.................................................................................................................................... 459
Text Conventions and Field Rules............................................................................................................................. 459
Code Programs.............................................................................................................................................................460
Structured Programming......................................................................................................................................... 461
Program Sections....................................................................................................................................................462
Define Files and Fields........................................................................................................................................... 463
8-Byte Binary Fields................................................................................................................................................467
Declarations.............................................................................................................................................................469
Literal and Data Formatting Rules..........................................................................................................................470
5
CA Easytrieve® Report Generator 11.6
Control Program Flow............................................................................................................................................. 473
Assignments and Moves.........................................................................................................................................480
Table Processing..................................................................................................................................................... 488
Array Processing..................................................................................................................................................... 490
Inter-Program Linkage.............................................................................................................................................500
Code Efficient Programs......................................................................................................................................... 517
Code CICS Programs............................................................................................................................................. 518
Multiple Platform Considerations............................................................................................................................ 519
SQL Database Processing.......................................................................................................................................... 519
Programming Methods............................................................................................................................................ 520
CA Easytrieve SQL Statement Rules..................................................................................................................... 521
Program Environment............................................................................................................................................. 521
Library Section Definition........................................................................................................................................ 525
CA Easytrieve SQL Files........................................................................................................................................ 532
Automatic Retrieval Without a File......................................................................................................................... 537
Native SQL Processing...........................................................................................................................................539
ODBC Data Sources...............................................................................................................................................544
Access a CSV File as an SQL File.................................................................................................................544
Access an Excel Spreadsheet as an SQL File............................................................................................... 545
CA IDMS Database Processing.................................................................................................................................. 546
CA IDMS Interface.................................................................................................................................................. 548
IDD Interface........................................................................................................................................................... 561
Sample Database and Logical Record................................................................................................................... 563
IMS/DLI Database Processing.....................................................................................................................................567
Test Database......................................................................................................................................................... 568
PCB and PSB Processing...................................................................................................................................... 569
Automatic Input....................................................................................................................................................... 570
Controlled Processing Using DLI Statements........................................................................................................ 575
IMS Fast Path DEDB Processing...........................................................................................................................579
CA Datacom/DB Database Processing...................................................................................................................... 580
Access the Database.............................................................................................................................................. 580
Access Macros........................................................................................................................................................ 581
File Processing............................................................................................................................................................. 594
File Processing Modes............................................................................................................................................596
Sequential Files.......................................................................................................................................................598
Virtual File Manager................................................................................................................................................ 600
Indexed Files........................................................................................................................................................... 601
Relative Files...........................................................................................................................................................604
Sorting Files............................................................................................................................................................ 608
Synchronized File Processing.................................................................................................................................610
6
CA Easytrieve® Report Generator 11.6
PRINTER Files........................................................................................................................................................ 615
Non-Mainframe Files............................................................................................................................................... 615
Report Processing........................................................................................................................................................617
PRINT Statement (Report Processing)...................................................................................................................618
Report Formats....................................................................................................................................................... 620
Report Generation...................................................................................................................................................622
Standard Reports.................................................................................................................................................... 624
Label Reports.......................................................................................................................................................... 630
XML Reports........................................................................................................................................................... 632
Sequenced Reports.................................................................................................................................................633
CONTROL Reports................................................................................................................................................. 634
Report Procedures.................................................................................................................................................. 652
Routing Printer Output............................................................................................................................................ 662
Use Extended Reporting.........................................................................................................................................664
Extended Reporting Concepts................................................................................................................................ 665
Report Layout Processing.......................................................................................................................................678
Screen Processing....................................................................................................................................................... 685
Screen Format.........................................................................................................................................................686
Use the SCREEN Statement.................................................................................................................................. 688
Screen Title Area.................................................................................................................................................... 690
Screen Work Area...................................................................................................................................................691
Format an Item for Display..................................................................................................................................... 693
Automatic Editing of Input............................................................................................................................... 696
Edit Error Messages........................................................................................................................................ 704
Cursor Placement............................................................................................................................................ 704
Repeating Rows of Data................................................................................................................................. 705
Screen Message Area............................................................................................................................................ 706
Screen Function Key Area......................................................................................................................................707
Screen Key Processing...........................................................................................................................................707
Screen Procedures..................................................................................................................................................708
Programmer-Defined Procedures.................................................................................................................... 709
Branch Actions................................................................................................................................................. 709
CICS Pseudo-conversational Programs.......................................................................................................... 711
Send Messages............................................................................................................................................... 711
Determine the Cursor Location........................................................................................................................713
Test for Field Modification................................................................................................................................713
Setting Errors................................................................................................................................................... 714
Commit Processing................................................................................................................................................. 715
Sample Screen Applications................................................................................................................................... 720
Macro Facility................................................................................................................................................................728
7
CA Easytrieve® Report Generator 11.6
Invoke a Macro....................................................................................................................................................... 729
Define Macros......................................................................................................................................................... 730
Process Macros.......................................................................................................................................................731
In-stream Macros.................................................................................................................................................... 733
SUPRA Interface Option.............................................................................................................................................. 734
SUPRA Interface Operation.................................................................................................................................... 735
SUPRA GET.................................................................................................................................................... 738
SUPRA INCLUDE............................................................................................................................................ 738
SUPRA ON ERROR........................................................................................................................................ 742
SUPRA RESET................................................................................................................................................742
SUPRA SIGN-OFF...........................................................................................................................................742
SUPRA SIGN-ON............................................................................................................................................ 743
Example JCL and SUPRA Statements........................................................................................................... 743
TOTAL Interface Option............................................................................................................................................... 749
%ADDM - Add Master (TOTAL)............................................................................................................................. 751
%ADDV - Add Variable (TOTAL)............................................................................................................................ 751
%CBLCNVRT.......................................................................................................................................................... 752
%CLOSX - Close TOTAL File.................................................................................................................................753
%CONCAT...............................................................................................................................................................753
%CONVAE...............................................................................................................................................................753
%CONVEA.............................................................................................................................................................. 754
%DATECALC...........................................................................................................................................................755
%DATECONV.......................................................................................................................................................... 756
%DATEVAL..............................................................................................................................................................757
%DELM....................................................................................................................................................................758
%DELVD.................................................................................................................................................................. 759
%DFNTOTF............................................................................................................................................................. 759
%EZSSID.................................................................................................................................................................760
%EZTINI.................................................................................................................................................................. 760
%FINDX...................................................................................................................................................................761
%GETCALEN.......................................................................................................................................................... 761
%GETJULI...............................................................................................................................................................762
%RDNXT................................................................................................................................................................. 762
%OPENX................................................................................................................................................................. 763
%READD................................................................................................................................................................. 763
%READM.................................................................................................................................................................764
%READR................................................................................................................................................................. 764
%READV................................................................................................................................................................. 765
%RGHTJUST.......................................................................................................................................................... 766
%SINOF...................................................................................................................................................................766
8
CA Easytrieve® Report Generator 11.6
%SINON.................................................................................................................................................................. 767
%VERNUMP............................................................................................................................................................767
%WRITM................................................................................................................................................................. 768
%WRITV.................................................................................................................................................................. 768
Example - Retrieve Records Using a Tickler File.................................................................................................. 769
Language Reference........................................................................................................................ 772
Character Sets.............................................................................................................................................................. 772
Statements.....................................................................................................................................................................774
Statement Overview................................................................................................................................................ 782
% (Macro Invocation) Statement............................................................................................................................ 786
* (Comment) Statement.......................................................................................................................................... 787
ACCESS Statement................................................................................................................................................ 787
AFTER-BREAK Report Procedure..........................................................................................................................787
AFTER-LINE Report Procedure..............................................................................................................................789
AFTER-SCREEN Screen Procedure...................................................................................................................... 791
Assignment Statement............................................................................................................................................ 792
ATTR Parameter..................................................................................................................................................... 796
BEFORE-BREAK Report Procedure.......................................................................................................................798
BEFORE-LINE Report Procedure...........................................................................................................................800
BEFORE-SCREEN Screen Procedure................................................................................................................... 800
CALL Statement...................................................................................................................................................... 801
CASE and END-CASE Statements........................................................................................................................ 802
CLOSE Statement...................................................................................................................................................804
COMMIT Statement................................................................................................................................................ 805
Conditional Expressions..........................................................................................................................................805
Field Bits Condition..........................................................................................................................................806
Field Class Condition.......................................................................................................................................807
Field Relational Condition................................................................................................................................809
Field Series Condition......................................................................................................................................812
File Presence Condition...................................................................................................................................813
File Relational Condition..................................................................................................................................815
Record Relational Condition............................................................................................................................ 816
CONTROL Statement............................................................................................................................................. 817
COPY Statement.....................................................................................................................................................818
CURSOR Statement............................................................................................................................................... 819
DECLARE Statement.............................................................................................................................................. 820
DEFAULT Statement............................................................................................................................................... 822
DEFINE Statement..................................................................................................................................................823
DELETE Statement................................................................................................................................................. 831
DISPLAY Statement................................................................................................................................................ 832
9
CA Easytrieve® Report Generator 11.6
DLI Statement......................................................................................................................................................... 835
DO UNTIL and DO WHILE Statements................................................................................................................. 838
ENDPAGE Report Procedure................................................................................................................................. 840
END-PROC Statement............................................................................................................................................841
ENDTABLE Statement............................................................................................................................................ 841
EXECUTE Statement.............................................................................................................................................. 841
EXIT Statement....................................................................................................................................................... 842
FETCH Statement................................................................................................................................................... 843
FILE Statement....................................................................................................................................................... 843
GET Statement........................................................................................................................................................853
GOTO Statement.................................................................................................................................................... 854
HEADING Statement...............................................................................................................................................856
IDD FILE Statement................................................................................................................................................857
IDD NAME Statement............................................................................................................................................. 858
IDD RECORD Statement........................................................................................................................................859
IDD SUBSCHEMA Statement.................................................................................................................................859
IDD VERSION Statement....................................................................................................................................... 860
IDMS ACCEPT DBKEY Statement.........................................................................................................................861
IDMS ACCEPT PAGE-INFO Statement................................................................................................................. 861
IDMS ACCEPT PROCEDURE Statement..............................................................................................................862
IDMS ACCEPT STATISTICS Statement.................................................................................................................862
IDMS BIND Statement............................................................................................................................................ 862
IDMS BIND FILE Statement................................................................................................................................... 863
IDMS BIND PROCEDURE Statement....................................................................................................................864
IDMS COMMIT Statement...................................................................................................................................... 864
IDMS CONNECT Statement................................................................................................................................... 864
IDMS DISCONNECT Statement............................................................................................................................. 865
IDMS ERASE Statement........................................................................................................................................ 865
IDMS FIND and IDMS OBTAIN Statements...........................................................................................................866
IDMS FINISH Statement......................................................................................................................................... 868
IDMS GET Statement............................................................................................................................................. 868
IDMS IF Statement................................................................................................................................................. 869
IDMS KEEP Statement........................................................................................................................................... 869
IDMS MODIFY Statement.......................................................................................................................................870
IDMS OBTAIN Statement........................................................................................................................................870
IDMS READY Statement........................................................................................................................................ 871
IDMS RETURN Statement......................................................................................................................................871
IDMS ROLLBACK Statement................................................................................................................................. 872
IDMS STORE Statement........................................................................................................................................ 872
IF, ELSE-IF, ELSE, and END-IF Statements.......................................................................................................... 873
10
CA Easytrieve® Report Generator 11.6
INITIATION Screen Procedure................................................................................................................................877
INSERT Statement.................................................................................................................................................. 877
JOB Statement........................................................................................................................................................ 878
KEY Statement........................................................................................................................................................881
LINE Statement....................................................................................................................................................... 883
LINK Statement....................................................................................................................................................... 885
LIST Statement....................................................................................................................................................... 886
MACRO Statement..................................................................................................................................................886
MASK Parameter.................................................................................................................................................... 887
MEND Statement.................................................................................................................................................... 891
MESSAGE Statement............................................................................................................................................. 891
MOVE Statement.................................................................................................................................................... 892
MOVE LIKE Statement........................................................................................................................................... 894
MSTART Statement.................................................................................................................................................896
NEWPAGE Statement............................................................................................................................................. 896
PARM Statement..................................................................................................................................................... 896
PERFORM Statement............................................................................................................................................. 905
POINT Statement.................................................................................................................................................... 906
POP Statement....................................................................................................................................................... 907
PRINT Statement.................................................................................................................................................... 907
PROC Statement.....................................................................................................................................................908
PROGRAM Statement............................................................................................................................................ 909
PUSH Statement..................................................................................................................................................... 912
PUT Statement........................................................................................................................................................912
READ Statement..................................................................................................................................................... 913
RECORD Statement (CA IDMS and IMS/DLI)....................................................................................................... 914
REFRESH Statement..............................................................................................................................................916
RELEASE Statement.............................................................................................................................................. 917
REPEAT and END-REPEAT Statements................................................................................................................917
REPORT Statement................................................................................................................................................ 919
REPORT-INPUT Report Procedure........................................................................................................................924
RESHOW Statement...............................................................................................................................................926
RETRIEVE Statement (CA IDMS and IMS/DLI).....................................................................................................927
ROLLBACK Statement............................................................................................................................................930
ROW Statement...................................................................................................................................................... 931
SCREEN Statement................................................................................................................................................ 935
SEARCH Statement................................................................................................................................................ 937
SELECT Statement (File-based SQL).................................................................................................................... 938
SELECT Statement (Non-file SQL)........................................................................................................................ 940
SELECT Statement (Report Selection).................................................................................................................. 942
11
CA Easytrieve® Report Generator 11.6
SELECT Statement (Sort Selection).......................................................................................................................943
SEQUENCE Statement...........................................................................................................................................944
SET Statement........................................................................................................................................................ 944
SKIP Statement.......................................................................................................................................................947
SORT Statement..................................................................................................................................................... 947
SQL Statement........................................................................................................................................................949
SQL INCLUDE Statement.......................................................................................................................................954
STOP Statement..................................................................................................................................................... 956
SUM Statement....................................................................................................................................................... 957
TERMINATION Report Procedure.......................................................................................................................... 958
TERMINATION Screen Procedure..........................................................................................................................958
TITLE Statement (Reports)..................................................................................................................................... 959
TITLE Statement (Screens).................................................................................................................................... 960
TRANSFER Statement............................................................................................................................................961
UPDATE Statement.................................................................................................................................................962
WRITE Statement................................................................................................................................................... 962
Symbols and Reserved Words................................................................................................................................... 964
Conversion from Old to Current CA Easytrieve Version......................................................................................... 967
Messages and Codes...................................................................................................................... 969
SUPRA Diagnostic Messages..................................................................................................................................... 969
Operational Diagnostic Messages.......................................................................................................................... 970
A001................................................................................................................................................................. 970
A002................................................................................................................................................................. 970
A003................................................................................................................................................................. 971
A004................................................................................................................................................................. 971
A005................................................................................................................................................................. 971
A006................................................................................................................................................................. 971
A007................................................................................................................................................................. 972
A008................................................................................................................................................................. 972
A009................................................................................................................................................................. 972
A010................................................................................................................................................................. 972
A012................................................................................................................................................................. 972
A013................................................................................................................................................................. 973
A101................................................................................................................................................................. 973
A102................................................................................................................................................................. 973
A103................................................................................................................................................................. 973
A104................................................................................................................................................................. 973
Syntax Diagnostic Messages..................................................................................................................................974
B001................................................................................................................................................................. 974
B002................................................................................................................................................................. 974
12
CA Easytrieve® Report Generator 11.6
B003................................................................................................................................................................. 974
B004................................................................................................................................................................. 974
B005................................................................................................................................................................. 974
B007................................................................................................................................................................. 975
B008................................................................................................................................................................. 975
B009................................................................................................................................................................. 975
B010................................................................................................................................................................. 975
B011................................................................................................................................................................. 975
B012................................................................................................................................................................. 976
B014................................................................................................................................................................. 976
Program Abend Messages (EZABX).......................................................................................................................... 976
EZABX000............................................................................................................................................................... 976
EZABX008............................................................................................................................................................... 977
EZABX009............................................................................................................................................................... 977
EZABX010............................................................................................................................................................... 977
EZABX016............................................................................................................................................................... 977
EZABX020............................................................................................................................................................... 977
EZABX024............................................................................................................................................................... 978
EZABX046............................................................................................................................................................... 978
EZABX047............................................................................................................................................................... 978
EZABX048............................................................................................................................................................... 979
EZABX049............................................................................................................................................................... 979
EZABX050............................................................................................................................................................... 979
EZABX051............................................................................................................................................................... 979
EZABX053............................................................................................................................................................... 979
EZABX054............................................................................................................................................................... 979
EZABX055............................................................................................................................................................... 980
EZABX056............................................................................................................................................................... 980
EZABX057............................................................................................................................................................... 980
EZABX058............................................................................................................................................................... 980
EZABX059............................................................................................................................................................... 980
EZABX060............................................................................................................................................................... 980
EZABX061............................................................................................................................................................... 981
EZABX062............................................................................................................................................................... 981
Linking, Transferring and Calling Messages............................................................................................................ 981
EZACT001............................................................................................................................................................... 981
EZACT002............................................................................................................................................................... 981
EZACT005............................................................................................................................................................... 982
Utility Messages........................................................................................................................................................... 982
EZALT001................................................................................................................................................................ 982
13
CA Easytrieve® Report Generator 11.6
EZALT002................................................................................................................................................................ 982
EZALT003................................................................................................................................................................ 982
EZALT004................................................................................................................................................................ 982
EZALT005................................................................................................................................................................ 983
EZALT006................................................................................................................................................................ 983
EZALT007................................................................................................................................................................ 983
EZALT008................................................................................................................................................................ 983
EZALT009................................................................................................................................................................ 983
EZALT010................................................................................................................................................................ 984
EZALT011................................................................................................................................................................ 984
EZALT012................................................................................................................................................................ 984
EZALT013................................................................................................................................................................ 984
EZALT014................................................................................................................................................................ 984
Configuration Manager Messages..............................................................................................................................985
EZCM001.................................................................................................................................................................985
EZCM002.................................................................................................................................................................985
EZCM003.................................................................................................................................................................985
EZCM004.................................................................................................................................................................985
EZCM005.................................................................................................................................................................985
EZCM006.................................................................................................................................................................986
EZCM007.................................................................................................................................................................986
EZCM008.................................................................................................................................................................986
EZCM009.................................................................................................................................................................986
EZCM010.................................................................................................................................................................986
EZCM011................................................................................................................................................................. 986
EZCM012.................................................................................................................................................................986
EZCM013.................................................................................................................................................................987
EZCM014.................................................................................................................................................................987
EZCM015.................................................................................................................................................................987
EZCM016.................................................................................................................................................................987
EZCM017.................................................................................................................................................................987
EZCM018.................................................................................................................................................................987
EZCM019.................................................................................................................................................................988
EZCM020.................................................................................................................................................................988
EZCM021.................................................................................................................................................................988
EZCM022.................................................................................................................................................................988
EZCM023.................................................................................................................................................................988
EZCM024.................................................................................................................................................................988
IMS_DLI Messages....................................................................................................................................................... 988
EZDLI001.................................................................................................................................................................989
14
CA Easytrieve® Report Generator 11.6
EZDLI002.................................................................................................................................................................989
EZDLI003.................................................................................................................................................................989
Program Abend Messages (EZEIP)............................................................................................................................ 989
EZEIP001................................................................................................................................................................ 989
EZEIP003................................................................................................................................................................ 990
EZEIP004................................................................................................................................................................ 990
EZEIP005................................................................................................................................................................ 990
EZEIP006................................................................................................................................................................ 990
EZEIP007................................................................................................................................................................ 990
EZEIP011.................................................................................................................................................................991
EZEIP015................................................................................................................................................................ 991
EZEIP017................................................................................................................................................................ 991
EZEIP018................................................................................................................................................................ 991
EZEIP019................................................................................................................................................................ 991
EZEIP021................................................................................................................................................................ 992
EZEIP022................................................................................................................................................................ 992
EZEIP023................................................................................................................................................................ 992
EZEIP024................................................................................................................................................................ 992
EZEIP025................................................................................................................................................................ 993
EZEIP028................................................................................................................................................................ 993
EZEIP992................................................................................................................................................................ 993
EZEIP997................................................................................................................................................................ 993
IDMS Messages............................................................................................................................................................ 993
EZIDM001................................................................................................................................................................993
EZIDM002................................................................................................................................................................994
EZIDM003................................................................................................................................................................994
File I_O Messages........................................................................................................................................................ 994
EZIOE001................................................................................................................................................................ 994
EZIOE002................................................................................................................................................................ 994
EZIOE003................................................................................................................................................................ 996
EZIOE004................................................................................................................................................................ 997
EZIOE005................................................................................................................................................................ 998
EZIOE007................................................................................................................................................................ 998
EZIOE008................................................................................................................................................................ 998
EZIOE009................................................................................................................................................................ 999
EZIOE011.............................................................................................................................................................. 1000
System Initialization Messages................................................................................................................................ 1000
EZKX0001............................................................................................................................................................. 1000
EZKX0004............................................................................................................................................................. 1000
EZKX0012............................................................................................................................................................. 1000
15
CA Easytrieve® Report Generator 11.6
EZKX0013............................................................................................................................................................. 1001
EZKX0014............................................................................................................................................................. 1001
EZKX0016............................................................................................................................................................. 1001
EZKX0017............................................................................................................................................................. 1001
EZKX0060............................................................................................................................................................. 1001
EZKX0061............................................................................................................................................................. 1001
ETOPLOAD Utility Messages.................................................................................................................................... 1002
EZOPT001.............................................................................................................................................................1002
EZOPT002.............................................................................................................................................................1002
EZOPT003.............................................................................................................................................................1002
EZOPT004.............................................................................................................................................................1002
EZOPT005.............................................................................................................................................................1002
EZOPT008.............................................................................................................................................................1003
EZOPT009.............................................................................................................................................................1003
EZOPT010.............................................................................................................................................................1003
EZOPT011............................................................................................................................................................. 1003
EZOPT012.............................................................................................................................................................1003
EZOPT013.............................................................................................................................................................1003
EZOPT014.............................................................................................................................................................1004
EZOPT015.............................................................................................................................................................1004
EZOPT016.............................................................................................................................................................1004
EZOPT017.............................................................................................................................................................1004
EZOPT018.............................................................................................................................................................1004
EZOPT020.............................................................................................................................................................1004
EZOPT021.............................................................................................................................................................1004
System Termination Message................................................................................................................................... 1005
EZSHT101............................................................................................................................................................. 1005
SQL Messages............................................................................................................................................................ 1005
EZSQL001............................................................................................................................................................. 1005
EZSQL002............................................................................................................................................................. 1005
EZSQL003............................................................................................................................................................. 1006
EZSQL004............................................................................................................................................................. 1006
EZSQL005............................................................................................................................................................. 1006
Sort Messages............................................................................................................................................................ 1006
EZSRT008............................................................................................................................................................. 1006
EZSRT009............................................................................................................................................................. 1006
EZSRT013............................................................................................................................................................. 1007
Compiler Messages....................................................................................................................................................1008
EZTC0744E........................................................................................................................................................... 1008
Runtime Error Check Codes..................................................................................................................................... 1009
16
CA Easytrieve® Report Generator 11.6
EBND.....................................................................................................................................................................1009
EBSN..................................................................................................................................................................... 1009
Runtime Code Generator Codes.............................................................................................................................. 1009
ECGO.................................................................................................................................................................... 1009
IMS_DLI Interface Codes........................................................................................................................................... 1010
EDLI.......................................................................................................................................................................1010
Dynamic Loader Codes............................................................................................................................................. 1010
EDSN.....................................................................................................................................................................1010
EDSO.....................................................................................................................................................................1010
Dynamic Segment Manager Codes.......................................................................................................................... 1010
EDSA..................................................................................................................................................................... 1010
EDSO0...................................................................................................................................................................1010
EDSS..................................................................................................................................................................... 1010
EDST..................................................................................................................................................................... 1011
EDSX..................................................................................................................................................................... 1011
Heap Manager Codes.................................................................................................................................................1011
EBND0...................................................................................................................................................................1011
EBSL......................................................................................................................................................................1011
EFLD......................................................................................................................................................................1011
EFML..................................................................................................................................................................... 1011
EFNF..................................................................................................................................................................... 1011
EFVL......................................................................................................................................................................1012
EHMD.................................................................................................................................................................... 1012
EHMF.....................................................................................................................................................................1012
EHMH.................................................................................................................................................................... 1012
EHMI......................................................................................................................................................................1012
EHML.....................................................................................................................................................................1012
EHMN.................................................................................................................................................................... 1012
EHMO.................................................................................................................................................................... 1012
EHMQ.................................................................................................................................................................... 1013
EHMR.................................................................................................................................................................... 1013
EHMV.................................................................................................................................................................... 1013
EHMW................................................................................................................................................................... 1013
EHMX.................................................................................................................................................................... 1013
Input_Output Statement Handler Codes..................................................................................................................1013
EIO0.......................................................................................................................................................................1013
EIO1.......................................................................................................................................................................1013
EIO2.......................................................................................................................................................................1014
EIO3.......................................................................................................................................................................1014
EIO4.......................................................................................................................................................................1014
17
CA Easytrieve® Report Generator 11.6
EIO5.......................................................................................................................................................................1014
EIO6.......................................................................................................................................................................1014
EIO9.......................................................................................................................................................................1014
EIOA...................................................................................................................................................................... 1014
EIDA...................................................................................................................................................................... 1015
EIOX...................................................................................................................................................................... 1015
Activity Management Codes..................................................................................................................................... 1015
EJA1...................................................................................................................................................................... 1015
System Spool Printer Interface Module Codes.......................................................................................................1015
EJSO..................................................................................................................................................................... 1015
EJSC......................................................................................................................................................................1015
EJSW.....................................................................................................................................................................1015
Task Execution Control Program Codes................................................................................................................. 1015
EKX0......................................................................................................................................................................1016
EKX1......................................................................................................................................................................1016
EKX2......................................................................................................................................................................1016
EKX5......................................................................................................................................................................1016
EKS6......................................................................................................................................................................1016
EKX7......................................................................................................................................................................1016
EKX8......................................................................................................................................................................1016
EKX9......................................................................................................................................................................1016
EKXB..................................................................................................................................................................... 1017
EKXC..................................................................................................................................................................... 1017
EKXE..................................................................................................................................................................... 1017
EKXF..................................................................................................................................................................... 1017
EKXG.....................................................................................................................................................................1017
EKXH..................................................................................................................................................................... 1017
Task Management Program Codes.......................................................................................................................... 1017
EKX3......................................................................................................................................................................1017
EKX4......................................................................................................................................................................1018
EKX80....................................................................................................................................................................1018
EKXA..................................................................................................................................................................... 1018
EKXD..................................................................................................................................................................... 1018
EKXI.......................................................................................................................................................................1018
EKXO.....................................................................................................................................................................1018
EKXS..................................................................................................................................................................... 1018
Program Link Manager Codes.................................................................................................................................. 1019
EPML..................................................................................................................................................................... 1019
Printer File Manager Codes...................................................................................................................................... 1019
EPR0..................................................................................................................................................................... 1019
18
CA Easytrieve® Report Generator 11.6
EPR1..................................................................................................................................................................... 1019
EPR2..................................................................................................................................................................... 1019
EPR3..................................................................................................................................................................... 1019
EPR4..................................................................................................................................................................... 1019
EPR5..................................................................................................................................................................... 1019
EPR6..................................................................................................................................................................... 1020
EPR9..................................................................................................................................................................... 1020
Reporting Codes.........................................................................................................................................................1020
ERP1..................................................................................................................................................................... 1020
ERP2..................................................................................................................................................................... 1020
Runtime Initialization Stub Codes............................................................................................................................1020
ERS0..................................................................................................................................................................... 1020
ERS1..................................................................................................................................................................... 1020
Sort Interface Codes.................................................................................................................................................. 1020
ESIB.......................................................................................................................................................................1021
SQL Interface Codes..................................................................................................................................................1021
ESQ1..................................................................................................................................................................... 1021
ESQ2..................................................................................................................................................................... 1021
ESQX.....................................................................................................................................................................1021
ESQY.....................................................................................................................................................................1021
EZIO...................................................................................................................................................................... 1021
Terminal Printer Despooler Program Codes........................................................................................................... 1021
ETID.......................................................................................................................................................................1022
ETIO...................................................................................................................................................................... 1022
ETIS....................................................................................................................................................................... 1022
ETIX....................................................................................................................................................................... 1022
Terminal Printer Interface Program Codes..............................................................................................................1022
ETPS..................................................................................................................................................................... 1022
Virtual File Manager Codes.......................................................................................................................................1022
EVF0......................................................................................................................................................................1022
EVF1......................................................................................................................................................................1022
EVF2......................................................................................................................................................................1023
EVF3......................................................................................................................................................................1023
EVF4......................................................................................................................................................................1023
EVF5......................................................................................................................................................................1023
EVF6......................................................................................................................................................................1023
EVF7......................................................................................................................................................................1023
EVF8......................................................................................................................................................................1023
EVF9......................................................................................................................................................................1024
EVFA......................................................................................................................................................................1024
19
CA Easytrieve® Report Generator 11.6
EVFB..................................................................................................................................................................... 1024
EVFC..................................................................................................................................................................... 1024
EVFD..................................................................................................................................................................... 1024
EVFE..................................................................................................................................................................... 1024
EVFF......................................................................................................................................................................1024
EVFG..................................................................................................................................................................... 1025
EVFH..................................................................................................................................................................... 1025
EVFI....................................................................................................................................................................... 1025
CA EZ/Key....................................................................................................................................... 1026
Documentation for Previous Releases........................................................................................ 1027
Additional Resources.................................................................................................................... 1028
Product Names............................................................................................................................... 1029
Product Accessibility Features.................................................................................................... 1030
Documentation Legal Notice........................................................................................................ 1031
20
CA Easytrieve® Report Generator 11.6
Announcements and News
• You can download documentation for previous releases of CA Easytrieve® products. To learn more, select Legacy
Bookshelves and PDF on the Tech Docs Portal.
• CA Easytrieve Version 11.6 now uses Continuous Delivery (CD) to provide features and fixes more efficiently. The
Incremental Release model bundled groups of features and fixes together into incremental updates. The CD model
provides more flexibility to select which service stream elements you want to apply and lets us provide you with earlier
access to features and fixes. To learn more, see the New Features article.
21
CA Easytrieve® Report Generator 11.6
Release Notes
Welcome to the CA Easytrieve® Report Generator Release Notes for Release 11.6. This section contains information
about key features and enhancements.
New Features
This article describes the following new features, enhancements, and changes in CA Easytrieve Report Generator for
Release 11.6:
8-Byte Binary Field Support
Support for 8-byte binary fields has been added. This allows access to BIGINT fields when processing a DB2 database.
Support for 8-byte binary fields also allows communicating with external programs that process 8-byte binary data.
Previously, this was not possible. Support for 8-byte binary provides extended range for CA Easytrieve Report Generator
programs that process binary data that exceeds the range of 4-byte binary data. For more information, see 8-Byte Binary
Fields.
Big Integer Value Support
Support for processing Big Integer (BIGINT) fields as 8-byte binary fields has been added to eliminate the possibility of
data loss. Previously, BIGINT fields were processed as 10-byte packed fields. Because 10-byte packed fields can have no
more than 18 digits and BIGINT fields can have up to 19 digits, data loss could have occurred.
CA Chorus Software Manager Support
CA Easytrieve Report Generator now supports CA Chorus™ Software Manager (CA CSM) Release 6.0. CA CSM is an
application that simplifies and unifies the management of CA Technologies mainframe products on z/OS systems.
CA CSM provides services that make it easier for you to perform the following actions:
• Acquire, install, deploy, and configure products
• Automatically obtain and apply maintenance
These services let you easily manage your software based on industry-accepted best practices. The web-based interface
provides a user-friendly environment that lets you install and maintain your products faster and with less chance of error.
With CA CSM Release 6.0, you can:
• Configure products without the need to deploy them first.
• Filter target zones in a multizone SMP/E environment and organize them in zone sets.
• Schedule an automatic maintenance update for all or some products that are installed in an SMP/E environment.
• Manage product maintenance in a unified and simplified manner.
In addition, the SMP/E Environments tab was reworked to let you navigate through your SMP/E environments easier and
faster, and improve your overall user experience.
NOTE
• To install CA CSM, go to the DOWNLOAD MANAGEMENT section of CA Support at http://support.ca.com.
• For more information about CA CSM, see the CA CSM documentation.
• For information about installing CA Easytrieve Report Generator, see Installing.
22
CA Easytrieve® Report Generator 11.6
Linux PC Support
CA Easytrieve Report Generator can now be installed in the Linux PC environment. For more information, see Install CA
Easytrieve for Linux PC.
Character Comparison Using Custom Collating Sequence Table
The new keyword COMPAREUSINGALTSEQ has been added to the PARM statement to enable character comparison
using custom collating sequence table. For more information, see PARM Statement.
EZTCOM Module Size Increase
The EZTCOM module is larger in CA Easytrieve Report Generator Release 11.6. Depending on your system settings, you
may need to specify a region on the EXEC statement or JOBCARD to obtain enough space.
Examples
The EXEC statement has the following format:
//STEP1 EXEC PGM=EZTPA00,REGION=2M
The JOBCARD has the following format:
REGION=OM
IDD NAME RETRIEVAL Parameter Ignored
The RETRIEVAL parameter of the IDD NAME statement is now ignored. Previously, the RETRIEVAL parameter caused a
compiler error. Ignoring the RETRIEVL parameter lets your job continue without error.
Library Name Changes
The library names have been changed to conform to new CA Technologies z/OS packaging standards.
We recommend that you review the following table to determine the impact to your installation:
Original Name New Name Description
CAIJCL CBAAJCL Target library
CAILIB CBAALOAD Target library
CAIMAC CBAAMAC Target library
C$AB5LLD ABAALOAD Distribution library
C$AB5MLD ABAAMAC Distribution library
C$AB5SLD ABAASRC Distribution library
Continuous Delivery
CA Easytrieve uses the continuous delivery (CD) release model for the delivery of new features. In the CD release model:
• Enhancements are delivered in the maintenance service stream as feature PTFs. New product features and fixes are
no longer bundled together.
• Enhancements are delivered disabled to give you more control over when and how the features are implemented. With
new features disabled, you control when to make the new features available for use in your environment. An explicit
action is required to enable the feature.
• Individual product fixes are provided when needed, separate from product features. You can apply product fixes
without enabling new features, which limits exposure to additional features being applied in a production environment.
These changes can limit SMP/E dependencies that were forced previously by bundling features and fixes together.
23
CA Easytrieve® Report Generator 11.6
After full integration and regression testing with other CA Technologies products, the enhancement and product fixes
are added into the CA Recommended Service for z/OS (CA RS), ensuring product quality and the integrity of your
environment. CA RS is an important part of a good preventive maintenance philosophy that lets you develop and
implement a proactive maintenance strategy in which you apply preventive maintenance on a regular schedule.
IMPORTANT
We recommend that you use the CA SMP/E Internet Service Retrieval to acquire product maintenance. This
service uses the IBM SMP/E RECEIVE ORDER command and can reduce hours of maintenance time to
just minutes. You can acquire maintenance on demand or can schedule an SMP/E job to run regularly, which
eliminates time consuming fix searches and the need to select maintenance manually through the Broadcom
Support Portal.
New Features Since Release 6.4
This article summarizes the new features and enhancements since CA Easytrieve Plus Release 6.4 that are included in
this release.
Enhancements Since Release 11 SP4
Enhancements since Release 11 SP4 include:
• Workfile Site Option
• Warning Message Condition Code Option
Workfile Site Option
Storage of intermediate reporting data can now be automatically directed to Report Workfiles (temporary sequential disk
files), instead of Virtual files (VFM). This is accomplished through the WORKFILE option. You can additionally specify the
number of cylinders to be allocated for each dynamically allocated Report Workfile by using the WORKFSPA parameter.
Warning Message Condition Code Option
WARNCC specifies which condition code the compiler returns for warning messages. Typically a compilation that reports
only warning messages returns with a condition code of 4. You cannot override this value during program compilation.
The WARNCC option has the following format:
WARNCC {F|S|Z}
• F
Returns a condition code of 4 for warnings. This is the default.
• S
Returns a condition code of 16 for warnings.
• Z
Returns a condition code of 0 for warnings.
Enhancements for Release 11 SP3
Enhancements for Release 11 SP3 include:
• Support for multiple SSIDs with CA PAN/SQL feature
• Determine data set block size
• New Function mode
24
CA Easytrieve® Report Generator 11.6
Support for Multiple SSIDs with CA Pan/SQL Feature
This feature allows a CA Easytrieve Report Generator program to invoke a specific DB2 PAN/SQL installation from among
multiple installations based on the value specified for PARM SSID in the program. With this feature, if you have multiple
versions of DB2 installed, you can have multiple CA PAN/SQL installations for each DB2 within a single library, and select
the DB2 you want to access by way of the PARM SSID value in the program. This is done by building the Easytrieve
SSID Table which is a cross-reference table that assigns a specific PAN/SQL installation with a DB2 SSID. The SAMPJCL
member SSIDTBL is used to build the table. Information about how to create multiple PAN/SQL for DB2 installations in the
same load library is provided with PAN/SQL.
NOTE
In Release 11.6, member SSIDTBL is in hlq.CBAAJCL.
Determine Data Set Blocksize
The new BLOCK0 option specifies whether a system-determined block size is used for files that do not have the logical
length and block size coded. This option passes a zero value to the operating system, which in turn determines the
optimum block size.
Use this option only if your operating system supports IBM system determined block size.
NOTE
You can override this option through Block-length of the FILE statement. There is no PARM statement override.
This option has the following format:
BLOCK0 {N|D|P|A}
• N
Indicates that the system does not determine the block size for data sets. Specify the block size through JCL or the
FILE statement. This is the default.
• D
Indicates that the system determines the block size for data sets that are stored in a tape or a disk.
• P
Indicates that the system determines the block size for data sets stored in a PRINTER.
• A
Indicates that the system determines the block size for data sets stored in a tape, disk or a PRINTER.
NOTE
This option was available in Release 6.4 but was not in Release 11 prior to SP3.
New Function Mode
NEWFUNC is a new option in the Options Table. The NEWFUNC option specifies whether to use the standard Release
11.x compiler or the compatibility mode compiler to compile your CA Easytrieve Report Generator programs. This option
does not have any impact on link-edited CA Easytrieve Report Generator application programs. NEWFUNC applies only
to z/OS.
The NEWFUNC option has the following format:
NEWFUNC {Y|N}
• Y
Compiles and runs programs using the latest product release. This option incorporates all new functionality. This is the
default.
• N
25
CA Easytrieve® Report Generator 11.6
Compiles and runs programs using the compatibility mode of CA Easytrieve Plus Report Generator. This option gives
you more control when moving your applications to CA Easytrieve Report Generator Release 11.x.
NOTE
• You cannot override this option in the PARM statement.
• For more information about the standard and compatibility mode compilers, see Migration Guidelines.
• For information about running programs in New Function mode, see Configuration Best Practices.
Enhancements for Release 11 SP2
Enhancements for Release11 SP2 include:
• New options
• Modified options
• Unsupported options
New Options
New options for Release 11 SP2 include:
• AMODE31 {Y|N}
Specifies the location of where memory is to be allocated during the execution of the CA Easytrieve Report
Generator application program. (execution time, z/OS only)
– Setting AMODE31 to Y allows all possible memory allocations to be made above the 16meg line.
– Setting AMODE31 to N causes all possible memory allocations to be made below the 16meg line.
– Storage allocation below the 16meg line is required if the Easytrieve application program calls, (or uses as a FILE
EXIT), a 24-bit subprogram. The default is Y.
– You can override this value through PARM CALL(AMODE31|AMODE24)
When the subprogram being called is link-edited as AMODE(24) and if any parameters are being passed to that
program, those parameters must reside in memory that is located below the 16meg line. Memory location can be
controlled at the following installation level as well as at the program level:
– Installation level
To force all storage below the 16meg line for all CA Easytrieve Report Generator programs, set the AMODE31
Installation Option to N. For more information see Configuration Best Practices and Updating the Table.
– Program level
To force storage below the 16meg line for a specific CA Easytrieve Report Generator program, you must specify the
CALL(AMODE24) parameter in the PARM statement in the program.
• MTVSERR (Y|N)
Determines how an empty input VSAM file is to be handled. Setting MTVSERR to Y will cause the CA Easytrieve
Report Generator I/O system to treat an empty VSAM input file as an I/O error condition. This will cause the immediate
abnormal termination of the program. Setting MTVSERR to N will cause an empty VSAM input file to be handled as
though it is at End-Of-File. The default is N.
• SPRTXIT modname
Specifies the name of a user-supplied SYSPRINT exit routine. The modname must be a valid program name. For more
information on the SYSPRINT exit capability, see Unit Record Exits. This is an execution time option for z/OS only. The
default is no exit name (blanks).
26
CA Easytrieve® Report Generator 11.6
Modified Options
The following options have been renamed or modified:
Former 6.X Name Current Release 11.x Name
ALL31 AMODE31
ALTSEQ ALTSEQU
LIST LISTPRM, LISTFIL, LISTUC
MACRO MACMOD, MACTYPE
NUMERIC SEPOTDC, SEPOTTH
PAGESIZE PAGESIZE, DISPPAGE
SCANCOL SCANCOLS, SCANCOLE
SEPDATE DATESEP
SEPTIME TIMESEP
SORTSIZE SORTSIZE, SORTMAX
SQLBIND BIND
SQLSYNTX SQLSYNTAX
The LIST(FILE) option setting default is now changed to LIST(NOFILE). In past releases the generation of end-of-job File
Statistics was the default operation. With this release, the default is changed to generate no File Statistics by default.
Unsupported Options
The following options are no longer supported in Release 11.x. Determine if any of these options are used at your site to
understand how your programs could be affected.
• DATEMLC
The DATEMLC option that was available in Release 6.X is no longer an option in Release 11. Instead, the DATEMLC
processing is now always equivalent to setting DATEMLC to Z (leading zero on single digit months). When the first part
of a date field, (month or day), is a one-digit value, that value will be prefixed with a leading zero. There is no built-in
option to replace that leading zero with a blank.
If programs compiled and linked under Release 6.4 0311 are now getting a blank instead of the leading zero when run
under CA Easytrieve Report Generator Release 11.x and you wish to simulate 6.4 0311 DATEMLC=B, you can copy
the 6.4 EZTPOPT load module to the r11 CAILIB.
• CMSVFM
Specifies the file mode of the CMS minidisk used for the VFM work file when operating under VM/CMS.
New Features for r11 SP0
The following features are new for CA Easytrieve Report Generator r11 SP0 if you are upgrading from CA Easytrieve
Report Generator for UNIX or Windows 1.4:
27
CA Easytrieve® Report Generator 11.6
• C-ISAM Processing (UNIX only)
• File Statistics
• New environments
• ODBC processing
• Program level date override
• XML report output
• Windows indexed files
• Windows-based Compiler and runtime environment
• Windows-based Interactive Development Environment (IDE)
• GUI printer set definition and option table generator
C-ISAM Processing (UNIX only)
Variable-length and relative record format C-ISAM files are supported with CA Easytrieve Release 11.x.
File Statistics
You can now optionally output file statistics containing activity I/O record counts.
NOTE
CA Easytrieve Release 11.x does not open output files that are not used in an activity. Therefore, the output
files remain undefined. This is a known difference between CA Easytrieve Release 6.4 and Release 11.x. CA
Easytrieve Release 6.4 opened all output files whether or not they are used which allowed files to be created
with DCB information.
New Environments
CA Easytrieve Report Generator Release 11.x operates in new environments, including Solaris UNIX, Linux, and
Windows.
ODBC Processing
The SQL Interface to CA Easytrieve Report Generator now supports ODBC environments.
In the Windows and UNIX environments, this allows access to any data source defined within the ODBC data source
administrator. Within CA Easytrieve Report Generator, the following statements are all that is required to define and
access an ODBC data source named PERSNL:
PARM SSID(‘PERSNLDB’)
FILE PERSNL SQL(PERSNL)
SQL INCLUDE LOCATION * FROM PERSNL
Program Level Date Override
CA Easytrieve Report Generator Release 11.x lets you override the date format at a program level with the Date
parameter.
XML Report Output
CA Easytrieve Report Generator Release 11.x produces reports in Extensible Markup Language (XML) format. A new
parameter, XML, has been added to the REPORT statement that will result in the generation of the report being formatted
as an XML file. Each field that appears on a CONTROL statement becomes a group or parent element and each field on
the LINE statement will be “wrapped” within that group.
For an XML report, note the following:
28
CA Easytrieve® Report Generator 11.6
• No printed output is generated.
• Control and summary totals are not generated.
• Spacing statements used on the REPORT statement will be ignored.
Windows Indexed Files
An internal Indexed Sequential Access Method (ISAM) is included with the Windows version. This will provide emulation
services for developing mainframe VSAM programs.
Windows-Based Compiler and Runtime Environment
In addition to the UNIX environment, the Compiler now runs in Windows as well as z/OS. This results in a single compiler
working on all supported platforms and automatic availability of new features on any other platform.
Windows-Based Interactive Development Environment (IDE)
This release includes the Workbench, a Graphical User Interface (GUI) for the development and testing of CA Easytrieve
Report Generator programs. The Workbench provides color-coded program displays based upon CA Easytrieve Report
Generator syntax.
Compiler error messages that highlight the error within the source code are also provided. Once all errors are
resolved and depending upon where the output is directed, the results of the program are displayed in a new window.
This Workbench provides a seamless testing and execution environment for most types of CA Easytrieve Report
Generator programs.
When the data for the program is not available from within the Windows environment, you can syntax-check the program
within the GUI and then upload it to the platform where the data exists. You can then compile and execute the program
using the CA Easytrieve Report Generator product for that platform. In most cases, this can occur without any changes to
the program.
Workbench features are as follows:
• You can group macros and called programs into an application that lets you easily open, view, and edit all components
of a program at the same time.
• An interface to Microsoft SourceSafe and CA Pan/LCM is provided to allow managed source control for your
programs.
• You can debug a program in the Workbench environment. Once a program is successfully compiled, it can be
executed in a step-by-step mode to allow a programmer to view and follow the program flow. At any point during
execution, any defined variable can be displayed within the Data Director and those values can be monitored during
the execution of the program. You can also set unconditional or conditional breakpoints on any executable line within
the program to compare the value of a variable.
GUI Printer Set Definition and Option Table Generator
CA Easytrieve Report Generator Release 11.x offers menu options from the Workbench to create printer set definitions
and maintain the options table. The Configuration Manager enables options and multiple printer definitions to be defined
and maintained. It enables the generation of a binary output file that is compatible with CA Easytrieve Report Generator in
the z/OS, UNIX, and Windows environments. You can subsequently move this file to the appropriate platform where it can
be used directly by the product.
Enhancements from CA Easytrieve Plus Report Generator
The product supports the following enhancements from CA Easytrieve Plus Report Generator:
29
CA Easytrieve® Report Generator 11.6
• Environment-independent FILE statements help ensure portability between environments and access methods.
• The CLOSE statement now allows controlled file opens and closes.
• A dynamic file name provides the ability to determine the file name at execution time.
• Simple read/write access to SQL files provides automated cursor management with full application capabilities.
• File-based SQL has been greatly enhanced to automate the SELECT statement. This new method automates the
work of coding the selected columns and the INTO list of host variables. SQL files previously required a SELECT
statement on the FILE statement and a complete INTO list for the columns. (The old style is supported though no
longer documented.)
• Complete control over SQL units of work is provided using the COMMIT statement and activity options.
• 128-character entity names for ANSI standard support.
• Descriptive logical file names longer than eight characters can now be used.
• Boundary checking of subscripts and indexes during execution protects environment and makes debugging easier.
• The PROGRAM super activity can execute other activities as logic dictates.
• The PROGRAM statement provides direct access to execution parameters.
• You can LINK and TRANSFER to other CA Easytrieve programs.
• SEARCH of INDEXED table file results in keyed read rather than binary search.
• You can specify column locations for title items in automatically adjusted reports.
• Warning messages are issued during compilation to provide helpful direction.
• The compilation listing has been enhanced.
• Storage of intermediate reporting data can now be automatically directed to report work files (temporary sequential
disk files) instead of to virtual (VFM) files. This option provides a large performance improvement for large reports.
• Effective in Release 11.x, you can use the COL parameter on the TITLE statement without specifying the ADJUST
parameter on the REPORT statement.
• You can use the BEFORE-LINE report procedure to modify detail line information.
• You can control and enable 24-bit processing at the installation and program level using a CALL (AMODE24)
parameter on the PARM statement. The default is 31-bit processing.
• You can specify a block size of zero as a parameter of the FILE statement or within the DCB parameter of your JCL.
This block size allows complete control of file allocations.
• CA Easytrieve uses the Large Block Interface (LBI) for TAPE files, which lets you use the maximum block size for that
tape device.
• You can execute multiple JOB activities under the same LE Run Unit. Specify ENVIRONMENT (COBOL) on the
PROGRAM statement and specify the EXECUTE statement within the PROGRAM activity to invoke the JOB activities.
Differences Between Releases
This article explains the functional differences between the current and prior releases of the product. This article is
intended for developers and other users who are converting from older batch mainframe releases of the product to the
current release of CA Easytrieve Report Generator for the UNIX, Linux for zSeries, Windows, and z/OS platforms.
This article includes the following information:
ASMTDLI Install Module
Prior Release
In Release 6.4, ASMTDLI is statically linked with EZTPA00 at the installation time. The IMS RESLIB is needed when you
run your JOB06 Installation job.
Release 11.x
30
CA Easytrieve® Report Generator 11.6
In Release 11.x, ASMTDLI is not statically linked with EZTPA00. When CA Easytrieve Report Generator application
programs specify DLI statements; link edits of these programs need the //SYSLIB DD statement which references the IMS
library that contains the ASMTDLI module.
Bounds Checking
The product now verifies that your indexes and subscripts do not refer past the end of the field. This verification increases
application stability and reliability. However, older programs that were miscoded can now display boundary problems that
silently existed in older versions.
Prior Release
A field definition could be defined that exceeded the length of the file record.
Release 11.x
The FILE record length is used to calculate the maximum length (starting position + length) of the fields defined for that
file.
Example:
FILE FILEA F(80)
FLD 1 1 A OCCURS 81
R11 gives EZTC0170E >>> $ FILE size of 80 exceeded by 1
Prior Release
An error was detected only when a subscript or INDEX causes an 0C1 or 0C4 abend. The programmer had only the
abend dump to identify the problem.
Release 11.x
If a subscript or INDEX is out of bounds, an informative error is always forced. This error message helps the programmer
identify the exact problem area.
In the following example, Release 6.4 would silently overwrite FLD3 with data from the assignment to FLD2(SUB)
because SUB starts with a value of 0. However, Release 11 would issue message EZABX009 to indicate that an index or
subscript is out of range.
DEFINE FLD1 S 16 A VALUE '1111111111111111'
DEFINE FLD2 S 16 A OCCURS 2
DEFINE FLD3 S 16 A VALUE '3333333333333333'
DEFINE SUB S 2 N
JOB INPUT NULL
DISPLAY FLD1 +2 FLD3
DO WHILE SUB < 3
FLD2(SUB) = '2222222222222222'
SUB = SUB + 1
END-DO
DISPLAY FLD1 +2 FLD3
STOP
CARD File Input
Prior Release
You could use an END statement to have CARD file input follow the source in compile-and-go mode.
Example:
31
CA Easytrieve® Report Generator 11.6
FILE CARDIN CARD
FLD1 1 3 A
JOB INPUT CARDIN
DISPLAY FLD1
END
ABC
DEF
XYZ
Release 11.x
CA Easytrieve Report Generator honors the END statement but does not support it. CARD input data that was used
within the program source must use a DD statement to point to the input data. For compile-and-go execution, remove the
CARD keyword and specify the file name in the DD statement on the FILE statement. For link-edited execution, you can
use the CARD keyword and specify SYSIN in the DD statement.
See the following example:
FILE CARDIN
FLD1 1 3 A
JOB INPUT CARDIN
DISPLAY FLD1
/*
//CARDIN DD *
ABC
DEF
XYZ
/*
Prior Release
The SYSIN exit could be invoked during execution of a program in compile-and-go mode.
Release 11.x
The SYSIN exit (SINXIT) is called only during the compilation phase and not during the execution phase. The parameter
list for the SYSIN exit is the same in r11 as it was in 6.x.
Conditional Expressions Changes
Prior Release
Comparisons involving a VARYING alphanumeric field as the subject or object used the current length of the subject field
as the length of the comparison.
NOTE
For complete details about the special VARYING alphanumeric field type, see DEFINE Statement and Define
Files and Fields.
Release 11.x
Comparisons involving a VARYING alphanumeric field as the subject or object use the longer of the subject or object for
the comparison. The shorter subject or object is padded with spaces.
Example:
DEFINE FLDV S 6 A VARYING VALUE 'ABCD'
DEFINE FLDA S 3 A VALUE 'ABC'
JOB INPUT NULL
IF FLDA = FLDV
32
CA Easytrieve® Report Generator 11.6
DISPLAY 'TRUE'
ELSE
DISPLAY 'FALSE'
END-IF
IF FLDV = FLDA. * Reverse the subject and object
DISPLAY 'TRUE'
ELSE
DISPLAY 'FALSE'
END-IF
STOP
For the previous code example, 6.4 displays the following:
TRUE
FALSE
For the previous code example, r11 displays the following:
FALSE
FALSE
CA-Corporate TIE Access
The ability to access the CA-Corporate TIE Host Disk has been removed from this release of the product and is no longer
supported on the FILE statement.
DBCS Support Options Module
The Release 6.x and Release 11.x DBCS options modules have the following differences:
NOTE
CA Easytrieve Report Generator does not support DBCS under UNIX, Linux for zSeries, and Windows.
Prior Release Release 11.x
The EZTPX04 utility created the DBCS options module. The PSIDBCLP utility creates the DBCS options module.
The command syntax is different. Carefully review the syntax
conventions. Some differences are highlighted in the following
paragraphs.
The CODE statement SHIFTCODES parameter used only SHIFTCODES are represented as hex characters (X'0E', X'0F').
characters (0E, 0F).
The DEFAULTS statement used a DATE parameter to specify The CODE SYSTEM provides a JAPANYEAR parameter that
separators in date fields. has the same meaning as the DEFAULTS DATE value from
6.x. You can now specify this parameter for each code system.
Also, because these values are actually DBCS data, they are
represented as D'DBCS hex values' (D’426142614040’). Release
6.x used separate characters (D’4261’, D’4261’, D’4040'). Always
set the DATE parameter of the DEFAULTS statement to 1988.
DEFINE Statement Changes
The Release 6.x and Release 11.x DEFINE statements have the following differences:
• If you define the same field more than once with different attributes as shown in the following example, a warning is
issued during compilation.
33
CA Easytrieve® Report Generator 11.6
DEFINE FLD1 S 3 A
JOB INPUT NULL
DEFINE FLD1 S 3 N
EZTC0393W >>> + type not same as original field
STOP
• When you redefine a field that contains an OCCURS value, the field inherits the OCCURS value. The inherited
value lets the field be subscripted. If the field length exceeds the redefined length, a warning message is issued
when the field is defined and subscripting at reference is not permitted. To implement bounds checking, the product
now provides this protection. When you intend to determine the starting location of a dynamically, use an INDEX
rather than a subscript. Subscripting carries the length of an item length with its references. Use of a smaller storage
area combined with subscripting can result in overlaid storage and protection exceptions in older versions. If a
multidimensional array is defined, all occurrences of secondary dimensions must fit into a single occurrence of the
corresponding primary dimension. A warning message results when the field is defined and subscripting of secondary
dimensions is not allowed at reference.
The following example illustrates the Release 11.x warning message given because FLDP-R redefines the shorter
FLDP field but inherits its OCCURS attribute. Release 6.4 gave no warning and either addressed bad storage or
abended.
DEFINE FLDP S 4 P OCCURS 3
DEFINE FLDP-R FLDP 5 P
EZTC0715W >>> + subscripting not allowed - length greater than overlayed field
DEFINE SUB S 1 N VALUE 1
JOB INPUT NULL
DO WHILE SUB < 4
FLDP (SUB) = SUB
DISPLAY 'FLDP=' FLDP (SUB)
SUB = SUB + 1
END-DO
SUB = 1
DO WHILE SUB < 4
DISPLAY 'FLDP-R=' FLDP-R (SUB)
SUB = SUB + 1
END-DO
STOP
6.4 gets data exception displaying FLDP-R (SUB)
r11 gives EZTC0715W >>> + subscripting not allowed - length greater than overlayed
field
• Fields referenced in activities in which no file I/O is specified now receive warning messages because open files
can now be inherited. In Release 6.4, they could not be inherited and therefore error messages were issued. This
difference, therefore, does not affect working Release 6.4 programs.
The following example shows 6.4 functionality:
1 FILE PFILE F(80)
2 FLD 1 1 A
3 JOB INPUT NULL
4 DISPLAY FLD
5 STOP
*******B062 FIELD REFERENCED IN UNAVAILABLE FILE - PFILE
*******B063 FIELD REFERENCED WAS - FLD
The following example shows Release 11.x functionality:
1 FILE PFILE F(80)
2 FLD 1 1 A
3 PROGRAM
4 GET PFILE
34
CA Easytrieve® Report Generator 11.6
5 EXECUTE JOB1
6 JOB INPUT NULL NAME JOB1
7 DISPLAY FLD
EZTC0654W >>> + file or file containing field may not be active
8 STOP
• Varying length alphanumeric fields are now modeled correctly. If you use a varying length alphanumeric field as a
model, the VARYING keyword is included in the length and type of the new field. See the following example:
DEFINE FLDV1 S 10 A VARYING VALUE 'ABC'
DEFINE FLDV2 S FLDV1 VALUE 'DEF'
JOB INPUT NULL
DISPLAY HEX FLDV1
DISPLAY HEX FLDV2
STOP
The following example shows the 6.4 results, in which FLDV2 is not VARYING:
CHAR ABC
ZONE 00CCC44444
NUMR 0312300000
1...5...10
CHAR DEF
ZONE CCC4444444
NUMR 4560000000
1...5...10
The following example, shows r11 results with FLDV2 correctly modeled after FLDV1:
CHAR ABC
ZONE 00CCC44444
NUMR 0312300000
1...5...10
CHAR DEF
ZONE 00CCC44444
NUMR 0345600000
1...5...10
• The behavior of W (work/spooled) fields and S (static) fields is now consistent.
DISPLAY Statement Changes
Prior Release
With 6.x, the DISPLAY NEWPAGE function does not consistently produce report titles and headings.
Release 11.x
Effective with Release 11.x, the DISPLAY NEWPAGE function has been replaced by the DISPLAY TITLE and DISPLAY
NOTITLE functions. For source compatibility, DISPLAY NEWPAGE is accepted and functions the same as DISPLAY
TITLE.
END Statement
See CARD File Input.
File Processing Changes
Prior Release
35
CA Easytrieve® Report Generator 11.6
If you did not specify WORKAREA on the FILE statement for the input files, the record was processed in Locate Mode.
When the record was read into memory, it remained in the system-allocated record buffer.
Release 11.x
If you do not specify WORKAREA on the FILE statement for the input files, the record is processed in Move Mode. When
the record is read, it is moved from the system-allocated record buffer to the buffer created in program storage.
What this change means to your program
When you are reading an input file where you do not know the record lengths (as with variable-length files), use the
RECORD-LENGTH field. After each record is read, the RECORD-LENGTH field contains the length of that record.
Structure your program logic to reference only fields that are not defined to extend beyond the length specified in the
RECORD-LENGTH field.
Because 6.4 used Locate Mode processing, your invalid references can refer to data beyond the actual record and into
the following record in the buffer. When you use Move Mode processing, the reference is always within the program
storage. However, if you do not use RECORD-LENGTH you can unintentionally refer to the data for a previous record.
The following example processes two records, with the second record shorter than the first. The example writes the
records to a file, then reads them and displays a field that is defined beyond the length of the record:
FILE VFILE VB(20 200)
VFLD1 * 10 A
VFLD2 * 10 A
JOB INPUT NULL
VFLD1 = '1111111111'
VFLD2 = 'ABC'
RECORD-LENGTH = 13
PUT VFILE
VFLD1 = '2222222222'
VFLD2 = 'X'
RECORD-LENGTH = 11
PUT VFILE
STOP
JOB INPUT VFILE
DISPLAY HEX VFLD2
The following example shows the 6.4 results:
CHAR ABC 222
ZONE CCC0000FFF
NUMR 1230F00222
1...5...10
CHAR X
ZONE E000000000
NUMR 7000000000
1...5...10
The following example shows the Release 11.x results:
CHAR ABC
ZONE CCC4444444
NUMR 1230000000
1...5...10
CHAR XBC
36
CA Easytrieve® Report Generator 11.6
ZONE ECC4444444
NUMR 7230000000
1...5...10
The Release 6.4 results display data outside of the first record and also a portion of the second record in the system
buffer. The Release 11.x results display the program storage buffer, but the second record still contains the ‘BC’
characters from the first record. Only refer to data that is constrained by RECORD-LENGTH. The buffer is not initialized
between input operations.
The following example reads the file and correctly displays the variable portion of the record (VFLD2):
JOB INPUT VFILE
DEFINE SFLD S 10 A
DEFINE LEN S 2 N
LEN = RECORD-LENGTH - 10. * Compute length to safely move data
MOVE VFLD2 LEN TO SFLD FILL ' '
DISPLAY HEX SFLD
If you write records from a variable-length input file to a variable-length output file, you must set the RECORD-LENGTH
field for each output record. The RECORD-LENGTH field of the output file must be set to the RECORD-LENGTH value of
the input file before the PUT to the output file. See the following example:
FILE VFILE VB(20 200)
VFLD1 * 10 A
VFLD2 * 10 A
FILE VFILEOUT VB(20 200)
JOB INPUT VFILE
VFILEOUT:RECORD-LENGTH = VFILE:RECORD-LENGTH
PUT VFILEOUT FROM VFILE
FILE Statement Changes
FILE-STATUS, RECORD-LENGTH, and RECORD-COUNT are system-defined 4-byte binary fields for files with
SEQUENTIAL, INDEXED, REALTIVE, or SQL specified on their FILE statement. Other file types use 2-byte binary fields.
The FILE-STATUS field for files with SEQUENTIAL, INDEXED, or RELATIVE specified contains codes that are generic
across access methods. Other file types use a FILE-STATUS obtained from the underlying access method.
Prior Release Release 11.x
SQL files required a SELECT statement on the FILE statement File-based SQL automates the SELECT statement. The old style
and required a complete INTO list for the columns. is supported though no longer documented.
SQL files without the DEFER keyword were SQL files behave like other file types. The cursor is opened before
opened before executing the user-defined START procedure, if a the user-defined START procedure, unless DEFER is coded. With
procedure was coded. This behavior contradicted the documented DEFER, the cursor is opened after the user-specified START
behavior and did not conform to the behavior for other file types. procedure. This way, host variables can be properly set before the
cursor is opened.
The access method for the VS parameter was determined at The VS parameter is replaced with SEQUENTIAL, INDEXED, and
execution time. RELATIVE to provide better portability. The underlying access
method is still determined at execution time. However, VS is
still valid syntax, and INDEXED (KSDS) is assumed when VS is
coded. See the example that follows.
Example: VS parameter
The following example shows 6.4 syntax:
37
CA Easytrieve® Report Generator 11.6
FILE KSDS VS
FILE ESDS VS ES
FILE RRDS VS
The following example shows Release 11.x syntax:
FILE KSDS INDEXED
FILE ESDS SEQUENTIAL
FILE RRDS RELATIVE
Embedded Hexadecimal Data in Source Code
Do not embed hexadecimal data in any source code (including instream table data). The CA Easytrieve Report
Generator language has never supported the use of hexadecimal codes embedded in the source code statements.
Though unintended, Release 6.4 was more tolerant than Release 11.x; using hexadecimal in source code was not
intended or supported. Embedding hexadecimal data in source code can cause errors for the compiler (both on input and
output in the compiler listing).
Ensure that your program source contains only character data. The CA Easytrieve Report Generator language supplies a
hexadecimal literal format (X’hh’) for times when you need to specify hexadecimal. Table data that is not character-based
should always be external to the source code.
Listing Format
Although the output of a printed report should look the same between Releases 6.4 and 11.x, we reserve the right
to change the format of the compile and runtime listings. While we do not change the listing format unless there is a
compelling case for doing so, it may happen between releases or even service packs. For example, the compile options,
compiler messages, runtime messages, and file statistics have all had formatting changes from Release 6.4 to Release
11.x for improved readability. The order of files shown in the statistics may differ from older versions. The format of the
PARM DEBUG options’ (ex. CLIST, PMAP, DMAP, etc.) output may also change based on need.
Macro Libraries Changes
Starting with Release 11.x, only z/OS partition data sets (PDS), CA Panvalet libraries, and CA Endevor libraries can be
used in z/OS to store macros (the installation default is PDS).
New Options
The following new Options Table settings are available in Release 11.x.
WORKFILE {Y|N}
The WORKFILE option is used to activate the Automatic Report Workfiles feature.
WORKFSPA nnn
The WORKFSPA option indicates the number of cylinders that should be allocated for each of the dynamically-allocated
Report Workfiles.
Printer Profiles are also new in Release 11.x. The profiles specify the physical data set attributes for logical printers
including SYSPRINT. If you increase the LINESIZ value, you should also review the settings of the SYSPRINT profile.
NOTE
For more information about these options, see Updating the Table.
38
CA Easytrieve® Report Generator 11.6
Options Table
Prior Release
With Release 6.x, the Options Table existed as a load module.
Release 11.x
Starting with Release 11.x on the z/OS platform, the Options Table exists as a file that may optionally be identified by the
EZOPTBL DD statement in the Compilation JCL and in the Execution JCL. If the DD is omitted from the Compilation JCL
and EZTINI was not created using JOB6EOP, default Option Table values are generated by the Compiler. If EZTINI does
not exist and the DD is omitted from the Execution JCL, an error occurs and the program cannot run.
A utility is supplied to convert your 6.x options table to the new format. The following 6.x options are not supported in the
new options table:
IDMSNAM MACDEV
COMPSTR MACRO
DATEADJ MACSYS$
DATEMLC PLACE
DEVICE PRESIZE
DISK REWIND
DLIV SORTOPT
DLISQL SORTWK#
EXITSTR STORMAX
IDDEXIT SYSTEM
NOTE
• Several Release 6.x options are still supported in Release 11.x, but with a new name. The conversion utility
will handle these options properly. For a list of former and current option names, see Modified Options in New
Features Since Release 6.4.
• The following 6.x options are supported in the new options table, but are ignored and reserved for future use:
– TBLMAX
– UPDTIDD
• While comments describing each option were given in the Release 6.x OPTTBL option table macro, in
Release 11.x, comments can only be written as a separate line, starting with an asterisk and describing the
particular option and meaning of possible values.
• Options can be started at any position, if the options name is the first non-blank entry on that line. They must
not end beyond column 80.
• Options can also be specified in lower case. If an option value is one of a set of valid values, it is converted to
upper case. Other option values remain in lower case. Those specifying a load module name, a device or a
DDNAME must be specified in upper case or they will cause a problem during compile or execution time.
Reports
The following enhancements have been made to reports in Release 11.x.
Prior Release Release 11.x
Report annotation did not always stay with the physical page. The DISPLAY statement now keeps printed output within the
physical page size that you specify.
Title fields were refreshed only when printing titles as the result of Items on the title line are now always refreshed with the current
a detail line. value of fields when produced.
Reports that included a control break had one extra blank line at The extra blank line at the end of the report is now omitted. This is
the end of the report. only at the end of the report, not at the end of every page.
39
CA Easytrieve® Report Generator 11.6
A single, nonsequenced (nonspooled) report was treated All reports work consistently in their handling of W fields. This
differently than other reports. As a result, W (working storage) change can cause older, miscoded programs to behave differently
fields were sometimes used instead of S (static) fields. When that due to misuse of W fields.
report became spooled (by adding sequencing or inserting a prior
report) the W field logic sometimes caused report misbehavior.
Special named break procedures referred to the first record of the Special named break procedures refer to the last detail record
new control group. As a result, detail references did not always of the control group so that detail references match control
match associated control and sum fields. and sum information. This change has no adverse effect when
standard programming practices were observed while saving
detail information manually. See the following example.
Example: Special named break procedure
FILE PERSNL
REGION 1 1 A
NAME 17 8 A
GROSS 94 4 P 2
JOB
REPORT
SEQUENCE REGION
CONTROL REGION
LINE REGION NAME GROSS
AFTER-BREAK. PROC
DISPLAY 'FINAL NAME WAS ' NAME
END-PROC
The following example shows Release 6.4 results:
REGION NAME GROSS
1 ARNOLD 445.50
BRANDOW 804.64
…
TALL 492.26
WIMN 373.60
1 4,601.16
FINAL NAME WAS DENNING
2 DENNING 135.85
FORREST 13.80
…
The following example shows Release 11.x results:
REGION NAME GROSS
1 ARNOLD 445.50
BRANDOW 804.64
…
TALL 492.26
WIMN 373.60
1 4,601.16
FINAL NAME WAS WIMN
40
CA Easytrieve® Report Generator 11.6
2 DENNING 135.85
FORREST 13.80
Reserved Words
The list of new reserved words follows. Programs that have field names with these values will cause errors.
• BREAK-LEVEL
• DRAW
• ELEMENT-RECORD
• END-REPEAT
• EXECUTE
• GRAPH
• HIGH-VALUES
• INITIATION
• LOGICAL-RECORD
• LOW-VALUES
• NOTITLE
• SET
• SUMMARY-INDEX
• SYSUSERID
SEQUENCE Statement Changes
Prior Release
Duplicate field names were allowed.
Release 11.x
Duplicate field names result in a compiler error. See the following example:
8 REPORT
9 SEQUENCE REGION NAME REGION
EZTC0092E >>> $ duplicate SEQUENCE field
10 LINE REGION NAME GROSS
SYSDATE and SYSTIME
Effective with Release 11.x, the SYSDATE and SYSTIME fields no longer use a space in place of a leading zero.
Programmers typically want to use SYSDATE in SQL WHERE clauses that have numeric comparisons. Historically, they
had to transform SYSDATE to be useful. Release 11.x corrects this problem by adding the leading zero when the month is
less than 10.
The following Release 6.4 SYSDATE code continues to execute correctly without requiring changes:
DEFINE MYDATE S 8 A
DEFINE MYDATE-MONTHCHAR MYDATE 1 A
JOB INPUT NULL
MYDATE = SYSDATE
DISPLAY MYDATE
IF MYDATE-MONTHCHAR = ' '
MYDATE-MONTHCHAR = '0'
END-IF
DISPLAY MYDATE
41
CA Easytrieve® Report Generator 11.6
STOP
The previous code provides the following results in Release 11.x:
5/10/11
05/10/11
SYSIN Exit (SINXIT)
Effective with Release 11, the SYSIN exit is called only during the compilation phase and not during the execution phase.
The parameter list for the SYSIN exit is the same in release 11.x as it was in Release 6.x. To determine whether this
change affects your site, dump the options table settings to see whether the option is used.
SYSPRINT Exit (SPRTXIT)
Effective with Release 11.x, the SYSPRINT exit is called only during the compilation phase and not during the execution
phase. The parameter list for the SYSPRINT exit is the same in release 11.x as it was in Release 6.x. To determine
whether this change affects your site, dump the options table settings to see whether the option is used.
VSAM File Processing
Prior Release
The UPDATE parameter was not always enforced when writing to a VSAM file.
Release 11.x
The UPDATE parameter is now required when writing to a VSAM file.
The following example shows the error that is issued when the UPDATE parameter is omitted:
2 FILE VSINP VS
3 INREC 1 150 A
4 *
5 JOB INPUT VSINP
6 PUT VSINP
EZTC0252E >>> $ must be CREATE or UPDATE file
Prior Release
A READ or POINT statement could override the FILE statement VSAM type (ES).
Release 11.x
If the FILE statement specifies sequential processing (by specifying the VS(ES) or SEQUENTIAL parameter), then direct-
access statements (READ, POINT, WRITE) are flagged as syntax errors. Files targeted by direct-access statements must
specify INDEXED or RELATIVE on the FILE statement. However, a file specifying INDEXED can be accessed using the
sequential-access statements (GET, PUT).
In the following example of 6.4 code, the READ overrides the FILE statement ES parameter:
2 FILE VSINP VS(ES)
3 INREC 1 150 A
4 *
5 WEMP# W 5 N VALUE 10000
6 *
7 JOB INPUT NULL
8 READ VSINP KEY WEMP# STATUS
9 STOP
42
CA Easytrieve® Report Generator 11.6
In the following release 11.x code example, the READ statement shows a syntax error because VS(ES) has not been
changed to INDEXED:
2 FILE VSINP VS(ES)
3 INREC 1 150 A
4 *
5 WEMP# W 5 N VALUE 10000
6 *
7 JOB INPUT NULL
8 READ VSINP KEY WEMP# STATUS
EZTC0443E >>> $ file type not compatible with READ
9 STOP
Prior Release
The attributes specified on the FILE statement were ignored. The access method for the VS parameter was determined at
execution time.
Release 11.x
The attributes specified on the FILE statement are not ignored. The attributes must match the organization of the actual
VSAM file.
For example, if the file that is being processed is a KSDS (keyed) VSAM file, but the FILE statement explicitly specifies
the ESDS type (sequential), processing is as follows: Release 6.4 compiles the program and executes without problems.
Release 11.x compiles without problems but, at execution time, recognizes that the file organization does not match what
was explicitly specified on the FILE statement.
The following example compiles and executes cleanly in Release 6.4:
2 FILE VSINP VS(ES)
3 INREC 1 150 A
4 *
5 JOB INPUT NULL
6 GET VSINP
7 STOP
The following errors occur when the code is executed in Release 11.x:
EZABX000 An error has occurred in program HELLO.
. . .
################ Diagnostic Information ################
EZABX003 The error occurred at 15:51 on 05/11/11.
EZIOE002 Error opening file VSINP.
File type incompatable with the dataset organization.
EZABX008 The error occurred at program statement number 6.
EZABX020 The program referred to the following files:
To access alternate index, set the DSN to the PATH file:
//VSAMFILE DD DSN=name of vsam file.PATH,DISP=SHR
W and S Field Differences
The following W and S field definition differences exist between Release 6.4 and Release 11.x:
Prior Release
43
CA Easytrieve® Report Generator 11.6
When the first report was unsequenced, W (work/spooled) fields were treated like S (static) fields. If the report later
became spooled (by sequencing or insertion of another report), the W fields were spooled and their behavior was
changed. As a result, the behavior of W and S fields was inconsistent. Users were able to invalidate the logic they had
developed for single unsequenced reports.
Release 11.x
All reports are treated as spooled, whether they are single, unsequenced reports. The distinction between W and S fields
is always maintained and their behavior is always consistent when new reports or sequencing is added.
We recommend always using S fields unless you know exactly what W means to your application and the special
processing associated with spooled work fields. W fields are added to the spool record with all FILE fields when PRINT
executes, freezing an instance of that variable. Each spool record has its own instance of that field. S fields behave the
way working storage works in other languages. For more information, see Define Files and Fields .
Remember that all file fields and W fields that are referenced in a REPORT are added to the spool record when the
PRINT is executed. S fields are not. A field is referenced by being coded anywhere in the report declaration, for example,
on a TITLE or LINE or in a report procedure. Work field types are often misused in procedures.
In the following example, a program tries to display a sequence number in an AFTER-LINE procedure:
FILE PERSNL
REGION 1 1 A
NAME 17 8 A
GROSS 94 4 P 2
WFLD W 2 N
JOB
PRINT
REPORT NOADJUST
LINE REGION NAME GROSS
AFTER-LINE. PROC
WFLD = WFLD + 1
DISPLAY 'SEQ=' WFLD
END-PROC
The following example shows the Release 6.4 results:
REGION NAME GROSS
1 NAGLE 554.40
SEQ=01
2 POST 292.00
SEQ=02
2 PETRIK 220.80
SEQ=03
The following example shows the Release 11.x results:
44
CA Easytrieve® Report Generator 11.6
REGION NAME GROSS
1 NAGLE 554.40
SEQ=01
2 POST 292.00
SEQ=01
2 PETRIK 220.80
SEQ=01
In the Release 6.4 results, the sequence numbers are 01, 02, and 03 because the W field was treated like an S field. In
the Release 11.x results, the sequence numbers are all 01 because r11 treats the W field properly. Because W fields are
copied to the spool record when PRINT executes, the WFLD is not added until AFTER-LINE executes during despooling
and printing. As a result, the WFLD copy for every spool record contains the zero that WFLD contained at the time of the
PRINT statement.
Release 6.4 incorrectly treated W fields like S fields when the first report was not sequenced. If you sequence this
single report or add a report before it, 6.4 properly spools the W field and shows the sequence numbers as "01". This
inconsistent treatment of the W fields causes inconsistent results.
NOTE
Both Release 6.4 and Release 11.x treat WFLDs coded as S fields properly, regardless of whether the report is
sequenced or is the first report. Future maintenance to the program will not jeopardize the working code.
Release Comparison
This article lists the key features added after Release 6.4. Click the link for more information about a feature.
Key Features Release 11.6 Release 6.4
(With all maintenance applied)
8-byte binary field support yes no
Big integer value support yes no
CA Chorus Software Manager support yes no
Linux PC support yes no
Character comparison using custom yes no
collating sequence table
IDD NAME RETRIEVAL parameter yes no
command is ignored
WORKFILE option enables automatic yes no
storage of intermediate reporting data
WARNCC option specifies the condition yes no
code that the compiler returns for warning
messages
Multiple SSIDs with CA Pan/SQL yes no
45
CA Easytrieve® Report Generator 11.6
BLOCK0 option allows system-determined yes no
data set block size
NEWFUNC option specifies whether to use yes no
the standard Release 11.x compiler or the
compatibility mode compiler
AMODE31 option Specifies the location of yes no
where memory is to be allocated during the
execution of the program
MTVSERR option specifies how an empty yes no
input VSAM file should be handled
SPRTXIT option specifies the name of a yes no
user-supplied SYSPRINT exit routine
Variable-length and relative record format yes no
C-ISAM file support (UNIX only)
Output of file statistics containing activity I/ yes no
O record counts
Solaris UNIX, Linux, and Windows support yes no
ODBC environment support for SQL yes no
interface
Date parameter allows date format override yes no
at program level
Report output in XML format yes no
Internal indexed ISAM included with yes no
Windows version
Windows-Based compiler and runtime yes no
environment
Windows GUI for program development yes no
Printer Set Definition and Option Table yes no
Generator
Migration Guidelines
It is important to have a solid migration strategy to ensure a smooth and successful migration to CA Easytrieve® Report
Generator release 11.x from a prior release. The release 11.x release is unlike prior releases because its architecture
resulted in a new version of both the language compiler and the runtime system. Read this chapter before starting your
migration.
Release 11.x Benefits
The release 11.x is based on a modern architecture, which helped us add many new features on multiple platforms. It will
also allow us to respond promptly to future feature requests and push them out to all the platforms using the current code
base.
The release 11.x compiler enforces strict adherence to the documented rules of the CA Easytrieve® Report Generator
language, which helps produce better programs and data integrity.
Migration Strategy
The CA Easytrieve® Report Generator product team provides a formalized migration strategy to help you upgrade from
release 6.4 to release 11.x. Many customers have already migrated to release 11.6 to take advantage of its new features
and functionality. Our migration strategy is based on our experience with those migrations and the resulting customer
46
CA Easytrieve® Report Generator 11.6
comments and feedback. We recommend migrating to release 11.6 compatibility mode first and then moving into new
function mode when you have time to test your migrated programs.
WARNING
Because release 11.x is a major release, do not migrate programs from release 6.4 without testing.
Compatibility Mode
When you are ready to migrate to release 11.6, we recommend that you start by running any recompiled programs in
compatibility mode. This recommendation includes programs that use 'compile and go' mode for on-demand reporting.
Compatibility mode is available in Service Pack 3 and higher and is enabled by setting the NEWFUNC option to N. In
compatibility mode, programs are compiled and executed as under the release 6.4 compiler and you can delay testing
and using new release 11.x functionality. The only additional migration task you must perform is to copy your release 6.4
options table load module EZTPOPT to release 11.x. This is done by copying the EZTPOPT load module from the release
6.4 CAILIB to CBAALOAD for r11.6 and higher (or CAILIB for r11.0/r11.5).
After you successfully run your programs in compatibility mode, you can enable new function mode by doing the following:
1. Create another options table that is set to enable new functionality (with NEWFUNC Y specified).
2. Use the new EZOPTBL DD in your JCL to point to the new options table. If you link your programs, the load modules
created and linked under the earlier release continue to run under release 11.x with no changes in compatibility mode.
WARNING
the same values for the option table parameters which you used with release 6.4.
If you link your programs, the load modules that are created and linked under the earlier release continue to run under
release 11.6 with no changes in compatibility mode.
NOTE
Compatibility mode may not be supported in future releases. Plan to migrate your programs to new function
mode.
Mode Detection
During migration, your environment can have some programs running in new function mode and some in compatibility
mode. You can determine how many programs are running in compatibility mode by using a monitoring tool to see which
runtime module your programs load. A program running in compatibility mode loads the module EZTPD01. A program
running in new function mode loads ETRSM.
Additionally, the CA Easytrieve Report Generator report header indicates the release and mode. Examples are as follows:
• CA Easytrieve 11.6 SP0 indicates new function mode (NEWFUNC is set to Y).
• CA Easytrieve Plus 11.6-C SP0 indicates compatibility mode (NEWFUNC is set to N).
CA SMP/E Internet Service Retrieval
As part of our ongoing Mainframe strategy, CA Technologies now offers a new maintenance delivery service: CA SMP/
E Internet Service Retrieval. This new delivery method uses the IBM SMP/E RECEIVE ORDER command to acquire CA
Mainframe product maintenance over the internet by securely submitting an order for PTFs and HOLDDATA to a remote
CA Technologies server.
This service can reduce hours of maintenance time to just minutes, making your system programmers more productive
and allowing them to focus on higher value tasks. “This capability has drastically reduced the time and effort needed to
find and download updates. Best of all, it is easy to use!” said Rob Capel, Senior Operating System Programmer, Sentara
Healthcare.
CA SMP/E Internet Service Retrieval:
47
CA Easytrieve® Report Generator 11.6
• Eliminates time-consuming fix searches and the need to select maintenance manually through CA Support Portal
• Automates delivery of CA maintenance directly to your mainframe
• Fulfills orders based on the status of your SMP/E environments
• Enables scheduling of maintenance downloads
• Facilitates an easier installation of CA Recommended and Preventive service
With the CA SMP/E Internet Service Retrieval, you can acquire maintenance on demand or can schedule an SMP/E job
to run regularly. The CA Order server supports the IBM-documented order types, which include: ALL, APARS, CRITICAL,
HOLDDATA, PTFS, and RECOMMENDED.
If you are an existing CA Chorus™ Software Manager customer, you can also use this new service to download
maintenance and dramatically reduce the time needed to download PTFs.
To get started, review the CA SMP/E Internet Service Retrieval Documentation.
Portfolio Simplification
This article includes the portfolio simplification updates for CA Easytrieve® Report Generator.
CA Easytrieve® Online Query Report Generator for TSO
CA Easytrieve Online Query Report Generator for TSO now includes the following features and capabilities.
Runtime Report Generator for TSO Provides the ability to run CA Easytrieve applications developed
on another system without requiring the full development
environment.
Report Generator for TSO/XA DB2 Performs reporting online and enables creation of complete online
systems that can browse or update files and tables using TSO.
CA Easytrieve® Online Query Report Generator for CICS/XA
CA Easytrieve Online Query Report Generator for CICS/XA now includes the following features and capabilities.
Runtime Report Generator for CICS Performs reporting online and enables creation of complete
online systems that can browse or update files and tables in IBM®
CICS®.
Report Generator for CICS/SP DB2 Performs reporting online and enables creation of complete online
systems that can browse or update files and tables in IBM DB2®.
Report Generator for CICS/XA DB2 Performs reporting online and enables creation of complete online
systems that can browse or update files and tables in DB2.
48
CA Easytrieve® Report Generator 11.6
CA Easytrieve® Online Report Generator for z/OS
CA Easytrieve Online Report Generator for z/OS now includes the following features and capabilities.
EZ/Key™ CICS for z/OS Provides a comfortable, highly productive interactive environment
within IBM® CICS® for creating, maintaining and running CA
Easytrieve programs. Regardless of their level of data processing
expertise, users can create programs ranging from simple reports
to complex updates of files and databases.
EZ/Key CMS for z/OS Provides a comfortable, highly productive interactive environment
within CMS for creating, maintaining and running CA Easytrieve
programs. Regardless of their level of data processing expertise,
users can create programs ranging from simple reports to complex
updates of files and databases.
EZ/Key TSO Provides a comfortable, highly productive interactive environment
within TSO for creating, maintaining and running CA Easytrieve
programs. Regardless of their level of data processing expertise,
users can create programs ranging from simple reports to complex
updates of files and databases.
Easytrieve Report Generator Runtime Provides the ability to run CA Easytrieve applications developed
on another system, without requiring the full development
environment.
CA Easytrieve® Report Generator CA Datacom® Option
CA Easytrieve Report Generator CA Datacom Option now includes the following features and capabilities.
Report Generator CA Datacom Option for SQL and Non-SQL Enables CA Easytrieve to access data stored in CA Datacom
databases using CA Datacom access commands or by coding
SQL statements to access the data.
Report Generator CA Datacom SQL Enables CA Easytrieve to access data stored in CA Datacom
databases by coding SQL statements to access the data.
CA Easytrieve® Report Generator for z/OS
CA Easytrieve Report Generator for z/OS now includes the following features and capabilities.
EZ/Key™ CICS for z/OS Provides a comfortable, highly productive interactive environment
within CICS for creating, maintaining and running CA Easytrieve
programs. Regardless of their level of data processing expertise,
users can create programs ranging from simple reports to complex
updates of files and databases.
EZ/Key CMS for z/OS Provides a comfortable, highly productive interactive environment
within CMS for creating, maintaining and running CA Easytrieve
programs. Regardless of their level of data processing expertise,
users can create programs ranging from simple reports to complex
updates of files and databases.
EZ/Key TSO Provides a comfortable, highly productive interactive environment
within TSO for creating, maintaining and running CA Easytrieve
programs. Regardless of their level of data processing expertise,
users can create programs ranging from simple reports to complex
updates of files and databases.
49
CA Easytrieve® Report Generator 11.6
Easytrieve Report Generator Runtime Provides the ability to run CA Easytrieve applications developed
on another system, without requiring the full development
environment.
CA Easytrieve® Report Generator With CA IDMS™
CA Easytrieve Report Generator with CA IDMS™ now includes the following features and capabilities.
Report Generator CA IDMS Option for SQL Enables CA Easytrieve to access data stored in CA IDMS
databases by coding SQL statements to access the data.
Report Generator CA IDMS Option for SQL and NON SQL Enables CA Easytrieve to access data stored in CA IDMS
databases using CA IDMS access commands or by coding SQL
statements to access the data.
Next Steps
To use these options, go to your usual download facility (for example, Download Management on Broadcom Support and
download the additional component features from the drop-down list. If one of the downloads requires an LMP key, follow
your usual process to acquire the key.
Simplified Design System
CA Easytrieve Simplified Design System (CA Easytrieve SDS) is a Windows application that simplifies CA Easytrieve
program development. Its intuitive GUI includes a text editor, report painter, wizards, and business objects. You can
download CA Easytrieve Simplified Design System from Broadcom Support.
CA Easytrieve SDS generates complete programs and reduces or eliminates the need to code CA Easytrieve language
statements. The just-in-time compiler in the text editor validates programs instantly, which ensures clean compiles on
your target operating environment. The compiler saves programming time and simplifies the generation of complex
applications, which increases productivity and lowers development costs. The compiler requires fewer mainframe
recourses and lets you generate and run CA Easytrieve programs without knowing the language.
CA Easytrieve SDS lets you remotely submit programs and reports to run on any supported operating environment. CA
Easytrieve SDS also provides you direct access to z/OS data sets and files, and lets you edit your mainframe programs.
NOTE
For more information, see the following articles:
• Install CA Easytrieve Simplified Design System
• Using CA Easytrieve SDS
Documentation Changes
Release Information
The following update has been made since the last release of this documentation:
• Linux PC Installation Support—Added this section.
• CA Easytrieve Simplified Design System—Moved the text from Configuration Best Practices to this article.
Installing
The following update has been made since the last release of this documentation:
50
CA Easytrieve® Report Generator 11.6
• Install CA Easytrieve for Linux PC—Revised the Install the License Key section, added the Install CA Licensing Files
section.
• Install CA Easytrieve SDS—Added this article.
• Install the License Key—Added this article.
• Maintain Your Product—Added this article.
Configuring
The following update has been made since the last release of this documentation:
• DDIVRND - Round or Truncate Division Result—Added to Compiler Options.
• Updating the Table—Moved the various option category sections to individual pages.
Using
The following updates have been made to the second edition of this documentation:
• Additional Compiler Options—Added WARNCC0 option description and removed RUNSYM option description.
• Alphabetical Listing of Options—Deleted RUNSYM option description and added WARNCC0 option description.
• Link-Editing Previously-Compiled Programs in UNIX, Linux for zSeries, or Linux PC> - Explained how and when to
force the assembler to create a 32-bit .o file.
• Link-Editing with Other Systems — Noted link-editing restrictions for the Linux PC environment.
The following updates have been made since the last release of this documentation:
• Program Compilation and Link-Editing Using JCL—Updated CAILIB to CBAALOAD.
• Using CA Easytrieve Simplified Design System—This article has been added
Programming
• Standard Reports
– Report Headings—Updated the statement syntax.
– Line Item Positioning in Reports—Updated the report example.
• Report Procedures
– Static Working Storage—Updated the statement syntax.
Language Reference
The following update has been made since the last release of this documentation:
• ASSIGNMENT Statement—This article has been added.
• PROGRAM Statement—Added note for the USING parameter.
51
CA Easytrieve® Report Generator 11.6
Installing
Installation Prerequisites
This section describes the software and knowledge prerequisites that you need to install the product.
Software
You must install CA Common Services (CCS) Release 14.1 or higher.
NOTE
For more information about CCS, see the CA Common Services for z/OS documentation.
Knowledge
Depending on the platform, the installer should have the following knowledge or privileges:
Windows
• Familiarity with standard Windows installation using InstallShield
UNIX/Linux zSeries
• System Administrator privileges
• Familiarity with tar and other UNIX commands
z/OS
Knowledge of:
• JCL
• TSO/ISPF
• The z/OS environment and installing software in this environment
• Your organization's IT environment, enterprise structure, and region structure
Installation Best Practices
This section provides best practices for installing CA Easytrieve® Report Generator.
CA CSM
CA Chorus™ Software Manager (CA CSM) provides a web interface that works with ESD and standardized installation to
provide a common way to manage CA Technologies mainframe products. You can use CA CSM to acquire, install, and
maintain CA Easytrieve.
After you use CA CSM to download your product or maintenance, you use the same interface to install the downloaded
software packages using SMP/E.
NOTE
• If maintenance is available for for VSAM data sets, you must use the Install Utility to update those data sets
for each region that you have set up.
• For more information about CA CSM, see Install Your Product Using CA CSM.
52
CA Easytrieve® Report Generator 11.6
Release Notes
The Release Notes section in this documentation describes the syntax enhancements that are made to several
statements. These changes affect the way your program compiles and executes. Not reading this section can delay your
upgrade.
Configuration
After you install CA Easytrieve, see the Configuring section for setup information.
Install CA Easytrieve for Windows
This article describes the pre-installation requirements, download instructions, installation, and post-installation tasks
for CA Easytrieve Report Generator for Windows.
Pre-Installation Requirements
Before you install the product in the Windows environment, verify that your computer meets the following requirements:
• Windows XP or later
• A minimum of 80 MB of free disk space.
Download the Product
You can download CA Easytrieve Report Generator for Windows from CA Support Online.
NOTE
A product installation DVD is available for sites that do not have Internet access. Contact Broadcom Support for
more information.
Follow these steps:
1. Log into Broadcom Support.
2. Select DOWNLOAD MANAGEMENT.
3. Click Change Download Preference at the top right of the window and select your preference.
4. Select Product Downloads.
5. Type CA Easytrieve Report Generator for Windows in the Filter Search Results field.
CA Easytrieve Report Generator for Windows WINDOWS SVR PLATFORMS appears in the results.
6. Click Download Now, select a folder for product installation, and click OK.
The installation files are downloaded as an ISO file.
7. Extract the contents of the ISO file.
Install the Product
Use this procedure to install CA Easytrieve Report Generator for Windows.
Follow these steps:
1. Run setup.exe in the extracted files or product DVD.
NOTE
With the product DVD, Windows may start this program automatically, depending on whether the Autorun
option is enabled in Windows.
The InstallShield Wizard Welcome page appears when you install the product for the first time.
2. Follow the installation steps in the installation wizard to complete the installation.
53
CA Easytrieve® Report Generator 11.6
NOTE
CA Easytrieve Report Generator for Windows has a per user license. Therefore, the user who does the
installation is the only user of the product. Administrative privileges are only required to install the licensing
portion. Once licensing is installed, any user can install the product.
Post Installation Tasks
Perform the tasks in this section after you install the product.
Apply Maintenance
We recommend that you download and install the published solutions for CA Easytrieve Report Generator for Windows
from CA Support Online. For more information, see Maintain your Product.
Install the License
You must install your ALP license key for the product. You can obtain your ALP license key from CA Support. For more
information, see Install the License Key.
Start the Product
To start CA Easytrieve Report Generator for Windows, click Start, Programs, CA, Easytrieve, Easytrieve Workbench.
The CA Easytrieve Workbench main window appears.
NOTE
CA Easytrieve Report Generator for Windows is also referred to as the Workbench. For information about using
the Workbench, see the Workbench section of this documentation.
Configure the Product
You must configure the Option Table and the Printer Set Definition using the Configuration Manager before you write and
compile programs.
For more information, see the Configuration Manager section.
Install CA Easytrieve for UNIX and Linux for zSeries
This section describes the steps that are required for installing CA Easytrieve® Report Generator for UNIX and Linux for
zSeries.
Pre-Installation Considerations for UNIX and Linux for zSeries
Before you start the installation, note the following:
• Before installing any product in a UNIX or Linux for zSeries environment, you must have system administrator
privileges.
• All products are installed using the tar command.
• Determine whether your system is 32-bit or 64-bit.
• Check the available disk space before beginning. 32 MB of disk space is required for this product.
See Using for additional information about the following tasks:
54
CA Easytrieve® Report Generator 11.6
• Customize the options table.
• Create and maintain an alternate collating sequence table.
• Define environment variables.
• Compile and execute your CA Easytrieve program.
Install in the UNIX or Linux for zSeries Environment
You must follow this procedure for installing CA Easytrieve in the UNIX or Linux for zSeries environment.
NOTE
(For AIX environments only) Earlier installed versions of CA Easytrieve 11.0 for AIX might have shared libraries
loaded into memory. Use the genkld command to inspect a list of modules currently loaded in storage. Run the
AIX command: slibclean (this might require sys admin authority). The slibclean command is an AIX command
that unloads shared libraries with a use count of 0. This command is also needed when applying new fixes to be
able to reload a corrected module. Before running the slibclean command, ensure that there are no current CA
Easytrieve users that are active.
Follow these steps:
1. Log in as a user who can create and has access to the directories where you install the software. Typically, root is the
user ID.
2. Create the directory where you install the software, typically, /ezt/bin. Make the directory the current directory.
NOTE
If you previously linked programs with shared libraries, you should install this release in a different directory,
to isolate existing programs from using the new shared libraries.
3. If you are installing in an HP-UX environment:
Insert and mount the CD-ROM and issue the following command:
$ /bin/csh /cdrom/ezt/eztsetup /cdrom/ezt
– /cdrom/ezt
Identifies the location of the installation tar file.
For other environments:
Insert and mount the CD-ROM and issue the tar command:
$ tar xvf - < /cdrom/ezt/ezt.tar
– /cdrom/ezt
Identifies the location of the installation tar file.
4. When the tar command completes, change to the bin directory and issue the ./setup command to install product
licensing. You must have root authority to complete the setup operation.
5. Optionally, create an options table as described in Create or Modify an Options Table.
6. Optionally, create an alternate collating sequence table as described in Alternate Collating Sequence Table.
7. Review the information that is provided about archive as compared to shared libraries in Link-Editing Non-Mainframe
Programs to determine if you want to use the CA Easytrieve archive or the shared libraries for your applications.
8. Set all environment variables.
9. (DB2 only) You must create packages in the database for the two command programs: dqspsdbc and dqspsdbx. Using
the DB2 command line processor, connect to the database and issue the bind command for the bind files that were
installed:
bind dqspsdbc.bnd
bind dqspsdbx.bnd
10. Install the license key as described in Install the License Key.
55
CA Easytrieve® Report Generator 11.6
Verify the Installation
After you install CA Easytrieve, you must verify that the installation was successful.
You can verify the installation as follows:
• Verify the basic functionality.
• Verify the installation with Ingres, Oracle, and DB2.
Verify Basic Functionality
You can verify that the software is installed correctly by compiling and executing the testezt.ezt program. This program is
installed in the directory where you installed CA Easytrieve.
You can compile and execute from the directory where you installed the software. You can also copy testezt.ezt to the
home directory of your user ID. This procedure assumes that you did not rename testezt.ezt.
Follow these steps:
1. Compile testezt.ezt with the following command:
ezt testezt.ezt
The program compiles.
2. Execute testezt.ezt with the following command:
a.out
The executing program shows the following message on your terminal:
<easy> installed correctly
If the previous message does not appear, review the steps in the installation procedure and repeat the verify
procedure. If the message still does not display, contact CA Support.
Verify the Installation with Ingres, Oracle, and DB2
You can verify that the software installed correctly and can communicate with Ingres, Oracle, or DB2 by compiling and
executing the program for your database. The programs are found in the directory where you installed the software. You
can compile and execute the program from the directory where you installed the software. You can also copy the program
to the home directory of your user ID. This procedure assumes that you did not rename the program.
NOTE
The mode version of the libraries you link with must match the mode of your OS (32-bit or 64-bit).
Follow these steps:
1. Edit the program for your database as follows:
– testingr.ezt
(Optional) Identifies the Ingres application program. Change the USERID parameter of the PARM statement to a
valid Ingres user ID and password.
– testora.ezt
(Optional) Identifies the Oracle application program. Change the USERID parameter of the PARM statement to a
valid Oracle user ID and password.
– testdb2.ezt
(Optional) Identifies the DB2 application program. Change the USERID parameter of the PARM statement to a valid
DB2 user ID and password. Also change the SSID parameter to a valid database name.
The program is edited and ready for compile.
2. Compile the program with the EZT command as follows:
56
CA Easytrieve® Report Generator 11.6
ezt program
– program
Identifies the program for your database.
Limits: testingr.ezt (for Ingres), testora.ezt (for Oracle), testdb2.ezt (for DB2)
The program compiles and is ready for execution.
3. Execute the program with the following command:
a.out
The following message appears:
<easy> and Ingres are communicatin
<easy> and Oracle are communicating
<easy> and DB2 are communicating
If the message does not display, review the steps in the installation procedure and repeat the verify procedure. If the
message still does not display, contact CA Support.
Install CA Easytrieve for Linux PC
This section describes the following steps that are required for installing CA Easytrieve® in the Linux PC environment.
Preparing for Installation
Before you start the installation, note the following:
• Root authority is not required to install CA Easytrieve. However, you must have root authority to install CA
Technologies licensing and the unixODBC driver.
• GNU C Library (glibc) version 2.3.4 or above is required.
• New Curses Library (ncurses) is required.
• Determine whether you have a 32-bit or 64-bit system. If you are running a 64-bit OS, verify that the 32-bit compatibility
packages listed below are installed.
• Verify the available disk space before beginning. This product requires 115 MB of disk space.
32-Bit Compatibility Packages
If you are running a 64-bit OS, the following 32-bit packages must be installed:
• ncurses-libs
• glibc-devel
• glibc
• libgcc
For example, when running a Pentium Pro or later processor, install the following packages:
• ncurses-libs.i686
• glibc-devel.i686
• glibc.i686
• libgcc.i686
Install in the Linux Environment
This section describes how to install CA Easytrieve in the Linux PC environment.
57
CA Easytrieve® Report Generator 11.6
NOTE
If CA Easytrieve is already installed on the PC, remove it before following these instructions. Navigate to the
uninstall subdirectory (in the installed directory), type ./ezt_uninstall at the command prompt, and follow the
prompts.
Follow these steps:
1. Log into your Linux PC.
NOTE
We recommend logging in as a user with root access. Although CA Easytrieve installation does not require
this level of access, it is required to install CA Technologies licensing and the unixODBC driver.
2. Download the ezt_install file to a directory and make it the current directory.
3. Type ./ezt_install at the command prompt and press Enter.
4. Follow the prompts to install the software. During the interview phase:
– When you are prompted for the installation path, press Enter to accept the default path /opt/CA/ezt. Otherwise,
type a preferred path.
– When you are prompted to install CA Licensing, press Enter to accept the default Yes.
– A unixODBC message appears. If you plan to use CA Easytrieve with a non-native database such as Db2, you
must install the unixODBC driver separately. For more information, see Install the unixODBC Driver.
The installation proceeds. Upon completion, a successful installation message appears. A second message instructs
you to add four lines to your login profile.
5. Press Enter to exit the installer. Next, perform the Post-installation Tasks in the next section.
Post-installation Tasks
This section contains tasks that you must perform after you install CA Easytrieve on a Linux PC:
Update Your Login Profile
After completing the CA Easytrieve installation, you must update your login profile. The profile is located at /etc/profile.CA.
Add the following lines after the end of the profile text in the global login profile or individual user login profiles:
export EZT=/your_installation_path
if [ -f $EZT/eztprofile ]; then
. $EZT/eztprofile
fi
NOTE
The first line specifies the path that was specified during CA Easytrieve installation. The default path is /opt/CA/
ezt.
Update the CA Easytrieve Profile
To ensure that CA Easytrieve runs with the correct settings, add the following lines to your profile in $EZT/eztprofile if they
are not already present:
export USR_PATH=/usr/bin:/usr/lib:/usr/lib32:/usr/local/lib
export EZTPATH=$EZT/bin:$EZT/eztpgms:$USR_PATH
export PATH=$PATH:$EZTPATH
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$EZTPATH
export EZTOPTS="-W a,--32 -I $EZT/macros"
58
CA Easytrieve® Report Generator 11.6
NOTE
The first line is an example. Your EZTPATH path may be different.
Install CA Licensing
CA Licensing must be installed before you install the license key.
If you did not install CA licensing during product installation, check for the existence of the following directory:
/opt/CA/SharedComponents/ca_lic
If the directory does not exist, you must perform this procedure.
NOTE
If you installed CA Licensing during product installation, you do not need to perform this procedure. Instead,
follow the steps in Install the License Key.
Follow these steps:
1. Run the following command:
uname -a
2. If the result is x86_64, locate the lic98_Linux_AMD.tar file in the installation directory. Otherwise, locate
the lic98_linuxIntel.tar file.
3. Run the following command, specifying your .tar file:
tar -xvf tar_file.tar
The files are extracted.
4. Run the following command:
./install
When the command completes, the licensing files are in the following directory:
/opt/CA/SharedComponents
5. Follow the steps in Install the License Key.
Install the License Key
After installing CA Easytrieve on a Linux PC, you must install the ALP license key that was sent to you when the product
was purchased.
Before you install the license, verify that the ca_lic directory exists, as described in the CA Licensing section above.
For information about installing the license key, see Install the License Key.
Create the Options Table
After installing the product, you must create the options table. The option table contains options such as compiler and
execution options.
To create an options table, type the following commands:
cd $EZT/bin
etopload -b -l >ezoptbl.def</dev/null
NOTE
For more information about the options table, see Updating the Table.
59
CA Easytrieve® Report Generator 11.6
Install the unixODBC Driver
CA Easytrieve supports a native Oracle interface and an ODBC interface to connect with database. If you intend to use
the ODBC interface to access information from a database such as Db2, follow these instructions to download and install
the unixODBC driver. These instructions assume that an Internet browser is already installed on the Linux PC.
WARNING
CA Technologies has built and tested the driver that is provided on the following site. We recommend that you
use this driver. We do not support any other unixODBC drivers.
Follow these steps:
1. Type the following command:
yum remove unixODBC
2. Download unixODBC-2.3.0.tar.gz from the following location:
http://www.unixodbc.org/unixODBC-2.3.0.tar.gz
3. Type the following commands:
cd /tmp/temp
gunzip unixODBC*.tar.gz
tar xvf unixODBC*.tar
cd unixODBC-2.3.0
CFLAGS=-m32 LDFLAGS=-m32 CXXFLAGS=-m32 ./configure
make
make install
4. Go to the root directory and type the following command:
odbcinst -j
The following lines are displayed, confirming the installation:
unixODBC 2.3.0
DRIVERS............: /usr/local/etc/odbcinst.ini
SYSTEM DATA SOURCES: /usr/local/etc/odbc.ini
FILE DATA SOURCES..: /usr/local/etc/ODBCDataSources
USER DATA SOURCES..: /root/.odbc.ini
SQLULEN Size.......: 4
SQLLEN Size........: 4
SQLSETPOSIROW Size.: 2
NOTE
If the numbers for SQLULEN size and SQLLEN size are 8, contact Broadcom Support.
Verify the Installation
After you install CA Easytrieve, verify that the installation was successful.
WARNING
Update the profiles before verifying your installation.
Follow these steps:
1. Log out and then log in again.
2. Verify that the EZTPATH variable has been set by issuing the printenv command from the terminal.
Verify Communication with Ingres, Oracle, and DB2
You can verify that the software was installed correctly and can communicate with Ingres, Oracle, or DB2 by compiling
and executing the program for your database. The programs are found in the directory where you installed the software.
60
CA Easytrieve® Report Generator 11.6
You can compile and execute the program from the directory where you installed the software. You can also copy the
program to the home directory of your user ID. This procedure assumes that you did not rename the program.
NOTE
The mode version of the libraries you link with must match the mode of your OS (32-bit or 64-bit).
Follow these steps:
1. Edit the program for your database as follows:
– testingr.ezt
(Optional) Identifies the Ingres application program. Change the USERID parameter of the PARM statement to a
valid Ingres user ID and password.
– testora.ezt
(Optional) Identifies the Oracle application program. Change the USERID parameter of the PARM statement to a
valid Oracle user ID and password.
– testdb2.ezt
(Optional) Identifies the DB2 application program. Change the USERID parameter of the PARM statement to a valid
DB2 user ID and password. Also change the SSID parameter to a valid database name.
The program is edited and ready for compile.
2. Compile the program with the EZT command as follows:
ezt program
– program
Identifies the program for your database.
Limits: testingr.ezt (for Ingres), testora.ezt (for Oracle), testdb2.ezt (for DB2)
The program compiles and is ready for execution.
3. Execute the program with the following command:
a.out
The following message appears:
<easy> and Ingres are communicating
<easy> and Oracle are communicating
<easy> and DB2 are communicating
If the message does not display, review the steps in the installation procedure and repeat the verify procedure. If the
message still does not display, contact Broadcom Support.
Apply Maintenance
After you install the product, you must apply the latest maintenance (also called published solution or PTF).
Follow these steps:
1. Download the latest published solution from Broadcom Support.
NOTE
For more information about downloading published solutions, see Maintain You Product.
2. Go to the root directory and type the following command:
./ezt_patch-release-and-date -i console
3. Follow the instructions in the installer.
4. When you are prompted to exit the installer, press Enter.
Installation Troubleshooting
All installation information is written to a log. If you experience problems during installation, this log can help CA Support
troubleshoot the cause.
61
CA Easytrieve® Report Generator 11.6
The log can be found in the directory where CA Easytrieve was installed, and is named
CA_Easytrieve_Report_Generator_Install_date_time.log.
More Information:
For more information about CA Easytrieve, see the following articles:
• Customizing the options table
• Creating and maintaining an alternate collating sequence table
• Defining environment variables
• How to compile and execute your CA Easytrieve program
Install CA Easytrieve for z/OS
This section provides an overview of CA Easytrieve® Report Generator on the mainframe and describes:
CA Easytrieve provides a language to develop reports against existing data and the ability to manipulate information from
different sources to create data. CA Easytrieve lets programs execute in linkedited mode, which results in a load module.
WARNING
To support programs compiled and linked on a prior release of CA Easytrieve, a compatible runtime system is
shipped with this product. To take advantage of the new features and functionality of this, and future releases, a
program must be recompiled.
A "toolkit" option is offered to package commonly used functionality. You can also access various optional database
products as described in the following sections.
Toolkit Option
The Toolkit option provides easy-to-use pre-written routines. These routines enable users to further enhance the
capabilities of CA Easytrieve with minimal effort.
SQL Options
CA Easytrieve offers options that provide SQL access to DB2, Oracle, CA Datacom/DB, and CA IDMS. These programs
are interpretive and access is always dynamic. For DB2, you can also program this access using static SQL.
You can run existing programs that were written using SQL with this release.
Operating Environment
In your z/OS operating system, CA Easytrieve link-edited application programs execute in as little as 640 KB of main
storage. CA Easytrieve compilations and compile-and-go applications require a 2 MB to 4 MB region size. The size
depends on the number of dynamically acquired storage areas, such as I/O buffers and operating system control blocks.
The maximum amount of storage that is required depends on the size of the program to be compiled or executed, and the
options that are implemented.
Migration Considerations
CA Easytrieve is upwardly compatible. This means that older CA Easytrieve programs execute using the new CA
Easytrieve runtime; however, programs that are compiled using the new release of the product will not execute properly
using the older runtime libraries. This should be a consideration during migration. If you compile new application programs
in development at the current release, they will not run in production until that system is also upgraded. For more
information about migrating to the current release of CA Easytrieve from prior releases, see Release Notes.
62
CA Easytrieve® Report Generator 11.6
JCL Notation
Many examples of JCL are in this section. Because sites vary in their conventions for naming data sets, volumes, and
other computer-related resources, you must adjust the JCL.
CA Common Services
The CA Common Services (CCS) are a group of system services that help you manage your data center more efficiently.
CA Easytrieve requires the CAIRIM service (CA Resource Initialization Manager), which acts as a common driver for
dynamic initialization routines. For more information about CAIRIM and how to install it, see Installing in the CA Common
Services documentation.
Pre-Installation Considerations
Before you install CA Easytrieve, consider:
• The product component structure
• The required disk space
Product Component Structure
CA Easytrieve consists of several components. The term component refers to the base product component and its options
or interfaces. The components are provided in several files on the media. You can unload the components from the media
by specifying the correct CA LMP keyword in the installation jobs.
The SMP/E installation process installs all components into a single target and distribution library. The installation process
always creates the target and distribution libraries.
This release has the following SYSMODs:
• CBAAB60
Contains the runtime component for release 11.6.
• CCL2B60
Contains the 6.4 compatibility component.
• CA03B60
Contains the compiler component for release 11.6.
Disk Space
Before you install the product, review the following table for adequate space availability:
Data Set Description 3390 Cylinders Block Size
SAMPJCL Sample JCL file 1 3120
CBAALOAD Target Load Library 20 6144
CBAAMAC Target Macro Library 2 3120
CBAAJCL Target JCL/Sample Library 2 3120
CBAAXML Target CSM Metadata Library 2 3120
ABAALOAD Distribution Load Library 20 6144
ABAASRC Distribution Source Library 1 3120
ABAAMAC Distribution Macro Library 2 3120
ABAAXML Distribution CSM Metadata 2 3120
Library
SMPMTS SMP MTS 2 9040
63
CA Easytrieve® Report Generator 11.6
SMPSCDS SMP SCDS 2 9040
SMPSTS SMP STS 1 9040
SMPLOG SMP LOG 5 32000
SMPLOGA SMP LOGA 5 32000
SMPPTS SMP PTS 10 3120
SMPCSI SMP CSI 8 4096
NOTE
If you are upgrading from a previous r11 release, you might need to increase the size of the SMPPTS data set.
Allocate the replacement with SPACE=(CYL,(10,1,20)).
z/OS Installation Process
The following steps describe the z/OS installation process:
1. Prepare for the installation by confirming that your site meets all installation requirements.
2. Install your product based on your acquisition method.
– CA Chorus™ Software Manager (CA CSM)
For instructions regarding this method, see Install Your Product using CA CSM.
NOTE
If you do not have CA CSM, you can download it from the the Download Management page on Broadcom
Support. Next, follow the Installing procedure in the CA CSM Version 6.1 documentation.
– Pax-Enhanced Electronic Software Delivery (ESD) or DVD
For instructions regarding this method, see Installing Your Product Using Pax ESD or DVD.
3. Apply maintenance, if applicable.
4. Deploy your product.
5. Configure the minimum settings for your product.
For configuration instructions, see Configure Your Product.
How the Installation Process Works
CA Technologies has standardized product installations across all mainframe products. Installation uses the following
process:
• Acquisition
Transports the software to your z/OS system.
• Installation using SMP/E
Creates an SMP/E environment and runs the RECEIVE, APPLY, and ACCEPT steps. The software is untailored.
• (For CA CSM Release 5.1 and earlier only) Deployment
Copies the target libraries to another system or LPAR.
NOTE
This step is optional for CA CSM Version 6.0. For more information, see Configure Your Product Using CA
CSM.
• Configuration
Creates customized load modules, bringing the software to an executable state.
• (For staging system configurations in CA CSM Version 6.0 only) Deployment
Makes configured run-time libraries available to a remote location where that software can be activated, bringing it to
an executable state.
CA Chorus™ Software Manager (CA CSM), formerly known as CA Mainframe Software Manager™ (CA MSM), is an
intuitive web-based tool that can automate and simplify many CA Technologies product installation activities on z/OS
64
CA Easytrieve® Report Generator 11.6
systems. This application also makes obtaining and applying corrective and recommended maintenance easier. A web-
based interface enables you to install and maintain your products faster and with less chance of error. As a best practice,
we recommend that you install mainframe products and maintenance using CA CSM. Using CA CSM, someone with
limited knowledge of JCL and SMP/E can install a product.
NOTE
If you do not have CA CSM, you can download it from Download Management on Broadcom Support. Follow
the installation instructions in the CA CSM documentation.
You can also complete the standardized installation process manually using pax files that are downloaded from Broadcom
Supportor a product DVD.
To install your product, do the following tasks:
1. Prepare for the installation by confirming that your site meets all installation requirements.
2. Verify that you acquired the product using one of the following methods:
– Download the software from Broadcom Support using CA CSM.
– Download the software from Broadcom Support using Pax-Enhanced Electronic Software Delivery (Pax ESD).
– Order a product DVD. To do so, contact your account manager or a CA Technologies Support representative.
3. Perform an SMP/E installation using one of the following methods:
– If you used CA CSM to acquire the product, start the installation process from the SMP/E Environments tab in CA
CSM.
– If you used Pax ESD to acquire the product, you can install the product in the following ways:
• Install the product manually.
• Complete the SMP/E installation using the Add Product option in CA CSM.
– If you have a product DVD, install the product manually.
NOTE
If a CA Recommended Service (CA RS) package is published for your product, install it before proceeding.
4. (For CA CSM Release 5.1 and earlier only) Deploy the target libraries.
NOTE
This step is optional for CA CSM Version 6.0. For more information, see the Configuring Products
scenario that is available in the CA CSM documentation.
5. Configure your product using CA CSM or manually.
6. (For staging system configurations in CA CSM Version 6.0 only) Deploy configured run-time libraries, and activate your
product.
NOTE
Configuration is considered part of starting your product.
Preparing for Installation
CA Common Services Requirements
The following CA Common Services are used with your product:
• CAIRIM
• CAICCI
• CA LMP
NOTE
If other CA Technologies products are installed at your site, some of these services are already installed.
65
CA Easytrieve® Report Generator 11.6
LMP Key Requirements
The CA License Management Program (CA LMP) tracks licensed software in a standardized and automated way. CA
LMP uses common real-time enforcement software to validate the user configuration. CA LMP reports on activities that
are related to the license, usage, and financials of CA Technologies products.
Your product is licensed with an LMP key. You acquire the LMP key with one of the following methods:
• From your product media
• With Pax ESD
• From the Licencing section on Broadcom Support
NOTE
For more information about LMP keys, see CA LMP in the CA Common Services for z/OS documentation.
USS Space Requirements
Ensure that you have sufficient free space in the USS file system that you are using for Pax ESD to hold the directory that
the pax command and its contents create. You need approximately 3.5 times the pax file size in free space.
If you do not have sufficient free space, you receive error message EDC5133I.
Concurrent Releases
You can install this release of your product and continue to use an older release in another SMP/E environment. If you
plan to continue to run a previous release, consider the following points:
• When you install the product into an existing SMP/E environment, this installation deletes previous releases in that
environment.
• If you acquired your product with Pax ESD, select different target and distribution zones for your new release from
where your current release is installed. The new zones use different libraries than your current release.
NOTE
CA CSM installs a product into a new SMP/E environment by default. You can select an existing SMP/E
environment from your working set. For more information, see the online help that is included in CA CSM.
• Define DDDEF entries in your new zones to point SMP/E to the proper libraries for installation. Ensure that they point
to the new release libraries.
Install Your Product Using CA CSM
As a system programmer, your responsibilities include acquiring, installing, maintaining, deploying, and configuring CA
Technologies mainframe products on your system.
CA Chorus™ Software Manager (CA CSM) is an application that simplifies and unifies the management of your CA
Technologies mainframe products on z/OS systems. As products adopt the CA CSM services, you can install your
products in a common way according to industry best practices.
If you do not have CA CSM installed, download it from Download Management on the Broadcom Support website.
NOTE
For more information, see the CA CSM documentation.
Use the following scenarios to guide you through the product installation process using CA CSM:
66
CA Easytrieve® Report Generator 11.6
• Acquire Products Using CA CSM
• Install Products Using CA CSM
• Maintain Products Using CA CSM
• Configure Products Using CA CSM
NOTE
For additional information about how to use CA CSM, use the CA CSM online help.
Acquire Products Using CA CSM
CA Chorus™ Software Manager (CA CSM) can help automate acquiring, installing, maintaining, deploying, and
configuring mainframe software. As a system programmer, you maintain an up-to-date repository of acquired product
packages that are ready for installation in your mainframe environment. CA CSM provides a product list that lets you
display the list of licensed product installation and maintenance packages and to download these packages. Also, you
can add to the product list external product packages that you acquired outside of CA CSM so that they are ready for
installation using CA CSM.
This diagram shows the product acquisition process:
67
CA Easytrieve® Report Generator 11.6
Figure 1: Acquiring_Products_CIG
1. Configure CA CSM.
2. If you can download the product package from Broadcom Support:
a. Update the product list.
b. Download product packages.
3. If you cannot download the product package from Broadcom Support:
a. Add external product installation packages.
b. Add external product maintenance packages.
After you complete this process, the product packages are ready for installation with CA CSM.
NOTE
For more information about acquiring products, see the CA CSM online help.
68
CA Easytrieve® Report Generator 11.6
Configure CA CSM
Before you start acquiring product packages, configure a Broadcom Support online account, a CA CSM account, and the
required download settings. If you have previously configured these settings, update the product list.
Follow these steps:
1. Start your Web browser, and enter the CA CSM access URL, which you can get from your system administrator.
NOTE
If the Notice and Consent Banner appears, read and confirm the provided information.
2. Enter your z/OS login user name and password, and log in.
The initial page appears. You are prompted to perform configuration.
3. Configure the following settings:
– Proxies that CA CSM uses to communicate with Broadcom Support.
If proxies are not used, CA CSM uses HTTPS Port Number 443 and FTP Port Number 21.
WARNING
If your site uses proxies, review your proxy credentials on the User Settings, Software Acquisition page.
– The USS path to the temporary directory for downloaded software packages
If you do not specify the directory, CA CSM sets it up using default settings that you can change later.
NOTE
These settings are also available on the System Settings, Software Acquisition page.
Select Next.
You are prompted to define your account on Broadcom Support.
4. Select New.
You are prompted for the credentials to use on Broadcom Support.
5. Specify the credentials, select OK, and then Next.
You are prompted to review your user settings.
NOTE
These settings are available on the User Settings page.
6. Change the settings or keep the defaults, and then select Finish.
A dialog opens, which shows the progress of the configuration task.
7. Select the Settings tab, and review other settings, as needed.
You have configured CA CSM to acquire products.
Update the Product List
The product list displays a list of downloadable licensed product packages. To see the current list of available product
packages for download, update the Available Products tree.
Follow these steps:
1. Log in to CA CSM using your credentials.
2. Select the Products tab.
3. (Optional) Update the product list only with packages that belong to specific site IDs.
a. Select the Edit button in the Filter section and associate one or more site IDs to a filter in the Edit Filter window.
b. Select the filter in the Filter section.
c. Right-click the Products link at the top of the product tree and select Update Product List.
4. Select the Update Product List link in the Actions section on the left side.
Updating of the product list with all products for all site IDs starts.
NOTE
Skip this step if you already updated the product list only for a selected filter.
69
CA Easytrieve® Report Generator 11.6
5. Confirm the update.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on
the Progress tab to close this dialog. The task output browser opens, and you can view the action details.
Select Close to close the task output browser.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
The product list is updated.
Download Product Packages
You can download product installation and maintenance packages from the updated product catalog so they are ready for
installation.
Follow these steps:
1. Log in to CA CSM using your credentials.
2. Select the Products tab.
3. Select the product name on the Available Products tree.
The product releases are listed in the Releases table on the right.
4. Select one of the following options:
– To download product packages for all product releases, right-click the product name in the list, and select Update
Product.
– To download packages only for specific releases, select one or more releases in the Releases table on the right
and select the Update Product Releases link.
5. To view the downloaded packages, you have the following options:
6. • To display the downloaded maintenance packages, select the product release
icon in
the product list.
• To display the downloaded base installation packages, select the product gen level
icon bel
the product release in the product list.
The product packages are downloaded and ready for installation.
Add External Product Installation Packages
Sometimes you have product installation packages that you downloaded outside of CA CSM. For example, you do
not have an HTTP or an FTP access in your mainframe environment, or the required packages are not available
from Broadcom Support. You can use CA CSM to install these external packages according to your organization policy. If
you are using this installation option, first add the external packages to the CA CSM software catalog.
Follow these steps:
1. Log in to CA CSM using your credentials.
2. Select the Products tab.
3. Select the Add Product link in the Actions section.
4. Specify the name, release, and gen level of the product, and select OK.
The product is added to the product list.
5. Select the gen level of the product that you want to download on the product tree.
The Base Install Packages section appears on the right.
6. Select the Add External Package button.
70
CA Easytrieve® Report Generator 11.6
7. Specify one of the following package types and package details, and select OK.
– UNIX File
Adds an installation package that is located in a USS directory in binary mode.
– FTP File
Adds a product package that is not published on Broadcom Support, for example, a beta version of a product.
• FTP Host
Specifies the FTP server where the installation package is located. Select a server from the list, or provide your
FTP server host.
• FTP Port
Specifies the FTP port number for the FTP server.
• FTP Path
Defines the FTP path where the installation package is located. Start the path with a forward slash (/). Enter only
a forward slash to specify the root directory.
Example: /outgoing/
• Package Name
Defines the package name.
Example: 0111.pax.Z
Note: You can use an asterisk (*) for the package name.
• User Name
Defines a valid user name to access the FTP location.
• Password
Defines a valid password to access the FTP location.
8. Refresh the page to see the added product package.
The product installation package is now listed in the product list and is available for installation with CA CSM.
Add External Product Maintenance Packages
Sometimes you have maintenance packages, for example, unpublished maintenance or a program temporary fix (PTF),
that you downloaded outside of CA CSM. You can use CA CSM to install these external maintenance packages per your
organization policy. For this installation option, first add the packages to the CA CSM software catalog.
Usually, the maintenance is placed as a single package. However, some CA products have older aggregated maintenance
packages that were released before December 31, 2013. An aggregated package is a file that comprises several single
maintenance packages (nested packages). When you add an aggregated package, CA CSM inserts all the nested
packages and the aggregated package itself. In the list of maintenance packages, the aggregated package is marked with
the CUMULATIVE type.
Follow these steps:
1. Log in to CA CSM using your credentials.
2. Select the Products tab.
3. Select the product release for which the maintenance applies.
The maintenance packages for the release are listed.
4. Select the Add External Maintenance button.
You are prompted to specify the package.
5. Specify one of the following package types and package details:
– Data Set
Adds a maintenance package that is located in a z/OS data set with a logical record length of 80 and with a record
format of fixed blocks.
– UNIX File
Adds a maintenance package that is located in a USS directory in binary mode.
– FTP File
71
CA Easytrieve® Report Generator 11.6
Adds a maintenance package that is not published on Broadcom Support. This option is intended for downloading a
PTF to validate it.
• FTP Host
Specifies the FTP server where the maintenance package is located. Select a server from the list, or provide
your FTP server host.
• FTP Port
Specifies the FTP port number for the FTP server.
• FTP Path
Defines the FTP path where the maintenance package is located. Start the path with a forward slash (/). Enter
only a forward slash to specify the root directory.
Example: /outgoing/
• Maintenance Name
Defines the maintenance package name.
Example: RO01111.bin
• User Name
Defines a valid user name to access the FTP location.
• Password
Defines a valid password to access the FTP location.
– Solution
Adds a published solution from Broadcom Support.
6. Refresh the page to see the added maintenance package.
The product maintenance package is now listed in the product catalog and is available for installation with CA CSM.
You completed the acquiring process. The product packages are ready for installation with CA CSM.
Install Products Using CA CSM
CA Chorus™ Software Manager (CA CSM) can help automate acquiring, installing, maintaining, deploying, and
configuring mainframe software. As a System Programmer, your responsibilities include installing products in your z/OS
environment using CA CSM.
This diagram shows the major steps to install your product using CA CSM.
72
CA Easytrieve® Report Generator 11.6
Figure 2: Installing_Products
73
1. (Optional) Configure base installation settings.
CA Easytrieve® Report Generator 11.6
2. (Optional) Configure a working set of SMP/E environments.
3. Initiate product installation and review product information.
4. Select an installation type.
5. Review installation prerequisites if any are presented.
6. Take one of the following steps to select an SMP/E environment:
– Create an SMP/E environment:
a. Set up the global zone.
b. Create a target zone.
c. Create a distribution zone.
– Use an existing SMP/E environment from your working set:
a. Update the global zone.
b. Set up the target zone: Either create a target zone or use an existing target zone.
c. Set up the distribution zone: Either create a distribution zone or use an existing distribution zone.
NOTE
If you install a product or its components into an existing target or distribution zone, older versions are
deleted from the zone and associated data sets. We recommend that you use new target and distribution
zones for this installation. Doing so means that you can apply maintenance to your current version, if
necessary.
7. Review the installation summary and start the installation.
NOTE
For more information about installing products, see the CA CSM online help.
Configure Base Installation Settings
You can configure base installation settings on the System Settings, Software Installation page.
Follow these steps:
1. Select the Settings tab, and select the Software Installation link under System Settings in the Settings section on the
left side.
2. In the SIS Base Install - File System section, select the file system type that is used when installing a product that
allocates file systems. You select one of the following options:
– Product Specific File System
– z/OS Distributed File Service zSeries File System (zFS)
NOTE
If you select Product Specific File System, the file system that is used for installing a product is defined
according to the product metadata. Otherwise, the product metadata is overwritten.
3. In the Execute Checks During Base Installation section, configure the following settings by selecting or clearing
corresponding checkboxes:
– Execute Apply Check During Base Installation
Verifies that all requirements for the Apply step are satisfied before the Apply step executes. If the Apply Check
step fails, installation stops and all the previous steps are undone.
– Suspend Base Installation After Apply Check
Suspends the base installation process after Apply Check is completed and generates pending installation actions
for the SMP/E environment where the product is being installed.
NOTE
This check box is enabled if you enable the Execute Apply Check During Base Installation checkbox.
– Execute Accept Check During Base Installation
74
CA Easytrieve® Report Generator 11.6
Verifies that all requirements for the Accept step are satisfied before the Accept step executes. If the Accept Check
step fails, installation stops and all the previous steps are undone.
– Suspend Base Installation After Accept Check
Suspends the base installation process after Accept Check is completed and generates pending installation actions
for the SMP/E environment where the product is being installed.
NOTE
This check box is enabled if you enable the Execute Accept Check During Base Installation checkbox.
4. Select Apply.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
The base installation settings are configured.
NOTE
If you configure the base installation settings to execute checks during base installation, CA CSM creates a
pending installation for the SMP/E environment. For more information about the pending installation, see the CA
CSM online help.
Configure a Working Set of SMP/E Environments
If you plan to install a product in an existing SMP/E environment, add this SMP/E environment to your working set. A
working set is a selected group of SMP/E environments with which you want to work. Although you can have only one
working set, you can have as many SMP/E environments in it as you need.
NOTE
CA CSM does not have a default working set.
If you do not have the SMP/E environment in your working set, you can only create a new SMP/E environment during
product installation. In this case, exit the installation wizard, configure your working set and then restart the wizard.
Follow these steps:
1. Select the SMP/E Environments tab, and select the SMP/E environments that you want to include in a working set.
An information text area under the list of SMP/E environments displays the number of environments you selected.
2. Select Use as Working Set.
3. Select OK.
The working set is configured.
The new working set replaces a previously defined working set.
You can display only those SMP/E environments that are in your working set by selecting Show Working Set Only.
Initiate Product Installation
You can install a downloaded product from the Products tab. The process starts a wizard that guides you through the
installation. At the end of the wizard, a task dynamically invokes the SMP/E and other utilities that are required to install
the product.
Follow these steps:
1. Select the Products tab.
2. Perform one of the following steps:
– If the package was acquired using CA CSM:
75
CA Easytrieve® Report Generator 11.6
From the product list on the left side, select the required product gen level (the innermost level in the product list
under the release level of a product; for example, SP0 or 0110). Locate the product package that you want to install,
select Actions to the right of the package, and select Install.
– If the package was acquired outside of CA CSM:
In the Actions section in the left pane, select the Install External Package link. Enter the location of the package.
Select OK.
The Introduction step of the wizard appears.
Review Product Information
Review the information about the product that you are installing.
Follow these steps:
1. On the Introduction step, review the information about the installation.
NOTE
If the product license agreement appears, review it. If you agree, accept it. If you do not accept the license
agreement, you cannot proceed with the installation.
2. Select Next.
You are prompted to select the type of installation.
NOTE
An information text area can appear at the bottom of the wizard. The area provides information that helps
you progress through the wizard. For example, if a field is highlighted (indicating an error), the information
text area identifies the error.
Select an Installation Type
When you install a product, you select an installation type. There can be one or more installation types, according to the
product.
When you select the custom installation type, you are prompted to select the features that you want to install. If your
selected features require installation of other features, the installation wizard includes the required features to the
installation process. If your selected features are mutually exclusive, the installation wizard excludes any features
conflicting with the features you selected last from the installation process. For example, you select feature 1 and then
select feature 2 that is mutually exclusive with feature 1. The wizard then automatically excludes feature 1.
Follow these steps:
1. On the Features step, select the type of installation, and select Next.
2. (Optional) If you select the custom installation type, select the features to install, and select Next.
A summary of the features to install appears, with prerequisites.
Review Installation Prerequisites
Some products require an installation of other products first.
Review the summary of installation prerequisites to verify that all prerequisites are satisfied on the Prerequisites step.
• If no prerequisites exist, select Next.
You are prompted to select an SMP/E environment for the installation.
• If all prerequisites exist and are satisfied, you are prompted to locate the installed prerequisites.
Install the product to the same SMP/E environment and the target zone where the product prerequisites are installed.
a. From the SMP/E environment drop-down list, select an SMP/E environment with the installed prerequisites. This
drop-down list represents all CA CSM-managed SMP/E environments where the prerequisites are installed.
A list of target zones for the selected SMP/E environment where the prerequisites are installed is populated.
76
CA Easytrieve® Report Generator 11.6
b. From the target zone drop-down list, select a target zone within the selected SMP/E environment where the
prerequisites are installed.
c. Select Next.
You are prompted to confirm the selected SMP/E environment for the installation.
• If prerequisites are not satisfied, perform one of the following actions:
– Select Cancel to exit the wizard. Install the prerequisites or migrate an SMP/E environment to CA CSM where the
prerequisites are installed. Restart the installation.
– Open CA CSM in another browser window and install the prerequisites, or migrate an SMP/E environment to CA
CSM where the prerequisites are installed. After you complete, select Refresh on the Prerequisites step of the
wizard. Then, select the SMP/E environment and a target zone where the prerequisites are installed. Select Next to
continue the product installation.
You are prompted to confirm the selected SMP/E environment for the installation.
Select an SMP/E Environment
You select the SMP/E environment where you want to install your product in. You can create an SMP/E environment, or
you can select an existing SMP/E environment from your working set. You can configure your working set from the SMP/E
Environments tab.
While you work with an SMP/E environment, the environment is locked and other CA CSM users cannot perform any
action against it. When the task finishes, logging out from CA CSM, or a CA CSM session is inactive for more than 10
minutes, the lock releases.
If you select an SMP/E environment being used in CA CSM by another user, a notification message appears. You are
prevented from performing any actions on the SMP/E environment. You can wait until the notification message disappears
and the SMP/E environment becomes available or can select Cancel to select another SMP/E environment.
Follow these steps:
1. On the SMP/E Environment step, substep 1, take one of the following steps:
– Select Create a New SMP/E Environment to create an SMP/E environment.
– Select an existing SMP/E environment from your working set.
• If no existing SMP/E environment appears, exit the wizard, configure your working set, and restart the wizard.
• If your product has the installed prerequisites, the SMP/E environment with the installed prerequisites that
you selected at the Prerequisites step of the wizard is preselected for you. You cannot select another SMP/E
environment. You cannot create a new SMP/E environment.
NOTE
When you install a product in an existing SMP/E environment where HOLDDATA is received, the
product installation may fail. For more information, see the online help.
2. Select Next.
You are prompted to set up the SMP/E environment.
Create an SMP/E Environment
You can create an SMP/E environment while you are installing a product. During the process, you are asked to specify the
following information:
• The SMP/E environment name and the prefix of the CSI data set in CA CSM
• Data set allocation parameters
You can specify data set allocation parameters collectively for all SMP/E data sets, target libraries, and distribution
libraries that are allocated during product installation. You allocate data sets using one of the following methods:
77
CA Easytrieve® Report Generator 11.6
• Allocate data sets using SMS parameters.
• Allocate cataloged data sets using UNIT and optionally VOLSER.
• Allocate uncataloged data sets using UNIT and VOLSER.
If you allocate uncataloged data sets, specify a VOLSER. Based on the value that you enter, CA CSM performs the
following validations to ensure integrity of the installation:
• The value of VOLSER must specify a mounted volume.
• You must have ALTER permissions for the data sets with the entered high-level qualifier (HLQ) on the volume that
VOLSER defines.
• To test allocation, CA CSM temporarily allocates one of the uncataloged data sets that are allocated during the
installation.
a. The data set is allocated with one track for both primary and secondary space.
b. CA CSM verifies that the data set has been allocated on the specified volume.
c. The data set is deleted.
If the data set allocation fails or the data set cannot be found on the specified volume, you cannot proceed with the
product installation wizard.
Follow these steps:
1. On the SMP/E Environment step, substep 2, review and specify the following parameters as applicable:
– SMP/E Environment Name
Defines the SMP/E environment name.
– Data Set Name Prefix
Defines the prefix for the name of the CSI VSAM data set.
– Catalog
Defines the name of the SMP/E CSI catalog.
– Cross-Region
Identifies the cross-region sharing option for SMP/E data sets.
NOTE
This parameter is set to its default value, and you cannot edit it.
– Cross-System
Identifies the cross-system sharing option for SMP/E data sets.
NOTE
This parameter is set to its default value, and you cannot edit it.
– High-Level Qualifier
Specifies the high-level qualifier (HLQ) for all SMP/E data sets that are allocated during installation. Product
packaging defines the low-level qualifiers (LLQ). The low-level qualifiers cannot be changed.
– DSN Type
Specifies the DSN type for allocating SMP/E data sets.
– SMS Parameters / Data Set Parameters
Specifies if this SMP/E environment is using SMS or data set parameters.
• Storage Class (SMS Parameters only)
Defines the SMS storage class for SMP/E data sets.
• Management Class (SMS Parameters only)
Defines the management class for SMP/E data sets.
• Data Class (SMS Parameters only)
Defines the data class for SMP/E data sets.
• VOLSER (Data Set Parameters only)
Defines the volume serial number on which to place data sets. The volume must have enough space for
allocating the data sets.
78
CA Easytrieve® Report Generator 11.6
NOTE
This field is mandatory if you set Catalog to No.
• Unit (Data Set Parameters only)
Defines the type of the DASD on which to place data sets.
• Catalog (Data Set Parameters only)
Specifies if you want SMP/E data set to be cataloged.
NOTE
An information text area can appear at the bottom of the wizard. The area provides information that helps
you progress through the wizard. For example, if a field is highlighted (indicating an error), the information
text area identifies the error.
2. Select Next.
Work DDDEF allocation parameters and a list of the data sets to be created for the SMP/E environment appear.
Review Parameters of an Existing SMP/E Environment
When you use an existing SMP/E environment to install your product, you review the SMP/E environment parameters.
If applicable, you also specify parameters for any new data sets to be allocated while installing a product. During the
process, you are asked to review allocation parameters for new data sets, which you can customize for each data set. The
existing data sets remain intact.
The Software Installation Service (SIS) determines which data sets exist and which must be allocated for the installation
using an existing SMP/E environment. If the SIS determines that new data sets must be allocated, you are prompted to
specify the data set allocation parameters. The data set allocation parameters are prepopulated with the values from the
existing data set that was found first.
Follow these steps:
1. On the SMP/E Environment step, substep 2, review the current SMP/E environment parameters and allocation
parameters for data sets that must be added to the SMP/E environment. Update the information as applicable:
NOTE
You cannot change the current SMP/E environment parameters.
– SMP/E Environment Name
Identifies the SMP/E environment name.
– Data Set Name Prefix
Identifies the prefix for the name of the CSI VSAM data set.
– Catalog
Identifies the name of the SMP/E CSI catalog.
– Cross-Region
Identifies the cross-region sharing option for SMP/E data sets.
– Cross-System
Identifies the cross-system sharing option for SMP/E data sets.
– High-Level Qualifier
Specifies the high-level qualifier (HLQ) for all SMP/E data sets that are allocated during installation. Product
packaging defines the low-level qualifiers (LLQ). The low-level qualifiers cannot be changed.
– DSN Type
Specifies the DSN type for allocating SMP/E data sets.
– SMS Parameters / Data Set Parameters
Specifies if this SMP/E environment is using SMS or data set parameters.
• Storage Class (SMS Parameters only)
Defines the SMS storage class for SMP/E data sets.
• Management Class (SMS Parameters only)
79
CA Easytrieve® Report Generator 11.6
Defines the management class for SMP/E data sets.
• Data Class (SMS Parameters only)
Defines the data class for SMP/E data sets.
• VOLSER (Data Set Parameters only)
Defines the volume serial number on which to place data sets. The volume must have enough space for
allocating the data sets.
NOTE
This field is mandatory if you set Catalog to No.
• Unit (Data Set Parameters only)
Defines the type of the DASD on which to place data sets.
• Catalog (Data Set Parameters only)
Specifies if you want SMP/E data set to be cataloged.
NOTE
An information text area can appear at the bottom of the wizard. The area provides information that helps
you progress through the wizard. For example, if a field is highlighted (indicating an error), the information
text area identifies the error.
2. Select Next.
Work DDDEF allocation parameters and a list of the data sets to be created for the SMP/E environment, if any,
appear.
Set Up SMP/E Environment Parameters
When creating an SMP/E environment for your product installation, you specify SMP/E environment parameters.
When using an existing SMP/E environment for installing your product, you review and, if necessary, update its SMP/E
environment parameters.
You can assign different prefixes to each newly allocated data set during the installation process.
Follow these steps:
1. On the SMP/E Environment step, substep 3, specify whether to use SMS or Unit parameters for allocating work
DDDEFs for the SMP/E environment. Complete the appropriate fields. The following fields are available depending on
your selection:
– Storage Class (SMS only)
Defines the SMS storage class for work DDDEFs.
– Management Class (SMS only)
Defines the management class for work DDDEFs.
– Data Class (SMS only)
Defines the data class for work DDDEFs.
– Unit (Unit only)
Defines the type of the DASD on which to place work DDDEFs.
The allocation parameters that you specify for work DDDEFs are applied only to new work DDDEFs that are created
during the installation. The existing work DDDEFs, if any, remain intact.
NOTE
The settings for allocating work DDDEFs are globally defined on the System Settings, Software
Installation tab. You must have the appropriate access rights to be able to modify these settings.
2. Review the data set names if any appear. Select the Override link to change the high-level qualifier of the data set
name and the allocation parameters. Select OK.
3. (Optional) If any additional parameters appear, review the parameters that already have the default values assigned.
Edit the parameters if necessary and specify any missing parameters.
4. Select Next.
80
CA Easytrieve® Report Generator 11.6
You are prompted to select a target zone to use.
Select a Target Zone
You select a target zone in the SMP/E environment where you want to install your product. You create a target zone or
select an existing target zone in the SMP/E environment (if you use an existing SMP/E environment).
Follow these steps:
1. On the Target Zone step, substep 1, perform one of the following actions:
– Select Create a New Target Zone to create a target zone.
– Select an existing target zone in the SMP/E environment.
This option is available only if you selected to use an existing SMP/E environment.
WARNING
• If you install a product or its components into an existing target or distribution zone, older versions are
deleted from the zone and associated data sets. We recommend that you use new target and distribution
zones for this installation so that you can apply maintenance to your current version, if necessary.
• If your product has the installed prerequisites, the target zone of the SMP/E environment with the installed
prerequisites that you selected at the Prerequisites step of the wizard is preselected for you. You cannot
select another target zone. You cannot create a new target zone.
2. Select Next.
You are prompted to set up the target zone.
Create a Target Zone
You can create a target zone in a new or an existing SMP/E environment where you install your product. The target zone
parameters are prepopulated with the values that are entered for the SMP/E environment. You can change data set
allocation parameters.
You can specify a different SMP/E environment data set to be used for a new target zone.
Follow these steps:
1. On the Target Zone step, substep 2, review and specify the following parameters as applicable:
– Target Zone Name
Defines the name for the target zone.
– Create New CSI Data Set
Specifies that a new CSI data set will be created for the target zone.
– Data Set Name Prefix
Defines the prefix for the name of the target zone data set.
NOTE
This field is only enabled when you have the Create New CSI Data Set check box selected.
– Catalog
Defines the name of the SMP/E target zone catalog.
NOTE
This field is only enabled when you have the Create New CSI Data Set check box selected.
– Cross-Region
Identifies the cross-region sharing option for SMP/E data sets.
NOTE
This parameter is set to its default value, and you cannot edit it.
– Cross-System
Identifies the cross-system sharing option for SMP/E data sets.
81
CA Easytrieve® Report Generator 11.6
NOTE
This parameter is set to its default value, and you cannot edit it.
– High-Level Qualifier
Specifies the high-level qualifier (HLQ) for all target zone data sets that are allocated during installation. Product
packaging defines the low-level qualifiers (LLQ) and they cannot be changed.
– DSN Type
Specifies the DSN type for allocating target zone data sets.
– SMS Parameters / Data Set Parameters
Specifies if this target zone uses SMS or data set parameters.
• Storage Class (SMS Parameters only)
Defines the SMS storage class for target zone data sets.
• Management Class (SMS Parameters only)
Defines the management class for target zone data sets.
• Data Class (SMS Parameters only)
Defines the data class for target zone data sets.
• VOLSER (Data Set Parameters only)
Defines the volume serial number on which to place data sets. The volume must have enough space for
allocating the data sets.
NOTE
This field is mandatory if you set Catalog to No.
• Unit (Data Set Parameters only)
Defines the type of the DASD on which to place data sets.
• Catalog (Data Set Parameters only)
Specifies if you want SMP/E data set to be cataloged.
NOTE
An information text area can appear at the bottom of the wizard. The area provides information that helps
you progress through the wizard. For example, if a field is highlighted (indicating an error), the information
text area identifies the error.
2. Select Next.
A list of the data sets to be created for the target zone appears.
Use an Existing Target Zone
When using an existing target zone for installing your product, you review and, if necessary, update its parameters.
Follow these steps:
1. On the Target Zone step, substep 2, review the current target zone parameters and allocation parameters for data
sets that must be added. Update as applicable:
NOTE
You cannot change the current SMP/E environment parameters.
a. • Target Zone Name
Identifies the name for the target zone.
• Data Set Name Prefix
Identifies the prefix for the name of the target zone data set.
• Catalog
Identifies the name of the SMP/E target zone catalog.
• Cross-Region
Identifies the cross-region sharing option for SMP/E data sets.
• Cross-System
82
CA Easytrieve® Report Generator 11.6
Identifies the cross-system sharing option for SMP/E data sets.
• High-Level Qualifier
Specifies the high-level qualifier (HLQ) for all target zone data sets that are allocated during installation. Product
packaging defines the low-level qualifiers (LLQ) and they cannot be changed.
• DSN Type
Specifies the DSN type for allocating target zone data sets.
• SMS Parameters / Data Set Parameters
Specifies if this target zone uses SMS or data set parameters.
• Storage Class (SMS Parameters only)
Defines the SMS storage class for target zone data sets.
• Management Class (SMS Parameters only)
Defines the management class for target zone data sets.
• Data Class (SMS Parameters only)
Defines the data class for target zone data sets.
• VOLSER (Data Set Parameters only)
Defines the volume serial number on which to place data sets. The volume must have enough space for
allocating the data sets.
Note: This field is mandatory if you set Catalog to No.
• Unit (Data Set Parameters only)
Defines the type of the DASD on which to place data sets.
• Catalog (Data Set Parameters only)
Specifies if you want SMP/E data set to be cataloged.
NOTE
An information text area can appear at the bottom of the wizard. The area provides information that helps
you progress through the wizard. For example, if a field is highlighted (indicating an error), the information
text area identifies the error.
2. Select Next.
If there are any data sets to be created for the target zone, a list of data sets appears. If the list is empty, no new data
sets are going to be allocated.
Set Up Target Zone Parameters
When creating a target zone in the SMP/E environment for your product installation, specify target zone parameters.
Follow these steps:
1. On the Target Zone step, substep 3, review the data set names if any appear. Select the Override link to change the
high-level qualifier of the data set name and the allocation parameters. Select OK.
2. (Optional) If more parameters appear, review the parameters that have the default values assigned. Edit the
parameters if necessary and specify any missing parameters.
3. Select Next.
You are prompted to confirm the distribution zone.
Confirm a Distribution Zone
You must confirm a distribution zone of the SMP/E environment where you want to install your product. Depending on
whether you created a target zone or you selected an existing target zone, create a distribution zone or select an existing
distribution zone in the SMP/E environment.
Follow these steps:
1. On the Distribution Zone step, substep 1, review the selected option for the distribution zone.
83
CA Easytrieve® Report Generator 11.6
– If you are using an existing target zone, the related distribution zone is automatically selected. You cannot select
other distribution zones or cannot create a new one.
NOTE
If you install a product or its components into an existing target or distribution zone, older versions are
deleted from the zone and associated data sets. We recommend that you use new target and distribution
zones for this installation so that you can apply maintenance to your current version, if necessary.
– If you are creating a target zone, you can create a distribution zone or you can select an existing distribution zone.
NOTE
Using an existing distribution zone with a new target zone relates the existing distribution zone to the
new target zone. This action breaks the relationship from the previous target zone that was related to
this distribution zone. You cannot accept maintenance packages from the previous target zone to this
distribution zone using CA CSM.
2. Select Next.
You are prompted to set up the distribution zone.
Create a Distribution Zone
You can create a distribution zone that is related to the newly created target zone. The distribution zone parameters are
prepopulated with the values that are entered for the SMP/E environment. You can change data set allocation parameters.
You can specify a different SMP/E environment data set to be used for the new distribution zone.
You can also specify the same SMP/E environment data set as the one that you specified for the target zone. In that
case, the target and distribution zones share the SMP/E environment data set. The SMP/E environment data set
will be allocated using the parameters that you have defined when specifying the target zone.
Follow these steps:
1. On the Distribution Zone step, substep 2, review and specify the following parameters as applicable:
– Distribution Zone Name
Defines the name for the distribution zone.
– Create New CSI Data Set
Specifies that a new CSI data set will be created for the distribution zone.
– Data Set Name Prefix
Defines the prefix for the name of the distribution zone data set.
NOTE
This field is only enabled when you have the Create New CSI Data Set check box selected.
– Catalog
Defines the name of the SMP/E distribution zone catalog.
NOTE
This field is only enabled when you have the Create New CSI Data Set check box selected.
– Cross-Region
Identifies the cross-region sharing option for SMP/E data sets.
NOTE
This parameter is set to its default value, and you cannot edit it.
– Cross-System
Identifies the cross-system sharing option for SMP/E data sets.
NOTE
This parameter is set to its default value, and you cannot edit it.
– High-Level Qualifier
84
CA Easytrieve® Report Generator 11.6
Specifies the high-level qualifier (HLQ) for all distribution zone data sets that are allocated during installation.
Product packaging defines the low-level qualifiers (LLQ) that cannot be changed.
– DSN Type
Specifies the DSN type for allocating distribution zone data sets.
– SMS Parameters / Data Set Parameters
Specify if this distribution zone is to use SMS or data set parameters. Complete the applicable fields.
• Storage Class (SMS Parameters only)
Defines the SMS storage class for distribution zone data sets.
• Management Class (SMS Parameters only)
Defines the management class for distribution zone data sets.
• Data Class (SMS Parameters only)
Defines the data class for distribution zone data sets.
• VOLSER (Data Set Parameters only)
Defines the volume serial number on which to place data sets. The volume must have enough space for
allocating the data sets.
NOTE
This field is mandatory if you set Catalog to No.
• Unit (Data Set Parameters only)
Defines the type of the DASD on which to place data sets.
• Catalog (Data Set Parameters only)
Specifies if you want SMP/E data set to be cataloged.
NOTE
An information text area can appear at the bottom of the wizard. The area provides information that helps
you progress through the wizard. For example, if a field is highlighted (indicating an error), the information
text area identifies the error.
2. Select Next.
A list of the data sets to be created for the distribution zone appears.
Use an Existing Distribution Zone
You can use an existing distribution zone that is related to the existing target zone you selected, or with a new target zone.
The distribution zone parameters are prepopulated with the values that are entered for the SMP/E environment. You can
change data set allocation parameters.
NOTE
Using an existing distribution zone with a new target zone relates the existing distribution zone to the new target
zone. This action breaks the relationship from the previous target zone that was related to this distribution zone.
You cannot accept maintenance packages from the previous target zone to this distribution zone using CA CSM.
Follow these steps:
1. On the Distribution Zone step, substep 2, review the current distribution zone parameters and allocation parameters
for data sets that you want to add. Update as applicable:
NOTE
You cannot change the current SMP/E environment parameters.
– Distribution Zone Name
Identifies the name for the distribution zone.
– Data Set Name Prefix
Identifies the prefix for the name of the distribution zone data set.
– Catalog
85
CA Easytrieve® Report Generator 11.6
Identifies the name of the SMP/E distribution zone catalog.
– Cross-Region
Identifies the cross-region sharing option for SMP/E data sets.
– Cross-System
Identifies the cross-system sharing option for SMP/E data sets.
– High-Level Qualifier
Specifies the high-level qualifier (HLQ) for all distribution zone data sets that are allocated during installation.
Product packaging defines the low-level qualifiers (LLQ) that cannot be changed.
– DSN Type
Specifies the DSN type for allocating distribution zone data sets.
– SMS Parameters / Data Set Parameters
Specify if this distribution zone is to use SMS or data set parameters. Complete the applicable fields.
• Storage Class (SMS Parameters only)
Defines the SMS storage class for distribution zone data sets.
• Management Class (SMS Parameters only)
Defines the management class for distribution zone data sets.
• Data Class (SMS Parameters only)
Defines the data class for distribution zone data sets.
• VOLSER (Data Set Parameters only)
Defines the volume serial number on which to place data sets. The volume must have enough space for
allocating the data sets.
NOTE
This field is mandatory if you set Catalog to No.
• Unit (Data Set Parameters only)
Defines the type of the DASD on which to place data sets.
• Catalog (Data Set Parameters only)
Specifies if you want SMP/E data set to be cataloged.
NOTE
An information text area can appear at the bottom of the wizard. The area provides information that helps
you progress through the wizard. For example, if a field is highlighted (indicating an error), the information
text area identifies the error.
2. Select Next.
If there are any data sets to be created for the distribution zone, a list of data sets appears. If the list is empty, no new
data sets are going to be allocated.
Set Up Distribution Zone Parameters
When creating a distribution zone in the SMP/E environment where you want to install your product, specify distribution
zone parameters.
Follow these steps:
1. On the Distribution Zone step, substep 3, review the data set names if any appear. Select the Override link to
change the high-level qualifier of the data set name and the allocation parameters. Select OK.
2. (Optional) If any additional parameters appear, review the parameters that already have the default values assigned.
Edit the parameters if necessary and specify any missing parameters.
3. Select Next.
You see a summary of the installation task.
Start the Installation
After you complete setting up the SMP/E environment and its zones, you are ready to start the installation.
86
CA Easytrieve® Report Generator 11.6
To start the installation, review the summary on the Summary step, and select Install.
A dialog that shows the progress of the task opens. When the task completes, Select Show Results on the Progress tab
to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task status
later on the Tasks tab.
You completed the product installation. You can now start maintaining the installed products.
Maintain Products Using CA CSM
CA Chorus™ Software Manager (CA CSM) can help automate acquiring, installing, maintaining, deploying, and
configuring mainframe software. As a System Programmer, your responsibilities include maintaining products and
maintenance packages in your mainframe environment. CA CSM provides a product list that enables you to display
the list of licensed product maintenance packages and to download these packages. Also, you can manage external
maintenance packages that you acquired outside of CA CSM so that they can be applied using CA CSM.
This diagram shows the maintenance process.
1. (Optional) Configure automatic HOLDDATA download.
2. (Optional) Configure CA CSM to reject unneeded maintenance.
87
CA Easytrieve® Report Generator 11.6
3. Download product maintenance packages.
– (Optional) Configure CA CSM to perform automatic maintenance updates.
4. (Optional) Manage maintenance downloaded outside of CA CSM.
5. Receive maintenance.
6. (Optional) Reject maintenance.
7. Apply maintenance.
a. Apply CA RS maintenance.
b. (Optional) Apply FIXCAT maintenance.
8. (Optional) Restore maintenance.
9. Accept maintenance.
– (Optional) Accept maintenance in GROUPEXTEND mode.
After you complete this process, the maintenance packages for your products are accepted.
NOTE
You have deployed and configured a product across your enterprise. Now you are applying maintenance to
this product. Create a deployment and a configuration for this product to get this maintenance to your target
systems.
Configure Automatic HOLDDATA Download
You can configure CA CSM to download automatically the available HOLDDATA that it uses for each maintenance
installation. You then have current information about what maintenance packages are marked as PE (PTF in Error).
Follow these steps:
1. Select the Settings tab, and select the Software Catalog link under System Settings in the Settings section on the
left side.
2. In the HOLDDATA Settings section, select the Enable Automatic Updates checkbox.
3. Set up values for the following fields, and select Apply:
– Owner of Update Task
Specifies the TSO user ID under which the update task is run.
– Recurrence
Specifies how often the task recurs.
– Update Software Catalog Every number of Days
or
– Update Software Catalog On day of week Every number of Weeks
Specifies the frequency of downloading HOLDDATA to your software catalog, in days or weeks, depending on the
value of Recurrence.
NOTE
Imagine you set the recurrence for a specific number of days and you set the time that precedes the
current time. Then the first update occurs in the specified number of days at the specified time. For
example, on Monday at 10.30am, you set the number of days to 3 and time to 07.00. The first update then
occurs on the third day, Thursday, at 7.00am. When you set the time past the current time, the first update
occurs on the same day at the time set. For example, on Monday at 10.30am, you set the number of days
to 3 and time to 11.00. The first update then occurs on that Monday at 11.00am.
– System Time
Specifies the system time when an automatic update occurs. The system time reflects your CA CSM application
server time zone. The TZ parameter within Tomcat startup libraries defines the time zone. If the TZ parameter is not
defined, the CA CSM application server time zone defaults to GMT - Greenwich Mean Time.
NOTE
Local time is calculated based on the system time that you set.
88
CA Easytrieve® Report Generator 11.6
NOTE
To download available HOLDDATA to the software catalog immediately, select Update Immediately.
The automatic HOLDDATA download is configured.
Configure CA CSM to Reject Unneeded Maintenance from the SMP/E Environment
During the regular, FIXCAT, or CA RS maintenance wizard execution, CA CSM may receive maintenance. Some
maintenance packages may not be directly associated with the maintenance that you want to apply.
You can configure CA CSM to reject the maintenance that was received but not applied during the wizard execution.
• If you exit the wizard before the maintenance installation started, CA CSM rejects the maintenance that has been
received during the wizard execution. The SMP/E environment is restored to the state that it had before you started the
wizard.
• If you navigated through the wizard steps, started the maintenance installation task, and the task completed
successfully, CA CSM rejects the received but not applied maintenance that is not directly associated with the
maintenance that you have applied.
This process ensures that your SMP/E environments do not contain unneeded received maintenance.
Follow these steps:
1. Select the Settings tab, and select the Software Installation link under System Settings on the left side.
2. In the Maintenance Installation section, select the Reject Received Maintenance checkbox.
3. Select Apply.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
CA CSM is configured to reject unneeded maintenance.
Download Product Maintenance Packages
You can download maintenance packages for installed products through the Products tab. You can download:
• All maintenance packages for a product
• Only maintenance packages that have been released from the time the product release was updated last
NOTE
The information for HIPERs and new maintenance on the Software Status tab is based on the current
information in your software catalog. We recommend that you update the product list on a daily or weekly basis
to keep it current.
WARNING
You can also download maintenance using the CA SMP/E Internet Service Retrieval. This option uses the
IBM SMP/E RECEIVE ORDER command to download CA Mainframe product maintenance over the Internet,
by securely submitting an order for PTFs and HOLDDATA to a remote CA server. This service eliminates the
manual steps that are required to download maintenance from CA Support Online. The orders are fulfilled
based on the status of your SMP/E environments. Based on your order criteria, all PTFs and their requisites are
downloaded automatically and received to your system.
To use this download option, complete the procedures in CA SMP/E Internet Service Retrieval. After you set up
this service, you can use CA CSM to apply and accept your maintenance.
89
CA Easytrieve® Report Generator 11.6
Follow these steps:
1. Verify that your CA CSM login user name is associated with a registered user of CA Support online on the Software
Acquisition Settings page.
CA CSM uses the credentials to access CA Support.
2. Select the name of the product for which you want to download maintenance in the product list on the left side.
Maintenance information about the product appears in the Releases section on the right side.
3. For the product release for which you want to download maintenance, select the Actions drop-down list to the right of
the release. Complete one of the following steps:
– Select Update Product Release to download all maintenance packages for the product release.
– Select Get Latest Maintenance to download only maintenance packages that have been released from the time
the product release was updated last.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
The maintenance packages are downloaded.
Configure CA CSM to Perform Automatic Maintenance Updates
You can configure CA CSM to perform automatic maintenance updates (downloading and receiving maintenance) for
products that are installed in an SMP/E environment.
NOTE
For more information about automatic maintenance updates, see Configuring CA CSM to Perform Automatic
Maintenance Updates in the CA Chorus Software Manager documentation.
Manage Maintenance Downloaded Outside of CA CSM
Sometimes you acquire maintenance packages, such as unpublished maintenance, PTF, APARs, and USERMODs,
outside of CA CSM. For example, you are validating a test PTF released for a product. You can add information about
these maintenance packages to CA CSM from the Products tab.
Adding these maintenance packages to CA CSM provides you with a complete view of all the maintenance for a product
release. After a package is migrated, you can use CA CSM to apply the maintenance.
Usually, the maintenance is placed as a single package. However, some CA Technologies products still have older
aggregated maintenance packages that were released before December 31, 2013. An aggregated package is a file that
comprises several single maintenance packages (nested packages). When you add an aggregated package, CA CSM
inserts all the nested packages and the aggregated package itself. In the list of maintenance packages, the aggregated
package is marked with the CUMULATIVE type.
When you insert an aggregated package, CA CSM assigns a fix number to it. The fix number is unique and contains eight
characters. The first two characters are AM (for Aggregated Maintenance) and a unique six-digit number follows. The
number value increases by 1 with each added aggregated package.
NOTE
If the aggregated maintenance package has the same fix number as one of its nested packages, only the nested
package is added. The aggregated package itself is not available in the list of maintenance packages.
Follow these steps:
1. Select the Products tab, and select the product release for which the maintenance applies.
2. Select the Add External Maintenance button.
90
CA Easytrieve® Report Generator 11.6
3. Specify one of the following package types and package details:
– Data Set
Adds a maintenance package that is located in a z/OS data set with an LRECL of 80 and RECFM of FB.
– UNIX File
Adds a maintenance package that is located in a USS directory in binary mode.
– FTP File
Adds a maintenance package that is not published on CA Support. This option is intended for downloading a PTF
to validate it.
• FTP Host
Specifies the FTP server where the maintenance package is located. Select a server from the list, or provide
your FTP server host.
• FTP Port
Specifies the FTP port number for the FTP server.
• FTP Path
Defines the FTP path where the maintenance package is located. Start the path with a forward slash (/). Enter
only a forward slash to specify the root directory.
Example: /outgoing/
• Maintenance Name
Defines the maintenance package name.
Example: RO01111.bin
• User Name
Defines a valid user name to access the FTP location.
• Password
Defines a valid password to access the FTP location.
– Solution
Adds a published solution on Broadcom Support.
NOTE
To add several data sets or UNIX file packages from the same location, use masking.
4. Select OK.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
The maintenance package with the related information is saved in the CA CSM database.
NOTE
To see the added package, refresh the page.
View Aggregated Package Details
You can view which nested packages are included in the aggregated package. The information includes the fix number,
package type, and package description.
NOTE
Aggregated maintenance packages were discontinued December 31, 2013. However, some CA Technologies
products have aggregated maintenance packages that were released before this date.
Follow these steps:
1. Select the Products tab, and select the product release that has the aggregated package whose details you want to
view.
91
CA Easytrieve® Report Generator 11.6
2. Select the Fix # link for the aggregated package.
The Maintenance Package Details dialog opens.
3. Select the Nested Packages tab.
A list of nested packages that the aggregated package contains appears.
Receive Maintenance
After maintenance has been downloaded for a product, you can receive the maintenance to the global zone of an SMP/E
environment where the related products are installed. Once received, maintenance packages can be applied.
NOTE
While you work with an SMP/E environment, the environment is locked and other CA CSM users cannot perform
any action against it. When the task finishes, logging out from CA CSM, or a CA CSM session is inactive for
more than 10 minutes, the lock releases.
Follow these steps:
1. Select the SMP/E Environments tab, and select the SMP/E environment where you want to receive maintenance
packages.
2. Select Maintenance.
NOTE
If you do not see any maintenance package listed, verify that you have maintenance view criteria defined.
3. Select the maintenance packages that you want to receive, and select the Receive link.
The maintenance wizard opens to the Introduction step.
NOTE
If you select an SMP/E environment being used in CA CSM by another user, a notification message appears.
You are prevented from performing any actions on the SMP/E environment. Wait until the notification
message disappears and the SMP/E environment becomes available, or select Cancel to select another
SMP/E environment.
4. Review the information about the receiving, and select Next.
5. Review and adjust the receive list selections as required, and select Next.
6. Review the summary, and select Receive.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
The maintenance packages are received to the SMP/E environment global zone.
Reject Maintenance
You can reject a received maintenance package. Information about the maintenance package is removed from the SMP/E
environment global zone.
NOTE
While you work with an SMP/E environment, the environment is locked and other CA CSM users cannot perform
any action against it. When the task finishes, logging out from CA CSM, or a CA CSM session is inactive for
more than 10 minutes, the lock releases.
Follow these steps:
1. Select the SMP/E Environments tab, and select the SMP/E environment from which you want to reject maintenance.
2. Select Maintenance.
92
CA Easytrieve® Report Generator 11.6
NOTE
If you do not see any maintenance package listed, verify that you have maintenance view criteria defined.
3. Select the maintenance packages that you want to reject, and select the Reject link.
NOTE
You can filter out only received packages.
The maintenance wizard opens to the Introduction step.
NOTE
If you select an SMP/E environment being used in CA CSM by another user, a notification message appears.
You are prevented from performing any actions on the SMP/E environment. Wait until the notification
message disappears and the SMP/E environment becomes available, or select Cancel to select another
SMP/E environment.
4. Review the information about the rejection, and select Next.
5. Review and adjust the rejected list selections as required, and select Next.
6. Review the summary, and select Reject.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
The maintenance packages are rejected. Information about the maintenance packages is removed from the SMP/E
environment global zone.
Apply Maintenance
After maintenance has been downloaded for a product, you can apply the maintenance to products that are installed in an
SMP/E environment.
As an option, CA CSM lets you verify that the maintenance packages can be applied to the selected target zones without
applying the packages.
NOTE
While you work with an SMP/E environment, the SMP/E environment is locked and other CA CSM users cannot
perform any action against it. When the task finishes, logging out from CA CSM, or a CA CSM session is
inactive for more than 10 minutes, the lock releases.
Follow these steps:
1. Select the SMP/E Environments tab, and select the SMP/E environment whose products you want to apply
maintenance to.
2. Select Maintenance.
NOTE
If you do not see any maintenance package listed, verify that you have maintenance view criteria defined.
3. Select the maintenance packages that you want to apply, and select the Apply link.
NOTE
If you select an SMP/E environment being used in CA CSM by another user, a notification message appears.
You are prevented from performing any actions on the SMP/E environment. Wait until the notification
message disappears and the SMP/E environment becomes available, or select Cancel to select another
SMP/E environment.
4. Follow the instructions on the wizard to navigate through the wizard steps.
5. From the Summary step, review the summary, and select Check and Apply.
93
CA Easytrieve® Report Generator 11.6
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
CA CSM verifies and applies the maintenance packages to the selected target zones.
If the task fails, navigate to the Tasks tab and review SMPOUT in the task output to identify and correct problems. Rerun
the wizard.
You have completed acquiring and applying maintenance. You can accept the applied maintenance (except USERMODs)
from the SMP/E Environments, Maintenance tab.
USERMODs
A product USERMOD can be provided as a published maintenance package downloaded during the Update Product
process. When CA CSM downloads a package including a ++USERMOD statement, it is loaded under the product with a
USERMOD type. You can install these packages using CA CSM but cannot accept them because they are not intended to
be permanent.
You can create a USERMOD manually, or we can provide an unpublished maintenance package as a USERMOD. In this
case, the USERMOD file, which contains the ++USERMOD statement and the body of the USERMOD, must be managed
as an externally downloaded package.
Unresolved HOLDDATA Processing
When you apply maintenance, review and process any unresolved HOLDDATA for the applied maintenance and its
prerequisites. The maintenance wizard displays all unresolved HOLDDATA and lets you review the HOLDDATA and
details about the HELD maintenance. You can then bypass the HOLDDATA or exclude the HELD maintenance. CA CSM
determines unresolved HOLDDATA by running SMP/E APPLY GROUP/GROUPEXTEND CHECK.
In the maintenance wizard, you can perform the following actions:
• Select HOLDDATA (HOLDDATA TYPE, REASON, or maintenance) to bypass it.
• Leave HOLDDATA unselected to exclude it. If you do not select a HOLDDATA entry checkbox, CA CSM excludes the
HELD maintenance from the processing.
If you exclude at least one HELD maintenance package, CA CSM runs an appropriate SMP/E APPLY GROUP/
GROUPEXTEND CHECK command to verify the processing. CA CSM verifies whether other maintenance requires the
excluded maintenance. If so, CA CSM also excludes it from processing.
If the SMP/E APPLY GROUP/GROUPEXTEND CHECK command discovers further unresolved HOLDDATA, you are
notified about all unresolved HOLDDATA again. Select what HOLDDATA to bypass and what HELD maintenance to
exclude.
This iterative process repeats until all HOLDDATA is resolved or bypassed. You can then proceed to the next step.
A list of maintenance packages that are excluded during the processing of unresolved HOLDDATA is displayed in the
Summary step.
Apply CA RS Maintenance
CA CSM lets you track and apply CA Recommended Services (CA RS) maintenance for your products.
CA Recommended Service (CA RS) is a set of maintenance packages that have been tested in a mainframe integrated
system test environment. We recommend that you install CA RS maintenance to keep your products current. CA
Technologies releases CA RS maintenance regularly. The release date determines the CA RS maintenance level.
94
CA Easytrieve® Report Generator 11.6
To learn about new CA RS maintenance available, download the CA RS files that are listed for published CA RS
maintenance. You can configure CA CSM to download CA RS files automatically, or add CARS files manually.
Based on information in CA RS files, you can filter CA RS maintenance in the SMP/E Environments, Maintenance section.
You can also select the packages that are applicable for within the CA RS level that you want to install.
You can apply particular CA RS maintenance packages. You can update all products in an SMP/E environment.
NOTE
A CA RS file can list a maintenance package that the HOLDDATA marked as PE (PTF in Error). The CA RS file
can also reflect a corrective maintenance package for this PE that is not listed in this CA RS file. This situation
can occur if a maintenance package is found in error after the CA RS file is published. The CA RS processing
continues as expected, and the maintenance package that is marked as PE is not applied. However, the CA RS
level for the product is not updated to the current level until you apply the corrective maintenance package to the
SMP/E environment.
Configure Automatic CA RS File Download
You can configure CA CSM to download available CA RS files automatically. After download, the CA RS files are stored in
a USS directory under the software catalog.
Follow these steps:
1. Select the Settings tab, and select the Software Catalog link under System Settings in the Settings section on the
left side.
2. In the CA RS Settings section, select the Enable Automatic Updates checkbox.
3. Set up values for the following fields, and select Apply:
– Owner of Update Task
Specifies the TSO user ID under which the update task is run.
– Recurrence
Specifies how often the task recurs.
– Update Software Catalog Every number of Days
or
– Update Software Catalog On day of week Every number of Weeks
Specifies the frequency of downloading CA RS files to your software catalog, in days or weeks, depending on the
value of Recurrence.
NOTE
Imagine you set the recurrence for a specific number of days and you set the time that precedes the
current time. Then the first update occurs in the specified number of days at the specified time. For
example, on Monday at 10.30am, you set the number of days to 3 and time to 07.00. The first update then
occurs on the third day, Thursday, at 7.00am. When you set the time past the current time, the first update
occurs on the same day at the time set. For example, on Monday at 10.30am, you set the number of days
to 3 and time to 11.00. The first update then occurs on that Monday at 11.00am.
– System Time
Specifies the system time when an automatic update occurs. The system time reflects your CA CSM application
server time zone. The TZ parameter within Tomcat startup libraries defines the time zone. If the TZ parameter is not
defined, the CA CSM application server time zone defaults to GMT - Greenwich Mean Time.
NOTE
Local time is calculated based on the system time that you set.
NOTE
To download available CA RS files to the software catalog immediately, select Update Immediately.
The automatic CA RS download is configured.
95
CA Easytrieve® Report Generator 11.6
Add a CA RS File
If you cannot automatically download available CA RS files, add them to the software catalog manually. Use the Add
CA RS File link. The CA RS files added manually are stored in the same USS directory as other CA RS files.
Follow these steps:
1. Download the CA RS file using FTP from the CA Technologies file server directly to your USS directory.
a. Connect to the FTP site at the following location:
ftp://ftp.broadcom.com
b. Log in to ftp.broadcom.com as follows:
user name: anonymous
password: your-email-address
c. Change to the following directory:
/pub/ASSIGNS
d. Change your download mode to ASCII.
e. Download the CA RS file. CA RS files appear in the format:
CARyymm.TXT
2. In the CA CSM web-based interface, select the Products tab, and select the Add CA RS File link in the Actions section
on the left side.
3. Specify the USS path to the CA RS file you want to add, and select OK.
Information about the CA RS file is saved in the CA CSM Software Catalog USS database.
Apply CA RS Maintenance to an SMP/E Environment
You can upgrade products that are installed in an SMP/E environment to a specific CA RS level. During processing, CA
CSM verifies that maintenance packages associated with the selected CA RS level can be applied to the products, and
then applies the packages.
As an option, CA CSM lets you verify that the maintenance packages can be applied to the selected target zones without
applying the packages.
NOTE
While you work with an SMP/E environment, the environment is locked and other CA CSM users cannot perform
any action against it. When the task finishes, logging out from CA CSM, or a CA CSM session is inactive for
more than 10 minutes, the lock releases.
Follow these steps:
1. Select the SMP/E Environments tab.
2. From the list on the right, locate the SMP/E environment whose products you want to upgrade the CA RS level for.
Select the Actions drop-down list to the right of the SMP/E environment, and select Upgrade CA RS Level.
NOTE
If you select an SMP/E environment being used in CA CSM by another user, a notification message appears.
You are prevented from performing any actions on the SMP/E environment. Wait until the notification
message disappears and the SMP/E environment becomes available, or select Cancel to select another
SMP/E environment.
3. Follow the instructions on the wizard to navigate through the wizard steps.
4. From the Summary step, review the summary and select Check and Apply.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
96
CA Easytrieve® Report Generator 11.6
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
CA CSM verifies and applies the CA RS maintenance packages to the selected target zones.
If the task fails, navigate to the Tasks tab and review SMPOUT in the task output to identify and correct problems. Rerun
the wizard.
You can accept the applied maintenance (except USERMODs) from the SMP/E Environments, Maintenance tab.
Apply FIXCAT Maintenance
CA CSM lets you select and apply maintenance for your products according to FIXCAT.
FIXCAT (fix category) associates a maintenance package to one or more categories of PTFs (for example, installation,
function, z/OS version, or communication).
FIXCAT data is provided in the same file as error HOLDDATA. Error HOLDDATA contains FIXCAT HOLDDATA statements
that assign a maintenance package to a category. Select a category, and CA CSM determines and applies associated
maintenance packages to the selected products installed in an SMP/E environment.
Masking Maintenance Categories
When you select maintenance categories in the wizard, you can use masking.
Use an asterisk (*), or a percent sign (%), or both to specify naming masks. An asterisk substitutes for any number of
symbols. A percent sign substitutes for one symbol.
For example:
• CA.System.z/OS.*
Selects all the categories whose names start with CA.System.z/OS.
• CA.System.z/OS.%% S
Selects all the categories under CA.System.z/OS whose last segment consists of two symbols.
Apply FIXCAT Maintenance
You can select and apply maintenance for your products based on FIXCAT using CA CSM.
As an option, CA CSM lets you verify that the maintenance packages can be applied to the selected target zones without
applying the packages.
NOTE
While you work with an SMP/E environment, the environment is locked and other CA CSM users cannot perform
any action against it. When the task finishes, logging out from CA CSM, or a CA CSM session is inactive for
more than 10 minutes, the lock releases.
Follow these steps:
1. Select the SMP/E Environments tab.
2. From the list on the right, locate the SMP/E environment whose products you want to apply FIXCAT
maintenance. Select the Actions drop-down list to the right of the SMP/E environment, and select Update Using Fix
Categories.
NOTE
If you select an SMP/E environment being used in CA CSM by another user, a notification message appears.
You are prevented from performing any actions on the SMP/E environment. Wait until the notification
97
CA Easytrieve® Report Generator 11.6
message disappears and the SMP/E environment becomes available, or select Cancel to select another
SMP/E environment.
3. Follow the instructions on the wizard to navigate through the wizard steps.
4. From the Summary step, review the summary, and select Check and Apply.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
CA CSM verifies and applies the FIXCAT maintenance packages to the selected target zones.
If the task fails, navigate to the Tasks tab and review SMPOUT in the task output to identify and correct problems. Rerun
the wizard.
You can accept the applied maintenance (except USERMODs) from the SMP/E Environments, Maintenance tab.
Restore Maintenance
You can restore (back out) an applied maintenance package (but not an accepted maintenance package).
NOTE
While you work with an SMP/E environment, the environment is locked and other CA CSM users cannot perform
any action against it. When the task finishes, logging out from CA CSM, or a CA CSM session is inactive for
more than 10 minutes, the lock releases.
Follow these steps:
1. Select the SMP/E Environments tab, and select the SMP/E environment from which you want to restore
maintenance.
2. Select Maintenance.
NOTE
If you do not see any maintenance package listed, verify that you have maintenance view criteria defined.
3. Select the maintenance packages that you want to restore, and select the Restore link.
NOTE
You can filter out only applied packages.
NOTE
If you select an SMP/E environment being used in CA CSM by another user, a notification message appears.
You are prevented from performing any actions on the SMP/E environment. Wait until the notification
message disappears and the SMP/E environment becomes available, or select Cancel to select another
SMP/E environment.
4. Review the information about the restoring, and select Next.
5. Review and adjust the list selections as required. Select Zones to review and adjust the zones where the maintenance
is restored from. You can only perform maintenance actions on zones you select here. Select OK to confirm the
selection and return to the wizard, and select Next.
6. Review the prerequisites if they exist, and select Next. CA CSM restores these prerequisites as part of the
maintenance restoring process.
7. Review the summary, and select Restore.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
98
CA Easytrieve® Report Generator 11.6
The maintenance packages are restored.
Accept Maintenance
After maintenance has been applied, you can accept the maintenance for products that are installed in an SMP/E
environment. You cannot accept USERMODs.
Use this procedure to accept the maintenance in GROUP mode.
WARNING
Before you start, update the HOLDDATA in your software catalog. To do so, select Update HOLDDATA in the
Actions section on the Software Catalog page. You can also set up the automatic HOLDDATA download as
described previously in this article.
NOTE
While you work with an SMP/E environment, the environment is locked and other CA CSM users cannot perform
any action against it. When the task finishes, logging out from CA CSM, or a CA CSM session is inactive for
more than 10 minutes, the lock releases.
Follow these steps:
1. Select the SMP/E Environments tab, and select the SMP/E environment whose products you want to accept
maintenance.
2. Select Maintenance.
NOTE
If you do not see any maintenance package listed, verify that you have maintenance view criteria defined.
3. Select the maintenance packages that you want to accept, and select the Accept link.
NOTE
If you select an SMP/E environment being used in CA CSM by another user, a notification message appears.
You are prevented from performing any actions on the SMP/E environment. Wait until the notification
message disappears and the SMP/E environment becomes available, or select Cancel to select another
SMP/E environment.
4. Review the information about the maintenance, and select Next.
5. Review and adjust the accept list selections as required. Select Zones to review and adjust the zones where the
maintenance is accepted. You can only perform maintenance actions on zones you select here. Select OK to confirm
the selection and return to the wizard, and select Next.
6. Select the installation mode for the selected maintenance, and select Next.
7. Perform one of the following actions to address prerequisites:
– If no prerequisites exist, select Next. A list of HOLDDATA appears.
– If prerequisites exist and are available, review them, and Select Next. A list of HOLDDATA appears. The
prerequisites are accepted as part of the process.
– If a prerequisite is not available, the wizard cannot continue. Select Cancel to exit the wizard. Acquire the
prerequisite and restart the process.
8. Review HOLDDATA entries, if they exist. Select Export Table to open all HOLDDATA information for all selected
maintenance in a separate browser window. Selecting Export Table is similar to running the LIST SYSMODS
HOLDDATA command within your SMP/E environment.
9. Select Next.
SMP/E work DDDEFs of SMPWRKx and SYSUTx, with their allocation parameters, are listed.
NOTE
For more information about SMPWRKx and SYSUTx data sets, see IBM SMP/E for z/OS Reference.
10. Review the work DDDEF allocation parameters, and edit them, if necessary, to verify that sufficient space is allocated
for them during the maintenance acceptance:
99
CA Easytrieve® Report Generator 11.6
NOTE
Changes in the allocation parameters apply to the current maintenance processing only.
1. Select Override for a DDDEF to edit its allocation parameters.
A pop-up window opens.
2. Make the necessary changes, and select OK to confirm.
The pop-up window closes, and the DDDEF entry is selected in the list indicating that the allocation
parameters have been overridden.
To update allocation parameters for the DDDEFs automatically, select Resolve Overrides. CA CSM provides
values for all DDDEFs based on the total size of the selected maintenance packages being accepted. All
DDDEF entries are selected in the list indicating that the allocation parameters have been overridden.
• To cancel a parameter update for any DDDEF, clear its checkbox.
• To edit the allocation parameters for a DDDEF after you automatically updated them using the Resolve
Overrides button, select Override. Make the necessary changes. Select OK to confirm and return to the
wizard.
11. (Optional) Select View SMP/E Work DDDEFs to review SMP/E work DDDEF and their allocation parameters for the
selected SMP/E environment zones. Select Close to return to the wizard.
NOTE
Sometimes, the allocation parameters differ from the allocation parameters that you obtained using the
Resolve Overrides button.
Select Next.
12. Review the summary, and select Accept.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
The maintenance packages are accepted.
Accept Maintenance in GROUPEXTEND Mode
CA CSM lets you invoke the SMP/E utility with the GROUPEXTEND option enabled for accepting maintenance.
NOTE
For more information about GROUP and GROUPEXTEND modes, see IBM SMP/E for z/OS Commands.
When you accept maintenance in GROUPEXTEND mode, the following installation modes are available:
• Accept Check
Checks if the maintenance can be accepted to the selected SMP/E environment in GROUPEXTEND mode.
• Accept
Accepts the maintenance to the selected SMP/E environment in GROUPEXTEND mode.
• Accept Check and Accept
Checks if the maintenance can be accepted to the selected SMP/E environment in GROUPEXTEND mode. Then
accepts it if possible.
For the GROUPEXTEND option, CA CSM does not automatically receive and display maintenance or HOLDDATA
prerequisites that must be bypassed when accepting the maintenance. Accept check mode lets you check if any
prerequisites or HOLDDATA exist and report them in the task output.
100
CA Easytrieve® Report Generator 11.6
How Maintenance in GROUPEXTEND Mode Works
We recommend that you accept maintenance in GROUPEXTEND mode in the following sequence:
1. Apply all maintenance packages that you want to include by the GROUPEXTEND option.
2. Run the maintenance in Accept check mode.
– If the task fails, review SMPOUT in the task output. Review if there are missing (not applied) maintenance
packages or HOLDDATA that must be resolved or bypassed.
– If the task succeeds, review SMPRPT in the task output. Review what maintenance packages were found and
accepted.
3. Run the maintenance in Accept mode. Specify the maintenance packages that you want to exclude and HOLDDATA
that you want to bypass, if any exist.
The followings options are available for bypassing HOLDDATA:
– HOLDSYSTEM
– HOLDCLASS
– HOLDERROR
– HOLDUSER
NOTE
For more information about the BYPASS options, see IBM SMP/E for z/OS Commands.
You can run the maintenance in Accept mode in the same CA CSM session after Accept check mode is completed. The
values that you entered for Accept check mode are then prepopulated on the wizard dialogs.
Accept Maintenance in GROUPEXTEND Mode
You can accept maintenance (except USERMODs) with the GROUPEXTEND option enabled.
NOTE
While you work with an SMP/E environment, the environment is locked and other CA CSM users cannot perform
any action against it. When the task finishes, logging out from CA CSM, or a CA CSM session is inactive for
more than 10 minutes, the lock releases.
Follow these steps:
1. Select the SMP/E Environments tab, and select the SMP/E environment holding the maintenance packages that you
want to accept in GROUPEXTEND mode.
2. Select Maintenance.
Maintenance packages available for the products are listed.
NOTE
If you do not see any maintenance package listed, verify that you have maintenance view criteria defined.
3. Select the maintenance packages that you want to accept in GROUPEXTEND mode, and select the Accept
GROUPEXTEND link.
NOTE
If you select an SMP/E environment being used in CA CSM by another user, a notification message appears.
You are prevented from performing any actions on the SMP/E environment. Wait until the notification
message disappears and the SMP/E environment becomes available, or select Cancel to select another
SMP/E environment.
4. Review the information about the maintenance, and select Next.
The packages that you want to accept are listed.
NOTE
Select a link in the Status column for a maintenance package, if available, to review a list of zones. The
zones indicate where the maintenance package is already received, applied, or accepted. Select Close to
return to the wizard.
101
CA Easytrieve® Report Generator 11.6
5. Review the packages, and select Next.
WARNING
For the GROUPEXTEND option, CA CSM does not automatically receive and display maintenance or
HOLDDATA prerequisites that must be bypassed when accepting the maintenance. Accept check mode lets
you review if any prerequisites or HOLDDATA exist and report them in the task output. We recommend that
you run the maintenance in Accept check mode first.
6. Read the information that is displayed on this tab, and select Next.
The installation options appear.
7. Specify installation options as follows, and select Next:
a. Select the installation mode for the selected maintenance.
b. Review the GROUPEXTEND options and select the ones that you want to apply to the maintenance:
• NOAPARS
Excludes APARs that resolve error reason ID.
• NOUSERMODS
Exclude USERMODs that resolve error reason ID.
c. (Optional) Enter maintenance packages that you want to exclude in the Excluded SYSMODs field. You can enter
several packages, separate them by a comma.
The Bypass HOLDDATA step of the wizard appears.
8. (Optional) Enter the BYPASS options for the HOLDDATA that you want to bypass during the maintenance installation.
You can enter several BYPASS options, separate them by a comma.
9. Select Next.
10. Review the summary, and select Accept GROUPEXTEND.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task
status later on the Tasks tab.
• If you run the maintenance installation in Accept check mode and the task succeeds, review SMPRPT in
the task output. Review what maintenance packages were found and accepted.
• If you run the maintenance installation in Accept check mode and the task fails, review SMPOUT in the
task output. Review if there are missing (not accepted) maintenance packages or HOLDDATA that must
be resolved or bypassed.
You completed maintaining products with CA CSM.
Configure Your Product Using CA CSM
CA Chorus™ Software Manager (CA CSM) can help automate acquiring, installing, maintaining, deploying, and
configuring mainframe software. As a system programmer, your responsibilities include configuring products using CA
CSM. A configuration is a CA CSM object that you create to tailor your installed software or CA CSM deployed software.
Configuration makes your software usable in your environment. A configuration contains the profiles, variables, and
resources specific to your environment.
This diagram explains the configuration process.
102
CA Easytrieve® Report Generator 11.6
103
CA Easytrieve® Report Generator 11.6
– If you configure a product from an SMP/E environment, you can only configure it on a staging system.
– If you configure a product from a configurable CA CSM deployment, you can configure it on a staging system or a
nonstaging system.
2. Create a configuration.
3. Build the configuration.
4. (Optional) Validate the configuration.
NOTE
Although validation is optional, we recommend that you validate the configuration before implementation.
• If validation fails, edit the configuration and repeat the process from step 3.
• If validation succeeded, implement the configuration.
5. (Staging systems only) Activate the configuration.
The product configuration process completes.
NOTE
Perform any manual configuration steps outside of CA CSM now if needed.
For more information about configuring products, see the CA CSM online help.
Create a Configuration
You can create a configuration for a product that is installed in an SMP/E environment, or a product from an existing
configurable CA CSM deployment.
The configuration wizard consists of several steps that let you set up your configuration as you prepare to implement
it. When you go through the wizard, you define a set of properties for your configuration. For example, you define the
product that you want to configure and the system you are targeting for the configuration. Optionally, you can select to
import product configuration settings and variable values from a previous configuration for the selected product.
Each product configuration includes various settings, such as:
• The functions and options for the product
• Settings and preferences that are associated with the specified target system
• Resources for the product
NOTE
To avoid a conflict of resources between two or more configurations of a product, SCS manages the
resources that are associated with previously defined configurations. To resolve conflicting (not unique)
resources in your configuration, perform one of the following actions:
• Change the appropriate target setting to create a unique resource name.
• Delete the older configuration containing the existing resource name and release the conflicting resource.
If you import values from another configuration, you can optionally delete the configuration that you are importing the
values from to avoid conflicts.
Follow these steps:
1. From the Configurations tab, select Create Configuration from the Actions section.
The configuration wizard opens to step 1.
NOTE
You can also start the configuration wizard from the following locations:
• The SMP/E Environments tab - for a product in an SMP/E environment.
• The Deployments tab - for a product from an existing configurable CA CSM deployment. Starting the
configuration wizard from the Deployments tab opens it to step 2.
104
CA Easytrieve® Report Generator 11.6
2. Follow the instructions on the wizard to navigate through the wizard steps.
3. From the Review and Build step, review the configuration summary.
You are ready to build the configuration.
NOTE
If you do not want to build configuration now, save the configuration and close the wizard. You can build it
later.
Configuring to a Staging System
Configuring a product that targets a staging system implies the DASD resources that are created as part of a product
implementation will be local to the CA CSM driving system. The CA CSM driving system is the system where the CA
CSM is running.
Configurations that you create for a staging system are implemented in the following phases:
1. CA CSM creates and customizes the product run-time data sets on the CA CSM driving system.
When a configuration targets a staging system, the configuration wizard provides a set of catalog preference variables
as part of the target settings. You can determine whether the customized run-time data sets that are created in the first
phase should be cataloged in the catalog that is associated with the CA CSM driving system. This setting is default.
If you decide not to catalog the data sets to the CA CSM driving system catalog, you can optionally specify the name
of a user catalog where the customized run-time data sets are to be cataloged. If you do not provide the user catalog
name, the data sets are uncataloged.
NOTE
The support for creating uncataloged run-time data sets assumes that the following statements are true:
• The volume that is specified for the run-time data sets is not SMS-managed.
• The rules that are established at your site allow the run-time data sets to be created as uncataloged data
sets.
When an optional user catalog name is specified, you can specify optional alternate, or indirect, system residence
volumes (SYSRES). By default, no SYSRES preference is specified.
– If no SYSRES preference is specified, the user catalog entries are created with the actual volume serial numbers of
the run-time data sets.
– If a SYSRES preference is specified, the user catalog entries are created with an indirect reference to a system
residence volume (or its logical extensions). Specifying a SYSRES preference lets you change the volume serial
numbers of the system residence volume (or its logical extensions) later without having to recatalog the run-time
data sets on those volumes.
NOTE
For more information about non-VSAM user catalog entries and indirect volume serial references,
see the description of the DEFINE NONVSAM command in IBM DFSMS Access Method Services for
Catalogs (SC26-7394).
2. You make the data sets accessible and activate the configuration.
Systems that do not share DASD with the CA CSM driving system do not have access to the run-time data sets. For
those systems, move the run-time data sets to DASD that is accessible to the remote system. For moving the data
sets, use a method that is appropriate for your site and environment. CA CSM does not endorse a specific technique
or support transmitting the customized run-time data sets that are created when configuring a product to a staging
system.
After making the data sets accessible, activate the configuration.
Build the Configuration
You can build a previously saved configuration, or you can rebuild your configuration (for example, if there is a problem
with the build).
105
CA Easytrieve® Report Generator 11.6
You can only build configurations with a status of Under Construction (8) (resume the configuration first), or Build failed.
Follow these steps:
Perform one of the following actions:
• If you are on the Review and Build step of the wizard, select Build.
• If your configuration is saved in a step before the Review and Build step, resume the configuration from
the Configurations tab. Follow the instructions on the wizard to navigate through the wizard steps. From the Review
and Build step, select Build.
• If your configuration is in Build failed status, select the Actions drop-down list to the right of the configuration, and
select Build.
Optionally, you can edit the configuration before you build it again. Navigate to the Review and Build step of the
wizard, and select Build.
A dialog that shows the progress of the task opens. When the task completes, select Show Results on the Progress tab
to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide to exit the dialog and view the task status
later on the Tasks tab.
The configuration is built.
Built configurations are ready to be optionally validated or implemented. Before you start implementing a configuration,
you can still edit the configuration.
You can build your configuration again later (for example, if there is a problem with the build).
Validate the Configuration
Before you implement a configuration, you can validate it. Validation verifies access to resources that are going to be
utilized when you implement the configuration.
NOTE
Although validation is optional, we recommend that you validate the configuration before implementation.
You can only validate configurations with a status of Build completed, Validated, Validation error, Implementation stopped,
or Implementation error.
While validation of a configuration is in progress, do not use the configuration data sets that are outside of CA CSM. Doing
so helps avoid data set contention between the CA CSM validate processing and data sets being accessed outside of CA
CSM.
Follow these steps:
1. Select the Configurations tab and locate the configuration that you want to validate.
2. Select the Actions drop-down list to the right of the configuration, and select Validate.
The validation dialog opens. This dialog contains status information and a table of numbered configuration steps.
The validation process is started and continues until it has successfully completed or fails. The steps in this dialog
automatically update as operation data changes.
3. Review the operation steps. You can perform the following actions:
– Select the link of a step name to display information about the actions that are associated with this step.
– Select the icon in the Text column to see details about the processing that is associated with this step. If this step
is manual, you can use this information to perform the step manually. Select Show Details to open a detailed
summary for all steps in the configuration.
– For the steps with prerequisites, hold the mouse over the icon in the Prereq column to review prerequisites details.
When the validation is completed, a message appears confirming that the validation succeeded or failed.
106
CA Easytrieve® Report Generator 11.6
NOTE
While a validation is in progress, you can perform other work. Select Hide to exit the dialog without stopping
the validation process. Select the configuration status link to bring back the validation dialog while the
validation is still in progress, or view the status of the validation task later from the Tasks tab.
After the validation finishes and before you start implementing, you can still edit the configuration.
After a validation has finished successfully for a configuration on a staging system, review the activation instructions,
if any. Select Activation Instructions from the validation dialog. Doing so opens the required steps that you will have to
complete after you implement the configuration to activate this configuration.
Edit the Configuration
You can edit configurations that you have previously created and built. You can edit a configuration if the build fails, or
when validation fails because of an errant value.
You can only edit configurations in a status of Build complete, Build failed, Validated, or Validation error.
You can only edit a configuration that has not started implementing yet. After a configuration has started implementing,
you cannot edit it.
You can only edit one configuration at a time.
Follow these steps:
1. Select the Configurations tab and locate the configuration that you want to edit.
NOTE
Select the Status column to sort by status and identify all configurations that you can edit.
2. Select the Actions drop-down list to the right of the configuration, and select Edit.
3. Change data on this step as needed, and navigate and make edits to the remaining steps in the wizard.
Implement the Configuration
When you start the implementation, CA CSM evaluates the defined steps and determines what steps to execute. The
selected steps are presented as a list. Release them so that they can be eligible to execute after their prerequisite steps
have successfully completed.
NOTE
Validation and implementation of a configuration may require exclusive access to data sets that the
configuration specifies. Using data sets outside of CA CSM, such as ISPF edit and browse data sets, can
introduce data set contention. Data set contention can result in validation and implementation errors. Therefore,
while validation or implementation of a configuration is in progress, do not use the configuration data sets that
are outside of CA CSM.
Implementation completes the configuration process for configurations on a nonstaging system. For configurations on
staging systems, you may be required to perform extra steps to activate your configuration.
Implementation executes on the target system, applying the variables, resources, and operations that are defined in the
configuration.
You can only implement configurations with a status of Build completed, Validated, Validation error, Implementation
stopped, or Implementation error.
Follow these steps:
1. Select the Configurations tab and locate the configuration that you want to implement.
2. Select the Actions drop-down list to the right of the configuration, and select Implement.
107
CA Easytrieve® Report Generator 11.6
The Implementation dialog opens. This dialog contains status information, and a table of numbered operation steps.
3. Review the operation steps. You can perform the following actions:
– Select the link of a step name to display information about the actions that are associated with this step.
– Select the icon in the Text column to see details about the processing that is associated with this step. If this step is
manual, you can use this information to perform the step manually.
– For the steps that have prerequisites, hold the mouse over the icon in the Prereq column to see details about the
prerequisites.
4. (Optional) Select one or more steps and perform the following actions using the action links:
– Set Automatic
Changes the mode of the selected manual steps so that CA CSM automatically performs them when they are
released and all prerequisites are satisfied.
You cannot change the mode of external steps. CA CSM cannot perform them automatically.
– Set Manual
Changes the mode of the selected automatic steps so that they become manual steps that you must perform
outside of CA CSM.
– Release
Releases the selected steps. The steps become eligible for execution when all prerequisite steps are complete.
– Bypass
Skips the selected steps. These steps are not released when you select Release All. If the bypassed steps are
prerequisites for other steps, the prerequisites are considered satisfied. The dependent steps are executed when
they are released.
5. For manual or external steps, select the Actions drop-down list to the right of a step, and select Confirm.
The step is confirmed as completed successfully. Any prerequisites that other steps within the implementation define
are satisfied.
6. Perform one of the following actions:
– Select Release All to release all steps at once and execute them. However, steps do not execute if they have
prerequisite steps that have not completed. Perform and confirm manual and external steps.
– Select Release Next to release and execute the next step in sequence. However, the step does not execute if
it has prerequisite steps that have not completed. Select Release Next for each subsequent step, and confirm
manual and external steps.
The implementation process is started and continues until it has successfully completed, is stopped manually, or fails.
The steps in this dialog automatically update as operation data changes.
NOTE
While an implementation is in progress, you can perform other work. Select Hide to exit the dialog without
stopping the implementation process. Select the configuration status link to bring back the implementation
dialog while the implementation is still in progress, or view the status of the implementation task later from
the Tasks tab.
You can select Stop to stop the implementation process. Non-executing steps are not started. You can start another
run of the implementation from the Configurations tab by selecting the configuration and selecting Implement.
When the implementation is completed, a message appears confirming that the implementation succeeded or failed.
7. (For successful configurations on staging systems) Select Activation Instructions to open the required steps that you
must complete next to activate this configuration.
NOTE
If the configuration fails, address implementation failures.
View Step and Action Details
The validation and implementation dialogs contain links that let you drill down for more information about steps and
actions that are associated with each step.
108
CA Easytrieve® Report Generator 11.6
Follow these steps:
1. On the Validate Configuration or Implement Configuration dialog, select the link for the step you want to view
details.
An Actions dialog opens. The dialog contains the actions that are associated with this step as links if more information
is available. This dialog contains the following columns:
– Name
Identifies the name of an action.
– Type
Identifies one of the following types for this action:
• Action
This type is an actual action.
• Backup
This action performs a backup operation if the action is recoverable.
• Commit
This action makes the changes from previous actions permanent.
• Rollback
This action reverts the changes from previous actions.
– Group
Identifies one of the following groups that are associated with this action:
• Operation action
Describes the set of actions that perform the function of the operation.
• Preop recovery
Describes the set of actions to be performed before all other actions in the operation.
• Postop recovery success
Describes the set of actions to be performed if all actions complete successfully.
• Postop recovery failure
Describes the set of actions to be performed if any action completes unsuccessfully.
• Cleanup
Describes the set of actions to be performed after all other actions in the operation.
– SRVC-CC
Identifies the CA CSM services completion code for this action.
NOTE
This code is an internal CA CSM completion code that is returned from the executed service in the SCS
address space.
– SRVC-RC
Identifies the CA CSM services return code for this action.
NOTE
This code is similar to the z/OS completion code.
– Status
Identifies the status for this action.
2. Select the link for the action you want to view details for.
Another dialog that contains details about this action opens.
Activate the Configuration
Activation of a configuration may be required when you configure a product on a staging system.
Configuring a product on a staging system can help:
109
CA Easytrieve® Report Generator 11.6
• Create a customized set of run-time data sets that youthen move to a target system for the final activation
• Create a fully implemented version of the product and test it locally
Activating the configuration makes your configuration fully functional on the target system.
You perform the following high-level process to activate the configuration:
1. (In CA CSM) Configure a product on a staging system.
2. (In CA CSM) Obtain the activation instructions that are available after the configuration is successfully built, validated,
or implemented on a staging system. The activation instructions include extra steps that you have to perform on the
configuration outside of CA CSM. For example, update data set members, or APF-authorize data sets.
3. (Outside of CA CSM) Perform one of the following actions:
– If you activate a configuration on a staging system, follow the activation instructions on the staging system. Doing
so activates the configuration and completes the configuration process.
– If you activate a configuration on a remote system, deploy the configuration to the remote location. To do so, select
and use a method that is appropriate for your site and environment. Follow the activation instructions on the remote
system to activate the configuration and complete the configuration process.
Follow these steps:
1. Select the Configurations tab and locate the configuration that you want to activate.
2. Select the Actions drop-down list to the right of the configuration, and select Activation Instructions.
A dialog that shows activation instructions opens. This dialog contains information about steps that you have to
perform to activate the configuration.
3. Review the steps.
4. (Optional) Select Export to print the activation instructions, or export them to a TXT file or a ZIP file.
5. Close the dialog.
6. Perform the steps that are described in the activation instructions.
Your configuration is activated and fully functional.
Address Implementation Failures
Follow these steps:
1. Determine the cause of the failure. Drill down into the step and action details, and analyze the details.
2. If the error is related to a problem in your environment, make the necessary changes to your environment to correct
the issue. Implement this configuration again.
3. If the error is related to the configuration settings in CA CSM, create a new configuration and import values from the
failed configuration:
a. When in step 3 (Import Values), select Import from Previous and Delete. Doing so imports the values from the
failed configuration, and deletes the failed configuration. This action prevents duplicate resource problems.
b. Modify the values in the new configuration as you need.
c. Complete the remaining wizard steps.
4. Build the configuration.
5. Validate the configuration to discover and clean up any data sets that may have been created as part of the failed
implementation attempt.
6. Implement the configuration.
7. (Optional: Staging systems only) Activate the configuration.
Installing Your Product Using Pax ESD or DVD
As a System Programmer, your responsibilities include installing products on your mainframe system. You can acquire a
product pax file from Broadcom Support or from a product DVD. The DVD contains a folder that includes the pax file for
110
CA Easytrieve® Report Generator 11.6
the product. Product updates may have occurred after you acquired the product DVD. To obtain the latest updates, go to
Download Management on CA Support.
Perform the following tasks to install a product with a pax file:
1. Allocate and mount the file system.
2. Acquire the product pax files.
3. Create a product directory from the pax file.
4. Copy the installation files to z/OS data sets.
5. Prepare the SMP/E environment for a pax installation.
6. Run the installation jobs for a pax installation.
7. (Optional) Clean up the USS directory.
8. Apply preventive maintenance.
UNIX System Services Environment
You need a UNIX System Services (USS) directory and a file system with adequate space to perform the following tasks:
• Receive product pax files from Broadcom Support.
• Perform utility functions to unpack the pax file into MVS data sets that you can use to complete the product installation.
111
CA Easytrieve® Report Generator 11.6
We recommend that you allocate and mount a file system that is dedicated to Pax ESD. The amount of space that you
need for the file system depends on the following variables:
• The size of the pax files that you intend to download.
• Whether you plan to keep the pax files after unpacking them. We do not recommend this practice.
We recommend that you use one directory for downloading and unpacking pax files. Reusing the same directory
minimizes USS setup. You need to complete the USS setup only one time. You reuse the same directory for subsequent
downloads. Alternatively, you can create a directory for each pax download.
WARNING
Downloading pax files for the SMP/E installation as part of the Pax ESD process requires write authority to the
UNIX System Services (USS) directories that are used for the Pax ESD process. In the file system that contains
the Pax ESD directories, you also need free space approximately 3.5 times the pax file size to download the pax
file and unpack its contents. For example, to download and unpack a 14 MB pax file, you need approximately
49 MB of free space in the file system hosting your Pax ESD directory.
Allocate and Mount a File System
We recommend that you allocate and mount a file system that is dedicated to the product acquisition. We also
recommend that you create a directory in this file system that will house the pax file. The product installation process
requires a USS directory to receive the pax file and to perform the unpack steps.
This procedure describes how to perform the following tasks:
• Allocate a zFS.
• Create a mount point in an existing maintenance directory of your choice in USS.
• Mount the file system on the newly created mount point.
NOTE
You must have SUPERUSER authority or the required SAF profile setting so you can issue the USS mount
command for the file system.
• Optionally, permit write access to anyone in the same group as the person who created the directory.
WARNING
USS commands are case-sensitive.
Follow these steps:
1. Allocate the zFS by customizing the following sample:
//DEFINE EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//AMSDUMP DD SYSOUT=*
//SYSIN DD *
DEFINE CLUSTER ( +
NAME(your_zFS_data_set_name) +
STORAGECLASS(class) +
LINEAR +
CYL(primary secondary) +
SHAREOPTIONS(3,3) +
)
/*
//FORMAT EXEC PGM=IOEAGFMT,REGION=0M,
// PARM=('-aggregate your_zFS_data_set_name -compat')
//SYSPRINT DD SYSOUT=*
112
CA Easytrieve® Report Generator 11.6
//SYSUDUMP DD SYSOUT=*
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
//*
The zFS is allocated.
NOTE
Ensure that the zFS data set name that you use conforms to your data set naming conventions for USS file
systems. If the allocation of the file system data set fails, it is because of environmental settings not allowing
for the allocation.
2. Create a mount point for the file system. This example shows how to create your USS pax directory named /CA/
CAPAX directory in the existing /u/maint directory. From the TSO OMVS shell, enter the following commands:
cd /u/maint/
mkdir CA
cd CA
mkdir CAPAX
NOTE
Further references to this mount point appear as yourUSSpaxdirectory.
The mount point is created.
3. Mount the file system by customizing the following sample:
MOUNT FILESYSTEM('your_zFS_data_set_name')
MOUNTPOINT('yourUSSpaxdirectory')
TYPE(ZFS) MODE(RDWR)
PARM(AGGRGROW)
The file system is mounted.
4. (Optional) Set security permissions for the directory. You can use the chmod command to let other users access the
USS pax directory and its files. For example, to allow write access to the USS pax directory for other users in your
USS group, from the TSO OMVS shell, enter the following command:
chmod -R 775 /yourUSSpaxdirectory/
Write access is granted.
NOTE
For more information about the chmod command, see the IBM z/OS UNIX System Services User Guide
(SA22-7802).
Acquire the Product Pax Files
To begin the CA Technologies product installation procedure, copy the product pax file into the USS directory that you set
up.
WARNING
Downloading pax files for the SMP/E installation as part of the Pax ESD process requires write authority to the
UNIX System Services (USS) directories that are used for the Pax ESD process. Also, you must have available
USS file space before you start the procedures in this section.
Use one of the following methods:
• Download the product pax file from https://casupport.broadcom.com to your PC, and then upload it to your USS file
system.
113
CA Easytrieve® Report Generator 11.6
If you download a zip file, you must unzip it before uploading to your USS file system.
• Download the pax files from http://casupport.broadcom.com directly to your USS file system.
• Download the pax file from the product DVD to your PC, and then upload the pax files to your USS file system.
This section includes the following information:
• A sample batch job to download a product pax file from the Broadcom Support Online FTP server directly to a USS
directory on your z/OS system
• Sample commands to upload a pax file from your PC to a USS directory on your z/OS system
WARNING
The FTP procedures vary due to local firewall and other security settings. Consult your local network
administrators to determine the appropriate FTP procedure to use at your site.
Download Files to a PC Using Pax ESD
You can download product installation files from Broadcom Support to your PC.
Follow these steps:
1. Confirm the following UNIX System Services (USS) requirements:
– You have write authority to the USS directories that are used for the pax installation process.
– You have available USS file space.
NOTE
In the file system that contains the pax directories, you also need free space approximately 3.5 times the
pax file size to download the pax file and unpack its contents. For example, to download and unpack a 14
MB pax file, you need approximately 49 MB of free space in the file system hosting your pax directory.
If you do not have sufficient free space, error messages similar to the following appear:
EZA1490I Error writing to data set
EZA2606W File I/O error 133
2. Log in to Broadcom Support Online.
3. Click DOWNLOAD MANAGEMENT.
4. Select CA Easytrieve in the first drop-down list.
5. Click the Product Downloads tab, and enter CA Easytrieve Report Generator in the Filter Search Results field.
6. Locate the appropriate software package.
TIP
To change the release, select the package and use the release drop-down.
If applicable, agree to the end user license agreement (EULA).
7. Select a download method:
TIP
Review the Broadcom Support Online download and FTP Help topics.
– If you select Enhanced Download Manager, a dialog opens. Follow the prompts to download the installer.
– The installer then downloads your product files to the location on your PC, as specified in the installer. Go to Step 9.
– If you select FTP, you are redirected to Cart History.
You receive an email notification when your files are ready. The email includes a link to your Cart History. Go to
Step 7.
– If you have previously set your download preference, the installer begins the download process. Go to Step 7 or 9
based on your download setting.
8. Select FTP next to your package in Cart History.
114
CA Easytrieve® Report Generator 11.6
Your FTP download details appear including hostname, username, and password.
TIP
To find the file names with the package, click FTP via Browser.
9. Download the shopping cart file to your workstation.
10. If you downloaded a zip file, unzip the file to prepare the product pax files for use.
The pax file is ready for FTP.
NOTE
Do not change the format of the pax.Z.
11. FTP the pax.Z files in binary mode to your mainframe USS file system.
Sample FTP commands from a Windows command prompt are provided in Download Files to Mainframe through a
PC, starting with step 2.
Download Using Batch JCL
You download a pax file from Broadcom Support by running batch JCL on the mainframe. You can modify the sample JCL
in CAtoMainframe to perform the download.
NOTE
This JCL procedure is the preferred download method for users who do not use CA CSM.
Follow these steps:
1. Modify CAtoMainframe.txt as follows:
– Replace ACCOUNTNO with a valid JOB statement.
– Replace yourTCPIP.PROFILE.dataset with the name of the TCP/IP profile data set for your system. Consult your
local network administrators, if necessary.
The job points to your profile.
– Replace YourEmailAddress with your email address.
The job points to your email address.
– Replace yourUSSpaxdirectory with the name of the USS directory that you use for Pax ESD downloads.
The job points to your USS directory.
2. Locate the product component to download on the Broadcom Support Product Download window.
3. Click Download for the applicable file.
NOTE
For multiple downloads, add files to a cart.
The Download Method window opens.
4. Click FTP Request.
The Review Download Requests window displays any files that you have requested to download.
NOTE
We send you an email when the file is ready to download or a link appears in this window when the file is
available.
5. Select one of the following methods:
– Preferred FTP
Uses CA Technologies worldwide content delivery network (CDN). If you cannot download using this method,
review the security restrictions for servers that company employees can download from that are outside your
corporate network.
Host Name: ftp://ftpdownloads.ca.com
– Alternate FTP
Uses the original download servers that are based on Long Island, New York.
115
CA Easytrieve® Report Generator 11.6
Host Name: ftp://scftpd.ca.com for product files and download cart files and ftp://ftp.ca.com for individual solution
files.
Both methods display the host, user name, password, and FTP location, which you then can copy into the sample
JCL.
NOTE
The following links provide details regarding FTP: the FTP Help document link in the Review Download
Requests window and the Learn More link available in the Download Methods window.
6. Submit the job.
WARNING
If your FTP commands are incorrect, it is possible for this job to fail and still return a zero condition code.
Read the messages in the job DDNAME SYSPRINT to verify the FTP succeeded.
After you run the JCL job, the pax file resides in the mainframe USS directory that you supplied.
Example CAtoMainframe.txt, JCL
The following text appears in the CAtoMainframe.txt JCL file:
//GETPAX JOB (ACCOUNTNO),'FTP GET PAX ESD PACKAGE',
// MSGCLASS=X,CLASS=A,NOTIFY=&SYSUID
//*********************************************************************
//* This sample job can be used to download a pax file directly from *
//* CA Support Online to a USS directory on your z/OS system. *
//* *
//* When editing the JCL ensure that you do not have sequence numbers *
//* turned on. *
//* *
//* This job must be customized as follows: *
//* 1. Supply a valid JOB statement. *
//* 2. The SYSTCPD and SYSFTPD JCL DD statements in this JCL may be *
//* optional at your site. Remove the statements that are not *
//* required. For the required statements, update the data set *
//* names with the correct site-specific data set names. *
//* 3. Replace "Host" based on the type of download method. *
//* 4. Replace "YourEmailAddress" with your email address. *
//* 5. Replace "yourUSSpaxdirectory" with the name of the USS *
//* directory used on your system for Pax ESD downloads. *
//* 6. Replace "FTP Location" with the complete path *
//* and name of the pax file obtained from the FTP location *
//* of the product download page. *
//*********************************************************************
//GETPAX EXEC PGM=FTP,PARM='(EXIT TIMEOUT 120',REGION=0M
//SYSTCPD DD DSN=yourTCPIP.PROFILE.dataset,DISP=SHR
//SYSFTPD DD DSN=yourFTP.DATA.dataset,DISP=SHR
//SYSPRINT DD SYSOUT=*
//OUTPUT DD SYSOUT=*
//INPUT DD *
Host
anonymous YourEmailAddress
lcd yourUSSpaxdirectory
binary
get FTP_location
quit
116
CA Easytrieve® Report Generator 11.6
/*
Download Files to Mainframe through a PC
You download the product installation files to your PC and transfer them to your USS system.
Follow these steps:
1. Download the product file to your PC using one of the following methods:
– Pax ESD. If you download a zip file, first unzip the file to use the product pax files.
– DVD. Copy the entire product software package (or individual pax files) to your PC.
The pax file resides on your PC.
NOTE
Do not change the format of the pax.Z.
2. Open a Windows command prompt.
3. Enter the following FTP commands, specifying values for the variables:
FTP mainframe
userid
password
bin
lcd C:\PC\folder\for\thePAXfile
cd /yourUSSpaxdirectory/
put paxfile.pax.Z
quit
exit
– mainframe
Specifies the z/OS system IP address or DNS name.
– userid
Specifies your z/OS user ID.
– password
Specifies your z/OS password.
– C:\PC\folder\for\thePAXfile
Specifies the location of the pax file on your PC.
NOTE
If you specify a location that has blanks or special characters in the path name, enclose that value in
double quotation marks.
– yourUSSpaxdirectory
Specifies the name of the USS directory that you use for Pax ESD downloads.
– paxfile.pax.Z
Specifies the name of the pax file to upload.
The pax file is transferred to the mainframe.
Create a Product Directory from the Pax File
The pax command performs the following actions:
• Extracts the files and directories that are packaged within the pax file.
• Creates a USS directory in the same directory structure where the pax file resides.
• Automatically generates a product and level-specific directory name.
Set the current working directory to the directory containing the pax file, and create a directory in your USS directory by
entering the following command:
117
CA Easytrieve® Report Generator 11.6
pax -rvf pax-filename
Use the following sample JCL to extract the product pax file into a product installation directory.
//ESDUNPAX JOB (ACCOUNTNO),'UNPAX PAX FILE',
// MSGCLASS=X,CLASS=A,NOTIFY=&SYSUID
//*********************************************************************
//* This sample job can be used to invoke the pax command to create *
//* the product-specific installation directory. *
//* *
//* This job must be customized as follows: *
//* 1. Supply a valid JOB statement. *
//* 2. Replace "yourUSSpaxdirectory" with the name of the USS *
//* directory used on your system for Pax ESD downloads. *
//* 3. Replace "paxfile.pax.Z" with the name of the pax file. *
//* NOTE: If you continue the PARM= statement on a second line, *
//* start entering characters in column 16 and make sure *
//* the 'X' continuation character is in column 72. *
//*********************************************************************
//UNPAXDIR EXEC PGM=BPXBATCH,
// PARM='sh cd /yourUSSpaxdirectory/; pax -rvf paxfile.pax.Z'
//*UNPAXDIR EXEC PGM=BPXBATCH,
//* PARM='sh cd /yourUSSpaxdirectory/; pax X
//* -rvf paxfile.pax.Z'
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
Follow these steps:
1. Replace ACCOUNTNO with a valid JOB statement.
2. Replace yourUSSpaxdirectory with the name of the USS directory that you use for product downloads.
The job points to your specific directory.
3. Replace paxfile.pax.Z with the name of the pax file.
The job points to your specific pax file.
4. Submit the job.
The job creates the product directory.
NOTE
If the PARM= statement exceeds 71 characters, comment out the first UNPAXDIR. Then uncomment and
use the second form of UNPAXDIR instead. This sample job uses an X in column 72 to continue the PARM=
parameters to a second line.
Copy Installation Files to zOS Data Sets
Use this procedure to invoke the SMP/E GIMUNZIP utility to create MVS data sets from the files in the product-specific
directory.
The file UNZIPJCL in the product directory contains a sample job to GIMUNZIP the installation package. You edit and
submit the UNZIPJCL job to create z/OS data sets.
118
CA Easytrieve® Report Generator 11.6
Follow these steps:
1. Locate and read the product readme file or installation notes, if applicable, which resides in the product-specific
directory that the pax command created. This file contains the product-specific details that you require to complete the
installation procedure.
You have identified the product-specific installation details.
2. Use ISPF EDIT or TSO ISHELL to edit the UNZIPJCL sample job. You can perform this step in one of the following
ways:
– Use ISPF EDIT
Specify the full path name of the UNZIPJCL file.
– Use TSO ISHELL
Navigate to the UNZIPJCL file and use the E line command to edit the file.
The job is edited.
3. Change the SMPDIR DD PATH to the product-specific directory created by the pax command.
Your view is of the product-specific directory.
4. If ICSF is not active, perform the following steps:
a. Change the SMPJHOME DD PATH to your Java runtime directory. This directory varies from system to system.
b. Perform one of the following steps:
• Change the SMPCPATH DD PATH to your SMP/E Java application classes directory, typically /usr/lpp/smp/
classes/.
• Change HASH=YES to HASH=NO on the GIMUNZIP parameter.
One of the following occurs: ICSF is active or you are using Java.
5. Change all occurrences of yourHLQ to the high-level qualifier (HLQ) for z/OS data sets that the installation
process uses. We suggest that you use a unique HLQ for each expanded pax file to identify uniquely the package.
Do not remove CAI after yourHLQ. Do not use the same value for yourHLQ as you use for the SMP/E RELFILEs.
All occurrences of yourHLQ are set to your high-level qualifier for z/OS data sets.
6. Submit the UNZIPJCL job.
The UNZIPJCL job completes with a zero return code. Messages GIM69158I and GIM48101I in the output and
IKJ56228I in the JES log are acceptable.
GIMUNZIP creates z/OS data sets with the high-level qualifier that you specified in the UNZIPJCL job. You use these
data sets to perform the product installation. The pax file and product-specific directory are no longer needed.
NOTE
For more information, see the IBM SMP/E for z/OS Reference (SA22-7772).
Prepare the SMPE Environment for a Pax Installation
The members that are used in this procedure prepare the data sets, initialize the zones, and create the DDDEFs for your
product.
Establishing a zSeries file system (zFS) may be required as part of the product installation or required as a feature of the
product.
For information about the members, see the comments in the JCL.
Follow these steps:
1. Customize the macro EZTSEDIT with your site-specific information and then copy the macro to your SYSPROC
location. Replace the rightmost parameters for each ISREDIT CHANGE command. Each time you edit an installation
member, type EZTSEDIT on the command line, and press Enter to replace the defaults with your specifications.
The macro is ready to customize the yourHLQ.SAMPJCL members.
NOTE
119
CA Easytrieve® Report Generator 11.6
• Set the DASD HLQ to the same value specified for yourHLQ within the JCL that is used to unzip the pax
file.
• The following steps include instructions to execute the EZTSEDIT macro each time you open a new
SAMPJCL member. To edit all SAMPJCL members simultaneously, read and follow the instructions in the
EZTAREAD member.
2. Open the SAMPJCL member EZT1ALL in an edit session and execute the EZTSEDIT macro from the command line.
EZT1ALL is customized.
3. Submit EZT1ALL.
This job produces the following results:
– The target and distribution data sets for your product are created.
– Unique SMPLTS, SMPMTS, SMPSCDS, and SMPSTS data sets for this target zone are created.
4. If your product requires a USS file system or if you want to install a feature of the product that requires a USS file
system, allocate and mount the file system:
NOTE
You can customize the supplied HFS JCL to zFS, if your site requires it.
5. Open the SAMPJCL member EZT2CSI in an edit session and execute the EZTSEDIT macro from the command line.
EZT2CSI is customized.
6. Submit EZT2CSI.
This job produces the following results:
– The CSI data set is defined.
– The SMPPTS and SMPLOG data sets are allocated.
– The global, target, and distribution zones are initialized.
– The DDDEF entries for your product are created.
– The DDDEFs for the required SMP/E data sets are created.
Run the Installation Jobs for a Pax Installation
The members in the following procedure are used to receive, apply, and accept SMP/E base functions. Submit and run
these SAMPJCL members in sequence. Do not proceed with any job until the previous job has completed successfully.
NOTE
The following steps include instructions to execute the EZTSEDIT macro each time you open a new SAMPJCL
member. To edit all SAMPJCL members simultaneously, read and follow the instructions in the EZTAREAD
member, and submit the EZTEDALL member.
Follow these steps:
1. Open the SAMPJCL member EZT3RECD in an edit session, and execute the EZTSEDIT macro from the command
line.
EZT3RECD is customized.
2. Submit EZT3RECD to receive SMP/E base functions and error HOLDDATA.
Your product is received and now resides in the global zone.
3. If an FMID was placed in error, download and receive PTFs from Broadcom Support.
4. Open the SAMPJCL member EZT4APP in an edit session, and execute the EZTSEDIT macro from the command line.
EZT4APP is customized.
5. Submit EZT4APP to apply SMP/E base functions with the CHECK option. If you find unresolved hold errors, we
recommend that you note these errors and verify that resolving PTFs are applied before implementing products in
production. Update the JCL to BYPASS the unresolved hold error IDs. After successful completion, rerun APPLY with
the CHECK option removed.
Your product is applied and now resides in the target libraries.
6. Open the SAMPJCL member EZT5ACC in an edit session, and execute the EZTSEDIT macro from the command line.
120
CA Easytrieve® Report Generator 11.6
EZT5ACC is customized.
7. Submit EZT5ACC to accept SMP/E base functions with the CHECK option. After successful completion, rerun
ACCEPT with the CHECK option removed.
Your product is accepted and now resides in the distribution libraries.
Clean Up the USS Directory
This procedure is optional. If you decide to perform the procedure, do so after you complete the installation process and
when you do not need the installation files anymore.
To free file system disk space for subsequent downloads after downloading and processing the pax files for your CA
Technologies product, we recommend removing the files from your USS directory and deleting unnecessary MVS data
sets. You can delete the following items:
• Pax file
• Product-specific directory that the pax command created and all of the files in it
• SMP/E RELFILEs, SMPMCS, and HOLDDATA MVS data sets
These data sets have the HLQ that you assigned in the UNZIPJCL job.
NOTE
Retain non-SMP/E installation data sets such as yourHLQ.INSTALL.NOTES for future reference.
Follow these steps:
1. Navigate to your Pax ESD USS directory.
Your view is of the applicable USS directory.
2. Delete the pax file by entering the following command:
rm paxfile
– paxfile
Specifies the name of the CA Technologies pax file that you downloaded.
The pax file is deleted.
3. Delete the product-specific directory by entering the following command:
rm -r product-specific_directory
– product-specific_directory
Specifies the product-specific directory that the pax command created.
The product-specific directory is deleted.
NOTE
You can also use TSO ISHELL to navigate to the pax file and product-specific directory, and delete them using
the D line command.
Apply Preventive Maintenance
To apply preventive maintenance, you download, receive, apply, and accept maintenance. Preventive maintenance lets
you apply PTFs that Broadcom Support has created and made public. You may not have experienced the issue that each
PTF addresses. We recommend that you apply preventive maintenance regularly so that you do not encounter known
issues with published and tested fixes.
The following content may also help you manage your site maintenance
121
CA Easytrieve® Report Generator 11.6
• To review the CA Technologies mainframe maintenance philosophy, see best practices for your product or visit the
Mainframe Installation and Maintenance Tools site.
• For a comprehensive collection of articles dedicated to all CA mainframe maintenance concepts and procedures, see
Mainframe Common Maintenance Procedures.
Download and Receive Maintenance
Maintenance and HOLDDATA is available at CA Support. After you complete the maintenance process, the product is
ready to deploy.
Use this procedure during product installation and for ongoing preventive maintenance in non-installation use cases
according to your maintenance strategy.
Follow these steps:
1. Select your download option:
WARNING
We recommend that you use the CA SMP/E Internet Service Retrieval option, which significantly simplifies
the download process. CA SMP/E is supported by CA Easytrieve Report Generator Release 11.6 and later
only.
– Download maintenance using the CA SMP/E Internet Service Retrieval
This option uses the IBM SMP/E RECEIVE ORDER command to download CA Mainframe product maintenance
over the Internet, by securely submitting an order for PTFs and HOLDDATA to a remote CA server. This service
eliminates the manual steps that are required to download maintenance from CA Support Online. The orders are
fulfilled based on the status of your SMP/E environments. Based on your order criteria, all PTFs and their requisites
are downloaded automatically and received to your system.
To use this download option, complete the procedures in CA SMP/E Internet Service Retrieval.
– Download maintenance manually from CA Support Online
With this option, you manually select PTFs and build a package for all applicable PTFs and requisites. You then
use the CAUNZIP utility to unpackage and receive the files. This utility processes ZIP packages directly on z/
OS without the need for an intermediate platform, such as a Microsoft Windows workstation. The utility resides
in yourCCSHLQ.CAW0JCL(CAUNZIP). To use this download option, you must be running CA Common Services
Release 14.1 with PTF RO58216 or Version 15.0. Review the CAUNZIP requirements under the section download
options and complete the following procedures.
2. Log in to Broadcom Support.
3. Select DOWNLOAD MANAGEMENT.
4. Locate your product in the download management tool.
Your product entry opens at the Product Downloads tab.
5. Select the Solution Downloads tab.
6. Select the applicable product and software release.
7. Select the applicable solutions and download them using the Cart or Download Now option.
TIP
Review the CA Support Online download and FTP Help topics.
8. Run the CAUNZIP utility.
CAUNZIP unzips the package of published solutions and creates a SMPNTS file structure that the SMP/E RECEIVE
FROMNTS command can process. For sample JCL to run the utility that is located in yourHLQ.CAW0JCL(CAUNZIP),
see the CA Common Services for z/OS CAUNZIP Administration documentation. After execution completes, the
ZIPRPT data set contains the summary report. The summary report does the following:
– Summarizes the content of the product order ZIP file.
– Details the content of each data set and the z/OS UNIX files produced.
– Provides a sample job to receive the PTFs in your order.
122
CA Easytrieve® Report Generator 11.6
9. Review the sample job that is provided in the CAUNZIP output ZIPRPT file.
10. Cut and paste the JCL into a data set,
11. Specify your SMP/E CSI on the SMPCSI DD statement.
12. Submit the job to receive the PTFs in your order.
13. Verify that you have the values from the base installation in the EZTSEDIT macro that was customized in the
installation steps.
14. (Optional) Apply CA Recommended Service (CA RS) Maintenance
Apply and Accept Maintenance
Use this procedure to apply and optionally accept CA Technologies corrective maintenance.
WARNING
We recommend that you use CA CSM to maintain your CA Technologies z/OS-based products. The procedure
that is discussed in this section is fully automated when you use CA CSM.
Follow these steps:
1. Open the SAMPJCL member EZT7APYP in an edit session and execute the EZTSEDIT macro from the command
line.
EZT7APYP is customized.
2. Submit EZT7APYP.
The PTFs are applied.
3. (Optional) Open the SAMPJCL member EZT8ACCP in an edit session and execute the EZTSEDIT macro from the
command line.
EZT8ACCP is customized.
4. (Optional) Submit EZT8ACCP.
The PTFs are accepted.
NOTE
You do not have to submit the job at this time. You can accept the PTFs according to your site policy.
Apply CA Recommended Service (CA RS) Maintenance
Use this procedure to apply CA RS maintenance as a part of managing preventive maintenance.
NOTE
We recommend that you review the CA RS overview.
Follow these steps:
1. Download the Assign statements:
a. Determine which ASSIGN statements to download.
• The yearly CA RS ASSIGN statements are stored in the following file:
ftp.ca.com/pub/ASSIGNS/YEARLY/YEARyyyy.TXT
• The monthly CA RS ASSIGN statements are stored in the following file:
ftp.ca.com/pub/ASSIGNS/CARyymm.TXT
b. Open the SAMPJCL member EZT6CARS in an edit session, update EZT6CARS SAMPJCL to download ASSIGN
statements from Broadcom Support, and execute the EZTSEDIT macro from the command line.
EZT6CARS is customized.
2. Submit EZT6CARS.
The job downloads the CA RS ASSIGN statements.
3. Open the SAMPJCL member EZT6RECP in an edit session, manually add the data set that contains the ASSIGN
statements to the SMPPTFIN DD, and execute the EZTSEDIT macro from the command line.
123
CA Easytrieve® Report Generator 11.6
EZT6RECP is customized.
4. Submit EZT6RECP.
The job receives the external HOLDDATA file and CA RS ASSIGN statements.
5. Open the SAMPJCL member EZT7APYP in an edit session and execute the EZTSEDIT macro from the command
line.
EZT7APYP is customized.
6. Submit EZT7APYP.
The PTFs are applied.
7. (Optional) Open the SAMPJCL member EZT8ACCP in an edit session and execute the EZTSEDIT macro from the
command line.
EZT8ACCP is customized.
8. (Optional) Submit EZT8ACCP.
The PTFs are accepted.
NOTE
You do not have to submit the job at this time. You can accept the PTFs according to your site policy.
HOLDDATA
When you apply maintenance, you typically encounter SMP/E HOLDDATA. We use HOLDDATA to notify your SMP/E
system of SYSMODs that have errors or special conditions.
HOLDDATA is included in PTFs.
System HOLDDATA
System HOLDDATA indicates data that is an in-stream part of the SYSMOD, informing you of special conditions. The
following reasons are used with SYSTEM HOLDDATA for your product:
• ACTION
Indicates that you must perform special processing before or after you apply this SYSMOD.
• AO
Affects automated operations. It changes either the message identifier or the displacement of a field inside the
message.
• DB2BIND
Indicates that DBRMs have changed and packages need to be rebound.
• DDDEF
Indicates that data sets and DDDEFs are being added or modified.
• DELETE
Deletes the SYSMOD load module. You cannot reverse this type of SYSMOD with the SMP/E RESTORE command.
• DEP
Indicates a dependency for this SYSMOD that you must externally verify.
• DOC
Indicates a documentation change with this SYSMOD.
• DOWNLD
Indicates that some or all of the elements that this SYSMOD delivers are to be downloaded to a workstation.
Code a BYPASS(HOLDSYS) operand on your APPLY command to install SYSMODs that have internal holds. Code
the BYPASS(HOLDSYS) operand only after you have performed the required action, or if you are performing the
action after the APPLY, if that is appropriate.
• DYNACT
Describes the steps to dynamically activate this fix without performing an IPL.
• EC
124
CA Easytrieve® Report Generator 11.6
Indicates that this SYSMOD requires a hardware engineering change. An EC hold SYSMOD usually does not affect
the product unless the EC is present on the hardware device.
• ENH
Introduces a small programming enhancement. The hold contains the instructions to implement the enhancement. If no
action is needed to implement the enhancement, give a summary of the enhancement.
• EXIT
Indicates that changes delivered by this SYSMOD require reassembly of user exits.
• EXRF
Indicates that the SYSMOD must be installed in both the Active and Alternate Extended Recovery Facility Systems.
• IPL
Indicates that an IPL is required for this SYSMOD to take effect. This option is used only when there is no alternative
for dynamic activation.
MSGSKEL
Indicates that the SYSMOD contains internationalized message versions that must be run through the message
compiler for each language.
• MULTSYS
Apply this SYSMOD to multiple systems for either pre-conditioning, coexistence, or exploitation.
• RESTART
Indicates that after applying this SYSMOD, the site must perform a special restart as opposed to a routine restart.
• SQLBIND
Indicates that a bind is required for a database system other than DB2.
Error HOLDDATA
If a SYSMOD has unresolved error HOLDDATA, SMP/E does not install it unless you add a bypass to your APPLY
command. You can bypass error HOLDDATA in situations that are not applicable to you. Error HOLDDATA that is not
applicable to you can include a problem that happens only with a hardware device that you do not have or in a product
feature that you do not use.
When CA Technologies publishes a SYSMOD that resolves the error HOLDDATA, the resolving SYSMOD supersedes the
error HOLDDATA. This action lets you apply the original SYSMOD in conjunction with the fixing SYSMOD.
The only manual task is running a REPORT ERRSYSMODS. This report identifies the following:
• Any held SYSMODs already applied to your system
• Any resolving SYSMODs that are in RECEIVE status
SMP/E identifies the SYSMOD to apply to correct the situation.
FIXCAT HOLDDATA
CA Technologies provides FIXCAT HOLDDATA to help identify maintenance that is required to support a particular
hardware device, software, or function. Fix categories are supplied as SMP/E FIXCAT HOLDDATA statements. Each
FIXCAT HOLDDATA statement associates an APAR and its related fixing PTF to one or more fix categories.
SAMPJCL and CBAAJCL Contents
The SAMPJCL and CBAAJCL data sets contain the jobs that are used to install and configure CA Easytrieve Report
Generator when you are using pax-enhanced ESD or from a DVD. SAMPJCL contains the file allocation and SMP/E
RECEIVE, APPLY, and ACCEPT jobs. CBAAJCL contains all other jobs. CBAAJCL is populated when you run the SMP/E
jobs.
WARNING
Do not modify and run JCL members from previous service packs because they can corrupt the installation.
125
CA Easytrieve® Report Generator 11.6
SAMPJCL Contents
The following table shows the installation jobs and related TSO macros that are provided in hlq.SAMPJCL. An index of the
SAMPJCL members is in hlq.SAMPJCL(EZTAREAD).
Member Name Description Topic Where Job is Mentioned
EZTSEDIT Edit macro that is used to customize the All Pax ESD installation topics where
product installation JCL. Update member editing a job is required
and store in SYSPROC library.
EZTEDALL Optional REXX EXEC to customize all Run the Installation Jobs for a Pax
jobs at once. Execute after updating the Installation
EZTSEDIT macro.
EZT1ALL Allocates product and SMP/E data sets. Prepare the SMP/E Environment for a Pax
Installation
EZT2CSI Creates and customizes SMP/E CSI. Prepare the SMP/E Environment for a Pax
Installation
EZT3RECT SMP/E receive of base functions from Not used
media.
EZT3RECD SMP/E receive of base functions from Run the Installation Jobs for a Pax
DASD. Installation
EZT4APP SMP/E apply of base functions. Run the Installation Jobs for a Pax
Installation
EZT5ACC SMP/E accept of base functions. Run the Installation Jobs for a Pax
Installation
EZT6RECP SMP/E receive of downloaded PTFs from Apply Preventive Maintenance
DASD. • Apply CA Recommended Service (CA
RS) Maintenance
EZT7APYP SMP/E apply of downloaded PTFs. Apply Preventive Maintenance
• Apply and Accept Maintenance
• Apply CA Recommended Service (CA
RS) Maintenance
EZT8ACCP SMP/E accept of downloaded PTFs. Apply Preventive Maintenance
• Apply and Accept Maintenance
• Apply CA Recommended Service (CA
RS) Maintenance
CBAAJCL Contents
The CBAAJCL data set contains configuration jobs and utility jobs.
126
CA Easytrieve® Report Generator 11.6
Configuration Jobs
The following table shows the configuration jobs to run after you run the installation jobs. JOB06OP1 is always required.
Run the other jobs only if you use the feature that is associated with that job.
Member Name Description Topics Where Job is Mentioned
JOB06OP1 Creates and initializes a CA Easytrieve Configuration Best Practices
Report Generator options table. • Create an EZTINI File
Note: This job is always required. Create the Options File and Update Its
Settings
Migrate Options Table Settings (from 6.4)
Migrate Options Table Settings (within 11
versions)
JOB06OP2 Updates specific settings in the CA Configuration Best Practices
Easytrieve Report Generator options table. • Set Global Options
Create the Options File and Update Its
Settings
JOB0764L Links CA Easytrieve Report Activate the 6.4 Compatibility IDMS and
Generator compatibility library link edits IMS Interface Option
(only necessary when using IMS or IDMS
feature with NEWFUNC=N set in the
options table).
JOB08DEM Executes CA Easytrieve Report Lesson 1 - Library section, FILE and
Generator program to verify installation and DEFINE statements
create the sample personnel file. • Report Output
JOB09URT Compiles and links the User Requirements Assemble a User Requirements Table for
Table (URT) for the CA Datacom/DB option. the CA Datacom/DB Option
JOB10SUP Link edits the SUPRA interface module. Activate the SUPRA Interface Option
JOB11SUA Installs the EZTPSPRA module for the Activate the SUPRA Interface Option
SUPRA interface without SMP/E.
JOB11SUB Installs the EZTPSPRA module for the Activate the SUPRA Interface Option
SUPRA interface through SMP/E.
JOB12TOT Link edits the TOTAL interface module. Activate the TOTAL Interface Option
JOB13DBO Build the DBCS Code System definition Create the DBCS Options Module
module (only necessary if you use the
DBCS feature).
JOB14PSD Builds the Extended Printer Set definition Printer Set Definition
module (only necessary if you use the • Create Extended Reporting Printer Set
Extended Reporting feature). Definition
JOB15ORA Activates Oracle support by linking the Activate the Oracle Interface Option
Oracle ORASTBL member into the CA
Easytrieve Report Generator compiler.
127
CA Easytrieve® Report Generator 11.6
Utility Jobs
The following table shows the utility jobs and example members that are provided in hlq.CBAAJCL. These members are
used for processing that can be unrelated to product installation.
Member Name Description
ASM64OPT Provides JCL job to update the values of the options table that is
provided with the CA Easytrieve Plus 6.4 compatibility library.
EXISTCSI Provides instructions for installing into an existing CSI.
EZTDB2 Provides sample JCL to create and link a static IBM DB2 plan.
EZTPAQTT Provides alternate sort sequence table Assembler source file.
MOV64OPT Provides JCL job to migrate the options table settings to the
current release options table.
MOV64PSD Provides JCL job to migrate the 6.4 Printer Set Definition.
PDLMODEL Provides examples of printer definitions to use as models for your
own printer definitions.
PERSNL Provides sample PERSNL macro.
SAM1HTML Provides HTML reporting example.
SAM2HTML Provides HTML reporting example.
SSIDTBL Provides job to create SSID table for the CA Easytrieve Report
Generator Multi DB2 Option feature.
SUM1HTML Provides HTML reporting example.
SUM2HTML Provides HTML reporting example.
Upgrade CA Easytrieve for z/OS
This article explains how to upgrade CA Easytrieve Report Generator for z/OS to the current release.
Software Prerequisites
The prerequisites to install CA Easytrieve Report Generator Release 11.6 are as follows:
• You must install CA Common Services (CCS) Release 2.2, Genlevel 9909 or higher. We recommend that you upgrade
to CCS Release 11 SP8 or higher.
NOTE
CAIRIM is the only CA Common Services component required for CA Easytrieve Report Generator.
• For a smooth migration from a release prior to Release 6.4, we recommend that you upgrade to CA Easytrieve
Report Generator 6.4 0311 and apply maintenance before installing Release 11.6. This will ensure the highest level of
compatibility with the Release 11.6 environment.
Installation Information
CA Easytrieve Report Generator Release 11.6 is available only as a new installation.
Several changes have been made in the product installation JCL members that are distributed in the hlq.CBAAJCL data
set. Be sure to review the updated members.
WARNING
128
CA Easytrieve® Report Generator 11.6
• If you modify and run JCL members from previous service packs, you can corrupt the installation. For
instructions on implementing CA Easytrieve Report Generator, see Installing.
• As of Release 11.x, the distribution loadlib and the target CBAALOAD are allocated as PDS/Es. If those
libraries are PDS-format data sets, CA Easytrieve Report Generator Release 11.x cannot be installed into
existing distribution load libraries and target CBAALOADs.
Published Fixes
All published fixes are available from Download Management on Broadcom Support. With this release, published fixes
are now supplied as PTFs instead of as APARs, as was done previously. This ensures compliance with CA Technologies
current z/OS packaging standards. Also, CA Easytrieve Report Generator fixes can now be ACCEPTed according to
IBM’s SMP/E standards.
Install CA Easytrieve Packaged with CCS
CA Easytrieve Report Generator Release 11.6 is packaged with CA Common Services for z/OS (CCS) Release
14.1 and later as a separate pax file. Because it is not a licensed product, functionality is limited to modifying and
running predefined reports that are included with other CA products.
To get the pax file, go to the CA Common Services MVS download page on Broadcom Support, and download and install
B60000ESACS.PAX.z.
For installation instructions, see Install CA Easytrieve for z/OS.
NOTE
• Apply all CCS maintenance.
• Apply all CA Easytrieve Report Generator maintenance after installation.
• Set NEWFUNC N, AMODE31 N, and MACTYPE D in the CA Easytrieve Report Generator Release 11.6
option table. For more information, see Updating the Table.
• Set SYSTEM=OS and MACRO=PDS in the CA Easytrieve Release 6.4 options table. For more information,
see the CA Easytrieve 6.4 Getting Started Release 6.4, available from Legacy Bookshelves and PDFs on
the CA Easytrieve Previous Releases.
Install CA Easytrieve SDS
CA Easytrieve Simplified Design System (CA Easytrieve SDS) lets you develop, run, and maintain CA Easytrieve reports
on a remote computer without having to learn the CA Easytrieve programming language. This article explains how to
install CA Easytrieve SDS.
Follow these steps:
1. Download the executable file that is located at the Index of /pub/easytrieve/eztsds/.
2. Double-click filename.exe.
A dialog appears.
3. Select one of the following locations:
– The default folder
– Click Browse and select a different folder
4. Click Unzip.
The CA Easytrieve SDS files are extracted to the specified folder. You can start CA Easytrieve SDS by double-clicking
easytrieve.exe in that folder.
129
CA Easytrieve® Report Generator 11.6
Install the License Key
After installing CA Easytrieve on Windows, UNIX or Linux for zSeries, or Linux PC, you must install the ALP license key
that was sent to you when the product was purchased.
NOTE
CA Easytrieve for z/OS uses an LMP license instead of an ALP license key. The LMP license for CA Easytrieve
for z/OS is available from Broadcom Support.
Follow these steps:
1. Locate your ALP license key. If you do not have the ALP license key, contact CA Customer Care at 1-800-CALLCAI
(1-800-2255-224).
2. Open the ALP license key in a text editor and verify that it includes product code 2EZT.
3. Verify that the ca.olf file is in the ca_lic folder. Directory path examples are as follows:
UNIX/Linux
/opt/CA/SharedComponents/ca_lic
Windows
C:\Program Files (x86)\CA\SharedComponents\CA_LIC
– If the ca.olf file exists, continue with Step 4.
– If the ca.olf file does not exist, create the file as follows:
a. Copy the entire ALP license key and paste it into a new text file.
b. Save the text file as ca.olf. The file must have security permissions that, at a minimum, allow all users to read
the file.
The license key installation is complete.
4. Run the following command:
MERGEOLF -n new_olf [-c current_olf] [-o output_olf] [-b backup_olf] [-d debug_log]
– -n new_olf
Specifies the name of the new OLF file to merge.
– -c current_olf
Specifies the path and name of the current OLF file to merge.
Default: ca.olf
– -o output_olf
Specifies the path and name of the new OLF file to create.
Default: ca.olf
– -b backup_olf
Specifies the path and name of the backup of the current OLF file.
Default: ca.old
– -d debug_log
Enables debugging and places information in the mergeolf.log file.
The new CA Easytrieve *.olf license file is merged with the existing ca.olf license file and the license key installation is
complete.
Example: Merge New License Into Old License File
The following example merges a new olf file that has been renamed to ca.nol into an existing ca.olf file:
MERGEOLF -n ca.nol -c c:\program files\ca\SharedComponents\ca_lic\ca.olf -o c:\program files\ca
\SharedComponents\ca_lic\ca.olf -b c:\program files\ca\SharedComponents\ca_lic\ca.old
130
CA Easytrieve® Report Generator 11.6
Maintain Your Product
This article explains how to maintain non-mainframe versions of the product. We recommend that you keep your product
up-to-date with maintenance to ensure best performance.
NOTE
For mainframe products, we recommend that you use CA SMP/E Internet Service Retrieval to download
maintenance, and use CA Chorus Software Management (CA CSM) to apply maintenance. Alternatively, you
can download and apply maintenance manually as described in Apply Preventive Maintenance.
Follow these steps:
1. Log into Broadcom Support and select DOWNLOAD MANAGEMENT.
2. Type easytrieve in the Search by Product Name field and select CA Easytrieve.
3. Select the EASYTRIEVE downloads box and select the Solution Downloads tab.
4. Type CA Easytrieve Report Generator in the Filter Search Results field.
The published solutions for all CA Easytrieve products appear on multiple pages.
5. Browse the pages until you find your product.
6. Select the appropriate release number and select the product link.
The published solutions for your product are displayed.
7. Select the applicable solutions and download them using the Cart or Download Now option.
TIP
Review the CA Support Online download and FTP Help topics.
8. Download and extract the file.
9. Use the appropriate method to run the ezt_patch-release-and-date file.
10. Follow the instructions in the installer.
131
CA Easytrieve® Report Generator 11.6
Configuring
This section discusses how to configure CA Easytrieve® Report Generator and includes the following topics:
• Configuration Best Practices
• Configure Your Product
• Configure Your System
Configuration Best Practices
This section provides the following best practices for configuring CA Easytrieve Report Generator:
These best practices are based on customer feedback to CA support, Development, and Technical Services.
We encourage you to share your best practices. To do so, you can enter a comment in the space provided at the bottom
of this article.
Set the Optimal Storage Amount
The optimal storage amount for your environment can vary from 256 KB to 640 KB, depending on the number of
dynamically acquired storage areas, such as I/O buffers and operating system control blocks. CA Easytrieve Report
Generator executes in as little as 192 KB of main storage in your z/OS. Setting an optimal storage amount for the
product helps you save space in your z/OS.
We recommend that you set the maximum storage amount based on the following two parameters:
• Size of the programs that you compile or execute
• The product options that you want to implement
Execute DB2 Programs as Statically Linked and Bound
The BIND option specifies the default Db2 bind that is used. We recommend that you execute Db2 programs as statically
linked and bound. Although you can use static or dynamic program execution for Db2, production programs are better
executed as statically linked and bound programs. These types of programs provide enhanced performance capabilities,
low overhead, and individual database mapping for each program.
NOTE
Some SQL processing types are available for either static or dynamic execution but not for both.
Run Programs in New Function Mode
The NEWFUNC option specifies whether to use the current version of the compiler or the Release 6.4 (Compatibility
Mode) compiler to compile your CA Easytrieve Report Generator programs. Running programs in new function mode
ensures adherence to the documented rules of the CA Easytrieve Report Generator language and lets you take
advantage of the new product features. For example, boundary checking of indexes and subscripts helps ensure data
integrity and output validity.
Do the following to run programs in new function mode:
1. Set NEWFUNC to Y in the Options Table. (The default is Y.)
2. Compile and link the program using CA Easytrieve Report Generator Release 11.6.
132
CA Easytrieve® Report Generator 11.6
NOTE
• You can view running programs in compatibility mode as a temporary workaround for specific problems by
setting NEWFUNC to N.
• For more information about the Options Table, see Updating the Table.
Set the AMODE31 Option
The AMODE31 option specifies the location of where memory is to be allocated during the execution of the CA Easytrieve
Report Generator application program. We recommend that you set the AMODE31 option depending on your processing
requirements as follows:
• If the programs are calling 31-bit subprograms, set AMODE31 to Y.
• If the programs are calling 24-bit subprograms, set AMODE31 to N. An override is available on the PARM statement by
using CALL(AMODE24).
• If the programs are calling 24-bit subprograms and ENVIRONMENT(COBOL) is used, set AMODE31 to N and set the
LE runtime options ALL31=(OFF),STACK=(,,BELOW).
NOTE
If you do not set AMODE31 correctly, it can result in a S0C4 ABEND or undesired storage allocation below the
16 MB line.
Increase the Number of I/O Buffers
Specifying more buffers for a large sequential file lets your job run faster. We recommend that you specify the number of I/
O buffers for each sequential file using the BUFNO option in the Options Table.
You can override the Options Table value through the BUFNO parameter of the FILE statement. The default BUFNO is 2.
You can specify BUFNO from 0 through 255.
NOTE
VFM and VSAM files do not use the BUFNO information.
Set Global Options
We recommend that you set the global options through the Options Table using JOB06OP2 that is provided
in hlq.CBAAJCL.
Setting options globally eliminates the need to code the options in their specific area, saves programming time, reduces
required knowledge, and lets you override certain options at run time.
Because the Options File is now a file instead of a load module, you can create files that are specific to program groups
and identified by the //EZOPTBL DD in your JCL.
NOTE
• You can also use the local overrides that are available through statements such as PARM and REPORT.
• For more information about setting global options, see Updating the Table.
Create an EZTINI File
Creating an EZTINI file lets you bypass the //EZOPTBL DD requirement. We recommend that you create an EZTINI file
using JOB06OP1 that is provided in hlq.CBAAJCL.
133
CA Easytrieve® Report Generator 11.6
Use Migration Utilities
Migration utilities reduce the time needed for migrating the Options Table and printer set definitions. We recommend that
you use the MOV64OPT and MOV64PSD migration utilities that are provided in hlq.CBAAJCL to migrate to Release 11.x.
The migration utilities perform the following tasks:
• MOV64OPT converts a CA Easytrieve Plus Release 6.4 Options Table to release 11.x option file.
• MOV64PSD converts CA Easytrieve Plus Release 6.4 Extended Reporting Printer Definitions (EZTPXRPT load
module) to CA Easytrieve Report Generator Release 11.x.
Configure Your Product
This section describes what you need to do to start CA Easytrieve® Report Generator.
• Configure With CA CSM
• Configure Without CA CSM
Configure With CA CSM
The CA CSM configuration process includes all configuration tasks except for creation of the Printer Set Definition. You
must create this module manually, regardless of whether you are using CA CSM to perform product configuration.
For more information, see Printer Set Definition.
Configure Without CA CSM
This section describes the manual tasks that you perform when configuring your product using CA CSM
The CA CSM configuration process includes all configuration tasks except for creation of the Printer Set Definition. You
must create this module manually, regardless of whether you are using CA CSM to perform product configuration.
Create the Options File and Update Its Settings
CA Easytrieve® Report Generator requires an EZOPTBL options table to execute successfully. You can create this table
and update its settings by running two jobs provided in the CBAAJCL data set.
Follow these instructions if you installed the product from tape or using Pax-Enhanced ESD. CA CSM lets you perform
this task through the Software Configuration Services (SCS) component.
NOTE
If you are upgrading from CA Easytrieve® Report Generator 6.4, you can optionally migrate your existing options
table settings and Printer Set Definition to the current release.
Follow these steps:
1. Execute the JOB06OP1 job in the CBAAJCL data set.
The options table is created and initialized. This job also assembles and link edits the EZTINI module, which contains
the DSN of the options table file. The EZTINI module is required for CA Easytrieve® Report Generator program
execution when the execution JCL does not contain an //EZOPTBL DD statement.
2. Update the settings in the options table by executing the JOB06OP2 job in the CBAAJCL data set.
NOTE
Detailed instructions and information are provided in the member comments.
The options table settings are updated.
134
CA Easytrieve® Report Generator 11.6
Migrate Options Table Settings (from 6.4)
If you are migrating from CA Easytrieve® Report Generator 6.4, you can optionally migrate your existing options table
settings to the current release.
NOTE
Follow these instructions if you installed the product using Pax-Enhanced ESD. CA CSM lets you perform this
task through the Software Configuration Services (SCS) component.
Follow these steps:
1. Execute the JOB06OP1 job in the CBAAJCL data set.
The options table is created and initialized with default option settings.
2. Execute the MOV64OPT job in the CBAAJCL data set.
Your existing options table settings are migrated to the current release.
Migrate Options Table Settings (within 11 versions)
If you are migrating from CA Easytrieve® Report Generator release 11 SP03, release 11 SP04, or release 11.5 to CA
Easytrieve® Report Generator release 11.6, you can optionally migrate your existing options table settings to the current
release.
Follow these steps:
1. Execute the JOB06OP1 job to create a release 11.6 EZOPTBL.
2. Copy the release 11 SP03, release 11 SP04, or release 11.5 EZOPTBL into the new one (via TSO).
Your existing option file settings are migrated to the current release.
EZOPTBL Options Table Settings
If you have set NEWFUNC to N (no) in your CA Easytrieve® Report Generator release 11 EZOPTBL Options Table, you
should copy your CA Easytrieve® Report Generator release 6.4 Options Table module EZTPOPT into your release 11.6
CBAALOAD in order to keep your 6.4 options.
To accomplish this, we recommend a TSO copy or run this job.
//jobcard
//STEP1 EXEC PGM=IEBCOPY
//CAILIB DD DISP=SHR,
// DSN=your.ezt64.CAILIB
//ABAALOAD DD DISP=SHR,
// DSN=your.r116.CBAALOAD
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
COPY INDD=CAILIB,OUTDD=CBAALOAD
SELECT MEMBER=((EZTPOPT,,R))
//*
Printer Set Definition
If you use the Extended Reporting feature of CA Easytrieve® Report Generator, build the Printer Set Definition (PSD). The
PSD contains the definitions for the extended printers used in the application programs.
If you are upgrading from the CA Easytrieve® Report Generator 6.4 release, you can migrate the existing PSD or create a
new one.
135
CA Easytrieve® Report Generator 11.6
If you are upgrading from the CA Easytrieve® Report Generator release 11.x, you do not need to migrate or create a
PSD. All release 11.x PSDs are compatible with the latest release.
Migrate Extended Reporting Printer Set Definition
If you are migrating from CA Easytrieve® Report Generator 6.4 and you use the Extended Reporting feature, you can
optionally migrate your existing Printer Set Definition (PSD) to the current release.
NOTE
The 6.4 PSD is not compatible with the current CA Easytrieve® Report Generator release. You must migrate the
existing 6.4 PSD or create a new one.
To migrate the Extended Reporting Printer Set Definition, execute the MOV64PSD job in the CBAAJCL data set.
The PSD is migrated to a new module that is compatible with this release and link edited.
Create Extended Reporting Printer Set Definition
If you are migrating from CA Easytrieve® Report Generator 6.4 and you use the Extended Reporting feature, you can
create a new Printer Set Definition (PSD).
NOTE
The 6.4 PSD is not compatible with the current CA Easytrieve® Report Generator release. You must migrate the
existing 6.4 PSD or create a new one.
To create the PSD, execute the JOB14PSD job in the CBAAJCL data set.
Activate the 6.4 Compatibility IDMS and IMS Interface Option
Activate the 6.4 Compatibility IDMS or IMS interface option when both of the following are true:
• You plan to use the 6.4 Compatibility feature to run your CA Easytrieve Report Generator programs.
• Those programs access an IDMS database (not by using SQL), an IMS database, or both.
To activate the 6.4 Compatibility option, execute the JOB0764L job in the CBAAJCL data set.
The JOB0764L job link edits the required IDMS and IMS stub modules into the EZTPA00 module in the target library
(CBAALOAD).
Modification for Using IDMS or IMS Only
If you are using only IDMS or only IMS (not both), follow these steps before you run JOB0764L:
1. Open JOB0764L for editing.
2. Locate the following line:
//LK64 EXEC EZT64LK
3. Modify the statement as follows:
For IDMS only:
//LK64 EXEC EZT64LK,LNKDLI=99
For IMS only:
//LK64 EXEC EZT64LK,LNKIDMS=99
4. Save the changes.
136
CA Easytrieve® Report Generator 11.6
Create the DBCS Options Module
If you use the DBCS feature of CA Easytrieve® Report Generator, build the DBCS options module (PSIDBOPT).
This module contains the DBCS Code System definitions that are available for use in CA Easytrieve® Report
Generator application programs.
To create the DBCS Options Module, execute the JOB13DBO job in the CBAAJCL data set.
The PSD is migrated to a new module that is compatible with this release and then link edited.
Activate the Oracle Interface Option
The Oracle interface lets you use CA Easytrieve® Report Generator to process data in an Oracle database by using SQL.
If you use this feature, activate the Oracle interface option.
NOTE
This interface requires you to have the Oracle version of CA Pan/SQL installed and configured appropriately.
To activate the Oracle interface option, execute the JOB15ORA job in the CBAAJCL data set.
The JOB15ORA job link edits the ORASTBL module (from the Oracle SQLLIB) into the CA Easytrieve® Report
Generator Compiler module (EZTCOM) and activates the Oracle interface.
Activate the SUPRA Interface Option
The SUPRA interface lets you use CA Easytrieve to retrieve information from a SUPRA database by invoking SUPRA as
a preprocessor. The preprocessor acts as the Relational Data Manipulation Language (RDML) compiler, taking the place
of the COBOL or PL/I preprocessor. The SUPRA preprocessor converts the RDML into CA Easytrieve source statements
with an expanded CA Easytrieve program as the result.
If you plan to use this feature, activate the SUPRA interface option.
Follow these steps:
1. Execute the JOB10SUP job in the CBAAJCL data set.
This job link edits the CSVILUVL module (from the SUPRA product library) into the target library (CBAALIB).
2. Enter your site-specific parameters in the EZTPSPRA macro, which is found in the JOB11SUA and JOB11SUB jobs in
the CBAAJCL data set.
NOTE
JOB11SUA installs the EZTPSPRA module without using SMP/E. JOB11SUB installs the module using SMP/
E. Choose the job that uses your preferred installation method.
3. Execute the JOB11SUA or JOB11SUB job in the CBAAJCL data set.
This job compiles and link edits the SUPRA preprocessor program (EZTPSPRA) into the target library (CBAALIB).
EZTPSPRA Macro
The EZTPSPRA macro executes when you execute JOB11SUA or JOB11SUB to install the SUPRA preprocessor. Add
your site-specific settings to the parameters before executing the job.
This macro has the following format:
[ { YES } ]
%EZTPSPRA SCHEMA schema-name [ OVERRIDE { } ] +
[ { NO } ]
[ { YES } ]
137
CA Easytrieve® Report Generator 11.6
[ FIELDS maxfields ] [ OPEN { } ] +
[ { NO } ]
[ SCAN start-column THRU end-column ]
• SCHEMA schema-name
Specifies the default name of the schema where the directory entries for the views to be accessed are located.
You can override the default schema-name at execution time by using a PARM on the job EXEC statement. This is
helpful when multiple schemas are used.
There is no default schema-name. For a SUPRA JCL example, see the SUPRA Interface Option section.
• OVERRIDE {YES|NO}
– YES
Overrides the schema-name when you execute the preprocessor.
– NO
Ignores attempts to override the schema name. This is the default.
• FIELDS maxfields
Specifies the maximum number of fields that can exist in a view included by the preprocessor.
If the number of fields in the view exceeds maxfields, an error message is printed and execution stops.
The specified value has an effect on the memory requirement when executing the preprocessor. Each field requires
approximately 110 bytes of storage. Decreasing the value conserves memory. Increasing the value causes more
memory to be used by the preprocessor.
Limits: 1 - 32767
Default: 250
• OPEN {YES|NO}
– YES
Specifies that the preprocessor is to issue open and close functions for the directory files. This is the default.
– NO
Indicates that the open function has been performed by a system task and the preprocessor is not to open and
close the directory files.
• SCAN start-column THRU end-column
– start-column
Specifies the column number where the preprocessor starts to scan for input.
Limits: 1 - 80; must be less than end-column
Default: 1
– end-column
Specifies the column number where the preprocessor stops scanning for input.
Limits: 1 - 80; must be greater than start-column
Default: 72
These values also control the columns used during code generation. Set these values in accordance with the
SCANCOL option.
NOTE
To compile the SUPRA preprocessor, you must define the Options Table with SCAN=(1,72). If your option
differs, rerun JOB11SUA or JOB11SUB as described previously, or assemble a temporary copy of the
options table to be used for the compile of the SUPRA preprocessor.
Activate the TOTAL Interface Option
The TOTAL interface lets you use CA Easytrieve® Report Generator to process data in a TOTAL database. If you plan to
use this feature, activate the TOTAL interface option.
To activate the TOTAL interface option, execute the JOB12TOT job in the CBAAJCL data set.
138
CA Easytrieve® Report Generator 11.6
The JOB12TOT job link edits the DATBAS module (from the TOTAL product library) into the target library (CBAALIB).
Assemble a User Requirements Table for the CA Datacom/DB Option
The CA Datacom/DB option lets you use CA Easytrieve Report Generator to process data in a CA Datacom/DB database.
If you plan to use this option, you must create at least one User Requirements Table (URT). Each URT is linked with a
copy of ETDRVR, creating a module with a user-defined name. For information about using the CA Datacom/DB option,
see CA Datacom/DB Database Processing.
NOTE
You can create multiple URTs. For more information about defining URTs, see the CA Datacom/DB Database
and System Administration section of the CA Datacom Core documentation. You must log into Broadcom
Support to view that section of the documentation.
Follow these steps:
1. Modify the JOB09URT job in the CBAAJCL data set:
– Specify values for the tblnam, update, and usrinfo parameters in the CA Datacom/DB macros.
– Specify a name for the link-edited URT in the MEMBER parameter of the PROC statement.
– Specify the URT name on the LINKURT.SYSLIN DD statement by replacing urtname with the same value you
specified in the MEMBER parameter.
– (Optional) Modify the URTLIB parameter to specify the target library name. (The default target library specified in
the SYSLMOD DD statement is CBAALOAD.)
2. Submit the job.
The ASM step completes with a return code of 0.
The LINKURT step completes with a return code of 4 and the following message:
IEW2454W SYMBOL DBMSCBL UNRESOLVED
The job assembles and link edits the URT.
Language Environment (LE) Considerations
When the CA Easytrieve Report Generator runtime routines are installed, one module (ETCOBSR) is statically link-edited
with the LE runtime option overrides that are required by CA Easytrieve Report Generator. These overrides are distributed
in the form of an object module named ETLEOPTS. In the SMP/E JCLIN for the ETCOBSR module, you can see that
ETLEOPTS is statically linked into module ETCOBSR with the ETCOBST module. If you require additional LE runtime
option overrides for your CA Easytrieve Report Generator jobs, you can add them in either of these ways:
• Change your LE runtime option installation defaults.
• Assemble the overrides into a CEEUOPT object file, and relink ETCOBSR including your new object file in place of
ETLEOPTS.
If you assemble your own CEEUOPT, be sure to include the following LE runtime option overrides:
TRAP=(OFF,NOSPIE),ABTERMENC=(RETCODE),TERMTHDACT(UAIMM)
Macro Libraries
The section provides additional information and the steps that must be executed for some of the macro interfaces.
139
CA Easytrieve® Report Generator 11.6
Macro Library Storage
Macro statements are stored and maintained in a macro library. The MACTYPE entry in the CA Easytrieve® Report
Generator options table (see the Option Tables in Language Reference) specifies the macro library storage access
method.
The types of access methods are listed below, (the letter under the macro library type is the corresponding value to be
used for the MACTYPE option):
Type Description
Panvalet(P) Macros are stored in a CA Panvalet library and maintained
through CA Panvalet utilities.
PDS (OS/390 and z/OS only)(D) Macros are stored in a Partitioned Data Set (PDS) and maintained
through the operating system utilities and TSO.
When creating the PDS macro library, specify the following data
set attributes:
DCB=(RECFM=FB,LRECL=80,BLKSIZE=nnnn
Where nnnn is any multiple of 80.
Endevor(E) Macros are stored in a CA Endevor library and maintained through
CA Endevor.
Security
z/OS provides the capability, through program products such as CA ACF2 and CA Top Secret to secure the entire macro
library against unauthorized access.
Unit Record Exits
CA Easytrieve® Report Generator provides the unit record exit routine capability, which permits all primary input and
output to be processed by user-written exit routines. A SYSIN exit routine provides primary compiler input when an exit
name is specified in the selectable option SINXIT. A SYSPRINT exit routine receives all primary output when an exit name
has been specified in the selectable option SPRTXIT. For more information about the options table, see Using.
Linkage Conventions
The exit routine is loaded at initiation, using the LOAD function of the operating system. When the exit routine is called, it
uses a three-word (SYSIN/SYSIPT) or a four-word (SYSPRINT/SYSLST) parameter list.
You must code exit routines following all of the conventions described in Programming .
SYSIN Exit
The SYSIN exit routine is invoked at compile-time and allows for pre-processing of the source statements that are input to
the compiler.
The SYSIN exit routine places the input record (80 bytes) into the data area pointed to by parameter one. Parameter two
points to a one-word code that is always zero, except at end-of-file when the exit is called with a code value of binary 8.
Parameter three points to a two-word area. The first word is always binary 0. The second word is binary 0 on the first call
to the exit and can be used by the exit to determine first time entry. The contents of the second word are not modified,
thus providing the exit with an anchor for re-entrant coding.
Sample SYSIN Exit Routine
The following is a sample SYSIN exit routine:
140
CA Easytrieve® Report Generator 11.6
SINEXIT CSECT
STM 14,12,12(13) Save registers
LR 11,15 Set base register
USING SINEXIT,11 Addressability
LA 14,0,(0,13) <easy>
save area
LA 13,MYSAVE Exit save area
ST 13,8(0,14) Chain forward
ST 14,MYSAVE+4 Chain backward
...
L 4,0(1) Data area pointer
L 5,4(1) Code area pointer
...
ENTRY1 NOP ENTRY2 First time switch
OI ENTRY1+1,X'FO' Change to unconditional branch
OPEN (SYSIN,INPUT) Open file
...
ENTRY2 GET SYSIN,(4) Get record into data area
B RETURN
...
ENTRY3 CLOSE SYSIN Close the file
LA 0,8 No more input
ST 0,0(5) Indicate EOF
...
RETURN L 13,4(0,13) <easy>
save area
LM 14,12,12(13) Restore EZT Registers
MVI 8(13),X'FF' Indicate unused save area
SR 15,15 Set zero return code
BR 14 Return to <easy>
...
MYSAVE DC 18A(0) Exit save area
...
SYSIN DCB DISORG=PS,DDNAME=SYSIN,MACREF=GM, *
EODAD=ENTRY3,LRECL=80,RECFM=FB
...
END
SYSPRINT Exit
The SYSPRINT exit routine receives a pointer to the data to be printed in parameter one. The second parameter has a
pointer to a one-word code, which always has the value of binary 4, except at end-of-file, when the exit is called with a
code value of binary 8.
Parameter three points to a two-word area. The first word is binary 0 during compilation and binary 4 during execution.
The second word is binary 0 on the first call to the exit and can be used by the exit to determine first time entry. The
contents of the second word are not modified, thus providing the exit with an anchor for reentrant coding. Parameter four
points to a one-word area that contains the binary length of the print line as defined for the Line Size option in the Printer
Profile Definition +1.
Sample SYSPRINT Exit Routine
The following is a sample SYSPRINT exit routine:
141
CA Easytrieve® Report Generator 11.6
SPRTEXIT CSECT
STM 14,12,12(13) Save registers
LR 11,15 Set base register
USING SPRTEXIT,11 Addressability
LA 14,0(,13) <easy>
save area
LA 13,MYSAVE Exit save area
ST 13,8(,14) Chain forward
ST 14,MYSAVE+4 Chain backward
L 4,0(1) Data area pointer
L 5,4(1) Code area pointer
...
ENTRY1 NOP ENTRY2 First time switch
OI ENTRY1+1,X'FO' Change to unconditional branch
OPEN (SYSPRINT,OUTPUT) Open file
...
Entry2 L 5,0(5) Get code
CL 5,=F'8' Q.EOF yet
BE ENTRY3 ..YES, go close
...
PUT SYSPRINT,(4) Print the line
B RETURN
ENTRY3 CLOSE SYSPRINT
RETURN L 13,4(,13) <easy>
save area
LM 14,12,12(13) Restore registers
MVI 8(13),X'FF' Indicate unused save area
SR 15,15 Zero return code
BR 14 Return to <easy>
MYSAVE DC 18A(0)
SYSPRINT DCB DSORG=PS,DDNAME=SPRINT,MACRF=PM, *
RECFM=FBA,LRECL=133
END
Configure Your System
This section describes how to configure CA Easytrieve® Report Generator for a UNIX, Linux for zSeries, and Windows
command line-based system, or for a z/OS system.
This section discusses the following configuration tasks:
• Setting Environment Variables
• Updating the Table
Setting Environment Variables
This section describes environment variables for UNIX, Linux for zSeries, and Windows only and provides examples.
This article includes the following information:
142
CA Easytrieve® Report Generator 11.6
Set PATH Variable
You may optionally add the directory where you installed CA Easytrieve® Report Generator to your system’s PATH
variable. You should do this when you intend to execute a system executable from a command prompt. With PATH set,
you can be current in a directory containing your source and execute the compiler, etc.
EZTPATH (UNIX and Linux for zSeries Only)
The EZTPATH environment variable defines the path to the components, options table, and alternate collating sequence
files that you can use in CA Easytrieve® Report Generator.
In UNIX and Linux for zSeries, each directory defined in EZTPATH generates an L directive for link-editing.
EZTPATH must contain the directory where you installed CA Easytrieve® Report Generator. EZTPATH can also contain
the directories where the Ingres or other database object libraries reside when these products are used. It can also
contain additional directories to use customized options tables or alternate collating sequence files.
Examples
For Bourne and KORN shell, place EZTPATH in the .profile for the users who need access to CA Easytrieve® Report
Generator. For example:
EZTPATH=path_name
export EZTPATH
For C shell, place EZTPATH in the .login for the users who need access to CA Easytrieve® Report Generator. For
example:
setenv EZTPATH path_name
The path_name should contain a list of directory names, separated by colons. For example, if CA Easytrieve® Report
Generator is installed in /ezt/bin and you want to use the options table or alternate collating sequence table in the group
directory /admin/ezt for Bourne and KORN shell users, enter the following:
EZTPATH=/admin/ezt:/ezt/bin
export EZTPATH
For C shell, enter the following:
setenv EZTPATH /admin/ezt:/ezt/bin
To link a program that uses Ingres, C-ISAM, or other databases in UNIX and Linux for zSeries, you can add the directories
that contain their shared or archived libraries to EZTPATH. For more information about each DBMS, see Compiling and
Linking Your Program. In Windows, programs are not linked so this step is not required.
WARNING
CA Easytrieve® Report Generator always searches for the options table and alternate collating sequence tables
in the current directory.
NOTE
If you place the options table or the alternate collating sequence table in the directory where you installed CA
Easytrieve® Report Generator, the options table and alternate collating sequence table are deleted the next time
you install CA Easytrieve® Report Generator into the same directory.
143
CA Easytrieve® Report Generator 11.6
EZTSQL (UNIX and Linux for zSeries Only)
The EZTSQL environment variable defines which SQL interface to use during a compile or link operation for a program
using SQL facilities. Valid values are:
ingres
openingres
oracle
db2
odbc
EZTLIBS (UNIX and Linux for zSeries Only)
The EZTLIBS environment variable defines the libraries needed to resolve any unresolved references from CA
Easytrieve® Report Generator to DBMSs. CA Easytrieve® Report Generator automatically adds its own libraries to the
command that is passed to the linker. You must supply the libraries required to resolve all references to DBMSs (such as
Ingres and Oracle).
The EZTLIBS variable should contain a list of libraries or object files, separated by spaces. CA Easytrieve® Report
Generator adds the parameters, specified in EZTLIBS, to the end of the command passed to the linker. If you did not add
the DBMS directory to EZTPATH, you should include an L directive to it in EZTLIBS.
For more information about each DBMS, see Compiling and Linking Your Program.
Examples
For Bourne and KORN shell, place EZTLIBS in the .profile for the users who need access to CA Easytrieve® Report
Generator. For example:
EZTLIBS="-llib1 -llib2"
export EZTLIBS
For C shell, place EZTLIBS in the .login for the users who need access to CA Easytrieve® Report Generator. For
example:
setenv EZTLIBS "-llib1 -llib2"
EZTOPTS (UNIX, Linux for zSeries, and Windows Only)
You can use an EZTOPTS environment variable to specify frequently used parameters for the EZT command. The EZT
command reads command line parameters from the EZTOPTS environment variable and combines them with parameters
specified on the EZT command line.
The syntax for the EZTOPTS environment variable is as follows:
[ pre-options ] [ | post-options ]
The values of pre-options are the command line parameters that ezt processes before the parameters specified on the
command line. The values of post-options are options that are processed after the command line parameters. A vertical
bar separates the two sets of parameters.
For example, using the C shell notation for setting environment variables, the following commands:
setenv EZTOPTS "-v | -I /usr/usr1/macros"
144
CA Easytrieve® Report Generator 11.6
ezt -I /usr/usr1/test/macros browse.ezt
are equivalent to:
ezt -v -I /usr/usr1/test/macros browse.ezt -I /usr/usr1/macros
By placing the macro search directory /usr/usr1/macros after the vertical bar in EZTOPTS, you ensure that any macro
directories specified on the command line are searched first. By placing the macro search directory before the vertical bar,
CA Easytrieve® Report Generator searches /usr/usr1/macros before any macro directories specified on the command
line.
For Windows, the recommended approach is to include this macro only within the Environment Manager. For more
information, see Workbench Tools and Utilities
EZTDLLS (Windows Only)
You can use an EZTDLLS environment variable to name a list of dynamic load libraries (DLLs) to be loaded when CA
Easytrieve® Report Generator tries to locate dynamically-loaded user-written subroutines.
Setting this value as an environment variable establishes a global value. During application development, we recommend
that you use the Environment Manager to control the location of dynamic libraries. See the following sections and
Workbench Tools and Utilities for information.
Operating System-Specific Variables in UNIX or Linux for zSeries
Your operating system can use an environment variable to define the path list the loader uses to locate shared objects
when an executable links with shared objects. This variable is typically named SHLIB_PATH (HP-UX), LIBPATH (AIX),
LD_LIBRARY_PATH (Solaris or Linux for zSeries). For more information, see your operating system documentation.
During compilation, this variable must be set to the location of the CA Easytrieve® Report Generator compiler shared
library: libeztcom.sl or libeztcom.so. During execution of a CA Easytrieve® Report Generator program, the variable must
contain both the location of the CA Easytrieve® Report Generator runtime shared libraries and any other shared libraries
that contain called programs.
Dynamic Control of the Windows Environment
Use the Environment Manager function to dynamically control environment variables. For more information, see
Workbench Tools and Utilities.
Updating the Table
To update the options table, type site option keywords and their corresponding values. For each site option you want to
update, you must supply a separate line with the keyword and its value. You can leave blank lines between input lines. A
double slash (//) begins a comment. Comments terminate at the end of the line.
[KEYWORD {value}] [// comment text]
This article includes the following information:
Site Option Syntax
ETOPLOAD requires as input a file containing card images that contain the options you want to update and their updated
values. The following pages of this section show each Site Option, its internal name, and the valid values. You should
refer to those pages when specifying input to these options.
145
CA Easytrieve® Report Generator 11.6
Each card image can update one (and only one) Site Option. Code the internal name of the option as the first word on the
card image. Code the value, following at least one space on the card image.
NOTE
Some option values are case-sensitive on some platforms.
Several Site Option update card images are sampled below. The following are sample option cards.
ABEXIT N
COMPNME ABC COMPANY, INC.
DMAP Y
LONGDTE N
PMAP N
Following the processing of the last input record, etopload writes all of the current options both to a listing and to an output
file. The output file can be used later to rebuild your site options after installing a new version of CA Easytrieve Report
Generator or if they happen to be destroyed.
Printer Profiles
To add or update a Printer Profile, use the following syntax examples.
NOTE
For information about printer profile options, see Printer Profile Definition.
For System Printers
PRINTER id S linesize pagesize class node userid EXTENDED-ID extid
Example:
PRINTER PRINTER S 132 58 A RSCS SMITH
For Terminal Printers
PRINTER id T linesize pagesize form-feed eject-after eject-before + termid EXTENDED-ID extid
Example:
PRINTER PRINTER T 80 58 N N N RMT1
For File Output
PRINTER id F linesize pagesize sysname EXTENDED-ID extid
Example:
PRINTER PRINTER F 132 58 SYSPRINT
Create or Maintain the Options Table Using the etopload Utility
Use the etopload utility to create or maintain the options table.
Follow these steps:
1. Enter the following on the command line:
For UNIX, Linux for zSeries, and Linux PC:
etopload -b -l >ezoptbl.def</dev/null
For Windows:
etopload -b -l >ezoptbl.def<nul
146
CA Easytrieve® Report Generator 11.6
This command invokes the etopload utility that builds a default options table that is named EZOPTBL and produces a
sequence of options in ezoptbl.def.
NOTE
For CA Easytrieve Report Generator on Windows, you can also use the Configuration Manager to create
and maintain the options table.
2. Specify the options that you want by editing ezoptbl.def. For more information about the options,
see OptionCategories.
3. Update the options table by typing the following command on the command line:
etopload -b <ezoptbl.def
The EZOPTBL options table in the current directory is updated.
Syntax for the etopload Utility
Specify etopload as follows:
etopload [options] [path]
The valid options are:
• -b -- If the site options table does not exist, create it. Otherwise, update it. Input is expected on stdin.
• -h -- Displays help information.
• -l -- Displays the site options table to stdout after all updates are applied.
The default is -h.
If the path is not specified, EZOPTBL is the default.
Submitting a Run of ETOPLOAD Using JCL
This section describes how to update the CA Easytrieve Report Generator options table on the mainframe using the
ETOPLOAD program through batch JCL.
There are two utility functions available for use with the batch update program, ETOPLOAD. These utility functions are not
necessary for updating an existing options table. To use these functions, the command would be specified for the SYSIN
instead of the Options Update cards.
• Create File
The Create File command rebuilds the site options with the default values supplied with CA Easytrieve Report
Generator.
follow these steps:
CREATEFILE
• Read File
The Read File command reads the existing site options and writes the records to an output file. This output file can be
used later to rebuild your site options after installing a new version of CA Easytrieve Report Generator or if your site
options are destroyed.
follow these steps:
READFILE
READFILE must be the first record in the input file.
z/OS JCL Example
The following code is z/OS site option update JCL:
//jobname JOB accounting.info
//UPDATE EXEC PGM=ETOPLOAD
147
CA Easytrieve® Report Generator 11.6
//STEPLIB DD DSN=EZT.loadlib,DISP=SHR
//SYSPRINT DD SYSOUT=A
//OUTPUT DD SYSOUT=A
//EZOPTBL DD DSN=your.EASYTRIEVE.EZOPTBL,DISP=SHR,
//SYSUT2 DD DISP=(,CATLG),DSN=EZT.option.output,
// SPACE=(TRK,(1,1),RLSE),
//SYSIN DD *
Site Option Update Cards
/*
//
NOTE
The EZOPTBL DD statement must be specified while running an ETOPLOAD job. This is in contrast to when
you are compiling or executing a CA Easytrieve Report Generator program where the EZOPTBL DSN can be
determined without the use of an EZOPTBL DD statement in the JCL.
Option Categories
Options are categorized as follows. Click each link for information about the options in the category.
• Compiler Options are general program compilation options that include listing options and compile-time debugging
aids.
• Execution Options are general program execution options.
• Environmental Options are general environmental options.
• Sort Options control how sort uses storage and sort messages.
• SQL Options control SQL program compilation and execution.
• IDMS Options control CA IDMS processing.
• Report Options are related to the Report Processing Facility.
• Mask Options are site-defined edit masks that are used for formatting numeric data.
• International Options let you customize the product for international use. Includes data and time display, currency
symbol used, and decimal point character.
• Printer Profile Definition maintains the destination to which reports and messages are routed.
Alphabetical Listing of Options
In addition to listing all the options, the following table indicates when the option is effective.
A compile-time option is effective only during the compilation or its value is bound into link-edited modules. Previously
compiled programs are affected by a change in the option only when the program is recompiled.
An execution-time option can be changed after compiling a link-edited program. The new option takes effect during
subsequent execution. You can change execution-time options that the PARM statement overrode at compilation only by
updating the PARM statement and recompiling.
Option Description Effective at Compile Time Effective at Execution Time
ABEXIT Use Abend Exit no yes
ACROSS Number of labels across yes no
ALTSEQ Alternate sequence table no yes
ALTSEQU Use alternate sequence no yes
AMODE31 Allocate storage above 16 meg no yes
line
ASCSIGN Zoned numeric format yes no
148
CA Easytrieve® Report Generator 11.6
BIND DB2 BIND yes no
BLOCK0 Sets usage of system- no yes
determined blocksize
BUFNO Number of Sequential I/O no yes
Buffers (TSO and CMS only)
CALCDUP Duplicate CALC record keys yes no
CLIST Condensed map yes no
COMPNME Company yes no
DATE Date format no yes
DATESEP Date separator character no yes
DISPPAGE Display page size yes no
DMAP Data map yes no
DOWN Number of lines on a label yes no
DTLCTL Print control fields on detail lines yes no
ENVIRON Specify the default execution yes no
environment
ERORSYM Error message symbol yes no
FASTSRT Fast sort no yes
FINALWRD Word used for FINAL yes no
FLDCHK Unavailable fields yes no
FLDMAX Maximum field size yes no
FLOW Trace statement flow yes no
FLOWSIZ Number of trace entries no yes
IDDCOMP IDD COMP field type yes no
LABLSIZ Print positions on a label yes no
LINESIZ Characters on a line yes no
LISTPRM Parms/summary yes no
LISTFIL File Statistics no yes
LISTUC Uppercase yes no
LONGDTE Use SYSDATE-LONG on yes no
reports
MAC#LIB Number of libraries to be yes no
searched if MACTYPE is P (CA
Panvalet) or E (CA Endevor)
MACDDN Ddname of macro library yes no
MACMOD Name of the interface routine yes no
when MACTYPE is P
MACTYPE Type of macro library support yes no
MONEY Currency symbol yes no
MSGID Message destination ID no yes
MTVSERR Empty VSAM input file is an I/O no yes
error
NEWFUNC Selects compiler mode of yes no
operation
149
CA Easytrieve® Report Generator 11.6
NEWPAGE New page for every label yes no
NUMWORK Number of work areas no yes
PAGESIZ Lines on a page yes no
PAGEWRD Word used for PAGE yes no
PANSQL CA Pan/SQL prefix no yes
PMAP Program map yes no
PREPNME Access module/plan yes no
PRINTID Report destination ID no yes
RUNSYM Runtime yes no
SCANCOLE End column yes no
SCANCOLS Start column yes no
SEPOTDC Decimal separator character yes no
SEPOTTH Thousands separator character yes no
SINXIT SYSIN Exit Routine name yes no
SKIP Lines to skip before detail yes no
SORTMAX Sort use available storage no yes
SORTMSG Level of message output no yes
SORTMSR Route sort messages no yes
SORTNAME Sort program name no yes
SORTPRT DDNAME for sort messages no yes
SORTRLS Amount released after sort no yes
SORTSIZ Maximum sort storage size no yes
SORTWRK Sort work device type no yes
SPACE Number of spaces between yes no
fields
SPREAD Spread columns as far as yes no
possible
SPRTXIT SYSPRINT Exit module name no yes
SQLSYNTX Type of syntax checking for SQL yes no
SSID Database name yes no
STATE Save statement number yes no
STDERR Standard error destination ID no yes
STDOUT Standard output destination ID no yes
STORCHK Check storage areas no yes
SUMCTL Print control fields on summary yes no
lines
SUMSPAC Additional positions for summed yes no
fields
TALYSIZ Size of TALLY field yes no
TBLMAX Maximum table entries no yes
TIMESEP Time separator character no yes
TITLSKP Lines to skip after title yes no
150
CA Easytrieve® Report Generator 11.6
TOTALWRD Word used for TOTAL yes no
UPDTDLI DLI updates yes yes
UPDTIDD Update IDD with compilation yes no
stats
UPDTIDM CA IDMS updates allowed yes yes
UPDTVS VS updates yes yes
VERFILE IDD FILE version yes no
VERREC IDD RECORD version yes no
VERSCHM IDD SCHEMA version yes no
VFMDEV VFM overflow device no yes
VFMSPAC VFM core storage (CICS only) no yes
USERMSK Mask identifier yes yes
WARNSYM Warning message symbol yes no
WKDSNPF Work data set prefix no yes
WORKFILE Use Report Workfiles instead of yes no
VFM
WORKFSPA Number of cylinders for each no yes
Report Workfile
XREF Compile cross-reference yes no
Compiler Options
This article describes the Compiler options that you can specify in the options table. The options are listed in categories.
Source Statement Scan Columns
SCANCOLS - Start Column
SCANCOLS establishes the starting column number that is scanned for CA Easytrieve Report Generator source input.
This option is in the Source Statement Scan Columns section in Configuration Manager.
This is a compile-time option. You cannot override this value during program compilation.
SCANCOLS nn
• Limits: 1 - 80
• Default: 1
SCANCOLE - End Column
SCANCOLE establishes the ending column number scanned for CA Easytrieve Report Generator source input. This
option is in the Source Statement Scan Columns section in Configuration Manager.
This is a compile-time option. You cannot override this value during program compilation.
SCANCOLE nn
• Limits: 1 - 80 and greater than SCANCOLS
• Default: 72
151
CA Easytrieve® Report Generator 11.6
Syntax Check Locator Symbols
WARNSYM - Warnings
WARNSYM specifies the symbol that the product uses on warning messages to identify the word causing the flagged
condition. Enter any single character. This option is in the Syntax Check Locator Symbols section in Configuration
Manager.
This is a compile-time option. You cannot override this value during program compilation.
WARNSYM x
• Default: +
ERORSYM - Errors
ERORSYM specifies the symbol the product uses on error messages to identify the word causing the flagged
condition. Enter any single character. This option is in the Syntax Check Locator Symbols section in Configuration
Manager.
This is a compile-time option. You cannot override this value during program compilation.
ERORSYM x
• Default: $
ASCSIGN - Zoned Numeric Sign
ASCSIGN specifies which system to use to create zoned numeric fields. All systems are valid upon input. This option is
only supported in Windows, UNIX, and Linux for zSeries environments. z/OS always uses the D value.
This is a compile-time option. You cannot override this value during program compilation.
ASCSIGN {D|2|7|H}
• D
Zoned numeric fields are in EBCDIC. The zone portion of a digit is a 0xF0 unless the digit is the last digit of a negative
value. The zone portion of the last digit of a negative value is 0xD0.
• 2
Zoned numeric fields are in ASCII. The zone portion of a digit is a 0x30 unless the digit is the last digit of a negative
value. The zone portion of the last digit of a negative value is 0x20. This is the default.
• 7
Zoned numeric fields are in ASCII. The zone portion of a digit is a 0x30 unless the digit is the last digit of a negative
value. The zone portion of the last digit of a negative value is 0x70.
• 5
Zoned numeric fields are in NETCOBOL ASCII format. The zone portion of a digit is a 0x30 unless the digit is the last
digit of a negative or positive signed value. In those cases, the zone portion of the last digit will be: 0x50 for a negative
value, or 0x40 for a positive value.
• H
Zoned numeric fields are in ASCII. The zone portion of a digit is a 0x30 unless the digit is the last digit of a negative
value. The zone portion of the last digit of a negative value is the ASCII translation of the EBCDIC negative digit. See
the following table for values.
Digit EBCDIC "H" ASCII Display Character
0 0xD0 0x7D }
1 0xD1 0x4A J
152
CA Easytrieve® Report Generator 11.6
2 0xD2 0x4B K
3 0xD3 0x4C L
4 0xD4 0x4D M
5 0xD5 0x4E N
6 0xD6 0x4F O
7 0xD7 0x50 P
8 0xD8 0x51 Q
9 0xD9 0x52 R
Listing Control Options
LISTUC - Uppercase
LISTUC specifies whether the compilation listing is translated to uppercase characters. Usually, the source statements are
printed as they are coded. Messages that are inserted into the program statements are in lowercase. This option is in the
Listing Control Options section in Configuration Manager.
This is a compile-time option. You cannot override this value during program compilation.
LISTUC {Y|N}
• Y
Translates to uppercase if printer does not support lowercase.
• N
Do not translate to uppercase. This is the default.
DMAP - Data Map
DMAP specifies whether a data map of the files and fields is produced in the program as a result of a compilation. This
option is in the Listing Control Options section in Configuration Manager.
This is a compile-time option. You can override this value with PARM DEBUG DMAP.
DMAP {Y|N}
• Y
Produces the data map.
• N
Suppresses the DMAP. This is the default.
PMAP - Program Map
PMAP specifies whether a program map of the program's generated code is produced as a result of a compilation. This
option is in the Listing Control Options section in Configuration Manager.
This is a compile-time option. You can override this value with PARM DEBUG PMAP.
NOTE
PMAP Y and CLIST Y are mutually exclusive options.
PMAP {Y|N}
• Y
Produces the program map.
• N
153
CA Easytrieve® Report Generator 11.6
Suppresses the PMAP. This is the default.
CLIST - Condensed Map
CLIST specifies whether a condensed program map of the program's generated code is produced as a result of a
compilation. This option is in the Listing Control Options section in Configuration Manager.
This is a compile-time option. You can override this value with PARM DEBUG CLIST.
NOTE
CLIST Y and PMAP Y are mutually exclusive options.
CLIST {Y|N}
• Y
Produces the condensed program map.
• N
Suppresses the CLIST. This is the default.
LISTPRM - Parms/Summary
LISTPRM specifies whether a summary of the compilation is produced. The summary contains the parameters that are in
effect during the compilation. This option is in the Listing Control Options section in Configuration Manager.
This is a compile-time option. You can override this value with PARM LIST PARM.
LISTPRM {Y|N}
• Y
Produces the summary.
• N
Suppresses the summary. This is the default.
XREF - Name Cross-Reference
XREF specifies whether a name cross-reference of the compilation is produced. This option is in the Listing Control
Options section in Configuration Manager.
This is a compile-time option. You can override this value with the DEBUG XREF parameter of the PARM statement.
XREF {L|S|N}
• L (long)
Produces a long cross-reference that includes unreferenced names.
• S (short)
Produces a short cross-reference that only includes referenced names.
• N (no)
Suppresses the XREF. This is the default.
COMPNAME - Company
COMPNME specifies the company name to center in the title area of the compilation listing. This option is in the Listing
Control Options section in Configuration Manager.
This is a compile-time option. You cannot override this value during program compilation.
COMPNME company name
154
CA Easytrieve® Report Generator 11.6
• Limits: 50 characters
• Default: COMPUTER ASSOCIATES, INC. FIELD INSTALLATION.
Syntax Control Options
FLDCHK - Unavailable Fields
FLDCHK specifies whether data references to each field are validated during execution. A data reference is invalid if a
field was referenced in a file that has no active record. An invalid reference can cause a program check or a reference to
invalid data. This option is in the Syntax Control Options section in Configuration Manager.
This is a compile-time option. You can override this value with PARM DEBUG NOFLDCHK.
FLDCHK {Y|N}
• Y
Validates references. This is the default.
• N
Suppresses reference validation.
Macro Library Control Options
MACTYPE - Macro Library Type (z/OS Only)
MACTYPE specifies the type of macro library support. This option is on the Macros tab in Configuration Manager.
This is a compile-time option for z/OS only.
MACTYPE {P|E|N|D}
• P
Specifies CA Panvalet.
• ESpecifies CA Endevor
• N
Specifies none.
• D
Specifies PDS. This is the default.
MACDDN - Macro DD Name (z/OS Only)
MACDDN indicates the DD name used by the standard CA Easytrieve Report Generator macro library facilities to
reference the desired macro library. This option is on the Macros tab in Configuration Manager.
This is a compile-time option for z/OS only.
MACDDN xxxxxxxx
• Limits: Up to 8 characters. If the MACTYPE option is P, (Panvalet), the MACDDN value can be no longer than 5
characters. If the MACTYPE option is E, (Endevor), the MACDDN value can be no longer than 7 characters.
• Default: PANDD
MAC#LIB - Number of Libraries (z/OS Only)
MAC#LIB specifies the number of CA Panvalet or CA Endevor libraries to be searched if the CA Panvalet or CA Endevor
macro library support is used. This value is used as a suffix to the name specified by MACDDN. This option is on the
Macros tab in Configuration Manager.
155
CA Easytrieve® Report Generator 11.6
This is a compile-time option for z/OS only. No override is available.
MAC#LIB n
• Limits: 1-9
• Default: 1
Example
MAC#LIB is specified as follows:
MACDDN = PANDD
MAC#LIB = 2
In the JCL, two ddnames are:
PANDD1
PANDD2
MACMOD - PANVALET Module Name (z/OS Only)
When the MACTYPE is P the MACMOD modname (or Macro Library Access Module) can be specified to identify the
interface routine.
This is a compile-time option for z/OS only.
MACMOD modname
• Default: PANMODI
Other Options
NOTE
These options are not available in the Configuration Manager.
NEWFUNC - New Functional Mode (z/OS only)
The NEWFUNC option specifies whether to use the current version of the compiler or the Release 6.4 (Compatibility
Mode) compiler to compile your CA Easytrieve Report Generator programs. This option does not have any impact on link-
edited CA Easytrieve Report Generator application programs.
This is a compile-time option for z/OS only. There is no PARM statement override.
NEWFUNC {Y|N}
• Y
Compiles and runs your programs using the latest product release thereby providing all new functionality therein. This
is the default.
• N
Compiles and runs your programs using the compatibility mode of CA Easytrieve Plus. This feature provides you with
more control over the process of moving your applications to CA Easytrieve Report Generator Version 11.0 and above.
SINXIT - SYSIN Exit Routine (z/OS only)
SINXIT specifies the name of a user supplied SYSIN exit routine. The module name must be a valid program name. The
SYSIN Exit Routine is called at compile time only to allow pre-processing of Compiler input source statements. More
information about the SYSIN exit capability can be found in Installing in the Unit Record Exits section.
This is a compile-time option for z/OS only. There is no PARM statement override.
156
CA Easytrieve® Report Generator 11.6
SINXIT xxxxxxxx
• Default: No exit name.
RUNSYM - Runtime Message ID (z/OS only)
RUNSYM specifies the symbol that the product uses on run time messages to identify the word that is causing the
condition being flagged. Type any single character.
This is a compile-time option for z/OS only. You cannot override this value during program compilation.
RUNSYM x
• Default: @
UPDTVS - VSAM Updates (z/OS only)
UPDTVS specifies whether or not VSAM file updates are allowed. The ability to update VSAM files is checked at different
times depending on the FILE statement parameters specified. If SEQUENTIAL, INDEXED, or RELATIVE is specified on
the FILE statement, the program is checked during execution. If VS is specified on the FILE statement, the program is
checked during compilation. The program is checked at different times because SEQUENTIAL, INDEXED, and RELATIVE
do not necessarily apply to VSAM files, and, therefore, these files cannot be checked until the program executes.
This is a compile-time and an execution-time option for z/OS only.
UPDTVS {Y|N}
• Y
Specifies that VSAM file updates are permitted. You cannot override this value during program compilation.
• N
Specifies that VSAM file updates are not permitted. This is the default.
NOTE
The VS parameter of the FILE statement is maintained for syntax compatibility with older versions of CA
Easytrieve Report Generator.
DDIVRND - Round or Truncate Division Result
DDIVRND specifies whether the result of a division operation is rounded or truncated when the number of decimal places
in the result exceeds the number of decimal places that are defined for the field.
This is a compile-time option.
DDIVRND {Y|N}
• Y
The result is rounded.
• N
The result is truncated. This is the default.
NOTE
In the following examples, WS-PERCENT-P1 is defined as a 7-byte packed decimal field with 6 decimal places.
The actual result of 29 divided by 266.91 with nine decimal places is 0.108650856.
Example 1: DDIVRND is set to N
In this example, the lowest three decimal places of the result are dropped, as shown in the displayed result.
DEFINE WS-PERCENT-P1 W 7 P 6
157
CA Easytrieve® Report Generator 11.6
WS-PERCENT-P1 = (29 / 266.91 )
DISPLAY '** NOT ROUNDED-P1: ' WS-PERCENT-P1
The displayed result is:
** NOT ROUNDED-P1: .108650
Example 2: DDIVRND is set to Y
In this example, the sixth decimal place value of the result (zero) is rounded up to 1 as shown in the displayed result,
because the seventh decimal place value is 8.
WS-PERCENT-P1 ROUNDED = (29 / 266.91 )
DISPLAY '** ROUNDED-P1: ' WS-PERCENT-P1
The displayed result is:
** ROUNDED-P1: .108651
STRICTQU - Strict Qualifier
Specifies whether a message is issued when the compiler encounters an unqualified field name. When this occurs, default
qualification is used to determine which field should be referenced.
This is a compile-time option. There is no PARM statement override.
STRICTQU {W|N|E}
• W
The program is compiled and a warning message is issued that states which file was used to qualify the field. This is
the default.
• N
The program is compiled. No warning or error message is issued.
• E
The program is not compiled and error message EZTC0644E: MORE QUALIFICATION REQUIRED is issued.
NOTE
For more information about data references and default qualification, see Define Files and Fields.
Example
In the following code, the programmer intends for the file status of PERSONAL to be checked:
FILE IDXF F(4)
IDX 1 4 B
FILE PERSONAL RELATIVE F 150
%PERSNL
JOB INPUT IDXF
READ PERSONAL KEY IDX STATUS
IF FILE-STATUS = 0
DISPLAY IDX +2 EMP# +2 EMPNAME
ELSE
STOP
END-IF
Because FILE-STATUS is not qualified, the following message is issued if STRICTQU is set to W:
strictqu.ezt: Line 7 Col 8: W743: File IDXF used to qualify FILE-STATUS
158
CA Easytrieve® Report Generator 11.6
Execution Options
This article describes the following Execution options that you can configure in the options table:
AMODE31 (z/OS only)
AMODE31 specifies the location of where memory is to be allocated during the execution of the CA Easytrieve Report
Generator application program. Storage allocation below the 16meg line is required if the application program calls (or
uses as a FILE EXIT) a 24-bit subprogram.
This is an execution-time option for z/OS only. You can override this value through PARM CALL(AMODE31|AMODE24).
AMODE31 {Y|N}
• Y
Allows all possible memory allocations to be made above the 16meg line. This is the default.
• N
Causes all possible memory allocations to be made below the 16 MB line.
BLOCK0 (z/OS only)
BLOCK0 specifies whether a system-determined block size is used for files that do not have logical record length and
block size coded. A zero is passed to the operating system that determines the optimum block size. This feature should
be used only if your operating system supports the use of the IBM system-determined block size. Override is through the
BLOCKSIZE parameter of the FILE statement.
This is an execution-time option for z/OS only. There is no PARM statement override.
BLOCK0 {N|D|P|A}
• N
Indicates that the system does not determine the block size for data sets. It must be specified through the JCL or FILE
statement.
• D
Indicates that the system determines the block size for disk and tape data sets. DSORG does not have to be coded in
the JCL with this option.
• P
Indicates that the system determines the block size for PRINTER data sets.
• A
Indicates that the system determines the block size for disk, tape and PRINTER data sets.
FLOWSIZ - Flow Table Size
FLOWSIZ specifies the number of trace entries available for the FLOW option. The table of trace entries is used only
when FLOW is set to Y. Each entry requires 2 bytes of storage. You can override this value with the DEBUG FLOWSIZ
parameter of the PARM statement.
This is an execution-time option.
FLOWSIZ nnnn
• Limits: 1 - 4096
• Default: 100
159
CA Easytrieve® Report Generator 11.6
LISTFIL - File Statistics
LISTFIL specifies whether file statistics are produced at the completion of each activity during execution. The statistics are
written to STDERR.
This is an execution-time option. You can override this value with PARM LIST FILE.
LISTFIL {Y|N}
• Y
Produces the statistics.
• N
Suppresses the statistics. This is the default.
STATE - Save Statement Number (z/OS only)
STATE specifies whether to maintain the statement number of the last statement executed. STATE or FLOW (see Trace
Program Flow) must be set to Y for the last statement number to appear on execution-time diagnostics messages.
This is an execution-time option for z/OS only. You can override this value through PARM DEBUG STATE.
STATE {Y|N}
• Y
Saves the statement number. This is the default.
• N
Does not save the statement number.
STORCHK - Check Storage Areas (z/OS only)
STORCHK specifies whether acquired storage is periodically validated. This is usually done at the direction of CA Support
to debug storage problems.
This is an execution-time option for z/OS only. You cannot override this value during program execution.
STORCHK {Y|N}
• Y
Checks storage areas.
• N
Does not check storage areas. This is the default.
FLOW - Trace Statement Flow (z/OS only)
FLOW specifies whether the product traces statement execution. FLOW or STATE (see Save Statement Number) must be
set to Y for the last statement number to appear in execution-time diagnostics messages.
This is an execution-time option for z/OS only. You can override this value through PARM DEBUG FLOW.
FLOW {Y|N}
• Y
Saves the statement numbers in a table for display upon abnormal termination.
• N
Does not save the statement numbers. This is the default.
160
CA Easytrieve® Report Generator 11.6
ABEXIT - Use Abend Exit (z/OS only)
ABEXIT specifies the type of processing that is performed when a program abnormally terminates.
This is an execution-time option for z/OS only. You can override this value through the ABEXIT parameter of the PARM
statement.
ABEXIT {S|P|N}
• S (Snap)
Tells the product to intercept any program checks and produce an Error Analysis Report. This is the default.
• P (nosnaP)
Performs the same function as S except that the CA Easytrieve Report Generator storage areas are not dumped.
• N (No)
Indicates that the product should not process any program checks.
TBLMAX - Maximum Table Entries (z/OS only)
TBLMAX specifies the maximum number of entries for a table that is loaded from an external file (not instream). If the
value you specify for TBLMAX is excessively high, then the total amount of storage required for CA Easytrieve Report
Generator is inflated. If the value is too low, then the product issues a diagnostic message when the file is loaded.
This is an execution-time option for z/OS only. You can override this value through the TABLE parameter of the table FILE
statement for particularly large tables.
TBLMAX nnnnn
• Limits: 0 - 32767. You should specify a value that is adequate for 90-95% of the tables used.
• Default: 256
NOTE
Although this option is still accepted, it is ignored and reserved for future use.
FLDMAX - Maximum Field Size (z/OS only)
FLDMAX specifies the maximum size for a working storage field or a file buffer permitted at compile time. The compiler
generates a syntax error if the total size of a working storage field (field length multiplied by number of occurrences)
exceeds this value. The value for FLDMAX is specified in kilobytes (K). The actual value used is eight bytes smaller than
the number of kilobytes specified to allow for storage header information.
This is an execution-time option for z/OS only.
FLDMAX nnnnn
• Limits (TSO): maximum 32767 (K)
• Default (TSO): 16000K
MTVSERR - Empty VSAM File Error (z/OS only)
MTVSERR specifies how an empty input VSAM file should be handled.
This is an execution-time option for z/OS only.
161
CA Easytrieve® Report Generator 11.6
MTVSERR {Y|N}
• Y
The CA Easytrieve Report Generator I/O system treats an empty VSAM input file as an I/O error condition. This will
cause the immediate abnormal termination of the program.
• N
An empty VSAM input file to be handled as though it is at End-Of-File. This is the default.
UPDTDLI - DLI Updates (z/OS only)
UPDTDLI specifies whether the DLI update function codes DLET, ISRT, or REPL are allowed on the DLI statement.
This is an execution-time option for z/OS only. No override is available.
UPDTDLI {Y|N}
• Y
Codes are allowed.
• N
Codes are not allowed. This is the default.
SPRTXIT - SYSPRINT Exit (z/OS only)
SPRTXIT specifies the name of a user-supplied SYSPRINT/SYSLST exit routine. The modname must be a valid program
name. More information on the SYSPRINT/SYSLST exit capability can be found in the Unit Record Exits section in
Installing.
This is an execution-time option for z/OS only.
SPRTXIT modname
• Default: blank (no exit name)
UPDTIDD - Update IDD with Compilation Stats
UPDTIDD specifies whether the dictionary is to be updated with program compilation statistics.
UPDTIDD={YES|NO}
• YES
Override is available through the RETRIEVE parameter on the IDD NAME statement.
• NO
No override is available. This is the default.
NOTE
Although this option is still accepted, it is ignored and reserved for future use.
WARNCC - Warning Message Condition Code Option
WARNCC specifies which condition code the compiler returns for warning messages. Typically a compilation that reports
only warning messages returns with a condition code of 4.
You cannot override this value during program compilation.
162
CA Easytrieve® Report Generator 11.6
WARNCC {F|S|Z}
• F
Returns a condition code of 4 for warnings. This is the default.
• S
Returns a condition code of 16 for warnings.
• Z
Returns a condition code of 0 for warnings.
Environmental Options
This article describes the following Environmental options that you can configure in the options table:
BUFNO - Number of Seq I/O Buffers (z/OS only)
BUFNO specifies the number of I/O buffers for each sequential file. VFM and VSAM files do not use this information.
This is an execution-time option for z/OS only. You can override this value through the BUFNO parameter of the FILE
statement.
BUFNO nnn
• Limits: 0 - 255.
• Default: 2
ENVIRON - Environment COBOL (z/OS only)
ENVIRON establishes whether to establish the COBOL Language Environment (LE) prior to calling any subprograms.
The environment is established prior to the PROGRAM activity or each JOB activity that contains a CALL statement or
accesses a FILE EXIT. The environment is terminated after the activity for which it was established.
This is an execution-time option for z/OS only. You can override the value using the ENVIRONMENT parameter of the
PARM, PROGRAM, or JOB statement.
ENVIRON {N|C}
• N
No environment is established. This is the default.
• C
The COBOL environment is established.
NOTE
For more information about the ENVIRONMENT COBOL parameter, see Inter-Program Linkage.
WKDSNPF - Work Data Set Prefix (z/OS only)
WKDSNPF specifies the three-character prefix that is used for all internal work files. It must be three characters that are
valid as a file name prefix. A user-specified name cannot begin with this prefix.
This is an execution-time option for z/OS only. You cannot override this value during program compilation.
WKDSNPF xxx
163
CA Easytrieve® Report Generator 11.6
• Default: EZT
WORKFILE - Use Report Workfiles (z/OS only)
WORKFILE specifies whether Report work files are to be used to store intermediate Reporting data.
This is a compile-time option for z/OS only. You can override this value through the WORKFILE parameter of the PARM
statement.
WORKFILE {Y|N}
• N
VFM files are used to store intermediate Reporting data. This is the default.
• Y
Temporary sequential disk files are used to store intermediate Reporting data.
WORKFSPA - Report Work Files Space (z/OS only)
WORKFSPA specifies the number of cylinders that are to be allocated to each Report work file.
This is an execution-time option for z/OS only. You can override this value through the WORKFILE parameter of the
PARM statement or by coding Report work file DD statements in the JCL that executes the CA Easytrieve Report
Generator program.
WORKFSPA nnn
• Default: 20
VFMDEV - VFM Overflow Device (z/OS only)
VFMDEV specifies the device type of the Virtual File Manager (VFM) overflow file.
This is an execution-time option for z/OS only. You can override this value through the VFM parameter of the PARM
statement.
VFMDEV {DISK|MEMORY}
• DISK
Overflows to disk. This is the default.
• MEMORY
Overflows to main memory.
VFMSPAC - VFM Core Storage (z/OS only)
VFMSPAC specifies the maximum amount of storage that is used by the Virtual File Manager (VFM) for its buffer pool.
If the product is executed in a partition of 256K or greater, you should specify a value that is 25 percent to 40 percent of
the total partition space:
• For a 256K partition, a value of 64K is suggested.
• For a 1M partition, a value of 400K is suggested.
164
CA Easytrieve® Report Generator 11.6
This is an execution-time option for z/OS only. You can override this value through the VFM parameter of the PARM
statement.
VFMSPAC nnnn
• Default: 64
• Limits: 6 - 4096
STDOUT - Standard Output Destination ID
STDOUT specifies the destination ID to which output is routed when a display or report is issued to the default system
output device (SYSPRINT). The value that you specify for STDOUT must be the destination ID of a valid printer profile
definition.
This is an execution-time option. You cannot override this value during program compilation.
STDOUT destination id
• Default: TERMINAL
STDERR - Standard Error Destination ID (z/OS only)
STDERR specifies the destination ID to which error messages are routed when runtime error messages are issued. The
value that you specify for STDERR must be the destination ID of a valid printer profile definition.
This is an execution-time option for z/OS only. You cannot override this value during program compilation.
STDERR destination id
• Default: TERMINAL
PRINTID - Report Destination ID (z/OS only)
PRINTID specifies the destination ID to which output is routed when the Report Display Facility prints a report. PRINTID
is also used when a report is routed to the originating terminal through the STDOUT option and no terminal is active. The
value that you specify for PRINTID must be the destination ID of a valid printer profile definition.
This is an execution-time option for z/OS only. You cannot override this value during program compilation.
PRINTID destination id
• Default: PRINTER. If the profile definition for PRINTID routes output to the originating terminal, an error occurs.
MSGID - Message Destination ID (z/OS only)
MSGID specifies the destination ID to which output is routed when the Report Display Facility prints an Error Analysis
Report. MSGID is also used when an Error Analysis Report is routed to the originating terminal using the STDERR
option, but no terminal is active. The value that you specify for MSGID must be the destination ID of a valid printer profile
definition.
This is an execution-time option for z/OS only. You cannot override this value during program compilation.
165
CA Easytrieve® Report Generator 11.6
MSGID destination id
• Default: PRINTER. If the profile definition for MSGID routes output to the originating terminal, an error occurs.
Sort Options
This article describes the following Sort options that you can configure in the options table:
ALTSEQU - Use Alternate Sequence
ALTSEQU specifies whether to use an alternate collating sequence table for the sort process. The name of the table is
contained in the Alternate Sequence Table (ALTSEQ) option. This option is used primarily where the English alphabet is
not used.
This is an execution-time option. You can override this value with the SORT parameter of the PARM statement.
ALTSEQU {Y|N}
• Y
Defines that the product uses an alternate sequence table.
• N
Suppresses the table. This is the default.
ALTSEQ - Alternate Sequence Table
ALTSEQ specifies the name of an alternate collating sequence table for the sort process. The table is used when you
specify Y for the ALTSEQU option, described previously, or when your program contains a PARM SORT (ALTSEQ YES)
statement.
Enter up to eight characters specifying the name of a module containing the alternate collating table.
This is an execution-time option. You can override this value with the SORT parameter of the PARM statement.
ALTSEQ xxxxxxxx
• Default: EZTPAQTT
SORTNAME - Sort Program Name (z/OS only)
SORTNAME specifies the sort program on your operating system. Type up to eight characters specifying a valid program
accessible to CA Easytrieve Report Generator.
This is an execution-time option for z/OS only. You cannot override this value during program compilation.
SORTNAME xxxxxxxx
• Default: SORT
SORTMAX - Sort Use Available Storage (z/OS only)
SORTMAX specifies the maximum amount of storage that the sort program is allowed to use.
166
CA Easytrieve® Report Generator 11.6
This is an execution-time option for z/OS only. You can override this value through the SORT MEMORY parameter of the
PARM statement.
SORTMAX {Y|N}
SORTMAX works in conjunction with the SORTSIZ parameter as follows:
SORTMAX SORTSIZE Description
N 16-4096 Specifies the amount of storage (in
kilobytes) the product can use. If the
number specified for SORTSIZ exceeds the
amount of storage available, the amount
available is used.
Y 0 Specifies the sort can use all available
This is the default. This is the default. storage (MAX).
Y 16-4096 Specifies the amount of storage (in
This is the default. kilobytes) released after the MAX amount
has been reserved.
SORTSIZ - Maximum Sort Storage Size (z/OS only)
SORTSIZ specifies the maximum amount of storage that the sort program is allowed to use. SORTSIZ works in
conjunction with the SORTMAX parameter.
This is an execution-time option for z/OS only. You can override this value through the SORT MEMORY parameter of the
PARM statement.
SORTSIZ nnnn
• Limits: 0, 16 - 4096
• Default: 0
NOTE
See the description of SORTMAX for an explanation of how to set this option.
SORTRLS - Amount Released After Sort (z/OS only)
SORTRLS specifies the amount of free storage to be made available after the sort program is invoked. This space may be
required when the input or output file is controlled by an exit and the exit needs to allocate storage (as by opening a file).
This is an execution-time option for z/OS only. You can override this value through the SORT parameter of the PARM
statement.
SORTRLS nnnn
• Limits: 0 - 1024
• Default: 0
FASTSRT - Fast Sort (z/OS only)
FASTSRT specifies whether the sort program handles all of the I/O. This option applies only to sort programs that support
extended parameter lists and the fast sort feature.
167
CA Easytrieve® Report Generator 11.6
This is an execution-time option for z/OS only. You cannot override this value during program compilation.
FASTSRT {Y|N}
• Y
Uses the fast sort interface.
• N
Uses standard sort interface. This is the default.
NUMWORK - Number of Work Areas (z/OS only)
NUMWORK specifies the number of work areas that are used by the sort.
This is an execution-time option for z/OS only. You can override this value through the SORT WORK parameter of the
PARM statement or the WORK parameter of the SORT statement.
NUMWORK nn
• nn
Specifies the number of work areas that are used by the sort.
Default: 3
– 1 - 31 -- A number in this range tells the sort program to dynamically allocate this number of work data sets.
– 0 -- Specifies that the data sets are not dynamically allocated and must be defined in DD statements. If your
operating system does not support dynamic allocation of data sets, this field must be zero.
SORTWRK - Sort Work Device Type (z/OS only)
SORTWRK specifies the sort work device type for sort programs that dynamically allocate their sort work data sets. Type
any specific or generic device name that is valid for your operating system.
This is an execution-time option for z/OS only. You can override this value through the SORT parameter of the PARM
statement.
SORTWRK xxxxx
• Default: SYSDA
SORTPRT - DDNAME for Sort Messages (z/OS only)
SORTPRT specifies a valid DDNAME for sort messages.
This is an execution-time option for z/OS only. You cannot override this value during program compilation.
SORTPRT xxxxxx
• Default: SYSOUT
SORTMSR - Route Sort Messages (z/OS only)
SORTMSR specifies the routing of sort messages.
168
CA Easytrieve® Report Generator 11.6
This is an execution-time option for z/OS only. You can override this value through the SORT parameter of the PARM
statement.
SORTMSR {P|C}
NOTE
This option is ignored if you specify D for the SORTMSG option, described next.
SORTMSG - Level of Message Output (z/OS only)
SORTMSG specifies which messages are output from your sort program.
This is an execution-time option for z/OS only. You can override this value through the SORT parameter of the PARM
statement.
SORTMSG {D|N|A|C}
• D (Default)
Outputs the level of messages that are specified when the sort program was installed. This is the default.
• A (All)
Outputs all messages.
• N (No)
Does not output messages.
• C (Critical)
Outputs critical messages only.
SQL Options
This article describes the SQL options that you can specify in the options table:
In the Configuration Manager, these options are on the SQL tab of the execution options.
SQLSYNTX - SQL Syntax Level
SQLSYNTX specifies the type of syntax checking to perform on the SQL statements.
This is a compile-time option.
SQLSYNTX {F|P|N}
• F (Full)
Fully syntax checks SQL statements using the facilities of the underlying DBMS. FULL syntax checking results in the
SQL statement undergoing a dynamic prepare. This is the default.
• P (Partial)
Checks SQL statements for valid keywords. No connection is made to the DBMS unless an INCLUDE statement
is coded for an SQL table. PARTIAL does not permit the program to execute until it has undergone FULL syntax
checking.
• N (None)
Performs PARTIAL syntax checking.
169
CA Easytrieve® Report Generator 11.6
SSID - Subsystem ID
SSID specifies the name of the subsystem (Ingres, SYBASE, or Db2 database name or ODBC data source name) to use
for compilation and execution.
This is a compile-time option. You can override this value through the SSID parameter of the PARM statement.
SSID subsystem-id
• Blank
No default subsystem specified. This is the default.
• SSID
All programs using this option execute with a specific subsystem.
NOTE
SSID is required for Ingres or SYBASE either through the PARM statement or this option. Mainframe
Db2 subsystems can also be obtained from the Db2 system default module DSNHDECP. Non-mainframe
subsystems can be obtained from the ID in the DB2DBDFT environment variable. Windows ODBC data sources
can be obtained through a connection dialog if not supplied through the PARM statement or this option.
PANSQL - PAN/SQL Prefix (z/OS only)
PANSQL specifies the prefix of the CA Pan/SQL modules. If your environment requires that the modules be renamed, you
can do so by specifying a new prefix. You must then rename the CICS CA Pan/SQL modules in your loadlib.
This is an execution-time option for z/OS only. You cannot override this value during program compilation.
PANSQL xxxxxs
• Default: DQSPS
NOTE
See the CA Pan/SQL documentation for more changes.
PREPNME - Access Module/Plan (z/OS only)
PREPNME specifies the default name of the access module or access plan to be created for the SQL/DS or CA Datacom/
DB with SQL databases.
This is a compile-time option for z/OS only. You can override this value through the PREPNME parameter of the PARM
statement.
PREPNME xxxxxxxx
• Default: EASYPLUS
NOTE
We recommend that you avoid using the default and specify a unique name for each user program.
BIND - Bind (z/OS only)
BIND specifies the default Db2 bind that is used.
This is a compile-time option for z/OS only. You can override this value through the BIND parameter of the PARM
statement.
170
CA Easytrieve® Report Generator 11.6
BIND {A|S|D}
• Blank
No default value specified. This is the default.
• A
Either STATIC-ONLY or DYNAMIC is used.
• S
STATIC-ONLY is used.
• D
DYNAMIC is used.
IDMS Options
This article describes the IDMS options that you can specify in the options table:
In the Configuration Manager, these options are on the IDMS tab of the execution options.
CALCDUP - Duplicate CALC Record Keys (z/OS only)
CALCDUP specifies whether CALC records with duplicate keys are to be retrieved for the IDMS RETRIEVE statement.
This is a compile-time option for z/OS only. You can override this value with the DUPS/NODUPS parameter of the
RETRIEVE statement.
CALCDUP {Y|N}
• Y
Indicates that root records with the same tickler file key are returned.
• N
Indicates that only the first of the duplicate records is returned. This is the default.
UPDTIDM - IDMS Update Allowed (z/OS only)
UPDTIDM specifies whether IDMS statements that update the database (CONNECT, DISCONNECT, ERASE, MODIFY,
STORE) are permitted during syntax check and execution operations.
This is a compile-time and an execution-time option for z/OS only.
UPDTIDM {Y|N|C|R}
• Y
Indicates that update functions are permitted.
• N
Indicates that update functions are not permitted. This is the default.
• C
Indicates that update functions are permitted at compile time only.
• R
Indicates that update functions are permitted at runtime only.
NOTE
The C and R options are not available in the Configuration Manager.
171
CA Easytrieve® Report Generator 11.6
UPDTIDD - IDD Updated with Program Compilation Stats (z/OS only)
UPDTIDD specifies whether the dictionary is to be updated with program compilation statistics.
This is a compile-time option for z/OS only.
UPDTIDD {Y|N}
• Y
Override is through the RETRIEVE parameter on the IDD NAME statement.
• N
No override is available. This is the default.
VERFILE - IDD FILE Version (z/OS only)
VERFILE specifies the version of the non-database file that you want to retrieve.
This is a compile-time option for z/OS only. You can override this value with the VERSION parameter of the IDD FILE
statement.
VERFILE {HIGHEST|LOWEST|nnnn}
• HIGHEST
This is the default.
• LOWEST
• nnnn
Indicates specific version number.
VERREC - IDD RECORD Version (z/OS only)
VERREC specifies the version of the record that you want to retrieve.
This is a compile-time option for z/OS only. You can override this value with the VERSION parameter of the IDD RECORD
statement.
VERREC {HIGHEST|LOWEST|nnnn}
• HIGHEST
This is the default.
• LOWEST
• nnnn
Indicates specific version number.
VERSCHM - IDD SCHEMA Version (z/OS only)
VERSCHM specifies the version of the schema owning the subschema that you want to retrieve.
This is a compile-time option for z/OS only. You can override this value with the VERSION parameter of the ID
SUBSCHEMA statement.
VERSCHM {HIGHEST|LOWEST|nnnn}
• HIGHEST
172
CA Easytrieve® Report Generator 11.6
This is the default.
• LOWEST
• nnnn
Indicates specific version number.
IDDCOMP - IDD COMP Field Type (UNIX only)
IDDCOMP specifies the field type to generate for a CPMP type field from the IDD.
This is a compile-time option for UNIX only.
IDDCOMP {B|I}
• B
Indicates a mainframe binary format. This is the default.
• I
Indicates an integer field type.
Report Options
This article describes the Report options that you can configure in the options table:
LONGDTE - Date Used on Reports
LONGDTE specifies whether SYSDATE or SYSDATE-LONG is the default date that appears on TITLE 01 on reports.
This is a compile-time option. You can override this parameter through the LONGDATE or SHORTDATE parameters of the
REPORT statement. The override is applicable only to report output, not to the compiler listing.
LONGDTE {Y|N}
• Y
Displays SYSDATE-LONG on reports and the compile listing.
• N
Displays SYSDATE on reports and the compile listing. This is the default.
NOTE
Also see the DATE and DATESEP options.
LINESIZ - Characters on a Line
LINESIZ specifies the default length of a report line, excluding the carriage control character.
This is a compile-time option.
LINESIZ is used:
• When a report is routed to the default system output device, SYSPRINT
• When a report is routed to PRINTER and no LINESIZE parm is specified in the FILE statement or REPORT statement
• To define the length of the compiler output lines
You can override this parameter through the LINESIZE parameter of the REPORT statement or a PRINTER FILE
statement. The override is applicable only to report output, not to the compiler listing.
LINESIZ nnn
173
CA Easytrieve® Report Generator 11.6
• Limits: 80 - 255
• Default: 132
PAGESIZ - Lines on a Page
PAGESIZ specifies the maximum length of a logical report page. This is the value that is compared by LINE statements
for end of page. This value also defines the page size of the compiler listing lines.
This is a compile-time option. You can override this value with the PAGESIZE parameter of the REPORT or FILE
statement.
PAGESIZ nnnnn
• Limits: 1 to 32767
• Default: 58
DISPPAGE - Display Page Size
DISPPAGE specifies the maximum print length of a report page for the DISPLAY statement. This is the value that is
compared by DISPLAY statements for end of page.
This is a compile-time option. You can override this value through the PAGESIZE (display-page-size) parameter of the
REPORT or FILE statement.
DISPPAGE nnnnn
• Limits: 0 - 32767
• Default: 0 (DISPLAY statements are not tested for end of page)
SKIP - Lines to Skip before Detail
SKIP specifies the number of blank lines that are inserted before each LINE 01 is printed, except for the first LINE 01 after
a page heading.
This is a compile-time option. You can override this value with the SKIP parameter of the REPORT statement.
SKIP nnn
• Limits: 0 - 255 or PAGESIZ, whichever is smaller
• Default: 0
TITLSKP - Lines to Skip after Title
TITLSKP specifies the number of blank lines to insert between the last title line and the first heading line (or the first data
line if NOHEADING is specified).
This is a compile-time option. You can override this value with the TITLESKIP parameter of the REPORT statement.
TITLSKP nnn
174
CA Easytrieve® Report Generator 11.6
• Limits: 0 - 255 or PAGESIZE, whichever is smaller
• Default: 3
SPACE - Number of Spaces between Fields
SPACE specifies the number of spaces to insert between fields that are specified on the TITLE and LINE statements.
This is a compile-time option. You can override this value with the SPACE parameter of the REPORT statement.
SPACE nnn
• Limits: 0 to the value of LINESIZ minus 2
• Default: 3
SPREAD - Spread Columns as Far as Possible
SPREAD specifies whether each line item (column) of a report is separated as far as possible from adjacent line items.
This is a compile-time option. You can override this value with the SPREAD parameter of the REPORT statement.
SPREAD {Y|N}
• Y
Spreads the items.
• N
Keeps the items separated by the minimum space that is specified in the SPACE option of the REPORT statement.
This is the default.
SUMSPAC - Additional Positions for Summed Fields
SUMSPAC specifies the number of additional print positions to reserve for printing summed fields in a report. The
additional space prevents an overflow condition when the summed field exceeds its defined size.
This is a compile-time option. You can override this value with the SUMSPACE parameter of the REPORT statement.
SUMSPAC n
• Limits: 0 - 9
• Default: 3
TALYSIZ - Size of TALLY Field
TALYSIZ specifies the size of the TALLY field in digits. The value of SUMSPAC is added to TALYSIZ to determine the
effective size of the printed field. Using the defaults for SUMSPAC and TALYSIZ, the effective size of TALLY is five digits.
This is a compile-time option. You can override this value with the TALLYSIZE parameter of the REPORT statement.
TALYSIZ nn
• Limits: 1 - 18
• Default: 2
DTLCTL - Print Control Fields on Detail Lines
DTLCTL specifies the method of printing the value of control fields on detail lines in a control report.
175
CA Easytrieve® Report Generator 11.6
This is a compile-time option. You can override this value using the DTLCTL parameter of the REPORT statement.
DTLCTL {F|E|N}
• F (First)
Prints all control fields on the first detail line at top-of-page and after each break. This is the default.
• E (Every)
Prints control fields on every detail line.
• N (None)
Does not print control fields on detail lines.
NOTE
For more information about this option, see the DTLCTL parameter of the REPORT statement in Language
Reference and Programming.
SUMCTL - Print Control Fields on Summary Lines
SUMCTL specifies how control fields are printed on the summary lines in a control report.
This is a compile-time option. You can override this value through the SUMCTL parameter of the REPORT statement.
SUMCTL {A|H|T|N}
• A (All)
Prints all control fields on all total lines.
• H (Hiar)
Prints control fields in hierarchical order on total lines. This is the default.
• T (Tag)
Tags each summary line with the control field.
• N (None)
Does not print control fields on the summary lines.
NOTE
For more information about this option, see the SUMCTL parameter of the REPORT statement in the Language
Reference and Programming .
ACROSS - Number of Labels Across
ACROSS specifies the number of labels to print across the print line.
This is a compile-time option.
ACROSS nnn
• Limits: 1 - 127
• Default: 4
DOWN - Number of Lines on a Label
DOWN specifies the number of lines in each label.
This is a compile-time option.
DOWN nnn
176
CA Easytrieve® Report Generator 11.6
• Limits: 1 to the value of PAGESIZ
• Default: 6
LABLSIZ - Print Positions on a Label
LABLSIZ specifies the number of print positions on a label.
This is a compile-time option.
LABLSIZ nnn
• Limits: 1 to the value of LINESIZ
• Default: 30
NEWPAGE - New Page for Every Label
NEWPAGE specifies whether to skip to the top of the next page for each new label.
This is a compile-time option.
NEWPAGE {Y|N}
• Y
Skip to the top of the next page.
• N
Do not skip to the top of the next page. This is the default.
Mask Options
This article describes the Mask option that you can specify in the options table.
USERMSK - Mask
You can use a mask ID in the MASK parameter of the DEFINE or ROW statement to identify a mask that is used in a CA
Easytrieve Report Generator program.
This is a compile-time and an execution-time option.
USERMSK x 'mask-literal'
• x
Valid values: A through Y
NOTE
Using letters at the end of the alphabet avoids conflicts with programmer-coded masks, as programmers
typically choose letters at the beginning of the alphabet.
• mask-literal
Describes the mask as it would be defined in a field definition.
NOTE
For information about coding masks, see the MASK parameter.
177
CA Easytrieve® Report Generator 11.6
International Options
This article describes the international options that you can specify in the options table:
DATE - Date Format
DATE specifies the format of the date that is placed at the top of the compiler listing and stored in the system defined
SYSDATE and SYSDATE-LONG fields.
This is an execution-time option.
DATE {M|D|Y}
• M (Month)
MM/DD/YY format. This is the default.
• D (Day)
DD/MM/YY format.
• Y (Year)
YY/MM/DD format.
DATESEP - Date Separator Character
DATESEP specifies the character that separates the month, day, and year of the date that is placed at the top of the listing
and stored in the system defined field SYSDATE.
This is an execution-time option. You cannot override this value during program compilation.
DATESEP x
• Default: Slash (/)
TIMESEP - Time Separator Character
TIMESEP specifies the character that separates the hours, minutes, and seconds of the time placed at the top of the
listing and stored in the system defined field SYSTIME.
This is an execution-time option. You cannot override this value during program compilation.
TIMESEP x
• Default: Colon (:)
MONEY - Currency Symbol
MONEY specifies the single character currency symbol that is used as the floating currency symbol in print edit masks.
This is a compile-time option. You cannot override this value during program compilation.
MONEY x
• Default: Dollar sign ($)
PAGEWRD - Word Used for PAGE
PAGEWRD specifies the spelling for the English word PAGE for non English language sites. The specified word
replaces the word PAGE in the first title line of each report and at the top of each page of the CA Easytrieve Report
Generator compiler output listing.
178
CA Easytrieve® Report Generator 11.6
This is a compile-time option. You cannot override this value during program compilation.
PAGEWRD xxxxxxxxxx
• Limits: 1 - 10 characters
• Default: PAGE
FINALWRD - Word Used for FINAL
FINALWRD specifies the spelling for the English word FINAL for non-English language sites. The specified word replaces
the word FINAL in the annotation for the final total line when the TAG subparameter is used in a CA Easytrieve Report
Generator report.
This is a compile-time option. You cannot override this value during program compilation.
FINALWRD xxxxxxxxxx
• Limits: 1 to 10 characters
• Default: FINAL
TOTALWRD - Word Used for TOTAL
TOTALWRD specifies the spelling for the English word TOTAL for non-English language sites. The specified word
replaces the word TOTAL in the annotation for the total lines when the TAG subparameter is used in a CA Easytrieve
Report Generator report.
This is a compile-time option. You cannot override this value during program compilation.
TOTALWRD xxxxxxxxxx
• Limits: 1 to 10 characters
• Default: TOTAL
SEPOTTH - Thousands Separator Character
SEPOTTH specifies the character that separates the thousands place in numeric fields.
This is a compile-time option. You cannot override this value during program compilation.
SEPOTTH x
• Default: Comma (,)
SEPOTDC - Decimal Separator Character
SEPOTDC specifies the character that separates the decimal places in a numeric field.
This is a compile-time option. You cannot override this value during program compilation.
SEPOTDC x
• Default: Decimal point (.)
Printer Profile Definition
Use Printer Profiles to maintain the destinations to which report and message output are routed.
NOTE
For more information, see the STDOUT, STDERR, PRINTID, and MSGID options in Environmental Options.
179
CA Easytrieve® Report Generator 11.6
This article describes the following Printer Profile options:
Destination ID
In Configuration Manager, displays the destination ID of the definition being added or maintained. It is taken from the
Environmental Options panel. You cannot change it here.
Printer Type
Specifies the type of destination to which output is routed. Valid values are:
• S (System)
Specifies that this is a system printer to be dynamically directed to the operating system spooling system. When you
type s, only the values that are specified for the For System Printers fields are used.
• T (Terminal)
Specifies that this is a terminal printer. When you type t, only the values that are specified for the For Terminal Printers
fields are used.
• F (File)
Specifies that output routed to this destination is to be written to a file. When you type f, only the values that are
specified for the For File Output field are used.
Note: This option is not valid in CICS. If used, an execution error occurs.
Line Size
Specifies the default number of characters in a print line that is routed to this destination. This number includes the
carriage control character.
The valid range is 72 through 204 for TERMINAL and SYSTEM printers. For FILE printers the valid range is 72 through
255. The default is 132.
You can override this value through the LINESIZE parameter of the REPORT statement for reports that are routed to this
destination, or through the LINESIZE parameter of the FILE statement for TERMINAL PRINTER files.
Page Size
This field specifies the default number of print lines for a report page that is routed to this destination. The valid range is 1
through 32767. The default is 58.
You can override this value through the PAGESIZE parameter of the REPORT statement for reports that are routed to this
destination, or with the PAGESIZE parameter of the FILE statement for TERMINAL PRINTER files.
Extended ID
This field specifies the extended reporting printer name as defined in the Printer Set Definition. See Create or Modify a
Printer Set Definition for more information.
For System Printers
Use these fields when the Printer type for this destination is S (System).
• Class
Specifies the spool class for the output. The default is A.
• Node
Specifies the destination location for the output. This is usually a local or remote printer device name or a network
node name. The default is blank.
• Userid
180
CA Easytrieve® Report Generator 11.6
Specifies the userid of the recipient of the printed output. The default is blank.
For Terminal Printers
Use these fields when the Printer type for this destination is T (Terminal).
• Terminal Id
Specifies the name of the destination terminal. Blank routes the output to the originating terminal. The z/OS output
can be viewed using the Report Display Facility. In TSO and CMS as well as in non-mainframe environments, this field
must be blank. The default is blank.
NOTE
Do not specify the originating terminal for a PRINTID or MSGID destination. This causes printed output to be
returned to the Report Display Facility.
• Use Form Feed
Specifies whether the product uses a form feed character to start a new page. Type y to use the formfeed character.
Type n to indicate that the formfeed character cannot be used to start a new page. The default is N.
• Page Eject After
Type y to eject a page at the end of each report. Type n for no page eject. The default is N.
• Page Eject Before
Type y to eject a page at the beginning of each report. Type n for no page eject. The default is N.
For File Output
Use this field when the Printer type for this destination is F (File).
SYSNAME
Associates output with an external data set. Valid values are determined by your operating environment as follows:
• CMS—Up to eight characters specifying a FILEDEF name.
• TSO—Up to eight characters specifying a DD name.
• CICS—SYSNAME is invalid in CICS. If used, an execution error occurs.
• Non-mainframe—Up to eight characters specifying a File Description String. This name will be used as the physical
file name unless an environment variable exists by this name. In this case, the value of the variable names the physical
file name or device.
Examples: The following are valid examples of environment variables:
SYSPRINT=c:\data\myapp.rpt
SYSPRINT=\mynet\printer1
For example, to route the output to the DD statement or environment variable SYSPRINT, type sysprint in the SYSNAME
field. The default is blank.
181
CA Easytrieve® Report Generator 11.6
Getting Started
CA Easytrieve® Report Generator is an information retrieval and data management system that is designed to simplify
report programming. Its English-like language and simple declarative statements provide you with the tools to produce
comprehensive reports and screens. If you are an experienced developer, CA Easytrieve provides you with the tools to
perform complex programming tasks.
CA Easytrieve operates in various mainframe, UNIX, Linux for zSeries, and Windows environments. CA Easytrieve runs
interactively for data inquiry, analysis, maintenance, and reporting. The output can be returned to your terminal or routed
to a printer.
The articles in this section explain how to write CA Easytrieve programs. The Programming Lessons section is a tutorial
for persons who are familiar with data processing concepts. Skills for other programming languages are not required.
The tutorial does not describe all product features, and some of the described features may not be available in all
implementations of the product. Because CA Easytrieve is a compiled language that runs in many data processing
environments, the examples in this section are generic and do not address variations between different installations.
Program Examples
Most program examples in this section use the sample input file PERSNL that is included when the product is installed.
You can use PERSNL when you run program examples. Report output in some examples has been edited or shortened
for illustrative purposes. Actual reports that are produced using the PERSNL file can be much longer.
Suggested Reading
To get familiar with the product, we suggest that you read the sections listed under Level One, Level Two, and Level
Three. Each level introduces more advanced concepts.
Level One
The level one articles explain how to:
• Write a complete CA Easytrieve program, using automatic input and output features.
• Generate standard reports and screens.
• Perform calculations and use conditional expressions.
• Be familiar with the system-defined fields that are provided with CA Easytrieve.
To begin learning about CA Easytrieve, we suggest that you read the following articles and sections:
• Programming Lessons — Lessons 1 through 4
• Library Section - Describe and Define Data
• Describe Files and Fields — Defining Data through DEFINE Within an Activity
• Job Activities — Job Statement through Parentheses in Calculations sections
• Activity Section - Input and Output — Automatic Input and Output through Work File Processing
• Activity Section - Reporting
• Processing of Reports
Level Two
The level two articles explain how to:
182
CA Easytrieve® Report Generator 11.6
• Write slightly more complex CA Easytrieve reports, using programmer-controlled input and output commands.
• Generate label reports.
• Perform data assignments and moves and use loops and branching in program logic.
• Perform basic debugging techniques.
After you read the level 1 articles, we suggest that you read the following articles and sections:
• Describe Files and Fields — Defining Static Working Storage through Implicit Start-location
• Job Activities — Assignment Statement through STOP Statement
• Activity Section - Input and Output — User Controlled Input and Output through PUT Statement
• Label Report and Testing Aid Parameters
Level Three
The level three articles explain how to:
• Use advanced FILE statement parameters, including VIRTUAL and EXIT.
• Perform sorts.
• Use procedures and tables.
• Perform programmer-controlled input and output of randomly accessed files, including VSAM.
• Use REPORT procedures.
After you read the level 2 articles, we suggest that you read the following articles and sections:
• Describe Files and Fields — FILE Statement Revisited through COPY Statement
• Job Activities — User Procedure (PROCS) section
• SORT Activities
• PROGRAM Activities
• Activity Section - Input and Output — POINT Statement through WRITE Format 2
• Format Determination Parameters
• Multiple Reports
• Report Procedures (PROCs)
Program Structure
Each CA Easytrieve program can contain an environment section, a library definition section, and one or more activity
sections. The environment and library definition sections are optional, but at least one activity section is required.
183
CA Easytrieve® Report Generator 11.6
Figure 3: easytrieve_program
Environment Section
The environment section establishes parameters for the program. This section lets you override standard CA Easytrieve
options and select a mode of operation. The environment section is not required for most of the examples in this section.
For more information about the environment section, see PARM Statement in Language Reference.
Library Definition Section
The library definition section describes the data the program processes, data files and their associated fields, and any
working storage requirements of the program. The library definition section is usually required; it is optional when the
program does not perform any file input or output.
Activity Section
The activity section is the only mandatory section of a CA Easytrieve program. The activity types are PROGRAM,
SCREEN, JOB, and SORT.
• PROGRAM
A simple top-down sequence of instructions. You can use a PROGRAM activity to conditionally execute the other types
of activities, using the EXECUTE statement.
• JOB
Reads information from files, examine and manipulate data, write information to files, and initiate printed reports.
• SORT
Creates sequenced or ordered files.
• SCREEN
Defines a screen-oriented transaction. Data can be displayed to a terminal operator and received back into the
program. Files can be read and updated. A SCREEN activity can EXECUTE a JOB or SORT activity to perform a
special process, such as printing a report.
NOTE
Screen processing activities are available only in CA Easytrieve® Online.
184
CA Easytrieve® Report Generator 11.6
You can code one or more procedures (PROCs) at the end of each activity. Procedures are separate modules of program
code that you use to perform specific tasks. See Activity Section - Processing and Logic for more information about
procedures.
REPORT subactivities are areas in a JOB activity where reports are described. You can code one or more REPORT
subactivities after the PROCs (if any) at the end of each JOB activity. Code any PROCs used within a REPORT
subactivity (REPORT PROCs) immediately after the REPORT subactivity in which you use them.
The following table shows some CA Easytrieve keywords and other items in the sections where they are usually located.
The table gives the general order of CA Easytrieve statements in a program.
Section Items
Environment Section PARM ...
Library Section FILE ...
DEFINE ...
...
Activity Section PROGRAM ...
(statements)
(program procedures)
JOB ...
(statements)
(job procedures)
REPORT ...
(report procedures)
SORT ...
(sort procedures)
SCREEN ...
(screen procedures)
...
Sample Program
A simple CA Easytrieve program example follows. This program produces a standard report that is used in the next
section as a starting point for the tutorial.
FILE PERSNL FB(150 1800) }
EMPNAME 17 8 A }
EMP# 9 5 N } Library Section
DEPT 98 3 N }
GROSS 94 4 P 2 }
JOB INPUT PERSNL NAME FIRST-PROGRAM }
PRINT PAY-RPT }
REPORT PAY-RPT LINESIZE 80 } Activity Section
TITLE 01 'PERSONNEL REPORT EXAMPLE-1' }
LINE 01 DEPT EMPNAME EMP# GROSS }
The sample program produces the following report:
01/31/18 PERSONNEL REPORT EXAMPLE-1 PAGE 1
185
CA Easytrieve® Report Generator 11.6
DEPT EMPNAME EMP# GROSS
903 WIMN 12267 373.60
943 BERG 11473 759.20
915 CORNING 02688 146.16
935 NAGLE 00370 554.40
911 ARNOLD 01963 445.50
914 MANHART 11602 344.80
917 TALL 11931 492.26
918 BRANDOW 02200 804.64
911 LARSON 11357 283.92
932 BYER 11467 396.68
921 HUSS 11376 360.80
911 POWELL 11710 243.20
943 MCMAHON 04234 386.40
You can generate reports faster with CA Easytrieve than with other programming languages or report generators. The
programming lessons show how to start creating CA Easytrieve programs.
Programming Lessons
Lesson 1 - Library Section, FILE and DEFINE Statements
In this lesson, we show you a sample CA Easytrieve® Report Generator program that you can enter and run on your
computer. However, you can follow the lessons in this tutorial without running the programs to learn the product.
Sample Program
This sample program has only ten lines of code, but it creates a useful report. The program also shows how some of the
most important CA Easytrieve keywords are used. In other programming languages, a more complex program would be
needed to produce the same report.
FILE PERSNL FB(150 1800)
EMPNAME 17 8 A
EMP# 9 5 N
DEPT 98 3 N
GROSS 94 4 P 2
JOB INPUT PERSNL NAME FIRST-PROGRAM
PRINT PAY-RPT
REPORT PAY-RPT LINESIZE 80
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS
Report Output
The sample program produces the following report, which is an edited display of data from an employee file named
PERSNL.
01/31/18 PERSONNEL REPORT EXAMPLE-1 PAGE 1
DEPT EMPNAME EMP# GROSS
903 WIMN 12267 373.60
186
CA Easytrieve® Report Generator 11.6
943 BERG 11473 759.20
915 CORNING 02688 146.16
935 NAGLE 00370 554.40
911 ARNOLD 01963 445.50
914 MANHART 11602 344.80
917 TALL 11931 492.26
918 BRANDOW 02200 804.64
911 LARSON 11357 283.92
932 BYER 11467 396.68
921 HUSS 11376 360.80
911 POWELL 11710 243.20
943 MCMAHON 04234 386.40
NOTE
The PERSNL sample file is provided with CA Easytrieve. Ask your system administrator where it is stored at
your site. The PERSNL file is created via the JOB08DEM job located in the CBAAJCL library.
Library Section Statements
This section shows the relationship between the sample program and the report, one statement at a time.
The FILE Statement
The first line of our program is:
FILE PERSNL FB(150 1800)
The FILE statement contains the FILE keyword. A FILE statement must be included for every file that your program uses
for input or output. The FILE statement tells the program where to get the data that you want processed, and can also
provide information about how that data is stored. To do this, the statement must include a file name. In our example, the
file name is PERSNL.
The remainder of line 1 is optional. FB(150 1800) provides the program with information about how the PERSNL file
is stored, which makes accessing the file more economical. The PERSNL file contains fixed-length records of 150
characters that are stored in 1800 character blocks. This is indicated as one parameter, FB(150 1800), where FB stands
for Fixed, Blocked. 150 indicates the record length and 1800 indicates the block size. Multiple sub-parameters must be
enclosed in parentheses.
The DEFINE Statement
Our program contains four DEFINE statements that describe fields in a PERSNL file record. The word DEFINE does not
need to appear in the statements because it is implied.
EMPNAME 17 8 A
EMP# 9 5 N
DEPT 98 3 N
GROSS 94 4 P 2
The definitions can also be written with the DEFINE keyword:
DEFINE EMPNAME 17 8 A
DEFINE EMP# 9 5 N
DEFINE DEPT 98 3 N
DEFINE GROSS 94 4 P 2
187
CA Easytrieve® Report Generator 11.6
NOTE
If you need to define a working storage field outside of the library section, you can use DEFINE statements
within your program logic. When a field is defined there, the DEFINE keyword is required. See Library Section -
Describe and Define Data for more information about using DEFINE statements.
The previous DEFINE statements describe the four fields in a PERSNL file record that our program uses. DEFINE
statements do not have to describe all the fields in the record or the spaces between fields. You describe only the fields
that the program uses.
The basic components of a field definition are as follows:
Field Name Starting Position in Length of Field Data Type Number of Decimal
Record Positions
EMPNAME 17 8 A
EMP# 9 5 N
DEPT 98 3 N
GROSS 94 4 P 2
When describing a field, you must identify its name, starting position in the record, length, type, and the number of digits to
the right of the decimal point, if any.
The components must be coded in the order that is shown above (left to right) and the components must be separated by
spaces. In our code example, the components are aligned vertically for readability, although alignment is not required.
• Field Name
Identifies the field as a unique storage location and is what you use later to refer to your data.
• Starting Position
Specifies where the first character of the field begins in the record.
Beginning at the first character of data in a record of the PERSNL file, count nine characters to the right to find the first
character of the EMP# field. The first character of the EMPNAME field is 17 characters to the right of position 1.
EMP# field EMPNAME field
┌─────┴────────┐ ┌───────────┴───────────┐
│ │ │ │ │ │ │ │ │9 │9 │9 │9 │9 │ │ │ │ X│ X│ X│ X│ X│ X│ X│ X│ ...
└───────────────────────────────────────────────────────────────────────┘──
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 . . .
A physical record in the PERSNL File
NOTE
Fields do not have to be defined in your program in the same order that they occur in the record. In our example,
we define EMPNAME before EMP# even though it is physically after EMP# in the record.
• Field Length
Specifies the number of bytes (characters) of storage that the field occupies in the record. In the previous example,
you can see that EMP# with a field length of 5 occupies 5 bytes or character positions in the PERSNL record.
• Data Type
Describes the kind of data that is stored in a field. In the example, the fields are defined as three different data types as
follows:
Field Data Type Purpose
EMPNAME A - Alphanumeric Stores non-numeric data
EMP# N - Numeric Stores numbers in zoned decimal format
188
CA Easytrieve® Report Generator 11.6
DEPT N - Numeric Stores numbers in zoned decimal format
GROSS P - Packed decimal Stores numbers in internal packed decimal
format
• Decimal Positions
In our example, GROSS is the only field that contains numbers to the right of a decimal point. When this field is printed
on your report, it shows up with two numbers to the right of a decimal point (for example, 999.99).
Decimal
Positions
└─────────┘
|
GROSS 94 4 P 2
Review
In this lesson, you learned about the FILE and DEFINE statements in the library section. These two statements define the
library of data that is used as input to processing activities:
• FILE describes the data file that the program is accessing (or creating).
• DEFINE describes the fields in the file that the program uses.
NOTE
For more Information about the library section, see Library Section - Describe and Define Data.
Next Lesson
Once you have defined your data, you can continue with processing activities.
The next lesson is Lesson 2 - Activity section, JOB and IF statements.
Lesson 2 - Activity Section, JOB and IF Statements
In the previous lesson, we showed you a complete CA Easytrieve® Report Generator program and explained the library
section. This lesson explains the JOB activity, which defines and initiates all processing activities in our sample program to
produce the report. Conditional statements and a calculation for salary deductions are included in the example.
The JOB Statement
The first line after the library section in our sample program is the JOB statement:
JOB INPUT PERSNL NAME FIRST-PROGRAM
A JOB statement indicates the beginning of processing. The JOB statement can also automatically provide input (if input
is available) to the processing statements that follow it. In our sample statement, the parameters that follow the word JOB
are optional.
Input to a JOB Activity
Typically, processing requires some kind of file input. Most programming languages require you to control the availability
of input files. Usually, files are opened and then an input statement is executed in a loop, with the end-of-file condition
being checked each time the loop is executed.
189
CA Easytrieve® Report Generator 11.6
Although you can control input, CA Easytrieve can also provide automatic input capability.
Automatic Input
The INPUT parameter of the JOB statement indicates that the named file (PERSNL in our example) should be made
automatically available to your program. It is like saying, "I want to use this file" and letting CA Easytrieve do the
necessary steps.
Because our sample program has only one input file (PERSNL), the INPUT parameter on the JOB statement is optional.
Without it, the program looks for input and uses the only file in our library section, PERSNL. If you do not specify INPUT,
the program looks for input and uses the first file described in the library section. However, if the JOB activity is preceded
by a SORT activity, the program uses the output from that SORT.
NOTE
For more information about SORT, see Activity Section - Input and Output.
Naming a JOB Activity
The next parameter after INPUT in our sample program is NAME. This tells the program that a job name follows.
A JOB activity is typically named for documentation purposes only. It helps to give JOB activities a descriptive name,
especially when you have more than one activity in your program. In our example, we named the JOB activity FIRST-
PROGRAM. We did this by typing the parameter NAME followed by a name (FIRST-PROGRAM) of our choice.
Program Logic
In this section, we add logic to our program.
Conditional Processing
So far, our sample program simply extracts data from a file and creates a report. A more complex program contains
conditions. When a condition is encountered, a test is performed to determine the next processing step.
If This, Then That
Suppose the report that you are working on has to include net pay and deductions. This is the program that we have been
working on so far:
FILE PERSNL FB(150 1800)
EMPNAME 17 8 A
EMP# 9 5 N
DEPT 98 3 N
GROSS 94 4 P 2
JOB INPUT PERSNL NAME FIRST-PROGRAM
PRINT PAY-RPT
REPORT PAY-RPT LINESIZE 80
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS
The program accesses the field named GROSS, which contains employee gross pay. You know that net pay is the gross
pay minus any deductions, and that employees who earn $500 or more get a 28 percent deduction; the rest do not get
any deduction.
The condition we have just described can be stated with a simple conditional expression:
IF GROSS GE 500
190
CA Easytrieve® Report Generator 11.6
DEDUCTIONS = .28 * GROSS
NET-PAY = GROSS - DEDUCTIONS
ELSE
NET-PAY = GROSS
DEDUCTIONS = 0
END-IF
In this expression, we say, "If the gross pay is greater than or equal to 500, deduct 28 percent to give the net pay.
Otherwise, if the gross is less than 500, there are no deductions and net pay is the same as gross." CA Easytrieve
requires an END-IF to complete the expression.
Adding Logic to the JOB Activity
Now that we have a logical statement to describe our condition, we simply type it into our program, placing it in the JOB
activity after the JOB statement:
FILE PERSNL FB(150 1800)
EMPNAME 17 8 A
EMP# 9 5 N
DEPT 98 3 N
GROSS 94 4 P 2
JOB INPUT PERSNL NAME FIRST-PROGRAM
IF GROSS GE 500
DEDUCTIONS = .28 * GROSS
NET-PAY = GROSS - DEDUCTIONS New
ELSE Logic
NET-PAY = GROSS
DEDUCTIONS = 0
END-IF
PRINT PAY-RPT
REPORT PAY-RPT LINESIZE 80
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS
There are several details we still need to take care of. We need a place to store the results for our two new variables,
DEDUCTIONS and NET-PAY. They can be stored in a place known as working storage.
CA Easytrieve Working Storage
Unlike many other languages, CA Easytrieve makes defining working storage fields easy. You can place them in the
library section of your program or in the activity section before the logic that requires them.
To define a working storage field, you use the same type of attributes used to describe other fields. However, you use the
letter W to replace the numeric value that normally describes the start location.
DEDUCTIONS W 4 P 2
NET-PAY W 4 P 2
191
CA Easytrieve® Report Generator 11.6
The previous fields can be described as: working storage fields, 4 characters long, in packed decimal format with 2
decimal places. We place these fields in the library section of our program. They are more easily seen in that section than
if they were placed in the activity section.
FILE PERSNL FB(150 1800)
EMPNAME 17 8 A
EMP# 9 5 N
DEPT 98 3 N
GROSS 94 4 P 2
DEDUCTIONS W 4 P 2 Working Storage
NET-PAY W 4 P 2 Fields
JOB INPUT PERSNL NAME FIRST-PROGRAM
IF GROSS GE 500
DEDUCTIONS = .28 * GROSS
NET-PAY = GROSS - DEDUCTIONS
ELSE
NET-PAY = GROSS
DEDUCTIONS = 0
END-IF
PRINT PAY-RPT
REPORT PAY-RPT LINESIZE 80
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS
So far, we have used some elementary logic, calculated some values, and created a place to store those values.
Review
In this lesson, you learned how to add conditional logic and calculations to your program to compute new information. You
also learned how to store the new information. You know that:
• JOB initiates program processing activities and can also provide automatic file input.
• IF is a conditional expression that is used to make decisions, based on certain criteria.
• W designates a working storage field on the DEFINE statement.
NOTE
For more Information about the JOB activity section, see Activity Section - Processing and Logic.
Next Lesson
In the next lesson, you learn about the LINE statement and the PRINT statement, which initiates printing of your report.
The MASK and HEADING parameters that let you edit and label your data are also explained.
The next lesson is Lesson 3 - Activity section, report output with PRINT Statement.
Lesson 3 - Activity Section, Report Output with PRINT Statement
This lesson introduces the PRINT statement. The PRINT statement activates the report statements that result in a printed
report.
192
CA Easytrieve® Report Generator 11.6
A report declaration that follows the PRINT statement consists of a series of statements that define the format and content
of a report. These statements consist of the REPORT statement, report definition statements, and report procedures. So
far, we have seen three such statements in our sample program:
• REPORT
• TITLE
• LINE
In our sample program, the PRINT statement is placed directly after the conditional statements that we added in the
previous lesson:
END-IF
PRINT PAY-RPT
REPORT PAY-RPT LINESIZE 80
Once the conditional statements have been run against a record of the PERSNL file, the PRINT statement tells CA
Easytrieve to execute the report definition statements. In the previous PRINT statement example, these statements are
identified by a user-supplied name, PAY-RPT. This name ties the PRINT statement to a specific report of the same name
as indicated on the REPORT statement. If the report name is not included, the first report in the JOB activity section is
executed, whether or not it has a name.
After the report statements have been executed, control is returned to the beginning of the JOB activity section where the
next record is processed or end-of-file processing is performed. All output routines, line counts, and page advances are
handled automatically when the PRINT statement is executed.
LINE Statement
The last line in the program is currently:
LINE 01 DEPT EMPNAME EMP# GROSS
This line causes the detail lines of the report to be printed. The LINE statement specifies the fields to print and the order in
which to print them.
To add DEDUCTIONS and NET-PAY to the report output, we add the field names in the order that they should appear in
the report:
LINE 01 DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
The program with all the changes that we have made is as follows:
FILE PERSNL FB(150 1800)
EMPNAME 17 8 A
EMP# 9 5 N
DEPT 98 3 N
GROSS 94 4 P 2
DEDUCTIONS W 4 P 2
NET-PAY W 4 P 2
JOB INPUT PERSNL NAME FIRST-PROGRAM
IF GROSS GE 500
DEDUCTIONS = .28 * GROSS
NET-PAY = GROSS - DEDUCTIONS
ELSE
NET-PAY = GROSS
DEDUCTIONS = 0
193
CA Easytrieve® Report Generator 11.6
END-IF
PRINT PAY-RPT
REPORT PAY-RPT LINESIZE 80
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
The sample output from this program follows. As you can see, the NET-PAY and DEDUCTIONS columns have been
added.
01/31/18 PERSONNEL REPORT EXAMPLE-1 PAGE 1
DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
903 WIMN 12267 373.60 373.60 .00
943 BERG 11473 759.20 546.63 212.57
915 CORNING 02688 146.16 146.16 .00
935 NAGLE 00370 554.40 399.17 155.23
911 ARNOLD 01963 445.50 445.50 .00
914 MANHART 11602 344.80 344.80 .00
917 TALL 11931 492.26 492.26 .00
918 BRANDOW 02200 804.64 579.35 225.29
911 LARSON 11357 283.92 283.92 .00
932 BYER 11467 396.68 396.68 .00
921 HUSS 11376 360.80 360.80 .00
911 POWELL 11710 243.20 243.20 .00
943 MCMAHON 04234 386.40 386.40 .00
Editing Your Report Output
In the previous section, we added NET-PAY and DEDUCTIONS to our report. Those values and GROSS are dollar
values. Until now, dollar values have printed as ordinary numbers with decimal places. We can modify the field definitions
by adding an edit mask so that the values in the report have dollar signs.
Edit Mask
An edit mask is a pattern of characters that specifies how numeric data should appear in the report.
NOTE
Alphanumeric fields cannot have an edit mask.
For example, we have added edit masks to the three currency fields in our example program so that they print with dollar
signs:
GROSS 94 4 P 2 MASK (A '$$,$$9.99')
NET-PAY W 4 P 2 MASK A
DEDUCTIONS W 4 P 2 MASK (A BWZ)
MASK is a parameter of the DEFINE statement that indicates that an edit mask follows. Edit masks are enclosed in single
quotes. In this code segment, the edit mask named A consists of the characters '$$,$$9.99'. Naming the mask lets you
use the same mask for other fields without defining it each time.
Adding the edit masks affects our report as follows:
01/31/18 PERSONNEL REPORT EXAMPLE-1 PAGE 1
194
CA Easytrieve® Report Generator 11.6
DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
903 WIMN 12267 $373.60 $373.60
943 BERG 11473 $759.20 $546.63 $212.57
915 CORNING 02688 $146.16 $146.16
935 NAGLE 00370 $554.40 $399.17 $155.23
911 ARNOLD 01963 $445.50 $445.50
914 MANHART 11602 $344.80 $344.80
917 TALL 11931 $492.26 $492.26
918 BRANDOW 02200 $804.64 $579.35 $225.29
911 LARSON 11357 $283.92 $283.92
932 BYER 11467 $396.68 $396.68
921 HUSS 11376 $360.80 $360.80
911 POWELL 11710 $243.20 $243.20
943 MCMAHON 04234 $386.40 $386.40
NOTE
Leading zeros are suppressed and each value has a dollar sign. The BWZ parameter causes any all-zero values
in the DEDUCTIONS column to appear as blanks.
The following explanations and rules apply to the edit masks in our example:
• Each digit in a field must be designated in the edit mask. Because a four-byte packed decimal field is capable of
containing seven digits, we need to designate seven digits in the mask. This is done with $$$$999.
• Dollar signs ($) in the edit mask indicate that a dollar sign is to be printed prior to the first non-zero digit of the printed
field. This is called a floating dollar sign. It means that, if one or more high-order zeros are stored in the positions
where a dollar sign appears in the mask, they are suppressed and replaced with a single dollar sign. For example:
Mask Field Value Resulting Output
'$$,$$9.99' 1234567 $12,345.67
0123456 $1,234.56
0012345 $123.45
0001234 $12.34
0000123 $1.23
0000012 $0.12
• As the number of leading zeros increases, the dollar sign automatically floats to the right.
• The digit 9 indicates that any value occurring in that position is printed as a digit. In the above example, all values
(including zeros) in the ones column or to the right of the decimal are printed as digits.
• Commas and decimal points are printed just as indicated. In the above example, you can see that commas are
suppressed along with high-order zeros for numbers less than 1000.
• When the same mask is to be used on more than one field, you can avoid coding the mask more than once by naming
it, and then specifying only the name on subsequent fields. Names can be any letter from A to Y.
In our example, we named the mask used on the GROSS field A. Then we specified the letter A on the NET-PAY
and DEDUCTIONS fields instead of coding the mask again. Remember, multiple parameters and subparameters are
enclosed in parentheses.
• To suppress all-zero values from printing (if you find that desirable) simply code BWZ (blank when zero) after the mask
or mask name. Because some employees in our report can have zero deductions, we included BWZ.
195
CA Easytrieve® Report Generator 11.6
Field Headings
So far in our example program, field (or column) headings have come directly from the field names themselves. CA
Easytrieve uses field names specified on the DEFINE statement as column headings by default, unless column headings
are described.
One way to describe alternative column headings for better identification is with the HEADING parameter of the field
definition. For example, you can replace the default heading EMP# with the more descriptive heading EMPLOYEE
NUMBER as follows:
EMPNAME 17 8 A
EMP# 9 5 N HEADING ('EMPLOYEE' 'NUMBER')
DEPT 98 3 N
By placing each word in single quotes, you indicate that the heading should be stacked, one word over the other.
The following report segment shows the effect of adding the HEADING parameter:
01/31/18 PERSONNEL REPORT EXAMPLE-1 PAGE 1
EMPLOYEE
DEPT EMPNAME NUMBER GROSS NET-PAY DEDUCTIONS
Review
In this lesson, you learned how the PRINT statement works and also how to use the MASK and HEADING parameters to
make your reports more readable. You have learned that:
• PRINT activates a report declaration resulting in a printed report.
• LINE determines which fields are printed on your report and in what order they are printed.
• MASK lets you change the look of fields on your report.
• HEADING enables you to customize column headings on your report.
In this lesson, we have made some minor changes to our ongoing program example. Here is how our program currently
looks:
FILE PERSNL FB(150 1800)
EMPNAME 17 8 A
EMP# 9 5 N HEADING ('EMPLOYEE' 'NUMBER')
DEPT 98 3 N
GROSS 94 4 P 2 MASK (A '$$,$$9.99')
NET-PAY W 4 P 2 MASK A
DEDUCTIONS W 4 P 2 MASK (A BWZ)
JOB INPUT PERSNL NAME FIRST-PROGRAM
IF GROSS GE 500
DEDUCTIONS = .28 * GROSS
NET-PAY = GROSS - DEDUCTIONS
ELSE
NET-PAY = GROSS
DEDUCTIONS = 0
END-IF
PRINT PAY-RPT
REPORT PAY-RPT LINESIZE 80
196
CA Easytrieve® Report Generator 11.6
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
NOTE
For more Information, see Activity Section - Input and Output about the PRINT statement.
Next Lesson
In the next lesson, you will learn about report declarations.
The next lesson is Lesson 4 - Activity section, REPORT statement and report definition statements
Lesson 4 - Activity Section, REPORT Statement and Report Definition
Statements
The example program that we have been discussing currently has only three statements in its report declaration:
REPORT, TITLE, and LINE.
REPORT PAY-RPT LINESIZE 80
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
In this lesson, we introduce the following statements and add them to our program:
• SEQUENCE
• CONTROL
• SUM
• HEADING
The REPORT Statement
The REPORT Statement must be the first statement in your report declaration. This statement precedes the report
description, and identifies the type of report and its various physical characteristics.
In our sample program, we identify the report by name (PAY-RPT) and also specify a LINESIZE of 80, but both of these
properties are optional. Because our program has only one report, we could have left the report name off both the PRINT
and the REPORT statements. A line size of 80 restricts report output to 80 characters to each printed line. If you enter
programs as we proceed and review the output at your terminal, then 80 characters per line is appropriate. Most terminals
display only 80 characters on a screen.
Report Definition Statements
Report definition statements define the contents of a report. These statements are presented in the order they must
occur in your report declaration. We add new statements to our example program as we go, showing the effects on report
output.
There are six report definition statements in CA Easytrieve. When used, they must occur after the REPORT statement in
the following order:
197
CA Easytrieve® Report Generator 11.6
• SEQUENCE
• CONTROL
• SUM
• TITLE
• HEADING
• LINE
A mnemonic for these statements and their order is:
Siblings Can Sometimes Tell Horrible Lies
E O U I E I
Q N M T A N
U T L D E
E R E I
N O N
C L G
E
Brief explanations of these statements follow. The order in which the statements are written is logical.
The SEQUENCE Statement
The SEQUENCE statement causes your report to be sorted on a specified key in ascending or descending order. In our
example, the report output should be sequenced on department in ascending order. We accomplish this by placing the
SEQUENCE statement and the field name DEPT after the REPORT statement:
REPORT PAY-RPT LINESIZE 80
SEQUENCE DEPT
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
Ascending order is the default for the SEQUENCE statement. For descending order, enter D after the field name,
separated by a space.
When we run our program, this report is produced:
01/31/18 PERSONNEL REPORT EXAMPLE-1 PAGE 1
EMPLOYEE
DEPT EMPNAME NUMBER GROSS NET-PAY DEDUCTIONS
901 WALTERS 11211 $424.00 $424.00
903 WIMN 12267 $373.60 $373.60
912 LOYAL 04225 $295.20 $295.20
914 MANHART 11602 $344.80 $344.80
914 VETTER 01895 $279.36 $279.36
914 GRECO 07231 $1,004.00 $722.88 $281.12
914 CROCI 08262 $376.00 $376.00
914 RYAN 10961 $399.20 $399.20
915 CORNING 02688 $146.16 $146.16
917 TALL 11931 $492.26 $492.26
918 BRANDOW 02200 $804.64 $579.35 $225.29
198
CA Easytrieve® Report Generator 11.6
918 EPERT 07781 $310.40 $310.40
919 DENNING 02765 $135.85 $135.85
920 MILLER 05914 $313.60 $313.60
NOTE
The records are now in order by department number. When you use the SEQUENCE statement, you do not
need to define any extra files or additional input/output commands in your program.
The CONTROL Statement
The CONTROL statement defines a control break on a specified field that is called the control field. The CONTROL
statement causes all quantitative fields (that is, fields with decimal positions) to be totaled at the time of the control break
and for a grand totals to appear at the end of the report.
Because we have sequenced our report by the DEPT field, we can also request a control break on the same field. This
gives us totals of GROSS, NET-PAY, and DEDUCTIONS for each department. To accomplish this, we add the CONTROL
statement and the field name DEPT after the SEQUENCE statement:
REPORT PAY-RPT LINESIZE 80
SEQUENCE DEPT
CONTROL DEPT
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
With that additional statement, gross and net pay totals are shown for each department with grand totals at the end of the
report:
01/31/18 PERSONNEL REPORT EXAMPLE-1 PAGE 1
EMPLOYEE
DEPT EMPNAME NUMBER GROSS NET-PAY DEDUCTIONS
901 WALTERS 11211 $424.00 $424.00
901 $424.00 $424.00
903 WIMN 12267 $373.60 $373.60
903 $373.60 $373.60
912 LOYAL 04225 $295.20 $295.20
912 $295.20 $295.20
914 MANHART 11602 $344.80 $344.80
VETTER 01895 $279.36 $279.36
GRECO 07231 $1,004.00 $722.88 $281.12
CROCI 08262 $376.00 $376.00
RYAN 10961 $399.20 $399.20
914 $2,403.36 $2,122.24 $281.12
$3,496.16 $3,215.04
199
CA Easytrieve® Report Generator 11.6
The SUM Statement
Suppose that you do not want totals for GROSS, NET-PAY, and DEDUCTIONS at each control break. You only want a
total for GROSS so you can get an idea of what the salary expense is. You can override the CONTROL statement that
normally totals all quantitative fields with the SUM statement.
The SUM statement specifies the quantitative fields that you want totaled on a control break. Using a SUM statement
ensures that only fields that are specified on the SUM statement are totaled. We have modified the program so that only
the gross pay has a total:
REPORT PAY-RPT LINESIZE 80
SEQUENCE DEPT
CONTROL DEPT
SUM GROSS
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
Now, GROSS is the only field that is totaled:
01/31/18 PERSONNEL REPORT EXAMPLE-1 PAGE 1
EMPLOYEE
DEPT EMPNAME NUMBER GROSS NET-PAY DEDUCTIONS
901 WALTERS 11211 $424.00 $424.00
901 $424.00
903 WIMN 12267 $373.60 $373.60
903 $373.60
912 LOYAL 04225 $295.20 $295.20
912 $295.20
914 MANHART 11602 $344.80 $344.80
VETTER 01895 $279.36 $279.36
GRECO 07231 $1,004.00 $722.88 $281.12
CROCI 08262 $376.00 $376.00
RYAN 10961 $399.20 $399.20
914 $2,403.36
The TITLE Statement
The TITLE statement causes the title to appear in our report. We have been calling our report PERSONNEL REPORT
EXAMPLE-1 throughout the tutorial.
REPORT PAY-RPT LINESIZE 80
SEQUENCE DEPT
CONTROL DEPT
200
CA Easytrieve® Report Generator 11.6
SUM GROSS
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
You can change it to any appropriate title. Include the word TITLE followed by a title number, followed by your title in
single quotes. If you have only one title, you can omit the title number; it defaults to 01. When you want more than one
title, you must number all TITLE statements in ascending order.
The result of the TITLE statement follows.
01/31/18 PERSONNEL REPORT EXAMPLE-1 PAGE 1
EMPLOYEE
DEPT EMPNAME NUMBER GROSS NET-PAY DEDUCTIONS
901 WALTERS 11211 $424.00 $424.00
901 $424.00
903 WIMN 12267 $373.60 $373.60
903 $373.60
The system date and the page number are automatically printed on the same line. The Activity Section -- Reporting
section explains how to override this feature.
The HEADING Statement
The HEADING statement, like the HEADING parameter of the DEFINE statement, prints user-defined column headings
for specified fields. It overrides the HEADING parameter of the DEFINE statement if one already exists for the field that
you are describing. See Lesson 3 for more information, if needed.
We have added this statement to our program to show you how this statement works. Suppose that we have decided
the field name EMPNAME is not really a good column heading. We want EMPLOYEE NAME instead. As we did with the
EMP# field, we can change our existing column heading.
We do so by typing the word HEADING followed by the field name EMPNAME, followed by the new column heading:
REPORT PAY-RPT LINESIZE 80
SEQUENCE DEPT
CONTROL DEPT
SUM GROSS
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
HEADING EMPNAME ('EMPLOYEE' 'NAME')
LINE 01 DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
To be consistent with our other heading, EMPLOYEE NUMBER, we have described our new heading so that it stacks
EMPLOYEE on top of NAME. To do this, type single quotes around each word in the heading. The parentheses are
required because the two words, each in single quotes, are treated the same as any other multiple parameters. Here's
how it prints:
01/31/18 PERSONNEL REPORT EXAMPLE-1 PAGE 1
EMPLOYEE EMPLOYEE
DEPT NAME NUMBER GROSS NET-PAY DEDUCTIONS
201
CA Easytrieve® Report Generator 11.6
901 WALTERS 11211 $424.00 $424.00
901 $424.00
903 WIMN 12267 $373.60 $373.60
903 $373.60
912 LOYAL 04225 $295.20 $295.20
912 $295.20
914 MANHART 11602 $344.80 $344.80
VETTER 01895 $279.36 $279.36
GRECO 07231 $1,004.00 $722.88 $281.12
CROCI 08262 $376.00 $376.00
RYAN 10961 $399.20 $399.20
914 $2,403.36
The LINE Statement
The LINE statement defines the contents of a printed line (detail line) in your report.
NOTE
You must include the LINE statement in your report declaration.
In our example program, it defines which fields we want printed on a line and the order in which we want them printed:
REPORT PAY-RPT LINESIZE 80
SEQUENCE DEPT
CONTROL DEPT
SUM GROSS
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
HEADING EMPNAME ('EMPLOYEE' 'NAME')
LINE DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
Review
You have learned how the REPORT, SEQUENCE, CONTROL, SUM, TITLE, HEADING, and LINE statements are used in
the creation of a CA Easytrieve report.
In summary:
• REPORT designates the beginning of a report declaration and can specify the type of report and report characteristics.
• SEQUENCE puts your report in alphabetical or numerical order, based on the contents of a field or fields.
• CONTROL causes a control break, based on the contents of a field. It causes the printing of control totals and grand
totals for all quantitative fields.
• SUM overrides control totals and causes totals only for specified fields.
• TITLE causes the printing of major report titles.
• HEADING causes the printing of customized column headings.
• LINE specifies the fields to include on detail lines and the field order.
NOTE
For more information about report declarations, see Activity Section - Reporting.
202
CA Easytrieve® Report Generator 11.6
This concludes the tutorial. You can now create your own standard reports using what you have learned.
Library Section - Describe and Define Data
To create CA Easytrieve® Report Generator programs that use input or output files, it is essential to describe and define
data. CA Easytrieve must know how data is stored before processing. Use the FILE and DEFINE statements to define
data.
CA Easytrieve Syntax Rules
The free-form English language structure of CA Easytrieve makes it easy for you to develop an efficient, flexible
programming style. To avoid programming errors, follow these syntax rules.
Statement Area
All CA Easytrieve source statements are records of 80 characters each. The default statement area is in columns 1
through 72. You can place your CA Easytrieve code anywhere within these columns. You can indent or line up certain
statements for readability, but it is not required.
Multiple Statements
The statement area typically contains a single statement. However, you can enter multiple statements on a single line.
A period followed by a space indicates the end of a statement. The next CA Easytrieve statement can start at the next
available position of the statement area (after the space). For example, the following two CA Easytrieve statements are on
one line:
COST = FIXED + VARIABLE. PRICE = COST + PROFIT
Comments
When the first non-blank character of a statement is an asterisk (*), the remainder of that line is considered to be a
comment that is ignored by the CA Easytrieve compiler. You can use comment statements any place within a program,
except within a continued statement. A statement containing all blanks is also treated as a comment.
To place a comment on the same line as a statement, code a period (.), one or more spaces, an asterisk (*), then the
comment.
Continuations
The last non-blank character of a statement terminates the statement unless that character is a minus (-) or a plus sign
(+).
• The - indicates that the statement continues at the start of the next statement area.
• The + indicates that the statement continues with the first non-blank character in the next statement area.
The difference between - and + is important only when continuing a line in the middle of a word. Continuation of a line
between words is the same for both. The following continued statements produce identical results:
FIELD-NAME W 6 A +
VALUE 'ABC -
DEF'
FIELD-NAME W 6 A +
VALUE 'ABC +
DEF'
203
CA Easytrieve® Report Generator 11.6
Words and Delimiters
One or more words make up each CA Easytrieve statement. A word can be a keyword, field name, literal, or symbol. All
words begin with a non-blank character. A delimiter or the end of the statement area terminates these words. Delimiters
make statements readable but are not considered part of the attached word. CA Easytrieve delimiters are shown in the
following table:
Delimiter Description
space The basic delimiter within each statement.
' single quote Encloses literals that are alphanumeric.
. period Terminates a statement.
, comma Used optionally for readability.
() parentheses Enclose multiple parameters and portions of arithmetic
expressions (the left parenthesis acts as a basic delimiter).
: colon Used as a delimiter for file, record, and field qualifications.
At least one space must follow all delimiters, except the left parenthesis and colon {( and :}. The word RECORD-COUNT
is shown below with various delimiters:
RECORD-COUNT
FILEONE:RECORD-COUNT
(RECORD-COUNT)
'RECORD-COUNT'
RECORD-COUNT,
RECORD-COUNT.
Keywords
Keywords are words having specific meaning to CA Easytrieve. Some keywords are reserved words. You can use non-
reserved keywords in the appropriate context as field names, whereas reserved words cannot be used as field names. For
a list of all reserved keywords, see Symbols and Reserved Words.
Multiple Parameters
You must enclose multiple parameters within parentheses to indicate group relationships. If parentheses are not used,
only one parameter is assumed. The following example is a CA Easytrieve statement with multiple parameters:
MASK (A BWZ '$$,$$9.99')
Field Names
Field names are composed of a combination of not more than 128 characters chosen from the following:
• Alphabetic characters A to Z (lower and upper case)
• Decimal digits 0 to 9
• All special characters, except delimiters
The first character of a field name must be an alphabetic character, a decimal digit, or a national character (#, @, $).
In addition, a field name must contain at least one alphabetic or special character to distinguish the field name from a
204
CA Easytrieve® Report Generator 11.6
number. All working storage field names must be unique, as well as all field names within a single file. If you use the same
field name in more than one file, or in a file and in working storage, you must qualify the field name with the file name or
the word WORK. A qualified field name consists of the qualifying word followed by a colon and the field name. You can
use any number of spaces, or no spaces, to separate the colon from either the qualifying word or the field name.
Assume FLD1 occurs in both working storage and the file FILEA. FLD1 can be qualified in the following ways:
FILEA: FLD1
FILEA:FLD1
FILEA : FLD1
WORK:FLD1
Labels
Labels identify specific PROGRAMs, JOBs, PROCedures, REPORTs, SCREENs, and statements. Labels can be 128
characters long, can contain any character other than a delimiter, and can begin with an alphabetic character (A to Z), a
numeric character (0 to 9), or a national character (#, @, $); they cannot consist of all numeric characters.
Identifiers
Identifiers are words that name things (field name, statement labels, etc.) in CA Easytrieve. Identifiers cannot contain
these delimiters:
, comma
' single quote
( left parenthesis
) right parenthesis
: colon
Arithmetic Operators
CA Easytrieve® Report Generator arithmetic expressions use the following arithmetic operators:
• multiplication (*)
• division (/)
• addition (+)
• subtraction (-)
See Activity Section - Processing and Logic for more information.
The arithmetic operator must lie between two spaces.
Alphanumeric Literals
Alphanumeric literals are words meant to be taken literally. They are enclosed within single quotes, and can be up to
254 characters long. An alphanumeric literal can contain alphabetic characters A to Z and numeric characters 0 to 9.
Whenever an alphanumeric literal contains an embedded single quote, you must code two single quotes. For example,
the literal O'KELLY is coded as:
'O''KELLY'
205
CA Easytrieve® Report Generator 11.6
Numeric Literals
Numeric literals can contain 18 numeric digits (characters 0 to 9). You can indicate the algebraic sign of a numeric
literal by attaching a plus (+) or a minus (-) prefix to the numeral. Also, you can use a single decimal point to indicate a
maximum precision up to 18 decimal positions. The following examples are valid numeric literals:
123
+123
-123.4321
Hexadecimal Literals
Hexadecimal literals are words used to code values that contain characters not available on standard data entry
keyboards. Prefix a hexadecimal literal with the letter X and a single quote (X'), and terminate it with a single quote.
CA Easytrieve compresses each pair of digits that you code within the single quotes into one character. CA Easytrieve
permits only the digits 0 to 9 and the letters A to F. The following hexadecimal literal defines two bytes of binary zeros:
X'0000'
Describe Files and Fields
All of the files, their associated fields, and working storage fields in your CA Easytrieve Report Generator program must
be described before they are referenced.
This article includes the following information:
Defining Data
You typically define data fields in the section of your program called the library. The library defines the data in terms of
fields, records, and files. A typical file layout follows:
NAME FIELD ADDRESS FIELD
┌────────┴───────┐┌────────────┴─────────────┐
RECORD { Jones, John J. 16822 Evergreen Chicago ... )
)
Hammond, Martha 422 Ash Ave. Evanston .. )
)
Gray, Frederick 16 Apple St. Lockport .. )
)
Freud, William G. 754 Lake St. Peotone .. ) F
) I
______________________________________________ ) L
) E
______________________________________________ )
)
______________________________________________ )
. )
. )
. )
Defining File Attributes
The FILE statement is used to describe a file or a database.
206
CA Easytrieve® Report Generator 11.6
Defining Field Data
Fields are defined in the library following the FILE statement, or later in the job activity, by using the DEFINE statement.
Two categories of data can be defined:
• File data (fields defined within a record).
• Working storage data (fields defined in working storage).
FILE Statement
The FILE statement describes the files you are using as input to your program and any files your program creates (output)
other than reports. Enter FILE statements at the beginning of the library section.
The FILE statement has the following format:
FILE file-name [file attributes]
• FILE
Specifies that a file name and description are to follow. File-name and file attributes describe the file you are using and
are typically supplied by your data processing department.
• file-name
A 1- to 128-character name used to define your file to CA Easytrieve Report Generator. All statements that operate on
the file refer to this name. File-name is also typically used on your JCL, CLIST, or EXEC statements to reference the
file. Every FILE statement must have a file-name immediately following the FILE keyword and it must be unique within
your program.
• file attributes
The FILE statement has many parameters that describe file attributes. File attributes are as varied as the methods and
environments available for storing data. Most file attributes are beyond the scope of this article. In general, they include
parameters for describing file type, storage device type, and record format. They are all optional and depend on the
particular environment in which you are operating. For complete FILE statement syntax, see FILE Statement.
DEFINE Statement
The DEFINE statement specifies data fields within a record on a file or within working storage:
• Four parameters are always required: field-name, start-location, field-length, and data-type.
• Additional parameters include the number of decimal positions for quantitative fields, HEADING, and MASK.
This statement has the following format:
DEFINE field-name start-location field-length +
data-type [decimal-positions] [HEADING 'heading-literal'] +
( ( ))
(MASK {[mask-identifier] [BWZ] ['mask-literal']})
( ( ))
• field-name
You create your own field-names or use already existing field names (provided to you in a record layout):
207
CA Easytrieve® Report Generator 11.6
– Field-names must be unique within a file.
– The name cannot be all numeric characters.
– The name can be 1 to 128 alphanumeric characters in length.
– The name must begin with A to Z, 0 to 9, or a national character (#, @, $).
– Special characters, such as dollar sign and hyphen, can be used, but not delimiters.
• start-location
The start location is the beginning location of a field in a record, relative to the first position (position 1) of the record.
Start location can be explicitly defined based on its distance from position 1 of the record:
NAME 17 starts in position 17
ADDRESS 37 starts in position 37
PAY-NET 90 starts in position 90
Here is an example of where the NAME field would appear in the previous record:
NAME field
┌─────────────┴───────────┐
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ X│ X│ X│ X│ X│ X│ X│ X│ ...
└───────────────────────────────────────────────────────────────────────┘───
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 ...
• field-length
You specify the length of a field in bytes (characters and/or spaces). The length of the NAME field in the previous
example is eight characters.
NAME 17 8
• data-type
You describe the type of data a field contains by coding the letter abbreviation for that type after the field-length. The
data-types are:
Type Maximum Field Length
A Alphanumeric 32,767
N Numeric 18
P Packed 10
U Unsigned Packed 9
B Binary 4
The data type of the NAME field (which probably contains only alphabetic characters) is A for alphanumeric:
NAME 17 8 A
• decimal-positions
This is an option that specifies the desired number of decimal positions for a field name. By specifying decimal
positions in your field description, you:
– Identify a field to CA Easytrieve Report Generator as being quantitative (a field that contains a quantity, as opposed
to a numeric identifier or code).
– Identify the field to be automatically totaled when specified in a CONTROL report.
– Allow for proper placement of commas and decimals with leading (high-order) zeros suppressed when the field is
printed.
These types of data can have decimal positions:
208
CA Easytrieve® Report Generator 11.6
– N (Numeric)
– P (Packed)
– B (Binary)
– U (Unsigned Packed)
Specify the decimal-positions by coding an integer (0 to 18) after the data-type. For example:
AMOUNT 40 5 N 2
is a five-byte numeric field with two decimal positions.
• HEADING
You use the HEADING parameter to specify an alternative column heading for a field. (The default column heading
is the field-name.) The column heading you specify is automatically used on report output unless overridden by a
HEADING statement in the activity section.
Place the alternate column heading within single quotes. For example:
CL-NAME 5 20 A HEADING 'CLIENT NAME'
produces the column heading:
CLIENT NAME
To stack a column heading, place each word in single quotes. You now must enclose the words in parentheses. For
example:
CL-NAME S 20 A HEADING ('CLIENT' 'NAME')
produces the column heading:
CLIENT
NAME
• MASK
Use the MASK parameter to create a customized edit mask. An edit mask is an optional pattern of characters
specifying how numeric data is to be printed. (Alphanumeric fields cannot be edited.) To create an edit mask, use
combinations of the following characters:
Character Meaning
9 Formats digits
Z Suppresses Leading zeros
* Replaces leading zeros with an asterisk
- Prints a minus sign prior to the first non-zero digit of a negative
number
$ Prints a currency symbol prior to the first non-zero digit
Each digit in the field must be designated by a character in the mask. For example:
Edit Mask Field Value Result
$$,$$9 01234 $1,234
$$,$$9 93142 $93,142
For clarity, you can include commas in the edit mask. Commas are printed in whatever location you indicate in the
mask, but are suppressed if the field value does not exceed the number of places to the right of the comma.
209
CA Easytrieve® Report Generator 11.6
Defining Edit Masks
Some standard edit masks you might use in your programs are shown here:
Edit Mask Used For
'(999)999-9999' Telephone Number
'999-99-9999 Social Security number
'Z9/99/99' Date
'$$,$$$,$$9.99 CREDIT' Money (with floating $)
'*,***,***,999.99-' Protected Check Amount
'-,---,--9.99' Negative Number
This statement has the following format:
[MASK {[mask-identifier] [BWZ] ['mask-literal']}]
• MASK is the CA Easytrieve Report Generator keyword that indicates an edit mask is to follow.
• Use the mask-identifier to name the edit mask that follows it. If you name a mask, you can reuse it on other field
definitions by specifying the name only. This means that once you have defined a mask, you don not have to define it
again to use it again. A name can be any single letter from A to Y.
• BWZ (blank when zero) specifies that a field should not be printed if the entire field contains zeros. Simply code the
letters BWZ whenever you want to suppress an all-zero field. BWZ is not carried over to other fields when using a
mask-identifier.
• The mask-literal is the actual format of the mask. It must be enclosed in single quotes and include one edit character
for each digit in the field being described.
Examples of Edit Masks
Given a numeric field with the contents 012345678, the following masks produce the results shown:
Mask Result
'999-99-9999' 012-34-5678
'Z99,999,999' 12,345,678
'ZZZ,ZZZ,999' 12,345,678
'$$$,$$$,999' $12,345,678
'***,***,999' *12,345,678
Masking Negative Values
Fields that can contain a negative value can be masked so that an negative indicator appears when the value is printed.
An negative indicator, such as minus sign (-), or the letters CR (for credit), or any other chosen indicator, prints only when
the field contains a negative value. To include a negative indicator, mask the field as normal with all digits are accounted
for, and then add the indicator to the right end of the mask.
Given a numeric field with the contents -012345678, the following masks produce the results shown:
Mask Result
'$$$,$$$,999 CREDIT' $12,345,678 CREDIT
'$$$,$$$,999-' $12,345,678-
'Z99,999,999-' 12,345,678-
210
CA Easytrieve® Report Generator 11.6
The indicators CREDIT and minus (-) print only if the field contains a negative value.
Default Edit Masks
Quantitative fields (fields defined with positions to the right of a decimal point) have system default edit masks that
account for the automatic printing of commas and decimal points in printed totals.
Numeric fields with no decimal positions defined are printed without commas or decimal points and are not automatically
totaled on control reports.
Assuming a field named PAY has a value of 1000, the following table gives the corresponding default edit masks and
results for some possible field definitions:
Field Definition Default Mask Result
PAY 10 5 N 0 'ZZ,ZZZ-' 1,000
PAY 10 5 N 2 'ZZZ.99-' 10.00
PAY 10 5 N '99999' 01000
NOTE
The number of decimal positions can be zero (0).
Defining Working Storage
Working storage gives you a method for setting aside a temporary area of storage in the computer memory. Working
storage is a place to keep the results of calculations or other information that is created during the running of a CA
Easytrieve Report Generator program.
Define working storage by specifying W as the start location. The following example defines a numeric working storage
field four characters long with two decimal positions. This field could be defined in the library section or in an activity prior
to being referenced.
WORK-DEDUCT W 4 N 2
DEFINE Within an Activity
You usually specify file fields and working storage fields in your CA Easytrieve Report Generator library section, but you
can also define them within an activity.
Compare the following two examples. The first shows DEFINE statements in the library section; the second shows
DEFINE statements in an activity section. Remember, the DEFINE keyword is optional when defining fields in the library
section.
The following example shows fields defined in the library section of a program. (The keyword DEFINE is shown but is
optional.) There are no fields defined in the activity section.
[ FILE PERSNL FB(150 1800)
| DEFINE EMP# 9 5 N
Library { DEFINE EMPNAME 17 20 A
... | DEFINE EMP-COUNT W 4 N
[ *
[ JOB INPUT PERSNL NAME MYPROG
| EMP-COUNT = EMP-COUNT + 1
Activities { PRINT REPORT1
211
CA Easytrieve® Report Generator 11.6
... | *
| REPORT REPORT1
[ LINE EMP# EMPNAME EMP-COUNT
In contrast to the previous example, this example shows fields defined in the activity section of a program. (The DEFINE
keyword is required.)
[ FILE PERSNL FB(150 1800)
Library { SALARY-CODE 134 2 N
... [ *
{ JOB INPUT PERSNL NAME MYPROG
| DEFINE EMP# 9 5 N
Activities { DEFINE EMPNAME 17 20 A
... | PRINT REPORT1
| *
| REPORT REPORT1
[ LINE EMP# EMPNAME SALARY-CODE
When fields are defined within an activity, each field definition must start with the DEFINE keyword and physically be
defined before the field is referenced.
Defining Static Working Storage
Static working storage fields are fields used for storing accumulated values that are printed at the end of a report or are
used to compute some other values at the end of a report or at control breaks, such as averages.
To define static working storage fields in your program, type S in the position on the DEFINE statement where you
typically type the field starting position or a W. For example:
AVG-GROSS S 8 N 2
Static working storage fields are necessary because of the way CA Easytrieve Report Generator processes reports. In the
Activity Section - Input and Output article, we explain the PRINT statement and the process that occurs when reports are
either sequenced (by the SEQUENCE statement) or multiple within one JOB activity (more than one REPORT statement
is used).
In both cases, data is sent to an intermediary file called a work file or spool file. Work files do not get formatted into reports
(through report definition statements) until they have first been sequenced or until the system printer becomes available.
Due to the use of intermediary work files, two different types of working storage fields are needed. The following
discussion provides the differences between them and helps you to understand the need for these two field types.
Static Versus Non-Static
Unlike static working storage fields (type S), non-static working storage fields (type W) are sent to work files for every
record in the input file. This is done whenever the non-static working storage field is referenced in a REPORT subactivity.
If such a field is used to accumulate values during the processing of an entire file, its value, at the time each record is
sent to the work file, appears on the record in the work file. If the file is then sequenced, the non-static working storage
fields are sequenced with the rest of the fields on the record. This means that accumulated results do not appear, either
internally or when printed, in the order they were accumulated.
Therefore, any calculations based on the value of a non-static working storage field performed at the time of report
formatting are likely to produce results that are in error. This is true only for non-static working storage fields (type W) used
to accumulate values for sequenced reports. For example:
212
CA Easytrieve® Report Generator 11.6
│ Work File Before SEQUENCE │ │ Work File After SEQUENCE │
│─────────────────────────────│ │─────────────────────────────│
│ SEQUENCE │ W-TYPE │ │ SEQUENCE │ W-TYPE │
│ KEY │ ACCUMULATOR │ │ KEY │ ACCUMULATOR │
│ FIELD │ FIELD │ │ FIELD │ FIELD │
│─────────────│───────────────│ │─────────────│───────────────│
│ ZZZ │ 1 │ ───> │ AAA │ 3 │
│ BBB │ 2 │ │ BBB │ 2 │
│ AAA │ 3 │ │ CCC │ 7 │
│ PPP │ 4 │ │ PPP │ 4 │
│ QQQ │ 5 │ │ QQQ │ 5 │
│ SSS │ 6 │ │ SSS │ 6 │
│ CCC │ 7 │ │ ZZZ │ 1 │
In the previous example, the W-type field is incremented by 1 each time a record is processed. Once the work file has
been sequenced and the report is formatted, the value contained in the W-type field when last processed (output to the
report) is now different than it was prior to sequencing. If you attempted to compute averages, based on this value, your
results would be in error.
Static working storage fields are not sent to work files. This means they are not affected by sequencing. The last value
accumulated into an S-type field remains unchanged regardless of what is done to the work file and is therefore suitable
for any end-of-report calculations such as averaging. For example:
│ Report File Before SEQUENCE │ │ Work File Before SEQUENCE │
│─────────────────────────────│ │─────────────────────────────│
│ SEQUENCE │ S-TYPE │ │ SEQUENCE │S-FIELD VALUES │
│ KEY │ ACCUMULATOR │ │ KEY │ NOT PASSED │
│ FIELD │ FIELD │ │ FIELD │ TO WORK FILE │
│─────────────│───────────────│ │─────────────│───────────────│
│ ZZZ │ 1 │ ───> │ ZZZ │ │
│ BBB │ 2 │ │ BBB │ │
│ AAA │ 3 │ │ AAA │ │
│ PPP │ 4 │ │ PPP │ │
│ QQQ │ 5 │ │ QQQ │ │
│ SSS │ 6 │ │ SSS │ │
│ CCC │ 7 │ │ CCC │ │
This example illustrates that static working storage fields are not copied to work files and therefore are not sequenced, as
are non-static (type W) fields. The static field shown in the previous example contains the value seven (7) at the time any
averaging is performed at end-of-report.
Initializing Working Storage Fields
To give working storage fields an initial value at the beginning of your program, use the VALUE option of the DEFINE
statement. The following example assigns an initial value of JANUARY to the alphanumeric working storage field CURR-
MON. When the value clause is not used, numeric working storage fields are automatically initialized to zeros and
alphanumeric working storage fields to blanks.
CURR-MON W 10 A VALUE 'JANUARY'
213
CA Easytrieve® Report Generator 11.6
Reset Option
The RESET option is used only for W working storage fields. When coded on the field definition for a W field, RESET
returns the field to its initial value whenever JOB or SORT executes. You cannot use RESET for redefine fields (fields
having overlay redefinition).
Redefining a Field
Sometimes it is necessary to break a field into several parts to get the exact information you want. A birth date, for
example, might have been entered originally as one field in a record. Now, you want to access this information by the
month, day, or year.
Explicit Redefinition
You can explicitly redefine the field as follows:
DATE-OF-BIRTH 103 6 N
MONTH 103 2 N
DAY 105 2 N
YEAR 107 2 N
Explicit redefinition requires the exact starting location of each field. Here is a physical representation of the previously-
defined field:
DATE-OF-BIRTH
| | | | | | |0|2|1|0|5|5| | | | |
| | |
position 103 105 107
in
record:
In this example, the MONTH (02) starts in position 103 and occupies positions 103 and 104. The DAY starts in 105 and
occupies positions 105 and 106. Finally, the YEAR starts in 107 and occupies positions 107 and 108.
Overlay Redefinition
You can perform overlay redefinition of a field by including the original field-name as the starting location for all
subsequent fields in the redefinition. This is especially useful when redefining a working storage field that does not have a
numeric starting position. For example:
DATE-OF-BIRTH W 6 N
MONTH DATE-OF-BIRTH 2 N
DAY DATE-OF-BIRTH +2 2 N
YEAR DATE-OF-BIRTH +4 2 N
To specify the starting position of the redefining field, use the original field name plus any offset (+2 or +4 in the previous
example).
When using overlay redefinition, verify that the redefining fields fit within the storage boundaries of the redefined field.
214
CA Easytrieve® Report Generator 11.6
Implicit Start-location
You can define the start-location of a field with an implicitly-defined position in the record. Implicitly defining a start-location
eliminates the need to identify the actual start-location of a field. Implicit start-locations are most useful when you are
creating output files, because output files generally have contiguous field locations.
Use an asterisk in place of the numeric start-location when implicitly defining a field. The asterisk implies that the field
begins in the next available starting position (highest location defined so far, plus one). The following example defines
contiguous fields in a record. Because EMP# begins in position 1, NAME begins in position 6, FILLER1 in position 22, and
ADDRESS in position 32. All locations between 1 and 70 are accounted for.
EMP# 1 5 N
NAME * 16 A
FILLER1 * 10 N
ADDRESS * 39 A
FILE Statement Revisited
Earlier in this article, we introduced the FILE statement for describing input and output files. We also mentioned that there
are parameters for the FILE statement. In the following sections, we introduce two FILE statement parameters.
Virtual File Manager (VFM)
The VIRTUAL parameter of the FILE statement invokes the virtual file management facility (VFM) of CA Easytrieve Report
Generator.
This statement has the following format:
| | [F]
FILE file-name [VIRTUAL [RETAIN]] [V] logical-record-length
| | [U]
VFM provides an easy method for establishing temporary work files without special job control or file allocation
statements. By using VFM, you can establish your own extract or temporary files, using only CA Easytrieve Report
Generator keywords.
The FILE keyword and a user-defined file name are required.
• VIRTUAL
Designates that the named file is to be a temporary VFM file. VFM files consist of a dynamically-allocated space in
memory (64K default). If the allocated space is exhausted, VFM automatically writes the excess data to a single spill
area on disk.
• RETAIN
Specifies that the VFM file is to remain in memory until the end of the associated CA Easytrieve Report Generator
execution. If RETAIN is not specified, the VFM file is deleted when it has been read back into your program.
• logical-record-length
You must specify a record length for all output files. When specifying record length, you must also specify record type
(F, V, or U). Block size is not required, because VFM files are automatically blocked.
EXIT Parameter
The EXIT parameter on the FILE statement invokes a user routine for every input or output operation performed on
the named file. You can use EXIT to access your own user-written routine to convert non-standard data files that CA
Easytrieve Report Generator does not process directly.
215
CA Easytrieve® Report Generator 11.6
NOTE
EXIT is not valid for VFM.
FILE file-name [EXIT (program-name +
[ | ] |
|USING ({ parm-field-name }... ) | [MODIFY] )] +
| | parm-literal | |
[ [ ] ]
[WORKAREA area-length]
The EXIT parameter followed by program-name indicates the routine or subprogram to be executed.
• USING
Specifies any parameters to be passed to the exit routine. It is limited to working storage fields, system-defined fields,
and card literals.
• MODIFY
Specifies that CA Easytrieve Report Generator provides input or output services but that the exit can inspect and
modify each record after input and before output.
• WORKAREA
Specifies that CA Easytrieve Report Generator sets up a special area of storage to be used as the data buffer for the
file. Area-length is used to specify the length of the data buffer.
COPY Statement
The COPY statement duplicates the field definitions of a named file. You can copy the field definitions of a given file an
unlimited number of times.
This statement has the following format:
COPY file-name
If you copy the same field name into more than one file and the files are used in the same activity, you must qualify the
field when referencing it in your programs; otherwise, CA Easytrieve Report Generator cannot uniquely identify the data
reference. You can qualify fields in CA Easytrieve® Report Generator by preceding them with their file name and a colon.
For example, OUTFILE:NAME.
Example of COPY Statement
FILE PERSNL FB(150 1800)
EMPNAME 17 20 A HEADING ('EMPLOYEE NAME')
NAME-LAST EMPNAME 8 A HEADING ('FIRST' 'NAME')
NAME-FIRST EMPNAME +8 12 A HEADING ('LAST' 'NAME')
FILE SORTWRK FB(150 1800) VIRTUAL
COPY PERSNL
SORT PERSNL TO SORTWRK USING +
(NAME-LAST NAME-FIRST) NAME MYSORT
JOB INPUT SORTWRK NAME MYPROG
PRINT REPORT1
216
CA Easytrieve® Report Generator 11.6
*
REPORT REPORT1
LINE NAME-FIRST NAME-LAST
Activity Section - Processing and Logic
The activity section of a CA Easytrieve program is where all processing logic and report declarations reside. The activity
section contains PROGRAM, SORT, and JOB activities.
JOB Activities
JOB Statement
The JOB statement defines and initiates processing activity. It also identifies the name of the automatic input file.
This statement has the following format:
JOB [INPUT file-name] [NAME job-name]
JOB statement parameters can be coded in any order.
• INPUT
The optional INPUT parameter identifies the automatic input to the activity. This means that all input-related logic, such
as opening the file, checking for end of file, and reading, are all controlled by CA Easytrieve® Report Generator.
When you do not specify INPUT, CA Easytrieve® Report Generator automatically provides an input file. If a SORT
activity immediately preceded the current JOB activity, the default input is the output file from that SORT activity.
Otherwise, the default input is the first file named in the library section.
• file-name
The file-name identifies the automatic input files. It can identify any file defined in the library section of the program
eligible for sequential input processing.
• NAME job-name
The optional NAME parameter names the JOB activity and is normally used only for documentation purposes. The job-
name:
– Can be up to 128 characters long
– Can contain any character other than a delimiter
– Can begin with A to Z, 0 to 9, or a national character (#, @, $)
– Must not consist of all numeric characters.
The following example shows the location of the JOB statement and the subactivities in a CA Easytrieve® Report
Generator program:
** Library **
*
Activity JOB INPUT PERSNL NAME EXAMPLE
Logic IF DEPARTMENT = 911 THRU 914 921
DEDUCTIONS = GROSS - NET
PRINT EXAMPLE
END-IF
*
217
CA Easytrieve® Report Generator 11.6
Report REPORT EXAMPLE
SEQUENCE DEPARTMENT NAME
TITLE 1 'EXAMPLE REPORT'
LINE 1 EMPNAME DEPARTMENT EMP# GROSS NET DEDUCTIONS
You can use the logic subactivity to examine and manipulate data, initiate printed reports, and write data to a file.
You can use the report subactivity to format the desired report.
Conditional Expressions
Data selection and manipulation takes place in the logic section of a CA Easytrieve® Report Generator program. Logic is
coded immediately after the JOB statement.
IF Statement
Processing within a JOB activity can be dependent on the conditional (IF) statements present in the program:
• When an IF statement is present, records read from the input file are processed according to the conditions it states.
• Every IF statement must end with END-IF.
[EQ = ]
|NE -=| #field two #
IF field one {GT > } #literal #
|GE >=| #arithmetic-expression #
|LT < |
{LE <=]
[statements executed for true IF condition]
[ELSE-IF alternate-expression]
[statements executed for true ELSE-IF condition]
[ELSE]
[statements executed for false IF condition]
END-IF
IF Statement Examples
• Comparing the value of a field to a literal:
IF DEPT = 910
IF EMPNAME = 'SMITH'
IF AMT GE 500
• Comparing two fields:
IF DIV = HOLD-DIV
• Comparing the value of a field to a series or range of values:
218
CA Easytrieve® Report Generator 11.6
IF STATE = 'GA' 'SC' 'TN'
IF CLASS = 'A' THRU 'E'
IF AMT NE 100 THRU 500
IF DEPT = 900 940 THRU 950 960 970 THRU 980
Arithmetic Operators
These arithmetic operators are valid in conditional statements:
Operators Meaning
EQ = Equal to
NE Ø= Not equal to
GT > Greater than
GE >= Greater than or equal to
LT < Less than
LE <= Less than or equal to
• IF/ELSE
ELSE directs CA Easytrieve® Report Generator to perform alternative processing when the condition established by
the IF statement is not met:
• For true IFs, all commands up to the ELSE (or END-IF if no ELSE is present) are executed.
• For false IFs, commands between ELSE and END-IF are executed.
• Following END-IF, processing continues regardless of the result of the IF.
IF/ELSE Example
IF DIVISION = 'A' THRU 'L'
DEDUCTIONS = GROSS * .15
ELSE
DEDUCTIONS = GROSS * .18
END-IF
In this example, records with a DIVISION field containing values in the range A to L are processed according to the
statement between the IF and ELSE statements (DEDUCTIONS = GROSS * .15). For records with DIVISION not in the
range A to L, the statement following ELSE (DEDUCTIONS = GROSS * .18) is executed. END-IF signifies the end of the
condition.
In words, we could restate the condition in the above example something like this, "For divisions A to L, deductions are
equal to 15 percent of the gross; for all other divisions, deductions are equal to 18 percent of the gross."
• ELSE-IF
ELSE-IF is optional and identifies a conditional expression to be tested when the previous conditional expression is
false. ELSE-IFs permit multiple conditions to be nested without requiring an END-IF for each condition. You can code
as many ELSE-IFs as necessary.
ELSE-IF Example
IF DIVISION = 'A' THRU 'L'
DEDUCTIONS = GROSS * .15
ELSE-IF DIVISION = 'M' THRU 'R'
DEDUCTIONS = GROSS * .2
ELSE
219
CA Easytrieve® Report Generator 11.6
DEDUCTIONS = GROSS * .18
END-IF
Special IF Statements
Use special IF statements to check the integrity of the data in your files.
This statement has the following format:
( ALPHABETIC )
( NULL )
( NUMERIC )
IF field-name [NOT] ( SPACE )
( SPACES )
( ZERO )
( ZEROS )
( ZEROES )
Special IF statement keywords check for the following conditions:
Keyword Condition
ALPHABETIC Value containing characters A to Z and blank spaces
NULL No current value
NUMERIC Value containing digits 0 to 9
SPACE Value containing all blank spaces
SPACES
ZERO Value containing all zeros (0)
ZEROS
ZEROES
Special IF Examples
This statement is true ... for this condition ...
IF AMT NOT NUMERIC AMT does not contain all digits
IF NAME SPACES NAME contains all spaces
IF STATE ALPHABETIC STATE contains all letters and spaces
IF AMT-DUE ZERO AMT-DUE contains all zeros
Combining Conditional Expressions
You can compound conditional expressions by combining them through the logical connectors AND and OR. For example,
if you need to determine a value based on two conditions, you can connect the conditions with a logical connector:
IF DIVISION = 'A' THRU 'L' AND AMOUNT GE 15
This statement is true when DIVISION is equal to a letter in the range A to L and when AMOUNT is also greater than
or equal to 15. Both conditions must be true for the entire statement to be true. The following statement uses the OR
connector:
IF DIVISION = 'A' THRU 'L' OR AMOUNT GE 15
220
CA Easytrieve® Report Generator 11.6
This statement is true when DIVISION is equal to a letter in the range A to L or when AMOUNT is greater than or equal to
15 or when both conditions are true. Either one or both of the conditions can be true to make the entire statement true.
When used together in the same statement, conditions connected by AND are examined before conditions connected by
OR. For example:
IF DIVISION = 'A' AND AMOUNT GE 15 OR STATE = 'GA'
In this statement, CA Easytrieve® Report Generator examines the portion "DIVISION = 'A' AND AMOUNT GE 15" first.
If both sides of the AND in that portion are found to be true then the entire statement is true. If not, then the portion "OR
STATE = 'GA'" is examined and, if it is found to be true, the entire statement is still true. If conditions on both sides of the
OR are false, then the entire statement is false.
The following table helps you visualize the concept of logical connectors. The assumptions for the table are:
DIVISION = A
AMOUNT = 15
STATE = GA
The following IF statement ... is ...
IF DIVISION = 'A' AND AMOUNT GE 15 OR STATE = 'GA' TRUE
IF DIVISION = 'A' AND AMOUNT = 14 OR STATE = 'FL' FALSE
IF DIVISION = 'A' OR AMOUNT = 15 AND STATE = 'FL' TRUE
IF DIVISION = 'B' AND AMOUNT = 15 AND STATE = 'FL' FALSE
IF (DIVISION = 'A' OR AMOUNT = 15) AND STATE = 'FL' FALSE
NOTE
Inserting parentheses around a set of conditions can alter the outcome of the statement. Remember these rules:
• All conditional expressions are considered one statement.
• AND statements are evaluated before OR statements.
• Parentheses may alter the normal order of evaluation.
Calculations
There are four arithmetic operations in CA Easytrieve® Report Generator:
• Multiplication (*)
• Division (/)
• Addition (+)
• Subtraction (-)
Multiplication and division are performed before addition and subtraction in order from left to right. There must be a space
before and after the arithmetic operators.
[ ] [ * ]
| = | | / |
field name { } value 1 { } value 2
| EQ| | + |
[ ] [ ]
221
CA Easytrieve® Report Generator 11.6
Parentheses in Calculations
You can use parentheses to override the normal order of operation. Operations contained in parentheses are performed
first. For example:
RESULTS = GROSS - AMT * 1.3
is the same as:
RESULT = GROSS - (AMT * 1.3)
but different from:
RESULT = (GROSS - AMT) * 1.3
You can nest parentheses to further alter the order of operation. Operation proceeds from the innermost set of
parentheses to the outermost:
RESULT = 1.3 * (GROSS - (AMT + DEDUCT))
In this example, AMT and DEDUCT are added before being subtracted from GROSS. After subtraction, the difference is
multiplied by 1.3 and the product of this is assigned to the RESULT field.
Assignment Statement
The assignment statement establishes a value in a field by copying the value from another field or literal. The value on the
right of the equal sign is copied to the field on the left of the equal sign. The assignment statement also accomplishes data
conversion, such as packing or unpacking numeric data.
[= ] ìsend-field-name ]
receive-field-name { } ísend-literal }
[EQ] îarithmetic expression]
Simple Assignment Examples
HOLD-DIV = DIV
DEPT-NAME = 'ACCOUNTING DEPT'
RATE = 1.1
MOVE Statement
Use the MOVE statement to transfer data from one location to another. MOVE is useful for moving data without
conversion and for moving character strings with variable lengths:
• You can move a field or a literal to a field, or move a file to a file.
• A sending field longer than a receiving field is truncated on the right.
• A receiving field longer than the sending field is padded on the right with spaces or an alternative fill character.
• Spaces or zeros can be moved to one or many fields.
The MOVE statement has two formats.
222
CA Easytrieve® Report Generator 11.6
MOVE Format 1
[send-file-name ] [ ] [receive-file-name ]
MOVE {send-field-name} |send-length| TO { } +
[send-literal ] [ ] [receive-field-name]
[receive-length] [FILL fill-character]
When you specify Format 1, data moves from one field to another, filling with spaces or a specified fill character on the
right. The FILL parameter enables you to place specified characters in the unused spaces of the new field (the default is
blank spaces).
NOTE
The MOVE statement does not convert data as it is moved. To convert the data from one field's data type to
another's, use the Assignment statement.
Example 1
MOVE NAME 20 TO HOLD-NAME
This example moves the first 20 characters of the NAME field to the HOLD-NAME field.
Example 2
MOVE NAME CTR TO HOLD-NAME FILL '*'
In this example, a numeric length for the sending field (NAME) is replaced by a field name CTR. CTR contains a numeric
value that determines the number of characters moved to HOLD-NAME. Any remaining spaces after the move (assuming
the sending field is smaller than the receiving field) are filled with asterisks.
MOVE Format 2
Syntax
[ NULL ]
| SPACE |
MOVE { SPACES } TO field-name-1 field-name-n
| ZERO |
| ZEROS |
[ ZEROES ]
You can use Format 2 to initialize the receiving field.
Example
MOVE SPACES TO NAME, HOLD-NAME, HOLD-DIV
This example fills all of the named fields with blank spaces.
MOVE LIKE Statement
MOVE LIKE moves the contents of fields in one file to identically-named fields in another file.
Syntax
223
CA Easytrieve® Report Generator 11.6
MOVE LIKE file-name-1 TO file-name-2
It is important to understand that the MOVE LIKE statement creates assignments of each LIKE field. These assignments
perform data conversions, if necessary.
Example
FILE INFILE1
EMPNAME 17 20 A
DEPT 98 3 N
AMT 90 4 P 2
FILE OUTFIL1
AMT 1 7 N 2
EMPNAME 8 11 A
JOB INPUT INFILE1 NAME MOVE-LIKE-EXAMPLE
** Logic **
*
MOVE LIKE INFILE1 TO OUTFIL1
** Logic **
In this example, the EMPNAME field of INFILE1 is moved to the EMPNAME field of OUTFIL1, where the last nine
characters are truncated. The AMT field of INFILE1 is moved to the AMT field of OUTFIL1, where it is converted to
numeric format from packed decimal format.
DO/ENDDO Statements
Use the DO and END-DO statements to provide a controlled loop for repetitive program logic.
Syntax
[WHILE]
DO { } conditional-expression
[UNTIL]
** Logic **
END-DO
• [WHILE]
• {}
• [UNTIL]
A WHILE loop evaluates the condition at the top of a group of statements. The UNTIL loop evaluates the condition at
the bottom of a group of statements.
• conditional-expression
Specifies the condition that is the basis for the continuing execution of the loop. Conditional expressions follow the
rules of IF statements.
• END-DO
Terminates the body of the loop associated with the DO statement. An END-DO statement must be specified after
each DO statement and its associated statements.
DO WHILE Example
224
CA Easytrieve® Report Generator 11.6
JOB INPUT PERSNL NAME DO-EX-1
CTR = 0
DO WHILE CTR LT 10
CTR = CTR + 1
** Logic **
END-DO
This DO WHILE statement causes "CTR = CTR + 1" to repeat until CTR is equal to 10. At that point, control transfers to
the first statement after the END-DO statement.
DO UNTIL Example
JOB INPUT PERSNL NAME DO-EX-2
CTR = 0
DO UNTIL CTR GE 10
CTR = CTR + 1
** Logic **
END-DO
This DO UNTIL statement causes "CTR = CTR + 1" to execute the logic once, and then repeat until CTR is equal to 10. At
that point, control transfers to the first statement after the END-DO statement.
As you can see from these examples, you can use the WHILE and UNTIL parameters of the DO statement to perform
identical tasks. The rule of thumb to follow when trying to determine which parameter to use is to use UNTIL if you want to
be sure the logic (CA Easytrieve® Report Generator statements) is executed at least once. The UNTIL parameter causes
CA Easytrieve® Report Generator to perform the logic and then evaluate the conditional expression.
Use WHILE if you do not want the logic executed. The WHILE parameter causes CA Easytrieve® Report Generator to
evaluate the conditional expression and perform the logic only if the condition is true.
DO Nesting Example
You can nest DO statements. (The inner logic loop must be completely within the outer logic loop.)
JOB INPUT PAYROLL NAME DO-EX-3
CTR1 = 0
225
CA Easytrieve® Report Generator 11.6
DO WHILE CTR1 LT 10
CTR2 = 0
DO WHILE CTR2 LT 5
CTR2 = CTR2 + 1
Inner
** Logic ** Loop
Outer
END-DO Loop
CTR1 = CTR1 + 1
** Logic **
END-DO
In this example, the inner DO WHILE loop executes five times for each single execution of the outer loop. When CTR1 is
equal to 10, control is passed to the first statement following the outer END-DO statement.
CASE and END-CASE Statements
The CASE and END-CASE statements are used to conditionally execute one of several alternative groups of statements,
based on the value of a specific field.
Syntax
CASE field-name
WHEN compare-literal-1 [THRU range-literal-1]
(statements)
WHEN compare-literal-n [THRU range-literal-n]
(statements)
[OTHERWISE]
(statements)
END-CASE
• field-name
Specifies a field that contains a value that is compared to the values represented by compare-literal [THRU range-
literal]. Field-name can be a field of any type except a varying length alphanumeric field. If field-name is alphanumeric,
it must be 254 or fewer bytes in length. If field-name is numeric, it must have zero or no decimal places.
• WHEN
You can specify as many WHEN conditions as necessary. At least one WHEN condition is required. You cannot code
statements between CASE and the first WHEN condition. You must supply a unique set of values to be compared with
field-name in each WHEN condition.
• compare-literal [THRU range-literal]
Compare-literal is the value to be compared with field-name. You can specify a single literal, a series of literals, or a
range of literals. A range is represented by compare-literal THRU range-literal. A range is satisfied when field-name
226
CA Easytrieve® Report Generator 11.6
is greater than or equal to the lesser of compare-literal and range-literal and is less than or equal to the greater of
compare-literal and range-literal.
When field-name is alphanumeric, compare-literal and range-literal must also be alphanumeric and must be equal in
length to field-name. When field-name is defined as a numeric data type, compare-literal and range-literal must also be
numeric and must not have any decimal places. Numeric literals need not be equal in length to field-name.
The set of literal values specified for a given WHEN, including the unspecified values implied by a range, must be
unique as compared to the literal values of any other WHEN for the same CASE.
• OTHERWISE
An optional statement that specifies a group of statements to be executed if no WHEN comparison was satisfied.
If OTHERWISE is not specified and field-name does not equal any of the specified WHEN conditions, execution
continues with the statement following END-CASE.
• END-CASE
Terminates the body of the CASE statement. END-CASE must be specified after each CASE statement and its
associated statements.
Nesting CASE Statements
A CASE statement can be nested within a CASE statement. Other conditional execution statements can also be nested
within a CASE statement. A CASE statement can be nested within any other conditional execution statement.
Example
The following example uses CASE to compare the value in JOB-CATEGORY to the range specified in the WHEN clauses
and calculate Christmas bonuses, based on that value:
FILE PERSNL FB (150 1800)
EMPNAME 17 8 A
EMP# 9 5 N
DEPT 98 3 N
GROSS 94 4 P 2
XMAS-BONUS W 4 P 2
JOB-CATEGORY 132 2 N 0
JOB INPUT PERSNL NAME COMPUTE-XMAS-BONUS
CASE JOB-CATEGORY
WHEN 1 THRU 29
XMAS-BONUS = GROSS * 1.03
WHEN 30 THRU 59
XMAS-BONUS = GROSS * 1.05
OTHERWISE
XMAS-BONUS = GROSS * 1.07
END-CASE
PRINT RPT
REPORT RPT
LINE EMPNAME XMAS-BONUS
GOTO Statement
You use the GOTO statement to branch out of the normal top-to-bottom logic flow in a program.
Syntax
[GOTO ] [label ]
{ } {JOB }
227
CA Easytrieve® Report Generator 11.6
[GO TO ] [SCREEN]
This statement directs program control to another area in the program. CA Easytrieve® Report Generator accepts either
GOTO or GO TO.
• GOTO label
Label refers to a statement label. GOTO label transfers control immediately to the first statement following the named
statement label. The statement label can be anywhere in the same activity or procedure. A statement label can:
• Can be up to 128 characters long
• Can contain any character other than a delimiter
• Can begin with A to Z, 0 to 9, or a national character (#, @, $)
• Must not consist of all numeric characters
• GOTO JOB
Transfers control to the top of the current JOB activity. This is useful to stop specific records from further processing.
• GOTO SCREEN
Transfers control to the top of the current SCREEN activity.
Example
JOB INPUT PERSNL NAME DIV-LIST <──────┐ Transfers
IF DIV = 'A' │ Control
GOTO JOB ──────────────────────────┘
END-IF
IF DIV = 'B'
GOTO CHECK-REG-ROUTINE ─────────┐
END-IF │
│ Transfers
** Logic ** │ Control
│
CHECK-REG-ROUTINE <───────────────┘
** More Logic **
STOP Statement
A STOP statement enables you to terminate an activity.
Syntax
STOP [EXECUTE]
• STOP ends the current JOB or SORT activity, completes the report processing for the activity, if any, and then goes on
to the next JOB or SORT activity, if one exists. A FINISH procedure (if one is present) is still executed before going on
to the next JOB or SORT activity.
• STOP EXECUTE immediately terminates all CA Easytrieve® Report Generator execution.
Example
IF AMT NOT NUMERIC
228
CA Easytrieve® Report Generator 11.6
STOP
END-IF
User Procedures (PROCs)
A user procedure (also called PROC for short) is a group of user-written CA Easytrieve® Report Generator statements
designed to accomplish some task. PROCs are useful when developing structured programs that modularize discrete and
repetitive tasks.
PROCs are invoked by using the PERFORM statement, which has the following format:
PERFORM proc-name
• proc-name
Specifies the name of a user-defined procedure located at the end of the activity in which it is performed. Proc-name
can:
• Can be up to 128 characters long
• Can contain any character other than a delimiter
• Can begin with A to Z, 0 to 9, or a national character (#, @, $)
• Must not consist of all numeric characters
As mentioned at the beginning of this section, procedures are discrete modules of program code that perform a task.
When coded, procedures must have this format:
proc-name. PROC
** Procedure Logic **
END-PROC
• PROC
The PROC keyword must follow the proc-name, separated by a period and a space. Proc-name is the same name as
on the PERFORM statement.
• END-PROC
Every PROC must have an END-PROC, which marks the end of the procedure. At END-PROC, control is returned to
the statement following the PERFORM statement that invoked the PROC.
Procedure Example
The following example performs two simple procedures, based on the value of a field named CODE:
IF CODE = 1
PERFORM CODE1-RTN
ELSE
PERFORM CODE2-RTN
END-IF
** Logic **
CODE1-RTN. PROC
229
CA Easytrieve® Report Generator 11.6
ORDER = 'NO'
END-PROC
CODE2-RTN. PROC
ORDER = 'YES'
END-PROC
Nesting PROCs
A PERFORM statement within a procedure can invoke another procedure. For example:
IF DEPT = 911
PERFORM PROCA
END-IF
** Logic **
PROCA. PROC
IF ST = 'NY'
PERFORM PROCB
ELSE
TAX = GROSS * .05
END-IF
END-PROC
PROCB. PROC
TAX = GROSS * .1
END-PROC
START/FINISH Procedures
You use the optional START and FINISH parameters of the JOB statement to automatically incorporate procedures into
processing activities.
Syntax
The format for invoking these procedures is as follows:
JOB INPUT file-name [NAME job-name] +
[START start-proc-name] [FINISH finish-proc-name]
• START start-proc-name
START procedures are used to execute routines prior to execution of the logic in the body of the JOB activity:
– The procedure is invoked automatically after the file is opened but before reading the first input record.
– A typical START procedure might initialize working storage fields or establish a position in a keyed sequenced file.
• FINISH finish-proc-name
FINISH procedures are used to identify a procedure to be executed during the normal termination of the JOB activity:
– The procedure is invoked after the last input record is processed but before any files are closed.
– A typical FINISH procedure displays control information accumulated during execution of the JOB activity.
– CA Easytrieve® Report Generator still executes FINISH procedures if a STOP statement is encountered during the
course of the program, but not if a STOP EXECUTE is encountered.
230
CA Easytrieve® Report Generator 11.6
Processing Tables
A table is a collection of uniform data records in a form suitable for quick reference.
Much like books in a library, a table has two components; an identifier that helps you find the information you are looking
for (analogous to a card catalog number) and the information you are looking for (a book). With tables however, the
identifier is called a search argument; the information you are after is called the description. Each entry in a table must
consist of:
• A search argument that uniquely identifies the entry -- this is defined as a field with the name ARG after the FILE
statement.
• A description (the data) associated with the search argument -- this is defined as a field with the name DESC after the
FILE statement.
Your objective is to obtain the description from a table, based on the search argument. Rules governing the processing of
search arguments are as follows:
• A table file must be arranged in ascending order by search argument.
• No duplicate search arguments can be placed in the file.
• You can use any number of tables in a job.
• A minimum of three entries is required in a table.
The following example shows a table with search arguments and descriptions. The argument is a numeric code used to
look up a descriptive state name:
ARG DESC
01 ALABAMA
02 ALASKA
03 ARIZONA
...
47 WASHINGTON
48 WEST VIRGINIA
49 WISCONSIN
50 WYOMING
Creation of Table Files
The creation of tables involves the inclusion of certain parameters on the CA Easytrieve® Report Generator FILE
statement:
This statement has the following syntax:
[INSTREAM ]
FILE file-name TABLE | |
[max-table-entries]
• TABLE
The TABLE parameter of the FILE statement declares that the file is the object of a CA Easytrieve® Report Generator
SEARCH statement, which is used to access tables. Tables can be either external (stored in a file outside your
program) or instream (data is included within your program). External table files must be sequentially accessible.
• INSTREAM
231
CA Easytrieve® Report Generator 11.6
Denotes that the table file data is within your program. Such data immediately follows the file description after the ARG
and DESC field definitions.
• max-table-entries
Specifies the maximum number of entries (records) in an external table. Specify a value here only if the number of
entries is greater than the maximum stored in the Site Options Table.
Instream Table Example
The word ENDTABLE must be the last entry in an instream table and must be coded in columns 1 to 8:
FILE STATTBL TABLE INSTREAM
ARG 1 2 N
DESC 4 15 A
01 ALABAMA
02 ALASKA
03 ARIZONA
...
47 WASHINGTON
48 WEST VIRGINIA
49 WISCONSIN
50 WYOMING
ENDTABLE
This example defines a table of state names that can now be looked up according to a two-digit code.
Accessing Table Files
SEARCH Statement
The SEARCH statement is used to perform a search of a table. SEARCH can be:
• Coded any place within a JOB, PROGRAM, or SCREEN activity
• Issued any number of times against any number of tables.
Syntax
The SEARCH statement has this format:
SEARCH file-name WITH search-field GIVING result-field
• file-name
The name of the table that appears on the FILE statement.
• search-field
The name of a field that contains a value that is compared to the search argument. It must be the same length and
type as the search argument (ARG).
• result-field
The name of a field into which the description is placed if a match exists between search-field and the search
argument. It must be the same length and type as the description (DESC).
After using the SEARCH statement, you can test to determine whether a match was found between the search-field and
the search argument by using a special IF statement.
The IF statement has this format:
IF [NOT] file-name
232
CA Easytrieve® Report Generator 11.6
External Table Example
FILE PERSNL
EMPNAME 17 8 A
STATE 69 2 A
ZIP 71 5 N
GROSS-PAY 94 4 P 2
POST-OFFICE-DESC W 20 A
FILE ZIPTABLE TABLE 5000
ARG 1 5 N
DESC 7 20 A
JOB INPUT PERSNL NAME TABLE-SEARCH
IF STATE = 'DC' 'IL'
SEARCH ZIPTABLE WITH ZIP GIVING POST-OFFICE-DESC
IF NOT ZIPTABLE
POST-OFFICE-DESC = 'BAD ZIP CODE FOUND'
END-IF
PRINT STATE-REPORT
END-IF
REPORT STATE-REPORT
SEQUENCE STATE
CONTROL STATE
TITLE 1 'REPORT OF EMPLOYEE SALARIES BY STATE'
LINE 1 STATE EMPNAME GROSS-PAY ZIP POST-OFFICE-DESC
SORT Activities
SORT is a separate activity (outside the activity of the JOB statement) that sequences an input file in alphabetical or
numerical order based on fields specified as keys. You can sort on as many fields as your system allows. The SORT
activity uses the sort utility provided by your system.
SORT Statement
Use the SORT statement to specify your sorting requirements.
Syntax
SORT input-file-name TO sorted-file-name +
USING (sort-key-field-name [D] ...) +
NAME sort-name
• input-file-name
The input file to be sorted.
• sorted-file-name
The output file.
• USING sort-key-field-name
Identifies those fields from input-file-name that you use as sort keys. Keys are specified in major-to-minor order. This
dictates how information is sorted. For example, you could sort a file of employee records by region, and then by
233
CA Easytrieve® Report Generator 11.6
location under region, and then by department under location. Region would be the major sort key, location would be
minor, and department would be more minor.
• D
Optionally sorts the field contents in descending order (ascending order is the default).
• NAME sort-name
Like NAME on the JOB statement, this parameter identifies the sort activity and is normally used for documentation
purposes only. Sort-name:
• Can be up to 128 characters long
• Can contain any character other than a delimiter
• Can begin with A to Z, 0 to 9, or a national character (#, @, $)
• Must not consist of all numeric characters
Sort Example
FILE PERSNL FB(150 1800)
EMPNAME 1 10 A
DEPT 11 5 N
GROSS-PAY 16 4 P 2
FILE PAYSORT FB(150 1800)
SORT PERSNL TO PAYSORT +
USING (DEPT GROSS-PAY) +
NAME SORT-EXAMPLE-1
This SORT example sorts the file PERSNL in ascending order, first by DEPT and then by GROSS-PAY under DEPT. This
produces a file containing records in order by department and records with LIKE departments in order by gross pay.
SORT Procedures
CA Easytrieve® Report Generator normally sorts all input records and outputs them into the TO file of the SORT
statement automatically. The output file usually has the same format and length as the input file. However, sometimes it is
desirable to sort only certain records or to modify the contents. To do this, you must write a SORT procedure, which must
immediately follow the SORT statement.
A SORT procedure is executed through the BEFORE parameter of the SORT statement.
Syntax
SORT input-file-name TO sorted-file-name +
USING (sort-key-field-name [D] ... ) +
NAME sort-name +
[BEFORE proc-name]
234
CA Easytrieve® Report Generator 11.6
• A SORT procedure must immediately follow the SORT statement.
• You invoke a SORT procedure with the BEFORE parameter.
• The SORT procedure executes for each record from input-file-name before passing the record to the sort.
• BEFORE proc-name
Identifies the user-defined procedure you want to execute. CA Easytrieve® Report Generator supplies input records
to your SORT procedure one at a time. If a BEFORE procedure is used, the SELECT statement must be executed for
each record that you want to sort.
– You must execute a SELECT statement for each record that you want returned to the output file.
– A selected record outputs only once, even if selected more than once in the procedure.
– Any record not selected does not go to the sorted file.
The SELECT statement has the following syntax:
SELECT
Sort Procedure Example
This example illustrates the use of the SORT activity and SORT procedures:
FILE PERSNL FB(150 1800)
EMPNAME 17 16 A
DEPT 98 3 N
GROSS-PAY 94 4 P 2
FILE PAYSORT F(120) VIRTUAL
SORT-NAME 17 16 A
SORT-DEPT 98 3 N
SORT-GROSS-PAY 94 4 P 2
JOB INPUT PERSNL NAME ACT-1
SORT PERSNL TO PAYSORT USING (DEPT GROSS-PAY D) +
BEFORE SELECT-REC NAME SORT-ACTIVITY
SELECT-REC. PROC
IF GROSS-PAY GE 500
SELECT
END-IF
END-PROC
JOB INPUT PAYSORT NAME ACT-2
PRINT RPT1
REPORT RPT1
LINE 1 SORT-NAME SORT-DEPT SORT-GROSS-PAY
In this example, SELECT-REC is the name of the SORT procedure. The procedure causes only those records with a
gross pay of greater than or equal to 500 to be selected for sorting.
PROGRAM Activities
You can use a PROGRAM activity for simple processing activities or to control the execution of JOB, SORT, and SCREEN
activities.
Simple PROGRAM Example
The following example illustrates the use of a PROGRAM activity where you merely need to perform an arithmetic
computation, display the results, and then stop processing:
235
CA Easytrieve® Report Generator 11.6
DEFINE RESULT W 4 P 2
PROGRAM NAME COMPUTE
RESULT = (2354.54 * 6) /3.8
DISPLAY THE RESULT IS RESULT
Controlling Other Activities
You can use a PROGRAM activity to conditionally initiate JOB, SORT, and SCREEN activities:
PROGRAM NAME PROCESSOR
IF SYSTIME = 09:00:00 THRU 17:00:00
EXECUTE PRIME-TIME-JOB
ELSE
EXECUTE OFF-TIME-JOB
END-IF
JOB NAME PRIME-TIME-JOB
** Logic **
JOB NAME OFF-TIME-JOB
** Logic **
In this example, the PROGRAM activity controls which JOB activity is executed, based on the time of day. If a PROGRAM
activity had not been specified, the JOB activities would have been executed sequentially from the first JOB activity.
EXECUTE Statement
The EXECUTE statement invokes a JOB, SORT, or SCREEN activity from either a PROGRAM or SCREEN activity. The
EXECUTE statement transfers control to an activity. After the activity is executed, control returns to the next executable
statement following the EXECUTE.
NOTE
You cannot invoke a JOB, SORT, or SCREEN activity within a JOB or SORT activity.
EXECUTE statements within a SCREEN activity can invoke other activities. This is called activity nesting.
Syntax
EXECUTE {job-name | sort-name | screen-name}
• {job-name | sort-name | screen-name}
Names the JOB, SORT, or SCREEN activity to be executed.
Activity Section - Input and Output
File input/output can be controlled either by CA Easytrieve Report Generator (automatic) or controlled by the user (user-
controlled). Several statements are available to provide input and output under various conditions. All input and output
occurs in the activity section of your programs.
This article includes the following information:
236
CA Easytrieve® Report Generator 11.6
Automatic Input and Output
CA Easytrieve Report Generator gives you the option of letting it take care of input and output for you. All of the usual
housekeeping considerations like opening and closing files, checking for end of file, issuing input and output statements in
a loop, can be taken care of automatically.
Automatic Input with the JOB Statement
The JOB statement lets you identify a file for automatic input to the JOB activity. Simply specify the file name after the
word INPUT; CA Easytrieve Report Generator takes care of all the rest.
Syntax
Here is how the JOB statement looks with automatic input:
JOB [INPUT file-name]
When you specify INPUT and a file name, the records of that file are automatically made available to the logic in your JOB
activity section. However, there are some implied statements being executed, which you do not see in your program. The
following steps are taken when the JOB statement is executed with automatic input:
IF THERE IS A START PROCEDURE
THEN PERFORM THE START PROCEDURE
END-IF
OPEN FILE(S)
+-> RETRIEVE THE INPUT
| IF NO MORE INPUT
| IF THERE IS A FINISH PROCEDURE
| THEN PERFORM THE FINISH PROCEDURE
| END-IF
| WRAP UP THE REPORTS
| GO TO THE NEXT ACTIVITY
| ELSE
| PERFORM LOGIC ACTIVITIES
| END-IF
+-< GO TO
You can omit the INPUT parameter from the JOB statement. If you do, the automatic input is provided by either the first
file that is described in your library section or the output of a directly previous SORT, if any.
Printing Reports
To initiate the printing of reports, use the CA Easytrieve Report Generator PRINT statement, which looks like this:
Syntax
PRINT [report-name]
PRINT is not completely automatic, in that it does permit you a certain amount of control. You can execute PRINT
anywhere in your JOB activity logic and you can use conditional logic to determine when it should execute. However,
when PRINT is executed, it activates the designated report declaration and takes care of all output considerations
automatically.
Usually, your reports do not go directly to a printer through a print file. Reports go to a CA Easytrieve Report Generator
work file (sometimes called a spool file) instead. Work files are necessary in two cases:
237
CA Easytrieve® Report Generator 11.6
• When the printer (print file) is already activated by a previous report of the same JOB activity (multiple reports directed
to the same printer).
• When a report requires sequencing (specifically, when a SEQUENCE statement is present).
The following example illustrates how the PRINT statement is executed for reports going to a single printer:
Figure 4: Executing a Print Statement
Work File Processing
If work files are created, as shown in the previous example, they are held until the end of the job activity. At end of job,
they are processed as shown in this example:
238
CA Easytrieve® Report Generator 11.6
Figure 5: Work File Processsing
User-Controlled Input and Output
Sequential File Processing
Three statements are provided for sequentially processing files:
• DISPLAY
Normally used to display data to your system output device
• GET
Used for sequential retrieval of input file records
• PUT
Used for sequential output of records to an output file
DISPLAY Statement
A DISPLAY statement sends data to a specified output file or output device. DISPLAY is commonly used:
239
CA Easytrieve® Report Generator 11.6
• For error messages
• For highlighting reports
• For hexadecimal display of selected information
If DISPLAY is used in the logic portion of the JOB activity and output is to a report, the lines to be displayed are
interspersed throughout the report in an unsequenced report or printed at the beginning of a sequenced report (before the
first title). When DISPLAY is used in report procedures, you are permitted to display to the system output device only (not
to a data file). The DISPLAY statement has two different formats.
DISPLAY Format 1
Syntax
[ ] [ [ ] ]
DISPLAY [display-file-name] [{TITLE | NOTITLE}] [ [+]offset ]+
[SKIP skip-integer] [ [-] ]
[ ] [ [ ] ]
[ COL column-number ]
[ POS position-number]
[ ]
[ ] [ ]
[literal-1 ] [literal-n ]
[field-name-1] ... [field-name-n]
[ ] [ ]
• display-file-name
If you specify display-file-name, data is printed to the named file. If you do not specify display-file-name, the default is
SYSPRINT.
• TITLE | NOTITLE
The TITLE option specifies that a skip to a new page occurs before the data is printed. Any titles and headings are also
produced. NOTITLE specifies that a skip to a new page occurs but titles and headings are not produced.
• SKIP skip-integer
The SKIP option specifies that the designated number of lines are skipped before the data is printed.
• offset
Coding a positive or negative offset modifies the horizontal spacing between display items.
• COL column-number
The COL column-number option specifies the print column number where the next display item is placed.
• POS position-number
When used in report procedures, the POS position-number option causes the next display item to be positioned under
the corresponding position on the LINE 01 statement.
• literal-1,n or field-name-1,n
Code literals or field-names in the order you want them to appear on the printed line.
DISPLAY Example 1
DISPLAY SKIP 2 '**RECORD NOT FOUND FOR KEY' +2 SSN
DISPLAY ERRFILE 'THIS REPORT IS FOR ERRORS +
THAT WERE FOUND IN THE EDIT PHASE.'
DISPLAY Format 2
Syntax
240
CA Easytrieve® Report Generator 11.6
[ ] [ ]
DISPLAY [display-file-name] [{TITLE | NOTITLE}] HEX [file-name ]
[SKIP skip-integer] [field-name]
[ ] [ ]
In this format, a hexadecimal and character dump of the current record or the specified field-name is produced. The
parameters, other than HEX, operate the same as in Format 1.
DISPLAY Example 2
DISPLAY HEX NAME
Produces:
CHAR WIMN
ZONE ECDD4444444444444444
NUMR 69450000000000000000
1...5...10...15...20
GET Statement
The GET statement retrieves the next record of the named file into the file input area.
Syntax
GET file-name
• file-name
Identifies the input file that is defined in the library section.
NOTE
When you use the GET command, you must test for end-of-file (EOF).
GET Example
FILE MASTER FB(150 1800)
EMP# 9 5 N
EMPNAME 17 16 A
GROSS 94 4 P 2
JOB INPUT NULL NAME READ-SEQ-MAN
GET MASTER
IF EOF MASTER
STOP
END-IF
IF GROSS > 500
PRINT RPT1
END-IF
REPORT RPT1
LINE 1 EMP# EMPNAME GROSS
241
CA Easytrieve® Report Generator 11.6
You cannot use GET for an automatic input file. To inhibit automatic input, specify INPUT NULL on the JOB statement. For
example:
JOB INPUT NULL
You might GET a secondary file while automatically accessing a primary file.
PUT Statement
The PUT statement outputs to a file sequentially.
Syntax
PUT output-file-name [FROM input-file-name]
• output-file-name
Identifies a file that is defined in the library section to which you are writing data.
• FROM input-file-name
Using the FROM option is like performing a MOVE of data from input-file-name to output-file-name before performing
the PUT.
PUT Example 1
FILE PERSNL FB(150 1800)
EMP# 9 5 N
EMPNAME 17 16 A
GROSS 94 4 P 2
FILE NEWPAY2 F(20)
EMPNAME 1 16 A
GROSS 17 4 P 2
JOB INPUT PERSNL NAME PUT-EXAMPLE
** Logic **
MOVE LIKE PERSNL TO NEWPAY2
PUT NEWPAY2
PUT Example 2
FILE MASTER FB(150 1800)
EMP# 9 5 N
EMPNAME 17 16 A
GROSS 94 4 P 2
FILE OUTMAST FB(150 1800)
JOB INPUT MASTER NAME CREATE-SEQ
IF GROSS > 500
*
PUT OUTMAST FROM MASTER
*
END-IF
242
CA Easytrieve® Report Generator 11.6
POINT Statement
Use the POINT statement to establish a starting position for sequential processing of a keyed file. This statement is for
use on INDEXED and RELATIVE files. CA Easytrieve does not require that you specify the length or location of the record
key field.
Data becomes available to your program only after the next successful sequential retrieval either by automatic file input or
by a GET statement.
Syntax
{ = } { }
POINT file-name { EQ } { field-name } [STATUS]
{ GE } { }
{ GQ } { literal }
{ >= } { }
• file-name
An INDEXED or RELATIVE file that is described on a FILE statement in the library section of your program.
• field-name or literal
Any valid field-name or literal can be used as a key search value for the POINT statement. This search value is
compared to the record key value in the file to determine the starting location for sequential access.
• STATUS
Causes the system-defined field FILE-STATUS to be set with a return code. By checking FILE-STATUS at some point
in your program after coding STATUS, you can determine whether the input/output request was performed properly.
The FILE-STATUS field normally contains a value of zero after a successful I/O request. This parameter is also used
on the GET, PUT, READ, and WRITE statements.
POINT Example
The following example causes sequential processing of an INDEXED file to begin on a record with a key value of 01963
or, if no such key exists, on a record with the next higher key value:
FILE PERSNL INDEXED
EMP# 9 5 N
EMPNAME 17 8 A
DEPT 98 3 N
GROSS 94 4 P 2
JOB INPUT NULL NAME MYPROG
POINT PERSNL GE '01963' STATUS
IF FILE-STATUS NE 0 OR EOF PERSNL
DISPLAY 'BAD POINT...FILE STATUS= ' FILE-STATUS
STOP
END-IF
GET PERSNL STATUS
IF FILE-STATUS NE 0
DISPLAY 'BAD GET...FILE STATUS= ' FILE-STATUS
ELSE
DISPLAY PERSNL
END-IF
STOP
243
CA Easytrieve® Report Generator 11.6
Random Access Processing
READ Statement
The READ statement provides random access to INDEXED and RELATIVE files.
Syntax
{key-field-name}
READ file-name KEY { } [STATUS]
{'key-literal' }
• file-name
The file name on a FILE statement in the library section of your program.
{key-field-name}
{ } [STATUS]
{'key-literal' }
Key-field-name contains the value of the record key to be found. This key value can also be expressed as a literal for
INDEXED files.
READ Example
The following example involves the use of two files: PAYROLL and MASTER. PAYROLL is a sequential transaction file
containing key values. MASTER is a master file that is keyed for random access.
The PAYROLL file is made available to the program through automatic input. Key values from this file, which is located
in the EMP-NO field, are used to READ the MASTER file. READs returning non-zero FILE-STATUS values cause the
DISPLAY of an error message.
FILE PAYROLL
EMP-NO 1 3 N
FILE MASTER INDEXED
EMP-NAME 40 10 A
*
JOB INPUT PAYROLL NAME READ-EXAMPLE
READ MASTER KEY EMP-NO STATUS
IF MASTER:FILE-STATUS NOT ZERO
DISPLAY 'ERROR READING VSAM +
FILE WITH KEY: ' EMP-NO +
' FILE-STATUS IS ' MASTER:FILE-STATUS
GOTO JOB
END-IF
** Logic **
244
CA Easytrieve® Report Generator 11.6
WRITE Statement
Use the WRITE statement to add a new record, update an existing record, or delete a record from an INDEXED or
RELATIVE file.
• When you use WRITE, you must specify the UPDATE parameter on the FILE statement of the file being written to.
• Before you can issue a WRITE to delete or update, you must already have read the record that you are writing.
WRITE Format 1
Use Format 1 when adding to or updating a record.
Syntax
[ ] [ ]
WRITE output-file-name [UPDATE] [FROM input-file-name ] [STATUS]
[ADD ] [ ]
[ ]
WRITE Example 1
This example involves two files: TRANS and PAYVS. TRANS is a sequential transaction file containing transaction
records, with a key value located in the EMP-NO field. PAYVS is a master file that is keyed for random access.
The TRANS file is made available to the program through automatic input. The EMP-NO field of the TRANS file is used as
a key to READ the PAYVS file.
The value returned to the FILE-STATUS field after a READ is checked to find out if a record with a matching key value
was found. If no record was found, then an ADD is performed.
If a record was found, then an UPDATE is performed. In either case, procedures (not shown) are performed to check the
FILE-STATUS value for each WRITE statement executed.
FILE TRANS
EMP-NO 1 3 N
GROSS 15 4 P 2
*
FILE PAYVS INDEXED UPDATE
GROSS 15 4 P 2
*
JOB INPUT TRANS NAME UPDATE-PGM
READ PAYVS KEY EMP-NO STATUS
IF PAYVS:FILE-STATUS NE 0 . * RECORD NOT FOUND
WRITE PAYVS ADD FROM TRANS STATUS
PERFORM ADD-STATUS-CHK
GOTO JOB
END-IF
IF PAYVS:FILE-STATUS = 0 . * RECORD FOUND
MOVE LIKE TRANS TO PAYVS
WRITE PAYVS UPDATE STATUS
PERFORM UPDATE-STATUS-CHK
GOTO JOB
245
CA Easytrieve® Report Generator 11.6
END-IF
WRITE Format 2
Use Format 2 for deleting a record.
Syntax
WRITE output-file-name DELETE [STATUS]
WRITE Example 1
FILE TRANS
TRANS-KEY 14 3 A
TRANS-CODE 17 1 A. * TRANS-CODE value of D means Delete
*
FILE PAYVS INDEXED UPDATE
JOB INPUT TRANS NAME VSAM-DELETE
IF TRANS-CODE = 'D'
READ PAYVS KEY TRANS-KEY STATUS
IF FILE-STATUS = 0
WRITE PAYVS DELETE STATUS
PERFORM WRITE-STAT-CHECK
ELSE
DISPLAY 'ERROR IN STATUS CHECK'
END-IF
END-IF
Activity Section - Reporting
One of the most powerful features of CA Easytrieve® Report Generator is the easy-to-use reporting facility. Seven
basic statements control most aspects of report production, including REPORT, SEQUENCE, CONTROL, SUM, TITLE,
HEADING, and LINE. Special-named procedures are also available for customizing reports, allowing for great flexibility
and user control.
Standard Reports
The CA Easytrieve report facility includes all of the functions necessary to produce most reports very easily. Using CA
Easytrieve report options, you can produce almost any report format. Most reports, however, are variations of what is
termed the standard report. Standard reports typically consist of the following items:
• Titles
• Headings
• Lines or line groups
The following diagram shows the structure of a standard report:
<──────────────────────LINESIZE──────────────────────>
┌────────────────────────────────────────────────────┐
246
CA Easytrieve® Report Generator 11.6
│ TOP MARGIN │
│────────────────────────────────────────────────────│ ───
│ TITLE AREA (optional) │
│ where titles are printed │ │
│────────────────────────────────────────────────────│ P
│ HEADING AREA (optional) │ A
│ where headings are printed │ G
│────────────────────────────────────────────────────│ E
│ │ S
│ │ I
│ REPORT BODY │ Z
│ │ E
│ where lines or line groups are printed │ │
│────────────────────────────────────────────────────│ │
│ BOTTOM MARGIN │ ¯
└────────────────────────────────────────────────────┘ ───
Titles
The title is the first item printed on each report page. The report title is specified in your program by the TITLE statement.
You can have up to 99 TITLE statements in your program. The following diagram shows the title area of a report.
<─────────────────────────LINESIZE────────────────────────>
SYSDATE PAGEWRD Page
│ │ count
│ │ │
¯ ¯ ¯
99/99/99 TITLE 01 items PAGE ZZ,ZZ9
TITLE 02 items
...
TITLE 04 items
...
TITLE 99 items
If more than one TITLE statement is coded in your program, TITLE must be followed by sequence numbers (01 to 99).
The following list highlights some points to remember about standard report titles:
• TITLE 01 items are printed at top-of-form.
• The current date and page count are automatically placed at either end of the TITLE 01 line.
• Title lines are centered within the space indicated by the LINESIZE parameter of the REPORT statement.
• The title sequence number controls the vertical spacing of titles relative to the first title.
• The SPACE parameter of the REPORT statement controls the number of blank characters (spaces) between title
items.
The following shows two TITLE statements and the resulting titles:
Statements:
FILE PERSNL FB(150 1800)
DEPT W 3 N VALUE '903'
247
CA Easytrieve® Report Generator 11.6
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 50
TITLE 01 'TEMPORARY EMPLOYEES'
TITLE 03 'IN DEPARTMENT' DEPT
LINE 01 ' '
Produce:
01/09/89 TEMPORARY EMPLOYEES PAGE 1
IN DEPARTMENT 903
NOTE
A blank line was inserted where a TITLE 02 item would have otherwise been printed.
Headings
Headings in a report describe the content of line items. Line items are the single pieces of information that make up a line
on a report. Usually, they form vertical columns. Each heading is centered over its associated line item. The following list
highlights points to remember about headings:
• If no headings are defined, CA Easytrieve uses the field names of the DEFINE statement as headings.
• Headings can be specified by HEADING statements in the report subactivity or by HEADING parameters on DEFINE
statements.
• HEADING statements override any HEADING parameters defined for the same field.
• Line items that are literals (do not come from defined fields) do not have headings.
• Headings can be stacked (take up more than one vertical space).
The following diagram shows the positioning of headings in a typical report:
T I T L E A R E A
HEADING
HEADING Heading
HEADING HEADING Area
HEADING HEADING HEADING
line line literal line
248
CA Easytrieve® Report Generator 11.6
item item line item Report
... ... item ... Body
... ... ... ...
The following example shows how headings can be defined in your program:
Statements:
FILE PERSNL FB(150 1800)
SSN 4 5 P HEADING('SOCIAL' 'SECURITY' 'NUMBER')
EMPNAME 17 20 A
PAY-NET 90 4 P 2
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65
HEADING PAY-NET ('NET' 'PAY')
LINE EMPNAME SSN '* NO OVERTIME *' PAY-NET
Produce:
SOCIAL
SECURITY NET
EMPNAME NUMBER PAY
WIMN GLORIA 025-30-5228 * NO OVERTIME * 251.65
BERG NANCY 121-16-6413 * NO OVERTIME * 547.88
Line Group
A line is the result of a single LINE statement in your program. Each time a PRINT statement is executed, all of the fields
indicated on the LINE statement are sent to the printer as a single formatted line. If there is more than one LINE statement
in your program, then they are output in groups for each PRINT statement issued. All of the LINE statements of the report
make up a line group, which is also called a logical report line:
LINE 01 ...ü
LINE 02 ...ý line group (logical report line)
LINE 03 ...þ
...
249
CA Easytrieve® Report Generator 11.6
The following example illustrates line item positioning:
FILE PERSNL FB(150 1800)
SSN 4 5 P MASK '999-99-9999' +
HEADING('SOCIAL' 'SECURITY' 'NUMBER')
EMPNAME 17 20 A HEADING 'EMPLOYEE NAME'
ADDR-STREET 37 20 A HEADING 'STREET'
ADDR-CITY 57 12 A HEADING 'CITY'
SEX 127 1 N HEADING('SEX' 'CODE')
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65
LINE EMPNAME SSN SEX
LINE 02 ADDR-STREET ADDR-CITY
item area item area item area
┌───────┴────────┐ ┌─────┴─────┐ ┌─┴──┐
1 5 10 15 1 5 10 1 4
............... ........... ....
SOCIAL ü
SECURITY SEX ý Heading
EMPLOYEE NAME NUMBER CODE þ
WIMN GLORIA 025-30-5228 1 ü Line
430 M ST SW 107 BOSTON ý Group
þ
For more information about line item positioning, see CA IDMS Database Processing.
Processing of Reports
The PRINT statement discussed in the Input and Output section identifies records for output to a report and initiates
the execution of a report declaration. This does not directly cause the printing of the report. Reports are printed and
formatted by the statements that make up the report declaration. Sometimes the report is called subactivity, because
report declarations are considered subactivities of the JOB activity.
There are two parts to every report declaration:
REPORT Statement
The REPORT statement is the first statement that is coded in a report declaration. The report statement includes the
keyword REPORT and various report parameters.
Report parameters are keywords that permit you to assign values that alter the physical characteristics of the final report.
Although you can specify many report parameters, you can produce most reports using default (defined by CA Easytrieve
Report Generator) parameter values.
Report statement parameters provide you with a simple way to define tailored reports. They can be divided into three
categories:
250
CA Easytrieve® Report Generator 11.6
• Spacing control parameters
• Testing aid parameters
• Format determination parameters
Spacing Control Parameters
The following REPORT statement parameters control spacing on a standard format report:
• PAGESIZE
Specifies the lines per page. The default is 58.
• LINESIZE
Specifies the length of each line. The default is 132.
• SKIP
Specifies the number of blank lines to be inserted between line groups. The default is 0.
• SPACE
Specifies the number of blanks inserted (horizontally) between field columns and between fields and literals in title and
detail lines. The default is 3.
• TITLESKIP
Specifies the number of blank lines inserted after last title line and before the first heading or detail line. The default is
3.
• SPREAD
Requests that the columns of data be spread evenly over the entire line; overrides the SPACE parameter. The default
is NOSPREAD.
• NOADJUST
Requests that title lines and report be left-justified on the page. The default is to center the report on the page.
SPREAD and NOADJUST are mutually exclusive.
• NODATE
Inhibits printing the system date in positions one through eight of the first title line.
• NOPAGE
Inhibits the printing of a page number.
• NOHEADING
Inhibits the printing of column headings.
Spacing control parameters are all optional. When used, they can be coded on the REPORT statement in any order. The
general format for these parameters is:
REPORT report-name +
[PAGESIZE nn] [LINESIZE nn] +
[SKIP nn] [SPACE nn] +
[TITLESKIP nn] +
É ù Spacing
êSPREAD ú Control
êNOSPREAD ú + Parameters
ë û
251
CA Easytrieve® Report Generator 11.6
[NOADJUST] +
[NODATE] [NOPAGE] +
[NOHEADING] +
REPORT Statement Example
The following program shows an example of how spacing control parameters can be used on the REPORT statement:
FILE PERSNL FB(150 1800)
EMP# 9 5 N
EMPNAME 17 8 A HEADING ('EMPLOYEE' 'NAME')
DEPT 98 3 N
GROSS 94 4 P 2 MASK '$$,$$9.99'
JOB INPUT PERSNL NAME FIRST-PROGRAM
PRINT PAY-RPT
REPORT PAY-RPT PAGESIZE 12 NOPAGE NODATE LINESIZE 70 SKIP 2 +
SPREAD TITLESKIP 4
TITLE 01 'EXAMPLE PROGRAM'
LINE 01 EMPNAME EMP# DEPT GROSS
This program produces the following report (only two pages are shown):
EXAMPLE PROGRAM
EMPLOYEE
NAME EMP# DEPT GROSS
WIMN 12267 903 $373.60
EXAMPLE PROGRAM
EMPLOYEE
NAME EMP# DEPT GROSS
BERG 11473 943 $759.20
252
CA Easytrieve® Report Generator 11.6
Report Definition Statements
The second part of a report declaration is the report definition statements. These statements define the content of your
report. When you use report definition statements, you must code them immediately after the REPORT statement, in the
following order:
• SEQUENCE
• CONTROL
• SUM
• TITLE
• HEADING
• LINE
SEQUENCE Statement
The SEQUENCE statement lets you specify the order of the lines in a report. For example, you might want reports to be in
alphabetical order by name or in numerical order by employee number.
• You can sequence on any field from any input file or any W working storage field.
• You can sequence on as many fields as your system sort permits.
• Sequence fields are stated in major to minor order.
• The default sequence order is ascending. Coding D after a field-name reverses the order for that field only.
Syntax
SEQUENCE field-name [D] ...
SEQUENCE Examples
SEQUENCE CO DIV DEPT GROSS-PAY D
SEQUENCE GROUP AMT D CODE
CONTROL Statement
A CONTROL statement specifies that a report should automatically accumulate and print totals. A control break occurs
whenever the value of any control field changes or end-of-report is reached. Control fields can be any non-quantitative
field from any input file or any W working storage field. At each control break, totals are printed for any quantitative fields
that are specified in the report.
• You can specify an unlimited number of control fields.
• Fields are coded on the CONTROL statement in major to minor order.
Syntax
É ù É ù
CONTROL êfield-nameú êNEWPAGEú [NOPRINT] ...
ê FINAL ú ê RENUM ú
ë û ë û
253
CA Easytrieve® Report Generator 11.6
• Final totals are automatically provided. You can alter the default by coding FINAL NOPRINT.
• NOPRINT following any field-name suppresses the printing of totals for that field (which are still accumulated) at the
corresponding control break.
• NEWPAGE following any field or FINAL causes a new page after the printing of the control break totals (or, in the case
of FINAL, before the printing of the final totals). Page numbers continue.
• RENUM following any field or FINAL causes a page break and restarts page numbers at 1 after the printing of the
control break totals (or, in the case of FINAL, before the printing of the final totals).
Control Examples
CONTROL COMPANY RENUM DIV DEPT NOPRINT
CONTROL FINAL NOPRINT COMPANY NEWPAGE DIV
SUM Statement
The SUM statement specifies that only certain quantitative fields are to be totaled for a control report. Normally on control
reports, CA Easytrieve Report Generator totals all quantitative fields that are specified on the LINE statement (to be
discussed later). The SUM statement overrides this process; only the fields specified on the SUM statement are totaled.
• You can use SUM only in control reports.
• You can SUM any quantitative field from any active file or any W working storage field.
Syntax
SUM field-name ...
SUM Example
SUM GROSS NET
TITLE Statement
The TITLE statement lets you define a title for your report. Up to 99 titles are permitted. You can specify literals and field
names on the TITLE statement.
Syntax
{[ ] field-name}
{[#font-number] }
TITLE [title-number] {[ ] 'literal' } ...
{+offset }
{-offset }
{COL column-number }
• You use ± offset to alter the normal horizontal spacing between literals or fields on the title lines. Spaces are added to
or subtracted from the SPACE parameter (which normally has a default of 3).
• COL column-number specifies the print column number where the next title item is to begin.
• If no TITLEs are coded, the date and page number, which are normally automatically included in the title, are not
printed.
TITLE Examples
TITLE 01 'REPORT ONE'
TITLE 03 'THIS PAGE FOR DIV' -2 DIV-NO
254
CA Easytrieve® Report Generator 11.6
TITLE 04 'ABC COMPANY'
prints:
01/31/18 REPORT ONE PAGE 1
THIS PAGE FOR DIV 15
ABC COMPANY
Control Field Values in Titles
Occasionally, you may want to print control field values in report titles. To do this, use the NEWPAGE parameter of the
CONTROL statement and include a control field name on the TITLE statement. Then control breaks occur on a new page
with the control field value in the title, as shown in the following example.
NOTE
Output has been edited for the purpose of illustration.
Statements:
FILE PERSNL FB(150 1800)
EMPNAME 17 8 A
STATE 69 2 A
ZIP 71 5 N
PAY-NET 90 4 P 2 MASK (A '$$,$$9.99')
JOB INPUT PERSNL NAME MY-PROG
PRINT REPORT-1
REPORT REPORT-1 LINESIZE 65
SEQUENCE STATE ZIP EMPNAME
CONTROL STATE NEWPAGE
TITLE 01 'REPORT FOR THE STATE OF' STATE
LINE 01 EMPNAME STATE ZIP PAY-NET
Produce:
1/17/18 REPORT FOR THE STATE OF DC PAGE 1
EMPNAME STATE ZIP PAY-NET
JUDAR DC 00000 $459.57
PHILPS 00000 $213.76
CROCI 20002 $215.95
WARD 20002 $141.47
DC $1,030.75
1/17/18 REPORT FOR THE STATE OF MD PAGE 2
EMPNAME STATE ZIP PAY-NET
255
CA Easytrieve® Report Generator 11.6
MILLER MD 20014 $222.61
PETRIK 20014 $154.70
LACH 20028 $215.91
VETTER 20028 $189.06
MD $782.28
1/17/18 REPORT FOR THE STATE OF VA PAGE 3
EMPNAME STATE ZIP PAY-NET
MCMAHON VA 22202 $283.19
CORNING 22204 $103.43
BYER 22207 $259.80
ARNOLD 22209 $356.87
VA $939.03
$2,752.06
HEADING Statement
As with the DEFINE statement in the library section, you can define an alternate column heading for a field in the report
declaration. The HEADING statement overrides a HEADING parameter that is coded for the same field in the library
section of the program. If alternative headings are not defined, either by a HEADING statement or by the HEADING
parameter of DEFINE, then the field name is used as the heading.
• Use one HEADING statement per field.
• Words in a heading can be stacked to save space in the column. To do this, place individual words in single quotes.
Syntax
HEADING field-name ('heading-literal'...)
HEADING Example 1
HEADING EMP-NO 'EMP NO'
This example prints a column heading on the report that looks like:
EMP NO
HEADING Example 2
HEADING SSN ('SOCIAL' 'SECURITY' 'NUMBER')
This example prints a stacked column heading:
SOCIAL
SECURITY
NUMBER
256
CA Easytrieve® Report Generator 11.6
LINE Statement
The LINE statement defines the content of a report line. Multiple LINE statements define a line group. Use LINE 01 to
designate headings for the report columns.
• You can specify up to 99 lines per record.
• You can specify any field from an input file or working storage.
Syntax
{[ ] field-name }
{[#font-number] }
{[ ] 'literal' }
LINE [line-number] {+offset } ...
{-offset }
{COL column-number }
{POS position-number }
• If literals are specified, they print on all lines but are not used as headings.
• ± offset is used to alter the normal spacing between line items. nn is added to or subtracted from the SPACE
parameter (which normally has a default of 3).
• COL (column) specifies the print column number where the next field is to begin.
• POS (position) provides for aligning fields under the corresponding column heading positions that are indicated on the
LINE 01 statement.
LINE Example
LINE 01 DEPT DIV EMPNAME
LINE 02 POS 2 CODE POS 3 ADDRESS
LINE 03 POS 3 CITY-STATE
This example prints the field contents in the following format:
DEPT DIV EMPNAME
911 02 MATT JONES
512 2232 HILL
ANYWHERE IL
Label Report
Use the label report capability of CA Easytrieve® Report Generator to print mailing labels and other applications that
require inserting variable data in a repetitious format. A label report is different from a standard report in the following
ways:
• Label reports do not have titles and headings.
• Multiple labels can be printed side-by-side.
• Controlled label reports permit control breaks, but do not automatically total quantitative fields. Totals, however, can be
specified on a SUM statement and processed in BEFORE-BREAK and AFTER-BREAK procedures (discussed later in
this chapter).
You can use the label report function whenever a complete logical print page is to be produced by each PRINT statement.
257
CA Easytrieve® Report Generator 11.6
Label Format
To specify label reports, use the LABELS option of the REPORT statement. The following diagram illustrates the basic
label report page format:
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ─
│ 1 │ │ 2 │ │ 3 │ │ 4 │ DOWN (6)
└─────────┘ └─────────┘ └─────────┘ └─────────┘ ¯
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ─
│ 5 │ │ 6 │ │ 7 │ │ 8 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│<─SIZE (30)─>│
<─────────────────────LINESIZE──────────────────────>
ACROSS (4)
A label line consists of one or more labels positioned across the label page. In this diagram, labels 1 to 4 compose
a label line. A single line group composes each label. Therefore, CA Easytrieve produces a label for each PRINT
statement execution. CA Easytrieve formats the labels on the page in the order shown in the diagram. DOWN and SIZE
(subparameters of the LABELS option) indicate the dimensions of each label.
LABELS Parameter
Format determination parameters are parameters of the REPORT statement that determine the type of report to be
printed. The LABELS parameter is responsible for formatting reports that print mailing labels.
LABELS specifies that the report is to be in label format rather than the standard report format. It automatically inhibits the
printing of the date, page, headings, and titles. The following subparameters are used with LABELS:
• ACROSS specifies the number of labels printed across the print line (default is 4).
• DOWN specifies the number of lines down from the first line of the first label to the first line of the second label (default
is 6).
• SIZE specifies the number of print positions from the first position on the first label to the first position on the second
label (default is 30).
The LABELS parameter has the following format:
[LABELS ] + Format
([ACROSS nn] Determination
[DOWN nn] Parameters
[SIZE nn])
REPORT Statement Example
The following program creates the label report shown:
FILE PERSNL FB (150 1800)
NAME 17 8 A
258
CA Easytrieve® Report Generator 11.6
ADDRESS 37 39 A
ADDR-STREET 37 20 A
ADDR-CITY 57 12 A
ADDR-STATE 69 2 A
ADDR-ZIP 71 5 N
JOB INPUT PERSNL NAME FIRST-PROGRAM
PRINT PAY-RPT
REPORT PAY-RPT LABELS (ACROSS 3 SIZE 23)
LINE 01 NAME
LINE 02 ADDR-STREET
LINE 03 ADDR-CITY ADDR-STATE
LINE 04 ADDR-ZIP
This program produces the following report:
WIMN BERG CORNING
430 M ST SW 107 3710 JENIFER ST N W 3208 S 5TH
WASHINGTON DC WASHINGTON DC ARLINGTON VA
20004 20015 22204
NAGLE ARNOLD MANHART
826 D STREET SE 1569 COLONIAL TERR A 1305 POTOMAC ST N W
WASHINGTON DC ARLINGTON VA WASHINGTON DC
20003 22209 20007
TALL BRANDOW LARSON
1412 36TH ST NW 3616 B ST S E 610 H ST SW
WASHINGTON DC WASHINGTON DC WASH DC
20007 20019 20024
BYER HUSS POWELL
3400 NORTH 18TH STRE 1355 TEWKESBURY PLAC 5023 AMES STREET N E
ARLINGTON VA WASHINGTON DC WASHINGTON DC
22207 20012 20019
Testing Aid Parameters
Testing aid parameters are provided as a testing aid for report development. You can run your newly-developed report
programs against real data while limiting the amount of information printed.
There are two testing aid parameters of the REPORT statement: LIMIT and EVERY.
Testing aid parameters have the following format:
REPORT [report-name] +
[LIMIT number-of-records]
259
CA Easytrieve® Report Generator 11.6
[EVERY n-number-of-lines]
• The LIMIT option limits the number of records processed by the report. The value, number-of-records, can be any
integer literal in the range 1 to 32,767.
• The EVERY option enables you to specify that only every nth line is to be printed in the report. The value of n-number-
of-lines can be any integer literal in the range 1 to 32,767.
Format Determination Parameters
The format determination parameter LABELS is used on the REPORT statement to format labels reports. There are
six other format-related parameters of the REPORT statement. This tutorial discusses the following four parameters. A
summary file can be optionally generated during processing of a control report.:
The format of these four parameters is:
REPORT [report-name] +
[SUMMARY] +
[SUMFILE summary-file-name] +
É ìEVERYü ù
êDTLCTLíFIRSTý ú +
ë îNONE þ û
É ì ÉALL ù ü ù
êSUMCTL í ( êHIARú ÉDTLCOPY ù ) ý ú +
ê ï êNONEú ëDTLCOPYALLû ï ú
ë î ëTAG û þ û
DTLCTL Parameter
The DTLCTL (Detail Control) parameter of REPORT establishes the method for printing control field values on detail lines
of a control report by using the subparameters EVERY, FIRST, and NONE. The following example program uses DTLCTL
options. This program can be run with any of the three options.
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
DTLCTL option (* replace with one: EVERY, FIRST, or NONE *)
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
SUMCTL Parameter
The SUMCTL (Sum Control) parameter of REPORT establishes the method for printing control field values on total lines
of a control report by using the subparameters ALL, HIAR, NONE, and TAG. (The DTLCOPY subparameter controls
all non-control non-total field values on total lines and is shown, with the SUMMARY parameter, later in this chapter.)
260
CA Easytrieve® Report Generator 11.6
The following example program uses these options. This program can be run with any of the four options. For more
information, see Processing of Reports.
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMCTL option
(* replace with one: ALL, HIAR, NONE, or TAG *)
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
SUMMARY Reports
SUMMARY is a parameter of the REPORT statement that causes the report to print as a summary report.
Summary reports consist of only total lines, which normally include only control fields and totals. All detail lines are
inhibited from printing.
DTLCOPY Subparameter
It can be helpful on summary reports to have detail field information printed on the total lines to provide greater readability.
The DTLCOPY option of the SUMCTL parameter of the REPORT statement copies detail fields (non-control and non-total
fields), as they appear just before the control break, onto the total lines of the summary report.
The following example shows a program that produces a summary report and includes the DTLCOPY option. If this option
were not used, the LAST-NAME values would not print.
DTLCOPY causes the detail information to be printed only on the first control level of the report. DTLCOPYALL causes the
detail to be printed on all summary lines.
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
Data:
261
CA Easytrieve® Report Generator 11.6
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Report:
Line
Description LAST-NAME STATE ZIP PAY-NET
ZIP total BROWN IL 60076 802.35
ZIP total JONES IL 60077 641.97
STATE total IL 1444.32
ZIP total SMITH TX 75218 777.77
STATE total TX 777.77
FINAL total 2222.09
Summary Files
A summary file, containing all the control and summed field values at each minor break, can be optionally generated
during processing of a control report. JOB activities in your program can subsequently process the summary file to provide
reports not otherwise available through the standard report facilities of CA Easytrieve® Report Generator. To request
the summary file, define the file in the library and then reference it with the REPORT SUMFILE parameter. For more
information, see Processing of Reports.
Multiple Reports
You can use CA Easytrieve® Report Generator to produce multiple reports.
Multiple Reports to a Single Printer
Several reports can be produced simultaneously with one pass of the input file. No special coding is needed for multiple
reports on the same printer. The following program produces three reports from one input file:
FILE PERSNL FB(150 1800)
EMPNAME 17 8 A
DEPARTMENT 98 3 N
NET 90 4 P 2
GROSS 94 4 P 2
DEDUCTIONS W 4 P 2
JOB INPUT PERSNL NAME MULTRPTS
PRINT RPT1
DEDUCTIONS = GROSS - NET
PRINT RPT2
IF DEPARTMENT = 911
PRINT RPT3
262
CA Easytrieve® Report Generator 11.6
END-IF
*
REPORT RPT1
TITLE 1 'REPORT ONE'
LINE 1 EMPNAME DEPARTMENT GROSS NET
*
REPORT RPT2
SEQUENCE DEPARTMENT
TITLE 1 'REPORT TWO'
LINE 1 DEPARTMENT EMPNAME GROSS NET DEDUCTIONS
*
REPORT RPT3
CONTROL
TITLE 1 'REPORT THREE - DEPT 911'
LINE 1 EMPNAME GROSS NET DEDUCTIONS
REPORT ONE (RPT1) produces a very simple listing of all employees.
REPORT TWO (RPT2) gives the same information as REPORT ONE but includes an additional column with the
deductions printed.
REPORT THREE (RPT3) produces a report that contains information from department 911 only.
Multiple Reports to More Than One Printer
Multiple reports in one program can be sent to multiple output devices or multiple printers. This can be an effective way of
economizing on processing time if your site supports multiple output devices.
FILE Directing Parameters
The PRINTER parameter of the REPORT statement directs the report's printed output to a file other than the system
default output device (SYSPRINT/SYSLST). Such files must be defined in the library section by a FILE statement that also
contains a PRINTER parameter.
The REPORT statement must identify the appropriate file-name, using the PRINTER parameter in the following format:
REPORT report-name
[PRINTER file-name]
The following example shows a CA Easytrieve® Report Generator program that produces two reports, each sent to
separate printers.
FILE PAYFILE
EMPNAME 17 16 A
ADDRESS 57 20 A
STREET 37 20 A
EMP-NUMBER 9 5 N
*
263
CA Easytrieve® Report Generator 11.6
FILE SPFORM PRINTER
*
JOB INPUT PAYFILE NAME MULT-PRINTERS
IF EMP-NUMBER LE 12345
PRINT FIRST-REPORT
PRINT NORM-REPORT
END-IF
*
REPORT FIRST-REPORT PRINTER SPFORM
SEQUENCE EMP-NUMBER
LINE 1 EMPNAME
LINE 3 STREET
LINE 5 ADDRESS
*
REPORT NORM-REPORT
LINE 1 EMPNAME ADDRESS EMP-NUMBER
The first report declaration produces a report to a print output file designated SPFORM in the second file statement. This
print file gets tied to a physical printer through your Job Control Language (JCL) statements.
The second report declaration produces a report that is output to the default printer used with other CA Easytrieve®
Report Generator programs.
Report Procedures (PROCs)
Report procedures (PROCs) are user-defined routines that are automatically invoked within a report declaration to
perform special data manipulation not included in the logic subactivity. There are seven report PROCs in CA Easytrieve®
Report Generator.
Code any report procedures immediately after the last LINE statement of each report in your program. To identify report
procedures in your program, use the . PROC keyword, as shown below:
REPORT statement
LINE statement
É ù
ê REPORT-INPUT. PROC ú
ê BEFORE-BREAK. PROC ú
ê AFTER-BREAK. PROC ú
ê BEFORE-LINE. PROC ú
ê AFTER-LINE. PROC ú
ê ENDPAGE. PROC ú
ê TERMINATION. PROC ú
ë û
** procedure logic **
END-PROC
264
CA Easytrieve® Report Generator 11.6
• You must code an END-PROC at the end of each procedure.
• Code the logic to be executed in a report PROC the same way you code logic in a JOB activity.
• DISPLAY is the only input or output operation permitted.
• Although you can code these procedures in any order, each procedure can be used only once per report.
REPORT-INPUT. PROC
The REPORT-INPUT. PROC allows for final screening and modification of report input data. It is performed for each
record selected for the report that contains the PROC.
• If you code a REPORT-INPUT procedure, then you must execute a SELECT statement in the PROC to cause data to
continue to the report.
• If a report has been sequenced, this procedure is invoked after each record is output from the system sort.
REPORT-INPUT Example
Statements:
FILE PERSNL
BRANCH 2 2 N
EMP# 9 5 N
EMPNAME 17 20 A
PAY-NET 90 4 P 2
TOT-NET S 5 P 2
PCT-NET-TO-TOT W 3 P 1
*
JOB INPUT PERSNL NAME RPTINPT
TOT-NET = TOT-NET + PAY-NET
PRINT PCT-RPT
*
REPORT PCT-RPT LIMIT 20
SEQUENCE BRANCH EMP#
CONTROL FINAL NOPRINT BRANCH NOPRINT
TITLE 1 'EXAMPLE OF REPORT-INPUT PROC'
LINE 1 BRANCH EMPNAME EMP# PAY-NET PCT-NET-TO-TOT
*
REPORT-INPUT. PROC
PCT-NET-TO-TOT = PAY-NET / TOT-NET * 100 + .05
SELECT
END-PROC
Produce:
265
CA Easytrieve® Report Generator 11.6
01/31/91 EXAMPLE OF REPORT-INPUT PROC PAGE 1
EMPLOYEE NET
BRANCH EMPLOYEE NAME NUMBER PAY PCT-NET-TO-TOT
1 BRANDOW LYDIA 02200 554.31 4.4
HUSS PATTI 11376 223.71 1.8
WIMN GLORIA 12267 251.65 2.0
2 NAGLE MARY 00370 340.59 2.7
KRUSE MAX 03571 182.09 1.5
BERG NANCY 11473 547.88 4.4
POWELL CAROL 11710 167.96 1.3
3 PETRIK KATHY 00577 154.70 1.2
CORNING GEORGE 02688 103.43 .8
DENNING RALPH 02765 109.60 .9
FORREST BILL 03416 13.19 .1
MCMAHON BARBARA 04234 283.19 2.3
MANHART VIRGINIA 11602 250.89 2.0
4 POST JEAN 00445 206.60 1.7
ARNOLD LINDA 01963 356.87 2.9
LARSON RODNEY 11357 215.47 1.7
BYER JULIE 11467 259.80 2.1
TALL ELAINE 11931 355.19 2.8
5 VETTER DENISE 01895 189.06 1.5
LOYAL NED 04225 230.50 1.8
BEFORE-BREAK. PROC
The BEFORE-BREAK. PROC allows for modification of totals and special annotation before total line printing caused by
the CONTROL statement. A system-defined field named LEVEL can be tested to determine the appropriate break:
LEVEL = 1 for minor break
= 2 for next break
= N + 1 for final totals.
(N is the number of control fields)
In the following example, the BEFORE-BREAK. PROC causes the DEPARTMENT annotation at each of the breaks and
modifies the total in PCT to be the percentage, based on total amounts:
Statements:
FILE PAYROLL
EMP# 9 5 N HEADING ('EMPLOYEE' 'NUMBER')
NET 90 4 P 2 HEADING ('NET' 'PAY')
DEPT 98 3 N
GROSS 94 4 P 2 HEADING ('GROSS' 'PAY')
DED W 3 P 2
266
CA Easytrieve® Report Generator 11.6
PCT W 4 N 2
JOB INPUT PAYROLL NAME CORRECT-PCT
IF DEPT = 911 914 921
DED = GROSS - NET
PCT = DED / GROSS * 100
PRINT PCT-REPORT
END-IF
REPORT PCT-REPORT LINESIZE 73
SEQUENCE DEPT
CONTROL FINAL NOPRINT DEPT NOPRINT
TITLE 1 'THIS REPORT WILL ILLUSTRATE USE OF'
TITLE 2 'BEFORE-BREAK PROCEDURE'
LINE DEPT EMP# GROSS NET DED PCT
BEFORE-BREAK. PROC
PCT = DED / GROSS * 100
IF LEVEL = 1. * DEPT TOTALS
DISPLAY SKIP 1 'DEPARTMENT ' DEPT POS 3 GROSS POS 4 NET +
POS 5 DED POS 6 PCT
DISPLAY SKIP 1
END-IF
IF LEVEL = 2. * FINAL TOTALS
DISPLAY SKIP 1 'FINAL' POS 3 GROSS POS 4 NET +
POS 5 DED POS 6 PCT
END-IF
END-PROC
Produce:
267
CA Easytrieve® Report Generator 11.6
01/31/91 THIS REPORT WILL ILLUSTRATE USE OF PAGE 1
BEFORE-BREAK PROCEDURE
EMPLOYEE GROSS NET
DEPT NUMBER PAY PAY DED PCT
911 00445 292.00 206.60 85.40 29.24
11710 243.24 167.96 75.24 30.93
11357 283.92 215.47 68.45 24.10
01963 445.50 356.87 88.63 19.89
09764 121.95 96.64 25.31 20.75
04589 313.60 229.69 83.91 26.75
05805 174.15 134.03 40.12 23.03
03890 386.40 272.53 113.87 29.46
12461 313.60 219.91 93.69 29.87
12829 365.60 238.04 127.56 34.89
01730 315.20 202.43 112.77 35.77
03571 242.40 182.09 60.31 24.88
DEPARTMENT 911 3,497.52 2,522.26 975.26 27.88
914 07231 1,004.00 685.23 318.77 31.75
08262 376.00 215.95 160.05 42.56
10961 399.20 291.70 107.50 26.92
11602 344.80 250.89 93.91 27.23
00185 279.36 189.06 90.30 32.32
DEPARTMENT 914 2,403.36 1,632.83 770.53 32.06
921 00577 220.80 154.70 66.10 29.93
11376 360.80 223.71 137.09 37.99
05482 183.75 141.47 42.28 23.00
DEPARTMENT 921 765.35 519.88 245.47 32.07
FINAL 6,666.23 4,674.97 1991.26 29.87
AFTER-BREAK. PROC
An AFTER-BREAK procedure can be used to produce special annotation on control reports. The value of LEVEL (a
system-defined field) can be used to determine which control break is being processed. In the following example, the total
line for the second control field ZIP receives special annotation.
AFTER-BREAK Example
268
CA Easytrieve® Report Generator 11.6
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
AFTER-BREAK. PROC
IF LEVEL EQ 2
DISPLAY 'TOTALS FOR THE STATE OF ' STATE
END-IF
END-PROC
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Produce:
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 802.35
269
CA Easytrieve® Report Generator 11.6
JONES IL 60077 641.97
IL 1444.32
TOTALS FOR THE STATE OF IL
SMITH TX 75218 777.77
TX 777.77
TOTALS FOR THE STATE OF TX
2222.09
ENDPAGE. PROC
You can use an ENDPAGE procedure to produce page footing information. It is invoked whenever end-of-page is
detected. It is typically used to produce page totals or other annotations, as in the following example of page footer
annotation.
ENDPAGE Example
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
ENDPAGE. PROC
DISPLAY SKIP 2 '* CONFIDENTIAL - FOR INTERNAL USE ONLY *'
END-PROC
Data:
270
CA Easytrieve® Report Generator 11.6
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Produce:
...
* CONFIDENTIAL - FOR INTERNAL USE ONLY *
╞══════════════════════════════════════════════════════════╡
...
TERMINATION. PROC
A TERMINATION procedure is invoked at the end of the report. You can use this procedure to print report footing
information, including control totals and distribution information. The following is an example of report footing.
TERMINATION Example
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
TOTAL-NET S 8 N 2
JOB INPUT FILE1 NAME MYPROG
TOTAL-NET = TOTAL-NET + PAY-NET
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
TERMINATION. PROC
DISPLAY NOTITLE
271
CA Easytrieve® Report Generator 11.6
DISPLAY SKIP 5 TOTAL-NET 'IS THE Y-T-D COMPANY NET PAY'
DISPLAY SKIP 5 'PLEASE ROUTE THIS REPORT TO CORPORATE OFFICERS'
END-PROC
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Produce:
...
╞═════════════════════════════════════════════════════════════════╡
2222.09 IS THE Y-T-D COMPANY NET PAY
PLEASE ROUTE THIS REPORT TO CORPORATE OFFICERS
BEFORE-LINE. PROC and AFTER-LINE. PROC
A BEFORE-LINE procedure is invoked immediately before, and an AFTER-LINE procedure immediately after, the printing
of each detail line.
A BEFORE-LINE or AFTER-LINE procedure is commonly used to print an annotation before or after a detail line on the
report. The following example shows how you can use an AFTER-LINE procedure to print information after a detail line of
a report:
Statements:
272
CA Easytrieve® Report Generator 11.6
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
DTLCTL EVERY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
AFTER-LINE. PROC
IF PAY-NET GE 500
DISPLAY '* EMPLOYEE ' LAST-NAME ' +
EXCEEDED WEEKLY SALARY GOAL *'
END-IF
END-PROC
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Produces:
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 678.90
273
CA Easytrieve® Report Generator 11.6
* EMPLOYEE BROWN EXCEEDED WEEKLY SALARY GOAL *
BROWN IL 60076 123.45
IL 60076 802.35
JONES IL 60077 543.21
* EMPLOYEE JONES EXCEEDED WEEKLY SALARY GOAL *
JONES IL 60077 98.76
IL 60077 641.97
IL 1444.32
SMITH TX 75218 666.66
* EMPLOYEE SMITH EXCEEDED WEEKLY SALARY GOAL *
SMITH TX 75218 111.11
TX 75218 777.77
TX 777.77
2222.09
System-Defined Fields
System-defined fields are fields that CA Easytrieve® Report Generator automatically defines and maintains internally.
You can access these fields in your program to retrieve data that can be useful in processing, or in certain types of error
trapping.
General Purpose Fields
CA Easytrieve Report Generator automatically provides the following system-defined fields for general use:
SYSDATE
SYSDATE is a read-only field that contains the system date at the start of CA Easytrieve Report Generator execution. The
DATE option of the Options Table determines the format of the date. Normally, a slash (/) separates the month, day, and
year components of the date (for example, MM/DD/YY). For more information about the DATE option, see the Language
Reference section.
SYSDATE-LONG
SYSDATE-LONG is a read-only field that contains the system date at the start of CA Easytrieve Report Generator
execution and is similar to SYSDATE, except that it includes the century (for example, MM/DD/YYYY).
SYSTIME
SYSTIME is a read-only field that contains the system time at the start of CA Easytrieve Report Generator execution.
Normally, a colon (:) separates the data into hours, minutes, and seconds (for example, HH:MM:SS).
274
CA Easytrieve® Report Generator 11.6
RETURN-CODE
RETURN-CODE is a field whose contents are returned to the operating system in register 15 when CA Easytrieve Report
Generator terminates. RETURN-CODE is initialized to zero, but you can set it to any value. RETURN-CODE applies only
to MVS systems.
UIBFCTR
When processing an IMS/DLI database in a CICS environment, UIBFCTR contains the values from the UIBFCTR fields in
the CICS UIB. For a description of the UIBFCTR fields, see the IBM CICS Application Programmer's Reference Manual.
UIBDLTR
When processing an IMS/DLI database in a CICS environment, UIBDLTR contains the values from the UIBDLTR fields in
the CICS UIB. For a description of the UIBDLTR fields, see the IBM CICS Application Programmer's Reference Manual.
UIB-ADDRESS
When processing an IMS/DLI database in a CICS environment, UIB-ADDRESS contains the address of the CICS UIB. It
only contains the UIB-ADDRESS following the execution of a Format 5 DL/I statement. For a description of the UIB, see
the IBM CICS Application Programmer's Reference Manual.
File Processing Fields
CA Easytrieve Report Generator automatically provides the following system-defined fields for each of your files:
These fields are stored as part of working storage but can be qualified by file-name. As working storage fields, they are
not subject to invalid file reference errors.
RECORDLENGTH
RECORD-LENGTH is a field with zero decimal places that is used for all file types to determine or establish the length
of the current data record. For variable-length records, this field contains only the length of the record's actual data. CA
Easytrieve Report Generator automatically adjusts the field to account for the 4-byte record-control word and 4-byte block-
control-word. For variable-length files, assign the length of the record to the RECORD-LENGTH field before the PUT or
WRITE statement is executed.
For SQL files, RECORD-LENGTH contains the sum of the maximum lengths of all fields in the file. For CA IDMS and IMS/
DLI files, RECORD-LENGTH contains the sum of the maximum lengths of all records in the file.
RECORDCOUNT
RECORD-COUNT is a read-only field with zero decimal places that contains the number of logical I/O operations that are
performed on a file.
For CA IDMS and IMS/DLI files, only automatic input increments RECORD-COUNT.
FILESTATUS
FILE-STATUS is a read-only field that contains the results of the most recent I/O operation on a file. FILE-STATUS is
available when you code STATUS on the I/O statement. If you do not code STATUS, an appropriate error message is
generated. The error message contains one of these codes.
For CA IDMS files using automatic input, FILE-STATUS contains IDMSSTATUS. For IMS/DLI files, FILE-STATUS contains
the status code from the PCB.
FILE-STATUS codes and their meanings are:
275
CA Easytrieve® Report Generator 11.6
• 0000 Operation successful.
Explanation: This is not an error condition. It indicates that the last I/O operation was successful. No additional
information is required.
• 0004 End of file.
Explanation: This is not an error condition. It indicates that the file position has been moved beyond the last record in
the file.
Cause: This condition occurs following a GET statement when the current record is the last record in the file. It can
occur for SEQUENTIAL, INDEXED, and RELATIVE files.
Following a GET PRIOR statement, this condition could also indicate the beginning of a file.
• 0008 Record with a duplicate alternate key exists.
Explanation: This is not an error condition. It indicates that the key of this record matches the key of the record that
follows it in the sequential order of this file.
Cause: This condition can occur following a GET or READ statement for an INDEXED file that does not have unique
keys.
Following a GET statement, this condition indicates that at least one more record with a matching key is waiting to be
processed.
Following a READ statement, this condition indicates that there is at least one more record in the file with a matching
key (a GET statement must be used to retrieve any remaining records).
In CICS/VS, MVS (batch and TSO), and CMS/OS, an INDEXED file can have non-unique keys if the associated data
set is a VSAM PATH and the auxiliary index data set was defined with non-unique keys.
• 0012 Duplicate key.
Explanation: This error condition indicates that an attempt was made to store a record with a duplicate key, or that
there is a duplicate record for an alternate index with the Unique Key option.
Cause: This condition can occur following a PUT or WRITE ADD statement for an INDEXED file, or a PUT statement
for a RELATIVE file.
For an INDEXED file, it indicates that the key of the record matches the key of a record already present in the file. For
a RELATIVE file, it indicates that the slot that is designated by the relative record number already contains a record
(the slot is not empty).
This condition can also occur following a WRITE UPDATE statement for a SEQUENTIAL or INDEXED file. It indicates
that:
– There is at least one alternate index that is associated with this file.
– The alternate index was defined with the unique key and the upgrade option.
– The updated record caused a duplicate key condition to occur when the alternate index was updated.
• 0016 Record not found.
Explanation: This error condition indicates that the record that is designated by the KEY parameter is not found in the
file.
Cause: This condition can occur following a READ or POINT statement for an INDEXED or RELATIVE file. For an
INDEXED file, it indicates that no record in the file matches the key that is specified by the statement. For a RELATIVE
file, it indicates that the slot that is designated by the relative record number is empty.
• 0024 Logical or physical error condition.
Explanation: This error condition indicates that a logical or physical error condition was detected by the access
method routines that are used to access the file. The specific cause of the error is displayed in a runtime abend
message. For a list of the feedback codes, see Messages and Codes.
PATH-ID
For CA IDMS and IMS/DLI files, PATH-ID is field that contains the ID value of the lowest record retrieve in a path, using
the RETRIEVE statement. For more information, see the Programming section.
276
CA Easytrieve® Report Generator 11.6
IDMSCOM
IDMSCOM contains a set of fields that are defined for the CA IDMS Communications Block. For more information, see the
Programming section.
SLC
SLC contains a set of fields that are defined for a logical record communications block. For more information, see the
Programming section.
SQLCA
SQLCA contains a set of fields that are defined for the SQL communications Block. For more information, see the
Programming section.
Report Processing Fields
CA Easytrieve Report Generator automatically provides the following system-defined fields for report generating:
These fields are stored as part of working storage and are read-only.
LINE-COUNT
LINE-COUNT contains the number of lines printed on the page.
LINE-NUMBER
LINE-NUMBER contains the number of the line being printed within the line group.
PAGE-COUNT
PAGE-COUNT contains the number of pages printed.
PAGE-NUMBER
PAGE-NUMBER contains the number of the page being printed.
TALLY
TALLY contains the number of detail records that comprise a control break. You can use TALLY on a LINE statement or
you can use it in calculations within report procedures. TALLY is commonly used to determine averages for a control level.
TALLY is a field with zero decimal places. This definition is used for calculations contained within report procedures.
The TALLYSIZE parameter of the REPORT statement defines the number of digits that are printed for TALLY. A TALLY
accumulator is created for each control break level.
LEVEL
LEVEL is a system-defined field provided for determining which control break is currently active. The value of LEVEL
indicates the control break level and varies from 0 to n based on the number of field names on the CONTROL statement
of the associated report. LEVEL contains the logical position number of the controlling field name. This value also applies
to FINAL, whether it is coded or not.
LEVEL Example
LEVEL = 1 on TERRITORY breaks
277
CA Easytrieve® Report Generator 11.6
LEVEL = 2 on REGION breaks
LEVEL = 3 on AREA breaks
LEVEL = 4 final break
CONTROL FINAL NOPRINT AREA REGION TERRITORY
4 3 2 1
CONTROL AREA REGION TERRITORY
4 3 2 1
BREAK-LEVEL
BREAK-LEVEL indicates the highest field in the break.
278
CA Easytrieve® Report Generator 11.6
Using
CA Easytrieve® Report Generator is an information retrieval and data management system designed to simplify computer
programming. Its English like language and simple declarative statements provide the new user with the tools needed
to produce comprehensive reports and screens with ease, and its enhanced facilities provide the experienced data
processor with the capabilities to perform complex programming tasks.
CA Easytrieve® Report Generator operates in a variety of mainframe, UNIX, Linux for zSeries, and Intel Windows
environments. CA Easytrieve® Report Generator runs interactively for data inquiry, analysis, maintenance and reporting.
The output can be returned to your terminal or routed to a printer.
This section describes how to compile, link edit, and execute CA Easytrieve® Report Generator programs. Use this
section, along with Language Reference and Programming, to provide the information you need to use CA Easytrieve®
Report Generator for all of your programming needs.
Using Best Practices
This article contains the following best practices for using CA Easytrieve Report Generator:
Use Link-Edit to Execute Production Programs
We recommend using the link-edit method for executing production programs instead of the compile-and-go method. The
compile-and-go method compiles and executes the programs in a single step, whereas the link-edit method results in a
load module.
Using the link-edit method instead of the compile-and-go method provides enhanced performance capabilities. Load
modules are less prone to unauthorized and inadvertent changes than source code. Also, compiling a program once
reduces the number of resources required.
Use Debugging Aids
You can use ABEXIT, SORTMSG, or other external debugging aids to debug your programs. We recommend that you use
the default values that are provided in the Options Table for testing purposes.
If you encounter a problem, CA Support may ask you to add the code that follows to the JCL and send the
documentation. By enabling these debugging aids for any documentation sent to CA Technologies, turnaround time for a
Support issue can be reduced.
//CAOESTOP DD DUMMY CA-OPT II & CA-SYMDUMP - OFF
//IDIOFF DD DUMMY IBM FAULT ANALYZER -- OFF
//ABNLIGNR DD DUMMY ABEND-AID -- OFF
//DMBENAN DD DUMMY DUMPMASTER -- OFF
//ESPYIBM DD DUMMY EYE-SPY -- OFF
//PSPOFF DD DUMMY SOFTWORKS PERFORMANCE ESSENTIAL -- OFF
Follow to the first line of the CA Easytrieve® Report Generator program (if not already specified):
LIST ON MACROS
Add the following DEBUG programs (if not already specified):
PARM DEBUG(PMAP DMAP STATE XREF LONG) ABEXIT NO SORT(MSG(ALL))+
279
CA Easytrieve® Report Generator 11.6
LIST FILE
NOTE
Generally, parameters that are useful for debugging are not the best choice when executing your program. They
can add unnecessary overhead to the execution of production programs. For example, a snap dump (produced
with ABEXIT SNAP) is ideal for debugging a S0C7 data exception ABEND. However, ABEXIT NO is a better
choice to debug actual source code problems. The default values that are provided in the Options File are ideal
for testing purposes.
Avoid Using Reserved Words
We recommend that you use unique, uncommon, and lowercase or mixed case words in your programs for naming the
fields, files, or labels. CA Easytrieve Report Generator uses uppercase, hyphenated, and common English words as
reserved words. Avoid using such words because they can be added to the list of reserved words in future releases.
If you use reserved words, change them for your program to compile with the new release. See Symbols and Reserved
Words.
Use VSAM KSDS Instead of Large Tables
We recommend using the VSAM Key Sequenced Data Set (KSDS) files instead of tables with many entries.
Large tables require a larger REGION size as compared to the VSAM KSDS files. The VSAM KSDS files also let you work
with variable record sizes and segmented data areas, which is not possible with tables.
NOTE
• If the estimated number of table entries exceeds 32767, use the VSAM KSDS setting.
• For more information about the FILE statement INDEXED option (for VSAM KSDS), see FILE Statement.
Use the IDD Interface
We recommend that you use the IDD interface instead of manually coding the definitions. The IDD interface automatically
generates definitions for files, records, logical records, element records, and fields. The definitions are taken from the CA
IDMS Integrated Data Dictionary.
The IDD interface greatly reduces the effort that is associated with database processing. The interface also provides
relevant programming information, which saves time and spares the database administrator an interruption.
Automatically Generate SQL Field Definitions
We recommend automatically generating CA Easytrieve Report Generator field definitions from the database catalog by
using the SQL INCLUDE Statement. The SQL INCLUDE statement names the SQL table or view for which column names
and data types are obtained. The statement then defines the location at which the field definitions are generated. The
SQL INCLUDE statement must precede any other SQL or SELECT statements and must be coded in the library section of
your program.
Using the SQL INCLUDE statement for automatically generating field definitions eliminates the need to code host variable
definitions in the library section of your program.
Use Macros
We recommend that you use macros in your programs. Macros let you add and remove sections of code based on
functionality. You can also add file and field names into macros. You can show macros inline or hide them to reduce the
program size.
280
CA Easytrieve® Report Generator 11.6
Using macros is an efficient and effective method for reusing code and reducing the coding time. Using macros is a better
method than copying code within your program. Copying the entire existing programs may make their development easy
but then programs are difficult to maintain and have excessive overhead.
NOTE
• You can purchase CA Easytrieve Toolkit macros, CA PanAudit Plus macros, and their related routines
separately. These macros perform several time, date, and conversion functions and JIF layouts.
• For more information about macros, see the Macro Facility section
Reduce CPU Overhead
Sorting data during a CA Easytrieve Report Generator report run increases CPU overhead. For example,
the SORT statement and using a SEQUENCE statement within a REPORT statement both increase CPU overhead.
We recommend the following methods for reducing CPU overhead:
• If possible, keep your master file in sorted order. Do not perform sorting during CA Easytrieve Report
Generator program execution.
• Before you merge new records with a master file, presort them using the same order as the master file.
• If sorting is necessary, filter the data in the file before sorting using the SELECT statement or an E15 sort exit.
Create and Format a Report
This article includes the following information:
NOTE
• This article includes basic information about creating a report. For more detailed examples and information
about the features and options that are available in all implementations of the product, see the other articles
in the Using section and the Language Reference section.
• For information about interfacing CA Easytrieve Report Generator programs with programs that are written in
other languages such as COBOL, C, or C++, see the Programming section.
• Because CA Easytrieve Report Generator is a compiled language that runs in many data processing
environments, the examples in this article are generic and do not address variations between different
installations. It is beyond the scope of this article to address the specifics of all the operating environments in
which the product can run.
Create a Report
A sample CA Easytrieve Report Generator program follows. You can enter the code and run the program from your
terminal.
FILE PERSNL FB(150 1800)
EMPNAME 17 8 A
EMP# 9 5 N
DEPT 98 3 N
GROSS 94 4 P 2
JOB INPUT PERSNL NAME FIRST-PROGRAM
PRINT PAY-RPT
REPORT PAY-RPT LINESIZE 80
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
LINE 01 DEPT EMPNAME EMP# GROSS
281
CA Easytrieve® Report Generator 11.6
When specified, this program produces a formatted report including date, page number, title, column headings, properly
spaced detailed lines, and more as follows:
01/31/91 PERSONNEL REPORT EXAMPLE-1 PAGE 1
DEPT EMPNAME EMP# GROSS
903 WIMN 12267 373.60
943 BERG 11473 759.20
915 CORNING 02688 146.16
935 NAGLE 00370 554.40
911 ARNOLD 01963 445.50
914 MANHART 11602 344.80
917 TALL 11931 492.26
918 BRANDOW 02200 804.64
911 LARSON 11357 283.92
932 BYER 11467 396.68
921 HUSS 11376 360.80
911 POWELL 11710 243.20
943 MCMAHON 04234 386.40
This report is simply an edited display of fields from an employee file named PERSNL.
NOTE
The PERSNL sample file is provided with the product. Ask your system administrator where it is stored at your
site.
The FILE and DEFINE Statements
The FILE and DEFINE statements define the library of data that is used as input to any processing activities.
The first line of this program contains the FILE statement. A FILE statement must be included for every file you use as
input to or output from your program. It tells the program where to get the data that you want processed and can also
describe how the data is stored.
There are four DEFINE statements in our sample program. The first definition is EMPNAME. DEFINE statements describe
fields in a record of the PERSNL file.
You do not see the word DEFINE in the previous lines, but it is implied. For example, we could have specified:
DEFINE EMPNAME 17 8 A
NOTE
You can also use DEFINE statements within the program logic to define working storage. In that case, the
DEFINE keyword is required.
The JOB and IF Statements
The JOB and IF statements define and initiate all processing activities in our sample program. You can also add
conditional statements and calculations for salary deductions.
The JOB statement indicates the beginning of some form of processing. The JOB statement can also automatically
provide input (if input is available) to the processing statements that follow it.
Although CA Easytrieve Report Generator lets you control input, automatic input is provided as an alternative.
282
CA Easytrieve® Report Generator 11.6
Automatic Input
Using the INPUT parameter of the JOB statement indicates that the named file (in this case PERSNL) is to be made
automatically available to your program.
If INPUT is not specified, the program looks for input and uses the first file that is described in the library section, unless
the JOB activity is preceded by a SORT activity. In that case, the program uses the output from that SORT. For more
information about SORT, see Sorting Files. Because our sample program has only one input file (PERSNL), the INPUT
parameter on the JOB statement is optional. Without the INPUT parameter, our sample program checks for input and
uses the first file that is encountered, which is PERSNL (the only file in our library section).
Naming a JOB Activity
The next element after the INPUT parameter in our sample program is the word NAME. NAME indicates that a job name
follows.
The IF Statement
In the previous report program, we have only extracted some data from a file and printed it out. You can also include IF
statements to add conditions to the program.
In the sample program, the program accesses a field called GROSS, which contains employee gross pay. Because net
pay (take home pay) is the gross pay minus any deductions, you realize that you must determine what to deduct. For
example, we deduct 28 percent from employees who earn $500 or more.
You can state this condition as follows with a simple conditional expression:
IF GROSS GE 500
DEDUCTIONS = .28 * GROSS
NET-PAY = GROSS - DEDUCTIONS
ELSE
NET-PAY = GROSS
DEDUCTIONS = 0
END-IF
In the previous expression, if the gross pay is greater than or equal to 500, deduct 28 percent to obtain the net pay.
Otherwise, if the gross is less than 500, there are no deductions and net pay equals gross pay. CA Easytrieve Report
Generator requires an END-IF statement to complete the expression.
To add conditional logic to the program, place it in the JOB activity section after the JOB statement. You can store the
results of the new variables, DEDUCTIONS and NET-PAY, in working storage.
Working Storage
Unlike many other programming languages, the definition of working storage fields in CA Easytrieve Report Generator is
easy. You can place them in the library section of your program, or in the activity section before the logic that uses them.
To define a working storage field, use the same type of attributes that are used to describe other fields. However, use the
letter W to replace the numeric value that typically describes the start location.
DEDUCTIONS W 4 P 2
NET-PAY W 4 P 2
The code describes two working storage fields, four characters in length, in packed decimal format, with two decimal
places.
283
CA Easytrieve® Report Generator 11.6
The PRINT Statement
When the conditional statements have run against a record in the PERSNL file, the PRINT statement tells the program to
execute the report definition statements. In the previous PRINT statement example, these statements are identified by a
user-supplied name, PAY RPT. This name ties the PRINT statement to a specific report of the same name as indicated
on the REPORT statement. If the report name is not included, the first report in the JOB activity section is executed
regardless of whether it has a name.
A report declaration consists of a series of statements that define the format and content of a report. These statements
consist of the REPORT statement, report definition statements, and report procedures. So far, we have seen three such
statements in our sample program:
• REPORT
• TITLE
• LINE
When the report statements have been executed, control is returned to the beginning of the JOB activity section where the
next record is processed or end of file processing is performed. All output routines, line counts, and page advances are
handled automatically.
The LINE Statement
The LINE statement is responsible for printing detail lines on the report. It tells the program what fields to print and the
order in which to print them.
To add DEDUCTIONS and NET PAY to the report output, specify:
LINE 01 DEPT EMPNAME EMP# GROSS NET PAY DEDUCTIONS
New Sample Program
We can run our updated program to generate a report. The updated program with all the changes that we have described
in this article is:
FILE PERSNL FB(150 1800)
EMPNAME 17 8 A
EMP# 9 5 N
DEPT 98 3 N
GROSS 94 4 P 2
DEDUCTIONS W 4 P 2
NET-PAY W 4 P 2
JOB INPUT PERSNL NAME FIRST-PROGRAM
IF GROSS GE 500
DEDUCTIONS = .28 * GROSS
NET-PAY = GROSS - DEDUCTIONS
ELSE
NET-PAY = GROSS
DEDUCTIONS = 0
END-IF
PRINT PAY-RPT
REPORT PAY-RPT LINESIZE 80
TITLE 01 'PERSONNEL REPORT EXAMPLE-1'
284
CA Easytrieve® Report Generator 11.6
LINE 01 DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
The sample output from this program follows. Two new columns have been added: NET-PAY and DEDUCTIONS.
01/31/91 PERSONNEL REPORT EXAMPLE-1 PAGE 1
DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
903 WIMN 12267 373.60 373.60 .00
943 BERG 11473 759.20 546.63 212.57
915 CORNING 02688 146.16 146.16 .00
935 NAGLE 00370 554.40 399.17 155.23
911 ARNOLD 01963 445.50 445.50 .00
914 MANHART 11602 344.80 344.80 .00
917 TALL 11931 492.26 492.26 .00
918 BRANDOW 02200 804.64 579.35 225.29
911 LARSON 11357 283.92 283.92 .00
932 BYER 11467 396.68 396.68 .00
921 HUSS 11376 360.80 360.80 .00
911 POWELL 11710 243.20 243.20 .00
943 MCMAHON 04234 386.40 386.40 .00
Format Report Output
You can format numeric values of your report output with dollar signs by adding an edit mask to the DEFINE statement.
You can also define custom field headings.
Edit Masks
An edit mask is a pattern of characters that specify how numeric data should be printed.
NOTE
Alphanumeric fields cannot be edited.
In the following example, edit masks have been added to the three currency fields in our example program so they print
with dollar signs:
GROSS 94 4 P 2 MASK (A '$$,$$9.99')
NET-PAY W 4 P 2 MASK A
DEDUCTIONS W 4 P 2 MASK (A BWZ)
The MASK parameter of the DEFINE statement indicates that an edit mask follows. In the previous example, the actual
mask consists of the characters '$$,$$9.99'. Masks are always enclosed in single quotes.
The effect on our report of adding these masks is as follows:
01/31/91 PERSONNEL REPORT EXAMPLE-1 PAGE 1
DEPT EMPNAME EMP# GROSS NET-PAY DEDUCTIONS
903 WIMN 12267 $373.60 $373.60
943 BERG 11473 $759.20 $546.63 $212.57
915 CORNING 02688 $146.16 $146.16
935 NAGLE 00370 $554.40 $399.17 $155.23
285
CA Easytrieve® Report Generator 11.6
911 ARNOLD 01963 $445.50 $445.50
914 MANHART 11602 $344.80 $344.80
917 TALL 11931 $492.26 $492.26
918 BRANDOW 02200 $804.64 $579.35 $225.29
911 LARSON 11357 $283.92 $283.92
932 BYER 11467 $396.68 $396.68
921 HUSS 11376 $360.80 $360.80
911 POWELL 11710 $243.20 $243.20
943 MCMAHON 04234 $386.40 $386.40
NOTE
Any leading zeros are suppressed and each value has a dollar sign. Any all-zero values in the DEDUCTIONS
column are printed as blanks.
Field Headings
So far in our example program, field (or column) headings have come directly from the field names themselves. The
program automatically uses field names specified on the DEFINE statement as column headings, unless column headings
are described separately.
One way to describe alternative column headings is with the HEADING parameter of the DEFINE statement. For example,
you can replace the somewhat cryptic heading EMP# with the more readable heading EMPLOYEE NUMBER as follows:
EMPNAME 17 8 A
EMP# 9 5 N HEADING ('EMPLOYEE' 'NUMBER')
DEPT 98 3 N
Placing each word in single quotes indicates that the headings should be printed on separate lines, one word over the
other.
The following example shows how the new heading prints when the program is run:
01/31/91 PERSONNEL REPORT EXAMPLE-1 PAGE 1
EMPLOYEE
DEPT EMPNAME NUMBER GROSS NET-PAY DEDUCTIONS
You can include headings on the DEFINE statement for any fields that need better identification than the field name.
Compile and Link Your Program
Controlling Compilation
You can control the compilation of your program using the following statements:
• PARM -- lets you customize your operating environment during the compilation of your program.
• LIST, NEWPAGE, SKIP, POP, PUSH -- let you control the physical layout of the compile listing.
PARM Statement
The PARM statement, if coded, must be the first statement in your program. It is also known as the environment section
of the program. When CA Easytrieve is installed, certain compiler options are specified for your site. The PARM statement
286
CA Easytrieve® Report Generator 11.6
lets you override these site options for a specific program. The following table summarizes the site options you can
override by coding parameters on the PARM statement:
Activity Parm Statement Parameters
Control object code generation COMPILE (Supported for compatibility with prior releases.)
LINK
SYNTAX
Control debugging information when compiling DEBUG:
DMAP|NODMAP
FLDCHK|NOFLDCHK
LIST:
PARM|NOPARM
Control operation of the sort program. SORT:
ALTSEQ
NOTE
For more information, see the PARM Statement.
Listing Control Statements
Listing control statements let you format the physical layout of the compile listing as follows:
• You can place listing control statements anywhere in the CA Easytrieve® Report Generator source.
• Listing control statements must be on a source line by themselves.
• Listing control statements do not appear in the printed output of your program.
NOTE
For complete syntax and use of the listing control statements, see the Language Reference section.
LIST
The LIST statement regulates the printing of all or portions of your program.
• LIST OFF suppresses the printing of all subsequent statements.
• LIST ON prints all subsequent statements.
• LIST MACROS/NOMACROS controls the printing of code stored in CA Easytrieve® Report Generator macros (pre-
written sections of source code).
The default is LIST ON MACROS.
NOTE
For more information about macros, see the Macro Facility section.
NEWPAGE
The NEWPAGE statement prints the next source statement at the top of the next page.
SKIP
The SKIP skips the specified number of lines before printing the next source statement. You can use SKIP to make your
program more readable.
287
CA Easytrieve® Report Generator 11.6
POP and PUSH
You use the PUSH statement to save the current settings of LIST ON/OFF MACROS/NOMACROS. You can then change
the settings temporarily, using the POP statement to restore the previous settings.
You can use PUSH and POP in macros to control the listing of the macro expansion without affecting listing control for the
entire program.
For example, if there is a portion of the macro that you do not want to print, you could specify LIST OFF in the macro, then
LIST ON to turn printing back on. However, if you specified LIST OFF before invoking the macro, LIST ON in the macro
prints the remainder of the program, though you may have explicitly specified LIST OFF.
Alternatively, start the macro by PUSHing (saving) the program's listing control settings. You can then code LIST OFF and
LIST ON as appropriate in the macro. End the macro by POPping (restoring) the program's settings so that the program
continues with the intended settings.
NOTE
For more information about macros, see the Macro Facility section.
Results of the Compilation
When you compile a CA Easytrieve Report Generator program, your source code is converted to object code. A
compilation results listing is also produced.
This article includes the following information:
Object Code (UNIX and Linux for zSeries Only)
Unless you specify the -P compilation parameter, your program is converted into executable object code. The object code
is written to an .o file.
Unless you specify the -c compilation parameter, the object code is linked into an executable file. The executable is called
a.out, unless otherwise directed with the -o compilation parameter. See Link-Editing Non-Mainframe Programs for details.
P-Code (Windows)
Unless Visual Studio is detected as being installed on your system, in Windows, your program is converted into a P-Code
file. The p-code is written to a .pco file.
Note that if Visual Studio or Visual Studio .NET is detected, you can specify that your program will result in a standard
executable program (EXE extension). This can be controlled through the Program Profile Manager. See Workbench Tools
and Utilities for more information.
The P-Code file is executed using the CA Easytrieve Report Generator interpreter (ezterp).
See Execute a Program for details.
Compile Listing
The compile listing documents a CA Easytrieve Report Generator program. The listing includes the program statements,
diagnostics, a cross reference table, data map, and a compilation summary. You can use this information alone or with the
Error Analysis Report to debug a program's logic and data. See Error Analysis Report for information.
The compile listing is written to a .lst file in the directory that contains the source file when you specify the -L or +L
compilation parameter.
288
CA Easytrieve® Report Generator 11.6
PARM Statement Listing Options
You can code optional PARM statement parameters to select the types of printed output the compilation generates.
Default values are taken from the options table. A compiled program uses the compile time options that were in effect at
the time of compilation.
The following table provides a list of optional printed output that can accompany the standard statement listing. You can
code LIST OFF as the first statement in your program to turn off the statement listing.
Compiler Option Result
DMAP Map of the data items in your program.
LIST: Compile summary including PARM options.
PARM/NOPARM
The order of the optional output is:
1. Statement listing
2. DMAP
3. Cross reference listing
4. Compile summary
Header
The header of each page of the compile listing consists of four lines:
• The first line, from left to right, contains the date and time of compile, a compiler identifier, and a page number.
• The second line contains the user ID of the person compiling the program and your company name.
• The third line is blank.
• The fourth line is the copyright of the product.
An example of a compile listing header format follows:
mm/dd/yy hh:mm:ss <easy> vv.rf yynn PAGE 1
userid your company name
Programs and all supporting materials copyright (c) 2008 CA, Inc.
Statement Listing
The statements in your program are listed and numbered. The statement listing shows:
• The origin of each statement, if it is contained in a macro
• Macro statements after parameter substitution is performed
• Warning and error messages.
The statement listing has three columns:
• (a)
Macro name
• (b)
Statement number
• (c)
Statement
289
CA Easytrieve® Report Generator 11.6
You receive warning and error messages inserted into your source code. The messages are specific and easily
identifiable. The messages normally use a special character that directs you to the word on the statement most likely
causing the error.
For example, the SEQUENTIAL parameter of the FILE statement may be misspelled. The error message uses a dollar
sign ($) to point to the word in error. A dollar sign identifies a critical error and a plus sign (+) begins a warning message.
NOTE
Characters identifying critical errors and warning messages can be different at your site. See your system
administrator for the characters used at your site.
In another example, an error message tells you that the data type of J in the definition of BRANCH is invalid because valid
types are A, B, N, P, or U. Finally, a warning message may tell you that the MYPROC procedure is never referenced.
NOTE
You can still execute a program with warning messages, but we recommend that you resolve warning conditions
before you execute the program.
DMAP
The DMAP (data map) provides the location of file and work fields. The DMAP also reports the attributes of all files and
fields in your program.
• (a)
The section title.
• (b)
The group header identifying the owner of the following fields.
• (c)
The Base identifies the storage block where a field is located. The storage block's address is given in the Error
Analysis Report.
• (d)
The location specifies:
– W
Fields defined as W working storage fields
– S
Fields defined as S working storage fields
– I
Names defined by INDEX
– Nn
The location, relative to 1, for regular file fields
– D
System-defined fields
• (e)
The field's displacement from the beginning of the storage block. In this example, field EMP# in file PERSNL is in
storage block 14, at displacement 10. The displacement is in hexadecimal format.
• (f)
The length of a single occurrence in decimal format.
• (g)
The field's format or type: A, B, I, N, P, or U. V indicates the VARYING option.
• (h)
The number of decimal positions for a numeric field.
• (i)
The number of times a field occurs, as declared by the OCCURS clause of the DEFINE statement.
• (j)
290
CA Easytrieve® Report Generator 11.6
ED indicates HEX or BWZ editing for this field.
– M
Identifies given mask name, A through Y.
– R
Indicates that the R (RESET) parameter was specified for a W field.
– KE
Indicates that this is a key field. The character C in this column indicates a CA IDMS CALC key.
• (k)
The level of the field.
• (l)
The field name. The name is indented one character for each level, up to level 7. Level 8 through level 50 names are
indented the same as level 7 names. If a field name does not fit on the page, it is truncated.
• (m)
Relative file number.
• (n)
File name.
Compile Summary
The Compile Summary summarizes any errors in your program and lists the set of compiler options, execution options,
and the list of macro libraries used during the compilation. The Compile Summary also lists the size of the code
generated.
• (a)
The section title.
• (b)
Diagnostic (error) counts reported by type.
• (c)
The options in effect.
• (d)
The macro library search list identifies the macro directories for CA Easytrieve Report Generator macros.
Program Compilation and Link-Editing Using JCL
This article provides JCL examples for running various job types in z/OS. The following JCL examples include the //
EZOPTBL DD statement to identify the Options Table file to CA Easytrieve® Report Generator. This DD statement is
optional and can be omitted. If it is omitted, the CA Easytrieve compiler and runtime retrieve the Options Table DSN from
the INI file. The INI file is a load module in the CBAALOAD named EZTINI. This load module is created in the installation
step that creates the Options Table file. You can override the Options Table DSN identified by the INI file by specifying
the //EZOPTBL DD statement. You can also modify the INI file by rerunning the installation step that creates the Options
Table file.
This article includes the following information:
WARNING
In all JCL examples, ensure that all lowercase entries are examined and changed.
In the following JCL examples, PGM=EZTPA00 is used to run Compile-only and Compile-and-Go jobs. For compatibility
with older product releases, PGM=EZT (for Compile-and-Go) and PGM=EZTCOM (for Compile-only) are still accepted.
However, these program names are deprecated and may not be supported in the same manner in the future. For this
reason, we recommend writing new application JCL using PGM=EZTPA00.
291
CA Easytrieve® Report Generator 11.6
Compile-only of a CA Easytrieve Program
The following example illustrates the JCL necessary to compile-only your CA Easytrieve application program.
//JOBNAME JOB (000000000),'COMMENT',
// MSGCLASS=X,CLASS=K,NOTIFY=USER,REGION=4M
//*********************************************
//************** COMPILE ********************
//*********************************************
//COMP EXEC PGM=EZTPA00
//STEPLIB DD DISP=SHR,DSN=RETSYS.R116.SP0.BASE.CBAALOAD
//EZTVFM DD UNIT=SYSDA,SPACE=(CYL,(3,1))
//PANDD DD DISP=SHR,DSN=RETSYS.R116.SP0.BASE.CBAAMAC
//SYSPRINT DD SYSOUT=*
//* The following SYSLIN is only required with PARM COMPILE
//SYSLIN DD DISP=(,PASS),DSN=&&PCODE
//SYSIN DD *
PARM SYNTAX or PARM COMPILE
...CA Easytrieve Report Generator source statements...
//
Compile-and-Go Execution of a CA Easytrieve Program
The following example illustrates the JCL necessary to compile and execute your CA Easytrieve application program
without separate link-edit and execution steps.
//jobname JOB accounting.info
//stepname EXEC PGM=EZTPA00,REGION=4M
//STEPLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
//EZOPTBL DD DISP=SHR,DSN=your.easytrieve.r11.EZOPTBL
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//SYSPRINT DD SYSOUT=A
//userfile DD dd-parms
//SYSIN DD *
...<easy> source statements...
//
If you are sending SYSPRINT output to a data set and wish to see both the program compile listing and any runtime
errors, you must put DISP=MOD into your JCL.
Example:
//SYSPRINT DD DSN=name,DISP=(MOD,KEEP),
// SPACE=(TRK(1)),UNIT=SYSDA
Compiling and Link-Editing a Load Module
This example illustrates the JCL necessary to compile and link-edit a load module to be executed later:
//jobname JOB accounting.info
//stepname EXEC PGM=EZTPA00,REGION=4M
//STEPLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
292
CA Easytrieve® Report Generator 11.6
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//SYSPRINT DD SYSOUT=A
//SYSLIN DD UNIT=SYSDA,SPACE=(400,(100,50)),DISP=(,PASS),
// DSN=&&SYSLIN
//SYSIN DD *
PARM LINK(TESTPGM)...
...<easy> source statements...
//LKED EXEC PGM=IEWL
//SYSPRINT DD SYSOUT=A
//SYSLIN DD DSN=&&SYSLIN,DISP=(OLD,DELETE)
//SYSLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
//SYSLMOD DD DISP=SHR,DSN=your.ezt.application.loadlib
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,5))
If an Extended Printer is specified on a FILE in the CA Easytrieve program, and if that Extended Printer is defined in a
Printer Set Definition file that was generated and ftp’d from the Configuration Manager, the following DD statement must
be added to the compilation step of the previous JCL:
//EZTXRPSD DD DISP=SHR,DSN=your.psd.file.from.ftp
Information about the Configuration Manager was provided earlier in this section. For more information about extended
reporting and extended printers, see Programming and Language Reference.
Executing a Compiled Program
This example illustrates the JCL necessary to execute a previously compiled and link-edited CA Easytrieve program:
//jobname JOB accounting.info
//stepname EXEC PGM=TESTPGM
//STEPLIB DD ...
//SYSPRINT DD SYSOUT=A
//SYSSNAP DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTWKO1 DD UNIT=SYSDA,SPACE=(CYL,1)
//EZOPTBL DD DISP=SHR,DSN=your.easytrieve.r11.EZOPTBL
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//userfile DD dd-parms
//SYSIN DD * (optional CARD input)
Executing with the IMS Option
The following procedure can be catalogued and used for executing CA Easytrieve with IMS:
//DLIBATCH PROC MBR=TEMPNAME,PSB=,BUF=8,SPIE=0,TEST=0,EXCPVR=0,
// RST=0,PRLD=,SRCH=0,CKPTID=,MON=N,LOGA=0
// EXEC PGM=DFSRRC00,REGION=512K,
// PARM=(DLI,&MBR,&PSB,&BUF,
// &SPIE&TEST&EXCPVR&RST,&PRLD,&SRCH,&CKPTID,&MON,&LOGA)
//STEPLIB DD DSN=IMSVS.RESLIB,DISP=SHR
// DD DSN=IMSVS.PGMLIB,DISP=SHR
// DD DSN=your.eztp.loadlib,DISP=SHR
//IMS DD DSN=IMSVS.PSBLIB,DISP=SHR
293
CA Easytrieve® Report Generator 11.6
// DD DSN=IMSVS.DBDLIB,DISP=SHR
//SYSPRINT DD SYSOUT=A
//EZOPTBL DD DISP=SHR,DSN=your.easytrieve.r11.EZOPTBL
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//SYSOUT DD SYSOUT=A
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,1)
//SORTWK02 DD UNIT=SYSDA,SPACE=(CYL,1)
//SORTWK03 DD UNIT=SYSDA,SPACE=(CYL,1)
The following JCL executes the previous procedure:
//jobname JOB accounting.info
//EZTPIMS EXEC DLIBATCH,MBR=EZTCOM,PSB=yourpsbname
//PAYFILE DD DISP=SHR,DSN=IMS.DATA.BASE
//PAYFLOW DD DISP=SHR,DSN=IMS.DATA.BASE.OVERFLOW
//SYSIN DD *
...<easy> IMS statements...
/*
//
When executing CA Easytrieve programs with both IMS and DB2 for z/OS statements (if you are running a version of DB2
for z/OS prior to 1.3), change the previous PARM statement to:
// PARM=(BMP,&MBR,&PSB,&BUF,
You also need to add the IBM DB2 SSPGM library and the CA Pan/SQL load library to the STEPLIB statement.
When executing CA Easytrieve® Report Generator Report Generator programs with both IMS and DB2 for z/OS
statements, see Mixed IMS and DB2 for OS/390 and z/OS Execution.
Executing with CA IDMS Under Central Version
The following example illustrates the JCL to compile and link-edit a CA Easytrieve program using CA IDMS under central
version:
//jobname JOB accounting.info
//stepname EXEC PGM=EZTPA00
//STEPLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
// DD DISP=SHR,DSN=idms.loadlib
//SYSPRINT DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,1)
//SYSCTL DD DISP=SHR,DSN=cdms.sysctl
//EZOPTBL DD DISP=SHR,DSN=your.easytrieve.r11.EZOPTBL
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//SYSLIN DD UNIT=SYSDA,SPACE=(400,(100,50)),DISP=(,PASS),
// DSN=&&SYSLIN
//SYSIN DD *
...<easy> source statements...
/*
//LKED EXEC PGM=IEWL
//SYSPRINT DD SYSOUT=A
//SYSLIN DD DSN=&&SYSLIN,DISP=(OLD,DELETE)
294
CA Easytrieve® Report Generator 11.6
//SYSLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
//SYSLMOD DD DISP=SHR,DSN=your.ezt.application.loadlib
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,5))
The following example illustrates the JCL to execute a previously compiled and link-edited CA Easytrieve program with
CA IDMS under central version:
//jobname JOB accounting.info
//stepname EXEC PGM=TESTPGM
//STEPLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
// DD DISP=SHR,DSN=idms.loadlib
//SYSPRINT DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,1)
//SYSCTL DD DISP=SHR,DSN=cdms.sysctl
//EZOPTBL DD DISP=SHR,DSN=your.ezt110.EZOPTBL
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//SYSIN DD * (optional CARD input)
Executing with CA IDMS Under Local Mode
The following example illustrates the JCL to compile and link-edit a CA Easytrieve program using CA IDMS under local
mode:
//jobname JOB accounting.info
//stepname EXEC PGM=EZTPA00
//STEPLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
// DD DISP=SHR,DSN=idms.loadlib
//SYSPRINT DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,1)
//SYSJRNL DD DISP=(NEW,KEEP),UNIT=TAPE,
// DSN=idms.tapejrnl
//IDMSDICT DD DISP=SHR,DSN=idms.dictdb
//idmsdb DD DISP=SHR,DSN=your.database
//EZOPTBL DD DISP=SHR,DSN=your.easytrieve.r11.EZOPTBL
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//SYSLIN DD UNIT=SYSDA,SPACE=(400,(100,50)),DISP=(,PASS),
// DSN=&&SYSLIN
//SYSIN DD *
...<easy> source statements...
/*
//LKED EXEC PGM=IEWL
//SYSPRINT DD SYSOUT=A
//SYSLIN DD DSN=&&SYSLIN,DISP=(OLD,DELETE)
//SYSLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
//SYSLMOD DD DISP=SHR,DSN=your.ezt.application.loadlib
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,5))
The following example illustrates the JCL to execute a previously compiled and link-edited CA Easytrieve program with
CA IDMS under local mode:
295
CA Easytrieve® Report Generator 11.6
//jobname JOB accounting.info
//stepname EXEC PGM=TESTPGM
//STEPLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
// DD DISP=SHR,DSN=idms.loadlib
//SYSPRINT DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,1)
//SYSJRNL DD DISP=(NEW,KEEP),UNIT=TAPE,
// DSN=idms.tapejrnl
//IDMSDICT DD DISP=SHR,DSN=idms.dictdb
//idmsdb DD DISP=SHR,DSN=your.database
//EZOPTBL DD DISP=SHR,DSN=your.easytrieve.r11.EZOPTBL
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//SYSIN DD * (optional CARD input)
Executing with the DB2 Option
The following example illustrates the JCL necessary to execute CA Easytrieve with DB2 for z/OS using dynamic SQL
mode:
/jobname JOB accounting.info,USER=userid
//*
// SET EZTLOAD='your.ezt.product.loadlib'
// SET APPLOAD='your.ezt.application.loadlib'
// SET OPTTBL='your.easytrieve.options.table'
// SET PSQLLOAD='your.pansql.loadlib'
// SET DSNLOAD='your.db2.dsnload'
//*
//* Compile the EZT application program
//COMP EXEC PGM=EZTPA00
//STEPLIB DD DISP=SHR,DSN=&EZTLOAD
// DD DISP=SHR,DSN=&PSQLLOAD
// DD DISP=SHR,DSN=&DSNLOAD
//SYSPRINT DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,1)
//EZOPTBL DD DISP=SHR,DSN=&OPTTBL
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//SYSLIN DD UNIT=SYSDA,SPACE=(400,(100,50)),DISP=(,PASS),
// DSN=&&SYSLIN
//SYSIN DD *
... <easy> DB2 source statements ...
/*
//* Link-edit the EZT application program
//LKED EXEC PGM=IEWL
//SYSPRINT DD SYSOUT=A
//SYSLIN DD DSN=&&SYSLIN,DISP=(OLD,DELETE)
//SYSLIB DD DISP=SHR,DSN=&EZTLOAD
//SYSLMOD DD DISP=SHR,DSN=&APPLOAD
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,5))
//*
//* Execute the EZT application program
296
CA Easytrieve® Report Generator 11.6
//RUN EXEC PGM=TESTPGM
//STEPLIB DD DISP=SHR,DSN=&EZTLOAD
// DD DISP=SHR,DSN=&PSQLLOAD
// DD DISP=SHR,DSN=&DSNLOAD
// DD DISP=SHR,DSN=&APPLOAD
//SYSPRINT DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,1)
//EZOPTBL DD DISP=SHR,DSN=&OPTTBL
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//SYSIN DD * (optional CARD input)
The following example illustrates the JCL necessary to execute CA Easytrieve with DB2 for z/OS using static SQL mode:
//jobname JOB accounting.info,USER=userid
//*
// SET EZTLOAD='your.ezt.product.loadlib'
// SET APPLOAD='your.ezt.application.loadlib'
// SET APPOBJ='your.ezt.application.objectlib'
// SET DBRMLIB='your.private.dbrmlib'
// SET OPTTBL='your.easytrieve.options.table'
// SET PSQLLOAD='your.pansql.loadlib'
// SET DSNLOAD='your.db2.dsnload'
//*
//* >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
//* STATIC PANSQL/EASYTRIEVE
//* >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
//*
//* Compile the EZT application program
//COMP EXEC PGM=EZTPA00
//STEPLIB DD DISP=SHR,DSN=&EZTLOAD
// DD DISP=SHR,DSN=&PSQLLOAD
// DD DISP=SHR,DSN=&DSNLOAD
//SYSPRINT DD SYSOUT=A
//SYSOUT DD SYSOUT=A
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,1)
//EZOPTBL DD DISP=SHR,DSN=&OPTTBL
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//SYSLIN DD DISP=SHR,DSN=&APPOBJ.(myeztpgmname)
//GENDATA DD DISP=(NEW,PASS),DSN=&&EZTDB2,
// DCB=(BLKSIZE=3120,LRECL=80,RECFM=FB),UNIT=SYSDA,
// SPACE=(3120,(100,50),RLSE)
//SYSIN DD *
PARM +
SSID('myssid') +
BIND STATIC-ONLY SQLSYNTAX NONE +
PLAN (myplanname) ENVIRONMENT(NONE) LINK
... <easy> DB2 source statements ...
/*
//*
//**********************************************************
//*
//* STEP B: GENERATE A COMMAND PROGRAM
297
CA Easytrieve® Report Generator 11.6
//* (PAN/SQL PRECOMPILE)
//**********************************************************
//GEN EXEC PGM=DQSCGEN,COND=(4,LT,COMP)
//GENDATA DD DISP=(OLD,DELETE),DSN=&&EZTDB2
//CMDPGM1 DD DISP=(NEW,PASS),DSN=&&CPGM1,
// UNIT=SYSDA,
// DCB=(BLKSIZE=3120,LRECL=80,RECFM=FB),
// SPACE=(TRK,(1,1))
//CMDPGM2 DD DISP=(NEW,PASS),DSN=&&CPGM2,
// UNIT=SYSDA,
// DCB=(BLKSIZE=3120,LRECL=80,RECFM=FB),
// SPACE=(TRK,(2,1))
//CMDPGM3 DD DISP=(NEW,PASS),DSN=&&CPGM3,
// UNIT=SYSDA,
// DCB=(BLKSIZE=3120,LRECL=80,RECFM=FB),
// SPACE=(TRK,(2,1))
//CMDPGM4 DD DISP=(NEW,PASS),DSN=&&CPGM4,
// UNIT=SYSDA,
// DCB=(BLKSIZE=3120,LRECL=80,RECFM=FB),
// SPACE=(TRK,(2,1))
//SYSPRINT DD SYSOUT=*
//ERRREPT DD SYSOUT=*
//**********************************************************
//*
//* STEP C: PREPROCESS THE COMMAND PROGRAM BY DB2
//* (DB2 PRECOMPILE)
//**********************************************************
//DB2PRE EXEC PGM=DSNHPC,
// COND=((4,LT,GEN),(4,LT,COMP)),
// PARM='HOST(ASM),XREF,SOURCE'
//DBRMLIB DD DISP=SHR,DSN=&DBRMLIB.(myplanname)
//SYSIN DD DISP=(OLD,DELETE),DSN=&&CPGM1
// DD DISP=(OLD,DELETE),DSN=&&CPGM2
// DD DISP=(OLD,DELETE),DSN=&&CPGM3
// DD DISP=(OLD,DELETE),DSN=&&CPGM4
//SYSCIN DD DSN=&&DB2OUT,DISP=(NEW,PASS),
// UNIT=SYSDA,DCB=BLKSIZE=3120,
// SPACE=(TRK,(3,3))
//SYSUT1 DD SPACE=(800,(1000,1000)),UNIT=SYSDA
//SYSUT2 DD SPACE=(800,(1000,1000)),UNIT=SYSDA
//SYSPRINT DD SYSOUT=*
//SYSTERM DD SYSOUT=*
//**********************************************************
//*
//* STEP D: ASSEMBLE THE COMMAND PROGRAM
//*
//**********************************************************
//ASM EXEC PGM=ASMA90,
// COND=((4,LT,DB2PRE),(4,LT,COMP)),
// PARM='OBJECT,NODECK,RENT,LIST'
//SYSIN DD DISP=(OLD,DELETE),DSN=&&DB2OUT
//SYSLIN DD DISP=SHR,DSN=RAABE01.TEST.OBJLIB(myplanname)
//SYSLIB DD DISP=(NEW,DELETE),DSN=&&SYSLIB,
298
CA Easytrieve® Report Generator 11.6
// UNIT=SYSDA,DCB=BLKSIZE=80,
// SPACE=(TRK,(1,1,1))
//SYSUT1 DD DSN=&&SYSUT1,UNIT=SYSDA,
// SPACE=(TRK,(10,5))
//SYSPUNCH DD DUMMY
//SYSPRINT DD SYSOUT=*
//**********************************************************
//*
//* STEP E: BIND AND GRANT AUTHORIZATION TO THE
//* COMMAND PROGRAM'S APPLICATION PLAN
//*
//**********************************************************
//AUTH EXEC PGM=IKJEFT01,DYNAMNBR=20
//DBRMLIB DD DISP=SHR,DSN=&DBRMLIB
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//REPORT DD SYSOUT=*
//SYSTSIN DD *
DSN SYSTEM(myssid)
BIND PACKAGE(myplanname) MEMBER(myplanname) VALIDATE(RUN) -
ACT(REPLACE) ISOLATION(CS)
BIND PLAN(myplanname) PKLIST(myplanname.*) -
ACT(REPLACE) ISOLATION(CS)
RUN PROGRAM(DSNTIAD) PLAN(DSNTIA10) -
LIB('db2.RUNLIB.LOAD')
END
/*
//SYSIN DD *
GRANT EXECUTE ON PLAN myplanname TO PUBLIC;
/*
//* Link-edit the EZT application program and DB2 plan
//LKEDEZT EXEC PGM=IEWL,COND=(0,NE,COMP),PARM=(LIST,XREF,REUS)
//SYSPRINT DD SYSOUT=*
//MYOBJ DD DISP=SHR,DSN=&APPOBJ
//SYSLIN DD *
INCLUDE MYOBJ(myeztpgmname)
INCLUDE MYOBJ(myplanname)
NAME totalpgmname(R)
//SYSLMOD DD DISP=SHR,DSN=&APPLOAD
//SYSLIB DD DISP=SHR,DSN=CEE.SCEELKED
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,5))
//*
//* Execute the EZT DB2 application program
//RUN EXEC PGM=totalpgmname,REGION=1024K,COND=(4,LE,LKEDEZT)
//STEPLIB DD DISP=SHR,DSN=&EZTLOAD
// DD DISP=SHR,DSN=&PSQLLOAD
// DD DISP=SHR,DSN=&DSNLOAD
// DD DISP=SHR,DSN=&APPLOAD
//* The following DD allows you to specify SSID and PLAN.
//PAN$SQL DD *
PLAN=myplanname,SSID=myssid
//SYSPRINT DD SYSOUT=A
299
CA Easytrieve® Report Generator 11.6
//SYSOUT DD SYSOUT=A
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,1)
//EZOPTBL DD DISP=SHR,DSN=&OPTTBL
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//
Mixed IMS and DB2 for OS/390 and z/OS Execution
If your CA Easytrieve program accesses an IMS database and DB2 for z/OS database, you should run your program
under the control of DB2-DL/I BATCH SUPPORT.
This ensures synchronization of checkpoints and rollbacks across both IMS and DB2 for z/OS.
Under this control, SQL COMMITs and SQL ROLLBACKs are not permitted.
To do this, change your execution JCL to execute Module DSNMTV01 instead of EZTPA00 or your linked application
program. DSNMTV01 then loads the real program.
The following is sample JCL:
//EZIMSDB2 EXEC PGM=DFSRRC00,
// PARM='DLI,DSNMTV01,PSBNAME,,,,,,,,,,O,N,N,'
//STEPLIB DD DSN=IMSVS.RESLIB,DISP=SHR
// DD DSN=IMSVS.PGMLIB,DISP=SHR
// DD DSN=your.ibm.db2.sspgm.library,DISP=SHR
// DD DSN=your.eztp.loadlib,DISP=SHR
// DD DSN=your.pansql.loadlib,DISP=SHR
//IMS DD DSN=IMSVS.PSBLIB,DISP=SHR
// DD DSN=IMSVS.DRDLIB,DISP=SHR
//SYSOUT DD SYSOUT=*
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//DDOTV02 DD DSN=&&TEMP,DISP=(NEW,PASS),SPACE=(TRK,(5,5),
UNIT=SYSDA,DCB=(RECFM=VB,LRECL=4092,BLKSIZE=4096)
//DDITV02 DD *
SSN,LIT,ESMT,RTT,ERR,CRC,CONNECTION_NAME,PLAN,PROG
/*
//SYSIN DD *
... <easy> statements ...
.
.
.
/*
//
NOTE
Under the control of DB2 for z/OS or DLI batch support, your STEPLIB must define the IMS RESLIB before the
DB2 for z/OS library.
The DDITV02 DD defines the following parameters:
Parameter Description
SSN DB2 for z/OS subsystem
LIT Language Interface token value
300
CA Easytrieve® Report Generator 11.6
ESMT Initialization module name, must be DSNMIN10
RTT Resource Translation Table
ERR Region Error Option
CRC Command Recognition Character
CONNECTION_NAME A unique one-to eight-character name
PLAN DB2 for z/OS plan name
PROG Application program name to execute -- either EZTPA00 or linked
program name.
Refer to your IBM DB2 guides for a detailed explanation of these parameters.
Compilation Condition Codes
Compilation of a CA Easytrieve program will end with one of these condition codes:
• 00
Identifies successful compilation with no errors or warnings.
• 04
Identifies successful compilation with warning messages.
• 16
Identifies failed compilation due to severe errors.
If warnings occur in a Compile-and-Go run, the 04 compilation condition code is not retained, and the final condition code
will be from the “Go” part of the Compile-and-Go.
Compilation warning messages may or may not result in an execution-time failure. Each warning message should be
reviewed in order to determine if there may be an execution-time affect.
Submitting Your Program for Non-Mainframe Compilation
To submit your program for compilation on a non-mainframe platform, perform the following steps:
1. Enable access to system files.
2. Execute the EZT command with the appropriate compiler execution parameters.
System File Access
Before compiling your program, you must have access to the CA Easytrieve system files by using the PATH, EZTPATH,
and SHLIB_PATH environment variables (where appropriate). You must specify the directory where CA Easytrieve is
installed for each user with the PATH, EZTPATH, and SHLIB_PATH environment variables.
If you are operating within the CA Easytrieve Workbench, access to the system files is automatically controlled and
therefore adding the installation directory to the PATH variable is not required.
UNIX/Linux for zSeries only: If your program uses SQL, you must set the EZTSQL environment variable. See your
system administrator (or the person who installed the product) for the correct values.
See Setting Environment Variables for information about environment variables.
Execute the EZT Command with Compiler Execution Parameters
The EZT command compiles your CA Easytrieve program and prepares it for execution. The EZT command specifies
compiler execution parameters for controlling the compilation of your CA Easytrieve program. You use these parameters
to specify:
301
CA Easytrieve® Report Generator 11.6
• Name of the source program you want to compile
• Whether to produce a compilation listing
• Name of the resulting executable file and other linker options
• Directories the compiler is to search for macro files
You can specify any number of parameters to the compiler. Only one source file name is required. All other parameters
are optional.
Syntax
ezt [options] source-files
Valid options are:
-c
-I macro-directory
-l system-library-name
+L
-L
-n
-N
-o executable-file-name
+OC
+OS
-P
-q
-Q
-s
-S
-v
-w
-W x,arg1[,arg2...]
-x
-z
-Z
source-files
The ezt command accepts CA Easytrieve source files and linker (ld) source files on the command line. You can specify
both types of source files with a full path specification (for example, /ezt/usr/user1/browse.ezt). The resulting files are
always placed in the current directory.
NOTE
In Windows, only source files are accepted.
CA Easytrieve Source Files
All CA Easytrieve source files must have the .ezt extension. Files whose names end with the file extension .ezt are
assumed to be CA Easytrieve source files. You can specify any number of CA Easytrieve files on the command line.
In UNIX, Linux/PC and Linux for zSeries, each source file is compiled with the CA Easytrieve compiler and an executable
(.out), Assembler (.s), or object (.o) file (see -c, -P, and -S options below) is created. If you specify only one CA Easytrieve
file on the command line and do not specify a -c, -P, or -S option, the intermediate object file is deleted.
302
CA Easytrieve® Report Generator 11.6
In Windows, each source file is compiled with the CA Easytrieve compiler and a P Code (.pco) file is created. The - c and -
S options are ignored.
Linker Input Files (UNIX, Linux/PC and Linux for zSeries only)
CA Easytrieve assumes all other types of files are linker input files. These types of files include object (.o) and library (.a)
files. These files are passed to the linker program (ld) along with object files CA Easytrieve compilations created.
Options
This section provides more information about the EZT command options:
• Compile Only Parameter (-c) (UNIX, Linux/PC and Linux for zSeries only)
The compile only parameter (-c) tells the EZT command to stop before the link edit phase. Object files for each
successfully compiled source program are left in the current directory. These object files must be link-edited before
execution.
• Macro Search Directory Parameter (-I macro-directory)
The macro search directory parameter (-I macro-directory) specifies a single directory where the EZT command
searches for macro source files. You can specify this parameter multiple times, each with a different search path. CA
Easytrieve always searches the directory of the source file before any directories specified with this parameter.
For each macro invocation statement in your CA Easytrieve program, ezt looks for a macro in a file named macro-
name.mac in each of the specified directories, where macro-name is the name of the macro on the macro invocation
statement.
For example, if you specify the following, ezt searches the directories /usr/usr1/source, /usr/usr1/macros, and /ezt/
macros for each macro file:
ezt -I /usr/usr1/macros -I /ezt/macros /usr/usr1/source/browse.ezt
• Linker System Library Parameter (-l system-library-name) (UNIX, Linux/PC and Linux for zSeries only)
The linker system library parameter (-l system-library-name) specifies a system library for the system linker (ld)
command to search for unresolved references. The -l parameter is passed directly to the ld command. The EZT
command automatically supplies the system libraries that are required for the CA Easytrieve runtime environment.
• Generate a Compiler Listing to Standard Output Parameter (-L)
The generate compiler listing parameter (-L) causes the compiler to generate a listing to the standard output device.
You can use the standard UNIX redirection symbols (>, >>, and so forth) to redirect the listing to a file. The default is
not to produce a listing.
• Generate a Compiler Listing to a File Parameter (+L)
The generate compiler listing parameter (+L) causes the compiler to generate a listing for each CA Easytrieve
source file to a separate listing file. The listing file name is created from the base name of the source file with an
added extension of .lst. For example, for the source file /usr/usr1/browse.ezt, the +L option generates a listing file in
browse.lst in the current directory. The default is not to produce a listing.
• Linker Generate Shared Output Parameter (-n) (UNIX, Linux/PC and Linux for zSeries only)
The linker generate shared output parameter (-n) marks the output from the linker (ld) as sharable. This parameter is
passed directly to ld.
• Linker Generate Unshared Output Parameter (-N) (UNIX, Linux/PC and Linux for zSeries only)
The linker generate unshared output parameter (-N) marks the output from the linker (ld) as unsharable. This
parameter is passed directly to ld.
• Specify Executable Name Parameter (-o executable-file-name) (UNIX, Linux/PC and Linux for zSeries only)
The specify executable name parameter (-o executable-file-name) names the executable file that is created by the
linker. The default is a.out.
• Omit C-ISAM Parameter (+OC) (UNIX, Linux/PC and Linux for zSeries only)
303
CA Easytrieve® Report Generator 11.6
The omit C-ISAM parameter (+OC) causes the EZT command to omit the C ISAM libraries from the default system
libraries that are specified to the linker. If you have the C-ISAM libraries directory in EZTPATH but you are not
accessing C-ISAM with your CA Easytrieve program, specify this parameter to reduce the size of your executable file.
• Omit SQL Parameter (+OS) (UNIX, Linux/PC and Linux for zSeries only)
The omit SQL parameter (+OS) causes the EZT command to omit the SQL libraries from the default system libraries
that are specified to the linker. If you have the EZTSQL variable set but you are not accessing SQL with your CA
Easytrieve program, specify this parameter to reduce the size of your executable file.
• Generate P-Code File Only Parameter (-P)
The generate P-Code file only parameter (-P) causes the EZT command to produce a P-Code file for each CA
Easytrieve source file that is specified on the command line. The P-Code file name is created from the base name of
the source file with an added extension of .pco. For example, for the source file /usr/usr1/browse.ezt, the -P parameter
generates a P-Code file in browse.pco in the current directory.
• Linker Generate Demand Loadable Executable Parameter (-q) (UNIX, Linux/PC and Linux for zSeries only)
The linker generate demand loadable executable parameter (-q) marks the output from the linker (ld) as demand
loadable. This parameter is passed directly to ld.
• Linker Generate Nondemand Loadable Executable Parameter (-Q) (UNIX, Linux/PC and Linux for zSeries only)
The linker generate nondemand loadable executable parameter ( Q) marks the output from the linker (ld) as not
demand loadable. This parameter is passed directly to ld.
• Linker Strip Executable Parameter (-s) (UNIX, Linux/PC and Linux for zSeries only)
The linker strip executable parameter (-s) strips the output of the linker of its symbol table information. This reduces the
size of the resulting executable file. This parameter is passed directly to ld.
• Generate Assembler File Only Parameter (-S) (UNIX, Linux/PC and Linux for zSeries only)
The generate Assembler file only parameter (-S) causes the EZT command to produce an Assembler file for each
CA Easytrieve source specified on the command line. The Assembler file name is created from the base name of the
source file with an added extension of .s. For example, for the source file /usr/usr1/browse.ezt, the -S option generates
an Assembler file in browse.s in the current directory.
The Assembler file contains code to call the CA Easytrieve interpreter with an imbedded copy of the P-Code. It must
be assembled and link-edited with the CA Easytrieve runtime environment to produce an executable program.
• Verbose Parameter(-v)
The verbose parameter (-v) displays the name of each process (compilation, Assembler generation, assembly, and
linkage editor) as it is invoked along with the command line options that are passed to that process. The verbose
parameter displays this information to the standard-error device.
• Suppress Warning Messages Parameter (-w)
The suppress warning messages parameter (-w) suppresses the display of warning messages to the standard-error
device during compilation. Warning messages are always generated in the listing file (if requested). The default is to
display warning messages along with error messages on standard-error.
• Pass Arguments to Process Parameter (-W x,arg1[,arg2...])
The pass arguments to process parameter (-W x,arg1[,arg2...]) passes options directly to a process invoked by the
EZT command.
Valid values for x are:
– c
CA Easytrieve compiler.
– g (UNIX, Linux/PC and Linux for zSeries only)
CA Easytrieve Assembler generator.
– a (UNIX, Linux/PC and Linux for zSeries only)
Assembler (as).
– l (UNIX, Linux/PC and Linux for zSeries only)
Linker (ld).
Note: Some ezt parameters can specify the above linker parameters in a more efficient way. For example, you can
specify W l, N as -N.
• Syntax Check Only Parameter (-x)
304
CA Easytrieve® Report Generator 11.6
The syntax check only parameter (-x) tells ezt to only check CA Easytrieve programs for syntax and semantic errors.
No output files (other than the optional listing file) are generated.
• Linker Runtime Null Pointer Check Parameter (-z) (UNIX, Linux/PC and Linux for zSeries only)
The linker runtime null pointer check parameter (-z) enables the linker to check for references to location zero in
storage. You can specify this parameter to enable null pointer checking in any c programs that are linked in with your
CA Easytrieve program (including the CA Easytrieve runtime program). This parameter is passed directly to ld.
• Linker Runtime Disable Null Pointer Check (-Z) (UNIX, Linux/PC and Linux for zSeries only)
The linker runtime disable null pointer check parameter (-Z) allows the linker to reference location zero in storage. You
can specify this parameter to allow null pointer references in any c programs that are linked with your CA Easytrieve
program. This parameter is passed directly to ld.
Specifying Multiple Parameters
You can specify any number of parameters anywhere on the EZT command line. Parameters from the command line are
read before any of the source files are processed. Command line parameters can be concatenated after a single "-" or "+."
However, a command line parameter that takes an argument must appear last in the concatenated list.
For example, the following commands are all equivalent:
ezt -v -n hello.ezt -x -w +L -o hello
ezt -vnxwo hello +L hello.ezt
ezt -xwv hello.ezt +L -no hello
Command line parameters specifying part of a search path (for example, -I or -l) are processed so they are read on the
command line.
Link-Editing Non-Mainframe Programs
When you compile your CA Easytrieve Report Generator program for execution as a stand-alone executable program, it is
automatically link-edited by the EZT command. This section explains how to link-edit the following types of programs:
• Previously-compiled CA Easytrieve Report Generator programs
• Programs that access:
– Ingres
– Oracle
– C-ISAM
– DB2
– ODBC
• CA Easytrieve Report Generator programs with external subroutines
This article includes the following information:
NOTE
Examples in the following sections do not show syntax or conventions specific to every non-mainframe operating
system or environment. For information about the syntax and convention specific to your operating environment,
see your operating environment manuals.
Link-Editing Previously-Compiled Programs in UNIX, Linux for zSeries, or Linux PC
If you previously compiled CA Easytrieve Report Generator programs using the -c parameter on the EZT command to
produce an object module, you can link edit the programs in a separate step. Use the EZT command to invoke the linkage
editor (ld) because it supplies the necessary command-line parameters.
305
CA Easytrieve® Report Generator 11.6
For example, if you previously compiled the program browse.ezt with the following command:
ezt -c browse.ezt
You can link edit the program by typing the following command:
ezt -o browse browse.o
Because you specified only an object file on the EZT command line, ezt skips the compile and proceeds to the link-edit
phase. The resulting executable file is named browse.
NOTE
• This option is enabled only if Visual Studio or .NET is detected on the development computer.
• The following warning can occur when you link a CA Easytrieve Report Generator program in a 64-bit Linux for zSeries
or Linux PC environment:
warning: xxxx architecture of input file `program.o' is incompatible with yyyy output
If you receive this warning, you can add a switch to your EZTOPTS environment variable that forces the assembler to
create a 32-bit .o file.
For a Linux PC environment, add the following switch:
-W a,--32
For a Linux for zSeries environment, add the following switch:
-W a,-m31
Archive and Shared Libraries
For most system libraries, CA Easytrieve Report Generator provides both archive and shared libraries. You can link
your program with either set of libraries. Applications that are linked with archive libraries contain all library routines in
the executable and are, therefore, self-contained. They can, however, be large. Because they are self-contained, they
are more portable and cannot be affected by changes in the shared libraries. This offers safety in that the applications
continue to run without re-linking.
Applications that are linked with shared libraries link to library routines at runtime, and therefore are much smaller. But, the
shared libraries must be available at runtime. Changes in shared libraries can affect all executables that are linked with
them.
NOTE
A shared library's full path name is stored in the executable unless you use the +s linker option. The +s option
causes the operating system to use the path list defined in the SHLIB_PATH environment variable.
By default, the HP-UX linker uses shared libraries ahead of archive libraries when both exist. You can force use of archive
libraries by using the compilation parameter, -Wl,-aarchive, or removing the shared libraries from the directory.
Add the following command to the EZT command line to ensure shared object lib usage in AIX:
-Wl,-brtl
This uses the AIX ld option -brtl while linking to ensure usage of the shared object. Without this option, all applications
become statically linked executables.
See your operating environment manuals for more details.
Link-Editing with Other Systems
If your CA Easytrieve Report Generator program accesses Ingres, Oracle, C-ISAM, DB2, or ODBC, link-edit the program
with the libraries for those products.
306
CA Easytrieve® Report Generator 11.6
NOTE
If you are running CA Easytrieve Report Generator in a Linux PC environment, you cannot link-edit the program
to Ingres, Oracle, or DB2. You can link-edit to C-ISAM and ODBC. See the commented lines in the eztprofile that
is provided with the program.
The UNIX ODBC interface has been tested using the unixODBC freeware product, which can be downloaded from
www.unixODBC.org. Consult your database documentation for the proper CONNECT string to code in CA Easytrieve
Report Generator. Each database purveyor has different rules when connecting using ODBC.
You can specify the +OS parameter for Ingres, Oracle, DB2, and ODBC, or the +OC parameter for C-ISAM. If you do not,
the EZT command automatically supplies the necessary commands to the linker (ld) to access the library directories for
those products. However, you must add the library directories to your EZTPATH environment variable. Also add the library
names to your EZTLIBS environment variable to access the correct libraries.
NOTE
For Ingres, Oracle, DB2, and ODBC, you can alternately include an -L directive to EZTLIBS to direct the linker to
the correct library directory.
To verify correct library specification, consult your Ingres, Oracle, C-ISAM, DB2, or ODBC documentation. CA Easytrieve
Report Generator provides an -L linker parameter specifying the Ingres, Oracle, C-ISAM, DB2, or ODBC directory
specified in EZTPATH. However, each user must supply the correct library names in EZTLIBS, as illustrated in the
following examples.
WARNING
Because CA Easytrieve Report Generator is a 32-bit product, ensure that the environment is pointing to the 32-
bit versions of the libraries.
NOTE
For an Oracle database, review the libraries that the proc.mk make file uses. These libraries are located in
$ORACLE_HOME/proc/demo.
• For Ingres, specify:
-lingres
• For Oracle, specify:
-lclntsh
• For DB2, specify:
-ldb2
• For ODBC, specify:
-lodbc
• For C-ISAM, specify:
-lisam
A standard Informix C-ISAM library is required. You cannot link with the modified C-ISAM library that is distributed with
COBOL.
NOTE
If the database cannot be found, the EZT command processes as if you specified +OS (for Ingres, Oracle, DB2,
and ODBC) or +OC (for C-ISAM).
Link-Editing Programs with Called Subroutines
You can call subroutines that are written in other languages using the CALL statement or the EXIT parameter of the FILE
statement. You can link-edit called subroutines as follows:
• Statically link-edited with your program (STATIC)
• Dynamically loaded (DYNAMIC)
307
CA Easytrieve® Report Generator 11.6
The default in Windows is DYNAMIC. The default on UNIX platforms is STATIC. You can override this default with the
DECLARE statement or the CALL parameter of the PARM statement. See the Programming section for more information.
Link-Editing with STATIC Subroutines
To link-edit STATIC subroutines with your program, you must compile the subroutine with the correct compiler to produce
an object module. When you compile your program, specify the object module on the EZT command line.
For example, if your program is named browse.ezt and it calls a subroutine named sqrt that is written in C, you must
perform the following steps:
1. Use the following command to compile the C program to produce an object file:
cc -c sqrt.c
2. Use the following command to compile and link-edit your program with the sqrt program:
ezt -o browse browse.ezt sqrt.o
Link-Editing with DYNAMIC Suboutines (UNIX and Linux for zSeries)
To call DYNAMIC subroutines from your program, you must first create one or more shared libraries that contain the
subroutines you want to call.
For example, if your program is named browse.ezt and it calls a subroutine named sqrt that is written in C, you must
perform the following steps:
1. Use the following command to compile the C program to produce an object file suitable for inclusion in a shared
library:
cc -c +z sqrt.c
2. Use the following command to link-edit the sqrt program to produce a shared library:
ld -b -o sqrt sqrt.o
3. Use the following command to compile and link-edit your program:
ezt -o browse browse.ezt
At execution time, the browse program loads the sqrt program during the initialization of the activity that contains the
CALL statement. CA Easytrieve® Report Generator searches for the file using the PATH environment variable in the same
way that the shell searches for executable files. Your PATH environment variable must contain the directory where sqrt
resides.
Generally, if your program contains the following statements:
DECLARE program-name PROGRAM DYNAMIC
...
CALL program-name USING parameters
...
You must then create a shared library containing the program using the following commands:
cc -c +z file-name.c
ld -b -o program-name ... file-name.o...
where file-name.c defines a function called program-name as:
...
int program-name( parameters )
{
...
}
...
308
CA Easytrieve® Report Generator 11.6
You can also link-edit more than one subroutine into a single shared library. You must give the shared library the name of
one of the subroutines on the ld command and then create additional links for the other subroutines.
For example, if you have subroutines cos, sin, and tan, you must follow these steps to create a single shared library
named cos that contains all three subroutines:
1. Use the following command to compile all subroutines to produce object files:
cc -c +z cos.c sin.c tan.c
2. Use the following command to link-edit the shared library:
ld -b -o cos cos.o sin.o tan.o
3. Use the following command to define additional links for the other subroutines:
ln cos sin
ln cos tan
Linking DYNAMIC Subroutines (Windows)
To call DYNAMIC subroutines from your program, you must create one or more dynamic load libraries (DLLs) that contain
the subroutines you want to call.
For example, if your program is named browse.ezt and it calls a subroutine named sqrt that is written in C, you must
perform the following steps:
1. Use the following command to compile the C program to produce an object file suitable for inclusion in a DLL:
cl -c sqrt.c
2. Use the following command to link-edit the sqrt program to produce a DLL:
link /dll /out:sqrt.dll sqrt.obj
At execution time, the interpretation of the browse program loads the sqrt program during the initialization of the activity
that contains the CALL statement. CA Easytrieve Report Generator searches for the file using the current directory and
the PATH environment variable in the same way that the command interpreter searches for executable files. Your PATH
environment variable must contain the directory where sqrt.dll resides if it is not in the current work directory.
Generally, if your program contains the following statements:
DECLARE program-name PROGRAM DYNAMIC
...
CALL program-name USING parameters
...
You must then create a DLL containing the program using the following commands:
cl -c file-name.c
link /dll /out:program-name.dll file-name.obj
where file-name.c defines a function called program-name as:
...
int program-name( parameters )
{
...
}
...
You can also link-edit more than one subroutine into a single DLL. You must then provide the name of the DLL in the
EZTDLLS environment variable to ensure that they are loaded correctly.
See the Workbench Utilities section and the Workbench Tools and Utilities section for more information.
309
CA Easytrieve® Report Generator 11.6
For example, if you have subroutines cos, sin, and tan, you must follow these steps to create a single DLL named
funcs.dll that contains all three subroutines:
1. Use the following command to compile all subroutines to produce object files:
cl -c cos.c sin.c tan.c
2. Use the following command to link-edit the DLL:
link /dll /out:funcs.dll cos.obj sin.obj tan.obj
Submitting Your Program for Non-Mainframe Compilation
Execute a Program
This section describes how to execute a CA Easytrieve program in:
• UNIX or Linux for zSeries using an executable file and the services that are supplied by the operating environment
• Windows using the interpreter (ezterp) and the compiler-generated P Code file and optionally creating executable files
• z/OS using JCL to execute your link-edited program
The Error Analysis report that you can use to debug an abnormal termination (ABEND) of your program is also described.
Execute a Program in UNIX and Linux for zSeries
This article describes how to execute your program in UNIX and Linux for zSeries with an executable file, and using
parameters.
Contents
Executing an Executable File
By default, the EZT command produces an executable file with the name of a.out. You can override the default name with
the -o parameter.
The syntax for executing the executable file follows:
[path]file-name [parameter]
If your path includes the directory where file-name resides, path is not required. You can specify a parameter to pass if
allowed by your program.
Executing Your Program Using Parameters
You can specify a parameter to pass using statements similar to the following:
DEFINE PARM-FIELD S 16 A
PROGRAM NAME MY-PROGRAM USING PARM-FIELD
The PARM-FIELD field contains the data that you entered on the command line or specified in the LINK or TRANSFER
statement. For portability with CA Easytrieve® Report Generator in other operating environments, the data is placed in the
USING field as is. This means that CA Easytrieve® Report Generator attempts to pass the command line just as the UNIX
shell received it before translation.
For example, if double quotation marks prevent spaces from being translated in the shell, double quotation marks are
placed back into the data in the USING field to recreate the data. It is up to your program to account for the double
quotation marks in your data.
310
CA Easytrieve® Report Generator 11.6
Temporary Files
Virtual (VFM) files and sort work files are written as temporary files. Your operating system directs temporary files to a
default location (typically, /tmp). You can redirect sort work files by setting the TMPDIR environment variable.
Execute a Program in Windows
This article describes how to execute your program in Windows and using parameters.
Contents
Executing a P-Code File
The EZT command produces a P-Code file with the name of program.PCO (where program is the file name of your source
program. For more information, see Compile and Link Your Program.
Use the following syntax to execute the P-Code file:
[path]ezterp pcode-file-name [parameter]
If your path includes the directory where ezterp resides, path is not required. You can specify a parameter to pass if
allowed by your program.
Executing Your Program Using Parameters
You can specify a parameter to pass using statements similar to the following:
DEFINE PARM-FIELD S 16 A
PROGRAM NAME MY-PROGRAM USING PARM-FIELD
The PARM-FIELD field contains the data that you entered on the command line or specified in the LINK or TRANSFER
statement. For portability with CA Easytrieve® Report Generator in other operating environments, the data is placed in the
USING field as is. This means that CA Easytrieve® Report Generator attempts to pass the command line as the command
interpreter received it before translation.
For example, if double quotation marks prevent spaces from being translated in the command interpreter, double
quotation marks are placed back into the data in the USING field to recreate the data. It is up to your program to account
for the double quotation marks in your data.
Temporary Files
Virtual (VFM) files and sort work files are written as temporary files. Your operating system directs temporary files to a
default location. You can redirect sort work files by setting the TMP environment variable.
Execute a Program in z/OS
This article describes how to execute your program in z/OS with a link-edited program, and using parameters.
Contents
Executing a Link-Edited Program
Use the following JCL as an example of how to execute your progam:
311
CA Easytrieve® Report Generator 11.6
//RUN EXEC PGM=HELLO
//STEPLIB DD DISP=SHR,DSN=your.ezt.loadlib
// DD DISP=SHR,DSN=your.loadlib
//EZOPTBL DD DISP=SHR,DSN=your.options.table
//SYSPRINT DD SYSOUT=*
//SYSSNAP DD SYSOUT=*
//PERSNL DD DISP=SHR,DSN=your.data.file
//
Executing Your Program Using Parameters
You can specify a parameter to pass using statements similar to the following:
DEFINE PARM-FIELD S 16 A
PROGRAM NAME MY-PROGRAM USING PARM-FIELD
The PARM-FIELD field contains the data that you entered on the command line or specified in the LINK or TRANSFER
statement or specified in the JCL (that is, // EXEC PGM=PROG,PARM='data value'). For portability with CA Easytrieve®
Report Generator in other operating environments, the data is placed in the USING field as is. This means that CA
Easytrieve® Report Generator attempts to pass the command line just as it received it before translation.
Temporary Files
Virtual (VFM) files and sort work files are written to the EZTVFM data set when required.
File Description String (Non-Mainframe Only)
The file description string supplies the drive, path, and format information for a non-SQL file, enabling CA Easytrieve
Report Generator to locate and recognize the file. You can supply the file description string using either of the following
methods:
• Use an environment variable of the same name as the file-identifier on the FILE statement used in the program
• Set the string directly or indirectly on the FILE statement SYSNAME parameter
This article includes the following information:
Setting the String with an Environment Variable
You can set the file description string using an environment variable with the same name used in the FILE statement. For
example, to reference a program containing this FILE statement:
FILE EMPLOYEE F(88) INDEXED
Bourne and KORN shell users can specify:
EMPLOYEE=file-description-string
export EMPLOYEE
C shell users can specify:
setenv EMPLOYEE file-description-string
Windows users can specify:
set EMPLOYEE=file-description-string
For more information about how to set the variable, see Workbench Utilities.
312
CA Easytrieve® Report Generator 11.6
Setting the String on the SYSNAME Parameter
You can set the file description string directly or indirectly in the SYSNAME parameter on the FILE statement. For
example:
FILE EMPLOYEE F(88) INDEXED SYSNAME 'file-descriptor-string'
NOTE
You can also set SYSNAME dynamically by using a field-name. For more information, see the Language
Reference section.
Format
The file description string format follows:
file-specifier [ [file-descriptor] ]
Where:
• file-specifier
Specifies the path required to locate the file. It can include the drive, directories, and file name. For example:
c/data/persnl.dat
• file-descriptor
Specifies the information that, optionally, describes the format type, access method of the file, and access method-
dependent information. You must enclose the file-descriptor in brackets. Separate multiple parameters by colons.
A file-descriptor can be used for FILE statements in case of sequential files that do not contain record format and
record length parameters. These are valid on the mainframe because the operating system supplies the information
when the file is opened. In non-mainframe environments, you can specify this information through a file-descriptor. The
following example demonstrates the usage:
A program on the mainframe was executed by JCL that used a DDNAME of PERSNL and DCB attributes, which
include a DSORG of FB, a record length of 150 bytes, and a block size of 3000. Given the file was ported and exists
within Windows as “persnl.dat” and is located in the “Test” subdirectory, the file-specifier and file-descriptor can be
coded with the following command:
Set PERSNL=c:\test\persnl.dat[F:L150]
Where F represents the record format of the file (use either F or V since “blocking” is not supported within Windows)
and ‘L150’ represents the logical record length of the file.
The other valid format-descriptors are for INDEXED files:
File Format Format Type Access Method Parameter
Indexed (Windows only) X
Installable C-ISAM Indexed File System Z CISAM
(UNIX and Linux for zSeries only)
Installable Btrieve Indexed File System Z EXIT(CARFSWBT)
(Windows only)
Execute a Windows Indexed File Program
In Windows, CA Easytrieve® Report Generator uses an internal Indexed File Access method.
Contents
313
CA Easytrieve® Report Generator 11.6
File Descriptor
For CA Easytrieve® Report Generator to recognize the file format of an INDEXED file, you must supply a file descriptor.
The file descriptor provides the X format that CA Easytrieve® Report Generator requires to determine which type of file
you are processing.
The following example shows an entire file description string:
C:\data\persnl[X]
Optional Sub-parameters
For an INDEXED file, the form of the file descriptor is as follows. If X is present, it must be the first item in the descriptor;
the other items can be in any order.
[X:B nn:D nn:I nn]
where:
• X
Specifies a CA Easytrieve® Report Generator INDEXED file. An INDEXED file must have one primary key and from
zero to 62 alternate keys contained in a record. The beginning offset of each key in a record must be different. For
any primary key value, only one record can occur in the file. More than one record can have the same value for an
alternate key, if the WITH DUPLICATES phrase is included in the ALTERNATE RECORD KEY phrase in the SELECT
for the file.
• Bnn
Specifies the index block size in kilobytes (1 kilobyte equals 1024 bytes). In general, this value should not exceed the
operating system unit of transfer; that is, FAT/cluster size. The default value for B is 4 (4 kilobytes).
• Inn
Controls the number of index blocks held in memory. If this parameter is not specified, the number of index buffers is
computed by using the following formula:
(512 / B) + nKeys * 16
where:
B
Specifies the index buffer size in kilobytes (as specified by the B parameter described previously).
• nKeys
Specifies the number of keys in the file.
For example, specify the following to indicate that the file has one primary and two alternate keys.:
B = 4
I = (512 / 4) + 3 * 16
I = 128 + 48
I = 176
This means that the memory usage for the index buffers for the file will be:
4K * 176 blocks or 704K
This is a fairly aggressive use of memory. You may want to reduce this usage if your program has many index files.
The I parameter has the most profound effect on indexed file I/O performance when alternate indexes are defined. This
is illustrated by the following table:
Settings Load Time Update Time
B4:I2 40.0 14.3
B4:I16 39.1 14.0
B4:I64 22.0 12.2
B4:I128 13.1 10.8
314
CA Easytrieve® Report Generator 11.6
These results should be used for comparison only. You must experiment to find the optimum value that meets
your performance and memory constraints. In general, you should use as much memory as you can afford without
burdening the virtual memory system of the operating system that you are using. The value you specify for I should be
greater than or equal to 2. If you specify a value of 1, I is set to 2.
• Dnn
This parameter controls the number of data blocks held in memory. In most cases, this parameter has a marginal
effect. In special cases, it can improve performance based on your hardware and file utilization requirements. You will
have to experiment to find the optimum value for D.
The default for this parameter is 2.
The block-length parameter is always ignored for INDEXED files because buffers for INDEXED file processing are
always allocated dynamically. The record-length parameter determines the maximum record length for the file, and
also whether the records are fixed- or variable-length. If an existing file is opened, the maximum record length must
match the length supplied when the file is created, and the position and lengths of the primary key and all alternate
keys must also match.
No special utility is required to create an INDEXED file. However, if you need an empty INDEXED file, you can create
one using a simple program such as:
FILE IPERSNL INDEXED F(150) SYSNAME 'JPERSNL[X]' CREATE KEY EMPNO
EMPNO 9 5 N
JOB INPUT NULL
STOP
PUT IPERSNL
Execute a Btrieve Program
In Windows, CA Easytrieve® Report Generator supports the Btrieve file system as an installable file system [Z]. You must
have access to the Btrieve product from Pervasive Software, Inc.
Contents
File Descriptor
For CA Easytrieve® Report Generator to recognize the file format of a Btrieve INDEXED file, you must supply a file
descriptor. The file descriptor provides the Z format that CA Easytrieve® Report Generator requires to determine which
type of file you are processing.
The following example shows an entire file description string:
C:\data\persnl[Z:EXIT(CARFSWBT):V:Pnnnn:Mnn:Ann:O'owner']
Optional Sub-parameters
For a Btrieve INDEXED file, the form of the file descriptor is as follows. If Z:EXIT(CARFSWBT) is present, it must be the
first item in the descriptor; the other items can be in any order.
• :Vnnnn
Specify V if the file is variable length. Specify the maximum record size if necessary.
• :Pnnnn
Specify the file page size. This parameter is optional. If not specified, the best file page size for the file will be
automatically set. If specified, this parameter must be a multiple of 512 between 512 and 4096. See your BTRIEVE
documentation for more information.
• :M[-]nn
315
CA Easytrieve® Report Generator 11.6
Specify the file open mode. This parameter is optional. If it is not set, the file will be opened in normal mode except
when opened for output, in which case the file will be opened in accelerated mode to provide faster file loading.
Following are the possible values of the file open mode (note that unless the value is zero, this is a negative number):
– 0
Indicates that the file open mode is normal.
– -1
Indicates that the file open mode is accelerated.
– -2
Indicates that the file open mode is read-only.
– -3
Indicates that the file open mode is verify.
– -4
Indicates that the file open mode is exclusive.
• :Ann
Specify the file access mode. This parameter has effect only when the file is being created and an owner (below) has
been specified for the file. If the access mode is not specified, the default access mode is 0.
The following table lists the possible values of the file access mode:
– 0
Requires owner name for any access; no data encryption
– 1
Permits read-only access without an owner name; no data encryption
– 3
Requires an owner name for any access; data is encrypted
– 4
Permits Read-only access without an owner name; data is encrypted
• O'owner' or O”owner”
Specify the file owner. This parameter specifies a password for access to the file as specified by the access mode.
BTRIEVE File Status Codes
The BTRIEVE installable file system automatically maps underlying BTRIEVE error codes to CA Easytrieve® Report
Generator file status values provided that the error can be mapped to a meaningful file status value. In the cases where
the BTRIEVE error code cannot be mapped, a file status value of 9Z (installable file system error) is returned. If you do
not specify the FILE STATUS phrase on the I/O statement in your program, the program is terminated with an appropriate
error message.
Execute a C-ISAM Program
In UNIX and Linux for zSeries, CA Easytrieve® Report Generator supports the C-ISAM file system as an installable file
system [Z]. CA Easytrieve® Report Generator uses the standard C-ISAM libraries. You must have access to the C-ISAM
product from IBM Inc. If your C-ISAM file was created using the modified version COBOL supplies, review the list of
differences between standard and modified C-ISAM in the COBOL System Reference.
CA Easytrieve® Report Generator supports C-ISAM file access for files sizes greater than 2 GB. CA Easytrieve® Report
Generator uses C-ISAM release 7.2.6 and requires access to the libisam.a C-ISAM library. Make the libisam.a library
available to CA Easytrieve® Report Generator by adding its location to the environment variable LIBPATH.
Contents
316
CA Easytrieve® Report Generator 11.6
File Descriptor
For CA Easytrieve® Report Generator to recognize the file format of a C-ISAM INDEXED file, you must supply a file
descriptor. The file descriptor provides the Z format that CA Easytrieve® Report Generator requires to determine which
type of INDEXED file you are processing.
Log File
To help control the integrity of your C-ISAM files, CA Easytrieve® Report Generator performs commit processing. For
more information about commit processing, see Programming.
When you are creating or updating a C-ISAM file, CA Easytrieve® Report Generator opens the C-ISAM log file. You
specify the name of the log file in the CISAMLOG environment variable. The log file must exist before you execute the CA
Easytrieve® Report Generator program. If it does not exist, an error occurs. For more information, see your C-ISAM guide.
Examples
The following is an example of the CISAMLOG variable for Bourne and KORN shell users:
CISAMLOG=/cisam/cisam.log
export CISAMLOG
The following is an example of the CISAMLOG variable for C shell users:
setenv CISAMLOG /cisam/cisam.log
Report Display Facility (z/OS Only)
The Report Display Facility is used to display printed output that is routed back to the originating terminal. The Report
Display Facility is automatically invoked whenever CA Easytrieve Report Generator closes a PRINTER file that contains
printed output pending display at the same terminal executing the program. This includes all output of DISPLAY and
REPORT statements directed to a PRINTER that is also the originating terminal. This can also include the system output
device, SYSPRINT. For more information, see Routing Printer Output section.
This article includes the following information:
Display Order
The order in which printed output is displayed with the Report Display Facility is:
1. Output from JOB activities with non-spooled reports is displayed first. The non-spooled reports are displayed in the
order in which they were defined, including any DISPLAY statements within the JOB activity which are output to the
terminal.
2. Spooled reports are displayed next in the order in which they were defined. A report is spooled when:
– The report is SEQUENCEd
– A previously defined report uses the associated print file (when you have multiple reports in a single JOB activity).
See Print Statement (Report Processing) for more information.
3. Any other output from DISPLAY statements within an activity is displayed at the end of the activity that opened the
PRINTER file. For DISPLAYs to SYSPRINT, this occurs at the end of the entire program.
4. Any runtime errors sent to the terminal are displayed last on the Error Analysis Report. See Error Analysis Report for
details on the contents of this report.
317
CA Easytrieve® Report Generator 11.6
Panel Title
The panel title is displayed on the first line of the panel. The left corner is reserved for the panel identifier when requested
with a panelid command.
Command Line
The second line of the panel contains the command area. You can type Report Display Facility commands after
Command ===>. However, most commands have a function key equivalent. See Function Keys for more information.
Scroll Field
The Scroll field allows you to specify how much the text on the panel moves when you press F7 (Backward) or F8
(Forward). Valid scroll amounts are the following.
Scroll Value Meaning Action
nnnn number Display the previous (or next) nnnn report
lines
P Page Display the previous (or next) full page of
report lines
H Half-page Display the previous (or next) half-page of
report lines
C Cursor Shift the report line at the cursor to the
CSR bottom (or top) of the panel.
CURS
Page is the default scroll amount.
NOTE
The displayed Scroll amount is ignored when you enter a specific number (of lines to scroll) after Command
===> and press a function key to scroll.
Lines x to y of z
The third line is used to indicate how many report lines are currently displayed on the panel: out of z number of lines,
lines x through y are displayed. This line can be temporarily overlaid with error messages regarding commands you have
entered.
Error Messages
Any error messages issued by CA Easytrieve Report Generator are also displayed on the third line of the panel. Error
messages can overlay the Lines x to y of z display.
More Indicator
The third line contains the More: indicator. The More: indicator tells you that there are more report lines or columns than
can currently be displayed on the panel. One of the following symbols can be displayed after More:.
Symbol Meaning
< indicates more report columns to the left
> indicates more report columns to the right
- indicates more report lines backward or above
+ indicates more report lines forward or below
318
CA Easytrieve® Report Generator 11.6
If all report lines are currently displayed on the panel, there is no symbol displayed.
Panel Body
The panel body, which contains the report, is separated from the above header items by a line of dashes (----).
The first line of each page in the report is preceded by a line of equal signs (====).
Function Keys
Function keys and their assignments are displayed on the last two lines of the panel. You can turn off the display of the
function keys with the keys command. See Commands for more information.
The valid function keys for the Report Display Facility are the following.
Key Function
F1 (Help) Display the Help panel for the Report Display panel.
F2 (Keys) Toggle the display of the functions keys on or off, depending on
the current setting.
F3 (Exit) Terminate the display of the report (more reports may follow).
Same as F12 (Cancel).
F5 (Refresh) Discard any requests or changes to the current panel, and
redisplay the panel.
F6 (Print) Send the current report to the default output destination as set up
by your system administrator in the Site Options Table.
F7 (Backward) Scroll the report backward by the amount specified in the Scroll
field.
F8 (Forward) Scroll the report forward by the amount specified in the Scroll field.
F10 (Prev) Scroll the report backward to the previous top of page.
F11 (Next) Scroll the report forward to the next top of page.
F12 (Cancel) Terminate the display of the report (more reports may follow).
Same as F3 (Exit).
F19 (Left) Move the report to the left by the amount specified in the Scroll
field.
F20 (Right) Move the report to the right by the amount specified in the Scroll
field.
F22 (Top) Scroll the report backward to the top of the report.
F23 (Bottom) Scroll the report forward to the bottom of the report.
Commands
The commands supported by the Report Display Facility are listed below. Command formats show the full spelling of each
command and its operands. You need only type enough of the command to make it or its operands unique. You enter
commands after Command ===> at the top of the panel.
Backward nnnn page half max csr/cursor
The backward command scrolls the amount you specify toward the top of the report (backwards).
• nnnn
Moves the report backward nnnn lines.
• Page
319
CA Easytrieve® Report Generator 11.6
Moves the report backward a page, that is, the number of report lines displayed on the panel.
• Half
Moves the report backward half the number of report lines displayed on the panel.
• Max
Moves to the top of the report. Same as the top command.
• csr/cursor
Shifts the report line at the cursor to the top of the panel.
If you do not specify a scroll amount, the amount displayed in the Scroll field is used.
You can use F7 in place of the backward command.
Bottom
The bottom command moves to the bottom of the report.
You can use F23 in place of the bottom command.
Cancel
The cancel command terminates the display of the report. More reports may follow. The cancel and exit commands are
synonymous.
You can use F12 in place of the cancel command.
Exit
The exit command terminates the display of the report. More reports may follow. The exit and cancel commands are
synonymous.
You can use F3 in place of the exit command.
Forward nnnn page half max csr/cursor
The forward command scrolls the amount you specify toward the bottom of the report (forward).
Scroll Amount Meaning
nnnn Move the report forward nnnn lines.
Page Move the report forward a page, that is, the number of report lines
displayed on the panel.
Half Move the report forward half the number of report lines displayed
on the panel.
Max Move to the bottom of the report. Same as the bottom command.
csr/cursor Shift the report line at the cursor to the bottom of the panel.
If you do not specify a scroll amount, the amount displayed in the Scroll field is used.
You can use F8 in place of the forward command.
Help
Help displays the help panel for Report Display.
You can use F1 in place of the help command.
320
CA Easytrieve® Report Generator 11.6
Keys on off
The keys command allows you to control the display of the function keys. On indicates that the keys are to be displayed.
Off indicates that the keys are not to be displayed. If no operand is specified, the current setting is toggled from off to on or
from on to off.
Left nnnn page half max csr/cursor
The left command scrolls the amount you specify toward the left of the report.
Scroll Amount Meaning
nnnn Move the report left nnnn columns.
Page Move the report left a page, that is, the number of report columns
displayed on the panel.
Half Move the report left half the number of report columns displayed
on the panel.
Max Move to the left edge of the report.
csr/cursor Shift the report column at the cursor to the left edge of the panel.
If you do not specify a scroll amount, the amount displayed in the Scroll field is used.
You can use F19 in place of the left command.
Next nnnn
The next command scrolls the report forward so that the next top of page in the report is positioned at the top.
Use nnnn to specify the number of report pages to be scrolled.
You can use F11 in place of the next command.
Paneid on off
The panelid command controls the display of the panel identifier in the title line. On indicates that the panel identifier is
to be displayed. Off indicates that the panel identifier is not to be displayed. If no operand is used, the current setting is
toggled from off to on or from on to off.
Prev nnnn
The prev command scrolls the report backward so that the previous top of page in the report is positioned at the top.
Use nnnn to specify the number of report pages to be scrolled.
You can use F11 in place of the prev command.
Print
The print command sends the report to the default output destination as set up by your system administrator in the Site
Options Table.
You can use F6 in place of the print command.
Refresh
The refresh command discards any requests or changes to the current screen and redisplays the screen.
You can use F5 in place of the refresh command.
321
CA Easytrieve® Report Generator 11.6
Right nnnn page half max csr cursor
The right command scrolls the amount you specify toward the right of the report.
Scroll Amount Meaning
nnnn Move the report right nnnn columns.
Page Move the report right a page, that is, the number of report columns
displayed on the panel.
Half Move the report right half the number of report columns displayed
on the panel.
Max Move to the right edge of the report.
csr/cursor Shift the report column at the cursor to the right edge of the panel.
If you do not specify a scroll amount, the amount displayed in the Scroll field is used.
You can use F20 in place of the right command.
Top
The top command moves to the top of the report.
You can use F22 in place of the top command.
Error Analysis Report
Programming errors fall into two categories:
• Syntax errors
• Execution errors
When CA Easytrieve® Report Generator encounters a syntax error, it prints diagnostic messages during the compilation of
the program.
When CA Easytrieve® Report Generator encounters an execution error, it prints a diagnostic message for the error and
terminates immediately. If your program is compiled with the ABEXIT SNAP or ABEXIT NOSNAP parameter of the PARM
statement, CA Easytrieve® Report Generator produces an Error Analysis report. Use the Error Analysis report to debug
your program.
Following is an example of a CA Easytrieve® Report Generator Error Analysis report. The actual report format depends on
your operating environment.
EZABX000 An error has occurred in program rpt10.
The following messages provide diagnostic information. Please
contact the person or persons responsible for maintaining this
application. They may want to see this information.
###################### Diagnostic Information ######################
The error occurred at 08:15:24 on 11/22/09.
EZEIP003 The following error occurred while converting a field to PACKED DECIMAL:
Number to be converted contained an invalid digit or an invalid sign.
EZEIP992 Internal P-Code offset: 194 .
EZABX008 The error occurred at program statement number 52.
EZABX016 The statement flow table contains a maximum of 100 entries.
The program executed the following statements most recently:
52 52 51
322
CA Easytrieve® Report Generator 11.6
EZAB020 The program referred to the following files
File Name State Length Count Status
RPERSNL Open 000141 000002 Normal
EZTR001 Open 000022 000001 Normal
STDOUT Open 000132 000000 Normal
The following highlights some of the information presented in the previous report:
• EZABX000
Identifies the name of the program that abended as specified in the PROGRAM statement. If no PROGRAM statement
is coded or there is no program name on the PROGRAM statement, the name is taken from the PARM LINK
parameter. If no PARM LINK parameter is specified, the name is taken from the command line.
This message also instructs the viewer of the report to contact the party responsible for the application. Remember, the
viewer of the abnormal termination can be the end user of the application. Make each user aware of the procedures to
follow if this report displays.
• EZEIP003
Identifies the error that caused the abend. This message can be different, depending on the type of abend.
• EZEIP992
Identifies the PCODE executing when the abend occurred. This information might be required if you contact CA
Support.
• EZABX008
Identifies the number of the statement executing when the abend occurred. The statement number can be different
than the source line number. See the compiler listing to identify the correct statement.
• EZABX016
Displays the flow table. If the FLOW option is in effect when an abnormal termination occurs, CA Easytrieve®
Report Generator prints a formatted list consisting of statement numbers beginning with the most recently executed
statements.
• EZABX020
Lists the active files and pertinent information at the time of the abend.
Execute a Program on a Web Server
This section describes how to execute a program on a web server.
Contents
CGI Programming
CGI (Common Gateway Interface) programs are executed on a web server. CGI programs usually perform a task, for
example, a search or storing information on the server and normally generate a dynamic HTML page in response to a
request.
You can write CGI programs using CA Easytrieve® Report Generator. Your program can accept the parameters passed
from the web browser and use extended reporting to create output in HTML format.
You should have a basic working knowledge of HTML (Hypertext Markup Language), the language used to create web
pages, before trying to use CA Easytrieve® Report Generator to create CGI programs. The following are examples of how
you can use CA Easytrieve® Report Generator as a tool in your CGI programming.
Making a CGI Application
To use CA Easytrieve® Report Generator as a CGI application, you must add an entry to the web server applications
list so that the server can map the file extension of your P-Code files to an executable file that the server can run. The
323
CA Easytrieve® Report Generator 11.6
following example shows how to set up CA Easytrieve® Report Generator as a web server application using Microsoft
Internet Information Services (IIS):
1. Open the properties for the web site and select the Home Directory tab.
The Default Web Site Properties dialog appears.
2. Click Configuration, and then click Add to create a new mapping.
3. Enter the fully-qualified path of the CA Easytrieve® Report Generator P-Code Interpreter (ezterp.exe) as the
Executable in the following format:
[path-name]\ezterp.exe %s %s
4. Enter .pco as the Extension and click OK.
When a web browser executes a P-Code file in a web browser, the interpreter executes using the name of the P-Code file
as input and has access to simple parameters.
Basic Execution
You can now perform basic execution of your program. The following example shows a simple program called echo.ezt,
compiled into echo.pco in a directory on your web server (that is, http://myserver.com):
FILE Browser EXTENDED HTML SYSNAME `stdout`
DEFINE Parm-Field S 40 A
PROGRAM NAME echo USING Parm-Field
DISPLAY Browser `You said ` Parm-Field
The Browser FILE allows the program to display output in the web browser. When you enter http://myserver.com/
echo.pco?Hello in the address field of your web browser, the following appears in the web browser window:
You said Hello
To make a web page invoke the echo program, enter the following HTML:
<a href="http://myserver.com/echo.pco?Hello">Say Hello</a>
This displays Say Hello as a hyperlink in your web page. When you click the hyperlink, the HTML invokes the echo.pco
file, which passes the literal Hello.
Form Input
Input to a CGI program comes from a user's response to a web page. The web page can contain a form that has edit
controls of fields. Each field is assigned a name and a value. The following is an example of a simple form that accepts an
employee number as input:
<form action="lookup.pco" method="GET">
Employee #: <input type="text" name="EmployeeNo" />
<input type="submit">
</form>
When this form sends information to a server CGI program, EmployeeNo would be a variable name and the value would
be whatever the user types in the edit box. A form has two methods for sending information to a CGI program: GET and
POST. The HTML for this web page contains a FORM tag, which indicates what type the page is (method=GET) and
which CGI program to run on the server (action="lookup.pco").
324
CA Easytrieve® Report Generator 11.6
GET Versus POST
A GET provides the user's input to the CGI program as an environment variable called QUERY_STRING. The CGI
program reads this environment variable (using the C getenv() function) and parses it to get the user's input. A GET
method also shows the input data to the user in the URL area of the browser, showing a string like www.somewhere.com/
lookup.pco?EmployeeNo=12345. The GET method is acceptable for small amounts of data and is the default method
when a CGI program is run through a link.
A POST provides the user's input to the CGI program as if it was typed at the keyboard, using the standard input device or
stdin. This section discusses the GET method only.
CA Easytrieve® Report Generator does not have a built-in function to return an environment variable; therefore, you must
code a small C program to return the value and length. The following is an example:
#include <stdio.h>
declspec(dllexport)
int getdata(char *pszOutstr)
{
char *pszEnvdata;
pszEnvdata = (char *)getenv("QUERY_STRING");
if (!pszEnvdata) {
pszOutstr = strcpy("no data");
return (0);
}
else {
strcpy(pszOutstr, pszEnvdata);
}
return(strlen(pszOutstr));
}
You can make this C program into a Windows DLL with the following commands:
cl - c getdata.c
link /DLL /OUT:getdata.dll getdata.obj
Parsing the Input
When the input is received, it must be parsed. All field values appear combined as one long string. Each value is actually
a paired value: "fieldname=fieldvalue". Multiple field-value pairs are separated by an & character. For example, a two-
value string can look like: EmployeeNum=12345&EmployeeName=Smith. Here, EmployeeNum and EmployeeName are
the names of two input fields from the form, and 12345 and Smith are what the user entered in those fields.
The server also performs the following conversions:
• All spaces are converted to a + character
• Special characters (like \n) are converted to a %, followed by the ASCII code for the character
For example, the value Smith, John is returned as:
EmployeeName=Smith%2C+John
You will need to un-do these conversions in your CGI program.
When parsed, you can proceed as required.
325
CA Easytrieve® Report Generator 11.6
Output
A CGI program outputs its result by sending the data to the standard output device (stdout); however, you must output in a
specific format.
The most common format is HTML text. You can use the HTML extended printer included with CA Easytrieve® Report
Generator. For more information, see Extended Reporting. The printer is configured to provide the basic format required
by CGI processing. A CGI program must begin its output with the string Content-type: text/html, followed by two new lines.
Any valid HTML can follow.
The data is sent using this extended printer to the system stdout device by using SYSNAME 'stdout':
FILE Browser EXTENDED HTML SYSNAME 'stdout'
Putting It All Together
The following is an example application that uses a web browser requesting the user enter an employee number. The
number is used by a CA Easytrieve® Report Generator program to access the employee's record in an SQL database and
display the result to the user in their web browser.
First the HTML for the web page:
<html>
<head>
<title>Find Employee</title>
</head>
<body>
<form action="lookup.pco" method="GET">
Employee #: <input type="text" name="EmployeeNo" />
<input type="submit">
</form>
</body>
</html>
The following is the CA Easytrieve® Report Generator program, which is compiled into lookup.pco. An explanation of the
program follows the source code.
PARM SSID 'EZTTest'
FILE HTM EXTENDED HTML SYSNAME 'stdout'
FILE PERSNL SQL(PERSNL) DEFER
SQL INCLUDE LOCATION * FROM PERSNL
DEFINE EMP EMP_NO EMP_NO MASK '99999'
DEFINE SSN SSN_NO SSN_NO MASK '999-99-9999'
DECLARE getdata PROGRAM DYNAMIC
DEFINE PARM-LEN S 3 P
DEFINE PARM S 80 A
DEFINE PARM-EMP PARM +11 5 A MASK HEX
DEFINE NEMP PARM-EMP 5 N MASK '99999'
PROGRAM NAME lookup
CALL getdata USING PARMS RETURNS PARM-LEN
IF PARM-LEN = 0 OR PARM-EMP NOT NUMERIC
DISPLAY HTM 'Invalid employee number. Must be five numeric digits.'
STOP
END-IF
326
CA Easytrieve® Report Generator 11.6
SELECT PERSNL WHERE EMP_NO = :NEMP
FETCH FROM PERSNL
IF EOF PERSNL
DISPLAY HTM 'Employee ' NEMP ' not on file'
ELSE
EXECUTE DISPLAY-EMP
END-IF
JOB INPUT NULL NAME DISPLAY-EMP
PRINT RPT
STOP
REPORT RPT PRINTER HTM LINESIZE 80 NOHEADING NOADJUST NODATE NOPAGE
LINE 1 COL 20 'Employee: ' EMP
LINE 3 COL 20 'Name: ' NAME_LAST NAME_FIRST
LINE 5 COL 20 'SSN: ' SSN
The PARM statement identifies the SQL data-source.
The HTM FILE statement defines a file to produce output in HTML format and route the output to the stdout device to
enable CGI to display it in the browser.
THE PERSNL FILE statement defines the PERSNL table and its columns are defined using the SQL INCLUDE catalog
interface. The default edit masks of two columns are then overridden.
DECLARE the external getdata subroutine as dynamic.
Working-storage fields are defined to accept the parameters received. The fields are defined to enable access to the five-
digit numeric employee number in the received string: 'EmployeeNo=nnnnn'.
The program first calls the getdata C subroutine shown previously, which accepts the QUERY_STRING environment
variable and passes it back in the PARMS field. The result is edited for validity before the result set is selected and
fetched. If the employee is found, the program executes a JOB activity to display the employee's name and social security
number in the browser.
Advanced Parsing
As discussed previously, the input received by the CGI program must be parsed. Be aware of the following:
• All field values appear combined as one long string.
• Each value is actually a paired value: "fieldname=fieldvalue"
• Multiple field-value pairs are separated by an & character
• All spaces are converted to a + character
• Special characters (like \n) are converted to a %, followed by the ASCII code for the character
When parsed, it is usually convenient to store the input parameters in an array of strings. You would probably want a
function to search the stored parameters to retrieve their values. A table file makes an excellent mechanism. The following
program illustrates these concepts.
The PROGRAM activity retrieves the value of the QUERY_STRING environment variable using the getdata C routine. It
then executes the LOAD-TABLE JOB activity, which parses the resulting string into words. An ampersand (&) delimits a
field-value pair. An equal sign (=) delimits the field name from the field value. A plus sign (+) is converted into a space. A
percent sign (%) signifies the next two characters are an ASCII code requiring translation. In the following case, a comma
is translated. This parsing handles a string such as "Num=31&Player=Maddux, Greg".
When a table argument and description are parsed, the entry is written to a virtual file.
The PROGRAM activity then executes a SORT activity to ensure the correct order for searching. The virtual file is sorted
and written to a file, which can then be searched for the expected fields. The resulting record is then inserted into the
database.
327
CA Easytrieve® Report Generator 11.6
FILE Browser EXTENDED HTML SYSNAME 'stdout'
FILE Roster SQL(Roster) UPDATE
SQL INCLUDE LOCATION * FROM Roster
FILE VPARMS V(80) VIRTUAL
argword 1 40 A
descword 41 40 A
FILE PARMS V(80) SYSNAME 'PARMS'
argword 1 40 A
descword 41 40 A
FILE PARMTBL V(80) TABLE SYSNAME 'PARMS'
ARG 1 40 A. DESC 41 40 A
DECLARE getdata PROGRAM DYNAMIC
DEFINE parms S 80 A
PROGRAM USING parms
DEFINE len S 4 N
CALL getdata USING parms RETURNS len. * Get the input string
EXECUTE LOAD-TABLE . * Load the table file values
EXECUTE SORT-TABLE . * Sort the table
DEFINE searcharg S 40 A
DEFINE searchdesc S 40 A
DEFINE search2N searchdesc 2 N
searcharg = 'Num' . * Retrieve the Num value
SEARCH PARMTBL WITH searcharg GIVING searchdesc
Num = search2N
searcharg = 'Player' . * Retrieve the Player value
SEARCH PARMTBL WITH searcharg GIVING searchdesc
MOVE searchdesc 30 TO Player FILL ' '
INSERT INTO Roster . * Add the row to the roster
DISPLAY Browser 'Player inserted'
JOB INPUT NULL NAME LOAD-TABLE
DEFINE data S 80 A
DEFINE data-byte data 1 A OCCURS 80 INDEX data-indx
DEFINE word S 40 A
DEFINE word-byte word 1 A OCCURS 40 INDEX word-indx
data = parms
data-indx = 0
word-indx = 0
DO WHILE data-indx < len
IF data-byte = '&'
* We're at the end of a value pair, put the parm table entry
PERFORM WRITE-ENTRY
ELSE-IF data-byte = '='
* We're at the end of a value name, save the name as an argument
VPARMS:argword = word
word-indx = 0
MOVE SPACES TO word
ELSE
IF data-byte NE '"' . * Ignore any wrapping quotes
* We have a character to save
IF data-byte = '+'
* Convert + to space
data-byte = ' '
328
CA Easytrieve® Report Generator 11.6
ELSE-IF data-byte = '%'
* We have an ASCII code to convert
data-indx = data-indx + 1
DEFINE hexcode S 2 A
MOVE data-byte 2 TO hexcode
IF hexcode = '2C' . * Convert a comma
word-byte = ','
ELSE
DISPLAY Browser 'Unsupported ASCII code found ' hexcode
STOP EXECUTE
END-IF
data-indx = data-indx + 1
ELSE
word-byte = data-byte
END-IF
word-indx = word-indx + 1
END-IF
END-IF
data-indx = data-indx + 1
END-DO
* Write out last entry
PERFORM WRITE-ENTRY
STOP
WRITE-ENTRY. PROC
VPARMS:descword = word
word-indx = 0
MOVE SPACES TO word
PUT VPARMS
END-PROC
SORT VPARMS TO VPARMS USING argword NAME SORT-TABLE
Alternate Collating Sequence Table
This article describes how to create and maintain an alternate collating sequence table. The use of an alternate collating
sequence table is optional.
The alternate collating sequence table default name is EZTPAQTT. You can change the name that CA Easytrieve Report
Generator uses with the etopload utility.
This article includes the following information:
Modify the Table on the z/OS Platform
CA Easytrieve Report Generator is distributed with an ascending sort sequence for EBCDIC characters. You can change
this sort sequence by modifying the Sort Sequence Table that is provided in the EZTPAQTT member of hlq.CBAAJCL. In
previous releases, EZTPAQTT, is in the SAMPJCL library.
Follow these steps:
1. Follow the instructions in the EZTPAQTT source member.
2. Reassemble and link the source module. Standard assemble and linkage jobs can be used.
3. Link the output load module to the product load library, naming the load module EZTPAQTT.
4. Set the Use Alternate Sequence site option ALTSEQU to Yes.
329
CA Easytrieve® Report Generator 11.6
Create and Modify the Table on Non-Mainframe Platforms
You can place EZTPAQTT in any directory to which you have access. When CA Easytrieve Report Generator searches for
the alternate collating sequence table, the current directory is searched first. Next, any directories that are specified in the
EZTPATH environment variable are searched. For more information about the EZTPATH environment variable, see the
Installing section.
Create an Alternate Collating Sequence Table
The etaltseq utility creates and maintains alternate collating sequence tables. You can create an initial version of the
alternate collating sequence table.
Follow these steps:
1. Run the following command from the EZTPATH path:
UNIX and Linux for zSeries:
etaltseq -b -l >eztpaqtt.def</dev/null
Windows:
etaltseq -b -l >eztpaqtt.def</nul
This command invokes the etaltseq utility that builds a default alternate collating sequence table called EZTPAQTT.
It also produces a file, eztpaqtt.def, which contains a listing of the alternate sequence table. You can edit this file to
update the alternate sequence table.
2. Edit and update eztpaqtt.def.
3. Update the table by typing the following command on the command line:
etaltseq -b <eztpaqtt.def
Command Line Syntax for ETALTSEQ
etaltseq [options] [path]
Valid options are:
• -b
If the table does not exist, create it. Otherwise, update it. Input is expected on stdin.
• -h
Displays the help information about stderr.
• -l
Displays the alternate collating sequence table to stdout after all updates are applied.
If no options are specified, the default is -h.
If the path is not specified, EZTPAQTT is the default.
Update the Table
A listing of eztpaqtt.def follows:
// 0 1 2 3 4 5 6 7 8 9 A B C D E F
0x00010203 0x04050607 0x08090A0B 0x0C0D0E0F // 0
0x10111213 0x14151617 0x18191A1B 0x1C1D1E1F // 1
0x20212223 0x24252627 0x28292A2B 0x2C2D2E2F // 2
0x30313233 0x34353637 0x38393A3B 0x3C3D3E3F // 3
330
CA Easytrieve® Report Generator 11.6
0x40414243 0x44454647 0x48494A4B 0x4C4D4E4F // 4
0x50515253 0x54555657 0x58595A5B 0x5C5D5E5F // 5
0x60616263 0x64656667 0x68696A6B 0x6C6D6E6F // 6
0x70717273 0x74757677 0x78797A7B 0x7C7D7E7F // 7
0x80818283 0x84858687 0x88898A8B 0x8C8D8E8F // 8
0x90919293 0x94959697 0x98999A9B 0x9C9D9E9F // 9
0xA0A1A2A3 0xA4A5A6A7 0xA8A9AAAB 0xACADAEAF // A
0xB0B1B2B3 0xB4B5B6B7 0xB8B9BABB 0xBCBDBEBF // B
0xC0C1C2C3 0xC4C5C6C7 0xC8C9CACB 0xCCCDCECF // C
0xD0D1D2D3 0xD4D5D6D7 0xD8D9DADB 0xDCDDDEDF // D
0xE0E1E2E3 0xE4E5E6E7 0xE8E9EAEB 0xECEDEEEF // E
0xF0F1F2F3 0xF4F5F6F7 0xF8F9FAFB 0xFCFDFEFF // F
// 0 1 2 3 4 5 6 7 8 9 A B C D E F
The table consists of 256 values from 0 to 255 displayed in hexadecimal. The value at each position remaps the position
to a new collating value.
Edit this table to change the sequence. Spaces serve as delimiters but are otherwise not important. A double slash (//)
begins a comment. Comments terminate at the end of the line.
The syntax rules for updating etaltseq are as follows:
Value Description
table_spec ::= character_spec table_spec
character_spec ::= [reposition_order] collating_values
reposition_order ::= ( literal )
collating_values ::= char_string | hex_string | octal_string | literal
literal ::= character_literal | hex_literal | octal_literal | decimal_literal
char_string A sequence of characters that are surrounded by double quotes.
Use the escape sequences listed for character_literal.
hex_string 0x prefixing multiple pairs of hex digits
octal_string 0 prefixing multiple triples of octal digits
character_literal A character that is surrounded by single quotes. Use \ as an
escape character. \a, \b, \f, \n, \r, \t, \v, \\\?, \', \", \ooo for octal, \xhh
for hex.
hex_literal 0x prefixing a pair of hex digits.
( 0..9, a..f, A..F )
octal_literal 0 prefixing a triple of octal digits ( 0..7 )
decimal_literal Sequence of digits not starting with 0
When you create a table, the table is initialized to collate every character as itself.
Collating_values specify either a single collating value or a sequence of values. The first value affects the character at
the current position, then increments the current position. The next value affects the character at the new current position,
then increments the current position.
The current position begins at 0x00. Reposition_orders change the current position. Collating_values use the current
position to determine which character they affect.
Example One
If you want ASCII 0 through 9 to collate as an EBCDIC 0 through 9, make the following changes:
The original line looks like:
331
CA Easytrieve® Report Generator 11.6
// 0 1 2 3 4 5 6 7 8 9 A B C D E F
.
.
.
0x30313233 0x34353637 0x38393A3B 0x3C3D3E3F // 3
.
.
.
After changing ASCII 0 through 9 to EBCDIC 0 through 9:
// 0 1 2 3 4 5 6 7 8 9 A B C D E F
.
.
.
0xF0F1F2F3 0xF4F5F6F7 0xF8F93A3B 0x3C3D3E3F // 3
.
.
.
Example Two
In the following code, ( 'a' ) is a reposition-order that sets the current position to 'a'. "ABCDEFG" is a collating-values string
that makes 'a' through 'g' collate as if they were 'A' through 'G'.
( 'a' ) "ABCDEFG"
Extended Reporting
This article assumes you are familiar with the CA Easytrieve® Report Generator language and understand basic data
programming concepts.
Contents
Here we introduce the major components of the reporting environment and explains the report printer definition language
and command language; this will help you use the Extended Reporting environment to produce reports on printer devices
or files without being concerned with environment and device specific characteristics in printing operations.
Note that reports written to files can be used with special browsers rather than actual printer devices. You can use
Extended Reporting to create specially formatted file outputs, such as HTML and RTF. Therefore, the term printer in the
context of Extended Reporting can mean either a printer device or file output.
Environment Overview
Printer definition and report printing are the two major processes of the reporting environment. These two processes are
illustrated in the following diagram:
332
CA Easytrieve® Report Generator 11.6
Figure 6: Printer Definition and Report Printing
Printer Definition is a process that converts a set of user supplied printer characteristics into a Printer Set Definition.
Report Printing is a process that formats reports from user supplied report specifications and prints the reports on printers
whose characteristics are defined in a printer set definition.
Configuration Manager
The CA Easytrieve® Report Generator Configuration Manager is a Windows graphical tool that helps you create your
printer definition.
Printer Definition
Printer Definition is a process that converts a set of user supplied printer characteristics into a printer set definition.
The following graphic illustrates the printer definition components:
333
CA Easytrieve® Report Generator 11.6
Figure 7: Printer Definition Components
Printer Support
The Reporting Environment supports a variety of printers. Each printer has its own characteristics, especially with respect
to the identification of the font, the presentation of print records, and the distinction between character sets. To support
each printer's characteristics, a printer set definition module is used. This module defines the type of printer supported and
the font codes that a program supports.
A default printer set definition module (eztxrpsd) is provided as part of a normal installation. Sample definitions for HTML
and RTF are provided in Configuration Manager.
Printing Concepts
This article introduces you to some of the concepts used in printing reports.
NOTE
For more detailed information, see Printer Characteristics and Font Characteristics.
This article includes the following information:
Terminology
This section defines the terminology used throughout this section. It is important that you thoroughly understand these
terms before reading the later sections in this section.
• Font
A font is an assortment of character images belonging to one data format. Fonts have one size, shape, style, and
design.
A font defines all of the information necessary to create character images of that font on a specific printer. This
information includes the characteristics of the font to format a report (such as height and width). It also includes the
printer control codes that specific printers require for output records that use the font.
If any of this information changes between two character images, the two characters belong to different fonts.
• Proportional Spaced Fonts
A proportional spaced font is a font in which each character occupies a different amount of horizontal spacing. This
can reduce the amount of white space between characters. For example, the letter i occupies less horizontal space
than the letter w. Proportional spaced fonts are commonly used in books and regular reading material. The Reporting
Environment does not support proportional spaced fonts.
• Fixed Space Fonts
334
CA Easytrieve® Report Generator 11.6
A fixed space font is a font in which each character occupies the same amount of horizontal spacing. This can cause
more white space to appear between characters. For example, the letter i will occupy the same horizontal space as
the letter w. With fixed space fonts, each character is aligned up and down the page in a vertical line. Most computer
reports use fixed space fonts. The Reporting Environment supports fixed space fonts.
• Characters Per Inch
Characters per inch (CPI) refers to the number of fixed space characters that can fit in one horizontal inch.
• Pitch
Pitch means the same as characters per inch (as discussed earlier).
• Lines Per Inch
Lines per inch (LPI) refers to the number of printed lines that can fit in one vertical inch.
• Unit of Measure
Prior to the Reporting Environment, when processing printed text, each character is to be printed using the same font.
This means that each character has the same height and width. Furthermore, it means that each print item (field or
literal) on a print line occupied an amount of horizontal space that is directly proportional to the number of characters in
that print item. All the calculations that determined the positioning of print items on a print line did not need to take into
consideration the size characteristic of the font being used to print that particular item. The size is assumed to be fixed.
This methodology is still used when using one font for a report. With the Reporting Environment, you can use multiple
fonts in the same report where each font can have a different height or width. As a result, a print item now occupies an
amount of vertical space equal to the height characteristic of the font and an amount of horizontal space (equal to the
number of characters in the item multiplied by the width characteristic of the font).
The Reporting Environment must position items on a print line using both the size of the print item and the size of the
font associated with that print item. To perform this, we must define the size characteristic of each font as a multiple of
a unit of measure that is standard for all the fonts in a given printer.
The specific unit of measure assigned to a particular printer is of no consequence for the reporting mechanism. What
is important is that the sizes of all fonts assigned to a particular printer be defined in terms of the selected unit of
measure. Sample units of measure include points, dots, and PELs.
• Points
Points are a linear unit of measurement normally associated with the width (or height) of typefaces. A point is
approximately equal to 72 dots per inch.
• Dots
A dot is the fundamental unit of imaging and digitization for electro-photographic printers. The size of a dot varies
depending upon the resolution of the printer. The resolution is normally expressed as the number of dots per inch. The
larger the number of dots, the higher the resolution quality of the printer. For example, the Xerox 8700 and Xerox 9700
support 300 dots per inch; the MELCOM 8290, IBM 3200, and HITACHI 8196 support 240 dots per inch; the TORAY
8500 supports 140 dots per inch.
• PELs
A PEL (picture element) is the IBM term used to refer to the fundamental unit of imaging on the IBM 3800 printing
systems. A PEL is the same as a dot, but it is also used as the addressable unit for "All Points Addressable" printing on
the 3800 Model III and VIII, and the 3820. For these printers, 240 PELs per inch are supported.
Usually, any one of the units of measure can give the same results. The following diagram illustrates this:
335
CA Easytrieve® Report Generator 11.6
Figure 8: Font Size and Units of Measure
There are certain characteristics regarding particular printers that you must consider when determining the unit of
measure. These characteristics are:
– The definition of the height and width characteristic of a font can only be accurate to two decimal positions. If a font
requires greater accuracy, then you must re-evaluate the unit of measure.
– For printers that are "All Points Addressable" (such as the IBM 3800 Model III and VIII, and the IBM 3820), positions
must be assigned to print items in terms of the unit of measure known by that printer. These printers require control
information (item positioning, item sizes, page sizes, and line sizes) in one unit of measure (for example, PELs).
To meet these requirements, you must use the same unit of measure to define the printer characteristics that the
options module identifies.
For example, if you define all the fonts in terms of a number of points, then the Reporting Environment cannot
support a printer that supports PELs as the unit of page addressing. The Reporting Environment positions items
on a page by using values that are multiples of points, but the printer interprets these values as a number of PELs.
This produces incorrect results. Therefore, for "All Points Addressable" printers, the Reporting Environment restricts
the selection of the unit of measure to the unit used to address positions on the page of a report.
– Some printers require values to be merged with the printer function code. These printers use this value for Paper
Control Codes (Carriage Control) where the amount of vertical space to be skipped is defined as a multiple of a
certain unit of measure.
For example, the SHOWA SP-7, SP-8, and the MELCOM 8250 all require the skip amount be defined in terms
of a number of points. For printers having this characteristic, the unit of measure selected to define the other
characteristics of the printer must be the same. Using more than one unit of measure causes the printer to interpret
the value the Reporting Environment merges by a unit of measure different from the one with which it was defined.
• Font Size
As illustrated earlier in the diagram for units of measure, a variety of units of measure can define a printer's
characteristics. From the Reporting Environment point of view, any unit of measure is fine. To simplify the discussion
of fonts, assume a standard unit defines a font's width (W-unit) and another defines a font's height (H-unit). Therefore,
independent of the actual unit of measure selected (such as points, dots, and PELs), a number of H-units and a
number of W-units define a font.
Using these base units, this section discusses the meaning of the size of a font. The Reporting Environment must
know the characteristics of a font to accurately determine the positioning of print items on a line or page. The definition
of the size of a font is expressed as the height and width of the character cell assigned to the font.
• Character Cell
Each fixed pitch font is associated with a character cell. The Character Cell defines the area required to encompass
the images of the characters of a particular font. The following diagram illustrates that the height and width of a
character cell is not always the same as the height and width of the actual character image. The reason is that the
character cell includes any additional vertical and horizontal spacing required to encompass images of the font's
characters.
336
CA Easytrieve® Report Generator 11.6
Figure 9: Character Cell
An important reference line in any font definition is the baseline. The definition of the baseline changes between
printers. The more commonly accepted definition of a baseline is an imaginary line supporting the bottom of capitals. In
the Reporting Environment, the baseline is an imaginary line supporting the bottom of character cells. The formatting
of a print line containing a mixture of fonts is based on the positioning of the bottom of each character's cell on that
baseline. The amount of vertical space between one print line and the next is the vertical distance between baselines.
This distance is the height of a line.
• Height
A font's height is the amount of vertical space (in H-units) that a printed character occupies. This means that the height
of the font is the height (in H-units) of the character cell associated with the font.
Some printers are able to adjust the vertical position of a font. These printers can move the base of the character cell
up or down a number of H-units from the baseline. You can incorporate this adjustment into the printer control codes
associated with a font. The Reporting Environment supports the definition of an adjust vertical position font, but you
must make the appropriate adjustment to the height to compensate for the font's movement.
• Upward Adjustment
For Upward Adjustment, the height of the font must include the adjustment amount. The reason is that the height of the
font is equal to the height of the character cell plus the amount of vertical adjustment. Therefore, an upward adjustment
is like extending the length of a character's cell. If the font's height is not adjusted up, there exists the possibility of
generating a vertical line feed that would be too small to include the upward adjustment.
For example, assume that a font normally prints with a height of 12 points. If you defined this font in such a manner
that the printer performed an upward adjustment of 4 points, then you would have to define the height of the font as 16.
You define the height of the font on the FONT specification. For more detailed information see Font Characteristics.
• Downward Adjustment
For Downward Vertical Adjustment, the bottom of the character cell is actually positioned below the baseline. To
support this adjustment, you must calculate the height of the font as the character cell's height minus the vertical
adjustment. This defines the correct height that the Reporting Environment requires. It is then your responsibility to
ensure that the next baseline is vertically displaced a sufficient amount to allow room for the portions of characters that
prints below the current baseline.
For example, assume that a font normally prints with a height of 12 points. If you defined this font in such a manner
that the printer performed a downward adjustment of 4 points, then you would have to define the height of the font as
8. You define the height of the font on the FONT specification. For more detailed information see Font Characteristics.
• Width
337
CA Easytrieve® Report Generator 11.6
A font's width is the amount of horizontal space (in W-units) that a printed character occupies. This means that the
width of the font (in W-units) is the width of the character cell associated with the font. The Reporting Environment
supports only fixed pitched fonts in which all of a font's character patterns occupy the same horizontal or lateral space.
Some printers support special horizontal adjustment functions that you can use to expand the horizontal size of a
character or squeeze the character. If you select either of these options, the width of the font that these function codes
identify must incorporate the horizontal adjustment factors.
For example, assume that a font normally prints with a width of 12 points. If you defined this font in such a manner that
the printer performed an expansion of 4 points, then you would have to define the width of the font as 16. You define
the width of the font on the FONT specification. For more detailed information see Font Characteristics.
• Print Records
In terms of the Reporting Environment, a print record is the base unit for a print output request. After a record is built, it
is output to the print data set.
Standard reporting associates the production of one print line with the output of one print record. This is appropriate for
basic printing on Line Printers.
With the Reporting Environment, the production of one print line is no longer associated with the output of one print
record. This is because some printers do not allow you to mix print items from different fonts on the one print line.
Multiple print records must be output by the Reporting Environment and the printer combines these records to form a
single print line.
Print records that the Reporting Environment builds have four components:
– Paper Control Codes (PCC)
– Overprint Codes
– Function Codes
– Print Data.
• Paper Control Code (PCC) - Carriage Control
At the start of each print record is a control field that defines the required vertical movement that occurs before printing
the text that follows. If you are combining multiple print records to form a single print line, then the first print record
contains the carriage control information that specifies the start of a new line. Additional print records for the same
logical print line would use a SKIP 0 carriage control.
• Overprint Code
This control field follows the PCC. Printers that output multiple print records to form a single print line use this control
field. It indicates the characteristics of the font(s) that this particular print record uses. Multiple print records destined
for the same print line would use different overprint codes to output text using different fonts.
Not all printers require overprint codes. Therefore, they will only be incorporated into print records when the assigned
printer requires them.
Overprint Codes are called Table Recognition Codes (TRC) on IBM printers that support multiple fonts while running in
Line Compatibility mode.
• Function Codes
Printers that require one print record to support the printing of multiple fonts on the same print line process print
records as a combination of two data types:
– Text
– Control information
The text is that portion of the print record that is to actually appear on the printed page.
Function Codes consist of control information that instructs the printer how to process the text. To perform this:
– Define the type of font
– Size of the characters
– Data type (single or double byte data)
– Special operations (such as repeating a character and underlining text)
The Reporting Environment processes function codes before data (Header Function Codes), or after data (Trailer
Function Codes). When you use the font to which function codes are assigned, the Reporting Environment combines
the appropriate function codes with the item in the print data.
• Print Data
338
CA Easytrieve® Report Generator 11.6
Print Data refers to the actual text or data that appears on the report.
Printer Types
This section describes the printer types that the Reporting Environment uses to generate the correct print data set for the
appropriate printer. There are three types of printer characteristics that the Reporting Environment supports:
• Printer Type -- defines the method used to build print records and how different fonts are combined onto the same print
line.
• Paper Control Code -- identifies the method used to control vertical positioning on a page.
• File Type -- defines the attributes of the print data set that the Reporting Environment creates as it outputs print
records.
Printer Type
The printers that the Reporting Environment supports use different techniques to identify fonts and print items in a print
record. The seven categories of printers that the Reporting Environment supports are displayed in the following diagram.
339
CA Easytrieve® Report Generator 11.6
Figure 10: Seven Categories of Printers
340
CA Easytrieve® Report Generator 11.6
Basic Printing
A printer in its simplest form will take a line of input data and display that data on the paper in the printer. It will then take
another line of data and then display that data on the next line of the printer. Repeating this process, eventually, all of the
input data is displayed by the printer. Input to a printer can be either blocked or unblocked.
Print Data
A basic print record follows:
Figure 11: Basic Print Record
The length of print data is limited by the amount of data that can be displayed by the particular printer.
Line Printers
This section describes the types of line printers.
ANSI Characters
A common modification to the process of basic printing (as discussed earlier) is to prefix each line of data with a Print
Control Character (PCC). This print control character is often referred to as an ANSI carriage control, or ASA character.
The control character tells the printer how to print this information. The standard control characters (given in EBCDIC) are
explained in the following table.
HEX EBCDIC Action
X'F1' C'1' The printer will skip to the top of the next
page before printing the next line of data.
This is often referred to as a channel 1 skip,
newpage, or top of form.
X'4E' C'+' The printer will stay on the same line and
print this line of data. This will cause the
output from this print line to overlay the
output from the previous print line. This
technique can be used to BOLD characters
on some printers.
X'40' C' ' The printer will skip to the next line before
printing the next line of data. This is
probably the most common situation. Each
line of data will appear on a new output line.
X'F0' C'0' The printer will skip an extra line before
printing the next line of data. This will cause
the output to appear as double spaced.
341
CA Easytrieve® Report Generator 11.6
X'60' C'-' The printer will skip two lines before printing
the next line of data. This will cause the
output to appear as triple spaced.
FCB Channel Skips
In addition to the previous control characters, a printed report could be associated with a specific form and that form could
have data that must be displayed on a specific line on the form. When this situation arises, a Forms Control Block (FCB)
could be used. An FCB associates Channel Skips with a particular output line. The channel skip is specified as a control
character like the ANSI carriage controls discussed earlier.
A channel skip is one of eleven codes (C'2', C'3', C'4', C'5', C'6', C'7', C'8', C'9', C'A', C'B', C'C') given to the printer.
Exactly what line the data is displayed on is coded in the FCB. The name of the FCB to be used is given in JCL for the job
execution.
Channel skips are often referred to by their printer codes. For example, a channel 2 skip would have a C'2' in the control
character, regardless of what line it actually prints on. The channel skips of C'A', C'B', and C'C' are often referred to as
channel 10, channel 11, and channel 12 skips.
Machine Characters
Some printers can be driven using print Machine Control Characters. These characters are similar in concept to ANSI
print control characters. The following table shows a small sampling of the machine print control characters that are
available.
The complete set of machine print control characters can be found in the manufacturers printer manuals.
HEX Action
X'0B' Space 1 line, then print the data.
X'09' Print the data, then space 1 line.
X'03' Print the data. Do not space before or after printing.
X'8B' Skip to channel 1, then print the data.
X'89' Print the data, then skip to channel 1.
No FCB Channel Skips
If the printer does not have access to an FCB, the process to skip to a given line is limited to using a combination of the
available print carriage control characters.
Point Skip
For Line Mode printers that do not support FCB, ANSI paper control codes, or machine control codes, Point Skip codes
are used to achieve vertical spacing. With this method, the Reporting Environment will generate a vertical spacing value
using the PSNEWPAGE and PSNEWLINE values. For more information on these values, see Using the Configuration
Manager.
Print Data
The format of print data that contains a Carriage Control (CC) is illustrated below:
342
CA Easytrieve® Report Generator 11.6
Figure 12: Print Data with Carriage Control
Most z/OS users are required to tell JES that the output contains an ASA or ANSI carriage control character
(DCB=RECFM=FA).
DOS/VSE users must code the presence of the ASA character into the DTFPR. The Reporting Environment does this.
Line Printers with Multiple Fonts
This section describes line printers that can use multiple fonts.
Overprint Codes
Some printers have the ability to use multiple fonts in a single report. This is accomplished through an overprint code. This
overprint code should not be confused with an overprint print control character (as discussed earlier). An overprint code is
often referred to as a TRC character.
The overprint code immediately precedes the print data in the output record. While the print control character tells the
printer which line to place the data on, the overprint code tells the printer which font to use to print this data. When used
with an overprint print carriage control character, multiple fonts can be used on a single print line.
The printing system must be told about the presence of the overprint code. This is accomplished by the following IBM
MVS/JCL statement:
//ddname DD ...,DCB=OPTCD=J
or the following IBM VSE/JCL statement:
// SETPRT SYSxxx,TRC=Y
Print Data
The format of print data that contains an overprint code is illustrated below:
Figure 13: Print Data with Overprint Code
343
CA Easytrieve® Report Generator 11.6
Overprint Techniques
The two techniques that the Reporting Environment supports for overprinting multiple print records to form a single print
line are:
• Merge Overprint
The Merge Overprint technique merges the print records by character position in the print record
• Print Overprint
The Print Overprint technique combines the print records by their physical position in the final print line. The results of
the print overprint technique are similar to those obtained when overprinting on an impact line printer.
The printer hardware defines the technique that should be used. The Reporting Environment automatically compensates
for the characteristics of the appropriate technique that the printer uses.
Merge Overprint
When merging multiple print records into a single print line, the merge process combines the data on a character-by-
character basis. The twelfth character in a print record, for example, merges with the twelfth character in another print
record. This happens regardless of where those characters must otherwise appear (as a result of differences in character
width) on the print line.
The rules that the printer uses to merge print records (of the same or different font widths) into one print line are:
• A printable character in a following record replaces an identical character or a blank.
• A blank in a following record does not replace either a blank or a printable character.
• A printable character trying to replace a previous printable character different from itself results in a data check, and
the character in the new record does not replace the character in the previous record.
• When merging blanks of different W-units, the resulting blank has the W-unit of the first one.
• When a printable character is merged with a blank, the resulting character has the W-units of the printable character.
To illustrate this process, assume that three print records are being merged and the W-units are in points. The first record
contains 7 point characters, the second contains 12 point characters, and the third contains 9 point characters. Each print
record contains four characters (three blanks and one printable character). The following diagram illustrates the three print
records and the resulting print line.
344
CA Easytrieve® Report Generator 11.6
Figure 14: Three Print Records and Resulting Print Line
Print Overprint
The Print Overprint technique overprints print records the same as does a normal impact line printer. The printer develops
the image (or images) each print record independent of any other print record for the same line. It is the imaged or
physical lines that are combined. With this technique you can have one character from one print record overlay another
character because the physical images of the two records occupy the same position on the line.
To illustrate this technique, the same three records that demonstrate the merge process are used. Therefore, 7, 12, and 9
point print records are used. As the following diagram demonstrates, the independent imaging of the three records results
in an overlap of character boundaries. For example, the character from the first record is overprinted by the character on
the second imaged record because they occupy the same physical space on the print line. In addition, there is a 3 point
gap between the character on the third imaged record and the 12 point character on the second imaged record.
345
CA Easytrieve® Report Generator 11.6
Figure 15: Overprint Print Records
The following blocks illustrate the format of the data immediately prior to being combined onto the single print line. Printers
that support the Print Overprint technique prepare or image each print record independently. Although the following three
blocks are destined for the same print line, they have been separated for the purpose of this illustration.
Figure 16: Data format prior to Being Combined (2)
346
CA Easytrieve® Report Generator 11.6
To overcome the problem of characters overlaying one another, the Reporting Environment must build the print records
to provide the necessary spacing to separate the characters in the different print records. Each print record must provide
sufficient spacing characters so that when the record is imaged, the characters on the physical lines will not overlay each
other. The Reporting Environment automatically compensates for this characteristic.
The following diagram uses the same 7, 12, and 9 point print records to illustrate the format of the print records that do not
cause overlaying of characters. The reason is that the print records have been built compensating for the attributes of the
print overprint technique.
Notice that the first record requires four blanks in front of the printable character. When imaged, the four blanks of 7 points
each give 28 points of lateral spacing in front of the character, thus positioning the character to the right of the second
character. Not only must the Reporting Environment take this additional spacing into account when building the print
records, but it also must compensate for the gaps that appear between characters. For example, the 3 point gap between
the 9 and the 12 point character and the 4 point gap between the 12 and the 7 point character.
Figure 17: Print Records - Five
The following blocks illustrate the format of the data immediately prior to being combined onto the single print line. Printers
that support the Print Overprint technique prepare or image each print record independently. Although the following three
blocks are destined for the same print line, they have been separated for the purpose of this illustration.
347
CA Easytrieve® Report Generator 11.6
Figure 18: Data format prior to Being Combined
Function Codes
As opposed to using overprint codes, some printers require a sequence of Function Codes to define the control
information to the printer. The control information is used to define the type of data font, and so on. One implementation of
function codes is the ESCAPE sequences used by PC printers.
Function codes are not limited to one code per print record like overprint codes are. For more information about the font
header and trailer specifications, see Using the Configuration Manager.
Print Data
The format of print data that contains function codes is illustrated below:
Figure 19: Format of Print Data with Function Codes
Overprint and Function Codes
Another aspect of printing multiple fonts with line mode printers are those that support a combination of overprint and
function codes.
• The overprint code is used to establish the font to be used
• The function code is used to distinguish data type.
The techniques used to merge overprint codes are the same as discussed in the Overprint Codes earlier in this article.
348
CA Easytrieve® Report Generator 11.6
Print Data
The format of print data that contains both overprint and function codes are illustrated below:
Figure 20: Format of Print Data with Overprint and Function Codes
Limitations
When placing items on a page, alignment is limited to a combination of the available fonts. The reason is that the
Reporting Environment cannot line up a given item in a particular column. When this occurs, the alignment is slightly to
the right so any previous data will not be overlaid.
Conversion Aids
This section contains conversion tables for IBM 3800 and Xerox printers.
IBM 3800 Printers
The IBM 3800 family of printers produces output with 240 dots (PELs) per inch resolution. The following conversion aids
should be used when working with IBM printers:
Width (Points) Pitch (Chars per inch/CPI)
7.2 10
6 12
4.8 15
Note the following:
• 1 point = 1/72 inch
• 72 points = 1 inch
Formula for converting Points to Pitch:
72/points = pitch
Formula for converting Pitch to Points:
72/pitch = points
The height of a line cannot be controlled in Line Compatibility mode. It is controlled by the font itself and the FCB specified
on the JCL statement.
349
CA Easytrieve® Report Generator 11.6
XEROX Printers
The XEROX 8700 and 9700 printers produce output with 300 dots per inch resolution. The following conversion aids
should be used when working with XEROX printers:
Width (Dots) Pitch (Chars per inch/CPI)
30 10
22 13.6
20 15
Note the following:
• 1 dot = 1/300 inch
• 300 dots = 1 inch
Formula for converting DOTS to Pitch:
300/dots = pitch
Formula for converting Pitch to DOTS:
300/pitch = dots
Height (Dots) LPI (Lines per inch)
50 6
37 8.1
28 10.7
24 12.5
Formula for converting DOTS to LPI:
300/dots = lpi
Formula for converting LPI to DOTS:
300/lpi = dots
Page Printers
The Reporting Environment does not currently support Page Mode or "All Points Addressable" (APA) printers.
Printer Characteristics
This article explains the printer characteristics that CA Easytrieve® Report Generator uses to generate the correct print
data set for the appropriate extended reporting printer. The three types of printer characteristics are:
350
CA Easytrieve® Report Generator 11.6
Printer Type
The printer type defines the method that is used to build print records and defines how different fonts are combined onto
the same print line. The supported printers use different techniques to identify fonts and print items within a print record.
The six categories of printers that CA Easytrieve supports are shown in the following diagram.
NOTE
CA Easytrieve does not currently support page printers (category 1).
351
CA Easytrieve® Report Generator 11.6
Figure 21: Printer Type
Page Printers
In contrast to line mode devices, which associate one print record with one print line, page printers are devices that
process a data stream containing printer commands and print data.
352
CA Easytrieve® Report Generator 11.6
NOTE
CA Easytrieve does not currently support page printers.
Line Mode
Line mode printers support print data sets whose print records contain data and control information particular to a line.
Line mode printers restrict control of mapping print items to a page allowing only the positioning of items along the current
line. At the start of each print record, carriage control codes control the vertical position on a page.
Line printers can be further divided into six more finite classifications that are based on their ability to support overprint
and function codes in the print record.
Overprint Codes
Printers that support only one font per print record use overprint codes. Therefore to combine more than one font on
a print line CA Easytrieve must build multiple print records. However, a print item is only output on the print record
whose overprint code matches the overprint code of that print item font. Line spacing occurs before the first print record.
Each additional print record overprints the first. The printer then merges all the print records to form one print line. CA
Easytrieve uses two methods of merging print records depending on the extended reporting printer characteristics. The
two methods are merge overprint and print overprint. This article explains both of these overprint methods.
The overprint feature is a function of the printer hardware. For both overprint techniques, CA Easytrieve generates
multiple print records containing the required data and printer control codes. However the layout of the data in the print
records that CA Easytrieve produces for each overprint technique must be different for the print items on the report to line
up properly. This becomes evident upon examining the different techniques.
The following diagram illustrates the overall structure of the print records built for printers that support overprint codes.
Figure 22: Structure of the Print Records Built for Printers that Support Overprint Codes
Function Codes
Printers that support both control and print data in the same print record use function codes. Printer manufacturers assign
the control information special values (function codes) that identify it from the normal print data. The printer does not print
353
CA Easytrieve® Report Generator 11.6
function codes on the report but uses them to define the function that is to be performed. A function code defines the
format of the data (EBCDIC or DBCS), the size of the characters, and so on.
The following diagram illustrates the structure of print records that are supported by function code printers:
Figure 23: Structure of Print Records Supported by Function Code Printers
Overprint and Function Codes
The third major category of line mode printers includes those that support both overprint and function codes in the same
print record. These printers use the overprint code to establish the font of the characters to be printed (size, style, shape,
and design). They use function codes to distinguish one Data Type from another. That is, to distinguish EBCDIC from
DBCS.
Because these printers support an overprint code, the printer combines multiple print records to form a single print line
when CA Easytrieve requires a mixture of fonts on one line. As previously mentioned, the two techniques applicable to
combining multiple print records are merge overprint and print overprint. These same techniques are also applicable to
this category of printer.
The following diagram illustrates the format of the print records built for this type of printer:
Figure 24: Print Records Format
354
CA Easytrieve® Report Generator 11.6
Overprint Techniques
Merge overprint and print overprint are two supported techniques for overprinting multiple print records to form a single
print line. The printer hardware defines the technique that is used. The characteristics of the appropriate technique that
the extended reporting printer uses are automatically compensated for.
Merge overprint merges the print records by character position in the print record.
Print overprint combines the print records by their physical position in the final print line. The results of the print overprint
technique are similar to those obtained when overprinting on an impact line printer.
Merge Overprint
When merging multiple print records into a single print line, the merge process combines the data on a character by
character basis. For example, the 12th character in a print record merges with the 12th character in another print record.
This happens regardless of where those characters might otherwise appear on the print line (as a result of differences in
character width). The rules that the printer uses to merge print records of the same or different font widths into one print
line are:
• A printable character in a following record replaces an identical character or a blank.
• A blank in a following record does not replace either a blank or a printable character.
• A printable character trying to replace a previous printable character different from itself results in a data check, and
the character in the new record does not replace the character in the previous record.
• When merging blanks of different W-units, the resulting blank has the W-unit of the first one.
• When a printable character is merged with a blank, the resulting character has the W-units of the printable character.
To illustrate this process, assume that three print records are being merged and the W-units are in points. The first record
contains 7 point characters, the second contains 12 point characters, and the third contains 9 point characters. Each print
record contains four characters (three blanks and one printable character in each case). The following diagram illustrates
the three print records and the resulting print line.
355
CA Easytrieve® Report Generator 11.6
Figure 25: Print Records Resulting Print Line
Print Overprint
The print overprint technique overprints print records the same as does a normal impact line printer. The printer develops
the image (or images) of each print record independent of any other print record for the same line. The imaged or physical
lines are combined. With this technique you can have one character from one print record overlay another character
because the physical images of the two records occupy the same position on the line.
To illustrate this technique, the same three records that demonstrate the merge process are used. That is, 7, 12, and 9
point print records. As the following diagram illustrates, the independent imaging of the three records results in an overlap
of character boundaries.
For example, the character from the first record is overprinted by the character on the second imaged record because
they occupy the same physical space on the print line. In addition, there will be a three point gap between the character
on the third imaged record and the 12 point character on the second imaged record.
356
CA Easytrieve® Report Generator 11.6
Figure 26: Overprint Print Records
The following blocks illustrate the format of the data immediately before being combined onto the single print line. Printers
that support the print overprint technique prepare or image each print record independently. Although the following three
blocks are destined for the same print line, they have been separated for the purpose of this illustration.
357
CA Easytrieve® Report Generator 11.6
Figure 27: Data Format prior Combination onto Single Print Line
To overcome the problem of characters overlaying one another, CA Easytrieve must build the print records to provide
the necessary spacing to separate the characters in the different print records. Each print record must provide sufficient
spacing characters so that when the record is imaged, the characters on the physical lines will not overlay each other. CA
Easytrieve automatically compensates for this characteristic.
The following diagram uses the same 7, 12, and 9 point print records to illustrate the format of the print records that do not
cause overlaying of characters. In this case, the print records have been built compensating for the attributes of the print
overprint technique. Notice here that the first record requires four blanks in front of the printable character.
When imaged, the four blanks of 7 points each give 28 points of lateral spacing in front of the character, thus positioning
the character to the right of the second character. CA Easytrieve must consider this additional spacing when building
the print records and must also compensate for the gaps that appear between characters. For example, the 3 point gap
between the 9 and the 12 point character, and the 4 point gap between the 12 and the 7 point character.
358
CA Easytrieve® Report Generator 11.6
Figure 28: Print Records Format Not Causing Overlaying of Characters
The following blocks illustrate the format of the data immediately before being combined onto the single print line. Printers
that support the print overprint technique prepare or image each print record independently. Although the following three
blocks are destined for the same print line, they have been separated in this illustration.
Figure 29: Data format prior to Being Combined
359
CA Easytrieve® Report Generator 11.6
Paper Control Codes (Carriage Control)
The paper control code identifies the method that is used to control vertical positioning on a page. The supported printers
use different techniques to control the vertical position on a page. Most printers support the ANSI carriage control and
support a Forms Control Block to enable the definition of line spacing. In addition to the ANSI system, the Extended
Reporting Facility supports four other techniques. The following diagram illustrates each of the techniques that is used to
control the vertical position on a page. This document explains each technique before discussing the technique that each
printer supports.
NOTE
CA Easytrieve currently does not support page printers.
Figure 30: Page Position Control
Page Printers
Page printers use structured fields to support "All Points Addressable" printing.
NOTE
CA Easytrieve currently does not support page printers.
360
CA Easytrieve® Report Generator 11.6
Line Mode
When using a printer that processes print records corresponding to print lines, CA Easytrieve uses the paper control code
to define the vertical positioning to be performed before printing a print record. The paper control code is positioned at the
start of each print record. The extended reporting facility supports these four paper control codes:
• ANSI Carriage Control plus a Forms Control Block
• Machine Carriage Control Codes plus a Forms Control Block
• ANSI Carriage Control with no Forms Control Block
• Point Skip vertical spacing control
ANSI Carriage Control with a Forms Control Block
This form of line mode carriage control indicates that the extended reporting printer supports a Forms Control Block
and that print records can use ANSI carriage control codes for paper control. When using an FCB, values in the FCB
define the line spacing that the printer is to use. A print record then provides the appropriate ANSI code for skipping the
appropriate number of lines. The printer determines the vertical spacing from the line sizes that are defined in the FCB.
Control over the paper is restricted to the ANSI codes. The values set in the FCB dictate the amount of space that is
skipped for any one line. The FCB parameter on the OS JCL DD or OUTPUT statement for the report data set specifies
the FCB that any extended reporting output uses. For DOS, the LST JCL statement defines the FCB.
A line counter of a report output to an ANSI plus FCB printer is maintained by incrementing the line counter by the number
of lines that are skipped for a particular print record. Therefore the line counter indicates the number of lines that are
processed on the current page. This value does not indicate the vertical spacing in H-units. You could obtain this value by
multiplying the value of the line counter by the H-units for each printed line that is defined in the FCB.
Machine Carriage Control Codes with a Forms Control Block
This form of line mode carriage control is processed exactly like ANSI codes except that the value of the carriage control
codes are the machine code equivalents of the ANSI codes.
ANSI Carriage Control with No Forms Control Block
This printer supports ANSI codes but the height of each line is dependent upon the height of the tallest font in the current
line and the height of the tallest font in the previous line. The larger of these two values is the amount of vertical space
that is allocated to the current line. In other words, the height of the current line is determined by the height of the tallest
font in use in the previous line except when the height of the tallest font on the current line is greater. In this situation,
the height of the tallest font in use on the current line defines the height of the current line. Therefore, if printing fonts of
different heights on the same report, the height of each line on the report varies. Fonts of equal height result in equal
spacing between lines on the page.
For this category of printer, the ANSI carriage control characters are used but all line skipping is output using the font that
defines the printer default height (see the default size specification for a printer in Using the Configuration Manager). This
means that all blank lines print at the default height of the extended reporting printer.
Also, to ensure that the first line on any new page has the same displacement from the top of the form, a blank line is
printed as the last record before the top of form print record. This print record uses the font that defines the printer default
height.
The line counter for a report on this type of printer is updated by maintaining the vertical positioning as a count of H-units.
The value of the line counter is determined by performing the following calculation:
(Total number of H-units printed)
--------------------------------
(Base height value assigned to
361
CA Easytrieve® Report Generator 11.6
this extended reporting printer)
The line counter value is always rounded up to give the maximum displacement down a page.
Point Skip Vertical Spacing Control
The printer uses a special function code to start a new line if the ANSI carriage control for vertical spacing is not
supported. The largest H-unit of the fonts that are defined to appear on the new print line determines the spacing between
the baseline of the current line and the baseline of the new line. The new line request can include vertical spacing in
addition to the vertical spacing generated by the new line request. This function is referred to as point skip processing.
CA Easytrieve performs the following steps to perform line feed operations:
1. Obtain the H-unit for the highest font to be printed on the line.
2. Using the H-unit that is defined as the base height for this extended reporting printer, the H-unit of the tallest font is
rounded up to a multiple of this base height. This gives the amount of vertical space that is assigned to this print line.
The value that the largest font H-unit was adjusted up is the value of the point skip operation. That is, all the print lines
occupy a vertical space amount that is a multiple of the base height.
3. By dividing the vertical space amount by the base height, CA Easytrieve obtains the amount that it adds to the line
counter for this line. Therefore the line counter is maintained as a multiple of the base height setting in the extended
reporting options module.
The skipping of blank lines is in multiples of the defined base height for the extended reporting printer. This means that a
request to skip one and then print a line containing 8 point characters where the base height is set to 9 point lines (eight
lines per inch), results in a point skip of 10 points (nine points for the blank line and one point for the adjustment to the
print line to round it up to a multiple of the base height).
362
CA Easytrieve® Report Generator 11.6
Figure 31: Printer Control Code Systems
File Type
The file type defines the attributes of the print data set that CA Easytrieve creates as print records are output. Reports
are output to data sets. The product is not concerned with whether the data sets may be under the control of a spooling
system, like JES and POWER, or whether the data sets are normal disk and/or tape files that are not controlled by a
spooling system. A data set that CA Easytrieve builds as a result of printing operations using the Extended Reporting
Facility must contain the records in a format that the extended reporting printer supports. The format of this data set varies
depending upon the printer you are using.
For line mode printers, a print data set consists of three types of records. The following diagram illustrates these records:
363
CA Easytrieve® Report Generator 11.6
Figure 32: Print Data Set
File Header Records
File header records are defined in the extended reporting options module. File header records output information
necessary to initiate the printer for the print records that follow. The file header records are output immediately after
opening the file, but before any print records are output.
Print Records
Print data sets consist mainly of print records. Each print record that the extended reporting facility builds can contain up
to four components:
• Carriage Control -- The Carriage Control code always starts the record.
• Overprint Code -- The Overprint Code is only required for printers that use multiple print records to support mixed fonts
on one print line. If required, this code always follows the Carriage Control code.
• Function Codes -- If a printer requires special control codes in the print record to identify different fonts and data types,
then CA Easytrieve mixes Function Codes with Print Items in the print record. Function Codes are not present for
printers that do not require such control information.
• Print Items -- Print Items include fields and literals that contain the data for the final print line. When the printer requires
Function Codes, CA Easytrieve mixes print items with Function Codes in the print record. If the printer does not require
Function Codes, the print record only contains Print Items.
364
CA Easytrieve® Report Generator 11.6
The maximum length of a print record is the maximum record length of the print data set that receives the record. A
runtime error occurs if a print record exceeds that size. This error stops the execution of the program and results in the
printing of an error message.
File Trailer Records
File trailer records are similar to the file header records. File trailer records contain control information and are defined in
the extended reporting options module. Each file trailer record is a logical record on the print data set. Before closing the
file, these records are output to the data set after the last print record is output.
File Format
The format of a print data set defines the relationship between print records that CA Easytrieve builds and the physical
records that are output to the data set. The three formats for a print data set that the extended reporting facility supports
are: unblocked records, blocked records, and concatenated records. The following diagram illustrates the three formats:
Figure 33: Print Data Formats
Blocked Records
This file type supports logical records that are either fixed or variable in length. CA Easytrieve combines the records to
form a block.
365
CA Easytrieve® Report Generator 11.6
CA Easytrieve builds variable length print records. Their size is the minimum that is required to contain the components
required to produce the print line. For print data sets that support variable length records, the length of the print record
remains the same. For files requiring fixed-length records, CA Easytrieve must pad the print record to fit into the defined
record length. The padding operation uses two attributes of the extended reporting printer that you must identify in the
extended reporting options module. A record-end string defines one or more control characters that delimit the print
record. The report-pad string defines one or more characters that begin immediately after the record-end and continues to
the end of the record.
Unblocked Records
This file type is similar to the blocked records format except that each logical record is also a physical record.
CA Easytrieve builds variable length print records. Their size is the minimum that is required to contain the components
required to produce the print line. For print data sets supporting variable or undefined record lengths, The print record
is output using the length of the original print record. For fixed-length record print data sets, CA Easytrieve must pad
the print record to fit into the defined record length. The padding operation uses two attributes of the extended reporting
printer that you must identify in the extended reporting options module. A record-end string defines one or more control
characters that delimit the print record. The Report-Pad string defines one or more characters that begin immediately after
the record-end and continues to the end of the record.
Concatenated Records
Externally, this file type looks like the unblocked file format. In contrast though, this file type concatenates logical
records of varying lengths into one long data stream of print records. Each time a print line is output, it concatenates the
associated print records onto the end of the file's current physical record. The physical record is output only when a print
record does not fit into the remainder of the file's physical record area. This process is similar to the building of a block
consisting of variable length records except with concatenated records, the four-byte RDW (Record Description Word) that
contains the record length is not added to the start of the record.
When a print record length exceeds the maximum record length of the print data set, a runtime error occurs.
For file types using variable and undefined record formats, the length of the output record equals the total of all the
concatenated print records that fit into the maximum physical record.
To support the fixed-length physical record (that is "F lrecl") with the concatenation option, the extended reporting options
module must identify a record-end and a record-pad string. Because CA Easytrieve generates print records that are
variable in length, there is no guarantee that each block ends at the end of the fixed-length physical record. Therefore, to
fill out a block, CA Easytrieve inserts a record-end string immediately after the last print record. CA Easytrieve adds the
pad string to the end of the physical record starting immediately after the record-end string.
This file format requires separate consideration with structured field printers and line mode printers.
Concatenated Records (Line Mode)
For line mode printers, CA Easytrieve concatenates output records except for file trailer records. For concatenated
records, the file trailer records are output at the start of their own physical record. The last physical record containing print
records is output before the print data set is closed. Then CA Easytrieve concatenates the file trailer records at the start of
a new physical record. This new record, once built and output, is the last one on the print data set. The following diagram
illustrates this relationship for Line Mode print data sets requiring concatenated records.
366
CA Easytrieve® Report Generator 11.6
Figure 34: Line Mode With Concatenated Records
Font Characteristics
In addition to defining the characteristics of the extended reporting printers, you also must define the fonts that a program
can use in a print line.
Contents
In terms of this discussion, a font is a collection of graphic characters of a given typeface and size. You must define fonts
in the extended reporting printer set definition. Fonts are associated with an extended reporting printer and each one is
given a unique font identifier number (1 to 256).
367
CA Easytrieve® Report Generator 11.6
It is the font identifier that you code in a program to associate the characteristics of a font to a print item, such as a field or
a literal. Using these characteristics the Extended Reporting Facility is able to position the item correctly on the print line
(using the W-unit and H-unit assigned to the font) plus build the print record(s) to produce the correct results.
The following diagram illustrates the use of a CA Easytrieve® Report Generator font identifier:
Figure 35: CA Easytrieve Font Identifier
Height and Width
For each font that the extended reporting options module defines, you must define the width of the font as a number
expressed in terms of the selected W-units. CA Easytrieve® Report Generator only requires the definition of the height of
a font when the Carriage Control system of the extended reporting printer does not support the ANSI or Machine systems
in association with a Forms Control Block (FCB). When CA Easytrieve® Report Generator requires the height definition,
you must define it as a number expressed in terms of the selected H-units.
Overprint Code
If the extended reporting printer supports Overprint Codes, all of the fonts associated with that printer must include the
Overprint Code. The FONT specification defines the overprint code.
Function Header and Function Trailer
If the extended reporting printer supports Function Codes, you must specify either the Function Header, the Function
Trailer, or both. You specify these attributes by using the FONT specification.
Space Replacement
For printers that support Overprint Codes and use the Merge Overprint technique to combine print records, the space
character is important.
The reason that the space is important is best demonstrated by an example. In the following diagram, a CA Easytrieve®
Report Generator DISPLAY statement builds a print line containing three literals. The first and third literals are to be output
as 7 point characters and the second is to be output at 9 point. Assuming the printer supports Overprint Codes and uses
the Merge Overprint technique, CA Easytrieve® Report Generator builds two print records. The following diagram also
demonstrates these records and the resultant print line. Note the way that spaces in the first print record are replaced
by non-blank characters in the second. Note also that a space in all the print records prints a space whose size is that
defined by the font of the first print record.
368
CA Easytrieve® Report Generator 11.6
Figure 36: Print Records and Resultant Print Line
CA Easytrieve® Report Generator automatically compensates for space replacement when it assigns fields to print
positions on a print line and when it determines the spacing between print items. However, CA Easytrieve® Report
Generator cannot directly control the occurrence of spaces in the fields or literals that it moves into print records. CA
Easytrieve® Report Generator assumes that each character in a print item is output at the same size; that size being
defined by the width of the print item's assigned font. CA Easytrieve® Report Generator prints the size of space characters
in an overprint record as the size of the space in the first record. The following diagram demonstrates this:
369
CA Easytrieve® Report Generator 11.6
Figure 37: CA Easytrieve Space Replacement
The previous diagram illustrates that a space in the second literal results in the character being positioned on the print line
using the 7 point space (as opposed to the 9 point space that was requested for the print item). The result of this process
is demonstrated by comparing the print line produced by this diagram with the following diagram.
370
CA Easytrieve® Report Generator 11.6
Figure 38: Print Line with no Space in Second Literal
The previous example illustrates that the size of the second character in the second literal coded on the DISPLAY
statement now prints at 9 point (as opposed to the space character in the previous example that printed at only 7 point).
The presence of the space in the literal (as opposed to a non-blank character) causes the characters that follow the space
character to shift left 2 points on the print line. This is not an error but a feature of the printer. CA Easytrieve® Report
Generator cannot prevent this from occurring. CA Easytrieve® Report Generator does compensate for spaces between
print items. CA Easytrieve® Report Generator does not compensate for spaces occurring within a print item. There are
three approaches that you can use to solve this problem.
1. Ensure that the fonts being mixed on one print line all have the same W-unit width.
2. Ensure that any field or literal that occurs on a print record other than the first does not contain spaces.
3. Define an alternative space within each font set that CA Easytrieve® Report Generator uses. Nothing prohibits
you from modifying a font set to replace one of the unused graphic characters with a space character. Once this
replacement space has been assigned to a font defined in the extended reporting options module, CA Easytrieve®
Report Generator automatically scans the contents of each field or literal that uses this font. The scan occurs after CA
Easytrieve® Report Generator moves the field or literal to the print record. The scan replaces all occurrences of the
normal space character with the replacement space. This ensures correct spacing on the report.
Line Complexes
A special printing feature of some extended reporting printers is the ability to define Line Complexes. For example, the
IBM 3200 and the HITACHI 8196 support the ability to expand a print item across multiple lines (2 or 4). This means that
the print items height is multiplied by the number of lines that the print item includes but its width remains the same. The
best way to describe a Line Complex is by a diagram.
As shown in the following diagram, a print item involved in a line complex must be included in all of the print records that
generate the print lines that the Line Complex covers. For a two line Line Complex, the print item must be included in the
371
CA Easytrieve® Report Generator 11.6
two print records that are combined to form the line complex. For four line complexes, the print item must be included in
four print records.
A font defined for an extended reporting printer that supports Line Complexes can include the Line Complex attribute.
CA Easytrieve® Report Generator then positions the print item assigned to such a font on the appropriate number of print
lines. It is up to you to ensure that no other print items are positioned in the same area of those print lines that a Line
Complex element occupies. If this occurs, a syntax error results.
372
CA Easytrieve® Report Generator 11.6
Figure 39: Two Line Line Complex
Set Up Source Control Supports
This article explains how to set up and use the following source code control products to manage application
development, and includes a sample session and information about how to get help:
373
CA Easytrieve® Report Generator 11.6
• Merant PVCS
• Microsoft Visual SourceSafe
The Workbench can support one or more of these products using a common interface, which, for typical source control
functions, masks the differences between the products.
All product names referenced herein are trademarks of their respective companies.
This article includes the following information:
Install Source Control Managers
Merant PVCS
To use this product for Source Control Management, Merant PVCS Version Manager 5.2.10 or higher and the PVCS
Version Manager Interface to Microsoft Development Environments V4.0 are required.
Verify correct installation by invoking the PVCS Version Manager.
The Workbench PVCS interface allows complete access to typical PVCS functions, including: file management, reports
and the PVCS Version Manager. Administrative and other functions not supported by the Workbench's File Source Control
menu must be performed via the PVCS Version Manager.
Microsoft Visual SourceSafe
Microsoft Visual SourceSafe V4.0 or newer is required to enable the Workbench interface to this product.
It is important that you install Visual SourceSafe on a server and then install the Visual SourceSafe client on every
client you will use to run the Workbench and Visual SourceSafe. This step is essential for the integration between the
Workbench and Visual SourceSafe to work. Verify correct operation by invoking the Visual SourceSafe Explorer.
The Workbench interface to this product allows complete access to typical SourceSafe functions, including: file
management, reports and the SourceSafe Explorer. Administrative and other functions not supported by the Workbench’s
File Source Control menu must be performed via the SourceSafe Explorer.
Select Your Source Control Manager
One or more of the source control managers discussed in this section may be installed on your system. The Workbench
can use any one of the installed products at any time. You simply select the desired product using the Source Control
Options dialog.
To access the Source Control Options dialog, select the Options menu, then select Source Control.
The Source Control Options dialog contains:
• User Name field -- Identifies the user. If no User Name is specified, then the User Name specified during your
Windows login is passed to the source control manager. (The User Name field should only be used to override the
User Name established during Windows login.)
• Source Control Provider list box -- This drop-down list box displays all of the source control managers installed on your
system. You can switch to any installed product at any time.
• Advanced button -- Accesses any source control options specific to the manager. This feature may not be available for
every source control manager.
NOTE
The Advanced button is not supported by all products; in these cases, it is disabled.
374
CA Easytrieve® Report Generator 11.6
Handling Differences Between Products
The Workbench determines the capabilities of the selected source control manager when it initializes communication with
that product. After source control manager initialization, the supported functions are enabled.
NOTE
Unsupported functions are disabled in the menus and associated dialogs. For example, the product might not
support the capability of directly removing files from source control; thus, the File menu Source Control Remove
from Source Control command is grayed out.
Access Your Source Control Manager
To access your source control manager, use the Workbench File menu. The Source Control menu item has a submenu
that contains all of the Workbench Source Control functions.
Most typical source control functions are provided directly by individual menu items. These functions include:
• Selecting source control projects
• Managing files with the following commands:
– Get latest version
– Check out
– Check in
– Check undo
– Add to source control
– Remove from source control
• Generating common reports
– History report
– Difference report
– File properties report
For these common functions, the source control interface is independent of any particular product.
Depending on the product's capabilities, some functions may be disabled. For example, not all products allow you to
remove files from source control. In those cases, the Remove from Source Control menu item is disabled.
Options specific to the active source control manager can be accessed by clicking the Advanced button, which is present
on many of the common source control dialogs.
Source Control Manager
The Workbench also provides the ability to invoke the product's main application by selecting the File, Source Control,
Source Control Manager command. This command accesses the application as if you had selected it directly from
Windows to perform product-specific Source Control functions.
Use the Source Control Manager to perform any source control function that is not directly supported by the Source
Control menu. Typical functions, which are performed using the Product-Dependent Interface include:
• Creating and modifying source control projects
• Performing any source control maintenance not directly supported by the common interface
• Generating any reports not directly supported by the common interface
Create a Workbench Application
Once your source control projects have been defined, you can create your applications. An application retains the name
of the source control manager and the name of the selected project. When an application is opened, the related source
control manager and the previously selected project are also opened.
375
CA Easytrieve® Report Generator 11.6
NOTE
Remember to save new applications when you close the application or exit the Workbench. Click Yes when
prompted to save the changes.
Add New Files to Source Control
Once you set up the source control project for your application, you can add files to the source control project.
NOTE
If you are an existing source control user and files have already been added to the source control system, you
do not need to perform this step.
• Utilities -- Describes CA Easytrieve Report Generator Workbench utilities.
• Sample Sessions -- Steps you through a typical development and test cycle using the PERSONEL sample application.
Sample Session
In this session, you will set up a source control project.
Prerequisites
Before you can perform any source control tasks, you must meet the prerequisites.
Follow these steps:
1. Install CA Easytrieve Report Generator in the Windows environment.
2. Install one or more source control managers:
– Microsoft SourceSafe
– Merant PVCS
– CA SCM
3. Select an installed source control manager for your specific development project.
4. Perform administrative source control management tasks, such as:
– Adding users and groups to the development team
– Defining projects
You must do these tasks from within the source control manager.
5. Use CA Easytrieve Report Generator to create an application.
Once these tasks have been completed, you can set up a source control project and add files to it.
Select a Project
Follow these steps:
1. Start CA Easytrieve Report Generator Workbench.
2. From the File menu, point to Source Control, then choose Select Project.
The Create local project from (source control) dialog appears.
Note: This example uses SourceSafe. Other source control managers display appropriate dialogs.
3. Click Browse, then select the local folder you want to use for storing the project files.
4. Select the desired project in the source control section and click OK.
This makes the connection between the source control application and the local folder. In the example, files can be
transferred between the sample folder and the local EZTPGMS folder.
You can now access the files using the following commands on the File, Source Control menu, if supported by the
source control manager.
376
CA Easytrieve® Report Generator 11.6
– Get Latest Version
– Check Out
– Check In
– Undo Check Out
– Add to Source Control
– Remove from Source Control
Workbench
The CA Easytrieve Workbench is a Windows application that lets you build, run, and debug CA Easytrieve Report
Generator programs.
Start the Workbench
To start the Workbench click Start, Programs, CA, Easytrieve, Easytrieve Workbench.
The CA Easytrieve Workbench main window appears.
Messages
All system information, error, and warning message are described in the Messages and Codes section.
Environment Variables
The CA Easytrieve Report Generator for Windows installation creates many files and sub-directories. These directories
are referenced using the following environment variables and values:
Environment Variable Default Location
EZTOPTS C:\Program Files (x86)\CA\Easytrieve\Macros
CA_EZTSettings C:\Program Files (x86)\CA\Easytrieve\Bin
Throughout this section, EZTOPTS and CA_EZTSettings refer to the path values associated with these environment
variables.
Sample Programs
Sample programs are located in the EZTpgms directory in the directory pane of the main window. For example:
c:\Users\user\Documents\EZTpgms
Using the Workbench
Main Window
The main window in a CA Easytrieve® Report Generator Windows session contains a menu bar at the top and a status
bar at the bottom. The area between these two objects is known as the client area and is typically occupied by one or
more windows. Each document window displays a portion of an analysis or edit file as follows:
• Use edit windows to modify source (.EZT) and macro (.MAC) files, as well as other files. You can edit any ASCII file.
Use the keyboard and edit commands, such as cut, copy, and paste to make changes. For more information, see Edit
Source or Text Files.
• Use analysis windows to display analytical information in .CVX files, which are created each time you compile a
program. Analysis windows are read-only; they let you perform static analysis and debugging. Analysis and debugging
377
CA Easytrieve® Report Generator 11.6
of a CA Easytrieve® Report Generator program always begins by opening the .EZT file, which detects if the program
has been compiled and the .CVX file exists. If so, debugging and analysis becomes enabled.
Contents
Title Bar
Each document window has a title bar that uniquely identifies it. The title bar for an edit window always contains the name
of the file being edited. The title bar for an analysis window contains a shorthand notation as follows:
filename(n) windowid /progname
• filename
The name of the file.
• (n)
The WorkSheet instance (1-15).
• Windowid
The type of window (WorkSheet or Twin).
• lbl=lblname
Used only for a WorkSpace window where:
– lbl FLD
Field definition name.
– Lblname
The name of the field.
• Progname
The name of the program, which might not be the same as the file name.
Examples
The following identifies the window as the first WorkSheet for a file named myupdte containing the source to a program
called myupdate:
myupdte(1) WORKSHEET/myupdte
The following identifies the window as a WorkSpace open on a file called myupdte, but contains just the subactivity portion
of the program. It is associated with the first WorkSheet.
myupdte(1) FLD=LASTNAME/myupdte
Toolbar
Use the toolbar buttons instead of the commands from the main menu. To get a brief description of the function of a
toolbar button, move the mouse to a toolbar button and read the brief help that appears in the pop-up window. Whenever
possible, procedures in this section use the toolbar button.
To move the toolbar, place the mouse pointer on an empty portion of the toolbar until the grabber hand appears. Then
click and hold the left mouse button while dragging the toolbar to another location in the Workbench window.
Status Bar
The status bar at the bottom of the window displays messages and information about the active worksheet. If the cursor
in the analysis window is on a data item, information about the type and size of the data item is displayed, otherwise the
following is shown.
378
CA Easytrieve® Report Generator 11.6
• Color Button
Click to change the current color that is used to highlight analysis files.
• Ln
Displays the current line number in the file.
• Col
Displays the current column number in the file.
• Pgm=
Displays the program name for a worksheet
• Activity=
Displays the current location of the worksheet: job, sort, or file activity name, a report sub activity or procedure name.
When the Debugger is active the following are also present:
• Debug Button
Click in a debugging session to execute the next debug command, such as Monitor, Initiate, or Run.
• Status Light
Indicates the current state of the debugging session, such as halted
You can also view messages from the compiler as well as abbreviated help for all menu commands on the status bar. In
addition, while in an analysis file, when you select a data item, the status bar displays its type. When you select a quoted
literal, the status bar reflects it as a string.
WorkSheet Windows
Whenever you open a .CVX file, the Workbench opens a window called a WorkSheet window. A WorkSheet window
initially starts as a Tree view, but can be toggled between Text and Tree views.
All WorkSheets have the word WORKSHEET in their title bar to help you identify them. You can have any number of
WorkSheets open at the same time for a file. Each WorkSheet is managed separately from the other WorkSheets so that
each can represent an entirely different set of analysis queries. A query in one WorkSheet has no effect on the content
of any other WorkSheet. For example, you can hide everything but move verbs in one WorkSheet while showing all
statements in another.
Twin Window
You can split a worksheet into a Twin window. A twin window shows a Tree view in the left-hand pane and the Text view
in the right-hand pane. The panes are closely related so that when you select text in one pane, the other pane scrolls to
match. This feature lets you navigate conveniently through large source files by using the Tree view as an outline of the
source shown in the Text view. To view the twin window, select the View menu and choose Twin.
Selecting a node in the Tree view causes the Text view to scroll to the first line of the matching source code. Selecting text
in the Text view causes the Tree view to scroll to reflect the new selection.
Workspace Windows
A WorkSpace is a Text-only window that contains the text for all of a program or any labeled subset of a program. The
WorkSpace lets you restrict analysis to just one section of code. For example, you can double-click a PROC statement to
open a WorkSpace with the procedure you selected. You can open as many additional WorkSpaces as you need.
WorkSpaces are different from WorkSheets:
• WorkSheets can be toggled between the two view modes: Tree and Text. WorkSpaces can be viewed in Text mode
only.
• WorkSheets always contain a complete program while WorkSpaces can be opened on a subset of a program, such as
a JOB activity, a procedure, or any data definition. A WorkSpace can also be opened on the entire program.
379
CA Easytrieve® Report Generator 11.6
A WorkSheet can have any number of WorkSpace windows open on it. The portion of the file shown in the WorkSpace
can also be shown simultaneously in other WorkSpaces. For example, you can define one WorkSpace for an entire
Procedure, while another is defined for a section in the procedure, and another for a line in the section, and so on.
Analysis commands performed on a WorkSheet affect every WorkSpace opened on that WorkSheet. For example, if you
hide all statements in a WorkSheet, all WorkSpace windows opened from that WorkSheet have all of their lines hidden.
Conversely, if you hide all of the lines in a WorkSpace that is open on a single paragraph, the Text view of the WorkSheet
shows that paragraph as hidden.
You can use the WorkSheet in Tree view as a road map or table of contents to help you locate the various WorkSpaces
that you have open.
To use the WorkSheet in Tree view as a road map:
• Click the node to immediately view that object's WorkSpace window.
• Double-click any white space area (anywhere there is no text shown) in the WorkSpace
To switch between a WorkSheet and Workspace:
1. Use the Tree view of the WorkSheet to locate a WorkSpace, and then double-click a label. You are placed in a
WorkSpace for the selected object.
2. Double-click in any non-text (white space) area and you are placed back in the tree.
3. Double-click another branch in the tree.
This is an example of how you can use just a series of double-clicks to quickly locate windows in CA Easytrieve® Report
Generator without having to search the list of open windows in the Window menu.
Selecting Objects in a Window
You can select objects such as verbs, data items, files, labels, and strings in an analysis window with a click of the left or
right mouse button. The left mouse button selects the object while the right button opens a pop-up menu of commands for
that object.
To select an object, place the cursor over the object and click the left mouse button.
Pop-up Menus
A pop-up menu is a context-sensitive list of commands available for a selected object. Pop-up menus let you choose a
command without returning to the menu bar. A pop-up menu appears when you click the right mouse button on a selected
item, or when you place the cursor on an object and click the right mouse button. The selected item can be in the Tree
view or any word in Text view.
The words that you can select in a Text view window for a CA Easytrieve® Report Generator program include:
• Labels
The naming label for a procedure.
• Label references
Any reference to a procedure name.
• File references
Any reference to a file -- implicit or explicit. For example, a PUT statement implies the file to which the record belongs.
• Data items
Any data item defined in the Library Section but selectable from any portion of the program.
You can also invoke pop-up menus from the Tree view by right-clicking a node.
380
CA Easytrieve® Report Generator 11.6
Context Sensitivity
All commands are sensitive to the selected object. For example, you select a data item, PAYROLL-AMT, from a
statement in a JOB activity like: MOVE ZEROES TO PAYFILE:PAYROLL-AMT. The selected object refers to the data item
PAYROLL-AMT as defined in the PAYFILE FILE definition. If there are other data items called PAYROLL-AMT within other
FILE definitions, then they are completely excluded from the processing of commands invoked when this specific instance
of PAYROLL-AMT is selected.
You can select strings and use analytical capabilities to locate references to strings, but the real power of CA Easytrieve®
Report Generator Workbench lies in its ability to perform object-specific actions on instances of a selected object.
Whenever you select a verb, file reference, data item, label, or label reference, all of the commands that you issue apply
to the selected object only -- not to similar strings.
The status bar is usually updated with the record number and column position of the selected object. There are two
exceptions:
• If the selected object is a quoted literal string, a hexadecimal notation of the string is displayed in the status bar.
• If the selected object is a data item, its size in bytes and type are displayed in the status bar.
Opening Windows
This article describes how to open windows in a WorkSpace.
Contents
Open a Window
You can open a window by double-clicking an object. Use this technique to open a window from:
• Any word in a Text view that refers to a program, job, procedure, or data item. Also included are statements in a JOB
activity with a reference to a data item or file name, and all references to procedures in transfer of control statements,
such as PERFORM.
• The labels to the right of the icons in the Tree view.
You can also use the Window menu to open, close, and arrange windows. All open windows are listed at the bottom of the
Window menu in the window cache. Selecting a window from the list brings the selected window into focus.
Open a Window on a Selected Label
To open a WorkSpace window on a selected label, select the View menu and choose the Open Window On command.
The window displays just that section of the program.
Unlike the View Jump To command, the View Open Window On command does not reposition you; it opens a window on
the selected label and overlays the active window. After you finish reviewing the selected paragraph you can close the
window.
NOTE
You can open a window on a label by double-clicking the label name, or clicking the right mouse button to get a
context-sensitive pop-up menu of the commands available for processing labels.
In the following screen, the GET_FIELD_DATA label was highlighted and Open Window On was selected from
the View menu. The result is a new window containing GET_FIELD_DATA Procedure.
This feature lets you look at the code in GET_FIELD_DATA without losing your place in the current activity. (Use the
Windows Tile command to neatly arrange all of your open windows without any overlapping.)
381
CA Easytrieve® Report Generator 11.6
Manage Files and Applications
This section describes how to open, print, and save files, group files using the application commands, and perform change
and version management using the source control commands.
This article includes the following information:
Open Files
Use either of the following methods to open a file:
• Select the file in the Workbench Explore window.
• Click File, Open. Select the file and click OK.
Save a File
Use any of the following methods to save your files:
• To save the file in the active edit window, click File, Save. Otherwise, close the active file. You are prompted to save.
• To save all files in open edit windows, click File, Save All.
• To automatically save open files at a specified time interval, click Options, File Save. Specify the time interval and
select the Enable Auto Save box.
NOTE
You can only save an analysis file (.CVX) as a text file (.TXT) while in text view using File Save As.
Set Save Options
The Save Options dialog lets you define the format of the program file that you want to save. It is similar to the View
Clone process in that the CVX file is converted back to source with only the non-excluded lines being saved to the
resulting output file. Once set, these parameters remain in effect for all subsequent files that you save until you change
the parameters either on this dialog or by using the View Exclude menu.
NOTE
The active file must be an analysis file (.CVX) in Text view.
Follow these steps:
1. Click File, Save As, and then click the Options button.
2. Press F1 for help on the File Save Options dialog.
3. Select the following types of statements to exclude:
– Macro Source -- When checked, the file is saved without any of the expanded macros within the source code.
– Comments -- When checked, the file is saved without any comments.
– Blank Lines -- When checked, the file is saved without including the blank lines.
– Click OK when you finish specifying options.
Print a File, View, or WorkSheet
The Print command lets you print all or selected pages of a file in an edit window, or the entire view range of the current
worksheet window. The view range includes all lines that can be displayed using the scroll bar. Your system default printer
and job properties are used unless you specify another configuration.
382
CA Easytrieve® Report Generator 11.6
• To print the Tree View of a program, make the Tree View the current window and select File Print. You can also print
Text views.
• To print an individual file definition or procedure of a program, open a WorkSheet window on the portion that you want
to print. For example, double-click a procedure name to open a WorkSheet showing just that procedure, and then
select File Print.
For information about the Print dialog, press F1 help.
Use Applications
Applications let you:
• Use a single command to load and open a series of files, or load and open selective files from the file list.
• Set compile, debug, and source control manager options for each application, so that switching among applications
automatically invokes the specific environment, options, and settings appropriate to it.
• Monitor any program in an application file list during a debug session, without having to first open the file. Instead, you
can simply select it from the file list.
Application File (*.APP)
An application is simply a file (*.APP) that associates a set of CA Easytrieve Report Generator options, including
debugging options and an optional set of program files, such as source, analysis, and macro files. Whenever the
application is open, CA Easytrieve Report Generator uses these options.
File List (*.FL)
A file list defines the individual files that are associated with an application such as the source files, analysis files, and
documentation or text files. The file list is then associated with the application. Keeping file lists separate from applications
allows programmers to share file lists, and applications associated with files at remote locations.
An application does not have to specify a file list, but doing so speeds file manipulation throughout the development cycle.
For example, you can open all source and macro files, all analysis files, or both using a single command. Or, you can
select specific files from a dialog to quickly open a few files at a time. In addition, any CA Easytrieve Report Generator file
in a file list can be monitored for a debugging session without first opening it.
Create an Application
Follow these steps:
1. Click File, Application, Open. For help, press F1.
2. Select the options that you require as follows:
– Load Analysis Files
Loads the analysis files.
– Save As Default
Automatically opens the application and any files that are checked by default when you open the Workbench.
3. Type a file name (for example, TEST.app) in the File Name field.
4. Click OK to create your application.
You have now created an application.APP file.
NOTE
Once you have created an application, you can open the source control manager project. In this way, the
Workbench always associates an application with a project.
383
CA Easytrieve® Report Generator 11.6
Open an Application
Follow these steps:
1. Click File, Application, Open. The Application Open dialog appears.
2. Select your desired application and click OK.
3. Check Save As Default to open the application every time you open CA Easytrieve Report Generator.
Edit an Application File List
After you open an application, you can edit the files that are listed on its file list using the File Application Edit File List
command.
Follow these steps:
1. Open the application.
2. Press F8.
3. Use the Edit Application dialog to perform any of the following tasks:
– To add another program module to the application, highlight your program in the File List box. Click Add.
– To remove a program module, highlight the program in the File List box. Click Delete.
– To view a Compile report on a CVX file, select a CVX file and click Details.
– To change the order that the application build process should process your files, select each file that you need to
move (in the bottom list box), and use the arrow buttons to change its position in the file list.
– To open all CVX files, select Load Analysis Files.
4. To return to the previous display and save the changes to your application file, click OK; to return and lose the
changes, click Cancel.
NOTE
You can double-click one or more files in the bottom list area to tag them for opening. Tagged files (highlighted in
cyan) are opened when you click OK to exit the dialog.
Close an Application
Follow these steps:
1. Click File, Application, Close, or open another application.
2. If the application is the default application, you are asked if you want to remove it as the default application.
– Click Yes to remove it as the default application.
– Click No to keep it as the default application.
3. If you made changes to any CA Easytrieve Report Generator options, you are asked if you want to save the changes
to the application file.
– Click Yes to save the changes so that they are saved in the application file.
– Click No to not save them with the application.
Source Control Commands
The Source Control commands provide easy-to-use Windows access to the basic needs of change/version management.
Any source control software that conforms to the industry standard Source Code Control interfaces is supported. This
includes CA SCM and Microsoft SourceSafe.
To specify an alternative source control manager for use, see Setting Up Source Control Supports for detailed setup
instructions.
Although you can invoke the desired source control manager directly from CA Easytrieve Report Generator to perform
more specialized or detailed operations, the product provides a seamless interface that lets you perform these tasks:
384
CA Easytrieve® Report Generator 11.6
• Select a project
• Check in a file
• Create new archives
• Check out a file
• Cancel a check-out
• Run various reports, such as history or differences
To invoke the source control manager, click File, Source Control, Source Control Manager.
NOTE
To use the Source Control commands to manage your applications, you must first create the appropriate project
for the selected source control manager and then define a CA Easytrieve Report Generator application.
What Happens When You Use Source Control Facility
When you use the File Source Control and Options Source Control commands, these requests are processed using the
selected source control manager. Your processing preferences and options, and the information that you specify in the
dialogs are merged into a request for the source control manager.
The actual technique to process your request varies depending on the source control manager. Typically, you receive a
message indicating the success or failure of your request.
Select a Project
Before you select a project, open the application that uses these project files. This automatically associates the
appropriate source control manager project with your application. When you open that application later, the related source
control manager project is also opened.
Follow these steps:
1. Click File, Source Control, and select Select Project.
The specified source control manager is invoked and the Select Project dialog is displayed. This dialog displays only
projects that were previously defined to your source control manager. You must use the source control manager
directly to create a project; CA Easytrieve Report Generator has no means to create projects.
2. Use the dialog to select a project, and click OK to return to the Workbench.
See the documentation for your source control manager for more information.
Check Out Files
Follow these steps:
1. Click File, Source Control, and select Check Out. The Check Out dialog appears.
2. Use any of the standard Windows selection techniques to select one or more of files that you want to check out. You
can click the Select All button to quickly select all the files.
3. (Optional) Click the Advanced button to invoke any special check-out criteria that are permitted by your source control
manager. For example, you may want to check out a particular revision of a file. See your source control manager
documentation for details.
You can also specify comments using the text box at the bottom of the dialog if your source control manager supports
comments on check-out.
4. When you have finished, click OK. The request is sent to your source control manager for processing. The success or
failure of the request is provided by the source control manager itself.
385
CA Easytrieve® Report Generator 11.6
Getting the Latest Version of a File
Suppose that you want to quickly refresh one or more source files or copybooks to run a quick compile. You are not going
to modify the file or files, so you do not need the source control manager to apply all the normal locks on the archives.
Follow these steps:
1. Click File, Source Control, and select Get Latest Version. The Get Latest Version dialog appears.
2. Use any of the standard Windows selection techniques to select the files that you want to check out. You can click the
Select All button to quickly select all the files.
3. Click the Advanced button to invoke any special check-out criteria that are permitted by your source control
manager. For example, you may want to check out a particular revision of a file. See your source control manager
documentation for details.
4. When you have finished, click OK. The Workbench sends your request to your source control manager for processing.
Cancel a Check Out
Undo Check Out lets you cancel a previously checked out project file and discard any changes that were made to it.
Follow these steps:
1. Click File, Source Control. Then select Undo Check Out. The Undo Check Out dialog appears.
2. Use any of the standard Windows selection techniques to select the files that you want to undo. You can click the
Select All button to quickly select all the files.
3. Click the Advanced button to invoke any special check-out criteria that are permitted by your source control manager.
For example, you may want to undo the check out a particular revision of a file. See your source control manager
documentation for details.
4. When you have finished, click OK. The request is sent to your source control manager for processing.
Check In Updates
After you update a file, you can check the file back into the source control manager.
Follow these steps:
1. Click File, Source Control, and select Check In. The Check In dialog appears.
2. Use any of the standard Windows selection techniques to select the file or files that you want to check in. You can click
the Select All button to quickly select all the files.
3. Click the Advanced button to invoke any special check-in criteria that are permitted by your source control manager.
For example, you may want to check in a particular revision of a file. See your source control manager documentation
for details.
Check the Keep checked out box if you want to check in your changes and keep the file checked out for more editing.
You can also specify comments using the text box at the bottom of the dialog.
4. Click the Differences button to display a difference report for the selected file. If you select more than one file, the one
with the dotted box around it is used. The difference report displays the changes that were made to the file that is to be
checked in.
5. When you have finished, click OK. The request is sent to your source control manager for processing.
Add Files to the Project
Add to Source Control adds the selected file to your project. Depending on your site, the Add function can be restricted to
authorized users. If you are not authorized to use the Add function, the source control manager displays an error.
Follow these steps:
1. Click File, Source Control, and select Add to Source Control. The Add to Source Control dialog appears.
386
CA Easytrieve® Report Generator 11.6
2. Use any of the standard Windows selection techniques to select the files that you want to check in. You can click the
Select All button to quickly select all the files.
3. Click the Advanced button to invoke any special check-in criteria that are permitted by your source control manager.
For example, you may want to check in a particular revision of a file. See your source control manager documentation
for details.
Check the Keep checked out box if you check in your changes and keep the file checked out for more editing.
You can also specify comments using the text box at the bottom of the dialog.
4. When you have finished, click OK. The request is sent to your source control manager for processing.
Remove Files from a Project
Remove from Source Control removes the selected files from your project. Depending on your site, the Remove function
can be restricted to authorized users. If you are not authorized to use the Remove function, the source control manager
displays an error.
Follow these steps:
1. Click File, Source Control, and select Remove from Source Control. The Remove from Source Control dialog appears.
2. Use any of the standard Windows selection techniques to select the files that you want to check in. You can click the
Select All button to quickly select all the files.
3. When you have finished, click OK. The request is sent to your source control manager for processing.
Run Reports
You can run the following reports:
• History -- Provides details on the history of check-outs and check-ins, and so forth.
• Differences -- Lets you compare versions of a file and generates a detailed report of differences.
• Properties -- Provides statistics such a file size and type.
To run any of these reports for a file, it must be the currently selected file in the Workbench editor.
Invoke the source control manager application to run any other reports that are supported or to run reports on multiple
files.
Edit Source or Text Files
You can use the editor to create or modify your source or text files, such as .EZT, .MAC, and .TXT files. You cannot
edit .CVX files.
This article includes the following information:
Open an Edit Window
An edit window is created whenever you:
• Open an existing text or source file
• Double-click an existing text or source file within the Workbench Explore window.
• Open an application that contains one or more . EZT or . MAC files
• Create a new file
• Create a clone of a WorkSheet
Open an Existing Text or Source File
There are two methods you can use to open an existing file:
387
CA Easytrieve® Report Generator 11.6
• Use the Workbench Explore window.
• Select File, Open.
NOTE
If you open a read-only file, (Read Only) appears in the title bar. You cannot edit this file until you change the file
attribute. The change takes effect immediately.
Open Files as Part of an Application
Follow these steps:
1. Click File, Application, Open.
2. Use the Edit Application Open dialog to select the application files as follows:
– If Open Source Files is checked, the source files are opened when you click OK.
– If Load Analysis Files is checked, the analysis files are opened when you click OK.
– Double-click (to select) the files in your application (shown in the Selected File List list box) to be opened.
3. Click OK to open the files.
Create a New File
You can create a new file using the text editor.
Follow these steps:
1. Click File, New.
An edit window with the title <Unnamed: n> opens, where n is a sequential digit. For example, if this is the first edit
window that you open, the title of the window will display <Unnamed: 1>.
2. Enter or paste text into the edit window. For example, paste a copy of a source program.
3. Click the X in the title bar to close the file.
You are prompted to save the file.
4. Click Yes.
The Save As dialog opens.
5. Specify the file name and extension. For example, specify .EZT for a CA Easytrieve Report Generator source
program.
6. Click Save.
Create a Clone
Use the View Create Clone command to place the contents of a WorkSheet or WorkSpace window into an edit window.
Follow these steps:
1. With a .CVX file open in Text view, use the View commands to select the text that you want to clone.
2. Click View, Clone. An unnamed Edit window opens containing the selection from the .CVX file. From here, you can
edit the text, copy and paste it into another edit window, or save the file.
Example
Use the View Tree command and scroll down through the branches, or use the View Expand or View Collapse commands
to isolate a section of code.
Double-click the section. A WorkSpace window opens for the selected section.
388
CA Easytrieve® Report Generator 11.6
• Use the View Exclude command to exclude lines that you do not want to place in the clone. For example, if you do not
want the cloned section to contain comments or blank lines, select View Exclude Comments and View Exclude Blank
Lines before you select Edit Clone.
• Select the View menu and select Clone, and an unnamed Edit window opens with the section from the .CVX file
displayed.
Select Text
Use standard mouse and keyboard methods for selecting text.
For example, to select all the text in an edit window, click Edit, Select All.
Positioning and Scrolling
You can move to different portions of your program using the Edit menu.
Jump to a Selected Label
Use the View Jump To command to jump to a selected label in a .CVX file in Text view. For example, if you are looking at
a PERFORM statement and want to see the paragraph being performed, highlight the label (paragraph name) and select
View Jump To. This action repositions you to the selected paragraph.
NOTE
You can also jump to a label without having to return to the menu bar. Click the right mouse button for a context-
sensitive pop-up menu of commands available for a program label and select Jump To Label.
Scroll to Labels
Use the Scroll To Labels command when you do not know the exact spelling of a label name in a .CVX file.
To scroll to a label, click View, Scroll To Labels. Hierarchy shows the hierarchy of the selected label from the highest to the
lowest level. This lets you select from two or more labels that have the same name but have different qualifications. When
you make your selection, your window repositions to that location. Press F1 for help.
Going to a Line Number
Follow these steps:
1. Select a file, if more than one file is open.
2. Click Edit, Go to Line #. The Go To Line dialog indicates the first and last line numbers in your view range in the
selected file. You can only jump to a line in the Viewable Range that is specified in the dialog.
The current line (Ln) and column (Col) numbers for the active window appear in the status bar at the bottom of the screen.
Find a String or Object
Use the Find bar at the bottom of the main window to search for text.
Follow these steps:
1. Click in the combo box in the Find bar and enter the text string that you want to locate. Or, you can double-click text to
place it in the combo box on the Find bar.
2. Use the search option buttons at the right of the Find bar to limit the scope of your search, if necessary.
3. Click one or more of the VCR buttons to move to an instance of the selected text. If the file is .CVX file, click the Show
All button to display all instances of the selected text.
389
CA Easytrieve® Report Generator 11.6
Replace Text
To find and replace a string of characters two methods are available:
Method one:
Click Edit, Replace.
The Find and Replace dialog is displayed.
Method two:
1. Click Edit, Replace.
2. Enter the text sting you want to replace in the text box on top. Enter the text string that you want entered in its place in
the Replace with box.
3. Use the VCR buttons to position to the strings that you want to replace and click the Replace button. Or click the
Replace All button to replace all instances of the string in the file. Replace All starts at the top of the file and replaces
all occurrences of the string, regardless of your starting position.
4. To cancel a replace operation, click Edit, Undo until you have backed out each replace operation.
If the text string is not found, a message appears on the status bar.
NOTE
This is a one-way search from the cursor position to the end of the file. Position the cursor at the top of the
file to search and replace a string throughout the entire file.
Undo and Redo Changes
Undo
If you make a mistake cutting or pasting text, use the Edit, Undo or Edit, Undo All commands to restore your file. These
commands work backwards, starting with the most recent change that you made to the file.
NOTE
Note the following information about the Undo and Undo All Commands:
• They can even restore saved changes -- to a point. For example, you delete ten lines of text from a file and
select File Save. Then move to another location in the file and delete 15 more lines. Selecting Edit Undo
returns the fifteen lines to their former place in the file. Selecting Edit Undo again returns the first ten lines to
their original location, effectively undoing the save.
• Try not to undo more changes than you can remember.
• They cannot restore changes after you close the window.
• They treat Replace All as a sequence of individual Replace commands. You must undo each replaced string.
Use Edit Undo to undo Show commands that are issued for a .CVX file. If you still see highlighting, use the Navigate Clear
Highlighter command.
Redo
If you undo a change you meant to keep, use Edit, Redo. The following are limitations of the Redo command:
• Redo restores only the action that were performed by the last Undo command. Until you select Edit, Undo again, the
Redo command is inactive. You can select Redo as many times as you performed consecutive Undo commands.
For example, you delete ten lines of text from a file. Then you move to another location in the file and delete 15 more
lines. Selecting Edit Undo returns the 15 lines. Selecting Edit Undo again returns the first ten lines to their original
location. Selecting Edit Redo, deletes the last ten lines again.
• Redo cannot restore changes after you close the window.
390
CA Easytrieve® Report Generator 11.6
Display Compiler Messages
The editor displays compiler error messages in the source file with red highlighting.
Follow these steps:
1. Compile the source file. If the compile produces errors, the error messages appear highlighted in the text as follows:
If the file has already been compiled, click Edit, Display Errors. Then click the Errs button on the Find bar to enable the
VCR buttons.
2. Use the VCR buttons on the Find bar to locate the errors in the file.
3. If you want to change the colors for the errors, click Options, Compile Feedback.
You can display each level or message in a different color. For example, make severe errors appear with a red
background, and make less serious informational messages appear with a lighter background, such as cyan.
4. Save the file, or edit the file to fix the errors and recompile. You can add new lines or edit existing lines without having
to worry about getting the error messages out of sync with the source text. The messages only appear to be in your
file. They are not saved in your source file.
Enter Non-Graphic Characters
If you need to enter characters which do not appear as keys on your keyboard, they can be entered using either of the
following two mechanisms:
NOTE
The null character (x'00') cannot be entered using either of these mechanisms.
• For characters below x'20' an escape sequence must be used. Type <ctrl>+D (or <ctrl>+d) followed by a character
(upper or lower-case) which represents x'01' thru x'1f" according to the following table:
a|A - x'01' i|I - x'09' q|Q - x'11' y|Y - x'19'
b|B - x'02' j|J - x'0a' r|R - x'12' Z - x'1a'
c|C - x'03' k|K - x'0b' s|S - x'13' 1 - x'1b'
d|D - x'04' l|L - x'0c' t|T - x'14' 2 - x'1c'
e|E - x'05' m|M - x'0d' u|U - x'15' 3 - x'1d'
f|F - x'06' n|N - x'0e' v|V - x'16' 4 - x'1e'
g|G - x'07' o|O - x'0f' w|W - x'17' 5 - x'1f'
h|H - x'08' p|P - x'10' x|X - x'18'
• For characters above x'20', the standard Windows ALT-numpad process can be used: while holding the ALT key down,
type in the decimal value of the character you want to enter, and then release the ALT key. For example, to enter a £
character, hold the ALT key down, and enter (with numlock selected) 1 then 5 then 6 (on the number pad) and then
release the ALT key.
Build and Run Programs
The Build menu lets you specify options to build, debug and run your programs. It reflects the Workbench default, which
is simply to compile a standalone CA Easytrieve® Report Generator program. To modify the default behavior, select the
Program Profile menu.
Contents
When you want to compile one or more programs within an application you need to perform these basic steps:
391
CA Easytrieve® Report Generator 11.6
• Open the application that contains your source files. (If the application does not exist, create it.)
• Select the files that you want to build.
• Execute the build request.
• When the program is successfully built, you can run it or initiate a debugger session.
The Workbench processes your build requests as background jobs so you can continue to use the Workbench without
having to wait for the job to finish. You can even queue multiple jobs to run one after the other.
Build Programs and Applications
What Happens When You Build
When you choose the Build command from the Build menu, a Batch Server session is initiated. The batch session lets you
continue to use the Workbench while your programs are being processed in the background. The following describes the
files created by the Build process.
You can run the batch session in the background (the default) or place it in focus (by turning on the Show Batch Window
option from the Options menu). The Script processor (R2SCRIPT) manages your batch jobs. As jobs finish, R2SCRIPT
sends status messages to the edit window title bars and the Workbench status bar to keep you aware of their progress.
R2SCRIPT appears as an icon on the desktop so that you can minimize or maximize it at any time.
CA Easytrieve® Report Generator Compiler Output Files
The CA Easytrieve® Report Generator compiler (EZTCOM.EXE) produces the following files with the same name as the
source file but different extensions:
File Description
<filename.CVX> Analysis File. This file is used for analysis and debugging.
<filename.ERR> Compiler Error Listing File.
<filename.LST> Listing File.
Compile Feedback
If errors are detected during a compile, the errors are displayed in the source edit window, directly below the statement
triggering the error.
In addition, the VCR buttons on the Find Bar now let you position to compiler warnings. As you move to the errors, you
can correct them (adding or deleting lines of text) without the error messages getting out of sync with the source lines.
After you have finished correcting the errors, you can recompile the program. When you recompile, the error messages
are not saved with the source file, but removed automatically.
NOTE
You can control the type of error messages that are reported, and the colors used to display them. For more
information, see Change the Color of Compile Errors in Set Preferences.
Build Programs within an Application
The following sections describe the steps required to build a program or programs within an application.
Key Compiler Options
Before you compile, ensure that the location of all CA Easytrieve® Report Generator macros used within your program
are known to the Workbench and the compiler. This is controlled by the environment variable EZTOPTS. Its value should
point to the subdirectory containing your macros. If they do not exist there, the product will look in the location that the CA
Easytrieve® Report Generator program was loaded from.
392
CA Easytrieve® Report Generator 11.6
Compile a Single Program
Follow these steps:
1. Open the source file.
2. Do one of the following:
– For programs within an application:
a. Select File, Application, Edit. The Edit Application dialog appears.
b. In the lower list box, double-click the files you want to open and click OK.
– When not working within an application:
a. Use the File Open dialog to open the source file.
b. Select the source file you want to build.
c. Press F7 or select the Build menu and choose Build.
Build an Application
Follow these steps:
1. Select the Build menu and choose Build Application. The Application Build dialog appears.
2. Select the items you want to build (or all of them by pressing Select ALL), and press Build Files.
NOTE
The programs are processed in the order they are defined in the application's file list. Make sure programs
that are needed to successfully link other programs are processed prior to ones dependent upon them.
3. When the last program that you requested has been compiled the Application Build Results dialog appears.
The Show Application Build Log command in the Build menu lets you view the Application Build Results dialog any time.
Start the Debugger
You can also start the debugger from the Build menu.
Follow these steps:
1. Select the Build menu and choose Debug: programname, or click the Debug toolbar button.
2. Click the Step Into debug-button or select the Debug menu and choose Go.
Debug Programs
This section explains how to debug your CA Easytrieve® Report Generator programs using the debugger. The Debugger
uses a Windows interface for visual presentation while the program itself runs in separate window.
Contents
Debugger Features
The debugger provides visual, CA Easytrieve® Report Generator intelligent facilities that are designed to dramatically
reduce the amount of time it takes to debug a program or an entire application comprised of numerous programs. Some of
the Workbench’s debug capabilities are:
393
CA Easytrieve® Report Generator 11.6
• Complete GUI object-action support. For example, you set breakpoints by selecting a line (object) and then an action:
Set Breakpoint.
• Convenient command selection. Pop-up menus appear when you click the right mouse button in a debug window.
• Program selection. You can select one or more programs in an application for monitoring to restrict the session to just
those programs you feel are relevant.
• Drag and drop support. You can monitor data items by dragging a reference to the data item into a Data Director.
• Watchpoints. You can place a watch on data items so that program execution halts whenever their values change.
• Breakpoints. You can set conditional or unconditional breakpoints in one or more programs by selecting a line from a
text view of a program. Also, you can define conditional breakpoints and conditions that take affect when the value of a
data item changes or when a condition is met.
The debugger facilities in the Workbench are completely integrated with the analysis facilities. This means that you can
perform analytical tasks at any time -- even while debugging!
For example, while waiting for a breakpoint to be reached, or perhaps while in a halted state brought about by an abend
condition, you can perform any number of analysis commands, such as switching from Text view to Tree, showing or
hiding statements, or tracing a program path.
Terms and Concepts
The Workbench debugger uses terms and concepts that you are already familiar with, but it also adds its own unique
capabilities and terminology. You should understand the following terms before you begin a debug session:
• Active Breakpoints
Breakpoints that have been defined by the user and are not disabled.
• Debug-Button
The button that appears on the right side of the status bar whenever a debugging session is started. The most likely
command for the current state of the debugger is set in the auto command button.
• Automatic Breakpoints
Breakpoints that are automatically triggered by the Workbench host debugger when it detects a statement whose
execution would cause an abend or serious program failure, such as an addressing error, data or program exception,
or subscript violation.
• Breakpoints
User-specified program locations, where program execution is to halt either unconditionally or under certain conditions.
• Conditional Breakpoints
User-requested interruptions that take effect at particular lines during debugging execution when execution reaches
the breakpoint line and a specified condition is true. A condition is defined as an expression that compares a data
item’s value to either a literal value or the value of another data item. The comparison is made using any of the
standard CA Easytrieve® Report Generator logical operations: equal, not equal, less than, less than or equal, greater
than, and greater than or equal.
• Current Statement
The statement where execution has halted in the application being debugged.
• CVX File
A file combining information from an original source member with information from compiler output, used in analysis
and debugging.
• Data Director
An optional dialog window where you can edit data items and perform other debugging tasks, such as setting a watch
on a data item.
• Data Items
Any of the named variables defined in your program.
• Disabled Breakpoints
Breakpoints that have been defined and then made temporarily non-functional by the user.
• Debug Session
394
CA Easytrieve® Report Generator 11.6
The activities related to the test execution of an application. A host connection is established by starting a session.
Initiating a session starts application execution. Killing or terminating the session ends execution. Ending the session
severs the host connection.
• Debug Window
A window where a monitored program is displayed for debugging.
• Execution Profile
A file that identifies the JCL and programs of a batch application that are to be tested.
• Focused Program
The program or program appearing in the active window.
• Module
A program contained in a .CVX file. A .CVX file is required to debug a program.
• Number Margin
The area on the left side of a debug window that contains line numbers from the compilation listing.
• Program
A program contained in a .CVX file. A .CVX file is required to debug a program.
• Session
An instance of the debugger. Multiple debugging sessions can be active simultaneously. Any program being debugged
contains the name of the related debugging session in the left side of its window title.
• Status Light
A round object that appears in the right-hand side of the status bar whenever a debugging session has been started.
The color of the light indicates the current state of the debug session.
• Unconditional Breakpoints
User-requested interruptions that take effect at particular lines during debugging whenever execution reaches the
breakpoint line. Every time a line with an unconditional breakpoint is executed, the program stops at that line.
• User Window
A window in which the user’s program executes. This window is automatically created whenever you issue the Debug
Start Session command.
• Watched Data
Data that will trigger an immediate breakpoint if its value changes.
Using Debug Windows
To debug a program, you must first start a debug session and monitor one program (a program is another name for the
program contained in a .CVX file). When you monitor a program, all of the windows open for that program automatically
become debug windows. The Debug Session Identifier appears in brackets on the left side of their title bars.
WorkSheets and WorkSpaces
A program can have any number of WorkSpaces opened on a debugging WorkSheet. Additional (non-debug) WorkSheets
can also be active for a program at the same time. This means that you can have analysis WorkSheets available that are
not in any way affected by the debugging of the program.
As with all WorkSpaces owned by a WorkSheet, WorkSpaces opened on a debug WorkSheet reflect what is displayed
in other WorkSpaces opened on the same WorkSheet. For example, if you open a WorkSpace on the entire Procedure
Division and also one on the first paragraph in the Procedure Division, breakpoints added to either of the WorkSpaces are
displayed in the other.
Features such as the Number Margin, the Status Light, debug-button and pop-up menus make it easy to observe and
control your debugging session.
Line Number Margin
The gray area on the left side of a debug window is a line number margin. It displays the line numbers from the compiler
listing. These line numbers have no relation to the line numbers contained in columns 1-6 or 73-80 of the source.
395
CA Easytrieve® Report Generator 11.6
Select the View menu and choose Line Numbers. Press F1 for a description.
Use the number margin to select lines for Debug commands.
• Click the left mouse button in the number margin to select the entire line.
• Click the right mouse button in the number margin to display a pop-up menu of Debug commands for that line.
Because many of the Debug commands require you to first select a line, the View Line Numbers command is
automatically activated when you select a program to be monitored.
Status Light
The Status Light appears as a round object on the right-hand side of the Workbench status bar whenever you are
debugging. The color of the Status Light changes as your session proceeds to show the state of the debugger session.
The following table lists the colors meaning:
Color Meaning
White A debug session has been started, but the focused window does
not contain a monitored program.
Cyan Monitored. The program in focus is being monitored, but the
(Light Blue) session has not been initiated.
Blue Initiated. The application to be debugged has been initiated, but is
not yet running.
Red Wait. The debug session is busy and the user cannot enter
commands.
Green Running. The program is executing.
Dark Gray The application has terminated. The debug session is still active
as are all monitored programs and breakpoints.
Light Green Halted. The focused program is attached to a session that has
been halted because of a breakpoint, interrupt, or other cause.
Black The debug session has been terminated and data not available.
To the left of the status light is a debug-button that contains the name of a command. Use the debug-button to perform
various debugging commands, such as Step Into, Auto, and Interrupt. Clicking this button executes the command. The
debugger tries to anticipate the command that you are most likely to issue next and places that command in the debug-
button.
Object Pop-up Menus
When the mouse pointer is positioned on a data item in your program, a click of the left mouse button selects and
highlights the object. A click of the right mouse button displays an Object Pop-up menu.
Object Pop-up menus list basic commands that are appropriate for the selected object. If the object is a data item,
additional menu items are enabled:
• Show All -- Shows all references for CVX files. Press F1 for details.
• Open Window On -- Open a WorkSpace window.
• Set Conditional -- Displays the Conditional Breakpoints dialog with the selected data item already defined in the left-
hand side of the condition. Use it to specify conditions for a breakpoint that will be located at the statement you have
selected.
• Add to Data Director -- Adds the selected data item to the Data Director dialog for the module. If a Data Director is not
yet defined, then one is created, and the data item is added as its first entry.
• Watch -- Adds the selected data item (as a watched data item) to the Data Director dialog for the module. If a Data
Director is not yet defined, then one is created, and the data item is added as its first entry.
396
CA Easytrieve® Report Generator 11.6
Debugging a Program
Follow these steps:
1. Open the program RPTHTML.EZT. If it had been previously compiled, the Debug icon and the Build Debug menu item
as well as the Debug Session menu item are enabled. Select one of these items.
The debugger stops at the first executable statement in a monitored program. At that point, the session's state
changes to halted as evidenced by the status light's light green color. The first executable statement is shown in green
highlighting. The session stays in a halted state until you direct the Workbench to resume execution of the program
with an execution command.
2. Set Breakpoints. You can set breakpoints on one or more lines in the program before or after you initiate the program.
3. Select the Step Into debug-button to begin stepping through the code.
Program execution proceeds asynchronously, which means you are free to use the other facilities in the Workbench, or
any other Windows programs, while waiting for your program to halt.
In addition, you may want to begin by setting debug options. The following sections describe each of these steps in detail.
Program Execution Commands
The execution commands are used to advance the execution of the program being debugged. You have the option
of executing any of the following Debug menu commands to change the state of the debug session. The execution
commands are enabled only when the session is in a halted state. Selecting an execution command causes the session's
state to change to a running state, indicated by a dark green status light.
Go
Go (Ctrl+G)
Execution proceeds without any indication of which statement is currently being executed, until the program terminates or
a breakpoint is encountered. If no breakpoints have been set, the program executes from beginning to end, stopping only
for exception conditions or normal program termination.
Step Into
Step (Ctrl+I)
The program single steps to the next statement.
Auto-Step
Auto-Step (Ctrl+A)
The program executes statement by statement, displaying each statement as it is executed. Auto Step is considered a
series of Step Into requests. Execution can be interrupted at any time by the use of the Interrupt hot key, Ctrl+Q (same as
Debug Session Interrupt).
• Run to Line
The program begins execution (using the Go command) and continues until it reaches the specified line. A temporary
break is established on the line that is reset when execution reaches the line.
• Set Next Line
Highlight a line within a monitored program and select Set Next Line. The next execution command will continue from
this point.
Interrupt
Interrupt (Ctrl+Q)
Interrupts the execution of a program and is enabled if running in Auto-Step mode.
Trace Backward and Forward
Trace
397
CA Easytrieve® Report Generator 11.6
The debugger retains a log of previously executed statements. You can use the Trace Backward and Trace Forward
commands to navigate through this information. The current line indicator (the green bar) identifies each line in the trace.
For example, you might use the Trace feature to determine how you arrived at a breakpoint. To resume execution, choose
one of the other execution commands.
Auto-Focus User Window
When checked, this command automatically places the User Window in focus each time the User Window is updated
or each time the keyboard is interrogated by the user program. For example, execution of a DISPLAY statement
automatically places the User Window in focus.
Manage Breakpoints
You can set unconditional and conditional breakpoints as follows before or after you initiate debugging of a program to
interrupt execution:
• Unconditional breakpoints -- Interrupt the execution of the program whenever the execution reaches the specified line.
• Conditional breakpoints -- Take effect when execution reaches a specified line and a condition is met. Specify the
breakpoint conditions using a dialog.
When a breakpoint is reached, execution halts. You can inspect and modify the contents of any data item, set and remove
other breakpoints, and perform other debugging activities. You can then decide to resume execution or close the session.
You can put unconditional and conditional breakpoints on the same line in any combination.
Set Breakpoints
You can use any of the following techniques to set a breakpoint:
• Use the Line Number Margin pop-up menu
• Select the line or data item and use the Debug Breakpoints command
• Tag verbs, then set breakpoints on all the lines with tagged verbs.
Set a Breakpoint Using the Line Number Margin Pop-up Menu
Follow these steps:
1. Click the right mouse button in the line number margin at the line where you want to place the breakpoint. The pop-up
menu above appears.
2. Choose Set Unconditional, Set Conditional, Run to Here, or Set Next Line to set a breakpoint. Press F1 with the cursor
on the command for a description of the command.
Set a Conditional Breakpoint From a Data Item in the Statement
Follow these steps:
1. Click the right mouse button on the data item where you want to set the conditional breakpoint. You cannot set
unconditional breakpoints from the pop-up menu.
2. Choose Set Conditional to set a breakpoint. This selection is available only when a current value exists for the data
item.
3. Set Conditional displays the Set Conditional Breakpoint dialog. After you set a conditional breakpoint, the background
color turns to yellow if you are using the system default options for color.
Set a Breakpoint Using the Debug Breakpoints Menu
Follow these steps:
1. Click the line number margin with the left mouse button to select the statement where the breakpoint is to be placed.
2. Select the Debug menu and choose Breakpoints. Then choose Set Unconditional or Set Conditional to set a
breakpoint:
398
CA Easytrieve® Report Generator 11.6
– Set Unconditional places an unconditional breakpoint at the line you have pointed to. After you set an unconditional
breakpoint, the background color turns to red if you are using the system options for color.
– Set Conditional displays the Set Conditional Breakpoint dialog. After you set a conditional breakpoint, the
background color turns to yellow if you are using the system options for color. See Setting Conditional breakpoints
next.
3. Alternatively, you can select the Debug menu and choose Run to Line to set a temporary breakpoint, or Set Next Line
to set the line where the program resumes execution.
Setting Conditional Breakpoints
You can specify conditional breakpoints for:
• A single line. Select the line, then issue the Set Conditional Breakpoint command from the pop-up or main menu.
• A set of tagged lines. Tag one or more lines using the Tag command, then create a set of conditional breakpoints all at
once by selecting the Debug Set Conditional on Tag command.
• All lines in a program. Use the Debug Set Conditional All command to specify a condition that when true causes the
program to immediately halt. The conditional is conceptually placed on every line in the program but is displayed
as being attached to the Procedure Division. Using the Procedure Division statement as a handle for these kinds of
breakpoints lets the user review and edit the condition without having to clutter the debug windows with conditional
breakpoints for each and every line in the program.
After you select a breakpoint and select Set Conditional, the Set Conditional Breakpoint dialog appears so that you can
specify what condition is to be met to activate the breakpoint:
A condition has three parts: a left side, an operator, and a right side. The left side always specifies a data item. The
operator specifies the type of comparison being made. The right side specifies a figurative constant, a value, or a data
item.
Choose among several kinds of conditions to be applied to a breakpoint:
• Test a data item to see whether its value has changed.
• Compare the value of one data item to the value of another data item or to a literal value, using relational operators.
• Make your test before or after the target line has executed.
• Skip a number of executions of the target line before activating the breakpoint.
To set a condition, you can specify the following:
• A left side
• An operator
• A right side
• Whether to test before or after a target line
Optionally, you can also specify a skip value.
Specifying the Left Side
You must specify the left side of a condition using a valid data name.
To enter a valid data name in the Left box, click the drop-down arrow next to the Left box to display the list of all the data
items used your program. When you highlight an item in this list, the item appears in the Left box.
You can also enter a data name directly into the Left box.
If the data item requires subscripts, you must specify them in the Left box. To specify a subscript, enter the name of the
data item followed by one or more subscripts in parentheses, for example dataname(subscript1, subscriptn).
Selecting an Operator
After you select the left-side element to be tested, select the operator to be used for the comparison.
399
CA Easytrieve® Report Generator 11.6
Click the arrow for Operators. Select the test to be made from among the relational operators in the display.
Seven operators are available. All of the operators are binary, except for CHG, which is unary. Descriptions are provided
in the following table.
Operator Description
= equal to
<> not equal to
> greater than
>= greater than or equal to
< less than
<= less than or equal to
CHG the value of the left-hand data item has changed (The right-hand
data item is not required).
Specifying the Right Side
You have the following options for specifying the right side:
• If the operator is CHG, no right-side entry is required. The Right box is dimmed.
• Otherwise, you can specify a figurative constant, a literal value, or a data name.
• Compare Left Side to a Figurative Constant
Select the value from among the items appearing in red in the Right box drop-down list. These choices are:
– HIGH-VALUE
– LOW-VALUE
– ZERO
– SPACE
Or type the value in the Right box.
• Compare Left Side to an Alphanumeric Literal
Enter the name of the literal, enclosed in single quotes, in the Right box. For example, 'Chapter'.
• Compare Left Side to a Numeric Literal
Enter the numeric literal, signed or unsigned, with or without a decimal point, in the Right box. For example, +20.00.
• Compare Left Side to a Data Name
Use the drop-down arrow in the Right box to select a valid data name, or enter the name in the Right box. To
enter a subscript, type the name of the data item followed by one or more subscripts in parentheses, for example
dataname(subscript1 subscriptn).
Specifying Before or After
The Before and After buttons let you specify whether the test of the condition is to take place before or after the target line
is executed.
Skipping Breakpoints
You can also specify the number of times a target line should be executed before the breakpoint is triggered. Enter a
value in the Skip box. The default is 0.
For example if you specify 5, the breakpoint occurs the sixth time execution reaches the statement. If you do not specify
a condition, you can use this option to set a breakpoint with no conditions other than the number of executions to be
skipped.
Sample of a Completed Dialog
The following is an example of a completed Set Conditional Breakpoint dialog.
400
CA Easytrieve® Report Generator 11.6
REGION from the PERSNL File has been selected as the first data name in this example.
For example, enter 3 in the Right box. When REGION is equal to 3, the breakpoint takes effect. The test is to be made
before the breakpoint statement is executed, and no true occurrences are to be skipped.
Display Active Conditions
After you set breakpoints, you can display the active conditions and then edit or delete them.
Follow these steps:
1. Select the Debug menu and choose Breakpoints Active Conditions. The Active Conditions dialog for the program
appears.
All active conditions, including Unconditional, are listed at the top. In the previous example, we see the first condition
is condition, Unconditional. The second condition is on variable change, which means that a specified variable must
change to meet the condition.
2. Highlight any of the conditions in the Conditions list at the top to see the affected breakpoints in the Breakpoints list at
the bottom. For example, if you select Unconditional, a list of all statements where unconditional breakpoints are set is
displayed.
3. Use the buttons at the bottom of the Active Conditions dialog to alter the active conditions, or perform the same
function by means of the keyboard.
– Disable/Enable -- If a condition is selected, disables the highlighted condition, but leaves it marked so that you can
still see it. To enable it again, click the same button, now labeled Enable.
– Add -- If a condition is selected, brings up the Set Conditional Breakpoints dialog, where you can add a condition.
– Change -- If a condition is selected, brings up the Set Conditional Breakpoints dialog, where you can change a
condition. Not available if a breakpoint is selected.
– Delete -- Deletes the selected breakpoint.
4. When you have finished, click Close to make the changes and exit the dialog.
Examine and Modify Data
The debugger provides the Data Director tool for you to use to examine and modify data after you initiate the program.
The Data Director displays a set of data items that you have selected. For each item you can modify its value, add it to
or remove it from the Data Director, or add it to the data items being watched or monitored by the debugger. Select View
then Data Director.
Use the Data Director
The Data Director is an optional dialog that lets you perform a wide variety of tasks relating to data items:
401
CA Easytrieve® Report Generator 11.6
• Monitor a data item
• Stop the monitoring of a data item
• Modify data
• Add or remove a data item from the watched list
• Modify the data item specification by adding or modifying its subscripts, indexes, or reference modification to the data
item name
The Data Director displays a list of variables with their names and current values.
Selecting a Data Item or Subscript
To place a data item into the Data Director, type the name of the data item directly into the Data Name box. To place a
subscript into the Data Director, type the name of the subscript directly into the Data Name box. You can place multiple
data items in the Data director. However, only one data item or subscript can be processed at one time by the Data
Director.
Alternatively, you can use the following procedure to drag any reference to the data item or subscript from a text window
into the Data Director window.
To drag a data item:
1. Select the data item by pressing the left mouse button over any reference to the data item in a window in Text View. If
the data item has a subscript, select the subscript. You can only drag and drop the subscript, not its data item.
2. Hold the left mouse button down and slowly drag the mouse until a Var with a plus sign appears next to the cursor.
3. Without letting go of the left mouse button, drag the data item or subscript into the Data Director window and release
the button.
The data name of the data item now appears in the Data Name box of the Data Director window, and its current value in
the Data Value box.
If you selected a subscript, the subscript appears in the Data Name box of the Data Director window, and its current value
in the Data Value box.
NOTE
When you drag a data item into the Data Director you are guaranteed that you are getting the specific data item
based on that data name qualification present in the text. You cannot qualify a data name by entering a phrase
such as follows in the Data Director:
A of B
Data Director Options
To set Data Director options, you must first select the data item from list box at the top of the Data Director. Then you can
select from the following:
• Add Watch -- Places a watch on the data item. Whenever the value of a watched data item changes, program
execution halts.
• Add -- Adds a data item that you select with the mouse or type into the Data Name box to the Data Director after you
press Add.
• Modify -- Modifies the value of a data item. Type the new value in the Data Value box and click Modify.
• Remove -- Removes a selected data item from the Data Director.
Press F1 for additional information.
Terminating a Session
After you have finished debugging your program you can initiate a new session, end your debugging session, or terminate
the existing session. Initiating a new session causes the existing session state to be maintained so that monitored
402
CA Easytrieve® Report Generator 11.6
programs are still monitored. Terminating a session, on the other hand, removes all breakpoints and drops monitoring
for all monitored programs. Terminating a session is a convenient way to remove all breakpoints and drop all monitored
programs.
Alternatively, you can choose to completely end a debugging session. To end the session, select the Debug menu, then
Session, and choose End. The debugger terminates the application, the application window is closed, and all programs
are dropped. This completely shuts down the debugger. Ending a session is appropriate if you think that you will no longer
be debugging since it frees Windows and memory resources.
In some cases, such as when the program is waiting for a keystroke, you must respond to the prompt and then halt the
program. Then you can end the debug session.
After you select Debug, then Session, and choose Terminate, the status light turns black and the Step button changes to
Initiate. All monitored programs are dropped and all of their breakpoints are removed. The Debugger Session Identifier
disappears from the title bars of all monitored programs as they are dropped from monitoring.
Set Preferences
You can customize CA Easytrieve Report Generator to meet your requirements. The Options menu controls global
options for the entire CA Easytrieve Report Generator session. Options settings that are changed while an application
is open are saved with the application. If an application is not open, the options are saved for all CA Easytrieve Report
Generator sessions.
This article explains the following items on the Options menu:
Color
You can select the text color for comments, macro lines, source lines, gap lines, and select the highlight color. The Color
menu item is available only when a .CVX file is the current file.
Follow these steps:
1. Click Options, Color.
2. The Color dialog appears.
3. Select a color type and color, and click Apply.
The change appears in the current file.
4. Click OK.
Font
You can select the font that is used in the product. To select the font, a file must be open.
Follow these steps:
1. Click Options, Font.
2. The Font dialog opens.
3. Select the font and properties.
4. Click OK.
The settings affect the entire Workbench and all of its windows. Font setting changes are in effect during the current and
future sessions.
Source Control
If you are using source control management, you must specify the source control manager login information.
403
CA Easytrieve® Report Generator 11.6
NOTE
Before you can use this option, your source control manager must be initialized and the user name must be
defined. For more information about source control, see Set Up Source Control Supports.
Follow these steps:
1. Click Options, Source Control.
The Source Control Options dialog opens.
2. Select the source control provider, enter you user name, and click OK.
NOTE
If a password is required for the User Name, you are prompted to enter it after you click OK.
3. If you are prompted, enter your password and click OK.
Source Filter Strings
Some files from the mainframe include embedded JCL that must be filtered out before the program can be compiled on
the PC. For example, if you want the CA Easytrieve Report Generator Windows compiler to ignore all statements that
begin with // and /* (as typically found in JCL), specify them as filter strings. A filter string lets you filter such files without
major changes to the original file.
If you enable Use Default Filter Strings on the Filter tab of the Program Profile Manager dialog, the filter strings that you
define in this procedure are used.
Follow these steps:
1. Select Options, Source Filter Strings.
The Default Source Filter Strings dialog opens. The dialog is similar to the Filter strings section on the Filter tab of
the Program Profile Manager dialog.
2. Add, edit, or delete the default filter strings.
NOTE
For more information about filters, see Define and Specify Filters.
3. Click OK.
Set Default Profile
You can modify the default profile options for the current directory or the currently loaded file.
NOTE
For more information, see How to Set Directory Defaults and Use the Program Profile Manager.
Compile Feedback
You can select the compiler messages that you want to be displayed. You can also change the text and background colors
for the source line and compiler messages.
Follow these steps:
1. Click Options, Compile Feedback.
The Compiler Feedback Colors dialog opens.
2. Select the compiler messages that you want to display.
3. Change the source line and message colors as needed.
4. Click OK.
404
CA Easytrieve® Report Generator 11.6
Reload
You can control how the product refreshes files when they have been modified by a background task.
Follow these steps:
1. Click Options, Reload.
The Reload Options dialog opens.
2. Select the following options:
– Source Files
This option controls how source files are processed.
Select one of the following options:
• Automatically Refreshed—Files are refreshed (reloaded) if they are altered by another task.
• Never Refreshed—Files are never refreshed.
• Prompt for Refresh—Files are refreshed after prompting.
– Analysis (.CVX) Files
This option controls how Analysis (.CVX) files files are processed. Analysis files are in effect altered whenever a
background compile is done. However, if you are doing a complex navigation or analysis on the currently opened
analysis file, you may not want the file to be refreshed in the middle of what you are doing.
Select one of the following options:
• Automatically Refreshed—Files are refreshed (reloaded) if they are altered by another task.
• Never Refreshed—Files are never refreshed.
• Prompt for Refresh—Files are refreshed after prompting.
3. Click OK.
Tools Menu File
You can select the tools menu file (.MNU) that defines the items that are listed on the Tools menu. The default.mnu file is
predefined to perform core functions. You can customize that file or select a customized .MNU file.
NOTE
For information about creating a customized toolkit and tools menu, see Creating Tools and Writing Scripts.
Follow these steps:
1. Click Options, Tools Menu File.
The Tools Menu dialog opens.
2. Enter the name and path of the .MNU file that you want to use.
NOTE
If you select *.MNU, all matching MNU files are logically concatenated to show all the defined items on the
Tools menu.
3. Click OK.
File Save
You can specify save options for the files that you are editing.
Follow these steps:
1. Click Options, File Save.
The File Save Options dialog opens.
2. Select the following options as needed:
– AutoSave
405
CA Easytrieve® Report Generator 11.6
When the AutoSave option is enabled, any open files that you have changed are saved every n minutes.
Otherwise, you must explicitly save the file. You are prompted to save when you close a modified file.
– Create BAK file
When the Create .BAK file option is enabled, the editor creates a copy of your original file at the beginning of the
edit session. If this option is enabled, the following actions occur:
• If you save the file during the session, the original copy is saved with .BAK appended to the file name.
• If you do not make changes to the file and quit the session, the temporary copy is erased. A .BAK file from a
previous session is not overwritten.
When this option is not enabled, the editor does not create a backup copy of your file.
3. Click OK.
Show Toolbar
To display the CA Easytrieve Report Generator Workbench toolbar, click Options and select Show Toolbar.
Show Batch Window
You can view the Batch Session window during a compile and during batch program execution. To view the Batch Session
window, click Options and select Show Batch Window.
The batch window is placed in focus when you:
• Compile and link programs
• Run batch programs from the Tools menu
Normally, the Show Batch Window option is not selected and the batch commands are executed in the background.
NOTE
The Show Batch Window option has no effect on the Debug User Window.
Pause Control Window
Normally, a batch session is closed when the program that is running within it ends. However, you may need to view
output that is displayed to the console before the batch session is closed.
To view the output, click Options and select Pause Console Window. The batch session remains open after program
termination.
To close the batch session after program termination, select the window and press any key.
Enable JES Tab
The JES control lets you manage the jobs and job output that is contained in the mainframe JES (Job Entry Subsystem)
from within the Workbench IDE. Because not all CA Easytrieve Report Generator users are mainframe clients, the JES
interface is not visible by default. If the JES tab does not appear at the bottom of the Explore window, click Options,
Enable JES Tab.
NOTE
For more information about the JES control tab, see JES control.
Configuration Manager
The Configuration Manager tool in the Workbench lets Windows users create, view, and modify the Options Table and
Printer Set Definition (PSD).
406
CA Easytrieve® Report Generator 11.6
Both configurations are saved as XML files for the Workbench. You can also create binary configuration files for the Intel,
UNIX, Linux, and z/OS platforms from the Build menu.
The Options Table has the following categories:
• Compiler
• Execution
• Report
• Mask
• International
• Profiles
The Printer Set Definition has the following types:
• HTML
• RTF
NOTE
The Printer Set Definition binary is used for extended reporting and the Options table binary is used to set
default values for the compiler. The generated binary files are compatible in Windows, Linux for zSeries, UNIX,
and z/OS environments.
To open the Configuration Manger from the Workbench, click Tools, Configuration Manager. Alternatively, click Start,
Programs, CA, Easytrieve, Easytrieve Configuration Manager. The current Options Table or Printer Set Definition
appears.
The following XML files are created with default values during installation:
• eztopt.xml (Options Table)
• eztpsd.xml (Printer Set Definition)
Create or Modify an Options Table
The Configuration Manager lets you create and modify the options table. Options table definitions are stored in an XML
configuration file. You can also generate a binary version of an options table for CA Easytrieve Report Generator on
Windows NT, UNIX, Linux for zSeries, or z/OS.
NOTE
You must use the Configuration Manager to view or modify the CA Easytrieve Report Generator options table.
You cannot access or view the table directly.
This article includes the following information:
How to Create or Modify an Options Table
The process is as follows:
1. Click Tools, Configuration Manager.
The Configuration Manager window opens the last viewed XML file.
2. Perform the appropriate action:
– If the file that you want to modify is open, go to Step 3.
– Click File, Open, select the options table XML file that you want to modify, and click Open.
– Click File, point to New, and then select Options Table from the menu that appears.
3. Define the options as follows:
407
CA Easytrieve® Report Generator 11.6
a. Click the plus box for the options table that you are defining to show the links. The links are compiler, execution,
report, mask, international, and profile.
b. Click the link in the left pane to display the options page you want to modify.
c. Select the appropriate options on the page. See the following sections for option details.
d. Click Apply to save the changes.
e. Repeat steps b through d for each option page.
4. Click File, Save. If you are creating a new option table, enter a file name and click Save.
5. (Optional) Click Build and select the targeted environment (Intel, UNIX, Linux, or Z/OS) to build the binary file.
The binary file is created and is ready to move to the target system.
Define Compiler Options
Follow these steps:
1. Select compiler in the left pane of the Configuration Manager.
The Compiler Options page appears in the right pane.
2. Accept the default, or specify a new value in the option fields.
3. Enable or disable the appropriate check box options.
4. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to save the default settings.
Define Execution Options
Follow these steps:
1. Select execution in the left pane of the Configuration Manager.
The Execution tab fields appear in the right pane.
2. Accept the default, or specify a new value in the option fields.
3. Enable or disable the appropriate check box options.
NOTE
Options marked with (z/OS) affect execution in z/OS only.
4. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to save the default settings.
Define Environmental Options
Follow these steps:
1. Click the Environmental tab.
2. Accept the default, or specify a new value in the option fields.
NOTE
For options marked as z/OS, the value only affects execution in z/OS.
3. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to save the default settings.
408
CA Easytrieve® Report Generator 11.6
Define Sort Options
Follow these steps:
1. Click the Sort tab.
2. Accept the default, or specify a new value in the option fields.
3. Enable or disable the appropriate check box options.
NOTE
For options marked as z/OS, the value only affects execution in z/OS.
4. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to save the default settings.
Define SQL Options
Follow these steps:
1. Click the SQL tab.
2. Accept the default, or specify a new value in the option fields.
NOTE
For options marked as z/OS, the value only affects execution in z/OS.
3. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to save the default settings.
Define IDMS Options
The IDMS options only apply to z/OS.
Follow these steps:
1. Click the IDMS tab.
2. Accept the default, or specify a new value in the option fields.
3. Enable or disable the appropriate check box options.
4. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to save the default settings.
Define Report Options
Follow these steps:
1. In the left pane of the Configuration Manager, select report.
The Report Options page appears in the right pane.
2. Accept the default, or specify a new value in the option fields.
3. Enable or disable the appropriate check box options.
4. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to save the default settings.
409
CA Easytrieve® Report Generator 11.6
Define Mask Options
Follow these steps:
1. Select mask in the left pane of the Configuration Manager.
The Mask Options page appears in the right pane. You can use a mask ID in the MASK parameter of the DEFINE or
ROW statement to identify a mask that is used in a CA Easytrieve Report Generator program.
2. (Optional) To add a Mask and Mask Literal to the list, specify the following options and click Add:
– Mask
Select a letter from the drop-down menu for the User Mask. The range is A through Y.
Note: Using letters at the end of the alphabet avoids conflicts with programmer coded masks, as programmers
typically select letters at the beginning of the alphabet.
– Mask Literal
Enter a literal value for the User Mask letter you chose. This value is the Mask Literal.
3. (Optional) To remove a Mask and Mask Literal from the list, select a User Mask and Mask Literal and click Delete.
4. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to save the default settings.
NOTE
For information about coding masks, see MASK Parameter.
Define International Options
Follow these steps:
1. Select international in the left pane of the Configuration Manager.
The International Options page appears in the right pane.
2. Accept the default, or specify a new value in the option fields.
Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to save the default settings.
Modify or Create a New Profile
Two profile definitions are included with CA Easytrieve Report Generator: Printer and Terminal. You can use the
definitions as they are with the default settings, modify a definition, or create a new definition.
Follow these steps:
1. Open the Configuration Manager as described previously.
2. Do one of the following actions:
– Expand profiles, and select the profile that you want to modify.
– Right-click profiles, and click Add Printer Profile.
3. Accept the default, or specify a new value in the option fields.
4. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to save the default settings.
Save the Options Table
To save the options table, do one of the following actions:
• Click File, Save.
• Click File, Save As, enter a file name, and click Save.
410
CA Easytrieve® Report Generator 11.6
Create a Binary Version of the Options Table
To create the binary version of the options table, select the appropriate platform from the Configuration Manager Build
menu.
Select one of the following platforms:
• Intel
• Unix
• Linux
• z/OS
A message appears, confirming that the options table has been built. The default location of the file is the same folder that
contains the options table XML file. If the binary file is to be used on another system, you must ftp it to the system.
Mainframe Considerations
If the destination system of the ftp is a z/OS mainframe, the resulting file on the mainframe must be specified on the
EZOPTBL DD statement in the compilation and execution JCL that is used to compile and run the CA Easytrieve Report
Generator program. This target file on the mainframe was allocated by the CA Easytrieve Report Generator installation job
JOB01ALC, and its DSN ends with "…EZOPTBL". If you are adding a new data set, allocate using the same attributes as
the installed file.
Create or Modify a Printer Set Definition
The Configuration Manager lets you create and modify printer set definitions (PSDs). Printer set definitions are stored in
an XML configuration file. You can also generate a binary version of a PSD for CA Easytrieve Report Generator on the
Windows NT, UNIX, Linux for zSeries, and z/OS.
NOTE
Configuring a Printer Set Definition requires knowledge of printer concepts and the Extended Reporting
feature of CA Easytrieve Report Generator. For more information, see Extended Reporting and the Report
Processing section.
This article includes the following information:
How to Create or Modify a Printer Set Definition
The process is as follows:
1. Click Tools, Configuration Manager.
The Configuration Manager window opens the last viewed XML file.
NOTE
You can also open the Configuration Manager from the CA Easytrieve Report Generator program menu.
2. Perform the appropriate action:
– If the file that you want to modify is open, go to Step 3.
– Click File, Open, select the printer set definition XML file that you want to modify, and click Open.
– Click File, point to New, then select Printer Set Definition from the menu that appears.
3. Click the printer that you want to define, for example, HTML or RTF, and define the properties on the Printer page.
4. Define the remaining properties as follows:
a. Click the plus box for the printer you are defining to show the links. The links are dataset, defaults, fileheaders,
filetrailers, or fonts.
b. Click the link in the left pane to display the properties page you want to modify.
411
CA Easytrieve® Report Generator 11.6
c. Define the attributes on the page.
d. Click Apply to save the changes.
e. Repeat Steps b through d for each property page.
5. Click File, Save. If you are creating a new printer set definition, enter a file name and click Save.
6. (Optional) Click Build and select the target environment (Intel, Unix, Linux, or z/OS).
The binary file is created and is ready to move to the target system.
Add a New Printer
Follow these steps:
1. Right-click the set icon.
The Add Printer pop-up button appears.
2. Click Add Printer.
The New Printer dialog appears.
3. Enter the new name of the printer and click OK.
A new printer is added.
Copy a Printer
Follow these steps:
1. Right-click the printer icon for the printer you want to copy.
The pop-up menu appears.
2. Click Copy Printer.
The New Printer dialog appears.
3. Enter the name of the new printer and click OK.
An icon for the new printer appears in the left pane.
Rename a Printer
Follow these steps:
1. Right-click the printer icon.
The pop-up menu appears.
2. Click Rename Printer.
The New Printer dialog appears.
3. Enter the new name of the printer and click OK.
The printer is renamed.
Delete a Printer
Follow these steps:
1. Right-click the printer icon.
The pop-up menu appears.
2. Click Delete Printer.
The printer is deleted.
Printer Codes
The Printer Set Definition holds several printer codes that are sent directly to the printer device. If you must insert
hexadecimal codes, insert them in the format X’xx’ where xx is one or more pairs of hexadecimal characters (0-9 A-F).
412
CA Easytrieve® Report Generator 11.6
Define Printer Properties
Use the Printer page to define properties that describe the basic printer characteristics.
Follow these steps:
1. Select the appropriate printer and configure the options on the Printer page.
2. Specify the following properties:
– Printer Name
Enter the name of the reporting printer. Each reporting printer in a printer set definition must be assigned a unique
name. This name is used to identify to the Reporting Environment which reporting printer is to be the target of a
report.
– Printer Type
This attribute identifies a reporting printer type as a line printer.
– Printer Description
Enter an optional keyword that you can use to assign a description for the reporting printer.
– Printer Use
This attribute identifies a reporting printer as a SYSTEM printer.
– Control
This attribute specifies the technique that is supported by the printer to control the vertical line position on a page.
Select one of the following options:
• ANSI: Specify that ANSI print control characters are to be used to control vertical position. This is the default.
• ANSI, NOFCB: Specify that the ANSI print control characters are to be used without a forms control block.
When you do not specify the NOFCB operand, the Reporting Environment implements the ANSI print control
characters in association with a forms control block.
• FEEDCHAR: Specify that feed characters are to be used to control vertical position on a page. When you specify
the FEEDCHAR operand for the CONTROL keyword, you must also specify the FORMFEED and LINEFEED
commands to define the feed characters.
In addition, if you specified the OVERPRINT keyword for this reporting printer, you must also specify the RETURN
command to define the carriage return feed character so that the Reporting Environment can overprint print
records.
• MACHINE: Specify that machine print control characters are to be used to control vertical position.
• MACHINE, NOFCB: Specify that the machine print control characters are to be used without a forms control
block. When you do not specify the NOFCB operand, the Reporting Environment implements the machine print
control characters in association with a forms control block.
• NONE: Specify that no printer control code is to be used for the reporting printer and vertical position on a page
is maintained by outputting blank print records.
• POINTSKIP: Specify that point skip control code is to be used to control vertical position on a page. When you
specify the POINTSKIP operand for the CONTROL keyword, you must also specify the PSNEWPAGE and
PSNEWLINE commands to define the point skip control codes.
– Overprint
This attribute specifies the technique that the printer supports for print records that overprint.
Specify one of the following values:
• MERGE: Specify that the reporting printer supports the merge overprint technique to combine multiple print
records into one print line.
• PRINT: Specify that the reporting printer supports the print overprint technique to combine multiple print records
into one print line.
– Maximum Records
Enter a value from 1 through 256. This attribute defines the maximum number of print records that can be
overprinted for one print line.
– Linefeed
413
CA Easytrieve® Report Generator 11.6
Enter the control code that causes a NewLine for a printer using the FeedChar form of paper control. This
command is required for a line printer type when you specify FEEDCHAR for the CONTROL option. You can only
specify one LINEFEED command per reporting printer.
– FormFeed
Enter the control code that is used to define the control code that causes a NewPage for a printer using the
FeedChar form of paper control. This command is required for a line printer type when you specify FEEDCHAR for
the CONTROL option. You can only specify one FORMFEED command per reporting printer.
3. Specify the following properties in the Point Skip Attributes section for a printer using the Point Skip form of paper
control (the Control option):
– New Line Printer Control Code
– Enter the control code that causes a NewLine for a printer using the point skip form of paper control.
– New Page Printer Control Code
Enter the control code that causes a NewPage for a printer using the Point Skip form of paper control.
– Start Position
Enter the start position in the Point Skip printer control code for a merge operation.
– Length
Enter the length in the Point Skip printer control code for a merge operation.
– Type
This attribute specifies the type of value to be merged into the Point Skip printer control code.
Select one of the following types:
• BINARY
• UNSIGNED PACKED
4. Specify the following properties:
– Record End
Enter the printer control code that must delimit the end of each print record output to the printer.
– Record Pad
Enter the printer control code that must pad the end of each fixed-length print record output to the printer.
– Return
Enter the printer control code that causes a carriage return without a NewLine for a printer using the FeedChar form
of paper control (the Control option).
5. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to undo the changes.
Define Dataset Properties
Use the Dataset page to define properties that describe the basic record characteristics of the report printer.
Follow these steps:
1. In the left pane, select dataset under the appropriate printer.
The Dataset page appears in the right pane.
2. Specify the following properties:
– ASA
Enable this option for the default RECFM=A attribute of the data set generated by the Reporting Environment for
the reporting printer. Disable when you do not want the RECFM=A attribute assigned to the data set.
– Record Format
This attribute controls the default record format, record length, and blocksize attributes of the data set generated by
the Reporting Environment for the reporting printer.
Specify one of the following options:
414
CA Easytrieve® Report Generator 11.6
• F: Specify fixed length, unblocked print records. Also enter a value for Record Length.
• FB: Specify fixed length, blocked print records. Also enter values for Record Length and Block Length.
• V: Specify variable length, unblocked print records. Also enter a value for Record Length.
• VB: Specify variable length, blocked print records. Also enter values for Record Length and Block Length.
• U: Specify print records output in blocks of undefined length. Also enter a value for Block Length.
– Record Length
Enter the fixed length of the print record. The default is 2048.
– Block Length
For blocked records, enter the block length.
– Device Type
This attribute specifies the default device attribute of the data set from the drop-down list.
Specify one of the following types:
• DISK: Specify that the data set generated by the Reporting Environment is to be output to a disk device.
• PRINTER: Specify that the data set generated by the Reporting Environment is to be output directly to the
printer.
• TAPE, NORWD: Specify that the data set generated by the Reporting Environment is to be output to a tape
device; stops the tape being rewound both when the data set is opened and when the data set is closed.
• TAPE, REWIND: Specify that the data set generated by the Reporting Environment is to be output to a tape
device; causes the tape to be rewound when the data set is opened on the tape.
• TAPE, UNLOAD: Specify that the data set generated by the Reporting Environment is to be output to a tape
device; causes the tape to be rewound and unloaded when the data set is closed.
– Print Record Maximum Length
Enter the maximum length of the print record that is supported by the reporting printer.
– Print Record Maximum Bytes
Enter the maximum number of bytes for the print record that is supported by the reporting printer.
NOTE
Print data is not the same as the length of a print record. In addition to the bytes of data that actually print
on a page of a report, a print record can also contain various printer control codes (such as paper control
codes, overprint codes, function headers, and function trailers).
If a reporting printer can only support a limited amount of print data in a print record, you can use the
MAXDATA keyword to specify that limitation. When you specify a MAXDATA value, the Reporting
Environment will ensure that no print record will be output to that reporting printer with print data in excess
of the Print Record Maximum Bytes value.
3. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to undo the changes.
Define Defaults Properties
Use the Defaults page to define the font and page properties of the report printer.
Follow these steps:
1. In the left pane, click defaults under the appropriate printer.
The Defaults page appears in the right pane.
2. Specify the Base Font (SBCS). Enter the reporting font that is assigned a data format of EBCDIC/ASCII. The default
is 3. Optionally enter the reporting formats assigned a data format of DBCS Font and Mixed Font if the printer
supports DBCS character sets. The reporting fonts must be defined for the reporting printer. For more information,
see Supported Formats.
3. Specify the following in the Font Size section:
415
CA Easytrieve® Report Generator 11.6
– Font Number (Width)
Enter the number of the font whose width attribute is used to convert column- and character-based widths and
horizontal positions into printer-based widths and horizontal positions. The default is 3.
– Font Number (Height)
Enter the number of the font whose height attribute is used to convert column- and character-based heights and
vertical positions into printer-based heights and vertical positions for printers that require them. This applies to Line
printers that support ANSI or machine paper control without an FCB and Line printers that support point skip paper
control. The default is 3.
4. Specify the following in the Page Properties section:
– Page Width
Enter the maximum width of a print line that is supported by the reporting printer.
– Page Height
Enter the maximum height of a page that is supported by the reporting printer.
5. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to undo the changes.
Define File Header Properties
Use the File Header page to define the record header properties of the report printer.
Follow these steps:
1. In the left pane, click fileheaders under the appropriate printer.
The File Header page appears in the right pane.
2. Do one of the following actions:
– To modify an existing file header, select it in the file header list. The current values are displayed. Continue with
Step 4 and modify the values as needed.
– To create a file header, continue with Step 3.
– To remove a file header, select it in the file header list and click Remove.
3. Enter the printer control code data that is sent to the printer to accomplish positioning in the Print Control Code field.
4. Specify the following attributes in the Current Record Number Attributes section:
– Start Position
Enter the start position in the printer control code for the merge operation.
– Length
Enter the length in the printer control code for the merge operation.
– Type
This attribute specifies the type of the value to be merged into the printer control code from the drop-down list.
Select one of the following types:
• BINARY
• UNSIGNED PACKED
5. Specify the following attributes in the Current Record Length Attributes section:
– Start Position
Enter the start position in the printer control code for the merge operation.
– Length
Enter the length in the printer control code for the merge operation.
– Type
Select the type of the value to be merged into the printer control code:
• BINARY
• UNSIGNED PACKED
6. Do one of the following actions:
416
CA Easytrieve® Report Generator 11.6
– If you are modifying an existing header, click Modify.
– If you are creating a new header, click Add.
7. (Optional) To change the order of a file header, select it in the file header list and click Move Up or Move Down.
File Trailer Properties
Use the File Trailer page to define the record trailer properties of the report printer.
Follow these steps:
1. In the left pane, select filetrailers under the appropriate printer.
The File Trailer page appears in the right pane.
2. Do one of the following actions:
– To modify an existing file trailer, select it in the file trailer list. The current values are displayed. Continue with Step 4
and modify the values as needed.
– To create a file trailer, continue with Step 3.
– To remove a file trailer, select it in the file trailer list and click Remove.
3. Enter the printer control code data that is sent to the printer to accomplish positioning in the Print Control Code field.
4. Specify the following attributes in the Current Record Number Attributes section:
– Start Position
Enter the start position in the printer control code for the merge operation.
– Length
Enter the length in the printer control code for the merge operation.
– Type
This attribute specifies the type of the value to be merged into the printer control code from the drop-down list.
Select one of the following types:
• BINARY
• UNSIGNED PACKED
5. Specify the following attributes in the Current Record Length Attributes section:
– Start Position
Enter the start position in the printer control code for the merge operation.
– Length
Enter the length in the printer control code for the merge operation.
– Type
Select the type of the value to be merged into the printer control code:
- BINARY
- UNSIGNED PACKED
6. Do one of the following actions:
– If you are modifying an existing header, click Modify.
– If you are creating a new header, click Add.
7. (Optional) To change the order of a file trailer, select it in the file trailer list and click Move Up or Move Down.
Add a New Font
Follow these steps:
1. Right-click the font icon.
The Add Font pop-up button appears.
2. Click Add Font.
The New Font dialog appears.
3. Enter the number and width of the new font and click OK.
The new font is added to the printer.
417
CA Easytrieve® Report Generator 11.6
Copy a New Font
Follow these steps:
1. Right-click the font icon of the font you want to copy.
The Copy Font pop-up button appears.
2. Click Copy Font.
The New Font dialog appears.
3. Enter the number and width of the new printer and click OK.
The new font is added to the printer.
Rename a Font
Follow these steps:
1. Right-click the font icon.
The Rename Font pop-up button appears.
2. Click Rename Font.
The New Font dialog appears.
3. Enter the new number and width of the font and click OK.
Delete a Font
Follow these steps:
1. Right-click the font icon.
The Delete Font pop-up button appears.
2. Click Delete Font.
Define Font Properties
Use the Font page to define the properties for each font of the report printer.
Follow these steps:
1. In the left pane, expand fonts under the appropriate printer.
2. Select the number of the font that you want to configure.
The Font page for the selected font appears in the right pane.
3. Specify the following properties:
– Name
(Optional) Enter the name of the reporting font that is assigned to the number. The default is the font number.
– Number
This field indicates the unique font number.
– Description
(Optional) Enter a description of the font.
– Height
Enter the height attribute of the font.
The Height value is required when the following conditions apply:
• The reporting font supports EBCDIC or ASCII format data.
• The reporting printer must process height and vertical position values. This applies to line printers that support
ANSI or machine paper control without an FCB and Line printers that support point skip paper control.
– Width
Enter the width attribute of the font. The Width value is required when defining a reporting font that supports
EBCDIC or ASCII format data.
– Line Complex
418
CA Easytrieve® Report Generator 11.6
(Optional) Enter the number of lines that the printer supports the font as a line complex. If specified, identifies that
the reporting printer supports the reporting font as a Line Complex. A line complex supports printing a print element
across multiple print lines on a report.
Enter one of the following values:
• 2—If the reporting font supports a Two Line line complex.
• 4—If the reporting font supports a Four Line line complex.
– Space Replace Character
(Optional) Enter the 1-byte character that is used to replace occurrences of X'40' in the print data element that is
associated with the font. This can only be specified when the reporting printer is a line printer with an overprint
attribute of merge.
4. Specify the following properties in the Font Header section:
– Printer Control Code
Enter the font header printer control code that is sent to the printer to accomplish printing.
– Merge Operation Start Position
Enter the start position in the printer control code for the merge operation.
– Length
Enter the length in the printer control code for the merge operation.
– Type
Select the type of the value to be merged into the printer control code:
• BINARY
• UNSIGNED PACKED
5. In the Printer Control Code field of the Font Trailer section, enter the font trailer printer control code that is sent to the
printer to accomplish printing.
6. In the Printer Control Code field of the Overprint Printer section, enter the printer control code overprint code that
identifies the font to a printer. Data is formatted onto a print record with the specified opcode printer control code at the
beginning of the print record.
NOTE
This option is only used if the printer is set to OVERPRINT.
7. Do one of the following actions:
– Click Apply to save the changes.
– Click Reset to undo the changes.
Save the Printer Set Definition
To save the Printer Set Definition, do one of the following actions:
• Click File, Save.
• Click File, Save As, enter a file name, and click Save.
Create a Binary Version of the Printer Set Definition
To create the binary version of the printer set definition, click Build and select the appropriate platform:
• Intel
• Unix
• Linux
• z/OS
A message appears, confirming that the Printer Set Definition has been built. The default location of the file is the same
folder that contains the Printer Set Definition XML file. If the binary file is to be used on another system, you must ftp it to
the system.
419
CA Easytrieve® Report Generator 11.6
Mainframe Considerations
If the destination system of the ftp is a z/OS mainframe, follow these steps before executing the FTP:
1. After building the Printer Set Definition file, make a note of the size of the file that is generated on the PC.
2. On the target mainframe, go to the =3.2 screen in TSO and allocate the hlq.EZTXRPSD file with the Block Size/
Record Length (they are the same value) equal or greater than the size of the PC file. The file is a fixed-length,
unblocked file. The SPACE for the file should be three blocks of the size that is used above.
The resulting file on the mainframe must be specified on the EZTXRPSD DD statement in the compilation JCL that is
used to compile the CA Easytrieve Report Generator program that references a printer that is defined in that Printer Set
Definition file.
Sample Printers
This section explains the sample printer definitions included with CA Easytrieve Report Generator.
Supported Formats
CA Easytrieve Report Generator contains a subset of the extended reporting capabilities that are provided by other
versions of the product for the mainframe. This subset lets you produce reports that are formatted for line mode printers
only.
CA Easytrieve Report Generator provides a printer set definition module that defines the following printers:
• Hypertext Markup Language (HTML)
• Rich Text Format (RTF)
The Configuration Manager lets you customize these definitions and add your own definitions.
HTML Printer Specification
The HTML printer wraps your report data in the special HTML codes required by HTML specifications. In addition, each
item is wrapped in codes necessary to format the item.
Fonts 1 through 7 format the data using HTML font sizes 1 through 7, respectively. For example:
<FONT SIZE=1>data</FONT>
The default font is font 3.
Fonts 11 through 17 format the data using HTML font sizes 1 through 7, respectively, and add the BOLD code. For
example:
<FONT SIZE=1><B>data</B></FONT>
Fonts 21 through 27 format the data using HTML font sizes 1 through 7, respectively, and add the ITALIC code. For
example:
<FONT SIZE=1><I>data</I></FONT>
Font 99 is a special font used to insert a horizontal rule (<HR>) into the report. Horizontal rules are useful for separating
areas of your report. For example, because HTML does not contain page breaks, you may want to add horizontal rules as
visual breaks between report pages. To do this, simply add the following statements to your report declaration:
ENDPAGE. PROC
DISPLAY #99 ' '
END-PROC
420
CA Easytrieve® Report Generator 11.6
RTF Printer Specification
The RTF printer wraps your report data in the special RTF codes required by RTF specifications. In addition, each item is
prefixed by codes necessary to format the item.
The following fonts are provided to format your reports. Each font index identifies the point size of the item. The font name
is Courier New in landscape orientation:
8, 9, 10, 11, 12, 14, 16, 18, 20,
22, 24, 26, 28, 36, 48, and 72
The default font is font 8.
Workbench Tools and Utilities
This section provides descriptions of CA Easytrieve® Report Generator tools and utilities and instructions about how to
use them to perform the tasks required to manage and maintain your programs and files; it includes:
• The Workbench Explore window
Manage drives, directories, and files, connect to FTP servers to upload and download files and programs, and connect
to JES to manage jobs and job output in the mainframe JES queue.
• The Host Profile Manager
Specify and maintain profiles containing variables such as Host Name, User ID, Directory, Port, and other information
needed to connect to remote FTP servers and to JES.
• The Program Profile Manager
Create and save profiles for individual programs or subdirectories. Tabs let you specify variables and instructions for
program compile and execution, program submission, packaging, and filters and you can indicate whether the profile is
to be used as a default for the subdirectory.
• Utilities
Perform data conversion tasks, package programs for delivery to an end user, manage environment variables, and
submit a program for execution on a remote server.
Workbench Explore
The Workbench Explore window consists of the Open window, the FTP control and the JES control.
The Workbench Explore window provides the following features:
The splitter bar provides tab control access to each of these features.
NOTE
The splitter bar width can be changed by positioning the caret over the splitter bar. At this point, the mouse will
be captured and the mouse pointer will change to an east/west caret. To resize the splitter bar, hold down the left
mouse button and drag the splitter bar left or right to the desired width. All windows within the Tab Control will be
resized to reflect the width of the splitter bar.
The Open Window
The Open window gives the user a graphical tree display of the files that are contained on a particular drive, directory, and
subdirectory; it consists of:
• A combo box for Drives
• A combo box for File names
• Files list box
• Directory tree
421
CA Easytrieve® Report Generator 11.6
How to Select a Drive, Directory, and File
Follow these steps:
1. Select a drive from the Drives combo box.
The folders and files on the targeted drive are displayed in the Directory and File Name list boxes.
2. Locate the directory that contains your programs.
Double-click a directory to drill down into the subdirectories and display the files.
NOTE
A single click displays the subdirectories under a directory and adds a plus sign to the tree.
3. Do one of the following:
– Enter a complete file name and file type in the File Name combo box.
– Enter a partial name with wildcards (for example, P*.* will display all files that start with the letter P).
– To locate your file:
a. Display the list of pre-programmed file types (*.ezt, *.mac, *.lst) in the File Name combo box.
b. Select your file type
c. Select your file from the list in the Files combo box.
4. Double-click the file name to display your file in an Edit window.
Update a File
Follow these steps:
1. Locate and select the file. See How to Select a Drive, Directory, and File for more information.
The file is displayed in the Edit window.
2. Use the commands on the Edit menu and customary word processing editing procedures to modify your file.
3. Click the Close file button in the upper right corner.
A confirmation dialog is displayed.
4. Click Yes to update the file.
Clone a File from an Existing File
Follow these steps:
1. From the Files combo box, right click a file.
2. Click Copy.
3. Right-click in the Files combo box again
4. Click Paste
The Paste to File dialog appears.
5. Enter a new name and click OK
The new file appears in the File Name combo box.
Manage Files and Directories in the Open Window
You can use the Dir and File Name combo boxes to manage the files in your directory.
Follow these steps:
1. Double-click a directory to display files and subdirectories. Right-click a file in the Files combo box to display the
command menu.
NOTE
If you are attempting to copy text from one file to another, copied text replaces any text in an existing file, it
does not append.
422
CA Easytrieve® Report Generator 11.6
2. In addition to the standard Cut, Copy, Delete, Rename commands, use the following as needed. Note that all
commands except Refresh and Create Directory relate to the object selected in the Files window.
– Paste
This option is enabled only if there is a text object on the clipboard.
Paste the text that was copied to the clipboard into the current directory file. You will be prompted to enter the name
of an existing file or a file that is to be created.
– Upload
Upload the selected file to the current FTP session. You will be prompted for the name of the file that is to be
created on the host system.
This option is enabled only if there is an active FTP session.
– Create Directory
Create a subdirectory under the current directory. You will be prompted for the name of the directory to be created.
Close or Activate the Explore Window
After installation, the Explore window opens by default. It can be closed or activated as needed.
• Close the Explore window
Click the red X icon in the upper right corner of the window.
• Activate a closed Explore window
Select View, Explore window.
JES Control
The JES control lets you to manage the jobs and job output contained in the mainframe JES (Job Entry Subsystem) from
within the CA Easytrieve® Report Generator Workbench IDE. Since not all CA Easytrieve® Report Generator users are
mainframe clients, the JES interface will not be visible at install time and must be enabled to make it available.
The JES control is selected by clicking the JES tab in the splitter bar.
When there is no active JES session, the JES control consists of the following:
• A combo box (Profile)
The Profile combo box contains a list of previously used profiles. Pressing the down arrow will display the list. Clicking
on an item will connect to JES using the selected profile.
• A connect button
• A disconnect button
• A refresh button
• An edit control (Owner prefix) and a static text message area.
The Owner prefix edit control allows you to select the owner of the jobs that you want displayed. This is useful for
controlling the amount of entries displayed so that only the desired jobs are displayed or for viewing JES items not
directly associated with your logon ID.
Connect to the JES Queue
The values stored in the Host Profile are used to make the MVS connection to the JES queue.
Follow these steps:
1. If necessary, activate the JES tab from Options, Enable JES tab.
2. Do one of the following:
– Click a profile in the Profile combo box.
If you have previously used the JES tab, the Profile combo box will be populated with your most recently used list.
You will automatically be connected to the host you select from the list.
423
CA Easytrieve® Report Generator 11.6
Note: You can have multiple host profiles but only the hosts you go to get added to that combo box.
– For a first-time connection to a host: Click Connect on the JES tab.
The Select Host Profile for JES dialog is displayed. Click Add.
The Add Host Profile dialog is displayed Add a new profile.
See Host Profile Manager for more information.
The new profile is included on the list in the Select Host Profile for JES dialog and is selected.
Click Select.
The JES connection is made and a list of the jobs in the JES queue is displayed in tree view. The list contains all of the
jobs for the targeted owner prefix, not just the jobs that were submitted using the workbench; this is similar to the type
of listing displayed by products like SDSF or SYSVIEW.
If the connection cannot be established or the system is not a z/OS system, an error message is displayed.
3. Click the disconnect button when done.
Change the Owner Prefix
The Owner Prefix edit control allows you to change the owner prefix you are using to access JES listings.
Enter the owner prefix as you would if you were viewing the JES queue under SDSF or SYSVIEW.
Only the jobs for the targeted user will be displayed.
Manage Jobs in the JES Queue
The various components and output files for a job can be viewed, or, a job in the JES queue can be deleted or canceled.
View the Component Files of a Particular Job
Follow these steps:
1. Click the plus sign next to the job.
The tree expands to show the various output files managed by JES for that job.
2. Pass the pointer over a job or a component.
A tooltip window is displayed that shows complete information about the item.
3. Click the targeted component file to display it.
The file is displayed in a read-only window.
Delete a Job and its Components
Follow these steps:
Right-click a job and one of the following will occur:
• If the job has completed, you can delete the job and components
• If the job has not completed, use the menu to cancel the job
All of its associated components will also be removed from the JES queue.
NOTE
Click Refresh to refresh the contents of the JES control at any time.
FTP Control
The FTP control is selected by clicking the FTP tab in the splitter bar. The FTP control lets you download and upload
programs or data files directly from within the CA Easytrieve® Report Generator Workbench.
You connect to remote FTP servers using the values specified within a profile which is defined and maintained using the
Host Profile Manager.
424
CA Easytrieve® Report Generator 11.6
When there is no active FTP session, the FTP control consists of the following:
• A combo box containing previously accessed remote hosts
• Connect and Disconnect buttons
• An ASCII transfer button (ABC icon) and a binary transfer button (010 button)
See Enable ASCII Upload and Download for an FTP Session for more information.
• A static text message area
• An abort button.
NOTE
Hovering the cursor over the buttons will display a tooltip for the button.
How the FTP Control Works
The Host Profile Manager lets you create and manage the profiles you use to make FTP connections. Clicking on any
item in the Profile combo box connects you to FTP using that profile. See Host Profile Manager for more information.
Once the FTP session has been established, the Files list box and Dir (directory) tree view for that definition are displayed
in the Files and Dir combo boxes.
NOTE
For MVS systems, a directory refers to a PDS or PDSE file structure; if selected the members contained within
the PDS(E) are displayed within the file list.
Manage Files and Directories Accessed Using FTP
Download and update files and directories using FTP.
Follow these steps:
1. Double-click a file in the Files combo box. The following actions occur:
– The file is downloaded into the temp directory as specified by the environment variable TEMP or TMP.
– The file is displayed in the Workbench edit window.
– The number of bytes downloaded is displayed as the download progresses. Right-click a file to display the
commands that can be used on the file and directory.
In addition to the standard Cut, Copy, Delete, Rename, and Refresh commands, use the following as needed.
– Paste
Paste the text that was copied to the clipboard to the current FTP session. You will be prompted to enter the name
of the file that is to be created. The file will be created in the current directory (or PDS).
Note: This option is enabled only if there is a text object on the clipboard.
– Download
Download the selected file to your local system. You will be prompted for the name of the subdirectory/file that is to
be created as well as the mode to be used for the file transfer.
– Create Directory
Create a subdirectory under the current directory. You will be prompted within a dialog for the name of the directory
to be created.
– Change Directory
Allows you to change to another subdirectory (or high-level qualifier on z/OS) on the host. You will be prompted
within a dialog for the name of the directory to change into.
Note: When you specify a subdirectory on a z/OS host, you are, in effect, changing the high-level qualifier (HLQ) on
that host. This should be specified in the 'HLQ' (the quotes are important within this command).
– Properties
Display the properties for the selected file. The name, creation date, creation time, size and attributes are
displayed. This display will vary based upon the type of system.
425
CA Easytrieve® Report Generator 11.6
To abort a transfer
Click the abort button.
To save a file
Do one of the following:
• Click Save.
The file is automatically uploaded to the host.
• Select File, Save As.
Choose your directory to save a local copy of the file.
Start or Terminate an FTP Session
An FTP session can be started from either the FTP tab or from the Host Profile Manager dialog.
Start an FTP Session
Follow these steps:
1. Do one of the following:
– From the FTP tab
Click the Connect icon on the FTP tab or if you have previously connected to FTP, select that host from the Profile
combo box.
– From the Host Profile Manager.
Choose Tools, Host Profile Manager to display the Host Profile dialog.
2. Select a previously-defined profile from the list in the Profiles list box.
3. Click Connect in the Host Profile Manager.
The FTP session is established.
Terminate an FTP Session
Click the Disconnect button on the FTP tab.
Host Profile Manager
Host profiles contain information such as the Host Name, User ID, Directory, Port, and so on. Use the Host Profile
Manager to add, delete, edit, rename, and copy profiles that are used to connect to remote FTP servers and JES.
Contents
Use the Add Host Profile Dialog
Follow these steps:
1. From Tools, select Host Profile Manager.
The Select Host Profile for JES or the Add Host Profile dialog is displayed, depending on whether you started from the
JES tab or the FTP tab.
2. Click Add.
The Add Host Profile dialog appears.
3. Complete the following fields:
– Profile Name
A name that describes the profile and makes it easy for you to remember what host system you are working with
– Host Name
426
CA Easytrieve® Report Generator 11.6
The name of the host system as it is known to FTP.
– User ID
Your User ID as it is known to the host system.
– Password
Your password as it is known to the host system.
– Save Password
If this box is checked, your password will automatically be sent to the host system when you connect, otherwise,
you will be prompted for your password when you attempt to connect.
Once the password has been entered and a connection has been established, subsequent connections will use this
password.
– Directory
Enter the initial directory that is to be used once the connection has been established.
• For MVS systems: Enter the high level qualifier in single quotes with the components separated by periods.
• For UNIX: Enter the directory name with the components separated by forward slashes '/'. For Windows, enter
the directory name with the components separated by backwards slashes '\'.
– Port
The FTP port number (usually 21).
– Keep Alive
Check this box if you would like to keep the FTP session from timing out.
– Interval (sec)
The keep alive interval. The FTP session will be refreshed when the keep alive interval time limit has been reached.
Set this to a value that is less than the timeout value of the host FTP server.
– Code Page
This specifies the code page to be used for ASCII data translation between the mainframe and the PC during file
upload, download and remote job submission.
This value must be set to the proper code page so that the Workbench can display characters that are not defined
in the default code page.
For example, if you are using the Euro or other national characters, the code page can be set to 924 Multinational
ISO Euro.
Note: The Workbench font must also be set to a font that supports the Euro and other national characters, such as
Lucida Console.
– Use plink ssh client for job submission (UNIX Only) -
Enables the use of the plink SSH client for remote job submission to UNIX systems. The plink (PuTTY link) client is
used instead of the Windows rsh (remote shell) client.
– Transfer Type
The desired transfer type:
• ASCII Trimmed - The file is translated on download or upload according to the FTP server translation method
and trailing spaces are trimmed. This option removes trailing spaces when files are downloaded from a fixed
length MVS PDS.
• ASCII - The file is translated on download or upload according to the FTP server translation method.
• BINARY - The file is transferred as is. No translation is performed.
4. Click OK.
The profile information is added.
Use the Edit Host Profile Dialog
Follow these steps:
1. From Tools, select Host Profile Manager.
The Select Host Profile for JES or the Edit Host Profile dialog is displayed, depending on whether you started from the
JES tab or the FTP tab.
427
CA Easytrieve® Report Generator 11.6
2. Click Edit.
The Edit Host Profile dialog is displayed.
3. Update the values in the fields as required.
4. Click OK.
The profile information is updated.
Enable ASCII Upload and Download for an FTP Session
Some UNIX systems (in particular - zLinux) may not have ASCII upload and download enabled by default.
Follow these steps:
1. Be sure that the file /etc/vsftpd.conf has "ascii_upload_enable=YES" and "ascii_download_enable=YES".
2. Click the ASCII button.
ASCII upload and download are enabled.
Program Profile Manager
The Program Profile Manager lets you create profiles so that variables and instructions for a CA Easytrieve Report
Generator program can be saved and reused. You can define a profile for a specific program or for an entire subdirectory.
The four tabs in the Program Profile Manager dialog let you manage and store program compiler and execution options,
instructions for program submission, filter specifications, and package information.
This article includes the following information:
NOTE
Only one profile may be defined for a program or file name; its name will match the program or file active in an
edit window at the time of creation and it will match any entity with that name in the subdirectory. For example,
program test.ezt and file test.mysjcl will both use the same test.prf profile.
Program Profile Manager Dialog
Use the Program Profile Manager dialog to design and save your processing options, specify whether the profile is for a
specific program or file only, and indicate if it is to be used as the default for the entire subdirectory.
This dialog contains the following tabs:
• Program tab
• Submit tab
• Filters tab
• Package tab
• Set as Default button
Use the Program Profile Manager
Use the Program Profile Manager to create and store your program or file options.
Follow these steps:
1. Select your drive and program directory in the Explore Window.
2. Double-click a program or file in the Files list.
The file or program is loaded into the CA Easytrieve Report Generator Workbench.
3. Select Build, Program Profile.
428
CA Easytrieve® Report Generator 11.6
NOTE
You must open a program or file to use the Program Profile command.
The Program Profile dialog is displayed.
4. Click the appropriate tab and select the options. The sections that follow explain the options on each tab.
5. Click Set as Default if you want the profile to be used as a default profile for the directory.
NOTE
For more information about the default profile, see Set Directory Defaults and Save the Profile.
6. Click OK.
The profile is saved and the dialog closes.
Program Tab
The Program tab lets you set compiler and execution options. You can specify what actions you want to happen during a
compile and supply any execution options that are to be used within the Workbench environment.
Specify Program Compiler and Execution Options
Follow these steps:
1. Click the button of the Compiler Option you want used when you run your program.
– Syntax check only
Performs a syntax check of the program. No PCode file or executable is created and no debugging information is
generated.
– Compile
Compiles the program and, if successful, creates a PCode file that can be executed by the CA Easytrieve Report
Generator interpreter or the debugger engine. Debugging information is generated (in a CVX file).
– Compile and create executable
Creates an executable version of the CA Easytrieve Report Generator program (.exe file). The .exe file can be run
stand-alone from the Command line without the need for the PCode interpreter (ezterp.exe).
No debugging information is generated.
Note: This option is available only if Microsoft Visual Studio version 6.0, 7.0, 7.1, 8.0, VC Express, 9.0, 2010, 2012,
2013, and 2015 has been previously installed on the user's system. If your version is not currently supported,
contact CA Support to check on availability.
2. Specify whether Warning messages are to be displayed as a result of a program compile.
By default, warnings are not displayed unless an error also occurs. Warning messages are helpful during program
development to ensure that statements that might result in runtime errors (although the syntax is correct) are
recognized and fixed.
3. Set program Execution Options.
Define the parameter list that is to be passed to the program when it is executed from within the Workbench. These
values can be obtained and processed by the USING parameter of the PROGRAM statement. See the PROGRAM
Statement for more information.
4. Do one of the following actions:
– Click OK if your definition is finished.
– Proceed to the next tab.
Submit Tab
The Submit tab lets you specify the Host profile to use, the type of output that will be retrieved, and any wrapper files that
are to be included as part of the remote submission. See the Program Submission Utility for more information.
429
CA Easytrieve® Report Generator 11.6
Specify Remote Submission Settings
Follow these steps:
1. Select the Host Profile name.
This is a profile created with the Host Profile Manager that you want to automatically use when you submit your
program. The profile supplies the information that is necessary for connecting to the remote system.
2. Click the desired Output retrieval option.
– All
Specifies that all output for the job will be retrieved in the Workbench Explore window.
• For MVS systems: All JES spool files will be concatenated when displayed; when the job output has been
retrieved, the JES spool files will be deleted.
• For UNIX systems: The job output that was sent to STDOUT and STDERR is displayed in separate edit
windows in the Workbench once the job has completed.
– Hold for select
The job output will not be retrieved in the Workbench window.
For MVS systems, the JES spool files will be left in the JES queue for later retrieval. You may want to use this
option for programs that generate hundreds of pages of output.
– SYSPRINT only
• MVS systems: Only the SYSPRINT output will be retrieved. Each SYSPRINT component will be retrieved in a
separate Workbench window.
• UNIX systems: Only the output that was sent to STDOUT will be retrieved.
Note: The selection of these options may change during the life-cycle of the application. During initial development,
'retrieve all output' may be desirable, but later as your application nears completion, you may simply want to see the
SYSPRINT output to validate program changes.
3. Specify the JCL prolog and epilog wrapper files that are to be used.
– MVS systems: When the program is submitted, it will be "wrapped" between the JCL Prolog and Epilog file.
The prolog file is copied to a temporary file, the program source code is appended, and finally, the epilog file is
appended.
Note: An easy way to create the Prolog and Epilog files is to take the JCL from an existing CA Easytrieve Report
Generator compile-and-go execution. All JCL up to and including the "SYSIN DD *" statement should be used for
the Prolog file. Typically, for the z/OS environment, a "//" statement is all that is required for the Epilog file.
HINT: Creating and storing all Prolog and Epilog files within a single subdirectory allows them to be located and
modified easily as you move within different projects and applications.
– UNIX systems: A command shell is created to compile, execute and capture the output that is sent to STDOUT
and STDERR.
The JCL prolog and epilog files are copied to this script before and after the compilation/execution commands.
These two files allow you to set up the parameters needed to compile and execute the program on a particular
UNIX platform.
Typically, the prolog file will contain the exported environment variables needed to configure database options
and define the external names of required files and is the only Prolog "wrapper" file required. See Program Profile
Manager for more information about the required export variables.
Note: If the remote shell script fails because output to STDERR was captured, this output will be brought up in a
separate edit window for inspection. A file will be created in the TEMP (or TMP) directory with the file name, job
number and an extension of ".submission error text".
4. Click OK if your definition is finished or proceed to the next tab.
Package Tab
The Package tab lets you add additional items needed to properly package your program.
This feature assists in the packaging process for a specific program. Note that if that program has external dependencies
outside of the runtime environment--for instance, called programs or programs executed using the LINK or TRANSFER
430
CA Easytrieve® Report Generator 11.6
statements within the CA Easytrieve Report Generator language--it is the programmers' responsibility to add these
programs to the target subdirectory before delivering the application package. Additionally, data files are not packaged as
part of this process.
The environment variables that are specified will be added as set statements to the generated .cmd file so that when
run_xxx.cmd (where xxx is the name of the program) is invoked, the selected environment variables will be set properly
for execution.
The Package Variables list will be included with the program so that when it is executed, data files can be located. For
more information, see the Package Program Utility.
Specify Items to be Packaged With Your Program
Follow these steps:
1. To include an item with your program, click the appropriate option button.
– Options table
A copy of the Options table is to be packaged with the program.
Note: Package the Options table only if you have changed any of the execution options and these options are
needed to execute the program correctly.
– Report viewer
Indicates that a copy of the CA Easytrieve Report Generator report viewer is to be packaged with the program.
The report viewer is a Windows interface that allows you to view the output of the program (that is, the data that
was sent to STDOUT and STDERR). The report viewer allows you to view plain text, rich text (RTF) or Web-based
HTML. You can then scroll through your report data and print it.
2. Build a list of Environment Variables to be packaged with the program; you can add as many variables as you need.
NOTE
You can view the value of any environment variable by right clicking on it from either window.
The list of variables to be packaged with the program is complete.
Click OK if your definition is finished or proceed to the next tab.
3. To remove an environment variable from the Package variable list, do the following actions:
a. Click the variable.
The Add button changes to Remove.
b. Click the Remove button.
The variable is moved from the Package Variables list back to the Environment Variables list.
Filters Tab
When you compile a program on a PC, you do not need the JCL statements that may be found in mainframe programs.
Use the Filters tab to:
• Define one or more strings that are to be used to filter out source statements
• Specify a default filter that already has the strings defined.
For information about creating a set of default filter strings, see the Source Filter Strings Utility.
Define and Specify Filters
Any statement that starts with any of the text strings specified as a filter will be commented out before the program is
compiled. For example, if you want the Windows compiler to ignore all statements that begin with // and /* (as typically
found in JCL), specify these as filter strings.
Follow these steps:
1. Click the Filters tab in the Program Profile Manager.
431
CA Easytrieve® Report Generator 11.6
2. Define the text strings that are to be used as filters:
a. In Filter Strings, click Add.
The Add dialog is displayed where you can enter a string of characters that will be used as a filter. Click OK.
The characters are added to the list in the combo box.
Use Delete and Edit if you want to remove or modify the text strings you have created.
b. Repeat until all of your filters are defined.
3. (Optional) Check the Use Default Filter Strings check box.
Any strings that you defined here and the strings specified in the default filters strings will be used before the program
is submitted to the CA Easytrieve Report Generator compiler on Windows.
4. Click OK if your definition is finished or proceed to the next tab.
Set Directory Defaults and Save the Profile
After you have made your choices on the four tabs, you can save your profile and set the selected options as your default
settings.
Follow these steps:
1. Click OK to save the profile.
The program profile information is saved as a file with the extension of ".prf" in the same subdirectory as the program.
Each time the program or file is loaded into the workbench, the corresponding profile information is retrieved.
2. Click Set as Default to use these options as default settings.
How Defaults Work
The options that you have selected may be valid for several, or all of your programs. You can specify that the profile that
you have just configured is the default profile for the entire subdirectory.
When you click Save as Default:
• The profile is named default.prf.
• The profile default.prf is saved in the same subdirectory as the currently loaded program or file.
• The profile is set as the default for all programs that are stored in the same subdirectory as the program you are
saving.
NOTE
If a program has a saved profile, the saved profile will take precedence and be used rather than the default.
This allows you to establish certain default actions for all programs within a subdirectory and specific actions that
are to occur for a single program.
How to Set Directory Defaults
You can set the default profile for the current directory or currently loaded file.
Follow these steps:
1. Select Options, Set Default Profile.
The Program Profile manager is displayed.
The dialog that appears is the same one that is used when you are defining an individual program profile (see Use the
Program Profile Manager). Observe that the directory is displayed in the window title bar, as opposed to a program
name.
2. Edit or delete the default profile.
Information is updated for one of the following profiles:
432
CA Easytrieve® Report Generator 11.6
– The profile that is used for all of the programs or files that are contained within the subdirectory of the currently
loaded program or file
– The profile of the last subdirectory used
How to Determine Which Profile Is Being Used
If there is a program or file that is loaded into an edit window, the default profile is assumed to be in the subdirectory of
the loaded program or file, otherwise the subdirectory of the last opened program or file is used when setting the Default
Profile.
Workbench Utilities
CA Easytrieve Report Generator has several tools and utilities accessible from the File, Tools, and Options menus
including:
Data Conversion Utility
Use the Data Conversion utility to convert data that has been downloaded to a PC to a format that matches your existing
data. The Data Conversion Utility applies a pre-defined CA Easytrieve Report Generator macro to your files that specifies
which fields in the input file are to be converted. An output file is generated that has those fields in the targeted format.
This section describes the Data Conversion process and how to use the Data Conversion utility.
Download Files
The Data Conversion utility uses the following types of files as input:
• Data files contain the source data that is used in the report
• Macro files contain data definitions
NOTE
• When you download files, specify binary format for data files and text format for a macro files.
• PC file names (excluding directory) are limited to 8 character positions and should not have any ‘.’ characters
in the name. The macro file name that you specify must either end in .mac or no extension.
Sample Macro File
The following sample macro file is in hlq.CBAAJCL(PERSNL):
MACRO
*
* Personnel File (PERSNL) Field Definitions
*
*
REGION 1 1 N
BRANCH 2 2 N
SSN 4 5 P MASK '999-99-9999' -
HEADING('SOCIAL' 'SECURITY' 'NUMBER')
EMP# 9 5 N HEADING('EMPLOYEE' 'NUMBER')
EMPNAME 17 16 A HEADING 'EMPLOYEE_NAME'
NAME-LAST EMPNAME 8 A HEADING('LAST' 'NAME')
NAME-FIRST EMPNAME +8 8 A HEADING('FIRST' 'NAME')
ADDRESS 37 39 A
433
CA Easytrieve® Report Generator 11.6
ADDR-STREET 37 20 A HEADING 'STREET'
ADDR-CITY 57 12 A HEADING 'CITY'
ADDR-STATE 69 2 A HEADING 'STATE'
ADDR-ZIP 71 5 N HEADING('ZIP' 'CODE')
PAY-NET 90 4 P 2 HEADING('NET' 'PAY')
PAY-GROSS 94 4 P 2 HEADING('GROSS' 'PAY')
DEPT 98 3 N
DATE-OF-BIRTH 103 6 N MASK( 'Z9/99/99') -
HEADING('DATE' 'OF' 'BIRTH')
TELEPHONE 117 10 N MASK '(999) 999-9999' -
HEADING('TELEPHONE' 'NUMBER')
SEX 127 1 N HEADING('SEX' 'CODE')
* 1 - FEMALE
* 2 - MALE
MARITAL-STAT 128 1 A HEADING('MARITAL' 'STATUS')
* M - MARRIED
* S - SINGLE
JOB-CATEGORY 132 2 N HEADING('JOB' 'CATEGORY')
SALARY-CODE 134 2 N HEADING('SALARY' 'CODE')
DATE-OF-HIRE 136 6 N MASK ( 'Z9/99/99') -
HEADING('DATE' 'OF' 'HIRE')
How Data Conversion Works
In order for the data to be converted, a pre-defined CA Easytrieve Report Generator macro must be present; this macro
specifies and defines the fields in the file so that a "smart" conversion can occur on those fields.
1. The CONVDATA file is run using the parameters specified in the Program Manager dialog.
FILE CONVDATA { F(lrecl) | V(lrecl) | FB(lrecl), blksiz) | VB(Lrecl, blksiz) } %MACNAME PROGRAM
2. A CA Easytrieve Report Generator program EZTCONV is generated in the TEMP (or TMP) directory that includes the
macro. The record format, record length and blocksize (if specified) are taken from the data entered on the Convert
File dialog.
3. The Data Conversion Utility obtains the field definitions for the data file. All Alpha fields will be converted based on the
conversion method specified by the user.
A temporary file is created during the conversion process in the directory specified for the output file.
4. Once the conversion process completes successfully, the temporary file is renamed to the name specified for the
output file.
This means that the input and output file names can be the same.
NOTE
• If an error occurs during the compilation of the temporary program, a message box indicating the error will
be displayed.
• The file conversion information specified by the user is saved in a .prf file (profile). The .prf file has the
same base name as the convert macro name in the same directory as the macro file. The next time the
conversion is performed using this macro name, the specified information will be available.
Convert Files Using the Data Conversion Utility
Use the Data Conversion utility to locate the macro that is to be used to convert your data to the proper format and specify
your conversion parameters.
434
CA Easytrieve® Report Generator 11.6
Follow these steps:
1. Select Tools, Convert File.
The File Conversion Macro dialog is displayed.
2. Do one of the following to specify the macro file that you want to use:
– Enter the name of the macro file and proceed to Step 3.
NOTE
The macro file name (excluding directory) is limited to 8 character positions. It must either end in .mac or
no extension and should not have any ‘.’ characters in the name.
– Click Browse to display the Select File Conversion Macro dialog.
a. Make a selection from the Files of Type combo box.
b. Highlight the macro file and click Select.
The Convert File dialog is displayed.
3. In the Convert File dialog, specify the following:
– Input file name
NOTE
The compiler limits the macro name to be no more than 8 characters in length (excluding the file
extension).
– Output file name
– Record format (F, V, FB, VB)
• F-Fixed
• V-Variable
• FB-Fixed Block
• VB-Variable Block
– Record length
– Blocksize (enabled only for FB and VB)
– Conversion method
• EBCDIC to ASCII
• ASCII to EBCDIC
4. Click OK to begin the conversion process.
Package Program Utility
The Package Program Utility lets you gather the required run-time files and all the user-written programs and files that are
required to run a program. These files are automatically copied to a targeted directory for easy distribution to your end
users.
Use the Package Program utility to include files listed on the Package tab of the Program Profile Manager in a directory
with the executable file.
If default environment variables or program specific environment variables have been specified, these should be selected
from the Package tab within the Program Profile; these will be included as a command within the CMD file.
Once this utility completes, the entire directory should be delivered to the user of the CA Easytrieve Report Generator
application. For easy execution, a file ("program_name.CMD") is created that can be added to the user's desktop for a
single-click execution.
Follow these steps:
1. Select the file to be packaged.
The file is displayed in the Edit window.
The Package Program command on the File menu will be enabled if a PCode file (.pco) or an executable file (.exe)
exists for the program being edited.
435
CA Easytrieve® Report Generator 11.6
2. Choose File, Package Program.
The Select Package Directory dialog is displayed.
3. Select a directory for the packaged program and click OK.
A message box indicating the result of the process is displayed. If the packaging operation fails, the cause of the
failure will be displayed in the message box.
Source Filter Strings Utility
Some files from the mainframe include embedded JCL that must be filtered out before the program can be compiled on
the PC. The Filter Strings Utility allows this to occur without major changes to the original file.
Filters allow you to specify one or more strings that are to be used to filter out statements that are not part of the CA
Easytrieve Report Generator language. Any statement that starts with any one of the filter strings will be commented out
before it is sent to the CA Easytrieve Report Generator compiler.
The Source Filter String utility lets you create a set of default filter strings. Once these strings are defined, you do not have
to define filters for each program you want to edit, you can simply use the defaults.
NOTE
The default filter strings will be saved in the registry so they will be available every time the workbench is started
up.
Set Default Filters Using the Source Filter Strings Utility
The values that you set here will be used if you checked Use Default Filter Strings on the Filter tab of the Program Profile
Manager.
Follow these steps:
1. Select Options, Source Filter Strings.
A dialog, identical to the Filter tab on the Program Manager dialog is displayed where you can enter, edit, or delete a
filter string.
2. Update the default filter strings.
3. Click OK.
The default filters are saved.
Environment Manager Utility
Use the Environment Manager to control the environment variables that will be used during program compilation and
execution from within the CA Easytrieve Report Generator Workbench.
The environment variables dictated by the Environment Manager get created as local environment variables to the
Workbench; they are stored in the registry under the CA Easytrieve Report Generator key and are available to programs
being compiled and executed within the workbench environment. The environment variables may also be packaged
and distributed with your application. When used to specify a location to a file, these work similar to JCL DD statements
and can be effectively used to produce applications that are portable from one system (or server) to the next. By simply
changing the environment variable, you can point to a different input or output file without having to change your CA
Easytrieve Report Generator program.
NOTE
The system environment is NOT changed. (This is a departure from the previous version which required the
EZTDLLS and EZTOPTS values be set for the environment.)
Manage Environment Variables Using the Environment Manager
This section explains how to add, edit, or delete environment variables.
436
CA Easytrieve® Report Generator 11.6
Follow these steps:
1. Select Tools, Environment Manager.
2. To add a variable, do the following:
a. Click New to add an environment variable.
The New Environment Variable dialog is displayed.
b. Enter the variable name and value and click OK.
The variable and value are accepted and are added to the other variables in the Environment Manager dialog box.
3. To edit or delete an environment variable, do the following:
a. Click the variable.
b. Click the Edit or Delete button and click OK.
Any changes made are accepted.
Program Submission Utility
The Program Submission utility lets you execute a program on a remote MVS or UNIX server. This section includes
information about:
• How remote job submission works for UNIX systems
• Submitting a program for execution
• How to use the Job List dialog
How Remote Job Submission Works for UNIX Systems
For UNIX systems, a command shell script is built and uploaded to the host system using FTP, if specified on the Submit
Tab of the Program Profile Manager, along with the program to be executed.
The shell script is executed using one of these methods:
• RSH (Remote SHell)
Verify that:
-- The remote shell daemon (RSHD) is running.
-- A ".rhosts" file exists in the home directory of the user requiring remote shell access.
A typical ".rhosts" file is as follows:
machine.xxx.com username
In this case, the local machine name where the CA Easytrieve Report Generator Workbench is running is
"machine.xxx.com" and the login name is "username". Your UNIX system administrator may need to set this up for
you.
NOTE
Due to security reasons, your system administrator may require you to use an SSH client as opposed to
RSH. CA Easytrieve Report Generator has been designed to support the plink (PuTTY link) SSH client.
• Plink (PuTTY link).
The "plink ssh client" option was checked on the Host Profile Manager.
The plink client uses SSH protocol (Secured SHell) to communicate with the host system and therefore provides
enhanced security.
PuTTY is an SSH enabled telnet program that allows you to access SSH-enabled UNIX systems. It is free and
downloadable from the Internet. It also contains a batch command processor program called plink that allows the
remote execution of UNIX commands using the SSH protocol.
Submit a Program for Execution
When you submit a job for execution, the values specified on the Submit tab of the Program Profile manager are used by
this utility.
437
CA Easytrieve® Report Generator 11.6
Follow these steps:
1. Locate and select a file for editing.
2. Select File, Submit (or press F2).
– One of the following actions will occur:
• If no program profile is defined, the Host Profile Manager dialog is displayed where you can choose or define a
host and submit the program.
• The active program is submitted to the remote system using the defined program profile.
– The Jobs button is enabled and a message area indicating the status of the job is displayed.
– The type of output specified on the Submit tab in the Program Profile Manager is automatically downloaded into an
edit window for inspection.
3. (Optional) Click Jobs to display the results for compiled or completed jobs.
Use the Job List Dialog
Once the active program is submitted to the remote system, the Jobs button is enabled and a message area indicating
the status of the job is displayed on the taskbar. You may also have other jobs active at the same time. (For z/OS
systems, the JES queue will be polled every 500 milliseconds (1/2 second) to check the status of the jobs that have been
submitted.
The Job List dialog provides more information about your jobs and is available from submission to job completion. If Hold
For Select was specified within the Program Profile Manager's Submit tab, this dialog will reflect that program status for
the duration of the Workbench session.
Use the Job List Dialog When Your Job is Compiling
Follow these steps:
1. Click Jobs (bottom taskbar, center) to display a list of the submitted jobs and their status.
2. Optionally, click Abort to terminate an active job.
Once terminated, any spool files created are deleted from the JES queue.
Use the Job List Dialog When Your Job has Completed
If the output type is:
• All
All JES spool files are concatenated together and downloaded to the edit window.
• Hold for Select
The job status display indicates that the job has completed and that it has been held. The job return code is also
displayed.
Follow these steps:
1. Click Jobs.
The jobs that are currently active or have completed and are being held are displayed.
2. Click a job and click Select.
The individual JES spool files that have been created for the job are displayed.
3. Do one of the following:
– Double-click a selection
– Click Get
The file contents are displayed in an edit window.
4. Optionally, click Delete to cancel the job if it is active.
All job output associated with this job is deleted from the JES queue.
438
CA Easytrieve® Report Generator 11.6
To collapse the spool file display, click the up arrow or click Close to close the Job List window.
Creating Toolkit and Writing Scripts
This section describes how to customize or extend the capabilities of the Tools menu to suit your development needs.
Included are instructions on how to:
• Define a Tools menu
• Create customized commands for the Tools menu
• Define script files for use with the R2SCRIPT processor program. These scripts are used to define and manage jobs
that run in the background.
The files that collectively extend the capabilities of CA Easytrieve® Report Generator are termed a toolkit. A toolkit can
contain any of the following kinds of files:
• Menu definition (.MNU) file that defines the menu entries of the Tools menu
• Script (.SCR) files that are interpreted by the R2Script processor program, which runs as a background application
• Custom Dynamic Load Libraries (.DLLs) that are invoked to perform operating-specific tasks
• Standard batch (.BAT) files for performing sequences of DOS commands.
You can use the procedures in this section to create a customized Tools menu that invokes a script, a DLL, or a batch file.
How to create and define script files that are interpreted by the R2SCRIPT processor is also covered in this section.
Defining a Tools Menu
This section describes the Tools menu definition language and how to use it to extend the standard Tools menu to include
your own menu commands and dialogs. You can use your extensions to the Tools menu to launch your favorite DOS or
Windows applications directly from CA Easytrieve® Report Generator.
Contents
The Tools menu file defines the content and operation of the Tools menu. The DEFAULT.MNU menu file is predefined
to perform core functions. In addition, you can customize it (or point to your own variation of it). Menu files can be
customized to:
• Invoke other Windows applications.
• Invoke DOS programs (.EXE) or even batch (.BAT) files that run as background tasks in a special command shell
window.
• Invoke a script that controls a batch task.
• Display a generic dialog to collect information before invoking a script.
NOTE
You are encouraged not to modify the predefined DEFAULT.MNU file directly, since it serves as a convenient
backup. Instead, create your own copy of the DEFAULT.MNU file and make changes to the new copy. After
modifying your .MNU file, use the Options Tools Menu File command to point to your new menu file.
Create Menu Files
A menu file is an ASCII text file that contains one instruction per line. It has the following characteristics:
• Comment records start with an asterisk (*) in column 1.
• A line cannot exceed 256 total characters.
• Blank lines are acceptable.
Each non-comment, non-blank line in a menu file is an instruction line. The sequence of instructions is important, because
many of these instructions are related to prior instruction lines. For example, a MenuItem is always followed by one
439
CA Easytrieve® Report Generator 11.6
or more lines of instruction that define the processing that is to occur when the menu (or submenu) item is selected.
Likewise, a SubMenu instruction indicates that one or more SubMenuItem instructions will follow. This forms a cascading
menu underneath the SubMenu entry.
The DEFAULT.MNU file invokes CA Easytrieve® Report Generator, as well as tools to run a program and establish a set
of environmental variables.
You can include your own tools on the Tools menu.
Follow these steps:
1. Create a copy of the default tools menu (DEFAULT.MNU) and give it an appropriate name, such as MYMENU.MNU.
2. Edit the new menu file. Add new menu and submenu entries along with instructions for what is to happen when the
menu or submenu entry is selected by the user.
3. Point CA Easytrieve® Report Generator to your new menu file. Select the Options Tools Menu File command and
specify your tools menu in the dialog box.
NOTE
To associate your customized menu with a specific application, have the application open when you select
the Options Tools Menu File command.
Menu Processing Overview
Each menu entry on the Tools menu is defined by a MenuItem or SubMenu instruction.
In the previous menu, the Run DOS Program entry is defined by a MenuItem instruction while the first menu is defined by
SubMenu instructions. The arrow to the far right of SubMenu entries is automatically shown for all SubMenu entries.
Selecting an entry defined by a MenuItem instruction invokes a dialog or launches another program, while selecting
a menu entry defined by a SubMenu instruction causes a submenu to be displayed. In the following example, the File
Utilities submenu entry is selected.
The MenuItem and SubMenuItem instructions are used to define programs (Win or DOS) or generic dialogs that are to be
launched when selected.
The MenuSeparator and SubMenuSeparator instructions draw horizontal lines in the main menu and submenus. These
are useful for visually grouping related menu entries. In the Tools menu example, four MenuSeparators are defined.
The Description instruction lets you provide a short description of the menu entry's function. It must follow the MenuItem,
SubMenu, or SubMenuItem instruction to which it refers. It defines the text that is displayed in the status bar whenever
you select the menu entry.
The MenuItem and SubMenuItem instructions must be followed by an instruction that specifies what to do when the menu
(or submenu) entry is selected:
• Launch -- Causes a program or batch file to be executed.
• Invoke -- Calls a function within a .DLL (Dynamic Link Library).
• DialogBox -- Brings up a generic dialog box in which the user can enter one or more variables before invoking a
function.
Menu Instructions Overview
Each non-blank, non-comment line in the menu file is an instruction that is processed to dynamically create the Tools
menu. These instructions define the menu text and processing that takes place when you select the menu item.
Each instruction line starts with a keyword. Some instructions have one or more parameters: some required and some
optional.
The basic format of an instruction is:
440
CA Easytrieve® Report Generator 11.6
keyword parm1 parm2…
The case of the keywords and parameters is insignificant, but each must be separated from the next by at least one
space.
MenuItem and SubMenuItem instructions define menu text, accelerator keys, and scripts.
• A MenuItem instruction defines an entry in the main Tools pull-down menu.
• A SubMenuItem defines a menu entry that extends, or cascades, from a menu entry.
The format of the MenuItem and SubMenuItem instructions are identical; therefore, the remainder of this discussion
focuses on MenuItem instruction, but it is also applies to the SubMenuItem.
A MenuItem line has the following format:
MenuItem "Menutext" keyname scriptfile
The text that is to appear in the Menu follows the MenuItem instruction and is enclosed within double-quotation marks (").
An ampersand (&) is used to indicate which of the characters in the menu text is the accelerator that will cause the menu
entry to be selected.
• Keyname
This optional parameter specifies the keyboard combination of Alt+Shift+function keys that invoke the command
directly. The format is Alt+Shift+Fn, where n is an integer from 1 to 12, allowing 12 valid key names.
• Scriptfile
This optional parameter specifies the script that is to be invoked in response to the MenuItem being selected.
MenuItem "&Run Program…" CARUNDOS.SCR
The previous example results in the following Tools menu entry:
Run Program
Selecting this entry invokes the CARUNDOS.SCR script.
• Description
A single line can be used to specify the text that is displayed in the status bar whenever the user selects the menu or
submenu entry that precedes the Description line.
MenuItem "My &Tools"
Description "Examples of User-defined Menu Entries"
No accelerator key was defined for this menu item.
• DialogBox
Used to start the definition of a generic dialog box. It always follows the MenuItem or SubmenuItem to which it refers.
A DialogBox line has the following format:
DialogBox "Titlebar text"
• Title-bar text
The title-bar text is placed in the title-bar area of the generic dialog. A generic dialog is a user-defined dialog that
contains the following:
441
CA Easytrieve® Report Generator 11.6
– OK -- Standard OK button that closes the dialog box and immediately invokes the script specified on the previous
MenuItem or SubMenuItem line.
– Cancel -- Standard Cancel button that closes the dialog and keeps the menu entry's script from processing.
– Prompts -- Edit controls and explanatory text that is used to gather information from the user. These are defined
with the Prompt instruction.
– File Prompts -- Edit controls for file names and buttons that are used to collect file-names from the user. These are
defined using the PromptFile instruction.
• Prompt
Each DialogBox instruction is followed by one or more Prompt and PromptFile instructions that define the generic
dialog controls and therefore always follow the DialogBox instruction. The Prompt instruction collects variable data
from the user so that it can be passed to the Workbench's script processor.
The format is as follows:
Prompt "title" variable Profile
– title -- This required parameter is enclosed with double quotes. It specifies the text that appears to the left of an edit
control in the generic dialog.
– variable -- This required parameter specifies the 1-30 character name of a variable to which the user's input text
string will be assigned.
– Profile -- An optional profile keyword that, if supplied, causes the variable and its current value to be stored in the
Workbench profile when the OK button is clicked. Using the profile parameter is a convenient way to allow the
specified value to remain from session to session.
Variables are named with 1-30 uppercase and lowercase alphabetic and numeric characters. You can also use the
hyphen (-) and underscore (_) characters to make the variable name more readable. Case is unimportant; for example,
ALPHA, alpha, and Alpha all refer to the same variable.
Variables pass information between a generic dialog and a script. Each variable in a generic dialog is available as an
identifier in the script language when the script starts to execute. This is a one-way exchange so that the changes
made to the values of variables during script processing are not retained.
DialogBox "Run Program"
PromptFile "&Command Line…" RUN_FN* Profile
Prompt "&Working Directory:" RUN_DIR Profile
• PromptFile
Collects the name of a file from the user. The format is as follows:
PromptFile "text" variable Profile
The title parameter is required and enclosed in double quotes. It specifies the text that appears to the left of an edit
control in the generic dialog. The variable parameter is also required. It specifies the 1-30 character name of a variable
to which the filename specified by the user will be assigned.
The final parameter is an optional profile keyword that, if supplied, causes the variable and its current value to be
stored in the Workbench profile when the generic dialog's OK button is clicked.
• BrowseFilter
Optional instruction that can be used after a PromptFile instruction to control the file name filters that are shown in the
generic Browse dialog. It is used to specify the file name filters that are shown in the File Type list box that is shown in
the drop down list that lists the type of files in the lower left corner of the Browse dialog.
The format is:
BrowseFilter "title1^filter1^text2^filter2"
The double quotes surround one or more pairs of title and filter specifications each of which is separated by a caret
(^) character. The title portion shows up in the File Type drop-down list of file types while the filter shows up in the File
Name edit control when the file type is selected.
442
CA Easytrieve® Report Generator 11.6
When you click on the Mapset File Name button, the Select BMS Map Name dialog box appears.
• MenuSeparator and SubMenuSeparator
These instructions place a horizontal bar in the menu or submenu in which they are defined.
• Invoke
Specifies the name of the DLL and the entry point for the function that is to be invoked. It must follow the MenuItem or
SubMenuItem or to which it refers.
• Launch
Specifies the name of the EXE or BAT file that contains the program that you want to execute. It must follow the
MenuItem or SubMenuItem to which it refers.
• BrowseTitle
An optional instruction that specifies the text that is displayed in the Browse File dialog. If specified, it must follow the
PromptFile instruction to which it refers. In the example in the previous section, the BrowseTitle instruction is used to
place "Select BMS Map Name" into the file browse dialog.
• PromptDirectory
Collects the path to a directory from the user. The format is as follows:
PromptDirectory "text" ConfDir Profile
The title parameter is required and enclosed in double quotes. It specifies the text that appears to the left of an edit
control in the generic dialog. The variable parameter is also required. It specifies the 1-30 character name of a variable
to which the pathname specified by the user will be assigned.
The final parameter is an optional Profile keyword that, if specified, causes the variable and its current value to be
stored in the Workbench profile when the generic dialog's OK button is clicked.
For example:
PromtDirectory "Temp Dir…" ConfDir Profile
BrowseTitle "Select Temp Directory"
When you click on the Temp Dir button, the Browse for Folder dialog box appears.
Document Variables
The Workbench conforms to the object/action paradigm whereby a user selects an object and then selects an action to
apply to it. Tools can conform to this paradigm by applying actions to the document (i.e., file) that is currently in focus.
To facilitate this capability the Workbench stores information about the currently focused document file in a series of
CA_DOC_FN (CA DOCument File-Name) variables:
• CA_DOC_FN_Full
The complete file description. For example:
EZTPGMS\Samples\Report1.EZT
• CA_DOC_FN
The file-name. For example, REPORT1.
• CA_DOC_FN_Drive
The file's drive. For example, C.
• CA_DOC_FN_Path
The complete path of the file. For example, EZTPGMS\SAMPLES.
• CA_DOC_FN_Ext
The file extension. For example, EZT.
These variables, along with any other variables defined in generic dialogs, are passed to the R2SCRIPT script processor.
If there is no file in focus when the menu command is selected, then each of the above variables is set to a value of
spaces.
443
CA Easytrieve® Report Generator 11.6
Using the R2SCRIPT Processor
R2SCRIPT is a script language interpreter used by the Workbench, and available for you to use when creating your own
Tools. R2SCRIPT has a particular advantage for Workbench users -- it allows your script to shell out to a DOS session,
execute commands, and have the results of the commands returned to your script, and thus to whatever invoked the
script. Other products allow shelling out, but R2SCRIPT can also evaluate responses.
For example, the Workbench runs an R2SCRIPT program whenever you compile a program. This script program invokes
the compiler in its own operating session. If the compiler detects errors, it passes a non-zero status code back to the script
processor (R2SCRIPT), which in turn passes the status code back to the Workbench. The Workbench reacts to a non-
zero status from a compile script by displaying the compile errors in the window that contains the source in error, and
launching the Find Errors dialog box.
This article includes the following information:
Create a Script File
A script file is a standard ASCII text file with the default extension of SCR. The file is simply a list of statements, following
the lexical and syntactic rules described later in this article.
Your script files can define procedures that run under Windows, interact with the user and then spawn and interact with
Windows or DOS programs and batch (BAT) files running in a separate command shell window.
Start R2SCRIPT
To start the script interpreter, use either of the following techniques.
Custom Tools Menu File
From your custom Tools Menu file, specify the name of the script at the end of a MenuItem or SubMenuItem statement.
Example 1:
MenuItem "&Run Program…" CARUNDOS.SCR
Example 2:
SubMenuItem "&Run Program…" CARUNDOS.SCR
NOTE
Communication between the Tools Menu and the script processor is established by passing the Tools Menu
variables to the script processor. The invoked script can access any of the variables defined in the tools menu,
not just the variables for the current menu item. If a variable is used in more than one menu, the variable for the
menu that invoked the script takes precedence.
Run Command
From a command prompt, enter the following command string:
R2SCRIPT [script-file-name] [argument…].
The interpreter terminates after script-file-name is executed when script-file-name is provided. If script-file-name is
omitted, the interpreter remains started in server mode. If script-file-name is provided but arguments are omitted, the
interpreter prompts for arguments.
444
CA Easytrieve® Report Generator 11.6
Lexical and Semantic Considerations
This section describes lexical and semantic considerations:
• Comments
Delimited by a single quote ('). When a single quote is encountered, all text from the quote to the end of the line is
ignored.
• Blank lines
Blank lines are ignored.
• Literal strings
Delimited by matching double quotes. If the string is to contain the string delimiter, it may be doubled inside the
string (that is, "….""…."). A "\n" sequence within the string is translated to an ASCII linefeed character and hence is
significant to displayed text.
• Number
Internally represented as long integers. They may not contain a decimal place. Numeric conversions from strings are
attempted when required; for example, the literal -255 is equivalent to the string "-255" for arithmetic expressions.
• Case of identifiers
Reserved words, and so on. This is not significant.
• String comparisons
Not case sensitive. If an integer is compared to a string, the integer is converted to a string for the comparison. Two
integers are compared as integers.
• Identifiers
Can consist of the characters A-Z, a-z, 0-9, @, %, $, !, ?, and _. An identifier's first character must be non-numeric.
Identifiers are translated internally to uppercase.
Identifiers need not be defined before use. An identifier that is referenced before it is assigned to has the string value
of the identifier name.
Identifier values are not explicitly typed. Conversions to integer and/or string are performed as required. Inability to
perform a conversion results in a runtime error.
The following identifiers are reserved to the language.
– Identifiers with underscores are constants or variables.
– Identifiers without underscores are commands or functions.
AND UCASE _RC
CLEAR ABORT _RETRY
COMMAND _CANCEL _SW_HIDE
ELSE _CHANGEDRIVE _SW_MAXIMIZE
END _DOS _SW_MINIMIZE
EXIT _IGNORE _SW_NORMAL
IF _MB_ABORTRETRYIGNORE _SW_RESTORE
LCASE _MB_EXCLAMATION _SW_SHOW
MESSAGEBOX _MB_INFORMATION _SW_SHOWMAXIMIZED
NOT _MB_OK _SW_SHOWMINIMIZED
OR _MB_OKCANCEL _SW_SHOWMINNOACTIVE
PROGRAM _MB_QUESTION _SW_SHOWNA
PROMPT _MB_RETRYCANCEL _SW_SHOWNOACTIVATE
RETURN _MB_STOP _SW_SHOWNORMAL
SETDIR _MB_YESNO _SW_YES
SHELL _MB_YESNOCANCEL
SHOWWINDOW _NO
THEN _OK
• Environment Variables
445
CA Easytrieve® Report Generator 11.6
A script can refer to existing environment variables (such as those in CONFIG.SYS) or change them. If a script
changes a variable, then shells out to a DOS session, the command session uses the changed variable.
When a script begins execution, the contents of the current environment are defined with their current values and can
be referred to wherever an identifier is valid.
The identifier has the value of the environment variable. Hence, all environment variables are directly accessible to the
script as identifier references. If the script changes the content of an environment variable, the new value becomes the
environment variable for subsequent command executions (actually, the entire interpreter symbol table becomes the
environment for subsequent command execution). Use the CLEAR command to remove an identifier from the symbol
table and thus prohibit the symbol from being defined in the environment when a command is being executed.
• Characters
The following characters or character sequences are lexically significant:
Character Meaning
= Equal to or assignment
<> Not equal to
> Greater than
>= Greater than or equal to
< Less than
<= Less than or equal to
+ Arithmetic binary addition or string concatenation
- Arithmetic binary or unary subtraction
* Arithmetic multiplication
/ Arithmetic integer division
( Open parenthesis
) Close parenthesis
; Semicolon
, Argument separator functions and procedure parameter lists
Relational Expressions
The language supports six relational operators:
Operator Meaning
= Equal to
<> Not equal to
> Greater than
>= Greater than or equal to
< Less than
<= Less than or equal to
All relational expressions are binary (that is, they take two operands). You can connect relational expressions using the
logical operators And, Or, and Not. Relational expressions can only be used in an IF statement. String comparisons
are not case sensitive. If an integer is compared to a string, the integer is converted to a string for the comparison. Two
integers are compared as integers. An example of a relational expression used in an IF statement is "If _rc > 4 Then Exit
Program".
446
CA Easytrieve® Report Generator 11.6
Logical Expressions
The language supports three logical operators: And, Or, and Not. Logical operators can only be used as part of a
relational expression in an IF statement. An example of a statement using the logical connective "And" is "If a = b And b =
c Then a = c".
All relational expressions connected by the logical operators are evaluated before determining the truth of the logical
expression as a whole.
Arithmetic Expressions
The language supports five arithmetic operators:
Operator Operator Type Meaning
- Unary Minus
+ Binary Plus
- Binary Minus
* Binary Times
/ Binary Divide
Operators must be enclosed by spaces. Precedence can be modified by enclosing sub expressions in parentheses.
All arithmetic operators are integer operations (integers are represented as signed 32-bit binary numbers). If an operand
of an arithmetic operator is a string, an attempt is made to convert the string to an integer before performing the operation;
if the conversion fails, a runtime error is generated. An arithmetic expression can be used as an argument to any
statement or built-in function in the language.
String Expressions
The language supports one string operator, concatenation (+). Since plus (+) is also used to represent arithmetic addition,
concatenation occurs only if the interpreter is unable to convert both operands of the plus operator to integer (that is,
integer addition has precedence over string concatenation).
A string expression can be used as an argument to any statement or built-in function in the language.
Built-in Functions
A built-in function can be used anywhere an arithmetic or string expression can be used. The following built-in functions
are defined.
Command$ Function
The Command$ function returns a string containing the arguments provided on the command line to the script interpreter.
Leading and trailing white space is removed.
This function has the following format:
Command$
Example
commandline = Command$
447
CA Easytrieve® Report Generator 11.6
LCase$ Function
The LCase$ expression returns a string containing the lowercase equivalent of <expression>.
This function has the following format:
LCase$(expression)
Example
lowercasestuff = LCase$("UPPERCASE STUFF")
MessageBox Function
This function displays a message box with the specified message and captions.
This function has the following format:
MessageBox(message expression, caption expression,
type flag [, icon flag [, default button]] )
• message expression
The text displayed in the message box.
• caption expression
The title of the message box window.
• type flag
Defines the type and number of buttons in the message box window. Type flag can be one of the following reserved
constants:
type flag Meaning
_MB_Ok Display an OK button
_MB_OkCancel Display OK and CANCEL buttons
_MB_YesNo Display YES and NO buttons
_MB_YesNoCancel Display YES, NO, and CANCEL buttons
_MB_RetryCancel Display RETRY and CANCEL buttons
_MB_AbortRetryIgnore Display ABORT, RETRY, and IGNORE buttons
• icon flag
Specifies an icon to be displayed in the message box. Icon flag can be one of the following reserved constants (the
default action is to not display an icon in the message box):
icon flag Meaning
_MB_Stop Display a Stop icon
_MB_Exclamation Display an exclamation icon
_MB_Question Display a Question icon
_MB_Information Display an Information icon
• default button
448
CA Easytrieve® Report Generator 11.6
Defines which of the buttons in message box is to be the default button (that is, which button is assumed when the
Enter key is pressed). Default button can be either 1, 2, or 3; 1 is the default. If there are fewer buttons displayed than
indicated by this constant, 1 is assumed without error.
The MessageBox function returns one of the following reserved values depending on which button is pressed by the user:
Value Cause
_Ok The OK button was pressed
_Cancel The Cancel button was pressed
_Yes The Yes button was pressed
_No The No button was pressed
_Abort The Abort button was pressed
_Retry The Retry button was pressed
_Ignore The Ignore button was pressed
Example
dummy = MessageBox("An error occurred in DOS
Command.", "Sample Script",
_MB_OK, _MB_EXCLAMATION, 1)
UCase$ Function
UCase$ returns a string containing the uppercase equivalent of expression.
This function has the following format:
UCase$(expression)
Example
uppercasestuff = UCase$("lowercase stuff")
Language Statements
The language supports the following statements (that is, commands).
IDENTIFIER Statement
The computed value of expression is assigned to the variable IDENTIFIER. IDENTIFIER is created if it does not already
exist; if it does exist, the current value of IDENTIFIER is replaced with the new value.
This statement has the following format:
identifier = expression
Example
directory = "c:\r2script"
i = (j + 1) * 10
449
CA Easytrieve® Report Generator 11.6
CLEAR IDENTIFIER Statement
Sets the identifiers indicated to an undefined state (just as if they had never been created). This frees storage occupied by
the identifiers.
This statement has the following format:
CLEAR identifier [, identifier ...]
Example
CLEAR name, age, address
EXIT Statement
Stops interpretation of the script and does not return a result to the user or program requesting interpretation of the script.
The PROGRAM keyword is optional and is assumed if it is not present.
This statement has the following format:
EXIT [PROGRAM]
Example
EXIT PROGRAM
IF Statement
Allows one or more statements to be conditionally executed. Relational expression is evaluated and if it evaluates to
TRUE then statement list 1 is executed. If relational expression is FALSE and the ELSE clause is present, statement list 2
is executed.
This statement has the following format:
IF relational expression THEN statement list 1
[ELSE statement list 2] END
Example
IF _rc > 4 THEN
dummy = MessageBox("An error occurred in DOS
Command.", "Sample Script", _MB_OK)
return _rc
ELSE
dummy = MessageBox("DOS Command executed OK.",
"Sample Script", _MB_OK)
END
RETURN Statement
Stops interpretation of the script and returns expression as the result of the script interpretation to the user or program
requesting interpretation of the script.
This statement has the following format:
450
CA Easytrieve® Report Generator 11.6
RETURN expression
Example
RETURN _rc
SHELL Statement
Allows a DOS command to be executed in a DOS box. The response from executing the command is placed in the
reserved, read-only, constant _RC. The _DOS keyword is optional and is assumed if it is not present.
This statement has the following format:
SHELL expression [, _DOS]
Example
SHELL "lcmlog.exe " + lcmuserid + " " + lcmuserpswd, _DOS
IF (_rc <> 0) THEN
ShowWindow(_SW_NORMAL)
dummy = MessageBox("An error has occurred while logging on
with userid - " +
lcmuserid, "Sample Script", _MB_OK)
return 4
end
SETDIR Statement
Allows the script to set the current directory when a command is executed via the SHELL command. The current directory
for the script interpreter is not affected.
This statement has the following format:
SETDIR(expression)
Example
SETDIR("C:\R2SCRIPT")
SHOWWINDOW Statement
Controls the display state of the batch window in which OS commands are executed via the SHELL command.
This statement has the following format:
SHOWWINDOW(flags)
Flags can be one of the following reserved constants:
Constant Effect
_SW_HIDE Hides the window and passes activation to another window.
451
CA Easytrieve® Report Generator 11.6
_SW_MAXIMIZE Activates the window and displays it as a maximized window.
_SW_MINIMIZE Minimizes the window to an icon and passes activation to another
window.
_SW_NORMAL Activates and displays the window. If the window is minimized or
maximized, it is restored to its original size and position.
_SW_RESTORE Same as _SW_NORMAL.
_SW_SHOW Activates the window and displays it in its current size and
position.
_SW_SHOWMAXIMIZED Same as _SW_MAXIMIZE.
_SW_SHOWMINIMIZED Activates the window and displays it as an icon.
_SW_SHOWMINNOACTIVE Displays the window as an icon. The window that is currently
active remains active.
_SW_SHOWNA Displays the window in its current state. The window that is
currently active remains active.
_SW_SHOWNOACTIVATE Displays the window in its most recent size and position. The
window that is currently active remains active.
_SW_SHOWNORMAL Same as _SW_NORMAL.
Sample Scripts
NOTE
Saving Open Files - If you need to make sure any files opened by the Workbench have any outstanding
changes saved prior to running some process, you can specify: EEExternal "cawbdisp.dll" Proc
WB_SaveAllFiles as Integer RC_EXT = WB_SaveAllFiles().
Sample #1
This script sample demonstrates just how simple a script can be.
1 shell "dir *.*" 'dummy =
2 MessageBox("ReturnCode="+_rc, "return code",'
_MB_OK, _MB_EXCLAMATION, 1)
3 shell "set" 'dummy =
4 MessageBox("ReturnCode="+_rc, "return code",'
_MB_OK, _MB_EXCLAMATION, 1)
Line Function
1 The Shell command issues a DOS Dir command to the OS
window.
2 Message Box command displays the return code from the OS dir
command.
3 The Shell command issues a Set command to the OS to dump the
contents of the environment area to screen.
4 Message Box command displays the return code from the OS Dir
command.
NOTE
All variables within the current script are made available to the OS window as environment variables. Thus, it is
possible to pass environment variables from your script to OS command procedures. However, the environment
variables that are modified within the DOS shell are not passed back to the script processor.
452
CA Easytrieve® Report Generator 11.6
Sample #2
For a sample script that demonstrates how to communicate between the Tools Menu and the CARUNDOS.SCR script file,
refer to the CARUNDOS.SCR file in the directory where you install CA Easytrieve® Report Generator. This is the actual
script invoked from the Run Program Tools menu item.
Workbench Help
The Workbench online help includes information about the user interface and tasks that you can perform, such as
configuring the options table and printer set definitions, and building and compiling programs.
The Workbench Help menu has the following items:
• Contents
Opens the Workbench online help.
• On Line PDF Documentation
Opens the documentation bookshelf. Links to the PDF guides that are installed with the product are provided.
• About CA Easytrieve Workbench
Displays the product version, build, and licensing information.
CA Easytrieve/Earl Usage
The CA Easytrieve® Report Generator/Earl file exit program is an assembly program that performs two functions.
• Translate the CA Easytrieve® Report Generator exit parameter list to the CA Earl parameter list.
• Invokes a specific CA Earl program.
Contents
Syntax
FILE filename WORKAREA (lrecl) +
EXIT ('EARLEXIT' USING (COMAREA, exitname, filename, +
PARM-REGISTER))
• filename
The DD name of the data file that the Exit reads.
• lrecl
The record length of the file.
• EARLEXIT
The name of the CA Easytrieve® Report Generator/EARL file exit.
• COMAREA
An 80-byte working storage field used as a communication area for the specific CA Earl exit being used. COMAREA
must be defined in the CA Easytrieve® Report Generator program as an 80-byte alpha field.
• exitname
The CA Earl exit supplied by a specific CA Technologies product.
• PARM-REGISTER
CA Easytrieve® Report Generator predefined field that contains the value of register 1 on the CA Easytrieve® Report
Generator program.
COMAREA must be passed to the exit as an 80-byte alpha field. It is redefined into two parts. The first four bytes of
COMAREA is an integer that contains the CA Earl return code. Its values are:
453
CA Easytrieve® Report Generator 11.6
• -1 End of File
• -2 Record not found
• 0 User cancel.
Redefine the remaining 76 bytes of COMAREA per the requirements of the specific exit. This area can be used to pass
additional parameters required by the Exit or for user messages.
Please refer to the appropriate product documentation for information on supplied CA Earl exits.
Sample CA Easytrieve® Report Generator/Earl Exit
* FILE DEFINITION
* FILE NAME: AIRPORTS
* EARL EXIT NAME: EARLGET
* RECORD LENGTH: 48
FILE AIRPORTS WORKAREA 48 +
EXIT (EARLEXIT USING (COMAREA, 'EARLGET ', 'AIRPORTS ', +
PARM-REGISTER)) F (48)
NAME 1 18 A
CITY 20 16 A
COUNTRY 37 3 A
PASS 41 8 A
DEFINE COMAREA W 80 A
DEFINE EARLCOM-FLAG COMAREA 4 B
DEFINE EARLCOM-MSG COMAREA +4 76 A
JOB INPUT AIRPORTS
PRINT AIRPORTS
REPORT AIRPORTS
CONTROL
LINE 1 +
NAME +
CITY +
COUNTRY +
PASS
CA Easytrieve SDS
CA Easytrieve Simplified Design System (CA Easytrieve SDS) is a Windows application that you can use to create CA
Easytrieve reports.
Data for the report can reside on a local or remote computer. You design a report using the Easytrieve Report Painter
feature and then submit the job. Report output is displayed in CA Easytrieve SDS.
NOTE
You must have a valid CA Easytrieve license to run reports using CA Easytrieve SDS.
Start CA Easytrieve SDS
To start CA Easytrieve SDS, double-click easytrieve.exe in the folder that contains the CA Easytrieve SDS files.
NOTE
For the first use, click Go directly to SDS in the Welcome screen. After the first use, the application starts
without displaying the Welcome screen.
454
CA Easytrieve® Report Generator 11.6
Create a Report
You can create a report by following this process:
1. Create a JCL/Submit Prolog Source File
2. Create a Project and Host Profile
3. Import File and Field Definitions
4. Design and Run a Report
More Information:
For more information about this application, see the CA Easytrieve Help.
Create a JCL/Submit Prolog Source File
When you create a host profile to access data on a remote computer, you must specify a source file that contains JCL for
submitting CA Easytrieve SDS jobs to that computer. The source file is imported into CA Easytrieve SDS as a JCL/Submit
prolog file (prolog file) when the host profile definition is saved.
You can create a source file by copying and modifying the JCL in the example that follows, and then saving it to a text file.
Alternatively, you can copy the JCL from an existing CA Easytrieve compile-and-go execution.
NOTE
For more information about compile-and-go execution, see Compile-and-Go Execution of a CA Easytrieve
Program.
Example
The JCL in this example accesses datasets that are included with CA Easytrieve. SAMPLE.PERSONEL contains the data
for the report and CBAAJCL contains the PERSNL member that has the master field definitions that are used in the report
definition.
//jobname JOB (account),'user',MSGCLASS=H,NOTIFY=&SYSUID.
//*------------------------------------------------------*
//EZTP EXEC PGM=EZT
//STEPLIB DD DISP=SHR,DSN=hlq.EZT.R116S0A.CBAALOAD
//EZOPTBL DD DISP=SHR,DSN=hlq.EZT.R116S0A.EZOPTBL
//PANDD DD DISP=SHR,DSN=hlq.EZT.R116S0A.CBAAMAC
// DD DISP=SHR,DSN=hlq.EZT.R116S0A.CBAAJCL
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSNAP DD SYSOUT=*
//SYSABOUT DD SYSOUT=*
//SORTWK01 DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SORTWK02 DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SORTWK03 DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//PARMS DD DUMMY
//PERSNL DD DISP=SHR,DSN=hlq.EZTRP11.SP01B.SAMPLE.PERSONEL
Next Step:
Create a Project and Host Profile
455
CA Easytrieve® Report Generator 11.6
Create a Project and Host Profile
A CA Easytrieve SDS project contains a host profile, report definitions, and other business objects for reports. You must
create a project and a host profile before you define and run reports.
Follow these steps:
1. Click File, New, Project.
The New Project panel appears.
2. Enter a project name and click Finish.
The new project appears in the Business Objects tree.
3. Select the new project and click File, New, Host Profile.
The Host Profile Wizard appears.
4. Click Next with Remote host selected.
NOTE
You can also create a local host profile. For more information, see the CA Easytrieve SDS Help.
The next wizard panel appears.
5. Enter the following information:
– Profile name
– Host name or IP address that you want to access
– TSO user name
– Host type (z/OS, UNIX, or VSE)
6. Click Browse for the JCL/Submit prolog file field and select the source file that contains JCL for submitting jobs to a
remote computer.
NOTE
The source file is imported into an internal JCL/Submit prolog file when the host profile is saved. For
information about the source file, see Create a JCL/Submit Prolog Source File.
7. Select one of the following ways to receive output in CA Easytrieve SDS:
– Retrieve all output—All output for the job is retrieved in the Report window.
– Hold output for selection—Holds the job output that is not to be retrieved in the Report window.
– Retrieve SYSPRINT only—On MVS systems, only the SYSPRINT output is retrieved. On UNIX systems, Only the
output that was sent to STDOUT is retrieved.
8. Click Finish.
The profile is created and appears in the Business Objects tree.
9. (Optional) To edit your prolog file, expand Host Profiles in the Business Objects pane, right-click your profile, and
select Edit Prolog.
NOTE
• This procedure shows the minimum properties that are required. For more information about projects and
host profiles, see the CA Easytrieve SDS Help.
• To edit a host profile after you save it, right click the host profile name in the business objects tree and select
Open.
• To edit the JCL/Submit prolog file after you save the host profile, right-click the host profile name in the
business objects tree and select Edit Prolog. Do not edit the source file that you select in Step 6.
• For a video demonstration of this procedure, click here.
Next Step:
Import File and Field Definitions
456
CA Easytrieve® Report Generator 11.6
Import File and Field Definitions
Before you design a report in CA Easytrieve SDS, you must import the file and field definitions. You can import file and
filed definitions from the following sources:
• CA Easytrieve business objects
• Source code from other CA Easytrieve projects
• COBOL programs and copybooks
• CA Easytrieve files and fields
• CA Easytrieve macros
• SQL data
Follow these steps:
1. In the Business Objects pane, right-click your project and select Import.
The Import wizard appears.
2. Expand the Easytrieve folder, select the appropriate source type, and click Next.
The Import type File Definitions dialog appears.
3. For COBOL, select program or copybook as the source type.
4. Perform one of the following actions:
– For sources other than SQL data, click Browse, select the directory path to the source objects, and click Open.
The objects or types appear.
– For a SQL data source, populate the Connection fields and click Connect. Next, enter the Filter information.
The tables that contain objects appear.
5. Select the objects or types that you want to import.
6. Specify the target CA Easytrieve SDS project name in the Into project field.
7. (Optional) Select Overwrite existing resources without warning.
NOTE
If you do not select this option, a warning message notifies you when you try to overwrite a file.
8. (Optional) Select Remove read-only attributes without warning.
NOTE
If you do not select this option, a warning message notifies you when you try to remove the ready-only
attributes of a file.
9. Click Finish.
Your files are imported into the selected project.
NOTE
For more information about importing file and field definitions, see the CA Easytrieve SDS Help.
Next Step:
Design and Run a Report
Design and Run a Report
You can design a report using Easytrieve Report Painter. You can then submit the report to the computer defined in your
host profile.
Follow these steps:
1. Import the file and field definitions from your data source.
457
CA Easytrieve® Report Generator 11.6
2. Perform one of the following actions:
– Click File, New, Report, and follow the wizard prompts.
– Expand Reports and Templates under your project in the tree and double-click the appropriate sample report.
Easytrieve Report Painter appears in the right pane.
3. Expand the Files branches in the Business Objects tree.
The fields that you can add to your report are displayed.
4. Drag the appropriate fields from the tree to the Easytrieve Report Painter.
5. Position the fields in the order that they should appear in the report.
6. (Optional) To sort the output:
a. Right-click in the top blue area of Easytrieve Report Painter and select Report properties.
b. Click the Sort Output tab in Report Properties and drag the field on which the output should be sorted from the tree
to the list box.
c. Click OK
The report is ready to be submitted.
7. Click the Generate Program tool or press F4.
The Save As dialog appears.
8. Select your project in the Business Objects tree, enter a file name for the report, and click OK.
The program source code appears. The program is ready to run; however, you can edit the code as needed.
9. (Optional) To suppress the output of any compile messages, add the following lines at the beginning of the source
code listing:
LIST OFF
PARM LIST (NOPARM)
10. Click the Submit Program tool or press F2.
The Host credentials dialog appears.
11. Enter your TSO password.
The program runs and progress messages are displayed. When the job completes, the report output appears in the
right pane.
NOTE
• For a video demonstration of this procedure, click here.
• For more information about the host profile, see Create a Project and Host Profile.
• For more information about using this application, see the CA Easytrieve SDS Help.
458
CA Easytrieve® Report Generator 11.6
Programming
This section is for CA Easytrieve Report Generator programmers. As a programmer, you should be familiar with the CA
Easytrieve Report Generator language and understand basic data processing concepts.
This section has information about:
• Applying CA Easytrieve Report Generator programs to various application tasks
• Creating efficient CA Easytrieve Report Generator programs
• Analyzing and modifying existing CA Easytrieve Report Generator programs
This section can be used with the following implementations of the product:
• CA Easytrieve Report Generator Report Generator
• CA Easytrieve Report Generator in the UNIX, Linux for zSeries, Windows, and z/OS batch environments
This section and the Language Reference section can help you write CA Easytrieve Report Generator programs. To learn
the basic parts of a CA Easytrieve Report Generator program, see Getting Started.
Text Conventions and Field Rules
This article shows the text conventions that are used in the syntax examples, and the rules for signed and unsigned fields.
Text Conventions
The following notations are used in syntax examples:
Notation Meaning
{braces} Mandatory choice of one of these entries.
[brackets] Optional entry or choice of one of these entries.
| (OR bar) Choice of one of these entries.
(parentheses) Multiple parameters must be enclosed in parentheses.
... Ellipses indicate you can code the immediately preceding
parameters multiple times.
BOLD Bold text in program code is used to highlight an example of the
use of a statement.
CAPS All capital letters indicate a CA Easytrieve Report Generator
keyword, or within text descriptions, indicate a name or field that is
used in a program example.
lowercase italics Lowercase italics represent variable information in statement
syntax.
Signed and Unsigned Field Rules
You can use both signed and unsigned fields in CA Easytrieve Report Generator programs.
Signed Fields
If you specify a numeric field with decimal positions (0 through 18), the product considers it a signed (quantitative) field.
The following rules apply to signed fields:
459
CA Easytrieve® Report Generator 11.6
• For binary numbers, the product takes the high-order (leftmost) bit as the sign, regardless of field length. For a positive
value, the high-order bit is zero and the remaining bits contain the value in true binary notation. For a negative value,
the high-order bit is 1 and the remaining bits contain the value in 2’s complement notation. For a value of zero, all bits
are zero.
For example, a 1-byte binary field containing a hexadecimal FF has the numeric value -1. Binary numbers are stored in
IBM mainframe byte order on all platforms. That is, the most significant byte of the value is stored first. This is referred
to as 'big endian' byte order.
• For non-negative, zoned decimal numbers on the left side of an assignment statement, the product sets an F sign if
EBCDIC, or a 3 sign if ASCII. Otherwise, it manipulates the number in packed decimal format.
• Packed decimal numbers are manipulated in packed decimal format. Arithmetic operations that result in a positive
result set a C sign.
• By definition, there is no sign in unsigned packed decimal numbers (U format). When you manipulate these numbers,
the product supplies an F sign.
• For most purposes, integer numbers are the same as binary numbers. The difference is that integer numbers are
stored in the native byte order of the platform.
For example, for the Intel X86 platform, integer numbers are stored with the least significant byte first. This is referred
to as 'little endian' byte order.
Unsigned Fields
If you specify a numeric field with no decimal positions, the product considers that field unsigned (non-quantitative). The
following rules apply to unsigned fields:
• For 4-byte binary numbers, the magnitude of the number must fit within 31 bits or less. The NUMERIC test is not true
for a 4-byte binary field with the high-order bit on. If the high-order bit is on, the remaining 31 bits are treated as a
negative value in 2’s complement notation.
• For 8-byte binary numbers, the magnitude of the number must fit within 63 bits or less. The NUMERIC test is not true
for an 8-byte binary field with the high-order bit on. If the high-order bit is on, the remaining 63 bits are treated as a
negative value in 2’s complement notation.
• For 1-, 2-, 3-, 5-, 6-, and 7-byte binary numbers, the high-order bit contributes to the magnitude of the number. For
example, a 1-byte binary field containing a hexadecimal FF has a numeric value of 255.
• All binary numbers are stored in IBM mainframe byte order. That is, the most significant byte is stored first, in big
endian byte order.
• Both zoned decimal and packed decimal fields follow the same rules. The product packs all zoned decimal fields and
handles them as packed fields. The product uses the actual storage value in the field, but it is your responsibility to
maintain a positive sign. An EBCDIC F sign or an ASCII 3 sign is placed in any unsigned field that is used on the left-
hand side of an assignment statement.
• An unsigned packed decimal field (U format) is always unsigned. When you manipulate the field, The product supplies
an F sign.
• As is the case with signed (quantitative) integer numbers, unsigned (non-quantitative) integer numbers are processed
in the same way as unsigned binary numbers and are subject to the same limitations. The only exception is that
integer numbers are always stored in native byte order.
• For fixed-point ASCII numbers, the actual ASCII numeric data can reside anywhere within the field and can contain
leading and trailing blanks or zeros.
Code Programs
The organization of this section simulates the way an application program is developed. The basic application
development process steps are:
1. Design the program:
460
CA Easytrieve® Report Generator 11.6
– Determine the task you want the program to accomplish.
– Define the files necessary to read and write the information used by the program.
– Fill in successive levels of the design until you have a program structure that accomplishes the task.
2. Code the program logic as designed:
– Code and test the basic flow of your program before filling in lower levels of the design.
For instructions on compiling, link-editing, and executing your program, see Using.
Structured Programming
The CA Easytrieve® Report Generator language supports structured programming concepts by requiring you to use
defined activities and special-named procedures. These activities and procedures help you create programs that are
efficient, reliable, and maintainable.
CA Easytrieve® Report Generator also lets you practice structured programming concepts when you want to incorporate
large sections of procedural code into your program.
CA Easytrieve® Report Generator lets you easily break a large program into manageable modules by using PROGRAM,
JOB, SCREEN, and SORT activities, and REPORT and SCREEN special-named procedures. You can code each module
to perform a specific function for the program. Each specific function is then easily identified and maintained.
CA Easytrieve® Report Generator lets you create well-structured programs that can be read easily. To accomplish this,
design your program with the following items in mind:
• Keep modules (procedures) small (small enough to fit on one page of the compile listing).
• Use meaningful comments wherever possible so that others can easily read and modify your program.
• Use the CA Easytrieve® Report Generator control flow structures to make programs more readable and efficient. CA
Easytrieve® Report Generator provides two special GOTO statements that are very useful: GOTO JOB and GOTO
SCREEN. These statements provide a well-defined method to instruct CA Easytrieve® Report Generator to iterate the
activity process.
• Use the following structured programming statements to control your program in a clear and logical way:
– IF/ELSE/ELSE-IF
– CASE
– DO WHILE
– DO UNTIL
– EXECUTE
– PERFORM
• Use consistent indentation that shows nesting and control flow. Indent statements that are enclosed in control flow
structures, such as IFs and DOs. When nesting these control flow structures, indent an additional level. For example:
Poor Indentation Good Indentation
================ ================
FILE FILEA FILE FILEA
REGION 1 1 N REGION 1 1 N
EMPNAME 17 20 A EMPNAME 17 20 A
JOB INPUT FILEA JOB INPUT FILEA
IF REGION = 1 IF REGION = 1
PRINT RPT PRINT RPT
END-IF END-IF
REPORT RPT REPORT RPT
LINE REGION EMPNAME LINE REGION EMPNAME
461
CA Easytrieve® Report Generator 11.6
Program Sections
A CA Easytrieve® Report Generator program consists of the following main sections:
Environment Section (Optional)
The environment section lets you customize the operating environment for the duration of a program's compilation and
execution by overriding selected general standards for a CA Easytrieve® Report Generator program.
Some of the standard CA Easytrieve® Report Generator options affect the efficiency of a CA Easytrieve® Report
Generator program. There can be minor trade-offs between the automatic debugging tools provided by CA Easytrieve®
Report Generator and the efficiency of the program code.
For example, you can specify that CA Easytrieve® Report Generator record the statement numbers of the statements
being executed for display during an abnormal termination (FLOW). Use of this option, however, does have a minor
impact on processing time. You can turn this option on or off in the environment section of each CA Easytrieve® Report
Generator program.
Library Section (Optional)
The library section describes the data to be processed by the program. It describes data files and their associated
fields, as well as working storage requirements of a program. The library section is said to be optional because, on rare
occasions, a program may not be doing any input or output of files. However, in most cases, use of the library definition
section is required.
You can shorten processing time by coding data definitions to avoid unnecessary data conversions.
Activity Section (at least one required)
The executable statements that process your data are coded in one or more activity sections. Executable statements in
CA Easytrieve® Report Generator can be procedural statements or declarative statements.
The activity section is the only required section of your program. There are four types of activities: PROGRAM, SCREEN,
JOB, and SORT.
• A PROGRAM activity is a simple top-down sequence of instructions. You can use a PROGRAM activity to conditionally
execute the other types of activities using the EXECUTE statement.
• SCREEN activities define screen-oriented transactions. Data can be displayed to a terminal operator and received
back into the program. Files can be read and updated. A SCREEN activity can EXECUTE a JOB or SORT activity to
perform a special process such as printing a report.
• JOB activities read information from files, examine and manipulate data, write information to files, and initiate reports.
• SORT activities create sequenced or ordered files.
You can code one or more procedures (PROCs) at the end of each activity. Procedures are separate modules of program
code you use to perform specific tasks.
REPORT subactivities are areas in a JOB activity where reports are described. You can code one or more REPORT
subactivities after the PROCs (if any) at the end of each JOB activity. You must code any PROCs used within a REPORT
subactivity (REPORT PROCs) immediately after the REPORT subactivity in which you use them.
462
CA Easytrieve® Report Generator 11.6
The following exhibit shows some CA Easytrieve® Report Generator keywords and other items in the sections where they
are usually located, and gives the general order of CA Easytrieve® Report Generator statements within a program.
PARM ... Environment
Section
FILE ... Library
DEFINE ... Section
...
PROGRAM Activity
(statements) Section
(program procedures)
SCREEN
(screen procedures)
JOB
(statements)
(job procedures)
REPORT
(report procedures)
SORT
(sort procedures)
...
Define Files and Fields
This article explains how to define files and fields in a CA Easytrieve Report Generator program.
Defining Files
Use the FILE statement to describe a file or a database. FILE statements must describe all files and databases that your
program references. FILE statements are the first statements that are coded in the library section of a CA Easytrieve
program.
The FILE statement can differ greatly, depending on the operating environment and the type of file being processed.
NOTE
For more information about files, see FILE Statement and File Processing.
Defining Fields
Use the DEFINE statement to define fields. The DEFINE statement specifies data fields within a record or within working
storage. You usually specify file fields and work fields in the library section, but you can also define them within an activity
as the following examples illustrate.
This example shows fields that are defined in the library section:
FILE PERSNL FB(150 1800)
DEFINE EMP# 9 5 N Library
DEFINE EMPNAME 17 20 A
DEFINE EMP-COUNT W 4 N
JOB INPUT PERSNL NAME MYPROG
EMP-COUNT = EMP-COUNT + 1
PRINT REPORT1 Activity
463
CA Easytrieve® Report Generator 11.6
*
REPORT REPORT1
LINE EMP# EMPNAME EMP-COUNT
This example shows a field that is defined in the activity section:
FILE PERSNL FB(150 1800)
DEFINE EMP# 9 5 N Library
DEFINE EMPNAME 17 20 A
*
JOB INPUT PERSNL NAME MYPROG
DEFINE EMP-COUNT W 4 N
EMP-COUNT = EMP-COUNT + 1
PRINT REPORT1 Activity
*
REPORT REPORT1
LINE EMP# EMPNAME EMP-COUNT
When fields are defined within an activity, each field definition must start with the DEFINE keyword and physically be
defined before the field is referenced. In the library section, using the DEFINE keyword is optional.
If the same field is defined more than once, the first definition is used and subsequent definitions are ignored.
NOTE
For more information about the DEFINE statement format, see DEFINE Statement.
File Fields
File fields are normally defined immediately following the associated FILE statement in the library section of a CA
Easytrieve program. Their rules of usage are:
• CA Easytrieve accepts an unlimited number of fields for each file (constrained by available memory).
• Field names must be unique within a file.
• You can define file fields anywhere in a library or activity section, except within a REPORT sub-activity or a SCREEN
declaration.
• For more specific information about defining fields in a database file, see the appropriate SQL or CA IDMS
documentation.
Working Storage Fields
You can specify two types of working storage fields: S (static) and W (work). Each type is used in a different way,
particularly when used in reporting. It is recommended to ALWAYS use S fields unless you know exactly what W means to
your application and the special processing that is associated with spooled work fields.
Fields that are defined as type S are stored in a static working storage area and are not copied onto report work files. All
references to S fields in a report occur at the time the report is formatted and printed.
Fields that are defined as type W are copied onto the report work files at the time a PRINT statement is executed. A
spooled report is not formatted and printed at the same time the PRINT is executed. Therefore, the value of a W field on a
report is set at the time the report data is selected for printing, not at the time it is printed.
With this in mind, you should use S (static) working storage fields for:
• Temporary work fields for report procedures
• Line annotations that are controlled from report procedures
• Grand total values that are used to calculate percentages
464
CA Easytrieve® Report Generator 11.6
For examples of the use of W and S fields, see Report Processing. Working storage fields are typically defined in the
library section. Their rules of usage are:
• CA Easytrieve accepts an unlimited number of working storage fields (constrained by available memory).
• Working storage fields must be uniquely named within working storage.
• You can define working storage fields anywhere in a library section, activity, or procedure.
Data Reference
Every data reference (file or field) in your program must be unique. You can provide uniqueness in one of the following
ways:
• Unique name -- A name is unique if no other file or work field has that name. For example, GROSS-PAY is unique
if it appears as field-name in only one DEFINE statement (and has never been copied to another file with a COPY
statement).
• Qualification -- Qualification occurs when you prefix the optional qualifier file-name: to a field name. CA Easytrieve
requires the use of the qualifier whenever the field name alone cannot uniquely identify the data reference. The
qualifier for file fields is the associated file name or record name. For working storage fields, the qualifier is the
keyword WORK.
• Default Qualification -- Through default qualification, CA Easytrieve attempts to determine which field you want to
reference when a field name is not a unique name.
If you are in the library section, the current FILE (if one is coded) and the WORK file are searched for an occurrence of the
field in question. If the field is not found in either the current file or the WORK file, or if the field occurs in both the current
file and the WORK file, an error message is issued, stating that additional qualification is required.
If you are in a SORT or JOB activity, and you code an INPUT filename on a JOB statement, the input file is searched
for an occurrence of the field in question. For synchronized file processing, all of the files that are coded on the INPUT
parameter of the JOB statement are checked for an occurrence of the field in question. If the field occurs in exactly one of
the input files, that field is used. If the field occurs in more than one of the default files, an error message is issued, stating
that additional qualification is required.
If the field does not occur in any of the default files, each of the remaining files (including WORK) is searched for an
occurrence of the field in question. If the field occurs in exactly one of the remaining files, that field is used. If the field
occurs in more than one of the remaining files, an error message is issued, stating that additional qualification is required.
If you do not specify an INPUT parameter on the JOB statement, a default input file is used. If the JOB activity
immediately follows a SORT activity, the output from the SORT activity is the default input file. If the JOB activity occurs
at any other point, the default input file is the first FILE coded that is not a TABLE file, a PUNCH file, or a PRINTER file.
Once a default input file is selected, default qualification occurs as described previously.
For PROGRAM, SCREEN, and JOB INPUT NULL activities, no default qualification occurs.
Indexing
Indexing is data reference that results from CA Easytrieve deriving a displacement value to correspond to a particular
occurrence in a field name that is defined with OCCURS. The formula for deriving the index value is: the number of the
desired occurrence minus one, multiplied by the length of the occurring field element. For example, if an occurring field is
defined as:
DEFINE MONTHWORD MONTH-TABLE 9 A OCCURS 12 INDEX MONTH-INDEX
MONTH-INDEX for the third occurrence is derived as follows:
MONTH-INDEX = (3 - 1) * 9 = 18
See Array Processing for more information.
465
CA Easytrieve® Report Generator 11.6
Subscripts
Subscripts are an alternative method available to select an individual element from an array. A subscript is a literal or field
that contains the actual occurrence of the element you are referencing.
Using subscripts removes the requirement of computing the index value; CA Easytrieve does it automatically. See Array
Processing for more information.
Varying Length Fields
The VARYING keyword on the DEFINE statement designates varying length alphanumeric fields. Varying length fields are
often used in SQL databases (VARCHAR). An example of a varying length field definition follows:
FLDA W 250 A VARYING
Because VARYING is used, this W-type work field has two parts, which are internally defined as follows:
W 2 B 0 for the two-byte field length
W 248 A for the data
When you reference this field in your statements, you can use FLDA to specify the field in any one of the following ways:
• To designate the entire field (both length and data portions), specify FLDA. This covers bytes 1 through 250.
• To designate only the length portion of the field (bytes 1 and 2), specify FLDA:LENGTH. This covers bytes 1 and 2
(the alphanumeric portion).
• To designate only the data portion of the field (bytes 3 through 250), specify FLDA:DATA. This covers bytes 3 through
250 (the binary portion).
NOTE
When you reference the entire field, CA Easytrieve automatically uses the length portion of the field when it acts
on the field.
Displaying Varying Length Fields
The display window for varying length fields is based on the maximum length. However, the current value of the length
portion determines how much of the data portion is displayed in the window.
The length portion of the field is not typically displayed. However when DISPLAY HEX is used, length and data is
displayed. DISPLAY HEX displays length and the full data field in hexadecimal and character format. An example follows.
Statements:
DEFINE FLDA W 7 A VALUE 'ABCD' VARYING
JOB INPUT NULL NAME MYPROG
DISPLAY FLDA
DISPLAY HEX FLDA
STOP
Results:
ABCD
CHAR ABCD
ZONE 00CCCC4
NUMB 0412340
Assigning and Moving Varying Length Fields
Assignments are based on the current length of the data and the rules of assignment. MOVEs default to the current length
of the data. MOVE SPACES moves blanks according to the maximum possible length of the varying length field. An
example follows.
466
CA Easytrieve® Report Generator 11.6
Statements:
DEFINE NULLSTRING W 10 A VARYING VALUE ''
DEFINE SENDVAR W 10 A VARYING VALUE '12345678'
DEFINE RECVVAR07 W 7 A VARYING
DEFINE RECVVAR10 W 10 A VARYING
JOB INPUT NULL NAME MYPROG
RECVVAR10 = NULLSTRING . * ASSIGN NULL STRING TO VARYING
DISPLAY '1. VALUE=' RECVVAR10 ' LENGTH=' RECVVAR10:LENGTH
RECVVAR10 = SENDVAR . * ASSIGN 10 BYTE VARYING TO 10 BYTE VARYING
DISPLAY '2. VALUE=' RECVVAR10 ' LENGTH=' RECVVAR10:LENGTH
RECVVAR07 = SENDVAR . * ASSIGN 10 BYTE VARYING TO 7 BYTE VARYING
DISPLAY '3. VALUE=' RECVVAR07 ' LENGTH=' RECVVAR07:LENGTH
RECVVAR10 = RECVVAR07 . * ASSIGN 7 BYTE VARYING TO 10 BYTE VARYING
DISPLAY '4. VALUE=' RECVVAR10 ' LENGTH=' RECVVAR10:LENGTH
MOVE SPACES TO RECVVAR07 . * MOVE SPACES TO 7 BYTE VARYING
DISPLAY '5. VALUE=' RECVVAR07 ' LENGTH=' RECVVAR07:LENGTH
STOP
Results:
1. VALUE= LENGTH=
2. VALUE=12345678 LENGTH= 8
3. VALUE=12345 LENGTH= 5
4. VALUE=12345 LENGTH= 5
5. VALUE= LENGTH= 5
NOTE
• If the sending field has a length of zero and the receiving field is a VARYING field, the receiving field has a
length of zero.
• If the sending field has a length of zero and the receiving field is not a VARYING field, the receiving field is
filled with the fill character (blank for assigned, blank, or specified fill character for MOVE).
Comparing Varying Length Fields
Comparisons of varying length fields are based on the length of the data at the time of the comparison.
8-Byte Binary Fields
Processing 8-byte binary fields in CA Easytrieve® Report Generator programs presents some special challenges. These
challenges arise from the fact that the maximum precision for an 8-byte binary field is 19 digits, which is more than CA
Easytrieve® Report Generator allows for any other field type. In order to allow an CA Easytrieve® Report Generator
program to work with 8-byte binary fields, the rule concerning maximum precision is relaxed. However, it is important to
remember that this applies solely to 8-byte binary fields.
Contents:
Edit Masks for 8-Byte Binary Fields
When defining an edit mask for an 8-byte binary field you must remember to provide 19 digit selectors. For example,
consider the following Easytrieve program:
467
CA Easytrieve® Report Generator 11.6
DEFINE TEST-B-FIELD W 8 B 0 +
MASK '-,---,---,---,---,---,--9'
JOB INPUT(NULL)
TEST-B-FIELD = 1000000
DISPLAY 'TEST-B-FIELD=' TEST-B-FIELD
TEST-B-FIELD = -1000000
DISPLAY 'TEST-B-FIELD=' TEST-B-FIELD
TEST-B-FIELD = -1000000000000000000
DISPLAY 'TEST-B-FIELD=' TEST-B-FIELD
STOP
This program will produce the following output:
TEST-B-FIELD= 1,000,000
TEST-B-FIELD= -1,000,000
TEST-B-FIELD=-1,000,000,000,000,000,000
NOTE
The last line of output includes all 19 digits of the value.
Assigning 8-Byte Binary Fields to Other Field Types
The 19-digit precision of 8-byte binary fields also affects the result of assignments to fields with other types. These other
fields have are restricted to a maximum precision of 18 digits. This means that there is a potential to lose the high-order
digit of the 8-byte binary field on assignment. For example, consider the program:
DEFINE TEST-B-FIELD W 8 B 0 VALUE 9223372036854775807
DEFINE TEST-P-FIELD W 10 P 0
JOB INPUT(NULL)
DISPLAY 'TEST-B-FIELD=' TEST-B-FIELD
TEST-P-FIELD = TEST-B-FIELD
DISPLAY 'TEST-P-FIELD=' TEST-P-FIELD
STOP
This program will produce the following output:
TEST-B-FIELD=9,223,372,036,854,775,807
TEST-P-FIELD=223,372,036,854,775,807
NOTE
The value lost the high-order digit of 9 during assignment from 8-byte binary to 10-byte packed.
Using 8-Byte Binary Fields in Expressions
As explained previously, the 8-byte binary field can lose its high-order digit during assignment. However, when an 8-byte
binary field appears as a term in an expression, the full value of the field is retained. For example, consider the program:
DEFINE TEST-B-FIELD W 8 B 0 VALUE 9223372036854775807
DEFINE TEST-P-FIELD W 10 P 0
DEFINE TEST-B-NEWFL W 8 B 0
JOB INPUT(NULL)
DISPLAY 'TEST-B-FIELD=' TEST-B-FIELD
TEST-P-FIELD = TEST-B-FIELD / 10
468
CA Easytrieve® Report Generator 11.6
DISPLAY 'TEST-P-FIELD=' TEST-P-FIELD
TEST-B-NEWFL = TEST-P-FIELD * 10 + 7
DISPLAY 'TEST-B-NEWFL=' TEST-B-NEWFL
STOP
This program will produce the following output:
TEST-B-FIELD=9,223,372,036,854,775,807
TEST-P-FIELD=922,337,203,685,477,580
TEST-B-NEWFL=9,223,372,036,854,775,807
NOTE
The division causes the low-order digit to be discarded as expected. Also, the multiplication of the 10-byte
packed value produced a 19-digit intermediate value such that the addition produced the original input value,
also as expected.
Declarations
This article explains the declarations that you can code using the DECLARE statement.
Declare Screen Item Attributes (CA Easytrieve Online)
You can declare named screen attribute fields by using the DECLARE statement. These declared attributes are different
from ordinary fields that you DEFINE. Screen attributes contain information that controls the display of screen items such
as their color and brightness.
Use of declared attributes provides the ability to dynamically change screen attributes during program execution, and
saves you coding time when the set of attributes is used many times. Declared attributes can be used as follows:
• Use the DECLARE statement to name a set of screen attributes you want to use on multiple screen items.
For example, it is easier to use a declared attribute containing the INTENSE, BLUE, and MUSTFILL attributes on
multiple items than to code the three attributes on each item in the screen. Declared attributes can be used in the
ATTR parameter of the DEFAULT, TITLE, and ROW statements.
• You can use declared attributes to contain a dynamic set of attributes, that is, you can declare named attributes
containing various sets of attributes. To do this, declare an empty named attribute to use on your ROW statements.
Before displaying the screen, you can assign one of the declared attributes containing a specific set of attributes into
the empty declared attribute. This lets you dynamically set the screen attributes of items based on decisions that are
made during execution.
Declare Input Edit Patterns
You can also use the DECLARE statement to declare named input edit patterns. An input edit pattern allows you to
specify a character sequence that describes the format of the data in the field.
NOTE
Use a PATTERN to edit complex combinations of data types and character sequences. Use a MASK to edit
numeric data.
These named input patterns can then be used in the PATTERN parameter of multiple items on ROW statements in a
SCREEN activity. Input data is automatically checked against the pattern and if the data does not conform to its specified
PATTERN, an appropriate error message is issued to the terminal user.
As with declared attributes, using a declared pattern requires you to specify the PATTERN only once. Declared patterns
can then be used on multiple items on ROW statements.
469
CA Easytrieve® Report Generator 11.6
Declare Subprogram Linkage
You can also use the DECLARE statement to specify how you want to link a subprogram. Subprograms can be linked
statically with your CA Easytrieve program or dynamically loaded.
NOTE
• For more information about using screen attributes and patterns, see the Screen Processing section.
• For more information about subprogram linkage, see Inter-Program Linkage.
Literal and Data Formatting Rules
You can code ASCII and EBCDIC alphanumeric, hexadecimal, DBCS, and MIXED format literals in CA Easytrieve
Report Generator programs. EBCDIC, ASCII, SBCS, MIXED, and DBCS data formats are processed, but all possible
relationships that can exist between these formats are not supported. The following sections describe each of the
supported literals, and explain the format and conversion rules and format relationship rules for the mainframe:
ASCII and EBCDIC Alphanumeric Literals
Alphanumeric literals are words that are enclosed within single quotes, and can be up to 254 characters long. An
alphanumeric literal can contain ASCII and EBCDIC alphabetic characters A to Z, and numeric characters 0 to 9.
Whenever an alphanumeric literal contains an embedded single quote, you must code two single quotes. For example,
the literal O'KELLY is coded as:
'O''KELLY'
Note: ASCII is supported on UNIX and on Windows. EBCDIC is supported on the mainframe.
Hexadecimal Literals
Hexadecimal literals are words used to code values that contain characters not available on standard data entry
keyboards. Prefix the hexadecimal literal with X' (the letter X and a single quote), and terminate it with a single quote.
Each pair of digits that you code within the single quotes is compressed into one character. Only the digits 0 through 9 and
the letters A through F are permitted. The following hexadecimal literal defines two bytes of binary zeros:
X'0000'
DBCS Format Literals
DBCS format literals contain DBCS characters only. Enclose a DBCS format literal within apostrophes. A DBCS format
literal can be up to 254 bytes long, including the shift codes. An example of a DBCS literal follows:
'[DBDBDBDBDBDB]'
The left bracket ([) and right bracket (]) indicate shift-out and shift-in codes.
MIXED Format Literals
MIXED format literals are words containing both SBCS and DBCS characters. Enclose MIXED format literals within
apostrophes. The presence of shift codes identifies DBCS subfields. Shift codes also identify the code system of that
DBCS data. The word coded within the apostrophes (including the shift codes) cannot exceed 254 bytes in length. A
MIXED literal is defined in the following example:
470
CA Easytrieve® Report Generator 11.6
'EEEE[DBDBDB]'
The left bracket ([) and right bracket (]) indicate shift-out and shift-in codes.
Non-mainframe Data Format
In non-mainframe environments, the product assumes all literals and alphanumeric data are ASCII and performs no
conversion.
Format and Conversion Rules (Mainframe Only)
During compilation, all literals coded in the source program are converted into the correct DBCS code system and data
format (SBCS, MIXED, or DBCS) as dictated by the statements in which they appear. To understand the process used to
determine the correct code system and data format, it is important to identify the element of each program statement that
is interpreted as the subject of that statement. The subject dictates the correct code system and format type.
Literal Subject Elements (Mainframe Only)
Each program statement has a subject element whose DBCS code system and data format define the DBCS code system
and data format of all the other elements that appear on that statement.
The following table lists the subject elements of those statements that support the coding of literals. Those that do not
have a subject element are also included. They are indicated by the words "not applicable."
Statement Subject Element
FILE file-name .... file-name
DEFINE field-name .... field-name
Assignment - field-name .... field-name
IF field-name .... field-name
DO WHILE field-name .... field-name
RETRIEVE WHILE field-name .... field-name
MOVE .... not applicable
POINT file-name .... file-name
CALL program-name .... not applicable
DISPLAY .... file-name(printer)
REPORT report-name .... file-name(printer)
HEADING .... file-name(printer)
TITLE (report) .... file-name(printer)
LINE .... file-name(printer)
SCREEN screen-name terminal
DEFAULT .... not applicable
KEY .... terminal
TITLE (screen) .... terminal
ROW/REPEAT .... terminal
DBCS Code System and Data Format Literal Rules
Using the identified subject element of each program statement, the table that follows defines the rules for determining
the DBCS code system and data format for a literal. If a literal is not in the required DBCS code system or data format, the
literal is converted to the correct DBCS code system and data format during compilation.
471
CA Easytrieve® Report Generator 11.6
In the following table, the code ASIS means that the data format (SBCS, MIXED, or DBCS) of the literal coded in the
program source is retained by the CA Easytrieve Report Generator compiler (it is not converted).
Statement/ Data Format of Literal DBCS Code System of Literal
Keyword
FILE - EXIT..USING ASIS PROCESSING
DEFINE - HEADING ASIS PROCESSING
IF/DO...WHILE field-name field-name
Assignment field-name field-name
POINT ASIS file-name
HEADING ASIS file-name(printer)
TITLE (report) ASIS file-name(printer)
LINE ASIS file-name(printer)
KEY ASIS terminal
TITLE (screen) ASIS terminal
ROW ASIS terminal
Format Relationship Rules (Mainframe Only)
The product processes SBCS, MIXED, and DBCS data formats, but does not support all the possible relationships
that can exist between these data formats. The following table defines the relationships that the product supports.
Relationships that are not defined in the table are not supported. Compilation errors occur if you specify them in your
program.
If a conversion is necessary, the conversion column in the table indicates the additional processing that applies to get the
object into the correct DBCS code system and applicable data format. The letter F means that the object is reformatted
to meet the requirements of the subject element. This category includes the reformatting of numeric data into the numeric
format of the subject and also the reformatting from one data format (SBCS, MIXED, or DBCS) into the data format of the
subject element.
The supported mainframe format relationships are:
Subject Element Data Format Supported Object Data Format Conversion
A - SBCS Alpha SBCS Alphabetic field none
A - SBCS Alpha SBCS Zoned Numeric field F
A - SBCS Alpha SBCS Packed field F
A - SBCS Alpha SBCS Unsigned Packed field F
A - SBCS Alpha SBCS Binary field F
A - SBCS Alpha SBCS Alphabetic Literal none
A - SBCS Alpha SBCS Hexadecimal Literal none
N - Zoned Numeric SBCS Zoned Numeric field none
N - Zoned Numeric SBCS Packed field F
N - Zoned Numeric SBCS Unsigned Packed field F
N - Zoned Numeric SBCS Binary field F
N - Zoned Numeric SBCS Numeric Literal none
P - Packed SBCS Zoned Numeric field F
N - Zoned Numeric SBCS Packed field none
472
CA Easytrieve® Report Generator 11.6
N - Zoned Numeric SBCS Unsigned Packed field F
N - Zoned Numeric SBCS Binary field F
N - Zoned Numeric SBCS Numeric Literal F
N - Unsigned Packed SBCS Zoned Numeric field F
N - Zoned Numeric SBCS Packed field none
N - Zoned Numeric SBCS Unsigned Packed field F
N - Zoned Numeric SBCS Binary field F
N - Zoned Numeric SBCS Numeric Literal F
B - Binary SBCS Zoned Numeric field F
B - Binary SBCS Packed field F
B - Binary SBCS Unsigned Packed field F
B - Binary SBCS Binary field none
B - Binary SBCS Numeric Literal F
M - Mixed SBCS Alphabetic field none
M - Mixed SBCS Zoned Numeric field F
M - Mixed SBCS Packed field F
M - Mixed SBCS Unsigned Packed field F
M - Mixed SBCS Binary field F
M - Mixed MIXED field FC
M - Mixed DBCS/Kanji field FC
M - Mixed SBCS Alphabetic Literal none
M - Mixed SBCS Numeric Literal F
M - Mixed SBCS Hexadecimal Literal none
M - Mixed DBCS Format Literal FC
M - Mixed MIXED Format Literal C
D/K - DBCS/Kanji SBCS Alphabetic field none
D/K - DBCS/Kanji SBCS Zoned Numeric field F
D/K - DBCS/Kanji SBCS Packed field F
D/K - DBCS/Kanji SBCS Unsigned Packed field F
D/K - DBCS/Kanji SBCS Binary field F
D/K - DBCS/Kanji MIXED field F
D/K - DBCS/Kanji DBCS/Kanji field none
D/K - DBCS/Kanji SBCS Alphabetic Literal F
D/K - DBCS/Kanji SBCS Numeric Literal F
D/K - DBCS/Kanji SBCS Hexadecimal Literal none
D/K - DBCS/Kanji DBCS Format Literal none
D/K - DBCS/Kanji MIXED Format Literal F
Control Program Flow
You control the flow of execution through your CA Easytrieve Report Generator program with the statements that are
coded within your activities.
473
CA Easytrieve® Report Generator 11.6
This article includes the following information:
Activities
CA Easytrieve Report Generator activities resemble the steps of a batch job, but they are not constrained by Job Control
Language (JCL) and associated operating system overhead. A CA Easytrieve Report Generator program consists of at
least one of the four types of activities: PROGRAM, SCREEN, JOB, and SORT.
A PROGRAM activity is optional. If used, only one PROGRAM activity can be coded in a CA Easytrieve Report Generator
program, and it must be coded before any other activities. PROGRAM activities can control the entire program. If used,
the PROGRAM activity must EXECUTE the other types of activities when they are to be initiated. If no PROGRAM activity
is coded, there is an implied PROGRAM activity that initiates other activities as follows:
• JOB and SORT activities are executed sequentially until a SCREEN activity is detected.
• The SCREEN activity is executed.
• Any remaining activities must be executed by the first SCREEN activity. Automatic sequential execution does not
proceed beyond the first SCREEN activity.
You can code one or more procedures (PROCs) at the end of each activity. Procedures are local to the activity after which
they are coded. You cannot perform procedures that are not associated with the activity in which the PERFORM is coded.
You can code one or more REPORT subactivities after the PROCs at the end of each JOB activity. You must code PROCs
used within a REPORT subactivity immediately after the REPORT subactivity in which you use them.
Program Flow
The PROGRAM activity is a simple top-down execution of the statements that are contained in it. PROGRAM activity
is delimited by another activity in the source. PROGRAM activity execution stops when any one of the following actions
occurs:
• The end of the activity is reached.
• A STOP statement is executed in the PROGRAM activity.
• A STOP EXECUTE or TRANSFER statement is executed anywhere in the program.
If a PROGRAM activity is coded, it is responsible for the execution of other activities in the program.
Screen Flow
The following code shows the basic flow of a SCREEN activity. See Screen Processing for more information.
RESET working storage
[PERFORM INITIATION]
SCREEN ...
RESET working storage
[PERFORM BEFORE-SCREEN]
1. Build screen using program fields,
pending messages, and cursor placement
2. Send the screen
3. Receive the screen
4. Edit the input data
5. Handle automatic actions
[PERFORM AFTER-SCREEN]
GOTO SCREEN
RESET working storage
[PERFORM TERMINATION]
474
CA Easytrieve® Report Generator 11.6
Job Flow
The following code shows the relationship between JOB activity statements and shows implied statements that are
attributed to JOB:
RESET working storage
[PERFORM start-proc]
JOB ... retrieve automatic input
IF EOF
RESET working storage Logic generated by JOB
[PERFORM finish-proc]
wrap-up REPORTS
return to invoking activity
END-IF
IF ...
PERFORM proc-name
PRINT report-name JOB activity statements
...
END-IF
RESET working storage
GOTO JOB Implied iteration at end
of JOB statements
proc-name. PROC
... Optional procedures
END-PROC and reports are
REPORT report-name placed at end of JOB
statements
...
JOB/SORT/SCREEN Other activities
CA Easytrieve Report Generator processes input records one at a time. You can use any valid combination of statements
to examine and manipulate the input record. CA Easytrieve Report Generator repeats the processing activity until the
input is exhausted or until you issue a STOP statement.
Sort Flow
The following example illustrates the flow of a SORT activity:
Retrieve first record from input file (file-a) Step 1
Logic generated by the
DO WHILE NOT EOF file-a SORT statement
IF BEFORE was specified Step 2
If BEFORE requested
IF RESET working storage fields specified Step 3
reset all RESET working storage fields Re-initialize RESET fields
PERFORM proc-name Step 4
475
CA Easytrieve® Report Generator 11.6
Perform the user's proc
IF SELECT statement was executed Step 5
pass record to SORT SELECT executed?
END-IF pass record to SORT
ELSE
Step 6
pass record to SORT No BEFORE proc,
pass all to SORT
END-IF
Step 7
Retrieve next record from input file (file-a) Get next record from
input file
END-DO
Step 8
Perform SORT process (USING fld1, ...) Actually SORT the
records
DO WHILE sorted records exist Step 9
Write sorted record to output file (file-b) Write sorted records to
END-DO output file
proc-name. PROC Step 10
... Optional user-written
SELECT procedure is placed
... after the SORT
END-PROC
JOB/SORT
Units of Work and Commit Processing
To help you control the integrity of your files, databases, and other resources, CA Easytrieve Report Generator performs
commit processing. Commit processing issues commands to the operating environment signifying the end of one unit
of work and the start of another. These commit points provide a point at which updates are committed to the operating
system. Changes that are not committed can be recovered or rolled back.
Commit points and rollbacks can be issued automatically by CA Easytrieve Report Generator or you can control this
processing yourself.
Automatic Commit Processing
Each CA Easytrieve Report Generator activity can be considered a logical unit of work. For each activity statement, you
can code a COMMIT parameter on the PROGRAM, JOB, SCREEN, and SORT statements to control the way the product
automatically issues commit points.
Commit points can be issued automatically as follows:
• Use the ACTIVITY | NOACTIVITY subparameter to indicate whether a commit point is issued during the normal
termination of an activity:
476
CA Easytrieve® Report Generator 11.6
– ACTIVITY -- Indicates to commit during the normal activity termination process. This is the default for PROGRAM
activities, if it is not specified.
– NOACTIVITY -- Indicates to not commit during activity termination. This is the default for JOB, SCREEN, and SORT
activities, if it is not specified.
• Use the TERMINAL | NOTERMINAL subparameter to indicate whether a commit point is issued during each terminal I/
O operation that is performed in the activity.
– TERMINAL -- Indicates to commit during each terminal I/O. This includes terminal I/O for SCREEN activities
and also for the Report Display Facility. In CICS, committing during terminal I/O runs your program pseudo-
conversationally. This is the default, if not specified.
– NOTERMINAL -- Indicates to not commit during terminal I/O. In CICS, this runs your program conversationally.
NOTE
• Once an activity with NOTERMINAL specified starts, all child activities execute with NOTERMINAL
specified for them until the parent activity terminates.
• When CA Easytrieve Report Generator determines that a program has been linked to, the linked to
program always behaves as if NOTERMINAL had been specified, that is, the child program always
executes in fully-conversational mode. See Inter-Program Linkage for more information about the LINK
statement.
When an activity terminates abnormally, a rollback is automatically issued to recover the updates that were made since
the last commit point.
If you execute a STOP EXECUTE statement in your activity, it is considered an abnormal termination.
Controlled Commit Processing
You can issue your own commit points and rollbacks as needed for your application by using the COMMIT and
ROLLBACK statements. These commits and rollbacks are performed in addition to the commits and rollbacks that are
automatically issued as a result of the COMMIT parameter on the activity statement.
Note: Controlled commits have no effect on whether programs run conversationally or pseudo-conversationally in CICS.
Recoverable Resources
With a recoverable resource, the actual processing that is performed by the execution of commits and rollbacks is
determined by the operating environment in which CA Easytrieve Report Generator is running. Each time a commit point
is issued, CA Easytrieve Report Generator causes the following actions to happen:
• An SQL COMMIT that closes cursors is executed.
• An IDMS COMMIT or IDMS FINISH is executed. IDMS FINISH statements end run-units and are used at the end
of activities or during terminal I/O. Following an IDMS FINISH statement, CA Easytrieve Report Generator does not
automatically bind the run-unit or re-establish currencies.
• HOLDs that have been issued are released.
• Browses of VSAM files are terminated. CA Easytrieve Report Generator can generally reposition the file for you.
However, the product cannot reposition an indexed file if the associated data set is a VSAM PATH and the auxiliary or
secondary index data set was defined with non-unique keys.
• Browses of C-ISAM files are terminated. Because only files with unique keys are supported, the product repositions the
file for you.
• In CICS, printer spool files are closed. CA Easytrieve Report Generator automatically defers opening these files until
they are used.
You must provide the necessary logic in your code to handle these events.
CICS
477
CA Easytrieve® Report Generator 11.6
In the CICS environment, the following resources are generally recoverable:
• SQL databases
• VSAM data sets specified as recoverable in their FCT entries
• CA IDMS databases
• IMS/DLI databases
In CICS, a commit request (either automatic or controlled) issues a CICS SYNCPOINT command. A rollback request
issues a CICS SYNCPOINT ROLLBACK command. A CICS SYNCPOINT ROLLBACK command terminates the DLI PSB
and database positioning is lost. CA Easytrieve Report Generator does not automatically reschedule the PSB or reposition
the DLI database.
When CA IDMS is available, a controlled commit request issues an IDMS COMMIT command. An automatic commit
issues an IDMS FINISH command. A rollback request issues an IDMS ROLLBACK command. Each time an IDMS
FINISH command is issued, CA IDMS ends the run-unit. You must provide the necessary logic in your program to bind a
new run-unit and re-establish currencies as needed.
TSO and CMS
In TSO and CMS, SQL databases are the only recoverable resources. In TSO, CA IDMS databases are also recoverable.
When SQL is available, a commit request (either automatic or controlled) issues an SQL COMMIT command. A rollback
request issues an SQL ROLLBACK command.
Each time a commit point is issued, SQL closes all cursors. You must provide the necessary logic in your program to open
and reposition the cursor as needed. Exceptions can exist for specific SQL databases that maintain cursor positioning
across commits.
For DL/I files, issuing a commit point has no effect. In this case, DL/I CHECKPOINT and RESTART functions should be
used to manage logical units of work. DL/I files do not lose positioning when a commit point is issued.
When CA IDMS is available, a controlled commit request issues an IDMS COMMIT command. An automatic commit
issues an IDMS FINISH command. A rollback request issues an IDMS ROLLBACK command. Each time an IDMS
FINISH command is issued, CA IDMS ends the run-unit. You must provide the necessary logic in your program to bind a
new run-unit and re-establish currencies as needed.
Non-mainframe
In non-mainframe environments, SQL and C-ISAM are recoverable resources.
When SQL is available, a commit request (either automatic or controlled) issues an SQL COMMIT command. A rollback
request issues an SQL ROLLBACK command. Each time a commit point is issued, SQL closes all cursors. You must
provide the necessary logic in your program to open and reposition the cursor as needed.
When C-ISAM is available, a commit request, either automatic or controlled, issues a call to iscommit. A rollback request
issues a call to isrollback. Each time a commit point is issued, CA Easytrieve Report Generator closes and reopens all
active C-ISAM files. Files are then repositioned upon the next browse operation.
Decision and Branching Logic
CA Easytrieve Report Generator uses certain statements to control the execution of your program using decision and
branching logic. These statements can govern program execution flow depending on the truth value of the conditional
expressions. The following statements are associated with decision and branching logic:
CASE IF
DO GOTO
EXECUTE PERFORM
PROC STOP
EXIT REFRESH
478
CA Easytrieve® Report Generator 11.6
RESHOW
Conditional Expressions
Conditional expressions that are used as parameters of IF and DO statements offer an alternative to the normal top to
bottom execution of CA Easytrieve Report Generator statements. The syntax of a conditional expression is:
{IF } [ {AND} ]
{DO WHILE} condition [ { } condition ]...
{DO UNTIL} [ {OR } ]
CA Easytrieve® Report Generator accepts seven different conditions. There are five simple conditions (having at most two
operands) and two extended conditions (having potentially an unlimited number of operands):
Simple Conditions Extended Conditions
Field relational Field series
Field class File relational
Field bits
File presence
Record relational
Skeletal examples of each type of conditional expression that are used in an IF statement follow:
Type Example
Field relational IF field-1 = field-2
Field series IF field-1 = field-2, field-3, field-4
Field class IF field-1 ALPHABETIC
Field bits IF field-1 ON X'0F4000'
File presence IF EOF file-name
File relational IF MATCHED file-1, file-2, file-3
Record relational IF DUPLICATE file-name
For more information about each of these conditional expressions, see the Language Reference section.
Double Byte Character Set Support
The following conditions provide support for DBCS and MIXED fields:
• Field relational
• Field series
• Field class
• Field bits
As with the data equations, when conversion from EBCDIC to DBCS format is part of the conditional expression, CA
Easytrieve Report Generator converts the EBCDIC data using the following techniques:
• Lowercase EBCDIC values into the applicable DBCS Katakana characters
• Other valid EBCDIC characters into their equivalent English values
• Invalid EBCDIC values into DBCS spaces
Combined Conditions
479
CA Easytrieve® Report Generator 11.6
Any of these conditions, simple and extended, can be combined by using the logical connectors AND or OR in any
combination.
For combined conditions, those connected by AND are evaluated first. The connected condition is true only if all of the
conditions are true. The conditions connected by OR are then evaluated. The combined condition is true if any of the
connected conditions are true. You can use parentheses to override the normal AND and OR relationships. The following
table illustrates the results of combining conditions with AND, OR, and parentheses. The values x, y, and z represent any
condition.
x y z x OR x AND x OR (x OR y)
y OR z y AND z y AND z AND z
True True True True True True True
True True False True False True False
True False True True False True True
True False False True False True False
False True True True False True True
False True False True False False False
False False True True False False False
False False False False False False False
Assignments and Moves
The assignment statement establishes the value of a field as a result of simple data movements, an arithmetic expression,
or logical bit manipulation. If necessary, data is converted to the correct format, depending on field type.
• An arithmetic expression produces a numeric value by adding, subtracting, multiplying, or dividing numeric quantities.
• The MOVE statement transfers, without conversion, character strings from one storage location to another.
• The MOVE LIKE statement copies fields with identical field names from one file to another. Assignments are generated
for each field moved. Because assignments are used, the MOVE LIKE statement converts data to the correct format of
the receiving field if necessary.
This article includes the following information:
Arithmetic Expressions
To fully understand how an assignment establishes the value of a field as a result of an arithmetic expression, you need
to know how arithmetic expressions work within CA Easytrieve Report Generator. An arithmetic expression allows two
or more numeric quantities to be combined to produce a single value. Arithmetic expressions can be used in assignment
statements and in field relational conditions.
Operators
The arithmetic operators that are used in CA Easytrieve Report Generator are:
Symbol Operation
* multiplication
/ division
+ addition
- subtraction
480
CA Easytrieve® Report Generator 11.6
All fields and literals in an arithmetic expression must be numeric. CA Easytrieve Report Generator follows the standard
mathematical order of operations when computing arithmetic expressions: multiplication and division are performed before
addition and subtraction, in order from left to right.
The following example illustrates how arithmetic expressions are evaluated:
11 + 5 * 8 - 48 / 16 + 4 Step 1
└───Ú───┘
11 + 40 - 48 / 16 + 4 Step 2
└────Ú────┘
11 + 40 - 3 + 4 Step 3
└────Ú──────┘
51 - 3 + 4 Step 4
└───────────Ú────────┘
48 + 4 Step 5
└────────Ú──────────┘
52
Parentheses
You can use parentheses to override the normal order of evaluation. Any level of parenthesis nesting is allowed.
Expressions within parentheses are evaluated first, proceeding from innermost parenthesis level to the outermost.
The following example illustrates how parentheses found within arithmetic expressions are evaluated:
11 + 5 * ((8 - 48) / 16 + 4) Step 1
└────Ú──────┘
11 + 5 * ( -40 / 16 + 4) Step 2
└───────────Ú─────┘
11 + 5 * ( -2.5 + 4) Step 3
└────────────────Ú────┘
11 + 5 * 1.5 Step 4
└───────────Ú──────────────┘
11 + 7.5 Step 5
└─────────Ú───────────┘
18.5
Evaluations
When evaluating an arithmetic expression, at most 30 decimal digits are maintained for each operation. During the
calculation of:
{*}
{= } {/}
field-name-1 { } value-1 { } value-2
{EQ} {+}
{-}
481
CA Easytrieve® Report Generator 11.6
The length and number of decimal places that are maintained during the calculation (intermediate results) are determined
for each operation according to the rules shown in the following table:
If operation is: The number of decimal places equals:
Addition or Decimal places -- The larger of the number of decimal places
subtraction in value-1 or value-2.
Length -- The larger of the number of integer places
in value-1 or value-2, plus the number of decimal places in result
plus 1.
Multiplication Decimal places -- The sum of the number of decimal places
in value-1 and value-2.
Length -- The sum of the length of value-1 and value-2.
Division Decimal places -- The larger of:
The number of decimal places in value-1 minus the number of
decimal places in value-2.
The number of decimal places in field-name-1 plus one.
Four decimal places.
Length -- The number of integer places in value-1 plus the
number of decimal places in the result.
If the length of the intermediate result has more than 30 digits, the excess digits must be truncated. For addition,
subtraction, and division, the excess digits are always truncated from the left side of the result.
For multiplication, however, truncation on the right side of the result is attempted. The minimum number of decimal places
to be maintained in the result is the larger of:
• The number of decimal places in field-name-1 plus one
• Four decimal places
If the number of decimal places in the result is less than or equal to this minimum, no digits are truncated from the right
side of the result. Otherwise, the number of digits that are truncated from the right is the smaller of these values:
• The number of excess digits
• The difference between the number of decimal places in the result and the minimum
When truncation occurs on the right, both the length and number of decimal places in the result are reduced by the
number of digits truncated. If there are still excess digits after right truncation, these excess digits are truncated from the
left.
For example, assume that value-1 and value-2 both have a length of 18 digits and both have 4 decimal places. Then,
according to the previous rules table, the result has a length of 36 digits and 8 decimal places. In this case, the number
of excess digits is 6. Then, for various values of the number of decimal places in field-name-1, the result is truncated as
shown in the next table:
Decimal places in field-name-1 Digits truncated Decimal places in result
(left) (right)
Fewer than 2 60 4
2 51 4
3 42 4
4 33 5
5 24 6
6 15 7
More than 6 06 8
482
CA Easytrieve® Report Generator 11.6
Assignment Statement
The assignment statement establishes a value in a field. The value can be a copy of the data in another field or literal, or it
can be the result of an arithmetic or logical expression evaluation.
The two formats of the assignment statement are:
Format 1 Syntax (Normal Assignment)
{= } {send-field-name }
receive-field-name { } {send-literal }
{EQ} {arithmetic-expression}
Format 2 Syntax (Logical Expression)
{= } {AND} {bit-mask-field-name}
receive-field-name { } send-field-name {OR } {bit-mask-literal }
{EQ} {XOR} { }
EBCDIC to DBCS Conversion (Mainframe Only)
When conversion from EBCDIC to Double Byte Character Set format is required for the assignment statement, the
EBCDIC data is converted using the following techniques:
• Converts lowercase EBCDIC values into the applicable DBCS Katakana characters.
• Converts other valid EBCDIC characters into their equivalent English values.
• Converts invalid EBCDIC values into DBCS spaces.
Format 1 (Normal Assignment)
Format 1 sets the value of receive-field-name equal to the value of send-field-name, send-literal, or the arithmetic
expression. The rules of the statement are shown in the following table:
Receive-field-name (Left-hand side) Send-field-name (Right-hand side) Resulting Value
Alphanumeric field Alphabetic field Resulting value of receive-field-name is
padded on right with spaces or truncated as
necessary.
Numeric field Resulting value of receive-field-name is the
non-quantitative zoned decimal equivalent
of send-field-name with padding or
truncation on left as necessary. Assignment
of numeric fields to varying alphanumeric
fields is not allowed.
Alphanumeric or hexadecimal literal Resulting value of receive-field-name is
padded on right with spaces as necessary.
Alphanumeric or hexadecimal field MIXED field Each byte of send-literal is moved
to receive-field-name unaltered. The
resulting value of receive-field-name is
padded on right with EBCDIC spaces.
483
CA Easytrieve® Report Generator 11.6
Numeric field Numeric field, Result is padded on left with zeros to fit
literal, the description of receive-field-name. If the
or arithmetic expression value of the assignment is too large to be
stored in receive-field-name, it is truncated
as follows:
For binary numbers (numbers that are
expressed in two's complement form), the
sign and high-order bits are truncated from
left as necessary, and the remaining left-
most bit becomes the new sign.
For zoned decimal, packed decimal,
and unsigned packed decimal numbers
(numbers that are expressed in sign-
magnitude form), the high-order digits
are truncated from left as necessary. The
result is truncated on right if the number of
decimal places in receive-field-name is less
than the right-hand side.
Declared attribute field Declared attribute field Receive-field name is replaced with the
attributes that are contained in send-field-
name.
Nullable field NULL field Indicator for receive-field-name is set to 1
(indicates NULL).
Not NULL field The assignment works as usual and the
indicator for receive-field-name is set to 0,
indicating NOT NULL.
Literal Indicator for receive-field-name is set to 0.
Arithmetic expression with any NULL A runtime error occurs.
operand
Arithmetic expression in which all operands Indicator for receive-field-name is set to 0.
are NOT NULL
Not nullable field NULL field A runtime error occurs.
DBCS field DBCS field Send-field-name is converted into the
DBCS code system of receive-field-
name. The resulting value of receive-field-
name is padded on right with DBCS spaces
or truncated on right as necessary.
MIXED field Each EBCDIC byte of send-field-name is
converted into its equivalent DBCS value.
Any DBCS data that is identified by shift
codes is converted to the DBCS code
system of receive-field-name. The shift
codes are then removed. The resulting
value of receive-field-name is padded on
right with DBCS spaces or truncated on
right as necessary.
Alphabetic field Each byte of send-field-name is converted
into its equivalent DBCS value and the
resulting value is stored in receive-field-
name. The resulting value of receive-field-
name is padded on right with DBCS spaces
or truncated on right as necessary.
484
CA Easytrieve® Report Generator 11.6
Numeric, Resulting value of receive-field-name is
packed, zoned decimal equivalent of send-field-
or binary field name with each byte converted into the
DBCS equivalent. Before the conversion,
the result is padded on left with DBCS
zeros, or truncated on left.
DBCS literal Resulting value of receive-field-name is
padded on right with DBCS spaces or
truncated on right as necessary.
DBCS Field Alphanumeric or hexadecimal literal Each byte of send-literal is converted into
its equivalent DBCS value and the result
is stored in receive-field-name. Resulting
value of receive-field-name is padded on
right with DBCS spaces or truncated on
right as necessary.
MIXED field DBCS field Send-field-name is converted into the
DBCS code system of receive-field-name.
The shift codes that are defined for the
code system of receive-field-name are
added and the resulting value is padded on
right with EBCDIC spaces or truncated on
right as necessary. When truncation occurs,
DBCS characters are not split. Truncation is
to the nearest double byte.
MIXED field The EBCDIC data in send-field-name is
moved unaltered to receive-field-name. The
DBCS data that is identified by shift codes
is converted to the DBCS code system
of receive-field-name. The shift codes are
also converted to meet the requirements
of that code system. The resulting value
of receive-field-name is padded on right
with EBCDIC spaces or truncated on right
as necessary. When truncation occurs
within the DBCS portion of a field, DBCS
characters are not split. Truncation is to the
nearest double byte.
Alphabetic field Each byte of send-field-name is moved
unaltered to receive-field-name. The
resulting value of receive-field-name is
padded on right with EBCDIC spaces or
truncated on right as necessary.
Numeric, Resulting value of receive-field-name is
packed, the zoned decimal equivalent of send-field-
or binary field name with padding or truncation on left, if
necessary.
DBCS literal Send-field-name is converted into the
code system of receive-field-name and the
correct shift codes are added. The result is
padded on right with EBCDIC spaces.
Examples
The following examples of Format 1 of the assignment statement illustrate its various rules:
485
CA Easytrieve® Report Generator 11.6
Format 1 (Normal Assignment, receive-field-name alphanumeric)
Statements:
F1A W 4 A
F2A1 W 1 A VALUE 'A'
F2A2 W 6 A VALUE 'ABCDEF'
F2N1 W 2 N VALUE 12
F2N2 W 3 P 1 VALUE 1234.5
...
Resulting Value:
F1A = F2A1 'A '
F1A = F2A2 'ABCD'
F1A = F2N1 '0012'
F1A = F2N2 '2345'
F1A = X'FF' X'FF404040'
Note: For an example using varying length alphanumeric fields, see Varying Length Fields in Defining Fields.
Format 1 (Normal Assignment, receive-field-name numeric)
Statements:
DEFINE F1N W 4 N 1
DEFINE F2N1 W 4 N 1 VALUE 1
DEFINE F2N2 W 4 N 1 VALUE 2
DEFINE F2N3 W 4 N 1 VALUE 3
JOB INPUT NULL NAME MYPROG
F1N = F2N1 + F2N2 + F2N3
DISPLAY SKIP 2 +
'F1N = F2N1 + F2N2 + F2N3 = ' F1N
F1N = F2N1 + F2N2 / F2N3
DISPLAY SKIP 2 +
'F1N = F2N1 + F2N2 / F2N3 = ' F1N
F1N = (F2N1 + F2N2) / F2N3
DISPLAY SKIP 2 +
'F1N = (F2N1 + F2N2) / F2N3 = ' F1N
F1N = ((F2N1 / F2N2) * 100) + .5
DISPLAY SKIP 2 +
'F1N = ((F2N1 / F2N2) * 100) + .5 = ' F1N
STOP
Results:
Resulting
Value
F1N = F2N1 + F2N2 + F2N3 = 6.0
(1 + 2 + 3)
F1N = F2N1 + F2N2 / F2N3 = 1.6
(1 + 2 / 3)
486
CA Easytrieve® Report Generator 11.6
(1 + 0.6666)
F1N = (F2N1 + F2N2) / F2N3 = 1.0
(( 1 + 2) / 3)
(3 / 3)
F1N = ((F2N1 / F2N2) * 100) + .5 = 50.5
(( 1 / 2) * 100) + .5
((0.5 * 100) + .5)
(50 + .5)
Format 2 (Logical Expression)
Format 2 of the assignment statement sets the value of receive-field-name equal to the result of evaluating a logical
expression. The value of send-field-name is logically acted upon by the value of bit-mask-field-name or bit-mask-literal.
The lengths of all values must be the same and bit-mask-literal must be hexadecimal.
• AND -- Zero bits in bit-mask-field-name or bit-mask-literal are carried forward to send-field-name and the result is
placed in receive-field-name.
• OR -- One bit in bit-mask-field-name or bit-mask-literal are carried forward to send-field-name and the result is placed
in receive-field-name.
• XOR -- Corresponding bits of bit-mask-field-name or bit-mask-literal, and of send-field-name must be opposite (zero
and one) to result in a one bit in receive-field-name.
Rules for Varying Length Fields
• Receive-field-name and send-field-name must both be varying length fields or fixed-length fields.
• Bit-mask-field-name must be a fixed-length field.
• If receive-field-name is a varying length field, the length of its data portion must be equal to the length of the data
portion of send-field-length and the length of bit-mask-field-name or bit-mask-literal.
Rules for Nullable Fields
The rules for nullable fields are shown in the following table:
Receive-field-name (Left-hand side) Send-field-name (Right-hand side) Resulting Value
Nullable field Nullable field but not NULL The receiving field's indicator is set to 0,
indicating NOT NULL.
Not a nullable field The receiving field's indicator is set to 0,
indicating NOT NULL.
Not nullable field NULL field A runtime error occurs.
Example
The following example of Format 2 of the assignment statement illustrates its various rules:
Format 2 (Logical Expression Evaluation) Statements:
Statements:
DEFINE F1P W 2 P MASK HEX
DEFINE F2P W 2 P VALUE X'123D'
JOB INPUT NULL NAME MYPROG
F1P = F2P AND X'FFFE'
DISPLAY SKIP 2 +
487
CA Easytrieve® Report Generator 11.6
'F1P = F2P AND X''FFFE'' = ' F1P
F1P = F2P OR X'000F
DISPLAY SKIP 2 +
'F1P = F2P OR X''000F'' = ' F1P
F1P = F2P XOR X'FFFF'
DISPLAY SKIP 2 +
'F1P = F2P XOR X''FFFF'' = ' F1P
F1P = F2P XOR F2P
DISPLAY SKIP 2 +
'F1P = F2P XOR F2P = ' F1P
STOP
Results:
Resulting
Value
F1P = F2P AND X'FFFE' = 123C
F1P = F2P OR X'000F' = 123F
F1P = F2P XOR X'FFFF' = EDC2
F1P = F2P XOR F2P = 0000
MOVE Statement
MOVE transfers characters from one storage location to another. It is used for moving data without conversion and for
moving variable length data strings. The following table illustrates the rules of the MOVE statement regarding nullable
fields:
Receive-field-name (Left-hand side) Send-field-name (Right-hand side) Resulting Value
Nullable field Send-field name that is not nullable Receiving field's indicator is set to 0,
indicating NOT NULL.
Literal Receiving field's indicator is set to 0,
indicating NOT NULL.
Send-field-name that is nullable The receiving field's indicator is set to -1
if the sending field is NULL, or if it is NOT
NULL.
Not nullable field NULL field A runtime error occurs.
MOVE LIKE Statement
MOVE LIKE moves the contents of fields with identical names from one file to another. Data movement and conversion
follow the rules of the assignment statement.
Table Processing
A table is a collection of uniform data records that presents unique processing opportunities. All tables have two parts:
• The argument uniquely identifies a table entry.
• The description is the remainder of the table entry.
488
CA Easytrieve® Report Generator 11.6
Some typical examples of table usage include organization structures, parts lists for assembly processes, and accounting
chart-of-accounts.
The search of CA Easytrieve® Report Generator table files is extremely efficient. Therefore, table use is recommended for
applications that need to validate encoded data and retrieve code description.
Contents
Defining Tables
There are two types of tables that you can specify on the FILE statement:
• In-stream (specified by the INSTREAM subparameter on the TABLE parameter) directs CA Easytrieve® Report
Generator to look for table data within the program immediately following the definition of the ARG and DESC fields for
the file. This table is established at the time the program is compiled. Its size is limited only by the amount of available
memory.
• External (INSTREAM is not specified) indicates that the table is located in a file external to the program. This file must
be sequentially accessible. An external table is established just before use.
An external table can be:
• An existing file that is in ascending order by its search argument
• Created by specifying the name of the table as the TO file-name parameter in a SORT activity.
External tables that are also indexed files result in a random read to the file using the search argument as the key. This
results in added efficiency.
All data needed to create small tables (to be processed by the SEARCH statement) can be entered instream along
with CA Easytrieve® Report Generator statements; that is, the table data can immediately follow the library definition
statements for the table. The data is delimited by the ENDTABLE statement in the first eight positions of a record.
In-stream table data is 80 characters per record and is unaffected by the SCANCOL options. All characters between the
ARG and DESC definitions and the ENDTABLE delimiter are treated as data.
Note: An in-stream table can be retrieved from a macro file. However, the macro must contain the entire table definition
(FILE statement through ENDTABLE).
The following illustrates a table-of-days definition:
FILE DAYTABL TABLE INSTREAM
ARG 1 1 A. DESC 3 9 A
1 SUNDAY }
2 MONDAY }
... } (instream data)
7 SATURDAY }
ENDTABLE }
The only way to modify an instream table is to recompile the program after supplying new table data. However, you
can modify external tables without program change, because CA Easytrieve® Report Generator builds these tables
dynamically prior to each use.
All tables must be sorted in ascending order by their search argument. No duplicate search arguments are allowed. Table
sequence is validated as the table is created.
The only fields defined for table files are ARG (argument) and DESC (description). ARG defines the field used
when searching the table. DESC defines the field that contains the desired information. The maximum length for an
alphanumeric ARG or DESC field is 254 bytes.
489
CA Easytrieve® Report Generator 11.6
The following illustrates a typical table file description. The resulting table provides descriptions of a hypothetical high
school curriculum:
1011 ENGLISH I }
1012 ENGLISH II } records from
... } CLASSES file
... }
9712 HOME ECONOMICS }
---------------------------------------
FILE CLASSES TABLE (150)...
ARG 1 4 A. DESC 10 40 A |
Searching Tables
The SEARCH statement provides access to table information. You can code SEARCH statements any place within a
PROGRAM, SCREEN, or JOB activity, and issue any number of searches against any number of tables. To test the
success of the SEARCH, use the file presence test: IF [NOT] file-name.
The following illustrates the retrieval of high school class descriptions based upon class identification codes:
Statements:
DEFINE CODE W 4 A
DEFINE DESCRIPTION W 40 A
FILE CLASSES TABLE INSTREAM
ARG 1 4 A
DESC 10 40 A
1011 ENGLISH I
1012 ENGLISH II
1013 ENGLISH III
1014 ENGLISH IV
ENDTABLE
PROGRAM NAME MYPROG
MOVE '1012' TO CODE
SEARCH CLASSES WITH CODE, GIVING DESCRIPTION
IF CLASSES
DISPLAY DESCRIPTION
ELSE
DISPLAY 'CLASS NOT FOUND'
END-IF
Result:
ENGLISH II
Array Processing
An array is a series of consecutive memory locations in one or more dimensions. You can process identical elements in
arrays by using either index manipulation or subscripting.
Contents
490
CA Easytrieve® Report Generator 11.6
Bounds Checking
CA Easytrieve® Report Generator automatically checks that indexes and subscripts do not reference data outside the
storage boundary of the field being referenced. If your index or subscript is out of bounds, an execution error occurs.
Subscripts are checked to ensure that they are within the OCCURS value of the field's definition. Indexes are checked to
ensure that the reference is within the largest enclosing data structure. For file fields, this structure is the file buffer. For
working storage fields, this is the defined field, or the base field if the defined field is a redefinition.
Indexing
Any data field definition can contain the INDEX attribute. An index can be used to reference data fields that occur
multiple times. If you do not use an index, you must either use subscripts or assign individual field names to multiple field
occurrences.
The data field's starting location is adjusted by the contents of its indexes to determine the desired field occurrence. The
INDEX index-name value is set to:
(desired occurrence number - 1) * (length of element)
Single Dimension Arrays
The following one-dimensional array is typical of those found in most programs. Data definition is straightforward. The
value of MONTH-INDEX controls access to the desired data occurrence, MONTH.
Statements:
DEFINE ARRAY-ELEMENT W 2 N
DEFINE MONTHS W 120 A VALUE +
'JANUARY +
FEBRUARY +
MARCH +
APRIL +
MAY +
JUNE +
JULY +
AUGUST +
SEPTEMBER +
OCTOBER +
NOVEMBER +
DECEMBER '
DEFINE MONTH MONTHS 10 A +
OCCURS (12) INDEX (MONTH-INDEX)
JOB INPUT NULL NAME MYPROG
ARRAY-ELEMENT = 11
MONTH-INDEX = (ARRAY-ELEMENT - 1) * 10
DISPLAY MONTH
STOP
Results:
NOVEMBER
491
CA Easytrieve® Report Generator 11.6
Because MONTH is 10 bytes long, the following relationships are true:
ARRAY-ELEMENT is: MONTH-INDEX is: DATA OCCURRENCE is:
1 0 JANUARY
2 10 FEBRUARY
3 20 MARCH
... ... ...
12 110 DECEMBER
Multiple Dimension Arrays
Multiple dimension arrays can be defined in two different ways:
• Define a single field with multiple indexes.
• Index a redefining field, as well as the parent field.
The following table illustrates two arrays that are identical in size and usage, but are defined very differently
MONTH-INDEX-1 MONTH-INDEX-2 MONTH ROW-INDEX-1 COL-INDEX-2 MONTH-CELL
0 0 JANUARY 0 0 JANUARY
0 10 FEBRUARY 0 10 FEBRUARY
0 20 MARCH 0 20 MARCH
30 0 APRIL 30 0 APRIL
30 10 MAY 30 10 MAY
30 20 JUNE 30 20 JUNE
60 0 JULY 60 0 JULY
60 10 AUGUST 60 10 AUGUST
60 20 SEPTEMBER 60 20 SEPTEMBER
90 0 OCTOBER 90 0 OCTOBER
90 10 NOVEMBER 90 10 NOVEMBER
90 20 DECEMBER 90 20 DECEMBER
In both cases, the sum of the indices determines which data occurrence is referenced. Both MONTH and MONTH-CELL
are 10-character fields with two indexes. Both fields also occur twelve times. MONTH-INDEX-1 and ROW-INDEX, and
MONTH-INDEX-2 and COL-INDEX are considered similar indexes.
You can define and access arrays of more than two dimensions by a simple extension of the following examples.
Defining a Field with Multiple Indexes
Statements:
DEFINE QUARTER-ROW W 2 N
DEFINE MONTH-COL W 2 N
DEFINE MONTHS W 120 A VALUE +
'JANUARY +
FEBRUARY +
MARCH +
492
CA Easytrieve® Report Generator 11.6
APRIL +
MAY +
JUNE +
JULY +
AUGUST +
SEPTEMBER +
OCTOBER +
NOVEMBER +
DECEMBER '
DEFINE MONTH MONTHS 10 A OCCURS (12) +
INDEX (MONTH-INDEX-1, MONTH-INDEX-2)
JOB INPUT NULL NAME MYPROG
QUARTER-ROW = 4
MONTH-COL = 2
MONTH-INDEX-1 = (QUARTER-ROW - 1) * 30
MONTH-INDEX-2 = (MONTH-COL - 1) * 10
DISPLAY MONTH
STOP
JANUARY FEBRUARY MARCH
(month-cell) (month-cell) (month-cell)
APRIL MAY JUNE <── Quarter-Row
JULY AUGUST SEPTEMBER <── Quarter-Row
OCTOBER NOVEMBER DECEMBER <── Quarter-Row
M M M
O O O
N N N
T T T
H H H
- - -
C C C
O O O
L L L
Result:
NOVEMBER
Redefining a Field, Giving Each Field Its Own Index
Statements:
DEFINE QUARTER-ROW W 2 N
DEFINE MONTH-COL W 2 N
DEFINE MONTHS W 120 A VALUE +
'JANUARY +
FEBRUARY +
493
CA Easytrieve® Report Generator 11.6
MARCH +
APRIL +
MAY +
JUNE +
JULY +
AUGUST +
SEPTEMBER +
OCTOBER +
NOVEMBER +
DECEMBER '
DEFINE MONTH MONTHS 10 A +
OCCURS (12)
DEFINE MONTH-ROW MONTH 30 A, +
OCCURS 4, INDEX (ROW-INDEX)
DEFINE MONTH-COLS MONTH-ROW 10 A, +
OCCURS 3, INDEX (COL-INDEX)
DEFINE MONTH-CELL MONTH-COLS 10 A
JOB INPUT NULL NAME MYPROG
QUARTER-ROW = 4
MONTH-COL = 2
ROW-INDEX = (QUARTER-ROW - 1) * 30
COL-INDEX = (MONTH-COL - 1) * 10
DISPLAY MONTH-CELL
STOP
JANUARY FEBRUARY MARCH
(month-cell) (month-cell) (month-cell)
APRIL MAY JUNE <── Quarter-Row
JULY AUGUST SEPTEMBER <── Quarter-Row
OCTOBER NOVEMBER DECEMBER <── Quarter-Row
M M M
O O O
N N N
T T T
H H H
- - -
C C C
O O O
L L L
S S S
Results:
NOVEMBER
494
CA Easytrieve® Report Generator 11.6
Subscripts
Subscripts are an alternative method available to select an individual element from an array. A subscript is an integer (or
a field containing an integer) that represents the occurrence number of the element within the array to be referenced. CA
Easytrieve® Report Generator computes the index value for you.
You can use subscripts with a field name in the following way:
[file-name:] field-name ( subscript ... )
The following restrictions apply to the use of subscripts:
• A subscript must be a field name or a literal. An arithmetic expression cannot be coded for a subscript.
• A subscript's value must be a positive integer, no greater than the value specified for the OCCURS parameter of the
DEFINE statement for field-name.
• You cannot subscript a field name used as a subscript.
• An indexed field cannot be used as a subscript.
Subscripting a One-Dimensional Array
A one-dimensional array is defined just as it would be if indexing were to be used. Referring to the Single Dimension
Array shown earlier, the following table illustrates the relationship between the array element and the corresponding array
element value:
ELEMENT is VALUE is
MONTH(1) JANUARY
MONTH(2) FEBRUARY
MONTH(3) MARCH
... ...
MONTH(12) DECEMBER
For this array the maximum value that can be specified for the occurrence number is 12.
Subscripting a Two-Dimensional Array
A two-dimensional array is somewhat more complicated. To define a two-dimensional array, you must define the length
and number of occurrences of each dimension. The following illustrates this:
DATA W 30 A VALUE 'AA+
BB+
CC+
...
00'
ROW DATA 10 A OCCURS 3
COLUMN ROW 2 A, OCCURS 5
ELEMENT COLUMN 2 A
This illustration defines a two-dimensional array (ELEMENT) with three rows and five columns, each occurrence of which
is an alphabetic field of two characters. The first dimension (ROW) is defined as having three occurrences. The second
dimension (COLUMN) is defined as having five occurrences. The length of the first dimension (ROW) must be the length
of the second dimension (COLUMN) times the number of occurrences of the second dimension (COLUMN).
495
CA Easytrieve® Report Generator 11.6
The following table illustrates the relationship between the array element and the corresponding array element value:
ELEMENT is VALUE is
ELEMENT(1,1) AA
ELEMENT(1,2) BB
ELEMENT(1,3) CC
ELEMENT(1,4) DD
ELEMENT(1,5) EE
ELEMENT(2,1) FF
... ...
ELEMENT(3,5) OO
Subscripting a Three-Dimensional Array
A three-dimensional array is a simple extension of a two-dimensional array. To define a three-dimensional array, you
define the length and number of occurrences of each dimension (as you did for a two-dimensional array). The only
difference is that you add the definition of a third dimension (MONTH-LET). This third dimension permits you to easily
select individual positions within a cell in the array.
The following illustrates the definition and use of a three-dimensional array:
Statements:
DEFINE QUARTER-ROW W 2 N
DEFINE MONTH-COL W 2 N
DEFINE MONTHS W 120 A VALUE +
'JANUARY +
FEBRUARY +
MARCH +
APRIL +
MAY +
JUNE +
JULY +
AUGUST +
SEPTEMBER +
OCTOBER +
NOVEMBER +
DECEMBER '
DEFINE MONTH-ROW MONTHS 30 A, +
OCCURS 4
DEFINE MONTH-COLS MONTH-ROW 10 A, +
OCCURS 3
DEFINE MONTH-LET MONTH-COLS 1 A, +
OCCURS 10
DEFINE MONTH-CELL MONTH-LET 1 A
JOB INPUT NULL NAME MYPROG
* THIS PROGRAM DISPLAYS THE 3RD
* LETTER OF THE MONTH IN THE 4TH
* ROW, 2ND COLUMN (THE V IN NOVEMBER)
496
CA Easytrieve® Report Generator 11.6
DISPLAY MONTH-CELL (4, 2, 3)
STOP
Results:
Segmented Data
One of the most common data structures is segmented data. Each record contains a fixed portion of data and multiple
occurrences of data segments. The actual number of occurrences is not known until execution time. In COBOL, these
structures are known as variable-length table definitions and are defined with an "occurs depending on" clause.
Defining Segmented Data
The following illustrates the field definitions necessary to describe a personnel record with a fixed area and variable
occurrences of dependent and salary history segments:
FILE MASTER SEQUENTIAL
*
* FIXED PORTION
*
EMP-ID 1 5 N
EMPNAME 6 20 A
NO-OF-DEPENDS 26 2 N
NO-OF-JOBS 28 2 N
*
* DEPENDENT SEGMENTS
*
DEPEND-INFO 30 26 A OCCURS 20
DEPEND-NAME 30 20 A INDEX DEPINDEX
DEPEND-BIRTH 50 6 N INDEX DEPINDEX
*
* SALARY HISTORY SEGMENTS
*
SALARY-HISTORY 30 16 A OCCURS 10
SALARY-AMOUNT 30 8 N 2 INDEX SALINDEX
SALARY-GRADE 38 2 N INDEX SALINDEX
SALARY-EFF-DATE 40 6 N INDEX SALINDEX
Because the starting location for each variable occurring segment is not known, the first position after the fixed portion is
used. Later, to access the data, the lengths of the preceding segments are added to the index to determine the starting
location of the next variable segment. The OCCURS parameter specifies the maximum number of occurrences for each
variable portion.
Accessing Segmented Data
The next example illustrates the index manipulation statements necessary to access the data contained in the file:
FILE MASTER SEQUENTIAL
*
* FIXED PORTION
*
EMP-ID 1 5 N
497
CA Easytrieve® Report Generator 11.6
EMPNAME 6 20 A
NO-OF-DEPENDS 26 2 N
NO-OF-JOBS 28 2 N
*
* DEPENDENT SEGMENTS
*
DEPEND-INFO 30 26 A OCCURS 20
DEPEND-NAME 30 20 A INDEX DEPINDEX
DEPEND-BIRTH 50 6 N INDEX DEPINDEX
*
* SALARY HISTORY SEGMENTS
*
SALARY-HISTORY 30 16 A OCCURS 10
SALARY-AMOUNT 30 8 N 2 INDEX SALINDEX
SALARY-GRADE 38 2 N INDEX SALINDEX
SALARY-EFF-DATE 40 6 N INDEX SALINDEX
WORK-CTR W 2 N
*
JOB INPUT MASTER NAME PERSONNEL-REPORTS
MOVE ZEROS TO DEPINDEX, WORK-CTR . * INITIALIZE DEPENDENT INDEX,CTR
DO WHILE WORK-CTR < NO-OF-DEPENDS. * PROCESS ALL DEPENDENT PORTIONS
PRINT DEPEND-REPORT
WORK-CTR = WORK-CTR + 1
DEPINDEX = DEPINDEX + 26
END-DO
*
MOVE ZERO TO WORK-CTR . * REINITIALIZE CTR
SALINDEX = (NO-OF-DEPENDS * 26) . * START OF SALARY HISTORY IS THE
* . * END OF THE DEPENDENT PORTION
DO WHILE WORK-CTR < NO-OF-JOBS . * PROCESS ALL SALARY PORTIONS
PRINT SALARY-REPORT
WORK-CTR = WORK-CTR + 1
SALINDEX = SALINDEX + 16
END-DO
*
REPORT DEPEND-REPORT LINESIZE 72 SPACE 1
TITLE 'DEPENDENT REPORT'
LINE EMP-ID EMPNAME DEPEND-NAME DEPEND-BIRTHDATE
*
REPORT SALARY-REPORT LINESIZE 72 SPACE 1
TITLE 'SALARY REPORT'
LINE EMP-ID EMPNAME SALARY-AMOUNT SALARY-GRADE SALARY-EFF-DATE
Data Strings
Evaluating strings of data is another common index process. The following illustrates a technique for taking names from
the input record, reversing them, and then printing them. The results of this program are:
REVERSED-NAME DATA-NAME
GLORIA WIMN WIMN,GLORIA
NANCY BERG BERG,NANCY
GEORGE CORNING CORNING,GEORGE
498
CA Easytrieve® Report Generator 11.6
MARY NAGLE NAGLE,MARY
The program code is as follows:
FILE NAMES CARD
DATA-NAME 1 20 A
SCAN-NAME DATA-NAME 1 A INDEX SUB1
REVERSED-NAME W 20 A
SCAN-REVERSED REVERSED-NAME 1 A INDEX SUB2
COUNTER W 2 P 0
SAVE-COUNT W 2 P 0
JOB INPUT NAMES
*
* INITIALIZE REVERSED NAME, SUB1, SUB2, AND COUNTER FIELDS
*
MOVE SPACES TO REVERSED-NAME
MOVE ZEROS TO SUB1, SUB2, COUNTER
*
* FIND LENGTH OF LAST NAME
*
DO WHILE SCAN-NAME NQ ','
COUNTER = COUNTER + 1
SUB1 = SUB1 + 1
END-DO
SAVE-COUNT = COUNTER . *SAVE LENGTH OF LAST NAME
COUNTER = 0 . *RESET COUNTER
SUB1 = SUB1 + 1 . *BUMP SUB1 PAST THE COMMA
*
* FIND FIRST NAME AND MOVE TO REVERSED NAME
*
DO WHILE SCAN-NAME NQ ' ' +
AND COUNTER LE 20 - SAVE-COUNT - 1
SCAN-REVERSED = SCAN-NAME
COUNTER = COUNTER + 1
SUB2 = SUB2 + 1
SUB1 = SUB1 + 1
END-DO
COUNTER = 0 . *RESET COUNTER
SUB1 = 0 . *RESET TO BEGINNING OF LAST NAME
SUB2 = SUB2 + 1 . *BUMP SO SPACE IS BETWEEN FIRST AND
* *LAST NAMES
* MOVE LAST NAME TO REVERSED NAME FIELD
*
DO WHILE COUNTER LQ SAVE-COUNT - 1
SCAN-REVERSED = SCAN-NAME
COUNTER = COUNTER + 1
SUB1 = SUB1 + 1
SUB2 = SUB2 + 1
END-DO
PRINT NAMES-REPORT
REPORT NAMES-REPORT LINESIZE 78
TITLE 1 'EXAMPLE OF HOW TO REVERSE NAMES'
499
CA Easytrieve® Report Generator 11.6
TITLE 2 'INPUT FIELD FORMAT IS:'
TITLE 3 'LAST-NAME,FIRST-NAME'
LINE REVERSED-NAME DATA-NAME
END
Inter-Program Linkage
The facilities of CA Easytrieve® Report Generator provide all of the functions necessary to perform standard input/output,
data examination, and data manipulation.
The LINK and TRANSFER statements can be used to invoke other CA Easytrieve® Report Generator programs. You can
also invoke subprograms written in other programming languages through the CALL, LINK, and TRANSFER statements,
and the EXIT parameter of the FILE statement.
This article contains the following information:
Using the CALL statement or the FILE EXIT parameter to invoke another CA Easytrieve® Report Generator program is
not supported and will yield unpredictable results. Invoking a CA Easytrieve® Report Generator program using a CALL
from a non-CA Easytrieve® Report Generator program is also unsupported and will produce unpredictable results. Control
can be safely transferred from a parent program to a CA Easytrieve program (as the child) using program LINK requests.
LINK request syntax varies depending on the calling program language.
• The FILE EXIT and CALL statements enable you to invoke subprograms written in other programming languages. All
discussions of the CALL statement also apply to FILE EXITs. (FILE EXITs are CALLs that are controlled automatically
by CA Easytrieve® Report Generator.)
• The LINK statement allows you to transfer control from the current program (parent) to another program (child) and
then return control to the parent program.
• The TRANSFER statement allows you to transfer execution to a target program without returning to the invoking
program.
CALL Statement on the Mainframe
The CALL statement on the mainframe provides a means to invoke subprograms written in other programming languages.
The following topics discuss the mainframe techniques used with the CALL statement:
• Program linking
• Storage management
• Linkage (register usage) conventions
• Parameter list
• Error condition handling
Program Linking
Called subprograms can be statically or dynamically linked with the CA Easytrieve® Report Generator object module. You
must declare which type of linkage you want to use in your CA Easytrieve® Report Generator program. To do this, use
one of the following on the PARM statement:
• The CALL parameter; for example:
PARM CALL (STATIC)
• The DECLARE statement; for example:
DECLARE INTCALC PROGRAM DYNAMIC
500
CA Easytrieve® Report Generator 11.6
The way that the called program is bound is determined by the following, in order:
1. If the program was declared on a DECLARE statement, the STATIC or DYNAMIC keyword on the DECLARE
statement determines how it is bound.
2. If specified, the CALL parameter on the PARM statement supplies the default for all called programs in your CA
Easytrieve® Report Generator program.
3. The default is determined by the environment. The default on the mainframe is DYNAMIC. The default on UNIX is
STATIC.
In CICS, all dynamic programs are loaded by executing the CICS LOAD command. The LOAD command dynamically
places the program in storage and returns the program's entry point to CA Easytrieve® Report Generator.
Each time the CALL statement is executed, CA Easytrieve® Report Generator determines whether or not the program has
been loaded. If the program has not been loaded, CA Easytrieve® Report Generator executes a CICS LOAD command to
load it. Once loaded, the program remains loaded until it reaches one of the following points:
• The end of the first activity that references the program -- If the current activity (the child activity) was invoked with an
EXECUTE statement from another activity (the parent activity), and if both the child and parent activity reference the
program, the program is not deleted until the parent activity terminates. The termination of the child activity does not
cause the program to be deleted.
• CA Easytrieve® Report Generator performs the next screen input/output operation -- However, if you specified
COMMIT NOTERMINAL on the SCREEN statement or the calling CA Easytrieve® Report Generator program is
executing conversationally, CA Easytrieve® Report Generator does not delete the program.
In MVS, all dynamic programs are loaded by invoking the LOAD function of the operating system, or by invoking the
CEELOAD function when ENVIRONMENT COBOL is used. The LOAD function dynamically places the program in
storage and returns the program's entry point to CA Easytrieve® Report Generator.
CA Easytrieve® Report Generator loads the program as part of the initialization of the first activity that references the
program. If the current activity (the child activity) was invoked with an EXECUTE statement from another activity (the
parent activity), and if both the child and parent activity reference the program, then CA Easytrieve® Report Generator
loads the program during the initialization of the parent activity. In addition, CA Easytrieve® Report Generator does not
delete the program until the termination of the parent activity. Neither the initialization nor the termination of the child
activity has any effect on the program's status.
Storage Management
In VSE, the author of programs in other languages is responsible for managing required storage. If additional storage is
needed (for example, to LOAD another program), you cannot use DOS COMREG facilities. All storage must be:
• Within the originally loaded program
• Obtained using GETVIS
• Uniquely controlled within the STORMAX area
Linkage (Register Usage) Conventions
When CA Easytrieve® Report Generator invokes a subprogram written in another programming language, it adheres to
standard IBM register management conventions. The called subprogram must honor these conventions:
Register Usage
REGISTER 1 Address of the parameter list
REGISTER 13 Address of an 18 fullword register save area
REGISTER 14 Address of where to return to within CA Easytrieve® Report
Generator
REGISTER 15 Address of the entry point in the subprogram
501
CA Easytrieve® Report Generator 11.6
The subprogram must save the CA Easytrieve® Report Generator registers in the save area addressed by REGISTER
13 and must restore them prior to returning using REGISTER 14. The 18-fullword register save area provided by CA
Easytrieve® Report Generator must be maintained as illustrated in the following table:
Save Area Usage
WORD 1 Reserved
WORD 2 Set by CA Easytrieve® Report Generator to the address of the
save area for the internal routine prior to the one issuing the
subprogram call
WORD 3 Set by the subprogram to the address of the save area within the
subprogram
WORD 4 to WORD 18 Set by the subprogram to values contained in CA Easytrieve®
Report Generator REGISTERS 4 to 12 upon entry to the
subprogram
Assembler Subprogram Linkage
Assembler language subprograms present no linkage problems. The following shows the instructions necessary to
successfully control assembler language subprogram linkage:
ASMPGM CSECT
STM 14,12,12(13) save registers 14 through 12
LR 11,15 set base register
USING ASMPGM,11 assign base register
LA 14,0(0,13) address of <easy> save area
LA 13,MYSAVE address of subprogram save area
ST 13,8(0,14) chain forward
ST 14,MYSAVE+4 chain backward
LR 10,1 save parameter list address
...
...
...
RETURN L 13,4(0,13) address of <easy> save area
LM 14,12,12(13) restore <easy> registers
MVI 8(13),X'FF' indicate unused save area
SR 15,15 set zero return code
BR 14 return to <easy>
...
MYSAVE DC 18A(0) 18 fullword save area
...
...
COBOL Subprogram Linkage
Note: COBOL subprograms are supported only in environments in which IBM supports a COBOL program invocation by
an Assembler program. CICS does not support such an invocation.
COBOL subprogram linkage is dependent upon the operating system (z/OS or z/VSE) and the COBOL parameters that
were in effect when the COBOL subprogram was compiled. For specific details about these parameters and linkage
conventions, see the COBOL Programmer's Guide.
The following shows typical COBOL instructions necessary to control subprogram linkage:
502
CA Easytrieve® Report Generator 11.6
...
LINKAGE SECTION.
01 PARAMETER-1.
...
01 PARAMETER-2.
...
01 PARAMETER-N.
...
PROCEDURE DIVISION USING PARAMETER-1,
PARAMETER-2,
...
PARAMETER-N.
...
...
GOBACK
...
ENVIRON Option and ENVIRONMENT Parameter
A COBOL environment is set for PROGRAM activities by coding the ENVIRONMENT COBOL parameter of the
PROGRAM statement to establish the proper LE and COBOL environment for subprograms only and sub-activities called
in that PROGRAM activity. The default for PROGRAM activities is ENVIRONMENT NONE. No default is taken from the
PARM statement or the options table.
WARNING
For performance considerations, we recommend that you set the ENVIRONMENT option to COBOL if many CA
Easytrieve® Report Generator programs are calling Language Environment subprograms. The option should be
set to NONE if most CALLs are made to non-Language Environment subprograms.
A COBOL environment is set for JOB activities in one of the following ways:
• Coding the ENVIRONMENT COBOL parameter of the JOB statement. This establishes the proper LE and COBOL
environment for subprograms called in that JOB activity only.
• Coding the ENVIRONMENT COBOL subparameter of the PARM statement. This establishes the proper LE and
COBOL environment for all subprograms called in all JOB activities of the CA Easytrieve® Report Generator program.
• Setting the ENVIRON=COBOL option of the system Options Table when CA Easytrieve® Report Generator is installed.
This establishes the proper LE and COBOL environment for all subprograms called in all JOB activities for all CA
Easytrieve® Report Generator programs. This option is set into the program at compile time. Changing the option
value will not affect link-edited CA Easytrieve® Report Generator application programs.
• Coding the ENVIRONMENT COBOL parameter of the PROGRAM statement, and that activity invokes the JOB
activity. The COBOL ENVIRONMENT established by the PROGRAM activity will be inherited by the JOB activity.
COBOL ENVIRONMENT Operation
When the ENVIRONMENT COBOL parameter or the ENVIRON=COBOL option is in effect, this alone will not cause the
COBOL ENVIRONMENT to be established. The ENVIRONMENT will not be established unless the activity for which
ENVIRONMENT is specified contains a CALL statement, (in PROGRAM or JOB activities), or an EXECUTE statement,
(in PROGRAM activities). However, if no CALL or EXECUTE is present, the ENVIRONMENT will still be established if the
CA Easytrieve® Report Generator program contains a FILE statement that specifies the EXIT parameter. If none of these
conditions exist (no CALL, EXECUTE, or FILE EXIT), the ENVIRONMENT will not be started even if ENVIRONMENT
COBOL is specified in the program. In that case, no ENVIRONMENT is needed, and that overhead is saved.
When ENVIRONMENT COBOL is in effect for an activity, the ENVIRONMENT is started at the start of the activity, and it is
terminated at the end of the activity.
503
CA Easytrieve® Report Generator 11.6
If a PROGRAM activity starts the COBOL ENVIRONMENT, and then executes a JOB activity, that ENVIRONMENT will
remain active during the execution of the JOB activity. It will not be started and stopped for the JOB activity. Even if the
JOB activity specifies ENVIRONMENT NONE, the ENVIRONMENT started in the PROGRAM activity will remain active
during the JOB activity execution. The COBOL ENVIRONMENT started in the PROGRAM activity will remain active
during all JOB activities EXECUTEd by that PROGRAM activity.
If ENVIRONMENT NONE is specified for the PROGRAM activity, each executed JOB activity for which ENVIRONMENT
COBOL is specified, will get the COBOL ENVIRONMENT started and terminated as the activity starts and terminates, (if
the CALL and FILE EXIT requirements are met).
If no PROGRAM activity is coded, each JOB activity for which ENVIRONMENT COBOL is specified, will get the COBOL
ENVIRONMENT started and terminated as the activity starts and terminates, (if the CALL and FILE EXIT requirements
are met).
When the COBOL ENVIRONMENT is active, the CA Easytrieve® Report Generator runtime becomes the LE Main
routine. Any programs called by the CA Easytrieve® Report Generator application program are LE subprograms. This lets
subprograms act properly as called subroutines without using the ENDJOB compiler option.
COBOL Environment Rules
The rules for using ENVIRONMENT COBOL are as follows:
• The parameter functions for CALLed subprograms, FILE EXITs; it functions in z/OS.
• All COBOL programs in the run unit must be compiled with the RESIDENT and REENTRANT compiler options. This
ensures that all COBOL modules access the same copy of the global data area and optimum performance is obtained.
• FILE EXITs and subprograms can have an AMODE of 24, 31, or ANY and an RMODE of 24 or ANY. If a 24-bit
subprogram is being called from a CA Easytrieve® Report Generator program when ENVIRONMENT(COBOL) is set,
these LE runtime options must also be set: ALL31=(OFF),STACK=(,,BELOW). For information regarding the setting of
LE runtime option overrides for CA Easytrieve® Report Generator, please see Installing.
• When the COBOL subprogram issues a GOBACK statement, control returns to the CA Easytrieve® Report Generator
statement following the CALL statement.
• When the COBOL subprogram executes a STOP RUN statement, the statement causes the current CA Easytrieve®
Report Generator activity to terminate. When an activity terminates due to a STOP RUN, any spooled reports currently
being printed are terminated. Any unprinted spooled reports are purged, therefore, programs that use FORTRAN
service routines cannot be called.
• Support for Language Environment (LE) takes place through the ENVIRONMENT COBOL parameter.
• The RENT Binder option must also be specified for called COBOL programs compiled with the RENT compiler option.
PL/I Subprogram Linkage
CA Easytrieve® Report Generator supports only DYNAMIC calls to PL/I subprograms. Linkage with PL/I is unique due
to its non-standard conventions. It requires the use of the PROC OPTIONS(COBOL) parameter. See the IBM PL/I
programming guide for details on the linkage of PL/I subprograms with other programming languages.
C Subprogram Linkage
CA Easytrieve® Report Generator supports both DYNAMIC and STATIC calls to C subprograms. As with COBOL, C
subprograms may be invoked through the CALL statement and as FILE EXITs, and they may be AMODE 24 or 31. C
subprograms are invoked by CA Easytrieve® Report Generator using the same IBM standard calling conventions used for
invoking COBOL programs.
The C subprogram coding required to process incoming parameters depends on whether the C subprogram is being
invoked as DYNAMIC or STATIC. The following sections show examples of both.
To Receive Parameters When C Subprogram is DYNAMIC
504
CA Easytrieve® Report Generator 11.6
CA Easytrieve® Report Generator main program:
PARM ENVIRONMENT(COBOL) LINK(EZTPGM R)
DECLARE CPROG PROGRAM DYNAMIC
DEFINE PARM1 W 4 B VALUE 1111
DEFINE PARM2 W 3 A VALUE 'ABC'
*
JOB INPUT NULL
DISPLAY '*** BEFORE CPROG CALL ***'
DISPLAY 'PARM1 IS >>-à ' PARM1
DISPLAY 'PARM2 IS >>-à ' PARM2
CALL CPROG USING (PARM1 PARM2)
DISPLAY '*** AFTER CPROG CALL ***'
DISPLAY 'PARM1 IS >>-à ' PARM1
DISPLAY 'PARM2 IS >>-à ' PARM2
STOP
C subprogram (link-edited as CPROG load module):
#pragma runopts (plist(os)) /* required MVS */
#include <csp.h> /* contains __csplist macro */
void main(void)
{
int * parm1_ptr ;
char * parm2_ptr ;
/* Retrieve the EZT program parameters */
parm1_ptr = (int *) __csplist[ 0 ]; /* 1st parm */
parm2_ptr = (char *) __csplist[ 1 ]; /* 2nd parm */
/* Modify the parameter values */
*parm1_ptr = 2222;
*parm2_ptr = 'Z';
}
To Receive Parameters When C Subprogram is STATIC
CA Easytrieve® Report Generator main program:
This program is exactly the same as the previous main program example except for the following statement:
. . .
DECLARE CPROG PROGRAM STATIC
. . .
C subprogram (statically link-edited with CA Easytrieve® Report Generator program EZTPGM):
#pragma runopts(plist(os)) /* required MVS */
extern "COBOL"
void CPROG(int parm1, char parm2[3])
{
/* Modify the parameter values */
parm1 = 2222;
parm2[0] = 'Z';
}
505
CA Easytrieve® Report Generator 11.6
Parameter Lists
The parameter list for both input/output and CALL exits (pointed to by register 1) passes information to the subprogram.
Each entry in this contiguous group of fullwords identifies one parameter. The end of the list is indicated by the high-order
bit of the high-order byte of the last entry being set to a one.
Parameter List Format
Figure 40: Parameter List Format
The parameter lists passed to subprograms for EXIT (FILE) and CALL are quite similar. In fact, the list for CALL is
identical to that associated with the USING subparameter of EXIT. The only difference is that EXIT always passes at least
two parameters.
Note: If multiple fields are coded on the USING subparameter, and storage areas overlap, results are unpredictable.
Exit Parameter List
You can use the EXIT parameter of the FILE statement to invoke subprograms written in other programming languages
for input/output related events. Code the name of these subprograms on the EXIT parameter of the FILE statement in the
library of your program.
506
CA Easytrieve® Report Generator 11.6
Figure 41: Exit Parameter List
For input/output exits, work area address and the control code address are required parameters. The control code is a
fullword used to indicate the function to be performed by the exit. For instance:
Control Code
Value Function
00000000 input request
00000004 output request
00000008 file close request, or end-of-input (set by input exit subprogram)
For MODIFY exits (subparameter of the FILE statement), the required two parameters are record area address and work
area address because the exit receives all records after input and before output.
507
CA Easytrieve® Report Generator 11.6
Figure 42: MODIFY Exits Parameter List
Parameters coded on the optional USING subparameter of EXIT are appended to the standard two parameters. The
following example shows input/output and MODIFY subprogram parameter list examples:
508
CA Easytrieve® Report Generator 11.6
Figure 43: Examples of Input, Output and MODIFY Subprogram Parameter List
Calling an AMODE(24) Subprogram
When the subprogram being called is link-edited as AMODE(24), and if any parameters are being passed to that program,
those parameters must reside in memory that is located below the 16meg line. Memory location can be controlled at the
installation level and at the program level.
Installation level:
To force all storage below the 16meg line for all CA Easytrieve® Report Generator programs, set the AMODE31
Installation Option to N. For more information see Configure Your System.
509
CA Easytrieve® Report Generator 11.6
Program level:
To force storage below the 16meg line for a specific CA Easytrieve® Report Generator program, you must specify the
CALL(AMODE24) parameter in the PARM statement in the CA Easytrieve® Report Generator program.
Error Condition Handling
Program errors that occur in subprogram exits cause the abnormal termination of CA Easytrieve® Report Generator
programs. Because these errors are occasionally difficult to analyze within the complex environment of CA Easytrieve®
Report Generator, exits should be tested first with simulation.
CALL Statement in UNIX, Linux for zSeries, and Windows
The CALL statement in UNIX, Linux for zSeries, and Windows provides a means to invoke subprograms written in other
programming languages. The following topics discuss the techniques used with the CALL statement:
• Program linking
• Storage management
• Linkage conventions
• Error condition handling
Storage Management
Called subprograms should use the malloc and free functions to allocate and free storage. The subprogram should free
any storage it has allocated.
Linkage Conventions
The CALL statement can be used to call programs that conform to the C calling conventions for the platform on which you
are running CA Easytrieve® Report Generator. For more information, see Using.
FILE EXIT Linkage
You can use the EXIT parameter of the FILE statement to invoke subprograms written in other programming languages
for input/output related events. There are two types of exits you can code:
• Standard
• Using the MODIFY subparameter
Standard Exits
A standard exit should perform its own I/O. A standard exit function should look like this:
unsigned long YourStandardExit(
long eOperation,
void * pRecord,
unsigned long * pcbRecord,
void * pKey,
unsigned long * pcbKey,
P_EZEXIT_FCB pFCB,
void * * pExitArgList
);
where the meaning of parameters is as follows:
• eOperation
510
CA Easytrieve® Report Generator 11.6
Has a value as shown in the following list of constants. These constants enumerate the possible values for eOperation
and their meaning:
#define IO_OPEN 0 /* Open the file */
#define IO_GET_NEXT_NH 4 /* GET NEXT NOHOLD */
#define IO_GET_NEXT_H 6 /* GET NEXT HOLD */
#define IO_GET_PRIOR_NH 10 /* GET PRIOR NOHOLD */
#define IO_GET_PRIOR_H 12 /* GET PRIOR HOLD */
#define IO_PUT 14 /* PUT */
#define IO_READ_NH 18 /* READ NOHOLD */
#define IO_READ_H 20 /* READ HOLD */
#define IO_WRITE_ADD 22 /* WRITE ADD */
#define IO_WRITE_UPD 24 /* WRITE UPDATE */
#define IO_WRITE_DEL 26 /* WRITE DELETE */
#define IO_POINT_FWD 28 /* POINT forward */
#define IO_RELEASE 30 /* RELEASE */
#define IO_CLOSE 42 /* CLOSE */
#define IO_DISPLAY 48 /* DISPLAY */
#define IO_SYNCPOINT 54 /* SYNCPOINT */
#define IO_POINT_BWD 56 /* POINT backward */
• pRecord
Is the pointer to the record buffer. On input operations, your exit places data into this buffer from the file. On output,
your exit writes the data from the buffer to the file.
• pcbRecord
Is the pointer to the length of the record currently in the buffer. On input operations, your exit must place the size of the
record at this location.
• pKey
Is the pointer to the key. This field is valid only for operations that require a key.
• pcbKey
Is the pointer to the length of the key.
• pFCB
Is the pointer to the EXIT_FCB. The EXIT_FCB contains information describing the file. The EXIT_FCB is described
after the description of the parameters.
• pExitArgList
Is the pointer to the array of pointers to the fields in the USING list of the EXIT phrase. The pointers are ordered as the
fields in the USING list are ordered.
• Return Value
The following list of constants enumerate the valid return values and the meanings:
#define FC_NORMAL 0 /* The operation completed */
/* normally. */
#define FC_ENDFILE 4 /* The operation attempted to */
/* position the file past the */
/* last record in the file */
#define FC_RDUPREC 8 /* The key of the record just */
/* read matches the key of the */
/* next record in the file */
#define FC_WDUPREC 12 /* The operation attempted to */
/* insert a record whose key */
/* matches a record already in */
511
CA Easytrieve® Report Generator 11.6
/* the file */
#define FC_NRFOUND 16 /* The key specified for the */
/* operation does not match */
/* the key of any record in */
/* the file */
#define FC_LOCKED 20 /* The operation attempted to */
/* retrieve a record that is */
/* locked by another user */
#define FC_IOERROR 24 /* The operation failed for some */
/* reason other than one of */
/* those given above */
The ANCHOR is a control block that the exit might want to allocate (it is not required). Its purpose is to hold information
that the exit needs from one invocation of the exit to the next. The ANCHOR is chained off the EXIT_FCB (which follows).
Your exit is responsible for the creation, maintenance, and destruction of this area.
typedef struct ANCHOR {
FILE * pFile;
/* More data could be placed here. Since there is no more data
* in this example, a better solution would be to use the pAnchor
* field in the EXIT_FCB as the file pointer.
*/
} ANCHOR, * P_ANCHOR;
The EXIT_FCB is a control block that is passed to the exit each time the exit is called. The same instance of the
EXIT_FCB is passed from the time the file is opened to the time the file is closed for each operation on the file.
Hence, if your exit allocates its own control block (like the ANCHOR, shown below), its address can be placed as the first
item in the EXIT_FCB and retrieved from the same place with each invocation of the exit. Remember to deallocate the
control block when the file is closed.
CA Easytrieve® Report Generator creates, maintains, and destroys this control block. Your exit should restrict itself solely
to changing the pAnchor field.
typedef struct EZEXIT_FCB {
P_ANCHOR pAnchor; /* for use by the Exit */
char *pszFileName; /* Pointer to the file name */
char *pszPathName; /* Pointer to the Path */
unsigned long cbRecordSize; /* Logical record length */
unsigned long cbBufAreaLen; /* Length of the buffer area */
void *pBuffer; /* Pointer to the file buffer */
char szProcessMode[ 4 ]; /* File Access Mode */
unsigned char eRecordFormat; /* Record format */
# define RF_NONE 0 /* Record format not specified */
# define RF_FIXED 1 /* F or FB specified */
# define RF_VARIABLE 2 /* V, VB, or VSB specified */
# define RF_UNDEFINED 3 /* U specified */
unsigned char eFileOrg; /* File type */
# define FO_NONE 0 /* File type not specified */
# define FO_SEQUENTIAL 1 /* SEQUENTIAL */
# define FO_INDEXED 2 /* INDEXED */
# define FO_RELATIVE 3 /* RELATIVE */
unsigned char fMiscFlags0; /* Miscellaneous flags */
512
CA Easytrieve® Report Generator 11.6
#if defined(LSB)
/* For architectures with the Least Significant Byte First
* such as the INTEL 80x86 chips.
*/
# define FM_DEFER 0x01 /* DEFER */
# define FM_ASA 0x02 /* ASA */
# define FM_CREATE 0x04 /* CREATE */
# define FM_RESET 0x08 /* CREATE RESET */
# define FM_UPDATE 0x20 /* UPDATE */
# define FM_NOVERIFY 0x40 /* NOVERIFY */
# define FM_MODIFY 0x80 /* EXIT with MODIFY */
#elif defined(MSB)
/* For architectures with the Most Significant Byte First
* such as the HP PA Risc (HP 9000) chips.
*/
# define FM_DEFER 0x80 /* DEFER */
# define FM_ASA 0x40 /* ASA */
# define FM_CREATE 0x20 /* CREATE */
# define FM_RESET 0x10 /* CREATE RESET */
# define FM_UPDATE 0x04 /* UPDATE */
# define FM_NOVERIFY 0x02 /* NOVERIFY */
# define FM_MODIFY 0x01 /* EXIT with MODIFY */
# endif
unsigned char Reserved1; /* Reserved for future expansion */
void * pReserved2;
void * pReserved3;
void * pReserved4;
} EZEXIT_FCB, * P_EZEXIT_FCB;
Note: The Installation Media contains an example of a standard exit program, VRTXTEXT.c. Ask your system
administrator where that program can be found.
MODIFY File Exit
If you code the MODIFY subparameter on the FILE statement, CA Easytrieve® Report Generator performs the I/O.
Your exit should examine the record and convert it into the correct form. On an input operation, CA Easytrieve® Report
Generator reads the record, then passes it to your MODIFY file exit to be reformatted. On an output operation, CA
Easytrieve® Report Generator passes the record to your exit to be reformatted. When your exit finishes, CA Easytrieve®
Report Generator writes the reformatted record to the file.
The prototype for your MODIFY file exit should look like this:
unsigned long YRMDEXIT(
void * pRecordArea,
void * pWorkArea,
unsigned long cbRecordLength,
unsigned long * pcbWorkAreaLength,
void * * pExitArgList
);
where:
• pRecord
Points to the record buffer. The record to be reformatted is in this buffer.
• pWorkArea
513
CA Easytrieve® Report Generator 11.6
Points to a buffer. The record from pRecord must be reformatted and placed in this buffer.
• cbRecord
This is the length of the record at pRecord.
• pcbWorkArea
Points to the length of pWorkArea's buffer. When your exit has placed the reformatted in the buffer, it must place the
length of the reformatted record at this field.
• pExitArgList
Is the pointer to the array of pointers to the fields in the USING list of the EXIT phrase. The pointers are ordered as the
fields in the USING list are ordered.
• Return Value
This exit uses the same values as were defined for the standard file exit.
Note: The Installation Media contains an example of a MODIFY exit program, YRMDEXIT.c. Ask your system
administrator where that program can be found.
If your exit processes variable length records, the RECORD-LENGTH field of the file should be in the USING list. Your exit
must place the correct value in the USING list.
If your exit handles both input and output operations, you should place a field in the USING list that can tell your exit what
type of operation the exit must perform.
Error Condition Handling
Program errors that occur in subprograms cause the abnormal termination of CA Easytrieve® Report Generator programs.
Because these errors can be difficult to analyze in the complex environment of CA Easytrieve® Report Generator, you
should test subprograms before using them in CA Easytrieve® Report Generator.
LINK Statement
The LINK statement is used to invoke another program and then return execution to the statement following the LINK
statement in the original (invoking) program. The program invoked can be written in any language that is supported by the
operating system in which the program is executing (including CA Easytrieve® Report Generator).
LINK Statement and CALL Statement
The LINK statement differs from the CALL statement in the following ways:
• LINK creates a new program execution environment that bears a child relationship to the program issuing the LINK
command (the parent program). A called program executes in the same execution environment as the program issuing
the CALL command.
• On the mainframe, a called program uses the same linkage conventions in all execution environments; LINK uses the
linkage conventions of the operating system in which the program is executing.
CA Technologies Product References
The child program can issue any command supported by the operating system. In a CICS environment, the program can
issue terminal I/O or display reports, but only in a fully conversational mode.
Commands issued by a child program, such as SYNCPOINT, and I/O commands, can affect the operating environment
of the parent program. CA Easytrieve® Report Generator does not guarantee that applications using LINK execute
identically in all execution environments. If portability between operating systems is required by an application, it is your
responsibility to code the application in such a way that portability is assured.
514
CA Easytrieve® Report Generator 11.6
USING Parameter
A single parameter can be passed to the child program by specifying the USING parameter. The parameter is passed
to the child program by value; that is, the parent program passes a copy of the value of the field or literal to the child
program. The child program cannot directly modify the value of the field or literal. You specify the field to receive the
parameter with the USING parameter on the PROGRAM statement in the child program.
Giving Parameter
You can allow the parent program to accept a return parameter from the child program by specifying the GIVING
parameter. You specify the field to be returned in the GIVING parameter of the PROGRAM statement in the child program.
CA Easytrieve® Report Generator returns a value to the parent program by writing the return value into the same
parameter area that was used by CA Easytrieve® Report Generator to pass the USING parameter to the child program.
When the child program terminates, the parameter is copied from the parameter area to the variable specified in the
GIVING parameter of the parent program. Because a single parameter area is used for communications in both directions,
CA Easytrieve® Report Generator determines the size of the parameter area by the larger of the fields specified on
the USING and GIVING parameters. If the child program copies a return parameter into the parameter area with
the PROGRAM GIVING parameter, but there is no GIVING parameter specified in the parent program, the returned
parameter is ignored without any error indication.
Operating System Implementation
The LINK statement is implemented as listed below:
Operating System Command Parameters Passed By
CICS EXEC CICS LINK CICS communication area
TSO MVS LINK SVC 6 Standard MVS/TSO linkage conventions
CMS CMS LINK SVC 6 Standard CMS linkage conventions
Non-mainframe (UNIX, Linux for zSeries, system ("routine_name using_data")
Windows)
Note: When linking to an OS/VS COBOL program in TSO or CMS, the COBOL program must be compiled with the
NORES compile option. Also, you cannot LINK and CALL an OS/VS COBOL program in the same activity.
Note: In CICS, the TRANSFER statement is more efficient than the LINK statement. In TSO and CMS, the opposite is
true.
Non-mainframe
The GIVING parameter on the LINK and PROGRAM statements is ignored in non-mainframe environments. The data
from the USING parameter must be acceptable in the shell you are running.
The program being linked to can be any valid shell program or command. For example, you can use LINK 'cls' (in
Windows) or LINK 'clear' (in UNIX) to clear the terminal or console screen for future DISPLAY statements. The following
LINK statement example executes the dir Windows command and redirects the output to a file for future processing:
LINK 'dir' USING '> dir.lst'
The LINK statement, combined with the rest of the CA Easytrieve® Report Generator language, provides powerful
scripting possibilities.
515
CA Easytrieve® Report Generator 11.6
TRANSFER Statement
The TRANSFER statement is used to transfer execution to a target program without returning to the invoking program.
The target program can be written in any language that is supported by the operating system in which the program is
executing.
The TRANSFER statement completely terminates the current CA Easytrieve® Report Generator program and invokes
a target program using the linkage conventions of the operating system in which the program is executing. The target
program inherits the execution environment of the program issuing the TRANSFER command.
Commands Issued by the Target Program
The target program can issue any command supported by the operating system. In a CICS environment, the program
can issue terminal I/O or display reports in a pseudo-conversational mode only if the program issuing the TRANSFER
command can operate pseudo-conversationally.
Complete termination of the current CA Easytrieve® Report Generator program does not imply the termination of the
current logical unit of work. Although CA Easytrieve® Report Generator attempts to terminate the current program (for
example, close files and complete reports), it does not necessarily terminate all activities performed by the operating
system for the CA Easytrieve® Report Generator program.
Commands issued by a child program, such as SYNCPOINT, and I/O commands can affect the operating environment of
the parent program. CA Easytrieve® Report Generator does not guarantee that applications using TRANSFER execute
identically in all execution environments. If portability between operating systems is required by an application, it is your
responsibility to code the application in such a way that portability is assured.
USING Parameter
A single parameter can be passed to the target program by specifying the USING parameter. The parameter is passed
to the target program by value, that is, the invoking program passes a copy of the value of the field or literal to the target
program. The target program cannot directly modify the value of the field or literal. You specify the field to receive the
parameter with the USING parameter on the PROGRAM statement in the target program.
Operating System Implementations
The TRANSFER statement is implemented as follows:
Operating System Command Parameters Passed By
CICS EXEC CICS XCTL CICS communication area
TSO MVS XCTL SVC 7 Standard MVS/TSO linkage conventions
CMS CMS XCTL SVC 7 andard CMS linkage conventions
Non-mainframe (UNIX, Linux for zSeries, execl ("/bin/sh", "routine_name using_data",
Windows) NULL)
Note: When running pseudo-conversationally in CICS, you must specify the TRANSID parameter on the PARM statement
in the target program. TRANSID specifies the CICS transaction ID that is invoked when the terminal user presses an
attention key following the program's termination for a pseudo-conversation. The transaction ID of the target program
must be defined in the PCT.
Note: In CICS, the TRANSFER statement is more efficient than the LINK statement. In TSO, CICS, and CMS, the
opposite is true.
Non-mainframe
If you coded a SHELL environment variable, CA Easytrieve® Report Generator uses that path instead of /bin/sh. The
data from the USING parameter must be acceptable in the shell you are running. The program being transferred to can
be any valid shell program or command. Used in this manner, a program could drive the execution of other programs.
516
CA Easytrieve® Report Generator 11.6
The TRANSFER statement, combined with the rest of the CA Easytrieve® Report Generator language, provides powerful
scripting possibilities.
Code Efficient Programs
This section provides coding tips to help you write more efficient CA Easytrieve® Report Generator programs.
Contents
Data Usage
CA Easytrieve® Report Generator normally generates the most efficient code when performing operations on binary
fields (data type B) on the mainframe. CA Easytrieve® Report Generator performs binary or integer arithmetic whenever
possible. When this is impractical due to the size of intermediate results, CA Easytrieve® Report Generator uses packed
decimal.
When you code packed decimal fields, if you use 15 or fewer digits, CA Easytrieve® Report Generator generates inline
program code. On the mainframe, if you use more than 15 digits, CA Easytrieve® Report Generator uses runtime library
routines for multiplication and division. The use of runtime library routines results in a longer execution time of your
program.
Avoid the use of zoned numeric fields for heavily used computations in your program.
Use indexes, rather than subscripts, in array processing to produce more efficient code. Although subscripts are easier to
use, they must be internally computed into the index displacements.
When you use subscripts to access arrays, use a two-byte binary field on the mainframe instead of a zoned numeric field
to reduce execution time.
CA Easytrieve® Report Generator must convert one of the operands when you perform an operation on fields of different
data types. To limit data conversions, code the fields to be updated or compared as the same type and the same number
of decimal places whenever possible.
In non-mainframe environments, all numeric operations require that the operands be converted to packed. Therefore
packed decimal is the most efficient data type. However, this is subject to change.
Table Processing
Avoid using very large tables, because they take more time to search and require more storage than small tables.
Note: CA Easytrieve® Report Generator automatically converts a SEARCH of an INDEXED table file into a keyed read
when the ARG field is also the file's key. This results in much faster access and reduced storage requirements.
Compiler Site and Program Options
The FASTSRT mainframe site option allows you to specify whether CA Easytrieve® Report Generator instructs the
mainframe sort program to process all of the I/O whenever possible. If the FASTSRT option is specified at your site,
ensure that the sort program can process extended parameter lists.
The STATE site option and PARM statement parameter saves the statement number of the statement currently being
executed for display during an abnormal termination. This option/parameter requires approximately six to eight bytes of
additional storage for each executable source line in your program.
The FLOW site option and PARM statement parameter activates a trace of statements being executed to be printed
during an abnormal termination. This option and this parameter require a subroutine to be invoked once for each
executable source line.
After you test your program, deactivate the FLOW trace, if possible, to decrease execution time of your program.
517
CA Easytrieve® Report Generator 11.6
The FLDCHK site option and PARM statement parameter validates all data references during program execution. This
option and this parameter generate additional CA Easytrieve® Report Generator code.
After you test your program, deactivate the FLDCHK validation, if possible, to decrease execution time of your program.
The VFM site option and PARM statement parameter specifies the amount of storage available for the Virtual File
Manager (VFM) buffer pool. Additional storage can decrease execution time.
The ABEXIT site option and PARM statement parameter activates the runtime SPIE exit which gets control in order
to produce debugging information in case of an abend in the CA Easytrieve® Report Generator application program.
Activating the SPIE exit requires additional storage and time resources.
Set ABEXIT=NO in the site options, and during development, specify PARM ABEXIT(SNAP) in the CA Easytrieve® Report
Generator program. After you test your program, remove the ABEXIT(SNAP) so the production compilation is done with
ABEXIT=NO.
Report Processing
In non-CICS mainframe environments, you can enhance report processing performance by coding the FILE parameter on
the REPORT statement or the WORKFILE parameter of the PARM statement, (or the WORKFILE Option in the Options
Table). Any of these parameters specifies that a dedicated work file is to be used rather than a VFM work file.
Code CICS Programs
Here are some tips to help you write efficient CA Easytrieve® Report Generator programs in a CICS environment:
• The following site options or PARM statement parameters are ignored under CICS:
– FASTSRT site option
– SSID site option
– SSID PARM statement parameter
• CA Easytrieve® Report Generator saves and restores all working storage fields, record I/O buffers, and table file
entries across pseudo-conversations using temporary storage. Limit the number of fields and table entries you use in
your program.
• To save on table usage, use INDEXED files, rather than in-stream files, as the subject of searches of large tables.
When an INDEXED file is used as a table, the SEARCH statement results in a random read to the INDEXED file using
the argument as the key.
• You must code the TRANSID parameter of the PARM statement if the program is invoked by another program through
the TRANSFER statement. TRANSID specifies the PCT transaction ID that is invoked after a pseudo-conversation.
• Terminal I/O is done pseudo-conversationally unless COMMIT NOTERMINAL is specified on the activity statement.
For more information about CA Easytrieve® Report Generator commit processing, see the topic Units of Work and
Commit Processing on the page Control Program Flow.
• It is important to remember that commit points and pseudo-conversational terminal I/O can cause the following:
– VSAM file browses on non-unique paths are terminated.
– File holds are released.
– SQL cursors are closed and data is committed.
– Called subroutines are deleted and reloaded.
– CA IDMS run units are terminated.
– DLI PSBs are terminated.
• You must code your programs carefully. For example, when browsing an SQL file, you must reposition browses after a
pseudo-conversation.
• Printer spool files are closed during each commit point, including pseudo-conversations.
518
CA Easytrieve® Report Generator 11.6
Multiple Platform Considerations
In addition to specific rules for how CA Easytrieve Report Generator works on different platforms, tips for migrating
programs to non-mainframe environments or when you have source that can run on multiple platforms follow:
• If your program relies on a specific collating sequence, you should review this code when moving platforms. For
example, you have to account for numeric values being higher than alphabetic values in EBCDIC but lower in ASCII.
INSTREAM tables, in particular, must be in proper order for the system you are compiling on. You may want to
consider converting these into external tables, which can be sorted for the specific platform.
• As you port files from one platform to another, you must address the manner that you use to transfer the files. You
should be aware that CA Easytrieve Report Generator uses ASCII or EBCDIC as appropriate for the environment in
which it runs. Be careful when you migrate your files to convert only the alphanumeric fields without corrupting numeric
data. Fixed sequential files on the mainframe may become line-feed delimited files on other platforms, and therefore
are required to be handled as variable files. For more information, see File Processing.
• The CONVAE/CONVEA toolkit macros can be used to convert alphanumeric fields between ASCII and EBCDIC. The
Workbench in CA Easytrieve Report Generator for Windows includes a data conversion utility that can convert a file
automatically, based on a macro containing that file’s field definitions.
• On distributed platforms, macros must be stored with an extension of .mac.
• Be aware that UNIX is case-sensitive and that %TEST will cause the compiler to look for TEST.mac, not test.mac.
• Mainframe FILE statements often get their attributes (record formats and record length) from JCL or from opening
an existing file. You may want to add the attributes to the FILE statement or you may want to get the attributes
dynamically through a file description string. For details, see the Execute a Program section.
• Be aware that the "I" data format is for integers of the native data format of the host environment you are executing
on. Your code should not expect specific hexadecimal values and still be considered portable because integers are not
stored identically on all platforms.
• You may find it useful for your code to test for the underlying code system when writing programs to be portable. A
simple method is to execute the following code that determines if execution is using an EBCDIC based system or not:
DEFINE TESTBYTE S 1 A VALUE 'A'
IF TESTBYTE = X'C1'
...
You can use this code example to dynamically set a FILE statement SYSNAME value so it can be a DDname on a
mainframe or a pathname on a PC.
SQL Database Processing
CA Easytrieve Report Generator provides optional processing facilities for SQL databases. The following SQL databases
are supported:
• IBM Db2, versions 9, 10, 11 and 12
• IBM's Db2 for AIX, version 2.1 and greater
• IBM's SQL/DS, version 2.2 and greater
• CA Datacom/DB with SQL, version 8.0 and greater
• CA IDMS, version 12.0 and greater
• Oracle, mainframe, version 10g and greater
• Oracle, HP-UX and AIX, version 7.1 and greater
• Ingres, HP-UX and AIX, version 6.4 and greater
• OpenIngres, HP-UX, and AIX, version 1.0 and greater
• ODBC, version 3.0 and greater
Mainframe users:
519
CA Easytrieve® Report Generator 11.6
• Before CA Easytrieve Report Generator can process these databases, the CA Pan/SQL Interface product, version 2.4,
must be correctly installed. To process an Oracle database, CA Pan/SQL version 2.5 must be installed. For complete
information, see the CA Pan/SQL Interface Getting Started Guide, available from Bookshelves and PDFs.
Non-mainframe users:
• All SQL Interface functionality is installed with CA Easytrieve Report Generator. No additional installation or
documentation is required.
To use these facilities effectively, you should have a basic knowledge of SQL and the database management system to be
processed.
Programming Methods
The supported programming methods for processing SQL databases are:
• Use native SQL statements to manually manage the SQL cursor.
• Let CA Easytrieve Report Generator automatically manage the SQL cursor.
Native SQL Statements
CA Easytrieve Report Generator supports most of the SQL statements available for a given DBMS. The exceptions are
those statements that are compiler directives and statements that cannot be dynamically prepared. Using these native
SQL statements, you can code fully SQL-compliant programs in which you control the SQL cursor operation. All native
SQL statements are prefixed with the SQL keyword. For complete syntax, see the Language Reference section.
For SQL commands, see the following sections:
• Supported SQL Commands
• Unsupported SQL Commands
Automatic Cursor Management
CA Easytrieve Report Generator can automatically manage the SQL cursor in the following ways:
• CA Easytrieve Report Generator files
• Automatic retrieval without a file
CA Easytrieve Report Generator Files
CA Easytrieve Report Generator can automate SQL cursor management when you associate an SQL cursor with a CA
Easytrieve® Report Generator file. The SQL file can then be accessed in two ways:
• JOB INPUT statement -- With each iteration of the JOB statement or activity, another row from the table is
automatically retrieved into the file's data area. Even if you have only a basic knowledge of SQL, you can report on
data that is contained in an SQL database.
• CA Easytrieve Report Generator SQL-like statements -- Use the following statements to read and write SQL data on a
controlled basis:
– CLOSE
– DELETE
– FETCH
– INSERT
– SELECT
– UPDATE
520
CA Easytrieve® Report Generator 11.6
Automatic Retrieval Without a File
In this read-only method, you must code SQL on the JOB statement in place of a file name. You must code a SELECT
statement directly after the JOB statement to specify the columns to be retrieved and the host variables to receive the
data. Each time the JOB activity is iterated, another row of SQL data is retrieved. This is a simple way to retrieve SQL
data into working storage or into an extract file for subsequent output. Automatic retrieval does not require that you define
a CA Easytrieve Report Generator file.
CA Easytrieve SQL Statement Rules
The following syntax rules apply when you code SQL control statements in CA Easytrieve Report Generator:
• Operators must be separated by blanks.
• Standard CA Easytrieve Report Generator continuation conventions are followed.
• Commas are not ignored.
• The period is used as a qualification separator, not to signify end-of-statement.
• The colon is used to identify host/indicator variables, not as a qualification separator.
• An SQL statement cannot be followed by another statement on the same source record.
Program Environment
CA Easytrieve® Report Generator processes SQL statements using the CA Pan/SQL interface on the mainframe and
internal interfaces in non-mainframe environments. A specific implementation exists for each supported database:
• For mainframe DB2, both a dynamic interface and a static interface are supported.
• For SQL/DS, extended dynamic SQL is supported. SQL statements are dynamically prepared during the compilation of
your CA Easytrieve program and an access module or package is created. At runtime, SQL statements are executed
from the access module or package.
• The CA Datacom/DB SQL interface is similar to the SQL/DS interface. An access plan, from which SQL statements
are executed, is created at compile time.
• The CA IDMS SQL interface is strictly a dynamic interface for both compilation and execution.
• The non-mainframe Ingres, DB2, ODBC, and Oracle SQL interfaces are strictly dynamic interfaces for both compilation
and execution.
See Unsupported SQL Commands for a list of commands that cannot be coded in CA Easytrieve programs.
Units of Work
Each CA Easytrieve activity is considered a separate SQL unit of work or transaction. If COMMIT TERMINAL is specified
on the activity statement, a commit is automatically executed during terminal I/O. If COMMIT ACTIVITY is specified in the
activity, a commit is also executed following the termination of the activity. If CA Easytrieve detects an error condition or if
you code a STOP EXECUTE statement in your program, a ROLLBACK statement is automatically executed.
You can issue your own COMMIT and ROLLBACK statements to signal the successful or unsuccessful end of the
transaction. These COMMIT and ROLLBACK statements are performed in addition to the ones CA Easytrieve does
automatically.
Each time a COMMIT or ROLLBACK statement is executed, all open SQL cursors are closed. Exceptions may exist for
specific databases that maintain cursor positioning across commits or syncpoints.
Support for Multiple SSIDs with CA Pan/SQL Feature
CA Easytrieve invokes a specific DB2 PAN/SQL installation from among multiple installations based on the value that is
specified for PARM SSID in the CA Easytrieve program. With this feature, if you have multiple versions of DB2 installed,
you can have multiple CA PAN/SQL installations for each DB2 within a single library, and select the DB2 you want to
521
CA Easytrieve® Report Generator 11.6
access by using the PARM SSID value in the CA Easytrieve program. This is done by building the CA Easytrieve SSID
Table which is a cross-reference table that assigns a specific PAN/SQL installation with a DB2 SSID. The CBAAJCL
member SSIDTBL is used to build the table. Information about how to create multiple PAN/SQL for DB2 installations in the
same load library is provided with PAN/SQL.
PARM Statement Parameters
The PARM statement parameters set the SQL environment for the program.
SQLSYNTAX
In all environments, use the SQLSYNTAX parameter to specify the level of SQL syntax checking to perform on the SQL
statements in your program. SQLSYNTAX FULL specifies that SQL statements undergo detail-level syntax checking. An
SQL PREPARE statement is executed for those SQL statements that can be dynamically prepared. Your DBMS must be
available to CA Easytrieve. SQLSYNTAX PARTIAL indicates that your SQL statements are checked for valid commands
and secondary keywords. No connection is made to your DBMS unless you have an SQL INCLUDE statement in your
program. Your program does not execute until it has undergone FULL syntax checking.
If you want syntax checking to be performed by the DB2 preprocessor in a batch environment, you can use the
SQLSYNTAX NONE parameter on the PARM statement with a static bind. An option of NONE causes your program to
undergo partial syntax checking. Your program continues execution if no partial-level compile errors are found, a BIND
option of STATIC-ONLY is specified, and no other non-SQL syntax errors are found.
DB2
The SQLID parameter of the PARM statement results in the execution of the SQL SET CURRENT SQLID command by
the SQL Interface at compile time. The SQL SET CURRENT SQLID command is executed at runtime for controlled or
automatic processing. Execution of the SQL SET CURRENT SQLID command is valid for sites that have an external
security package that supports group IDs. The SQLID parameter applies to mainframe only.
The SSID parameter of the PARM statement can be used to specify the desired DB2 subsystem in non-CICS
environments. If the SSID parameter is not coded, the SQL interface gets the DB2 subsystem ID from the DB2 system
default module DSNHDECP. DSNHDECP is made available through the JOBLIB or steplib libraries. In CICS, the currently
attached subsystem is used. In non-mainframe environments, the SSID identifies the database to be connected.
Static SQL is used to improve the performance of an SQL program. In a static SQL program, all SQL statements are
known ahead of time and an optimized plan is created prior to execution time.
Static SQL is specified by two parameters on the PARM statement. PLAN specifies the name of the DB2 static-command-
program and its plan name. The command program can either be linked with the CA Easytrieve program or linked as a
separate load module. A BIND parameter of STATIC-ONLY or ANY causes the static-command-program to be generated.
The PLAN and BIND parameters apply to mainframe only.
To run your program statically, you must run special steps to create and link the static command program and plan. For
more information, see Program Compilation and Link-Editing Using JCL.
Dynamic SQL is used to process your program when running under the interpreter, regardless of the BIND parameter
specified.
Static SQL and the LINK Statement
When you execute multiple static SQL programs in a given transaction or task, you must bind all of the involved DBRMs
into a single plan. Therefore, specify the same plan name for the PLAN parameter of each application program.
PAN$SQL DD File
You can code a PAN$SQL DD statement to provide a plan name and DB2 for z/OS subsystem to be used at the time of
your execution. The PAN$SQL DD file is processed only when executing statically and if the DB2 for z/OS Call Attach
Facility is used to establish a connection. The PAN$SQL file can also be used to indicate that you want to execute
522
CA Easytrieve® Report Generator 11.6
under the TSO Terminal Monitor Program in background mode. If TSO execution is specified, then the plan name and
subsystem ID parameters are ignored. Valid parameters for the PAN$SQL file are the following:
• PLAN—provide the name of the DB2 for z/OS plan to use for execution.
• SSID—provide the name of the DB2 for z/OS subsystem to use for the DB2 for z/OS Call Attach Facility for a
connection.
• TSO—indicates that you want to execute your CA Easytrieve program under the TSO Terminal Monitor Program in
background mode. You must code the correct JCL.
The following is sample JCL for the PAN$SQL statement:
//PAN$SQL DD *
PLAN=TESTPLAN,SSID=D810
The ability to specify a plan name for execution enables you to compile and link your CA Easytrieve DB2 for z/OS
application program once. The DBRM can then be bound into any DB2 for z/OS subsystem with any planname.
Execution under TSO resolves the problem of called DB2 for z/OS subroutines that previously had to be linked with
DSNALI, the DB2 for z/OS Call Attach Facility module. This restriction required subroutines to be linked one way for other
applications.
If your CA Easytrieve program contains SQL statements and it also calls COBOL (or other language) subroutines, you can
now share those subroutines with CA Easytrieve applications and other applications.
You can link your COBOL subroutines once with DSNELI and it can be used by all your applications.
Sample JCL for Execution Under TSO:
//EXECEZT EXEC PGM=IKJEFT01,DYNAMNBR=20
//STEPLIB DD DISP=SHR,DSN=your.ezt.target.library
// DD DISP=SHR,DSN=your.ezt.db2.application.library
// DD DISP=SHR,DSN=your.pansql.tso.load.library
// DD DISP=SHR,DSN=your.db2.sdsnload.library
//PAN$SQL DD *
TSO <=== Indicate TSO execution
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//REPORT DD SYSOUT=*
//SYSIN DD DUMMY
//SYSTSIN DD *
DSN SYSTEM(D810)
RUN PROGRAM(eztpgm) PLAN(testplan)
END
/*
Qualifying DB2 for z/OS Tables
Unqualified tables are implicitly qualified by the primary authorization ID of the program. This ID is usually established by
the USER parameter of your JCL JOB statement. You can modify qualification in one of three ways:
• SQLID keyword on the CA Easytrieve PARM statement
• SQL SET CURRENT SQLID command
• OWNER or QUALIFIER parameter on the DB2 for z/OS BIND statement
Use of the SQLID and its effect on table qualification depends on whether automatic or controlled processing is performed
and whether static or dynamic SQL is used.
523
CA Easytrieve® Report Generator 11.6
To eliminate the authorization problems that are encountered with the use of SQLID, use SQLSYNTAX NONE with BIND
STATIC-ONLY. These parameters enable the use of unqualified table names and bypass the dynamic prepare of SQL
statements. Unqualified table names can then be qualified by the BIND process.
SQL/DS
Specify the SQL/DS user ID to be used for compiling the program on the USERID parameter of the PARM statement. At
execution time, a CONNECT is executed by CA Easytrieve for automatic processing only. For controlled processing, you
must code the SQL CONNECT command providing the values for an sqlid and password.
Specify the name of the SQL/DS access module for this program on the PREPNAME parameter of the PARM statement.
When an SQL program is compiled, an access module is created or replaced. To avoid using the default name, use
unique access module names for each application program. In a high volume system, using the default PREPNAME can
result in catalog contention and a -911 SQLCODE resulting from a rollback.
CA Datacom/DB
Use the PLANOPTS parameter on the PARM statement to specify the name of a CA Pan/SQL PLAN options module to
override the default module (DQSMPLN@). For more information about defining your own options module, see the CA
Pan/SQL Interface Getting Started Guide, available from Bookshelves and PDFs.
CA IDMS
Use the USERID parameter to specify the name of the IDMS dictionary to be used for explicit connect (no password is
needed).
If no dictionary name is provided, an implicit connection is attempted when the first SQL statement is processed. The
dictionary name is then obtained from the SYSCTL DD card provided in your JCL.
Ingres
Use the SSID parameter on the PARM statement to specify the name of the database to which this session connects.
Use the USERID parameter on the PARM statement to specify the user identifier under which this session runs. The
password subparameter is ignored.
ORACLE
Use the USERID parameter of the PARM statement to specify the ORACLE user ID for compiling the program. At
execution time, CA Easytrieve executes a CONNECT for automatic processing only. For controlled processing, you must
code the SQL CONNECT command, providing the values for an sqlid and password.
Language Environment is required for Oracle execution. The CA Easytrieve program that accesses an Oracle database
must run as an LE application. Therefore, PARM ENVIRONMENT(COBOL) is unconditionally activated for programs that
access Oracle.
ODBC
Use the SSID parameter on the PARM statement to specify the name of the data source to which this session connects.
In Windows, a connection dialog box is displayed if no SSID is provided.
Use the USERID parameter of the PARM statement to specify a user ID for compiling the program. At execution time,
CA Easytrieve executes a CONNECT for automatic processing only. For controlled processing, you must code the SQL
CONNECT command, providing the values for a data source, user ID, and password.
524
CA Easytrieve® Report Generator 11.6
Library Section Definition
Before SQL data can be accessed, you must define the fields to hold the columns to be retrieved. These fields are known
as host variables.
If you are using native SQL commands or using automatic retrieval without a file, you usually define the fields as working
storage fields. Alternatively, you can define the fields within an active output file. This is an effective method to select SQL
data into a sequential file for extraction purposes. You must specify which columns are to be retrieved and which host
variables are to receive the data.
When using a CA Easytrieve Report Generator file, however, fields defined within the file correspond to the selected
columns of the SQL table. The table columns are retrieved into the file fields.
This article contains the following information:
SQL Catalog INCLUDE Facility
You can use the SQL catalog INCLUDE facility to automatically generate CA Easytrieve Report Generator field definitions
directly from the SQL catalog. This eliminates the need to code host variable definitions in the library section of your
program. You may wish to add redefinitions of the generated fields. For example, you may wish to code field segments for
large alphanumeric fields that will not fit on a single print line or you may wish to add MASKs to your redefinition.
The SQL INCLUDE statement names the SQL table or view from which column names and data types are obtained, and
defines the location at which the field definitions are generated.
The SQL INCLUDE statement must precede any other SQL or SELECT statements and must be coded in the library
section of your CA Easytrieve Report Generator program.
Note: To use the SQL catalog INCLUDE facility for ORACLE, your database administrator must have installed the catalog
views (catalog.sql).
Processing Nullable Fields
CA Easytrieve Report Generator supports the SQL concept of a null data value. Null is a value that denotes the absence
of a known value for a field. Specify the keyword NULLABLE on the SQL INCLUDE statement to generate the null
indicator variables. CA Easytrieve Report Generator does the rest of the processing for you when processing the SQL
table as a file.
When a field is defined as nullable, you can use special processing statements:
• IF NULL can be used to determine if the field contains a null value.
• MOVE NULL can be used to set a field's value to null.
Manual NULL Processing
When you use native SQL statements or automatic retrieval without a file, you define null values differently. You define an
indicator variable as a two-byte quantitative binary field (2 B 0). This indicator variable is then used in the INTO clause of
the native or automatic SELECT statement. SQL returns a negative value to the indicator variable when the field's value is
null. See the native SQL examples for the use of manual indicator values.
Note: CA Datacom/DB uses I type fields as indicator variables. You can code B or I data types as indicator variables,
however, if you code B type data, conversion is performed whenever the database is accessed.
525
CA Easytrieve® Report Generator 11.6
SQL Data Types
The following tables illustrate SQL data types and corresponding CA Easytrieve Report Generator field definitions. SQL
provides some data conversion in SQL assignments and comparisons. For more information about SQL data conversions,
see your SQL manuals. See the corresponding notes after the tables for asterisked items in the tables.
The first table includes DB2, SQL/DS, CA Datacom/DB, and ODBC databases.
SQL CA Easytrieve DB2, SQL/DS CA Datacom/DB SQL ODBC
BIGINT 8B0 Y N N
8I0
INTEGER 4B0 Y Y Y
4I0
SMALL INTEGER 2B0 Y Y Y
2I0
DECIMAL (x,y) xPy Y Y Y
UNSIGNED DECIMAL xPy N N N
(x,y)
CHARACTER (x) xA Y Y Y
VARCHAR (x) x A VARYING Y Y (8.1) Y
(x <= 254)
TEXT (x) x A VARYING N N N
LONG VARCHAR (x) x A VARYING Y Y (8.1) Y
(x > 254)
VARCHAR2 (x) x A VARYING N N Y
RAW x A VARYING N N N
LONG RAW (x) x A VARYING N N N
NUMERIC (x,y) xNy N Y Y
UNSIGNED NUMERIC xNy N N N
(x,y)
FLOAT 10 P 3 Y Y Y
REAL 10 P 3 Y Y Y
DOUBLE PRECISION 10 P 3 Y Y Y
NUMBER xPy N N N
MONEY 10 P 2 N N N
GRAPHIC (x) xM Y N N
xK
VARGRAPHIC (x) x M VARYING Y N N
x K VARYING
(x <= 254)
LONG VARGRAPHIC (x) x M VARYING Y N N
x K VARYING
(x > 254)
DATE 10 A *2 Y Y Y
TIME 8A Y Y Y
TIMESTAMP 26 A Y Y Y
526
CA Easytrieve® Report Generator 11.6
BINARY x B y *1 N N N
none xUy - - -
The next table includes CA IDMS, Ingres, and Oracle databases:
SQL CA Easytrieve CA IDMS SQL Ingres Oracle
INTEGER 4B0 Y Y N
4I0
SMALL INTEGER 2B0 Y Y N
2I0
DECIMAL (x,y) xPy Y N N
UNSIGNED DECIMAL xPy Y N N
(x,y)
CHARACTER (x) xA Y Y Y
VARCHAR (x) x A VARYING Y Y Y
(x <= 254)
TEXT (x) x A VARYING N Y N
LONG VARCHAR (x) x A VARYING Y N N
(x > 254)
VARCHAR2 (x) x A VARYING N N Y
RAW (x) x A VARYING N N Y
LONG RAW (x) x A VARYING N N Y
NUMERIC (x,y) xNy Y N N
UNSIGNED NUMERIC xNy Y N N
(x,y)
FLOAT 10 P 3 Y Y Y
REAL 10 P 3 Y N N
DOUBLE PRECISION 10 P 3 Y N N
NUMBER (x,y) x P y *3 N N Y
MONEY 10 P 2 N Y N
GRAPHIC (x) xM Y N N
xK
VARGRAPHIC (x) x M VARYING Y N N
x K VARYING
(x < = 254)
LONG VARGRAPHIC (x) x M VARYING Y N N
x K VARYING
(x > 254)
DATE 10 A *2 Y Y Y
TIME 8A Y N N
TIMESTAMP 26 A Y N N
BINARY x B y *1 Y N N
none xUy - - -
527
CA Easytrieve® Report Generator 11.6
Note 1: The data type of BINARY is invalid for lengths other than 2, 4, or 8. When processing an SQL INCLUDE
statement on the mainframe, this data type is converted to x A.
Note 2: For Ingres, dates are 11 bytes in length.
Note 3: Maximum length = 10 bytes.
Decimal Data Types
For SQL DECIMAL data types, the scale is the same as the decimal places of a CA Easytrieve field. SQL precision
refers to the total number of digits that can occur in the packed field. A CA Easytrieve length refers to the number of
bytes occupied by the packed field. A CA Easytrieve field that is 5 P 2 is the equivalent of an SQL DECIMAL data type
of precision = 9 and scale = 2. Depending on your SQL release, SQL may not support CA Easytrieve packed fields with
lengths > 8.
SQL Syntax Checking
When an SQL statement is passed to SQL for syntax checking, host variables are converted to question marks (?) by
the product. It is possible that when an SQL error is detected, the question mark is identified as the field in error. In this
case, you are responsible for looking up the error message and identifying which host variable is in error. Because host
variables are replaced with question marks, their use in arithmetic expressions may result in compile errors. For DB2 and
SQL/DS, an SQLCODE of -418 can occur.
System-Defined File Fields
When using a CA Easytrieve Report Generator file to process an SQL database, the following system-defined fields are
used:
RECORD-COUNT
RECORD-COUNT contains the number of rows returned to the CA Easytrieve Report Generator program. This is the
number of rows fetched by either automatic or controlled processing.
RECORD-LENGTH
RECORD-LENGTH is the length of the SQL file. The length is the sum of the maximum lengths of all fields in the file.
EOF Processing
When the end of the tables has been reached, either with automatic (JOB) or controlled (FETCH) processing, the file is
marked EOF (end of file). In automatic processing, execution stops, and the FINISH procedure (if present) executes. In
controlled processing, you can code file presence tests (IF EOF file-name) to determine whether an end of file condition
exists.
SQL Communications Area Fields
All of the SQL Communication Area fields (SQLCA) are automatically created in S (static) working storage when any of
the following occurs:
• The first SQL-managed file is encountered.
• The first SQL INCLUDE statement is encountered.
• The first native or controlled SQL statement is found.
• The first JOB INPUT SQL statement is found.
The fields generated for SQLCA for the supported SQL database management systems are shown in the following lists.
SQL Communication Area Fields for DB2, SQL/DS, Ingres, ODBC, and ORACLE
528
CA Easytrieve® Report Generator 11.6
DEFINE SQLCA S 136 A
DEFINE SQLCAID SQLCA 8 A
DEFINE SQLCABC SQLCA +8 4 B 0
DEFINE SQLCODE SQLCA +12 4 B 0
DEFINE SQLERRM SQLCA +16 72 A
DEFINE SQLERRML SQLCA +16 2 B 0
DEFINE SQLERRMC SQLCA +18 70 A
DEFINE SQLERRP SQLCA +88 8 A
DEFINE SQLERRD SQLCA +96 4 B 0 OCCURS 6
DEFINE SQLWARN SQLCA +120 8 A
DEFINE SQLWARN0 SQLCA +120 1 A
DEFINE SQLWARN1 SQLCA +121 1 A
DEFINE SQLWARN2 SQLCA +122 1 A
DEFINE SQLWARN3 SQLCA +123 1 A
DEFINE SQLWARN4 SQLCA +124 1 A
DEFINE SQLWARN5 SQLCA +125 1 A
DEFINE SQLWARN6 SQLCA +126 1 A
DEFINE SQLWARN7 SQLCA +127 1 A
DEFINE SQLWARN8 SQLCA +128 1 A
DEFINE SQLWARN9 SQLCA +129 1 A
DEFINE SQLWARNA SQLCA +130 1 A
DEFINE SQLEXT SQLCA +131 5 A
DEFINE SQLSTATE SQLCA +131 5 A
SQL Communication Area Fields for CA Datacom/DB
SQLCA S 196 A
SQLCA-EYE-CATCH SQLCA 8 A
SQLCAID SQLCA 8 A
SQLCA-LEN SQLCA +8 4 B 0
SQLCABC SQLCA +8 4 B 0
SQLCA-DB-VRS SQLCA +12 2 A
SQLCA-DB-RLS SQLCA +14 2 A
SQLCA-LUWID SQLCA +16 8 A
SQLCODE SQLCA +24 4 B 0
SQLCA-ERROR-INFO SQLCA +28 82 A
SQLCA-ERR-LEN SQLCA +28 2 B 0
SQLCA-ERR-MSG SQLCA +30 80 A
SQLERRM SQLCA +28 72 A
SQLERRML SQLCA +28 2 B 0
SQLERRMC SQLCA +30 70 A
SQLCA-ERROR-PGM SQLCA +110 8 A
SQLERRP SQLCA +110 8 A
SQLCA-FILLER-1 SQLCA +118 2 A
SQLCA-ERROR-DATA SQLCA +120 24 A
SQLCA-DSFCODE SQLCA +120 4 A
SQLCA-INFCODE SQLCA +124 4 B 0
SQLCA-DBCODE SQLCA +128 4 A
SQLCA-DBCODE-EXT SQLCA +128 2 A
SQLCA-DBCODE-INT SQLCA +130 2 B 0
SQLCA-MISC-CODE1 SQLCA +132 4 A
SQLCA-MISC-CODE2 SQLCA +136 4 B 0
529
CA Easytrieve® Report Generator 11.6
SQLCA-MISC-CODE3 SQLCA +140 4 A
SQLCA-WRN-AREA SQLCA +144 8 A
SQLCA-WARNING SQLCA +144 1 A OCCURS 8
SQLWARN SQLCA +144 8 A
SQLWARN0 SQLCA +144 1 A
SQLWARN1 SQLCA +145 1 A
SQLWARN2 SQLCA +146 1 A
SQLWARN3 SQLCA +147 1 A
SQLWARN4 SQLCA +148 1 A
SQLWARN5 SQLCA +149 1 A
SQLWARN6 SQLCA +150 1 A
SQLWARN7 SQLCA +151 1 A
SQLCA-PGM-NAME SQLCA +152 8 A
SQLCA-AUTHID SQLCA +160 18 A
SQLCA-PLAN-NAME SQLCA +178 18 A
SQL Communication Area Fields for CA IDMS
SQLCA S 344 A
SQLCAID SQLCA 8 A
SQLCODE SQLCA +8 4 B 0
SQLCSID SQLCA +12 4 B 0 OCCURS 2
SQLCERC SQLCA +20 4 B 0
SQLCNRP SQLCA +28 4 B 0
SQLCSER SQLCA +36 4 B 0
SQLCLNO SQLCA +44 4 B 0
SQLCMCT SQLCA +48 4 B 0
SQLCOPTS SQLCA +52 4 B 0
SQLCFJB SQLCA +56 4 B 0
SQLCPCID SQLCA +60 4 B 0
SQLCLCID SQLCA +64 4 B 0
SQLCERL SQLCA +68 2 B 0
SQLCERM SQLCA +72 256 A
SQLSTATE SQLCA +328 5 A
NOTE
When the CA Easytrieve Report Generator client is using ODBC, only the following SQLCA variables are set.
For all SQL statements:
• SQLCODE
For all SQL statements when an error occurs:
• SQLMESG
• SQLERRM
• SQLERRMC
• SQLERRML
• SQLEXT
• SQLSTATE
Upon successful execution of INSERT, UPDATE, and DELETE statements:
• SQLERRD(3)
530
CA Easytrieve® Report Generator 11.6
Because the ODBC standard does not provide an interface to read SQLCA values, all other SQLCA variables
are empty.
For more information about SQLCA, go to https://www.ibm.com/support/knowledgecenter/ and search for
SQLCA (SQL communications area) Db2.
Sample Database
The following two tables are used for all the examples in this section.
TABLE: PERSONNEL
------------------------------------------
COLUMNS: EMPNAME WORKDEPT EMPPHONE
------------------------------------------
DATA: NORIDGE DEBBIE 901 5001
OSMON SAMUEL 901 5004
MILLER JOAN 950 6034
EPERT LINDA 950 null
STRIDE ANN 901 null
ROGERS PAT 921 2231
EMPNAME - CHAR(20) (NOT NULL)
WORKDEPT - DECIMAL(3,0) (NOT NULL)
EMPPHONE - DECIMAL(5,0) (NULL)
.....................................................
TABLE: DEPARTMENTS
------------------------------
COLUMNS: DEPTNAME DEPTNUMBER
------------------------------
DATA: SHIPPING 901
HUMAN RESOURCES 921
ACCOUNTING 950
DATA PROCESSING 951
DEPTNAME - VARCHAR(20) (NOT NULL)
DEPTNUMBER - DECIMAL(3,0) (NOT NULL)
WORKDEPT in the PERSONNEL table corresponds with
the DEPTNUMBER in the DEPARTMENTS table.
Working Storage Definitions
This code shows working storage field definitions for the two sample tables:
DEFINE EMPNAME W 20 A
DEFINE WORKDEPT W 2 P 0
DEFINE EMPPHONE W 3 P 0
DEFINE DEPTNAME W 22 A VARYING
DEFINE DEPTNUMBER W 2 P 0
DEFINE NULLPHONE W 2 B 0 .* NULL INDICATOR
DEFINE USERID W 8 A VALUE('SQLDBA') .* SQL/DS USERID
DEFINE PASSWORD W 8 A VALUE('SQLDBAPW') .* SQL/DS PASSWORD
531
CA Easytrieve® Report Generator 11.6
CA Easytrieve SQL Files
In this method of processing SQL, CA Easytrieve Report Generator automates cursor management by associating an
SQL cursor with a CA Easytrieve Report Generator file.
This article includes the following information:
Processing Requirements
To process data from an SQL table using this method, you must code the following items:
• A FILE statement that specifies one or more table names
• If all columns defined in the file are subject to update, specify the UPDATE keyword on the FILE statement.
• One or more field definitions for the columns within the tables that you want to retrieve
You can code these definitions by using the DEFINE statement or by using the SQL INCLUDE statement to
automatically generate the definitions from the SQL catalog. If you want to selectively update only a few columns of
those defined within the file, omit the UPDATE keyword from the FILE statement and specify UPDATE only on the
field definitions (columns) you want to update. Coding UPDATE on the SQL INCLUDE statement causes generated
definitions to be subject to update.
• A SELECT statement that defines the result set for the cursor
If you do not use a SELECT statement, CA Easytrieve Report Generator generates a default SELECT to retrieve all
rows for the tables. You can override this default by specifying your own file-based SELECT statement as the first
statement following the JOB statement.
Overriding the default SELECT allows you to use SQL techniques to customize the result set for the cursor. For
example, you can:
– Limit the result set to a subset of records (WHERE)
– Organize the data in the table by groups (GROUP BY)
– Limit the groups returned (HAVING)
– Sequence the returning records (ORDER BY)
In addition to overriding the default SELECT, you can code one or more SELECTs anywhere in your JOB activity. This
lets you use conditional logic to dynamically determine which SELECT is executed.
A SELECT statement for an SQL file is similar to opening the file. Selecting a file that is already open first closes the
file and then reopens the file based on the new SELECT statement.
NOTE
For more information about SELECT statement usage, see the Language Reference section.
Operation
If you are executing in an SQL/DS, Advantage Ingres, non-mainframe DB2, ODBC, or ORACLE system, CA Easytrieve
Report Generator generates and executes a CONNECT statement. You need not code an SQL CONNECT statement
when using CA Easytrieve Report Generator automatic processing. The user ID and password parameters are taken from
those specified in the USERID parameter of the PARM statement.
CA Easytrieve Report Generator checks the SQLCODE field following each execution of a file-based SQL statement. If
the SQLCODE indicates an error, CA Easytrieve Report Generator issues an error message based on the SQL error and
terminates execution. During automatic processing, an SQLCODE indicating end of data causes CA Easytrieve Report
Generator to initiate end-of-input processing; the FINISH PROC (if any) executes, spooled reports are printed, and the
current JOB activity ends. During controlled processing, an SQLCODE indicating end of data causes CA Easytrieve
Report Generator to set the value of EOF to true.
The SQL cursor that is automatically defined by a SELECT statement is closed following the termination of the activity that
opened it.
532
CA Easytrieve® Report Generator 11.6
NOTE
Non-mainframe systems are limited to a maximum of 10 open cursors.
Input Processing
You can access SQL data using a CA Easytrieve Report Generator file either automatically or with controlled processing.
Automatic Processing
If you name the SQL file as the input file on a JOB statement, CA Easytrieve Report Generator automatically accesses
your SQL database. When you specify an SQL file as automatic input, CA Easytrieve Report Generator prepares a default
SELECT statement for the cursor.
The following program displays all records in the table named PERSONNEL:
FILE PERSNL SQL (PERSONNEL)
EMPNAME * 20 A
WORKDEPT * 2 P 0
JOB NAME RETRIEVE-PERSONNEL INPUT PERSNL
DISPLAY EMPNAME +2 WORKDEPT
You can override the default SELECT statement by coding a SELECT statement for the automatic input file as the first
statement in the JOB, as follows:
FILE PERSNL SQL (PERSONNEL)
EMPNAME * 20 A
WORKDEPT * 2 P 0
JOB NAME RETRIEVE-PERSONNEL INPUT PERSNL
SELECT FROM PERSNL WHERE WORKDEPT = 901
DISPLAY EMPNAME +2 WORKDEPT
This program displays only the records for employees that are assigned to department 901. The SELECT statement
provides the new default selection criteria.
Using DEFER with SELECT
You can use the DEFER parameter on the SQL FILE statement to delay SELECT processing. For example, assume that
you want to select only employee numbers in a particular department and the department number is kept in a card file.
The SELECT statement contains a WHERE clause specifying the host variable in the card file. CA Easytrieve® Report
Generator opens the CARD file at the initiation of the JOB activity but the GET statement is coded in a START procedure.
If the file SELECT is not deferred, the SELECT is performed using an uninitialized host variable. Coding DEFER enables
the START procedure to get the card before the SELECT is performed.
In addition, if DEFER is not specified, the default SELECT is executed before the START procedure. Then the SELECT in
the START procedure is executed. This causes extra processing that is not needed. For example:
FILE PERSNL SQL (PERSONNEL) DEFER
EMPNAME * 20 A
WORKDEPT * 2 P
FILE CARDFIL CARD
CARDDEPT 1 3 N
JOB NAME RETRIEVE-PERSONNEL INPUT PERSNL START GETCARD
DISPLAY EMPNAME +2 WORKDEPT
GETCARD. PROC
533
CA Easytrieve® Report Generator 11.6
GET CARDFIL
SELECT FROM PERSNL WHERE WORKDEPT = :CARDDEPT
END-PROC
NULLable Field Processing
The following example illustrates how to process the nullable field, EMPPHONE. You must test for a nullable field before
processing it. If EMPPHONE contains a null value, it is set to zero before displaying it:
FILE PERSNL SQL (PERSONNEL)
SQL INCLUDE (EMPNAME, WORKDEPT, EMPPHONE) +
FROM PERSONNEL LOCATION * NULLABLE
JOB NAME RETRIEVE-PERSONNEL INPUT PERSNL
IF EMPPHONE NULL
EMPPHONE = 0
END-IF
DISPLAY EMPNAME +2 WORKDEPT +2 EMPPHONE
Multiple Tables
The following example illustrates joining two tables, PERSONNEL and DEPARTMENTS, to report on employees and the
departments in which they work:
FILE PERSNL SQL (PERSONNEL, DEPARTMENTS)
EMPNAME * 20 A HEADING 'EMPLOYEE NAME'
WORKDEPT * 2 P 0 HEADING ('DEPT', 'NO')
DEPTNAME * 22 A HEADING 'DEPARTMENT'
DEPTNUMBER * 2 P 0
JOB NAME RETRIEVE-PERSONNEL INPUT PERSNL
SELECT FROM PERSNL WHERE WORKDEPT = DEPTNUMBER
PRINT PERSNL-REPORT
REPORT PERSNL-REPORT
LINE EMPNAME WORKDEPT DEPTNAME
Both table names are specified on the FILE statement. The default SELECT is overridden because the result set should
include only those DEPARTMENT records that match the department number of the PERSONNEL record.
Controlled Processing
You use the FETCH statement (in conjunction with SELECT and CLOSE statements) to retrieve the records from the file
with controlled processing. You can code these statements within a PROGRAM, SCREEN, or JOB activity, with or without
automatic input. The following rules apply:
• Controlled statements are not permitted in SORT or REPORT procedures.
• The FETCH statement cannot reference an automatic input file within the same JOB activity. You can FETCH from a
file other than the file subject to automatic input.
In a PROGRAM Activity
The following example illustrates controlled input from a default cursor:
FILE PERSNL SQL (PERSONNEL)
EMPNAME * 20 A
WORKDEPT * 2 P 0
PROGRAM NAME RETRIEVE-PERSONNEL
534
CA Easytrieve® Report Generator 11.6
FETCH FROM PERSNL
DO WHILE NOT EOF PERSNL
DISPLAY EMPNAME +2 WORKDEPT
FETCH FROM PERSNL
END-DO
The PROGRAM activity fetches each row of the table and displays the fields. The DO statement executes until end-of-file.
In a JOB Activity
The same process used in a JOB activity is coded as follows:
FILE PERSNL SQL (PERSONNEL)
EMPNAME * 20 A
WORKDEPT * 2 P 0
JOB NAME RETRIEVE-PERSONNEL INPUT NULL
FETCH FROM PERSNL
IF NOT EOF PERSNL
DISPLAY EMPNAME +2 WORKDEPT
ELSE
STOP
END-IF
You must execute a STOP statement when end-of-file is reached, because a NULL JOB activity automatically loops.
Random Processing
The following example illustrates a type of random processing in which the SQL file cursor is built using a key that is
contained in a sequential file.
FILE ESDS SEQUENTIAL
FILENAME 17 20 A
FILE PERSNL SQL (PERSONNEL) DEFER
EMPNAME * 20 A
WORKDEPT * 2 P 0
JOB NAME RETRIEVE-PERSONNEL INPUT ESDS
SELECT FROM PERSNL WHERE EMPNAME = :FILENAME
FETCH FROM PERSNL
IF EOF PERSNL
DISPLAY 'EMPLOYEE NOT ON FILE ' FILENAME
ELSE
DISPLAY EMPNAME +2 WORKDEPT
END-IF
CLOSE PERSNL
The sequential file is read automatically by the JOB activity. For each record, a SELECT statement is executed to
locate the employee in the PERSONNEL table. If the FETCH statement results in end-of-file, the employee is not found.
Otherwise, the employee name and department are displayed.
Synchronized File Processing
The following example illustrates a way to match a sequential file with an SQL file. This example uses the default SELECT
and then matches the two files based on the employee name in both files:
FILE ESDS SEQUENTIAL
535
CA Easytrieve® Report Generator 11.6
FILENAME 17 20 A
FILE PERSNL SQL (PERSONNEL)
EMPNAME * 20 A
WORKDEPT * 2 P 0
JOB NAME MATCH-PERSNL INPUT (ESDS KEY (FILENAME) PERSNL KEY (EMPNAME))
IF NOT MATCHED AND ESDS
DISPLAY 'EMPLOYEE NOT IN SQL FILE' FILENAME
ELSE
IF NOT MATCHED AND PERSNL
DISPLAY 'EMPLOYEE NOT ON ESDS FILE' EMPNAME
ELSE
DISPLAY 'EMPLOYEE ON BOTH FILES' EMPNAME
END-IF
END-IF
The default SELECT could have been overridden by coding a SELECT as the first statement after the JOB statement.
Update Processing
Additional requirements for updating a CA Easytrieve Report Generator SQL file are as follows:
• You can name only one table on the FILE statement for updates, inserts, or deletions.
• You must specify the UPDATE parameter on the FILE statement if all fields defined are subject to update. If you want
to update only certain fields, do not specify UPDATE on the FILE statement, but specify UPDATE on the DEFINE
statement for each field to be updated. You can also use the SQL INCLUDE statement to automatically generate
definitions with UPDATE.
• You must specify UPDATE on the FILE statement to insert or delete rows.
• For updating, you must code a SELECT statement for the file that contains the FOR UPDATE clause. If the FOR
UPDATE clause is omitted, the first UPDATE statement is flagged in error. Default SELECT statements that are
created by CA Easytrieve Report Generator do not contain the FOR UPDATE clause.
• For ORACLE, dynamic UPDATEs and DELETEs must be mimicked by CA Easytrieve Report Generator by selecting
the ROWID of each row, then using that value to identify the current row during the UPDATE or DELETE. For this
reason, you must use a SELECT statement with the FOR UPDATE clause.
• For certain ODBC data sources, UPDATEs and DELETEs WHERE CURRENT OF CURSOR are not supported. In
these cases, you must use native SQL statements.
Controlled Processing
The following example selects a specific row from the table, updates the department to 930, and moves a null data value
to the phone number:
FILE PERSNL SQL (PERSONNEL) UPDATE
SQL INCLUDE (EMPNAME, WORKDEPT, EMPPHONE) +
FROM PERSONNEL LOCATION * NULLABLE
PROGRAM NAME RETRIEVE-PERSONNEL
SELECT FROM PERSNL WHERE EMPNAME = 'ROGERS PAT' FOR UPDATE
FETCH FROM PERSNL
IF EOF PERSNL
DISPLAY 'EMPLOYEE NOT FOUND'
ELSE
WORKDEPT = 930
MOVE NULL TO EMPPHONE
UPDATE PERSNL
536
CA Easytrieve® Report Generator 11.6
END-IF
Automatic Processing
The following example changes the department number for all employees in departments 901 through 921:
FILE PERSNL SQL (PERSONNEL) UPDATE
SQL INCLUDE (WORKDEPT) +
FROM PERSONNEL LOCATION *
JOB NAME RETRIEVE-PERSONNEL INPUT PERSNL
SELECT FROM PERSNL WHERE WORKDEPT = 901 FOR UPDATE
WORKDEPT = 921
UPDATE PERSNL
Deleting from an SQL File
The following example illustrates how to select a specific row from the table, and then delete it:
FILE PERSNL SQL (PERSONNEL) UPDATE
SQL INCLUDE (EMPNAME, WORKDEPT, EMPPHONE) +
FROM PERSONNEL LOCATION * NULLABLE
PROGRAM NAME RETRIEVE-PERSONNEL
SELECT FROM PERSNL WHERE EMPNAME = 'ROGERS PAT' FOR UPDATE
FETCH FROM PERSNL
IF EOF PERSNL
DISPLAY 'EMPLOYEE NOT FOUND'
ELSE
DELETE FROM PERSNL
END-IF
Inserting an SQL Row
The following example illustrates how to insert a new row into a table:
FILE PERSNL SQL (PERSONNEL) UPDATE
SQL INCLUDE (EMPNAME, WORKDEPT, EMPPHONE) +
FROM PERSONNEL LOCATION * NULLABLE
PROGRAM NAME RETRIEVE-PERSONNEL
EMPNAME = 'WIMN GLORIA'
WORKDEPT = 921
EMPPHONE = 3478
INSERT INTO PERSNL
Automatic Retrieval Without a File
In this method of processing, SQL data is retrieved as a result of a specially-coded JOB and SELECT statement
combination. Automatic retrieval without a file is a read-only method that typically uses working storage fields as the
receiving area for the data. This method allows some advanced selection techniques not available for cursors associated
with CA Easytrieve® Report Generator files.
Contents
537
CA Easytrieve® Report Generator 11.6
Processing Requirements
To process data from an SQL table using this method, you must provide the following:
• One or more field definitions for the columns within the tables that you want to retrieve
• These definitions can be coded using the DEFINE statement or by using the SQL INCLUDE statement to automatically
generate the definitions from the SQL catalog. The definitions are usually coded in working storage, but you can define
the fields in an output file for extraction purposes.
• A JOB statement with the INPUT SQL parameter
• SQL signifies that the automatic processing does not involve a CA Easytrieve® Report Generator file.
• A non-file-based SELECT statement that defines the result set for the cursor
• Only one non-file based SELECT statement can be coded in each JOB activity.
This SELECT statement is very different from the file-based SELECT statement used with a CA Easytrieve® Report
Generator SQL file, because it more closely approximates a true SQL SELECT clause. For example, you name the
tables that participate in the result. Also, the SELECT can perform more advanced selections such as UNIONs.
Operation
CA Easytrieve® Report Generator generates and executes a CONNECT statement. You need not code an SQL
CONNECT statement when using CA Easytrieve® Report Generator automatic processing. The user ID and password
parameters are taken from those specified in the USERID parameter of the PARM statement.
CA Easytrieve® Report Generator checks the SQLCODE field following each execution of the SELECT statement. If the
SQLCODE indicates an error, CA Easytrieve® Report Generator issues an error message based on the SQL error and
terminates execution. An SQLCODE indicating end of data causes CA Easytrieve® Report Generator to initiate end-of-
input processing: the FINISH PROC (if any) executes, spooled reports are printed, and the current JOB activity ends.
The SQL cursor that is automatically defined by a non-file-based SELECT statement is closed following the termination of
the JOB activity that opened it.
Retrieving All Columns
The following code retrieves all columns and all rows from the PERSONNEL table. A report is generated showing
WORKDEPT, EMPNAME, and EMPPHONE. CA Easytrieve® Report Generator sorts the report by WORKDEPT. Note the
use of manual null variable indicators.
DEFINE EMPNAME W 20 A
DEFINE WORKDEPT W 2 P 0
DEFINE EMPPHONE W 3 P 0
DEFINE NULLPHONE W 2 B 0 .* NULL INDICATOR
JOB INPUT SQL NAME(SQLEX1)
SELECT * FROM PERSONNEL +
INTO :EMPNAME, :WORKDEPT, :EMPPHONE :NULLPHONE
IF NULLPHONE < 0 .* PHONE PRESENT?
EMPPHONE = 0 .* NO, SET TO 0
END-IF
PRINT PERSNL
REPORT PERSNL LINESIZE 65
SEQUENCE WORKDEPT
LINE WORKDEPT EMPNAME EMPPHONE
538
CA Easytrieve® Report Generator 11.6
Selected Columns
The following code retrieves all rows of selected columns from the PERSONNEL table and generates a report showing
WORKDEPT and EMPNAME. SQL orders the rows by WORKDEPT.
DEFINE EMPNAME W 20 A
DEFINE WORKDEPT W 2 P 0
JOB INPUT SQL NAME(SQLEX2)
SELECT EMPNAME, WORKDEPT +
FROM PERSONNEL +
ORDER BY WORKDEPT +
INTO :EMPNAME, :WORKDEPT
PRINT PERSNL
REPORT PERSNL LINESIZE 65
LINE WORKDEPT EMPNAME
Multiple Tables
The following code retrieves an employee name and the corresponding department name from the PERSONNEL and
DEPARTMENTS tables. This example shows parameters required for SQL/DS.
PARM USERID('SQLDBA' 'SQLDBAPW') +
PREPNAME(EASYOL 'SQLDBA')
DEFINE EMPNAME W 20 A
DEFINE WORKDEPT W 2 P 0
DEFINE EMPPHONE W 3 P 0
DEFINE DEPTNAME W 22 A VARYING
DEFINE DEPTNUMBER W 2 P 0
DEFINE NULLPHONE W 2 B 0 .* NULL INDICATOR
JOB INPUT SQL NAME(SQLEX3)
SELECT EMPNAME, DEPTNAME +
FROM PERSONNEL, DEPARTMENTS +
WHERE WORKDEPT = DEPTNUMBER +
INTO :EMPNAME, :DEPTNAME
PRINT PERSNL
REPORT PERSNL LINESIZE 65
LINE EMPNAME DEPTNAME
Native SQL Processing
This method of processing uses native SQL statements that are equivalent to many of those used in COBOL. Using these
native SQL statements, you can code fully SQL-compliant programs in which you control the SQL cursor operation. All
native SQL statements are prefixed with the SQL keyword. For complete syntax, see the Language Reference section.
This article contains the following information:
Processing Requirements
You must code the SQL DECLARE statement in the Library Definition section of a CA Easytrieve Report
Generator program. You must code all other SQL statements, except SQL INCLUDE, in the Activity Definition section.
539
CA Easytrieve® Report Generator 11.6
You should test the SQLCODE field in the SQLCA to determine whether or not the execution of each controlled
processing statement is successful.
If the SQLCODE field contains a zero (0), you should test the SQLWARN0 field to ensure that no warning conditions were
issued during processing of the SQL statement. To determine acceptable values for SQLWARN0, see the appropriate
SQL reference documentation.
You must code all SQL INCLUDE statements and SQL-managed file definitions before any controlled SQL statements.
Operation
Coding native SQL statements requires an advanced knowledge of SQL statements and of the database to be processed.
You can code native SQL statements in any PROGRAM or JOB activity. You cannot code them in SORT or REPORT
procedures.
Supported SQL Commands
Following is a list of commonly used SQL commands. They must be prefixed by SQL. For a complete list, see
the Language Reference section. For more information, see your SQL vendor reference documentation.
• CLOSE
• COMMIT
• CONNECT
• DECLARE
• DELETE
• FETCH
• INSERT
• OPEN
• PUT
• ROLLBACK
• UPDATE
DB2
All DB2 commands that can be executed using the DYNAMIC execution facilities of DB2 are supported. For more
information, see the SQL reference manual for your current release.
SQL/DS
All SQL/DS commands that are supported through the EXTENDED DYNAMIC facilities of SQL/DS are supported. For
more information, see either of the following manuals:
• SQL/Data System Application Programming for VSE (SH24-5018)
• SQL/Data System Application Programming for VM/SP (SH24-5068)
Advantage Ingres
All Ingres SQL commands that can be executed using the DYNAMIC execution facilities are supported. For more
information, see the Ingres Enterprise Relational Database SQL Reference Guide.
Oracle
All Oracle SQL commands that can be executed using the DYNAMIC execution facilities are supported. For more
information, see the Oracle SQL Reference Guide.
540
CA Easytrieve® Report Generator 11.6
Note: Due to the Oracle restriction against using the CURRENT OF clause with dynamic SQL, CA Easytrieve Report
Generator must mimic the CURRENT OF clause using ROWID. This technique prohibits use of SELECT * in conjunction
with DELETE or UPDATE WHERE CURRENT OF cursor.
Note: Oracle systems are limited to a maximum of 10 cursors.
Unsupported SQL Commands
The following SQL commands cannot be issued using CA Easytrieve Report Generator controlled SQL processing:
• BEGIN DECLARE
• CREATE PROGRAM
• DECLARE STATEMENT
• DECLARE TABLE
• DESCRIBE
• END DECLARE
• EXECUTE
• EXECUTE IMMEDIATE
• PREPARE
• SELECT ... INTO ...
• WHENEVER
The SELECT ...INTO... command is valid when processing DB2 static-only programs. For more information, see
the SQLSYNTAX parameter for the PARM statement.
Note: The SELECT ... INTO ... command (singleton SELECT) can be simulated using CA Easytrieve Report
Generator automatic cursor management.
Retrieving All Columns
The following example retrieves all columns from the PERSONNEL table.
PARM USERID('SQLDBA' 'SQLDBAPW') +
PREPNAME(EASYOL 'SQLDBA')
DEFINE EMPNAME W 20 A
DEFINE WORKDEPT W 2 P 0
DEFINE EMPPHONE W 3 P 0
DEFINE DEPTNAME W 22 A VARYING
DEFINE DEPTNUMBER W 2 P 0
DEFINE NULLPHONE W 2 B 0 .* NULL INDICATOR
DEFINE USERID W 8 A VALUE ('SQLDBA')
DEFINE PASSWORD W 8 A VALUE ('SQLDBAPW')
SQL DECLARE CURSOR1 CURSOR FOR +
SELECT * +
FROM PERSONNEL
JOB INPUT NULL NAME(SQLEX4)
SQL CONNECT :USERID IDENTIFIED BY :PASSWORD
PERFORM CHECKSQL
SQL OPEN CURSOR1
PERFORM CHECKSQL
DO WHILE SQLCODE NE 100. * 1403 FOR ORACLE
SQL FETCH CURSOR1 +
INTO :EMPNAME, :WORKDEPT, :EMPPHONE :NULLPHONE
PERFORM CHECKSQL
541
CA Easytrieve® Report Generator 11.6
IF NULLPHONE < 0 . * PHONE PRESENT?
EMPPHONE = 0 . * NO, SET TO 0
END-IF
IF SQLCODE NE 100 . * NOT END OF TABLE
PRINT PERSNL
END-IF
END-DO
SQL CLOSE CURSOR1
PERFORM CHECKSQL
STOP
CHECKSQL. PROC
IF SQLCODE NE 0 AND SQLCODE NE 100. * 1403 FOR ORACLE
DISPLAY 'SQLCODE = ' SQLCODE
STOP EXECUTE
END-IF
END-PROC
REPORT PERSNL LINESIZE 65
LINE EMPNAME WORKDEPT EMPPHONE
Reassign Departments
The following example reassigns all employees in department 901 to department 109 and displays the names of the
employees. The PARM statement parameters are necessary only if you want to access a DB2 or Ingres database
subsystem other than the default.
PARM SSID('DB2B')
DEFINE EMPNAME W 20 A
DEFINE WORKDEPT W 2 P 0
SQL DECLARE CURSOR1 CURSOR FOR +
SELECT EMPNAME +
FROM PERSONNEL +
WHERE WORKDEPT = 901 +
FOR UPDATE OF WORKDEPT
JOB INPUT NULL NAME(SQLEX5)
SQL CONNECT :USERID IDENTIFIED BY :PASSWORD
PERFORM CHECKSQL
SQL OPEN CURSOR1
PERFORM CHECKSQL
DO WHILE SQLCODE NE 100. * 1403 FOR ORACLE
SQL FETCH CURSOR1 +
INTO :EMPNAME
PERFORM CHECKSQL
IF SQLCODE NE 100 . * 1403 FOR ORACLE
PRINT PERSNL
SQL UPDATE PERSONNEL +
SET WORKDEPT = 109 +
WHERE CURRENT OF CURSOR1
PERFORM CHECKSQL
END-IF
END-DO
SQL CLOSE CURSOR1
PERFORM CHECKSQL
STOP
542
CA Easytrieve® Report Generator 11.6
CHECKSQL. PROC
IF SQLCODE NE 0 AND SQLCODE NE 100. * 1403 FOR ORACLE
DISPLAY 'SQLCODE = ' SQLCODE
STOP EXECUTE
END-IF
END-PROC
REPORT PERSNL LINESIZE 65
LINE EMPNAME
Update Phone Numbers
The following example illustrates how to update a phone system. In this case all phone numbers must be changed to 5
digits. The first character must be a 7 and the rest of the digits remain the same. If an employee does not have a phone
number, his or her record is not updated. No update report is necessary.
JOB INPUT NULL NAME(SQLEX6)
SQL CONNECT :USERID IDENTIFIED BY :PASSWORD
PERFORM CHECKSQL
SQL UPDATE PERSONNEL +
SET EMPPHONE = 70000 + EMPPHONE +
WHERE EMPPHONE IS NOT NULL
PERFORM CHECKSQL
STOP
CHECKSQL. PROC
IF SQLCODE NE 0 AND SQLCODE NE 100. * 1403 FOR ORACLE
DISPLAY 'SQLCODE = ' SQLCODE
STOP EXECUTE
END-IF
END-PROC
Using Table Name as Host Variable with Indicator Array
In this example, INDARRAY is used instead of the default indicator created by the SQL INCLUDE statement. An indicator
is matched for each field in the PERSONNEL table.
PARM USERID('SQLDBA' 'SQLDBAPW') +
PREPNAME(EASYOL 'SQLDBA')
SQL INCLUDE (EMPNAME, WORKDEPT, EMPPHONE) FROM PERSONNEL NULLABLE
DEFINE INDARRAY W 2 B 0 OCCURS 3
SQL DECLARE CURSOR1 CURSOR FOR +
SELECT * FROM PERSONNEL
JOB INPUT NULL NAME(SQLEXT)
SQL CONNECT :USERID IDENTIFIED BY :PASSWORD
PERFORM CHECKSQL
SQL OPEN CURSOR1
PERFORM CHECKSQL
DO WHILE SQLCODE EQ 0
SQL FETCH CURSOR1 +
INTO :PERSONNEL :INDARRAY
PERFORM CHECKSQL
IF INDARRAY(3) < 0
EMPPHONE = 0
END-IF
IF SQLCODE NE 100. * 1403 FOR ORACLE
543
CA Easytrieve® Report Generator 11.6
PRINT PERSNL
END-IF
END-DO
SQL CLOSE CURSOR1
PERFORM CHECKSQL
STOP
CHECKSQL. PROC
IF SQLCODE NE 0 AND SQLCODE NE 100. * 1403 FOR ORACLE
DISPLAY 'SQLCODE = ' SQLCODE
STOP EXECUTE
END-IF
END-PROC
REPORT PERSNL LINESIZE 65
LINE EMPNAME WORKDEPT EMPPHONE
ODBC Data Sources
You can use a CA Easytrieve® Report Generator to access your ODBC data sources. Because of the processing
performed, there are limitations on the activities you can use with data sources.
The following table presents data sources tested by CA Technologies and provides usage notes:
Data Source Usage Notes
Microsoft SQL Server All processing supported
Microsoft Access Does not support UPDATE or DELETE WHERE CURRENT OF
CURSOR.
Microsoft Excel Does not support UPDATE or DELETE WHERE CURRENT OF
CURSOR.
See Access an Excel Spreadsheet as an SQL File for tips on
setup.
Comma-Separated Values Files Read and insert processing only.
See Access a CSV File as an SQL File for tips on setup.
SQL INCLUDE is not supported.
Advantage EDBC All processing supported
DB2 All processing supported
Oracle Does not support UPDATE or DELETE WHERE CURRENT OF
CURSOR.
MySQL Does not support UPDATE or DELETE WHERE CURRENT OF
CURSOR.
Access a CSV File as an SQL File
You can use a Comma-Separated Values (CSV) File as an SQL file in a CA Easytrieve® Report Generator program
using ODBC. Generally, the file supports read access and insert processing only. For more information, see your ODBC
documentation.
Contents
Set Up Your File
To set up your file, you must define your file as an ODBC data source.
544
CA Easytrieve® Report Generator 11.6
Follow these steps:
1. From the Windows Start menu, select Settings, Control Panel, Administrative Tools, Data Sources (ODBC). The
ODBC Data Source Administrator dialog opens.
2. Under the User DSN tab, click Add… and then select Microsoft Text Driver (*.txt, *.csv).
3. Enter a Data Source Name and select the directory where the CSV file resides. Because this Data Source Name
defines the directory, it can be used for all CSV files in the directory.
4. Click Define Format to see a list of all files in the directory.
5. Select your CSV file and set the attributes for the columns in the file. If your file's first row will be used as column
names, check Column Name Header and click Guess to propagate the column list.
Reference Your File in Your CA Easytrieve® Report Generator Program
Follow these steps:
• As the database name in the SSID parameter, specify the ODBC data source name that identifies the directory
containing the CSV file.
• Code your FILE statement, using any name you choose as the file name and the physical file name (including file
extension) as the table name.
Note: This differs from the standard SQL syntax of owner.table.
• Specify field definitions for each column in your file.
Note: Do not use the SQL INCLUDE statement for data definition. Because of the non-standard table name in Step 2,
you cannot use the SQL Catalog interface to generate your field definitions.
You are now ready to access the file by using SQL in your CA Easytrieve® Report Generator program.
Example
The following example shows how to list the fields in a CSV file:
PARM SSID 'MyDocs'
FILE Contacts SQL(Contacts.csv)
LASTNAME * 20 A
FIRSTNAME * 20 A
HOMEPHONE * 15 A
JOB INPUT Contacts
REPORT LINESIZE 80
TITLE 'Contact Information'
LINE LASTNAME FIRSTNAME HOMEPHONE
Access an Excel Spreadsheet as an SQL File
You can use an Excel spreadsheet as an SQL file in a CA Easytrieve® Report Generator program using ODBC.
Contents
Set Up Your Spreadsheet in Excel
Follow these steps:
1. In a new or existing Excel spreadsheet, enter the required column name in the top cell of each column.
Note: These are the column names you reference in your CA Easytrieve® Report Generator program. They must be
valid for CA Easytrieve® Report Generator syntax.
545
CA Easytrieve® Report Generator 11.6
2. From the Tools dropdown menu, select Share Workbook, and then check Allow changes by more than one user at the
same time. The Excel workbook is now shared.
3. Define the SQL table name for the Excel spreadsheet:
a. Highlight all the rows and columns that are to be part of the SQL table.
b. From the Insert dropdown menu, select Name, Define. The Define Name dialog opens.
c. Enter the name of the SQL table to be used in your CA Easytrieve® Report Generator program.
Note: The name must be valid for use in the syntax of a CA Easytrieve® Report Generator program.
4. Define the SQL column name for each Excel spreadsheet column to be used:
a. Highlight an entire column by clicking on the Excel-generated column heading.
b. From the Insert dropdown menu, select Name, Define. The Define Name dialog opens, showing the default name
you entered for this column in Step
c. Click OK to use the default name.
d. Repeat for each column.
5. Define the data format for each column:
a. Highlight an entire column by clicking on the Excel-generated column heading.
b. From the Format dropdown menu, select Cells. The Format Cells dialog opens.
c. From the Category list, select the data format for the SQL column.
6. Save your Excel worksheet. Your SQL table is now defined.
7. Define your Excel spreadsheet as an ODBC Data Source:
a. From the Windows Start menu, select Settings, Control Panel, Administrative Tools, Data Sources (ODBC). The
ODBC Data Source Administrator dialog opens.
b. Under the User DSN tab, click Add… and then select Microsoft Excel Driver (*.xls).
c. Enter a Data Source Name, click the Select Workbook… button, and then find and select your Excel file.
Reference Your Excel Spreadsheet in Your CA Easytrieve® Report Generator Program
Follow these steps:
• Specify the ODBC data source name as the database name in the SSID parameter.
• Code your FILE statement, using any name you choose as the file name and the table name from Step 3 above as the
table name.
• If you use the SQL INCLUDE statement for data definition, run a compile specifying PARM DEBUG(DMAP) to view the
CA Easytrieve® Report Generator field (column) definition attributes. (Excel does not provide detailed field definition
information for all data types.)
You are now ready to access the Excel spreadsheet by using SQL in your CA Easytrieve® Report Generator program.
CA IDMS Database Processing
CA Easytrieve® Report Generator provides optional processing facilities that interface with CA IDMS databases and with
the CA IDMS Integrated Data Dictionary (IDD).
Contents
Processing Overview
The following diagram gives an overview of how CA Easytrieve® Report Generator interacts with a CA IDMS database:
FILE file-name-1 IDMS
RECORD record-name
546
CA Easytrieve® Report Generator 11.6
JOB INPUT (file-name-1) ...
Automatic Input
-------------
| |
RETRIEVE file-name-1 ... ---------------->| <IDMS> |
| |
| |
(<idms> records in <----------| | |
path form for automatic input) | |
... -------------
Controlled Processing
-------------
| |
IDMS statement ... ---------------------->| <IDMS> |
| |
| |
(<idms> controlled <----------| | |
record processing) | |
... -------------
CA IDMS Functionality
CA Easytrieve® Report Generator portability is constrained by CA IDMS portability. Where differences exist, CA
Easytrieve® Report Generator attempts to resolve the difference while still allowing your program to execute. Therefore,
some parameters may be ignored where they do not function.
CA IDMS Statements
The following statements are used to define CA IDMS database activities:
• IDD statements
Retrieve definitions from the Integrated Data Dictionary
• FILE
Identify a CA IDMS database
• RECORD
Describe database records
• LOGICAL-RECORD
Describe logical records
• ELEMENT-RECORD
Describe the database records that are part of a logical record
• RETRIEVE
Describe automatic (path) processing for database records
• SELECT
Describe automatic (path) processing for logical records
• IDMS statements
Provide controlled retrieval and maintenance for both database and logical records
For complete syntax for these statements, see Language Reference.
547
CA Easytrieve® Report Generator 11.6
CA IDMS Interface
The CA IDMS interface provides complete facilities for information retrieval from, and maintenance of, CA IDMS
databases. To use this interface effectively, you should have a basic knowledge of CA IDMS and of the databases to be
processed.
You can access a CA IDMS database in the following ways:
• Using automatic input
• Using controlled processing, which incorporates statements similar to those used in COBOL
With automatic input (also called path processing), you can sweep an entire area of the database or retrieve records
under the control of a tickler file or integrated indexing.
If the IDD interface is not used to generate definitions, the database administrator should build the FILE, RECORD,
LOGICAL-RECORD, ELEMENT-RECORD, and DEFINE statements to describe the subschemas that are used. The
subschema descriptions can then be stored in a CA Easytrieve Report Generator macro library.
When using the CA IDMS interface, you can define subschemas using the following statements:
Statement Description
FILE Identify the database to be processed.
RECORD Identify the database records available for automatic or controlled
processing.
LOGICAL-RECORD Identify the logical records available for automatic or controlled
processing.
ELEMENT-RECORD Identify the element records that comprise the logical record.
See Logical Record Definition in Sample Database and Logical Record for statement examples that can be used by the
database administrator to establish database field definitions. These definitions can then be stored in CA Easytrieve
macros for your access. You can also generate these statements automatically using the IDD interface.
For complete syntax for these statements, see the Language Reference section.
This article includes the following information:
IDMS Communications Block
When the first IDMS FILE statement is encountered, a CA IDMS Communications Block is created in S working storage.
IDMS Communications Block (Mainframe)
The fields that are generated in CA Easytrieve on the mainframe are as follows:
DEFINE IDMSCOM S 216 A
DEFINE IDMSNAME IDMSCOM 8 A, VALUE 'EASYPLUS'
DEFINE IDMSSTATUS IDMSCOM + 8 4 A
DEFINE IDMSKEY IDMSCOM + 12 4 B 0, MASK HEX
DEFINE IDMSREC IDMSCOM + 16 16 A
DEFINE IDMSNODE IDMSCOM + 16 8 A
DEFINE IDMSDB IDMSCOM + 24 8 A
DEFINE IDMSAREA IDMSCOM + 32 16 A
DEFINE IDMSDICTNODE IDMSCOM + 32 8 A
DEFINE IDMSDICTNAME IDMSCOM + 40 8 A
DEFINE IDMSESET IDMSCOM + 48 16 A
548
CA Easytrieve® Report Generator 11.6
DEFINE IDMSEREC IDMSCOM + 64 16 A
DEFINE IDMSEAREA IDMSCOM + 80 16 A
DEFINE IDMSPGINFO IDMSCOM + 96 4 B 0, MASK HEX
DEFINE IDMSPGGRP IDMSCOM + 96 2 B 0, MASK HEX
DEFINE IDMSPGDBK IDMSCOM + 98 2 B 0, MASK HEX
DEFINE IDMSCON IDMSCOM + 96 1 A, OCCURS 100, INDEX IDMSCON-INDEX
DEFINE IDMSCON02 IDMSCOM + 97 1 A. * FINISH
DEFINE IDMSCON03 IDMSCOM + 98 1 A. * ERASE PERMANENT
DEFINE IDMSCON04 IDMSCOM + 99 1 A. * ERASE ALL
DEFINE IDMSCON06 IDMSCOM +101 1 A. * FIND DB-KEY REC
DEFINE IDMSCON07 IDMSCOM +102 1 A. * FIND CURRENT REC
DEFINE IDMSCON08 IDMSCOM +103 1 A. * FIND CURRENT SET
DEFINE IDMSCON09 IDMSCOM +104 1 A. * FIND CURRENT AREA
DEFINE IDMSCON10 IDMSCOM +105 1 A. * FIND NEXT REC SET
DEFINE IDMSCON11 IDMSCOM +106 1 A. * FIND NEXT REC AREA
DEFINE IDMSCON12 IDMSCOM +107 1 A. * FIND PRIOR REC SET
DEFINE IDMSCON13 IDMSCOM +108 1 A. * FIND PRIOR REC AREA
DEFINE IDMSCON14 IDMSCOM +109 1 A. * FIND NEXT SET
DEFINE IDMSCON15 IDMSCOM +110 1 A. * FIND NEXT AREA
DEFINE IDMSCON16 IDMSCOM +111 1 A. * FIND PRIOR SET
DEFINE IDMSCON17 IDMSCOM +112 1 A. * FIND PRIOR AREA
DEFINE IDMSCON18 IDMSCOM +113 1 A. * FIND FIRST REC SET
DEFINE IDMSCON19 IDMSCOM +114 1 A. * FIND FIRST REC AREA
DEFINE IDMSCON20 IDMSCOM +115 1 A. * FIND FIRST SET
DEFINE IDMSCON21 IDMSCOM +116 1 A. * FIND FIRST AREA
DEFINE IDMSCON22 IDMSCOM +117 1 A. * FIND LAST REC SET
DEFINE IDMSCON23 IDMSCOM +118 1 A. * FIND LAST REC AREA
DEFINE IDMSCON24 IDMSCOM +119 1 A. * FIND LAST SET
DEFINE IDMSCON25 IDMSCOM +120 1 A. * FIND LAST AREA
DEFINE IDMSCON30 IDMSCOM +125 1 A. * FIND CURRENT
DEFINE IDMSCON31 IDMSCOM +126 1 A. * FIND OWNER SET
DEFINE IDMSCON32 IDMSCOM +127 1 A. * FIND CALC
DEFINE IDMSCON33 IDMSCOM +128 1 A. * FIND REC SET USING
DEFINE IDMSCON34 IDMSCOM +129 1 A. * GET REC
DEFINE IDMSCON35 IDMSCOM +130 1 A. * MODIFY
DEFINE IDMSCON36 IDMSCOM +131 1 A. * READY UPDATE
DEFINE IDMSCON37 IDMSCOM +132 1 A. * READY RETRIEVAL
DEFINE IDMSCON38 IDMSCOM +133 1 A. * READY UPDATE PROT
DEFINE IDMSCON39 IDMSCOM +134 1 A. * READY RETRIEVE PROT
DEFINE IDMSCON40 IDMSCOM +135 1 A. * READY RETRIEVE EXCL
DEFINE IDMSCON41 IDMSCOM +136 1 A. * READY UPDATE EXCL
DEFINE IDMSCON42 IDMSCOM +137 1 A. * STORE
DEFINE IDMSCON43 IDMSCOM +138 1 A. * GET
DEFINE IDMSCON44 IDMSCOM +139 1 A. * CONNECT
DEFINE IDMSCON46 IDMSCOM +141 1 A. * DISCONNECT
DEFINE IDMSCON48 IDMSCOM +143 1 A. * BIND REC
DEFINE IDMSCON50 IDMSCOM +145 1 A. * FIND DUP
DEFINE IDMSCON51 IDMSCOM +146 1 A. * FIND REC SET CURR USING
DEFINE IDMSCON52 IDMSCOM +147 1 A. * ERASE MEMBER
DEFINE IDMSCON53 IDMSCOM +148 1 A. * ERASE SELECTIVE
DEFINE IDMSCON54 IDMSCOM +149 1 A. * ACCEPT
DEFINE IDMSCON55 IDMSCOM +150 1 A. * ACCEPT RECORD
DEFINE IDMSCON56 IDMSCOM +151 1 A. * ACCEPT AREA
549
CA Easytrieve® Report Generator 11.6
DEFINE IDMSCON57 IDMSCOM +152 1 A. * ACCEPT SET
DEFINE IDMSCON59 IDMSCOM +154 1 A. * BIND SUBSCHEMA
DEFINE IDMSCON60 IDMSCOM +155 1 A. * IF MEMBER
DEFINE IDMSCON62 IDMSCOM +157 1 A. * IF NOMEMBER
DEFINE IDMSCON64 IDMSCOM +159 1 A. * IF EMPTY
DEFINE IDMSCON65 IDMSCOM +160 1 A. * IF NOEMPTY
DEFINE IDMSCON66 IDMSCOM +161 1 A. * COMMIT
DEFINE IDMSCON67 IDMSCOM +162 1 A. * ROLLBACK
DEFINE IDMSCON68 IDMSCOM +163 1 A. * ACCEPT NEXT SET
DEFINE IDMSCON69 IDMSCOM +164 1 A. * ACCEPT PRIOR SET
DEFINE IDMSCON70 IDMSCOM +165 1 A. * ACCEPT OWNER SET
DEFINE IDMSCON71 IDMSCOM +166 1 A. * ACCEPT STATISTICS
DEFINE IDMSCON73 IDMSCOM +168 1 A. * BIND PROCEDURE
DEFINE IDMSCON74 IDMSCOM +169 1 A. * ACCEPT PROCEDURE
DEFINE IDMSCON75 IDMSCOM +170 1 A. * FIND DB-KEY
DEFINE IDMSCON76 IDMSCOM +171 1 A. * FIND NTH REC SET
DEFINE IDMSCON77 IDMSCOM +172 1 A. * FIND NTH REC AREA
DEFINE IDMSCON78 IDMSCOM +173 1 A. * FIND NTH SET
DEFINE IDMSCON79 IDMSCOM +174 1 A. * FIND NTH AREA
DEFINE IDMSCON81 IDMSCOM +176 1 A. * RETURN
DEFINE IDMSCON82 IDMSCOM +177 1 A. * RETURN FIRST
DEFINE IDMSCON83 IDMSCOM +178 1 A. * RETURN LAST
DEFINE IDMSCON84 IDMSCOM +179 1 A. * RETURN NEXT
DEFINE IDMSCON85 IDMSCOM +180 1 A. * RETURN PRIOR
DEFINE IDMSCON86 IDMSCOM +181 1 A. * RETURN USING
DEFINE IDMSCON87 IDMSCOM +182 1 A. * KEEP
DEFINE IDMSCON88 IDMSCOM +183 1 A. * KEEP EXCLUSIVE
DEFINE IDMSCON89 IDMSCOM +184 1 A. * KEEP REC
DEFINE IDMSCON90 IDMSCOM +185 1 A. * KEEP EXCLUSIVE REC
DEFINE IDMSCON91 IDMSCOM +186 1 A. * KEEP SET
DEFINE IDMSCON92 IDMSCOM +187 1 A. * KEEP EXCLUSIVE SET
DEFINE IDMSCON93 IDMSCOM +188 1 A. * KEEP AREA
DEFINE IDMSCON94 IDMSCOM +189 1 A. * KEEP EXCLUSIVE AREA
DEFINE IDMSCON95 IDMSCOM +190 1 A. * COMMIT ALL
DEFINE IDMSCON96 IDMSCOM +191 1 A. * ROLLBACK CONTINUE
DEFINE IDMSCON99 IDMSCOM +194 1 A. * LRF FUNCTION
DEFINE IDMSDIRECT IDMSCOM +196 4 B 0, MASK HEX
DEFINE IDMSRESV IDMSCOM +200 7 N, MASK HEX
DEFINE IDMSFILL IDMSCOM +207 1 N, MASK HEX
DEFINE IDMSOCCUR IDMSCOM +208 4 B 0, MASK HEX
DEFINE IDMSSEQ IDMSCOM +212 4 B 0, MASK HEX
Logical Record Communications Block
When the first Logical Record statement is encountered, a Logical Record Communications Block is created in S working
storage. The fields that are generated are:
DEFINE SLC S 1024 A
DEFINE SUBSCHEMA-LR-CTRL SLC 1024 A
DEFINE LRC-LRPXELNG SLC 2 B
DEFINE LRC-MAXVXP SLC +0002 2 B
DEFINE LRIDENT SLC +0004 4 A
DEFINE LRVERB SLC +0008 8 A
550
CA Easytrieve® Report Generator 11.6
DEFINE LRNAME SLC +0016 16 A
DEFINE LR-STATUS SLC +0032 16 A
DEFINE LR-FILLER-01 SLC +0048 16 A
DEFINE LRPXE SLC +0064 1 A +
OCCURS 960 INDEX LR-PXE-NDX
DEFINE PXE LRPXE 256 A
DEFINE PXENEXT LRPXE 4 B
DEFINE PXETABO LRPXE +0004 2 B
DEFINE PXEDSPL LRPXE +0006 2 B
DEFINE PXEDYN LRPXE +0008 2 B
DEFINE PXEDLEN LRPXE +0010 2 B
DEFINE PXENDEC LRPXE +0012 1 A
DEFINE PXEDTYP LRPXE +0013 1 A
DEFINE PXEOTYP LRPXE +0014 1 A
DEFINE PXEFLAG LRPXE +0015 1 A
DEFINE PXE-FILLER-01 LRPXE +0016 240 A
Logical and Element Records in Non-IDMS Statements
Non-IDMS statements in CA Easytrieve treat database records in much the same way as files. That is, the database
record can be written to a file using the FROM parameter of the PUT or WRITE statement, the contents of the record
buffer can be accessed using the MOVE statement, and the fields of the record can be moved selectively using the MOVE
LIKE statement. In addition, the definitions of all fields defined in the record can be copied to another record or file using
the COPY statement.
For those non-IDMS statements that allow record names to be used, a logical record is treated in exactly the same
manner as a database record.
However, element records are not treated like database records. In non-IDMS statements, element records are treated
as alphanumeric fields. This means that you can use an element record name in any context where you can use an
alphanumeric field.
Automatic Input
Automatic input is a facility whereby CA Easytrieve retrieves information from the database and makes it available to
the program. See Controlled Processing and Automatic Processing for a description of automatic input as it applies to
conventional files. To indicate that automatic input is to occur for a database, you must perform certain steps.
Follow these steps:
1. Code the INPUT parameter on the JOB statement for each activity that requires automatic input from the database.
The INPUT parameter must specify the file name from the FILE statement that defines the subschema. This must be
the only file name specified. CA Easytrieve does not support synchronized file processing for CA IDMS database files.
2. Code either a RETRIEVE statement or a SELECT statement following the JOB statement. Use a RETRIEVE
statement to retrieve database records. Use a SELECT statement for logical records. Only one statement, RETRIEVE
or SELECT, must be coded.
The RETRIEVE and SELECT statements describe the particular portion of the database to be retrieved. CA Easytrieve
performs all the calls needed to retrieve the information described by the automatic input statements. The sequence of
processing for automatic input from a CA IDMS database is shown in the following code:
IF first call
IDMS BIND subschema-name from INPUT file +
PROGRAM-NAME parameter from RETRIEVE/SELECT +
DBNAME parameter from RETRIEVE/SELECT +
NODE parameter from RETRIEVE/SELECT +
551
CA Easytrieve® Report Generator 11.6
DICTNAME parameter from RETRIEVE/SELECT +
DICTNODE parameter from RETRIEVE/SELECT
IDMS BIND FILE file-name RECORD record-name (RETRIEVE only)
... (repeated for each record specified)
IDMS READY ALL RETRIEVAL
END-IF
retrieve next set of information
IF no more information
wrap up reports
STOP
END-IF
... (your program processes the information)
GO TO JOB
The RETRIEVE statement provides for automatic input of CA IDMS databases. Input is accomplished in one of the
following ways:
• By sweeping an entire database area and sequentially processing all occurrences of the root record
• By selectively processing root records through the use of a tickler file or integrated index.
Sweep of an Area
Sweeping an entire database area for all occurrences of the root record provides the default input. OBTAIN NEXT
RECORD WITHIN AREA calls are issued at the root level until the database area has been exhausted. If they are
specified, the INDEX, LIMIT, and WHILE subparameters control the sweep.
Tickler File Control
Optionally, a file of root record keys can control the extent of the database to be processed. The keys are obtained one at
a time from the tickler file. OBTAIN CALC calls are issued for each key in the tickler file. When the tickler file is used, only
CALC records can be the root. The record must have the KEY parameter specified on the RECORD statement.
Input Definition (Paths)
Automatic input of CA IDMS databases depends on the concept of path processing. Each database path, identified by
the SELECT parameter, is processed in a top-to-bottom order. A root record is obtained first, then path access continues
downward through the records coded in the SELECT parameter. When the end of each path is reached, that data is made
available to the program as an input record.
If another path is defined, denoted by a repeated record name or node, that path is then processed until end-of-path.
When all paths for the root have been exhausted, the next root is obtained. Paths can be defined from a member
occurrence to its owner occurrence if owner pointers exist for the set.
If the owner record type is at the higher level, then records at each level of the path below the root are retrieved by using
OBTAIN NEXT RECORD WITHIN SET. If the member record type is specified at the higher level, then OBTAIN OWNER
calls are used. The name of the set to be used must be specified with the SET subparameter of the SELECT parameter
entry for the lower-level record.
Automatic Input of Logical Records
The SELECT statement provides for automatic input of logical records from CA IDMS databases. The input is a sequential
retrieval of all occurrences of a specified logical record that satisfy a user-specified WHERE clause. OBTAIN NEXT
RECORD WHERE calls are issued for the logical record until all records have been retrieved. A logical path is not input if
LR-STATUS is LR-ERROR or LR-NOT-FOUND.
552
CA Easytrieve® Report Generator 11.6
WHERE Clause
To code the Boolean expression required by the WHERE parameter of the SELECT statement, use the syntax required
by CA IDMS for COBOL programs. The only difference is that if the Boolean expression extends over multiple source
records, each record must be continued using the CA Easytrieve conventions. For more information, see the Language
Reference section.
Examples
Processing Two Distinct Paths from a Single Root
This example illustrates path processing. The RETRIEVE statement returns all data to the program for processing.
Information about missing data is also available.
CUSTOMER SALES
CUSTOMER ORDOR OREMARK
FILE DBASE IDMS(DEMOSS03)
RECORD CUSTOMER 104
CUST-NO 1 10 A
CUST-NAME 11 20 A
RECORD ORDOR 40
ORD-NO 1 7 A
ORD-CPO# 8 10 A
RECORD OREMARK 72
ORD-SEQ 1 2 A
ORD-TEXT 3 70 A
RECORD SALES 28
SLS-CUST-NO 1 10 A
JOB INPUT (DBASE) NAME TWO-DISTINCT-PATHS
RETRIEVE DBASE +
SELECT (CUSTOMER AREA 'CUSTOMER-REGION' +
SALES ID 'SA' SET 'CUSTOMER-SALES' +
CUSTOMER +
ORDOR SET 'CUSTOMER-ORDER' +
OREMARK ID 'RE' SET 'ORDER-OREMARK')
IF PATH-ID EQ 'RE'
DISPLAY ORD-TEXT
ELSE
DISPLAY SLS-CUST-NO
END-IF
The first customer record in the area is obtained. The first sales record for the customer is then obtained. If no sales exist,
the order path is processed. If a sale record exists for the customer, the path containing the customer and sales record is
returned to the program. This processing continues until no more sales records exist for the customer. The order path is
then processed.
The first order for the root customer is then obtained, and the first remark for the order. This path is then returned to the
program. Next, the second remark for the first order is obtained and the path is returned. The customer and order records
remain unchanged. Only the remark record is affected. When all remarks for the first order are returned, the next order for
the customer is obtained with all its remarks. This processing continues until all orders and all remarks are obtained and
returned to the program. The second customer root is then obtained and processing continues as described above until all
customer records have been processed.
553
CA Easytrieve® Report Generator 11.6
PATH-ID is used to test which path is returned to the program. When PATH-ID = SA, the customer sales path is available.
When PATH-ID = RE, the customer/order/remark path is available. This program does not process paths for customers
without sales or without orders.
Processing Two Paths with Intermediate Records the Same
Like the previous example, the program in this example also processes two paths. The product, sales, customers, and
order records are all processed. Then the first path specifies that the item records for each order are to be returned and
then the remark records for the same order are returned. Each record also has an ID specified.
PRODUCT SALES CUSTOMER ORDOR ITEM
PRODUCT SALES CUSTOMER ORDOR OREMARK
FILE DBASE IDMS(DEMOSS03)
RECORD CUSTOMER 104
CUST-NO 1 10 A
CUST-NAME 11 20 A
RECORD ORDOR 40
ORD-NO 1 7 A
ORD-CPO# 8 10 A
RECORD OREMARK 72
ORD-SEQ 1 2 A
ORD-TEXT 3 70 A
RECORD SALES 28
SLS-CUST-NO 1 10 A
RECORD PRODUCT 48
PROD-NO 1 8 A
PROD-DESC 9 20 A
RECORD ITEM 3226
ITEM-PROD# 1 8 A
JOB INPUT (DBASE) NAME TWO-PATHS
RETRIEVE DBASE +
SELECT (PRODUCT ID 'PR' AREA 'PRODUCT-REGION' +
SALES ID 'SA' SET 'PRODUCT-SALES' +
CUSTOMER ID 'CU' SET 'CUSTOMER-SALES' +
ORDOR ID 'OR' SET 'CUSTOMER-ORDER' +
ITEM ID 'IT' SET 'ORDER-ITEM' +
ORDOR +
OREMARK ID 'RE' SET 'ORDER-OREMARK')
IF PATH-ID EQ 'RE'
DISPLAY PROD-DESC CUST-NAME ORD-TEXT
END-IF
IF PATH-ID EQ 'IT'
DISPLAY PROD-DESC CUST-NAME ITEM-PROD#
END-IF
In a typical CA IDMS database path, each record can occur multiple times or may not occur at all. Occasionally, you may
want to determine which path is available and which records in the path are available. Based on the previous example, the
information in the following table is provided.
PATH-ID Available RECORD(s)
PR PRODUCT
SA PRODUCT - SALES
554
CA Easytrieve® Report Generator 11.6
CU PRODUCT - SALES - CUSTOMER
OR PRODUCT - SALES - CUSTOMER - ORDOR
IT PRODUCT - SALES - CUSTOMER - ORDOR - ITEM
RE PRODUCT - SALES - CUSTOMER - ORDOR - OREMARK
Tickler File Control of Root Records
The program in this example illustrates path processing using a tickler file to identify the root records to be processed:
FILE DBASE IDMS(DEMOSS03)
RECORD CUSTOMER 104 KEY(CUST-NO)
CUST-NO 1 10 A
CUST-NAME 11 20 A
FILE KEYS
KEY-FLD 1 10 N
JOB INPUT (DBASE) NAME TICKLER-FILE-CONTROL
RETRIEVE DBASE +
KEYFILE KEYS KEYVALUE(CUST-NO = KEY-FLD) +
SELECT (CUSTOMER AREA 'CUSTOMER-REGION')
IF PATH-ID EQ 'NF'
DISPLAY 'ROOT RECORD NOT FOUND FOR ' KEY-FLD
GO TO JOB
END-IF
DISPLAY CUST-NAME
Complete Path Processing
The program in this example illustrates how to bypass certain paths, specifically those paths whose lowest record is not
present. This example selects only complete paths for data processing.
FILE DBASE IDMS(DEMOSS03)
RECORD CUSTOMER 104
CUST-NO 1 10 A
CUST-NAME 11 20 A
RECORD ORDOR 40
ORD-NO 1 7 A
ORD-CPO# 8 10 A
RECORD ITEM 3226
ITEM-PROD# 1 8 A
JOB INPUT (DBASE) NAME COMPLETE-PATH-PROCESSING
RETRIEVE DBASE +
SELECT (CUSTOMER AREA 'CUSTOMER-REGION' +
ORDOR SET 'CUSTOMER-ORDER' +
ITEM ID 'IT' SET 'ORDER-ITEM')
IF PATH-ID NE 'IT'
GO TO JOB
END-IF
DISPLAY CUST-NAME ITEM-PROD#
Limited Record Retrieval
You can use the LIMIT subparameter of the SELECT statement to limit record occurrence retrieval. This example
describes an area sweep where the number of root records retrieved is limited to five for program testing purposes. When
the limit is reached, input processing is terminated.
555
CA Easytrieve® Report Generator 11.6
FILE DBASE IDMS(DEMOSS03)
RECORD SALES 28
SLS-CUST-NO 1 10 A
JOB INPUT (DBASE) NAME RETRIEVAL-LIMIT
RETRIEVE DBASE +
SELECT (SALES AREA 'CUSTOMER-REGION' LIMIT 5)
DISPLAY SLS-CUST-NO
Another reason to limit record retrieval is to inhibit potential redundant calls to CA IDMS. For example, if it is known that
a particular record never occurs more than twice in a path, code LIMIT 2 for that record. This use of LIMIT improves
throughput for database activities.
Conditional Record Retrieval
You can screen any record to establish the acceptability of the record. CA Easytrieve bypasses record occurrences that
fail the acceptance test for input consideration. Use the WHILE condition to control record acceptance.
FILE DBASE IDMS(DEMOSS03)
RECORD CUSTOMER 104
CUST-NO 1 10 A
CUST-NAME 11 20 A
JOB INPUT (DBASE) NAME RECORD-PROCESSING
RETRIEVE DBASE +
SELECT (CUSTOMER AREA 'CUSTOMER-REGION' +
WHILE (CUST-NAME EQ 'JONES'))
DISPLAY CUST-NO
Select Statement
The following shows a logical record select statement.
*
IDD SUBSCHEMA DEMOSSLR SCHEMA DEMOSCHM +
SELECT (CUST-SALES-LR)
*
JOB INPUT DEMOSSLR
SELECT CUST-SALES-LR
*
DISPLAY CUST-NAME +2 SLS-CUST-NO +2 PROD-DESC
Controlled Processing
All valid CA IDMS functions can be performed using the controlled processing commands of the IDMS statement.
Basically, each of these commands generates a call to CA IDMS in much the same manner as a COBOL program. For
information about using these commands, see the appropriate DML Reference section in the CA IDMS Reference. The
first parameter of the IDMS statement identifies the command to be issued. These commands are:
556
CA Easytrieve® Report Generator 11.6
• ACCEPT
• BIND
• COMMIT
• CONNECT
• DISCONNECT
• ERASE
• FIND or OBTAIN
• FINISH
• GET
• IF
• KEEP
• MODIFY
• READY
• RETURN
• ROLLBACK
• STORE
You should test the IDMSSTATUS field in the CA IDMS Communications Block to determine whether the execution of
each controlled processing statement is successful.
IDMS Statement
The IDMS statement provides controlled input/output of a CA IDMS database. You can use the commands of the CA
IDMS statement either with or without the automatic input associated with RETRIEVE or SELECT.
WARNING
To ensure that currency is maintained for automatic input, take care when combining automatic input and
controlled processing.
You can code these statements at any place in a JOB where an I/O statement for any other file can be coded. For
complete syntax for all IDMS statements, see the Language Reference section.
Controlled Processing Examples
The following examples use the CA IDMS test database supplied with your CA IDMS system.
Area Sweep for Record Type
%IDMSCUST. * INVOKE FIELD DEFINITIONS
*
JOB INPUT(NULL), START(SIGN-ON), NAME(AREA-SWEEP)
*
* RETRIEVE FIRST RECORD
IDMS OBTAIN FIRST, RECORD 'CUSTOMER', AREA 'CUSTOMER-REGION'
LOOP
* IF STATUS IS OK, PRINT CUSTOMER NAME
* AND RETRIEVE NEXT RECORD
PERFORM STATUS-CHECK
PRINT AREA-SWEEP
IDMS OBTAIN, NEXT, RECORD 'CUSTOMER', AREA 'CUSTOMER-REGION'
GO TO LOOP
*
SIGN-ON. PROC
*
557
CA Easytrieve® Report Generator 11.6
* BIND THE RUN-UNIT
IDMS BIND 'DEMOSS03'
PERFORM STATUS-CHECK
* ASSIGN RECORD WORK AREA
IDMS BIND, FILE DBASE, RECORD CUSTOMER
PERFORM STATUS-CHECK
* READY THE AREA
IDMS READY, AREA 'CUSTOMER-REGION'
PERFORM STATUS-CHECK
END-PROC
*
STATUS-CHECK. PROC
* IF STATUS NOT OK, TERMINATE PROCESSING
IF IDMSSTATUS NE '0000'
DISPLAY NEWPAGE, 'IDMS STATUS IS ', IDMSSTATUS
IDMS FINISH
STOP
END-IF
END-PROC
*
REPORT AREA-SWEEP LINESIZE(72)
TITLE 'SWEEP OF ''CUSTOMER-REGION'' FOR ALL ''CUSTOMERS'''
LINE CUST-NAME
Record Retrieval Using a Tickler File
%IDMSCUST. * INVOKE FIELD DEFINITIONS
*
FILE KEYFILE
CUSTOMER-KEY 1 10 A
*
JOB INPUT(KEYFILE), START(SIGN-ON), FINISH(SIGN-OFF)
* ESTABLISH KEY AND RETRIEVE RECORD
CUST-NO = CUSTOMER-KEY
IDMS OBTAIN, CALC, RECORD 'CUSTOMER'
* IF "RECORD-NOT-FOUND", INDICATE SO
IF IDMSSTATUS EQ '0326'
CUST-NAME = 'NOT FOUND'
CUST-NO = CUSTOMER-KEY
ELSE
PERFORM STATUS-CHECK
END-IF
* PRODUCE REPORT
PRINT CALC-RPT
*
SIGN-ON. PROC
* BIND THE RUN-UNIT
IDMS BIND 'DEMOSS03'
PERFORM STATUS-CHECK
* ASSIGN RECORD WORK AREA
IDMS BIND, FILE DBASE, RECORD CUSTOMER
PERFORM STATUS-CHECK
* READY THE AREA
IDMS READY, AREA 'CUSTOMER-REGION'
558
CA Easytrieve® Report Generator 11.6
PERFORM STATUS-CHECK
END-PROC
*
STATUS-CHECK. PROC
* IF STATUS NOT OK, TERMINATE PROCESSING
IF IDMSSTATUS NE '0000'
DISPLAY NEWPAGE, 'IDMS STATUS IS ', IDMSSTATUS
IDMS FINISH
END-IF
END-PROC
*
SIGN-OFF. PROC
* SIGN-OFF THE DATA BASE
IDMS FINISH
END-PROC
*
REPORT CALC-RPT LINESIZE(72)
TITLE 'RECORD RETRIEVAL BY CALC KEY'
LINE CUST-NO CUST-NAME
*
Locate all Customer Orders
%IDMSCUST. * INVOKE FIELD DEFINITIONS
*
JOB INPUT(NULL), START(SIGN-ON)
* RETRIEVE FIRST CUSTOMER
IDMS OBTAIN, FIRST, RECORD 'CUSTOMER', AREA 'CUSTOMER-REGION'
GO TO CUSTOMER-CHECK
CUSTOMER-NEXT.
PERFORM STATUS-CHECK
* RETRIEVE NEXT CUSTOMER
IDMS OBTAIN, NEXT, RECORD 'CUSTOMER', AREA 'CUSTOMER-REGION'
* IF "END-OF-AREA", SIGN-OFF
IF IDMSSTATUS EQ '0307'
IDMS FINISH
STOP
END-IF
CUSTOMER-CHECK.
PERFORM STATUS-CHECK
* RETRIEVE FIRST ORDER
IDMS OBTAIN, NEXT, RECORD 'ORDOR' SET 'CUSTOMER-ORDER'
IF IDMSSTATUS EQ '0307'
MOVE SPACES TO ORD-NO ORD-CPO#
PRINT CUST-ORD
GO TO CUSTOMER-NEXT
END-IF
PERFORM STATUS-CHECK
ORDER-NEXT.
PRINT CUST-ORD
*
* RETRIEVE NEXT ORDER AND PRINT
IDMS OBTAIN, NEXT, RECORD 'ORDOR', SET 'CUSTOMER-ORDER'
IF IDMSSTATUS EQ '0000'
559
CA Easytrieve® Report Generator 11.6
GO TO ORDER-NEXT
END-IF
* IF "END-OF-AREA", GET THE NEXT
* CUSTOMER
IF IDMSSTATUS EQ '0307'
GO TO CUSTOMER-NEXT
END-IF
PERFORM STATUS-CHECK
*
SIGN-ON. PROC
* BIND THE RUN-UNIT
IDMS BIND 'DEMOSS03'
PERFORM STATUS-CHECK
* ASSIGN RECORD WORK AREA
IDMS BIND, FILE DBASE, RECORD CUSTOMER
PERFORM STATUS-CHECK
* ASSIGN ORDER WORK AREA
IDMS BIND, FILE DBASE, RECORD ORDOR
PERFORM STATUS-CHECK
* READY THE AREA
IDMS READY, AREA 'CUSTOMER-REGION'
PERFORM STATUS-CHECK
* READY THE AREA
IDMS READY, AREA 'ORDER-REGION'
PERFORM STATUS-CHECK
END-PROC
*
STATUS-CHECK. PROC
* IF STATUS NOT OK, TERMINATE
* PROCESSING
IF IDMSSTATUS NE '0000'
DISPLAY NEWPAGE, 'IDMS STATUS IS ', IDMSSTATUS
IDMS FINISH
STOP
END-IF
END-PROC
*
REPORT CUST-ORD LINESIZE(72), DTLCTL(FIRST)
SEQUENCE CUST-NO
CONTROL FINAL NOPRINT, CUST-NO NOPRINT, CUST-NAME NOPRINT
TITLE 'CUSTOMER ORDERS'
LINE CUST-NO, CUST-NAME ORD-NO, ORD-CPO#
Obtain Logical Record
PARM DEBUG (DMAP)
*
IDD SUBSCHEMA DEMOSSLR SCHEMA DEMOSCHM +
SELECT (CUST-SALES-LR)
*
FILE IDS FB (80 8000)
IDENT 1 4 N
*
JOB INPUT IDS NAME (LROBTAIN) +
560
CA Easytrieve® Report Generator 11.6
START SIGN-ON FINISH SIGN-OFF
*
IDMS OBTAIN NEXT RECORD CUST-SALES-LR +
WHERE (IDENT = CUST-NUMBER)
PERFORM LR-STATUS-CHECK
*
IF LR-STATUS = 'LR-FOUND'
DISPLAY CUST-NAME +2 SLS-CUST-NO +2 PROD-DESC
END-IF
*
SIGN-ON. PROC
IDMS BIND 'DEMOSSLR' DICTNAME 'DICTDB'
PERFORM STATUS-CHECK
IDMS READY
PERFORM STATUS-CHECK
END-PROC
*
SIGN-OFF. PROC
IDMS FINISH
PERFORM STATUS-CHECK
END-PROC
*
STATUS-CHECK. PROC
IF IDMSSTATUS NE '0000'
DISPLAY 'IDMS STATUS ' IDMSSTATUS
DISPLAY 'ERROR DATA: AREA ' IDMSEAREA +
' SET ' IDMSESET ' RECORD ' IDMSEREC
STOP
END-IF
END-PROC
*
LR-STATUS-CHECK. PROC
IF LR-STATUS EQ 'LR-ERROR'
DISPLAY 'LR STATUS ' LR-STATUS ' NAME ' LRNAME +
' VERB ' LRVERB
PERFORM STATUS-CHECK
END-IF
END-PROC
IDD Interface
The interface between CA Easytrieve Report Generator and the CA IDMS Integrated Data Dictionary (IDD) is
accomplished by the use of IDD statements.
This article includes the following information:
IDD Statements
To give you the fullest control over this access, the following IDD statements are provided:
• IDD NAMEControl which dictionary is accessed.
• IDD VERSION
561
CA Easytrieve® Report Generator 11.6
Specify which version of the information is to be retrieved.
• IDD SUBSCHEMA
Retrieve definitions of IDMS files (subschemas).
• IDD FILE
Retrieve definitions of non-IDMS files.
• IDD RECORD
Retrieve definitions of records.
IDD statements generate CA Easytrieve Report Generator library definitions based on the parameters that are coded
on the statement. IDD statement parameters direct the retrieval of data definition information from the IDD and insert
definitions for files, database records, logical records, element records, and fields directly into the product's internal tables.
The actual FILE, RECORD, LOGICAL-RECORD, ELEMENT-RECORD, and DEFINE statements are not generated as
visible source code, and do not appear in the output listing. Instead, the IDD NAME statement simulates the presence of
these statements by storing the information that is obtained from the IDD in the same manner that the statements would.
The DMAP parameter of the PARM statement can be used to obtain a description of the information stored.
NOTE
Syntax for the previous statements is in the Language Reference section.
Program Name
If a subschema has restricted authorization, a properly-registered program name must be supplied to the product. This
program name can be specified on the IDD NAME statement. If the IDD NAME statement is not coded, a default name of
EASYPLUS is used. The default program name would have to have been previously stored in the IDD definition for the
restricted subschema.
Conform IDD Item Descriptions to CA Easytrieve Report Generator Standards
To ensure the correct translation of certain IDD record constructs into CA Easytrieve Report Generator formats, the
following adaptations have been made:
• For an item that occurs multiple times in a record and is supplied with an index, the index name is used as the CA
Easytrieve Report Generator INDEX name. If the index is not supplied in the IDD, the product generates an INDEX
name is by concatenating the item name with the string +INDEX.
• If the item being defined is part of a group item, the relationship between the defined item and its containing group item
is preserved. The group item is defined as a segmented data item. If the group item occurs multiple times, then the
defined item also occurs multiple times.
• Data types that do not conform to the rules of the product are treated as alphanumeric (A) fields.
Handle Group Item Definition
When the IDD interface creates a definition of a group item and its component items, it is possible that an ambiguity might
occur, making the definition unusable by your CA Easytrieve Report Generator program. This ambiguity is created when
a component of the group item and another item within the same database record have identical names. The component
item name, either alone or with the record name as a qualifier, is not sufficient to distinguish between the two items. To
resolve this ambiguity, you can use the group item's name as a qualifier for any item it contains.
Because the group item itself might be part of a larger group item, it is possible for an item that is defined with the IDD
interface to use many levels of qualification. The only limit on the number of levels is the number of levels the IDD allows
you to define for the record definition in the dictionary.
As a result, the syntax of a reference to an item defined with the IDD interface is as follows:
• For an item defined in a database record:
562
CA Easytrieve® Report Generator 11.6
[file-name :] [record-name :] [group-item-name : ...] field-name
• For an item defined in a logical record:
[file-name :] [logical-record-name :] [element-record-name :] +
[group-item-name : ...] field-name
Examples
Defining a Subschema
PARM DEBUG (DMAP)
*
IDD SUBSCHEMA DEMOSS03 SCHEMA DEMOSCHM
*
JOB INPUT NULL
STOP
Defining a Logical Record of a Subschema
PARM DEBUG (DMAP)
*
IDD SUBSCHEMA DEMOSSLR SCHEMA DEMOSCHM +
SELECT (CUST-SALES-LR)
*
JOB INPUT NULL
STOP
Defining Only Select Records from a Subschema
PARM DEBUG (DMAP)
*
IDD VERSION SCHEMA 100
IDD SUBSCHEMA DEMOSS03 SCHEMA DEMOSCHM +
SELECT (SALES OREMARK)
*
JOB INPUT NULL
STOP
Sample Database and Logical Record
This article includes the following information:
Sample CA IDMS Database
The following diagram illustrates a portion of the database that is used in examples in this section. The CA Easytrieve
Report Generator field definitions for this portion follow the diagram.
563
CA Easytrieve® Report Generator 11.6
Figure 44: Database Portion
CUSTOMER ORDOR OREMARK
--------------- --------------- ------------
611|F|104|CALC 620|F|40|CALC 622|V|72|VIA
--------------- --------------- ------------
CUST-NUMBER|DN ORD-NUMBER|DN ORDER-OREMARK
--------------- --------------- ------------
CUSTOMER-REGION ORDER-REGION ORDER-REGION
564
CA Easytrieve® Report Generator 11.6
CUSTOMER-ORDER ORDER-OREMARK
NPO MA NP MA LAST
ASC ORD-DATE-PROM
CUSTOMER-SALES DL
NPO MA
ASC SLS-PROD-NUMBER
SALES ORDER-ITEM
-------------- N MA NEXT
640|F|28|VIA
--------------
CUST-SALES
--------------
CUSTOMER-REGION
PRODUCT-SALES
NPO MA
ASC SLS-CUST-NUMBER
PRODUCT ITEM
-------------- --------------
631|F|48|CALC 621|V|3226|VIA
-------------- --------------
PROD-NUMBER|DN ORDER-ITEM
-------------- --------------
PRODUCT-REGION ORDER-REGION
PRODUCT-ITEM
NPO OA
ASC ITEM-LOG-NUMBER DF
Field Definitions
The following field definitions describe the sample database that is shown in the previous diagram. These definitions are
established by the database administrator and stored in a CA Easytrieve Report Generator macro.
FILE DBASE IDMS(DEMOSS03)
RECORD CUSTOMER 104 KEY(CUST-NO)
CUST-NO 1 10 A
CUST-NAME 11 20 A
RECORD ORDOR 40
ORD-NO 1 7 A
ORD-CPO# 8 10 A
RECORD OREMARK 72
ORD-SEQ 1 2 A
ORD-TEXT 3 70 A
RECORD SALES 28
SLS-CUST-NO 1 10 A
RECORD PRODUCT 48
PROD-NO 1 8 A
PROD-DESC 9 20 A
RECORD ITEM 3226
565
CA Easytrieve® Report Generator 11.6
ITEM-PROD# 1 8 A
Sample Logical Record
A description of the logical record definition for our database example as defined in CA IDMS is as follows:
ADD LOGICAL RECORD NAME IS CUST-SALES-LR
ELEMENTS ARE CUSTOMER
SALES
PRODUCT
COMMENTS.
'********************************'
-' '
-'LR VERBS ALLOWED: ALL '
-' '
-'********************************'
ADD PATH-GROUP OBTAIN CUST-SALES-LR
SELECT FOR FIELDNAME-EQ CUST-NUMBER
OBTAIN EMPLOYEE WHERE CALCKEY EQ CUST-NUMBER
OF REQUEST
ON 0326 CLEAR RETURN LR-NOT-FOUND
OBTAIN EACH SALES WITHIN CUSTOMER-SALES
OBTAIN EACH PRODUCT WITHIN PRODUCT-SALES
SELECT FOR FIELDNAME-EQ PROD-NUMBER
OBTAIN PRODUCT WHERE CALCKEY EQ PROD-NUMBER
OF REQUEST
ON 0326 CLEAR RETURN LR-NOT-FOUND
OBTAIN OWNER WITHIN PRODUCT-SALES
OBTAIN OWNER WITHIN CUSTOMER-SALES
SELECT
OBTAIN EACH CUSTOMER WITHIN CUSTOMER-REGION
OBTAIN EACH SALES WITHIN CUSTOMER-SALES
OBTAIN EACH PRODUCT WITHIN PRODUCT-REGION
ADD PATH-GROUP MODIFY CUST-SALES-LR
SELECT
MODIFY SALES.
ADD PATH-GROUP ERASE CUST-SALES-LR
SELECT
ERASE SALES.
566
CA Easytrieve® Report Generator 11.6
ADD PATH-GROUP STORE CUST-SALES-LR
SELECT
STORE SALES.
Logical Record Definition
The field definitions that follow describe the sample logical record. These definitions are established by the database
administrator and stored in a CA Easytrieve Report Generator macro.
*
IDD NAME DBNAME 'TSTDICT'
*
FILE DEMOSSLR IDMS (DEMOSSLR)
LOGICAL-RECORD CUST-SALES-LR
ELEMENT-RECORD CUSTOMER
CUST-NUMBER 1 10 A
CUST-NAME 11 20 A
ELEMENT-RECORD SALES
SLS-CUST-NO 1 10 A
ELEMENT-RECORD PRODUCT
PROD-NUMBER 1 8 A
PROD-DESC 9 20 A
*
JOB INPUT NULL
STOP
IMS/DLI Database Processing
The IMS/DL/I interface provides complete facilities for information retrieval and maintenance of IMS/DL/I databases.
To use this interface efficiently, you should have a basic knowledge of IMS/DL/I and of the databases to be processed.
Preparatory work by the database administrator significantly reduces the effort of writing programs that process
databases.
The database administrator should place the data definition statements necessary to process each database into the CA
Easytrieve Report Generator macro library. Control of these segment and field definition statements can greatly reduce
the number of simple programming errors that are associated with database processing.
This section discusses CA Easytrieve Report Generator database processing requirements in detail. The four statements
that define database activities are described in the Language Reference section:
• FILE statement -- Identifies the database.
• RECORD statement -- Identifies the database segments that are available for processing.
• RETRIEVE statement -- Describes automatic database input.
• DLI statement -- Provides controlled processing for the creation, retrieval, and maintenance of a database.
CA Easytrieve® Report Generator cannot access PSBs generated with a language type of PL/I; a language type of
ASSEM or COBOL is required.
The Automatic Input article describes how automatic input uses the RETRIEVE statement in these ways:
• Sweep of a database
• Tickler file control
• Input definition (paths)
567
CA Easytrieve® Report Generator 11.6
Test Database
The source statement samples that follow show database definition statements (DBD) and program specification block
(PSB) statements that describe the database that is referenced throughout this section. The database is a portion of the
PARTS test database that is provided by IBM with the IMS system. For more information about the database, see the
IBM IMS/VS Installation Guide. For information about the test database for DLI DOS/VS, see the IBM Guide for New
Users. This section uses only the OS/IMS test database that is shown in the diagram in the Test Database Structure
section.
This article includes the following information:
DBD Source Statements
DBD NAME=DI21PART,ACCESS=(HISAM,ISAM)
DATASET DD1=DI21PART,DEVICE=3330,OVFLW=DI21PARO
SEGM NAME=PARTROOT,PARENT=0,BYTES=50,FREQ=250
FIELD NAME=(PARTKEY,SEQ),TYPE=C,BYTES=17,START=1
SEGM NAME=STANINFO,PARENT=PARTROOT,BYTES=85,FREQ=1
FIELD NAME=(STANKEY,SEQ),TYPE=C,BYTES=2,START=1
SEGM NAME=STOKSTAT,PARENT=PARTROOT,BYTES=160,FREQ=2
FIELD NAME=(STOCKEY,SEQ),TYPE=C,BYTES=16,START=1
SEGM NAME=CYCCOUNT,PARENT=STOKSTAT,BYTES=25,FREQ=1
FIELD NAME=(CYCLKEY,SEQ),TYPE=C,BYTES=2,START=1
SEGM NAME=BACKORDR,PARENT=STOKSTAT,BYTES=75,FREQ=0
FIELD NAME=(BACKKEY,SEQ),TYPE=C,BYTES=10,START=1
DBDGEN
PSB Source Statements
PCB TYPE=DB,DBDNAME=DI21PART,PROCOPT=A,KEYLEN=43
SENSEG PARTROOT
SENSEG STANINFO,PARTROOT
SENSEG STOKSTAT,PARTROOT
SENSEG CYCCOUNT,STOKSTAT
SENSEG BACKORDR,STOKSTAT
PSBGEN LANG=ASSEM,PSBNAME=EZTPPSBA
Test Database Structure
An illustration of the test database structure follows.
568
CA Easytrieve® Report Generator 11.6
Figure 45: Test Database Structure
PCB and PSB Processing
CA Easytrieve Report Generator uses the Call DLI interface to access an IMS/DLI database. ASMTDLI is statically linked
with your CA Easytrieve Report Generator program when you run a batch compile. For more information about program
linkage, see the Using section.
PCB Specification and Access
Regardless of the execution environment, the PCB to be processed is specified on the FILE statement. For a complete
description, see FILE Statement. Field definitions immediately following the FILE statement map the specified PCB. All
PCB fields can be accessed in a CA Easytrieve Report Generator program.
PSB Specification
In batch and TSO environments, the PSB name is passed to IMS/DLI as a parameter on the statement that executes the
DFSRRC00 program. When your CA Easytrieve Report Generator program begins executing, the PCB specified on the
FILE statement is found in the PSB by the CA Easytrieve® Report Generator library routines and made available to your
program automatically.
In CICS, your program must explicitly schedule a PSB before any DLI file can be accessed. The DLI PCB statement must
be used to schedule a PSB. For a complete description, see DLI Statement. For information about PSB scheduling and
terminating, see the IBM CICS Application Programmer's Reference Manual.
After a DLI PCB statement is executed, all DLI files in the CA Easytrieve Report Generator program are accessible. The
DLI PCB statement must be executed even when automatic input (the RETRIEVE statement) is being used to read the
database. Because the PSB can only be scheduled once, the DLI PCB statement should be placed in a JOB START proc,
or in some other one-time only code. When all DLI processing is finished, use the DLI TERM statement to terminate the
PSB. If this is not done, the PSB remains scheduled until task termination.
Note: In non-CICS environments, the DLI PCB and DLI TERM statements have no effect.
569
CA Easytrieve® Report Generator 11.6
Status Information
After each DLI operation, the PCB Status Code field is placed in the CA Easytrieve Report Generator system-defined
field, FILE-STATUS. For the definition of the status code values, see the IBM DLI Programmer's Reference Manual.
In CICS, two additional system-defined fields are supplied to give additional status data: UIBFCTR and UIBDLTR. Each is
a 1-byte binary field. The value of each field is copied directly from the same-named UIB fields after each DLI operation.
For a definition of the UIB field values, see the IBM CICS Application Programmer's Reference Manual.
In non-CICS environments, UIBFCTR and UIBDLTR contain zeros.
Automatic Input
Automatic input is a facility whereby CA Easytrieve Report Generator retrieves records from the database and makes
them available to the program. For a description of automatic input as it applies to conventional files, see Controlled
Processing and Automatic Processing.
This article contains the following information:
Automatic Input
To indicate that automatic input is to occur for the IMS/DLI database, you must perform certain steps.
Follow these steps:
1. Code the INPUT parameter on the JOB statement for each activity that will require automatic input from the database.
The INPUT parameter must specify the file name from the FILE statement that defines the IMS/DLI file. This must be
the only file name specified. CA Easytrieve Report Generator does not support synchronized file processing for IMS/
DLI database files.
2. Code a RETRIEVE statement following the JOB statement. Only one RETRIEVE statement must be coded.
The RETRIEVE statement with SELECT parameters describes the particular portion of the database to be retrieved. CA
Easytrieve Report Generator performs all the DLI calls needed to retrieve the records described by the automatic input
statements. Automatic input is either a sweep of the entire database or a selection of root statements through the use of a
tickler file.
Sweeping the Database
Sweeping the entire database provides the default input. A get next (GN) call is issued at the root level until the database
has been exhausted. LIMIT, SSA, or WHILE parameters, if specified, control the sweep.
Tickler File Control
Optionally, a file of root segment keys can control the extent of the database to be processed. Root segment keys are
obtained one at a time from the tickler file. Get unique (GU) calls are issued for each key on the tickler file. The KEY
parameter must be specified on the RECORD statement for the root segments retrieved by the tickler file option.
Input Definition (Paths)
Automatic input of IMS/DLI databases depends upon the concept of path processing. Each database path identified with
the SELECT parameter is processed in a top-to-bottom, front-to-back, and left-to-right order. A root segment is accessed
first, with path accessing continuing downward to the left until the end of the path. When the end of each path is reached,
that data is made available to the program as an input record. The following diagram illustrates the paths in a portion of
the test database. Path-id is enclosed in parentheses ( ) above the field-name:
570
CA Easytrieve® Report Generator 11.6
Figure 46: Paths in a Portion of the Test Database
INPUT PARTROOT STOKSTAT CYCCOUNT BACKORDR
RECORD DATA DATA DATA DATA
1 02N51P3003F0 0025906026 20
2 02N51P3003F0 0025906026 21
3 02N51P3003F0 0025906026 30
4 02RC07GF273J 00...
CA Easytrieve® Report Generator exhausts each path before proceeding to the next path. When it exhausts the last path,
it retrieves the next root and processing begins again with the leftmost path.
Typical Path Examples
The following series of path processing examples illustrates the functions of the various statements and parameters
associated with automatic database input. The examples are based upon the Test Database Structure in this section.
Each example also relies upon the following data definition:
FILE DLIFILE DLI(DI21PART 1)
DBD-NAME 1 8 A
SEG-LEVEL 9 2 A
STATUS-CODE 11 2 A
571
CA Easytrieve® Report Generator 11.6
PROC-OPTIONS 13 4 A
RESERVE-DL1 17 4 B
SEG-NAME-FB 21 8 A
LENGTH-FB-KEY 29 4 B
NUMB-SENS-SEGS 33 4 B
KEY-FB-AREA 37 43 A
*
RECORD PARTROOT 50 KEY(PARTKEY 1 17)
PARTKEY 1 17 A
PART-NUMBER 1 17 A
PART-DESC 27 24 A
*
RECORD STANINFO 85 PARTROOT KEY(STANKEY 1 2)
STANKEY 1 2 A
STAN-MAKE-DEPT 48 6 A
STAN-MAKE-TIME 62 3 A
*
RECORD STOKSTAT 160 PARTROOT KEY(STOCKEY 1 16)
STOKKEY 1 16 A
STOK-ON-ORDER 106 8 N
STOK-IN-STOCK 114 8 N
*
RECORD CYCCOUNT 25 STOKSTAT
CYCLKEY 1 2 A
*
RECORD BACKORDR 75 STOKSTAT
BACKKEY 1 2 A
BACK-Q1 11 13 A
Tickler File Usage Example
This example illustrates path processing using a tickler file to identify the root segments to be processed:
FILE DLIFILE DLI (DI21PART 1)
RECORD PARTROOT 50 KEY(PARTKEY 1 17)
PARTKEY 1 17 A
PART-NUMBER 1 17 A
PART-DESC 27 24 A
FILE KEYS
KEY 1 17 A
JOB INPUT (DLIFILE) NAME MYPROG
RETRIEVE DLIFILE +
KEYFILE KEYS, +
KEYVALUE KEY, +
SELECT PARTROOT
IF PATH-ID EQ 'NF'
DISPLAY 'ROOT NOT FOUND FOR ' KEY
ELSE
DISPLAY PART-NUMBER PART-DESC
END-IF
572
CA Easytrieve® Report Generator 11.6
Segment Selection Examples
Segment selection must include complete paths. Therefore, knowledge of the logical structures of a database is
mandatory. The following examples illustrate the results of various SELECT parameters.
Root-only Processing
...
RETRIEVE DLIFILE ... +
SELECT (PARTROOT)
...
...
Two Path, One Parent Example
...
RETRIEVE DLIFILE ... +
SELECT (PARTROOT +
STANINFO +
STOKSTAT)
...
paths are: 1 - PARTROOT AND STANINFO
2 - PARTROOT AND STOKSTAT
Two Path, Two Parent Example
...
RETRIEVE DLIFILE ... +
SELECT (PARTROOT ID 'A' +
STOKSTAT ID 'AC' +
CYCCOUNT ID 'CE' +
BACKORDR ID 'CF')
...
paths are: 1 - PARTROOT AND STOKSTAT AND CYCCOUNT
2 - PARTROOT AND STOKSTAT AND BACKORDR
Path Identification Example
In a typical IMS/DLI database path, each segment can occur multiple times, or it may not occur at all. It is often desirable
to be able to determine not only which path is available, but also which segments in the path are available. Based upon
the previous Two Path, One Parent Example, the following information is provided:
PATH-ID Value Segments Available
A PARTROOT
AC PARTROOT - STOKSTAT
CE PARTROOT - STOKSTAT - CYCCOUNT
CF PARTROOT - STOKSTAT - BACKORDR
573
CA Easytrieve® Report Generator 11.6
Complete Path Processing with Schedule and Terminate
Consider the following example in which we want to process data only from a complete path. That is, when the lowest
segment in the path is not present, we want to bypass processing the path altogether.
FILE DLIFILE DLI (DI21PART 1)
RECORD PARTROOT 50 KEY(PARTKEY 1 17)
PARTKEY 1 17 A
PART-NUMBER 1 17 A
PART-DESC 27 24 A
RECORD STOKSTAT 160 PARTROOT KEY(STOKKEY 1 16)
STOKKEY 1 17 A
STOK-ON-ORDER 1 17 A
STOK-IN-STOK 27 24 A
RECORD BACKORDR 75 STOKSTAT
BACKKEY 1 2 A
BACK-Q1 11 13 A
JOB INPUT (DLIFILE) NAME MYPROG START INITPSB FINISH TERMPSB
RETRIEVE DLIFILE +
SELECT (PARTROOT +
STOKSTAT +
BACKORDR ID 'CF')
IF PATH-ID NE 'CF'
GO TO JOB
END-IF
DISPLAY PART-NUMBER PART-DESC BACK-Q1
INITPSB. PROC
DLI PCB 'EZTPPSBA'
END-PROC.
TERMPSB. PROC
DLI TERM
END-PROC
Note: The DLI PCB and DLI TERM statements are required only in CICS environments. They are ignored in non-CICS
environments.
Limiting Segment Retrieval
You can use the LIMIT subparameter of SELECT to limit segment occurrence retrieval. The following example describes
an area sweep where the number of root segments retrieved is limited to five for program testing purposes. When the limit
is reached, input processing is terminated.
FILE DLIFILE DLI (DI21PART 1)
RECORD PARTROOT 50 KEY(PARTKEY 1 17)
PARTKEY 1 17 A
PART-NUMBER 1 17 A
PART-DESC 27 24 A
JOB INPUT (DLIFILE) NAME MYPROG
RETRIEVE DLIFILE +
SELECT (PARTROOT LIMIT 5)
DISPLAY PART-NUMBER PART-DESC
574
CA Easytrieve® Report Generator 11.6
Another example of limiting segment retrieval is its use to inhibit potential redundant calls to IMS/DLI. For example, if it is
known that a particular segment never occurs more than two times in a path, code LIMIT 2 for that segment. This use of
LIMIT improves performance for database activities.
Root Segment Qualification Input Control
You can qualify root segments for retrieval by using the SSA subparameter of SELECT. The value supplied with SSA is
enclosed within parentheses and concatenated with the segment-name to produce the root segment's SSA. The following
example illustrates the control of input through root segment qualification. Processing terminates when IMS/DLI returns a
status-code indicating that the qualification cannot be satisfied.
FILE DLIFILE DLI (DI21PART 1)
RECORD PARTROOT 50 KEY(PARTKEY 1 17)
PARTKEY 1 17 A
PART-NUMBER 1 17 A
PART-DESC 27 24 A
JOB INPUT (DLIFILE) NAME MYPROG
RETRIEVE DLIFILE +
SELECT (PARTROOT SSA 'PARTKEY = 02N51P3003F000 ')
DISPLAY PARTKEY PART-NUMBER PART-DESC
Conditional Segment Retrieval (Segment Prescreening)
You can prescreen any segment to establish the acceptability of the segment. CA Easytrieve Report Generator bypasses
segment occurrences that fail the acceptance test for input consideration. Use the WHILE condition when the Boolean
logic of IMS/DLI is inadequate for root SSA qualification or for segment qualification below the root level. The following
example demonstrates a segment prescreen that is unavailable through normal IMS/DLI interfaces:
FILE DLIFILE DLI (DI21PART 1)
RECORD PARTROOT 50 KEY(PARTKEY 1 17)
PARTKEY 1 17 A
PART-NUMBER 1 17 A
PART-DESC 27 24 A
JOB INPUT (DLIFILE) NAME MYPROG
RETRIEVE DLIFILE +
SELECT (PARTROOT WHILE (PART-DESC ALPHABETIC))
DISPLAY PART-NUMBER +3 PART-DESC
Controlled Processing Using DLI Statements
You perform IMS/DLI functions using the DLI statement. This statement generates a call to IMS/DLI that is identical to that
generated by other programming languages. It is essential that you test the status-code returned in the PCB to determine
the success of each DLI statement. For information about these return codes, see the IMS/DLI Applications Programming
Manual. The following examples illustrate typical use of DLI statements.
WARNING
You must exercise caution when using the DLI statement in conjunction with RETRIEVE. You should save and
restore database positioning to ensure the correct continuation of automatic input. Otherwise, input data can be
lost or repeated.
In all the following examples, if the execution environment is CICS, the PSB must be scheduled using the DLI PCB
statement before the database is accessed using the DLI or RETRIEVE statement. If the execution environment is not
CICS, the DLI PCB and DLI TERM statements have no effect.
575
CA Easytrieve® Report Generator 11.6
This article includes the following information:
Repositioning Databases with Schedule and Terminate
When accessing a database in multiple JOBs, it is your responsibility to reposition the database to where processing is to
begin in each JOB 2 to JOB n. In the following code for repositioning databases with schedule and terminate, processing
is to begin at the start of the database. Using the START procedure on the JOB statement means that DLI statements can
be issued to reposition the database at its beginning.
FILE DLIFILE DLI (DI21PART 1)
RECORD PARTROOT 50 KEY(PARTKEY 1 17)
PARTKEY 1 17 A
PART-NUMBER 1 17 A
PART-DESC 27 24 A
RECORD STOKSTAT 160 PARTROOT KEY(STOKKEY 1 16)
STOKKEY 1 17 A
STOK-ON-ORDER 1 17 A
STOK-IN-STOK 27 24 A
RECORD BACKORDR 75 STOKSTAT
BACKKEY 1 2 A
BACK-Q1 11 13 A
JOB INPUT (DLIFILE) NAME MYPROG START INITPSB
RETRIEVE DLIFILE +
SELECT (PARTROOT +
STOKSTAT +
BACKORDR ID 'CF')
IF PATH-ID NE 'CF'
GO TO JOB
END-IF
DISPLAY PART-NUMBER BACK-Q1
INITPSB. PROC
DLI PCB 'EZTPPSBA'
END-PROC
JOB INPUT (DLIFILE) START BEGIN NAME MYPROG2 FINISH TERMPSB
RETRIEVE DLIFILE +
SELECT (PARTROOT STOKSTAT ID 'SS')
IF PATH-ID EQ 'SS'
DISPLAY STOK-ON-ORDER
END-IF
*
BEGIN. PROC
DLI DLIFILE PARTROOT 'GU ' +
SSA 'PARTROOT(PARTKEY =>99999999999999999)'
DLI DLIFILE PARTROOT 'GN'
END-PROC
TERMPSB. PROC
DLI TERM
END-PROC.
576
CA Easytrieve® Report Generator 11.6
Complete Path Processing
The following example illustrates the DLI statements necessary to produce the same input data as is produced by the
automatic input of the Complete Path Processing example in Automatic Input.
SSA-PART W 37 A VALUE 'PARTROOT(PARTKEY = XXXXXXXXXXXXXXXXX)'
SSA-PART-DATA SSA-PART +19 17 A
SSA-STOK W 36 A VALUE 'STOKSTAT(STOCKEY = XXXXXXXXXXXXXXXX)'
SSA-STOK-DATA SSA-STOK +19 16 A
...
JOB INPUT (NULL)
DLI DLIFILE PARTROOT 'GN'
IF FILE-STATUS EQ 'GE', 'GB'
STOP
END-IF
IF FILE-STATUS NOT SPACE
DISPLAY 'JOB TERMINATED, CODE = ' FILE-STATUS
STOP
END-IF
NEXT-STOK
SSA-PART-DATA = PARTKEY
DLI DLIFILE STOKSTAT 'GNP ' SSA (SSA-PART, +
'STOKSTAT ')
IF FILE-STATUS EQ 'GE'
GO TO JOB
END-IF
IF FILE-STATUS NOT SPACE
DISPLAY 'JOB ...'
STOP
END-IF
NEXT-BACK
SSA-STOK-DATA = STOK-KEY
DLI DLIFILE BACKORDR 'GNP ' SSA (SSA-PART, +
SSA-STOK, +
'BACKORDR ')
IF FILE-STATUS EQ 'GE'
GO TO NEXT-STOK
END-IF
IF FILE-STATUS NOT SPACE
DISPLAY 'JOB ... '
STOP
END-IF
...
process data base path
...
GO TO NEXT-BACK
Database Maintenance
You can perform complete database maintenance using the DLI statement. One of the programming techniques used in
association with database maintenance is usually the dynamic construction and use of SSAs.
577
CA Easytrieve® Report Generator 11.6
Creation of IMS/DLI Calls
This example depicts some of the basic programming necessary to dynamically create IMS/DLI calls.
...
SSA-COUNT W 4 B
FUNCTION W 4 A
*
SSA-ROOT W 37 A VALUE 'PARTROOT(PARTKEY = XXXXXXXXXXXXXXXXX)'
SSA-ROOT-QUAL SSA-ROOT +8 1 A
SSA-ROOT-DATA SSA-ROOT +19 17 A
*
SSA-LVL2 W 23 A VALUE 'STANINFO(STANKEY = XX)'
SSA-LVL2-SEG SSA-LVL2 8 A
SSA-LVL2-QUAL SSA-LVL2 +8 1 A
SSA-LVL2-KEY SSA-LVL2 +9 8 A
SSA-LVL2-DATA SSA-LVL2 +19 2 A
...
JOB ...
...
SSA-COUNT = 1
SSA-ROOT-QUAL = ' '
FUNCTION = 'GN '
DLI DLIFILE PARTROOT FUNCTION SSANO SSA-COUNT SSA(SSA-ROOT)
PERFORM TEST-STATUS
SSA-ROOT-QUAL = '('
SSA-ROOT-DATA = PARTKEY
FUNCTION = 'GNP '
SSA-LVL2-SEG = 'STANINFO'
SSA-LVL2-QUAL = ' '
SSA-COUNT = 2
PERFORM DLI-CALL
IF FILE-STATUS ...
...
ELSE
PERFORM TEST-STATUS
END-IF
...
DLI-CALL. PROC
DLI DLIFILE STANINFO FUNCTION +
SSANO SSA-COUNT +
SSA (SSA-ROOT, +
SSA-LVL2, +
...)
END-PROC
TEST-STATUS. PROC
IF FILE-STATUS ...
...
END-IF
END-PROC.
...
...
578
CA Easytrieve® Report Generator 11.6
Basic Database Maintenance Activity
This example shows basic activities that do not require the sophistication of dynamic call generation.
...
... ...
DLI DLIFILE PARTROOT 'GHN '
IF FILE-STATUS EQ 'GE'
STOP
ELSE
PERFORM TEST-STATUS
END-IF
IF PARTKEY ...
DLI DLIFILE PARTROOT 'DLET'
PERFORM TEST-STATUS
END-IF
IF FILE-STATUS SPACES
PRINT
END-IF
...
TEST-STATUS. PROC
IF FILE-STATUS NOT SPACE
DISPLAY ...
...
STOP
END-IF
END-PROC
...
...
IMS Fast Path DEDB Processing
IMS Fast Path DEDBs can be processed by CA Easytrieve Report Generator programs.
WARNING
Your program must include a CHKP call before terminating, otherwise an IMS U1008 user abend will occur.
Example
In this example, F99D is an IMS Program Specification Block (PSB) associated with a Fast Path DEDB. Observe the
placement of the CHKP call.
FILE FPDEDB DLI F99D
RECORD F99DS1 20
F99DS1K 1 10 A
F99DF1D 11 10 A
RECORD F99DS2 20 F99DS1
F99DS2K 1 10 A
F99DF2D 11 10 A
RECORD F99DS3 20 F99DS1
F99DS3K 1 10 A
F99DF3D 11 10 A
579
CA Easytrieve® Report Generator 11.6
*
DEFINE IMSSTAT W 8 A
*
JOB INPUT FPDEDB FINISH TERM-PROC
RETRIEVE FPDEDB +
SELECT ( F99DS1 ID 'S1' +
F99DS2 ID 'S2' +
F99DS3 ID 'S3' )
DISPLAY F99DS1K ' ' PATH-ID
TERM-PROC. PROC
DLI CHKP IMSSTAT
DISPLAY HEX CHKP-STATUS
END-PROC
CA Datacom/DB Database Processing
The CA Datacom/DB interface option lets you access your CA Datacom/DB database.
Required Knowledge
To use this interface, you must know how to use CA Datacom/DB and know the layout of the database that you want
processed. Specifically, you must know:
• The purpose and syntax of the commands common to CA Datacom/DB.
• The contents of the database.
• How the data is organized within the database.
• What elements of data you can read and/or update.
Such knowledge makes the task of accessing the database much simpler.
Preparatory Work
Preparatory work by your database administrator significantly reduces the effort of writing the CA Easytrieve Report
Generator programs that access CA Datacom/DB databases. The database administrator should place the data definition
statements necessary to access each element in the database into the CA Easytrieve® Report Generator macro library.
Keeping these element field definition statements within the control of the database administrator can greatly reduce the
number of programming errors that are associated with database processing. See Access Macros for examples that use
the test database that is supplied with CA Datacom/DB.
How the Interface Works
CA Easytrieve® Report Generator communicates with CA Datacom/DB through the User Requirements Table and the CA
Datacom/DB interface module, ETDTCM. The CALL statement or the EXIT parameter of the FILE statement invokes the
ETDTCM routine. The ETDTCM routine links CA Easytrieve® Report Generator and CA Datacom/DB.
The ETDTCM routine communicates with a driver routine named ETDRVR (supplied by CA Technologies). You must link-
edit ETDRVR with the User Requirement Tables produced by your database administrator. The installation instructions for
this interface are discussed in the Installing section.
Access the Database
You can access the database with automatic processing or controlled processing, using control macros similar to
statements used in COBOL.
580
CA Easytrieve® Report Generator 11.6
Automatic Processing
With automatic processing, you sequentially retrieve all or part of a table within any defined CA Datacom/DB key.
Automatic processing uses the EXIT parameter of the FILE statement. The EXIT parameter of the FILE statement
automatically links with the assembler routine that enables CA Easytrieve Report Generator and CA Datacom/DB to
communicate. The name of this routine is ETDTCM.
Controlled Processing
With controlled processing, you can perform any retrieval process (for example, sequential access and/or random access)
on all or part of a table. Just use the CALL statement to link to the ETDTCM routine that enables CA Easytrieve Report
Generator and CA Datacom/DB to communicate.
NOTE
Never mix automatic and controlled processing in the same CA Easytrieve Report Generator job activity. This
is because automatic processing automatically performs functions that are not automatically performed under
controlled processing.
Access Macros
The CA Datacom/DB interface option uses a series of macros that access CA Datacom/DB and eliminate the need for
much of the user coding. These macros fall into two categories:
• Macros that generate parameter areas that CA Datacom/DB requires.
• Macros that generate the appropriate calls to CA Datacom/DB.
NOTE
For more information about CA Datacom/DB, see the Programming section in the CA Datacom/DB
documentation.
This article includes the following information:
Generating Parameter Areas
The following macros generate parameter areas that CA Datacom/DB requires. You must code these macros in the library
section of each CA Easytrieve Report Generator program that accesses CA Datacom/DB:
• %DBUIB defines the User Information Block (UIB) for communication with CA Datacom/DB. Use this macro for
automatic or controlled processing.
• %DBRA defines the Request Area for communication with CA Datacom/DB. Use this macro for automatic or controlled
processing.
• %DBEL defines the Element List for communication with CA Datacom/DB. Use this macro for automatic or controlled
processing.
• %DBWA defines the Work Area for communication with CA Datacom/DB. This macro is used only for controlled
processing, because the %DBFILE macro automatically generates an equivalent work area.
Refer to the table in Macro Synopsis for a summary of each macro.
NOTE
The %DBRA, %DBEL, and %DBWA macros each define parameter areas that CA Datacom/DB requires. For
automatic processing, the prefixes to all three of these macros must be identical. A matched set occurs when all
three prefixes are the same.
581
CA Easytrieve® Report Generator 11.6
Generating Calls
The following macros generate the appropriate calls to CA Datacom/DB.
• %DBFILE generates the FILE statement that you use during automatic processing. Code this macro immediately
before the Job statement in your CA Easytrieve Report Generator program. Use this macro for automatic processing
only.
• %DBOPEN opens the CA Datacom/DB tables for further processing. Use this macro for controlled processing only.
• %DBCLOSE closes all open CA Datacom/DB tables. Use this macro for controlled processing only.
• %DBLREQ (long parameter list) provides the direct request interface to CA Datacom/DB using all four parameter
areas (UIB, RA, EL, and WA). Use this macro for controlled processing only.
• %DBSREQ (short parameter list) provides the direct request interface to CA Datacom/DB using only the UIB and RA
parameter areas. Use this macro for controlled processing only.
Macro Synopsis
The following table is a reference tool that lists information about each macro and where it is coded in the CA Easytrieve
Report Generator program.
Macro Function Type of Processing Where Coded in Program
%DBCLOSE Close CA Datacom/DB tables Controlled only Activity section
%DBEL Define EL Automatic or controlled Library section
%DBFILE Define WA and generate FILE Automatic only Library section
statement
%DBLREQ Provide Direct Request Interface Controlled only Activity section
to CA Datacom/DB using all four
parameter areas
%DBOPEN Open CA Datacom/DB tables Controlled only Activity section
%DBRA Define RA Automatic or controlled Library section
%DBSREQ Provide Direct Request Interface Controlled only Activity section
to CA Datacom/DB using UIB
and RA parameter areas
%DBUIB Define UIB Automatic or controlled Library section
%DBWA Define WA Controlled only Library section
%DBUIB Define User Information Block
Use the %DBUIB macro to define the User Information Block (UIB) for communication with CA Datacom/DB. The 40-byte
required UIB area identifies the requester of CA Datacom/DB services. Use this macro for both automatic and controlled
processing.
Syntax
%DBUIB literal urt-name
Both parameters are required for this macro.
• literal
Specifies the eight-character name of the current CA Easytrieve Report Generator program. CA Datacom/DB does
not require you to enter a value for this field. However, you should include your program name here to aid you in
debugging your application.
• urt-name
582
CA Easytrieve® Report Generator 11.6
Specifies the eight-character name of the link-edited URT/ETDRVR module that is prepared by the database
administrator for your use. The urt-name is located outside the normal bounds of the UIB as defined by CA Datacom/
DB. Including this field causes no problems for any of the CA Datacom/DB requirements.
A URT/ETDRVR must be generated for each table that is accessed by your application. For instructions to generate the
URT, see install JOB09URT in the Installing section.
%DBRA Define Request Area
The %DBRA macro statement defines the Request Area (RA) within your CA Easytrieve Report Generator program.
This 286-byte, required Request Area, is used to specify requests made to CA Datacom/DB and to test the results. CA
Datacom/DB uses the Request Area to save control information between related requests. A program must have an active
Request Area for each CA Datacom/DB table you access. The program can also use multiple Request Areas for the same
table. Use this macro for either automatic or controlled processing.
See the Programming section in the CA Datacom/DB documentation for more information about the full definition and
uses of the Request Area.
Syntax
%DBRA prfx tbl-nm ky-nm [DBID db-id-no]
The prfx, tbl-nm, and ky-nm parameters are required. The db-id-no parameter is optional.
• prfx
Specifies the prefix for the CA Datacom/DB access set you are using to access the CA Datacom/DB table. This unique
prefix enables multiple access paths into the same CA Datacom/DB table and must match the prefix that you use for
the %DBEL and %DBWA macros.
Because the interface uses prfx to generate other field names, prfx must follow CA Easytrieve Report Generator
naming conventions and be no longer than 30 characters when you use controlled processing. When you use this
macro with automatic input, prfx can only be eight characters long for z/OS and seven characters long for VSE. This is
because the prfx is also used as a filename.
The %DBRA macro loads prfx into the variable prfx-PREFIX to aid the interface in identifying the RA. Prfx-PREFIX
is located outside the normal bounds of the RA, as defined by CA Datacom/DB. Therefore, prfx-PREFIX causes no
problems for any of the CA Datacom/DB requirements.
• tbl-rm
Specifies the three-character table name that you assign in CA Datacom/DB to the set of records you are accessing.
The tbl-nm parameter must match a valid table name in the CA Datacom/DB data dictionary. If not, all requests that
use the Request Area fail.
• ky-nm
Specifies the five-character name of the key you use to traverse the table. The ky-nm parameter must match a valid
name in the CA Datacom/DB data dictionary.
• dh-id-no
Optional binary value for a specific database ID. When you use the SYNONYM=YES parameter in your URT, you must
code the db-id-no parameter to address the correct database.
%DBEL Define Element List
The %DBEL macro statement defines the Element List (EL) for communication with CA Datacom/DB. This optional area
controls the data elements that you reference. Use this macro for either automatic or controlled processing.
Syntax
%DBEL prfx elmt-nm [elmt-nm ...]
• prfx
583
CA Easytrieve® Report Generator 11.6
Specifies the prefix for the CA Datacom/DB access set. It must match the prefix that you use for the %DBRA and
%DBWA macros. Prfx must follow CA Easytrieve Report Generator naming conventions and be no longer than 30
characters when you use controlled processing. When you use this macro with automatic input, prfx can only be eight
characters long for z/OS. This is because the prfx is also used as a filename.
• elmt-nm
Specifies the data element that you retrieve, update, or add to the database. The format of the elmt-nm parameter is:
EEEEES
Where EEEEE is the element name as defined in the data dictionary, and S is the security code that is defined for that
element.
– If the element name does not have a security code, you do not have to enter it.
– If the element name is fewer than five characters long, and there is a security code, you must enter the element
name in quotes with filling blanks. For example:
ABC 'D'
In this example, ABC is the element name and D is the security code.
Because the element name is three characters long, there are two blanks between C and D.
You must enter at least one element name when you use this macro. You can enter as many as 16 element names,
depending on the needs of your program.
%DBWA Define Work Area
The %DBWA macro statement defines the Work Area (WA) for communication with CA Datacom/DB. You can use the
optional Work Area to provide a local working storage area in which to manipulate the data elements that are listed in the
matching Element List. Use the %DBWA macro for controlled processing requests only.
Syntax
%DBWA prfx wrk-area-sz
Both parameters are required.
• prfx
Specifies the prefix that you use for the CA Datacom/DB access set. It must match the prefix that you use for the
%DBRA and %DBEL macros. Prfx must follow CA Easytrieve Report Generator naming conventions and be no longer
than 30 characters.
• wrk-area-sz
Specifies the length of the Work Area that you define to contain the elements that are listed in the Element List. It is
a numeric value from 1 to 32767. The size must be large enough to fit the combined lengths of all the elements that
are listed. If the size is too small, retrieved elements overlay whatever follows the Work Area in storage, such as CA
Easytrieve Report Generator code.
Usage Notes
The %DBWA macro generates the following statement:
DEFINE prfx-WORK-AREA W 1 A OCCURS wrk-area-sz
You must provide working storage definitions to redefine the Work Area with the appropriate field definitions. The field
definitions describe the data elements that your CA Easytrieve Report Generator program manipulates. Search for
Controlled Processing Examples here for a working storage definition with the %DBWA macro.
%DBFILE Generate FILE Statement
The %DBFILE macro statement generates the FILE statement that you use during automatic processing. Use this macro
for automatic processing only.
584
CA Easytrieve® Report Generator 11.6
Syntax
%DBFILE prfx wrk-area-sz [START strt-val]
• prfx
Specifies the prefix that is associated with the Request Area and Element List. Prfx must follow CA Easytrieve Report
Generator naming conventions. Prfx can only be eight characters long for z/OS and seven characters long for VSE.
This is because the prfx is also used as a filename.
The interface uses prfx to tailor the generated code which in turn establishes the appropriate CA Datacom/DB
parameter list. The %DBUIB, %DBRA, and %DBEL macros generate the required data areas that communicate with
CA Datacom/DB.
• wrk-area-sz
Specifies the length of the Work Area that you define to contain the elements that are listed in the Element List. The
size of this work area must be large enough to fit the combined lengths of all the elements that are listed. If the size
is too small, retrieval commands overlay whatever follows the Work Area in storage, such as CA Easytrieve Report
Generator code.
• strt-val
Optional value that you can use for skip sequential processing. When you omit strt-val, the table is processed
beginning with the first key value found. When you supply strt-val, the table is processed beginning with the first key
value found that is equal to or greater than the value supplied. If the strt-val contains embedded blanks, you must
enclose it in triple quotes.
For example:
START '''Smith 91700'''
In this example, there are three blanks between Smith and 91700. Therefore, you must place triple quotes around
them (you have to place the triple quotes, even if there is one blank). If you do not, processing stops at the blank after
Smith.
Usage Notes
The %DBFILE macro generates the following statements:
DEFINE prfx-KEY-VAL2 prfx-REQ-AREA +76 180 A VALUE 'strt-val'
FILE prfx +
WORKAREA(wrk-area-sz) +
EXIT (ETDTCM USING (USER-INFO +
prfx-REQ-STRT +
prfx-ELEM-LIST))
WORK-AREA 1 1 A OCCURS wrk-area-sz
CA Datacom/DB needs the WORK-AREA defined after the FILE statement for data transfer. It is defined here as a file
field to make it possible to use automatic processing. See the Programming section in the CA Datacom/DB documentation
for more information about the full definition and uses of the Work Area.
You must provide FILE field definitions to redefine the WORK-AREA with the appropriate field definitions that describe
the data elements that your CA Easytrieve Report Generator program manipulates. See Examples for a working storage
definition following the %DBFILE macro.
%DBOPEN Open Tables
The %DBOPEN macro statement opens the CA Datacom/DB tables for further processing. You must code this macro in
the activity section of the CA Easytrieve Report Generator program (before any other CA Datacom/DB commands). Use
this macro for controlled processing only.
Syntax
%DBOPEN
585
CA Easytrieve® Report Generator 11.6
Usage Notes
You must invoke the %DBOPEN macro (that generates the DBOPEN PROCedure) once in each CA Easytrieve Report
Generator program that uses controlled processing. Automatic processing does not require the %DBOPEN macro,
because the FILE EXIT routine automatically opens the tables.
If the %DBOPEN macro is invoked, a %DBCLOSE macro must be invoked before the CA Easytrieve Report Generator
program has ended to close the database. If the %DBCLOSE is not done, the database is left in an open condition, and a
system abend may occur at termination.
%DBCLOSE Close Tables
The %DBCLOSE macro statement closes all open CA Datacom/DB tables. The %DBCLOSE macro has no parameters.
Use this macro for controlled processing only.
Syntax
%DBCLOSE
Usage Notes
You must invoke the %DBCLOSE macro (that generates the DBCLOSE PROCedure) once at the end of each CA
Easytrieve Report Generator program that uses controlled processing. The DBCLOSE PROCedure closes all open CA
Datacom/DB tables.
%DBLREQ Direct Request (Long List)
The %DBLREQ (long parameter list) macro statement provides the direct request interface to CA Datacom/DB using all
four CA Datacom/DB parameters areas (UIB, RA, EL, WA). Use %DBLREQ only for controlled processing requests into
CA Datacom/DB.
The DBLREQ macro uses the internal macros DBREQ2 and DBREQ3.
Syntax
%DBLREQ prfx cmnd-cd [EL el-prfx] [WA wa-prfx]
The first two parameters are required for this macro. The el-prfx and wa-prfx parameters are optional.
• prfx
Specifies the prefix that was previously associated with a set of RA, EL, and WA areas. Prfx must follow CA Easytrieve
Report Generator naming conventions and can be no longer than 30 characters. The prefix tailors the generated code
that accesses the appropriate CA Datacom/DB parameter areas for the request.
• cmnd-cd
Specifies a valid five-character CA Datacom/DB command code. Use cmnd-cd to specify the operation to be
performed. See the Programming section in the CA Datacom/DB documentation for a list of valid command codes.
• el-prfx
Optionally points to an element list other than the one you specify in prfx. When you specify this parameter, CA
Datacom/DB accesses the element list that el-prfx points to and ignores the value in prfx. If you do not enter a value
for el-prfx, then the el-prfx defaults to the value in prfx. The el-prfx parameter enables you to communicate with CA
Datacom/DB using the exact data areas that provide you with the optimum access path.
• wa-prfx
Optionally points to a work area other than the one you specify in prfx. When you specify this parameter, CA Datacom/
DB accesses the work area that wa-prfx points to and ignores the value in prfx. If you do not enter a value for wa-prfx,
then the wa-prfx defaults to the value in prfx. The wa-prfx parameter enables you to communicate with CA Datacom/
DB using the exact data areas that provide you with the optimum access path.
586
CA Easytrieve® Report Generator 11.6
Usage Notes
After the call, the result of the operation is found in prfx-RET-CD.
%DBSREQ Direct Request (Short List)
The %DBSREQ (short parameter list) macro statement provides the direct request interface into CA Datacom/DB using
the UIB and RA parameter areas only. This macro saves programming time because it eliminates the need to code the
WA and EL areas. Use this macro with only those commands that require the UIB and WA areas (such as in LOCATE,
DELETE, and RELEASE). See the Programming section in the CA Datacom/DB documentation for a complete list of
these commands.
Use the %DBSREQ macro only for controlled processing requests into CA Datacom/DB.
Syntax
%DBSREQ prfx cmnd-cd
Both parameters are required for this macro.
• prfx
Specifies the prefix that was previously associated with a set of RA, EL, and WA areas. Prfx must follow CA Easytrieve
Report Generator naming conventions and can be no longer than 30 characters. Use this prefix to tailor the generated
code that accesses the appropriate CA Datacom/DB parameter areas for the request.
• cmnd-cd
Specifies a valid five-character CA Datacom/DB command code. Use cmnd-cd to specify an operation to be
performed.
Usage Notes
After the call, the result of the operation is found in prfx-RET-CD.
Examples
The following programs with CA Datacom/DB interface macro examples are based on the sample database and programs
that are provided with CA Datacom/DB and illustrated in the Programming section in the CA Datacom/DB documentation.
Automatic Processing - All Records
In the following example of automatic processing, the program prints a report. This report lists every record in the
purchase order header (POH) table:
1: %DBUIB EZT+DB MYURT
2: %DBRA ABC POH POLI
3: %DBEL ABC PO LI VENDR TPVAL LATE
4: %DBFILE ABC 20
5: PO 1 5 A
6: LI 6 3 A
7: VENDR 9 3 A
8: TPVAL 12 8 N MASK 'ZZZ,ZZ9.99'
9: LATE 20 1 A
10: *
11: JOB NAME ACCESS-ALL-ROWS INPUT ABC
12: PRINT ABC-RPT
13: *
14: REPORT ABC-RPT LINESIZE 80
15: LINE PO VENDR TPVAL LATE
587
CA Easytrieve® Report Generator 11.6
Line 1 defines the standard User Information Block (UIB) parameter area for CA Datacom/DB calls. Only one of these is
required in any program.
Lines 2 and 3 define two other standard parameter areas: the Request Area (RA) and the Element List (EL).
Line 4 defines the Work Area (WA) size, sets up the automatic processing file, and defines the starting value for the
sequential scan (LOW-VALUES is the default).
The %DBFILE macro automatically generates the FILE statement and EXIT parameter, causing the CA Datacom/DB files
to be properly opened, accessed, and closed.
Note: The RA, EL, and WA are matched together by the prefix ABC.
Lines 5-9 define the field structure of the WA.
Lines 11-15 are the typical statements that are required to produce a sequential report.
Macro Generated Statements
The example of automatic processing is now shown with all statements that the macros generate. The statements that are
generated by the macros are identified with an asterisk in the left column:
%DBUIB EZT+DB MYURT
* DEFINE USER-INFO S 40 A
* DEFINE USER-PGM USER-INFO 8 A VALUE 'EZT+DB'
* DEFINE URT-NAME USER-INFO +32 8 A VALUE 'MYURT'
%DBRA ABC POH POLI
* DEFINE ABC-REQ-AREA S 284 A
* DEFINE ABC-REQ-STRT S 1 A
* DEFINE ABC-CMND ABC-REQ-AREA 5 A
* DEFINE ABC-TBL-NM ABC-REQ-AREA +5 3 A VALUE 'POH'
* DEFINE ABC-KEY-NM ABC-REQ-AREA +8 5 A VALUE 'POLI'
* DEFINE ABC-RET-CD ABC-REQ-AREA +13 2 A
* DEFINE ABC-INT-RET-CD ABC-REQ-AREA +15 1 B VALUE 0
* DEFINE ABC-DB-ID ABC-REQ-AREA +16 2 B VALUE 0
* DEFINE ABC-REC-ID ABC-REQ-AREA +18 7 A
* DEFINE ABC-TBL-ID ABC-REQ-AREA +18 2 B VALUE 0
* DEFINE ABC-BLK ABC-REQ-AREA +20 4 B VALUE 0
* DEFINE ABC-REC ABC-REQ-AREA +24 1 B VALUE 0
* DEFINE ABC-RQA-ERR ABC-REQ-AREA +26 4 A
* DEFINE ABC-RQA-SEC ABC-REQ-AREA +26 1 A
* DEFINE ABC-RQA-ENTRY ABC-REQ-AREA +27 3 N VALUE 0
* DEFINE ABC-SET-CNT ABC-REQ-AREA +40 4 B VALUE 0
* DEFINE ABC-SET-NBR ABC-REQ-AREA +44 4 B VALUE 0
* DEFINE ABC-CNT-MAX ABC-REQ-AREA +50 2 B VALUE 0
* DEFINE ABC-IO-CNT ABC-REQ-AREA +52 2 B VALUE 0
* DEFINE ABC-SKP-CNT ABC-REQ-AREA +71 2 B VALUE 0
* DEFINE ABC-KEY-VAL ABC-REQ-AREA +76 180 A
* DEFINE ABC-WHO-AM-I ABC-REQ-AREA +256 28 A VALUE 'ABC'
%DBEL ABC PO LI VENDR TPVAL LATE
* DEFINE ABC-ELEM-LIST S 101 A
* DEFINE ABC-ELM01 ABC-ELEM-LIST 7 A VALUE 'PO '
* DEFINE ABC-ELM02 ABC-ELEM-LIST +6 7 A VALUE 'LI '
* DEFINE ABC-ELM03 ABC-ELEM-LIST +12 7 A VALUE 'VENDR '
* DEFINE ABC-ELM04 ABC-ELEM-LIST +18 7 A VALUE 'TPVAL '
* DEFINE ABC-ELM05 ABC-ELEM-LIST +24 7 A VALUE 'LATE '
* DEFINE ABC-ELM06 ABC-ELEM-LIST +30 7 A VALUE ' '
588
CA Easytrieve® Report Generator 11.6
* DEFINE ABC-ELM07 ABC-ELEM-LIST +36 7 A VALUE ' '
* DEFINE ABC-ELM08 ABC-ELEM-LIST +42 7 A VALUE ' '
* DEFINE ABC-ELM09 ABC-ELEM-LIST +48 7 A VALUE ' '
* DEFINE ABC-ELM10 ABC-ELEM-LIST +54 7 A VALUE ' '
* DEFINE ABC-ELM11 ABC-ELEM-LIST +60 7 A VALUE ' '
* DEFINE ABC-ELM12 ABC-ELEM-LIST +66 7 A VALUE ' '
* DEFINE ABC-ELM13 ABC-ELEM-LIST +72 7 A VALUE ' '
* DEFINE ABC-ELM14 ABC-ELEM-LIST +78 7 A VALUE ' '
* DEFINE ABC-ELM15 ABC-ELEM-LIST +84 7 A VALUE ' '
* DEFINE ABC-ELM16 ABC-ELEM-LIST +90 7 A VALUE ' '
%DBFILE ABC 20
* DEFINE ABC-KEY-VAL2 ABC-REQ-AREA +76 180 A VALUE '00000000'
* FILE ABC +
* WORKAREA(20) +
* EXIT (ETDTCM USING (USER-INFO +
* ABC-REQ-STRT +
* ABC-ELEM-LIST)
* WORK-AREA 1 1 A OCCURS 20
PO 1 5 A
LI 6 3 A
VENDR 9 3 A
TPVAL 12 8 N MASK 'ZZZ,ZZ9.99'
LATE 20 1 A
JOB NAME ACCESS-ALL-ROWS INPUT ABC
PRINT ABC-RPT
REPORT ABC-RPT LINESIZE 80
LINE PO VENDR TPVAL LATE
Automatic Processing - Selected Records
The following program prints all purchase orders between PO numbers 1000 and 1999. The purchase order records
reside in the purchase order header (POH) table.
1 %DBUIB EZT+DB MYURT
2 %DBRA DEF POH POLI
3 %DBEL DEF PO LI VENDR TPVAL LATE
4 %DBFILE DEF 20 START '''01000'''
5 PO 1 5 A
6 LI 6 3 A
7 VENDR 9 3 A
8 TPVAL 12 8 N MASK 'ZZZ,ZZ9.99'
9 LATE 20 1 A
10 *
11 JOB NAME ACCESS-SOME-ROWS INPUT DEF
12 IF PO > '01999'
13 STOP
14 END-IF
15 PRINT DEF-RPT
16 *
17 REPORT DEF-RPT LINESIZE 80
18 LINE PO VENDR TPVAL LATE
Line 1 defines the standard User Information Block (UIB) parameter area for CA Datacom/DB calls. Only one of these is
required in any program.
589
CA Easytrieve® Report Generator 11.6
Lines 2 and 3 define two other standard parameter areas: the Request Area (RA) and the Element List (EL).
Line 4 defines the Work Area (WA) size, sets up the automatic processing file, and defines the starting value for the
sequential scan ('01000').
The %DBFILE macro automatically generates the FILE statement and EXIT parameter causing the CA Datacom/DB files
to be properly opened, accessed, and closed.
Note: The RA, EL, and WA are matched together by the prefix DEF.
Lines 5-9 define the field structure of the WA.
Lines 11-18 are the typical statements that are required to produce a report for the desired range of records.
Controlled Processing
The following program is an example of controlled processing. Like the first example program, it prints a report of
all records in the purchase order header (POH) table. This program duplicates the results of the first example under
Automatic Processing.
1 %DBUIB EZT+DB MYURT
2 %DBRA GHI POH POLI
3 %DBEL GHI PO LI VENDR TPVAL LATE
4 %DBWA GHI 20
5 DEFINE GHI-PO GHI-WORK-AREA 5 A
6 DEFINE GHI-LI GHI-WORK-AREA +5 3 A
7 DEFINE GHI-VENDR GHI-WORK-AREA +8 3 A
8 DEFINE GHI-TPVAL GHI-WORK-AREA +11 8 N MASK 'ZZZ,ZZ9.99'
9 DEFINE GHI-LATE GHI-WORK-AREA +19 1 A
10 *
11 JOB NAME ALL-RECORDS INPUT NULL START STARTUP FINISH DBCLOSE
12 PRINT GHI-RPT . * Print this record
13 %DBLREQ GHI REDNX . * Read next record
14 IF GHI-RET-CD = '14' . * Have we reached end of file?
15 STOP . * Yes; we're done
16 END-IF
17 STARTUP.
18 PROC . * Procedure for start-up processing
19 PERFORM DBOPEN . * Open the CA-Datacom/DB file
20 GHI-KEY-VAL = X'0000000000' . * Set the first key value
21 %DBSREQ GHI LOCKY . * Locate key => start value
22 IF GHI-RET-CD = '14' . * Did we not find one?
23 STOP . * Then we must not have any records
24 END-IF
25 %DBLREQ GHI REDLE . * Read the located record
26 END-PROC
27 %DBOPEN
28 %DBCLOSE
29 *
30 REPORT GHI-RPT LINESIZE 80
31 LINE GHI-PO GHI-VENDR GHI-TPVAL GHI-LATE
Line 1 defines the standard User Information Block (UIB) parameter area for CA Datacom/DB calls. Only one of these is
required in any program.
Lines 2-4 define the other three standard parameter areas - the Request Area (RA), the Element List (EL), and the Work
Area (WA).
590
CA Easytrieve® Report Generator 11.6
Note: The RA, EL, and WA are matched together by the prefix GHI.
Lines 5-9 define the field structure of the WA.
Line 11 is a JOB statement which specifies the initializing and terminating procedures that you use. You must always
code these procedures to point to the %DBOPEN or %DBCLOSE macros or to PROCedures that invoke them.
Lines 12-16 contain the logic to print the current record and read the next record in the table, checking for end of file.
Lines 17-26 perform the required initializing operations. This operation calls the DBOPEN PROCedure, sets the initial key
value, and reads a record.
Line 27 contains the %DBOPEN macro that opens the required CA Datacom/DB tables.
Line 28 contains the %DBCLOSE macro that closes the required CA Datacom/DB tables.
Lines 30-31 contain the typical statements needed to produce a report.
Macro Generated Statements
The example of controlled processing is now shown with all statements that the macros generate. The statements
generated by the macros are identified with an asterisk in the left column:
%DBUIB EZT+DB MYURT
* DEFINE USER-INFO S 40 A
* DEFINE USER-PGM USER-INFO 8 A VALUE 'EZT+DB'
* DEFINE URT-NAME USER-INFO +32 8 A VALUE 'MYURT'
%DBRA GHI POH POLI
* DEFINE GHI-REQ-AREA S 284 A
* DEFINE GHI-REQ-STRT S 1 A
* DEFINE GHI-CMND GHI-REQ-AREA 5 A
* DEFINE GHI-TBL-NM GHI-REQ-AREA +5 3 A VALUE 'POH'
* DEFINE GHI-KEY-NM GHI-REQ-AREA +8 5 A VALUE 'POLI'
* DEFINE GHI-RET-CD GHI-REQ-AREA +13 2 A
* DEFINE GHI-INT-RET-CD GHI-REQ-AREA +15 1 B VALUE 0
* DEFINE GHI-DB-ID GHI-REQ-AREA +16 2 B VALUE 0
* DEFINE GHI-REC-ID GHI-REQ-AREA +18 7 A
* DEFINE GHI-TBL-ID GHI-REQ-AREA +18 2 B VALUE 0
* DEFINE GHI-BLK GHI-REQ-AREA +20 4 B VALUE 0
* DEFINE GHI-REC GHI-REQ-AREA +24 1 B VALUE 0
* DEFINE GHI-RQA-ERR GHI-REQ-AREA +26 4 A
* DEFINE GHI-RQA-SEC GHI-REQ-AREA +26 1 A
* DEFINE GHI-RQA-ENTRY GHI-REQ-AREA +27 3 N VALUE 0
* DEFINE GHI-SET-CNT GHI-REQ-AREA +40 4 B VALUE 0
* DEFINE GHI-SET-NBR GHI-REQ-AREA +44 4 B VALUE 0
* DEFINE GHI-CNT-MAX GHI-REQ-AREA +50 2 B VALUE 0
* DEFINE GHI-IO-CNT GHI-REQ-AREA +52 2 B VALUE 0
* DEFINE GHI-SKP-CNT GHI-REQ-AREA +71 2 B VALUE 0
* DEFINE GHI-KEY-VAL GHI-REQ-AREA +76 180 A
* DEFINE GHI-WHO-AM-I GHI-REQ-AREA +256 28 A VALUE 'GHI'
%DBEL GHI PO LI VENDR TPVAL LATE
* DEFINE GHI-ELEM-LIST S 101 A
* DEFINE GHI-ELM01 GHI-ELEM-LIST 7 A VALUE 'PO '
* DEFINE GHI-ELM02 GHI-ELEM-LIST +6 7 A VALUE 'LI '
* DEFINE GHI-ELM03 GHI-ELEM-LIST +12 7 A VALUE 'VENDR '
* DEFINE GHI-ELM04 GHI-ELEM-LIST +18 7 A VALUE 'TPVAL '
* DEFINE GHI-ELM05 GHI-ELEM-LIST +24 7 A VALUE 'LATE '
* DEFINE GHI-ELM06 GHI-ELEM-LIST +30 7 A VALUE ' '
591
CA Easytrieve® Report Generator 11.6
* DEFINE GHI-ELM07 GHI-ELEM-LIST +36 7 A VALUE ' '
* DEFINE GHI-ELM08 GHI-ELEM-LIST +42 7 A VALUE ' '
* DEFINE GHI-ELM09 GHI-ELEM-LIST +48 7 A VALUE ' '
* DEFINE GHI-ELM10 GHI-ELEM-LIST +54 7 A VALUE ' '
* DEFINE GHI-ELM11 GHI-ELEM-LIST +60 7 A VALUE ' '
* DEFINE GHI-ELM12 GHI-ELEM-LIST +66 7 A VALUE ' '
* DEFINE GHI-ELM13 GHI-ELEM-LIST +72 7 A VALUE ' '
* DEFINE GHI-ELM14 GHI-ELEM-LIST +78 7 A VALUE ' '
* DEFINE GHI-ELM15 GHI-ELEM-LIST +84 7 A VALUE ' '
* DEFINE GHI-ELM16 GHI-ELEM-LIST +90 7 A VALUE ' '
%DBWA GHI 20
* DEFINE GHI-WORK-AREA W 1 A OCCURS 20
DEFINE GHI-PO GHI-WORK-AREA 5 A
DEFINE GHI-LI GHI-WORK-AREA +5 3 A
DEFINE GHI-VENDR GHI-WORK-AREA +8 3 A
DEFINE GHI-TPVAL GHI-WORK-AREA +11 8 N MASK 'ZZZ,ZZZ9.99'
DEFINE GHI-LATE GHI-WORK-AREA +19 1 A
JOB NAME ALL-RECORDS INPUT NULL START STARTUP FINISH DBCLOSE
PRINT GHI-RPT . * Print this record
%DBLREQ GHI REDNX . * Read next record
* GHI-CMD = 'REDNX'
* CALL ETDTCM USING(USER-INFO +
* GHI-REQ-STRT +
* GHI-WORK-AREA +
* GHI-ELEM-LIST)
IF GHI-RET-CD = '14' . * Have we reached end of file?
STOP . * Yes; we're done
END-IF
STARTUP.
PROC . * Procedure for start-up processing
PERFORM DBOPEN . * Open the CA-Datacom/DB file
GHI-KEY-VAL = X'0000000000' . * Set the first key value
%DBSREQ GHI LOCKY . * Locate key => start value
* GHI-CMD = 'LOCKY'
* CALL ETDTCM USING(USER-INFO +
* GHI-REQ-AREA)
IF GHI-RET-CD = '14' . * Did we not find one?
STOP . * Then we must not have any records
END-IF
%DBLREQ GHI REDLE . * Read the located record
* GHI-CMD = 'REDLE'
* CALL ETDTCM USING(USER-INFO +
* GHI-REQ-STRT +
* GHI-WORK-AREA +
* GHI-ELEM-LIST)
END-PROC
%DBOPEN
* DBOPEN.
* PROC
* CALL ETDTCM USING(USER-INFO 'OPEN ')
* END-PROC
%DBCLOSE
* DBCLOSE.
592
CA Easytrieve® Report Generator 11.6
* PROC
* CALL ETDTCM USING(USER-INFO 'CLOSE')
* END-PROC
REPORT GHI-RPT LINESIZE 80
LINE GHI-PO GHI-VENDR GHI-TPVAL GHI-LATE
Purchase Orders by Line Item
This final program lists all purchase orders by line item, showing the part name on each line. The POH, POL, and PNM
tables are accessed in this program.
1 %DBUIB EZT+DB MYURT
2 %DBRA JKL POH POLI
3 %DBEL JKL PO LI VENDR
4 %DBWA JKL 11
5 DEFINE JKL-PO JKL-WORK-AREA 5 A
6 DEFINE JKL-LI JKL-WORK-AREA +5 3 A
7 DEFINE JKL-VENDR JKL-WORK-AREA +8 3 A
8 %DBRA MNO POL POLI
9 %DBEL MNO PO LI PN
10 %DBWA MNO 11
11 DEFINE MNO-PO MNO-WORK-AREA 5 A
12 DEFINE MNO-LI MNO-WORK-AREA +5 3 A
13 DEFINE MNO-PN MNO-WORK-AREA +8 3 A
14 %DBRA PQR PNM PN
15 %DBEL PQR PN DESC
16 %DBWA PQR 23
17 DEFINE PQR-PN PQR-WORK-AREA +1 3 A
18 DEFINE PQR-DESC PQR-WORK-AREA +3 20 A
19 *
20 JOB NAME TESTJOB4 INPUT NULL START STARTUP FINISH DBCLOSE
21 POL-KEY-VAL = POH-PO . * Set up POL key from POH record
22 %DBSREQ POL LOCKY . * Locate the key =>
23 IF POL-RET-CD = '14' . * Have we reached end of file?
24 GOTO NEXT-PO . * Yes; we don't have any line items
25 END-IF
26 %DBLREQ POL REDLE . * Read the located record
27 DO WHILE POL-PO = POH-PO
28 PNM-KEY-VAL = POL-PN . * Set up PNM key from POL record
29 %DBLREQ PNM REDKY . * Read the record
30 PRINT JKL-MNO-PQR-RPT . * Print the line from the 3 records
31 %DBLREQ POL REDNX . * Read next POL record
32 END-DO
33 NEXT-PO.
34 %DBLREQ POH REDNX . * Read the next POH record
35 IF POH-RET-CD = '14' . * Have we reached end of file?
36 STOP . * Yes; we're done with report
37 END-IF
38 STARTUP.
39 PROC . * Proc for startup processing
40 PERFORM DBOPEN . * Open the CA-Datacom/DB files
41 POH-KEY-VAL = X'0000000000' . * Set initial key value
42 %DBSREQ POH LOCKY . * Locate the key => start value
593
CA Easytrieve® Report Generator 11.6
43 IF POH-RET-CD = '14' . * Have we reached end of file?
44 STOP . * Yes; we must not have any records
45 END-IF
46 %DBLREQ POH REDLE . * Read the located record
47 END-PROC
48 %DBOPEN
49 %DBCLOSE
50 *
50 REPORT JKL-MNO-PQR-RPT LINESIZE 80
51 LINE JKL-PO JKL-LI JKL-VENDR MNO-PN PQR-DESC
Line 1 defines the standard User Information Block (UIB) parameter area for CA Datacom/DB calls. Only one of these is
required in any program.
Lines 2-18 define the other three standard parameter areas: the Request Area (RA), the Element List (EL), and the Work
Area (WA). These lines also define the particular field structure of each WA for each of the access paths you need into the
database.
In lines 2-4, the RA, EL, and WA are matched together by the prefix JKL.
In lines 8-10, the RA, EL, and WA are matched together by the prefix MNO.
In lines 14-16, the RA, EL, and WA are matched together by the prefix PQR.
Line 20 is a JOB statement which specifies the initializing and terminating procedures that you use. You must always
code these procedures to point to the %DBOPEN or %DBCLOSE macros or to PROCedures that invoke them.
Lines 21-26 define your position in the POL file and read any line items that are to be printed.
Lines 27-32 contain a loop that reads the part name record for the current line item, prints the line, and reads the next line
item. This process continues until the line items for the current purchase order are exhausted.
Lines 33-37 contain the logic to read the next purchase order and check for end of file.
Lines 38-47 contain the logic to perform the required initializing operations, such as invoking the DBOPEN procedure,
setting the initial key value, and reading that record.
Line 48 contains the %DBOPEN macro that opens the required CA Datacom/DB tables.
Line 49 contains the %DBCLOSE macro that closes the required CA Datacom/DB tables.
Lines 51-52 are the typical statements that are required to produce a report.
File Processing
Prior:
If you did not specify WORKAREA on the FILE statement for the input files, CA Easytrieve® Report Generator processed
the record in Locate Mode. When the record was read into memory, it remained in the system-allocated record buffer.
release 11.x:
If you do not specify WORKAREA on the FILE statement for the input files, CA Easytrieve® Report Generator processes
the record in Move Mode. When the record is read, it is moved from the system-allocated record buffer to the buffer
created in program storage.
What this change means to your CA Easytrieve® Report Generator program:
When you are reading an input file where you do not know the record lengths (as with variable-length files), use the
RECORD-LENGTH field. After each record is read, the RECORD-LENGTH field contains the length of that record.
594
CA Easytrieve® Report Generator 11.6
Structure your program logic to reference only fields that are not defined to extend beyond the length specified in the
RECORD-LENGTH field.
Because release 6.4 used Locate Mode processing, your invalid references can refer to data beyond the actual record
and into the following record in the buffer. When you use Move Mode processing, the reference is always within the
program storage. However, if you do not use RECORD-LENGTH you can unintentionally refer to the data for a previous
record.
The following example processes two records, with the second record shorter than the first. The example writes the
records to a file, then reads them and displays a field that is defined beyond the length of the record:
FILE VFILE VB(20 200)
VFLD1 * 10 A
VFLD2 * 10 A
JOB INPUT NULL
VFLD1 = '1111111111'
VFLD2 = 'ABC'
RECORD-LENGTH = 13
PUT VFILE
VFLD1 = '2222222222'
VFLD2 = 'X'
RECORD-LENGTH = 11
PUT VFILE
STOP
JOB INPUT VFILE
DISPLAY HEX VFLD2
The following example shows the release 6.4 results:
CHAR ABC 222
ZONE CCC0000FFF
NUMR 1230F00222
1...5...10
CHAR X
ZONE E000000000
NUMR 7000000000
1...5...10
The following example shows the release 11 results:
CHAR ABC
ZONE CCC4444444
NUMR 1230000000
1...5...10
CHAR XBC
ZONE ECC4444444
NUMR 7230000000
1...5...10
The release 6.4 results display data outside of the first record and also a portion of the second record in the system buffer.
The release 11 results display the program storage buffer, but the second record still contains the ‘BC’ characters from
595
CA Easytrieve® Report Generator 11.6
the first record. Only refer to data that is constrained by RECORD-LENGTH. CA Easytrieve® Report Generator does not
initialize the buffer between input operations.
The following example reads the file and correctly displays the variable portion of the record (VFLD2):
JOB INPUT VFILE
DEFINE SFLD S 10 A
DEFINE LEN S 2 N
LEN = RECORD-LENGTH - 10. * Compute length to safely move data
MOVE VFLD2 LEN TO SFLD FILL ' '
DISPLAY HEX SFLD
If you write records from a variable-length input file to a variable-length output file, you must set the RECORD-LENGTH
field for each output record. The RECORD-LENGTH field of the output file must be set to the RECORD-LENGTH value of
the input file before the PUT to the output file. See the following example:
FILE VFILE VB(20 200)
VFLD1 * 10 A
VFLD2 * 10 A
FILE VFILEOUT VB(20 200)
JOB INPUT VFILE
VFILEOUT:RECORD-LENGTH = VFILE:RECORD-LENGTH
PUT VFILEOUT FROM VFILE
File Processing Modes
CA Easytrieve® Report Generator makes certain assumptions about the use of each file in an activity by scanning the I/
O statements coded in the activity. (This is assuming that all statement syntax is valid.) One of these assumptions is the
file's processing mode. The processing mode dictates whether the file is opened for read or write access. CA Easytrieve®
Report Generator file processing modes are:
• Input -- Indicates that only GET, POINT, and READ statements are coded in the activity that opened the file.
• Create -- Indicates that the file has CREATE specified on the FILE statement and that a PUT statement is coded in the
activity. If you coded RESET on the FILE statement, CA Easytrieve® Report Generator attempts to reload an existing
file.
• Output -- Indicates that UPDATE is specified on the FILE statement and PUT or WRITE ADD statements are coded in
the activity.
• Update -- Indicates that UPDATE is specified on the FILE statement and WRITE UPDATE or WRITE DELETE
statements are coded in the activity that opened the file.
Contents
File Access Mode
The other assumption CA Easytrieve® Report Generator makes about a file is the file's access mode. CA Easytrieve®
Report Generator always opens a file for dynamic access. This allows records to be read either sequentially or directly as
follows:
• Sequential -- Indicates that records are accessed in a sequence determined by the file type as follows:
596
CA Easytrieve® Report Generator 11.6
– For file type SEQUENTIAL, the records are accessed in the sequence in which the records were added to the file.
– For file type INDEXED, the records are accessed in the sequence defined by the key of the associated data set.
– For file type RELATIVE, the records are accessed in ascending sequence of relative record numbers.
• Sequential access allows the use of the GET, PUT, and WRITE UPDATE statements. If the file type is INDEXED or
RELATIVE, sequential access also allows the use of the WRITE DELETE statement.
• Direct -- Indicates that records are accessed in a sequence determined by the program. Each statement that accesses
a record specifies the key of the record to be accessed as follows:
– For file type SEQUENTIAL, direct access is not allowed.
– For file type INDEXED, the key value must be an alphanumeric item whose length is equal to the key length
specified for the associated data set.
– For file type RELATIVE, the key value is a four-byte binary integer that specifies a relative record number.
• Direct access allows the use of the READ, WRITE ADD, WRITE DELETE, and WRITE UPDATE statements.
Valid Syntax FILE Statement
If file type is... And parameters are... I/O statements allowed:
SEQUENTIAL CREATE PUT
UPDATE GET, WRITE UPDATE
(none) GET
RELATIVE CREATE PUT
UPDATE All except WRITE ADD
(none) GET, POINT, or READ
INDEXED CREATE PUT
UPDATE All
(none) GET, POINT, or READ
(none) CREATE or UPDATE *** Error condition ***
(none) File type must be specified
PUT or GET
File Browse Mode
Sequential input of a file implies a browse mode. CA Easytrieve® Report Generator normally maintains the positioning
within a file during a browse. The following operations terminate the browse and lose positioning within the file:
• A RELEASE statement
• Commit processing, automatic or by a COMMIT statement during a browse of a file containing a path of non-unique
keys. For more information, see the topic Units of Work and Commit Processing in Control Program Flow.
Note: You can use the PRIOR parameter on the GET statement to perform a backward browse.
Hold/Release Processing
CA Easytrieve® Report Generator automatically issues a hold for a record when the FILE statement specifies UPDATE.
You can override this by specifying HOLD or NOHOLD on your READ and GET statements.
When CA Easytrieve® Report Generator holds a record for update, it establishes the intent to update a record with the
operating system. This intent does not mean you are obligated to actually perform the update. It just holds the position in
the file and may also lock the record (in CICS). Locks are automatically released when the update operation completes or
a commit point is taken.
You can manually release the hold on any file with the RELEASE statement.
597
CA Easytrieve® Report Generator 11.6
In CICS, the default action for a READ statement is HOLD when you specify UPDATE on the FILE statement. The default
action for a GET statement and for automatic input is NOHOLD. CICS does not allow you to browse a file for update.
In all other environments, CA Easytrieve® Report Generator issues a HOLD by default for READs, GETs, and for
automatic input. See Commit Processing for examples of hold processing in screen processing.
Sequential Files
CA Easytrieve® Report Generator supports the access of all sequential files that the operating environment in which CA
Easytrieve® Report Generator is running also supports.
Contents
Sequential Files
When also supported by the operating environment, CA Easytrieve® Report Generator supports all of the following
sequential access methods:
• Queued Sequential Access Method (QSAM)
• Virtual Storage Access Method Entry Sequenced Data Set (VSAM ESDS)
• CARD and PUNCH files (not valid in CICS)
• CA Easytrieve® Report Generator's Virtual File Manager
• Non-mainframe variable-length text files and fixed-length record files (including standard devices: stdin, stdout)
Sequential File Processing Rules
CA Easytrieve® Report Generator processes sequential files according to the following rules:
• When you do not code a file type on the FILE statement, SEQUENTIAL is the default. CARD, PUNCH, and VIRTUAL
files imply a SEQUENTIAL file type.
Note: When SEQUENTIAL is not specified for a sequential file, the FILE-STATUS field is not available for the file.
• You cannot process the same sequential file as both an input and an output file within the same activity.
• You can create sequential files in one activity and process them in subsequent activities.
• CA Easytrieve® Report Generator permits only one CARD file in a program.
Sequential Input
CA Easytrieve® Report Generator provides both automatic and controlled processing of sequential files.
Automatic Processing
The following example shows sequential processing with automatic control:
FILE SEQFILE FB(150 1800)
%PERSNL
JOB INPUT SEQFILE NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65
LINE EMP# EMPNAME
Controlled Processing
The next example shows sequential processing with programmer control:
598
CA Easytrieve® Report Generator 11.6
FILE SEQFILE FB(150 1800)
%PERSNL
JOB INPUT NULL NAME MYPROG
GET SEQFILE
IF EOF SEQFILE
STOP
END-IF
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65
LINE EMP# EMPNAME
CARD Input
In TSO or CMS, you can process one of the input files through the system input stream (SYSIN) by defining the file with a
device type of CARD.
In non-mainframe environments, the device type of CARD is equal to stdin. The file is treated as a variable-length text file.
Note: Unless redirected, stdin reads input from the terminal device.
FILE CARDFILE CARD
FIELD 1 5 A
JOB INPUT CARDFILE NAME MYPROG
DISPLAY FIELD
Sequential Output
You can create output files using controlled processing with the PUT statement.
Fixed-Length File Creation
The following example shows fixed-length sequential file creation:
FILE INFILE
FIELD 1 5 A
FILE OUTFILE FB(100 500)
FIELD 1 5 A
JOB INPUT INFILE NAME MYPROG
PUT OUTFILE FROM INFILE
Variable-Length File Creation
The next example shows variable-length sequential file creation:
FILE INFILE
FIELD 1 5 A
FILE OUTFILE VB(100 504)
FIELD 1 5 A
JOB INPUT INFILE NAME MYPROG
OUTFILE:RECORD-LENGTH = 5
PUT OUTFILE FROM INFILE
599
CA Easytrieve® Report Generator 11.6
VSAM File Creation
The FILE statement and the PUT statement are used to create (load) VSAM ESDS files. You can reference a newly
created file in subsequent activities by coding another FILE statement with a different file name, but with JCL pointing to
the same physical file. The example below illustrates reloading a fixed-length ESDS file.
You can create INDEXED and RELATIVE files using a similar technique. The data set must be defined as reusable to use
the RESET option on the FILE statement.
FILE ESDS SEQUENTIAL CREATE RESET
%PERSNL
FILE PERSNL FB(150 1800)
COPY ESDS
JOB INPUT PERSNL NAME MYPROG
PUT ESDS FROM PERSNL STATUS
IF ESDS:FILE-STATUS NE 0
DISPLAY 'LOAD ERROR STATUS= ' ESDS:FILE-STATUS
STOP
END-IF
Note: When using multiple files, you should qualify FILE-STATUS, as illustrated above (ESDS:FILE-STATUS).
PUNCH Files
Except for the PUNCH parameter, CA Easytrieve® Report Generator treats PUNCH files the same as any other 80-byte
sequential file. The next example illustrates PUNCH file output:
FILE INFILE
FIELD 1 5 A
FILE OUTFILE PUNCH
FIELD 1 5 A
JOB INPUT INFILE NAME MYPROG
PUT OUTFILE FROM INFILE
In MVS, the PUNCH parameter is not required, due to its device independence. Simply define an output sequential file as
fixed-length 80 characters and assign it to the proper SYSOUT class via the DD card. If you code the PUNCH parameter,
MVS routes the output to the DD, SYSPUNCH.
Virtual File Manager
The Virtual File Manager (VFM) is a sequential access method that processes work files needed by a program. Typically,
when a program needs work files, separate disk areas must be reserved for each work file. VFM, however, maintains as
much disk area in memory as possible. If the area in memory is exhausted, VFM writes the excess data to a single spill
area. When you use VFM, you need only define one physical file.
As a virtual file is read back into the program, the space it occupied is released and the area can be immediately reused.
You can, however, retain VFM files for subsequent CA Easytrieve® Report Generator activities.
On non-mainframe platforms, each virtual file is a temporary file.
On the mainframe, VFM files are limited due to the operating system to a single disk drive in size. All data being
processed must fit within that constraint. When allocating VFM space, if possible, the primary allocation should specify
an amount near the maximum amount of data being processed. This will avoid the potential problem of not being able to
obtain additional space on the volume.
The use of VFM is identical to sequential processing with the following additions:
600
CA Easytrieve® Report Generator 11.6
• VFM files without the RETAIN option are deleted once CA Easytrieve® Report Generator has processed them as input
files and closed them.
• VFM files with the RETAIN option are deleted at the end of the associated CA Easytrieve® Report Generator
execution.
• VFM files are automatically blocked. Any block size you supply is ignored.
The following example illustrates a typical use of the VFM access method:
FILE PERSNL FB(150 1800)
%PERSNL
FILE SORTFILE VIRTUAL F(150)
COPY PERSNL
SORT PERSNL TO SORTFILE USING PAY-NET NAME MYSORT
JOB INPUT SORTFILE NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1
LINE EMPNAME PAY-NET
Because the file SORTFILE is a virtual file:
• You do not have to define SORTFILE in JCL
• SORTFILE does not leave any files known to the operating system.
Indexed Files
CA Easytrieve® Report Generator supports both sequential and random (direct) processing of indexed files. Indexed files
use a key that is contained in each record. Sequential processing retrieves records sequenced by the key. When also
supported by the operating environment, CA Easytrieve® Report Generator supports the following index access methods:
• Virtual Storage Access Method Keyed Sequenced Data Set (VSAM KSDS)
• C-ISAM files (fixed or variable-length format, unique single keys only)
• Windows Indexed files (fixed or variable-length format, unique single keys only)
Contents
Indexed Sequential Input
CA Easytrieve® Report Generator can process indexed files as if they were sequential files. The access can be done
either automatically (JOB INPUT) or controlled (GET). The process used is essentially the same as that described for
sequential file input. Additionally, you can also start the input at a specific record or use skip-sequential processing to
bypass groups of records. The following two examples illustrate INDEXED sequential input with a starting record and with
skip-sequential processing.
Pointing to a Specific Record
FILE KSDS INDEXED F(150)
%PERSNL
JOB INPUT KSDS NAME MYPROG START POINT-PROC
DISPLAY EMP# +2 EMPNAME
POINT-PROC. PROC
POINT KSDS EQ '12318' STATUS
IF KSDS:FILE-STATUS NE 0
601
CA Easytrieve® Report Generator 11.6
DISPLAY 'FILE-STATUS= ', KSDS:FILE-STATUS
STOP
END-IF
END-PROC
Skip-Sequential Processing
FILE VSAM INDEXED
%PERSNL
JOB INPUT VSAM NAME MYPROG
IF EMP# EQ 1000 THRU 1999
PERFORM POINT-VSAM
GOTO JOB
END-IF
PRINT REPORT1
*
POINT-VSAM. PROC
POINT VSAM GE '02000' STATUS
IF VSAM:FILE-STATUS NE 0
DISPLAY 'VSAM:FILE-STATUS= ' VSAM:FILE-STATUS
END-IF
END-PROC
*
REPORT REPORT1 LINESIZE 65
LINE EMP# EMPNAME
Random Input
The READ statement can read indexed files randomly (direct access mode). This example illustrates reading an indexed
file (PERSNL) using keys contained in a sequential file (INKEYS):
FILE PERSNL INDEXED
%PERSNL
FILE INKEYS
WHO * 5 N
JOB INPUT INKEYS NAME MYPROG
READ PERSNL KEY WHO STATUS
IF PERSNL:FILE-STATUS EQ 16
DISPLAY 'BAD KEY=' WHO
GOTO JOB
END-IF
DISPLAY SKIP 2 HEX PERSNL
Adding Records to an Indexed File
You can use either the WRITE or PUT statements to add records to an indexed file. Either statement adds a single record
to the file, but to use mass-sequential insertion, use the PUT statement to add many records to the same place in the file.
If you use the WRITE or PUT statements, you must include the CREATE or UPDATE parameter on the FILE statement.
UPDATE informs CA Easytrieve® Report Generator that all input records can potentially be updated or deleted. CREATE
informs CA Easytrieve® Report Generator that the activity will use the PUT statement to load the file.
The following examples illustrate single and mass-insertion record addition.
602
CA Easytrieve® Report Generator 11.6
Adding a Single Record
FILE PERSNL INDEXED UPDATE
%PERSNL
FILE INKEYS
WHO * 5 N
PHONE * 10 N
JOB INPUT INKEYS NAME MYPROG
MOVE WHO TO EMP#
MOVE PHONE TO TELEPHONE
WRITE PERSNL ADD STATUS
IF PERSNL:FILE-STATUS NE 0
DISPLAY 'BAD KEY=' WHO ' STATUS=' PERSNL:FILE-STATUS
GOTO JOB
END-IF
Mass-Sequential Record Insertion
FILE PERSNL INDEXED UPDATE
%PERSNL
FILE LOADER
COPY PERSNL
JOB INPUT LOADER NAME MYPROG
PUT PERSNL FROM LOADER STATUS
IF PERSNL:FILE-STATUS NE 0
DISPLAY 'ADD FAILED'
DISPLAY HEX LOADER
STOP
END-IF
File Creation
The FILE statement and the PUT statement are used to create (load) indexed files. You can reference a newly created file
in subsequent activities by coding another FILE statement with a different file name, but with JCL that points to the same
physical file. The following example illustrates reloading an indexed file. To use the RESET option on the FILE statement,
you must define the data set as reusable.
FILE KSDS INDEXED CREATE RESET
%PERSNL
FILE PERSNL FB(150 1800)
COPY KSDS
JOB INPUT PERSNL NAME MYPROG
PUT KSDS FROM PERSNL STATUS
IF KSDS:FILE-STATUS NE 0
DISPLAY 'LOAD ERROR STATUS= ' KSDS:FILE-STATUS
STOP
END-IF
Deleting a Record
You can use the WRITE statement to delete individual records from an indexed file. The deleted record is the file's current
input record.
603
CA Easytrieve® Report Generator 11.6
FILE KSDS INDEXED UPDATE
%PERSNL
FILE KEYS
WHO 1 5 N
JOB INPUT KEYS NAME MYPROG
READ KSDS KEY WHO STATUS
IF KSDS:FILE-STATUS NE 0
DISPLAY 'READ FAILED...KEY= ' WHO
STOP
END-IF
WRITE KSDS DELETE STATUS
IF KSDS:FILE-STATUS NE 0
DISPLAY 'DELETE FAILED'
STOP
END-IF
Updating a Record
You can modify and rewrite the current input record by using the WRITE statement.
FILE KSDS INDEXED UPDATE
%PERSNL
FILE KEYS
WHO 1 5 N
PHONE 6 10 N
JOB INPUT KEYS NAME MYPROG
READ KSDS KEY WHO STATUS
IF KSDS:FILE-STATUS NE 0
DISPLAY 'READ FAILED...KEY= ' WHO
STOP
END-IF
MOVE PHONE TO TELEPHONE
WRITE KSDS UPDATE STATUS
IF KSDS:FILE-STATUS NE 0
DISPLAY 'UPDATE FAILED...KEY= ' WHO
STOP
END-IF
Relative Files
CA Easytrieve® Report Generator supports both sequential and random (direct file access) processing of relative
files. Relative files use a four-byte binary key that contains an integer value that specifies the relative record number.
Sequential processing retrieves records sequenced by the relative sequence number. When also supported by the
operating environment, CA Easytrieve® Report Generator supports the following relative access methods:
• Virtual Storage Access Method Relative Record Data Set (VSAM:RRDS)
• Non-mainframe fixed-length relative (random-access) files
• C-ISAM files (fixed or variable-length format)
Contents
604
CA Easytrieve® Report Generator 11.6
Relative File Sequential Input
CA Easytrieve® Report Generator can process relative files as if they were sequential files. The access can be done
either automatically (JOB INPUT) or controlled (GET). The process used is essentially the same as that described for
sequential file input. Additionally, you can start the input at a specific record or use skip-sequential processing to bypass
groups of records.
Pointing to a Specific Record
This example shows relative sequential input with a starting record:
FILE RRDS RELATIVE
%PERSNL
REC-NUMBER W 4 B
JOB INPUT RRDS NAME MYPROG START POINT-PROC
DISPLAY EMP# +2 NAME
POINT-PROC. PROC
REC-NUMBER = 20
POINT RRDS EQ REC-NUMBER STATUS
IF FILE-STATUS NE 0
DISPLAY 'FILE-STATUS= ', RRDS:FILE-STATUS
STOP
END-IF
END-PROC
Skip-Sequential Processing
This example shows RELATIVE skip-sequential processing:
FILE RRDS RELATIVE
%PERSNL
REC-NUMBER W 4 B
JOB INPUT RRDS NAME MYPROG
IF RECORD-COUNT GR 3
PERFORM POINT-RRDS
GOTO JOB
END-IF
PRINT REPORT1
*
POINT-RRDS. PROC
REC-NUMBER = 40
POINT RRDS GE REC-NUMBER STATUS
IF RRDS:FILE-STATUS NE 0
DISPLAY 'FILE-STATUS= ' FILE-STATUS
END-IF
END-PROC
*
REPORT REPORT1 LINESIZE 65
LINE EMP# EMPNAME
605
CA Easytrieve® Report Generator 11.6
Random Input
The READ statement can read relative files randomly (direct access mode). The example below illustrates reading a
relative file, PERSNL, using keys contained in a sequential file, INKEYS:
FILE PERSNL RELATIVE
%PERSNL
FILE INKEYS
WHO * 4 B
JOB INPUT INKEYS NAME MYPROG
READ PERSNL KEY WHO STATUS
IF FILE-STATUS NE 0
DISPLAY 'BAD KEY=' WHO
GOTO JOB
END-IF
DISPLAY SKIP 2 HEX PERSNL
Adding Records to a Relative file
You can use the PUT statement to add records to a relative file. If you use the PUT statement, you must include the
CREATE or UPDATE parameter on the FILE statement. UPDATE informs CA Easytrieve® Report Generator that all input
records can potentially be updated or deleted. CREATE informs CA Easytrieve® Report Generator that the activity will use
the PUT statement to load the file. The following examples illustrate record addition and file creation.
Record Addition
FILE PERSNL RELATIVE UPDATE
%PERSNL
FILE LOADER
COPY PERSNL
REC-NUMBER W 4 B VALUE 330. * STARTING SLOT NUMBER
JOB INPUT LOADER NAME MYPROG
POINT PERSNL GE REC-NUMBER STATUS
PUT PERSNL FROM LOADER STATUS
IF FILE-STATUS NE 0
DISPLAY 'ADD FAILED'
DISPLAY HEX LOADER
STOP
END-IF
REC-NUMBER = REC-NUMBER + 1
File Creation
You can use the FILE statement and the PUT statement to create (load) relative files. You can reference a newly created
file in subsequent activities by coding another FILE statement with a different file name, but with JCL that points to the
same physical file. The following example illustrates reloading a relative file. To use the RESET option on the FILE
statement, you must define the data set as reusable.
FILE RRDS RELATIVE CREATE RESET
%PERSNL
FILE PERSNL FB(150 1800)
COPY RRDS
606
CA Easytrieve® Report Generator 11.6
JOB INPUT PERSNL NAME MYPROG
PUT RRDS FROM PERSNL STATUS
IF RRDS:FILE-STATUS NE 0
DISPLAY 'LOAD ERROR STATUS= ' RRDS:FILE-STATUS
STOP
END-IF
Deleting a Record
You can use the WRITE statement to delete individual records from a RELATIVE file. The deleted record is the file's
current input record. For example:
FILE RRDS RELATIVE UPDATE
%PERSNL
FILE KEYS
WHO 1 4 B
JOB INPUT KEYS NAME MYPROG
READ RRDS KEY WHO STATUS
IF FILE-STATUS NE 0
DISPLAY 'READ FAILED...KEY= ' WHO
STOP
END-IF
WRITE RRDS DELETE STATUS
IF FILE-STATUS NE 0
DISPLAY 'DELETE FAILED'
STOP
END-IF
Updating a Record
You can use the WRITE statement to modify and rewrite the current input record. For example:
FILE RRDS RELATIVE UPDATE
%PERSNL
FILE KEYS
WHO 1 4 B
PHONE 6 10 N
JOB INPUT KEYS NAME MYPROG
READ RRDS KEY WHO STATUS
IF FILE-STATUS NE 0
DISPLAY 'READ FAILED...KEY= ' WHO
STOP
END-IF
MOVE PHONE TO TELEPHONE
WRITE RRDS UPDATE STATUS
IF FILE-STATUS NE 0
DISPLAY 'UPDATE FAILED...KEY= ' WHO
STOP
END-IF
607
CA Easytrieve® Report Generator 11.6
Sorting Files
You can use the SORT statement to sort files. CA Easytrieve Report Generator can sort any file that can be processed
sequentially.
NOTE
Sorting files during CA Easytrieve Report Generator program execution significantly increases CPU overhead.
See Usage Best Practices for information about reducing CPU overhead.
This article includes the following information:
Sorting Files
The following illustrates the position of a SORT activity within a CA Easytrieve® Report Generator program:
Environment
...
Library
...
Activities
...
...
SORT sort procedure
... ...
...
Your installation's sort program performs the actual sort process, except in CICS and in non-mainframe environments,
where CA Easytrieve® Report Generator supplies its own sort program. CA Easytrieve® Report Generator normally
utilizes conventional sort interface techniques. For example, on a mainframe CA Easytrieve® Report Generator invokes
the sort program's E15 (input) and E35 (output) exits.
You can set a site option to use versions of sort in which the sort processes all input and output. For more information
about the available options for sort program utilization, see your installation's sort program manual.
NOTE
In CICS and in non-mainframe environments, CA Easytrieve® Report Generator provides a sort program.
See Sequenced Reports for information about sorting report output.
SORT Activity Example
In the following example, the output file contains all of the records of the input file sorted into ascending sequence by the
values of fields REGION and BRANCH:
FILE PERSNL FB(150 1800)
%PERSNL
FILE SORTWRK FB(150 1800) VIRTUAL
COPY PERSNL
SORT PERSNL TO SORTWRK USING +
(REGION, BRANCH) NAME MYSORT
JOB INPUT SORTWRK NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1
LINE REGION BRANCH EMPNAME
608
CA Easytrieve® Report Generator 11.6
Sort Procedures
CA Easytrieve® Report Generator normally sorts all input records and outputs them to the file you specify. The output file
usually has the same format and length as the input file. However, sometimes you may want to sort only certain records or
modify the contents. To do this, you can write a sort procedure, which must immediately follow the SORT statement.
You can code any valid CA Easytrieve® Report Generator statement in a sort procedure, but you cannot code statements
that generate input/output. Invalid statements are:
• COMMIT
• DELETE
• DISPLAY
• FETCH
• GET
• IDMS
• INSERT
• POINT
• PRINT
• PUT
• READ
• RETRIEVE (IDMS)
• ROLLBACK
• SELECT (SQL)
• SELECT (IDMS)
• SQL
• UPDATE
• WRITE
Note: For debugging purposes, you can DISPLAY to the system output device (SYSPRINT/SYSLST).
The only valid field references within a sort procedure are:
• Any field of the input file
• Any working storage field
• System-defined fields such as SYSDATE and RECORD-LENGTH
Sorting a Selected Portion of a File
CA Easytrieve® Report Generator supplies input records to your sort procedure one at a time. If you code a BEFORE
procedure, a SELECT statement must be executed for each record that you want to sort.
The following example illustrates how to code an output file that will contain only a reordered subset of the input file. The
output file contains only those records for which the SELECT statement is executed:
FILE PERSNL FB(150 1800)
%PERSNL
FILE SORTWRK FB(150 1800) VIRTUAL
COPY PERSNL
SORT PERSNL TO SORTWRK USING +
(REGION, BRANCH, DEPT, +
NAME-LAST, NAME-FIRST) +
NAME MYSORT BEFORE SCREENER
*
SCREENER. PROC
IF MARITAL-STAT = 'S' AND SEX = 1
609
CA Easytrieve® Report Generator 11.6
SELECT
END-IF
END-PROC
*
JOB INPUT SORTWRK NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1
LINE REGION BRANCH DEPT NAME-LAST NAME-FIRST
Synchronized File Processing
You can use the Synchronized File Processing (SFP) facility with one file or multiple files:
• Synchronized File Input performs match/merge operations on multiple files.
• Single File Keyed Processing compares the contents of a key field or fields from one record to the next in a single file.
This article includes the following information:
Synchronized File Input
CA Easytrieve Report Generator has a twofold solution to help you avoid coding complex logic for match/merge
operations:
• Automatic input that includes a universally adaptable match/merge algorithm
• Special conditional expressions that help to determine simple, yet precise file relationships
The synchronized file match/merge algorithm is based on the following assumptions and rules:
• Two or more files capable of being processed sequentially can be accessed.
• All files that are involved in the operation must be in ascending order by their key values.
• The number of keys for each file is identical.
• Corresponding keys of all files must be either alphanumeric or numeric. An alphanumeric key must be alphanumeric in
all files, but can have different lengths. A numeric key must be numeric in all files, but can have different data types (N,
P, U, B, F, I) and lengths.
• Because the algorithm must read ahead to perform a match/merge, INDEXED, RELATIVE, and input files cannot be
updated during synchronized file processing.
• You can use the POINT statement to position an INDEXED or RELATIVE file at a record other than the first record
before processing. Use a START procedure to perform the positioning.
Example
The INPUT parameter of the JOB statement designates files and their keys for synchronized file input. The following
example illustrates various synchronized file and key combinations:
FILE FILE1 ...
KEY1A 1 5 A
KEY1B 6 4 P
...
KEY1X ...
...
FILE FILE2 ...
KEY2A 24 5 A
KEY2B 1 2 B
610
CA Easytrieve® Report Generator 11.6
...
KEY2X ...
...
FILE FILEN ...
KEYNA 17 5 A
KEYNB 10 7 N
...
KEYNX ...
...
JOB INPUT(FILE1 KEY KEY1A +
FILE2 KEY KEY2A)
...
JOB INPUT (FILEN KEY(KEYNB, KEYNA) +
FILE1 KEY(KEY1B, KEY1A) +
FILE2 KEY(KEY2B, KEY2A))
...
JOB INPUT (FILE1 KEY(KEY1A ...) +
... +
FILEN KEY(KEYNA ...))
...
...
Record Availability
Records from files in CA Easytrieve Report Generator synchronized file input are made available for processing based
on the relationship of the files' keys. Records with the lowest keys are made available first, and the match is hierarchical
based on the order of the files that are specified on the JOB statement.
The following three input files show an example of synchronized file input:
FILE1 FILE2 FILE3
1 2 1
2 3 A 3
3 A 3 B 4
3 B 4 A 5
8 A 4 B 7
8 B 6 8 A
9 7 8 B
The key is the single numeric digit and the letter indicates duplicates for illustrative purposes. The JOB statement to
process the three files for the match/merge operation is:
JOB INPUT (FILE1 KEY(KEY1) +
FILE2 KEY(KEY2) +
FILE3 KEY(KEY3)) NAME MYPROG
Duplicate key values affect record availability differently, based on which file contains the duplicates. Remember, the
matching algorithm is hierarchical, so the key is exhausted on the lowest level before another record is processed from
the next higher-level file.
Match/Merge Operation Output
611
CA Easytrieve® Report Generator 11.6
The following example illustrates the match/merge output from the synchronized file input process. The output shows the
result of each iteration (loop) through the JOB activity. N/A under a file indicates that a record from the file is not available
and no fields from this file can be referenced during the associated iteration.
Note: CA Easytrieve Report Generator provides special IF statements to help you determine record availability. See
Special IF Statements for more information.
JOB FILE1 FILE2 FILE3
ITERATION RECORD RECORD RECORD
1 1 N/A 1
2 2 2 N/A
3 3A 3A 3
4 3A 3B N/A
5 3B N/A N/A
6 N/A 4A 4
7 N/A 4B N/A
8 N/A N/A 5
9 N/A 6 N/A
10 N/A 7 7
11 8A N/A 8A
12 8A N/A 8B
13 8B N/A N/A
14 9 N/A N/A
Look at iterations 3 trough 5 in this output. FILE1 and FILE2 both contain two records with a key value of 3. FILE3
contains only one record of key 3. CA Easytrieve Report Generator processes these records as follows:
• Iteration 3 -- The first record 3 from FILE1 and FILE2 and the only record with key 3 from FILE3 are available.
• Iteration 4 -- Because the next record on FILE3 is a key 4 record and there are still key 3 records to process in the
other files, FILE3's record is not available. CA Easytrieve Report Generator goes back to FILE2 and gets the next key
3 record. The original key 3 record from FILE1 and the second key 3 record from FILE2 are available.
• Iteration 5 -- Because the next record on FILE2 is a key 4 record and there is still a key 3 record on FILE1 to process,
FILE2 is now unavailable. CA Easytrieve Report Generator returns to FILE1 and retrieves the next record. This time
the only record available is the second key 3 record from FILE1.
Special IF Statements
CA Easytrieve Report Generator provides a simple way of determining the contents of current synchronized file input with
special conditional expressions.
MATCHED
Use the MATCHED test to determine the relationship between the current record of one file and the current record of one
or more other files:
IF [NOT] MATCHED [file-name-1 ... file-name-2 ...]
Using the table of automatic synchronized file input in the Match/Merge Operation Output section if this article, the
MATCHED test provides the following conclusions:
• IF MATCHED is true for JOB iteration 3.
• IF MATCHED FILE1, FILE3 is true for JOB iterations 1, 3, 11, and 12.
• IF MATCHED FILE2, FILE3 is true for JOB iterations 3, 6, and 10.
612
CA Easytrieve® Report Generator 11.6
File Existence
To determine the presence of data from a particular file, use the following special conditional expressions:
IF [NOT] file-name
IF [NOT] EOF file-name
When the IF file-name condition is true, a record from that file is present and available for processing. The IF NOT file-
name condition is true when the file does not contain a record with a current key. When this condition is true, no fields
from the file can be referenced in the activity. If you reference a field in an unavailable file, CA Easytrieve® Report
Generator issues a runtime error.
Using the table of automatic synchronized file input in the Match/Merge Operation Output section of this article, the special
conditional expressions provide the following conclusions:
• IF FILE1 is true for JOB iterations 1 through 5 and 11 through 14.
• IF NOT FILE2 is true for JOB iterations 1, 5, 8, and 11 through 14.
• IF EOF FILE2 is true for JOB iterations 11 through 14.
DUPLICATE, FIRSTDUP, and LASTDUP
The DUPLICATE, FIRST-DUP, and LAST-DUP tests determine the relationship of the current record of a file to the
preceding and following records in the same file:
{DUPLICATE}
IF [NOT] {FIRST-DUP} file-name
{LAST-DUP }
Using the table of automatic synchronized file input in the Match/Merge Operation Output section of this article, the record
relationship tests provide the following conclusions:
• IF DUPLICATE FILE1 is true for JOB iterations 3 through 5 and 11 through 13.
• IF FIRST-DUP FILE2 is true for JOB iterations 3 and 6.
• IF LAST-DUP FILE3 is true for JOB iteration 12.
The FIRST-DUP and LAST-DUP conditions are also DUPLICATE conditions. A record that satisfies the IF LAST-DUP or
IF FIRST-DUP condition also satisfies the IF DUPLICATE condition.
For more detailed examples of conditional expressions, see the Language Reference section.
Updating a Master File
The next example illustrates updating a master file based on matching transaction file records. The program assumes:
• A new master record is written when a match exists between the master file and the transaction file.
• There should be no duplicate transactions for a given master record. If this occurs, the first duplicate is processed but
subsequent duplicates are bypassed.
• No transaction records should exist without a matching master record. If this occurs, the record is displayed on an error
report and processing is bypassed.
FILE OLDMSTR SEQUENTIAL
O-KEY 1 2 N
O-AMT 3 3 N
FILE TRANS SEQUENTIAL
T-KEY 1 2 N
613
CA Easytrieve® Report Generator 11.6
T-AMT 3 3 N
FILE NEWMSTR SEQUENTIAL
N-KEY 1 2 N
N-AMT 3 3 N
JOB INPUT (OLDMSTR KEY(O-KEY) +
TRANS KEY(T-KEY)) NAME MYPROG
* FOR MATCHED: UPDATE WITH TRAN AMT AND PUT NEWMSTR.
* IF TRAN IS A DUPLICATE BUT NOT THE FIRST, BYPASS THE RECORD.
IF MATCHED
IF DUPLICATE TRANS AND NOT FIRST-DUP TRANS
GOTO JOB
END-IF
MOVE O-KEY TO N-KEY
N-AMT = O-AMT + T-AMT
PUT NEWMSTR
GOTO JOB
END-IF
* ON OLDMSTR ONLY: PUT THE NEWMSTR WITHOUT ANY UPDATE.
IF OLDMSTR
PUT NEWMSTR FROM OLDMSTR
GOTO JOB
END-IF
* ON TRANS ONLY: PRINT ERROR REPORT.
IF TRANS
PRINT ERROR-RPT
GOTO JOB
END-IF
*
REPORT ERROR-RPT
TITLE 'REPORT OF TRANSACTION WITH INVALID KEYS'
LINE T-KEY T-AMT
Single File Keyed Processing
Using Synchronized File Processing on a single file allows you to compare the contents of a key field or fields from one
record to the next and use IF tests to group records according to the key fields. The file name is coded on the JOB INPUT
statement as follows:
JOB INPUT (filename KEY (keyfield...))
Using single file input lets you determine the start of a new key value and the end of the current key value using IF tests.
The following IF statement determines the start of a new key:
IF FIRST-DUP filename OR NOT DUPLICATE filename
The next IF statement determines the end of the current key:
IF LAST-DUP filename OR NOT DUPLICATE filename
The file must be in ascending order by its key values.
614
CA Easytrieve® Report Generator 11.6
PRINTER Files
CA Easytrieve® Report Generator enables you to create files with a device type of PRINTER to write printed output with
the REPORT and/or DISPLAY statements. See Routing Printer Output for information about output creation. A PRINTER
file can be directed to one of the following destinations:
• The user's terminal
• Any other terminal (only in CICS)
• Your operating system's spooling subsystem
• An external data set
The FILE statement for the PRINTER file determines the destination.
Contents
Defining a PRINTER File
To specify a PRINTER file, code PRINTER as the device type on the FILE statement. To designate the destination of the
file, specify the data set type. The data set type can be one of the following:
• TERMINAL indicates that the output for the printer is routed to a terminal. The terminal can be a display terminal
or an online CICS printer terminal. In CICS, you can specify the ID of a terminal other than the originating user's
terminal. When you do not specify a terminal ID (regardless of operating environment), the output is routed back to the
originating terminal.
• SPOOL indicates that the output for this printer is routed to the operating system spooling subsystem. You can also
specify the output class, destination node, and destination userid. In CMS, spooling requires that the user's machine
has its printer spooled to RSCS.
• If you are not executing in a CICS environment, SYSNAME associates the PRINTER file to an external data set. If you
do not specify a valid data set type for the PRINTER file, CA Easytrieve® Report Generator attempts to write the output
to an external data set. When SYSNAME is not coded for an external data set, the file name is used as the external
name of the file. In non-mainframe environments, SYSNAME can associate a PRINTER file with the standard output
device 'stdout'.
SYSPRINT
SYSPRINT is a system-defined PRINTER file where printed output is sent unless otherwise specified. You can override
this default by specifying the name of your PRINTER file on the REPORT or DISPLAY statement. SYSPRINT is routed to
the destination specified in your site options. This may cause the output to be sent to one of the above destinations. For
more information, see your system administrator.
Non-Mainframe Files
The following guidelines apply when you code the FILE statement in non-mainframe environments.
Contents
File Type
The FILE statement for each file specifies the type of CA Easytrieve® Report Generator access. CA Easytrieve® Report
Generator supports SEQUENTIAL, INDEXED, and RELATIVE file types. SEQUENTIAL is the default if not specified.
INDEXED files can be processed using various access methods. See Execute a Program in Using.
615
CA Easytrieve® Report Generator 11.6
Record Format
Sequential files can have fixed or variable format records. Variable format records are line-feed (newline) delimited. Only
text files where the delimiter cannot occur in data can be variable. Binary data cannot be stored in a sequential variable
file because of the delimiter. You should set your record length to the length of the longest text. CA Easytrieve® Report
Generator reads the file for record-length-plus-one characters, or up to a newline character, whichever comes first. If no
newline character is present, CA Easytrieve® Report Generator issues an I/O error.
Fixed format records are fixed in length. The record length of the file determines where each record in the file begins. For
example, if a file has a record length of 20, bytes 0 to 19 make up the first record, bytes 20 to 39 make up the second
record, and so on. You can store binary data in fixed format files. Because fixed format records are not line-feed delimited,
you can get unpredictable results viewing or editing them.
Logical Record Length
You should specify the logical record length for each file. The defaults CA Easytrieve® Report Generator may assume
most likely are wrong.
• If you set the record length of a variable file too short, an error occurs.
• If you set the record length of a fixed file incorrectly, any record after the first appears to have fields shifted out of
place. Often, this causes data errors.
Generally, CA Easytrieve® Report Generator computes the default record length to be the greater of the following items:
• The highest location of a field defined in the file
• The WORKAREA parameter of the FILE statement
• The logical record length specified on the FILE statement
CISAM
Creating C-ISAM files requires that CA Easytrieve® Report Generator know what field represents the key of the record.
CA Easytrieve® Report Generator receives key information from C-ISAM after the files are created. Currently, CA
Easytrieve® Report Generator supports only unique single-keyed C-ISAM files and only as INDEXED files.
CA Easytrieve® Report Generator does not directly support all C-ISAM data types. The following table shows the C-ISAM
data types and their CA Easytrieve® Report Generator equivalents:
C-ISAM Data Type CA Easytrieve® Report Generator Field Definition
CHARTYPE xA
INTTYPE 2I
LONGTYPE 4I
FLOATTYPE 4 A*
DOUBLETYPE 8 A*
DECIMALTYPE x A*
• These C-ISAM numeric data types are not directly usable within CA Easytrieve® Report Generator. C-ISAM provides
functions to convert between their machine-independent data representation and the internal representation required
by CA Easytrieve® Report Generator when it executes. You can call these routines from a FILE MODIFY exit to
reformat data into any of the various CA Easytrieve® Report Generator numeric data types. A sample exit is supplied
with CA Easytrieve® Report Generator as CISAMXIT.c.
• C-ISAM execution requires special execution setup. For more information about executing your C-ISAM program,
see Using.
616
CA Easytrieve® Report Generator 11.6
Windows Indexed Files
Creating Windows Indexed files requires that CA Easytrieve® Report Generator know what field represents the key of the
record. CA Easytrieve® Report Generator receives key information from the files after the files are created. Currently, CA
Easytrieve® Report Generator supports only unique single-keyed indexed files and only as INDEXED files.
Report Processing
A major function of many CA Easytrieve Report Generator programs is to produce printed reports. The non-procedural
nature of CA Easytrieve Report Generator report syntax is readily adaptable to the production of basic and extremely
complex reports, both with minimum programming effort. Two statements generate printed output:
• The PRINT statement initiates the basic declarative report facility.
• The DISPLAY statement produces single print lines on print files.
PRINT is the preferred method because of its many automatic facilities. This section primarily discusses report processing
using the PRINT statement. Using the DISPLAY statement to mix single print lines within a report is discussed with report
procedures.
Basic Report Structure
The CA Easytrieve Report Generator report facility is basically declarative; you need only define the format and content
of the report and the product creates the necessary instructions to produce the report. The following exhibit illustrates the
basic structure of a CA Easytrieve Report Generator job with report processing. You can define one or more reports for
each activity.
Figure 47: basic_report_structure
NOTE
You can use the CA Easytrieve/Online Report Painter to automate the coding of a report declaration. For more
information, see Design and Run a Report.
617
CA Easytrieve® Report Generator 11.6
PRINT Statement (Report Processing)
The PRINT statement activates the report logic that is defined by REPORT declarations. CA Easytrieve Report
Generator extracts the data that is required for the requested report, formats it in the specified manner, and sends it to the
printer. The immediate result of a PRINT statement is one of the following actions:
• Data output to a print file
• Data output to a work (or spool) file
NOTE
Output to a printer can be sent to a terminal. See Routing Printer Output for information.
CA Easytrieve Report Generator automatically creates work file records when:
• The report is sequenced.
• Another report is already using the associated print file (when you have multiple reports in a single JOB activity).
The results of a PRINT statement are illustrated as follows:
Figure 48: PRINT statement result
Work File Records
Each work file record contains all of the data that is required to produce the report. The PRINT statements generate the
work file when it is necessary. The order of occurrence of work file fields is the same as the field reference occurrence in
the REPORT statements. In this example, the underlined fields determine work file record contents:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
618
CA Easytrieve® Report Generator 11.6
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
DTLCTL EVERY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
Figure 49: Work File Record
By default, work files are written to the CA Easytrieve Report Generator system work file, xxxVFM (where xxx is the
value of WKDSNPF in the options table). The algorithm for naming work files is xxxRnnn, where xxx is the value of the
WKDSNPF option and nnn is the sequential number of the report within the JOB activity. A typical work file name for the
first work file in a JOB is EZTR001.
To save the work file contents for future processing, code the FILE parameter on the REPORT statement. The
corresponding FILE statement, coded in the library, must identify a sequential file. You must also specify that the work
file's record length is at least as long as the dynamically created work file record. Records should be blocked to a
reasonable value to ensure efficient processing. This technique can also be used to offload the amount of Virtual File
Manager (VFM) space that is required by the program to another file.
Large Reports
If you have multiple large reports in a program, you can code the WORKFILE YES parameter on the PARM statement or
set the WORKFILE site option to Y. This allows you to use a report work file without coding a FILE statement and a FILE
parameter on the REPORT statement for every report in your program. REPORT WORKFILEs are dynamically allocated,
no DD statements are required to be coded in the JCL.
If you code the WORKFILE DD statements in your JCL, the dynamic allocation will not be done.
If you manually code the DD statements, the DDname must conform to the format xxxRnnn, where xxx is the WKDSNPF
option in your site option table (EZT is the default) and nnn is the report number. For example, the first report in your
program would use the DD EZTR001.
We also recommend that you code a large block size in the JCL. The default DCB for the work file is FB with record and
block lengths set for maximum efficiency. For more information, see PARM Statement.
NOTE
Use VFM for small reports and all reports executing in CICS.
619
CA Easytrieve® Report Generator 11.6
PRINT Work File Processing
The normal termination process of each JOB activity, illustrated in the following diagram, includes the processing of any
print work files that are created during the JOB activity. If the JOB activity abends or terminates due to a STOP EXECUTE
statement, the print work files are not processed.
Figure 50: PRINT Work File Processing
Report Formats
620
CA Easytrieve® Report Generator 11.6
There are two basic report formats:
Standard Report
The CA Easytrieve® Report Generator default report format is the standard format illustrated below:
Figure 51: Default Report Format
Top Margin
The top margin is the space between the physical top of the form and the point to which the printer positions when a top-
of-form order is issued to the printer. The size of the top margin is controlled by the printer carriage tape or forms control
buffer.
Title Area
The optional title area consists of 1 to 99 title lines plus a title margin between the last title line and the first heading line.
Heading Area
The optional heading area consists of 1 to 99 heading lines plus a heading margin between the last heading line and the
report body.
Report Body
The report body consists of one or more occurrences of a line group. Each occurrence of a line group is 1 to 99 lines plus,
optionally, one or more blank lines between occurrences.
Bottom Margin
The bottom margin is the area remaining between the bottom of the report body and the physical bottom of the page.
621
CA Easytrieve® Report Generator 11.6
Label Report
The second report format is used to print labels. The following exhibit illustrates the basic label report page format:
Figure 52: Basic Label Report Page
A label line consists of one or more labels positioned across the label page. In this diagram, labels 1 to 4 compose a
label line. A single line group composes each label. CA Easytrieve® Report Generator produces a label for each PRINT
statement execution. CA Easytrieve® Report Generator formats the labels on the page in the order as numbered above.
DOWN and SIZE indicate the dimensions of each label.
Report Generation
You define a report in CA Easytrieve Report Generator by coding a REPORT statement followed by a series of report
definition statements. You must code the REPORT statement first in a report declarative. The REPORT statement
establishes the type and characteristics of the report. Although you can specify many REPORT statement parameters,
you probably will produce most reports using default parameter values. REPORT statement parameters provide a
simple way to define tailored reports. For complete explanations of REPORT statement parameters, see the Language
Reference section.
This article contains the following information:
Report Definition Structure
A set of report definition statements defines every CA Easytrieve Report Generator report. The statements define the
report type, format, sequence, and data content. Report definition statements are the last statements coded in a JOB
activity. These statements must be coded in the following order:
...
JOB ...
...
622
CA Easytrieve® Report Generator 11.6
PRINT ...
...
REPORT
{ SEQUENCE
{ CONTROL
Report { SUM
Definition { TITLE { REPORT-INPUT
Statements { HEADING { BEFORE-LINE
{ LINE { AFTER-LINE
{ special-name procedures { BEFORE-BREAK
{ AFTER-BREAK
{ ENDPAGE
{ TERMINATION
You can code report procedures in any order and can define any number of reports for each JOB activity.
Report Definition Statements
The REPORT statement and its parameters define the physical attributes of your report. Code the following statements to
define the content of your report:
• SEQUENCE -- Optionally specifies the order of the report based on the content of one or more fields.
• CONTROL -- Identifies control fields that are used for a control report. A control break occurs whenever the value of
any control field changes or end-of-report occurs.
• SUM -- Specifies the quantitative fields which are totaled for a control report.
• TITLE -- Defines optional report title items and their position on the title line.
• HEADING -- Optionally defines an alternate heading for a field.
• LINE -- Defines the content of a report line.
For the complete syntax of these statements, see the Language Reference section.
System-Defined Fields
CA Easytrieve Report Generator automatically provides the special data fields that follow for your reports. These fields are
stored as part of working storage and are read-only.
• LINE-COUNT
Indicates the number of lines that are printed on the page.
• LINE-NUMBER
Indicates the number of the line being printed within the line group. See Standard Reports for information about line
groups.
• PAGE-COUNT
Indicates the number of pages printed.
• PAGE-NUMBER
Indicates the number of the page being printed.
• TALLY
Indicates the number of detail records in a control break. See Control Reports for more information.
• LEVEL
Indicates the control break level. See Control Reports for more information.
• BREAK-LEVEL
Indicates the highest field in the break. See Control Reports for more information.
623
CA Easytrieve® Report Generator 11.6
Standard Reports
The report facility in CA Easytrieve® Report Generator includes all of the functions necessary to produce most reports
very easily. Using CA Easytrieve® Report Generator report options, you can produce a report in almost any format. Most
reports, however, are variations of a CA Easytrieve® Report Generator standard report.
Contents:
Titles
The title is the first item printed on each report page. You can specify the report title with up to 99 TITLE statements. The
following diagram illustrates the title area of a report:
Figure 53: Title Area of a Report
The following are true for standard report titles:
• TITLE 01 items are printed at top-of-form.
• The current date and page count are placed at either end of the TITLE 01 line.
• Title lines are centered within the space indicated by the LINESIZE parameter of the REPORT statement.
• The title line number controls the vertical spacing of titles relative to the first title.
• The SPACE parameter controls the number of blank characters (spaces) between title items. SPACE also controls the
separation of the items in the line group in the report body.
Following are title statement examples and their resulting titles:
Statements:
FILE PERSNL FB(150 1800)
%PERSNL
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 50
624
CA Easytrieve® Report Generator 11.6
TITLE 01 'TEMPORARY EMPLOYEES'
TITLE 03 'IN DEPARTMENT' DEPT
LINE 01 ' '
Results:
2/09/09 TEMPORARY EMPLOYEES PAGE 1
IN DEPARTMENT 903
Overriding Defaults
You can override the automatic (default) functions associated with title contents and spacing to produce any required
report title. This may be necessary to produce reports that use preprinted forms as the output medium. You can use the
following parameters to produce nonstandard title content and spacing:
• NOADJUST -- Causes each title line to be left-justified on the page. NOADJUST may cause line items to overlay the
tags printed for SUMCTL TAG. COL positioning is necessary for tag to appear.
• NODATE and NOPAGE -- Inhibit current date and page count information from being placed on the first title line.
• COL -- Use the COL positioning parameter to position items in specific print columns. COL can be used with ADJUST
or NODADJUST.
Note: If you specify NOADJUST, the date overlays the leftmost positions of TITLE 1. To avoid this problem, do one of the
following:
• Use NODATE.
• Reserve an area for SYSDATE by specifying COL 10 for SHORTDATE or COL 12 for LONGDATE before the first item
on the TITLE statement.
Examples
The following examples of title statements use title content and space adjustment parameters. The report title that results
from the statements is also illustrated.
Statements:
FILE PERSNL FB(150 1800)
%PERSNL
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
REPORT REPORT1 NOADJUST NODATE NOPAGE
TITLE 01 COL 20 SSN
TITLE 02 SYSDATE COL 20 NAME
TITLE 03 COL 20 ADDR-STREET
TITLE 04 COL 20 ADDR-CITY -3 ',' +
-2 ADDR-STATE +5 ADDR-ZIP
LINE 01 ' '
Results:
625
CA Easytrieve® Report Generator 11.6
column column
0 2
1 0
025-30-5228
11/19/09 WIMN GLORIA
430 M ST SW 107
BOSTON , MA 02005
Report Headings
A report heading is normally printed for line items that are specified on LINE 01. Each heading is centered over its
associated line item. The following rules control the heading; the order in which they are listed indicates the hierarchy of
override.
1. The NOHEADING parameter of the REPORT statement inhibits the printing of any headings.
2. The HEADING statement sets the item heading content.
3. The HEADING parameter of the DEFINE statement sets the item heading content.
4. The field-name of the DEFINE statement sets the item heading content.
5. Line items that are literals do not have headings.
6. Only LINE 01 items have headings.
The following diagram illustrates the positioning of headings in a typical report. Line items might not always have the same
number of heading entries. In this case, the corresponding heading line area is blank for those items with no headings.
T I T L E A R E A
TITLESKIP space
HEADING
HEADING
Heading HEADING HEADING
area HEADING HEADING HEADING
line line literal line
report item item line item
body ... ... item ...
... ... ... ...
Example: Set Heading Content
This example illustrates statements that contain various heading options:
FILE PERSNL FB(150 1800)
SSN 4 5 P MASK '999-99-9999' +
HEADING('SOCIAL' 'SECURITY' 'NUMBER')
EMPNAME 17 20 A
NAME-LAST EMPNAME 8 A
NAME-FIRST EMPNAME +8 12 A
PAY-NET 90 4 P 2
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
*
626
CA Easytrieve® Report Generator 11.6
REPORT REPORT1 LINESIZE 65
HEADING PAY-NET ('NET', 'PAY')
LINE EMPNAME SSN '* NO OVERTIME *' PAY-NET
Based on the statements, the report output is as follows:
SOCIAL
SECURITY NET
NAME NUMBER PAY
WIMN GLORIA 025-30-5228 * NO OVERTIME * 251.65
BERG NANCY 121-16-6413 * NO OVERTIME * 547.88
Line Group
Lines compose the body of a report. The lines of a report are output in groups for each PRINT statement issued. All of the
LINE statements of the report make up a line group, which is also called a logical report line:
LINE ... }
LINE 02 ...} line or logical report
LINE 03 ...} group line
...
Line Item Positioning in Reports
Line item positioning uses the following rules:
• LINE 01 items and their associated headings are centered in an area whose length is controlled by the longer of the
following items:
– The line item
– The longest heading entry
The resulting value is called the item length.
• Data on LINE 02 through LINE 99 is left-justified under the LINE 01 data, regardless of the heading size.
• Blank characters (spaces) separate all line items according to the value of the SPACE parameter of the REPORT
statement.
Note: When CA Easytrieve® Report Generator analyzes a LINE statement according to these rules, the total number of
characters on that line must not exceed LINESIZE.
The following example illustrates line item positioning:
FILE PERSNL FB(150 1800)
SSN 4 5 P MASK '999-99-9999' +
HEADING('SOCIAL' 'SECURITY' 'NUMBER')
EMPNAME 17 20 A HEADING 'EMPLOYEE NAME'
NAME-LAST EMPNAME 8 A HEADING('LAST' 'NAME')
NAME-FIRST EMPNAME +8 12 A HEADING('FIRST' 'NAME')
ADDRESS 37 39 A
ADDR-STREET 37 20 A HEADING 'STREET'
ADDR-CITY 57 12 A HEADING 'CITY'
ADDR-STATE 69 2 A HEADING 'STATE'
627
CA Easytrieve® Report Generator 11.6
ADDR-ZIP 71 5 N HEADING('ZIP' 'CODE')
SEX 127 1 N HEADING('SEX' 'CODE')
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65
LINE EMPNAME SSN SEX
LINE 02 ADDR-STREET POS 2 ADDR-CITY
item area item area item area
1 5 10 15 1 5 10 1 4
............... ........... ....
SOCIAL
SECURITY SEX heading
EMPLOYEE NAME NUMBER CODE
WIMN GLORIA 025-30-5228 1 line
430 M ST SW 107 BOSTON group
Special Positioning
Sometimes the standard positioning of line items on a report is unsuitable for producing the desired result, as in the
case of aligning numeric fields on LINE 02 with the decimal point of corresponding fields on LINE 01. The POS line item
adjusting parameter left-justifies the corresponding fields, but when the LINE 02 field is not as long as the LINE 01 field,
the two fields are unaligned. If that happens, use the +offset or -offset line item adjustment parameter after the POS
parameter to adjust the position of the data.
The next example illustrates poor and good decimal alignment. The first occurrence of FLD2 on LINE 02 is not decimal-
aligned with FLD1 on LINE 01. To align the second occurrence correctly, an additional offset of 3 spaces (+3) is specified.
Statements:
DEFINE FLD1 W 4 P 2 VALUE 123.45
DEFINE FLD2 W 3 P 2 VALUE 678.90
JOB INPUT NULL NAME MYPROG
PRINT REPORT1
STOP
*
REPORT REPORT1 LINESIZE 40
LINE 01 FLD1 FLD1
LINE 02 FLD2 POS 2 +3 FLD2
Results:
poor good
column column
1 5 10 15 1 5 10 15
628
CA Easytrieve® Report Generator 11.6
............... ...............
FLD1 FLD1
123.45 123.45 line 01
678.90 678.90 line 02
Preprinted Form Production
Preprinted form production is another instance when standard line item positioning must be overridden. A very simple
example of this override is W-2 form printing in a payroll application. The following code shows the report declarative
statements necessary to print a hypothetical W-2 form. This is followed by the result on the preprinted form.
REPORT PAGESIZE 20 NOADJUST NOHEADING SPACE 1
LINE COL 7 'YOUR COMPANY NAME' COL 33 '903' +
COL 39 '12-3456789'
LINE 02 COL 7 'YOUR COMPANY STREET'
LINE 03 COL 7 'YOUR COMPANY CITY STATE ZIP'
LINE 10 COL 7 SSN COL 23 YTD-FEDTAX +
COL 39 YTD-WAGES +
COL 54 YTD-FICA
LINE 12 COL 7 EMP-NAME COL 39 YTD-WAGES
LINE 14 COL 7 EMP-STREET
LINE 15 COL 7 EMP-CITY EMP-STATE EMP-ZIP
SPREAD Parameter
The SPREAD parameter of the REPORT statement offers a unique way to space line items. When you use reports as
work sheets, it is often desirable to space line items as far apart as possible. SPREAD overrides the SPACE parameter of
the REPORT statement and creates report lines with the maximum number of spaces between each item, as this example
illustrates:
Statements:
DEFINE FLD1 W 4 P 2 VALUE 123.45
DEFINE FLD2 W 3 P 2 VALUE 678.90
DEFINE FLD3 W 4 P 2 VALUE 1129.59
JOB INPUT NULL NAME MYPROG
PRINT REPORT1
PRINT REPORT2
STOP
*
REPORT REPORT1 SPREAD LINESIZE 65
TITLE 'S P R E A D EXAMPLE'
LINE FLD1 FLD2 FLD3
*
REPORT REPORT2 NOSPREAD LINESIZE 65
TITLE 'NOSPREAD EXAMPLE'
LINE FLD1 FLD2 FLD3
Results:
629
CA Easytrieve® Report Generator 11.6
11/19/86 S P R E A D EXAMPLE PAGE 1
FLD1 FLD2 FLD3
123.45 678.90 1,129.59
................................................................. .
11/19/86 NOSPREAD EXAMPLE PAGE 1
FLD1 FLD2 FLD3
123.45 678.90 1,129.59
Label Reports
You can use the label report capability of CA Easytrieve® Report Generator to print mailing labels and other applications
that require inserting variable data in a repetitious format. A label report is different from a standard report in the following
ways:
• Label reports do not have titles and headings.
• Multiple labels can be printed side-by-side.
• Controlled label reports allow for control breaks, but do not automatically total quantitative fields. Totals, however, can
be specified on a SUM statement and processed in BEFORE-BREAK and AFTER-BREAK procedures.
You can use the label report function whenever a complete logical print page is to be produced by each PRINT statement.
Consider the W-2 form-printing example; print time could be substantially reduced by having 2-up forms. You can then
modify report declaration statements as shown in the following code. A sample result follows the code.
REPORT LBLS LABELS (ACROSS 2 DOWN 15 SIZE 65 NEWPAGE) SPACE 1
LINE 01 COL 7 'YOUR COMPANY NAME' COL 33 '903' +
COL 39 '12-3456789'
LINE 02 COL 7 'YOUR COMPANY STREET'
LINE 03 COL 7 'YOUR COMPANY CITY STATE ZIP'
LINE 10 COL 7 SSN COL 23 YTD-FEDTAX +
COL 39 YTD-WAGES +
COL 54 YTD-FICA
LINE 12 COL 7 EMP-NAME COL 39 YTD-WAGES
LINE 14 COL 7 EMP-STREET
LINE 15 COL 7 EMP-CITY EMP-STATE EMP-ZIP
Sample Label Report
630
CA Easytrieve® Report Generator 11.6
CONTROL Statement
You can use the CONTROL statement with label reports to truncate a group of labels. Truncating makes it easy to
separate labels after they are printed. The following example demonstrates how a new label page starts when the control
field changes.
Statements:
FILE PERSNL FB(150 1800)
%PERSNL
FILE SORTWRK FB(150 1800) VIRTUAL
COPY PERSNL
SORT PERSNL TO SORTWRK +
USING (ADDR-STATE, ADDR-ZIP) NAME MYSORT
JOB INPUT SORTWRK NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LABELS
CONTROL ADDR-STATE NEWPAGE
LINE 01 NAME
LINE 02 ADDR-STREET
LINE 03 ADDR-CITY, ADDR-STATE, ADDR-ZIP
Results:
xxx xxx xxx xxx
xxx xxx xxx xxx
xxx xxx xxx xxx
xxx
xxx
xxx
631
CA Easytrieve® Report Generator 11.6
(goes to new page when ADDR-STATE changes)
yyy yyy
...
Any labels remaining on a line are left unused. The optional NEWPAGE parameter causes a top-of-page for the next print
line.
XML Reports
You can use the XML report capability of CA Easytrieve® Report Generator to create a file formatted in Extensible Markup
Language (XML). A hierarchically-structured XML file is built according to the field relationships defined by the REPORT,
CONTROL, and LINE statements. The CONTROL fields become group (or parent) elements, and the LINE statement
fields become the lowest level child elements. The REPORT name (from the REPORT statement) becomes the lowest-
level group element that contains (or wraps) all the fields specified on the LINE statement.
Just as with a non-XML report, the statements used to write records to an XML file are PRINT and DISPLAY. With each
PRINT executed, all LINE statement fields are formatted as XML and then written to the printer file. DISPLAY statement
output records are not formatted as XML data. The data is written exactly as a DISPLAY would write data to a non-XML
report file. Just as with non-XML reports, the location of the DISPLAY statement records in the XML file depends on
whether the XML report is spooled.
For an XML report, no printed output is generated. There are no control totals or summary data lines printed or written to
any file.
When using an XML report keep the following items in mind:
• For an XML report, all spacing or positioning parameters (such as NOADJUST, COL, SKIP, and Font-Numbers) are
ignored. This is because an XML file contains only field names (or HEADING values) and data values.
• The reporting SEQUENCE statement functions in an XML report as it does with non-XML. You can use it to build the
XML output file in the required order.
• The reporting TITLE statement is ignored for XML reports, because the concept of page and column headings does
not apply to XML data.
• Report procedures are still invoked as they are in non-XML reports. However, BEFORE-PAGE and AFTER-PAGE are
ignored, because there is no page concept in an XML report.
• If a PRINTER FILE is specified on the REPORT statement in an XML report, and if a MODIFY EXIT is defined for that
file, each physical record being written to the printer file is passed to the exit. This is the same as for non-XML reports.
• A SUMFILE can be produced from an XML report just as it is from a non-XML report.
• The XML element tag is built from the HEADING value or the Fieldname. Since CA Easytrieve® Report Generator
does not force XML-compliant characters for HEADINGs or Fieldnames, you must be sure the characters used are
valid as XML tags. For example, because a space character is not valid in an XML tag name, a HEADING of 'EMP
NAME' must be changed to something like 'EMP_NAME'.
The following example demonstrates how an XML file is created:
Statements:
FILE PERSNL FB(150 1800)
%PERSNL
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 XML
632
CA Easytrieve® Report Generator 11.6
CONTROL REGION BRANCH
LINE 01 DEPT EMPNO EMPNAME
Results:
<REPORT1_REPORT>
<REGION REGION="1">
<BRANCH BRANCH="01">
<REPORT1>
<DEPT>100</DEPT>
<EMPLOYEE_NUMBER>12345</EMPLOYEE_NUMBER>
<EMPLOYEE_NAME>JOHNNY BGOOD </EMPLOYEE_NAME>
</REPORT1>
<REPORT1>
<DEPT>100</DEPT>
<EMPLOYEE_NUMBER>12346</EMPLOYEE_NUMBER>
<EMPLOYEE_NAME>CHUCK ROCKS </EMPLOYEE_NAME>
</REPORT1>
</BRANCH>
<BRANCH BRANCH="02">
<REPORT1>
<DEPT>100</DEPT>
<EMPLOYEE_NUMBER>99999</EMPLOYEE_NUMBER>
<EMPLOYEE_NAME>JAMES DEAN </EMPLOYEE_NAME>
</REPORT1>
</BRANCH>
</REGION>
<REGION REGION="2">
<BRANCH BRANCH="01">
<REPORT1>
<DEPT>150</DEPT>
<EMPLOYEE_NUMBER>11111</EMPLOYEE_NUMBER>
<EMPLOYEE_NAME>JIM SHOE </EMPLOYEE_NAME>
</REPORT1>
</BRANCH>
</REGION>
</REPORT1_REPORT>
Sequenced Reports
Report sequence is controlled either by the order in which PRINT statements were issued or by the SEQUENCE
statement. You can print both standard reports and label reports in any sequence.
Report definitions that contain SEQUENCE statements cause the report data to be spooled to a temporary work file upon
execution of a PRINT statement. Work file usage is transparent.
The SEQUENCE function is performed by invoking your installation's sort program or, in CICS or UNIX, the sort provided
with CA Easytrieve® Report Generator. The temporary work file is input to the sort program. When the sort is complete,
the work file data is retrieved and the report is produced.
Only those data items used in the report are sorted. The sorted output is directly printed from the sort. These attributes
combine to make the SEQUENCE facility of CA Easytrieve® Report Generator extremely efficient.
633
CA Easytrieve® Report Generator 11.6
CONTROL Reports
The CONTROL statement specifies that a report automatically accumulates and prints totals of quantitative report
information. The report accumulates information according to the hierarchy indicated on the CONTROL statement.
Contents
Terminology
The following terms are used throughout the discussion on control reports:
• A control field is any field named on a CONTROL statement to establish the hierarchy of a control report.
• A control break occurs whenever any field of the control hierarchy changes value.
• A total line is a logical line group in a report body that contains control totals. These control totals can contain subtotal
or final values. Total lines are normally annotated with the value of control fields according to the SUMCTL parameter
of the REPORT statement. To do this, list the control fields first on the LINE statement.
• A detail line is the same line data as in a standard body line (not a total line). Control fields on detail lines are printed
according to the DTLCTL parameter of the REPORT statement. The SUMMARY parameter of the REPORT statement
inhibits the printing of detail lines on a control report.
• Accumulators are system-created fields that contain totals. Accumulators are created for:
– All fields designated on the SUM statement
– All active file or W storage quantitative fields designated on the line group (LINE nn) statements, if a SUM statement
is not specified. (Quantitative fields are numeric fields with a decimal point designation of 0 through 18.)
• SUMFILE data is the contents of control fields and accumulators at each minor control break.
Data Reference
In general, report statements and procedures can reference any field of an active file or working storage. (Some report
procedures have minor restrictions, which are described with the associated procedure.)
Statements and procedures can directly reference data for detail lines in noncontrol reports. When control or total fields
are referenced, CA Easytrieve® Report Generator automatically adjusts so that SUMFILE data is used. This assures
access to the field actually used in the report. SUMFILE data includes all control fields and 10-byte (18-digit) packed fields
for all accumulators. See Summary File for more information.
TALLY
TALLY is a system-defined field for control reports. TALLY contains the number of detail records that comprise a control
break. You can use TALLY on a LINE statement or you can use it in calculations within report procedures. TALLY is
commonly used to determine averages for a control break.
TALLY is a 10-byte packed decimal field with zero decimal places. This definition is used for calculations contained within
report procedures. REPORT TALLYSIZE defines the number of digits that are printed for TALLY. A TALLY accumulator is
created for each control break level.
LEVEL
LEVEL is a system-defined field provided for control reports. The field is defined as a two-byte binary field. The value of
LEVEL indicates the control break level and varies from 0 to n + 1, where:
• LEVEL = 0 when processing detail lines
• LEVEL = n for total line processing at each control level
• LEVEL = n + 1, when processing FINAL totals
The LEVEL values for fields on the CONTROL statement are as follows:
634
CA Easytrieve® Report Generator 11.6
REPORT
SEQUENCE REGION BRANCH
CONTROL REGION BRANCH
LEVEL = 1
LEVEL = 2
LEVEL = 3 (FINAL)
The following diagram illustrates the relationship between control fields, accumulators, and LEVEL:
SUMFILE data
Control Fields Accumulators LEVEL
control control control SUM SUM 1
field-n .. field-2 field-1 TALLY field-1 ... field-n
TALLY ... 2
...
TALLY ... n
SUM SUM
FINAL TALLY field-1 ... field-n n + 1
See BREAKLEVEL for more information.
BREAK-LEVEL
BREAK-LEVEL is a system-defined field whose value indicates the highest control break level. The following example
illustrates using BREAK-LEVEL to display an appropriate message in a BEFORE-BREAK procedure:
REPORT RPT
SEQUENCE REGION BRANCH
CONTROL REGION BRANCH
LINE REGION BRANCH NAME PAY-GROSS
BEFORE-BREAK. PROC
IF LEVEL = 1 . * processing lowest break
IF BREAK-LEVEL = 1 . * only branch is breaking
DISPLAY '*** BRANCH TOTALS'
ELSE-IF BREAK-LEVEL = 2. * region is breaking too
DISPLAY '*** BRANCH AND REGION TOTALS'
ELSE-IF BREAK-LEVEL = 3. * final report totals
DISPLAY '*** BRANCH, REGION, AND FINAL TOTALS'
END-IF
END-IF
END-PROC
635
CA Easytrieve® Report Generator 11.6
CA Easytrieve® Report Generator invokes the BEFORE-BREAK procedure before printing summary lines. See Report
Procedures for more information.
In the above example, LEVEL and BREAK-LEVEL fields are used to determine the appropriate message to be displayed
before the summary lines are printed. Testing for LEVEL 1 tells us that CA Easytrieve® Report Generator is going to print
the first summary line next (BRANCH totals). When BREAK-LEVEL is 1, only the BRANCH field is breaking. Therefore,
we want to display a message stating this. When BREAK-LEVEL is 2, the REGION field is breaking. This causes both
BRANCH and REGION summary lines to print. When BREAK-LEVEL is 3, CA Easytrieve® Report Generator prints
BRANCH, REGION, and final summary lines.
Note: (Mainframe and UNIX only) An alternative to testing LEVEL and BREAK-LEVEL is to use IF field-name BREAK and
IF field-name HIGHEST-BREAK processing. Using the previous example, you can code the following for the same result:
REPORT RPT
SEQUENCE REGION BRANCH
CONTROL REGION BRANCH
LINE REGION BRANCH NAME PAY-GROSS
BEFORE-BREAK. PROC
IF BRANCH BREAK . * processing lowest break
IF BRANCH HIGHEST-BREAK . * only branch is breaking
DISPLAY '*** BRANCH TOTALS ***'
ELSE-IF REGION HIGHEST-BREAK . * region is breaking also
DISPLAY '*** BRANCH AND REGION TOTALS ***'
ELSE-IF BREAK-LEVEL = 3 . * final report totals
DISPLAY '*** BRANCH, REGION AND FINAL TOTALS ***'
END-IF
END-IF
END-PROC
Control Report Contents
The report body contains the only difference between standard and control report contents. Control reports print total lines
in addition to detail lines (optional). The following examples use two control fields (STATE and ZIP) containing data that is
two and five bytes long, respectively, and one quantitative field (PAY-NET) containing numeric data.
The standard control report contains standard report data plus total data. The following example illustrates the report body
of such a report. Detail and total lines are shown, with the totals illustrating the hierarchy of the report data.
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
636
CA Easytrieve® Report Generator 11.6
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
Line
Description Control Fields Accumulator
LAST-NAME STATE ZIP PAY-NET
detail BROWN IL 60076 678.90
detail BROWN 123.45
ZIP total IL 60076 802.35
detail JONES IL 60077 543.21
detail JONES 98.76
ZIP total IL 60077 641.97
STATE total IL 1444.32
detail SMITH TX 75218 666.66
detail SMITH 111.11
ZIP total TX 75218 777.77
STATE total TX 777.77
FINAL total 2222.09
The same report without the detail lines is a SUMMARY report. For example:
Statements:
FILE FILE1
LAST-NAME 1 20 A
STATE 21 2 A
ZIP 23 5 N
PAY-NET 28 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 SUMMARY +
DTLCTL NONE
637
CA Easytrieve® Report Generator 11.6
SEQUENCE STATE ZIP
CONTROL STATE ZIP
LINE 01 STATE ZIP PAY-NET
Data:
BROWN IL6007612345
BROWN IL6007667890
JONES IL6007709876
JONES IL6007754321
SMITH TX7521811111
SMITH TX7521866666
Results:
Line
Description Control Fields Accumulator
STATE ZIP PAY-NET
ZIP total IL 60076 802.35
ZIP total IL 60077 641.97
STATE total IL 1444.32
ZIP total TX 75218 777.77
STATE total TX 777.77
FINAL total 2222.09
This report contains only control totals because SUMMARY was specified on the REPORT statement.
DTLCTL
The REPORT statement DTLCTL parameter establishes the method for printing control field values on detail lines by
using the subparameters EVERY, FIRST, and NONE. The following is an example program using DTLCTL options:
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
DTLCTL option (* with option being EVERY, FIRST, or NONE *)
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
638
CA Easytrieve® Report Generator 11.6
LINE 01 LAST-NAME STATE ZIP PAY-NET
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
The next three examples show the results of using each of the DTLCTL options:
EVERY
EVERY prints all control fields on every detail line.
Line
Description Control Fields Accumulator
LAST-NAME STATE ZIP PAY-NET
detail BROWN IL 60076 678.90
detail BROWN IL 60076 123.45
ZIP total IL 60076 802.35
detail JONES IL 60077 543.21
detail JONES IL 60077 98.76
ZIP total IL 60077 641.97
STATE total IL 1444.32
detail SMITH TX 75218 666.66
detail SMITH TX 75218 111.11
ZIP total TX 75218 777.77
STATE total TX 777.77
FINAL total 2222.09
FIRST
FIRST prints all control fields on the first detail line at top-of-page and after each break.
Line
Description Control Fields Accumulator
LAST-NAME STATE ZIP PAY-NET
detail BROWN IL 60076 678.90
detail BROWN 123.45
639
CA Easytrieve® Report Generator 11.6
ZIP total IL 60076 802.35
detail JONES IL 60077 543.21
detail JONES 98.76
ZIP total IL 60077 641.97
STATE total IL 1444.32
detail SMITH TX 75218 666.66
detail SMITH 111.11
ZIP total TX 75218 777.77
STATE total TX 777.77
FINAL total 2222.09
NONE
NONE prints no control fields on detail lines.
Line
Description Control Fields Accumulator
LAST-NAME STATE ZIP PAY-NET
detail BROWN 678.90
detail BROWN 123.45
ZIP total IL 60076 802.35
detail JONES 543.21
detail JONES 98.76
ZIP total IL 60077 641.97
STATE total IL 1444.32
detail SMITH 666.66
detail SMITH 111.11
ZIP total TX 75218 777.77
STATE total TX 777.77
FINAL total 2222.09
SUMCTL
The SUMCTL parameter of the REPORT statement establishes the method for printing control field values on total lines
of a control report by using the subparameters ALL, HIAR, NONE, and TAG. (The DTLCOPY subparameter controls all
noncontrol nontotal values on total lines.) The following shows an example program using these parameters:
Statements:
FILE FILE1
640
CA Easytrieve® Report Generator 11.6
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMCTL option
(* with option being ALL, HIAR, NONE, or TAG *)
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
The next three examples illustrate the results of using All, HIAR, and NONE.
ALL
ALL prints all control fields on every total line.
Line
Description Control Fields Accumulator
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 678.90
BROWN 123.45
ZIP total IL 60076 802.35
JONES IL 60077 543.21
JONES 98.76
ZIP total IL 60077 641.97
STATE total IL 60077 1444.32
SMITH TX 75218 666.66
SMITH 111.11
ZIP total TX 75218 777.77
STATE total TX 75218 777.77
FINAL total TX 75218 2222.09
641
CA Easytrieve® Report Generator 11.6
HIAR
HIAR prints control fields in hierarchical order on total lines.
Line
Description Control Fields Accumulator
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 678.90
BROWN 123.45
ZIP total IL 60076 802.35
JONES IL 60077 543.21
JONES 98.76
ZIP total IL 60077 641.97
STATE total IL 1444.32
SMITH TX 75218 666.66
SMITH 111.11
ZIP total TX 75218 777.77
STATE total TX 777.77
FINAL total 2222.09
NONE
NONE prints no control fields on total lines.
Line
Description Control Fields Accumulator
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 678.90
BROWN 123.45
ZIP total 802.35
JONES IL 60077 543.21
JONES 98.76
ZIP total 641.97
STATE total 1444.32
SMITH TX 75218 666.66
SMITH 111.11
ZIP total 777.77
STATE total 777.77
642
CA Easytrieve® Report Generator 11.6
FINAL total 2222.09
TAG
Use the TAG subparameter of SUMCTL to annotate the total line with a description of the total values being printed. The
TAG subparameter of SUMCTL creates a line area on the left side of the total line. This LINE 01 item is governed by the
following rules:
• The length of the area is the length of the longest control-field-name plus seven.
• TOTAL preceded by the control-field-name is the annotation for control break totals.
• FINAL TOTAL is the annotation for the final totals line.
• The line item area is positioned at the left margin of the report.
The following example illustrates how tags appear on a report.
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMCTL TAG
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 678.90
BROWN 123.45
ZIP TOTAL 802.35
JONES IL 60077 543.21
JONES 98.76
643
CA Easytrieve® Report Generator 11.6
ZIP TOTAL 641.97
STATE TOTAL 1444.32
SMITH TX 75218 666.66
SMITH 111.11
ZIP TOTAL 777.77
STATE TOTAL 777.77
FINAL TOTAL 2222.09
DTLCOPY
When printing control reports (particularly a summary report) you may want to include detail information in total lines
(normally, CA Easytrieve® Report Generator prints only control field values and associated totals on total lines). The
DTLCOPY subparameter of SUMCTL causes detail field contents (values just prior to the break) to be printed on total
lines for LEVEL 1 breaks. The following example illustrates the use of DTLCOPY to print the contents of the LAST-NAME
detail field on the lowest level total line (ZIP).
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 802.35
644
CA Easytrieve® Report Generator 11.6
JONES IL 60077 641.97
IL 1444.32
SMITH TX 75218 777.77
TX 777.77
2222.09
DTLCOPYALL
DTLCOPYALL has the same effect as DTLCOPY, except that the detail fields are printed for all control break totals. The
following example illustrates the use of DTLCOPYALL to print LAST-NAME on all total lines.
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPYALL
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 802.35
JONES IL 60077 641.35
JONES IL 1444.32
SMITH TX 75218 777.77
SMITH TX 777.77
SMITH TX 2222.09
645
CA Easytrieve® Report Generator 11.6
Control Field Values in Titles
Occasionally, you may want to print control field values in report titles. For example, you can use control field annotation
within the title of a report to emphasize the structure of an organization, particularly at its higher levels. This technique
uses only basic report facilities, and does not require special parameters. The following example shows field annotation
within a report title.
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
11/23/09 REPORT FOR THE STATE OF IL PAGE 1
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 802.35
JONES IL 60077 641.97
IL 1444.32
11/23/09 REPORT FOR THE STATE OF TX PAGE 2
LAST-NAME STATE ZIP PAY-NET
SMITH TX 75218 777.77
TX 777.77
2222.09
646
CA Easytrieve® Report Generator 11.6
Overflow of Total Values
In control reports, line items for totaled fields define an area not only for detail lines, but also for corresponding total lines.
Since totals are normally larger than the detail, you need a means of expanding the item area. Without this expansion,
the item area might be too small to contain the totals. If your report contains this overflow condition, CA Easytrieve®
Report Generator automatically depicts it by setting the rightmost character of the item area byte to an asterisk (*), as the
following example illustrates:
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
*
JOB INPUT FILE1 NAME MYPROG
*
PRINT REPORT1
*
REPORT REPORT1 SUMSPACE 0 +
SUMCTL HIAR LINESIZE 65
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
2/11/09 REPORT FOR THE STATE OF IL PAGE 1
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 678.90
BROWN 123.45
IL 60076 802.35
JONES IL 60077 543.21
JONES 98.76
IL 60077 641.97
IL 444.32*
647
CA Easytrieve® Report Generator 11.6
2/11/09 REPORT FOR THE STATE OF TX PAGE 2
LAST-NAME STATE ZIP PAY-NET
SMITH TX 75218 666.66
SMITH 111.11
TX 75218 777.77
TX 777.77
222.09*
Controlling Overflow
You can control overflow using two methods, as illustrated by the following examples:
• Line item expansion -- Ensure that the detail field being totaled is large enough to absorb the totals. This example
illustrates how overflow can be prevented by effectively expanding the line item to six-digit positions.
– Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
T-PAY-NET W 6 N 2 HEADING ('PAY-NET')
*
JOB INPUT FILE1 NAME MYPROG
T-PAY-NET = PAY-NET
PRINT REPORT1
*
REPORT REPORT1 SUMSPACE 0 +
SUMCTL HIAR LINESIZE 65
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP T-PAY-NET
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
648
CA Easytrieve® Report Generator 11.6
2/11/09 REPORT FOR THE STATE OF IL PAGE 1
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 678.90
BROWN 123.45
IL 60076 802.35
JONES IL 60077 543.21
JONES 98.76
IL 60077 641.97
IL 1,444.32
2/11/09 REPORT FOR THE STATE OF TX PAGE 2
LAST-NAME STATE ZIP PAY-NET
SMITH TX 75218 666.66
SMITH 111.11
TX 75218 777.77
TX 777.77
2,222.09
• Item area expansion -- Expand the item area by using the SUMSPACE parameter of the REPORT statement. The
value of SUMSPACE is added to the length of detail fields to determine an adjusted line item length for the total field.
The resulting line item expansion is illustrated in the next example as a print edit mask.
– Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2 .* (999.99- mask without SUMSPACE specified)
*
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 SUMSPACE 1 +
SUMCTL HIAR LINESIZE 65
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
649
CA Easytrieve® Report Generator 11.6
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
2/11/09 REPORT FOR THE STATE OF IL PAGE 1
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 678.90
BROWN 123.45
IL 60076 802.35
JONES IL 60077 543.21
JONES 98.76
IL 60077 641.97
IL 1444.32 (9999.99- mask
with SUMSPACE 1)
2/11/09 REPORT FOR THE STATE OF TX PAGE 2
LAST-NAME STATE ZIP PAY-NET
SMITH TX 75218 666.66
SMITH 111.11
TX 75218 777.77
TX 777.77
2222.09 (9999.99- mask
with SUMSPACE 1)
Summary File
A summary file, which contains all the control and summed field values at each minor break, can be optionally generated
during processing of a control report. JOB activities in your program can subsequently process the summary file to provide
reports not otherwise available using the standard report facilities of CA Easytrieve® Report Generator.
You can produce a summary file by defining the file in the library and then referencing it with the REPORT SUMFILE
parameter.
The FILE statement must contain the file name, record format, logical record length, and block size. When you just want
to retain the file for the duration of the program, you can specify the file as an unblocked VIRTUAL file. The record format
can be any standard format. The record length must be large enough to contain the output data. Block size should be
appropriate for the specified format and record length.
The summary file record contains three parts:
1. Control field area -- A concatenation of the control fields specified on the CONTROL statement. The sum of the
lengths of the control fields defines the length of the control field area.
2. TALLY -- A 10-byte field.
3. Summed field area -- A concatenation of summed fields to form the remaining segment of the summary file record.
Each summed field is a 10-byte packed field with the same decimal specification as the source field.
650
CA Easytrieve® Report Generator 11.6
Therefore, the summary file record length is the sum of the control field area length, plus 10 bytes for TALLY, plus 10 times
the number of summed fields.
SUMFILE Example
The following example illustrates the use of SUMFILE data. The values of SFILE are listed in order of ascending
magnitude within SFILE-STATE, without reprocessing the original data.
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
FILE SFILE F(30)
SFILE-STATE 1 2 A
SFILE-ZIP 3 5 N
SFILE-TALLY 8 10 P 0
SFILE-PAY-NET 18 10 P 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMFILE SFILE SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
JOB INPUT SFILE NAME MYPROG2
PRINT REPORT2
*
REPORT REPORT2 NOADJUST
SEQUENCE SFILE-STATE SFILE-PAY-NET
LINE 01 SFILE-STATE SFILE-ZIP +
SFILE-TALLY SFILE-PAY-NET
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
SFILE-STATE SFILE-ZIP SFILE-TALLY SFILE-PAY-NET
651
CA Easytrieve® Report Generator 11.6
IL 60077 2 641.97
IL 60076 2 802.35
TX 75218 2 777.77
Report Procedures
Although REPORT statements meet most report requirements, some reports depend upon special data manipulation.
Report procedures are routines provided by CA Easytrieve® Report Generator to satisfy this requirement.
Code report procedures at the end of their associated report. The report processor invokes special-name procedures
(such as BEFORE-LINE or AFTER-BREAK) as required.
Contents:
Special-name Report Procedures
Report procedures are invoked at specific points during the report processing activity. You can determine the specific point
based on the name of the procedure. The following example illustrates the use of these procedures:
• REPORT-INPUT -- Final screening of report input data. Report data can be selected and modified. This procedure is
invoked after the PRINT statement is executed or as records are read back from the work file (if used).
• BEFORE-LINE -- Detail line has not been created or printed. It is typically used to modify the contents of fields or
annotate the body of the report before line printing.
• AFTER-LINE -- Detail line has been printed. It is typically used to annotate the body of the report after each line is
printed.
• BEFORE-BREAK -- Modification of totals before total line printing. It is typically used to calculate averages on control
reports.
• AFTER-BREAK -- Total line has been printed. It is typically used to produce special annotation following total lines on
control reports.
• ENDPAGE -- At end-of-page body based on page size. This procedure can be used to produce footers on each page
of the report.
• TERMINATION -- At end-of-report. This procedure produces end-of-report information such as hash or other control
totals.
(REPORT-INPUT - caused by the first PRINT statement)
5/18/09 PROCEDURE USAGE PAGE 1
STATE ZIP PAY-NET
(BEFORE-LINE)
detail IL 60076 678.90
(AFTER-LINE)
(REPORT-INPUT - caused by the second PRINT statement)
(BEFORE-LINE)
detail IL 60076 123.45
(AFTER-LINE)
(REPORT-INPUT - caused by the third PRINT statement)
(BEFORE-BREAK)
652
CA Easytrieve® Report Generator 11.6
total IL 60076 802.35
(AFTER-BREAK
(BEFORE-LINE)
detail IL 60077 543.21
(AFTER-LINE)
(REPORT-INPUT - caused by the fourth PRINT statement)
(BEFORE-LINE)
detail IL 60077 98.76
(AFTER-LINE)
(REPORT-INPUT - caused by the fifth PRINT statement)
(BEFORE-BREAK)
total IL 60077 641.97
(AFTER-BREAK)
(BEFORE-BREAK)
total IL 1444.32
(AFTER-BREAK)
...
...
(ENDPAGE)
Coding Techniques
Coding report procedures is the same as coding procedures within JOB activities, with the following exceptions:
You cannot use the following input/output generating statements:
• DELETE
• FETCH
• GET
• INSERT
• POINT
• PRINT
• PUT
• READ
• SELECT (SQL)
• SQL
• UPDATE
• WRITE
You cannot use the STOP, TRANSFER, or GOTO JOB statements.
You cannot PERFORM other procedures from within report procedures.
Use the DISPLAY statement to perform special report annotations. Using DISPLAY requires the following extra
considerations:
653
CA Easytrieve® Report Generator 11.6
• You cannot code the DISPLAY statement's display-file-name parameter. DISPLAY is only to the associated report.
• You cannot code the HEX parameter of DISPLAY.
• DISPLAY lines are counted and included in the end-of-page determination. DISPLAY statements cause page breaks
only when the line count exceeds the display-page-size REPORT parameter or DISPLAY TITLE or NOTITLE is used.
• With display-page-size specified, using DISPLAY in a BEFORE-LINE procedure could result in a page overflow by one
line.
Field Reference
In report procedures, you can reference any field contained in an active file or in working storage. When control or total
fields are referenced, CA Easytrieve® Report Generator automatically adjusts so that SUMFILE data is used. This assures
access to the field actually used in the report.
Static Working Storage
Fields contained in S storage exhibit unique properties during report processing. S fields are stored in a static working
storage area and are not copied onto report work files. All references to S fields occur at the time the report is formatted
and printed. The format and print operation can occur at one of the following times:
• Immediately at execution of the PRINT statement
• After the processing of work files
Use S storage fields for the following purposes:
• Temporary work fields for report procedures
• Line annotations controlled from report procedures
• Grand total values from which you can calculate percentages
Example: Use of S Fields and W Fields in a Report
The following example illustrates the use of S fields versus W fields in a spooled report:
Statements:
*******************************************************
**** NOTE: ***
**** W FIELDS CONTAIN THEIR VALUE AT TIME OF ***
**** PRINT STATEMENT. ***
**** S FIELDS CONTAIN THE LAST VALUE PLACED ***
**** IN THE FIELD . ***
*******************************************************
FILE FILEA
INPUT-FIELD 1 5 A
SFLD-RECORD-COUNT S 2 N
WFLD-RECORD-COUNT W 2 N
JOB INPUT FILEA
SFLD-RECORD-COUNT = RECORD-COUNT
WFLD-RECORD-COUNT = RECORD-COUNT
PRINT RPT
REPORT RPT NOADJUST
SEQUENCE INPUT-FIELD
LINE INPUT-FIELD SFLD-RECORD-COUNT WFLD-RECORD-COUNT
Data:
654
CA Easytrieve® Report Generator 11.6
TESTA
TESTB
TESTC
Results:
INPUT-FIELD SFLD-RECORD-COUNT WFLD-RECORD-COUNT
TESTA 03 01
TESTB 03 02
TESTC 03 03
Based on the SEQUENCE statement, the report information is copied to the report work file when the PRINT statement
is executed. The format and print operation is performed when the JOB activity completes. All references to S fields
occur when the actual print and format takes place. Thus, the value of SFLD-RECORD-COUNT on the report is always 3.
WFLD-RECORD-COUNT is taken from the report work record and maintains the value that it had at the execution of the
PRINT statement.
The same program with the SEQUENCE statement removed produces different results as illustrated below in the non-
spooled report:
INPUT-FIELD SFLD-RECORD-COUNT WFLD-RECORD-COUNT
TESTA 01 01
TESTB 02 02
TESTC 03 03
In this example, no report work file is needed. The format and print operation occur upon execution of the PRINT
statement and the value of SFLD-RECORD-COUNT is captured with each execution of the PRINT statement.
In non-spooled reports, little difference exists between S fields and W fields. The difference lies in how and when spooled
reports reference the fields. It is important to understand when to use S fields and when to use W fields. Though the report
you may be writing is a non-spooled report today, a future change to your program might cause the report to become
spooled. For example, if you add another report before this report or you add a SEQUENCE statement to this report, your
non-spooled report becomes a spooled report. If you do not define your working storage fields properly, your program may
produce incorrect output in the future.
REPORT-INPUT
A REPORT-INPUT procedure selects and modifies report input data. This procedure is performed for each PRINT
statement (report input). In order to cause the data to continue into report processing, you must execute a SELECT
statement for the associated input data. In other words, input that is not selected is bypassed for continued processing.
When the report data has been spooled (because the report was sequenced or the printer file was in use), the REPORT-
INPUT procedure is invoked as each spooled record is read to produce this report. This implies that if the report is
sequenced, the REPORT-INPUT procedure is invoked after the sort program returns the sorted spool record.
Although you can code the logic within the JOB activity itself, it is occasionally desirable to place the logic in a REPORT-
INPUT procedure. The next example illustrates use of the REPORT-INPUT procedure in final report input selection. Only
the first record within each ZIP code is selected.
Statements:
655
CA Easytrieve® Report Generator 11.6
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
HOLD-ZIP S 5 N VALUE 00000
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
REPORT-INPUT. PROC
IF ZIP NE HOLD-ZIP
HOLD-ZIP = ZIP
SELECT
END-IF
END-PROC
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
11/23/09 REPORT FOR THE STATE OF IL PAGE 1
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 678.90
JONES IL 60077 543.21
IL 1222.11
11/23/09 REPORT FOR THE STATE OF TX PAGE 2
LAST-NAME STATE ZIP PAY-NET
SMITH TX 75218 666.66
TX 666.66
1888.77
656
CA Easytrieve® Report Generator 11.6
BEFORE-LINE and AFTER-LINE
A BEFORE-LINE procedure is invoked immediately before, and an AFTER-LINE procedure immediately after, the printing
of each detail line. BEFORE-LINE procedure is the final chance to modify the data in the detail line before it is printed.
The following example illustrates how an AFTER-LINE procedure can cause information to be printed following a detail
line of a report:
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
DTLCTL EVERY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
AFTER-LINE. PROC
IF PAY-NET GE 500
DISPLAY '* EMPLOYEE ' LAST-NAME ' +
EXCEEDED WEEKLY SALARY GOAL *'
END-IF
END-PROC
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 678.90
* EMPLOYEE BROWN EXCEEDED WEEKLY SALARY GOAL *
BROWN IL 60076 123.45
IL 60076 802.35
JONES IL 60077 543.21
* EMPLOYEE JONES EXCEEDED WEEKLY SALARY GOAL *
657
CA Easytrieve® Report Generator 11.6
JONES IL 60077 98.76
IL 60077 641.97
IL 1444.32
SMITH TX 75218 666.66
* EMPLOYEE SMITH EXCEEDED WEEKLY SALARY GOAL *
SMITH TX 75218 111.11
TX 75218 777.77
TX 777.77
2222.09
BEFORE-BREAK
You can use a BEFORE-BREAK procedure to calculate percentages and average totals. These values must be calculated
immediately before printing.
The grand-total for percentage and average calculations is often maintained in S storage. TALLY is typically used as the
number of items when calculating averages. You can use the value of LEVEL (a system-defined field) to determine which
control break is being processed. You can use the value of BREAK-LEVEL to determine the highest level to break.
Consider the percentage calculation in the following example, paying special attention to when and how PERCENT is
calculated:
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
*
PERCENT W 2 N 2
TOTAL-NET S 8 N 2
*
JOB INPUT FILE1 NAME MYPROG
*
TOTAL-NET = TOTAL-NET + PAY-NET
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 80 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET PERCENT
*
BEFORE-BREAK. PROC
PERCENT = PAY-NET * 100 / TOTAL-NET + .005
END-PROC
Data:
658
CA Easytrieve® Report Generator 11.6
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
LAST-NAME STATE ZIP PAY-NET PERCENT
BROWN IL 60076 802.35 36.11
JONES IL 60077 641.97 28.89
IL 1444.32 65.00
SMITH TX 75218 777.77 35.00
TX 777.77 35.00
2222.09 100.00
AFTER-BREAK
You can use an AFTER-BREAK procedure to produce special annotation on control reports. You can use the value of
LEVEL (a system-defined field) to determine which control break is being processed. You can use the value of BREAK-
LEVEL to determine the highest level to break.
In this example, the total line for the control field STATE receives special annotation:
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
AFTER-BREAK. PROC
IF LEVEL EQ 2
DISPLAY 'TOTALS FOR THE STATE OF ' STATE
END-IF
END-PROC
659
CA Easytrieve® Report Generator 11.6
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 802.35
JONES IL 60077 641.97
IL 1444.32
TOTALS FOR THE STATE OF IL
SMITH TX 75218 777.77
TX 777.77
TOTALS FOR THE STATE OF TX
2222.09
ENDPAGE
You can use an ENDPAGE procedure to produce page footing information. It is invoked whenever end-of-page is
detected. It is typically used to produce page totals or other annotations, as in the following example of page footer
annotation:
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
ENDPAGE. PROC
DISPLAY SKIP 2 '* CONFIDENTIAL - FOR INTERNAL USE ONLY *'
END-PROC
660
CA Easytrieve® Report Generator 11.6
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
...
* CONFIDENTIAL - FOR INTERNAL USE ONLY *
..................................................
...
TERMINATION
A TERMINATION procedure is invoked at the end of the report. You can use this procedure to print report footing
information, including control totals and distribution information. The following is an example of report footing:
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
TOTAL-NET S 8 N 2
JOB INPUT FILE1 NAME MYPROG
TOTAL-NET = TOTAL-NET + PAY-NET
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
TERMINATION. PROC
DISPLAY NOTITLE
DISPLAY SKIP 5 TOTAL-NET 'IS THE Y-T-D COMPANY NET PAY'
DISPLAY SKIP 5 'PLEASE ROUTE THIS REPORT TO CORPORATE OFFICERS'
END-PROC
Data:
661
CA Easytrieve® Report Generator 11.6
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
...
..................................................
2222.09 IS THE Y-T-D COMPANY NET PAY
PLEASE ROUTE THIS REPORT TO CORPORATE OFFICERS
Routing Printer Output
You can route reports to any printer, terminal, or file. The default destination is the CA Easytrieve Report Generator
system output printer, SYSPRINT. The actual SYSPRINT destination on the mainframe is set in the Site Options Table.
For more information, see your system administrator. However, because most operating systems support multiple logical
printers (spool files), you can realize significant performance improvements by routing each output to a different logical
printer, if no SEQUENCE is specified.
On non-mainframe platforms, SYSPRINT is displayed to the user's terminal (the stdout device).
Use the PRINTER parameter of the REPORT statement to route the printed report. The file named by this parameter
corresponds to a library-defined file. The FILE statement that is used to define the file must have the PRINTER parameter
specified. Unless otherwise designated, the record length of these files defaults based on a site option or the LINESIZE of
the REPORT statement.
You can direct a PRINTER file to one of the following destinations:
• The originating terminal
• Another terminal (valid only in CICS)
• The spooling subsystem of your operating system
• An external data set
The destination is determined on the FILE statement for the PRINTER file.
When output is sent back to the originating terminal on the mainframe, the Report Display Facility is automatically
invoked. For more information, see Report Display Facility.
The following example shows a program that takes advantage of print routing to multiple logical files:
FILE PRINTR1 PRINTER F(121)
FILE PRINTR2 PRINTER F(121)
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
IF ZIP EQ 60076, 60077
662
CA Easytrieve® Report Generator 11.6
PRINT REPORT1
ELSE
PRINT REPORT2
END-IF
*
REPORT REPORT1 PRINTER PRINTR1 LINESIZE 120 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
REPORT REPORT2 PRINTER PRINTR2 LINESIZE 120 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
Each report in the example is routed to a different logical file.
This CA Easytrieve® Report Generator facility is an efficient way to separate output to different printer form types such as
standard paper, labels, or preprinted forms.
Reporting to the Terminal
Whenever CA Easytrieve Report Generator routes output to the originating terminal on the mainframe, the following
events take place:
1. When CA Easytrieve Report Generator opens a PRINTER file, a Virtual File Manager (VFM) file is substituted for the
terminal. Remember that SYSPRINT is the system-defined PRINTER file.
2. When the file is closed, the Report Display Facility is invoked to enable you to browse the printed output.
3. You can print the report being displayed from the Report Display Facility. The output is printed to the device specified
by your system administrator as the standard print device.
4. In CA Easytrieve Report Generator, runtime errors and any snap dumps produced are also written to a VFM file for
display with the Report Display Facility. When you request these to be printed, they are printed to the device specified
by your system administrator as the standard error print device. When there is no terminal associated with the task,
errors are also written to the same device.
5. The order in which printed output is displayed within the Report Display Facility is determined by the following rules:
– Runtime errors are displayed at the point the error occurs, but after any pending printer output.
– The contents of PRINTER files are displayed when the PRINTER file is closed, except for REPORT output and
DISPLAY statements in JOB activities with non-spooled reports.
– Each PRINTER file is closed during the termination of the activity that opened it.
– The system-defined PRINTER file, SYSPRINT, is opened during the initiation of the program. Therefore, it is closed
during termination of the program. All DISPLAYs to SYSPRINT are displayed last. This does not include DISPLAY
statements within report procedures or within JOB activities with non-spooled reports.
– Spooled report output, including any DISPLAYs within report procedures, is always displayed at the termination of
the JOB activity.
– Non-spooled report output, including any DISPLAYs within the report procedures or the JOB activity, is displayed at
the termination of the JOB activity.
– If an activity does not produce non-spooled reports, output from DISPLAYs within the activity is displayed at the end
of the activity that opened the PRINTER file. For displays to SYSPRINT, this is at the end of the program.
– When a JOB activity terminates, the file's contents are displayed in the following order:
663
CA Easytrieve® Report Generator 11.6
• Non-spooled reports are displayed in the order in which they were defined. These reports are displayed at
the time the activity actually terminates. DISPLAY statement output that is not associated with a REPORT is
displayed, along with non-spooled report output to the same printer file.
• Spooled reports are displayed in the order in which they were defined. These reports are displayed at the time
they are despooled.
For more information, see Report Display Facility.
If you instruct CA Easytrieve Report Generator to write output to the terminal and no terminal is associated with the task,
the output is routed directly to the device specified by your system administrator as the standard print device.
Use Extended Reporting
With extended reporting, your reports can contain special formatting information for various print devices and display
browsers such as a web browser, word processor, or RTF viewer. You can also use multiple print fonts in a report to
highlight fields of specific interest.
This article contains the following information:
Syntax
You specify extended reporting by using a special FILE statement, the PRINTER parameter on the REPORT statement,
and, optionally, TITLE, HEADING, and LINE statements to identify special fonts.
You use the EXTENDED parameter on a FILE statement to identify the file that is associated with the printer you want to
use, and to specify the type of the predefined printer:
FILE printer-file EXTENDED {xrpt-printer}
You use the PRINTER parameter on the REPORT statement to again specify the name of the file that you specified on the
FILE statement. The syntax of the relevant portion of the REPORT statement is:
REPORT PRINTER printer-file
The REPORT statement directs the report output to printer-file.
TITLE #n 'title-1'
HEADING field-1 #n 'heading-1'
LINE #n field-1
Note: You can also use the DISPLAY statement to route data to an extended printer by specifying the name of the file you
specified on the FILE statement. The syntax is:
DISPLAY printer-file #n field-1
Example
The following program uses extended reporting to create a report that is formatted with HTML. Note the bold characters
that highlight the code that is used for extended reporting.
FILE PERSNL
REGION 1 1 N
NAME 17 16 A
664
CA Easytrieve® Report Generator 11.6
GROSS 94 4 P 2
FILE PRINTFIL01 EXTENDED HTML
JOB INPUT PERSNL NAME BASIC
REPORT PRINTER PRINTFIL01
TITLE #5 'Employee Listing'
LINE #13 REGION NAME #23 GROSS
The FILE statement identifies the extended reporting file (PRINTFIL01) and specifies that the file is associated with an
HTML printer. The REPORT statement directs report output to PRINTFIL01. The TITLE and LINE statements use font
indexes to identify special fonts. In this case, the title literal prints using font 5, the field REGION prints using font 13, and
the field GROSS prints using font 23. The NAME field prints using the default font.
NOTE
You could change this example to produce an RTF formatted report simply by using the keyword RTF instead of
HTML, and by specifying an appropriate print file.
Release 11 Reporting Environment
On Release 11 platforms, CA Easytrieve Report Generator uses an integrated reporting environment that lets you produce
reports that are formatted for line mode printers only. This provides support for many formats including HyperText Markup
Language (HTML) and Rich Text Format (RTF) as well as printer devices.
See Extended Reporting Concepts and Report Layout Processing for detailed information about Extended Reporting in
Release 11.
Use the CA Easytrieve Report Generator Configuration Manager to define and customize your printer definitions. For
more information, see Configuration Manager.
Extended Reporting Concepts
The Reporting Environment produces reports. Reports can be simple, where the format for each print line on the
report is independent of any other print line on the report. Reports can also be complex, where a set of print lines are
interdependent. This is typical of reports where headings are placed towards the top of each page of the report and the
headings are centered over the print data output in the main body of the report.
This article includes the following information:
To support both types of reports, the Reporting Environment introduces a set of concepts that support the generic
definition of print lines in a report.
This article introduces these concepts and in particular, it will establish the meaning and usage of each of the following
terms used by the Reporting Environment:
• Print Elements
• Print Items
• Print Groups
Sample Report
To introduce the key concepts of reporting with the Reporting Environment, a sample report has been produced that
includes interdependencies between the print lines in the report.
The following sample report illustrates one page.
665
CA Easytrieve® Report Generator 11.6
Note: The numbers on the left side of the diagram are not part of the report, but are included here so that print lines can
be directly referenced.
01 12/03/09 Proposed Salary Schedule for Region 4 Employees Page 1
02 Detail by Branch -- Descending Gross Pay
03
04 Social Current Pay Raise New Pay
05 Security Empl
06 Branch Number Number Employee Name Gross/Net % Gross/Net
07
08 01 216-44-7756 05525 TALUS RUTH 460.80 9.00 502.27
09 9331 CAROLINE AVENU 279.56 304.72
10 SEATTLE WA 98003
11
12 558-44-7609 10961 RYAN PAMELA 399.20 7.00 427.14
13 1717 R N W # 301 219.70 235.07
14 SEATTLE WA 98009
15
16 577-58-0363 05482 WARD MARINA 183.75 7.00 196.61
17 1725 H ST NE APT 2 141.47 151.37
18 SEATTLE WA 98015
19
20 01 1,043.75 7.67 1,126.02
21 640.73 691.16
22
23
24 02 484-30-8293 06239 JOHNSON LISA 712.80 7.00 762.70
25 806 CONNECTICUT AVE 451.92 483.55
26 SAN DIEGO CA 92045
27
28 104-20-0956 09764 HAFER ARTHUR 121.95 9.00 132.93
29 806 CONNECTICUT AVE 96.64 105.33
30 SAN DIEGO CA 92041
31
32 02 834.75 8.00 895.63
33 548.56 588.88
34
35
36 03 060-26-8978 10949 JONES ALFRED 804.80 9.00 877.23
37 2070 BELMONT ROAD N 560.63 611.08
38 LOS ANGELES CA 90052
39
40 537-03-4039 11211 WALTERS KAREN 424.00 7.00 453.68
41 1022 S KENSINGTON P 282.45 302.22
42 LOS ANGELES CA 90030
666
CA Easytrieve® Report Generator 11.6
43
44 03 1,228.80 8.00 1,330.91
45 843.08 913.30
Types of Print Lines
The sample report includes four types of print lines:
• Title Print Lines
Title Print Lines are the print lines that appear at the top of each page of the sample report.
Print lines 01 and 02 are title print lines in previous diagram.
• Heading Print Lines
Heading Print Lines are the print lines that also appear at the top of each page of the sample report, immediately after
the title print lines.
Print lines 04, 05 and 06 are heading print lines in the previous diagram.
• Detail Print Lines
Detail Print Lines are the print lines that repeat down the page, in the main body of the report. Detail print lines contain
detail data that is to appear on the sample report.
Print lines 08, 09 and 10 form one instance of detail print lines. Print lines 12, 13 and 14 form another instance. In total,
there are seven instances of detail print lines in the previous diagram.
• Summary Print Lines
Summary Print Lines are print lines that contain summary or total information for a set of one or more detail print
lines. Summary print lines are output by a calling application when a break condition occurs. A break condition usually
occurs when one or more values on the detail print lines change from one instance of the detail print lines to the next
instance. The sample report contains summary print lines for each change in the value in the Branch column of the
detail print lines.
Print lines 20, 21 and 22 form one instance of the summary print lines. Print lines 32, 33 and 34 form another instance.
In total, there are three instances of the summary print lines in the previous diagram.
NOTE
Print line types are used in this section to describe the sample report and introduce the concepts of reporting.
The names assigned to the types of print lines in the sample report are for the purposes of describing the
sample report and are not intended to place restrictions on the types of print lines that a calling application can
define in a report.
Print Elements
Print Elements are the individual fields or items that appear on a print line.
The following diagram redisplays the title print lines from the sample report.
667
CA Easytrieve® Report Generator 11.6
Figure 54: Title Print Lines from the Sample Report
Print line 01 contains four print elements as marked by the arrowed lines:
• #1 Date, left justified on the print line
• #2 Title line 1 text, centered on the print line
• #3 Page text
• #4 A page number, right justified on the print line.
Print line 02 contains only one print element as marked by the arrowed lines:
• #5 Title line 2 text, centered on the print line.
Print Element Types
The Reporting Environment supports two types of print elements:
• Static Print Elements
Static Print Elements are print elements that do not vary from one instance of a print line to the next instance.
Constants that appear in title and heading print lines are generally static print elements.
– Print elements #2 and #3 on print line 01 are examples of static print elements in the previous diagram.
– Print element #5, the only print element on print line 02, is also a static print element in the previous diagram.
• Variable Print Elements
Variable Print Elements are print elements that do vary from one instance of a print line to the next instance. The print
elements that appear on detail print lines are generally all variable print elements because their value varies from one
instance of the detail print lines to the next instance.
– Print elements #1 and #4 on print line 01 are examples of variable print elements in the previous diagram of the
sample report.
– There are no variable print elements on print line 02 in the previous diagram of the sample report.
Attributes
When a print element is defined to the Reporting Environment, the Reporting Environment requires certain information
about that print element. The information required by the Reporting Environment for a print element includes:
• Length
Length defines the number of bytes in the print element. The Reporting Environment uses this value when positioning
the print element in a print item and when placing the print element on a print line.
• Font
Font provides the font identification of a reporting font that is used to print the characters in the print element.
668
CA Easytrieve® Report Generator 11.6
The font assigned to a print element must be defined for the printer that is assigned to print the print element, and the
data format supported by that font must match the data format of the print element.
When a print element is defined without a font, the Reporting Environment will select a printer's default font for the data
format of the print element.
• WfbOffset
WfbOffset is required for a variable print element.
WfbOffset defines the offset into a write fields buffer that will contain the print data to be output for the print element.
The reporting write service requires a WfbOffset in order to locate the print data for the print element when writing the
print element's print line.
• Value
Value is required for a static print element.
Value defines the print data that is to be printed for the print element.
Print Items
A Print Item defines a set of one or more print elements where:
• Each print element occurs on a different print line
• The position of each print element on a print line is regulated so that all the print elements are positioned under each
other on the report.
The following diagram re-displays the heading print lines and first instance of the detail print lines from the sample report.
Figure 55: Heading Print Lines and First Instance of Detail Print Lines
The illustrated set of print lines include seven print items:
• Print Item #1 -- occupies six characters across the report, as set by the number of characters in the widest print
element in the print item, the print element on the third heading print line (line number 06). The value of the branch that
is output by the print element on the detail print line 08 is then centered in the six characters assigned to this print item.
• Print Item #2 -- occupies eleven characters across the report, as set by the number of characters in the widest print
element in the print item, the print element that occurs on the detail print line (line number 08). The three print elements
that occur on the heading print lines are then centered in the eleven characters assigned to this print item.
• Print Item #3 -- occupies six characters across the report, as set by the number of characters in the widest print
element in the print item, the print element on the third heading print line (line number 06). The print element on the
669
CA Easytrieve® Report Generator 11.6
second heading print line 05 and the print element on the detail print line 08 are then centered in the six characters
assigned to this print item.
• Print Item #4 -- occupies twenty characters across a report, as set by the number of characters in the widest print
element in the print item, the print elements on the second and third detail print lines (line numbers 09 and 10). The
print element on the third heading print line 06 and the print element on the first detail print line 08 are then centered in
the twenty characters assigned to this print item.
• Print Item #5 -- occupies eleven characters across a report, as set by the number of characters in the widest print
element in the print item, the print element on the first heading print line (line number 04). The print element on the
third heading print line 06 and the print elements on the detail print lines 08 and 09 are then centered in the eleven
characters assigned to this print item.
• Print Item #6 -- occupies seven characters across a report, as set by the number of characters in the widest print
element in the print item, the print element on the first detail print line (line number 08). The print elements on the first
and third heading print lines 04 and 06 are then centered in the seven characters assigned to this print item.
• Print Item #7 -- occupies nine characters across a report, as set by the number of characters in the widest print
element in the print item, the print element on the third heading print line (line number 06). The print element on the
first heading print line 04 and the print elements on the first and second detail print lines 08 and 09 are then centered in
the nine characters assigned to this print item.
Print Groups
A Print Group defines a set of one or more print lines where:
• Print items can be positioned relative to each other across the report
• Print elements can be assigned to a print line in the print group
• Print elements can be assigned to print items in the print group.
The sample report includes three print groups. A detailed description of each print group is discussed next.
Print Group #1
The following diagram redisplays the first print line of the title print lines.
Figure 56: Print Item
The definition of Print Group #1 to the Reporting Environment included the following characteristics:
670
CA Easytrieve® Report Generator 11.6
• Print line 01 was defined in print group #1.
• Print item #1 was defined in print group #1.
• Print element #2 was defined in print item #1, to appear on print line 01.
• Print element #1 was positioned at the beginning of print line 01.
• Print elements #3 and #4 were positioned at the end of print line 01.
The processing performed by the Reporting Environment for print group #1 included the following actions:
• Print item #1 was centered across the print line defined in print group #1.
• Print element #2 was centered in the portion of the report allocated to print item #1 and thereby assigned a print
position on print line 01.
• Print elements #1, #3 and #4, which were not assigned to a print item, were positioned on print line 01 at their
assigned locations.
Print Group #2
The following diagram redisplays the second print line of the title print lines.
Figure 57: Second Title Print Line
The definition of Print Group #2 to the Reporting Environment included the following characteristics:
• Print line 02 was defined in print group #2.
• Print item #1 was defined in print group #2.
• Print element #1 was defined in print item #1, to appear on print line 02.
The processing performed by the Reporting Environment for print group #2 included the following actions:
• Print item #1 was centered across the print line defined in print group #2.
• Print element #1 was centered in print item #1 and thereby assigned a print position on print line 02.
Print Group #3
The following diagram redisplays the heading, detail and summary print lines that form Print Group #3.
671
CA Easytrieve® Report Generator 11.6
The definition of print group #3 to the Reporting Environment included the following characteristics:
• Print lines 04, 05, 06 were defined in print group #3.
• Print lines 08, 09, 10 were defined in print group #3.
• Print lines 20, 21, 22 were defined in print group #3.
• Print items #1 through #7 were defined in print group #3.
• The following print elements were defined in print item #1:
– Print element #1, to appear on print line 06.
– Print element #2, to appear on print line 08.
– Print element #3, to appear on print line 20.
• The following print elements were defined in print item #2:
– Print element #4, to appear on print line 04.
– Print element #5, to appear on print line 05.
– Print element #6, to appear on print line 06.
– Print element #7, to appear on print line 08.
• The following Print elements were defined in print item #3:
– Print element #8, to appear on print line 05.
– Print element #9, to appear on print line 06.
– Print element #10, to appear on print line 08.
• The following print elements were defined in print item #4:
672
CA Easytrieve® Report Generator 11.6
– Print element #11, to appear on print line 06.
– Print element #12, to appear on print line 08.
– Print element #13, to appear on print line 09.
– Print element #14, to appear on Print Line 10.
• The following print elements were defined in print item #5:
– Print element #15, to appear on print line 04.
– Print element #16, to appear on print line 06.
– Print element #17, to appear on print line 08.
– Print element #18, to appear on print line 09.
– Print element #19, to appear on print line 20.
– Print element #20, to appear on Print Line 21.
• The following print elements were defined in print item #6:
– Print element #21, to appear on print line 04.
– Print element #22, to appear on print line 06.
– Print element #23, to appear on print line 08.
– Print element #24, to appear on print line 20.
• The following print elements were defined in print item #7:
– Print element #25, to appear on print line 04.
– Print element #26, to appear on print line 06.
– Print element #27, to appear on print line 08.
– Print element #28, to appear on print line 09.
– Print element #29, to appear on print line 20.
– Print element #30, to appear on print line 21.
The processing performed by the Reporting Environment for print group #3 included the following actions:
• Insert one space character between each print item across the print group.
• The width of each print item was calculated.
• The width of the print group was calculated by totaling the width of each print item in the print group. The spacing
between the print items in the print group is also include in the width of the print group.
• The width of the print group is then centered in the print line defined for the print group. The width of each print line in a
print group is defined by the line size value assigned to the print group.
• Each print item in the print group is assigned a print position on the report.
• Print element #1, #2 and #3 are centered in print item #1 and thereby assigned a print position on their respective print
lines.
• Print element #4, #5, #6 and #7 are centered in print item #2 and thereby assigned a print position on their respective
print lines.
• Print element #8, #9 and #10 are centered in print item #3 and thereby assigned a print position on their respective
print lines.
• Print element #11, #12, #13 and #14 are centered in print item #4 and thereby assigned a print position on their
respective print lines.
• Print element #15, #16, #17, #18, #19 and #20 are centered print item #5 and thereby assigned a print position on their
respective print lines.
• Print element #21, #22, #23 and #24 are centered in print item #6 and thereby assigned a print position on their
respective print lines.
• Print element #25, #26, #27, #28, #29 and #30 are centered in print item #7 and thereby assigned a print position on
their respective print lines.
673
CA Easytrieve® Report Generator 11.6
Attributes
When a print group is defined to the Reporting Environment, the Reporting Environment requires certain information about
that print group. The information required by the Reporting Environment for a print group includes:
• Spacing
Spacing defines the number of spaces that are to be inserted between each print item defined in the print group.
• Justification
Justification defines how the Reporting Environment is to distribute the print items in a print group across the print lines
defined in the print group.
• Indentation
Indentation defines the size of left and/or right margins that are to be allocated on the print lines of the print group.
• Line Size
Line Size establishes the number of character positions in the print lines generated for a print group.
Operations
The Reporting Environment supports a set of operations that manipulate the print items in a print group. The operations
include:
• Spacing -- inserts spaces between print items in a print group
• Justification -- controls how print items in a print group are distributed across the page of a report
• Indentation -- adjusts the size of margins on the left and right sides of a report.
A detailed description of each operation follows.
Spacing
Spacing defines the number of space characters that the Reporting Environment is to insert between print items in a print
group.
The spacing operation defines a minimum separation between print items that is applied to the print items in a print group
before any justification operation is performed.
The following diagram illustrates an unjustified set of four print items with a spacing value of zero.
The following diagram illustrates the same unjustified set of four print items with a spacing value of three.
674
CA Easytrieve® Report Generator 11.6
Justification
Justification controls how the Reporting Environment distributes the print items in a print group across the print lines of a
print group.
The justification operation supports five settings:
• Left Justification
Left Justification starts the left-most print item in a print group at the first print position in the print group and distributes
the other print items to the right, inserting the appropriate spacing between each print item.
The following diagram illustrates left justification with a spacing value of three:
• Right Justification
Right Justification ends the right-most print item in a print group at the last print position in the print group and
distributes the other print items to the left, inserting the appropriate spacing between each print item.
The following diagram illustrates right justification with a spacing value of three:
675
CA Easytrieve® Report Generator 11.6
• Centering
Centering positions a set of print items in a print group in the middle of the print group's print lines. The Reporting
Environment achieves this justification by:
– Calculating the width of each print item in the print group, as set by the number of characters in the widest print
element in the print item.
– Calculating the width of the print group by totaling the width of each print item in the print group. The spacing
between the print items in the print group is also included in the width of the print group.
– Centering the width of the print group in the width of the print lines in the print group, thus giving an evenly
distributed left and right margin. The width of the print lines in a panel group is defined by the line size value
assigned to the panel group.
– The left-most print item in a print group is assigned a start print position after the left margin and the additional print
items are distributed to the right, inserting the appropriate spacing between each print item.
The following diagram illustrates centering with a spacing value of three:
• Spreading
Spreading positions the print items in a print group such that the print items are evenly distributed across the print lines
of a print group. The Reporting Environment achieves this justification by:
676
CA Easytrieve® Report Generator 11.6
– Calculating the width of each print item in the print group, as set by the number of characters in the widest print
element in the print item.
– Calculating the width of the print group by totaling the width of each print item in the print group. The spacing
between the print items in the print group is also included in the width of the print group.
– Determining the number of free spaces on the print group's print lines by subtracting the width of the print group
from the width of print lines in the print group. The width of print lines in a print group is defined by the line size
value assigned to the print group.
– The number of free spaces on the print group's print lines is then evenly distributed between the print items,
including the left and right margins. This value defines the spread spacing that is added to the original spacing,
giving the total spacing between the print items.
– The left-most print item in a print group is assigned a start print position after allocating spread spacing for the left
margin. The additional print items are then distributed to the right, inserting the total spacing (original spacing plus
spread spacing) between each print item.
The following diagram illustrates spreading with a spacing value of three:
• Indentation
Indentation controls the creation of a right or left margin (or both) in which the reporting justification operations are
performed.
The definition of a left or right margin (or both) using Indentation effectively reduces the line size of a print group's print
lines by requiring that the Reporting Environment preallocate the spaces for the margins.
The following diagram illustrates a left indentation of five with left justification and spacing value of three:
The following diagram illustrates a left indentation of eight with a justification of centering and spacing value of three:
677
CA Easytrieve® Report Generator 11.6
Report Layout Processing
You request printed output from a CA Easytrieve® Report Generator program by using either the TITLE, LINE or DISPLAY
statements. CA Easytrieve® Report Generator then interprets the appropriate statement(s) and based on a set of user
modifiable parameters (SPACE, SKIP, LINESIZE, PAGESIZE, and so on), automatically formats the print line(s). From this
format, CA Easytrieve® Report Generator builds the print records that produce the correct lines.
The Reporting Environment does not change this process. CA Easytrieve® Report Generator still automatically formats
the print line(s) and builds the print records. The impact of the Reporting Environment concerns the processing that CA
Easytrieve® Report Generator must perform in order to format a report. Because CA Easytrieve® Report Generator now
supports multiple fonts and extended reporting printers, CA Easytrieve® Report Generator can no longer rely on the same
formatting algorithm that supported line printers.
The CA Easytrieve® Report Generator process to format a print line still supports all the standard line printer report
generation options, but a number of considerations influence the format of the resultant print line. This section discusses
these considerations. Reading this section ensures that you can analyze and explain the results that you obtain by using
an extended reporting printer, when they differ from the results that you obtain when using a standard line printer.
This section discusses the following subjects:
LINE Element Processing
The standard CA Easytrieve® Report Generator reporting system positions items on a print line using three rules:
1. LINE 01 items and their associated headings are centered in an area whose length is controlled by the longer of the
following:
– The line item entry. This item is expanded by the value of SUMSPACE if the item is a field that is summarized.
– The longest heading entry.
The resulting value is called the item length or item window.
2. The first line item other than on LINE 01 (that is LINE 02 through LINE 99) is positioned under the first item of LINE 01.
The data is left-justified under the LINE 01 data regardless of the heading size.
3. Blank characters (spaces) separate all line items according to the value of the SPACE parameter of the REPORT
statement. In addition, the number of spaces can be altered by the +/- spacing options plus the effect of the SPREAD
operation.
The Reporting Environment changes this process in one way. CA Easytrieve® Report Generator must calculate the length
of each of the elements associated with LINE 01 line items (namely the heading, detail and summary line elements) as:
(number of chars in element) X (width of font assigned to element)
678
CA Easytrieve® Report Generator 11.6
where the width of the largest element defines the size of the item's window.
This process can result in some change to the format of a CA Easytrieve® Report Generator report when the print item
has heading and detail elements that use fonts of different width. This situation impacts the process CA Easytrieve®
Report Generator uses to determine the appropriate window for the print item. When you are using fonts of different
widths for the elements of any item coded on the LINE 01 statement, CA Easytrieve® Report Generator must determine a
window for the item. This window includes any adjustments necessary to ensure that all the elements of the item fit within
the window after each element has been positioned on its applicable print record. This means that the window may be
larger than CA Easytrieve® Report Generator originally determined.
The five diagrams that follow illustrate the effect of mixing fonts of different sizes in a report.
The following diagram illustrates CA Easytrieve® Report Generator syntax that uses multiple fonts.
CA Easytrieve Syntax:
DEFINE TEST-FIELD-1 1 8 A +
HEADING (#1 'THE FIRST LINE' 'THE SECOND LINE')
DEFINE TEST-FIELD-2 9 10 A +
HEADING (#2 'SECOND FIELD HEADING')
.
.
JOB INPUT
.
.
LINE 1 #1 TEST-FIELD-1 TEST-FIELD-2
The following diagram describes the fonts that the previous example references.
FONTS W-UNIT SIZES
default 10
#1 8
#2 7.2
To create a print line, CA Easytrieve® Report Generator must analyze the heading lines and the detail lines (the contents
of TEST-FIELD-1 and TEST-FIELD-2) taking into account the size of the fonts. CA Easytrieve® Report Generator then
calculates a window that is large enough to encompass each of the elements of the print item that is to be output to the
print line.
The following diagram illustrates the windows that CA Easytrieve® Report Generator would create using the syntax in the
first diagram in this section.
679
CA Easytrieve® Report Generator 11.6
Figure 58: Windows Created by CA Easytrieve
After calculating the windows, CA Easytrieve® Report Generator determines the format of each of the print lines. To do
this, CA Easytrieve® Report Generator must center each print element within its own window and then determine the
correct amount of space between those elements that occur on the same print line. This step is illustrated by the following
diagram.
680
CA Easytrieve® Report Generator 11.6
Figure 59: Space Between Elements of data
As is shown in the previous diagram, there are four gaps that must be filled with spaces by CA Easytrieve® Report
Generator. CA Easytrieve® Report Generator attempts to fill each gap using a combination of the fonts assigned to
print items on the original CA Easytrieve® Report Generator statement. In this example, not only will CA Easytrieve®
Report Generator use the default font (size of 10 points), but also font #1 (8 points in width) and font #2 (7.2 points). CA
Easytrieve® Report Generator will analyze each gap individually and attempt to determine the spacing factors that will
position an element as close as possible to its assigned print position. For the current example, the following diagram
illustrates the results produced by CA Easytrieve® Report Generator.
681
CA Easytrieve® Report Generator 11.6
Figure 60: Element Spacing Factors Result
As illustrated above, the first gap on Heading Line 1 was filled by 2 spaces using the 7.2 point font. This is as close to
print position 14 as was possible with the available fonts. For the gap on Heading Line 2, the insertion of 3 spaces using
the 10 point font filled the gap exactly. On the Detail Line, the first gap was filled by 6 spaces using the 7.2 point font. The
second gap to be filled on the Detail Line was originally 95 points wide but because the first gap on this same line actually
increased, the second gap was reduced by 0.2 points (the increase in the first gap). The resultant gap of 94.8 was then
filled exactly by CA Easytrieve® Report Generator using a combination of 9 spaces of 7.2 points in width and 3 spaces of
10 points in width. Consequently, CA Easytrieve® Report Generator was able to position the second element on the Detail
Line exactly at its assigned print position.
As was illustrated by Heading Line 1 in the previous diagram, when CA Easytrieve® Report Generator cannot position
an element at its assigned print position, CA Easytrieve® Report Generator will position the element as close as possible
to its assigned position. If this movement of the element results in the element moving outside the item window for the
element, the window will be expanded and all the elements to be positioned in that window will be re-centered. The
spacing between elements on the same print line will then be re-calculated. When CA Easytrieve® Report Generator
expands the size of a window, CA Easytrieve® Report Generator ensures that a window does not overlap another window.
This technique ensures that no two elements on the same print line will ever overlap.
682
CA Easytrieve® Report Generator 11.6
Print Item Positioning Considerations
The various characteristics of the numerous printers that the CA Easytrieve® Report Generator Extended Reporting
Facility supports has given rise to a number of limitations with respect to item positioning on a print line that the Extended
Reporting Facility cannot overcome. These limitations are primarily caused by the techniques required by printers to build
print records. This section describes each of these limitations in turn.
The Overprint Gap
This output consideration was introduced by the discussion regarding the Print Overprint technique for combining multiple
print records on the one print line. The Overprint Gap results from the printer imaging each print record independent
of other print records that may appear on the same line. Once the printer images the records, the printer combines the
records to form the print line that is output to the page. As a result of imaging each line separately (as opposed to the
Merge Overprint technique which does not suffer from this limitation), the ability to position print items of different fonts
(thus different print records) adjacent to each other is restricted. The diagram that follows illustrates the reasons.
Assume that three characters of different fonts had to be printed adjacent to each other. The first character was to be
output using a 9 point font, the second output with a 12 point font, and the third output with a 7 point font. As a result three
print records would be built; each with their own font indicator after the Carriage Control.
The following diagram illustrates these three records. Notice that the second print record cannot have the 12 point
character in the first byte of the print record or it would print over the character output by the first print record. Therefore,
CA Easytrieve® Report Generator must insert one space byte into the 12 point print record before the actual character.
This space prints at 12 points, thereby positioning the 12 point character to the right of the 9 point character. In doing this,
the position of the 12 point character is not adjacent to the 9 point character. The 12 point space was 3 points too large
but nothing can be done to overcome this -- it is the Overprint Gap.
Figure 61: Overprint Gap
683
CA Easytrieve® Report Generator 11.6
The following blocks illustrate the format of the data immediately prior to being combined onto the single print line. Printers
that support the Print Overprint technique prepare or image each print record independently. Although the following three
blocks are destined for the same print line, they have been separated for the purposes of this illustration.
Figure 62: Data Format before Combination to Single Print Line
The same process applies to the third character that is to print from a 7 point print record. To ensure that this character
does not print over the 9 or the 12 point character, CA Easytrieve® Report Generator inserts sufficient spaces before
the 7 point character in the third print record. The correct amount of space would be 24 points of spaces as the 7 point
character cannot print over the 12 point character that is positioned 12 points from the start of the line (12 + 12 = 24). For
the 7 point print line though, 24 points of spacing is not possible using a 7 point space. The closest CA Easytrieve® Report
Generator can come to this figure is 28 (four 7 point spaces). As a result, there is a 4 point gap between the second and
third characters. Again another Overprint Gap.
CA Easytrieve® Report Generator automatically calculates the correct positioning of print items such that they do not
overlap, thereby incorporating this limitation into the positioning of items on a report.
Item Placement Restrictions
CA Easytrieve® Report Generator reporting provides a set of features that enable you to specify the exact position that
you want an item to appear on a print line. The use of the COL keywords on the DISPLAY, TITLE, and LINE statements,
and the POS keyword on the LINE and DISPLAY statements both provide this ability.
With the Reporting Environment, getting the item precisely at the requested COL or POS position depends upon the use
of different sized fonts within the report. If you are using only one font, no problems will arise. If you are using multiple
fonts, it may not be possible to position the print item exactly at the requested location.
All extended reporting printers except "All Points Addressable" printers suffer this limitation. The best way to explain this
restriction is by an example.
The following diagram illustrates the use of a printer that supports the Print Overprint technique of font combination on
a line. Assume that CA Easytrieve® Report Generator is to position two 7 point characters on the print line starting in
COLumn 3. If the default W-unit for the assigned extended reporting printer is 12 point, the COL value of 3 would be
interpreted as 2 X 12 points, thus 24 points from the start of the print line. The characters though must print from a print
record producing 7 point characters. As a result, the closest CA Easytrieve® Report Generator can position the two
684
CA Easytrieve® Report Generator 11.6
characters to their assigned location is 28 points (4 X 7 point spaces). CA Easytrieve® Report Generator cannot solve the
inability to position the characters on the 24th point.
CA Easytrieve® Report Generator allows for the effects of this limitation when it occurs by positioning the print item as
close as is possible to the assigned location, but always on the right side of the location.
Figure 63: Print Item placed on the Right Side of the Assigned Location
Screen Processing
The product provides all the facilities necessary to display and receive information from an online terminal. As with other
features, the non-procedural nature of the product provides relief from having to deal with many of the complexities of
transaction programming.
NOTE
Screen processing activities are available only in CA Easytrieve/Online.
Basic Structure
You use a SCREEN activity to describe and process a screen display. The screen processing facility is basically
declarative; you only need to define the format and content of the screen and the product creates the necessary
instructions to send and receive the screen. There are two sections in a SCREEN activity:
• The screen declaration statements that define the contents of the screen
• The optional screen procedures that let you code procedural logic to perform file I/O or complex editing of fields
displayed on the screen
The following exhibit illustrates the basic structure of screen processing in a program. You can define one or more screens
for each program.
685
CA Easytrieve® Report Generator 11.6
<easy> Program
FILE
(library section)
SCREEN NAME SCREEN1
Screen Declaration
Screen Procedures
SCREEN NAME SCREEN2
Screen Declaration
Screen Procedures
NOTE
You can automate the screen declaration process by using the CA Easytrieve/Online Screen Painter.
Screen Format
This article describes the online screen format.
The size of the screen defaults to the values specified in your site options. These values can be overridden by the
LINESIZE and ROWCOUNT parameters of the SCREEN statement.
LINESIZE
Title Area
R
O
W
Work Area C
O
U
N
T
Message Area
Function Key Area
• Title Area
The title area is an optional area that consists of screen rows designated as titles by TITLE statements in the screen
declaration. Titles normally identify the screen to the user and are automatically centered at the top of the screen. The
title area cannot be updated by the terminal user.
• Work Area
The work area contains the items to be displayed to or received from the terminal user. Use ROW statements in the
screen declaration to specify the items. Use the REPEAT and END-REPEAT statements to specify repeating groups of
rows.
• Message Area
The message area is used to display system and programmer-issued messages to the terminal user. The default
location of the message area is the line just above the function key display area at the bottom of the screen. You can
issue your own messages by using the MESSAGE or SET statement.
• Function Key Area
686
CA Easytrieve® Report Generator 11.6
The optional function key area is used to tell the terminal user which function keys are active and the action they
perform. This area, if used, is always located on the last lines at the bottom of the screen. You use the KEY statement
in the screen declaration to define the function key area.
• Screen Borders
Specifying the BORDER parameter on a SCREEN statement reduces the size of available screen areas to allow space
for the border characters. A border reduces the total screen area by two rows and four columns. For example, if you
define a screen with a border and LINESIZE(80) ROWCOUNT(24), available rows are from 1 to 22, and available
columns are from 1 to 76. ROW 1, COLUMN 1 always refers to the first usable display position on the screen.
Screen Example
The following example illustrates the type of screen that you can create with the online product:
Employee File Main Menu
Type an option, then press Enter.
Option ===> W
V View employee
E Edit employee
D Delete employee
X Exit
Please type V, E, D, or X
F1=Help F3=Exit F12=Cancel
The screen declaration that is used to create the example screen follows:
SCREEN NAME MAIN-MENU
TITLE 'Employee File Main Menu'
ROW 6 COL 10 'Type an option, then press Enter.'
ROW 8 COL 10 'Option ===>' WS-REPLY VALUE ('V' 'E' 'D' 'X') +
ERROR 'Please type V, E, D, or X'
ROW 10 COL 22 'V View employee'
ROW COL 22 'E Edit employee'
ROW COL 22 'D Delete employee'
ROW COL 22 'X Exit'
KEY F1 NAME 'Help' IMMEDIATE
KEY F3 NAME 'Exit' EXIT
KEY F12 NAME 'Cancel' EXIT IMMEDIATE
KEY ENTER
687
CA Easytrieve® Report Generator 11.6
Use the SCREEN Statement
To define a screen, code a SCREEN statement followed by a series of screen definition statements. You must code the
SCREEN statement first in a screen declaration. The SCREEN statement defines the characteristics of the screen and
activity. For more information about SCREEN statement parameters, see the Language Reference section.
This article contains the following information:
Screen Definition Statements
A set of screen definition statements defines every CA Easytrieve screen. The statements define the screen format and
data content. Screen definition statements must follow the SCREEN statements and precede any procedures in the
SCREEN activity. The following diagram illustrates the order that statements must appear in a SCREEN activity:
SCREEN ...
Screen { DEFAULT
Definition { KEY
Statements { TITLE
{ ROW/REPEAT
{ INITIATION
special-named procedures { BEFORE-SCREEN
{ AFTER-SCREEN
{ TERMINATION
programmer-defined procedures
• DEFAULT
(Optional) overrides system-defined screen attributes and message locations.
• KEY
Defines valid terminal keys for a screen, specifies descriptive text, and assigns functions to terminal keys.
• TITLE
Defines optional screen title items, their attributes, and their position on the title row.
• ROW
Defines the contents of a screen row. Item attributes and positioning are optionally specified.
• REPEAT
Displays arrays on a screen.
For the complete syntax of these statements, see the Language Reference section.
Screen Items
Screen items include the fields and literals that you want to display to or receive from the terminal user. Basic rules
regarding items on a screen include the following:
• Unless directed otherwise, items for the same screen row are placed one space apart. You can optionally add to this
space or locate an item at a specific column number.
• The space preceding each item contains system information describing the screen attributes for the item. The
attributes contain information that controls the display of screen items such as color and brightness. The space
preceding each screen item is used for attributes.
688
CA Easytrieve® Report Generator 11.6
NOTE
The space preceding an item located in the first column of any screen row is actually located in the last
column of the previous screen row. The space preceding an item located in the first column of the first screen
row is located in the last column of the last screen row.
• You can override the automatic placement of items by using the COL parameter. You use COL to specify an explicit
screen column number where the item is placed. The COL parameter specifies the column number where the data that
is contained in the item is placed.
Use an offset (+n) to add to the minimum single space used between items (+1 is the default). The offset applies to
the data to be displayed. To add more space, use an offset greater than +1. There must always be at least one space
between each item on the screen. Items cannot overlap each other.
• You can specify screen attributes for each item on the screen. If you do not specify attributes for each item, default
attributes apply. The following hierarchy is used to determine screen attributes:
– If attributes are not specified for an item (ATTR parameter on the ROW or TITLE statement), the product uses
default attributes that are specified on the DEFAULT statement at the beginning of the SCREEN declaration.
– If a DEFAULT statement is not coded in the SCREEN activity, the product uses attributes set in the site options.
Attributes can be specified as one or more keywords or by using a declared screen attribute. Using declared attributes
lets you define and name a set of attribute keywords. See Declarations for more information. Also see DECLARE
Statement in the Language Reference section. You can also change screen attributes dynamically during program
execution by using the SET statement. See SET Statement for more information.
• You must ensure that fields that are used on a screen are in available storage. This requires that you code
WORKAREA on FILE statements for fields that are used on the screen where you do not execute an input statement
to fill the fields with data prior to displaying the screen.
NOTE
You must know the record length to reserve a WORKAREA. The product does not initialize WORKAREAs.
Results are unpredictable if an uninitialized WORKAREA is displayed.
System-Defined Fields
Special data fields for screens are automatically provided. These fields are stored as part of working storage and are
read-only.
• KEY-PRESSED
KEY-PRESSED is a two-byte binary field that contains a value representing the most recent terminal key that is
pressed by the terminal user.
The product automatically defines symbolic names that correspond to values for the most common keys. Only keys
with symbolic names can be used on a KEY statement.
Terminal Key Symbolic Name Constant Value
Unknown 0
Enter ENTER 1
Clear CLEAR 11
PA1 to PA3 PA1 to PA3 12 to 14
PF1 to PF24 F1 to F2 21 to 44
F1 to F12 F1 to F12 21 to 32
Test Request 220
Op ID card Reader 222
Magnetic Slot Reader 223
Trigger Action 224
689
CA Easytrieve® Report Generator 11.6
Structured Field 230
Clear Partition 231
Read Partition 232
No Aid Generated 255
• TERM-COLUMNS
TERM-COLUMNS is a 2-byte binary field containing the maximum number of columns the screen supports. You can
test TERM-COLUMNS to execute a SCREEN activity designed specifically for the terminal being used.
• TERM-ROWS
TERM-ROWS is a 2-byte binary field containing the maximum number of rows the screen supports. You can test
TERM-ROWS to execute a SCREEN activity designed specifically for the terminal being used.
• TERM-NAME
TERM-NAME is a 16-byte alphanumeric field containing the terminal identification. This field is set only in CICS
environments.
• SYSUSERID
SYSUSERID is a 16-byte alphanumeric field identifying the terminal user. In CICS, SYSUSERID is copied from the
EIB.
Screen Title Area
The title area is the first area on each screen. A screen title is optional but well-designed screens are usually identified
with a title. Specify the screen title by coding TITLE statements in the SCREEN declaration.
This article contains the following information:
Screen Title Rules
Rules for specifying screen titles are as follows:
• Titles are for display purposes only. You cannot receive data from the terminal user in a TITLE. (To receive data, use a
ROW statement in the screen work area.)
• You can specify the screen row number for the title in the TITLE statement. If you do not specify an explicit row
number, the next screen row number is assigned. The next row number is one higher than the previous TITLE or ROW
statement coded. If no TITLE statement is previously coded, the title is assigned to the top of the screen.
• All title row numbers must precede row numbers that are associated with the screen work area.
• You need not code TITLE statements for empty rows between titles. For example, if you specify titles for rows 1 and 3
of the screen, row 2 is also considered part of the title area.
• Title items are automatically centered on the screen, based on the LINESIZE parameter of the SCREEN statement.
• All title items without explicit column numbers participate in centering.
• Multiple items on a title row are automatically separated from each other by one space. This space contains the screen
attributes for the second of the two items. You can optionally add to this space or locate an item at a specific column
number.
• You can override the automatic placement of title items by using the COL parameter. Use COL to specify an explicit
screen column number where the title item is placed. The COL parameter specifies the column number where the data
that is contained in the item is placed.
Use an offset (+n) to add to the minimum single space used between items (+1 is the default). The offset applies to
the title to be displayed. To add more space, use an offset greater than +1. There must always be at least one space
between each item on the screen. Title items cannot overlap each other.
• You can specify screen attributes for each title item on the screen. If you do not specify attributes for each item, default
attributes apply. The following hierarchy is used to determine screen attributes:
690
CA Easytrieve® Report Generator 11.6
– If attributes are not specified for a title item (ATTR parameter on the TITLE statement), default attributes that are
specified on the DEFAULT TITLE statement at the beginning of the SCREEN declaration are used.
– If a DEFAULT TITLE statement is not coded in the SCREEN activity, attributes that are set in the site options are
used.
Because titles are not updatable, the following attributes are flagged as warnings when compiled, and ignored when
used:
– ALARM
– CURSOR
– INVISIBLE
– MUSTENTER
– MUSTFILL
– NUMERIC
– TRIGGER
Screen Title Examples
This section contains title statement examples and the resulting screens.
Default Centering and Attributes
This example illustrates two title rows that are automatically centered on the screen. The titles are displayed with default
screen attributes.
SCREEN NAME SCREEN1
TITLE 1 'Personnel View Utility'
TITLE 2 'Acme, Inc.'
Personnel View Utility
Acme, Inc.
Explicit Locations and Attributes
This example shows titles that contain items that are explicitly located on the title row by using column specification
(COL). The company name in the second title row is displayed bright yellow because the ATTR parameter for the literal is
coded to override the default set of attributes for title items.
SCREEN NAME SCREEN1
TITLE 1 COL 1 'ViewUtil' 'Personnel View Utility' COL 73 SYSDATE
TITLE 2 'Acme, Inc.' ATTR (INTENSE YELLOW) COL 73 SYSTIME
ViewUtil Personnel View Utility 07/08/09
Acme, Inc. 12:32:04
Screen Work Area
The screen work area is built by coding ROW statements in a SCREEN declaration. Each ROW statement describes the
fields and literals to be located on each row of the screen.
This article contains the following information:
691
CA Easytrieve® Report Generator 11.6
Item Location
The following rules apply to the location of items in the screen work area:
• You can specify the screen row number in the ROW statement. If you do not specify a row number, the next screen
row number is assigned. The next row number is one higher than the row number for the previous ROW or TITLE
statement. If no TITLE or ROW statement is previously coded, the row is assigned to the first line at the top of the
screen.
• All title rows must precede rows that are associated with the screen work area. This does not mean that you must code
all TITLEs before ROWs. Instead, a row number explicitly or implicitly defined for a title cannot be greater than any row
number defined for a work area row.
• You need not code ROW statements for empty rows between rows with data. You can code ROW statements as
placeholders for other ROWs defined without row-numbers. An empty row is coded with a ROW statement without any
items.
• Multiple items on a row are automatically separated from each other by one space. This space contains the screen
attributes for the second of the two items. You can optionally add to this space or locate an item at a specific column
number.
• You can override the automatic placement of items using the COL parameter. Use the COL parameter to specify an
explicit screen column number where the item is placed. The COL parameter specifies the column number where the
data that is contained in the item is placed.
Use an offset (+n) to add to the minimum single space used between items (+1 is the default). The offset applies to
the data to be displayed. To add more space, use an offset greater than +1. There must always be at least one space
between each item on the screen. Items cannot overlap each other.
• You can repeat a ROW statement or group of ROW statements within the REPEAT and END-REPEAT statements to
display an array on a screen.
• You can specify the screen attributes for each item on a work area row. If you do not specify attributes for each item,
default attributes apply as follows:
– If attributes are not specified for a field (ATTR parameter on the ROW statement), default attributes that are
specified on the DEFAULT FIELD statement are used, if they are coded at the beginning of the SCREEN
declaration.
– If attributes are not specified for a literal (ATTR parameter), default attributes specified on the DEFAULT LITERAL
statement are used, if coded.
– If DEFAULT statements are not coded in the SCREEN activity, attributes set in site options are used.
Because literals and read-only fields are not updatable, the following attributes are flagged as warnings when compiled
and ignored when used:
– ALARM
– CURSOR
– INVISIBLE
– MUSTENTER
– MUSTFILL
– NUMERIC
– TRIGGER
• Field attributes can be changed during program execution with the SET statement. For more information, see SET
Statement in the Language Reference section.
Location Examples
The following example illustrates various ROW statements and their resulting screen displays.
SCREEN NAME SCREEN1
TITLE 1 'Personnel View Utility'
692
CA Easytrieve® Report Generator 11.6
ROW 3 'Type the following information, then press Enter.'
ROW 6 COL 10 'Name . . . .' EMPNAME
ROW 8 COL 10 'Gross Pay . .' GROSS-PAY
ROW 10 COL 10 'Dept . . . .' DEPT-NO
Personnel View Utility
Type the following information, then press Enter.
Name . . . . BERG
Gross Pay . . 759.20
Dept . . . . 943
Attribute Examples
The following example illustrates various ROW statements coded with specific attributes. The default attribute for fields is
changed to protect the data. The screen attribute for GROSS-PAY is then specified to unprotect data entry in the field. The
cursor is automatically placed in the first unprotected field on the screen.
SCREEN NAME SCREEN1
DEFAULT FIELD ATTR (PROTECT TURQUOISE)
TITLE 1 'Personnel View Utility'
ROW 3 'Type the new gross pay, then press Enter.' ATTR WHITE
ROW 6 COL 10 'Name . . . .' EMPNAME
ROW 8 COL 10 'Gross Pay . .' GROSS-PAY ATTR (INTENSE TURQUOISE)
ROW 10 COL 10 'Dept . . . .' DEPT-NO
Personnel View Utility
Type the following information, then press Enter.
Name . . . . BERG
Gross Pay . . _ 759.20
Dept . . . . 943
NOTE
When you override the default attribute setting, you must supply all the attributes for the item. Attributes are not
merged. For example, if the default attribute is BLUE PROTECT and you specify ATTR TURQ, the field is left
unprotected because you did not also specify PROTECT in the override.
Format an Item for Display
You can use the following parameters to customize the display of an item in the screen work area:
693
CA Easytrieve® Report Generator 11.6
• FILL
• JUSTIFY
• MASK
This article contains the following information:
Filling an Item for Display
Use the FILL parameter to translate all trailing blanks in a field or literal to a specific character or nulls. If the field is also
an input field, all fill characters are automatically translated to spaces before the data is placed back into the field data
area.
Varying length fields with FILL NULL specified do not have trailing nulls translated to spaces. The first trailing null
terminates the varying length field and sets its length.
Filling with Underscores
The following example illustrates filling a data entry field with underscores to show the terminal user how much data can
be entered. Any remaining underscores are removed when the screen is received.
SCREEN NAME SCREEN1
TITLE 1 'Personnel View Utility'
ROW 3 'Change the employee''s name, then press Enter.'
ROW 6 COL 10 'Name . . . .' EMPNAME FILL '_'
Personnel View Utility
Change the employee's name, then press Enter.
Name . . . . BERG________________
Filling with NULLs
The following example illustrates filling a data entry field with nulls in order to allow the user to insert characters into the
field. The 3270 Display Station requires trailing nulls in a field in order for insertion to work.
SCREEN NAME SCREEN1
TITLE 1 'Personnel View Utility'
ROW 3 'Change the employee''s name, then press Enter.'
ROW 6 COL 10 'Name . . . .' EMPNAME FILL NULL
The screen the user receives is:
Personnel View Utility
Change the employee's name, then press Enter.
Name . . . . BRG
The user can then insert characters into the field to change it to the correct name, BERG.
694
CA Easytrieve® Report Generator 11.6
Justifying Field Contents
Data is typically displayed exactly as it exists in the field, which is determined by its definition.
The JUSTIFY RIGHT parameter shifts the data in the display field to the right. Trailing spaces and nulls are deleted and
leading spaces are inserted. The JUSTIFY LEFT parameter shifts the data in the display field to the left. Leading spaces
and nulls are deleted and trailing spaces are inserted. The following example illustrates these two parameters.
SCREEN NAME SCREEN1
TITLE 1 'Personnel View Utility'
ROW 3 COL 10 'Name . . . .' EMPNAME
ROW 4 COL 10 'Name . . . .' EMPNAME JUSTIFY RIGHT
ROW 6 COL 10 'Gross Pay . .' GROSS-PAY
ROW 7 COL 10 'Gross Pay . .' GROSS-PAY JUSTIFY LEFT
Personnel View Utility
Name . . . . BERG
Name . . . . BERG
Gross Pay . . 759.20
Gross Pay . . 759.20
Using Edit Masks
A mask is automatically applied to numeric fields when displayed. All numeric fields have a default edit mask. You can
override this default with a mask you define. For an explanation of the default mask and how to code your own mask, see
DEFINE Statement and MASK Parameter.
When a numeric field is displayed, it uses the mask associated with the field (either the default or its override on the
DEFINE statement). If you want to use a mask other than the default or override mask for display upon the screen, use
the MASK parameter on the ROW statement. The mask on the ROW specifies the mask to be used for this specific
occurrence of the field on the screen. If the field is used more than once on the screen, the mask must be specified for
each occurrence.
You can use a mask identifier to identify a mask for future use. This shortens coding time when you want to use a
particular mask for several fields of the same size on the screen.
If you have defined a mask for a field on a DEFINE statement and you want to use the system-defined default mask, code
NOMASK on the ROW statement for the field.
Mask Example
The following example illustrates masks:
DEFINE FIELD-WITH-DEFAULT-MASK W 4 P 2 VALUE 1234.56
DEFINE FIELD-WITH-DEFINED-MASK W 4 P 2 VALUE 1234.56 MASK '$$,$$$.99'
DEFINE FIELD-WITH-BWZ-MASK W 4 P 2 VALUE 0 MASK BWZ
SCREEN NAME SCREEN1
TITLE 1 'Mask Examples'
ROW 3 'Using Default Mask' FIELD-WITH-DEFAULT-MASK
ROW 4 'Using Defined Mask' FIELD-WITH-DEFINED-MASK
ROW 5 'Applying a Mask ' FIELD-WITH-DEFAULT-MASK MASK '**,***.99'
ROW 6 'Reverting a Mask ' FIELD-WITH-DEFINED-MASK NOMASK
695
CA Easytrieve® Report Generator 11.6
ROW 7 'BWZ Mask' FIELD-WITH-BWZ-MASK
Mask Examples
Using Default Mask 1,234.56
Using Defined Mask $1,234.56
Applying a Mask *1,234.56
Reverting a Mask 1,234.56
BWZ Mask
Hexadecimal Mask Example
You can display data in hexadecimal format. A hexadecimal mask can be applied to fields of any data type, including
alphanumeric (except for varying length fields). This feature lets you display the actual contents of a field in double-digit
hexadecimal format. For a screen input field, you can use the product to enter or modify data in hexadecimal format. Each
digit is automatically checked for validity (0 to F) and any errors are returned for correction.
SCREEN NAME SCREEN1
TITLE 1 'Mask Examples'
ROW 3 'Name . . . .' EMPNAME MASK HEX
ROW 5 'Gross Pay . .' GROSS-PAY MASK HEX
Mask Examples
Name . . . . C2C5D9C740404040404040404040404040404040
Gross Pay . . 0075920C
Automatic Editing of Input
Input data is automatically edited with little or no coding required.
The following types of edits are performed:
• Data type validation
• Upper casing
• Value checking
• Mask checking
• Pattern matching
Editing is performed in the following order:
1. If UPPERCASE is specified for the field, translate the field to all uppercase characters.
2. If a PATTERN is specified for the field, edit the data against the pattern.
3. If a MASK is specified for the field, edit the data against the mask, including data type validation.
4. If a VALUE is specified for the field, edit the data against the value.
NOTE
You can use the SET statement to edit input data. For more information, see SET Statement.
This article contains the following information:
696
CA Easytrieve® Report Generator 11.6
UPPERCASE
You can specify UPPERCASE for fields that are coded on a ROW statement. When UPPERCASE is coded, data that is
entered on the screen is converted to uppercase characters as it is received from the terminal. To convert all fields on the
screen to uppercase, code UPPERCASE on the SCREEN statement.
PATTERN
PATTERN lets each input character be edited according to the pattern specified. A pattern is a sequence of characters
describing the format of the data in the field. You can use a PATTERN to edit complex combinations of data types and
character sequences.
NOTE
A MASK is used only for numeric data. If you use arithmetic on the data, you probably do not want to use a
PATTERN.
You typically use a PATTERN to edit a field that contains a mixture of alphabetic and numeric characters in a specific
sequence.
For example, to specify a part identification that is a five-character alphanumeric field where the first and last characters
must be uppercase alphabetic (U) and the middle three characters must be numeric digits (D), code:
ROW 'Part ID . . .' PART-ID PATTERN 'UDDDU'
This pattern allows acceptance of entries such as A123C and rejection of entries such as 1A23C.
Valid PATTERN Characters
The valid pattern characters and their meanings are listed in the following table:
Character Meaning
A Represents an uppercase or a lowercase letter.
B Represents a single blank.
D Represents a digit.
E Represents an empty string.
L Represents a lowercase letter.
N Represents an uppercase letter or a national character.
U Represents an uppercase letter.
X Represents any character.
"x" Double quotes surrounding a character or a sequence of
characters literally represent the character or the sequence
of characters that are contained within. The x represents any
character. To literally represent single or double quotes, use two
sets of quotes within the surrounding set of double quotes ('""""' or
'"x""x"', '"''"' or '"x''x"').
blank Blanks (unless contained in double quotes) serve as delimiters
but are otherwise ignored. They can be inserted into the pattern to
increase readability.
() Represents grouping to control the precedence of operators.
or | or , Represents a choice between alternatives.
697
CA Easytrieve® Report Generator 11.6
(m) or (m..n) Represents the repetition of the preceding pattern expression.
or (m..*) The m and n represent numbers and m must be less than n. A
or (*) single number within the parentheses indicates the exact number
or * of repetitions. (m..n) represents a range of repetitions, minimum
to maximum. An asterisk in a range, (m..*), represents an infinite
maximum. An asterisk by itself, (*) or *, represents a range from 0
to infinity.
# or /-/ Represents the remove (or toss) operation. This operation applies
only to a single character set at a time and must immediately
follow the character set in the pattern. This operation removes
from the data the character that matched the character set.
+ Represents character set addition to form another character set.
- Represents character set difference to form another character set.
concatenation Concatenation is implied by proximity. For example, DDDU means
3 digits followed by an uppercase letter.
The precedence of operators from highest to lowest is:
• Grouping: () and ""
• Set construction: + and -
• Actions: #
• Repetition: (n) (m..n) (m..*) (*)
• Concatenation: proximity
• Choice: |
The edit pattern is evaluated from left to right (that is, the data from the screen is processed from left to right). Patterns
examine only one character at a time. They do not look ahead and they do not backtrack.
How to Build a Pattern
The steps for building a pattern are:
1. Analyze your requirements.
2. Determine the order in which you expect users to key characters. Use concatenation to describe the order.
3. Determine how to describe which characters you want to allow in each position in the order.
4. If there is more than one order, use the choice operator to separate the orders.
5. If, within an order, you expect a character or a sequence of characters to be repeated, use an appropriate repetition
operator.
Examples that use these steps follow.
Example 1: Build a ZIP Code Pattern
You have a field into which five digits (such as a ZIP Code) are entered. You define the following rules for the field based
on the How to Build a Pattern steps:
1. The field must have only five digits.
2. The pattern can best be described by:
– Accept 0 through 9 for position 1.
– Accept 0 through 9 for position 2.
– Accept 0 through 9 for position 3.
– Accept 0 through 9 for position 4.
– Accept 0 through 9 for position 5.
698
CA Easytrieve® Report Generator 11.6
3. The best pattern character for each position is D, because D represents the character set of digits. The pattern
becomes: DDDDD.
4. Because only one order is expected for this field, Step 4 of How to Build a Pattern does not apply.
5. Because D repeats five times, the pattern can be D(5). In this case, the application of this step is not required. DDDDD
and D(5) are internally generated the same way. You can use either pattern.
Example 2: Build a Name Pattern
You have a field that represents a first name. You define the following rules for the field that are based on the How to Build
a Pattern steps:
1. Analyze your requirements:
– All blanks are acceptable.
– If a name is keyed, the first character must be uppercase and the remaining characters must be lowercase.
– If a name is keyed, there can be no leading blanks.
– If a name is keyed, trailing blanks are acceptable.
– If only an initial is keyed, it must be uppercase and it must be followed by a period. The remainder of the field must
be blank.
– If an initial is keyed, there can be no leading blanks.
2. There are three possible orders for how the characters for this field can be keyed:
– The first order is all blanks (requirement 1).
– The second order is an uppercase character followed by one or more lowercase characters followed by 0 or more
blanks (requirements 2, 3, and 4).
– The third order is an uppercase character followed by a period followed by blanks (requirements 5 and 6).
3. The part of the pattern that corresponds to the first order is a repetition of B, because B represents blanks.
If the field is ten characters long, one way to specify this order is B(10) or BBBBBBBBBB. A better way to specify this
order is B*. B* means that an infinite number of blanks can be accepted. Because the field is only 10 bytes long, there
can be at most ten blanks to accept. The B* generates a much smaller internal representation, and also adapts better
to changes in the size of the field.
4. The part of the pattern that corresponds to the second order is:
– A U for the uppercase character
– A repetition of Ls for the lowercase characters
– A repetition of Bs for the trailing blanks
– If the field is ten characters long, there can be 1 through 9 lowercase letters. One way to specify the repetition is
L(1..9), but a better way is to use L(1..*), because the length of the field enforces a practical limit. For the repetition
of blanks, use B* instead of B(0..8). The part of the pattern for the second order is UL(1..*) B*. Blanks that are
embedded in patterns are ignored.
5. The part of the pattern that corresponds to the third order is:
– A U for the uppercase character
– A "." for the period
– A repetition of Bs for the blanks
Although there is always the same number of blanks, use B* to describe the trailing blanks in the order. B(*) produces
a much smaller internal representation and is also more flexible. The part of the pattern for the third order is U "." B*.
Combining the parts into a single pattern results in:
'(B*) | (U L(1..*) B*) | (U "." B*)'
Character Sets
A pattern represents the order of character sets in which you accept the data from the screen for a particular field. The
letters A, B, E, D, L, N, U, and X represent predefined character sets. A single letter that is enclosed in double quotes
699
CA Easytrieve® Report Generator 11.6
represents a character set consisting of one character. A sequence of letters that is enclosed in double quotes represents
a series of character sets.
A character set indicates which characters are acceptable. For example, the letter U (when not enclosed in double quotes)
indicates that any uppercase letter is acceptable.
Occasionally, you may prefer to identify characters that do not fit into one of the predefined character sets. In these cases,
you can build a character set that identifies exactly the characters you require. The + and the - operators enable you to
add sets together or to obtain the set difference. Parentheses ( ) let you control the precedence of the operations.
A frequent use for set difference is constructing a set of all characters except a specific set of characters. For example, a
pattern to specify all characters except blanks is X-B.
A frequent use for set addition is constructing a set of characters consisting of one of the predefined sets plus a few
additional characters. For example, a pattern to specify uppercase letters plus blanks is U+B.
Both U+B and U|B recognize the same data. The internal form of U+B is marginally better than U|B because U+B
describes a character set; U|B does not. As a character set, the action operator # can be appended to the set. The set can
be combined with another set using - or + to form a different set.
NOTE
If you need to specify a pattern for predefined character sets in another language, contact CA Support.
Advanced Numeric Patterns
You can use a PATTERN to provide advanced editing of numeric data. For example, you can use a MASK to provide
basic display and edit criteria for a nine-digit ZIP Code:
ROW 13 'ZIP Code . . .' ZIP-CODE MASK '99999-9999'
The mask, when used alone, allows the user to simply type zero. To require the user to enter all nine digits with or without
the hyphen, add the following PATTERN:
ROW 13 'ZIP Code . . .' ZIP-CODE MASK '99999-9999' +
PATTERN 'D(5)"-"(0..1)D(4)B(*)'
The pattern specifies that there should be exactly five digits that are entered, followed by 0 to 1 hyphens followed by
exactly four digits.
A similar example of a PATTERN for a social security number follows:
ROW 13 'SSN . . .' SSN MASK '999-99-9999' +
PATTERN 'DDD "-"(0..1) DD "-"(0..1) DDDDB(*)'
The PATTERN specifies that exactly three digits should be entered, followed by 0 to 1 hyphens, followed by exactly two
digits, followed by 0 to 1 hyphens, followed by exactly four digits, followed by any number of spaces.
Advanced Editing of Names
You can use a PATTERN to ensure that the terminal operator enters valid data in a name field:
ROW 13 'Name . .' EMPNAME PATTERN 'U(1..*) B(*)'
The PATTERN specifies that only a single name of at least one uppercase-only character, followed by any number of
spaces, is valid.
To allow a single uppercase letter followed by only uppercase, or only lowercase letters followed by any number of
spaces, use:
700
CA Easytrieve® Report Generator 11.6
ROW 13 'Name . .' EMPNAME PATTERN 'U(U(*),L(*)) B(*)'
To strip leading blanks, add:
ROW 13 'Name . .' EMPNAME PATTERN 'B#(*) U(U(*),L(*)) B(*)'
To enable one or more names in uppercase with separation by only one space:
ROW 13 'Name . .' EMPNAME PATTERN 'U(1..*) (B U(1..*))(*) B(*)'
To permit uppercase or lowercase letters after the first uppercase letter:
ROW 13 'Name . .' EMPNAME PATTERN 'U(U(*),L(*) (B U(U(*),L(*))(*) B(*)'
Miscellaneous Advanced Editing
This pattern strips leading blanks while not permitting an all-blank field:
ROW 13 'Description . .' DESCRIPTION PATTERN 'B#(*) (X-B) X(*)'
X-B signifies that all characters except blanks are allowed. To allow an all-blank field:
ROW 13 'Description . .' DESCRIPTION +
PATTERN 'B(*) ((X-B)(1..*), B(*))(*)'
To strip leading spaces and remove extra spaces:
ROW 13 'Description . .' DESCRIPTION +
PATTERN 'B#(*) ((X-B)(1..*) B B#(*))(*)'
Internal Operation of Patterns
This topic discusses some advanced material relating to the internal operation of patterns. This information is not required
to build most patterns. However, if you have difficulty building a pattern with the # and (m..n) operators, this information is
helpful.
Patterns are implemented as state tables. A state table examines each character in a string to determine if the string
is acceptable or not. Each character examined causes a transition from one state to the next. Most compilers use state
tables for recognizing tokens (for example, labels or identifiers).
Two extensions in the pattern language are not always converted to a state table: the # and the (m..n) operators. These
operations are implemented as actions associated with transitions.
First Extension -- TOSS Operator
The first extension is the toss operator, # or /-/. It is possible to compose a pattern that converts to a state table in which
the transition from one state to the next does not know whether to toss or keep the recognized character. Consider the
following pattern:
'B* (X-B)* B*'
This pattern allows data that consists of a single string of non-blank characters with or without leading and trailing blanks,
or an all-blank field.
701
CA Easytrieve® Report Generator 11.6
The body of the table indicates what is done when in a given state with given input. If the entry indicates a state, the
product goes to that state. If the entry indicates accept, the data is valid. If the entry is error, the data is rejected.
If you change the pattern to remove any leading blanks, the pattern becomes:
'B#* (X-B)* B*'
In the process of converting the pattern to the state table, all of the possible paths through the pattern are considered. If
the first entry is a blank, the product does not know whether to remove the character or not (does it match the B#* or the
B*?). This pattern generates an error message when compiled.
To correct this pattern and achieve the same results, use:
'B#* (X-B) B#*'
This pattern removes leading and trailing blanks. When the first character is a blank, it does not matter if it is a leading or
a trailing blank because both are removed. The loss of trailing blanks is not damaging. After the data has been accepted,
The data is moved into the corresponding field in the library section. If the field is alphanumeric, it is padded with blanks. If
it is a VARYING alphanumeric field, the length of the field reflects the data, less the trailing blanks. If the field is numeric,
the conversion to the correct data format ignores the blanks.
Second Extension -- Limited Repetition
The second extension is the range repetition with a fixed upper bound, (m..n). This type of repetition is called a limited
repetition. The restrictions on its use are:
1. Limited repetitions cannot be nested within other repetitions (except (m)).
2. When a character from the input data is examined, there can be no ambiguity as to which is the next state and how to
count the character.
Rule 1 is the result of the nature of state tables. All actions are done at the transition from one state to the next. The
counting and checking required by a limited repetition are done at a transition. It is impossible, in all cases, to assign an
action to one or more transitions that reset the counters.
To illustrate Rule 2, consider the following pattern:
'D(0..2) ("."|E) D(0..2) B*'
If the first character in the input data is a digit, does it match the first D(0..2) or the second? If the product could look
ahead to see the rest of the input, it could decide which one it was. But, as stated earlier, patterns examine only one
character at a time. Therefore, this pattern generates an error message when compiled.
NOTE
The pattern 'D(0..2) ("."|E) D(0..2)' does not appear to have any practical application.
Additional Considerations
Consider the following pattern:
'B* X'
If the first character to be examined by the pattern is a blank, does the blank match the B* or the X? If it matches the
B* there can be more data. If it matches the X, there can be no more input. Therefore, this pattern generates an error
message when compiled.
When the product receives data from the screen, the data is almost always padded with trailing blanks unless the user
filled the entire field with data. The EOF key on the 3270 terminal may set the rest of the field on the screen to nulls, but
702
CA Easytrieve® Report Generator 11.6
by the time the pattern sees the data, the nulls have been converted to blanks. You may want to allow for trailing blanks in
your patterns.
NOTE
Trailing blanks in displayed VARYING alphanumeric fields are converted to nulls when received.
MASK
Data that is entered in a numeric field is automatically edited according to an edit mask (default or override):
• Allow and accept digits, a leading or trailing sign (but not both), and a single decimal point. Leading signs are + or -.
Trailing signs are +, -, or the trailing string in the mask (for example, CR). Leading and trailing blanks are accepted and
discarded.
• Align the decimal point when the data is received from the screen.
For example, if you code the following field:
DEFINE NUMFLD W 3 P 2 MASK 'ZZ9.99'
Data is placed into the field as follows:
Value Entered Value Stored
1 001 .00
1.2 001 .20
.235 000 .24
Data is automatically rounded to fit the field.
Decimal alignment is performed only for input. When you display data with a mask, there is no implied relationship
between the mask and the number of decimal digits in the field.
• Allow and discard characters that appear in the mask that are displayed along with the data. For example, commas
appearing in a quantitative field or parentheses and a hyphen appearing in a telephone number are discarded from the
input before the data is stored in the actual field.
Display characters in the data must occur in the same order they appear in the mask. The characters, however, are not
required to appear in the data. For example, applying the mask, 99,999.99, against the data, 12345.67 does not cause
an error condition. However, applying the mask, '(999) 999-9999', against the data, '(617 322-2762)' is in error because
the display characters are out of order.
Any other characters not appearing in the mask cause an error message to be displayed to the terminal user. Blanks
that are embedded in the middle of data that are not part of the mask also cause an error condition.
• Allow only numeric data for numeric fields. A blank entry is allowed only when the mask specifies blank when zero
(BWZ). If the mask is BWZ or contains only Z's for digits, the field is blank when zero.
• Fields that use a hexadecimal mask (MASK HEX) have the input data automatically validated for correct double-
digit hexadecimal characters (0 to F). You can display numeric or alphanumeric (except VARYING) fields with the
hexadecimal mask. If MASK HEX is applied to a numeric field, data is edited only for a valid hexadecimal format, not
for numeric validity.
VALUE
Input data is automatically edited against the values that are specified in the VALUE parameter for the field on the ROW
statement. You can automatically edit the data against a single value, a range of values, or a series of values. The VALUE
parameter works similar to an IF statement.
When an alphanumeric field is edited:
703
CA Easytrieve® Report Generator 11.6
• The values must be alphanumeric literals that are enclosed in quotes.
• The comparison is based on the greater of the length of the value and the length of the field. The shorter item is
padded with blanks out to the length of the longer item. This rule is subject to the exception that follows.
• When a fixed-length field is compared with a longer fixed-length value, the comparison is based on the length of the
field. The value is truncated to match the length of the field. A warning message is generated by the compiler.
• The comparison is logical (bit-by-bit).
When a numeric field is edited:
• The values must be numeric literals.
• Comparison is arithmetic.
The following ROW statements illustrate automatic value editing:
DEFINE ALPHA-FIELD W 1 A
DEFINE NUMERIC FIELD W 3 N 0
ROW 'Alpha Test . . .' ALPHA-FIELD VALUE ('A', 'D', 'U')
ROW 'Numeric Test . .' NUMERIC-FIELD VALUE (1, 101 THRU 500, 999)
Edit Error Messages
As a result of the automatic editing process, the online version of the product handles error conditions as follows:
• Input fields are edited as found on the screen from left-to-right and top-to-bottom.
• All input fields are edited each time a user presses a programmable key (for example, PA keys, function keys, Enter)
unless the key pressed is an IMMEDIATE key. IMMEDIATE keys cause the screen to be received but the data is not
edited and moved into program fields. For more information, see Screen Key Processing.
• Each field found in error receives the FIELD ERROR attribute. You can specify this attribute on a DEFAULT FIELD
ERROR statement at the beginning of the screen declaration. If you do not use the DEFAULT FIELD ERROR
statement, this attribute is taken from the site options. You can set individual error attributes for a field using the
ERROR ATTR parameter for the field on the ROW statement.
• A message describing the error for the first field in error on the screen is automatically displayed. This message
typically tells the user that the field did not match one of the values that are permitted for the field or that the format
of the data was incorrect. You can override the system-issued message with your own message using the ERROR
parameter for the field on the ROW statement.
• Messages that are issued for editing errors, whether system-issued or from the ERROR parameter, are always an
ACTION message level. For more information, see Screen Message Area.
Cursor Placement
You can specify the placement of the cursor on the screen in the following ways:
• Use the CURSOR attribute in the ATTR parameter for the field on the ROW statement. You can also specify the
CURSOR attribute for a field that is flagged in error using the ERROR ATTR parameter for the field on the ROW
statement.
• Execute a CURSOR statement in a screen procedure to specify the field on the screen that receives the cursor upon
the next display of the screen.
704
CA Easytrieve® Report Generator 11.6
Cursor Placement Hierarchy
When more than one way is used to place the cursor in a specific location, the following hierarchy determines how the
cursor is placed. The priority is listed from highest to lowest:
1. If the screen is redisplayed using a RESHOW action, the cursor is placed in the same position as when the screen
was received, regardless of any other method used.
2. If the field is detected in error by the automatic editing process or a SET statement, the first field containing the
CURSOR attribute on the ERROR ATTR parameter of the ROW statement receives the cursor. First is defined as left-
to-right, top-to-bottom.
3. If not a RESHOW or error condition, a CURSOR statement that is executed in a screen procedure names the field
to receive the cursor. If the CURSOR statement is executed more than once before the screen is displayed, the last
CURSOR statement that was executed determines cursor placement.
4. If a CURSOR statement is not executed, the first field on the screen with the CURSOR attribute receives the cursor.
5. If no field on the screen contains the CURSOR attribute, the first modifiable field on the screen receives the cursor.
6. If there are no modifiable fields on the screen, the first item on the screen receives the cursor.
Repeating Rows of Data
The display of arrays on the screen with the REPEAT and END-REPEAT statements is supported. Use the REPEAT and
END-REPEAT statements to surround one or more ROW statements in the screen declaration, and specify the number of
times that the enclosed group of ROW statements is repeated on the screen.
You can also use the REPEAT and END-REPEAT statements to name a subscript field, which is incremented each time
that the repeated rows are displayed. The subscript field helps to automate the process of moving the array to the screen
and then back again upon receiving the data when you use it for the array elements. You can define the subscript field or
let the product automatically define it for you.
REPEAT Example - Simple
An example of how to display an array in a file on the screen follows. The subscript field, POLICY-SUB, used on the
REPEAT statement, is automatically defined.
FILE POLICIES INDEXED
CUST-NO * 5 N
CUST-NAME * 20 A
POLICY-NO 50 8 N OCCURS 3. * Customer may have up to 3
. * policies
SCREEN NAME SHOW-POLICIES
TITLE 'View Customer Policy Numbers'
ROW 3 'Customer Number . .' CUST-NO
ROW 5 'Customer Name . . .' CUST-NAME
ROW 7 'Policies'
REPEAT 3 TIMES VARYING POLICY-SUB
ROW POLICY-NO (POLICY-SUB)
END-REPEAT
View Customer Policy Numbers
Customer Number . . 10346
705
CA Easytrieve® Report Generator 11.6
Customer Name . . . JONES
Policies
32894671
65274902
76642915
Two-Dimensional Arrays
As shown in the previous example, you can code a subscript on each element of an array within a REPEAT group. If
these fields are elements of a two-dimensional array, you can also add a second subscript. A second subscript is not
automatically incremented. You must specify the second subscript as a literal or as a static field, as shown in the following
example:
...
WS-EMPLOYEE W 33 A OCCURS 3 . * 2-dimensional table of
WS-NAME WS-EMPLOYEE 30 A . * 3 employees containing:
WS-STATUSES WS-EMPLOYEE +30 3 A . * employee name and
WS-STAT WS-STATUSES 1 A OCCURS 3. * 3 statuses
...
SCREEN NAME EMPLOYEE-LIST
TITLE 'List of Employees'
ROW 3 'Name' COL 30 'Statuses'
REPEAT 3 TIMES VARYING USER-SUB
ROW WS-NAME (USER-SUB) +
WS-STAT (USER-SUB, 1) WS-STAT (USER-SUB, 2) +
WS-STAT (USER-SUB, 3)
END-REPEAT
List of Employees
Name Statuses
WIMN, GLORIA F G O
BERG, NANCY C
CORNING, GEORGE I T
Screen Message Area
The message area displays system-issued and programmer-issued messages to the terminal user.
You can issue different levels of messages depending on the severity of the error. The three message levels in ascending
severity are:
• Information messages typically inform a user that processing is proceeding normally.
• Warning messages tell the user that a potentially undesirable result has occurred or could occur.
• Action messages tell users that an action is required to correct a situation.
System-issued messages and messages that are specified on the SET statement are always the ACTION message level.
Message Area Location
The default message area location is at the bottom of the screen, just above the function key display area. You can
move the message area by specifying its row number on a DEFAULT MESSAGE statement at the beginning of the
706
CA Easytrieve® Report Generator 11.6
screen declaration. By default, all three levels of messages are sent to the same screen row number. Use the DEFAULT
statement to designate from one to three rows to display different levels of messages on the screen.
Message Attributes
You can specify attributes for the three levels of messages on DEFAULT MESSAGE statements. If you do not use a
DEFAULT MESSAGE statement, screen attributes for each message level are taken from the site options.
Message Text
The screen message area is used for both system-issued and programmer-issued messages. System-issued messages
result from the edit process that the product automatically performs on input data. You can override the message resulting
from the edit process with the ERROR parameter of the ROW statement. See Automatic Editing of Input for more
information.
You can also issue messages from the screen procedures that you code following the screen declaration by executing the
MESSAGE or SET statement prior to the display of the screen.
Screen Function Key Area
The optional function key area is used to tell the terminal user which function keys are active and the action that each key
performs.
Location
The function key area is always located at the bottom of the screen. The display is determined by the KEY statements you
code in the screen declaration. You can specify descriptive text on each KEY statement to be displayed with the name of
the key. Depending on the number of keys and the length of the descriptive text, more than one row of the screen may be
required to display the active function keys.
NOTE
If you specify that one or more message areas use the same screen row as the function key area, messages
may overlap the function key area. The default location for messages is just above the function key area.
Attributes
You can specify attributes for the function key area on a DEFAULT KEY statement. If you do not use a DEFAULT KEY
statement, screen attributes for the function key area are taken from the site options.
Screen Key Processing
Keys that the terminal user presses to send the screen to the program for processing are automatically validated. You
control this process by coding KEY statements in the screen declaration. KEY statements determine which keys are valid
on a particular screen.
Keys can also be assigned to perform specific actions when the key is pressed. You can also control the display of
information about the keys to the terminal user on KEY statements. For more information, see Screen Function Key Area.
The following rules apply to key processing:
707
CA Easytrieve® Report Generator 11.6
• Each KEY statement specifies one or more keys that are active for that SCREEN activity. If the user presses an
inactive key, an error message is automatically sent to the user.
• Each KEY statement can specify a NAME parameter containing text to be displayed at the bottom of the screen.
• If you do not code any KEY statements in your SCREEN activity, all keys are active and you must provide code in your
SCREEN procedures to validate key values.
• With each KEY statement, you can optionally assign the key to perform a branch action automatically. Branch actions
cause activity execution to branch to a specific step in the process. The branch actions that you can code on a KEY
statement and their effects are:
Action Effect
REFRESH Restore the initial condition of the screen
EXIT Terminate the SCREEN activity
For more information, see Screen Procedures.
• With each KEY statement, you can optionally assign the key to perform IMMEDIATE processing. IMMEDIATE indicates
that the key is to be processed immediately, without editing the input data and moving the data into the program fields.
• KEY statements can only be coded for keys for which the product has defined a symbolic name. The symbolic names
are assigned to specific values of the system-defined field, KEY-PRESSED. For symbolic names, see System-Defined
Fields.
NOTE
If you process values of KEY-PRESSED that do not have symbolic names (in screen procedures) you cannot
code KEY statements in your screen declaration.
3270 Display Station Keys
When the terminal user presses CLEAR, PA1, PA2, or PA3, the 3270 Display Station returns only the name of the key
pressed. Data on the screen is not received and the cursor position cannot be determined.
Screen Procedures
The execution of a SCREEN activity is actually a collection of procedures that the product performs in a certain sequence.
Points in which special-named procedures are invoked in a SCREEN activity are:
You can code these special-named procedures to perform customized actions specific to your application. For more
information about these screen procedures, see Branch Actions.
You are not required to code these procedures. If they are not coded, the program proceeds to the next step in the activity.
The following steps illustrate the SCREEN activity process that the product performs and when the special-named
procedures, if coded, are executed:
1. Reset working storage and then perform the INITIATION procedure, processing any branch actions.
2. Reset working storage and then perform the BEFORE-SCREEN procedure, processing any branch actions.
3. Build the screen using program fields, pending messages, and pending cursor placement. Clear the internal pending
message buffer.
4. Send the screen to the terminal. Terminate and resume the program (if pseudo-conversational). Receive the screen
from the terminal.
5. If KEY-PRESSED is an IMMEDIATE key, go to step 7.
6. If KEY-PRESSED is not an IMMEDIATE key, edit input data. If there are any errors, go to step 4. If there are no errors,
move the data into the program fields.
7. If KEY-PRESSED has an associated branch action, perform the action.
708
CA Easytrieve® Report Generator 11.6
8. Perform the AFTER-SCREEN procedure, processing any branch actions.
9. Go to Step 2.
10. When EXIT is requested, reset working storage, and then perform the TERMINATION procedure, processing any
branch actions.
INITIATION
The INITIATION procedure is performed once during the initiation of the activity. Use INITIATION to perform actions that
can be executed only once. For example, setting a field to an initial value or positioning a file at a specific starting location.
Work fields with the RESET parameter specified are automatically initialized before the INITIATION procedure is invoked.
The REFRESH and RESHOW branch actions are invalid in an INITIATION procedure.
BEFORE-SCREEN
The BEFORE-SCREEN procedure is invoked during each iteration of the SCREEN activity and precedes building the
screen and the terminal I/O process. Typically, BEFORE-SCREEN is used to perform file I/O, initialize fields, or set
the cursor position. Work fields with the RESET parameter specified are automatically initialized before the BEFORE-
SCREEN procedure is invoked.
GOTO SCREEN, REFRESH, and RESHOW are invalid in a BEFORE-SCREEN procedure.
AFTER-SCREEN
The AFTER-SCREEN procedure is performed during each iteration of the activity after the terminal I/O processes. The
procedure is not executed if the key pressed is assigned to execute a branch action. An AFTER-SCREEN procedure can
be used to perform complex editing and to update files with data that is entered on the screen.
All branch actions are valid in the AFTER-SCREEN procedure.
TERMINATION
The TERMINATION procedure is performed when an EXIT action is executed, either from a key pressed or from another
screen procedure. The procedure is used to perform actions that are to be executed only at the end of the activity. Work
fields with the RESET parameter specified are automatically initialized before the TERMINATION procedure is invoked.
If GOTO SCREEN or EXIT is executed in a TERMINATION procedure, the activity is terminated. REFRESH and
RESHOW are invalid in a TERMINATION procedure.
Programmer-Defined Procedures
You can code your own procedures in a SCREEN activity and perform them from the special-named screen procedures.
Procedures that you code are local to the screen activity and cannot be performed from other activities.
Branch Actions
This article describes the four actions that cause program execution to branch to specific steps in the SCREEN activity
process:
Action Step Effect
GOTO SCREEN 2 Repeat the activity process.
REFRESH 3 Restore the initial condition of the screen.
RESHOW 4 Redisplay the screen as it was received.
709
CA Easytrieve® Report Generator 11.6
EXIT 10 Terminate the activity.
GOTO SCREEN
You can use the GOTO SCREEN statement to repeat the activity process. The default action of a SCREEN activity is
to repeat the process until an EXIT action is executed. If the bottom of the process (the end of the AFTER-SCREEN
procedure) is reached, the activity simply repeats, starting with the BEFORE-SCREEN procedure. (The INITIATION
procedure is a one-time-only procedure).
You can code the GOTO SCREEN statement to cause an immediate branch to the top of the activity. This is similar to how
GOTO JOB branches to the top of a JOB activity.
REFRESH
REFRESH causes the screen to be restored to its initial condition or updated to reflect the current status of information.
The screen is rebuilt using the current value of the fields specified on the screen.
When REFRESH is coded on an IMMEDIATE key, the product ignores data that is entered on the screen and refreshes
the screen as it was originally sent to the user. When REFRESH is coded on a non-IMMEDIATE key, it causes entered
data to be edited and moved into the program field areas, but no special-named procedure is invoked. This enables you to
assign a key solely to allow the user to edit data. The entered data is edited against the automatic edits that you code and
no additional code is required in the AFTER-SCREEN procedure. When the user wants to update the file with the data,
they can press another key to invoke the AFTER-SCREEN procedure. This is illustrated in the following example.
SCREEN NAME MYSCREEN
TITLE 'Inventory Control'
KEY F5 NAME 'Refresh' IMMEDIATE REFRESH
KEY F6 NAME 'Edit input' REFRESH
KEY F10 NAME 'Update'
...
When the user presses F5, data currently on the screen is ignored and the screen is rebuilt from the original field
contents. When the user presses F6, the data that was entered is edited as specified on the ROW statements. Pressing
F10 also edits the data but then performs an AFTER-SCREEN procedure that updates the file.
You can also use REFRESH to update the screen contents with the current data available. For example, a user enters
a quantity and a price and wants to see the extended price (price times quantity). You can use a REFRESH coded in an
AFTER-SCREEN procedure to compute the extended price as shown in this example:
SCREEN NAME MYSCREEN
TITLE 'Inventory Control'
KEY F2 NAME 'Reset to zero'
KEY F6 NAME 'Refresh' IMMEDIATE REFRESH
KEY F9 NAME 'Show Extended Price'
KEY F10 NAME 'Update'
ROW 3 'Quantity . .' QUANTITY
ROW 5 'Price . . . .' PRICE
ROW 7 'Ext Price . .' EXT-PRICE ATTR (TURQ ASKIP)
...
BEFORE-SCREEN. PROC
MOVE ZEROS TO QUANTITY, PRICE, EXT-PRICE
END-PROC
AFTER-SCREEN. PROC
IF KEY-PRESSED = F9
710
CA Easytrieve® Report Generator 11.6
EXT-PRICE = PRICE * QUANTITY
REFRESH
END-IF
...
END-PROC
When the user types the quantity and price and presses F9, the quantity and price are received, and the extended price
is computed. The REFRESH then redisplays the screen using the current value of the program fields, and the newly
computed extended price is displayed.
RESHOW
You can use RESHOW in an AFTER-SCREEN procedure to redisplay the screen after the screen has been received.
A copy of the received screen image is saved. You can then EXECUTE another SCREEN activity. When the program
returns to the first activity, use RESHOW to redisplay the saved image of the first screen.
When associated indirectly with an IMMEDIATE key, you can ignore any data that is entered on the screen, display a
second screen, and then RESHOW the first screen intact. For example, you can permit the user to view a help screen,
then return to the screen on which the user requested help.
When associated indirectly with a non-IMMEDIATE key, you can permit the user to display a selection list, accept and
process the user selections, and then redisplay the original screen.
EXIT
EXIT terminates the SCREEN activity and returns control to the activity from which it was executed. If the current
SCREEN activity was not executed from another activity, EXIT terminates the program. Associating EXIT with an
IMMEDIATE key is equivalent to a cancel function. Any data on the screen is ignored and the activity terminates.
Associating EXIT with a non-IMMEDIATE key saves the data into the program fields after editing it.
NOTE
It is your responsibility to save the data to a file if your application requires it. Data saved into the program fields
is lost when the program terminates, unless written to a file.
CICS Pseudo-conversational Programs
The SCREEN activity process shows how pseudo-conversational programs are handled. In Step 4 of Screen Procedures,
the screen is sent to the terminal. If your SCREEN activity is executing in a pseudo-conversational mode (COMMIT
NOTERMINAL is not specified for a CICS program), the product then terminates the task and returns to CICS. When the
terminal user presses a programmable terminal key, CICS executes the program again, and the product resumes the task
and receives the screen. For more information, see the following articles:
• Commit Processing
• Control Program Flow
• Code CICS Programs
Send Messages
An internal message area is maintained for each message area that is defined on your screen. The MESSAGE statement
can be executed anywhere in your program to update the pending message area. When the next screen is displayed, the
screen message area is built from the pending message. The pending message area is then cleared.
You can use these pending messages across activities to prepare messages in one activity for display on a screen in
another activity. The following example shows how to code messages in a SCREEN activity:
711
CA Easytrieve® Report Generator 11.6
FILE PERSNL INDEXED WORKAREA 150
%PERSNL
SCREEN NAME VIEW-UTILITY
KEY ENTER
KEY F3 NAME 'Exit' EXIT
TITLE 1 'Employee View Utility'
ROW 3 'Employee Number . .' EMP#
ROW 5 'Employee Name . . .' EMPNAME
INITIATION. PROC
MESSAGE 'Enter an employee number.' LEVEL INFORMATION
MOVE ZERO TO EMP-NO
MOVE SPACES TO EMPNAME
END-PROC
AFTER-SCREEN. PROC
READ PERSNL KEY EMP# STATUS
IF NOT PERSNL
MESSAGE 'Employee not found. Enter another number.' LEVEL ACTION
ELSE
MESSAGE 'Employee found. Enter another number.' LEVEL INFORMATION
END-IF
END-PROC
Employee View Utility
Employee Number . . _
Employee Name . . .
...
Enter an employee number.
F3=Exit
An introductory message (message level INFORMATION) is issued to the terminal user from an INITIATION procedure.
After the user enters an employee number and presses Enter, the AFTER-SCREEN procedure is performed and issues
an appropriate message describing the results of the file I/O. If the record is found, the user receives an INFORMATION
message. If the record is not found, an ACTION message is issued, flagging an error condition that must be corrected
before the process can continue.
Message Levels
The product lets you automatically manage different levels of messages. For example, you can issue INFORMATION
or WARNING messages in your program, but discover later in the process that a severe error condition that requires an
ACTION message could arise. If the message areas for the different message levels are located on the same screen row,
coding the ACTION message overlays any previous or subsequent INFORMATION or WARNING messages because of
the severity hierarchy of the message levels. When you issue multiple messages of the same level, the last one issued for
the highest level is displayed.
712
CA Easytrieve® Report Generator 11.6
Determine the Cursor Location
You can determine the position of the cursor when the screen is received by using the special IF CURSOR statement
in a screen procedure. Use the IF CURSOR statement to test whether the cursor is present within a specified field. The
following example illustrates the IF CURSOR statement testing for cursor placement on any of four subscripted array
elements on the screen:
DEFINE OPTION W 1 A OCCURS 4
SCREEN NAME MENU
KEY F2 NAME 'Select'
KEY F3 NAME 'Exit' EXIT
TITLE 1 'Employee System Main Menu'
ROW 3 'Position the cursor by your selection, press F2 to select.'
ROW 5 COL 10 OPTION (1) 'View employee'
ROW COL 10 OPTION (2) 'Edit employee'
ROW COL 10 OPTION (3) 'Delete employee'
ROW COL 10 OPTION (4) 'Add employee'
AFTER-SCREEN. PROC
IF OPTION (1) CURSOR
EXECUTE VIEW-EMPLOYEE
ELSE-IF OPTION (2) CURSOR
EXECUTE EDIT-EMPLOYEE
ELSE-IF OPTION (3) CURSOR
EXECUTE DELETE-EMPLOYEE
ELSE-IF OPTION (4) CURSOR
EXECUTE ADD-EMPLOYEE
ELSE
MESSAGE 'Position cursor by a menu selection.'
END-IF
END-PROC
...
Employee System Main Menu
Position the cursor by your selection, press F2 to select.
_ View employee
Edit employee
Delete employee
Add employee
...
F2=Select F3=Exit
Test for Field Modification
You can use the IF MODIFIED statement to test whether a field has been modified by the terminal user. Following are the
rules for using the IF MODIFIED statement:
713
CA Easytrieve® Report Generator 11.6
• The test for modification determines whether the value of the field actually changed. If the user types the same value in
the field as was originally displayed, the modification test is false.
• The results of the IF MODIFIED test are set at the time the screen is received. If the value of the input data is not
equal to the value of the program field, the field was modified. If the input data is equal to the program field, the field is
considered not modified.
• The IF MODIFIED comparison is performed logically for both alphanumeric fields and numeric fields.
• If the screen is received as the result of an IMMEDIATE key, PA key, or CLEAR key, the IF MODIFIED test is always
false.
Using the IF MODIFIED test can help you write more efficient programs. For example, you may not want to perform
complex editing on a field unless the user has changed it. The following is an example of the IF MODIFIED test:
SCREEN NAME EDIT-EMPLOYEE
KEY ENTER
KEY F3 NAME 'Exit' EXIT
TITLE 1 'Employee Edit Utility'
ROW 3 'Enter the employee number and new job category.'
ROW 5 'Employee number . .' EMP#
ROW 7 'Job Category . . . .' JOB-CATEGORY
AFTER-SCREEN. PROC
IF JOB-CATEGORY MODIFIED
PERFORM SEARCH-JOB-CATEGORY-TABLE
IF NOT JOBTABLE
MESSAGE 'Job category is invalid. Please reenter.'
ELSE
PERFORM UPDATE-EMPLOYEE
MESSAGE 'Job category updated.' LEVEL INFORMATION
MOVE ZERO TO EMP# JOB-CATEGORY
END-IF
ELSE
MESSAGE 'Job category not modified.' LEVEL WARNING
JOB-CATEGORY = 0
END-IF
END-PROC
...
The IF MODIFIED test of the JOB-CATEGORY field determines whether to look up the field in a table and update the
record. If the user does not modify the screen contents, these I/O operations are not performed.
Setting Errors
When you can determine the validity of user input with a simple IF statement, such as IF DEPT = 901 THRU 999, the
VALUE parameter on the ROW statement provides easy automatic error handling. Often, however, you must provide more
complex logic to determine the validity of a value. For example, you may need to perform cross-field editing where the
value of one field on the screen determines acceptable values for another field on the screen, or you may have to perform
a table lookup or other advanced processing to determine validity.
You can use the SET statement to extend automatic error handling in screen procedures. When you execute a SET
statement for a field, the SET information is used the next time that the screen is displayed. You can simply change the
screen attributes for the field. However, the screen process treats the field as if automatic editing detected the error if you
code the ERROR parameter. The error attributes and error message for the field are used by default, but you can even
override these with a SET statement. For more information, see SET Statement.
714
CA Easytrieve® Report Generator 11.6
Commit Processing
You can use commit processing in screen activities to provide file integrity during update operations. See Units of
Work and Commit Processing for information about instructing the product to use either automatic or controlled commit
processing during program execution. See File Processing Modes for information about how requests are processed to
update records during file processing.
This article contains the following information:
SCREEN COMMIT Parameter
The COMMIT parameter of the SCREEN statement controls the way commit points are automatically issued during
screen processing. The TERMINAL|NOTERMINAL subparameter controls whether records are held during terminal I/O
operations. In multiuser environments such as CICS networks, it is important to fully understand the use of TERMINAL|
NOTERMINAL.
COMMIT TERMINAL tells the product to commit during each terminal I/O. A commit point releases any holds you
have active. Before the program can update a record, it must read the record again after the user returns the screen
to the program for processing. A user cannot inadvertently lock a record from being accessed by other users while
thinking about updating a record. COMMIT TERMINAL is the default for screen activities. In a CICS environment, this is
called running the program pseudo-conversationally.
COMMIT NOTERMINAL tells the product not to commit during terminal I/O. In CICS, this is called running
conversationally. The advantage of running conversationally is that the program must read a record only once, display it
on the screen, and then simply update it when instructed by the terminal user. The disadvantage is that the record is held
until the user presses an attention key, the update is performed, or a commit point is explicitly issued.
Conversational Processing Example
The following example program illustrates using COMMIT NOTERMINAL to keep the product from issuing a commit point
during terminal I/O. The terminal user types an employee number and then presses F5 to find the employee record. When
the user modifies the social security number and presses F6, the employee record is updated. Because UPDATE is coded
on the FILE statement, the READ statement automatically holds the record until it is updated. This hold is in effect the
entire time the user thinks about the change. The hold prohibits other users in a multiuser environment from accessing
the record during this time. Not issuing a commit point also keeps the system from freeing system resources while the
program is running.
FILE KPERSNL INDEXED UPDATE
%PERSNL
WORK-EMP# W 5 N
SCREEN NAME UPDATE-KPERSNL COMMIT NOTERMINAL
KEY F3 NAME 'Exit' EXIT
KEY F5 NAME 'Find employee'
KEY F6 NAME 'Update employee'
TITLE 'Update Social Security Number'
ROW 5 'Employee Number. . . . . .' WORK-EMP#
ROW 7 'Social Security Number . .' SSN
INITIATION. PROC
SSN = 0
MESSAGE 'ENTER EMPLOYEE NUMBER. PRESS F5 TO FIND.' +
LEVEL INFORMATION
END-PROC
AFTER-SCREEN. PROC
CASE KEY-PRESSED
715
CA Easytrieve® Report Generator 11.6
WHEN F5
READ KPERSNL KEY WORK-EMP# STATUS
IF NOT KPERSNL
MESSAGE 'EMPLOYEE NOT FOUND. ENTER NEXT EMPLOYEE.'
MOVE ZERO TO SSN
ELSE
MESSAGE 'ENTER NEW SSN. PRESS F6.' LEVEL INFORMATION
CURSOR AT SSN
END-IF
WHEN F6
WRITE KPERSNL UPDATE STATUS
IF FILE-STATUS NE 0
MESSAGE 'EMPLOYEE NOT UPDATED. REASON=' FILE-STATUS
ELSE
MESSAGE 'SSN UPDATED. ENTER NEXT EMPLOYEE. PRESS F5.' +
LEVEL INFORMATION
END-IF
END-CASE
END-PROC
Pseudo-conversational Processing Example
The next example shows the same program using COMMIT TERMINAL to tell the product to issue a commit point during
terminal I/O. COMMIT TERMINAL is the default if not specified. The commit point that is issued between the time the user
sees the record and finally updates it allows other users to access the record. It also frees valuable system resources
each time a terminal operation is performed.
The program must read the record again following the user's request to update it (F6). Any hold that is issued during the
read for the find request (F5) is lost when the employee record is displayed on the terminal. The program specifically
states NOHOLD on the READ statement for finding the record and HOLD on the READ statement for updating the record.
If NOHOLD had not been specified, a hold would have been issued but released when the screen was displayed.
Reading the record again presents more complexity. If the actual record is used as the screen data area (as in this
example), the second READ statement causes the data that is entered by the terminal user to be lost. To handle this
condition, simply define a work area to hold the record contents during the read operation. Restore the contents before the
update takes place.
FILE KPERSNL INDEXED UPDATE
%PERSNL
WORK-EMP# W 5 N
WORK-AREA W 150 A
SCREEN NAME UPDATE-KPERSNL COMMIT TERMINAL
KEY F3 NAME 'Exit' EXIT
KEY F5 NAME 'Find employee'
KEY F6 NAME 'Update employee'
TITLE 'Update Social Security Number'
ROW 5 'Employee Number. . . . . .' WORK-EMP#
ROW 7 'Social Security Number . .' SSN
INITIATION. PROC
SSN = 0
MESSAGE 'ENTER EMPLOYEE NUMBER. PRESS F5 TO FIND.' +
LEVEL INFORMATION
END-PROC
AFTER-SCREEN. PROC
716
CA Easytrieve® Report Generator 11.6
CASE KEY-PRESSED
WHEN F5
READ KPERSNL KEY WORK-EMP# NOHOLD STATUS
IF NOT KPERSNL
MESSAGE 'EMPLOYEE NOT FOUND. ENTER NEXT EMPLOYEE.'
MOVE ZERO TO SSN
ELSE
MESSAGE 'ENTER NEW SSN. PRESS F6.' LEVEL INFORMATION
CURSOR AT SSN
END-IF
WHEN F6
MOVE KPERSNL TO WORK-AREA
READ KPERSNL KEY WORK-EMP# HOLD
MOVE WORK-AREA TO KPERSNL
WRITE KPERSNL UPDATE STATUS
IF FILE-STATUS NE 0
MESSAGE 'EMPLOYEE NOT UPDATED. REASON=' FILE-STATUS
ELSE
MESSAGE 'SSN UPDATED. ENTER NEXT EMPLOYEE. PRESS F5.' +
LEVEL INFORMATION
END-IF
END-CASE
END-PROC
Concurrent Updates
When many users concurrently update the same file in a pseudo-conversational environment, your program must handle
certain conditions. During the time the terminal user is thinking about modifying a record, the record could be deleted or
updated by another user. For example, when a user is shown the quantity of an item in inventory, by the time they deducts
the order quantity, another user may have depleted the stock. If you do not reevaluate the quantity when you read the
record again for update, the user could sell stock they do not really have.
There are several coding conventions to handle these conditions. Two of the more common coding conventions are:
• Set a flag in the record that is under consideration for update. All programs accessing the file must test the flag before
allowing any update access.
• Save a copy of the data that is displayed to the user. Before updating it, compare the current data to the saved copy.
If any changes are detected, display the current data and warn the user that there was a concurrent change to the
record.
The next example contains the previous program in which code has been added to handle concurrent updates. A copy of
the social security number that is displayed to the user is saved in the working storage field, SAVE-SSN. Code has been
added to detect if another user deletes the record. When the read is successful, the social security number in the record
is compared to the number that was originally displayed to the user. If it is not the same, the user is warned that another
user already changed the number, and is asked to process the change again.
FILE KPERSNL INDEXED UPDATE
%PERSNL
WORK-EMP# W 5 N
WORK-AREA W 150 A
SAVE-SSN W SSN
SCREEN NAME UPDATE-KPERSNL COMMIT TERMINAL
KEY F3 NAME 'Exit' EXIT
KEY F5 NAME 'Find Employee'
KEY F6 NAME 'Update employee'
717
CA Easytrieve® Report Generator 11.6
TITLE 'Update Social Security Number'
ROW 5 'Employee Number. . . . . .' WORK-EMP#
ROW 7 'Social Security Number . .' SSN
INITIATION. PROC
SSN = 0
MESSAGE 'ENTER EMPLOYEE NUMBER. PRESS F5 TO FIND.' +
LEVEL INFORMATION
END-PROC
AFTER-SCREEN. PROC
CASE KEY-PRESSED
WHEN F5
READ KPERSNL KEY WORK-EMP# NOHOLD STATUS
IF NOT KPERSNL
MESSAGE 'EMPLOYEE NOT FOUND. ENTER NEXT EMPLOYEE.'
MOVE ZERO TO SSN
ELSE
SAVE-SSN = SSN
MESSAGE 'ENTER NEW SSN. PRESS F6.' LEVEL INFORMATION
CURSOR AT SSN
END-IF
WHEN F6
MOVE KPERSNL TO WORK-AREA
READ KPERSNL KEY WORK-EMP# HOLD STATUS
IF NOT KPERSNL
MESSAGE 'EMPLOYEE ' WORK-EMP# ' NO LONGER ON FILE. +
ENTER NEW EMPLOYEE. PRESS F5.'
MOVE ZERO TO SSN
GOTO SCREEN
ELSE-IF SSN NE SAVE-SSN
MESSAGE 'INTERMITTENT CHANGE DETECTED! RETYPE NEW VALUE +
AND PRESS F6 TO UPDATE.' LEVEL WARNING
SAVE-SSN = SSN
GOTO SCREEN
END-IF
MOVE WORK-AREA TO KPERSNL
WRITE KPERSNL UPDATE STATUS
IF FILE-STATUS NE 0
MESSAGE 'EMPLOYEE NOT UPDATED. REASON=' FILE-STATUS
ELSE
MESSAGE 'SSN UPDATED. ENTER NEXT EMPLOYEE. PRESS F5.' +
LEVEL INFORMATION
END-IF
END-CASE
END-PROC
SQL Processing Example
The programs in the previous examples process an indexed file. This next example illustrates how the previous program
(Concurrent Updates) looks when an SQL table is processed instead:
FILE KPERSNL SQL( SSRPRS0.PERSNL) UPDATE
SQL INCLUDE ( EMP#, SSN) FROM SSRPRS0.PERSNL LOCATION *
MASK-SSN SSN SSN MASK('999-99-9999')
718
CA Easytrieve® Report Generator 11.6
WORK-EMP# W EMP# MASK('99999')
WORK-AREA W 8 A
SAVE-SSN W SSN
SCREEN NAME UPDATE-PERSNL COMMIT TERMINAL
KEY F3 NAME 'Exit' EXIT
KEY F5 NAME 'Find Employee'
KEY F6 NAME 'Update employee'
TITLE 'Update Social Security Number'
ROW 5 'Employee Number. . . . . .' WORK-EMP#
ROW 7 'Social Security Number . .' MASK-SSN
INITIATION. PROC
MASK-SSN = 0
MESSAGE 'ENTER EMPLOYEE NUMBER. PRESS F5 TO FIND.' +
LEVEL INFORMATION
END-PROC
AFTER-SCREEN. PROC
CASE KEY-PRESSED
WHEN F5
SELECT FROM KPERSNL +
WHERE EMP# = :WORK-EMP#
FETCH FROM KPERSNL
IF NOT KPERSNL
MESSAGE 'EMPLOYEE NOT FOUND. ENTER NEXT EMPLOYEE.'
MOVE ZERO TO MASK-SSN
ELSE
SAVE-SSN = SSN
MESSAGE 'ENTER NEW SSN. PRESS F6.' LEVEL INFORMATION
CURSOR AT MASK-SSN
END-IF
WHEN F6
MOVE KPERSNL TO WORK-AREA
SELECT FROM KPERSNL +
WHERE EMP# = :WORK-EMP# +
FOR UPDATE
FETCH FROM KPERSNL
IF NOT KPERSNL
MESSAGE 'EMPLOYEE ' WORK-EMP# ' NO LONGER ON FILE. +
ENTER NEW EMPLOYEE. PRESS F5.'
MOVE ZERO TO MASK-SSN
GOTO SCREEN
ELSE-IF SSN NE SAVE-SSN
MESSAGE 'INTERMITTENT CHANGE DETECTED! RETYPE NEW +
VALUE AND PRESS F6 TO UPDATE.' LEVEL WARNING
SAVE-SSN=SNN
GOTO SCREEN
END-IF
MOVE WORK-AREA TO KPERSNL
UPDATE KPERSNL
IF FILE-STATUS NE 0
MESSAGE 'EMPLOYEE NOT UPDATED. REASON=' FILE-STATUS
ELSE
MESSAGE 'SSN UPDATED. ENTER NEXT EMPLOYEE. PRESS F5.' +
LEVEL INFORMATION
719
CA Easytrieve® Report Generator 11.6
END-IF
END-CASE
END-PROC
Sample Screen Applications
This article contains the following coding examples for several common screen applications:
Editing Data and Setting Errors
ROW statements provide automatic editing and error handling. However, complex edits may require logic in the screen
procedures. The next example illustrates using an in-stream table file to verify the value that is typed for an employee job
category. When the search fails, the SET statement is used to indicate the field as being in error and an appropriate error
message is issued:
FILE KPERSNL INDEXED UPDATE WORKAREA 150
%PERSNL
FILE JOBTABLE TABLE INSTREAM
ARG 1 2 N
DESC 3 1 A
10X
25X
30X
...
ENDTABLE
SCREEN NAME EDIT-EMPLOYEE LINESIZE 80 ROWCOUNT 24
KEY ENTER
KEY F3 NAME 'Exit' EXIT
TITLE 1 'Employee Edit Utility'
ROW 3 'Enter the employee number and new job category.'
ROW 5 'Employee number . .' EMP#
ROW 7 'Job Category . . . .' JOB-CATEGORY
...
AFTER-SCREEN. PROC
IF JOB-CATEGORY MODIFIED
PERFORM SEARCH-JOB-CATEGORY-TABLE
IF NOT JOBTABLE
SET JOB-CATEGORY ERROR +
'Job category is invalid. Please reenter.'
ELSE
PERFORM UPDATE-EMPLOYEE
MESSAGE 'Job category updated.' LEVEL INFORMATION
MOVE ZERO TO EMP# JOB-CATEGORY
END-IF
ELSE
MESSAGE 'Job category not modified.' LEVEL WARNING
JOB-CATEGORY = 0
END-IF
END-PROC
SEARCH-JOB-CATEGORY-TABLE. PROC
DEFINE WCAT W 1 A
SEARCH JOBTABLE WITH JOB-CATEGORY GIVING WCAT
720
CA Easytrieve® Report Generator 11.6
END-PROC
...
Using Dynamic Screen Attributes
The following example illustrates a screen activity that uses dynamic screen attributes. Declared attributes are used for
the job category prompt text and JOB-CATEGORY field. These declared attributes are initialized when created with the
DECLARE statement. When an error occurs, the attributes of both the prompt text and field are changed to highlight the
condition. When no error condition exists, the normal attributes are used.
DECLARE TEXT-ATTR ATTR (GREEN ASKIP)
DECLARE FIELD-ATTR ATTR (TURQ)
DECLARE NORMAL-TEXT-ATTR ATTR (GREEN ASKIP)
DECLARE ERROR-TEXT-ATTR ATTR (YELLOW INTENSE REVERSE ASKIP ALARM)
DECLARE NORMAL-FIELD-ATTR ATTR (TURQ)
DECLARE ERROR-FIELD-ATTR ATTR (YELLOW INTENSE REVERSE ALARM)
SCREEN NAME EDIT-EMPLOYEE
KEY ENTER
KEY F3 NAME 'Exit' EXIT
TITLE 1 'Employee Edit Utility'
ROW 3 'Enter the employee number and new job category.'
ROW 5 'Employee number . .' EMP#
ROW 7 'Job Category . . . .' ATTR TEXT-ATTR +
JOB-CATEGORY ATTR FIELD-ATTR
INITIATION. PROC
EMP# = 0
JOB-CATEGORY = 0
END-PROC
AFTER-SCREEN. PROC
IF JOB-CATEGORY MODIFIED
PERFORM SEARCH-JOB-CATEGORY-TABLE
IF NOT JOBTABLE
MESSAGE 'Job category is invalid. Please reenter.'
TEXT-ATTR = ERROR-TEXT-ATTR
FIELD-ATTR = ERROR-FIELD-ATTR
ELSE
PERFORM UPDATE-EMPLOYEE
MESSAGE 'Job category updated.' LEVEL INFORMATION
MOVE ZERO TO EMP# JOB-CATEGORY
TEXT-ATTR = NORMAL-TEXT-ATTR
FIELD-ATTR = NORMAL-FIELD-ATTR
END-IF
ELSE
MESSAGE 'Job category not modified.' LEVEL WARNING
JOB-CATEGORY = 0
TEXT-ATTR = NORMAL-TEXT-ATTR
FIELD-ATTR = NORMAL-FIELD-ATTR
END-IF
END-PROC
...
721
CA Easytrieve® Report Generator 11.6
Using a Menu
You can implement a menu application by coding multiple SCREEN activities within one program. This example shows
how you can create a menu that executes other SCREEN activities as child screens. When the child screen terminates
due to an EXIT, the parent screen executes until the next EXIT. This example also demonstrates the ability for the child
screen to send a message to be displayed on the parent screen:
FILE PERSNL INDEXED UPDATE WORKAREA 150
%PERSNL
DEFINE OPTION W 1 A
SCREEN NAME MENU UPPERCASE
KEY ENTER
KEY F3 NAME 'Exit' EXIT
TITLE 1 'Employee System Main Menu'
ROW 3 'Type an option and an employee number, then press Enter.'
ROW 5 'Option . . . . . .' OPTION VALUE ('V', 'E', 'X') +
ERROR 'Please type V, E, or X.'
ROW 7 COL 25 'V View employee'
ROW COL 25 'E Edit employee'
ROW 11 'Employee Number . .' EMP# ATTR MUSTENTER +
ERROR 'Please enter an employee name.'
INITIATION. PROC
EMP# = 0
END-PROC
AFTER-SCREEN. PROC
CASE OPTION
WHEN 'V'
EXECUTE VIEW-EMPLOYEE
WHEN 'E'
EXECUTE EDIT-EMPLOYEE
END-CASE
END-PROC
SCREEN NAME VIEW-EMPLOYEE
DEFAULT FIELD ATTR (TURQ PROTECT)
KEY F3 NAME 'Exit' EXIT
TITLE 'Employee View Utility'
ROW 3 'Number . .' EMP#
ROW 'Name . . .' EMPNAME
ROW 'SSN . . .' SSN
ROW 'Dept . . .' DEPT
ROW 'Phone . .' TELEPHONE
BEFORE-SCREEN. PROC
READ PERSNL KEY EMP# STATUS
IF NOT PERSNL
MESSAGE 'Employee number not found. Please re-enter.'
EXIT
END-IF
END-PROC
SCREEN NAME EDIT-EMPLOYEE COMMIT NOTERMINAL
KEY ENTER
KEY F3 NAME 'Exit' EXIT
TITLE 'Employee Edit Utility'
ROW 3 'Number . .' EMP#
722
CA Easytrieve® Report Generator 11.6
ROW 'Name . . .' EMPNAME
ROW 'SSN . . .' SSN
ROW 'Dept . . .' DEPT
ROW 'Phone . .' TELEPHONE
BEFORE-SCREEN. PROC
READ PERSNL KEY EMP# STATUS
IF NOT PERSNL
MESSAGE 'Employee number not found. Please re-enter.'
EXIT
END-IF
END-PROC
AFTER-SCREEN. PROC
WRITE PERSNL UPDATE
MESSAGE 'Employee updated successfully.' LEVEL INFORMATION
END-PROC
Providing Help Screens
You can provide help screens for your terminal users. The example in this section illustrates how you can display a help
screen from the main menu that was used in the previous example.
Follow these steps:
1. Add a KEY statement to the menu screen for F1. F1 is designated as an IMMEDIATE key. This lets the user request
help even though the data on the screen is in error. If IMMEDIATE is not specified, the user continues to receive
editing errors when they press F1, and can never display the help screen that is needed.
2. In the AFTER-SCREEN procedure, test for when F1 is pressed. When true, EXECUTE the screen activity, MENU-
HELP.
3. After the EXECUTE statement, code a RESHOW statement. RESHOW tells the product to redisplay the contents
of the screen as it was received when F1 was pressed. If the terminal user has entered data on the screen, then
requested help, RESHOW lets your program display the help screen and then redisplay the original screen after the
user exits the help screen. If REFRESH or GOTO SCREEN is used here, the user's data is lost.
4. Add the MENU-HELP SCREEN activity. Because the KEY statement for F3 automatically exits the screen and no
other processing is required, you do not need to code any screen procedures.
...
SCREEN NAME MENU UPPERCASE
KEY ENTER
KEY F1 NAME 'Help' IMMEDIATE
KEY F3 NAME 'Exit' EXIT
TITLE 1 'Employee System Main Menu'
ROW 3 'Type an option and an employee number, then press Enter.'
ROW 5 'Option . . . . . .' OPTION VALUE ('V', 'E', 'X') +
ERROR 'Please type V, E, or X.'
ROW 7 COL 25 'V View employee'
ROW COL 25 'E Edit employee'
ROW 11 'Employee Number . .' EMP# ATTR MUSTENTER +
ERROR 'Please enter an employee name.'
AFTER-SCREEN. PROC
IF KEY-PRESSED = F1
EXECUTE MENU-HELP
RESHOW
END-IF
723
CA Easytrieve® Report Generator 11.6
CASE OPTION
...
END-PROC
SCREEN NAME MENU-HELP
KEY F3 NAME 'Exit' EXIT
TITLE 'Employee Menu Help'
ROW 3 COL 10 'The Employee System Menu provides the ability to view'
ROW COL 10 'or edit an employee''s name, social security number,'
ROW COL 10 'department, or telephone number.'
ROW 7 COL 10 'Type V to view the employee data.'
ROW 9 COL 10 'Type E to edit the employee data.'
ROW 11 COL 10 'You must also type the employee''s number.'
Employee Menu Help
The Employee System Menu provides the ability to view
or edit an employee's name, social security number,
department, or telephone number.
Type V to view the employee data.
Type E to edit the employee data.
You must also type the employee's number.
F3=Exit
Field-specific Help
You can easily implement field-specific help screens by using code similar to the previous example combined with the IF
CURSOR test:
• The terminal user could press a function key while the cursor is in the field for which they want help.
• Test each field on your screen to determine the position of the cursor in an AFTER-SCREEN procedure.
• EXECUTE a specific SCREEN activity that displays help for the specific field.
Code the AFTER-SCREEN procedure as follows:
AFTER-SCREEN. PROC
IF KEY-PRESSED = F1
IF EMP# CURSOR
EXECUTE EMP#-HELP
ELSE-IF NAME CURSOR
EXECUTE NAME-HELP
ELSE-IF SSN CURSOR
EXECUTE SSN-HELP
724
CA Easytrieve® Report Generator 11.6
ELSE-IF TELEPHONE CURSOR
EXECUTE TELEPHONE-HELP
END-IF
RESHOW
END-IF
Windowed Screens
You can code pop-up windows or dialog boxes in your screen declarations. Windows are easily coded by executing one
screen activity from another in which the second screen is smaller than the first. The following example illustrates a pop-
up window in which the terminal user is asked to confirm an update request before the update is actually performed:
...
SCREEN NAME EMPLOYEE-UPDATE LINESIZE 80 ROWCOUNT 24
KEY F3 NAME 'Exit' EXIT
KEY F6 NAME 'Update'
TITLE 1 'EMPLOYEE RECORD'
ROW 3 'EMPLOYEE NUMBER' COL 24 EMP#
ROW 6 'SOCIAL SECURITY NUMBER' SSN
ROW 8 'LAST NAME' COL 24 NAME-LAST
ROW 10 'FIRST NAME' COL 24 NAME-FIRST
...
AFTER-SCREEN. PROC
EXECUTE CONFIRM-WINDOW
END-PROC
SCREEN NAME CONFIRM-WINDOW LINESIZE 40 ROWCOUNT 10 ROW 12 COL 20 +
BORDER (SINGLE)
KEY F6 NAME 'Update'
KEY F12 NAME 'Cancel' EXIT IMMEDIATE
TITLE 1 'Confirm Update'
ROW 3 'Are you sure?'
ROW 5 'Press F6 to update record'
ROW 6 'Press F12 to cancel update'
AFTER-SCREEN. PROC
MOVE PERSNL TO WORK-AREA
READ PERSNL KEY EMP#
MOVE WORK-AREA TO PERSNL
WRITE PERSNL UPDATE
MESSAGE 'Record updated.' LEVEL INFORMATION
EXIT
END-PROC
The first screen is defined as 24 rows by 80 columns. When the user presses F6 to update the record, a second SCREEN
activity, CONFIRM-WINDOW, is executed. CONFIRM-ACTIVITY is defined as 10 rows by 40 columns and the upper-left
corner is located in row 12 column 20. This second screen overlays the first and waits for the user to confirm the request
before updating the record. The screen appears as follows:
EMPLOYEE RECORD
EMPLOYEE NUMBER 00370
725
CA Easytrieve® Report Generator 11.6
SOCIAL SECURITY NUMBER 256-52-8737
LAST NAME NAGLE
FIRST NAME MARY
Confirm Update
Are you sure?
Press F6 to update record
Press F12 to cancel update
F6=Update F12=Cancel
F3=Exit F6=Update
Action Bar Pull-Downs
You can use an action bar with a pull-down menu in your application by invoking overlay screens. The following screen
has an action bar at the top of the screen:
EMPLOYEE RECORD
Options
+---------------+
EMPLOYEE NUMBER 00370
SOCIAL SECURITY NUMBER 256-52-8737
LAST NAME NAGLE
FIRST NAME MARY
...
F3=Exit F10=Pulldown options
When the user presses F10, the following pull-down menu is displayed:
EMPLOYEE RECORD
Options
726
CA Easytrieve® Report Generator 11.6
+---------------+
| Find>> |
| Print | 00370
| | BER 256-52-8737
| |
| F3=Exit | NAGLE
+---------------+
FIRST NAME MARY
...
F3=Exit F10=Pulldown options
The following program code is for this example:
FILE PERSNL F(150) INDEXED UPDATE
%PERSNL
ACTION-BAR S 7 A VALUE 'Options'
DASH-LINE S 17 A VALUE '+---------------+'
FIND-ACTION W 8 A VALUE 'Find>>' RESET
PRINT-ACTION W 8 A VALUE 'Print' RESET
SCREEN LINESIZE 80 ROWCOUNT 24
KEY F3 NAME 'Exit' EXIT
KEY F10 NAME 'Pulldown options'
TITLE 1 'EMPLOYEE RECORD'
ROW 3 COL 2 ACTION-BAR ATTR (WHITE PROTECT)
ROW 4 COL 2 DASH-LINE ATTR (WHITE PROTECT)
ROW 6 'EMPLOYEE NUMBER' COL 24 EMP#
...
AFTER-SCREEN. PROC
EXECUTE PULLDOWN-WINDOW
END-PROC
SCREEN NAME PULLDOWN-WINDOW LINESIZE 17 ROWCOUNT 7 ROW 4 COL 2 +
BORDER (SINGLE ATTR (WHITE))
KEY ENTER
KEY F3 NAME 'Exit' EXIT IMMEDIATE
ROW 1 FIND-ACTION
ROW 2 PRINT-ACTION
AFTER-SCREEN. PROC
IF FIND-ACTION CURSOR
EXECUTE FIND-WINDOW
ELSE
EXECUTE PRINT-JOB
END-IF
EXIT
END-PROC
SCREEN-NAME FIND-WINDOW LINESIZE 27 ROWCOUNT 10 ROW 4 COL 18 +
BORDER (SINGLE ATTR (WHITE))
KEY ENTER
727
CA Easytrieve® Report Generator 11.6
KEY F3 NAME 'Exit' EXIT IMMEDIATE
TITLE 'Find'
ROW 3
'Key. . .' EMP#
AFTER-SCREEN. PROC
READ PERSNL KEY EMP# STATUS
...
Macro Facility
The Macro Facility lets you easily duplicate often-repeated source statements in any program. This lets you tailor the
product to the programming standards of your installation.
This article contains the following information:
Even the most inexperienced programmer can effectively use CA Easytrieve Report Generator macros. The macro library
allows you to store the data definition statements of frequently used files using standardized data-naming conventions.
This section first discusses how to invoke macros by using the macro invocation statement. Next, it discusses the two
parts of a macro:
• The macro prototype statement
• The macro body
This section concludes with a description of Process Macros.
Macro Invocation Statement
The macro invocation statement consists of a macro name that is preceded by a percent (%) sign.
Syntax:
%macro-name [positional-parameters]...[keyword-parameters]
Parameters:
• %macro-name Supply the name of a previously stored macro that you want to invoke.
• positional-parameter Supply values of positional parameters in the macro. You must supply positional parameters
before any keyword parameters.
• keyword-parameter Supply both the keyword and its value in the macro.
Macro Library
Mainframe macro statements are stored and maintained in a macro library.
For the CA Easytrieve/Online environment, each macro library is connected by your system administrator. You can
enable or disable the libraries as required. Various file-types are supported for macro libraries. For more information, see
the Configuring section.
For CA Easytrieve Report Generator, only a PDS file-type is supported for macro libraries. For more information about
compiling using batch JCL, see the Using section.
Macro Library Security
You can protect your macro statements using an ACCESS record. For both CA Panvalet and VSAM macro storage
access methods, the ACCESS record can appear anywhere in the program prior to the retrieval of the macro, and
remains in effect until the next ACCESS record is encountered. The ACCESS record must be on a record by itself. CA
728
CA Easytrieve® Report Generator 11.6
Easytrieve Report Generator does not print the ACCESS record. For detailed information about creating and maintaining
macro libraries for use with CA Easytrieve/Online, see the CA Easytrieve/Online Administrator Guide, available
from Bookshelves and PDFs.
CA Panvalet
In addition to having the maintenance and backup capabilities that are provided by CA Panvalet, the product gives you the
ability to secure the macro against unauthorized access. Do this by using a security access code that can be applied to a
CA Panvalet member.
A security access code applies to an individual CA Panvalet library member. You must supply the security access code on
an ACCESS record before CA Easytrieve Report Generator can retrieve a secured member. The syntax is:
ACCESS 'eight-byte code'
VSAM
VSAM lets you protect the macro library by using VSAM password protection. Before CA Easytrieve Report Generator can
retrieve a macro from a secured library, you must supply the library password on an ACCESS record prior to the first
macro call. The syntax is:
ACCESS 'eight-byte password'
Macro Files
Non-mainframe macro statements are stored as files. Each macro is stored in a file that is named xxxxxxxx.mac
where xxxxxxxx is the macro name. For more information, see the Using section.
Invoke a Macro
To invoke a macro, code a macro invocation statement anywhere within the CA Easytrieve® Report Generator source
program. Macro invocation statements cause a series of statements to be retrieved from the macro library and included
as source statements in the CA Easytrieve® Report Generator program. The series of statements can be modified by
parameters supplied on the macro invocation statement.
Source Input Macro Library
macro-1
..
macro-1 invocation series of
... macro-1
macro-2 invocation statements
...
...
macro-2
series of
macro-2
statements
...
Produces
<easy> input
...
729
CA Easytrieve® Report Generator 11.6
macro-1
expanded
statements
...
macro-2
expanded
statements
...
Define Macros
A macro consists of three parts:
1. The macro prototype, which defines the parameters of the macro.
2. The macro body, which contains the CA Easytrieve Report Generator statements to be generated by a macro
invocation statement.
3. The optional macro termination command.
A macro name is the same as the member name in the macro storage library. A macro name is 1-8 characters in length.
The following code illustrates the parts of a macro:
PROTOTYPE
STATEMENT MACRO 2 NUMBER RESULT
**********************************************************
* *
* NAME: MACRO EXAMPLE *
* CALCULATE THE CUBE OF A NUMBER *
* *
BODY * FUNCTION: THIS MACRO CALCULATES THE CUBE OF A NUMBER.*
* *
**********************************************************
DEFINE CUBE_NUMBER_ S 6 N VALUE 000000
CUBE_NUMBER_ = &NUMBER * &NUMBER * &NUMBER
&RESULT = CUBE_NUMBER_
Optional
Termination MEND
Command
Macro Prototype Statement
The prototype statement must be the first statement of a macro. It optionally defines the parameters of the macro. You can
use both positional and keyword parameters.
Positional Parameters
Use positional parameters when a value is always required for the parameter each time the macro is invoked. Frequently
used parameters are often positional, because you need to code only the value of the parameter.
Keyword Parameters
Use keyword parameters as follows:
730
CA Easytrieve® Report Generator 11.6
• To help keep track of a large number of parameters
• To specify optionally-used parameters
• To specify a default value for parameters
Prototype Example -- No Substitution Parameters
Following are examples of macro prototype statements. The first example shows a macro with no substitution parameters:
MACRO
...
...
Prototype Example -- Only Positional Parameters
This example shows a macro with only positional parameters. The number of positional parameters is not indicated. You
could have coded the optional parameter as a 2.
MACRO POS1 POS2
...
...
Prototype Example -- Only Keyword Parameters
This example shows a macro with only keyword parameters. Here you code the number of positional parameters as zero.
This is a required parameter when you use keyword parameters.
MACRO 0 KEY1 VALUE1 KEY2 VALUE2
...
...
Prototype Example -- Positional and Keyword Parameters
This example shows a macro with positional and keyword parameters. Here you code the number of positional
parameters as a 1.
MACRO 1 POS1 KEY1 VALUE1
...
...
Macro Body
The macro body consists of a series of model and actual CA Easytrieve Report Generator statements. The model
statements contain one or more parameters that are replaced by the values of corresponding parameters on the prototype
statement.
Macro Termination Command
The optional macro termination command is used at the end of a macro. Its syntax is:
MEND
Process Macros
Macros are processed whenever a macro invocation statement appears in a CA Easytrieve® Report Generator program.
To designate a macro invocation, prefix a percent sign (%) to the macro name. Each macro invocation retrieves a copy
731
CA Easytrieve® Report Generator 11.6
of the macro from the library and, if necessary, replaces parameters with their corresponding values from the macro
invocation statement or the prototype statement.
Contents:
Parameter Substitution
The rules for substituting macro parameters are the basic rules of syntax and the following:
• You must specify positional parameter values on the macro invocation statement in the same order as they appear on
the prototype statement.
• CA Easytrieve® Report Generator gives the value of a null string to unsupplied positional parameter values. The
parameter is treated as nonexistent.
• You can specify keyword parameter values in any order on the macro invocation statement.
• CA Easytrieve® Report Generator gives unsupplied keyword parameter values the default value from the prototype
statement.
• Within the body of a macro, the ampersand (&) is the prefix concatenated to parameter substitution words. You must
spell parameter substitution words exactly the same their counterparts on the macro prototype, except for the leading
ampersand.
• Delimit parameter substitution words with a space or a period (.). Use a period when the substituted value is to be
concatenated with another word. CA Easytrieve® Report Generator deletes the period when the parameter is replaced
by its value.
• When you want to use an ampersand in the body of the macro, you must code two consecutive ampersands (&&).
• If you need to pass a hexadecimal literal as a parameter, you must pass it first as an alphanumeric literal ('X''xx''').
CA Easytrieve® Report Generator treats a macro invocation statement within the body of a macro (nested) as if it were
outside of the macro. You can use any number of nesting levels.
Examples
The following example illustrates positional parameter substitution. The second parameter value (' ') is supplied only to
maintain correct positioning for the third parameter ('FB (150 1800)').
Macro invocation Macro member = FILE
... MACRO NAME TYPE FORMAT
%FILE TESTIN ' ' + FILE &NAME &TYPE &FORMAT
'FB (150 1800)'
...
Produces:
...
FILE TESTIN FB (150 1800)
...
The next example illustrates keyword parameter substitution. The default value of a space for the second keyword entry
(TYPE) is an efficient way to code parameters that are used infrequently.
Macro invocation Macro member = FILE
MACRO 0 NAME FILEA +
%FILE NAME TESTIN + TYPE ' ' +
FORMAT 'V (1000)' + FORMAT 'FB(150 1800)'
732
CA Easytrieve® Report Generator 11.6
TYPE VIRTUAL
... FILE &NAME &TYPE &FORMAT
Produces:
...
FILE TESTIN VIRTUAL V (1000)
...
Parameter Substitution in a Macro
This example illustrates the use of the ampersand within a macro body statement and concatenated substitution words.
The extra ampersand and the periods used for concatenation are not part of the resulting statements.
Macro invocation Macro member = FILE
... MACRO NAME PREFIX
%FILE TESTIN NEW FILE &NAME
... &PREFIX.-SSN 1 9 N
&PREFIX.-MAIL 10 75 A, +
HEADING 'NAME && ADDRESS'
Produces:
...
FILE TESTIN
NEW-SSN 1 9 N
NEW-MAIL 10 75 A, +
HEADING 'NAME & ADDRESS'
...
In-stream Macros
You can also include macro statements in the source input to CA Easytrieve® Report Generator. This capability is
particularly useful for testing new macros prior to storing them in the macro library. When an in-stream macro has the
same name as a macro in the library, the in-stream macro is used.
In-stream macros are placed at the beginning of the source input prior to any other statements. Use an MSTART and an
MEND statement to bound each in-stream macro. The format of these statements is:
MSTART macro-name
MACRO 2 NUMBER RESULT
****************************************************************
* *
* NAME: MACRO EXAMPLE *
* CALCULATE THE CUBE OF A NUMBER *
* *
* FUNCTION: THIS MACRO CALCULATES THE CUBE OF A NUMBER. *
* *
****************************************************************
DEFINE CUBE_NUMBER_ S 6 N VALUE 00000
CUBE_NUMBER_ = &NUMBER * &NUMBER * &NUMBER
&RESULT = CUBE_NUMBER_
MEND
733
CA Easytrieve® Report Generator 11.6
Macro-name is the name of the macro. It can be from one to eight characters long. The first character must be alphabetic.
Examples
This example illustrates the use of in-stream macros:
Statements:
MSTART EXMACRO
MACRO 2 NUMBER RESULT
PUSH
SKIP 1
SKIP 1
LIST OFF
*****************************************************************
* *
* NAME: MACRO EXAMPLE *
* CALCULATE THE CUBE OF A NUMBER *
* *
* FUNCTION: THIS MACRO CALCULATES THE CUBE OF A NUMBER. *
* *
*****************************************************************
POP
SKIP 1
DEFINE CUBE_NUMBER_ S 6 N VALUE 000000
SKIP 1
CUBE_NUMBER_ = &NUMBER * &NUMBER * &NUMBER
&RESULT = CUBE_NUMBER_
SKIP 1
MEND
*
DEFINE CUBED_RESULT W 6 N VALUE 000000 MASK (J 'ZZZZZ9')
JOB INPUT NULL NAME MACROI
%EXMACRO 3 CUBED_RESULT
DISPLAY CUBED_RESULT
STOP
Produce:
27
SUPRA Interface Option
The SUPRA Interface lets you use CA Easytrieve Report Generator to retrieve information from a SUPRA database.
You invoke the SUPRA Interface as a preprocessor to CA Easytrieve Report Generator. The preprocessor acts as the
Relational Data Manipulation Language (RDML) compiler, taking the place of the COBOL or PL/I preprocessor. The
SUPRA preprocessor converts the RDML into CA Easytrieve Report Generator source statements. The result is an
expanded CA Easytrieve Report Generator program.
Next, you use CA Easytrieve Report Generator to compile and execute the expanded program which, in turn, accesses
the SUPRA data base.
734
CA Easytrieve® Report Generator 11.6
NOTE
You must use the interface with CA Easytrieve Report Generator Release 5 or higher.
How This Interface Works
The preprocessor locates the logical view in the SUPRA directory and then generates CA Easytrieve Report
Generator working storage definitions. It also converts SUPRA RDML statements in your CA Easytrieve Report
Generator program into the appropriate calls to the Relational Data Manager (RDM).
These working storage definitions and RDM calls let the expanded program retrieve data in the SUPRA database
when CA Easytrieve Report Generator compiles and executes it.
How and when the preprocessor writes and converts statements to the output file depends on the statement type:
• SUPRA statements are converted into CA Easytrieve Report Generator comments when written to the output file.
• Generated CA Easytrieve Report Generator statements are written to the output file following SUPRA statements.
• Non-SUPRA statements are written to the output file without being converted.
The interface prints a report of all input statements and any errors that are encountered during processing. Errors set
the CA Easytrieve Report Generator RETURN-CODE field to a value of 16 (OS/390 and z/OS only).
Prerequisite Knowledge
To use this interface effectively, you should have:
• Basic knowledge of the SUPRA Database Management System
• Working knowledge of CA Easytrieve Report Generator
• Knowledge of the views you want to access
Specifically, you should know:
• Your SUPRA user ID and password
• Names of the views you want to access
• Names of the attributes and keys that comprise those views
• How-to-use the fields that are contained in TIS-CONTROL to control access to the logical views
Related Publications
The following publications (not produced by CA Technologies) are either referenced in this section or are recommended
reading:
• SUPRA RDM COBOL
• PL/I Programmer's Guide
More Information:
For more information, see the following sections:
• SUPRA Interface Operation
• Diagnostic Messages
SUPRA Interface Operation
This article includes the following information:
735
CA Easytrieve® Report Generator 11.6
Overview of SUPRA Statements
You establish and control the interface between CA Easytrieve Report Generator and SUPRA with the following SUPRA
statements:
SUPRA Statements Description
GET Retrieves logical record from the logical view.
INCLUDE Indicates logical views that your program accesses.
ON ERROR Specifies automatic or controlled error handling. You can ask
SUPRA to handle all errors or name a CA Easytrieve Report
Generator procedure to handle error conditions set by the
Relational Data Manager (RDM).
RESET Restarts the task.
SIGN-OFF Signs you off the RDM system.
SIGN-ON Identifies you to the RDM.
Error Handling
The interface automatically generates the appropriate error-handling logic when preprocessing each SUPRA function call.
Also, you can issue the SUPRA ON ERROR statement to control error handling by yourself.
Error handling occurs as follows:
• For a SIGN-ON or SIGN-OFF statement:
– If the SUPRA Function Status Indicator (FSI) is an asterisk (*), the generated code recognizes the statement as
successfully executed.
– If the FSI is not an asterisk and SUPRA ON ERROR SYSTEM (the default) is in effect, the program displays an
error message and TIS-MESSAGE, performs a SUPRA RESET, and terminates the execution.
• For a Get statement:
– If the FSI is an asterisk (*) or an N, the program recognizes the statement as successfully executed. An N indicates
that an occurrence was not found.
– If the FSI is not an asterisk or an N and if SUPRA ON ERROR SYSTEM (the default) is in effect, the program
displays an error message and TIS-MESSAGE, performs a RESET, and terminates the execution.
NOTE
Because error handling does not occur when a "not found" (TIS-FSI="N") condition happens, it is your
responsibility to test for this condition and to specify the logic to follow when the condition occurs.
The generated code performs the error handling logic when you specify SYSTEM on a SUPRA ON ERROR statement.
However, you can specify your own procedure instead of SYSTEM. When this is the case, the preprocessor automatically
generates a CA Easytrieve Report Generator PERFORM of that procedure.
When you specify your own error handling procedure, it is your responsibility to handle the error conditions:
• From that point on in the source program, or
• Until you reset the error handling logic with a SUPRA ON ERROR SYSTEM statement
The advantages to specifying your own error handling procedures are that you can include error diagnosis and issue
customized error messages.
Example Program
The code that follows shows how SUPRA statements are incorporated into a CA Easytrieve Report Generator program.
This program accesses the logical records that are defined as CUSTOMER:
736
CA Easytrieve® Report Generator 11.6
SUPRA INCLUDE CUSTOMER
JOB INPUT NULL
SUPRA SIGN-ON 'SMITH'
SUPRA GET FIRST CUSTOMER
DO WHILE TIS-FSI NE 'N'
PRINT CUSTOMER-REPORT
SUPRA GET NEXT CUSTOMER
END-DO
SUPRA SIGN-OFF
STOP
*
REPORT CUSTOMER-REPORT
TITLE 'CUSTOMER REPORT'
LINE CUSTOMER-NO CUSTOMER-NAME CUSTOMER-BRANCH
As the example displays, relatively few statements are required to create a report of the data that is contained in a SUPRA
database. The SUPRA statements in this program are explained in the articles that follow.
Usage Rules
When coding SUPRA statements, follow these rules:
• In a single record, do not combine one SUPRA statement with another or with a CA Easytrieve Report
Generator statement or comment.
• Do not code SUPRA statements in a CA Easytrieve Report Generator macro.
• Code SUPRA statements only in the established statement area. This area is set during installation of the interface.
The default statement area is columns 1 through 72.
• Continue SUPRA statements with a plus (+) symbol.
• Code SUPRA INCLUDEs before any other SUPRA or CA Easytrieve Report Generator statement that references the
view or fields in the view. Generally, code SUPRA INCLUDEs in the program library section.
• When continuing CA Easytrieve Report Generator statements, do not break lines in such a way that the first word in
a source record is SUPRA. The preprocessor assumes that if the first word of the source record is SUPRA, the record
is a SUPRA statement and should be processed as such. This means that a line that begins with SUPRA that is not a
SUPRA statement causes an error during preprocessing.
For example, the preprocessor misinterprets the second record in the following TITLE statement:
TITLE 01 'THIS IS A +
SUPRA PROGRAM'
The preprocessor tries to interpret the second record as a SUPRA statement. But, because SUPRA PROGRAM is not
a valid SUPRA statement, the preprocessor flags the line as an error.
To prevent this from happening, break continued statements in such a way that SUPRA is not the first word in a source
record. Using the previous example, you could break the first line after the word IS, instead of after A. Thus, the first
word of the second record is A instead of SUPRA.
TITLE 01 'THIS IS +
A SUPRA PROGRAM'
Field Name Restrictions
When defining a field, do not give it the same name as that of a field that is generated by the interface. If you do so, an
error occurs when you execute the interface. See Generated Statements in SUPRA INCLUDE for a list of field names that
are generated by the preprocessor.
Also, do not name a field SUPRA. SUPRA is a SUPRA interface keyword.
737
CA Easytrieve® Report Generator 11.6
SUPRA Statement Details
SUPRA GET
Contents
The SUPRA GET statement retrieves the logical record from the logical view.
Syntax
[ {field-name...) }]
SUPRA GET [ NEXT ] view [ USING { }]
[ LAST ] [ { (literal... ) }]
[ SAME ]
[ FIRST ]
[ PRIOR ]
Parameters
[ NEXT ]
[ LAST ]
[ SAME ]
[ FIRST ]
[ PRIOR ]
This parameter indicates the order in which the logical records are retrieved from the database.
The default is NEXT.
view
View is the name of the logical view accessed. This name must be the same as the logical view name in the SUPRA
INCLUDE statement. If, however, you specify a user view name in the SUPRA INCLUDE statement, view must be the
same as that user view name.
[ { (field-name...) } ]
[ USING { } ]
[ { (literal...) } ]
Field-name or literal identifies the key values that access the logical view. The interface generates assignment statements
that place these values in the key fields defined in the SUPRA access set. The value order must correspond to the key
declaration order in the view's access set.
You can specify up to nine values. However, the number of values must be less than or equal to the number of keys in the
access set.
If you do not specify USING, the default is sequential (rather than random) access of the view.
SUPRA INCLUDE
The SUPRA INCLUDE statement generates the CA Easytrieve® Report Generator DEFINE statements and the
associated record and status data areas for a logical view. You can include a maximum of ten views in a CA Easytrieve®
Report Generator program.
738
CA Easytrieve® Report Generator 11.6
With this statement, you identify the view name as it is known by the Relational Data Manager (RDM). Also, you can
specify an alternate view name in the program to simplify the coding of unusually long view names.
Contents
Specify the optional parameters in the order shown below:
Syntax
SUPRA INCLUDE logical-view-name [PREFIX] +
[NAME user-view-name] SELECT (user-field...)]
Parameters
logical-view-name
Logical-view-name specifies the name by which the SUPRA directory knows the logical view.
• [PREFIX]
Prefixes the view's attribute names with the view name. You need only to include this parameter when several views
contain an attribute with the same name, or when a view and an attribute have the same name. When you do prefix
the field name, the field is qualified in the view.
Default: Generate a field-name that is the same as the SUPRA attribute name.
• [NAME user-view-name]
The user view name is a shorter or more meaningful name you can assign to the view. If you specify it, also use the
user view name in all of the view's SUPRA GET statements. If you specify it with PREFIX rather than the logical view
name, the preprocessor uses this name as the prefix for all generated DEFINE statements.
The logical view name is the default for field-name generation and for all references to the view.
• [SELECT (user-field...)]
With the optional SELECT parameter, you indicate which logical view fields the preprocessor generates. If you do not
specify the parameter, all fields for the view are generated.
User-field is the attribute name in the access set for the view. Enclose multiple fields in parentheses and separate each
with a blank. You can specify a maximum of 50 user fields.
By default, the preprocessor generates all attributes found in the view.
Generated Statements
TIS-CONTROL Statements
When the preprocessor encounters the first SUPRA INCLUDE statement, it defines a SUPRA communications area in S
working storage. This communications area, TIS-CONTROL, contains information about the operation and the status of
attempts to access the logical views.
The preprocessor generates the following DEFINE statements in the TIS-CONTROL communications area:
DEFINE TIS-CONTROL S 100 A
DEFINE TIS-OBJECT-NAME TIS-CONTROL 30 A
DEFINE TIS-OPERATION TIS-CONTROL +30 6 A
DEFINE TIS-ID TIS-OPERATION 2 A
DEFINE TIS-OPCODE TIS-OPERATION +2 1 A
DEFINE TIS-POSITION TIS-OPERATION +3 1 A
DEFINE TIS-MODE TIS-OPERATION +4 1 A
DEFINE TIS-KEYS TIS-OPERATION +5 1 A
DEFINE TIS-FSI TIS-CONTROL +36 1 A
DEFINE TIS-VSI TIS-CONTROL +37 1 A
739
CA Easytrieve® Report Generator 11.6
DEFINE TIS-FILLER TIS-CONTROL +38 2 A
DEFINE TIS-MESSAGE TIS-CONTROL +40 40 A
DEFINE TIS-PASSWORD TIS-CONTROL +80 8 A
DEFINE TIS-OPTIONS TIS-CONTROL +88 4 A
DEFINE TIS-CONTEXT TIS-CONTROL +92 4 A
DEFINE TIS-LVCONTEXT TIS-CONTROL +96 4 A
• Use the SUPRA Function Status Indicator (TIS-FSI) to test if a SUPRA GET function call was completed successfully.
• Use the Validity Status Indicator (TIS-VSI) to test the validity of the user view returned by a SUPRA GET.
• Use TIS-MESSAGE to display diagnostic information.
Consult your SUPRA RDM COBOL or PL/I Programmer's Guide for details regarding the use of TIS-CONTROL.
The preprocessor also generates fields to contain the date and time the preprocessor generated the CA Easytrieve®
Report Generator view definitions. The RDM uses these fields to detect any changes to the views after preprocessing.
The following date and time fields are generated:
DEFINE TIS-VER-DATA S 14 A
DEFINE TIS-DATE-STAMP TIS-VER-DATA 14 A
DEFINE TIS-DATE TIS-DATE-STAMP 8 A
DEFINE TIS-TIME TIS-DATE-STAMP +8 6 A
View Definition Statements
The preprocessor generates statements that define the fields that belong to the logical view. The interface defines these
fields in W working storage.
For each field, the preprocessor also generates an Attribute Status Indicator (ASI). You refer to these fields in other CA
Easytrieve® Report Generator statements.
The naming scheme for these fields is shown below:
Name Description
DEFINE LUV-view (1,2) Defines the entire view.
DEFINE view (1,2) Defines the view's data area.
DEFINE fieldname (1) Defines a field in the view.
DEFINE view-fieldname (2)
DEFINE ASI-view (1,2) Defines the view's ASI area.
DEFINE ASI-fieldname (1) Defines the field's Attribute Status Indicator (ASI).
DEFINE ASI-view-fieldname (2)
(1) Used when the PREFIX parameter is not specified.
(2) Used when the PREFIX parameter is specified.
In the table above, view is the logical view name you specify in the SUPRA INCLUDE statement, unless you override it
with a user view name. Fieldname is the attribute name found in the view access set.
You can test Attribute Status Indicators for the status of each field in the view. Consult your SUPRA RDM COBOL or PL/I
Programmer's Guide for complete details regarding the use of ASIs.
The preprocessor generates CA Easytrieve® Report Generator definitions based on the length, format, and number of
decimal places of the field's director entry. When possible, the definition matches the SUPRA definition.
740
CA Easytrieve® Report Generator 11.6
The following table summarizes the data format conversion:
SUPRA DATA FORMAT LENGTH CA Easytrieve® Report LENGTH
Generator DATA FORMAT
B(inary) 1, 4 B 1, 4
B 8 A(lphanumeric) 8
C(haracter) 1-32767 A 1-32767
F(loating point) 4, 8, 16 A 4, 8, 16
K(anji) 2-32766 K* 2-32766
P(acked decimal) 1-10 P 1-10
P 11-16 A 11-16
Z(oned decimal) 1-18 N(umeric) 1-18
* Supported in CA Easytrieve® Report Generator r5.3 and above.
Note: The length of the CA Easytrieve® Report Generator field is always the same as that of the SUPRA field.
You can use the first nine KEYs (unique or non-unique) found in the view's access set for keyed processing.
CA Easytrieve® Report Generator field names cannot be more than 40 characters in length. However, if you do not
specify a user view name, field names longer than 40 characters can be generated. This is particularly true when prefixing
is in effect.
For example, the name generated for an ASI for a field named CUSTOMER-PHONE-NO in a view named CUSTOMER-
ORDER-VIEW is:
ASI-CUSTOMER-ORDER-VIEW-CUSTOMER-PHONE-NO
This name is 41 characters in length and so it is flagged as an error.
If you specify user-view-name as CO, however, a valid name is generated, as shown here:
ASI-CO-CUSTOMER-PHONE-NO
When you have a 30-character field name, the addition of the four character ASI- prefix leaves only five characters for a
view name (six including the hyphen):
ASI-view-fieldname
• ASI = 4 characters (including hyphen)
• view = 6 characters (including hyphen)
• fieldname = 30 characters
• Total characters = 40
Using the user-view-name also simplifies the coding of other SUPRA and CA Easytrieve® Report Generator statements.
For example, you can retrieve the view CUSTOMER-ORDER-VIEW in either of the following ways:
SUPRA INCLUDE CUSTOMER-ORDER-VIEW
SUPRA GET CUSTOMER-ORDER-VIEW
or
741
CA Easytrieve® Report Generator 11.6
SUPRA INCLUDE CUSTOMER-ORDER-VIEW NAME CO
SUPRA GET CO
SUPRA ON ERROR
The SUPRA ON ERROR statement specifies how the program handles error conditions set by the Relational Data
Manager (RDM).
To control error handling yourself, identify a CA Easytrieve® Report Generator procedure name to perform when an
unexpected RDM error is encountered.
A SUPRA ON ERROR PERFORM statement overrides error handling (whether automatic or the result of previous
SUPRA ON ERROR statements) on all SUPRA function calls generated from that point on.
A SUPRA ON ERROR SYSTEM statement resets automatic error handling.
Contents
Syntax
{ PERFORM procedure-name }
SUPRA ON ERROR { }
{ SYSTEM }
Parameters
{ PERFORM procedure-name }
• {}
• { SYSTEM }
With procedure-name, you can specify the CA Easytrieve® Report Generator procedure to perform when an
unexpected error occurs. With SYSTEM, you specify that error handling is handled automatically.
If SUPRA ON ERROR is never specified, the default is automatic error handling (SYSTEM).
SUPRA RESET
The SUPRA RESET statement restarts a task.
See your SUPRA RDM COBOL or PL/I Programmer's Guide for details of the RESET function.
Syntax
SUPRA RESET
SUPRA SIGN-OFF
The SUPRA SIGN-OFF statement informs the RDM that the user no longer wants access to the system.
Syntax
SUPRA SIGN-OFF
742
CA Easytrieve® Report Generator 11.6
SUPRA SIGN-ON
The SUPRA SIGN-ON statement identifies a user to the RDM.
Contents
Syntax
SUPRA SIGN-ON user-name [password]
Parameters
user-name
User name is the user's name as defined in the directory. The user name can be an alphanumeric literal (enclosed in
apostrophes) or the name of a CA Easytrieve® Report Generator field that contains the user's name.
[password]
Password is the user's password as defined in the directory. This parameter is not required if the user was not assigned a
password. A password can be an alphanumeric literal (enclosed in apostrophes) or the name of a CA Easytrieve® Report
Generator field containing the password.
If you do not specify a password, a password is created that is composed of blanks.
For security reasons, you can accept a password from a JCL parameter rather than keep it in the CA Easytrieve® Report
Generator source.
Example JCL and SUPRA Statements
This section provides examples of the JCL and SUPRA statements needed to execute the SUPRA interface.
This article contains the following information:
Execution JCL
The following examples are of the JCL needed to execute the SUPRA preprocessor and the resulting CA Easytrieve
Report Generator program. The actual JCL you use depends on the way the two products were installed on your system.
Review your product and SUPRA documentation to determine the actual JCL to use.
z/OS JCL
This example is of the z/OS JCL required to execute a CA Easytrieve Report Generator program to access SUPRA.
Variable Description
ezt.library Name of the CA Easytrieve Report Generator load library.
supra.library(s) Names of the SUPRA load library.
csiparm.file Parameter for the directory files schema with read-only
environment.
expanded.program Expanded CA Easytrieve Report Generator program ready for
compilation and execution.
The z/OS JCL example is:
743
CA Easytrieve® Report Generator 11.6
//jobname JOB accounting.info
//*
//* EXECUTE THE <EASY> SUPRA PREPROCESSOR
//*
//EZTPSPRA EXEC PGM=EZTPSPRA
//STEPLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
// DD DISP=SHR,DSN=supra.library(s)
//SYSPRINT DD SYSOUT=A
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//CSIPARM DD DISP=SHR,DSN=csiparm.file
//* ADDITIONAL JCL FOR SUPRA DIRECTORY AND USER FILES
//PROGOUT DD DISP=(NEW,PASS),DSN=expanded.program,
// UNIT=SYSDA,DCB=(RECFM=F,LRECL=80),
// SPACE=(CYL,(1,1),RLSE),VOL=SER=volser
//SYSIN DD *
...<easy> source statements and SUPRA commands...
//*
//* COMPILE THE <EASY>
//*
//EZTCOMP EXEC PGM=EZTPA00,COND=(0,NE)
//STEPLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
//SYSPRINT DD SYSOUT=A
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//SYSIN DD DISP=(OLD,DELETE),DSN=expanded.program
//*
//* LINK-EDIT THE <EASY> PROGRAM
//*
//EZTLKED EXEC PGM=IEWL
//SYSPRINT DD SYSOUT=A
//SYSLIN DD DISP=(OLD,DELETE),DSN=&&SYSLIN
//SYSLIB DD DISP=SHR,DSN=your.ezt.product.loadlib
//SYSLMOD DD DISP=SHR,DSN=your.ezt.application.loadlib
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,5))
//*
//* EXECUTE your <easy> PROGRAM linked in step EZTLKED
//*
//EZTRUN EXEC PGM=your.linked.easytrieve.programname,COND=(0,NE)
//STEPLIB DD DISP=SHR,DSN=your.ezt.application.loadlib
// DD DISP=SHR,DSN=your.ezt.product.loadlib
// DD DISP=SHR,DSN=supra.loadlib(s)
//SYSPRINT DD SYSOUT=A
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
//CSIPARM DD DISP=SHR,DSN=csiparm.file
//* ADDITIONAL JCL FOR SUPRA DIRECTORY AND USER FILES
//
The first step, EZTPSPRA, is the SUPRA preprocessor. The CA Easytrieve Report Generator source statements, with the
SUPRA commands, are read from SYSIN.
The output file, PROGOUT, contains the non-SUPRA CA Easytrieve Report Generator statements and all statements
generated by the preprocessor as directed by SUPRA commands.
The system output file, SYSPRINT, contains a listing of the input file, and the status and error messages.
744
CA Easytrieve® Report Generator 11.6
The second step, EZTPLUS, demonstrates how the output file from the preprocessor, PROGOUT, is used as input to
the execution of CA Easytrieve Report Generator. Due to the COND parameter of the EXEC statement, this step does
not execute if the preprocessor encounters any errors. If the input to the first step contains a PARM LINK statement, you
could link edit the object resulting from this second step for later execution.
Overriding the Default Directory Schema
If you use multiple schemas, you can override the default directory schema (specified during the interface installation
process). You can only do this, however, if the OVERRIDE parameter in the EZTPSPRA installation routine is set to YES.
For more information on the OVERRIDE parameter in the EZTPSPRA installation, see Activate the SUPRA Interface
Option.
To override the default directory schema, simply use a PARM during the execution of the preprocessor, as shown below:
//EZTPSPRA EXEC PGM=EZTPSPRA,PARM='schema-name'
SUPRA Statements
The examples that follow show how to use SUPRA statements to perform these tasks:
• Rename a Logical View
• Access a Logical View by Key
• Supply Password from JCL PARM
• Control Error Handling
• Retrieve Multiple Views
• Extract Data from a View
Rename a Logical View
This example shows how to use the user view name parameter when coding SUPRA statements. With a user view name,
you can rename the logical view for the purposes of your program. The user view name can be more descriptive or easier
to code than the logical view name. With a user view name, you can also create names that can otherwise be too long.
In this example the logical view name, CUSTOMER-ORDER-VIEW, is assigned the user view name, CUSTVIEW:
SUPRA INCLUDE CUSTOMER-ORDER-VIEW NAME CUSTVIEW
JOB INPUT NULL
SUPRA SIGN-ON 'SMITH'
SUPRA GET CUSTVIEW
DO WHILE TIS-FSI = '*'
DISPLAY PART-NUMBER PART-COST
SUPRA GET CUSTVIEW
END-DO
STOP
Once you define the user view name in the INCLUDE statement, code the other SUPRA statements so they refer to the
user view name, not to the logical view name.
Access a Logical View by Key
his example shows how to access a logical view by its key. Here, the STOCK view has two keys, STOCK-BRANCH and
STOCK-PRODUCT. This program reads the view, using the keys supplied in a card file.
Note: The START and FINISH PROCedures control the SIGN-ON and SIGN-OFF:
FILE KEYFILE CARD
KEY-BRANCH 1 4 A
745
CA Easytrieve® Report Generator 11.6
KEY-PRODUCT 5 9 A
SUPRA INCLUDE STOCK
JOB INPUT KEYFILE START SIGNON FINISH SIGNOFF
SUPRA GET STOCK USING (KEY-BRANCH KEY-PRODUCT)
IF TIS-FSI = 'N'
DISPLAY 'NOT FOUND' +1 KEY-BRANCH +1 KEY-PRODUCT
ELSE
PRINT QNTY-REPORT
END-IF
*
SIGNON. PROC
SUPRA SIGN-ON 'SMITH'
END-PROC
*
SIGNOFF. PROC
SUPRA SIGN-OFF
DISPLAY 'END OF REPORT'
END-PROC
*
REPORT QNTY-REPORT
TITLE 'QUANTITY REPORT'
LINE STOCK-BRANCH STOCK-PRODUCT STOCK-QNTY
END
1241TL-4002-A
1241HD-7214-C
Supply Password from JCL PARM
The following example shows how to supply a SIGN-ON password without storing it in the source program. The field
specified on the PROGRAM USING parm is loaded with the data value specified on the JCL EXEC PARM parameter:
//STEP1 EXEC PGM=TSTPGM1,PARM='password'
...
PARM LINK(TSTPGM1 R)
SUPRA INCLUDE CUSTOMER
PASSWORD S 8 A
PARM-DATA S 8 A VALUE ' '
*
PROGRAM MAINRTN USING(PARM-DATA)
EXECUTE JOB1
*
JOB NAME JOB1 INPUT NULL START SIGNON FINISH SIGNOFF
SUPRA GET CUSTOMER
DO WHILE TIS-FSI = '*'
DISPLAY 'BRANCH=' CUSTOMER-BRANCH
SUPRA GET CUSTOMER
END-DO
STOP
*
SIGNON. PROC
IF PARM-DATA = SPACES . * PASSWORD WAS NOT SUPPLIED
DISPLAY '****** PASSWORD MISSING'
746
CA Easytrieve® Report Generator 11.6
ELSE
PASSWORD = PARM-DATA
END-IF
END-PROC
*
SIGNOFF. PROC
SUPRA SIGN-OFF
END-PROC
Control Error Handling
This example shows how to use the SUPRA ON ERROR statement to control the logic performed when an unexpected
error occurs during a call to the RDM:
SUPRA INCLUDE CUSTOMER
JOB INPUT NULL
SUPRA ON ERROR PERFORM ERROR-ON-SIGN-ON
SUPRA SIGN-ON 'SMITH'
SUPRA ON ERROR PERFORM ERROR-ON-GET
SUPRA GET CUSTOMER USING 'W45780'
IF TIS-GET = '*'
DISPLAY 'BRANCH=' CUSTOMER-BRANCH
ELSE
DISPLAY 'NOT FOUND
END-IF
SUPRA ON ERROR SYSTEM
SUPRA SIGN-OFF
STOP
*
ERROR-ON-SIGN-ON. PROC
DISPLAY '****** SIGN-ON ERROR'
DISPLAY 'FSI=' TIS-FSI ' MESSAGE=' TIS-MESSAGE
SUPRA RESET
RETURN-CODE = 16
STOP EXECUTE
END-PROC
*
ERROR-ON-GET. PROC
DISPLAY '****** GET ERROR'
DISPLAY 'FSI=' TIS-FSI ' MESSAGE=' TIS-MESSAGE
IF ASI-CUSTOMER-BRANCH = 'V'
DISPLAY 'BRANCH CONTAINS INVALID DATA'
END-IF
SUPRA RESET
RETURN-CODE = 16
STOP EXECUTE
END-PROC
This program reads one logical record from the view. If errors occur, special error handling procedures are performed.
These procedures can refer to fields in TIS-CONTROL to help diagnose the error.
NOTE
When you use a SUPRA ON ERROR PERFORM statement, no further automatic error handling is performed
until you reset it with the SYSTEM parameter.
747
CA Easytrieve® Report Generator 11.6
Also, when you specify a procedure name, it remains in effect until you specify another. For example, if you do not code a
SUPRA ON ERROR statement before the SUPRA SIGN-OFF, ERROR-ON-GET is performed during a SIGN-OFF error.
In the previous example:
• If an error occurs during the SIGN-ON, the ERROR-ON-SIGN-ON procedure is performed.
• If an error occurs during the GET, the ERROR-ON-GET procedure is performed.
• If an error occurs during the SIGN-OFF, automatic error handling is performed. because the SYSTEM parameter is
included in the SUPRA ON ERROR statement.
Retrieve Multiple Views
This example shows how you can access multiple views in one CA Easytrieve Report Generator job activity. For each
INVOICE view record, the INVOICE-CUSTOMER field is used as the key to retrieve the CUSTOMER view record. If the
CUSTOMER record is found, a report is printed of the invoice and the customer's name and address:
SUPRA INCLUDE INVOICE
SUPRA INCLUDE CUSTOMER
JOB INPUT NULL
SUPRA SIGN-ON 'SMITH' 'XYZPASS'
SUPRA GET INVOICE
DO WHILE TIS-FSI = '*'
SUPRA GET CUSTOMER USING INVOICE-CUSTOMER
IF TIS-FSI = '*'
PRINT RPT
END-IF
SUPRA GET NEXT INVOICE
END-DO
SUPRA SIGN-OFF
STOP
*
REPORT RPT
TITLE 'OUTSTANDING INVOICES'
LINE 1 INVOICE-NO INVOICE-DATE CUSTOMER-NAME
LINE 2 POS 3 CUSTOMER-ADDR
LINE 3 POS 3 CUSTOMER-CITY
LINE 4 POS 3 CUSTOMER-STATE
Extract Data from a View
This example shows how to retrieve a view and extract the data portion to a non-database file for further processing:
SUPRA INCLUDE CUSTOMER
FILE CUSTFILE F(250)
CUSTREC 1 250 A
JOB INPUT NULL
SUPRA SIGN-ON 'SMITH'
SUPRA GET FIRST CUSTOMER
DO WHILE TIS-FSI = '*'
MOVE CUSTOMER TO CUSTREC
PUT CUSTFILE
SUPRA GET NEXT CUSTOMER
END-DO
SUPRA SIGN-OFF
STOP
748
CA Easytrieve® Report Generator 11.6
When each CUSTOMER record is retrieved, the view's data area, defined as CUSTOMER, is moved and written to the
sequential output file, CUSTFILE.
See Generated Statements in SUPRA INCLUDE for details regarding the naming convention to use when you define the
various portions of the INCLUDEd view.
Note: When you use a SUPRA ON ERROR PERFORM statement, no further automatic error handling is performed until
you reset it with the SYSTEM parameter.
TOTAL Interface Option
CA Easytrieve Report Generator, like other languages, communicates with TOTAL through the DATBAS module. The
CALL statement is the linkage vehicle. This section describes a series of macro statements that facilitate the generation of
the appropriate calls to TOTAL.
The CALL statements are for a routine named EZTPDBAS. EZTPDBAS is created by link-editing routines that are
supplied with TOTAL.
• For OS/390 and z/OS, EZTPDBAS is created by supplying an alias for DATBAS.
• For VSE, EZTPDBAS is a user-defined version of DATBAS that is loaded into EXITSTR space.
To use this interface, you should have a basic knowledge of TOTAL and of the databases to process.
The examples in this section use the test database that is supplied with TOTAL. For a detailed description of how to tailor
DATBAS to your environment, refer to the TOTAL Application Programmer's Guide.
The macros are based on reference to the TOTAL communications area. This area is generated by the macro statement
%TOTALCOM, which must be defined in the library section of any program that uses the TOTAL macros.
This article contains the following information:
Installation
The installation procedures for the TOTAL Interface Option are described in the Installing section.
Communications Area
%TOTALCOM
The %TOTALCOM macro statement defines common data areas necessary for communication with TOTAL. Each of the
other macros reference one or more of the areas that are defined here.
Syntax
%TOTALCOM TASK literal-1 +
END literal-2 +
REALM literal-3
• literal-1
Literal-1 sets the value of an eight-character field (TOTALTASK) used by %SINON and %SINOF. The default is
EASYPLUS.
• literal-2
Literal-2 sets the value for the list delimiter (TOTALEND). Acceptable values are END and RLSE. The default is RLSE.
• literal-3
749
CA Easytrieve® Report Generator 11.6
Literal-3 sets the size of the REALM= parameter (TOTALREALM) used by %OPENX and %CLOSX. The value of
literal-3 is established by the formula:
10 + (#files x 12)
where #files is the maximum number of files opened or closed on any single %OPENX or %CLOSX statement. The
default is 130 (for a maximum of 10 files).
The fields that are defined by %TOTALCOM are:
TOTALCOM W 49 A. * COMMUNICATIONS AREA
TOTALDBMOD TOTALCOM 8 A. * DBMOD NAME
TOTALTASK TOTALCOM +8 8 A, VALUE '&TASK'
TOTALEND TOTALCOM +16 4 A, VALUE '&END'
TOTALSTATUS TOTALCOM +20 4 A, VALUE '****'
TOTALFILE TOTALCOM +24 4 A. * FILE NAME
TOTALREF TOTALCOM +28 4 A. * LKXX
TOTALLINK TOTALCOM +32 8 A. * LINKPATH
TOTALCMND TOTALCOM +40 5 A. * COMMAND
TOTALENDP TOTALCOM +45 4 A, VALUE 'END.'
*
* REALM=FILE/MODE/STATUS...END.
TOTALREALM W &REALM A, VALUE 'REALM='
TOTALREALMF TOTALREALM +6 4 A, INDEX REALMINDEX
TOTALREALMM TOTALREALM +10 4 A, INDEX REALMINDEX
TOTALREALMS TOTALREALM +14 4 A, INDEX REALMINDEX
*
%OPENX Macro-Generated Statements
The generated statements are:
TOTALCMND = 'OPENX'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALREALM, +
TOTALEND)
REALMINDEX = 0
DO WHILE TOTALREALMF NE TOTALENDP
IF TOTALREALMS NE '****'
DISPLAY 'OPEN ERROR FOR', +
TOTALREALMF, ' ', +
TOTALREALMS
TOTALSTATUS = 'OPEN'
END-IF
REALMINDEX = REALMINDEX + 12
END-DO
IF TOTALSTATUS = 'OPEN'
STOP
END-IF
REALMINDEX = 0
750
CA Easytrieve® Report Generator 11.6
If any of the files that are named in TOTALREALM fail to open properly, the name and status of the files are printed and
execution of the job is stopped.
TOTAL Macro Facility
%ADDM - Add Master (TOTAL)
Contents
Use the %ADDM macro to logically add a record to a master file.
Syntax
%ADDM literal-1 field-1 field-2 field-3
• literal-1
Four-character name of the file to which the record is added.
• field-1
Name of the field containing the record's control key.
• field-2
Name of the field containing the data list of elements to add.
• field-3
Name of the field containing the data record to add to the file.
%ADDM Macro-Generated Statements
The generated statements are:
TOTALCMND = 'ADD-M'
TOTALFILE = 'literal-1'
CALL EZTPDBAS, +
USING(TOTAL CMND, +
TOTALSTATUS, +
TOTAL FILE, +
field-1, +
field-2, +
field-3, +
TOTALEND)
%ADDV - Add Variable (TOTAL)
Contents
Use the %ADDV macro to logically add records to a variable file.
Syntax
%ADDV literal-1 literal-2 +
field-1 literal-3 +
field-2 field-3 field-4
• literal-1
751
CA Easytrieve® Report Generator 11.6
Determines the specific type of variable record addition. Valid values for literal-1 are:
Valid Value Description
ADDVA Add variable after.
ADDVB Add variable before.
ADDVC Add variable continue.
ADDVR Add variable replace.
• literal-2
Four-character name of the file to which the record is added.
• field-1
Name of a field containing the four-character reference, for example, LK01.
• literal-3
Eight-character linkpath, that is, ABCDLK01.
• field-2
Name of the field containing the record's control key.
• field-3
Name of the field containing the data list of elements to add.
• field-4
Name of the field containing the data record to add to the file.
%ADDV Macro-Generated Statements
The generated statements are:
TOTALCMND = 'literal-1'
TOTALFILE = 'literal-2'
TOTALREF = field-1
TOTALLINK = 'literal-3'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
TOTALREF, +
TOTALLINK, +
field-2, +
field-3, +
field-4, +
TOTALEND)
field-1 = TOTALREF
%CBLCNVRT
Converts COBOL data definitions to their CA Easytrieve® Report Generator equivalent.
The following are used internally by the CBLCNVRT macro: CBLDI122, CBLDI212, CBLDI320, CBLDI341, CBLDII,
CBLDII12, CBLDII13, CBLDMPII, CBLDMPVS, CBLDVS, CBLII122, CBLII212, CBLII320, CBLII341, CBLIII, CBLIII12,
CBLIII13, CBLINTII, CBLINTVS, CBLIVS, CBLSI122, CBLSI212, CBLSI320, CBLSI341, CBLSII, CBLSII12, CBLSII13,
CBLSRCII, CBLSRCVS, and CBLSVS.
752
CA Easytrieve® Report Generator 11.6
NOTE
For more information about using this macro, see the CBLCNVRD member in hlq.CBAAMAC. For releases
before Release 11.6, see the CBLCNVRD member in hlq.CAIMAC.
%CLOSX - Close TOTAL File
Contents
Use the %CLOSX macro to close one or more files. Field TOTALREALM must be set with the correct realm value before
the execution of %CLOSX.
Syntax
%CLOSX
%CLOSX Macro-Generated Statements
The generated statements are:
TOTALREALMM = 'COMP'
TOTALCMND = 'CLOSX'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALREALM, +
TOTALEND)
%CONCAT
Contents
Takes two fields and concatenates them into one, with variable spacing between the fields. The result is placed in the first
field.
Syntax
%CONCAT field-1 space field-2
• field-1
Name of the original field and where the concatenated result will be returned.
• space
Amount of blank space desired between field-1 and field-2.
• field-2
Field to be concatenated to field-1.
%CONVAE
Contents
Converts ASCII alphanumeric characters to their EBCDIC equivalent. CONVAE is an inline routine that you can use with
other CA Easytrieve® Report Generator routines. The inline design of CONVAE reduces execution time and reduces
753
CA Easytrieve® Report Generator 11.6
requirements for temporary or permanent storage space. You can also use CONVAE to create a permanent file of
converted data.
CONVAE and CONVEA use the CV and CVDBNAME macros internally.
Syntax
%CONVAE [DBFILE] [STARTPOS identifier] [LENGTH value]
• [DBFILE]
Specify this optional parameter only for database use of CONVAE. Specify only the literal DBFILE, not the name of the
active input file.
• [STARTPOS identifier]
This optional parameter specifies the starting position for the conversion process. The identifier must be a previously
defined field.
Conversion takes place in the active input file starting at the position defined by STARTPOS and continuing for the
length specified by the length parameter.
The default value for STARTPOS is the first byte of the active input file. This means that when using the default value
the conversion begins with the first byte of the active input file.
The requirements for specifying STARTPOS are different when you use CONVAE in a database application. In this
case the STARTPOS parameter is no longer optional.it is a required parameter.
• [LENGTH value]
This optional parameter specifies the length, or number of bytes, that you want to convert. The conversion starts at the
position that STARTPOS defines and continues for the length that the LENGTH parameter specifies. The default value
is the record length of the current record. A valid value is an actual numeric value or the name of a field containing a
numeric value. The value that you specify for LENGTH plus the numeric value of STARTPOS must be less than or
equal to the length of the current record.
%CONVEA
Contents
The CONVEA macro converts EBCDIC alphanumeric characters to their ASCII equivalent. CONVEA is an inline routine
that you can use with other CA Easytrieve® Report Generator routines. The inline design of CONVEA reduces execution
time and reduces requirements for temporary or permanent storage space. You can also use CONVEA to create a
permanent file of converted data.
CONVAE and CONVEA use the CV and CVDBNAME macros internally.
Syntax
%CONVEA [DBFILE] [STARTPOS identifier] [LENGTH value]
• [DBFILE]
Specify this optional parameter only for database use of CONVEA. Specify only the literal DBFILE, not the name of the
active input file.
• [STARTPOS identifier]
This optional parameter specifies the starting position for the conversion process. The identifier must be a previously
defined field.
Conversion takes place in the active input file starting at the position defined by STARTPOS and continuing for the
length specified by the length parameter means that when using the default value the conversion begins with the first
byte of the active input file.
754
CA Easytrieve® Report Generator 11.6
The requirements for specifying STARTPOS are different when you use CONVEA in a database application. In this
case the STARTPOS parameter is no longer optional, it is a required parameter.
• [LENGTH value]
This optional parameter specifies the length, or number of bytes, that you want to convert. The conversion starts at the
position that STARTPOS defines and continues for the length that the LENGTH parameter specifies. The default value
is the record length of the current record. A valid value is an actual numeric value or the name of a field containing a
numeric value. The value that you specify for LENGTH plus the numeric value of STARTPOS must be less than or
equal to the length of the current record.
%DATECALC
Contents
The DATECALC macro adds or subtracts a given number of days from the date specified in a field and writes the resulting
date to a second field.
Syntax
%DATECALC [date-1] [format-1] {PLUS|MINUS} [days] [date-2] [format-2] [THRESHOLD]
• [date-1]
Specify the name of the field containing the date to which a given number of days are to be added or subtracted. The
date in this field must be in the format specified by format1. A valid name is any previously defined field.
• [format-1]
Specify the format of the date1 field. This is a literal description of pairs of letters. The letters indicate positions as
follows:
MM = month
DD = day
YY = year
CC = century
The value of date1 is not checked for a valid date with format1. However, CC always maintains the value specified
in accordance with the THRESHOLD parameter. If you want date validation, use the DATEVAL routine before using
DATECALC. The only valid Julian format is YYDDD. The following are some, but not all, of the valid formats:
MMDDYY
MMDDCCYY
YYMMDD
YYDDD (Julian)
• [PLUS|MINUS]
Specify whether the value of the days parameter is added to (PLUS) or subtracted from (MINUS) date1.
NOTE
DATECALC performs an arithmetic calculation. If you specify the PLUS keyword, and the value of the days is
negative, the value is subtracted.Conversely, if you specify MINUS, and days is negative, the value is added.
• [days]
Specify a numeric literal or a field that contains the value to be added or subtracted.
• [date-2]
Specify the name of the field to which the resulting date is written. The date is written using the format specified by the
format2 parameter. A valid name is any previously defined field.
• [format-2]
Specify the format for date2.
• [THRESHOLD]
Supplied in the century format (CC) in the date. Specify a value that establishes the upper end of a one-hundred-year
range in the 20th and 21st centuries used to control the CC portion of generated dates.
755
CA Easytrieve® Report Generator 11.6
General rules for specifying THRESHOLD values are:
– The THRESHOLD value is ignored if you provide a century value (CC).
– If the dates to be generated do not exceed the year 2000, specify the THRESHOLD default value of 0. This causes
all dates to have a range of 1901 through 2000.
– If the dates exceed the year 2000, choose a THRESHOLD high enough to generate correct dates in the 21st
century, but not so high as to convert dates from the 20th century to the 21st century.
– When dates to be generated do not involve calculations for century, specify the THRESHOLD default value of 0.
– Valid values for THRESHOLD are 0 through 99.
For example, if THRESHOLD is 40, the upper boundary of the range is set to 2040, and the lower boundary is 1941.
When converting YY to CCYY, each year is assigned a two-position century based on the range established by
THRESHOLD. In this example, if year is 52, century is 19; if year is 21, century is 20.
It is important that the THRESHOLD value be correct for the range of dates to be generated. For example, if
DATECALC is invoked to process dates between the years 1949 and 1952, and THRESHOLD is 50, the years 1949
and 1950 become 2049 and 2050, while the years 1951 and 1952 remain 1951 and 1952. In this respect, the YY
(year) portion of the date controls the CC (century) portion in accordance with the THRESHOLD value.
%DATECONV
Contents
The DATECONV macro converts a date in one format to any other date format. For example, you can convert month-
day-year to year-month-day, Julian to Gregorian, and similar date conversions. Using non-numeric data or a zero for date
fields results in an error.
Syntax
%DATECONV [date-1] [format-1] [date-2] [format-2] [THRESHOLD]
• [date-1]
Specify the name of the field containing the date to be converted. The date in this field must be in the format specified
by format1. The name of any previously defined numeric field is valid.
• [format-1]
Specify the format of the date1 field. Format1 is a literal description of pairs of letters. The letters indicate positions as
follows:
MM = month
DD = day
YY = year
CC = century
The value of date1 is not checked for a valid date with the specified format. However, CC always maintains the value
specified in accordance with the THRESHOLD parameter. If you want date validation, use the DATEVAL routine before
using DATECONV.
The following are some, but not all, of the valid formats:
MMDDYY
MMDDCCYY
YYMMDD
YYDDD (Julian)
NOTE
For non-Julian dates, format1 must include the values MM, DD, and YY (in any order). The only valid Julian
format is YYDDD.
• [date-2]
756
CA Easytrieve® Report Generator 11.6
Specify the name of the field to which the converted date will be written. The date is written in the format specified by
format2. A valid name is any previously defined field.
• [format-2]
Specify the format for the date-2 field.
• [THRESHOLD]
The THRESHOLD parameter is used to determine the century value if it is not supplied in the century format (CC) in
the date. Specify a value that establishes the upper end of a one-hundred-year range in the 20th and 21st centuries
used to control the CC portion of generated dates.
General rules for specifying THRESHOLD values are:
– The THRESHOLD value is ignored if you provide a century value (CC).
– If the dates to be generated do not exceed the year 2000, specify the THRESHOLD default value of 0. This causes
all dates to have a range of 1901 through 2000.
– If the dates exceed the year 2000, choose a THRESHOLD high enough to generate correct dates in the 21st
century, but not so high as to convert dates from the 20th century to the 21st century.
– When dates to be generated do not involve calculations for century, specify the THRESHOLD default value of 0.
– Valid values for THRESHOLD are 0 through 99.
For example, if THRESHOLD is 40, the upper boundary of the range is set to 2040, and the lower boundary is 1941.
When converting YY to CCYY, each year is assigned a two-position century based on the range established by
THRESHOLD. In this example, if year is 52, century is 19; if year is 21, century is 20.
It is important that the THRESHOLD value be correct for the range of dates to be generated. For example, if
DATECONV is invoked to process dates between the years 1949 and 1952, and THRESHOLD is 50, the years 1949
and 1950 become 2049 and 2050, while the years 1951 and 1952 remain 1951 and 1952. In this respect, the YY
(year) portion of the date controls the CC (century) portion in accordance with the THRESHOLD value.
%DATEVAL
Contents
The DATEVAL macro examines the content of a specified date field for a valid date in accordance with a specified date
format. If the date field contains a valid date, the field DATEVAL-FLAG is set to the value YES. If the date field is invalid,
the DATEVAL-FLAG is set to the value NO.
Syntax
%DATEVAL [field] [format] [THRESHOLD]
• [field]
Specify the name of the field that contains the date being validated. Valid names include any previously defined
numeric field.
• [format]
The format for the comparison is a literal description of pairs of letters. The letters indicate positions as follows:
MM = month
DD = day
YY = year
CC = century
You can specify the letter pairs in any order. YY must be specified whenever you specify CC. The only valid Julian
format is YYDDD. The following are some, but not all, of the valid formats:
MMDDYY
MMDDCCYY
YYMMDD
YYDDD (Julian)
• [THRESHOLD]
757
CA Easytrieve® Report Generator 11.6
The THRESHOLD parameter is used to determine the century value if it is not supplied in the century format (CC) in
the date. Specify a value that establishes the upper end of a one-hundred-year range in the 20th and 21st centuries
used to control the CC portion of generated dates.
General rules for specifying THRESHOLD values are:
– The THRESHOLD value is ignored if you provide a century value (CC).
– If the dates to be generated do not exceed the year 2000, specify the THRESHOLD default value of 0. This causes
all dates to have a range of 1901 through 2000.
– If the dates exceed the year 2000, choose a THRESHOLD high enough to generate correct dates in the 21st
century, but not so high as to convert dates from the 20th century to the 21st century.
– When dates to be generated do not involve calculations for century, specify the THRESHOLD default value of 0.
– Valid values for THRESHOLD are 0 through 99.
For example, if THRESHOLD is 40, the upper boundary of the range is set to 2040, and the lower boundary is 1941.
When converting YY to CCYY, each year is assigned a two-position century based on the range established by
THRESHOLD. In this example, if year is 52, century is 19; if year is 21, century is 20.
It is important that the THRESHOLD value be correct for the range of dates to be generated. For example, if DATEVAL
is invoked to process dates between the years 1949 and 1952, and THRESHOLD is 50, the years 1949 and 1950
become 2049 and 2050, while the years 1951 and 1952 remain 1951 and 1952. In this respect, the YY (year) portion
of the date controls the CC (century) portion in accordance with the THRESHOLD value.
%DELM
Contents
Use the %DELM macro to logically delete the master record which is identified by the control key.
Syntax
%DELM literal-1 field-1 +
field-2 field-3
• literal-1
Four-character name of the file from which the record is deleted.
• field-1
Name of the field containing the record's control key.
• field-2
Name of the field containing the data list of elements to delete.
• field-3
Name of the field containing the file's data.
%DELM Macro-Generated Statements
The generated statements are:
TOTALCMND = 'DEL-M'
TOTALFILE = 'literal-1'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
field-1, +
field-2, +
field-3, +
758
CA Easytrieve® Report Generator 11.6
TOTALEND)
%DELVD
Contents
Use the %DELVD macro to logically delete the variable record identified by its reference point.
Syntax
%DELVD literal-1 field-1 +
literal-2 field-2 +
field-3 field-4
• literal-1
Four-character name of the file from which the record is deleted.
• field-1
Name of a field containing the four-character reference point.
• literal-2
Eight-character linkpath.
• field-2
Name of the field containing the record's control key.
• field-3
Name of the field containing the data list of elements to delete.
• field-4
Name of the field containing the file's data.
%DELVD Macro-Generated Statements
The generated statements are:
TOTALCMND = 'DELVD'
TOTALFILE = 'literal-1'
TOTALREF = field-1
TOTALLINK = 'literal-2'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
TOTALREF, +
TOTALLINK, +
field-2, +
field-3, +
field-4, +
TOTALEND)
field-1 = TOTALREF
%DFNTOTF
Contents
Use the %DFNTOTF macro to initialize the REALM= (TOTALREALM) values.
759
CA Easytrieve® Report Generator 11.6
Syntax
%DFNTOFT literal-1 literal-2
• literal-1
Four-character name of the file.
• literal-2
File's mode.
%DFNTOTF Macro-Generated Statements
The generated statements are:
TOTALREALMF = 'literal-1'
TOTALREALMM = 'literal-2'
TOTALREALMS = '****'
REALMINDEX = REALMINDEX + 12
TOTALREALMK = TOTALENDP
%EZSSID
Contents
An Assembler macro which generates:
• A table used to map an SSID to a PAN/SQL module to invoke for that SSID.
• An Assembler DSECT of the above table.
Syntax
%EZSSID SSID='ssid' PSMOD='psmod' DSECT={YES|NO}
• [ssid]
This is the DB2 SSID used to identify the correct PAN/SQL load module. It must be a value whose length is less-than-
or-equal 8.
• [psmod]
This is the 1-character suffux of PAN/SQL load modules to invoke for the above SSID. It must be set to either a '2', '3',
'4', or '5'.
• [dsect]
If YES is specified for this parm, the macro generates just the DSECT of the SSID-PAN/SQL Table that is built when
DSECT is NOT specified. The intended user of the DSECT parm is the Easytreive runtime.
%EZTINI
Contents
An Assembler macro which generates the Assembler constants that are assembled into the EZTINI load module. Also
generate a DSECT of the EZTINI contents.
Syntax
%EZTINI EZOPTBL='ezoptbl' DSECT={YES|NO}
• [ezoptbl]
760
CA Easytrieve® Report Generator 11.6
DSN of CA Easytrieve® Report Generator options table. This indicates that the macro should generate the EZOPTBL
entry in the EZTINI file.
• [DSECT]
Indicates whether or not to generate the EZTINI DSECT.
%FINDX
Contents
Use the %FINDX macro to search a file and retrieve records that satisfy the search argument.
Syntax
%FINDX literal-1 field-1 field-2 +
field-3 field-4
• literal-1
Four-character name of the file to search.
• field-1
Name of the field containing the position controlling qualifier data.
• field-2
Name of the field containing the argument list.
• field-3
Name of the field containing the data list of elements to retrieve.
• field-4
Name of the field into which the data is to retrieve.
%FINDX Macro-Generated Statements
The generated statements are:
TOTALCMND = 'FINDX'
TOTALFILE = 'literal-1'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
field-1, +
field-2, +
field-3, +
field-4, +
TOTALEND)
%GETCALEN
Contents
Converts an integer into a date in the format CCYYMMDD.
Syntax
%GETCALEN [date-in] [date-out]
761
CA Easytrieve® Report Generator 11.6
• [date-in]
Integer value that represents a Julian day number.
• [date-out]
Returned date in the format CCYYMMDD.
%GETJULI
Contents
Converts a date in the format CCYYMMDD to an integer representing a Julian day number.
Syntax
%GETJULI [date-in] [date-out]
• [date-in]
Calendar date in the format CCYYMMDD.
• [date-out]
Returned integer value that represents a Julian day number.
%RDNXT
Contents
The %RDNXT macro serially retrieves either master or variable file records.
Syntax
%RDNXT literal-1 field-1 +
field-2 field-3
• literal-1
Four-character name of the file to read.
• field-1
Name of the field containing the position controlling qualifier data.
• field-2
Name of the field containing the argument list.
• field-3
Name of the field into which the data is retrieved.
%RDNXT Macro-Generated Statements
The generated statements are:
TOTALCMND = 'RDNXT'
TOTALFILE = 'literal-1'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
field-1, +
field-2, +
field-3, +
762
CA Easytrieve® Report Generator 11.6
TOTALEND)
%OPENX
Contents
Use the %OPENX macro to open one or more files. Field TOTALREALM must be set with the correct realm value before
the execution of %OPENX.
Syntax
%OPENX
%READD
Contents
Use the %READD macro to directly retrieve the record identified by the reference point.
Syntax
%READD literal-1 field-1 +
literal-2 field-2 +
field-3 field-4
• literal-1
Four-character name of the file from which the record is retrieved.
• field-1
Name of a field containing the four-character reference point.
• literal-2
Eight-character linkpath.
• field-2
Name of the field containing the record's control key.
• field-3
Name of the field containing the data list of elements to retrieve.
• field-4
Name of the field to receive the data.
%READD Macro-Generated Statements
The generated statements are:
TOTALCMND = 'READD'
TOTALFILE = 'literal-1'
TOTALREF = field-1
TOTALLINK = 'literal-2'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
TOTALREF, +
TOTALLINK, +
763
CA Easytrieve® Report Generator 11.6
field-2, +
field-3, +
field-4, +
TOTALEND)
field-1 = TOTALREF
%READM
Contents
Use the %READM macro to retrieve the master record identified by the control key.
Syntax
%READM literal-1 field-1 +
field-2 field-3
• literal-1
Four-character name of the file from which the record is retrieved.
• field-1
Name of the field containing the record's control key.
• field-2
Name of the field containing the data list of elements to retrieve.
• field-3
Name of the field containing the file's data.
%READM Macro-Generated Statements
The generated statements are:
TOTALCMND = 'READM'
TOTALFILE = 'literal-1'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
field-1, +
field-2, +
field-3, +
TOTALEND)
%READR
Contents
Use the %READR macro to retrieve records by following the chain of back pointers.
Syntax
%READR literal-1 field-1 +
literal-2 field-2 +
field-3 field-4
764
CA Easytrieve® Report Generator 11.6
• literal-1
Four-character name of the file from which the record is retrieved.
• field-1
Name of a field containing the four-character reference point.
• literal-2
Eight-character linkpath.
• field-2
Name of the field containing the record's control key.
• field-3
Name of the field containing the data list of elements to retrieve.
• field-4
Name of the field to receive the data.
%READR Macro-Generated Statements
The generated statements are:
TOTALCMND = 'READR'
TOTALFILE = 'literal-1'
TOTALREF = field-1
TOTALLINK = 'literal-2'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
TOTALREF, +
TOTALLINK, +
field-2, +
field-3, +
field-4, +
TOTALEND)
field-1 = TOTALREF
%READV
Contents
Use the %READV macro to retrieve variable file records by following the chain of forward pointers.
Syntax
%READV literal-1 field-1 +
literal-2 field-2 +
field-3 field-4
• literal-1
Four-character name of the file from which the record is retrieved.
• field-1
Name of a field containing the four-character reference point.
• literal-2
Eight-character linkpath.
• field-2
765
CA Easytrieve® Report Generator 11.6
Name of the field containing the record's control key.
• field-3
Name of the field containing the data list of elements to retrieve.
• field-4
Name of the field to receive the data.
%READV Macro-Generated Statements
The generated statements are:
TOTALCMND = 'READV'
TOTALFILE = 'literal-1'
TOTALREF = field-1
TOTALLINK = 'literal-2'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
TOTALREF, +
TOTALLINK, +
field-2, +
field-3, +
field-4, +
TOTALEND)
field-1 = TOTALREF
%RGHTJUST
Contents
Right justify a field's contents.
Syntax
%RGHTJUST [field-name] [length]
• [field-name]
The name of the field to be right-justified.
• [length]
The length of the field to be right-justified.
%SINOF
Contents
Use the %SINOF macro to terminate task activities.
Syntax
%SINOF
766
CA Easytrieve® Report Generator 11.6
%SINOF Macro-Generated Statements
The generated statements are:
TOTALCMND = 'SINOF'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALTASK, +
TOTALEND)
%SINON
Contents
Use the %SINON macro to initialize task activities.
Syntax
%SINON literal-1 literal-2 field-1
• literal-1
Access function. Valid values are RDONLY and UPDATE.
• literal-2
Eight-character DBMOD name.
• field-1
Name of the field containing the logging options.
%SINON Generated Statements
The generated statements are:
TOTALCMND = 'SINON'
TOTALDBMOD = 'literal-2'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
'literal-1', +
TOTALDBMOD, +
TOTALTASK, +
field-1, +
TOTALEND)
IF TOTALSTATUS NE '****'
DISPLAY 'SIGN-ON ERROR', TOTALSTATUS
STOP
END-IF
TOTALREALM = 'REALM = '
REALMINDEX = 0
%VERNUMP
Contents
767
CA Easytrieve® Report Generator 11.6
Validates user supplied parameters for valid numeric data.
Syntax
%VERNUMP [param]
• [param]
The parameter field to be verified.
%WRITM
Contents
Use the %WRITM macro to update master file records identified by the control key.
Syntax
%WRITM literal-1 field-1 +
field-2 field-3
• literal-1
Four-character name of the file to update.
• field-1
Name of the field containing the record's control key.
• field-2
Name of the field containing the data list of elements to update.
• field-3
Name of the field containing the file's data.
%WRITM Macro-Generated Statements
The generated statements are:
TOTALCMND = 'WRITM'
TOTALFILE = 'literal-1'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
field-1, +
field-2, +
field-3, +
TOTALEND)
%WRITV
Contents
Use the %WRITV macro to update variable file records.
Syntax
768
CA Easytrieve® Report Generator 11.6
%WRITV literal-1 field-1 +
literal-2 field-2 +
field-3 field-4
• literal-1
Literal-1 is the four-character name of the file to update.
• field-1
Field-1 is the name of a field containing the four-character reference point.
• literal-2
Literal-2 is the eight-character link path.
• field-2
Field-2 is the name of the field containing the record's control key.
• field-3
Field-3 is the name of the field containing the data list of elements to update.
• field-4
Field-4 is the name of the field containing the data.
%WRITV Macro-Generated Statements
The generated statements are:
TOTALCMND = 'WRITV'
TOTALFILE = 'literal-1'
TOTALREF = field-1
TOTALLINK = 'literal-2'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
TOTALREF, +
TOTALLINK, +
field-2, +
field-3, +
field-4, +
TOTALEND)
field-1 = TOTALREF
Example - Retrieve Records Using a Tickler File
The following example illustrates retrieving records using a tickler file.
*
%TOTALCOM
*
FILE KEYS, CARD
CARD-KEY 1 7 A
*
*
DEFINE INVN-AREA W 100 A
DEFINE INVN-KEY INVN-AREA 7 A
DEFINE INVN-NAME INVN-AREA +7 20 A
769
CA Easytrieve® Report Generator 11.6
DEFINE INVN-CODE INVN-AREA +27 1 A
*
DEFINE BVIT-AREA W 100 A
DEFINE BVIT-COST BVIT-AREA 4 P 2
DEFINE BVIT-AMT BVIT-AREA +4 4 P 0
DEFINE BVIT-RATE BVIT-AREA +8 4 P 2
*
DEFINE INVN-ELEM W 20 A, VALUE 'INVNCTRL+
INVNDATA+
END.'
*
DEFINE MY-REF W 4 A
*
DEFINE BVIT-ELEM W 12 A, VALUE 'BVIDATA+
END.'
*
DEFINE SINON-OPTIONS W 20 A, VALUE 'LOGOPTS=N,+
END.'
*
JOB INPUT(KEYS), START(SIGN-ON), FINISH(SIGN-OFF)
*
INVN-KEY = CARD-KEY. * CONTROL KEY
%READM INVN, INVN-KEY, INVN-ELEM, INVN-AREA. * READ MASTER
PERFORM STATUS-CHECK. * ERROR TEST
READ-VAR. * READ VARIABLE
MY-REF = 'LK01'
%READV BVIT, MY-REF, 'INVNLK01' , INVN-KEY, +
BVIT-ELEM, BVIT-AREA
PERFORM STATUS-CHECK. * ERROR TEST
IF TOTALREF NE TOTALENDP
GOTO READ-VAR
END-IF
*
PRINT
*
STATUS-CHECK. PROC. * TEST FOR SUCCESSFUL CALL
IF TOTALSTATUS NE '****'. * IF NOT SUCCESSFUL
DISPLAY 'UNSUCCESSFUL TOTAL COMMAND=', TOTALCMND. +
' ON FILE=', TOTALFILE, +
' STATUS=', TOTALSTATUS
STOP. * ABORT THE JOB
END-IF
*
SIGN-ON. PROC. * INITIAL CALL TO TOTAL
%SINON RDONLY, BASE127, SINON-OPTIONS
%DFNTOTF INVN, READ
%DFNTOTF BVIT, READ
%OPENX
END-PROC
*
770
CA Easytrieve® Report Generator 11.6
SIGN-OFF. PROC. * WRAP-UP
%CLOSX
%SINOF. * FINAL CALL TO TOTAL
END-PROC
*
REPORT
SEQUENCE INVN-KEY
CONTROL INVN-KEY
TITLE 'INVENTORY CONTROL LISTING'
LINE INVN-KEY, INVN-NAME, INVN-CODE, +
BVIT-COST, BVIT-AMT, BVIT-RATE
771
CA Easytrieve® Report Generator 11.6
Language Reference
This section includes information about CA Easytrieve Report Generator character sets, statements, symbols and
reserved words, and converting from older versions to the current version.
Documentation Conventions
The following conventions are used throughout this section for illustrative purposes:
Notation Meaning
{braces} Mandatory choice of one of these entries.
[brackets] Optional entry or choice of one of these entries.
| (OR bar) Choice of one of these entries.
(parentheses) Multiple parameters must be enclosed in parentheses.
... Ellipses indicate that you can code the immediately preceding
parameters multiple times.
BOLD Bold text in program code is used to highlight an example of the
use of a statement.
CAPS All capital letters indicate a CA Easytrieve® Report
Generator keyword, or within text descriptions, indicate a name or
field used in a program example.
lowercase italics Lowercase italics represent variable information in statement
syntax.
Syntax Rules
The free form English language structure of CA Easytrieve® Report Generator makes it easy for you to develop an
efficient, flexible programming style. To avoid programming errors, follow the simple syntax rules described for each
statement in this section.
Character Sets
CA Easytrieve Report Generator supports both single-byte character sets (SBCS) and double byte character sets
(DBCS). MIXED format is data that contains both SBCS and DBCS formatted data. SBCS data is limited to either EBCDIC
or ASCII depending on the platform. DBCS data is currently supported only in z/OS.
NOTE
Report processing is limited to EBCDIC and ASCII data format for standard reports and to any data format for
extended reports. Identifiers (for example, field names or labels) can contain DBCS and MIXED data as part of
the name. MIXED data format is supported only to the extent that such data is allowed. The product provides no
additional formatting based on the alignment of the DBCS portion of the data. DBCS data is not supported in the
UNIX or Windows environments.
EBCDIC and DBCS
Both EBCDIC and DBCS data processing are applicable to China (Hanzi characters), Japan (Kanji, Hiragana, and
Katakana characters), and Korea (Haja and Hangual characters). CA Easytrieve Report Generator supports both
character sets, based on the following assumptions and rules:
772
CA Easytrieve® Report Generator 11.6
• All the syntax rules that are described in the Statement Overview section apply to EBCDIC data only. DBCS data in the
program statement area is not processed for such things as continuation characters, delimiters, words, and identifiers.
• Unless otherwise noted, source statements are expected to contain character data. Hexadecimal codes embedded
into statements are not supported as they may cause problems reading and printing the source program.
• A DBCS character occupies two bytes in storage. If not identified as DBCS characters, these same two bytes would be
processed as a pair of single-byte EBCDIC characters. To distinguish EBCDIC data from DBCS data, CA Easytrieve
uses a shift code system. This system, called the wrapping shift code system, takes the form of two codes -- one code
preceding and the second following the DBCS data. These codes wrap or enclose the DBCS data, thereby identifying
the beginning and end of DBCS data. The term that is associated with the code that precedes the DBCS data is a shift-
out code (shift-out of EBCDIC). The code that delimits (separates) the DBCS data is called a shift-in code (shift-in to
EBCDIC). These codes can be one or two bytes in length.
The following diagram illustrates the use of the wrapping shift code system:
• A shift code is a special one- or two-byte character that is contained in the program statement area. Shift code values
are defined in the DBCS Options module. For more information about the Options module, see the Using section. Each
shift code value uniquely identifies the DBCS code system of the data. If the system cannot be uniquely identified, a
default is assumed. You can alter this default at compile time by using the PARM statement. For more information, see
the PARM Statement.
• In the statement area, shift codes are required to distinguish DBCS data from EBCDIC data. When a CA Easytrieve
Report Generator word has been identified, the word is known to be of EBCDIC, DBCS, or MIXED data format. Shift
773
CA Easytrieve® Report Generator 11.6
codes are maintained for MIXED words only. The compiler identifies the statement containing the word and, when
necessary, performs the required processing to remove the shift codes and convert EBCDIC data.
• Once a shift-out code is found in a word, the data that follows is processed as DBCS data if any one of the following
actions occurs:
– The end statement area is reached before the related shift-in code is found.
– The shift-in code is found but it is not on a double byte boundary.
– The shift-out code is found as part of the identified DBCS data.
Statements
This article contains an alphabetical list of CA Easytrieve Report Generator statements and a summary of the statements,
categorized by function.
Alphabetical Summary of Statements
The following table describes the statements that you can use in CA Easytrieve Report Generator programs.
Statement Description
% (percent) Invoke a macro
* (asterisk) Document comments in a program.
ACCESS Access a macro secured against unauthorized access in CA
Panvalet or VSAM.
AFTER-BREAK A REPORT procedure invoked following the printing of summary
lines for a control break.
AFTER-LINE A REPORT procedure invoked after printing a detail line on a
report.
AFTER-SCREEN A SCREEN procedure performed after a SCREEN activity
receives data from the terminal.
Assignment Establish a value in a field.
BEFORE-BREAK A REPORT procedure invoked before printing the summary lines
for a control break.
BEFORE-LINE A REPORT procedure invoked before printing a detail line on a
report.
BEFORE-SCREEN A SCREEN procedure invoked before a SCREEN activity sends
data to the terminal.
CALL Invoke subprograms written in other programming languages.
CASE Conditionally execute one of several alternative groups of
statements based on the value of a specific field.
CLOSE Close a file.
COMMIT Commit a logical unit of recoverable work.
CONTROL Identify control fields used in a control report.
COPY Duplicate field definitions of a named file.
CURSOR Set the initial position of the screen cursor.
DECLARE Name a set of screen attributes or an input edit pattern, or whether
a program is statically or dynamically linked.
DEFAULT Override system-defined screen attributes and message locations.
DEFINE Specify a data field within a file or within working storage.
774
CA Easytrieve® Report Generator 11.6
DELETE Delete a row from an SQL file.
DISPLAY Format and transfer data to the system output device or to a
named file.
DLI Perform IMS/DLI functions against an IMS/DLI database.
DO UNTIL Control repetitive program logic by evaluating the condition at the
bottom of a group of statements.
DO WHILE Control repetitive program logic by evaluating the condition at the
top of a group of statements.
ELEMENT RECORD Identify the element records that comprise the logical record.
ELSE Identify statements to be executed when IF conditions are false.
See IF.
ELSE-IF Identify a conditional expression to be tested when the previous IF
or ELSE-IF conditional expression is false. See IF.
END-CASE Terminate the body of a CASE statement. See CASE.
END-DO Terminate the body of a loop associated with a DO UNTIL or DO
WHILE statement. See DO UNTIL and DO WHILE.
END-IF Terminate the logic associated with the previous IF statement. See
IF.
ENDPAGE A REPORT procedure used to produce page footing information.
END-PROC Delimit the statements in a procedure. See PROC Statement.
END-REPEAT Terminate the body of a REPEAT statement. See REPEAT.
ENDTABLE Delimit instream data used to create small tables.
EXECUTE Invoke a JOB, SORT, or SCREEN activity from a PROGRAM or
SCREEN activity.
EXIT Terminate a SCREEN activity.
FETCH Retrieve a row from an SQL file.
FILE Describe a file and database references.
GET Place the next sequential record of the named file into the file's
record buffer.
GOTO Modify the top-to-bottom logic flow of statement execution.
GOTO JOB Branch to the top of the current JOB activity.
GOTO SCREEN Branch to the top of the current SCREEN activity.
HEADING Define an alternative heading for a field on a report.
IDD FILE Identify a non CA IDMS file in the IDD and build the file and field
definition.
IDD NAME Establish the dictionary entity retrieval environment.
IDD RECORD Identify and define CA IDMS and non CA IDMS records.
IDD SUBSCHEMA Identify the subschema and build the file, record, logical record,
element record, and field definitions.
IDD VERSION Set a global override of the Options Table VERFILE, VERREC,
and VERSCHM defaults.
IDMS ACCEPT DBKEY Transfer database keys to program storage.
IDMS ACCEPT PROCEDURE Return information from the Application Program Information Block
(APIB) associated with a database procedure to the program.
IDMS ACCEPT STATISTICS Retrieve the system statistics.
775
CA Easytrieve® Report Generator 11.6
IDMS BIND Sign on the activity with the database management system.
IDMS BIND FILE Give the database management system access to the record in
program storage.
IDMS BIND PROCEDURE Establish communications between a program and a DBA-written
database procedure.
IDMS COMMIT Request the creation of a checkpoint.
IDMS CONNECT Establish a record as a member of a set occurrence.
IDMS DISCONNECT Cancel the relationship between a record and a set occurrence.
IDMS ERASE Make a record or logical record unavailable for further processing
and remove it from all set occurrences in which it participates as a
member.
IDMS FIND Locate a record.
IDMS FINISH Sign off the database management system.
IDMS GET Retrieve current data records.
IDMS IF Test the status of a set.
IDMS KEEP Place a shared or exclusive lock on a record.
IDMS MODIFY Update a record or logical record within the database.
IDMS OBTAIN Locate and then retrieve a record. For database records, see
IDMS FIND and IDMB OBTAIN Statements. For logical records,
see IDMS OBTAIN.
IDMS READY Establish area availability with the database manager.
IDMS RETURN Retrieve the database key for an indexed record without retrieving
the record.
IDMS ROLLBACK Request recovery.
IDMS STORE Place a new record or logical record occurrence into a database.
IF Control the execution of associated statements by testing
conditional expressions.
INITIATION A SCREEN procedure invoked during the start of a SCREEN
activity.
INSERT Insert a row into an SQL file.
JOB Define and initiate processing activities.
JOB INPUT Identify automatic input to the activity.
JOB INPUT NULL Inhibit automatic input.
JOB INPUT SQL Allow to automatically manage the SQL cursor without a file.
KEY Define valid terminal keys for a screen, specify descriptive text,
and assign functions to terminal keys.
LINE Define the content of a report line.
LINK Transfer control from current program to another named program
and return to current program.
LIST Regulate the printing or suppression of all statements in the
printed output of a program.
LOGICAL-RECORD Identify the logical records available for automatic or controlled
processing of CA IDMS databases.
MACRO Define the parameters of a macro.
MEND Terminate a macro.
776
CA Easytrieve® Report Generator 11.6
MESSAGE Define message type and text for messages in a SCREEN activity.
MOVE Transfer character strings from one storage location to another.
MOVE LIKE Move contents of fields with identical names from one file or
record to another.
MSTART Begin an instream macro.
NEWPAGE Eject the printer to the top of the next page before printing the next
line of source program on a statement listing.
PARM Override selected general standards for a program that are set in
the Site Options Table.
PERFORM Transfer control to a procedure and return control to next
executable statement in current program.
POINT Establish a position within an INDEXED or RELATIVE file from
which subsequent data is sequentially retrieved.
POP Restore the previous listing control indicators.
PRINT Produce report output.
PROC Initiate a CA Easytrieve Report Generator procedure.
PROGRAM Identify and initiate a processing activity that can optionally initiate
JOB, SORT, and SCREEN activities.
PUSH Save the current listing control indicators.
PUT Perform sequential file output.
READ Provide random access to INDEXED and RELATIVE files.
RECORD Identify the CA IDMS database records available for automatic or
controlled processing.
REFRESH Restore the initial screen image by rebuilding it with the current
values of program fields.
RELEASE Manually release the hold on any record in an INDEXED or
RELATIVE file.
REPEAT Display arrays on a screen.
REPORT Define the type and characteristics of a report.
REPORT-INPUT A REPORT procedure that selects or modifies report input data.
RESHOW Redisplay a screen image without rebuilding the screen using the
current values of program fields.
RETRIEVE Identify the CA IDMS or IMS/DLI database records that are input
to the JOB activity.
ROLLBACK Roll back all recoverable work since the last commit-point.
ROW Specify items to be displayed and received on a row of a screen.
SCREEN Define and initiate a SCREEN activity.
SEARCH Provide access to table data.
SELECT (File-based SQL) Cause a cursor to be declared and opened for a SQL file.
SELECT (CA IDMS) Specify automatic input of logical records from CA IDMS
databases.
SELECT (Non-file SQL) Identify the rows and columns to be input to a JOB activity when a
CA Easytrieve Report Generator file is not used.
SELECT (Report Selection) Select report input data.
SELECT (Sort Selection) Select sort input data.
777
CA Easytrieve® Report Generator 11.6
SEQUENCE Specify the order of a report based on the content of one or more
fields.
SET Dynamically change screen attributes and control the display of
screen errors.
SKIP Space the printer a designated number of lines before printing the
next line of a statement listing.
SORT Sequence an input file in alphabetical or numerical order based on
fields specified as keys.
SQL Indicate a valid SQL statement for any of the supported SQL
database management systems.
SQL INCLUDE Indicate SQL table information is used to generate CA Easytrieve
Report Generator field definitions.
STOP Terminate activities.
SUM Specify the quantitative fields that are to be totaled for a control
report.
TERMINATION (Reports) A REPORT procedure invoked at the end of a report, commonly
used to print report footing information.
TERMINATION (Screens) A SCREEN procedure invoked once during the end of a SCREEN
activity, used to perform actions that are executed once at the end
of the activity.
TITLE (Reports) Define an optional report title and its position on a title line.
TITLE (Screens) Define and center title items on a screen.
TRANSFER Transfer execution to a program without returning to the invoking
program.
UPDATE Update a row from an SQL file.
WRITE Update and delete existing records or add new records to
INDEXED and RELATIVE files.
Statements Categorized by Function
The following CA Easytrieve Report Generator statements are categorized by function:
Library Definition
• COPY
• DECLARE
• DEFINE
• FILE
• SQL INCLUDE
778
CA Easytrieve® Report Generator 11.6
File Management
• CLOSE
• COMMIT
• DELETE
• DISPLAY
• ENDTABLE
• FETCH
• GET
• INSERT
• JOB
• JOB INPUT NULL
• JOB INPUT SQL
• POINT
• PUT
• READ
• RELEASE
• ROLLBACK
• SELECT (File-based SQL)
• SELECT (Non-file SQL)
• SELECT (Sort selection)
• SORT
• UPDATE
• WRITE
Screen Processing
NOTE
Screen processing commands are supported only with Online versions of the product.
• AFTER-SCREEN
• BEFORE-SCREEN
• CURSOR
• DEFAULT
• EXIT
• INITIATION
• KEY
• MESSAGE
• REFRESH
• REPEAT
• RESHOW
• ROW
• SCREEN
• SET
• TERMINATION
• TITLE
779
CA Easytrieve® Report Generator 11.6
Report Processing
• AFTER-BREAK
• AFTER-LINE
• BEFORE-BREAK
• BEFORE-LINE
• CONTROL
• ENDPAGE
• HEADING
• LINE
• PRINT
• REPORT
• REPORT-INPUT
• SELECT
• SEQUENCE
• SUM
• TERMINATION
• TITLE
Generalized Programming
• PARM
• PROGRAM
Inter-Program Execution
• CALL
• LINK
• TRANSFER
Decision and Branching Logic
• CASE
• DO UNTIL
• DO WHILE
• ELSE
• ELSE-IF
• END-DO
• END-IF
• EXECUTE
• GOTO
• GOTO JOB
• GOTO SCREEN
• IF
• PERFORM
• STOP
780
CA Easytrieve® Report Generator 11.6
Listing Control
• * (asterisk)
• LIST
• NEWPAGE
• POP
• PUSH
• SKIP
Assignment and Moves
• Assignment
• MOVE
• MOVE LIKE
Macro Processing
• % (percent)
• ACCESS
• MACRO
• MEND
• MSART
Native SQL
• SQL
781
CA Easytrieve® Report Generator 11.6
CA IDMS Database Processing
• ELEMENT-RECORD
• IDD FILE
• IDD NAME
• IDD RECORD
• IDD SUBSCHEMA
• IDD VERSION
• IDMS ACCEPT DBKEY
• IDMS ACCEPT PROCEDURE
• IDMS ACCEPT STATISTICS
• IDMS BIND
• IDMS BIND FILE
• IDMS BIND PROCEDURE
• IDMS COMMIT
• IDMS CONNECT
• IDMS DISCONNECT
• IDMS ERASE
• IDMS FIND
• IDMS FINISH
• IDMS GET
• IDMS IF
• IDMS KEEP
• IDMS MODIFY
• IDMS OBTAIN
• IDMS READY
• IDMS ROLLBACK
• IDMS STORE
• LOGICAL-RECORD
• RECORD
• RETRIEVE
• SELECT (CA IDMS)
IMS/DLI Database Processing
• DLI
Statement Overview
This article includes the following information about statements for CA Easytrieve Report Generator programs:
Statement Area
All source statements are records of 80 characters each. A system installation option establishes a statement area within
the 80 available positions. The default statement area is in columns 1 to 72.
For example, although positions 1 to 80 are available, ‘SCANCOLS 7, SCANCOLE 72’ establishes the statement area as
positions 7 to 72. This allows for optional data (for example, sequence numbers and program identifiers) to be entered
782
CA Easytrieve® Report Generator 11.6
on the record, but still be ignored by CA Easytrieve Report Generator. The complete record is always printed on the
statement listing.
7 7 8
1....6 7......................................2 3......0
001000 PRGMNAME
ignored statement area ignored
Multiple Statements
The statement area normally contains a single statement. However, you can enter multiple statements on a single record.
The character string '. ' (period followed by a space) indicates the end of a statement. Another CA Easytrieve statement
begins at the next available position of the statement area (after the space). For example, the following two statements
are on one record:
COST = FIXED + VARIABLE. PRICE = COST + PROFIT
Comments
When the first non-blank character of a statement is an asterisk (*), the remainder of that record is a comment statement
that is ignored by the CA Easytrieve compiler. You can use comment statements at any place within a program, except
within a continued statement. A statement containing all blanks is treated as a comment.
To place a comment on the same line as a statement, code a period (.), one or more spaces, an asterisk (*), and then the
comment:
FIELD-NAME W 5 A . * This is a comment
Continuations
The last non-blank character of a statement terminates the statement, unless that character is a - (minus) or a + (plus).
The - indicates that the statement continues at the start of the next statement area. The + indicates that the statement
continues with the first non-blank character in the next statement area. The difference between - and + is important only
when continuing words. Continuation between words is the same for both. The following continued statements produce
identical results:
FIELD-NAME W 6 A +
VALUE 'ABC-
DEF'
----------------------------
FIELD-NAME W 6 A -
VALUE 'ABC+
DEF'
DBCS Data
To continue a statement defining DBCS data, you must delimit the DBCS data. This means a shift-in code must precede
the continuation character and a shift-out code must precede the continuing DBCS data on the next record. The following
example illustrates continuing a DBCS literal:
783
CA Easytrieve® Report Generator 11.6
FIELD-NAME W 10 K +
VALUE '[DBDBDB] +
[DBDB]'
The [ and ] indicate shift-out and shift-in codes.
Words and Delimiters
One or more words make up each CA Easytrieve statement. A word can be a keyword, field name, literal, or symbol. All
words begin with a non-blank character. A delimiter or the end of the statement area terminates these words. Delimiters
make statements readable but are not considered part of the attached word. CA Easytrieve word delimiters are:
Delimiter Description
space The basic delimiter within each statement.
' single quote Encloses literals that are alphanumeric.
. period followed Terminates a statement.
by a space
, comma Used optionally for readability.
() parentheses Encloses multiple parameters and portions of arithmetic
expressions (the left parenthesis acts as a basic delimiter).
: colon Used as a delimiter for file, record, and field qualifications.
= equal sign Used as a delimiter for assignment and comparison statements.
NOTE
At least one space must follow all delimiters except for the '(' (left parenthesis), and the ':' (colon). Additionally,
the equal sign '=' can be coded with or without surrounding spaces.
Examples of the words RECORD-COUNT and NUM with various delimiters:
RECORD-COUNT
FILEONE:RECORD-COUNT
(RECORD-COUNT)
'RECORD-COUNT'
RECORD-COUNT,
RECORD-COUNT.
RECORD-COUNT=10
IF RECORD-COUNT=10
NUM = 20
IF NUM = 20
Keywords
Keywords are words that have specific meaning to CA Easytrieve. Some keywords are reserved words. You can use non-
reserved keywords in the appropriate context as field names, whereas reserved words cannot be used as field names. For
more information about keywords and reserved words, see Symbols and Reserved Words.
784
CA Easytrieve® Report Generator 11.6
Multiple Parameters
You must enclose multiple parameters within parentheses to indicate group relationships. If parentheses are not used,
only one parameter is assumed. The following example is a CA Easytrieve statement with multiple parameters:
CALL PGMNAME USING(FIELDA, FIELDB, FIELDC)
Field Names
Field names are composed of a combination of not more than 128 characters as follows:
• Alphabetic characters, A to Z, lowercase, and uppercase
• Decimal digits 0 through 9
• All special characters, except delimiters
The first character of a field name must be an alphabetic character, a decimal digit, or a national character (#, @, $).
In addition, a field name must contain at least one alphabetic or special character to distinguish the field name from a
number.
All working storage field names must be unique, and so must all field names within a single file. If you use the same field
name in more than one file, or in a file and in working storage, you must qualify the field name with the file name or the
word WORK. A qualified field name consists of the qualifying word followed by a colon and the field name. You can use
any number of spaces, or no spaces, to separate the colon from either the qualifying word or the field name. Field names
can contain DBCS characters.
Assume FLD1 occurs in both working storage and the file FILEA. FLD1 can be qualified in the following ways:
FILEA: FLD1
FILEA:FLD1
FILEA : FLD1
WORK:FLD1
Labels
Labels identify specific PROGRAMs, JOBs, PROCedures, REPORTs, SCREENs, and statements. Labels can be 128
characters long, can contain any character other than a delimiter, and can begin with A to Z, 0 through 9, or a national
character (#, @, $); they cannot consist of all numeric characters. Labels can contain DBCS characters.
Identifiers
Identifiers are words that name things (for example, field names or statement labels) in CA Easytrieve. Identifiers cannot
contain these delimiters:
• comma {,}
• single quote {'}
• left parenthesis {(}
• right parenthesis {)}
• colon {:}
Arithmetic Operators
CA Easytrieve arithmetic expressions use the following arithmetic operators:
785
CA Easytrieve® Report Generator 11.6
• multiplication (*)
• division (/)
• addition (+)
• subtraction (-)
The arithmetic operator must lie between two spaces.
Numeric Literals
Numeric literals can contain 18-numeric digits (characters 0 through 9). You can indicate the algebraic sign of a numeric
literal by attaching a + (plus) or a - (minus) prefix to the numeral. Also, you can use a single decimal point to indicate a
maximum precision of up to 18 decimal positions. The following examples are valid numeric literals:
123
+123
-123.4321
Alphanumeric Literals
Alphanumeric literals are words that are enclosed within single quotes, and can be 254 characters long. For more
information, see Literal and Data Formatting Rules.
Font Numbers
Font numbers are used by extended report processing to identify which font is used to display the field name or literal.
A font number must begin with a pound sign (#) and contain only numeric digits. Font numbers can be specified on the
following statements:
• DEFINE
• DISPLAY
• HEADING
• LINE
• TITLE
% (Macro Invocation) Statement
The macro invocation statement consists of a macro name preceded by a percent (%) sign.
NOTE
For more information about defining substitutable parameters in the macro, see MACRO Statement. For more
information about using macros, see the Programming section.
This statement has the following format:
%macro-name positional-parameters...keyword-parameters
• %macro-name
Specifies a previously stored macro that you want to invoke. Macro names are limited to eight characters.
NOTE
For CA Panvalet and CA Endevor libraries the macro name can be from 1 to 10 characters in length.
• positional-parameters
786
CA Easytrieve® Report Generator 11.6
Specifies values of positional parameters in the macro. You must supply positional parameters before any keyword
parameters.
• keyword-parameters
Specifies both the keyword and values of keyword parameters in the macro.
* (Comment) Statement
The * (comment) statement lets you document comments in a program. When the first non-blank character of a statement
is an asterisk (*), the remainder of that record is a comment statement. You can use comment statements any place within
a program, except within a continued statement. A statement containing all blanks is treated as a comment.
If you code comment statements within a SCREEN declaration and maintain the screen with the CA Easytrieve® Report
Generator Online Report Generator Screen Painter, all comment statements are moved to the top of the declaration.
This statement has the following format:
* comment-text
• comment-text
Specifies the text that you want to enter as comment in the program.
ACCESS Statement
The ACCESS statement lets you access a macro secured against unauthorized access in CA Panvalet or VSAM.
For both CA Panvalet and VSAM macro storage access methods, the ACCESS record can appear anywhere in the CA
Easytrieve® Report Generator program prior to the retrieval of the macro, and remains in effect until the next ACCESS
record is encountered. The ACCESS record must be on a record by itself. CA Easytrieve® Report Generator does not
print the ACCESS record.
This statement has the following format:
CA Panvalet:
ACCESS 'eight-byte code'
VSAM:
ACCESS 'eight-byte password'
• 'eight-byte code'
Specifies a security access code that applies to an individual CA Panvalet library member. You must supply the
security access code on an ACCESS record before CA Easytrieve® Report Generator can retrieve a secured member.
• 'eight-byte password'
Specifies a VSAM password. VSAM provides the capability of protecting the macro library by using this password.
Before CA Easytrieve® Report Generator can retrieve a macro from a secured library, you must supply the library
password on an ACCESS record prior to the first macro call.
AFTER-BREAK Report Procedure
An AFTER-BREAK procedure is invoked following the printing of summary lines for a control break. It can be used to
produce special annotation on control reports.
787
CA Easytrieve® Report Generator 11.6
The AFTER-BREAK procedure is invoked once for each level of break. For example, assume two control fields are
specified. When the minor field causes a control break, the AFTER-BREAK procedure is invoked only once. When the
major field causes a control break, AFTER-BREAK is invoked twice.
The value of LEVEL (a system-defined field) can be used to determine which control break is being processed. The value
of BREAK-LEVEL (a system-defined field) contains the number of the field causing the control break. TALLY (a system-
defined field) contains the number of records in a particular control group. For examples of LEVEL and BREAK-LEVEL,
see Programming.
NOTE
If NOPRINT is specified on a CONTROL statement, the AFTER-BREAK procedure is still executed.
An AFTER-BREAK procedure must be delimited by an END-PROC statement. For more information, see PROC
Statement.
This procedure has the following format:
AFTER-BREAK. PROC
• AFTER-BREAK. PROC
Specifies a REPORT procedure that is invoked following the printing of summary lines for a control break.
Example:
In the following example, the total line for the control field STATE receives special annotation:
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
AFTER-BREAK. PROC
IF LEVEL EQ 2
DISPLAY 'TOTALS FOR THE STATE OF ' STATE
END-IF
788
CA Easytrieve® Report Generator 11.6
END-PROC
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 802.35
JONES IL 60077 641.97
IL 1444.32
TOTALS FOR THE STATE OF IL
SMITH TX 75218 777.77
TX 777.77
TOTALS FOR THE STATE OF TX
2222.09
AFTER-LINE Report Procedure
An AFTER-LINE procedure is invoked immediately following the printing of each detail line on a report. An AFTER-LINE
procedure is commonly used to print a literal string after a detail line on the report.
The AFTER-LINE procedure is invoked after each individual line in a line group. The system-defined field LINE-NUMBER
contains the number of the line in the group being processed.
NOTE
When the AFTER-LINE procedure is invoked, the detail line for the report has already been built. You cannot
modify the contents of the detail line with an AFTER-LINE procedure. (To modify the contents of a detail line on
a report, use a REPORT-INPUT or BEFORE-LINE procedure.)
An AFTER-LINE procedure must be delimited by an END-PROC statement. For more information, see PROC Statement.
This statement has the following format:
AFTER-LINE. PROC
Example
The following example shows how an AFTER-LINE procedure can cause information to be printed following a detail line of
a report:
Statements:
789
CA Easytrieve® Report Generator 11.6
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
DTLCTL EVERY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
AFTER-LINE. PROC
IF PAY-NET GE 500
DISPLAY '* EMPLOYEE ' LAST-NAME ' +
EXCEEDED WEEKLY SALARY GOAL *'
END-IF
END-PROC
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 678.90
* EMPLOYEE BROWN EXCEEDED WEEKLY SALARY GOAL *
BROWN IL 60076 123.45
IL 60076 802.35
790
CA Easytrieve® Report Generator 11.6
JONES IL 60077 543.21
* EMPLOYEE JONES EXCEEDED WEEKLY SALARY GOAL *
JONES IL 60077 98.76
IL 60077 641.97
IL 1444.32
SMITH TX 75218 666.66
* EMPLOYEE SMITH EXCEEDED WEEKLY SALARY GOAL *
SMITH TX 75218 111.11
TX 75218 777.77
TX 777.77
2222.09
AFTER-SCREEN Screen Procedure
An AFTER-SCREEN procedure is invoked after the screen activity receives data from the terminal.
All branch actions (REFRESH, RESHOW, EXIT, GOTO SCREEN) are valid in the AFTER-SCREEN procedure and in
any procedure performed by the AFTER-SCREEN procedure. The AFTER-SCREEN procedure is not executed if the key
pressed is assigned to execute a branch action with a KEY statement. You typically use an AFTER-SCREEN procedure to
perform complex editing and to perform I/O after data entry.
An AFTER-SCREEN procedure must be delimited by an END-PROC statement. For more information, see PROC
Statement.
This statement has the following format:
AFTER-SCREEN. PROC
Example
SCREEN NAME SCRN1
KEY F3 NAME 'Exit' EXIT
KEY F8 NAME 'Forward'
. . .
AFTER-SCREEN. PROC
GET PERSNL
IF EOF PERSNL
EXIT
791
CA Easytrieve® Report Generator 11.6
END-IF
END-PROC
Assignment Statement
The assignment statement establishes a value in a field. The value can be a copy of the data in another field or literal, or it
can be the result of an arithmetic or logical expression evaluation.
The assignment statement has a normal assignment format and a logical expression format.
The normal assignment format sets the value of receive-field-name equal to the value of send-field-name, send-literal,
or the arithmetic expression. For complete rules of the assignment statement and rules for converting from EBCDIC to
DBCS, see the Programming section.
The logical expression format sets the value of receive-field-name equal to the result of evaluating a logical expression.
The value of send-field-name is logically acted upon by the value of bit-mask-field-name or bit-mask-literal. The lengths of
all values must be the same and bit-mask-literal must be hexadecimal.
NOTE
If receive-field-name is nullable, then its indicator is set to zero, indicating NOT NULL. If any operands on the
right-hand side contain nulls, a runtime error occurs.
The normal assignment format is as follows:
[ROUNDED ] {= } {send-field-name }
receive-field-name [INTEGER] [ ] { } {send-literal }
[TRUNCATED] {EQ} {arithmetic-expression}
• receive-field-name
Specify the field name to which a value is to be assigned.
• INTEGER
Specify INTEGER to ignore the fractional portion of the value being assigned. INTEGER causes only the numerics to
the left of the decimal point to be transferred during the assignment.
• ROUNDED or TRUNCATED
Specify ROUNDED or TRUNCATED when the receiving field (receive-field-name) is too small to handle the fractional
result of the assignment. TRUNCATED is the default.
Specify ROUNDED to round off the fractional result of the assignment statement. The least significant digit of the result
(receiving field) has its value increased by one when the most significant digit of the excess decimal digits is greater
than or equal to five. For example, if 10.75 is the value of the sending field and the receiving field has one decimal
place, ROUNDED causes the receiving field to be 10.8.
Specify TRUNCATED to truncate the result of the assignment statement. Low order digits are truncated on the right as
necessary when the result is moved to the receiving field.
If INTEGER is used with ROUNDED, the result is rounded to the nearest integer before the INTEGER function is
performed. If INTEGER is used with TRUNCATED (the default), then only the INTEGER function is performed.
NOTE
INTEGER, ROUNDED, and TRUNCATED are valid only with numeric fields.
• "= " or EQ
792
CA Easytrieve® Report Generator 11.6
Use EQ or = to indicate equivalency.
• send-field-name or send-literal or arithmetic-expression
Send-field-name names the field that is copied to receive-field-name.
Send-literal contains the literal that is copied to receive-field-name.
Arithmetic-expression contains numeric values separated by arithmetic operators (+, -, *, /). The result of the
arithmetic-expression is placed in receive-field-name.
The logical expression format is as follows:
{= } {AND} {bit-mask-field-name}
receive-field-name { } send-field-name {OR } { }
{EQ} {XOR} {bit-mask-literal }
• receive-field-name
Specify the field name to which a value is to be assigned.
• "= " or EQ
Use EQ or = to indicate equivalency.
• send-field-name
send-field-name names the field that is copied to receive-field-name.
• AND or OR or XOR
Specify AND, OR, or XOR:
– AND—Zero bits in bit-mask-field-name or bit-mask-literal are carried forward to send-field-name and the result is
placed in receive-field-name.
– OR—One bits in bit-mask-field-name or bit-mask-literal are carried forward to send-field-name and the result is
placed in receive-field-name.
– XOR—Corresponding bits of bit-mask-field-name or bit-mask-literal, and send-field-name must be opposite (zero
and one) to result in a one bit in receive-field-name.
• bit-mask-field-name or bit-mask-literal
Bit-mask-field-name is the name of a field that is logically combined with send-field-name, the result of which is carried
forward to receive-field-name.
Bit-mask-literal is a literal bit mask that is logically combined with send-field-name, the result of which is carried forward
to receive-field-name.
Examples
The following examples of the assignment statement illustrate its various rules.
Example 1
The first example shows assignment format 1 when the receive-field-name is alphanumeric:
Format 1 (Normal Assignment)
DEFINE F1A W 4 A
DEFINE F2A1 W 1 A VALUE 'A'
DEFINE F2A2 W 6 A VALUE 'ABCDEF'
DEFINE F2N1 W 2 N VALUE 12
DEFINE F2N2 W 3 P 1 VALUE 1234.5
...
Resulting Value
793
CA Easytrieve® Report Generator 11.6
F1A = F2A1 'A '
F1A = F2A2 'ABCD'
F1A = F2N1 '0012'
F1A = F2N2 '2345'
F1A = X'FF' X'FF404040'
NOTE
For an example using varying length alphanumeric fields, see Programming.
Example 2
This example shows assignment format 1 when the receive-field-name is numeric:
Format 1 (Normal Assignment)
DEFINE F1N W 4 N 1
DEFINE F2N1 W 4 N 1 VALUE 1
DEFINE F2N2 W 4 N 1 VALUE 2
DEFINE F2N3 W 4 N 1 VALUE 3
JOB INPUT NULL NAME MYPROG
F1N = F2N1 + F2N2 + F2N3
DISPLAY SKIP 2 +
'F1N = F2N1 + F2N2 + F2N3 = ' F1N
F1N = F2N1 + F2N2 / F2N3
DISPLAY SKIP 2 +
'F1N = F2N1 + F2N2 / F2N3 = ' F1N
F1N = (F2N1 + F2N2) / F2N3
DISPLAY SKIP 2 +
'F1N = (F2N1 + F2N2) / F2N3 = ' F1N
F1N = ((F2N1 / F2N2) * 100) + .5
DISPLAY SKIP 2 +
'F1N = ((F2N1 / F2N2) * 100) + .5 = ' F1N
STOP
Results:
Resulting
Value
F1N = F2N1 + F2N2 + F2N3 = 6.0
(1 + 2 + 3)
F1N = F2N1 + F2N2 / F2N3 = 1.6
(1 + 2 / 3)
(1 + 0.6666)
794
CA Easytrieve® Report Generator 11.6
F1N = (F2N1 + F2N2) / F2N3 = 1.0
(( 1 + 2) / 3)
(3 / 3)
F1N = ((F2N1 / F2N2) * 100) + .5 = 50.5
(( 1 / 2) * 100) + .5
((0.5 * 100) + .5)
(50 + .5)
Example 3
The following example illustrates the use of the INTEGER, ROUNDED, and TRUNCATED parameters:
If:
SENDFLD W 5 N 2 VALUE(10.75)
RCVFLD W 5 N 1
Then:
Assignment Statement RCVFLD Result
RCVFLD INTEGER ROUNDED = SENDFLD 11.0
RCVFLD INTEGER TRUNCATED = SENDFLD 10.0
RCVFLD INTEGER = SENDFLD 10.0
RCVFLD ROUNDED = SENDFLD 10.8
RCVFLD TRUNCATED = SENDFLD 10.7
RCVFLD = SENDFLD 10.7
Format 2 (Logical Expression Evaluation)
Statements:
DEFINE F1P W 2 P MASK HEX
DEFINE F2P W 2 P VALUE X'123D'
JOB INPUT NULL NAME MYPROG
F1P = F2P AND X'FFFE'
DISPLAY SKIP 2 +
'F1P = F2P AND X''FFFE'' = ' F1P
F1P = F2P OR X'000F'
DISPLAY SKIP 2 +
'F1P = F2P OR X''000F'' = ' F1P
F1P = F2P XOR X'FFFF'
DISPLAY SKIP 2 +
'F1P = F2P XOR X''FFFF'' = ' F1P
795
CA Easytrieve® Report Generator 11.6
F1P = F2P XOR F2P
DISPLAY SKIP 2 +
'F1P = F2P XOR F2P = ' F1P
STOP
Results:
Resulting
Value
F1P = F2P AND X'FFFE' = 123C
F1P = F2P OR X'000F' = 123F
F1P = F2P XOR X'FFFF' = EDC2
F1P = F2P XOR F2P = 0000
ATTR Parameter
Use the ATTR parameter to assign screen attributes to a field or literal. You can specify a declared screen attribute name
or a list of attribute keywords. You can use the ATTR parameter in the following statements:
• DECLARE
• DEFAULT
• ROW
• TITLE
When used in these statements, the ATTR parameter completely overrides any site or screen default attributes. For
information about how to set default screen attributes that override site attributes, see DEFAULT Statement.
The ATTR parameter can be specified without an attribute-name or an attribute-list only on the DECLARE statement. This
lets a named attribute be declared and then assigned later in the program. A runtime error occurs if a named attribute
is used without any attributes assigned to it. The DEFAULT, ROW, and TITLE statements require an attribute-name or
an attribute-list after the ATTR keyword.
This parameter has the following format:
ATTR [attribute-name ]
[(attribute-list)]
attribute-list
[SENDONLY] +
[CURSOR] +
796
CA Easytrieve® Report Generator 11.6
[ASKIP ] +
[PROTECT]
[NUMERIC] +
[INTENSE ] +
[INVISIBLE]
[GREEN ]
[RED ]
[BLUE ]
[TURQ|TURQUOISE] +
[PINK ]
[YELLOW ]
[BLACK ]
[WHITE ]
[MUSTFILL] +
[MUSTENTER] +
[TRIGGER] +
[BLINK ]
[REVERSE ] +
[UNDERLINE]
[ALARM] +
[BOX ]
[LEFT ]
[RIGHT]
[UNDER]
[OVER ]
• attribute-name
Specify a declared screen attribute name. For more information, see DECLARE Statement.
• SENDONLY
The SENDONLY parameter specifies that the field is not to be received. The field is ignored if entered. SENDONLY is
implied for literals.
• CURSOR
Specify CURSOR to place the cursor on this field when displayed on the terminal. If more than one field contains the
CURSOR attribute, the cursor is placed on the first field that contains CURSOR.
CURSOR is ignored for literals.
Note: The cursor cannot be moved into a field that also contains the ASKIP, PROTECT, or SENDONLY attributes.
• [ASKIP ] or [PROTECT]
ASKIP specifies that the field is an auto-skip field. PROTECT specifies that the field is protected and not auto-skipped.
If neither is specified, the field is unprotected.
ASKIP is implied for literals.
• [NUMERIC]
797
CA Easytrieve® Report Generator 11.6
NUMERIC specifies that only numeric data can be entered in this screen field. Use NUMERIC for permitting only
numeric data in alphanumeric fields. NUMERIC is implied for all numeric data types, and ignored for literals.
• [INTENSE] or [INVISIBLE]
INTENSE specifies that the field displays brightly. INVISIBLE specifies that the field is present on the screen but is not
displayed. INVISIBLE is ignored for literals.
On 3270 extended attribute terminals, INTENSE is ignored if a color attribute is also specified.
• [GREEN], [RED], [BLUE], [TURQ|TURQUOISE], [PINK], [YELLOW], or [WHITE]
The value specified is the color of the field or literal when displayed on a screen. If no color is specified, hardware
defaults apply.
• [MUSTFILL]
Specify MUSTFILL to require that all spaces have a non-blank character typed into them. MUSTFILL is ignored for
literals and on terminals that do not support a mandatory-fill attribute.
• [MUSTENTER]
Specify MUSTENTER to send an error message to the terminal if the field was not changed. MUSTENTER is ignored
for literals and on terminals that do not support a mandatory-enter attribute. MUSTENTER is ignored for literals.
• [TRIGGER]
TRIGGER causes the screen to be received as soon as the terminal operator has modified the field and tries to move
the cursor out of the field. TRIGGER is ignored for literals and on terminals that do not support a trigger attribute.
• [BLINK] or [REVERSE] or [UNDERLINE]
BLINK displays the item blinking. REVERSE displays the item in reverse video. UNDERLINE displays the item
underlined.
• [ALARM]
ALARM causes the terminal alarm to sound. ALARM is ignored for literals.
• [BOX], [LEFT], [RIGHT], [UNDER], or [OVER]
BOX specifies that field outlining displays a box surrounding the field.
LEFT specifies that field outlining displays a vertical line to the left of a field.
RIGHT specifies that field outlining displays a vertical line to the right of a field.
UNDER specifies that field outlining displays a horizontal line below a field.
OVER specifies that field outlining displays a horizontal line above a field.
Note: BOX, LEFT, RIGHT, UNDER, and OVER are ignored on terminals that do not support outlining attributes.
BEFORE-BREAK Report Procedure
A BEFORE-BREAK procedure is invoked before printing the summary lines for a control break. It can be used to calculate
percentages and average totals. These values must be calculated immediately before printing.
The BEFORE-BREAK procedure is invoked once for each level of break. For example, assume two control fields are
specified. When the minor field causes a control break, the BEFORE-BREAK procedure is invoked only once. When the
major field causes a control break, BEFORE-BREAK is invoked twice.
The value of LEVEL (a system-defined field) can be used to determine which control break is being processed. The value
of BREAK-LEVEL (a system-defined field) contains the number of the field causing the control break. TALLY (a system-
defined field) contains the number of records in a particular control group. For examples of LEVEL and BREAK-LEVEL,
see Programming.
NOTE
If NOPRINT is specified on a CONTROL statement, the BEFORE-BREAK procedure is still executed.
A BEFORE-BREAK procedure must be delimited by an END-PROC statement. For more information, see PROC
Statement.
This statement has the following format:
798
CA Easytrieve® Report Generator 11.6
BEFORE-BREAK. PROC
Example
Consider the following percentage calculation, paying special attention to when and how PERCENT is calculated:
Statements:
FILE FILE1 FB(80 8000)
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
*
PERCENT W 2 N 2
TOTAL-NET S 8 N 2
*
JOB INPUT FILE1 NAME MYPROG
*
TOTAL-NET = TOTAL-NET + PAY-NET
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 80 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-NET PERCENT
*
BEFORE-BREAK. PROC
PERCENT = PAY-NET * 100 / TOTAL-NET
END-PROC
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
Results:
LAST-NAME STATE ZIP PAY-NET PERCENT
BROWN IL 60076 802.35 36.10
JONES IL 60077 641.97 28.89
IL 1444.32 64.99
SMITH TX 75218 777.77 35.00
799
CA Easytrieve® Report Generator 11.6
TX 777.77 35.00
2222.09 100.00
The BEFORE-BREAK procedure computes the percentage for each control break by multiplying the sum of PAY-NET by
100 and then dividing by TOTAL-NET.
NOTE
TOTAL-NET is a static (S) working storage field summed in the JOB activity processing.
BEFORE-LINE Report Procedure
A BEFORE-LINE procedure is invoked immediately before the printing of each detail line on a report. A BEFORE-LINE
procedure is commonly used to print a literal string before a detail line on the report or to change the contents of the detail
line before printing.
The BEFORE-LINE procedure is invoked before each individual line in a line group. The system-defined field LINE-
NUMBER contains the number of the line in the group being processed.
A BEFORE-LINE procedure must be delimited by an END-PROC statement. For more information, see PROC Statement.
For an example, see the AFTER-LINE Report Procedure.
This statement has the following format:
BEFORE-LINE. PROC
BEFORE-SCREEN Screen Procedure
A BEFORE-SCREEN procedure is invoked before the screen activity sends the data to the terminal. It precedes building
the screen and the terminal I/O process.
You typically use a BEFORE-SCREEN procedure to perform I/O, initialize screen fields, or set the cursor position.
GOTO SCREEN, REFRESH, and RESHOW are invalid in the BEFORE-SCREEN procedure, and in any procedure
performed by the BEFORE-SCREEN procedure.
A BEFORE-SCREEN procedure must be delimited by an END-PROC statement. For more information, see the PROC
Statement.
This statement has the following format:
BEFORE-SCREEN. PROC
Example
SCREEN NAME SCRN1
KEY F3 NAME 'Exit' EXIT
KEY F8 NAME 'Forward'
. . .
BEFORE-SCREEN. PROC
GET PERSNL
IF EOF PERSNL
800
CA Easytrieve® Report Generator 11.6
EXIT
END-IF
END-PROC
CALL Statement
The CALL statement provides a means to dynamically or statically invoke subprograms written in other programming
languages.
The program being called can be either statically or dynamically bound with your CA Easytrieve® Report Generator
program. The way that the called program is bound is determined by the following, in order:
1. If the program was declared on a DECLARE statement, the STATIC or DYNAMIC keyword on the DECLARE
statement determines how it is bound.
2. If specified, the CALL parameter on the PARM statement supplies the default for all called programs in your CA
Easytrieve program.
3. The default is determined by the environment. The default on the mainframe and Windows is DYNAMIC. The default
on Unix platforms is STATIC.
COBOL programs cannot be called by CA Easytrieve programs in the CICS environment. For more information, see the
IBM CICS Programmer's Reference Manual.
Any mainframe program being called in a CICS environment must execute in conversational mode. The task must not be
terminated by a called program.
For more information about subprogram linkage, see Inter-Program Linkage.
This statement has the following format:
[ {field-name} ]
CALL program-name [USING ( { } ...)] [RETURNS return-field]
[ {'literal' } ]
• program-name
Program-name is the name of the subprogram that you want invoked. It is loaded into storage as part of an activity
initiation.
• USING {field-name} or USING {'literal'}
USING specifies the parameter list passed to the subprogram.
Field-name must identify a system-defined field, a working storage field, or a field defined in an accessible file.
'Literal' can be any alphanumeric literal that is passed to the program.
NOTE
The field-name for the USING parameter includes only the data. It does not include the leading two-byte
length value as in the field-name for the USING parameter used with the PROGRAM statement.
• [RETURNS return-field]
RETURNS identifies a numeric field that will contain the return code passed back by a called subprogram. If the
program is calling a COBOL subprogram, the return code is the value in the COBOL RETURN-CODE field. If the
program is calling an Assembler subprogram, the return code is the value contained in register 15 on the mainframe. If
you are coding a C subprogram, the return code is the value returned from the function.
Return-field is a numeric CA Easytrieve field that contains the returned value. The field can be a user-defined field or
you can use the system-defined field, RETURN-CODE, to pass the return code to the operating system.
801
CA Easytrieve® Report Generator 11.6
Examples
The first example shows a CALL statement without parameters; the second shows one with parameters:
CALL ASMPGM
CALL ASMPGM USING ('USERFIL', USERFLD)
CASE and END-CASE Statements
Use the CASE and END-CASE statements to conditionally execute one of several alternative groups of statements based
on the value of a specific field.
A CASE statement can be nested within a CASE statement. Other conditional execution statements can also be nested
within a CASE statement. A CASE statement can be nested within any other conditional execution statement.
This statement has the following format:
CASE field-name
WHEN compare-literal-1 [THRU range-literal-1] [...]
statement-1
WHEN compare-literal-n [THRU range-literal-n] [...]
statement-n
[OTHERWISE ]
[ statement-n+1]
END-CASE
The following diagram illustrates CASE statement logic:
802
CA Easytrieve® Report Generator 11.6
• field-name
Field-name specifies a field that contains a value that is compared to the values represented by compare-literal [THRU
range-literal].
Field-name can be a field of any type. If field-name is numeric, it must have zero or no decimal places.
• WHEN
You can specify as many WHEN conditions as necessary. At least one WHEN condition is required. You cannot code
statements between CASE and the first WHEN condition. You must supply a unique set of values to be compared with
field-name in each WHEN condition.
• compare-literal [THRU range-literal]
Compare-literal is the value to be compared with field-name. You can specify a single literal, a series of literals, or a
range of literals. A range is represented by compare-literal THRU range-literal. A range is satisfied when field-name
is greater than or equal to the lesser of compare-literal and range-literal and is less than or equal to the greater of
compare-literal and range-literal.
When field-name is alphanumeric, compare-literal and range-literal must also be alphanumeric. The comparison is
based on the greater of the length of field-name and compare-literal or range-literal. The shorter field is padded with
spaces to equal the length of the longer field.
When field-name is numeric, compare-literal and range-literal must also be numeric and must not have any decimal
places.
803
CA Easytrieve® Report Generator 11.6
The set of literal values specified for a given WHEN, including the unspecified values implied by a range, must be
unique as compared to the literal values of any other WHEN for the same CASE.
• statement-1 to statement-n
Statement-1 and statement-n represent any number of CA Easytrieve® Report Generator statements executed when
the WHEN comparison is satisfied. Whenever one or more of these statements is a CASE statement, the CASE
statements are considered to be nested.
• OTHERWISE
OTHERWISE is an optional statement that specifies a group of statements to be executed if no WHEN comparison
was satisfied. If OTHERWISE is not specified and field-name does not equal any of the specified WHEN conditions,
execution continues with the statement following END-CASE.
• statement-n+1
Statement-n+1 represents any number of CA Easytrieve® Report Generator statements executed when no WHEN
comparisons are equal. Whenever one or more of these statements is a CASE statement, the CASE statements are
considered to be nested.
• END-CASE
END-CASE terminates the body of the CASE statement. END-CASE must be specified after each CASE statement
and its associated statements.
Example
The following example uses CASE to analyze the data to select employees' years of service that fall into a range
(identified by the WHEN statement) and, as a result, display 'ONE WEEK VACATION' or 'TWO WEEKS VACATION', or for
all other cases, display 'THREE WEEKS VACATION'.
FILE EMPLOYEE
EMPYRS 5 2 N
...
CASE EMPYRS
WHEN 0 THRU 4
DISPLAY 'ONE WEEK VACATION'
WHEN 5 THRU 10
DISPLAY 'TWO WEEKS VACATION'
OTHERWISE
DISPLAY 'THREE WEEKS VACATION'
END-CASE
...
CLOSE Statement
The CLOSE statement closes a file.
At the termination of each activity, all files that were opened during the activity are automatically closed. You can use the
CLOSE statement to close the file before the activity terminates. The next I/O statement using the file reopens the file.
You can also close an SQL file with the CLOSE statement so that a new cursor can be created. For more information, see
SQL Database Processing.
Note: You cannot use the CLOSE statement to close a printer file or to close an automatic input or output file. Virtual files
without RETAIN are deleted when closed. CLOSE has no effect on IDMS files.
This statement has the following format:
804
CA Easytrieve® Report Generator 11.6
CLOSE file-name
• file-name
File-name specifies the file to be closed.
Example
CLOSE FILEA
COMMIT Statement
The COMMIT statement causes a logical unit of work to be established.
The COMMIT statement establishes the end of the current logical unit of work and the beginning of the next.
The COMMIT statement establishes a recovery point for updates. The ROLLBACK statement can then be used to recover
any recoverable actions since the last COMMIT. (The operating environment determines which actions are recoverable.
For more information, see Control Program Flow.)
COMMIT terminates any active holds on files. All open SQL cursors are closed and all updates to databases are
committed.
Note: Cursors defined with the HOLD option (DB2 only) are not closed.
This statement has the following format:
COMMIT
Example
WRITE PERSNL ADD
. . .
IF . . .
COMMIT
ELSE
ROLLBACK
END-IF
Conditional Expressions
Conditional expressions used as parameters of IF and DO statements offer an alternative to the normal top-to-bottom
execution of CA Easytrieve® Report Generator statements.
CA Easytrieve® Report Generator accepts seven different conditions: Field Relational, Field Series, Field Class, Field
Bits, File Presence, File Relational, Record Relational.
This statement has the following format:
{IF } [ {AND} ]
{DO WHILE } condition [ { } condition]...
{DO UNTIL } [ {OR } ]
805
CA Easytrieve® Report Generator 11.6
Examples
The following are skeletal examples of each type of conditional expression used in an IF statement:
Type Example
Field Relational IF field-1 = field-2
Field Series IF field-1 = field-2, field-3, field-4
Field Class IF field-1 ALPHABETIC
Field Bits IF field-1 ON X'0F4000
File Presence IF EOF file-name
File Relational IF MATCHED file-1, file-2, file-3
Record Relational IF DUPLICATE file-name
Field Bits Condition
The field bits condition compares selected bits of a field for on (1) or off (0) conditions.
This statement has the following format:
Relational
Subject Operator Object
{IF } {ON } {field-name-2}
{DO WHILE} field-name-1 [NOT] { } { }
{DO UNTIL} {OFF} {literal }
• Subject
Field-name-1 is the subject of the comparison. It can be any field type. The NOT parameter indicates the condition test
is reversed.
• Relational Operator
The relational operators ON and OFF test for bit values of one or zero respectively.
• Object
Field-name-2 or a literal identifies the bit mask to be tested. CA Easytrieve® Report Generator tests only those bits
that correspond to one (1) bits in the mask. The length of the object must equal the length of the subject. When you
code a literal as the object, it must be a hexadecimal literal. Indicate a hexadecimal literal by preceding it with an X and
enclosing it in single quotes.
If the subject is a VARYING field, the object must be equal to the length of the data portion of the subject. The test is
performed based on the actual length of the subject. The object cannot be a VARYING field.
Example
This example illustrates the use of the field bits condition:
DEFINE FIELD-1 W 1 B VALUE X'20'
DEFINE FIELD-NUM W 4 B VALUE X'FF00FF00'
DEFINE PATTERN-8 W 1 B VALUE X'80'
DEFINE LOWER-CASE W 1 A VALUE X'81'
*
JOB INPUT NULL NAME MYPROG
IF FIELD-1 ON PATTERN-8
806
CA Easytrieve® Report Generator 11.6
DISPLAY 'PERFORM CODE FOR PATTERN 8'
END-IF
IF LOWER-CASE OFF X'40'
DISPLAY 'THIS LETTER IS LOWER CASE'
END-IF
IF FIELD-NUM ON X'FF000000'
DISPLAY '1ST BYTE HIGH VALUES'
END-IF
STOP
Field Class Condition
The field class condition determines whether:
• All positions of a field contain alphabetic, numeric, space, or zero characters.
• A nullable field is null.
• The cursor is in a specific field on the screen.
• A field was modified by the terminal user.
• A field is active in a control break of the current report.
This statement has the following format:
Subject Object
{ALPHABETIC }
{BREAK }
{CURSOR }
{HIGHEST-BREAK}
{IF } {MODIFIED }
{DO UNTIL } field-name [NOT] {NULL }
{DO WHILE } {NUMERIC }
{SPACE }
{SPACES }
{ZERO }
{ZEROS }
{ZEROES }
{HIGH-VALUES }
{LOW-VALUES }
• Subject
Field-name is the subject of the comparison. Each byte of the field must pass the test before the test is true. The NOT
parameter indicates that the condition test is reversed.
Field-name can be indexed or subscripted.
• Object
The object determines the class of data to be tested for.
• {ALPHABETIC}
ALPHABETIC tests for the upper-case characters A to Z or a blank space in each byte of the subject field.
• {BREAK}
807
CA Easytrieve® Report Generator 11.6
BREAK tests whether this field is currently being processed as a CONTROL break field on a report. The BREAK
test is an alternative to testing the field-name LEVEL for a specific numeric value. Field-name must be defined on a
CONTROL statement or it must be the reserved word FINAL.
• {CURSOR}
CURSOR tests whether the cursor is in the specified field on the screen. CURSOR can be used only in screen activity
procedures.
If CURSOR is used, the condition must refer to a field on a ROW statement within the screen declaration.
NOTE
Results are unpredictable if:
• Field-name contains the ASKIP, PROTECT, or SENDONLY attributes.
• Field-name occurs more than once in a screen.
• Two screen fields redefine the same storage area and one of the fields is used in an IF test.
• The subject is indexed or subscripted and the value of the index or subscript has changed since the
screen was received.
• The test is performed after the user presses CLEAR, PA1, PA2, or PA3.
• {HIGHEST-BREAK}
HIGHEST-BREAK tests whether this field caused the CONTROL break on a report. The HIGHEST-BREAK test is an
alternative to testing the field-name BREAK-LEVEL for a specific numeric value. Field-name must be defined on a
CONTROL statement or it must be the reserved word FINAL.
• {MODIFIED}
MODIFIED tests whether the terminal operator changed the data in the field. The field is considered MODIFIED only
if the contents of the field upon receipt of the screen do not equal the contents of the screen at the time the screen is
displayed.
MODIFIED can be used only in screen activity procedures.
If MODIFIED is used, the condition must refer to a field on a ROW statement within the screen declaration.
NOTE
Results are unpredictable if:
• Field-name occurs more than once in a screen.
• Two screen fields redefine the same storage area and one of the fields is used in an IF test.
• The subject is indexed or subscripted and the value of the index or subscript has changed since the
screen was received.
• The test is performed after the user presses CLEAR, PA1, PA2, or PA3.
• {NULL}
NULL tests whether a nullable field is NULL.
• {NUMERIC}
NUMERIC tests for the digits 0 to 9 (in the correct format for the field's data type), and for a possible algebraic sign in
the low-order position of type-P fields or in the high-order position of type-N fields.
• {SPACE}
SPACE and SPACES test for the character space in each byte of single-byte subjects.
• {ZERO}
ZERO, ZEROS, and ZEROES test for the digit 0 (in the correct format for the field's data type), and for a possible
algebraic sign in the low-order position of type-P fields or in the high-order position of type-N fields.
• {HIGH-VALUES}
HIGH-VALUES tests for the character X'FF' in each byte of single-byte and MIXED format subjects and in each double
byte of DBCS subjects.
• {LOW-VALUES}
LOW-VALUES tests for the character X'00' in each byte of single-byte and MIXED format subjects and in each double
byte of DBCS subjects.
808
CA Easytrieve® Report Generator 11.6
Example
This example illustrates the use of the field class condition:
FILE PERSNL FB(150 1800)
REGION 1 1 N
BRANCH 2 2 N
EMPNAME 17 20 A
NAME-LAST EMPNAME 8 A
NAME-FIRST EMPNAME +8 12 A
*
TOTAL-NUMERIC W 3 N VALUE 0
TOTAL-NON-ZEROS W 3 N VALUE 0
TOTAL-ALPHABETIC W 3 N VALUE 0
*
JOB INPUT PERSNL NAME MYPROG FINISH FINISH-PROC
IF REGION NUMERIC
TOTAL-NUMERIC = TOTAL-NUMERIC + 1
END-IF
IF BRANCH NOT ZERO
TOTAL-NON-ZEROS = TOTAL-NON-ZEROS + 1
END-IF
IF EMPNAME ALPHABETIC
TOTAL-ALPHABETIC = TOTAL-ALPHABETIC + 1
END-IF
*
FINISH-PROC. PROC
DISPLAY TOTAL-NUMERIC
DISPLAY TOTAL-NON-ZEROS
DISPLAY TOTAL-ALPHABETIC
END-PROC
Field Relational Condition
The field relational condition compares fields with values.
This statement has the following format:
Relational
Subject Operator Object
{IF } {EQ|= }
{ELSE-IF } {NE|Ø=|NQ } {field-name-2 }
{ } field-name-1 {LT|< |LS } {literal }
{DO WHILE} {LE|<=|LQ|Ø> } {arithmetic-expression }
{DO UNTIL} {GT|> |GR }
{GE|>=|GQ|Ø< }
• Subject
809
CA Easytrieve® Report Generator 11.6
Field-name-1 is the subject of the comparison.
• Relational Operator
Code any of the relational operators to control the condition's evaluation process.
• Object Code
Code field-name-2, a literal, or an arithmetic-expression designates the object of the comparison.
Note: Alphanumeric literals must be enclosed within single quotes.
For information about how CA Easytrieve Report Generator evaluates arithmetic expressions, see Assignments and
Moves in the Programming section.
Alphanumeric Subjects
When the condition subject is an alphanumeric field, the following evaluation rules apply:
• The object must be either a field or an alphanumeric literal.
• If necessary, numeric field objects are converted to zoned decimal. Comparison of VARYING alphanumeric fields with
numeric fields is not permitted.
• The comparison is based on the greater of the length of the subject and the length of the object. The shorter item is
padded with spaces to the length of the longer item. For downward compatibility with existing CA Easytrieve Report
Generator programs, this rule is subject to the following exception:
– When a fixed length subject is compared with a longer fixed length object, the comparison is based on the length of
the subject.
– The object is truncated to match the length of the subject. The compiler then generates a warning message.
• Comparison is logical (bit-by-bit).
• Comparisons of varying length fields (fields which use the VARYING option of the DEFINE statement) are based on
the length of the data at the time of the comparison.
Numeric Subjects
When the condition subject is a numeric field, the following evaluation rules apply:
• The object must be a numeric field, a numeric literal, or an arithmetic expression.
• Comparison is arithmetic.
Mixed Subjects
When the condition subject is a MIXED field, the following evaluation rules apply:
• CA Easytrieve Report Generator supports only equal (EQ =) and not equal (NE Ø= NQ) conditions. If you use any of
the other conditional operators, an error occurs.
• The object must be a field, an alphanumeric literal, a MIXED literal, or a DBCS literal.
• A conversion is not performed if the object is an EBCDIC alphanumeric field or literal.
• If the object is a MIXED field or literal, the DBCS portion of data is converted into the DBCS code system of the
subject. CA Easytrieve® Report Generator also converts the shift codes to the values defined for the DBCS code
system of the subject in the DBCS Options module.
• If the object is a DBCS field or literal, the data is converted into the DBCS code system of the subject. When this
conversion occurs, the shift codes defined for the code system of the subject are added to the data.
• Numeric field objects are converted to zoned decimal (if necessary).
• To match the length of the subject, CA Easytrieve Report Generator truncates or pads the object. Padding uses the
single-byte space character. During truncation, no DBCS character is split. When truncation occurs within the DBCS
portion of a field, the truncation is adjusted to the nearest double byte boundary.
• Comparison is logical (bit-by-bit).
DBCS Subjects
When the condition subject is a DBCS field, the following evaluation rules apply:
810
CA Easytrieve® Report Generator 11.6
• CA Easytrieve Report Generator supports only equal (EQ =) and not equal (NE Ø= NQ) conditions. If you use any of
the other conditional operators, an error occurs.
• The object must be a field, an alphanumeric literal, a MIXED literal, or a DBCS literal.
• If the object is an EBCDIC alphanumeric field or literal, then each character is converted into the DBCS code system of
field-name-1.
• If the object is a MIXED field or literal, the DBCS portion of data is converted into the DBCS code system of the
subject. CA Easytrieve® Report Generator also converts the EBCDIC portion of data to its equivalent DBCS value
based on the code system of the subject. Shift codes are removed.
• If the object is a DBCS field or literal, the data is converted into the DBCS code system of the subject.
• If necessary, numeric field objects are converted to zoned decimal and then converts the EBCDIC result into the
equivalent DBCS characters based on the code system of field-name-1.
• To match the length of the subject, CA Easytrieve Report Generator truncates or pads the object. Padding uses the
DBCS space character.
• Comparison is logical (bit-by-bit).
Example
This example illustrates various field relational conditions:
FILE PERSNL FB(150 1800)
EMP# 9 5 N
EMPNAME 17 20 A
NAME-LAST EMPNAME 8 A
NAME-FIRST EMPNAME +8 12 A
PAY-NET 90 4 P 2
PAY-GROSS 94 4 P 2
SEX 127 1 N
TOTAL-EMP# W 3 N VALUE 0
TOTAL-SEX W 3 N VALUE 0
TOTAL-PAY W 3 N VALUE 0
TOTAL-FIRST-NAME W 3 N VALUE 0
MALE W 1 N VALUE 1
JOB INPUT PERSNL NAME MYPROG FINISH FINISH-PROC
IF EMP# GT 10000
TOTAL-EMP# = TOTAL-EMP# + 1
END-IF
IF SEX NE MALE
TOTAL-SEX = TOTAL-SEX + 1
END-IF
IF PAY-NET LT (PAY-GROSS / 2)
TOTAL-PAY = TOTAL-PAY + 1
END-IF
IF NAME-FIRST EQ 'LINDA'
TOTAL-FIRST-NAME = TOTAL-FIRST-NAME + 1
END-IF
*
FINISH-PROC. PROC
DISPLAY TOTAL-EMP#
811
CA Easytrieve® Report Generator 11.6
DISPLAY TOTAL-SEX
DISPLAY TOTAL-PAY
DISPLAY TOTAL-FIRST-NAME
END-PROC
Field Series Condition
The field series condition compares a field to a series or a range of values.
Evaluation rules for field series conditions are as follows:
• Alphanumeric (including DBCS and MIXED format fields) and numeric fields are evaluated as in the field relational
condition.
• An equal (=) relational operator tests if the subject is equal to or within range of any of the series of values comprising
the object.
• A not equal (Ø=) relational operator tests if the subject is unequal to or outside the range of all the series of values
comprising the object.
Note: A comparison within a range is satisfied if the subject is greater than the lesser of the two range values and the
subject is less than the greater of the two range values.
This statement has the following format:
Relational
Subject Operator
{IF }
{ELSE-IF } {EQ | = }
{ } field-name-1 { } +
{DO WHILE } {NE | Ø= | NQ}
{DO UNTIL }
Object
{field-name-2 [ {field-name-3 } ] }
{ [THRU { } ]...}
{literal-1 [ {literal-2 } ] }
• Subject
Field-name-1 is the subject of the comparison.
• Relational Operator
Equal and not equal are the only valid relational operators for field series conditions.
• Object
Code field-name-2 or a literal-1 as often as you need to indicate the series of comparison objects. Field-name-2 THRU
field-name-3, field-name-2 THRU literal-2, literal-1 THRU field-name-3, or literal-1 THRU literal-2 designate a value
range.
Note: Alphanumeric literals must be enclosed within single quotes.
Example
This example illustrates the field series condition:
FILE PERSNL FB(150 1800)
REGION 1 1 N
812
CA Easytrieve® Report Generator 11.6
BRANCH 2 2 N
DEPT 98 3 N
MARITAL-STAT 128 1 A
*
TOTAL-REGION W 3 N VALUE 0
TOTAL-BRANCH W 3 N VALUE 0
TOTAL-DEPT W 3 N VALUE 0
TOTAL-MARITAL W 3 N VALUE 0
WORK-REGION W 2 N VALUE 04
*
JOB INPUT PERSNL NAME MYPROG FINISH FINISH-PROC
IF REGION = 0, 8, 9
TOTAL-REGION = TOTAL-REGION + 1
END-IF
IF BRANCH NE 01, WORK-REGION
TOTAL-BRANCH = TOTAL-BRANCH + 1
END-IF
IF DEPT EQ 940 THRU 950
TOTAL-DEPT = TOTAL-DEPT + 1
END-IF
IF MARITAL-STAT NE 'M', 'S'
TOTAL-MARITAL = TOTAL-MARITAL + 1
END-IF
*
FINISH-PROC. PROC
DISPLAY TOTAL-REGION
DISPLAY TOTAL-BRANCH
DISPLAY TOTAL-DEPT
DISPLAY TOTAL-MARITAL
END-PROC
File Presence Condition
The file presence condition determines whether a record of the file is currently available for processing.
The object of the test is simply the availability of the record for processing. The file is available if the last GET or READ
operation was successful and there is a record that can be accessed.
NOTE
Results are unpredictable if data in a file is referenced after any output operation.
The optional EOF parameter causes the test to be true when the subject is at end-of-file. This test can never be true for
automatic input files.
The optional NOT parameter reverses the condition test.
For more information about file presence conditions, see the CA Easytrieve® Report Generator Programming Guide.
This statement has the following format:
Subject
813
CA Easytrieve® Report Generator 11.6
{IF }
{DO WHILE} [NOT] [EOF] {file-name}
{DO UNTIL}
• Subject
File-name designates the subject of the test.
Example 1
This example illustrates the use of the file presence condition:
FILE PERSNL INDEXED
%PERSNL
*
JOB INPUT NULL NAME MYPROG
READ PERSNL KEY '00970' STATUS
IF NOT PERSNL
DISPLAY '00970 NOT ON FILE'
ELSE
DISPLAY EMPNAME
END-IF
STOP
Example 2
This example illustrates the use of the file presence condition in synchronized file processing:
FILE PERSNL FB(150 1800)
%PERSNL
FILE INVENT FB(200 3200)
%INVMSTR
FILE SORT1 FB(150 1800) VIRTUAL
COPY PERSNL
FILE SORT2 FB(200 3200) VIRTUAL
COPY INVENT
COUNT-1 W 3 N VALUE 0
COUNT-2 W 3 N VALUE 0
*
SORT PERSNL TO SORT1 USING (ADDR-STATE) NAME MYSORT1
SORT INVENT TO SORT2 USING (LOCATION-STATE) NAME MYSORT2
*
JOB INPUT (SORT1 KEY (ADDR-STATE), +
SORT2 KEY (LOCATION-STATE)) +
NAME MYPROG FINISH FINISH-PROC
IF EOF SORT2
DISPLAY 'EOF ON SECONDARY'
STOP
END-IF
IF NOT PRIMARY
DISPLAY 'NO PERSONNEL RECORD- ' LOCATION-STATE
814
CA Easytrieve® Report Generator 11.6
END-IF
IF NOT SECONDARY
DISPLAY 'NO INVENTORY RECORD- ' ADDR-STATE
END-IF
IF SORT1
* HOW MANY PERSONNEL RECORDS RETURNED
COUNT-1 = COUNT-1 + 1
END-IF
IF SORT2
* HOW MANY INVENT RECORDS RETURNED
COUNT-2 = COUNT-2 + 1
END-IF
*
FINISH-PROC. PROC
DISPLAY COUNT-1
DISPLAY COUNT-2
END-PROC
File Relational Condition
The file relational condition determines file presence and record matching for more than one file in JOBs with
synchronized file input.
This statement has the following format:
Subject
[file-name]
IF [NOT] MATCHED [PRIMARY ] ...
[SECONDARY]
• Subject
The optional file-name, PRIMARY, and SECONDARY parameters identify the files to be tested. If you do not code this
parameter, the condition is true only if all input files have matching records.
The optional NOT parameter reverses the condition test.
Example
This example illustrates the use of the file relational condition:
FILE PERSNL FB(150 1800)
%PERSNL
FILE INVENT FB(200 3200)
%INVMSTR
FILE SORT1 F(150) VIRTUAL
COPY PERSNL
FILE SORT2 F(200) VIRTUAL
COPY INVENT
COUNT-1 W 3 N VALUE 0
*
815
CA Easytrieve® Report Generator 11.6
SORT PERSNL TO SORT1 USING (ADDR-STATE) NAME MYSORT1
SORT INVENT TO SORT2 USING (LOCATION-STATE) NAME MYSORT2
*
JOB INPUT (SORT1 KEY (ADDR-STATE), +
SORT2 KEY (LOCATION-STATE)) +
NAME MYPROG FINISH FINISH-PROC
IF MATCHED
COUNT-1 = COUNT-1 + 1
END-IF
*
FINISH-PROC. PROC
DISPLAY COUNT-1
END-PROC
Record Relational Condition
The record relational condition determines the relationship of the current record of a file to the previous and next records
of the same file. This test is valid only for synchronized file processing and single file keyed processing.
This statement has the following format:
Subject
{DUPLICATE} {file-name}
IF [NOT] {FIRST-DUP} {PRIMARY }
{LAST-DUP } {SECONDARY}
• {DUPLICATE}
DUPLICATE is true when the previous or next record has the same key as the current record.
• {FIRST-DUP}
FIRST-DUP is true for the first of two or more records with the same key.
• {LAST-DUP}
LAST-DUP is true for the last of two or more records with the same key.
• Subject
The file-name, PRIMARY, and SECONDARY parameters identify the file to be tested.
The optional NOT parameter reverses the condition.
Example
This example illustrates the use of the record relational condition:
FILE PERSNL FB(150 1800)
%PERSNL
FILE INVENT FB(200 3200)
%INVMSTR
FILE SORT1 FB(150 1800) VIRTUAL
COPY PERSNL
FILE SORT2 FB(200 3200) VIRTUAL
COPY INVENT
COUNT-1 W 3 N VALUE 0
COUNT-2 W 3 N VALUE 0
*
816
CA Easytrieve® Report Generator 11.6
SORT PERSNL TO SORT1 USING (ADDR-STATE) NAME MYSORT1
SORT INVENT TO SORT2 USING (LOCATION-STATE) NAME MYSORT2
*
JOB INPUT (SORT1 KEY (ADDR-STATE) +
SORT2 KEY (LOCATION-STATE)) +
NAME MYPROG FINISH FINISH-PROC
IF DUPLICATE PRIMARY
COUNT-1 = COUNT-1 + 1
END-IF
IF DUPLICATE SORT2
COUNT-2 = COUNT-2 + 1
END-IF
*
FINISH-PROC. PROC
DISPLAY COUNT-1
DISPLAY COUNT-2
END-PROC
CONTROL Statement
The CONTROL statement identifies control fields used for a report. A control break occurs whenever the value of any
control field changes or end-of-report occurs. The control break at end-of-report is equivalent to the final break. A break
level is also assigned to each control field. Comparison of control fields is a logical compare.
You can specify one or more control breaks. If you do not specify any control breaks, a FINAL break is implied.
A break level is assigned to each control field. The system-defined field LEVEL contains the break level used in the
BEFORE-BREAK and AFTER-BREAK report procedures. LEVEL can have the following values:
• 1 when processing the minor field break
• The number of control fields (n) when processing the major field break
• The number of control fields plus one (n+1) when processing the FINAL control break
The system-defined field BREAK-LEVEL contains the break level of the highest field to break.
An alternative to testing the LEVEL and BREAK-LEVEL fields is to use the IF BREAK and IF HIGHEST-BREAK tests.
Coding IF BREAK field-name is equivalent to coding IF LEVEL = x, where x is the break level assigned to field-name.
IF HIGHEST-BREAK performs the same function against the BREAK-LEVEL field. IF BREAK and IF HIGHEST-BREAK
have the advantage of dynamically changing the LEVEL value if fields are added to or removed from the CONTROL
statement. For examples using LEVEL, BREAK-LEVEL, IF BREAK, and IF HIGHEST-BREAK, see the Programming
Guide.
Control fields are compared logically, rather than bit-by-bit. For example, packed fields containing zero with a C sign are
logically equal to zero with an F sign.
In an XML-formatted report, the CONTROL fields represent the hierarchy in the XML output file and all other CONTROL
statement parameters are ignored.
For detailed examples of the CONTROL statement, see Report Processing.
This statement has the following format:
[field-name] [NEWPAGE]
CONTROL [ ] [ ] [NOPRINT]...
817
CA Easytrieve® Report Generator 11.6
[FINAL ] [RENUM ]
• [field-name] or [FINAL]
Prior to the first field-name, you can code FINAL to specify options for the control break at end-of-report. Field-name
specifies any non-quantitative field located in an active file or in a W-type working storage field.
Specify control fields in major to minor order.
NOTE
Varying length, K (DBCS/Kanji), and M (MIXED) fields cannot be specified on a CONTROL statement.
The following three options alter normal processing of a control break:
• [NEWPAGE]
NEWPAGE causes a skip to top-of-page after control break processing is complete for the specified field.
• [RENUM]
RENUM performs the same function as NEWPAGE, and also resets the page number to 1 on the page following the
control break.
• [NOPRINT]
NOPRINT suppresses printing the summary line group for the specified control break. All other control break
processing for the specified control break is performed as usual.
Example
CONTROL FINAL NEWPAGE REGION NEWPAGE BRANCH DEPT
COPY Statement
The COPY statement duplicates the field definitions of a named file.
You can code an unlimited number of COPY statements for any one file. CA Easytrieve® Report Generator duplicates the
fields as if they were coded at the place where CA Easytrieve® Report Generator encounters the COPY statement.
The same rules of field definition apply when using the COPY statement (that is, field names must be unique in a given
file).
This statement has the following format:
{file-name }
COPY { }
{[database-file-name]:record-name}
• file-name
File-name is the name of a previously-defined file whose fields you want to duplicate.
• [database-file-name]:record-name
Record-name is the name of a previously-defined database record whose fields you want to duplicate. Optionally, code
database-file-name for qualification.
Example 1
The following is a COPY statement example:
FILE PERSNL FB(150 1800)
EMPNAME 17 20 A HEADING ('EMPLOYEE NAME')
NAME-LAST EMPNAME 8 A HEADING ('LAST' 'NAME')
NAME-FIRST EMPNAME +8 12 A HEADING ('FIRST' 'NAME')
818
CA Easytrieve® Report Generator 11.6
FILE SORTWRK FB(150 1800) VIRTUAL
COPY PERSNL
SORT PERSNL TO SORTWRK USING +
(NAME-LAST NAME-FIRST) NAME MYSORT
JOB INPUT SORTWRK NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1
LINE NAME-FIRST NAME-LAST
Example 2
This example shows a COPY with IDMS:
FILE DBASE IDMS(DEMOSS03)
RECORD CUSTOMER 104 KEY(CUST-NO)
CUST-NO 1 10 A
CUST-NAME 11 20 A
RECORD SALES 28
SLS-CUST-NO 1 10 A
FILE DDBASE FB(28 280)
COPY SALES (fields from RECORD SALES copied)
JOB INPUT (DNASE) NAME MYPROG
RETRIEVE DBASE +
SELECT (CUSTOMER AREA 'CUSTOMER-REGION' +
SALES ID 'SA' SET 'CUSTOMER-SALES')
IF PATH-ID EQ 'SA'
MOVE LIKE SALES TO DDBASE
PUT DDBASE
ELSE
GO TO JOB
END-IF
CURSOR Statement
The CURSOR statement is used within a screen procedure to set the initial position of the cursor in a field for the next
display of the screen.
You can use the CURSOR statement only within screen procedures (AFTER-SCREEN, BEFORE-SCREEN, INITIATION,
TERMINATION), or within any procedure performed from a screen procedure.
The CURSOR statement must refer to a field on a ROW statement within the screen declaration.
NOTE
Results are unpredictable if:
• Field-name contains the ASKIP, PROTECT, or SENDONLY attributes
• Field-name occurs more than once in a screen
• Two screen fields redefine the same storage area and one is used in the CURSOR statement
Field-name can be subscripted or indexed. However, if the value of the subscript or index changes between the time the
CURSOR statement is executed and the time the screen is actually displayed, the CURSOR positioning is ignored. The
CURSOR statement:
819
CA Easytrieve® Report Generator 11.6
• Overrides cursor placement if a screen field contains the CURSOR attribute.
• Can be executed any number of times before displaying the screen. The last CURSOR statement executed
determines the cursor placement.
• Cannot be moved into an auto-skip (ASKIP) field.
For information about cursor placement hierarchy, see the Programming section.
This statement has the following format:
CURSOR AT field-name
• field-name
Field-name refers to a field on a ROW statement within the screen declaration.
Example
SCREEN NAME SCRN1
ROW 3 WORK-DESCRIPTION
ROW 5 EMP#
. . .
BEFORE-SCREEN. PROC
CURSOR AT EMP#
END-PROC
DECLARE Statement
The DECLARE statement lets you declare named screen attributes and input edit patterns, and to specify how a
subprogram is to be linked. Using declared attributes lets you dynamically change screen attributes during program
execution. Using declared attributes and edit patterns saves you coding time when the set of attributes or edit patterns are
used many times.
An attribute field can be assigned to another attribute field. Patterns and programs cannot be assigned.
Other than the assignment, declared screen attributes can be used only on DEFAULT, TITLE, and ROW statements.
Attributes can also be dynamically changed using the SET statement.
This statement has the following format:
{ATTR [(attribute-list)] }
DECLARE name {PATTERN 'pattern' }
{PROGRAM {STATIC|DYNAMIC}}
• name
Specify a name up to 128 characters for the set of declared screen attributes or set of declared pattern characters.
• ATTR [(attribute-list)]
Specify a list of attribute values. The attribute list must be enclosed in parentheses. For a list and explanations of valid
attributes, see ATTR Parameter.
• PATTERN 'pattern'
PATTERN lets you specify a sequence of characters that describe the format of the data in the field. The character
string must be enclosed in single quotes.
Note: Use PATTERN to edit complex combinations of data types and character sequences. Use the MASK parameter
to edit numeric data.
820
CA Easytrieve® Report Generator 11.6
The valid pattern characters and their meanings are listed in the following table:
Character Meaning
A Represents a lowercase or an uppercase letter.
B Represents a single blank.
D Represents a digit.
E Represents an empty string.
L Represents a lowercase letter.
N Represents an uppercase letter or a national character.
U Represents an uppercase letter.
X Represents any character.
"x" Double quotes surrounding a character or a sequence of
characters literally represent the character or sequence of
characters contained within. The x represents any character. . To
literally represent single or double quotes, use two sets of quotes
within the surrounding set of double quotes ('""""' or '"x""x"', '"''"' or
'"x''x"').
blank Blanks (unless contained in double quotes) serve as delimiters
but are otherwise ignored. They can be inserted into the pattern to
increase readability.
() Represents grouping to control the precedence of operators.
or | or , Represents a choice (or alternation operator).
(m) or (m..n) or (m..*) or (*) or * Represents the repetition of the preceding pattern expression.
The m and n represent numbers and m must be less than n. A
single number with parentheses indicates the exact number of
repetitions. (m..n) represents a range of repetitions, minimum to
maximum. An asterisk in a range, (m..*), represents an infinite
maximum. An asterisk by itself, (*) or *, represents a range from 0
to infinity.
# or /-/ Represents the remove (or toss) operation. This operation applies
only to a single character set at a time and must immediately
follow that character set in the pattern. This operation removes the
character that matched the character set from the data.
+ Represents character set addition to form another character set.
- Represents character set difference to form another character set.
concatenation Concatenation is implied by proximity. For example, DDDU means
3 digits followed by an uppercase letter.
The precedence of operators from highest to lowest:
Grouping: () " "
Set construction: + -
Actions: #
Repetition: (n) (m..n) (m..*) (*)
Concatenation: proximity
Choice: |
The edit pattern is evaluated from left to right (the data from the screen is processed from left to right). Patterns examine
only one character at a time. They do not look ahead and they do not backtrack. For more information, see the CA
Easytrieve® Report Generator Programming Guide.
821
CA Easytrieve® Report Generator 11.6
• PROGRAM {STATIC|DYNAMIC}
PROGRAM lets you specify how you want to link a subprogram. Specify STATIC to indicate that you want the
subprogram to be linked with your CA Easytrieve® Report Generator program. Specify DYNAMIC to indicate that you
want the subprogram to be dynamically loaded. The default is taken from the PARM CALL statement.
Example
DECLARE PROTECT-FIELD ATTR (TURQ PROTECT)
DECLARE VARYING-ATTR ATTR
DECLARE PART-ID PATTERN 'A"-"DDA'
DEFAULT Statement
The DEFAULT statement lets you specify screen-level overrides of system-defined attributes (Format 1) and message
attributes and locations (Format 2).
If used, DEFAULT statements must be the first statements coded in a screen activity.
You cannot code overlapping overrides. For example, the following code is in error because the attribute for
INFORMATION level messages is coded twice:
DEFAULT MESSAGE INFORMATION ATTR BLUE
DEFAULT MESSAGE (INFORMATION WARNING) ATTR GREEN
The following attributes are ignored for TITLE, LITERAL, and KEY:
• CURSOR
• NUMERIC
• INVISIBLE
• MUSTFILL
• MUSTENTER
• TRIGGER
• ALARM
If coded, CA Easytrieve® Report Generator issues a warning message during compilation. All of the above attributes are
also ignored for MESSAGE, except for ALARM.
This statement has the following format:
Format 1
{TITLE }
{FIELD {attribute-name } }
DEFAULT { [ERROR] ATTR { } }
{LITERAL {(attribute-list)} }
{KEY }
Format 2
{ {attribute-name } }
[INFORMATION] {ATTR { } }
DEFAULT MESSAGE ( [WARNING ]...) { {(attribute-list)} }...
[ACTION ] { }
{ROW row-number }
• TITLE
Use TITLE to override attributes for all screen titles (fields and literals) in a screen activity.
822
CA Easytrieve® Report Generator 11.6
Note: You can also override attributes at a title item level. See TITLE Statement.
• LITERAL
Use LITERAL to override attributes for all row literals in a screen activity.
NOTE
You can also override attributes at a screen item level. See ROW Statement.
• FIELD [ERROR]
Use FIELD to override attributes for all row fields in a screen activity. Optionally, specify ERROR to override attributes
for fields flagged in error by the automatic edit process.
NOTE
You can also override attributes at a screen item level. See ROW Statement.
• KEY
Use KEY to override attributes for a function key display area in a screen activity.
• ATTR {attribute-name} or ATTR {(attribute-list)}
Specify either a declared screen attribute name or one or more attribute keywords. For a list of attributes, see ATTR
Parameter. For information about how to declare screen attributes, see DECLARE Statement.
• MESSAGE
Use MESSAGE to override attributes for any or all message levels (INFORMATION, WARNING, ACTION).
• ROW row-number
Use ROW to override the placement of the message level (INFORMATION, WARNING, ACTION). Row-number must
be an unsigned integer that does not exceed the maximum screen size (SCREEN ROWCOUNT) and specifies the row
number on which the message is displayed.
If ROW is not specified, all messages are displayed one line above the key display area, if used. For more information,
see KEY Statement.
Examples
Note the following examples of the message statement.
Example 1
You can use MESSAGE to display INFORMATION level messages in yellow and all other levels of messages in red:
DEFAULT MESSAGE INFORMATION ATTR YELLOW
DEFAULT MESSAGE (WARNING ACTION) ATTR (RED INTENSE)
Example 2
You can override the placement of messages on a screen using the ROW parameter:
SCREEN NAME MENU-SCREEN
DEFAULT FIELD ATTR (TURQ PROTECT)
DEFAULT FIELD ERROR ATTR (RED BLINK ALARM)
DEFAULT MESSAGE (INFORMATION WARNING) ATTR YELLOW ROW 23
DEFAULT MESSAGE (ACTION) ATTR RED ROW 24
DEFINE Statement
The DEFINE statement specifies data fields within a file or within working storage.
You can generate DEFINE statements automatically by using the SQL INCLUDE or IDD statements.
This article contains the following information:
823
CA Easytrieve® Report Generator 11.6
Field Length and Decimal Positions
Use the following table when specifying field-length and decimal-positions:
Data Maximum Number of
Format Length Decimal
Code (bytes) Positions
A 32,767* not valid
K 32,766* not valid
M 32,767* not valid
N 18 0 - 18
P 10 0 - 18
B 8 0 - 10
U 9 0 - 18
I 8 0
* For table file fields, ARG (argument) and DESC (description), the maximum length is 254 bytes.
NOTE
In CICS, the maximum total field length (field-length multiplied by maximum-occurrences) is 32,759.
Format
The DEFINE statement has the following format:
DEFINE +
[file-qualifier:] field-name + } Field Name
{start-location } }
{* [+offset-value] } }
{W } + } Location
{S } }
{[file-qualifier:] overlay-field-name [+offset-value]} }
{field-length {A|M|K|N|P|B|U|I} [decimal-positions] [EVEN]} }
{ } + } Attributes
{[VARYING] [file-qualifier:] model-field-name } }
[UPDATE] + }
}
[HEADING ([#font-number] 'heading-literal' ...)] + }
}
[INDEX (index-field-name)] + }
}
[MASK ({[mask-identifier][BWZ]['mask-literal']|HEX})] + } Characteristics
}
[OCCURS maximum-occurrences] + }
}
[VALUE initial-value] + }
}
[RESET] }
824
CA Easytrieve® Report Generator 11.6
Keyword
• DEFINE
The DEFINE keyword must precede each field definition for definitions outside the library section.
You can omit the DEFINE keyword for fields defined after the associated FILE statement or for working storage fields
defined after any FILE statement.
Field Name
• [file-qualifier:] field-name
File-qualifier identifies the appropriate file, record, or working storage for the field you are defining.
Field-name is the name of the field that you are defining. The field-name:
– Can be from 1 through 128 alphanumeric characters in length
– Can contain any character other than a delimiter
– Must begin with A through Z, 0 to 9, or a national character (#, @, $)
– Cannot be all numeric characters
Location
You must establish the location of the field's leftmost (starting) position in one of the following ways:
• {start-location}
Start-location specifies the starting position relative to position one of the current file or record.
NOTE
Start-location must be specified as an unsigned integer.
• {* [+offset-value]}
The * (asterisk) indicates that the field begins in the next available starting position (highest location defined so far, plus
1). The optional +offset-value is an offset you want added to the * value. There must be at least one blank between the
* and the optional +offset-value.
NOTE
+offset-value must be specified as a positive literal.
• {W} or {S}
Coding W or S establishes a working storage field. S indicates a static working storage field. The product spools W
fields to report (work) files; it does not spool S fields.
NOTE
For more information about working storage fields, see Define Files and Fields.
• {[file-qualifier:] overlay-field-name [+offset-value]}
Specify overlay-field-name if you want an overlay redefinition. If you use overlay redefinition, make sure that field-
name fits within the storage boundaries of overlay-field-name. Overlaying fields with a different data format is allowed
but may result in unexpected results as contents are not revalidated. Any indexes associated with overlay-field-
name also apply to field-name.
Specify the optional file-qualifier if the redefined field is in a file or record other than the file or record currently being
defined.
The optional +offset-value allows you to offset the field from the beginning of overlay-field-name.
Attributes
For each field-name you define, you must specify the field length in bytes, the data format, the number of decimal-
positions (if any), and the optional VARYING parameter for varying length alphanumeric fields.
• {field-length}
Field-length specifies the length (in bytes) of the defined field. Field-length must be an unsigned integer.
• {A|M|K|N|P|B|U|I}
Specify the data format by entering one of the following letters:
825
CA Easytrieve® Report Generator 11.6
– A (alphanumeric) -- Use A when none of the numeric data types applies to the associated field. A-type fields
in files are EBCDIC format, unless the associated file was declared ASCII on the CODE parameter of the PARM
or FILE statement. A-type fields in working storage are either EBCDIC or ASCII, depending on the PARM CODE
PROCESS value.
– M (MIXED alphanumeric) -- (Mainframe only) Use M when you know the data in the associated field is EBCDIC,
DBCS, or a mixture of both. CA Easytrieve processes the field assuming that it contains EBCDIC data. The DBCS
data in this field must be identified by the shift codes in the field's DBCS code system. CA Easytrieve assumes that
the field's DBCS code system is the CA-PSI/DBCS processing code system, unless the field belongs to a file that
has the CODE parameter specified on its FILE statement. This field type is invalid for those DBCS code systems
that do not have an assigned shift code system and cannot support a MIXED field type.
– K (DBCS alphanumeric) -- (Mainframe only) Use K when you know the data in the field is in DBCS format. The
length of the field must be a multiple of two. The data in this field is associated with the DBCS code system defined
as the CA-PSI/DBCS processing code, unless the field belongs to a file that has the CODE parameter specified on
its FILE statement.
– N (zoned decimal) -- Use N when the field contains digits 0 to 9 in external decimal form. For example, 0 = X'F0' in
EBCDIC and X'30' in ASCII.
Note: In the options table, ASCSIGN specifies which system to use to create zoned numeric fields. For more
information, see Compiler Options.
– P (packed decimal) -- Use P when the field contains numbers that meet the IBM definition of internal packed
decimal. For example, the two-byte packed field containing 123 looks like X'123F', and the two-byte packed field
containing -123 looks like X'123D'
– B (binary) -- Use B when the field contains binary data. In a quantitative binary field (a field with zero or more
decimal places specified), the high order bit is the sign bit. In a non-quantitative binary field (a field with no decimal
place specification), the high order bit is a binary digit.
NOTE
Information about signed (quantitative) and unsigned (non-quantitative) fields follows. For rules about
working with signed and unsigned fields, see Programming.
For example, in a one-byte quantitative binary field the following is true:
(HEX) 7F = (BIN) 0111 1111 = (DECIMAL) 127
(HEX) 80 = (BIN) 1000 0000 = (DECIMAL) 128-
For a one-byte non-quantitative binary field, the following is true:
(HEX) 7F = (BIN) 0111 1111 = (DECIMAL) 127
(HEX) 80 = (BIN) 1000 0000 = (DECIMAL) 128
The following table shows the length equivalent and maximum possible values for quantitative binary fields:
Field Length (in Bytes) Digits Maximum Value Minimum Value
1 3 127 128-
2 5 32,767 32,768-
3 7 8,388,607 8,388,608-
4 10 2,147,483,647 2,147,483,648-
5 12 549,755,813,887 549,755,813,888-
6 15 140,737,488,355,327 140,737,488,355,328-
7 17 36,028,797,018,963,967 36,028,797,018,963,968-
8 19 9,223,372,036,854,775,807 9,223,372,036,854,775,808-
826
CA Easytrieve® Report Generator 11.6
The following table shows the length equivalent and maximum possible values for non-quantitative binary fields:
Field Length (in Bytes) Digits Maximum Unsigned Value
1 3 255
2 5 65,535
3 8 16,777,215
4 10 2,147,483,647
5 13 1,099,511,627,775
6 15 281,474,976,710,655
7 17 72,057,594,037,927,935
8 19 9,223,372,036,854,775,807
• U (unsigned packed decimal) -- Use U for packed data where a sign is not needed. For example, a two-byte
unsigned packed field containing 123 looks like X'0123'.
• I (integer) -- The field contains integer-formatted data in the native format of the host environment. The length of an
Integer (I) field must be two, four, or eight bytes. Decimal places must be blank or zero.
Numeric field capacities for signed I fields (quantitative) are:
Field Length (in Bytes) Maximum Value Minimum Value
2 32,767 -32,768
4 2,147,483,647 -2,147,483,648
8 9,223,372,036,854,775,807 -9,223,372,036,854,775,808
Numeric field capacities for unsigned I fields (non-quantitative) are:
Field Length (in Bytes) Maximum Unsigned Value
2 65,535
4 2,147,483,647
8 9,223,372,036,854,775,807
• {[decimal-positions]}
Decimal-positions is an option that specifies the desired number of decimal positions for field-name. Decimal-
positions must be specified as an unsigned integer. If decimal-positions is specified (even if 0), the field is considered
to be quantitative. Otherwise, the field is considered non-quantitative. Quantitative fields are automatically summed on
reports. Decimal-positions cannot be specified for data type A.
• [EVEN]
Use EVEN to indicate that a packed decimal field (P) is to contain an even number of digits. The high order digit is
zero. For example, a two-byte packed even field can only contain two digits, such as X'012F'.
NOTE
EVEN is valid only for P fields.
• [VARYING]
Use VARYING to indicate that field-name is a varying length field. This means that the length of the data in this field,
for each occurrence in separate records, is unique. Varying length fields are alphanumeric and consist of a two-byte
length value followed by the data. VARYING fields typically are used for SQL VARCHAR columns.
NOTE
The VARYING parameter is not supported for M or K fields.
827
CA Easytrieve® Report Generator 11.6
You can specify VARYING on type A fields. When VARYING is specified, the length attribute (field-length) is the total
number of bytes that the varying length field can occupy (two-byte length plus maximum size of data).
You can specify VARYING for file fields or working storage fields. For file fields, the starting position (start-location)
points to the two-byte indicator. For both file fields and working storage fields, overlay redefinition begins with the two-
byte length indicator.
When referencing a VARYING field in your program, you can use field-name alone or suffixed as shown below.
Assume field-name is FLDA:
– FLDA references the entire field (both length and data) as a variable length field
– FLDA:LENGTH references only the length (first two bytes) as a two-byte binary field
– FLDA:DATA references the data portion of the field (from byte three on) as an alphanumeric field
When a VARYING field is displayed in your output, the data window is based on the maximum length of the field (field-
length minus two). The length indicator does not display in output unless DISPLAY HEX is specified.
Length restrictions for varying length fields are as follows:
Field Type Minimum Length Maximum Length
A 3 32769
The default value for a varying field is a string of zero length. However, if the VALUE option is coded, its value and
length become the default for the field.
• {[file-qualifier:] model-field-name}
Optionally, you can specify a field name to use as a model for the field you are defining (field-name). The attributes
used in model-field-name are duplicated for field-name. If model-field-name is in a different file or record, specify the
name of that file. If you use this option, you need not specify attributes for field-name.
Characteristics
• [UPDATE]
Specify UPDATE for each SQL field to be modified. You can specify UPDATE only for fields defined in a CA Easytrieve
SQL file.
NOTE
Only SQL fields specified as UPDATE can be modified by the UPDATE statement.
If UPDATE is specified on the FILE statement, UPDATE is used for all fields defined in the file.
NOTE
You must have UPDATE authorization for the column in the SQL table that this file references.
• [HEADING ([#font-number] 'heading-literal'...)]
The HEADING option specifies an alternative report heading for field-name (the default is the actual field-name).
NOTE
HEADING can be used in the CA Easytrieve Online Screen Painter as a default prompt for field-name.
• [INDEX (index-field-name ...)]
The INDEX option establishes indexes for field-name. You can specify multiple indexes by coding a list of index names
(index-field-name) enclosed in parentheses.
CA Easytrieve automatically allocates a four-byte quantitative binary field for each index. Any references you make to
a field with the INDEX option cause that field's location to be adjusted by the amount contained in index-field-name.
For more information, see the Programming section.
• [MASK ({[mask-identifier][BWZ]['mask-literal']|HEX})]
The optional MASK parameter is used to format field-name for display.
You can use any letter from A to Y as an optional mask-identifier. You can use the letter to identify a new mask or to
retrieve a mask that was previously defined either in the Options Table or by a mask parameter on a previous field
definition. If the new mask that you identify does not already exist, CA Easytrieve retains the mask for future reference.
828
CA Easytrieve® Report Generator 11.6
If you subsequently reference field-name for display, CA Easytrieve automatically uses the associated letter identifier
to determine the edit mask. Do not use the same identifier to establish more than one mask.
The BWZ (blank when zero) option suppresses the display of field-name when it contains all zeros. BWZ can be used
by itself or with other options on the MASK parameter.
– 'mask-literal'
Defines an edit mask and must be enclosed within single quotes. The actual edit mask is coded according to the
rules specified under the MASK Parameter. For more information, see MASK Parameter.
– HEX
Specifies a special edit mask that instructs CA Easytrieve to display the contents of field-name in double-digit
hexadecimal format. You can display fields of up to 50 bytes with the HEX mask.
NOTE
HEX edit masks are not allowed for VARYING fields.
• [OCCURS maximum-occurrences]
The OCCURS option establishes an array for field-name.
Maximum-occurrences specifies the number of elements in the array (the number of occurrences of field-
name). Maximum-occurrences must be specified as an unsigned integer. The maximum value is 32,767. The total
size of the field (length * occurrences) is limited by the FLDMAX option in the options table. For more information on
FLDMAX, see Updating the Table. You can reference the elements of this array by manipulating the INDEX defined for
field-name or by using subscripts. For more information, see the Programming section.
• [VALUE initial-value]
The VALUE option initializes the contents of a field in working storage.
Initial-value can be any valid literal whose type matches the field-name type. If initial-value is non-numeric, it must be
enclosed in single quotes. The maximum length for initial-value is 254 bytes.
If the initial-value does not match the length of field-name, it is truncated or padded according to assignment rules.
• [RESET]
Use RESET only for W working storage fields. When you code RESET on the field definition for a W field, RESET
returns the field to its initial value whenever a JOB, SCREEN, or SORT is executed. You can use RESET with
OCCURS for array fields but not for redefined fields (fields having overlay redefinition). When you use RESET on
multiple fields, the fields are reset in the order of the field definitions.
NOTE
When W working fields are referenced in report processing, a RESET is not performed during the printing of
spooled reports.
Examples
The DEFINE statement specifies data fields within a file or within working storage. You usually specify file fields and work
fields in your CA Easytrieve library section, but you can also define them within an activity, as the following examples
illustrate.
Example 1: DEFINE Statement in the Library Section
{ FILE PERSNL FB(150 1800)
Library { DEFINE EMP# 9 5 N
{ DEFINE EMPNAME 17 20 A
{ DEFINE EMP-COUNT W 4 N
*
{ JOB INPUT PERSNL NAME MYPROG
{ EMP-COUNT = EMP-COUNT + 1
Activities { PRINT REPORT1
*
{ REPORT REPORT1
829
CA Easytrieve® Report Generator 11.6
{ LINE EMP# EMPNAME EMP-COUNT
Example 2: DEFINE Statement in an Activity
{ FILE PERSNL FB(150 1800)
Library { SALARY-CODE 134 2 N
{ *
{ JOB INPUT PERSNL NAME MYPROG
{ DEFINE EMP# 9 5 N
{ DEFINE EMPNAME 17 20 A
Activities { PRINT REPORT1
{ *
{ REPORT REPORT1
{ LINE EMP# EMPNAME SALARY-CODE
When fields are defined in an activity, each field definition must start with the DEFINE keyword and physically be defined
before the field is referenced. In the library section, the use of the DEFINE keyword is optional.
Record Description
The examples below illustrate two ways of describing a record from a personnel file. The first method uses an asterisk (*)
to define the starting location of the fields. The second method uses absolute starting positions. In this case, both methods
result in the same description. The DEFINE keyword is not needed when the field definitions immediately follow the FILE
statement.
Method 1
FILE PERSNL FB(150 1800)
REGION * 1 N
BRANCH * 2 N
SSN * 5 P
EMP# * 5 N
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1
LINE EMP# REGION BRANCH
Method 2
FILE PERSNL FB(150 1800)
REGION 1 1 N
BRANCH 2 2 N
SSN 4 5 P
EMP# 9 5 N
JOB INPUT PERSNL NAME MYPROG
830
CA Easytrieve® Report Generator 11.6
PRINT REPORT1
*
REPORT REPORT1
LINE EMP# REGION BRANCH
Working Storage Initialization
CA Easytrieve initializes numeric work fields to zeros and alphabetic work fields to blanks. To initialize these fields to other
values, use the VALUE parameter, as shown below:
DEFINE CURRENT-MONTH W 10 A VALUE 'JANUARY'
To reinitialize the field each time a JOB, SORT, or SCREEN activity is executed, add the RESET parameter.
Varying Length Fields
The VARYING parameter on the DEFINE statement designates varying length fields. An example of a varying length field
definition is as follows:
FLDA W 250 A VARYING
Because VARYING is used, this W type work field has two parts that are internally defined as follows:
W 2 B 0 forthetwo-bytefieldlength
W 248 A forthedata
Alternative Report Headings
The default report heading for a field is the field name. You can override this default by using the HEADING parameter, as
shown in the following example:
FILE PERSNL FB(150 1800)
EMP# 9 5 N HEADING('EMPLOYEE' 'NUMBER')
PAY-NET 90 4 P2 HEADING('NET' 'PAY')
PAY-GROSS 94 4 P2 HEADING('GROSS' 'PAY')
WORK-FIELD W 4 P2 HEADING('AMOUNT' 'OF' 'TAXES')
Edit Masks
To add an edit mask to a telephone number, use the MASK parameter:
DEFINE PHONE S 10 N MASK '(999) 999-9999'
Arrays
The following example defines an array. There are 10 occurrences of the 2-byte numeric field, ELEMENT, in the array.
When the array field is used to define the entire array, ARRAY can be used to refer to the entire storage area.
DEFINE ARRAY W 20 A
DEFINE ELEMENT ARRAY 2 N 0 OCCURS 10
For more information about array processing, see Array Processing.
DELETE Statement
Use the DELETE statement to delete a specific row from a CA Easytrieve® Report Generator SQL file.
831
CA Easytrieve® Report Generator 11.6
DELETE performs a DELETE WHERE CURRENT OF cursor. The file must be defined with the UPDATE parameter. For
more information about SQL database processing, see the Programming Guide.
Note: DELETE WHERE CURRENT OF cursor cannot be dynamically processed by the SQL interface for CA IDMS. To
perform SQL deletes, you must code native SQL statements using a searched delete statement.
This statement has the following format:
DELETE [FROM] file-name
• [FROM]
Optionally, code FROM for statement readability.
• [file-name]
File-name must be the name of a CA Easytrieve® Report Generator SQL file.
Example
The following example selects a specific row from the table, and then deletes it:
FILE PERSNL SQL (PERSONNEL) UPDATE
EMPNAME * 20 A
WORKDEPT * 2 P O
EMPPHONE * 3 P O
PROGRAM NAME RETRIEVE-PERSONNEL
SELECT FROM PERSNL WHERE EMPNAME = 'ROGERS PAT'
FETCH FROM PERSNL
IF EOF PERSNL
DISPLAY 'EMPLOYEE NOT FOUND'
ELSE
DELETE FROM PERSNL
END-IF
DISPLAY Statement
The DISPLAY statement formats and transfers data to the system output device or to a named file. You can code
DISPLAY to transfer printed data to the system output device, or you can optionally code a file name after DISPLAY to
cause data to be printed to the named file. The DISPLAY statement has three formats; Format 3 can only be used when
the file is associated with an extended reporting printer.
Unless you specify relative or absolute positioning, the first data entry of each DISPLAY statement begins in column 1 of
the print line. Each data entry that follows is printed next to the preceding entry. For HEX displays, the output is printed
five lines per 100 bytes of the record or field.
When you use DISPLAY in REPORT procedures, output is always in the appropriate place in the report. However, when
you use DISPLAY in a JOB activity, the output can be interspersed with the first unsequenced report if no file-name is
specified.
Data displayed to an output file is in an edited format. DISPLAY is not valid for nullable fields, but DISPLAY HEX is valid.
This statement has the following format:
Format 1
[display-file-name] [{TITLE|NOTITLE} ]
DISPLAY [ ] [SKIP skip-integer ] +
832
CA Easytrieve® Report Generator 11.6
[SYSPRINT ] [CONTROL 'carriage-control-character']
[ [ ]field-name]
[ [#font-number] ]
[ [ ]'literal' ]
[+offset ] ...
[-offset ]
[COL column-number ]
[POS position-number ]
Format 2
[display-file-name] [{TITLE|NOTITLE} ]
DISPLAY [ ] [SKIP skip-integer ] +
[SYSPRINT ] [CONTROL 'carriage-control-character']
{file-name }
HEX {field-name }
{record-name}
Format 3
[display-file-name] [ ]
DISPLAY [ ] [CONTROL 'control-literal']
[SYSPRINT ] [ ]
Format 1
• [display-file-name] or [SYSPRINT]
When you specify display-file-name, CA Easytrieve® Report Generator prints data to the named file. The named file
should be designated as a PRINTER file or unpredictable results can occur. If you do not specify display-file-name, the
default is SYSPRINT. SYSPRINT implies the system output device. The actual destination of SYSPRINT is determined
by the environment or a site option. For more information, see your system administrator.
• [{TITLE|NOTITLE}]
The TITLE option specifies that a skip to a new page occurs before the data is printed. It also produces any titles and
headings if coded in a report procedure. If not coded in a report procedure, no titles are produced.
NOTITLE specifies that a skip to a new page occurs but titles and headings are not produced.
• [SKIP skip-integer]
The SKIP skip-integer option specifies the number of lines skipped before printing data. When skip-integer is zero, the
current line being displayed overlays the previous line output to display-file-name.
• [CONTROL 'carriage-control-character']
The CONTROL 'carriage-control-character' option sets the print carriage control character for the print line. Valid
alphanumeric values for 'carriage-control-character' are 0 to 9, +, -, A, B, or C. Depending on the make and model of
impact printer used, these characters select a precoded channel on a carriage control tape that determines print line
positions associated with the form to be printed.
When display-file-name is associated with an extended reporting printer, the printer must support ANSI or machine
carriage controls. For more information, see the User Guide.
Note: This parameter is not valid for use in REPORT procedures.
• [#font-number]
#font-number identifies the font that CA Easytrieve® Report Generator uses for the next display item. You can specify
this option only if display-file-name has been associated with an extended reporting printer. #font-number identifies the
833
CA Easytrieve® Report Generator 11.6
number of a font defined for the extended reporting printer assigned to receive the print output. If you do not code the
font index, then the next display item uses the default font for the assigned extended reporting printer.
• [field-name] or ['literal']
Code field-name or 'literal' in the order you want them to appear on the printed line.
Note: K fields are not valid on a DISPLAY statement.
• [+offset] or [-offset]
Use the space adjustment options to add (+offset ) or subtract (-offset) horizontal line spaces preceding the next
display item.
Note: ±offset does not extend space beyond the left and right margin set points.
• [COL column-number]
The COL column-number option specifies the absolute print column number on which CA Easytrieve® Report
Generator begins to print the next display item. Column-number can be any value that does not extend beyond the line
margins.
Note: When using an extended reporting printer, an error occurs if two or more fields or literals overlap. For more
information, see the Programming Guide.
• [POS position-number]
The POS position-number option coded in a DISPLAY statement within report procedures causes the next display item
to be left-justified under the corresponding position-number item in the LINE 01 statement.
Note: When using an extended reporting printer, an error occurs if two or more fields or literals overlap. For more
information, see the Programming Guide.
Format 2
• HEX {file-name} or HEX {field-name} or HEX {record-name}
CA Easytrieve® Report Generator produces a hexadecimal and character dump of the current file-name or field-name,
whichever you specify. For CA IDMS files, record-name refers to any record (segment); file-name refers to all records
(segments).
Note: HEX file-name cannot be used in REPORT procedures.
Format 3
You can use this format of the DISPLAY statement only when display-file-name is associated with an extended reporting
printer. A syntax error occurs if display-file-name is not an extended reporting printer. For more information about
extended reporting, see the Programming Guide.
• [CONTROL 'control-literal']
You can use the CONTROL parameter to output printer control records. 'Control-literal' can be an alphanumeric or
hexadecimal literal that CA Easytrieve® Report Generator outputs to the print file without paper control information.
These control cards contain instructions to extended reporting printers. Print control records for some printing systems
define the specification of the font sets that CA Easytrieve® Report Generator uses for a particular report. These
control cards can be output to the print data set before a report that uses the loaded font sets.
Examples
Format 1
The following example illustrates the use of Format 1 of the DISPLAY statement:
FILE BADKEYS FB(150 1800) TERMINAL
FILE PERSNL INDEXED
%PERSNL
FILE INKEYS
WHO * 5 N
JOB INPUT INKEYS NAME MYPROG
READ PERSNL KEY WHO STATUS
IF NOT PERSNL
834
CA Easytrieve® Report Generator 11.6
DISPLAY BADKEYS 'BAD KEY =' +1 WHO
GOTO JOB
END-IF
When executed, the statements in this example produce the following output:
BAD KEY = 00973
Format 2
The following example illustrates the use of Format 2 of the DISPLAY statement:
FILE PERSNL INDEXED
%PERSNL
FILE INKEYS
WHO * 5 N
JOB INPUT INKEYS NAME MYPROG
READ PERSNL KEY WHO
DISPLAY SKIP 2 HEX PERSNL
When executed, the statements in this example produce the following output:
CHAR 104 G 01963 7ARNOLD LINDA 1569 COLONIAL TERR ANEW YORK NY10012 @ 911
ZONE FFF21683FFFFF44FCDDDDC44DCDCC4444444FFFF4CDDDDCCD4ECDD4CDCE4EDDD4444DEFFFFF4444444444444403670450FFF
NUMR 1048327C019630071956340039541000000015690363659130359901556086920000581001200000000000000058C045C911
1...5...10...15...20...25...30...35...40...45...50...55...60...65...70...75...80...85...90...95..100
CHAR 082942 21245140401S 1001101968
ZONE 44FFFFFF44444444FFFFFFFFFFFE444FFFFFFFFFF444444444
NUMR 00082942000000002124514040120001001101968000000000
101...5...10...15...20...25...30...35...40...45...50
DLI Statement
The DLI statement provides controlled input/output of an IMS/DLI database. You can use the DLI statement in conjunction
with (or independently of) the automatic input associated with RETRIEVE. You can code the DLI statement at any place
in a JOB activity that an input/output statement for any other file can be coded. This statement provides complete control
over the creation and maintenance of a database.
There are six different formats for the DLI statement:
Format 1
{io-record-name} {'function-literal' }
DLI file-name { } { } +
{io-field-name } {function-field-name}
[ ] [ {'search-value-literal' } ]
[SSANO ssa-number ] [SSA { } ] ...
[ ] [ {search-value-field-name} ]
Format 2
{CHKP} {'seg-len-literal' }
835
CA Easytrieve® Report Generator 11.6
DLI { } { } id-field-name +
{XRST} {seg-len-field-name}
[ {'checkpoint-len-literal' } ]
[ { } checkpoint-field-name ] ...
[ {checkpoint-len-field-name} ]
Format 3
DLI CHKP id-field-name
Format 4
DLI file-name FOR ACCESS
Format 5
{'psb-name-literal' }
DLI PCB { }
{psb-name-field-name}
Format 6
DLI TERM
This section describes the parameters for each of the six formats of the DLI statement.
Format 1
• file-name
File-name identifies the database being processed. File-name is the same as the name coded on the FILE file-
name statement that identifies the DBD to be processed.
• {io-record-name} or {io-field-name}
Io-record-name or io-field-name identifies the input/output area that is to receive the data. Io-record-name must be
the same as a corresponding segment-name coded on a RECORD statement. Io-field-name can only be a working
storage field. In either case, the area specified must be large enough to contain the longest segment retrieved from the
database.
• {'function-literal'} or {function-field-name}
You can specify any IMS/DL/I function code whose parameter requirements conform to Format 1. The function code
can be specified as either an EBCDIC alphabetic literal ('function-literal') or an alphanumeric function-field-name that
contains a four-byte alphabetic code. Valid function codes (for example, GNP) are described in IBM's IMS/DL/I
Application Programming publications.
• [SSANO ssa-number] or [SSA {'search-value-literal'}] or [SSA {search-value-field-name}]
Code the optional SSANO and SSA parameters when the database activity to be performed cannot be satisfied
without using segment search arguments. SSANO identifies a function-field-name that represents a four-byte binary
field. Function-field-name can be set dynamically to control the number of SSAs used in database system calls. This
value overrides the assumed number, which is equal to the count of SSA parameter entries.
The SSA parameter supplies segment search argument values. You can code the SSA values as search-value-field-
name or an alphabetic literal ('search-value-literal'). The SSA value must contain the segment search argument in the
exact form required by IMS/DL/I. If search-value-field-name contains DBCS data, the DBCS code system of search-
value-field-name must equal the DBCS code system of file-name.
Note: Multiple search value literals or search value field names must be enclosed in parentheses.
Format 2
Use Format 2 of the DLI statement to perform a symbolic checkpoint/restart. You must specify the compatibility option
(COMPAT=YES) for the PSB being processed; this option generates a dummy PCB that acts as an I/O PCB during
checkpoint/restart processing. Test CHKP-STATUS to determine the results of the call. For more information about CHKP-
836
CA Easytrieve® Report Generator 11.6
STATUS, see the chapter "File Processing" in the Programming Guide. For more information about symbolic checkpoint/
restart, see IBM's IMS/DL/I Application Programming publications.
• {CHKP} or {XRST}
Code CHKP to perform symbolic checkpoint or XRST to perform a symbolic restart.
• {'seg-len-literal'} or {seg-len-field-name}
'Seg-len-literal' or seg-len-field-name specifies the length of the longest segment (or path of segments) in the PSB.
'Seg-len-literal' must be a four-byte binary field.
• [id-field-name]
Id-field-name must identify a 12-byte area in working storage. The first eight bytes of this area contain the checkpoint
ID. You should set the 12-byte area to spaces before performing the DLI XRST operation, then test it after performing
the operation. If your program is being started normally, the area will still contain spaces. If your program is being
restarted from a checkpoint, the area will contain the checkpoint ID that you supplied during the DLI CHKP operation
and in the restart JCL.
Optionally, you can also specify up to seven checkpoint areas in working storage that are saved during each
checkpoint and restored during a restart.
• {'checkpoint-len-literal' } or {checkpoint-len-field-name}
'Checkpoint-len-literal' or checkpoint-len-field-name specifies the length of the checkpoint area defined by checkpoint-
field-name. Checkpoint-len-field-name must be a four-byte binary field.
• [checkpoint-field-name]
Checkpoint-field-name must identify a field in working storage. The length of this checkpoint area is specified
by checkpoint-len-field-name or 'checkpoint-len-literal'.
A checkpoint can be taken on a maximum of seven areas.
Format 3
Use Format 3 of the DLI statement to perform a basic checkpoint. For IMS, you must specify the compatibility option
(COMPAT=YES) for the PSB being processed; this option generates a dummy PCB that acts as an I/O PCB during
checkpoint processing. Test CHKP-STATUS to determine the results of the call. For more information of CHKP-STATUS,
see the chapter "File Processing" in the Programming Guide. For more information about basic checkpoints, see IBM's
IMS/DL/I Application Programming publications.
• CHKP
CHKP causes a basic checkpoint to be performed.
• id-field-name
Id-field-name must identify an 8-byte area in working storage. This area contains the checkpoint ID.
Format 4
Use Format 4 of the DLI statement when you are calling a subprogram (such as a COBOL program) that accesses DL/I
records. Coding this statement before referencing DLI fields causes the fields to become available for processing.
• DLI file-name FOR ACCESS
File-name refers to a CA Easytrieve® Report Generator file definition containing the appropriate PCB field, record, and
record field definitions.
Format 5
Use Format 5 to schedule a PSB. Format 5 is used for CICS execution only. In other environments, it is ignored. Any
program that executes under CICS must schedule the PSB before accessing any PSB, including programs that are
accessing DL/I with the RETRIEVE statement. For activities that use the RETRIEVE statement, the PSB must be
scheduled in a JOB START proc, or in a previously-executed activity. When a PSB is scheduled, it stays scheduled until
one of the following occurs:
• Task termination
• Syncpoint
• Execution of the DLI TERM statement (see Format 6)
837
CA Easytrieve® Report Generator 11.6
Test the UIBFCTR and UIBDLTR system-defined fields to determine the results of the operation. For more information
about scheduling PSBs and the values of UIBFCTR and UIBDLTR, see IBM's IMS/DL/I Application Programming
publications.
• {'psb-name-literal'} or {sb-name-field-name}
'Psb-name-literal' or psb-name-field-name specifies the PSB to be scheduled. The maximum length of a PSB name is
eight bytes.
Format 6
Use Format 6 to terminate a PSB. Format 6 is used only for CICS execution. In other environments, it is ignored. Test
the UIBFCTR and UIBDLTR system-defined fields to determine the results of the operation. For more information about
scheduling PSBs and the values of UIBFCTR and UIBDLTR, see IBM's IMS/DL/I Application Programming publications.
DO UNTIL and DO WHILE Statements
The loop control statements DO UNTIL, DO WHILE, and END-DO control and delimit repetitive program logic.
DO WHILE
The truth value of the conditional expression determines whether statement-1 to statement-n are executed. Statement-1
... statement-n represents any number of CA Easytrieve Report Generator statements. When the conditional expression
is true, the statements are executed and the program branches back to test the conditional expression. The program
continues to loop as long as the conditional expression is true. When the conditional expression is false, the program
branches to the statement following END-DO.
DO UNTIL
Statement-1 to statement-n are executed. The truth value of the conditional expression determines whether the group of
statements are executed again. When the conditional expression is true, the program branches to the statement following
the END-DO. When the conditional expression is false, the program branches back to execute the statements. The
program continues to loop until the conditional expression is true.
This statement has the following format:
{WHILE}
DO { } conditional-expression
{UNTIL}
statement-1
...
statement-n
END-DO
The following diagram illustrates DO and END-DO statement logic:
838
CA Easytrieve® Report Generator 11.6
• {WHILE} or {UNTIL}
A WHILE loop evaluates the condition at the top of a group of statements. An UNTIL loop evaluates the condition at
the bottom of a group of statements.
• conditional-expression
Specify the condition that is the basis for the continuing execution of the loop. For conditional expression syntax, see
Conditional Expressions in the chapter "Statements A - C."
• END-DO
END-DO terminates the body of the loop associated with the DO statement. An END-DO statement must be specified
after each DO statement and its associated statements.
Examples
DO UNTIL statement example:
FILE FILEA
ELEMENT 1 10 A OCCURS 10
CTR W 2 N
JOB INPUT FILEA
CTR = 1
DO UNTIL CTR > 10
839
CA Easytrieve® Report Generator 11.6
DISPLAY ELEMENT (CTR)
CTR = CTR + 1
END-DO
DO WHILE loop nesting example:
DEFINE COUNT-1 W 3 N VALUE 0
DEFINE COUNT-2 W 3 N VALUE 0
DEFINE RESULT W 3 N VALUE 0
*
JOB INPUT NULL NAME MYPROG
DO WHILE COUNT-1 LT 10
COUNT-1 = COUNT-1 + 1
COUNT-2 = 0
DO WHILE COUNT-2 < 10
COUNT-2 = COUNT-2 + 1
RESULT = COUNT-1 * COUNT-2
DISPLAY 'COUNT-1= ' COUNT-1 ' COUNT-2= ' COUNT-2 +
' RESULT= ' RESULT
END-DO
END-DO
STOP
ENDPAGE Report Procedure
An ENDPAGE procedure can be used to produce page footing information. It is invoked whenever end-of-page is
detected.
An ENDPAGE procedure must be delimited by an END-PROC statement. For more information, see PROC Statement in
the chapter "Statements N - R."
This statement has the following format:
ENDPAGE. PROC
Example
ENDPAGE is typically used to produce page totals or other annotations, as in the following example of page footer
annotation:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
840
CA Easytrieve® Report Generator 11.6
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
ENDPAGE. PROC
DISPLAY SKIP 2 '* CONFIDENTIAL - FOR INTERNAL USE ONLY *'
END-PROC
*
END-PROC Statement
The END-PROC statement delimits the statements in a procedure. A procedure is a group of user-written CA Easytrieve®
Report Generator statements designed to accomplish a particular objective.
For more information, see PROC Statement in the chapter "Statements N - R."
This statement has the following format:
END-PROC
ENDTABLE Statement
ENDTABLE is used to delimit instream data used to create small tables. ENDTABLE must be coded in the first eight
positions of the source statement. The ninth position must be blank.
All data required to create an instream table file must be coded between the definition statements and the ENDTABLE
statement.
If the table data is to be stored in a macro, you must store the entire table definition from the FILE statement to the
ENDTABLE statement.
This statement has the following format:
ENDTABLE
Example
FILE DAYTABL TABLE INSTREAM
ARG 1 1 A. DESC 3 9 A
1 SUNDAY
2 MONDAY
...
7 SATURDAY
ENDTABLE
EXECUTE Statement
The EXECUTE statement invokes a JOB, SORT, or SCREEN activity from either a PROGRAM or SCREEN activity.
The EXECUTE statement transfers control to an activity. After the activity is executed, control returns to the next
executable statement following the EXECUTE. You cannot invoke a JOB, SORT, or SCREEN activity in a JOB or SORT
activity.
EXECUTE statements in a SCREEN activity can invoke other activities. This is called activity nesting. However, recursion
is not permitted. That is, activity A can EXECUTE activity B, but activity B cannot then EXECUTE activity A.
841
CA Easytrieve® Report Generator 11.6
NOTE
Recursion cannot be detected in the program. If it is attempted, unpredictable results can occur.
You can use the EXECUTE statement to invoke multiple stacked windows from a SCREEN activity. When each stacked
window terminates with an EXIT, the full screen image is restored to the screen image that existed before the EXECUTE.
An EXIT from the primary screen does not restore the screen.
This statement has the following format:
EXECUTE {job-name|sort-name|screen-name}
• {job-name|sort-name|screen-name}
Identifies the JOB, SORT, or SCREEN activity to be executed.
Example
PARM-FIELD W 5 A
PROGRAM NAME SAMPLE-PROGRAM USING PARM-FIELD
IF PARM-FIELD = 'DAILY'
EXECUTE DAILY-JOB
ELSE
EXECUTE WEEKLY-JOB
END-IF
JOB NAME DAILY-JOB
. . .
JOB NAME WEEKLY-JOB
EXIT Statement
The EXIT statement terminates a SCREEN activity.
When an EXIT statement is encountered and the SCREEN activity was invoked from a PROGRAM or SCREEN activity,
control is returned to the statement following the EXECUTE statement.
If a SCREEN activity was invoked by an implied PROGRAM activity, EXIT terminates the program.
EXIT is a branch action that can be invoked directly by pressing a particular attention key. For more information, see KEY
Statement in the chapter "Statements G - M."
This statement has the following format:
EXIT
Example
SCREEN NAME MENU
KEY F3
...
AFTER-SCREEN. PROC
IF KEY-PRESSED = F3
EXIT
END-IF
END-PROC
842
CA Easytrieve® Report Generator 11.6
FETCH Statement
The FETCH statement is used to retrieve rows from an SQL file.
The FETCH statement retrieves rows from the open cursor and places the data in the file's data area. If the file does not
have an open cursor associated with it, the cursor previously selected is reopened. If no cursor was previously selected,
the default cursor (SELECT all defined fields FROM table) is opened.
You cannot use controlled statements (SELECT, FETCH, CLOSE) in a SORT or REPORT procedure.
The FETCH statement cannot reference an automatic input file in the same JOB activity. You can FETCH from a file other
than the automatic input file.
This statement has the following format:
FETCH [FROM] file-name
• [FROM]
Optionally, code FROM for statement readability.
• file-name
File-name is the name of a CA Easytrieve® Report Generator SQL file.
Example
Following is an example of a PROGRAM activity that uses a default cursor:
FILE PERSNL SQL (PERSONNEL)
EMPNAME * 20 A
WORKDEPT * 2 P 0
PROGRAM NAME RETRIEVE-PERSONNEL
FETCH FROM PERSNL
DO UNTIL EOF PERSNL
DISPLAY EMPNAME +2 WORKDEPT
FETCH FROM PERSNL
END-DO
The above PROGRAM activity simply fetches each row of the table and displays the fields. The DO loop repeats the
process until end-of-file.
FILE Statement
FILE statements must describe all files that your program references. You can also access SQL, CA IDMS, and IMS/DL/
I databases using CA Easytrieve Report Generator files. Code FILE statements at the beginning of a program after the
PARM statement, if one is used. Not all parameters are necessary (or valid) for describing any one file. A review of all
parameters will quickly indicate those required for any particular file.
Code the optional parameters and subparameters of the FILE statement in any order following the file name. As shown,
you must code multiple subparameters within parentheses. The complete syntax of the FILE statement is shown below.
To maintain compatibility of programs using VSAM files that were written in prior versions of the product, CA Easytrieve
Report Generator supports FILE statements containing VS and its related keywords (as follows):
FILE file-name VS ([ES] [F] [PASSWORD 'literal'] +
CREATE [RESET|UPDATE] [NOVERIFY]
For more information about using the FILE statement, see the Programming section.
843
CA Easytrieve® Report Generator 11.6
This statement has the following format:
FILE filename +
[SEQUENTIAL [CREATE [RESET]] ] }
[INDEXED [UPDATE ] ] + }
[RELATIVE ] }
[SQL ([owner-name.] table-name [correlation-name]{,}...) ] } File
[IDMS (subschema-name [RESET]) ] } Type
[ {relative-position } ] }
[DLI ({ }[RESET]) ] }
[ {dbd-name[relative-occurrence]} ] }
[ {'password-literal' } ]
[PASSWORD { } ] +
[ {password-field-name} ]
[NOVERIFY] +
[ [ {parm-literal } ] ]
[EXIT (program-name [USING ( { } ...) ] [MODIFY]) ] +
[ [ {parm-field-name} ] ]
[CARD ] }
[PUNCH ] } Device
[PRINTER [([PAGESIZE (line-page-size [display-page-size]) + ] } Type
[ [LINESIZE line-length])] ] }
[F [record-length] ] }
[ ] }
[V [record-length] ] }
[ ] }
[ [block-length] ] }
[U [FULLTRK ] ] }
[ ] }
[FB [ (record-length [block-length] ) ] + } Record
[ [ [FULLTRK ] ] ] } Format
[ ] }
[VB [ (record-length [block-length] ) ] ] }
[ [ [FULLTRK ] ] ] }
[ }
[VBS [ (record-length [block-length] ) ] ] }
[ [ [FULLTRK ] ] ] }
[WORKAREAarea-length] +
[ [INSTREAM ] ]
[TABLE [ ] ] +
[ [max-table-entries] ]
[BUFNObuffers] +
[DEFER] +
844
CA Easytrieve® Report Generator 11.6
[ASA] +
[EXTENDEDxrpt-printer] +
[CODE {EBCDIC|ASCII|dbcs-code-name}] +
[KEYkey-field-name] +
[ {'file-identifier' } ] }
[SYSNAME { } ] }
[ {file-identifier-field-name} ] }
[ ] }
[ [MEMORY] ] }
[VIRTUAL ([RETAIN] [DISK ] ) ] }
[ ] }
[ [ {'terminal-id-literal' } ] ] }
[TERMINAL ([ID { } ] + ] }
[ [ {terminal-id-field-name} ] ] }
[ ] }
[ [NOFORMFEED] + ] }
[ ] }
[ [ [BEFORE] ] ] } Data
[ [NEWPAGE [AFTER ] ]... ) ] } Set
[ ] } Type
[ [ {'spool-class-literal' } ] ] }
[SPOOL ( [CLASS { } ] + ] }
[ [ {spool-class-field-name} ] ] }
[ ] }
[ [ {'destination-literal' } ] ] }
[ [NODE { } ] + ] }
[ [ {destination-field-name} ] ] }
[ ] }
[ [ {'user-id-literal' } ] ] }
[ [USERID { } ] ) ] }
[ [ {user-id-field-name} ] ] }
• file-name (return to top)
File-name is a 1- to 128-character name used to define the file to CA Easytrieve® Report Generator. All statements
that operate on the file refer to this name. Every FILE statement must have a file-name immediately following the FILE
keyword. File-names must be unique in the program (that is, you can use a given file-name for only one file). The first
three characters of file-name must be different from the value of the work data set name prefix specified in the Site
Options Table (normally EZT).
For the relationship between a FILE statement and an external data set, see the SYSNAME parameter under Data Set
Types in this article.
File Types
CA Easytrieve Report Generator processes all standard file types available in the operating environment. On a
mainframe, this includes QSAM (Queued Sequential Access Method); VSAM (Virtual Storage Access Method); SQL;
printer files directed to an online printer, terminal, or the operating system spooling subsystem (JES2 or JES3 in z/OS and
POWER in VSE); CA IDMS and IMS/DL/I database files; and the CA Easytrieve Report Generator Virtual File Manager
(VFM). On non-mainframe platforms, these include fixed length sequential, variable length sequential (new-line delimited),
indexed, relative, VFM, and SQL database files. If you do not specify a file type, the file is assumed to be sequential.
• [SEQUENTIAL] (return to top)
845
CA Easytrieve® Report Generator 11.6
SEQUENTIAL designates a QSAM or VSAM Entry Sequenced Data Set (ESDS) on a mainframe. On other platforms,
the file can be a fixed length or a variable length (new-line delimited) file. SEQUENTIAL is the default file type if a file
type is not specified.
Note: When SEQUENTIAL is specified, FILE-STATUS (a system-defined field) is available for the file.
• [INDEXED] (return to top)
INDEXED designates a VSAM Key Sequenced Data Set (KSDS) or an ISAM file on a non-mainframe platform.
• [RELATIVE] (return to top)
RELATIVE designates a mainframe VSAM Relative Record Data Set (RRDS), or a relative file on non-mainframe
platforms.
• [SQL] ([owner-name.] table-name [correlation-name] {,} ...) (return to top)
The SQL parameter designates an SQL file. This parameter enables the product to manage the SQL cursor.
NOTE
• Only UPDATE, DEFER, and CODE are valid FILE statement parameters for an SQL file.
Table-name is the name of the SQL table to be accessed. Optionally, qualify the table with owner-
name. Table-name must be enclosed in parentheses.
Correlation-name is the name used to clarify or simplify the table to which a column belongs. If you
specify owner-name and your DBMS does not permit more than one level of qualification (CA IDMS,
Ingres, or Oracle), you should code a correlation-name for each table.
• The comma is a required separator.
When you specify SQL, the file can be used as the subject of either automatic input or controlled
processing using the SELECT, FETCH, CLOSE, INSERT, UPDATE, and DELETE statements. These
statements support full read-write access to the tables but you do not have to declare, open, and close
cursors to manage the tables. Multiple tables for a single file are joined for inquiry only.
• [IDMS (subschema-name [RESET]) (return to top)
IDMS designates the file as a CA IDMS database file.
Subschema-name is a one- to eight-character name that specifies the subschema to be processed.
The optional RESET subparameter requests that all records under control of RETRIEVE be reset to binary zero
immediately prior to retrieving each root record.
When the first IDMS FILE statement is encountered, a CA IDMS Communications Block is created in working storage.
For more information about CA IDMS processing, see the CA IDMS Database Processing section.
Note: Fields cannot be defined in association with the IDMS FILE statement. Fields are defined following the RECORD
or ELEMENT-RECORD statement.
• DLI ({relative-position} [RESET]) or DLI ({dbd-name[relative-occurrence]} [RESET]) (return to top)
(Mainframe only) DLI designates the file as an IMS/DL/I database file.
Relative-position is a positive numeric literal that identifies the relative position of the PCB within the PSB to be
processed.
Dbd-name specifies the name of the DBD. Relative-occurrence is the relative occurrence of like-name DBDs in the
PSB. It is required only if two or more DBDs have the same name.
The optional RESET subparameter requests that all records under control of RETRIEVE be reset to binary zero
immediately prior to retrieving each root record.
For more information, see IMS/DL/I Database Processing.
• [CREATE [RESET]] (return to top)
Use CREATE to load the associated file.
(Mainframe only) If you specify RESET, CA Easytrieve® Report Generator overwrites an existing data set with the
REUSE attribute. If RESET is not specified, or if RESET is specified and the associated VSAM data set does not have
the REUSE attribute, then CA Easytrieve® Report Generator receives an error condition when the OPEN is executed.
Note: In CICS, the use of RESET results in an execution error.
846
CA Easytrieve® Report Generator 11.6
(Non-mainframe platforms only) If you specify RESET, CA Easytrieve® Report Generator deletes an existing data
set before creation or instructs the access method to overwrite the file. If RESET is not specified, new records are
appended.
• [UPDATE] (return to top)
Use UPDATE to permit the file to be updated.
For SQL, code UPDATE to specify that all columns defined for the file can be updated. If you do not specify UPDATE
for an SQL file, only those columns defined with the UPDATE parameter can be updated. UPDATE is required to
DELETE from or INSERT to an SQL file.
Note: You must have UPDATE, INSERT, or DELETE authorization for the SQL table that this file references.
• [PASSWORD {'password-literal'}] or [PASSWORD {password-field-name}] (return to top)
'Password-literal' is the optional password for the file. You can specify the password as an alphabetic literal or a
hexadecimal quoted literal.
Password-field-name is a field you define that contains the password for the file. CA Easytrieve® Report
Generator accesses the value in password-field-name when the file is opened. Any valid password is accepted.
• [NOVERIFY] (return to top)
Code NOVERIFY to ignore a VSAM open error code of 116(X'74'). This error indicates that a previous job terminated
without properly closing the associated VSAM data set. It could also indicate that a job executing on another CPU is
using the associated VSAM data set.
WARNING
Indiscriminate use of NOVERIFY can cause loss of data records.
• [EXIT]
EXIT invokes a user-written program for each CA Easytrieve® Report Generator operation on the file. EXIT is not valid
for VFM, SQL, DL/I, or CA IDMS.
– program-name
Specify the name of the user program.
– [USING {parm-literal}] or [USING {parm-field-name}]
USING appends the associated parameters (parm-literal or parm-field-name) to the standard parameter list passed
to the exit program. Field names must be working storage or system-defined fields and must be defined in the
library section. There is a limit of 62 fields that can be passed to the exit program.
– [MODIFY]
MODIFY specifies that CA Easytrieve® Report Generator provides input or output services, but that the exit can
inspect and modify each record after input and before output.
Device Types
The optional parameters CARD, PUNCH, and PRINTER specify the device type for SEQUENTIAL files. For MVS, if you
do not specify one of these parameters, the device type is determined by your JCL.
• [CARD] (return to top)
(TSO and CMS usage) The CARD option retrieves the file data from the system input stream (SYSIN). Only one file in
a CA Easytrieve® Report Generator execution can use the CARD option. Files using this option must be 80-character
unblocked records.
Note: In TSO and CMS, you cannot use a CARD file if you want to execute your program interpretively.
(Non-mainframe platform usage) The CARD option indicates the file is stdin. It is treated as a variable length file (new-
line delimited) with a maximum record length of 256.
• [PUNCH] (return to top)
(TSO and CMS only) The PUNCH option indicates punched card output. Files created with this option are 80-character
unblocked records.
• [PRINTER] (return to top)
PRINTER indicates that the file receives printed output routed to a file, an online printer, a terminal, or a subsystem
(JES/POWER) data set. Although normal input/output statements (GET, PUT, READ, WRITE) cannot reference
PRINTER files, the DISPLAY statement and the PRINTER parameter of the REPORT statement can reference
PRINTER files.
847
CA Easytrieve® Report Generator 11.6
– [PAGESIZE (line-page-size [display-page-size])
Specify PAGESIZE to define the logical print length of a printed page. For complete rules for specifying PAGESIZE,
see REPORT - Statement.
– [LINESIZE line-length]
Code the LINESIZE parameter to specify the maximum number of data characters that can be printed on a
line. Line-length must be an unsigned integer from 1 to 32767.
Line-length must be at least one less than the length of the data portion of the file's logical record. If the FILE
definition does not provide the file's format and logical record length, then no compile time verification of the line-
length is done.
Line-length provides the default value for any REPORT specifying this file as its PRINTER file.
The default value of LINESIZE is calculated as one less than the data portion of the logical record if the file format
and record length are known at compile time. Otherwise, the default is taken from the LINESIZE site option.
There are additional control characters (forms control information) that also must be stored in a logical record. If one
of the record format parameters is specified, it must be large enough to hold both the forms control information and
the data characters. The value of line-length must be less than or equal to the maximum record length minus the
size of the forms control information.
Record Format (return to top)
You can optionally code the record format of non-VSAM files for z/OS programs. If you do not code a record format in z/
OS, CA Easytrieve® Report Generator obtains it from the operating system when the file is opened. For input files, CA
Easytrieve® Report Generator always obtains the record format from z/OS. The record format and length are required for
VSE and non-mainframe FILE statements.
[F [record-length] ]
[ ]
[V [record-length] ]
[ ]
[U [block-length] ]
[ [FULLTRK ] ]
[ ]
[FB [ (record-length [block-length] ) ] ]
[ [ [FULLTRK ] ] ]
[ ]
[VB [ (record-length [block-length] ) ] ]
[ [ [FULLTRK ] ] ]
[ ]
[VBS [ (record-length [block-length] ) ] ]
[ [ [FULLTRK ] ] ]
CA Easytrieve® Report Generator supports fixed (F), variable (V), and undefined (U) formats. Fixed and variable length
records can be blocked (FB,VB), though the blocking factor is ignored on non-mainframe platforms.
• [VBS] (return to top)
(z/OS only) z/OS systems can process Variable Block Spanned (VBS) records using BFTEK=A processing.
• [record-length] (return to top)
Record-length specifies the maximum record length.
• [block-length] (return to top)
Block-length specifies the file's maximum block length.
For mainframe variable format files, allow four bytes of the record length for the Record Description Word (RDW) and,
if the file is blocked, four bytes of the block size for the Block Description Word (BDW).
848
CA Easytrieve® Report Generator 11.6
NOTE
To obtain an MVS/DFP system determined block size within CA Easytrieve® Report Generator on the
mainframe, do one of the following:
• Include the DSORG, LRECL and RECFM parameters in the original JCL or TSO dynamic allocation. This
forces SMS to establish the block size before CA Easytrieve® Report Generator gets control in OPEN
processing. This is applicable for disk data sets only.
• Define a value of zero for the block length value. If you want CA Easytrieve® Report Generator to pick up
the logical record length from your JCL, code a zero for record-length. You must also code a BLKSIZE=0
in your JCL or code no BLKSIZE parameter at all.
Examples
FILE file-name FB(0 0)
This tells CA Easytrieve® Report Generator to pick up the LRECL from the JCL and to utilize the block size set by
SMS.
FILE file-name FB(150 0)
This tells CA Easytrieve® Report Generator to pick up the LRECL from this definition and to utilize the block size set by
SMS.
FILE file-name FB(150 3000)
This tells CA Easytrieve® Report Generator to pick up this definition and ignore both the JCL and the SMS-determined
block size.
NOTE
If you code a zero block size within CA Easytrieve® Report Generator or in your JCL, and your data set is not
SMS managed, your program will abend with a 013 open problem.
• [FULLTRK] (return to top)
A block length designation of FULLTRK establishes an output block size that equals the maximum track capacity of the
direct access device, or the next lower multiple of record size for FB files.
• [WORKAREA area-length] (return to top)
The WORKAREA option establishes the number of bytes to be allocated as a work area for the file. WORKAREA
cannot be coded if the CARD parameter is specified. Area-length specifies the number of bytes to be allocated and
must be large enough to contain the longest record processed.
WORKAREA allows you to reference the fields in a file prior to the normal allocation of a file's data buffer. For more
information, see File Processing.
Note: WORKAREAs are not initialized by CA Easytrieve® Report Generator.
• [TABLE] (return to top)
The TABLE option declares the file as the source for a SEARCH statement to access a table.
NOTE
VARYING length fields cannot be used for TABLE files.
• [INSTREAM] or [max-table-entries]
The INSTREAM option indicates that the table file immediately follows the file description. The size of an INSTREAM
table is limited only by the amount of available memory. Max-table-entries specifies the maximum number of entries
in an external table. If INSTREAM or max-table-entries is not specified, the file is an external table whose maximum
number of entries is limited by the site option TBLMAX.
• [BUFNO buffers] (return to top)
BUFNO establishes the number of buffers allocated for the file. Buffers can be 1 to 255 for MVS programs. The default
value is obtained from the Site Options Table.
•
849
CA Easytrieve® Report Generator 11.6
[DEFER] (return to top)
• Coding the DEFER option instructs CA Easytrieve® Report Generator to delay the opening of the file until the first input
or output operation for the file occurs. The default opens all referenced files at the beginning of each CA Easytrieve®
Report Generator activity.
• [ASA] (return to top)
For MVS, the optional ASA parameter sets the DCB A option for RECFM.
For non-mainframe platforms, the optional ASA parameter causes output records to be written using the set of
mainframe ASA characters in column one. Without ASA, all records are formatted using ASCII printer control
characters.
• [EXTENDED xrpt-printer] (return to top)
The EXTENDED parameter indicates that the file is to be associated with an extended reporting printer. This means
that input/output statements (GET, PUT, READ, WRITE) cannot reference these printer files. However, the DISPLAY
statement and REPORT statements can reference these printer files. Unless you code them, record length and block
size default to those defined for the printer in the printer set definition module.
Xrpt-printer identifies the extended reporting printer whose characteristics are to be associated with this file. You must
define the xrpt-printer in the printer set definition module.
For more information, see Extended Reporting and the Programming section.
• [CODE {EBCDIC|ASCII|dbcs-code-name}] (Mainframe only) (return to top)
Use CODE dbcs-code-name to define the DBCS code system to be used for all K and M fields for this file. If this is
not specified, the default is taken from the CODE parameter on the PARM statement for this program. If the CODE
parameter is not specified on the PARM statement, then the default is taken from the processing code system as
defined in the CA-PSI Subsystems DBCS Options table.
• [KEY key-field-name] (return to top)
Use the KEY parameter to specify the key field for your non-mainframe ISAM file. CA Easytrieve® Report
Generator uses this parameter only when the file is created. After the file is created, this parameter is ignored and key
information is obtained from the access method. If KEY is not specified during creation, the first field defined in the file
is used as the key field.
Data Set Types
• SYSNAME {'file-identifier'} or SYSNAME {file-identifier-field-name} (return to top)
Code SYSNAME to associate a CA Easytrieve® Report Generator file with an external data set.
– file-identifier
Must be an alphanumeric string.
– file-identifier-field-name
Must be defined as an alphanumeric field of the required length.
The value of file-identifier-field-name is accessed when the file is opened. The required length and the set of valid
characters depend on the file type, the implementation, and the operating system.
NOTE
If SYSNAME is not specified, the file-name specified after the FILE keyword is used. The length of file-
name must conform to operating system standards.
For CICS:
For file types SEQUENTIAL, INDEXED, and RELATIVE, this is the FCT name of the associated VSAM data set.
The requirements for the format of the file-identifier character string are the same as the requirements for the FCT
name. If fewer than eight characters are provided, the value is padded with blanks on the right to obtain a string of
eight characters. File-identifier-field-name must be an alphanumeric field of any format. Only uppercase alphabetic
and numeric digits are allowed. The first character must not be a digit. If File-identifier-field-name is defined with a
length greater than eight, the FCT name must reside in the first 8 (or less) bytes with the remainder set to blanks.
For device type PRINTER, the SYSNAME parameter cannot be used. An execution error occurs.
For TSO:
850
CA Easytrieve® Report Generator 11.6
For file types SEQUENTIAL, INDEXED, and RELATIVE, and device type PRINTER, this is the DDname of the
associated data set. The requirements for the format of the file-identifier character string are the same as the
requirements for the DDname. If fewer than eight characters are provided, the value is padded with blanks on the
right to obtain a string of eight characters. File-identifier-field-name must be an alphanumeric field of any format.
Only uppercase alphabetic and numeric digits are allowed. The first character must not be a digit. If File-identifier-
field-name is defined with a length greater than eight, the DDname must reside in the first 8 (or less) bytes with the
remainder set to blanks.
For data set type VIRTUAL, the SYSNAME parameter is ignored.
For CMS:
For file types SEQUENTIAL, INDEXED, and RELATIVE, and device type PRINTER, this is the FILEDEF or DLBL
name of the associated data set. The requirements for the format of the file-identifier character string are the same
as the requirements for the FILEDEF or DLBL. If fewer than eight characters are provided, the value is padded with
blanks on the right to obtain a string of eight characters. File-identifier-field-name must be an alphanumeric field of
any format. Only uppercase alphabetic and numeric digits are allowed. The first character must not be a digit. If File-
identifier-field-name is defined with a length greater than eight, the FILEDEF or DLBL name must reside in the first 8
(or less) bytes with the remainder set to blanks.
For non-mainframe platforms:
For SEQUENTIAL, INDEXED, and RELATIVE file types and the PRINTER device type, SYSNAME is either a
file description string or an environment variable specifying the file description string. If the value of SYSNAME
contains a path separator (/ or \), it is treated as a file description string. If it does not contain a path separator, CA
Easytrieve® Report Generator searches for an environment variable with the same name. If such a variable is
found, the value of the variable is used as the file description string. If the variable is not found, the SYSNAME value
is used as the path.
For more information about the file description string, see File Description String (Non-Mainframe Only).
The length of SYSNAME is limited to the lesser of 256 characters or the maximum path length supported by your
operating system.
• [VIRTUAL] (return to top)
VIRTUAL identifies a file as a CA Easytrieve® Report Generator Virtual File Manager (VFM) file. CA Easytrieve®
Report Generator virtual files are temporary sequential work files that are normally deleted after the file is read and
closed.
– [RETAIN]
RETAIN inhibits the automatic deletion of a VFM file after it is read. The file is deleted if it is opened for OUTPUT or
CREATE in a subsequent JOB activity or at program termination.
– [MEMORY] or [DISK]
MEMORY and DISK indicate the type of CICS temporary storage that CA Easytrieve® Report Generator is to use
for storing this file. MEMORY indicates a main storage resident temporary storage queue in CICS. DISK indicates
an auxiliary storage resident temporary storage queue. DISK is the default.
• [TERMINAL] (return to top)
Code the TERMINAL parameter to route the output for this printer file to an online terminal. The TERMINAL parameter
is mutually exclusive with the SPOOL, VIRTUAL, and SYSNAME parameters.
A device type of PRINTER is implied.
– [ID {'terminal-id-literal'}] or [ID {terminal-id-field-name}] (CICS only)
Specify the name of the destination terminal in 'terminal-id-literal' or terminal-id-field-name. This terminal can be
either a display terminal or an online printer. Any valid terminal ID is accepted.
When ID is not specified, output directed to this file is spooled until the file is closed. The output can then be
browsed at the originating terminal using the Report Display Facility. You can also then print the file.
– [NOFORMFEED]
Code NOFORMFEED to indicate that the form feed character cannot be used to start a new page. If
NOFORMFEED is not specified, then CA Easytrieve® Report Generator can use the form feed character to start a
new page.
– NEWPAGE [BEFORE] or NEWPAGE [AFTER]
851
CA Easytrieve® Report Generator 11.6
Code NEWPAGE to eject the page each time the file is opened and each time it is closed. Specify NEWPAGE
BEFORE to eject the page each time the file is opened. Specify NEWPAGE AFTER to eject the page each time the
file is closed.
If NEWPAGE is not specified, CA Easytrieve® Report Generator does nothing to position the page.
• [SPOOL] (return to top)
Code the SPOOL parameter to route the output for this printer file to the operating system spooling subsystem. The
SPOOL parameter is mutually exclusive with the VIRTUAL, TERMINAL and SYSNAME parameters. In CMS, the
printer device must be spooled to RSCS. SPOOL is ignored in non-mainframe platforms.
A device type of PRINTER is implied.
– CLASS {'spool-class-literal'} or CLASS {spool-class-field-name}
Code CLASS to specify the spool class for the file. CLASS can be specified as a literal or as a field name. Any valid
class is accepted.
The default is CLASS A.
– NODE {'destination-literal'} or NODE {destination-field-name}
Code NODE to specify the destination for the file. This destination is usually a local or remote printer device name
or a network node name, but can be anything meaningful to the operating system spooling subsystem.
NODE can be specified as a literal or as a field name. Any valid node is accepted.
Note: If NODE is not specified, the destination for the file is not passed to the operating system spooling
subsystem.
– USERID {'user-id-literal'} or USERID {user-id-field-name}
Code USERID to specify the user of the printed output. The NODE subparameter must also be specified and must
contain a network node name.
USERID can be specified as a literal or as a field name. Any valid user ID is accepted.
Note: If the USERID subparameter is not specified, the user ID is not passed to the operating system spooling
subsystem.
For mainframe tape files, if no BLKSIZE is explicitly specified on the FILE statement or in the JCL, the SAM Large Block
Interface (LBI) is used. This allows block sizes larger than 32760 for tape files.
Examples
The following examples illustrate FILE statements for various files.
Sequential (SAM) Files in z/OS
To define a sequential (SAM) file in z/OS, use:
FILE SEQFILE
Entry-sequenced, Fixed-length VSAM Files
To load an entry-sequenced, fixed-length VSAM file, use:
FILE ENTSEQ SEQUENTIAL F CREATE RESET
Virtual Files with RETAIN
To define a virtual file with RETAIN, use:
FILE VRTFILE V(200) +
VIRTUAL RETAIN
Printer Files to Be Viewed at the Terminal
To define a printer file to be viewed at the terminal, use:
FILE PRTFILE PRINTER (PAGESIZE 20 LINESIZE 80) +
TERMINAL
852
CA Easytrieve® Report Generator 11.6
GET Statement
GET places the next or previous sequential record of the named file into the file's record buffer.
To ensure record availability when using the GET statement, you must test for end-of-file (EOF) or file presence (IF file-
name). If you specify GET PRIOR, an EOF means you have reached the beginning of the file.
When you reverse the direction of a GET statement by using GET PRIOR, the record returned is the record immediately
preceding the record previously placed in the file's record buffer. When you reverse the direction of a GET PRIOR
statement by using only GET, the record returned is the record immediately following the record previously placed in the
field's record buffer.
You cannot issue a GET PRIOR statement following a POINT statement, or a GET statement following a POINT PRIOR
statement. For more information, see POINT Statement in the chapter "Statements N - R."
You cannot use GET for a file designated as automatic input. To inhibit automatic input, specify INPUT NULL on the JOB
statement:
JOB INPUT NULL
You can use GET to access a secondary file while automatically accessing a primary file.
This statement has the following format:
[HOLD ]
GET file-name [PRIOR] [ ] [STATUS]
[OHOLD ]
• file-name
File-name identifies the input file defined in the library section. File-name can be any file type except SQL.
• [PRIOR]
Specify PRIOR to place the previous sequential record of the named file into the file's record buffer. If you specify
PRIOR and the position in the file is not established, the last record in the file is placed in the file's record buffer.
Note: If the access method of the operating system does not support retrieval of previous records, an execution error
occurs.
• [HOLD] or [NOHOLD]
Except in CICS, CA Easytrieve® Report Generator automatically issues a hold request for records when UPDATE is
specified on the FILE statement. Use NOHOLD to override this process. In CICS, NOHOLD is the default.
Specify HOLD to hold a record for update. HOLD is invalid if UPDATE is not specified on the FILE statement. HOLD
does not mean you are required to perform the update; it holds the position in the file. Records are automatically
released when the update operation completes or a commit point is taken. You can also manually release the hold on
any record with the RELEASE statement.
NOHOLD specifies that a record is not to be held for update.
NOTE
In CICS, if you specify HOLD, you cannot browse (GET) a file; an execution error occurs. When you want to
update a record, use the READ statement.
• [STATUS]
Specify STATUS whenever the possibility exists for an unsatisfactory completion of the input/output request.
STATUS checks input/output processing to see if it was performed properly. STATUS causes the file's FILE-STATUS
field to be set with the appropriate return code. For information about how to determine the meaning of the contents of
FILE-STATUS, see the appendix "System-Defined Fields." Normally, a zero or non-zero test is sufficient.
NOTE
FILE-STATUS is not defined if you do not specify a file type parameter on the FILE statement.
853
CA Easytrieve® Report Generator 11.6
If you do not code STATUS and the operating system returns a non-zero status, CA Easytrieve® Report Generator
issues an appropriate diagnostic message.
Examples
The following code illustrates the use of the GET statement:
FILE PERSNL INDEXED
%PERSNL
PROGRAM NAME MYPROG
GET PERSNL STATUS
IF PERSNL:FILE-STATUS NE 0
DISPLAY PERSNL:FILE-STATUS
ELSE
DISPLAY HEX PERSNL
END-IF
The following code illustrates testing for EOF when using the GET statement:
FILE MASTER
...
GET MASTER
IF EOF MASTER
STOP
END-IF
...
GOTO Statement
The GOTO statement allows you to modify the natural top to bottom logic flow of statement execution.
This statement has the following format:
{GOTO } {label }
{ } {JOB }
{GO TO} {SCREEN}
• {label}
Specify label to immediately transfer execution control to the first statement following the associated label. Processing
then continues in a top-to-bottom sequence. The label must be contained in the same activity or procedure. A label:
– Can be up to 128 alphanumeric characters in length
– Can contain any character other than a delimiter
– Can begin with A to Z, 0 to 9, or a national character (#, @, $)
– Must not consist of all numeric characters.
A statement label is a complete CA Easytrieve® Report Generator statement that you can code before the following
statements:
854
CA Easytrieve® Report Generator 11.6
– Assignment
– CASE
– COMMIT
– DELETE
– DLI
– END-DO
– END-PROC
– EXIT
– GET
– IDMS
– INSERT
– MOVE
– PERFORM
– PRINT
– READ
– RELEASE
– ROLLBACK
– SELECT (except non-file SQL)
– SQL
– STOP
– UPDATE
– CALL
– CLOSE
– CURSOR
– DISPLAY
– DO
– END-IF
– EXECUTE
– FETCH
– GOTO
– IF
– MESSAGE
– MOVE LIKE
– POINT
– PUT
– REFRESH
– RESHOW
– SEARCH
– SET
– Statement label
– TRANSFER
– WRITE
• {JOB}
GOTO JOB causes an immediate branch to the top of the current JOB activity. It does not include execution of the
START procedure. When used in a START procedure, GOTO JOB terminates the START procedure. When used in a
FINISH procedure, GOTO JOB terminates the FINISH procedure.
• {SCREEN}
855
CA Easytrieve® Report Generator 11.6
GOTO SCREEN branches immediately to the top of the current SCREEN activity, including execution of the BEFORE-
SCREEN procedure. It does not include execution of the INITIATION procedure. When used in an INITIATION
procedure, GOTO SCREEN terminates the INITIATION procedure.
GOTO SCREEN cannot be coded in a BEFORE-SCREEN procedure. If GOTO SCREEN is coded in a TERMINATION
procedure, GOTO SCREEN terminates the screen activity.
Example
The following example illustrates the use of GOTO in a program. The arrows indicate that control is passed to the first
executable statement following the label or job statement.
HEADING Statement
The HEADING statement optionally defines an alternative heading for a field. When defining a field, you specify the
default heading. Using the HEADING statement in a report allows you to override the default field headings for that report.
The HEADING statement overrides default field headings defined in the library section. The HEADING statement also
provides alternative heading capabilities for system-defined fields such as TALLY and LEVEL.
This statement has the following format:
HEADING field-name ([#font-number] 'heading-literal'...)
• field-name
For reports, field-name specifies a field in your program. The heading you define is used for fields identified on LINE 01
of your report declaration.
• [#font-number]
#Font-number defines the number of a font that CA Easytrieve® Report Generator uses to format 'heading-literal'
in the heading area of a report. You can only specify #font-number if you direct the report to an extended reporting
856
CA Easytrieve® Report Generator 11.6
printer. If you direct the report to a normal printer, a syntax error occurs when you code #font-number. You can specify
a unique font index for each 'heading-literal' by coding the # sign and a value for #font-number before 'heading-literal'.
Any 'heading-literal' that does not have a font index assigned uses the default font for the assigned extended reporting
printer.
• 'heading-literal'
'Heading-literal' can be up to 128 characters in length.
For reports, a single line of alphanumeric text replaces the default header and prints as a header over a column
or field. Multiple literals, each enclosed within single quotes ('') and separated by one or more blanks within the
parentheses, are stacked vertically over the column or field when printed.
Examples
The following example illustrates various report heading options:
Statements:
FILE PERSNL FB(150 1800)
SSN 4 5 P MASK '999-99-9999' +
HEADING('SOCIAL' 'SECURITY' 'NUMBER')
EMPNAME 17 20 A
NAME-LAST EMPNAME 8 A
NAME-FIRST EMPNAME +8 12 A
PAY-NET 90 4 P 2
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65
HEADING PAY-NET ('NET', 'PAY')
LINE EMPNAME SSN '* NO OVERTIME *' PAY-NET
Results:
SOCIAL
SECURITY NET
EMPNAME NUMBER PAY
WIMN GLORIA 025-30-5228 * NO OVERTIME * 251.65
BERG NANCY 121-16-6413 * NO OVERTIME * 547.88
IDD FILE Statement
The IDD FILE statement identifies a non-CA IDMS file in the IDD and builds file and field definitions.
The file-name can be qualified by the file-name's version. All records defined within the file are used to generate the file's
field definitions, unless the optional SELECT parameter identifies specific records to be used.
This statement has the following format:
[ {HIGHEST}]
IDD FILE file-name [VERSION {LOWEST }] +
857
CA Easytrieve® Report Generator 11.6
[ {nnnn }]
[SELECT (record-name...)] +
[FILENAME new-file-name]
• file-name
File-name is the one to 32-character name that specifies the IDD file. File-name becomes the name of the FILE
created by the IDD FILE statement. To override this name, see the FILENAME parameter.
• [VERSION {HIGHEST}] or [VERSION {LOWEST}] or [VERSION {nnnn}]
Specify HIGHEST, LOWEST, or nnnn (a positive integer) as the version of the file.
• [SELECT (record-name ...)]
Record-name is a 1- to 32-character name that identifies a record of the file-name defined. Repeat the record-name
to identify as many records as needed. If you want to define all the field definitions for the file-name, omit the SELECT
clause.
• [FILENAME new-file-name]
New-file-name is a 1- to 128-character name specifying the name of the file created by the IDD FILE statement.
IDD NAME Statement
The IDD NAME statement establishes or re-establishes the dictionary entity retrieval environment. The IDD NAME
statement specifies the program name, the database name of the data dictionary, the Central Version Node, and the
Secondary Load Area's dictionary name and dictionary node.
IDD entities are retrieved from the designated dictionary/node until the environment is altered by issuing another IDD
NAME statement. You can use the IDD NAME statement as many times as required and before any other IDD statement.
However, you can use the PROGRAM-NAME parameter only once.
This statement has the following format:
IDD NAME [PROGRAM-NAME 'program-literal'] +
[DBNAME 'db-name-table-literal'] +
[NODE 'node-literal'] +
[DICTNAME 'dictionary-literal'] +
[DICTNODE 'dictionary-node-literal']
• [PROGRAM-NAME 'program-literal']
'Program-literal' identifies the program name used to access an authorized subschema. 'Program-literal' must be
alphanumeric and is padded to the right (if necessary) to create an eight-byte value.
• [DBNAME 'db-name-table-literal']
'Db-name-table-literal' identifies the DB Name Table of the data dictionary that contains definitions of schema,
subschema, records, and fields. 'Db-name-table-literal' must be alphanumeric and is padded to the right (if necessary)
to create an eight-byte value.
• [NODE 'node-literal']
'Node-literal' specifies the CA IDMS Central Version Node that will process CA Easytrieve® Report Generator IDD
requests. 'Node-literal' must be alphanumeric and is padded to the right (if necessary) to create an eight-byte value.
• [DICTNAME 'dictionary-literal']
'Dictionary-literal' identifies the Secondary Load Area dictionary name. 'Dictionary-literal' must be alphanumeric and is
padded to the right (if necessary) to create an eight-byte value.
• [DICTNODE 'dictionary-node-literal']
'Dictionary-node-literal' identifies the Secondary Load Area dictionary node. 'Dictionary-node-literal' must be
alphanumeric and is padded to the right (if necessary) to create an eight-byte value.
858
CA Easytrieve® Report Generator 11.6
IDD RECORD Statement
The IDD RECORD statement identifies and defines CA IDMS and non-CA IDMS records. The record-name can be
qualified by the record's version. The elements defined within the record are used to generate field definitions at the
location specified.
This statement has the following format:
[ {HIGHEST}]
IDD RECORD record-name [VERSION {LOWEST }] +
[ {nnnn }]
[ {start-position}]
[ {* [+offset] }]
[LOCATION { }]
[ {W }]
[ {S }]
• record-name
The record-name is the 1- to 32-character name that specifies the IDD logical record or the IDD standard record.
• [VERSION {HIGHEST}] or [VERSION {LOWEST}] or [VERSION {nnnn}]
Specify HIGHEST, LOWEST, or nnnn (a positive integer) as the version of the file.
• [LOCATION]
Use this optional parameter to specify the location at which the field definitions will be generated. If you do not specify
LOCATION, W (a W-type working storage field) is the default.
• {start-position}
Start-position specifies the starting position relative to position one of the record.
• {* [+offset]}
The * (asterisk) indicates that the field begins in the next available starting position (highest position assigned so far,
plus 1). The optional +offset is an offset you want added to the * value. There must be at least one blank between the *
and the optional +offset.
• {W or S}
Coding W or S establishes a working storage field. W fields are spooled to report (work) files; S fields are not. W is the
default location if the LOCATION parameter is not coded.
IDD SUBSCHEMA Statement
The IDD SUBSCHEMA statement identifies the subschema and builds the file, record, logical record, element record, and
field definitions for a subschema. The subschema can be qualified by the schema and version.
You can use the optional SELECT parameter to request that only specific records be defined. If the SELECT parameter
is omitted, the definitions of logical records are not generated. Only database records can be defined in this way. The
SELECT parameter must be used to generate logical record definitions.
This statement has the following format:
IDD SUBSCHEMA subschema-name +
[ [ {HIGHEST}]]
[SCHEMA schema-name [VERSION {LOWEST }]] +
[ [ {nnnn }]]
[RESET] +
[SELECT (record-name...)] +
859
CA Easytrieve® Report Generator 11.6
[FILENAME file-name]
• subschema-name
Subschema-name is a 1- to 8-character name specifying the SUBSCHEMA that contains the record and field
definitions to be retrieved. Subschema-name becomes the name of the FILE created by the IDD SUBSCHEMA
statement. For information about how to override this name, see FILENAME Parameter.
• [SCHEMA schema-name [VERSION {HIGHEST} or {LOWEST} or {nnnn}]]
Schema-name is the one to eight-character name that specifies the schema that owns the subschema (when a
subschema can be owned by multiple schemas). The optional VERSION parameter specifies the version of the
schema.
• [RESET]
The optional RESET parameter requests that all element records under control of RETRIEVE be reset to binary zero
immediately prior to retrieving each root record.
• [SELECT (record-name ...)]
The optional SELECT clause identifies specific subschema records. Record-name is a one to 32-character name
that identifies a record for which the definition is accessed. Repeat record-name to specifically identify all the records
you need. To access all the database records (but not logical records) defined for the subschema, you can omit the
SELECT parameter.
• [FILENAME file-name]
File-name is a 1- to 128-character name specifying the name of the file created by the IDD SUBSCHEMA statement.
IDD VERSION Statement
Use the IDD VERSION statement to set a global override of the Site Options Table VERFILE, VERREC, and VERSCHM
defaults.
Other IDD statements appearing after the IDD VERSION statement, that have VERSION parameters as part of their
syntax but no VERSION parameter coded, default to the version specified in the IDD VERSION statement. IDD
statements that have a VERSION parameter coded override the VERSION statement. The defaults specified by the IDD
VERSION statement remain in effect until another IDD VERSION statement is issued.
You can code as many IDD VERSION statements as you require. If the IDD VERSION statement is not used, the default
versions are retrieved from the Site Options Table.
This statement has the following format:
[ {HIGHEST}]
IDD VERSION [SCHEMA {LOWEST }] +
[ {nnnn }]
[ {HIGHEST}]
[FILE {LOWEST }] +
[ {nnnn }]
[ {HIGHEST}]
[RECORD {LOWEST }]
[ {nnnn }]
• [SCHEMA {HIGHEST}] or {LOWEST} or {nnnn}]
Specify HIGHEST, LOWEST, or a positive integer (nnnn) to identify the default version of the SCHEMA. Any request to
retrieve a subschema that specifies a schema but not a version uses this value.
• [FILE {HIGHEST}] or {LOWEST} or {nnnn}]
860
CA Easytrieve® Report Generator 11.6
Specify HIGHEST, LOWEST, or a positive integer (nnnn) to identify the default version of any FILE to be retrieved
when the version is not specified on the IDD FILE statement.
• [RECORD {HIGHEST}] or {LOWEST} or {nnnn}]
Specify HIGHEST, LOWEST, or a positive integer (nnnn) to identify the default version of any RECORD to be retrieved
when the version is not specified on the IDD RECORD statement.
IDMS ACCEPT DBKEY Statement
The IDMS ACCEPT DBKEY statement transfers database keys to program storage. The IDMS ACCEPT DBKEY
statement has two formats. Format 1 returns the current database key for the record, set, or area specified. Format 2
returns the database key that is the next, prior, or owner of the specified set.
This statement has the following format:
Format 1
[{RECORD} {currency-field-name}]
IDMS ACCEPT DBKEY receive-field-name [{AREA } { }]
[{SET } {'currency-literal' }]
Format 2
{NEXT } {set-field-name}
IDMS ACCEPT DBKEY receive-field-name {PRIOR} { }
{OWNER} {'set-literal' }
Format 1
• receive-field-name
Receive-field-name identifies the four-byte binary field to receive the specified database key.
• {RECORD} or {AREA} or {SET}
Specify RECORD, SET, or AREA.
• {currency-field-name} or {'currency-literal'}
Currency-field-name or 'currency-literal' identifies the currency for the desired key. Currency-field-name must be a 16-
byte alphanumeric field. 'Currency-literal' must be alphanumeric and is padded to the right (if necessary) to create a
16-byte value. The default is the current record of the run-unit.
Format 2
• receive-field-name
Receive-field-name identifies the four-byte binary field to receive the specified database key.
• {NEXT} or {PRIOR} or {OWNER}
Specify NEXT, PRIOR, or OWNER.
• {set-field-name} or {'set-literal'}
Set-field-name or 'set-literal' identifies the name of the desired set. Set-field-name must be a 16-byte alphanumeric
field. 'Set-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte value.
IDMS ACCEPT PAGE-INFO Statement
The IDMS ACCEPT PAGE-INFO statement transfers database page information to program storage.
This statement has the following format:
{ } {currency-field-name}
861
CA Easytrieve® Report Generator 11.6
IDMS ACCEPT PAGE-INFO receive-field-name {RECORD} { }
{ } {'currency-literal' }
• receive-field-name
Receive-field-name identifies the four-byte binary field to receive the page information.
• {currency-field-name} or {'currency-literal'}
Currency-field-name or 'currency-literal' identifies the record name for the desired key. Currency-field-name must be a
16-byte alphanumeric field. 'Currency-literal' must be alphanumeric and is padded to the right (if necessary) to create a
16-byte value.
IDMS ACCEPT PROCEDURE Statement
The IDMS ACCEPT PROCEDURE statement returns information from the Application Program Information Block (APIB)
associated with a database procedure to the program.
This statement has the following format:
{proc-field-name}
IDMS ACCEPT PROCEDURE { } TO apib-field-name
{'proc-literal' }
• {proc-field-name} or {'proc-literal'}
Proc-field-name or 'proc-literal' identifies the name of a DBA-written database procedure. Proc-field-name must be an
eight-byte alphanumeric field. 'Proc-literal' must be alphanumeric and is padded to the right (if necessary) to create an
eight-byte value.
• TO apib-field-name
Apib-field-name is a 256-byte alphanumeric area of storage to which the APIB is copied.
IDMS ACCEPT STATISTICS Statement
The IDMS ACCEPT STATISTICS statement retrieves the system statistics.
For more information about the statistics produced, see your CA IDMS documentation.
This statement has the following format:
IDMS ACCEPT STATISTICS stat-field-name
• stat-field-name
Stat-field-name identifies a 100-byte field that you must define in working storage to receive the current system runtime
statistical information.
IDMS BIND Statement
The IDMS BIND statement signs on the activity with the database management system.
This statement has the following format:
{subschema-name }
IDMS BIND { } +
{'subschema-literal'}
[ {program-name }]
862
CA Easytrieve® Report Generator 11.6
[PROGRAM-NAME { }] +
[ {'program-literal'}]
[ {db-name-table-name }]
[DBNAME { }] +
[ {'db-name-table-literal'}]
[ {node-name }]
[NODE { }] +
[ {'node-literal'}]
[ {dictionary-name }]
[DICTNAME { }] +
[ {'dictionary-literal'}]
[ {dictionary-node-name }]
[DICTNODE { }]
[ {'dictionary-node-literal'}]
• {subschema-name} or {'subschema-literal'}
Subschema-name identifies the subschema to be processed with CA IDMS. Subschema-name must be an eight-byte
alphanumeric field. 'Subschema-literal' must be alphanumeric and is padded to the right (if necessary) to create an
eight-byte value.
• [PROGRAM-NAME {program-name}] or [PROGRAM-NAME {'program-literal'}]
Program-name or 'program-literal' specifies the name used to identify the program to CA IDMS during execution.
Program-name must be an eight-byte alphanumeric field. 'Program-literal' must be alphanumeric and is padded to the
right (if necessary) to create an eight-byte value.
• [DBNAME {db-name-table-name}] or [DBNAME {'db-name-table-literal'}]
Db-name-table-name or 'db-name-table-literal' specifies a DB Name Table. Data retrieved during execution of the
user's program will be from the named database. Db-name-table-name must be an eight-byte alphanumeric field. 'Db-
name-table-literal' must be alphanumeric and is padded to the right (if necessary) to create an eight-byte value.
• [NODE {node-name}] or [NODE {'node-literal'}]
Node-name or 'node-literal' specifies the Central Version Node that will host the CA IDMS activity generated by the
user's program. Node-name must be an eight-byte alphanumeric field. 'Node-literal' must be alphanumeric and is
padded to the right (if necessary) to create an eight-byte value.
• [DICTNAME {dictionary-name}] or [DICTNAME {'dictionary-literal'}]
Dictionary-name or 'dictionary-literal' specifies the dictionary name of a secondary load area. Dictionary-name must be
an eight-byte alphanumeric field. 'Dictionary-literal' must be alphanumeric and is padded to the right (if necessary) to
create an eight-byte value.
• [DICTNODE {dictionary-node-name}] or [DICTNODE {'dictionary-node-literal'}]
Dictionary-node-name or 'dictionary-node-literal' specifies the dictionary node of a secondary load area. Dictionary-
node-name must be an eight-byte alphanumeric field. 'Dictionary-node-literal' must be alphanumeric and is padded to
the right (if necessary) to create an eight-byte value.
IDMS BIND FILE Statement
The IDMS BIND FILE statement gives the database management system access to the record in program storage.
This statement has the following format:
IDMS BIND FILE file-name RECORD record-name
• file-name
863
CA Easytrieve® Report Generator 11.6
File-name identifies the file where the record-area is to be allocated.
• RECORD record-name
Record-name identifies the record to be bound with CA IDMS.
IDMS BIND PROCEDURE Statement
The IDMS BIND PROCEDURE statement establishes communications between a program and a DBA-written database
procedure.
This statement has the following format:
{proc-field-name}
IDMS BIND PROCEDURE { } TO receive-field-name
{'proc-literal' }
• {proc-field-name} or {'proc-literal'}
Proc-field-name or 'proc-literal' identifies the name of a DBA-written database procedure. Proc-field-name must be an
eight-byte alphanumeric field. 'Proc-literal' must be alphanumeric and is padded to the right (if necessary) to create an
eight-byte value.
• TO receive-field-name
Receive-field-name must be a 256-byte alphanumeric field. The contents of receive-field-name are copied to the APIB
as part of the execution of the IDMS BIND PROCEDURE statement.
IDMS COMMIT Statement
The IDMS COMMIT statement requests the creation of a checkpoint.
This statement has the following format:
IDMS COMMIT [ALL]
• [ALL]
This optional parameter controls which locks are released. The default is ALL EXCEPT THOSE HELD.
IDMS CONNECT Statement
The IDMS CONNECT statement establishes a record as a member of a set occurrence.
This statement has the following format:
{record-field-name} {set-field-name}
IDMS CONNECT RECORD { } SET { }
{'record-literal' } {'set-literal' }
• {record-field-name} or {'record-literal'}
Record-field-name or 'record-literal' identifies the record to be connected. Record-field-name must be a 16-byte
alphanumeric field. 'Record-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte
value.
• {set-field-name} or {'set-literal'}
Set-field-name or 'set-literal' specifies the set to which the record is to be connected. Set-field-name must be a 16-
byte alphanumeric field. 'Set-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte
value.
864
CA Easytrieve® Report Generator 11.6
IDMS DISCONNECT Statement
The IDMS DISCONNECT statement cancels the relationship between a record and a set occurrence.
This statement has the following format:
{record-field-name} {set-field-name}
IDMS DISCONNECT RECORD { } SET { }
{'record-literal' } {'set-literal' }
• RECORD {record-field-name} or RECORD {'record-literal'}
Record-field-name or 'record-literal' identifies the record to be disconnected. Record-field-name must be a 16-byte
alphanumeric field. 'Record-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte
value.
• SET {set-field-name} or SET {'set-literal'}
Set-field-name or 'set-literal' specifies the set from which the record is to be disconnected. Set-field-name must be a
16-byte alphanumeric field. 'Set-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-
byte value.
IDMS ERASE Statement
Format 1 of the IDMS ERASE statement makes a record unavailable for further processing and removes it from all set
occurrences in which it participates as a member. Format 2 makes a logical record unavailable for further processing.
This statement has the following format:
Format 1
[MEMBERS ]
{record-field-name} [PERMANENT]
IDMS ERASE RECORD { } [ ]
{'record-literal' } [SELECTIVE]
[ALL ]
Format 2
IDMS ERASE RECORD logical-record-name [WHERE (boolean-expression)]
Format 1
• RECORD {record-field-name} or RECORD {'record-literal'}
Record-field-name or 'record-literal' identifies the record to be erased. Record-field-name must be a 16-byte
alphanumeric field. 'Record-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte
value.
• [MEMBERS] or [PERMANENT] or [SELECTIVE] or [ALL]
This optional parameter controls the type of erasure. The default is MEMBERS.
Format 2
• RECORD logical-record-name
Logical-record-name is a one to 16-character name that identifies the logical record to be erased. Logical-record-name
must be the name of a logical record defined by a LOGICAL-RECORD statement.
• [WHERE (boolean-expression)]
865
CA Easytrieve® Report Generator 11.6
Code the optional WHERE clause to provide a Boolean expression CA IDMS uses to select the logical records to be
erased.
IDMS FIND and IDMS OBTAIN Statements
The IDMS FIND and IDMS OBTAIN statements are described together because their formats are the same. The IDMS
FIND statement only locates (positions to) a record; the IDMS OBTAIN statement locates and then retrieves a record.
These statements have six formats:
• Format 1 locates/retrieves a record based on its DBKEY.
• Format 2 locates/retrieves the current occurrence of the record type, set, or area.
• Format 3 locates/retrieves a record within a set or area.
• Format 4 locates/retrieves the owner record within the set.
• Format 5 locates/retrieves a record based on its CALC key.
• Format 6 locates retrieves an ordered (sorted) record from a set.
NOTE
For information about how to retrieve logical records, see IDMS OBTAIN Statement in this chapter.
This statement has the following format:
Format 1
[ {record-field-name}]
[ RECORD { }]
{FIND } {key-field-name} [ {'record-literal' }] [SHARE|SHR ]
IDMS { } DBKEY { } [ ] [ ]
{OBTAIN} {'key-literal' } [ {page-field-name }] [EXCLUSIVE|EXC]
[ PAGE-INFO { }]
[ {'page-literal' }]
Format 2
{FIND } [{RECORD} {field-name}] [SHARE|SHR ]
IDMS { } CURRENT [{SET } { }] [ ]
{OBTAIN} [{AREA } {'literal' }] [EXCLUSIVE|EXC]
Format 3
{FIND }# {NEXT } [ {record-field-name}]
IDMS { }# {PRIOR } [RECORD { }] +
{OBTAIN}# {FIRST } [ {'record-literal' }]
{LAST }
{ {nth-field-name} }
{NTH { } }
{ {nth-literal } }
{SET } {search-field-name} [SHARE|SHR ]
{ } { } [ ]
{AREA} {'search-literal' } [EXCLUSIVE|EXC]
Format 4
866
CA Easytrieve® Report Generator 11.6
{FIND } {set-field-name} [SHARE|SHR ]
IDMS { } OWNER SET { } [ ]
{OBTAIN} {'set-literal' } [EXCLUSIVE|EXC]
Format 5
{FIND } {CALC } {record-field-name} [SHARE|SHR ]
IDMS { } { } RECORD { } [ ]
{OBTAIN} {DUPLICATE} {'record-literal' } [EXCLUSIVE|EXC]
Format 6
{FIND } {record-field-name} {set-field-name}
IDMS { } [CURRENT] RECORD { } SET { } +
{OBTAIN} {'record-literal' } {'set-literal' }
{control-field-name} [SHARE|SHR ]
USING ({ }...) [ ]
{'control-literal' } [EXCLUSIVE|EXC]
Format 1
• DBKEY {key-field-name} or DBKEY {'key-literal'}
Key-field-name or 'key-literal' identifies the key of the database record. Key-field-name must be a four-byte binary field.
'Key-literal' must be a four-byte hexadecimal value.
• [RECORD {record-field-name}] or [RECORD {'record-literal'}]
Record-field-name or 'record-literal' identifies the record to be located/retrieved. Record-field-name must be a 16-byte
alphanumeric field. 'Record-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte
value. The default is any record type that satisfies the DBKEY.
• [PAGE-INFO {page-field-name}] or [PAGE-INFO {'page-literal'}]
Page-field-name or 'page-literal' identifies the record to be located/retrieved by its page information. Page-field-name
must be a 4-byte binary field. 'Page-literal' must be a 4-byte hexadecimal value.
• [SHARE|SHR] or [EXCLUSIVE|EXC]
These optional parameters determine the type of lock to be placed on the object record.
Format 2
• [{RECORD|SET|AREA} {field-name|'literal'}]
Field-name or 'literal' identifies the record, set, or area to be located/retrieved. Field-name must be a 16-byte
alphanumeric field. 'Literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte value.
The default locates/retrieves the current record of the run-unit.
• [SHARE|SHR] or [EXCLUSIVE|EXC]
These optional parameters determine the type of lock to be placed on the object record.
Format 3
• {NEXT} or {PRIOR} or {FIRST} or {LAST} or {NTH {nth-field-name|nth-literal}}
Nth-field-name or nth-literal identifies the record occurrence of the set or area to be located/retrieved. Nth-field-name
must be a four-byte binary integer. Nth-literal must be a positive or negative integer.
• [RECORD {record-field-name}|'record-literal'}]
Record-field-name or 'record-literal' identifies the record to be located/retrieved. Record-field-name must be a 16-byte
alphanumeric field. 'Record-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte
value. The default is the record that otherwise satisfies the search criteria.
• {SET|AREA}{search-field-name|'search-literal'}
867
CA Easytrieve® Report Generator 11.6
Search-field-name or 'search-literal' identifies the set or area that determines the scope of the search. Search-field-
name must be a 16-byte alphanumeric field. 'Search-literal' must be alphanumeric and is padded to the right (if
necessary) to create a 16-byte value.
• [SHARE|SHR ] or [EXCLUSIVE|EXC]
These optional parameters determine the type of lock to be placed on the object record.
Format 4
• OWNER SET {set-field-name|'set-literal'}
Set-field-name or 'set-literal' identifies the set to search. Set-field-name must be a 16-byte alphanumeric field. 'Set-
literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte value.
• [SHARE|SHR] or [EXCLUSIVE|EXC]
These optional parameters determine the type of lock to be placed on the object record.
Format 5
• {CALC} or {DUPLICATE}
This parameter determines whether the first (CALC) or next (DUPLICATE) record is located/retrieved.
• RECORD {record-field-name|'record-literal'}
Record-field-name or 'record-literal' identifies the record to locate/retrieve. Record-field-name must be a 16-byte
alphanumeric field. 'Record-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte
value.
• [SHARE|SHR] or [EXCLUSIVE|EXC]
These optional parameters determine the type of lock to be placed on the object record.
Format 6
• [CURRENT]
This optional parameter controls the start of the search. The default begins with the owner of the current record within
the set.
• RECORD {record-field-name|'record-literal'}
Record-field-name or 'record-literal' identifies the record to locate/retrieve. Record-field-name must be a 16-byte
alphanumeric field. 'Record-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte
value.
• SET {set-field-name|'set-literal'}
Set-field-name or 'set-literal' identifies the set to search. Set-field-name must be a 16-byte alphanumeric field. 'Set-
literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte value.
• USING {control-field-name|'control-literal'}
Control-field-name or 'control-literal' identifies the control data item. The length and code system of the control data
item must match that in the database.
• [SHARE|SHR] or [EXCLUSIVE|EXC]
These optional parameters determine the type of lock to be placed on the object record.
IDMS FINISH Statement
The IDMS FINISH statement signs off the database management system.
This statement has the following format:
IDMS FINISH
IDMS GET Statement
The IDMS GET statement retrieves current data records.
868
CA Easytrieve® Report Generator 11.6
This statement has the following format:
[ {record-field-name}]
IDMS GET [RECORD { }]
[ {'record-literal' }]
• RECORD {record-field-name|'record-literal'}
Record-field-name or 'record-literal' identifies the record to locate/retrieve. Record-field-name must be a 16-byte
alphanumeric field. 'Record-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte
value. The default record is the current record type of the run-unit.
IDMS IF Statement
The IDMS IF statement tests the status of a set.
This statement has the following format:
{MEMBER }
{set-field-name} {NOMEMBER}
IDMS IF SET { } { }
{'set-literal' } {EMPTY }
{NOEMPTY }
• SET {set-field-name|'set-literal'}
Set-field-name or 'set-literal' identifies the set to search. Set-field-name must be a 16-byte alphanumeric field. 'Set-
literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte value.
• {MEMBER} or {NOMEMBER} or {EMPTY} or {NOEMPTY}
This parameter determines the type of test:
– Specify MEMBER if the current record is a member of specified set.
– Specify NOMEMBER if the current record is not a member of specified set.
– Specify EMPTY if no member record occurrences exist.
– Specify NOEMPTY if member record occurrences exist.
The IDMS IF statement is similar to the CA Easytrieve® Report Generator IF statement in that a corresponding END-IF
statement is required and the ELSE statement is optional. For more information, see the following sections in this chapter:
• IF Statement
• ELSE-IF Statement
• ELSE Statement
• END-IF Statement
IDMS KEEP Statement
The IDMS KEEP statement places a shared or exclusive lock on a record.
This statement has the following format:
[{RECORD} {field-name}]
IDMS KEEP [{SET } { }] [EXCLUSIVE]
[{AREA } {'literal' }]
• [{RECORD|SET|AREA} {field-name|'literal'}]
869
CA Easytrieve® Report Generator 11.6
Field-name or 'literal' identifies the desired record, set, or area to be locked. Field-name must be a 16-byte
alphanumeric field. 'Literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte value.
• [EXCLUSIVE]
This optional parameter controls the lock for the record. The default is SHARED LOCK.
IDMS MODIFY Statement
Format 1 of the IDMS MODIFY statement updates a record within the database. Format 2 updates a logical record within
the database.
This statement has the following format:
Format 1
{record-field-name}
IDMS MODIFY RECORD { }
{'record-literal' }
Format 2
IDMS MODIFY RECORD logical-record-name [WHERE (boolean-expression)]
Format 1
• RECORD {record-field-name|'record-literal'}
Record-field-name or 'record-literal' identifies the record to be modified. Record-field-name must be a 16-byte
alphanumeric field. 'Record-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte
value.
Format 2
• RECORD logical-record-name
Logical-record-name is a 1- to 16-character name that identifies the logical record to be modified by CA IDMS.
• [WHERE (boolean-expression)]
Code the optional WHERE clause to provide a Boolean expression to CA IDMS to select the logical records to be
modified.
IDMS OBTAIN Statement
The IDMS OBTAIN statement is used to retrieve logical records.
NOTE
For information about how to retrieve database records, see IDMS FIND and IDMS OBTAIN Statements in this
chapter.
This statement has the following format:
{FIRST}
IDMS OBTAIN { } RECORD logical-record-name [WHERE(boolean-expression)]
{NEXT }
• {FIRST} or {NEXT}
Specify FIRST to retrieve the first occurrence of the logical record. Specify NEXT to retrieve subsequent occurrences.
• RECORD logical-record-name
870
CA Easytrieve® Report Generator 11.6
Logical-record-name is a 1- to 16-character name that identifies the logical record to be retrieved. Logical-record-name
must be the name of a logical record defined by a LOGICAL-RECORD statement.
• [WHERE (boolean-expression)]
Code the optional WHERE clause to provide a Boolean expression CA IDMS uses to select the logical records to be
retrieved.
IDMS READY Statement
The IDMS READY statement establishes area availability with the database manager.
This statement has the following format:
[ {area-field-name}] [{RETRIEVAL} [PROTECTED]]
IDMS READY [AREA { }] [{ } [ ]]
[ {'area-literal' }] [{UPDATE } [EXCLUSIVE]]
• [AREA {area-field-name|'area-literal'}]
Area-field-name or 'area-literal' identifies the area to be made available for processing. Area-field-name must be a 16-
byte alphanumeric field. 'Area-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-
byte value. If not specified, all areas in the subschema are readied.
• [{RETRIEVAL|UPDATE} [PROTECTED|EXCLUSIVE]]
These optional parameters determine the type of access. The default is RETRIEVAL.
IDMS RETURN Statement
The IDMS RETURN statement retrieves the database key for an indexed record without retrieving the record itself.
This statement has the following format:
{set-field-name}
IDMS RETURN DBKEY receive-field-name FROM { } +
{'set-literal' }
[KEY symbolic-key] +
{ }
{CURRENCY }
{FIRST [CURRENCY] }
{LAST [CURRENCY] }
{NEXT [CURRENCY] }
{PRIOR [CURRENCY] }
{ }
{ {key-field-name} }
{USING ({ }...)}
{ {'key-literal' } }
• DBKEY receive-field-name
This is a four-byte binary field with zero (0) decimal places. This field receives the DBKEY of the indexed record.
• FROM {set-field-name|'set-literal'}
Set-field-name or 'set-literal' identifies the index set to be accessed. Set-field-name must be a 16-byte alphanumeric
field. 'Set-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte value.
• [KEY symbolic-key]
871
CA Easytrieve® Report Generator 11.6
This parameter retrieves the record's symbolic key into symbolic-key. Symbolic-key is the name of an alphanumeric
field that is large enough to contain the record's symbolic key.
• {CURRENCY|FIRST [CURRENCY]|LAST [CURRENCY]|{NEXT [CURRENCY]|{PRIOR [CURRENCY]} {USING
{key-field-name|'key-literal'}}
These parameters determine the record for which the database key is returned:
– CURRENCY -- the current index entry
– FIRST [CURRENCY] -- the first entry in the index
– LAST [CURRENCY] -- the last entry in the index
– NEXT [CURRENCY] -- the entry following current of index. If the current of index is the last entry, an error status of
1707 (END OF INDEX) is returned.
– PRIOR [CURRENCY] -- the entry before current of index
– USING -- the first index entry whose symbolic key matches the key-field-name or 'key-literal'. If no such entry exists,
a status code of 1726 (INDEX ENTRY NOT FOUND) is returned. The attributes of key-field-name or 'key-literal'
must match the symbolic key of the index.
IDMS ROLLBACK Statement
The IDMS ROLLBACK statement requests recovery.
This statement has the following format:
IDMS ROLLBACK [CONTINUE]
• [CONTINUE]
This optional parameter specifies the action taken after the recovery. The default is to terminate the run-unit.
IDMS STORE Statement
Format 1 of the IDMS STORE statement places a new record occurrence into the database. Format 2 places a new
logical record occurrence into the database.
This statement has the following format:
Format 1
{record-field-name}
IDMS STORE RECORD { }
{'record-literal' }
Format 2
IDMS STORE RECORD logical-record-name [WHERE (boolean-expression)]
Format 1
• RECORD {record-field-name|'record-literal'}
Record-field-name or 'record-literal' identifies the record to store. Record-field-name must be a 16-byte alphanumeric
field. 'Record-literal' must be alphanumeric and is padded to the right (if necessary) to create a 16-byte value.
Format 2
• RECORD logical-record-name
Logical-record-name is a one to sixteen-character name that identifies the logical record that CA IDMS stores.
• [WHERE (boolean-expression)]
872
CA Easytrieve® Report Generator 11.6
Code the optional WHERE clause to provide a Boolean expression CA IDMS uses to select the logical records to be
stored.
IF, ELSE-IF, ELSE, and END-IF Statements
The IF statement controls the execution of its associated statements. Associated statements are those that are coded
between IF and END-IF.
The truth value of conditional-expression-1 determines whether statement-1 is executed. If conditional-expression-1 is
true, CA Easytrieve® Report Generator executes statements designated by statement-1. If conditional-expression-1 is
false, CA Easytrieve® Report Generator tests conditional-expression-2, if ELSE-IF is specified.
If ELSE-IF is specified, the truth value of conditional-expression-2 determines whether statement-2 is executed. If
conditional-expression-2 is true, CA Easytrieve® Report Generator executes statements designated by statement-2. If
conditional-expression-2 is false, CA Easytrieve® Report Generator tests the conditional expression of the next ELSE-
IF, if specified. If the conditional expression of the last ELSE-IF statement is also false, CA Easytrieve® Report Generator
executes statements designated by statement-3. You can nest as many ELSE-IF statements within the IF as necessary.
You must terminate the IF statement with a single END-IF.
If ELSE-IF is not specified and conditional-expression-1 is false, CA Easytrieve® Report Generator executes statements
designated by statement-3.
If the ELSE statement is not specified and the conditional-expression is false, no statements are executed and control
passes to the statement following END-IF.
Statement-1, statement-2, and statement-3 each represent any number of CA Easytrieve® Report Generator statements.
Whenever one or more of these statements is an IF statement, the IF statements are considered to be nested. The format
of nested IF statements is that statement-1, statement-2, and statement-3 of any IF can be an IF statement.
This statement has the following format:
IF conditional-expression-1
[statement-1]
[ELSE-IF conditional-expression-2] [ . . . ]
[ [statement-2] ] [ ]
[ELSE ]
[ [statement-3] ]
END-IF
The following diagram illustrates IF, ELSE-IF, ELSE, and END-IF logic:
873
CA Easytrieve® Report Generator 11.6
• conditional-expression
For conditional expression syntax, see Conditional Expressions in the chapter "Statements A - C."
• ELSE-IF
ELSE-IF is optional and identifies a conditional expression to be tested when the previous conditional expression
is false. ELSE-IF statements allow multiple conditions to be nested without requiring an END-IF statement on each
condition. You can code as many ELSE-IF statements as necessary.
• ELSE
ELSE is optional and identifies the statements to be executed when conditions are false. When the conditions of the
preceding IF or ELSE-IF are not satisfied, CA Easytrieve® Report Generator continues execution with the statement
following ELSE.
NOTE
ELSE must be on a source statement by itself, unless it is followed by a period and a space.
• END-IF
END-IF terminates the logic associated with the previous IF statement. An END-IF statement must be specified after
each IF statement and its associated statements. You do not specify an END-IF for an ELSE-IF.
Examples
874
CA Easytrieve® Report Generator 11.6
The following three examples illustrate the IF statement usage. In each of the illustrated cases, the field XMAS-BONUS
is computed to be three or five percent over PAY-GROSS. If the field PAY-GROSS is non-numeric, a warning message is
issued and the record is bypassed from further processing.
Example 1, Without Nested IF Statements:
FILE PERSNL FB(150 1800)
%PERSNL
XMAS-BONUS W 4 P 2 VALUE 0
TOT-XMAS-BONUS W 6 P 2 VALUE 0
*
JOB INPUT PERSNL NAME MYPROG FINISH FINISH-PROC
IF PAY-GROSS NOT NUMERIC
DISPLAY EMP# ' PERSONNEL RECORD IS DAMAGED'
GO TO JOB
END-IF
IF PAY-GROSS > 500.00
XMAS-BONUS = PAY-GROSS * 1.03
ELSE
XMAS-BONUS = PAY-GROSS * 1.05
END-IF
TOT-XMAS-BONUS = TOT-XMASBONUS +
+ XMAS-BONUS
PRINT MYREPORT
*
FINISH-PROC. PROC
DISPLAY
DISPLAY 'TOTAL $ SPENT IN BONUS ' +
'MONEY ====> ' TOT-XMAS-BONUS
END-PROC
*
REPORT MYREPORT
LINE NAME-LAST XMAS-BONUS
Example 2, with Nested IF Statements:
FILE PERSNL FB(150 1800)
%PERSNL
XMAS-BONUS W 4 P 2 VALUE 0
TOT-XMAS-BONUS W 6 P 2 VALUE 0
*
JOB INPUT PERSNL NAME MYPROG FINISH FINISH-PROC
IF PAY-GROSS NOT NUMERIC
DISPLAY EMP# ' PERSONNEL RECORD IS DAMAGED'
GOTO JOB
ELSE
875
CA Easytrieve® Report Generator 11.6
IF PAY-GROSS > 500.00
XMAS-BONUS = PAY-GROSS * 1.03
ELSE
XMAS-BONUS = PAY-GROSS * 1.05
END-IF
END-IF
TOT-XMAS-BONUS = TOT-XMAS-BONUS + XMAS-BONUS
PRINT MYREPORT
*
FINISH-PROC. PROC
DISPLAY
DISPLAY 'TOTAL $ SPENT IN BONUS ' +
'MONEY ====> ' TOT-XMAS-BONUS
END-PROC
*
REPORT MYREPORT
LINE NAME-LAST XMAS-BONUS
Example 3, with ELSE-IF Statements:
FILE PERSNL FB(150 1800)
%PERSNL
XMAS-BONUS W 4 P 2 VALUE 0
TOT-XMAS-BONUS W 6 P 2 VALUE 0
*
JOB INPUT PERSNL NAME MYPROG FINISH FINISH-PROC
IF PAY-GROSS NOT NUMERIC
DISPLAY EMP# ' PERSONNEL RECORD IS DAMAGED'
GOTO JOB
ELSE-IF PAY-GROSS > 500.00
XMAS-BONUS = PAY-GROSS * 1.03
ELSE
XMAS-BONUS = PAY-GROSS * 1.05
END-IF
TOT-XMAS-BONUS = TOT-XMAS-BONUS + XMAS-BONUS
PRINT MYREPORT
*
FINISH-PROC. PROC
DISPLAY
DISPLAY 'TOTAL $ SPENT IN BONUS ' +
'MONEY ====> ' TOT-XMAS-BONUS
END-PROC
*
876
CA Easytrieve® Report Generator 11.6
REPORT MYREPORT
LINE NAME-LAST XMAS-BONUS
INITIATION Screen Procedure
An INITIATION procedure is invoked once during the start of the screen activity.
You use INITIATION to perform actions that are to be executed only once. Typically, you use INITIATION to initialize a field
or position a file at a specific starting position.
REFRESH and RESHOW are invalid in an INITIATION procedure.
If GOTO SCREEN is executed in an INITIATION procedure, the INITIATION procedure is terminated and the BEFORE-
SCREEN procedure is invoked.
An INITIATION procedure must be delimited by an END-PROC statement. For more information, see PROC Statement in
the chapter "Statements N - R."
This statement has the following format:
INITIATION. PROC
Example
INITIATION. PROC
MESSAGE 'Enter an employee number.' LEVEL INFORMATION
MOVE ZERO TO EMP-NO
MOVE SPACES TO EMPNAME
END-PROC
INSERT Statement
Use the INSERT statement to insert a row into a CA Easytrieve® Report Generator SQL file.
INSERT does not require an open cursor. If no cursor is open for the file, one is not opened automatically. If a cursor is
open, the inserted record does not appear in the cursor's result set until the cursor is closed and re-opened with a new
SELECT statement.
The file must be specified with the UPDATE parameter.
This statement has the following format:
INSERT [INTO] file-name
• [INTO]
Optionally, code INTO for statement readability.
• file-name
File-name identifies a CA Easytrieve® Report Generator SQL file.
Example
The following example inserts a new row into a table:
877
CA Easytrieve® Report Generator 11.6
FILE PERSNL SQL (PERSONNEL) UPDATE
EMPNAME * 20 A
WORKDEPT * 2 P 0
EMPPHONE * 3 P 0
PROGRAM NAME RETRIEVE-PERSONNEL
EMPNAME = 'WIMN GLORIA'
WORKDEPT = 921
EMPPHONE = 3478
INSERT INTO PERSNL
JOB Statement
The JOB statement defines and initiates a processing activity. In a JOB activity, statements can specify various processing
tasks:
• Retrieval of input files and databases
• Examination and manipulation of data
• Initiation of printed reports
• Production of output files and databases
The JOB statement can also identify the name of an automatic input file (which can be any file or database that is
processed sequentially).
JOB activities can be executed by PROGRAM or SCREEN activities. If a PROGRAM activity is not coded, JOB and
SORT activities are automatically executed sequentially until a SCREEN activity is encountered.
This statement has the following format:
JOB +
[ {(file-name [KEY field-name-1...)]...)} ]
[INPUT {NULL } ] +
[ {SQL } ]
[START start-proc-name] +
[FINISH finish-proc-name] +
[NAME job-name] +
[ { }]
[ENVIRONMENT{NONE }] +
[ {COBOL}]
[ [ACTIVITY ] [TERMINAL ] ]
[COMMIT ([ ] [ ])]
[ [NOACTIVITY] [NOTERMINAL] ]
• [INPUT]
The optional INPUT parameter identifies the automatic input to the activity.
878
CA Easytrieve® Report Generator 11.6
When you do not specify INPUT, CA Easytrieve® Report Generator automatically provides an input file. If a SORT
activity immediately preceded the current JOB activity, the default input is the output file from that SORT activity.
Otherwise, the default input is the first file named in the library section.
• {file-name}
File-name identifies the automatic input file. File-name identifies any file defined in the library section of the program
eligible for sequential input processing. When CA Easytrieve® Report Generator processes the last automatic input
record, CA Easytrieve® Report Generator terminates the job activity.
NOTE
Except in CICS, CA Easytrieve® Report Generator issues a GET HOLD for a VSAM file with the UPDATE
parameter as automatic input. This lets you update an automatic input file in all environments except CICS.
For more information about database processing, see the Programming Guide.
• {[KEY (key-field-name ...)]}
Specify key fields for JOB statement activities.
Code KEY (key-field-name) for each file-name of a synchronized file input process. During synchronized file
processing, CA Easytrieve® Report Generator sequentially processes the files, using KEY fields. KEY fields can be
any fields from the associated file. The only exceptions are varying length, index, or subscript fields, which cannot be
used as keys. For more detailed information about synchronized file processing, see the Programming Guide.
NOTE
Synchronized file processing is not allowed for CA IDMS and IMS/DLI database files.
• {NULL}
Code NULL as a file-name to inhibit automatic input. Use this when no input is required or when input is retrieved by
statements in the activity. When NULL is used, a STOP or TRANSFER statement must be executed in the JOB activity,
otherwise the activity executes indefinitely.
• {SQL}
Code SQL instead of a file-name to use automatic retrieval of an SQL database without a file. The selection criteria for
the input are specified on the non-file SQL SELECT statement that must immediately follow the JOB statement. For
more information about automatic retrieval without a file and SQL database processing, see the Programming Guide.
• [START start-proc-name]
The optional START start-proc-name parameter identifies a procedure to be executed during the initiation of the JOB.
CA Easytrieve® Report Generator optionally performs the procedure coded in start-proc-name before it retrieves the
first automatic input record. A typical START procedure sets working storage fields to an initial value or positions a file
to a specific record. You cannot reference fields in automatic input files, because no records have been retrieved at
this stage of processing.
If GOTO JOB is executed in a START procedure, the START procedure is terminated.
• [FINISH finish-proc-name]
The optional FINISH finish-proc-name parameter identifies a procedure to be executed during the normal termination
of the JOB. After CA Easytrieve® Report Generator processes the last automatic input record, it performs the finish-
proc-name procedure. A typical finish-proc-name procedure displays control information accumulated during the
activity.
If GOTO JOB is executed in a FINISH procedure, the FINISH procedure is terminated at that point.
If STOP EXECUTE is executed in the JOB activity, the FINISH procedure is not performed.
• ENVIRONMENT (z/OS only)
Specifies to establish the proper execution environment prior to calling any COBOL subprograms. The environment is
established prior to the JOB activity and is terminated after the activity termination.
ENVIRONMENT(COBOL) is ignored if the JOB activity contains no CALL statement and if no FILE EXITs are
specified. When used on the JOB statement, it establishes the ENVIRONMENT for only that JOB activity.
This processing is different if the JOB activity is invoked from within a PROGRAM activity if that PROGRAM activity
had activated the ENVIRONMENT, (through the PROGRAM ENVIRONMENT(COBOL) parm). In that case, the
PROGRAM activity's ENVIRONMENT will remain active during the execution of the invoked JOB activity, and the
879
CA Easytrieve® Report Generator 11.6
ENVIRONMENT will not end at the JOB activity termination. Even if ENVIRONMENT(NONE) is specified on the JOB
or PARM statements, the PROGRAM activity's ENVIRONMENT will remain active during the JOB activity execution.
When this parameter is absent, the default for ENVIRONMENT depends on how the ENVIRON system option was
set at installation and whether the ENVIRONMENT parameter of the PARM statement was specified. Using the
subparameter NONE overrides an existing default of COBOL and using COBOL overrides a default of NONE. See
the discussion of the PROGRAM statement, and see the chapter "Subprograms" for more information about this
parameter and the functionality of this feature.
• [NAME job-name]
The NAME parameter names the JOB activity. Job-name:
– Can be up to 128 characters in length
– Can contain any character other than a delimiter
– Can begin with A to Z, 0 to 9, or a national character (#, @, $)
– Must not consist of all numeric characters
This parameter is used for documentation purposes or to identify this JOB on an EXECUTE statement.
• [COMMIT [ACTIVITY|NOACTIVITY] [TERMINAL|NOTERMINAL]]
Specify the COMMIT parameter to control the logical unit of work. COMMIT indicates when the activity commits
recoverable work. Each commit point posts all updates, additions, and deletions, terminates holds, and closes SQL
cursors.
Specify ACTIVITY to commit all recoverable work during the normal termination of the activity. Specify NOACTIVITY to
tell CA Easytrieve® Report Generator not to commit at the end of the activity. NOACTIVITY is the default.
Specify TERMINAL to commit all recoverable work during any terminal I/O operation. In CICS, this results in terminal I/
O being performed in a pseudo-conversational mode. Specify NOTERMINAL to tell CA Easytrieve® Report Generator
not to commit during a terminal I/O. TERMINAL is the default.
If this activity is executed by an activity that has NOTERMINAL specified, this activity performs terminal I/O as if
NOTERMINAL was specified.
NOTE
You can also issue your own COMMIT and ROLLBACK statements to commit or recover work on a
controlled basis.
For more information, see the Programming Guide.
Examples
Example 1
The following example illustrates the position of the JOB activities in a CA Easytrieve® Report Generator program.
Environment
...
Library
...
Activities {JOB...
... {...
JOB, SCREEN { job procedures
and/or { ...
SORT { ...
... { reports
... { ...
For more information about JOB activity flow control, see the Programming Guide.
Example 2
The following example illustrates a JOB statement that automatically reads a sequential file:
880
CA Easytrieve® Report Generator 11.6
JOB INPUT PERSNL NAME SCAN-PERSONNEL-RECORDS
Example 3
The following example illustrates synchronized file processing. It shows a JOB statement for matching a transaction file
(TRANFILE) with a master file (MASTFILE). The JOB uses the FINISH parameter to execute a procedure when all the
input records have been recorded.
JOB NAME MATCH-FILES INPUT (TRANFILE KEY TRAN-EMP-NO +
MASTFILE KEY MAST-EMP-NO) +
FINISH DISPLAY-EOJ-MESSAGE
KEY Statement
Use the KEY statement to:
• Define valid keys for a screen
• Specify descriptive text to be displayed for each valid key
• Assign automatic functions to be executed for each valid key
If a key that is not defined on a KEY statement is pressed, an error message is displayed on the terminal prompting the
user to press a valid key.
If no KEY statements are coded, all keys are valid and you must provide code for all keys in your SCREEN activity
procedures.
The function key area is built depending on the sequence of keys specified in KEY statements. You must specify keys in
the order you want them displayed.
The key display area is built on the bottom line of a screen. If the key display area requires additional lines because of the
number of keys and the length of the descriptive text, additional lines at the bottom of the screen are used.
When used as the result of pressing an IMMEDIATE key, REFRESH redisplays the screen image with the original data
displayed on the screen. This is useful when the terminal user enters erroneous data on the screen and wants to restore
the screen with its original data.
When used as the result of a non-IMMEDIATE key, REFRESH can be used to rebuild the screen using current data from
the screen.
REFRESH can also be invoked by using the REFRESH statement. For more information, see REFRESH Statement in the
chapter "Statements N - R."
EXIT can also be invoked indirectly by executing it in a screen procedure. For more information, see EXIT Statement in
the chapter "Statements D - F."
NOTE
If you specify that one or more message areas use the same screen row as the function key area, messages
might overlap the function key area. The default for the message area is the row immediately preceding the key
display area.
Note: The CLEAR, PA1, PA2, and PA3 keys do not transmit data from the screen to the program. Also, cursor positioning
cannot be determined when these keys are pressed.
This statement has the following format:
[EXIT ]
KEY key-name [THRU key-name]...[NAME 'literal'] [ ] [IMMEDIATE]
881
CA Easytrieve® Report Generator 11.6
[REFRESH]
• key-name
Specify a symbolic name for a terminal key as described by the system-defined field, KEY-PRESSED.
KEY-PRESSED is a two-byte binary field that contains a value representing the most recent terminal key pressed by
the terminal user.
CA Easytrieve® Report Generator automatically defines symbolic names that correspond to values for the most
common keys:
Terminal Key Symbolic Name Constant Value
Enter ENTER 1
Clear CLEAR 11
PA1 to PA3 PA1 to PA3 12 to 14
PF1 to PF24 F1 to F24 21 to 44
F1 to F12 F1 to F12 21 to 32
NOTE
Only terminal keys with a KEY-PRESSED symbolic name can be used on a KEY statement. If other terminal
keys (such as test request) are required, you must test KEY-PRESSED using the constant value of the
terminal key in your program code. If you test for terminal keys without a symbolic name, you cannot code KEY
statements in your program.
• [THRU key-name]
Use THRU key-name to specify a range of key-names. A range of key-names includes all keys whose constant values
for KEY-PRESSED fall between the constant values of the keys you specify for the range. For example, if you code:
KEY CLEAR THRU F12
the PA1, PA2, and PA3 keys are also valid. The constant values of the PA keys (12, 13, 14) fall between the value for
CLEAR (11) and F12 (32).
NOTE
You can also specify a series of non-consecutive key-names by omitting THRU. You can optionally separate
a series of key-names with commas for readability. You can specify a range of key-names and a series of
key-names on the same KEY statement. See the examples below.
• [NAME 'literal']
The optional NAME parameter allows you to specify descriptive text to be displayed with the key on the screen. The
format displayed on the screen is:
key-name=literal
Example:
F1=Help F3=Exit F12=Cancel
'Literal' can contain a maximum of 20 characters.
To display only the key-name on a screen, code NAME 'literal' with a blank space between single quotes (' ').
If you do not code NAME, no display is created for the key.
• [EXIT|REFRESH]
Optionally, you can code EXIT or REFRESH to specify the branch action taken when a user presses key-name. If EXIT
or REFRESH is specified, the action is automatically executed by CA Easytrieve® Report Generator and the AFTER-
SCREEN procedure (if any) is not executed.
882
CA Easytrieve® Report Generator 11.6
Specify EXIT to terminate the screen activity after editing and extracting data from screen fields into program fields.
Specify REFRESH to restore the initial screen image by rebuilding it with current values of the program fields. Data in
screen fields is edited and extracted into program fields.
If no action is specified for key-name, you can test for key-name in your SCREEN activity procedures with the system-
defined field, KEY-PRESSED.
• [IMMEDIATE]
Specify IMMEDIATE to execute a branch action, or the AFTER-SCREEN procedure if no action is specified, without
editing data in screen fields and moving it into the program fields.
Examples
The following table shows KEY statement examples:
Code Meaning
KEY F1 F1 is valid, but nothing is displayed on the screen. You must
provide code.
KEY F1 THRU F24 F1 to F24 are valid keys, but nothing is displayed on the screen.
You must provide code for all keys.
KEY F1 NAME 'Help' F1 is valid. F1=Help is displayed on the screen. You must provide
code.
KEY F1 F4 F1 and F4 are valid keys, but nothing is displayed on the screen.
You must provide code.
KEY F1 THRU F4, F8 F1, F2, F3, F4, and F8 are valid keys, but nothing is displayed on
the screen. You must provide code for all keys.
KEY F12 EXIT NAME + F12 terminates the screen activity without moving data from
'CANCEL' IMMEDIATE screen fields into program fields. The AFTER-SCREEN procedure
(if any) is not executed. F12=CANCEL is displayed on the screen.
KEY F3 IMMEDIATE The AFTER-SCREEN procedure (if any) is executed without
editing or moving data in screen fields to program fields. Nothing
is displayed on the screen. You must provide code for F3.
KEY F3 EXIT F3 terminates the activity after editing and moving data from the
screen.
KEY F5 IMMEDIATE + REFRESH NAME + 'Refresh' F5 ignores the data on the screen and rebuilds the screen with
the values currently in memory. F5=Refresh is displayed on the
screen.
LINE Statement
The LINE statement defines the contents of a report line. One or more field values or literals can be contained on a report
line; each one is a line item. The data format of the field or literal remains unchanged.
For control reports, any quantitative field on the LINE statement is automatically totaled on each summary line. This
feature can be overridden on the SUM statement.
In an XML-formatted report, only one LINE statement is allowed. All LINE statement parameters except field-name and
'literal' are ignored. For a detailed description of the XML report feature, see the Programming Guide.
This statement has the following format:
{[ ] field-name }
{[#font-number] }
{[ ] 'literal' }
883
CA Easytrieve® Report Generator 11.6
LINE [line-number] {+offset } ...
{-offset }
{COL column-number }
{POS position-number }
• [line-number]
Specify the optional line number with line-number. The line number specifies the position of the line in the line group.
The value must be from 1 to 99; the default is 1. You can omit line-number for the first LINE. You must specify the line
numbers for multiple LINE statements in ascending order with no duplicates. Specify at least one data item (field-name
or literal) on each LINE statement.
• [#font-number]
#Font-number identifies the font specifications to be used for the next display item. You can only specify this option
if the report has been associated with an extended reporting printer. #Font-number identifies the number of a font
defined for the associated extended reporting printer. If you do not code the font, the next display item uses the default
font for the assigned extended reporting printer.
• {field-name}
Field-name can specify any field contained in an active file or in working storage. If the field is contained in a file or W
storage, data is transferred to the print line at the time the PRINT statement is executed. If the field is contained in S
storage, data is transferred to the print line at the time the line is printed.
NOTE
Field-name cannot specify a K field.
• {'literal'}
'Literal' defines a static value for a line item. It must be a numeric literal, a hexadecimal literal, or an alphanumeric
literal. Alphanumeric literals must be enclosed within single quotes.
• {+offset|-offset}
The space adjustment parameters, +offset or -offset, modify the spacing between line items. The offset value is added
to or subtracted from the SPACE value on the REPORT statement to give the absolute spacing between line items.
The absolute space value can range from zero to any amount that still allows the next line item to fit in the line defined
by LINESIZE on the REPORT statement.
• {COL column-number}
COL specifies the column number where the next line item is placed. The value of column-number has a valid range
of 1 to nnn, where nnn cannot be so large that the following line item extends beyond the end of the line defined by
LINESIZE.
NOTE
You must specify the NOADJUST parameter on the REPORT statement to use the COL parameter.
When the report is associated with an extended reporting printer, an error results if two or more fields and/or literals
overlap.
• {POS position-number}
The POS parameter lets you position line items on lines 2 to 99 so that they line up under particular line items on the
first line. Position-number corresponds to the line item number of LINE 01 under which the line item is placed.
Example
LINE 1 REGION BRANCH +5 DEPT EMPNAME
LINE 2 POS 4 ADDRESS
LINE 3 'NET==>' -2 PAY-NET POS 4 CITY ST ZIP
884
CA Easytrieve® Report Generator 11.6
LINK Statement
Use the LINK statement to transfer control from the current program (parent program) to another named program (child
program). When the child program terminates, execution is then returned to the statement following the LINK statement in
the parent program.
You can use LINK to invoke any program written in any language that is supported by the operating system in which
the program is executing, including CA Easytrieve Report Generator. Similarly, the program can issue any command
supported by the operating system.
A program invoked using the LINK statement can issue terminal I/O or display reports, but only in fully-conversational
mode. For more information, see the Programming section.
NOTE
If you code the USING or GIVING parameter on the LINK statement, you must code a PROGRAM statement to
handle the parameters in the child program when it is written in CA Easytrieve Report Generator.
This statement has the following format:
{program-field-name}
LINK { } +
{'program-name' }
[ {field-name} ]
[USING { } ] +
[ {'literal' } ]
[GIVING field-name ]
• {program-field-name|'program-name'}
Program-field-name is the name of the field that contains the name of the program to which you want to LINK.
'Program-name' is the name of the program to which you want to LINK.
• USING {field-name|'literal'}
Code USING to pass a single parameter to the child program.
Field-name is the name of a field containing the parameter you want to pass to the child program.
'Literal' is a literal value you want to pass to the child program.
• [GIVING field-name]
Specify GIVING to indicate that the parent program can accept a return parameter from the child program. Field-name
is the name of a field to which the returned parameter is written. For more information, see the Programming section.
NOTE
If the child program returns a value, but the GIVING parameter is not specified, the value is ignored. Not all
operating systems allow the child program to return data to the parent program.
Example
LINK 'PROGB' USING EMP# GIVING PROGB-RETURN
885
CA Easytrieve® Report Generator 11.6
LIST Statement
LIST regulates the printing or suppression of all statements in the printed output.
You can place a LIST statement anywhere in CA Easytrieve® Report Generator source code. LIST must be on a record by
itself.
LIST does not appear in the printed output.
To suppress all CA Easytrieve® Report Generator listing information, use the following:
LIST OFF
PARM LIST(NOPARM)
For more information, see PARM Statement in the chapter "Statements N - R."
This statement has the following format:
[ON ] [MACROS ]
LIST [ ] [ ]
[OFF] [NOMACROS]
• [ON|OFF]
ON specifies that all subsequent statements are to be printed. OFF suppresses the printing of all subsequent
statements.
• [MACROS|NOMACROS]
MACROS specifies that macro statements are to be printed if a LIST ON is in effect. NOMACROS suppresses the
printing of macro statements.
Default: LIST ON MACROS.
MACRO Statement
The MACRO prototype statement must be the first statement of a macro. It optionally defines the parameters of a macro.
You can use positional and keyword parameters. The definition of positional and keyword parameters follow the same
rules as Field and Label names (see "Syntax Rules").
This statement has the following format:
MACRO [positional-count] +
[positional-parameters] ... [keyword-parameters] ...
• MACRO
MACRO must be the first word on a prototype statement.
• [positional-count]
Positional-count is an optional parameter that specifies the number of positional-parameters on the prototype
statement. It is required only when you use keyword-parameters and positional-parameters. You must code the value
as zero when you specify only keyword-parameters on the prototype statement.
• [positional-parameters]
Use positional-parameters when a value is always required for the parameters each time the macro is invoked.
Frequently-used parameters are often positional, because you need only code the value of the parameter.
You must code positional-parameters before any keyword-parameters. The positional values are substituted according
to their position on the prototype statement.
• [keyword-parameters]
886
CA Easytrieve® Report Generator 11.6
Use keyword-parameters:
– To help keep track of a large number of parameters
– For optionally-used parameters
– To specify a default value for parameters
Keyword-parameters have two parts: the keyword name and the default value.
Examples
The following series of examples depict the coding of macro prototype statements. For more information about system
services, see the Programming Guide.
Macro with No Substitution MACRO
...
...
Macro with Only Positional MACRO POS1 POS2
...
...
The number of positional-parameters is not indicated. You could have coded the optional positional-count parameter as a
'2.'
Macro with Only Keyword MACRO 0 KEY1 VALUE1 KEY2 VALUE2
...
...
Code the number of positional-parameters as zero. Positional-count is a required parameter when you use keyword-
parameters.
Macro with Positional and Keyword MACRO 1 POS1 KEY1 VALUE1
...
...
Macros with both positional and keyword-parameters require that you supply positional-parameters first, and also supply a
positional-count.
MASK Parameter
The optional MASK parameter establishes a pattern (edit mask) for a field name. The MASK parameter can be coded in
the syntax of the following CA Easytrieve Report Generator statements:
• DEFINE
• ROW
This statement has the following format:
[MASK ({[mask-identifier][BWZ]['mask-literal']|HEX })]
• [mask-identifier]
Any letter from A to Y can be used as an optional mask-identifier. You can use the letter to identify a new mask or
to retrieve a mask that was previously defined in the Site Options Table or by a mask parameter on a previous field
definition. If the new mask that you identify does not already exist, the mask is retained for future reference. If you
subsequently reference a field-name for display, the associated letter identifier is automatically used to determine the
887
CA Easytrieve® Report Generator 11.6
edit mask. Do not use the same identifier to establish more than one mask. You can define 192 unidentified edit masks
and 25 identified edit masks for a total of 217 edit masks.
• [BWZ]
The BWZ (blank when zero) option suppresses the display of field-name when it contains all zeros. BWZ can be used
by itself or with other options on the MASK parameter.
• ['mask-literal']
'Mask-literal' defines an edit mask and must be enclosed within single quotes. For information about coding the actual
edit mask, see the Editing Rules section that follows.
• HEX
HEX is a special edit mask that instructs the product to display the contents of field-name in double-digit hexadecimal
format. You can display fields of up to 50 bytes with the HEX mask.
NOTE
HEX edit masks are not allowed for VARYING fields.
Editing Rules
• CA Easytrieve Report Generator edits field data only at the time of display and according to a specified edit mask
pattern.
• The MASK parameter of the DEFINE and ROW statements specifies the edit mask pattern.
• Each digit of the field must be designated in the mask by an edit mask character:
Symbol Meaning
9 Prints a digit.
Z Prints a digit, except for leading zeros.
* Prints asterisks instead of leading zeros.
- Prints a minus sign prior to the first non-zero digit of a negative
number.
$ Prints a currency symbol prior to the first non-zero digit. The type
of currency symbol ($, ¥, £, _, etc.) is determined by the MONEY
Site Option.
x Insertion symbol -- prints any character with the edited data.
Decimal Digits
• When you display data, there is no implied relationship between the number of decimal digits in the edit mask and the
number of decimal digits in the field definition. You must code the correct number of decimal digits in the mask.
• When screen data is edited against a mask, the decimal point is automatically aligned.
Alphanumeric Fields
• Alphanumeric fields cannot be edited. (The exception is MASK HEX.)
Currency Symbols
• The currency symbol indicator is recognized in the input edit mask and appears in the output edit mask. For example, if
the currency symbol is set to #, a valid edit mask is '###,##9.99.'
Insertion Symbols
• Z, $, -, and * print digits only when coded as the first symbol of the edit mask, and only up to the first nine symbols.
All other symbols before the last digit position are treated as insertion symbols, including Z, $, -, and *. The symbols
comma (,) and period (.) can also be used as insertion symbols.
Insertion symbols before the first digit position always print.
• Insertion symbols between digit positions print according to the following rules:
888
CA Easytrieve® Report Generator 11.6
– If the symbol that prints a digit following the insertion symbol is a 9, the insertion characters always print.
– If the digit position following the insertion symbols is a Z, $, -, or *, the insertion symbols print only if the digit position
prints. If the digit position does not print, the insertion symbols are replaced by fill symbols.
For example, in the mask 'ZZZ,999.99,' the comma always prints. In the mask 'ZZZ,Z99,99,' the comma prints only if the
digit prior to the comma is non-zero.
Fill Characters
• The default fill character for an edit mask is a blank, unless an * (asterisk) is specified.
Mask Display Length
• When the first symbol of an edit mask is a dash (-) or a currency symbol, the display length of the mask is the length of
the mask plus one.
• The mask for a SUM field in a report is automatically increased by the number of digits that are specified by the
SUMSPACE parameter on the REPORT statement. The first digit position is duplicated the required number of times.
Negative Indicators
• Symbols following the last digit position specify the negative indicator. The symbols print if the value edited is negative.
If the value edited is positive, the symbols are replaced by fill characters.
System Default Masks - Numeric Fields
When you do not specify a mask, the following defaults apply:
Number of
Decimals Mask
none ZZZZZZZZZZZZZZZZZZ *
0 ZZZ,ZZZ,ZZZ,ZZZ,ZZZ,ZZZ-
1 ZZ,ZZZ,ZZZ,ZZZ,ZZZ,ZZZ.9-
2 Z,ZZZ,ZZZ,ZZZ,ZZZ,ZZZ.99-
3 ZZZ,ZZZ,ZZZ,ZZZ,ZZZ.999-
4 ZZ,ZZZ,ZZZ,ZZZ,ZZZ.9999-
5 Z,ZZZ,ZZZ,ZZZ,ZZZ.99999-
6 ZZZ,ZZZ,ZZZ,ZZZ.999999-
7 ZZ,ZZZ,ZZZ,ZZZ.9999999-
8 Z,ZZZ,ZZZ,ZZZ.99999999-
9 ZZZ,ZZZ,ZZZ.999999999-
10 ZZ,ZZZ,ZZZ.9999999999-
11 Z,ZZZ,ZZZ.99999999999-
12 ZZZ,ZZZ.999999999999-
13 ZZ,ZZZ.9999999999999-
14 Z,ZZZ.99999999999999-
15 ZZZ.999999999999999-
16 ZZ.9999999999999999-
17 Z.99999999999999999-
18 .999999999999999999-
* For zoned decimal fields with no decimals, the default mask
is '999999999999999999'.
Your system administrator can define additional edit masks in the Site Options Table when the product is installed.
889
CA Easytrieve® Report Generator 11.6
Leading Zeros
Various methods are available for processing leading zeros.
Display
When leading zeros are an important part of the number (such as social security numbers and part numbers) an edit mask
that displays these zeros is essential. These are examples of edit masks that display leading zeros:
Mask Field Contents Displayed Results
999-99-9999 053707163 053-70-7163
(99)-9999 006421 (00)-6421
Suppress
In some instances, leading zeros add unnecessary information and can confuse the reader. You can suppress the display
of leading zeros by using one of the following masks:
Mask Field Contents Displayed Results
$$,$$9 01234 $1,234
$$,$$9 00008 $8
$$,$$9.99 0123456 $1,234.56
ZZZ,ZZ9 000123 123
---,--9 +001234 1,234
---,--9 -001234 -1,234
Replace
In cases where fields must be protected (such as check amounts), you can use edit masks that replace leading zeros with
other symbols:
Mask Field Contents Displayed Results
**9 001 **1
**,**9 01234 *1,234
**,**9.99 0123456 *1,234.56
Negative Numbers
The symbols that are used as negative number indicators are displayed to the right of the last digit of the negative data
that you edit. You can use any symbols as negative number indicators, although the most typical indicators are the minus
sign (-) and the credit indicator (CR). If the number is positive, display of these symbols is inhibited. However, when the
field contents turn negative, the negative number indicators are edited into the displayed output as follows:
Mask Field Contents Displayed Results
ZZZ- -123 123-
ZZZ- +123 123
ZZZ CR -123 123 CR
ZZZ CR +123 123
ZZZ IS MINUS -123 123 IS MINUS
Examples
890
CA Easytrieve® Report Generator 11.6
The following edit mask examples illustrate editing mask rules:
Mask Field Contents Displayed Results
'Z,ZZZ,ZZZ.99' .01 .01
'ZZHELLOZZ9.99' 123.01 123.01
'ZZHELLOZZ9.99' 1234.01 1HELLO234.01
'**HELLO**9.99' 11.01 ********11.01
'**HELLO**9.99' 123.99 *******123.99
'**HELLO**9.99' 1234.99 *1HELLO234.99
'$$99$$99.99' 1234.99 $02$$34.99
'999Z999.99' 12345.99 012Z345.99
'SSN 999-99-9999' 123456789 SSN 123-45-6789
'ZZZ.99 MINUS' 12.45 12.45
'ZZZ.99 MINUS' -12.45 12.45 MINUS
'***.99 MINUS' 12.45 *12.45******
'***.99 MINUS' -12.45 *12.45 MINUS
'---.99' 123.45 123.45
'---.99' -123.45 -123.45
MEND Statement
The MEND statement is an optional macro termination command used at the end of a macro. MEND is required at the
end of an instream macro. See also MSTART Statement in this chapter.
MEND must be coded on a line by itself.
This statement has the following format:
MEND
MESSAGE Statement
The MESSAGE statement allows you to issue your own specific messages for a screen activity. You define the message
type and specify the message text using the MESSAGE statement.
You can code the MESSAGE statement in a screen procedure or in another activity.
You can determine where messages of a particular level are displayed on the screen by overriding the default message
area on a DEFAULT statement. (The default message area is one line above the function key display area at the bottom
of the screen.) You can also use the DEFAULT statement to override default message attributes.
CA Easytrieve® Report Generator maintains an internal message area for each type of message. The MESSAGE
statement updates the pending message area. When the next screen is displayed, the screen message area is built from
the pending message.
If different levels of messages are displayed on the same line (by default or override), then the message displayed is
controlled by message precedence. If two messages are sent to the same line on the screen, the message with the
highest severity is displayed. The severity precedence from highest to lowest is:
891
CA Easytrieve® Report Generator 11.6
• ACTION
• WARNING
• INFORMATION
If multiple MESSAGE statements of the same precedence are issued before displaying the screen, the last message
issued is displayed. There are Site Options that determine the display attributes for the three levels of messages. You can
override these attributes on a DEFAULT statement.
This statement has the following format:
MESSAGE {'literal' }
{ } ... +
{field-name}
[ {INFORMATION} ]
[LEVEL {WARNING } ]
[ {ACTION } ]
• {'literal'} or {field-name}
Use 'literal' to define the text you want displayed in the message. Use field-name to specify a field whose contents you
want displayed as part of the message. A message can consist of a combination of literals and field-names.
The maximum length of a message is 130 characters. If the message exceeds the message area for the screen on
which it is displayed, the message is truncated.
• [LEVEL {INFORMATION|WARNING|ACTION}]
Use LEVEL to specify the type of message you are defining.
INFORMATION messages typically inform a user that processing is proceeding normally.
WARNING messages tell the user that a potentially undesirable condition could occur or has occurred, even though
the error can be ignored.
ACTION messages are the most severe. They tell a user that an error has occurred and an action is required to correct
the error before continuing. ACTION is the default message level if no level is specified.
Example
MESSAGE 'Department of ' EMP-DEPT ' not 900-999.' LEVEL ACTION
MOVE Statement
MOVE transfers character strings from one storage location to another. The MOVE statement is especially useful for
moving data without conversion and for moving variable length data strings.
When you specify Format 1 parameters, data moves from left to right as if both areas were alphanumeric. The data
moved is unconverted. Send-file-name and receive-file-name can be any file in which data is currently available. For more
information about MOVE statement specification rules, see the Programming section.
When you process an SQL table as a CA Easytrieve Report Generator file, the product knows which fields are nullable.
This information is obtained automatically from the SQL catalog when used to generate CA Easytrieve Report Generator
field definitions.
This statement has two formats.
Format 1
892
CA Easytrieve® Report Generator 11.6
{send-file-name }
{send-record-name } [send-length-field ]
MOVE { } [ ] +
{send-field-name } [send-length-literal ]
{send-literal }
{receive-file-name } [receive-length-field ]
TO {receive-record-name} [ ] [FILL fill-character]
{receive-field-name } [receive-length-literal]
• {send-file-name} or {send-record-name} or {send-field-name} or {send-literal}
The first parameter after the MOVE keyword (send-file-name, send-record-name, send-field-name, or send-literal)
identifies the sending data area. Send-file-name or send-record-name can be any file or database record with current
data availability. When send-file-name is a CA IDMS file, all records in the file are moved.
The default length of send-file-name is the current value of the system-defined RECORD-LENGTH field.
NOTE
If send-literal is non-numeric, it must be enclosed within single quotes.
• [send-length-field] or [send-length-literal]
You can override the length of the sending field with the current value of send-length-field or send-length-literal.
• {receive-file-name} or {receive-record-name} or {receive-field-name}
These parameters identify the receiving data area. Receive-file-name or receive-record-name can be any file or
database record with current data availability. The default length of receive-file-name is the current value of the
system-defined RECORD-LENGTH field.
• [receive-length-field] or [receive-length-literal]
You can override the length of the receiving field with the current value of receive-length-field or receive-length-literal.
• [FILL fill-character]
Longer sending fields on the right are truncated. Longer receiving fields are padded on the right with spaces or a
character you specify in fill-character.
Fill-character must be one or two bytes. Non-numeric characters must be enclosed within single quotes. When fill-
character contains numeric characters, they are treated as a zoned decimal value.
Example
FILE PERSNL SQL (PERSONNEL)
SQL INCLUDE (EMP#) FROM PERSONNEL LOCATION * NULLABLE
DEFINE CTR1 W 10 N
DEFINE CTR2 W 2 N
DEFINE PLINE W 130 A
. . .
MOVE ZEROS TO CTR1, CTR2
MOVE SPACES TO PLINE
MOVE NULL TO EMP#
Format 2
{NULL }
{SPACE }
{SPACES }
893
CA Easytrieve® Report Generator 11.6
MOVE { } TO receive-field-name...
{ZERO }
{ZEROS }
{ZEROES }
{HIGH-VALUES}
{LOW-VALUES }
• {NULL} or {SPACE} or {SPACES} or {ZERO} or {ZEROS} or {ZEROES} or {HIGH-VALUES} or {LOW-VALUES}
The first parameter after the MOVE keyword (NULL, SPACE, SPACES, ZERO, ZEROS, ZEROES, HIGH-VALUES, or
LOW-VALUES) identifies the sending data area. The default length of the field is the defined length of receive-field-
name. Moving spaces or zeros to a field fills the entire field with the selected character. Moving nulls sets a nullable
field to NULL. Moving spaces or zeros sets a nullable field to NOT NULL.
• receive-field-name
Receive-field-name identifies the receiving data area. You can specify multiple receive-field-names. Receive-field-
names are set to the appropriate data format, such as packed zero for fields with a type of P.
Example
Statements:
DEFINE ASTERISK-LINE W 10 A VALUE '=========='
DEFINE COUNTER-1 W 10 N VALUE 99
DEFINE COUNTER-2 W 2 N VALUE 66
PROGRAM NAME MYPROG
DISPLAY COUNTER-1 +2 COUNTER-2
MOVE ZEROS TO COUNTER-1 COUNTER-2
DISPLAY COUNTER-1 +2 COUNTER-2
DISPLAY ASTERISK-LINE
MOVE '*' TO ASTERISK-LINE FILL '*'
DISPLAY ASTERISK-LINE
Results:
0000000099 66
0000000000 00
==========
**********
MOVE LIKE Statement
The MOVE LIKE statement moves the contents of fields with identical names from one file, record, or working storage to
another. Data movement and conversion follow the rules of the assignment statement.
This statement has the following format:
{send-file-name } {receive-file-name }
MOVE LIKE { } TO { }
{send-record-name} {receive-record-name}
• {send-file-name} or {send-record-name}
894
CA Easytrieve® Report Generator 11.6
Send-file-name or send-record-name identifies the sending data area.
• {receive-file-name} or {receive-record-name}
Receive-file-name or receive-record-name identifies the receiving data area.
Usage Notes
When you issue a MOVE LIKE statement, the contents of fields in send-file-name or send-record-name replace the
contents of fields with identical names in receive-file-name or receive-record-name. When receive-file-name or receive-
record-name contains overlapping fields, the order in which the fields are defined is important. The moves occur starting
with the first identically-named field in receive-file-name or receive-record-name and ending with the last identically-named
field in the file.
NOTE
The order in which fields are processed differs from previous versions of the product. In previous versions, the
moves occurred starting with the last identically-named field in receive-file-name or receive-record-name and
ended with the first identically-named field in the file.
If you want to move identically-named fields to or from working storage, you can use the keyword WORK as the send-file-
name or receive-file-name.
CA IDMS IDD Processing
In CA IDMS IDD processing, the fields of a file defined by an IDD statement are organized into group item structures.
A group item is a field subdivided by smaller fields. The smaller fields can themselves be group items and, therefore,
subdivided by even smaller fields. A group item owns its subdividing fields. A field without subdivision is called an
elementary field.
In IDD processing, MOVE LIKE assigns a new value to the receiving field if all of the following conditions are met:
• The sending and receiving fields have matching names.
• The sending and receiving fields have matching qualifier (group item) names.
• Either the sending or receiving field is an elementary field.
Record name qualifiers do not participate in the process of matching qualifiers between two fields. For example, in a
MOVE LIKE from a record to a file (that owns the record), no matching is done between the record names of the receiving
file and qualifiers of source (record) fields. Therefore, source fields can be matched to a field under one record and
another source field can be matched to a field under a different record.
Differences Between MOVE LIKE and MOVE
The differences between the MOVE LIKE statement and the MOVE statement are as follows:
• The MOVE LIKE statement generates an assignment statement that provides data conversion according to data type.
For assignment statement specification rules, see the Programming section.
• The MOVE statement moves data without converting it.
Example
FILE PERSNL FB(150 1800)
REGION 1 1 N
BRANCH 2 2 N
NAME 17 16 A
NAME-LAST 17 8 A
NAME-FIRST 25 8 A
FILE MYFILE FB(150 1800)
895
CA Easytrieve® Report Generator 11.6
COPY PERSNL
JOB INPUT PERSONL NAME MYPROG
MOVE LIKE PERSNL TO MYFILE
PUT MYFILE
In this example, MOVE LIKE generates the following assignment statements:
MYFILE:NAME-FIRST = PERSNL:NAME-FIRST
MYFILE:NAME-LAST = PERSNL:NAME-LAST
MYFILE:NAME = PERSNL:NAME
MYFILE:BRANCH = PERSNL:BRANCH
MYFILE:REGION = PERSNL:REGION
Whatever values were in the fields of the file PERSNL are now found in the fields of the file MYFILE.
MSTART Statement
The MSTART statement is used to begin an instream macro. MSTART must be the first statement in the program.
This statement has the following format:
MSTART macro-name
• macro-name
Specify the name of the macro. Macro-name must be from one to eight characters in length. The first character must be
alphabetic.
NOTE
For CA Panvalet and CA Endevor libraries the macro name can be from 1 to 10 characters in length.
NEWPAGE Statement
NEWPAGE is a listing control statement that ejects the printer to the top of the next page before printing the next line of
the source program on the statement listing.
You can code a NEWPAGE statement anywhere in CA Easytrieve® Report Generator source code. NEWPAGE must be
on a record by itself. NEWPAGE does not appear in the printed output.
This statement has the following format:
NEWPAGE
PARM Statement
The PARM statement lets you override selected general standards for a program that are set in the Site Options Table.
Alteration of the environment with the PARM statement lasts for only as long as the program is running.
Specification of the PARM statement is optional. Code the PARM statement only to modify the environment for your
program. If used, the PARM statement must be the first statement in your CA Easytrieve® Report Generator job.
Environment <============== PARM
...
Library
896
CA Easytrieve® Report Generator 11.6
...
Activities
Code PARM statement parameters and their subparameters in any order. You must code multiple subparameters within
parentheses.
PARM establishes program-level parameters in the following areas:
• SYNTAX, COMPILE, and LINK determine the mode of execution.
• ABEXIT, DEBUG, and LIST establish control over system facilities associated with compiler output and execution error
handling.
• VFM establishes system control parameters.
• SORT controls the interface to your installation's sort program.
• BIND, PLAN, PREPNAME, SQLID, SSID, USERID, PLANOPTS, and SQLSYNTAX establish parameters for SQL
execution.
• TRANSID controls CICS execution.
For more information about controlling CA Easytrieve® Report Generator with the PARM statement, see Compile and Link
Your Program.
This statement has the following format:
PARM +
[ {SNAP } ]
[ABEXIT {NOSNAP} ] +
[ {NO } ]
[ {DYNAMIC } ]
[BIND {STATIC-ONLY} ] +
[ {ANY } ]
[ {STATIC } ]
[CALL {DYNAMIC} ] +
[ {AMODE24} ]
[ {EBCDIC } ]
[CODE PROCESS {ASCII } ] +
[ {dbcs-code-name} ]
[COMPAREUSINGALTSEQ {YES|NO } ] +
[COMPILE] +
[ {MMDDYY}]
[DATE {YYMMDD}] +
[ {DDMMYY}]
[ [CLIST ] [PMAP ] [DMAP ] [FLDCHK ] [FLOW ]
[DEBUG ( [ ] [ ] [ ] [ ] [ ] +
[ [NOCLIST] [NOPMAP] [NODMAP] [NOFLDCHK] [NOFLOW]
[STATE ] [XREF {LONG } ] ]
[FLOWSIZ number-of-table-entries] [ ] [ { } ] ) ] +
[NOSTATE] [NOXREF {SHORT} ] ]
[ { }]
897
CA Easytrieve® Report Generator 11.6
[ENVIRONMENT{NONE }] +
[ {COBOL}]
[LINK (program-name [R])] +
[ [FILE ] [PARM ] ]
[LIST ([ ] [ ] ] +
[ [NOFILE] [NOPARM] ]
[PLAN (planname [command-program-name])] +
[PLANOPTS 'plan-options-module'] +
[PREPNAME(SQL-access-module ['access-userid'])] +
[SORT +
[ {NO } ]
([ALTSEQ { } ] +
[ {(YES [alt-sort-table])} ]
[DEVICE device-type] +
[ {storage-amount } ]
[MEMORY { } ] +
[ {(MAX [-storage-released])} ]
[ {ALL [CONSOLE] } ]
[ { [PRINTER] } ]
[ { } ]
[MSG ( {CRITICAL [CONSOLE] } ) ] +
[ { [PRINTER] } ]
[ {DEFAULT } ]
[ {NO } ]
[RELEASE core-storage-amount] +
[WORK number-of-work-data-sets])] +
[SQLID 'auth-id'] +
[ {FULL } ]
[SQLSYNTAX {PARTIAL} ] +
[ {NONE } ]
[SSID 'ssid'] +
[SYNTAX] +
[TRANSID 'transid'] +
[USERID ('connect-userid' ['password'])] +
898
CA Easytrieve® Report Generator 11.6
[ [ {DISK } ] ]
[VFM ([buffer-core-storage] [DEVICE { } ] ) ] +
[ [ {MEMORY} ] ]
[ {YES} ]
[WORKFILE ( { } [number-of-cylinders] )]
[ {NO } ]
ABEXIT
[ABEXIT {SNAP|NOSNAP|NO}]
ABEXIT indicates the level of control exercised over program interrupt codes 1 to 11. SNAP prints a formatted dump of CA
Easytrieve® Report Generator storage areas along with an error analysis report. NOSNAP prints only an error analysis
report. NO inhibits CA Easytrieve® Report Generator interception of program interrupts.
It is advisable that the ABEXIT value in the site options table be set to NO, and to use the PARM ABEXIT(SNAP or
NOSNAP) during development as a debugging aid. Before moving the CA Easytrieve® Report Generator program into
production, remove the PARM ABEXIT override. This will reduce overhead for production applications.
BIND
[BIND {DYNAMIC|STATIC-ONLY|ANY}]
BIND is an SQL-related parameter that identifies the type of SQL bind that you want for the execution of your application
program. BIND is currently used only by the mainframe DB2 SQL interface. It is ignored in other environments.
BIND DYNAMIC results in the dynamic execution of the SQL statements in your program. Dynamic processing
requires SQL statements to be dynamically prepared before they can be executed. The SQL interface controls the SQL
environment and does not prepare SQL statements repeatedly unless a syncpoint has been taken.
BIND STATIC-ONLY indicates that your application program is to execute statically. This option requires the creation of
a static-command-program that is then processed by the DB2 preprocessor. The DB2 preprocessor generates a DBRM
and finally a PLAN. During the execution of your application program, the SQL interface processes the SQL statements
in the static-command-program. If any errors are found in the static-command-program or its PLAN, SQL processing is
terminated.
BIND ANY indicates that a static-command-program is to be generated and a PLAN created, as with an option of STATIC-
ONLY. However, if the SQL interface encounters any errors with the static-command-program or its PLAN during the
execution of your application program, it switches to dynamic processing.
BIND STATIC-ONLY or BIND ANY requires a value for the PLAN and LINK parameters. PLAN specifies the name of
the static-command-program and its DB2 PLAN name. LINK identifies the load module name of your link-edited CA
Easytrieve® Report Generator program. Your CA Easytrieve® Report Generator application program must run as a link-
edited program for static SQL processing.
Note: Regardless of the option you specify for the BIND parameter, your program is dynamically processed when being
processed by the interpreter, that is, whenever the CHECK or RUN commands are executed.
If no value is specified for the BIND parameter in the program or in the options table, DYNAMIC is the default mode of
execution. Otherwise, the BIND value in the options table becomes the default.
The following table shows the use of the BIND parameter with the value specified in the options table.
BIND Parameter Options Table Options Table Options Table Options Table
Value Value Value Value
Value None A S D
None BIND defaults to BIND defaults to BIND defaults to BIND defaults to
DYNAMIC ANY STATIC-ONLY DYNAMIC
ANY ANY is the BIND ANY is the BIND Invalid -- an error Invalid -- an error
parameter parameter occurs occurs
899
CA Easytrieve® Report Generator 11.6
STATIC-ONLY STATIC-ONLY is the STATIC-ONLY is the STATIC-ONLY is the Invalid -- an error
BIND parameter BIND parameter BIND parameter occurs
DYNAMIC DYNAMIC is the Invalid -- an error Invalid -- an error DYNAMIC is the
BIND parameter occurs occurs BIND parameter
CALL
[CALL {STATIC|DYNAMIC|AMODE24|AMODE31}]
CALL enables you to specify how subprograms referenced in CALL statements are linked to your CA Easytrieve®
Report Generator program. STATIC indicates that you want the subprogram to be linked with your CA Easytrieve®
Report Generator program. DYNAMIC indicates that you want the subprogram to be dynamically loaded. The default is
DYNAMIC on the mainframe and in Windows, and the default is STATIC in Unix environments. Individual subprograms
can override this setting using the DECLARE statement. AMODE24 indicates that this CA Easytrieve® Report Generator
program will be calling an AMODE-24 subprogram, (using the CALL statement or as a FILE EXIT). This will cause the
CA Easytrieve® Report Generator runtime to allocate all dynamic storage and record buffers below the 16 MB line.
AMODE31 allows all possible memory allocations to be made above the 16MB line. The default AMODE is the setting of
the AMODE31 system installation option.
CODE PROCESS
[CODE PROCESS {EBCDIC|ASCII|dbcs-code-name}]
(Mainframe DBCS) Use CODE dbcs-code-name to define the DBCS code system to be used for all K and M fields for this
file. If this parameter is not specified here, the default is taken from the processing code system as defined in the CA PSI
Subsystems DBCS Options Table.
Note: Using multiple code systems in a program can result in a longer execution time due to code system conversions.
COMPAREUSINGALTSEQ
[COMPAREUSINGALTSEQ {YES|NO}]
Identifies whether the collating sequence table is used for the character compare process. YES indicates that the collating
sequence table is used. NO indicates that the collating sequence table is not used. For more information about the
alternate collating sequence table, see Alternate Collating Sequence Table.
COMPILE
[COMPILE]
COMPILE terminates execution after the completion of the syntax check and compile operations. Use COMPILE to review
the code generated in the CA Easytrieve® Report Generator Program Map (PMAP).
DATE
[DATE {MMDDYY|YYMMDD|DDMMYY}]
DATE specifies the format of the date placed at the top of the compiler listing and the date stored in the system-defined
SYSDATE field. Valid values are MMDDYY, YYMMDD, and DDMMYY, where MM is the month, DD is the day, and YY is
the year.
DEBUG
[DEBUG]
DEBUG and its subparameters control generation of certain system outputs.
WARNING
These outputs are very helpful to analyze programming errors that cause abnormal execution termination
(ABENDs).
900
CA Easytrieve® Report Generator 11.6
ENVIRONMENT
ENVIRONMENT (z/OS only)
Specifies to establish the proper execution environment prior to calling COBOL subprograms. The environment is
established prior to each JOB activity that contains a CALL statement and is terminated after the activity for which it was
established.
When used on the PARM statement, it establishes the default (NONE or COBOL) for all JOB activities in the entire
program. When this parameter is absent, the default for ENVIRONMENT depends on the ENVIRON setting within the Site
Options Table being used. Using this parameter overrides that setting.
This parameter does not establish the default for PROGRAM activities. If the environment is desired for the PROGRAM
activity, the ENVIRONMENT parameter must be specified on the PROGRAM statement. The ENVIRONMENT is not
supported in SORT activities, or in REPORT PROCs executed within a SEQUENCEd REPORT. For more information
about this parameter and its functionality of this feature, see the PROGRAM and JOB statements, and the Code
Programs section.
LINK
[LINK (program-name [R])]
On the mainframe, controls the generation of the link editor NAME command as follows:
• If LINK(program-name) is specified, 'NAME program-name' is generated as the last line in the object deck.
• If LINK(program-name R) is specified, 'NAME program-name (R)' is generated as the last line in the object deck. The
subparameter R specifies that the program replaces an existing program with the same name.
• If no LINK parm is specified, no NAME command is generated into the object deck. In this case, the NAME command
must be provided manually in the link edit JCL. For example:
//LINK EXEC PGM=IEWL,PARM='LET,LIST,MAP'
...
//SYSLIN DD DISP=SHR,DSN=&&OBJECT.FROM.COMPILE
// DD *
NAME PROGNAM(R)
/*
NOTE
On non-mainframe platforms, LINK is ignored
LIST
[LIST [FILE|NOFILE] [PARM|NOPARM]]
LIST controls the printing of certain system outputs.
FILE prints file statistics at the end of each activity. NOFILE inhibits this operation.
PARM prints a compile summary and system parameters at the conclusion of the syntax check operation. NOPARM
inhibits this operation.
[PLAN (planname [command-program-name])]
PLAN is an SQL parameter. Currently, it is used only by the mainframe DB2 SQL interface.
The PLAN parameter enables you to specify values for the static-command-program and its DB2 PLAN. The name
you specify for the static-command-program must be a valid load module name. This name must be different from the
program-name specified for the LINK parameter.
The value specified for planname must be the name of the DB2 PLAN that identifies the DBRM of the given static-
command-program. For information about how to generate the static-command-program, see Program Environment.
If not specified, command-program-name defaults to planname.
Because the link-edit of the static-command-program and the bind of the DB2 PLAN are performed outside the control of
CA Easytrieve® Report Generator, you must specify the correct names on the batch JCL to ensure successful execution
of your program.
901
CA Easytrieve® Report Generator 11.6
[PLANOPTS 'plan-options-module']
PLANOPTS is an SQL parameter. Currently, this parameter is used only by the CA Datacom/DB SQL interface.
Use PLANOPTS to specify the name of the plan options module that is to override the default CA Easytrieve® Report
Generator plan options module.
[PREPNAME (SQL-access-module ['access-userid'])]
PREPNAME is an SQL parameter. Currently, it is used by the SQL/DS and CA Datacom/DB SQL interfaces.
For the SQL/DS SQL interface, the PREPNAME parameter enables you to specify the name of the access module or
package that is to be associated with the SQL statements for this application program.
For the CA Datacom/DB SQL interface, PREPNAME enables you to specify the access plan.
For either database, the PREPNAME parameter also enables you to specify an owner ID ('access-userid') for the access
module or access plan. For information about obtaining an authorization ID, see your specific database documentation.
If PREPNAME is not specified, SQL-access-module defaults to program-name on the LINK parameter. If the LINK
parameter is not specified, SQL-access-module defaults to the value specified in the Site Options Table.
NOTE
You should specify a unique value for the SQL-access-module for each CA Easytrieve® Report Generator
program. If you use the same name for either parameter value, database catalog contention can occur, or
an existing access module could be replaced with another one. For information about establishing naming
conventions, see your database administrator.
PREPNAME can be abbreviated to PREP.
[SORT]
SORT overrides the default parameters used to interface with your installation's sort program. For information about these
SORT parameters, see the installation procedures on your product media.
• – [ALTSEQ {NO|(YES [alt-sort-table])}]
ALTSEQ identifies the collating sequence table for the sort process. NO indicates usage of the standard table. YES
identifies an alternative table. Alt-sort-table specifies the name of the table that you provide. When you omit alt-sort-
table, the default name is EZTPAQTT.
– [DEVICE device-type]
DEVICE specifies the device type for dynamically allocated sort work data sets. Device-type can be any valid unit
name or generic device type.
– [MEMORY {storage-amount|(MAX [-storage-released])}]
MEMORY specifies the maximum amount of core storage used by the sort program. Storage-amount is the amount
of storage made available for the sort and must be a value from 16 to 4096. MAX allows the sort program to obtain
maximum storage available. Storage-released is the amount of storage released (for system use) after the MAX
amount has been reserved. A minus sign must immediately precede storage-released. Storage-amount and
storage-released values represent 1024-byte units of storage.
– [MSG {ALL|CRITICAL [CONSOLE|PRINTER]}|{DEFAULT|NO}]
Specifies the level of messages to be output by the sort program.
ALL outputs all messages. CRITICAL outputs only critical level messages. DEFAULT outputs messages at the level
specified when the sort program was installed. NO outputs no messages.
For ALL or CRITICAL messages, specify the location at which messages are received: PRINTER or CONSOLE.
– [RELEASE core-storage-amount]
RELEASE determines the amount of core storage reserved from the sort program. The value of core-storage-
amount should be set large enough to supply all of the core storage needs of any exits used as a part of the sort
process. Core-storage-amount must be a numeric value from 0 to 1024. The value represents 1024-byte units of
storage.
– [WORK number-of-work-data-sets])]
WORK specifies the type and number of work data sets used by the sort.
The value of number-of-work-data-sets controls the allocation of work data sets. When number-of-work-data-sets
is zero, you must supply DD statements for all work data sets (none are dynamically allocated). A number-of-work-
data-sets value from 1 to 31 specifies the number of work data sets dynamically allocated by the sort program.
902
CA Easytrieve® Report Generator 11.6
[SQLID 'auth-id']
SQLID is an SQL parameter. Currently, this parameter is used only by the mainframe DB2 SQL interface.
SQLID enables you to change the authorization ID of your SQL session. If you specify a value for 'auth-id', the DB2 SET
CURRENT SQLID command is executed by the DB2 SQL interface at compile time. For the SET CURRENT SQLID
command to execute successfully, you must have installed the CA Pan/SQL Interface for a DB2 release of 2.1 or greater.
You must also have the correct DB2 authorization to execute the SET CURRENT SQLID command. For more information
about the SET CURRENT SQLID command, see your DB2 documentation.
This parameter is in effect only for the compilation of your application program, unless your program is coded using
automatic processing. If your program is coded using automatic processing, the SET CURRENT SQLID command is
executed again at the start of runtime. For native SQL processing, you must code the SET CURRENT SQLID command in
your program if you want to change the value for the current authorization ID.
For more information, see the SQL Database Processing section.
[SQLSYNTAX {FULL|PARTIAL|NONE}]
Use SQLSYNTAX to specify the level of SQL syntax checking that is to be performed on the SQL statements coded in
your program.
Specify FULL to indicate that detail level syntax checking should be performed. An SQL PREPARE statement is executed
by the CA Pan/SQL interface for those SQL statements that can be dynamically prepared. If you specify FULL, your
DBMS catalog must be available to CA Easytrieve® Report Generator.
Specify PARTIAL to indicate that SQL statements in your program should be syntax checked for valid commands and
secondary keywords. No connection is made to the DBMS catalog unless you have coded the SQL INCLUDE statement.
If you coded an SQL INCLUDE statement, your DBMS catalog must be available to CA Easytrieve® Report Generator.
Your program cannot be executed until it has been fully syntax checked, as described above.
Specify NONE with a BIND STATIC-ONLY parameter if you want syntax checking to be performed by the DB2
preprocessor in a batch environment. NONE causes partial syntax checking, as described above. If no compile errors
are found, your program executes, unless CA Easytrieve® Report Generator errors are found. No connection is made to
the DBMS catalog unless you have coded the SQL INCLUDE statement. If you coded an SQL INCLUDE statement, your
DBMS catalog must be available to CA Easytrieve® Report Generator.
If you specify NONE for a non-DB2 environment, partial syntax checking is performed, but the program is not executed
until full syntax checking is performed.
When running under the CA Easytrieve® Report Generator interpreter, dynamic processing is always performed. An
option of NONE is effective only for the batch compilation and execution of your program.
[SSID 'ssid']
SSID is an SQL parameter. Currently, SSID is used only by the DB2, Sybase, and Ingres interfaces.
(For mainframe DB2) You can use SSID to specify the DB2 subsystem ID. If you specify this value, it is used at both
compile and runtime. If you do not specify the DB2 subsystem ID, the subsystem ID from the Site Options Table is used.
If no DB2 subsystem ID is specified in the Site Options Table, the SQL interface uses the ID from the DB2 system default
module DSNHDECP. The value of the subsystem ID is obtained at compile and runtime dynamically; therefore, there is
no need to recompile your program to change the ID. For the default values defined for your DB2 system, see your DB2
systems programmer or administrator.
(For non-mainframe platforms) You can use SSID to specify the name of the database or ODBC data source to which this
session will connect. If you do not specify the subsystem ID, the subsystem ID from the Site Options Table is used. If no
DB2 subsystem ID is specified in the site options table, DB2 uses the ID in the DB2DBDFT environment variable.
SSID is ignored in CICS.
[SYNTAX]
SYNTAX terminates CA Easytrieve® Report Generator processing after the syntax check operation.
[TRANSID 'transid']
(CICS only) Use TRANSID to specify the transaction identifier of a program to which control is transferred when the
application user presses an attention key after a pseudo-conversational terminal I/O.
[USERID ('connect-userid' ['password'])]
903
CA Easytrieve® Report Generator 11.6
USERID is an SQL parameter. Currently, USERID is used by the SQL/DS, CA IDMS, and non-mainframe SQL interfaces.
USERID is used by the SQL interface to establish a connection to the database for compilation of the application program.
(For SQL/DS) You can use USERID to specify a valid userid and password for an explicit CONNECT.
(For CA IDMS) You can use 'connect-userid' to specify the CA IDMS dictionary name for an explicit CONNECT. If you do
not specify USERID, an implicit connection occurs according to the rules of the given database system.
(For non-mainframe SQL interfaces) You can use 'connect-userid' to specify the user identifier under which this session
will run. If you do not specify USERID, an explicit connection occurs without an 'identified-by' clause. 'Password' is
ignored.
NOTE
USERID can be abbreviated as USER.
[VFM ([buffer-core-storage] [DEVICE {DISK|MEMORY}])]
VFM establishes the work area parameters used by the CA Easytrieve® Report Generator Virtual File Manager access
method.
Buffer-core-storage specifies the amount of core storage made available for the buffer pool. Valid numeric values for
buffer-core-storage are 6 to 4096. Buffer-core-storage represents 1024-byte units of storage.
DEVICE DISK reverts to disk device usage when the site option default is DEVICE MEMORY. DEVICE MEMORY inhibits
the use of an overflow device.
[WORKFILE ( {YES|NO} [number-of-cylinders])]
Use WORKFILE YES instead of VFM if you have multiple large reports in your program. NO is the default. When YES is
specified, sequential temporary disk files will be dynamically allocated for use as Report Workfiles. The space allocated
for each file is indicated by the number-of-cylinders parameter. If DD statements are coded for the Report Workfiles, the
number-of-cylinders parameter is ignored. For more information about print statement processing, see PRINT Statement
(Report Processing).
Examples
The following examples illustrate typical uses of the PARM statement.
Example: Use of PARM for Production
PARM LINK(MYPROG) DEBUG(CLIST, DMAP) +
SORT (MSG (ALL, PRINTER))
FILE PERSNL FB(150 1800)
%PERSNL
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1
LINE EMPNAME DEPT
Example: Use of PARM for Program Testing
PARM ABEXIT (SNAP) +
DEBUG (PMAP, DMAP, FLDCHK, FLOW, +
FLOWSIZ (20), STATE)
FILE PERSNL FB(150 1800)
%PERSNL
JOB INPUT PERSNL NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1
904
CA Easytrieve® Report Generator 11.6
LINE EMPNAME DEPT SALARY-COD
PERFORM Statement
PERFORM transfers control to a procedure and, after the procedure has been executed, returns control to the next
executable statement after the PERFORM statement.
When CA Easytrieve® Report Generator encounters the PERFORM statement, it immediately branches to the named
procedure. After exiting from the procedure, program execution continues with the next executable statement following the
just-executed PERFORM statement.
PERFORM statements in a procedure can invoke other procedures; this is called procedure nesting. However, recursion
is not permitted. That is, procedure A can invoke procedure B, but procedure B cannot then invoke procedure A. If
recursion is attempted, unpredictable results can occur.
This statement has the following format:
PERFORM proc-name
• proc-name
Specify the name of the procedure to be executed.
Example
The following example illustrates the use of the PERFORM statement in executing a user procedure:
FILE PERSNL FB(150 1800)
%PERSNL
XMAS-BONUS W 4 P 2 VALUE 0
*
JOB INPUT PERSNL NAME MYPROG
IF PAY-GROSS < 300.99
PERFORM SPECIAL-BONUS
ELSE
PERFORM STANDARD-BONUS
END-IF
PRINT MYREPORT
*
SPECIAL-BONUS. PROC
XMAS-BONUS = PAY-GROSS * 1.20
END-PROC
*
STANDARD-BONUS. PROC
XMAS-BONUS = PAY-GROSS * 1.05
END-PROC
*
REPORT MYREPORT
LINE NAME-LAST XMAS-BONUS
905
CA Easytrieve® Report Generator 11.6
POINT Statement
The POINT statement enables you to establish the position in an INDEXED or RELATIVE file from which subsequent data
is sequentially retrieved. Data in the file becomes available only after the next successful sequential retrieval by either
automatic file input or a GET statement.
You cannot use a file presence test (IF file-name) to test the success of a POINT.
You cannot issue a GET PRIOR statement following a POINT statement, or a GET statement following a POINT PRIOR
statement. For more information, see GET Statement in the chapter "Statements G - M."
GE is not supported for POINT PRIOR when the underlying access method does not support it.
This statement has the following format:
{= }
{EQ} {field-name}
POINT file-name [PRIOR] {GE} { } [STATUS]
{GQ} {literal }
{>=}
• file-name
File-name must be the same as on a FILE statement that describes an INDEXED or RELATIVE file.
• [PRIOR]
Specify PRIOR if you want to use PRIOR on the GET statement. For more information, see GET Statement in the
chapter "Statements G - M."
• {= } or {EQ} or {GE} or {GQ} or {>=}
Equal operators (= and EQ) initiate a file position search, based on an exact match between the file's keys and the
search value. The greater-than operators (GE, GQ, and >=) initiate a file position search, based on a file's key being
equal to or greater than the search value.
• {field-name} or {literal}
The search value can be any valid field-name or literal. Alphanumeric literals must be enclosed within single quotes.
CA Easytrieve® Report Generator does not change the data format of field-name or literal. The search value must
have the same length as the file's key. RELATIVE files require field-name to be a 4-byte binary integer field. Field-
name cannot be nullable. Literal is not allowed for a RELATIVE file.
• [STATUS]
Specify the STATUS parameter whenever the possibility exists for an unsatisfactory completion of the input/output
request.
STATUS checks input/output processing to see if it was performed correctly. STATUS causes the file's FILE-STATUS
field to be set with the appropriate return code. To determine the meaning of the contents of FILE-STATUS, see the
appendix "System-Defined Fields." Normally, a zero or non-zero test is sufficient.
NOTE
FILE-STATUS is not defined if you do not specify a file type parameter on the FILE statement.
If you do not code STATUS and the operating system returns a non-zero status, CA Easytrieve® Report Generator
issues an appropriate diagnostic message.
In addition to FILE-STATUS, IF EOF file-name is true when the search value is greater than the highest key in the file.
NOTE
CICS does not set EOF.
Example
The following example illustrates the use of POINT:
906
CA Easytrieve® Report Generator 11.6
FILE PERSNL INDEXED
%PERSNL
JOB INPUT NULL NAME MYPROG
POINT PERSNL GE '01963' STATUS
IF FILE-STATUS NE 0 OR EOF PERSNL
DISPLAY 'BAD POINT...FILE STATUS= ' FILE-STATUS
STOP
END-IF
GET PERSNL STATUS
IF FILE-STATUS NE 0
DISPLAY 'BAD GET...FILE STATUS= ' FILE-STATUS
ELSE
DISPLAY HEX PERSNL
END-IF
STOP
For more detailed examples on the use of POINT in file processing, see the Programming Guide.
POP Statement
POP is a listing control statement that restores previous listing control indicators.
POP is especially useful in macros to control the listing of the macro expansion without affecting listing control indicators
outside the macro. Use the PUSH statement to save the current indicators. You can then set listing control indicators for
use during macro expansion. The POP statement restores the saved indicators.
NOTE
Use the LIST statement to set listing control indicators.
You can place POP statements anywhere in the CA Easytrieve® Report Generator source code. POP must be on a record
by itself. POP does not appear in the printed output.
This statement has the following format:
POP
PRINT Statement
The PRINT statement produces report output. Issue the PRINT statement to initiate a printed line.
In general, report output is not written directly to a report's printer file as with DISPLAY, but is scheduled for deferred
formatting and writing to the report's printer file, perhaps following resequencing of an intermediate file.
For detailed examples of the use of PRINT in report processing, see the Programming Guide.
When you require an intermediate file (referred to as a report work file) for a report, executing PRINT causes fixed format
records (called spool records) to be output to the work file. CA Easytrieve® Report Generator determines the format of
these records, which includes all the fields required to produce the report except those in S type working storage.
This statement has the following format:
PRINT [report-name]
• [report-name]
Report-name is the name of the report as specified on a REPORT statement. If not given, it is assumed to be the first
report in the JOB activity.
907
CA Easytrieve® Report Generator 11.6
Example
FILE PERSNL FB(150 1800)
%PERSNL
JOB INPUT PERSNL NAME PRINT-RPT
PRINT REPORT1
REPORT REPORT1
TITLE 'PERSONNEL REPORT'
LINE EMP# SSN EMPNAME
PROC Statement
The PROC statement is used to begin a CA Easytrieve® Report Generator procedure. A procedure is a group of user-
written CA Easytrieve® Report Generator statements designed to accomplish a particular objective. The syntax of a
procedure has two statements:
• A label naming the procedure
• The PROC statement
In most cases, you can code any statement in a procedure. However, you cannot code certain input/output statements
(such as GET, PUT) in procedures invoked during SORT or REPORT processing.
PERFORM statements within a procedure can invoke other procedures; this is called procedure nesting. However,
recursion is not permitted. That is, procedure A can invoke procedure B, but procedure B cannot then invoke procedure A.
If recursion is attempted, unpredictable results can occur.
Screens and reports can contain special-named procedures. Each procedure is explained separately in this manual.
The screen procedures are as follows:
• AFTER-SCREEN
• BEFORE-SCREEN
• INITIATION
• TERMINATION
The report procedures are as follows:
• AFTER-BREAK
• AFTER-LINE
• BEFORE-BREAK
• BEFORE-LINE
• ENDPAGE
• REPORT-INPUT
• TERMINATION
This statement has the following format:
Format 1
proc-name. PROC
statement-1
...
statement-n
END-PROC
908
CA Easytrieve® Report Generator 11.6
Format 2
proc-name
PROC
statement-1
...
statement-n
END-PROC
• proc-name
Proc-name is a label that identifies the procedure. A label:
– Can be up to 128 characters in length
– Can contain any character other than a delimiter
– Can begin with A to Z, 0 to 9, or a national character (#, @, $)
– Must not consist of all numeric characters
Proc-name must be followed by the keyword PROC as a separate statement.
• statement-1...n
Statement-1 to statement-n are the statements that accomplish your procedure's task.
• END-PROC
The END-PROC statement delimits the statements contained in the procedure.
PROGRAM Statement
The PROGRAM statement identifies and initiates a processing activity that can optionally initiate JOB, SORT, and
SCREEN activities.
NOTE
Programs that include the PROGRAM statement must be compiled with the NEWFUNC option set to Y. The
following message is displayed when a program that includes the PROGRAM statement is compiled with the
NEWFUNC option set to N (compatibility mode):
*******B014 UNABLE TO RECOGNIZE STATEMENT
For more information about the NEWFUNC option, see Features and Enhancements Since Release 6.4.
A PROGRAM statement is required when:
• A program is the target of a TRANSFER from another program and parameters are passed between programs. See
TRANSFER Statement in the chapter "Statements S - Z."
• A program is the child program linked to from a parent program and parameters are passed between programs. See
LINK Statement in the chapter "Statements G - M."
• A parameter is passed to a program invoked from the operating system.
• You want to selectively execute other activities or execute a single activity multiple times.
A PROGRAM statement defines an activity in which JOB, SORT, and SCREEN activities can be conditionally invoked.
If there is no PROGRAM statement, any JOB or SORT activities are sequentially executed until a SCREEN activity is
detected. The SCREEN activity is then executed. The sequential execution of activities does not proceed past the first
SCREEN activity. Any remaining activities must be executed by the first SCREEN activity.
A program terminates when:
909
CA Easytrieve® Report Generator 11.6
• The bottom of the activity is reached
• A STOP EXECUTE statement is executed
• A TRANSFER statement is executed
A PROGRAM statement can be used to execute a sequence of statements. You can also use a JOB INPUT NULL
statement; however, you must then execute a STOP statement to terminate the activity.
This statement has the following format:
[ [ACTIVITY ] [TERMINAL ] ]
PROGRAM [NAME program-name] [COMMIT ([ ] [ ])] +
[ [NOACTIVITY] [NOTERMINAL] ]
[ENVIRONMENT {NONE }] +
[ {COBOL}]
[USING field-name] [GIVING field-name]
• [NAME program-name]
The NAME parameter names the processing activity. Program-name identifies the program. Program-name:
– Can be up to 128 characters in length
– Can contain any character other than a delimiter
– Can begin with A to Z, 0 to 9, or a national character (#, @, $)
– Must not consist of all numeric characters
This parameter is used for documentation purposes.
• [COMMIT ([ACTIVITY|NOACTIVITY] [TERMINAL|NOTERMINAL])]
Specify the COMMIT parameter to control the logical unit of work. COMMIT indicates when the activity commits
recoverable work. Each commit point posts all updates, additions, and deletions, terminates holds, and closes SQL
cursors.
Specify ACTIVITY to commit all recoverable work during the normal termination of the activity. Specify NOACTIVITY to
tell CA Easytrieve® Report Generator not to commit at the end of the activity. ACTIVITY is the default.
Specify TERMINAL to commit all recoverable work during any terminal I/O operation. In CICS, this results in terminal I/
O being performed in a pseudo-conversational mode. Specify NOTERMINAL to tell CA Easytrieve® Report Generator
not to commit during a terminal I/O. TERMINAL is the default.
If this program is linked to by another CA Easytrieve® Report Generator program, this program performs terminal I/O
as if NOTERMINAL was specified.
NOTE
You can also issue your own COMMIT and ROLLBACK statements to commit or recover work on a
controlled basis.
For more information about commit processing, see the Programming Guide.
• ENVIRONMENT (z/OS only)
Specifies to establish the proper execution environment prior to calling any COBOL subprograms. The environment
is established prior to the PROGRAM activity startup and is terminated after the activity has terminated.
ENVIRONMENT(COBOL) is ignored if the PROGRAM activity contains no CALL or EXECUTE statement, and if no
FILE EXITs are specified.
The COBOL ENVIRONMENT started at the PROGRAM activity level stays active during any JOB activities invoked
from that PROGRAM activity. If the PROGRAM activity does not start a COBOL ENVIRONMENT, (or if there is no
PROGRAM activity), the COBOL ENVIRONMENT will be started for the JOB activities as directed by the PARM
ENVIRONMENT or the JOB ENVIRONMENT parameter specification.
When this parameter is absent, the default is ENVIRONMENT(NONE). No PARM statement, or Site Option default is
used. See JOB Statement for more information about this parameter and the functionality of this feature.
910
CA Easytrieve® Report Generator 11.6
WARNING
For performance considerations, we recommend that you set the ENVIRONMENT option to COBOL if many
CA Easytrieve® Report Generator programs are calling Language Environment subprograms. The option
should be set to NONE if most CALLs are made to non-Language Environment subprograms.
• [USING field-name]
Specify USING to indicate that this program (child program) can accept a parameter from the parent program or
operating system. Field-name is the name of a field to which the parameter is passed.
NOTE
The data for the field-name consists of a two-byte length value followed by the data. If the field-name
definition includes the VARYING parameter, the data in the field is alphanumeric and of varying length. This
applies to the standard way that z/OS invokes main programs. For more information about the VARYING
parameter, see DEFINE Statement.
If the program is linked via the LINK option of the PARM statement, the program could be invoked directly
on the JCL EXEC statement. Other programs could also invoke the program, but the other program must
observe the standard type one linkage convention. For more information, see "Conventions for passing
information through a parameter list" in the IBM z/OS MVS Programming: Assembler Services Guide,
available on the IBM website.
• [GIVING field-name]
Code GIVING to return a single parameter to the parent program. Field-name is the name of a field containing the
parameter you want to return to the parent program.
Example: Equivalent Statements
FILE ...
...
PROGRAM NAME EXAMPLE1
EXECUTE JOB1
EXECUTE PANEL1
JOB NAME JOB1
...
SCREEN NAME PANEL1
...
is equivalent to:
FILE ...
...
JOB NAME JOB1
...
SCREEN NAME PANEL1
...
Example: PROGRAM Statement with the USING Parameter
This example shows how the USING parameter can be used with the PROGRAM statement. The field that the USING
parameter accesses is named JCL-PARM, which is defined in the code with the VARYING option. The program
TESTPARM receives the value for JCL-PARM from the PARM argument of the EXEC statement for the parent program
EZTPA00.
Program code:
//COMP EXEC PGM=EZTPA00,PARM='0123456789ABCDEF'
//SYSIN DD *
911
CA Easytrieve® Report Generator 11.6
PARM DUMP(PCODE)
DEFINE JCL-PARM S 100 A VARYING
PROGRAM NAME TESTPARM USING(JCL-PARM)
EXECUTE TESTPARM1
JOB INPUT(NULL) NAME TESTPARM1
DISPLAY 'JCL-PARM: +' JCL-PARM '+'
DISPLAY 'JCL-PARM:LENGTH: +' JCL-PARM:LENGTH '+'
STOP
Program output:
JCL-PARM: +0123456789ABCDEF +
JCL-PARM:LENGTH: + 16 +
PUSH Statement
PUSH is a listing control statement that saves the current listing control indicators.
PUSH is useful in macros to control the listing of the macro expansion without affecting the listing control indicators
outside the macro. PUSH saves the current indicators. You can then set the listing control indicators for use during macro
expansion. Use the POP statement to restore the saved indicators.
NOTE
Use the LIST statement to set listing control indicators.
You can code a PUSH statement anywhere in CA Easytrieve® Report Generator source code. PUSH must be on a record
by itself. PUSH does not appear in the printed output.
This statement has the following format:
PUSH
PUT Statement
The PUT statement performs sequential file output. PUT outputs records to SEQUENTIAL files and also adds consecutive
records (mass sequential insertion) to an INDEXED or RELATIVE file.
To take advantage of VSAM's mass-sequential-insertion capabilities, you can use the PUT statement to add many records
to the same place in any established VSAM file.
If you use the PUT statement, you must include the UPDATE parameter on the FILE statement for RELATIVE or
INDEXED files. You must specify CREATE for SEQUENTIAL files. UPDATE informs CA Easytrieve® Report Generator
that all input records can potentially be updated or deleted.
This statement has the following format:
[ {input-file-name] }]
PUT output-file-name [FROM { }][STATUS]
[ {input-record-name}]
• output-file-name
The output-file-name parameter identifies the output file.
• [FROM {input-file-name|input-record-name}]
FROM identifies the file or record from which the current record is copied.
When input-file-name is specified, the length of the output data is the same as output-file-name: RECORD-LENGTH.
The current value of input-file-name: RECORD-LENGTH is equal to the length of the input data. However, if the length
912
CA Easytrieve® Report Generator 11.6
of the output file is greater than the length of the input file, the excess storage is not initialized. Also, use of the FROM
parameter does not update the data area of the output file.
For more information about RECORD-LENGTH, see the Programming Guide.
• [STATUS]
Specify the STATUS parameter whenever the possibility exists for an unsatisfactory completion of the input/output
request.
STATUS checks input/output processing to see if it was performed properly. STATUS causes the file's FILE-STATUS
field to be set with the appropriate return code. To determine the meaning of the contents of FILE-STATUS, see
System-defined Fields. Normally, a zero or non-zero test is sufficient.
NOTE
FILE-STATUS is not defined if you do not specify a file type parameter on the FILE statement.
If you do not code STATUS and the operating system returns a non-zero status, CA Easytrieve® Report Generator
issues an appropriate diagnostic message.
Example
FILE FILEA INDEXED UPDATE
%PERSNL
FILE PERSNL
COPY FILEA
JOB INPUT PERSNL NAME MYPROG
PUT FILEA FROM PERSNL STATUS
IF FILE-STATUS NE 0
DISPLAY 'ADD FAILED'
DISPLAY HEX PERSNL
STOP
END-IF
READ Statement
READ provides random access to INDEXED and RELATIVE files.
The key specified is normally a working storage field or a field in another file. It cannot be the key field of the file unless
WORKAREA is specified to make the field available prior to the READ.
You can use a file presence test (IF file-name) to determine the success of the READ. The test is true when the last GET
or READ was successful.
This statement has the following format:
{key-field-name} [HOLD ]
READ file-name KEY { } [ ] [STATUS]
{'key-literal' } [NOHOLD]
• file-name
Specify the file-name of the INDEXED or RELATIVE file to be randomly accessed.
• KEY {key-field-name|'key-literal'}
You must provide the key to the required record. The contents of key-field-name or 'key-literal' are used in a search for
a corresponding record in the file. Alphanumeric literals must be enclosed within single quotes. The data format of key-
field-name or 'key-literal.' is not changed. The access method can require that the search value have the same length
as the file's key. Key-field-name cannot be nullable.
913
CA Easytrieve® Report Generator 11.6
RELATIVE files require key-field-name to be a 4-byte binary integer field. 'Key-literal' is not allowed for a RELATIVE
file.
• [HOLD|NOHOLD]
A hold request is automatically issued for records when UPDATE is specified on the FILE statement. Use NOHOLD to
override this process.
Specify HOLD to hold a record for update. This is the default when UPDATE is specified for the file. HOLD is invalid
if UPDATE is not specified on the FILE statement. HOLD does not mean you are required to perform the update. It
holds the position of the file and can also lock the record (CICS only). Records are automatically released when the
update operation completes or a commit point is taken. You can also manually release the hold on any record with the
RELEASE statement.
NOHOLD specifies that a record is not held for update.
• [STATUS]
Specify the STATUS parameter whenever the possibility exists for an unsatisfactory completion of the input/output
request.
STATUS checks input/output processing to see if it was performed properly. STATUS causes the file's FILE-STATUS
field to be set with the appropriate return code. To determine the meaning of the contents of FILE-STATUS, see
System-Defined Fields. Normally, a zero or non-zero test is sufficient.
NOTE
FILE-STATUS is not defined if you do not specify a file type parameter on the FILE statement.
If you do not code STATUS and the operating system returns a non-zero status, an appropriate diagnostic message is
issued.
The key specified is normally a working storage field or a field in another file. It cannot be the file's key field unless
WORKAREA is specified to make the field available prior to the READ.
You can use a file presence test (IF file-name) to determine the success of the READ. The test is true when the last
GET or READ was successful.
Example
FILE PERSNL INDEXED
%PERSNL
FILE INKEYS SEQUENTIAL
WHO 1 5 N
TOTAL-NET W 5 P 2
JOB INPUT INKEYS NAME MYPROG FINISH DISPLAY-TOTAL
READ PERSNL KEY WHO STATUS
IF PERSNL:FILE-STATUS NE 0
DISPLAY 'UNSUCCESSFUL READ +
PERFORMED ON FILE PERSNL' +
+2 'KEY= ' WHO
ELSE
TOTAL-NET = TOTAL-NET + PAY-NET
END-IF
DISPLAY-TOTAL. PROC
DISPLAY 'TOTAL NET PAY' TOTAL-NET
END-PROC
RECORD Statement (CA IDMS and IMS/DLI)
Code RECORD statements (Format 1) following the FILE statement to identify the CA IDMS database records available
for automatic or controlled processing.
914
CA Easytrieve® Report Generator 11.6
RECORD statements (Format 2) identify the IMS/DLI database segments that are to be available for processing.
CA IDMS
All fields defined following the RECORD statement are part of this record. The name of each field must be unique within
the record. However, the field does not have to be unique within the file that contains the record being defined. If a field
defined in another record has the same name as a field defined in this record, then all references to either field must be
qualified with the name of the field's containing record.
NOTE
The RECORD statement cannot be used to define logical records. To define a logical record, use the LOGICAL-
RECORD statement. To define an element record within a logical record, use the ELEMENT-RECORD
statement.
IMS/DLI
RECORD allocates a work space that contains the segment data during execution. Field definition statements, coded
immediately following a RECORD statement, relate to data fields within that segment. One RECORD statement must
be coded for each segment of the database to be processed. They must be coded in the same order as in the PSB that
defines the database. Not all segments of a database need to be defined, but the parent segment of each RECORD must
be coded because incomplete paths are not supported.
This statement has the following format:
Format 1 (CA IDMS)
RECORD record-name record-length [KEY (field-name ...)]
Format 2 (IMS/DLI)
RECORD segment-name segment-length [parent-segment-name] +
[KEY (key-field-name, key-field-location, key-field-length)]
Format 1 (CA IDMS)
• record-name
Record-name is the 1- to 16-character name of the record as defined in the subschema.
• record-length
Record-length is a positive integer that designates the length of the record as defined in the subschema.
• [KEY (field-name ...)]
KEY is an optional parameter that identifies the CALC keys of the record. The KEY parameter is required only for the
root record when using the tickler file. Field-name is the 1- to 30-character name used to designate one of the record's
CALC keys. Field-name must correspond to a CALC key field defined with the DDL for the record. You must code the
field-name parameter for each CALC key defined for the record.
In addition, a DEFINE statement for each field-name must be coded following the RECORD statement. The DEFINE
statement can be intermingled with DEFINE statements for other non-key fields of the record.
Format 2 (IMS/DLI)
• segment-name
Segment-name is the one- to eight-character name of the segment. This name must correspond to the name of a
segment in the DBD.
• segment-length
Segment-length is a positive numeric integer that designates the length of the segment.
• [parent-segment-name]
915
CA Easytrieve® Report Generator 11.6
Parent-segment-name is an optional parameter that designates the parent of segment-name. This parameter is not
coded for the root segment, but it is required for all other segments.
• [KEY]
The optional KEY parameter identifies the sequence field for the segment.
The KEY parameter is not necessary for the RECORD statement that defines the lowest segment in a path. The KEY
parameter is required for the root segment when using the tickler file.
• (key-field-name)
Key-field-name is the one- to eight-character name used to designate the keyfield to the IMS/DLI database. The name
must correspond to the sequence field named in the DBD.
• (key-field-location)
Key-field-location is a positive numeric integer that specifies the location of the key field within the segment.
• (key-field-length)
Key-field-length is a positive numeric integer that specifies the length of the key field.
REFRESH Statement
The REFRESH statement is used in the AFTER-SCREEN procedure to restore the initial screen image by rebuilding it
with the current values of the program fields.
When used as the result of pressing an IMMEDIATE key, REFRESH redisplays the screen image with the original data
displayed on the screen. This is useful when the terminal user enters erroneous data on the screen and wants to restore
the screen with its original data.
When used as the result of a non-IMMEDIATE key, REFRESH can be used to rebuild the screen using current data from
the screen.
REFRESH can also be invoked directly by pressing a particular attention key. For more information, see KEY Statement.
This statement has the following format:
REFRESH
Example
The following example illustrates the REFRESH statement being invoked when F6 is pressed. Because F6 is not an
IMMEDIATE key, the current values of QTY and PRICE are used to compute the extended price. F5 is used to clear
erroneous data from the screen.
DEFINE EXT-PRICE W 4 P 2
DEFINE QTY W 4 P 0
DEFINE PRICE W 4 P 2
SCREEN NAME TEST-REFRESH
KEY F2 NAME 'Reset to zero'
KEY F3 EXIT NAME 'Exit'
KEY F5 IMMEDIATE REFRESH NAME 'Refresh screen'
KEY F6 NAME 'Compute Ext Price'
TITLE 'TEST REFRESH'
ROW 3 'Quantity . .' QTY
ROW 5 'Price . . .' PRICE
ROW 7 'Ext Price .' EXT-PRICE
BEFORE SCREEN. PROC
MOVE ZERO TO QTY, PRICE, EXT-PRICE
END-PROC
AFTER-SCREEN. PROC
916
CA Easytrieve® Report Generator 11.6
IF KEY-PRESSED = F6
EXT-PRICE = QTY * PRICE
REFRESH
END-IF
END-PROC
RELEASE Statement
The RELEASE statement explicitly releases the hold on any record in a file.
CA Easytrieve® Report Generator automatically issues a hold request for GETs and READs when UPDATE is specified
on the FILE statement. Records are automatically released when the update operation completes or a commit point
is taken. Alternatively, you can use the RELEASE statement to manually release the hold on a record. If HOLD is not
specified, RELEASE is ignored.
This statement has the following format:
RELEASE file-name
• file-name
File-name is the name of a file.
Example
READ PERSNL KEY '01193' HOLD
...
IF ...
WRITE PERSNL UPDATE
ELSE
RELEASE PERSNL
END-IF
REPEAT and END-REPEAT Statements
The REPEAT/END-REPEAT construct is used to display arrays on a screen.
Each array field on a ROW statement can be subscripted by the subscript specified in the VARYING parameter.
Optionally, array fields on ROW statements can contain a subscript for a second dimension. However, CA Easytrieve®
Report Generator does not automatically increment this second subscript.
This statement has the following format:
[ [ {start-field-name} ] ]
REPEAT number [TIMES] [VARYING subscript [FROM { } ] ] +
[ [ {start-integer } ] ]
[ROW row-number]
ROW statements
917
CA Easytrieve® Report Generator 11.6
END-REPEAT
• number
Number is the number of times the group of ROW statements in the REPEAT construct is repeated.
• [TIMES]
Optionally, code TIMES for statement readability.
• [VARYING subscript]
VARYING is an optional parameter that causes CA Easytrieve® Report Generator to automatically increment a
subscript field (subscript).
The subscript is incremented by one, n times, where n is specified by number.
Subscript can be the name of a previously defined field. However, if it is not defined, CA Easytrieve® Report Generator
automatically defines the field as a 2 B 0 field. If you defined the field, you must have defined it as numeric (N, P, U, B,
I) with zero or no decimal places.
• [FROM {start-field-name|start-integer}]
FROM is an optional parameter that defines the initial value for the REPEAT subscript. Subscript is automatically
incremented by one from either start-field-name or start-integer for each iteration of the group of ROW statements. If
FROM is omitted, the subscript starts at 1.
• [ROW row-number]
Specify the row-number on which the repeating group of rows starts. If this is not specified, the repeating group of rows
starts on the last screen row specified plus one.
• ROW statements
Code one or more ROW statements to be repeated. ROW statements are coded in a REPEAT/END-REPEAT
construct. For more information, see ROW Statement.
NOTE
ROW statements to be repeated cannot specify explicit row-numbers.
• END-REPEAT
END-REPEAT terminates the body of the REPEAT statement. END-REPEAT must be specified after each REPEAT
statement and its associated ROW statements.
Example
The following example illustrates how to display an array on a screen. The REPEAT construct displays both a one-
dimensional array (WS-NAME), and a two-dimensional array (WS-STAT). Starting at row 4, CA Easytrieve® Report
Generator displays the first occurrence of the fields. The second dimension of WS-STAT is stated explicitly. CA
Easytrieve® Report Generator increments USER-SUB and displays the next occurrence until 15 occurrences are
displayed.
This code:
...
WS-EMPLOYEE W 33 A OCCURS 30 . * 2-DIMENSIONAL TABLE OF
WS-NAME WS-EMPLOYEE 30 A . * 30 EMPLOYEES CONTAINING:
WS-STATUSES WS-EMPLOYEE +30 3 A . * EMPLOYEE NAME AND
WS-STAT WS-STATUSES 1 A OCCURS 3. * 3 STATUSES
...
SCREEN NAME EMPLOYEE-LIST
TITLE 'List of Employees'
ROW 3 'Name' COL 30 'Statuses'
REPEAT 15 TIMES VARYING USER-SUB
ROW WS-NAME (USER-SUB) +
WS-STAT (USER-SUB, 1) WS-STAT (USER-SUB, 2) WS-STAT (USER-SUB, 3)
918
CA Easytrieve® Report Generator 11.6
END-REPEAT
Produces:
List of Employees
Name Statuses
WIMN, GLORIA F G O
BERG, NANCY C
CORNING, GEORGE I T
...
REPORT Statement
The REPORT statement allows you to define the type and characteristics of a report. Although you can specify a large
number of REPORT statement parameters, you will probably produce most reports using default parameter values
specified in the Site Options Table.
REPORT statement parameters fall into five basic groups:
• Format determination parameters
• Label parameters
• File directing parameters
• Spacing control parameters
• Testing aid parameters
The data window for fields with VARYING specified on the DEFINE statement is based on the maximum length of the
field. The window is padded to the right with blanks for VARYING fields less than the maximum.
You need not code the SUMMARY parameter to use SUMFILE.
For a complete explanation of reporting facilities, see Programming.
This statement has the following format:
REPORT [report-name]+
[XML]+ }
[SUMMARY]+ }
[SUMFILE summary-
file-
name]+ }
[SUMSPACE sumfield-addition]+ }
[TALLYSIZE tally-
print-
size]+ }
}
[ {EVERY}] }
[DTLCTL{FIRST}]+ } Format
[ {NONE}] } Determination
} Parameters
[ { [ALL] }] }
[SUMCTL {([HIAR] [DTLCOPY])}]+ }
[ { [NONE] [DTLCOPYALL] }] }
[ { [TAG ] }] }
919
CA Easytrieve® Report Generator 11.6
[ [ACROSS number-
of-
labels] ] }
[LABELS ([DOWN number-
of-
lines ])]+ } Label
[ [SIZE label-length ] ] } Parameters
[ [NEWPAGE ] ] }
}
[FILE work-
file-
name]+ } File Directing
[PRINTER receive-
file-
name]+ } Parameters
[PAGESIZE (line-
page-
size [display-
page-
size])]+ }
[LINESIZE line-length]+ }
[SKIP number-
of-
lines]+ }
[SPACE number-
of-
spaces]+ }
[TITLESKIP number-
of-
lines]+ }
[CONTROLSKIP number-
of-
lines]+ }
}
[SPREAD ]+ }
[NOSPREAD] } Spacing Control
} Parameters
[NOADJUST]+ }
}
[NODATE ] }
[LONGDATE ]+ }
[SHORTDATE] }
}
[NOPAGE]+ }
[NOHEADING]+ }
}
920
CA Easytrieve® Report Generator 11.6
[LIMIT number-
of-
records]+ } Testing Aid
[EVERY n-
number-
of-lines] } Parameters
• Format Determination [report-name] Report-name identifies the report. It is optional when there is only one report in
a JOB activity. If you code multiple reports, the first report can be unnamed but all others must be named. Each report-
name must be unique in the JOB activity. At least one report-name must be coded on a PRINT report-name statement.
For unnamed reports, code the PRINT statement without a report-name parameter.
Report-name:
• – Can be up to 128 characters in length
– Can contain any character other than a delimiter
– Can begin with A to Z, 0 to 9, or a national character (#, @, $)
– Must not consist of all numeric characters
• [XML]
Optionally use XML to produce a file formatted using Extensible Markup Language (XML). This hierarchically-
structured file is built according to the field relationships defined by REPORT, CONTROL, and LINE statements.
Any spacing or positioning parameters (such as NOADJUST, COL, and SKIP) are ignored because the XML file
contains only field name (or HEADING) values and data values. XML also changes the default setting of the DTLCTL
parameter to EVERY. This causes every line-statement field to be written to the XML output file for each execution of a
PRINT statement. This behavior can be overridden using the DTLCTL parameter described later in this section.
For an XML-formatted report, no printed output is generated. There are no control totals or summary data lines printed
or written to any file. For information about the XML report feature, see Programming.
• [SUMMARY]On control reports, SUMMARY inhibits printing of detail data. Only control totals are printed.
• [SUMFILE summary-file-name]Optionally, use SUMFILE to generate a summary file that contains the control and
summary field values. Summary-file-name identifies the file to contain the summary data.
• [SUMSPACE sumfield-addition]Use SUMSPACE to define the print size for total fields on a control report. Sumfield-
addition is added to the length (in digits) of the field to define its print size. This expansion is necessary to prevent the
loss of significant data due to overflow conditions. The resulting print length is limited to a maximum of 18 digits. Valid
values for sumfield-addition are 0 to 9. No additional numeric edit characters are included in the resulting edit mask.
For example, totals such as 55555,555.55 can appear.
• [TALLYSIZE tally- print-size ]Use TALLYSIZE to set the print size for the field TALLY. Valid values for tally-print-
size are 1 to 18. The number of digits used for TALLY on a summary line is the sum of the values of TALLYSIZE and
SUMSPACE.
• [DTLCTL {EVERY|FIRST|NONE}]DTLCTL optionally defines detail line printing characteristics.
Specify EVERY to print the value of all control fields on every detail line.
Specify FIRST to print the value of all control fields on the first detail line of a page and on the first detail line after each
control break. Control field values are not printed on all other detail lines. Specify NONE to inhibit the printing of control
field values on detail lines.
• [SUMCTL {[ALL|HIAR|NONE|TAG] [DTLCOPY|DTLCOPYALL]}]
SUMCTL optionally defines total line printing characteristics. Specify ALL to print control field values on every total
line.
Specify HIAR to print control field values in a hierarchical fashion on total lines. Only values for control fields on the
same hierarchical level, or higher than the breaking control field, are printed on the associated total line.
Specify NONE to inhibit printing of control field values on total lines.
Specify TAG to print control-field-name TOTAL as an annotation to the left of the associated total line where control-
field-name is the field-name for the breaking control field. There must be sufficient unused space on the left side of the
total line for this annotation.
921
CA Easytrieve® Report Generator 11.6
Specify DTLCOPY to print detail information on total lines. Normally, only control field values and associated totals are
printed on total lines. Coding DTLCOPY prints the detail field contents, prior to the break, on the total line. These fields
are printed only when LEVEL is one (1).
Specify DTLCOPYALL to print detail fields for all control breaks.
• Label [LABELS [ACROSS number-of-labels ][DOWN number-of-lines ][SIZE label-length][NEWPAGE]]
Specify LABELS to indicate that the report is a label report.
NOTE
The NOHEADING and NOADJUST options are automatically activated when you specify LABELS; therefore,
you cannot specify TITLE and HEADING statements. You cannot use LABELS with SUMMARY.
Specify ACROSS number-of-labels to define the number of labels printed across the print line.
Specify DOWN to define the number of lines in a label. The value of number-of-lines is the number of lines reserved for
each label. The value range for number-of-lines is 1 to nnn, where nnn is at least as large as the largest corresponding
LINE nnn value.
Specify SIZE to set the length of each label. The value of label-length is the number of print positions on a label. Label-
length has a value range from 1 to nnn, where nnn is the length of the label.
NOTE
LABELS cannot be specified for extended reporting printers.
NEWPAGE controls the printing of the first line (LINE 01) of each label. When coded, NEWPAGE associates a printer
top-of-form request with the first line of each label.
The following algorithm confines the overall size of labels:
LINESIZE >= (ACROSS - 1) * SIZE + (number of print positions on an individual label)
• File Directing [FILE work-file-name]
Optionally, specify FILE to identify the work file used for very large reports. Code this parameter when the default VFM
work file is too small to contain the report data. Work-file-name identifies the FILE that receives the work file data
NOTE
You should not use the FILE parameter in CICS. An execution error occurs when work-file-name is not a
virtual file.
NOTE
Instead of coding the FILE parameter for each report in your program, you can use the WORKFILE YES
parameter on the PARM statement. For more information, see PARM Statement.
• [PRINTER receive-file-name]
Optionally, specify PRINTER to direct the report's printed output. Receive-file-name identifies the FILE that receives
the report. This file must have the PRINTER or EXTENDED attribute specified. The default is the CA Easytrieve
standard print output file: SYSPRINT. The actual destination of SYSPRINT is determined by a site option. For more
information about the actual destination of SYSPRINT, see your system administrator. For more information about
PRINTER files, see Programming.
If the system print output file or receive-file-name has been associated with an extended reporting printer, then CA
Easytrieve automatically formats the report to satisfy the requirements defined for that extended reporting printer. CA
Easytrieve restricts the support of extended reporting facilities to those reports that are output to printer files that have
been associated with an extended reporting printer.
Spacing Control-each of the following parameters modifies the default spacing of a report page. You normally do not
use these parameters; however, they are available to support unique report spacing requirements.
• [PAGESIZE (line-page-size [display-page-size])]Specify PAGESIZE to define the logical print length of a printed
page. Line-page-size must be an unsigned integer from 1 to 32767, and must be at least as large as the sum of:
922
CA Easytrieve® Report Generator 11.6
• – Title-number of the last TITLE statement
– Number-of-lines of TITLESKIP
– Number of HEADING lines plus one
– Line-number of the last LINE statement
– Number-of-lines of SKIP
In other words, at least one line group must fit on a report page.
Specify an asterisk (*) for line-page-size if you want to change display-page-size without changing the default line-
page-size.
Display-page-size must be zero or greater than or equal to the line-page-size.
When CA Easytrieve processes a LINE statement, it compares the line count to line-page-size. If the line count
is less than line-page-size, the LINE statement performs the BEFORE-LINE procedure and then prints the line. If
the line count is greater than or equal to line-page-size, the LINE statement performs the ENDPAGE procedure,
processes TITLEs, performs the BEFORE-LINE procedure, and finally prints the line. The line count is not
compared again to line-page-size after the LINE statement performs the BEFORE-LINE procedure.
Specify a value greater than zero for display-page-size to allow the DISPLAY statement to generate page breaks.
When display-page-size is greater than zero, the line count is compared to display-page-size. If the line count is
greater than display-page-size, then the DISPLAY statement performs the ENDPAGE procedure and generates a
page break with TITLEs.
Specify zero for display-page-size to inhibit DISPLAY statement generated page breaks. When display-page-
size is zero, the DISPLAY statement does not compare line count to display-page-size, and a page break is not
generated.
The DISPLAY statement always increases line count, regardless of the display-page-size value.
When the report is directed to an extended reporting printer that does not support a Forms Control Block (FCB),
then CA Easytrieve multiplies line-page-size by the default height of the assigned extended reporting printer. This
enables CA Easytrieve to compare PAGESIZE with the heights of fonts used on the report, because they are both
in the same base unit (the H-unit). The value of line-page-size multiplied by the default height of the assigned
extended reporting printer cannot exceed the maximum page length of that extended reporting printer.
• [LINESIZE line-length]
Code the LINESIZE parameter to specify the maximum number of data characters that can be printed on a line. Line-
length must be an unsigned integer from 1 to 32767.
Line-length must be at least one less than the length of the data portion of the file's logical record. If the FILE definition
does not provide the file's format and logical record length, then no compile time verification of the line-length is done.
The default value of LINESIZE is calculated as one less than the data portion of the logical record if the file format and
record length are known at compile time. Otherwise, the default is taken from the LINESIZE site option.
There are additional control characters (forms control information) that also must be stored in a logical record. If one of
the record format parameters is specified, it must be large enough to hold both the forms control information and the
data characters. The value of line-length must be less than or equal to the maximum record length minus the size of
the forms control information.
The first character in a PRINTER file contains the ASA carriage control information.
When the report is assigned to an extended reporting printer that is not a standard line printer, the maximum value of
line-length is not dependent upon the record size of the print data set. The insertion of overprint and function codes
into print records and the support of different fonts on the same print line all impact the relationship between LINESIZE
and print data set record size. CA Easytrieve supports any LINESIZE, provided line-length multiplied by the value of
the assigned extended reporting printers default width does not exceed the maximum page width of that extended
reporting printer.
Line-length overrides the value defined in the Site Options Table. If the report is directed to an extended reporting
printer, CA Easytrieve multiplies line-length by the default width of the assigned extended reporting printer. This value
defines the width of the print line in terms of the extended reporting printer's W-unit.
• [SKIP number-of-lines]Specify SKIP to define the number of blank lines to be inserted between line groups (between
the last LINE nnn and the next LINE 01). Number-of-lines has a valid range of 0 to nnn, where nnn allows for the
printing of at least one line group on each page. When you specify a value of 0, a line group containing multiple
lines can be spanned across a page break. A non-zero value inhibits this spanning. When the report is directed to
923
CA Easytrieve® Report Generator 11.6
an extended reporting printer that does not support a Forms Control Block (FCB), the default height of the assigned
extended reporting printer defines the height of each line.
• [SPACE number-of-spaces]Specify SPACE to adjust the default number of blanks (space characters) inserted
between fields on TITLE and LINE statement items. The value of number-of-spaces has a valid range of 0
to nnn (default is 3), where nnn does not cause line overflow. When the report is directed to an extended reporting
printer, CA Easytrieve multiplies number-of-spaces by the default width of the assigned extended reporting printer. This
operation expresses number-of-lines in terms of the printer's W-unit.
NOTE
The SPREAD parameter overrides this parameter.
• [TITLESKIP number- of-lines ]
Specify TITLESKIP to insert blank lines between the last title line and the first heading line (or LINE 01) of a report.
The value of number-of-lines has a valid range of 0 to nnn, where nnn allows for the printing of at least one line group
on each page.
When the report is directed to an extended reporting printer that does not support a Forms Control Block (FCB), the
height of each line is defined by the default height of the assigned extended reporting printer. This operation converts
number-of-lines into the H-units applicable to the printer.
• [CONTROLSKIP number- of-lines ]Specify CONTROLSKIP to define the number of blank lines to be inserted
following CONTROL total lines and the next detail line. Number-of-lines must be between 0 and 32767. If
CONTROLSKIP is not specified, one blank line plus the SKIP value is inserted after the CONTROL total line.
• [SPREAD|NOSPREAD]Specify SPREAD to insert the maximum number of spaces between each column of a report.
NOSPREAD deactivates SPREAD when it is the default specified in the Site Options Table. SPREAD and NOADJUST
are mutually exclusive. For more information about this parameter, and examples, see Programming.
NOTE
SPREAD overrides the SPACE parameter.
• [NOADJUST] Specify NOADJUST to left-justify the title lines and report on the page. The default is centered on the
page. SPREAD and NOADJUST are mutually exclusive.
• [NODATE|LONGDATE|SHORTDATE]Specify NODATE to inhibit the printing of the date value on the first title line
(TITLE 01).
LONGDATE specifies that SYSDATE-LONG is to appear on the first title line.
SHORTDATE specifies that SYSDATE is to appear on the first title line.
• [NOPAGE]Specify NOPAGE to inhibit the printing of the value of PAGEWRD (in the Site Options Table) and the
current page number in the report title.
• [NOHEADING]Specify NOHEADING to inhibit the printing of column headings. The default is that each field's
HEADING value is printed as a column heading.
Testing Aid LIMIT and EVERY are used as testing aids for report development. These parameters control the amount
of data output on a report.
• [LIMIT number-of-records]Specify LIMIT to limit the number of records processed by the report. The value
of number-of-records has a valid range of 1 to 32,767.
• [EVERY n-number-of-lines]Specify EVERY to indicate that only every n line is printed in the report. The value of n-
number-of-lines has a valid range of 1 to 32,767.
REPORT-INPUT Report Procedure
A REPORT-INPUT procedure selects or modifies report input data.
This procedure is performed for each PRINT statement (report input). To cause the data to continue into report
processing, you must execute a SELECT statement for the associated input data. In other words, input that does not get
selected is bypassed for continued processing.
Although you can code the logic to select records in the JOB activity itself, you can occasionally place the logic in a
REPORT-INPUT procedure.
924
CA Easytrieve® Report Generator 11.6
When the report data has been spooled (because the report had been sequenced or the printer file was in use), the
REPORT-INPUT procedure is invoked as each spooled record is read to produce this report. This means that all records
printed are spooled and sorted (if SEQUENCE is specified). The REPORT-INPUT procedure is then invoked. For
performance reasons, you should select the records in a JOB activity, if possible.
A REPORT-INPUT procedure must be delimited by an END-PROC statement. See PROC Statement for more
information.
This statement has the following format:
REPORT-INPUT. PROC
Example
The following example illustrates use of the REPORT-INPUT procedure in final report input selection. Only the first record
in each ZIP code is selected.
Statements:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
HOLD-ZIP S 5 N VALUE 00000
JOB INPUT FILE1 NAME MYPROG
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
REPORT-INPUT. PROC
IF ZIP NE HOLD-ZIP
HOLD-ZIP = ZIP
SELECT
END-IF
END-PROC
*
Data:
BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666
925
CA Easytrieve® Report Generator 11.6
Results:
11/23/09 REPORT FOR THE STATE OF IL PAGE 1
LAST-NAME STATE ZIP PAY-NET
BROWN IL 60076 123.45
JONES IL 60077 98.76
IL 222.21
11/23/09 REPORT FOR THE STATE OF TX PAGE 2
LAST-NAME STATE ZIP PAY-NET
SMITH TX 75218 111.11
TX 111.11
333.43
RESHOW Statement
The RESHOW statement is used in an AFTER-SCREEN procedure to redisplay the screen image with user-entered data
intact. In contrast to the REFRESH statement, the screen image is not rebuilt using the current values of program fields.
Upon receiving the screen, CA Easytrieve® Report Generator saves a copy of the screen image. The RESHOW
statement restores the saved image.
This statement has the following format:
RESHOW
Example
As shown in the following example, RESHOW can be used to redisplay a screen following a request for help. The data
that the user entered on the screen before they requested help is redisplayed intact. When RESHOW is used with an
IMMEDIATE KEY, original screen data is retained, but not edited or saved into program fields.
...
SCREEN NAME MENU UPPERCASE
KEY ENTER
KEY F1 NAME 'Help' IMMEDIATE
KEY F3 NAME 'Exit' EXIT
TITLE...
ROW...
AFTER-SCREEN. PROC
IF KEY-PRESSED = F1
EXECUTE MENU-HELP
RESHOW
END-IF
CASE OPTION
...
END-PROC
SCREEN NAME MENU-HELP
KEY F3 NAME 'Exit' EXIT
926
CA Easytrieve® Report Generator 11.6
TITLE...
ROW...
RETRIEVE Statement (CA IDMS and IMS/DLI)
The RETRIEVE statement identifies the database records that are automatically input to the JOB activity. Code the
RETRIEVE statement immediately following a JOB statement to specify automatic input. You can code only one
RETRIEVE statement in each JOB activity. CA Easytrieve® Report Generator processes the automatic input the same
way as non-database input.
For RETRIEVE statement examples, see the Programming Guide.
This statement has the following format:
Format 1 (CA IDMS)
RETRIEVE file-name +
[ {program-name }]
[PROGRAM-NAME { }] +
[ {'program-literal'}]
[ {db-name-table-name }]
[DBNAME { }] +
[ {'db-name-table-literal'}]
[ {node-name }]
[NODE { }] +
[ {'node-literal'}]
[ {dictionary-name }]
[DICTNAME { }] +
[ {'dictionary-literal'}]
[ {dictionary-node-name }]
[DICTNODE { }] +
[ {'dictionary-node-literal'}]
[KEYFILE tickler-file-name + ] ]
[KEYVALUE (calc-key-field-name EQ calc-value-field-name ...) ] + ]
[ ] +
[DUPS ]
[NODUPS ]
SELECT (record-name +
[AREA 'area-literal' + ]
[SET 'set-literal' + ] +
[INDEX 'index-set-literal' [USING ('index-key-literal' ...)]]
[ID 'path-literal'] +
[LIMIT number-of-records] +
927
CA Easytrieve® Report Generator 11.6
[WHILE (condition)] +
...)
Format 2 (IMS/DLI)
RETRIEVE file-name +
[KEYFILE tickler-file-name KEYVALUE key-field-name] +
SELECT (record-name +
[ID 'path-literal'] +
[LIMIT number-of-records] +
[SSA 'segment-literal'] +
[WHILE (condition)] +
...)
Format 1 (CA IDMS)
• file-name
File-name is the same as the name coded in the FILE file-name IDMS and JOB INPUT (file-name) statements.
• [PROGRAM-NAME {program-name|'program-literal'}]
Program-name or 'program-literal' specifies the name used to identify the program to CA IDMS during execution.
Program-name must be an eight-byte alphanumeric field. 'Program-literal' must be alphanumeric and is padded to the
right (if necessary) to create an eight-byte value.
• [DBNAME {db-name-table-name|'db-name-table-literal'}]
Db-name-table-name or 'db-name-table-literal' specifies a DB name table. Data retrieved during execution of the user's
program is from the named CA IDMS database. Db-name-table-name must be an eight-byte alphanumeric field. 'Db-
name-table-literal' must be alphanumeric and is padded to the right (if necessary) to create an eight-byte value.
• [NODE {node-name|'node-literal'}]
Node-name or 'node-literal' specifies the central version node that hosts the CA IDMS activity generated by the user's
program. Node-name must be an eight-byte alphanumeric field. 'Node-literal' must be alphanumeric and is padded to
the right (if necessary) to create an eight-byte value.
• [DICTNAME {dictionary-name|'dictionary-literal'}]
Dictionary-name or 'dictionary-literal' specifies the dictionary name of a secondary load area. Dictionary-name must be
an eight-byte alphanumeric field. 'Dictionary-literal' must be alphanumeric and is padded to the right (if necessary) to
create an eight-byte value.
• [DICTNODE {dictionary-node-name|'dictionary-node-literal'}]
Dictionary-node-name or 'dictionary-node-literal' specifies the dictionary node of a secondary load area. Dictionary-
node-name must be an eight-byte alphanumeric field. 'Dictionary-node-literal' must be alphanumeric and is padded to
the right (if necessary) to create an eight-byte value.
• [KEYFILE tickler-file-name][KEYVALUE (calc-key-field-name EQ calc-value-field-name ...)][DUPS|NODUPS]
The optional tickler file is designated by coding the KEYFILE and KEYVALUE parameters. Tickler-file-name is the
name of a file that is sequentially processed to obtain the keys of the root records to be retrieved. The DBCS code
system of tickler-file-name must equal the DBCS code system of file-name.
Calc-value-field-name is a data field from tickler-file-name that contains a value for one of the CALC keys of the root
record. Calc-key-field-name is a CALC key field defined in the RECORD statement for the root record that is to receive
928
CA Easytrieve® Report Generator 11.6
the value of calc-value-field-name. For information about coding how calc-value-field-name is assigned to calc-key-
field-name, see the Programming Guide.
You must code one calc-value-field-name for each key field defined in the KEY parameter of the RECORD statement
for the root record.
The key values are used in the CALC retrieval of root records. Therefore, only CALC records can be root records when
the tickler file is used. The optional keywords, DUPS and NODUPS, are used to specify whether CALC records with
duplicate keys are also retrieved. The OPTIONS table parameter CALCDUP has the default value. The JOB activity is
terminated at end-of-file for tickler-file-name.
The KEY parameter for the root record retrieved by the tickler file option must be specified on the RECORD statement.
• [SELECT (record-name ...)]
The SELECT parameter identifies which paths are retrieved. Record-name must be the same as coded on a RECORD
statement. Any number of records and paths can be coded under control of the following rules of network structure:
– The first record-name coded is the root. It is retrieved by an area sweep, tickler file, or integrated index.
– A repeated record-name denotes a node in the network. A node is a record-type that is common in multiple paths.
The optional subparameters are not allowed when a record-name is repeated as a node.
– Paths are retrieved in the order in which they are identified.
• [AREA 'area-literal']
The optional AREA subparameter is coded to supply the sweep area. This subparameter can be specified only if
record-name is a root record. AREA is not allowed if INDEX has already been specified for this record. The 1- to
16-character CA IDMS area name ('area-literal') controls retrieval within area of root records. 'Area-literal' must be
alphanumeric (non-DBCS), and is padded to the right (if necessary) to create a 16-byte value.
If the AREA subparameter is coded, CA Easytrieve® Report Generator uses OBTAIN NEXT record-name WITHIN
AREA calls to retrieve occurrences of this record. If this subparameter is omitted, CA Easytrieve® Report Generator
uses OBTAIN NEXT record-name calls instead.
• [SET 'set-literal']
The SET subparameter specifies the name of the set used for retrieving the named record (record-name). This
subparameter is not allowed if record-name is the root record or if record-name is a node. SET is required for all other
records. 'Set-literal' must be alphanumeric (non-DBCS), and is padded to the right (if necessary) to create a 16-byte
value.
If this record is a member of the specified set, CA Easytrieve® Report Generator uses OBTAIN NEXT record-name
WITHIN SET calls to retrieve occurrence of this record. If this record is the owner of the specified set, CA Easytrieve®
Report Generator uses OBTAIN OWNER calls instead.
• [INDEX 'index-set-literal'[USING ('index-key-literal' ...)]]
Code the optional INDEX subparameter to designate the index set ('index-set-literal') that controls root retrieval by
integrated indexing. This subparameter can be specified only if record-name is a root record. INDEX is not allowed
if AREA has already been specified for this record. 'Index-key-literal' must be a alphanumeric (non-DBCS), and is
padded to the right (if necessary) to create a 16-byte value.
Note: The INDEX subparameter cannot be used with the tickler file.
The optional USING subparameter ('index-key-literal') designates the alphanumeric literals used to constrain the index.
You can code as many occurrences of 'index-key-literal' as are required to fully specify the index key value. The values
are concatenated in the order specified and form the index key value that is passed to CA IDMS. The cumulative
length of all literals specified must match the length of the index known to integrated indexing. The code system of the
data must also match.
When the INDEX subparameter is coded, CA Easytrieve® Report Generator uses OBTAIN NEXT WITHIN SET calls
to retrieve all occurrences of the root record except for the first occurrence. The retrieval of the first occurrence is
determined by the optional USING subparameter. If the USING subparameter is coded, CA Easytrieve® Report
Generator retrieves the first root record occurrence using an OBTAIN WITHIN SET USING SORT KEY call. If the
USING subparameter is omitted, an OBTAIN FIRST WITHIN SET call is used. CA Easytrieve® Report Generator
uses the USING subparameter to establish the initial position within the index set. Once this initial position has been
established, retrieval of the root record proceeds until the end of the index set is reached.
• [ID 'path-literal']
929
CA Easytrieve® Report Generator 11.6
Code the optional ID subparameter to establish the identity of retrieved paths. The system-defined field file-
name:PATH-ID is set to the value of 'path-literal' for the lowest record retrieved in the current path. 'Path-literal' can be
an alphanumeric value of one or two characters. It cannot contain any DBCS data. The default is spaces. Whenever a
key of the tickler file does not correspond to a root record in the database, file-name:PATH-ID is set to NF (Not Found).
• [LIMIT 'number-of-records']
The optional LIMIT subparameter controls the number of record occurrences to be retrieved. The limit applies to the
specific record in the path. 'Number-of-records' must be a positive integer. When this subparameter is not coded, all
occurrences of the record are retrieved.
• [WHILE (condition)]
Code the optional WHILE subparameter to pre-screen input records. The syntax of the condition is exactly the same
as the conditional expressions described in the Programming Guide. When the associated record is retrieved from CA
IDMS, the condition is evaluated. Records are accepted for input only if the condition is true.
Format 2 (IMS/DLI)
• file-name
File-name identifies the database being accessed. File-name is the same as the name coded in JOB INPUT file-name
and FILE file-name statements.
• [KEYFILE tickler-file-name KEYVALUE key-field-name]
You can designate the tickler file option by coding both the KEYFILE and the KEYVALUE parameters. Tickler-file-
name is the name of the file that is sequentially processed to get the keys of the root segments to be retrieved. Key-
field-name is a data field from tickler-file-name that contains the keys. The key values are used in the segment search
argument for the root segment. CA Easytrieve® Report Generator issues GU (get unique) calls at the root level for
each key found in tickler-file-name. Automatic input is terminated at end-of-file for tickler-file-name.
The DBCS code system assigned to tickler-file-name must match the DBCS code system of file-name.
• [SELECT (record-name ...)]
The SELECT parameter identifies which segments (record-name) CA Easytrieve® Report Generator is to retrieve.
Record-name must be the same as the segment-name coded on a RECORD statement. You can identify any number
of record-names for input; however, the parent of all selected segments must also be selected.
• [ID 'path-literal']
Code the optional ID subparameter to establish the identity of retrieved paths. The system-defined field PATH-ID is set
to the value of 'path-literal' for the lowest segment retrieved in the current path. PATH-ID is a two-byte alphabetic field.
'Path-literal' can be an alphabetic value of one or two bytes. It cannot contain any DBCS data. The default value for
PATH-ID is spaces. When a key of the tickler file does not correspond to a root record in the database, PATH-ID is set
to NF (Not Found).
• [LIMIT 'number-of-records']
The optional LIMIT subparameter controls the number of segment occurrences to be retrieved. The limit applies to
each path. 'Number-of-records' must be a positive integer. When this subparameter is not coded, all occurrences of the
segment are retrieved.
• [SSA 'segment-literal']
You can code the optional Segment Search Argument (SSA) parameter for the root segment. 'Segment-literal' is used
in the creation of the SSA to qualify segment retrieval. This parameter is not valid when you use a tickler file. The
value supplied with SSA is enclosed within parentheses and concatenated with the segment-name to produce the root
segment's SSA. 'Segment-literal' cannot contain any DBCS data.
• [WHILE (condition)]
Code the optional WHILE subparameter to pre-screen input segments. The syntax of the condition is exactly the same
as the conditional expressions described in the Programming Guide. When the associated record is returned by IMS/
DLI, the condition is evaluated. Segments are accepted for input only if the condition is true.
ROLLBACK Statement
The ROLLBACK statement causes all uncommitted updates in the current logical unit of work to be rolled back.
930
CA Easytrieve® Report Generator 11.6
For more information about types of work that are recoverable, see the Programming Guide. Use the COMMIT statement
to commit any pending changes.
This statement has the following format:
ROLLBACK
Example
WRITE PERSNL ADD
...
IF ...
ROLLBACK
ELSE
COMMIT
END-IF
ROW Statement
The ROW statement specifies the items (fields or literals) to be displayed or received on a row of a screen. Multiple
items can be coded on each ROW statement. Attributes can be specified for each literal coded on the ROW statement.
Attributes and editing criteria can be specified for each field-name coded on the ROW statement.
For more information, see the Programming Guide.
This statement has the following format:
ROW [row-number] +
[+offset-value ] {field-name }
[ ] { } +
[COL column-number] {'row-literal'}
[ {attribute-name } ]
[ATTR { } ] +
[ {(attribute-list)} ]
[ {RIGHT} ]
[JUSTIFY { } ] +
[ {LEFT } ]
[FILL {'fill-character'|NULL}] +
[MASK ({[mask-identifier] [BWZ] ['mask-literal']|HEX})] +
[NOMASK ]
[ {pattern-name} ]
[PATTERN { } ] +
[ {'pattern' } ]
[UPPERCASE] +
[VALUE (literal [THRU literal] [...])] +
931
CA Easytrieve® Report Generator 11.6
[ [ {attribute-name }] ] ]
[ERROR ( [ATTR { }] + ] ]
[ [ {(attribute-list)}] ] ]
[ ] ] ...
[ [ {'literal' [ ] } ] ] ]
[ [ { [...] } ] ) ] ]
[ [ {field-name [ ] } ] ] ]
• [row-number]
Row-number specifies the line on which the item on the screen is displayed. A ROW without a row-number is assigned
the next row number on the screen. Next is defined as the previous row-number plus one, not the highest number used
as yet.
A ROW without any fields or literals displays a blank line on the screen at the corresponding row-number.
Row-number cannot exceed the default ROWCOUNT value set in the site options or the value of the ROWCOUNT
parameter specified on the SCREEN statement, if coded.
• [+offset-value|COL column-number] {field-name|'row-literal'}
The +offset-value or the COL column-number parameter allows you to control positioning of an item on the row.
+Offset-value is the number of columns (spaces) preceding a screen item. The default +offset-value is +1 because the
space preceding each screen item is reserved for screen attributes. +Offset-value must be a signed positive integer
and can only be used for items other than the first in the row.
Use column-number to explicitly specify the column at which the screen item is displayed.
If you do not code a +offset-value or column-number, the next field-name or 'row-literal' is displayed one column after
the end of the previous field-name or 'row-literal.' If no previous item exists in the row, the item is displayed in column
one.
Field-name can be any defined field in your program.
'Row-literal' can be any text you want to display on the screen.
The sum of the length of all screen items (fields and literals) plus offset-values and column-numbers (if used) cannot
exceed the value of the default LINESIZE set in the site options, or the value of the LINESIZE parameter on the
SCREEN statement, if coded.
• [ATTR {attribute-name|attribute-list)}]
ATTR specifies either a declared screen attribute name or one or more attribute keywords. For a list of attributes, see
ATTR Parameter . For more information about declared screen attributes, see DECLARE Statement .
The following attributes are invalid for literals and system-defined read-only fields:
– CURSOR
– NUMERIC
– INVISIBLE
– MUSTFILL
– MUSTENTER
– TRIGGER
– ALARM
They are ignored if used, but CA Easytrieve® Report Generator issues a warning message during compilation.
SENDONLY and ASKIP are assumed for literals and system-defined read-only fields.
• [JUSTIFY {RIGHT|LEFT}]
Use the JUSTIFY parameter to specify whether the data in the field is left or right justified when displayed at the
terminal.
• [FILL {'fill-character'|NULL}]
Specify FILL to translate trailing blanks into either 'fill-character' or NULL. 'Fill-character' must be a one-byte
alphanumeric literal.
Upon receiving data from the screen, CA Easytrieve® Report Generator translates all remaining fill characters to
spaces.
932
CA Easytrieve® Report Generator 11.6
You can use the FILL parameter to fill a field with underscores to illustrate the total length of the field. You can fill a field
with NULL on a 3270 display to allow insertion of characters.
Varying length fields with FILL NULL do not have trailing nulls translated to spaces. The first trailing null terminates the
varying length field, and then sets its length.
• [MASK ({[mask-identifier] [BWZ] ['mask-literal']|HEX})]|[NOMASK]
The optional MASK parameter is used to format the field for display.
If MASK is not coded, the MASK coded on the field's definition is used. Use NOMASK to specify that the field's default
MASK is to be used instead of the field's definition MASK.
Any letter from A to Y can be used as an optional mask-identifier. You can use the letter to identify a new mask or to
retrieve a mask that was previously defined either in the Site Options Table or by a mask parameter on a previous field
definition or ROW usage. If the new mask that you identify does not already exist, CA Easytrieve® Report Generator
retains the mask for future reference. Do not use the same identifier to establish more than one mask.
The BWZ (blank when zero) option suppresses the display of field-name when it contains all zeros. BWZ can be used
by itself or with other options on the MASK parameter.
'Mask-literal' defines an edit mask and must be enclosed within single quotes.
Specify HEX to display the field in double-digit hexadecimal format. You can display fields of up to 50 bytes with the
HEX mask.
When fields are received from the terminal, the mask is used as an editing template also. Special characters in
the MASK are stripped from the data before it is moved into the field data area. For more information, see the
Programming Guide.
NOTE
HEX edit masks are not allowed for VARYING fields.
• [PATTERN {pattern-name|'pattern'}]
PATTERN allows you to specify a pattern against which each input character is edited. The pattern can be specified as
a literal or as the name of a declared pattern. See DECLARE Statement for more information.
The valid pattern characters and their meanings are as follows:
– A
Represents a lower-case or an upper-case letter.
– B
Represents a single blank.
– D
Represents a digit.
– E
Represents an empty string.
– L
Represents a lower-case letter.
– N
Represents an upper-case letter or a national character.
– U
Represents an upper-case letter.
– X
Represents any character.
– "x"
Double quotes surrounding a character or a sequence of characters literally represent the character or sequence of
characters contained within. The x represents any character. To literally represent single or double quotes, use two
sets of quotes within the surrounding set of double quotes ('""""' or '"x""x"', '"''"', or '"x''x"').
– blank
Blanks (unless contained in double quotes) serve as delimiters but are otherwise ignored. They can be inserted into
the pattern to increase readability.
– ()
933
CA Easytrieve® Report Generator 11.6
Represents grouping to control the precedence of operators.
– or | or ,
Represents a choice (or alternation operator).
– (m) or (m..n) or (m..*) or (*) or *
Represents the repetition of the preceding pattern expression. The m and n represent numbers and m must be less
than n. A single number with parentheses indicates the exact number of repetitions. (m..n) represents a range of
repetitions, minimum to maximum. An asterisk in a range, (m..*), represents an infinite maximum. An asterisk by
itself, (*) or *, represents a range from 0 to infinity.
– # or /-/
Represents the remove (or toss) operation. This operation applies only to a single character set at a time and
must immediately follow that character set in the pattern. This operation removes the character that matched the
character set from the data.
– +
Represents character set addition to form another character set.
– -
Represents character set difference to form another character set.
– concatenation
Concatenation is implied by proximity. For example, DDDU means 3 digits followed by an upper-case letter.
The precedence of operators from highest to lowest is:
Grouping: () " "
Set construction: + -
Actions: #
Repetition: (n) (m..n) (m..*) (*)
Concatenation: proximity
Choice: |
The edit pattern is evaluated from left to right (the data from the screen is processed from left to right). Patterns
examine only one character at a time. They do not look ahead and they do not back track. For more information, see
the Programming Guide.
• [UPPERCASE]
Specify UPPERCASE to translate the field coming from the terminal to upper case before placing it in the field data
area.
• [VALUE (literal [THRU literal] [...])]
Use VALUE to specify a value, a series of values, or a range of values (or a combination) that constrain the values
accepted in the field. Values must be specified as literals of the correct type for the field. See Conditional Expressions
for more information.
• [ERROR [ATTR {attribute-name|(attribute-list)}][{'literal'[ ]}|{field-name[ ]}]
ERROR specifies one or more fields or alphanumeric literals to be used as the error message issued by CA
Easytrieve® Report Generator in case of an automatically-detected error condition. The total length of the message
text cannot exceed the current screen size less two or the compiler issues an error message. Optionally, you can
specify the screen attribute to be used for the field in error.
Example
ROW 5 'Number' COL 20 EMP-NUMBER ATTR PROTECT MASK 'ZZ9'
ROW 'Name' COL 20 EMP-NAME UPPERCASE
ROW 'Dept' COL 20 EMP-DEPT VALUE (900 THRU 999) +
ERROR 'Invalid Department'
934
CA Easytrieve® Report Generator 11.6
SCREEN Statement
The SCREEN statement defines and initiates a SCREEN activity. A SCREEN activity defines a transaction-oriented
processing activity under the control of keys pressed by the terminal operator. Statements can also be inserted in screen
procedures to retrieve and maintain files and databases.
NOTE
Screen processing is only available in CA Easytrieve® Report Generator Online.
The structure of a SCREEN activity is as follows:
SCREEN statement
Screen declaration statements:
DEFAULTs (first in declaration section)
KEYs, TITLEs, ROWs (in any order)
Screen procedures (both special-named and user-defined, in any order)
SCREEN activities can be executed by PROGRAM or other SCREEN activities. If a PROGRAM activity is not present,
the first SCREEN activity detected is automatically executed. A SCREEN activity continues processing until an EXIT,
STOP, or TRANSFER statement is executed. CA Easytrieve® Report Generator issues an error message when compiling
a screen activity that does not contain one of these statements.
If the LINESIZE and ROWCOUNT for a screen are less than the line size and number of rows on the terminal, the screen
is displayed as a pop-up window. Any fields from previous screens that are still displayed are given the ASKIP attribute to
prevent data entry on those screens.
When executing in TSO and CMS, if the terminal supports two presentation sizes, CA Easytrieve® Report Generator
selects the presentation size based on the size of the screen. When a pop-up window is displayed, the presentation space
is based on the larger of the previous display size or the size of the pop-up window.
This statement has the following format:
[ [ACTIVITY ] [TERMINAL ] ]
SCREEN [NAME screen-name] [COMMIT ([ ] [ ])] +
[ [NOACTIVITY] [NOTERMINAL] ]
[UPPERCASE] [ROWCOUNT rows] [LINESIZE columns] +
[ROW screen-start-row] [COL screen-start-column] +
[ {attribute-name } ]
[BACKGROUND ATTR { } ] +
[ {(attribute-list)} ]
[ {SINGLE } ]
[ {DOUBLE } [ {attribute-name } ] ]
[BORDER ({ } [ATTR { } ] ] +
[ {WIDE } [ {(attribute-list)} ] ]
[ {'border literal'} ]
[SHADOW]
• [NAME screen-name]
Optionally, specify a name for the SCREEN activity. Screen-name:
935
CA Easytrieve® Report Generator 11.6
– Can be up to 128 characters in length
– Can contain any character other than a delimiter
– Can begin with A to Z, 0 to 9, or a national character (#, @, $)
– Must not consist of all numeric characters
The screen-name can be used to identify the screen in an EXECUTE statement.
• [COMMIT [ACTIVITY|NOACTIVITY] [TERMINAL|NOTERMINAL]]
Specify the COMMIT parameter to control the logical unit of work. COMMIT indicates when the activity commits
recoverable work. Each commit point posts all updates, additions and deletions, terminates holds, and closes SQL
cursors.
Specify ACTIVITY to commit all recoverable work during the normal termination of the activity. Specify NOACTIVITY to
tell CA Easytrieve® Report Generator not to commit at the end of the activity. NOACTIVITY is the default.
Specify TERMINAL to commit all recoverable work during any terminal I/O operation. In CICS, this results in terminal I/
O being performed in a pseudo-conversational mode. Specify NOTERMINAL to tell CA Easytrieve® Report Generator
not to commit during a terminal I/O. TERMINAL is the default.
If this activity is executed by an activity that has NOTERMINAL specified, this activity performs terminal I/O as if
NOTERMINAL was specified.
NOTE
You can also issue your own COMMIT and ROLLBACK statements to commit or recover on a controlled
basis.
• [UPPERCASE]
Specify UPPERCASE to translate the data received from the terminal to upper case before it is processed. If
UPPERCASE is not specified, the data is processed as the user enters it.
• [ROWCOUNT rows]
ROWCOUNT rows lets you override the default number of terminal rows for the screen display. The default is set in the
Site Options Table. For valid ROWCOUNT-LINESIZE combinations, see the next parameter, LINESIZE columns.
• [LINESIZE columns]
LINESIZE columns lets you override the default number of columns for the screen display. The default is set in the Site
Options Table.
On the mainframe, ROWCOUNT can be any value from 1 to 255. LINESIZE can be any value from 1 to 255. If the
dimensions of the screen exceed the screen size available on the display terminal, only a portion of the screen is
displayed.
• [ROW screen-start-row] [COL screen-start-column]
Screen-start-row specifies the starting row of the screen. The default is 1.
Screen-start-column specifies the starting column of the screen. The default is 1.
• [BORDER {SINGLE|DOUBLE|WIDE|'border literal'} [ATTR {attribute-name|(attribute-list)} ] ]
Use BORDER to specify that the screen has a border.
SINGLE, DOUBLE, or WIDE specifies that the border is built from a predefined line-drawing character set.
Borders on the mainframe are:
'Border literal' specifies the character to be used for the screen border. This value must be a single character enclosed in
single quotes.
936
CA Easytrieve® Report Generator 11.6
Optionally, specify a declared screen attribute name or a list of attribute keywords for the screen border. The following
attributes are ignored for BORDER:
• CURSOR
• NUMERIC
• INVISIBLE
• MUSTFILL
• MUSTENTER
• TRIGGER
• ALARM
For a list of attribute keywords, see ATTR Parameter . For more information about declared screen attributes, see the
DECLARE Statement .
Example
DEFINE WS-REPLY W 1 A
SCREEN NAME MAIN-MENU
TITLE 'Employee File Main Menu'
ROW 6 COL 10 'Type an option, then press Enter.'
ROW 8 COL 10 'Option ===>' WS-REPLY VALUE ('V' 'E' 'D' 'X') +
ERROR 'Please type V, E, D, or X'
ROW 10 COL 22 'V View employee'
ROW COL 22 'E Edit employee'
ROW COL 22 'D Delete employee'
ROW COL 22 'X Exit'
KEY F1 NAME 'Help' IMMEDIATE
KEY F3 NAME 'Exit' EXIT
KEY F12 NAME 'Cancel' EXIT IMMEDIATE
SEARCH Statement
The SEARCH statement provides access to table information. Special conditions of the IF statement can be used to
validate the results of SEARCH operations.
After each SEARCH statement, you can code an IF file-name test to determine the success of the table search. When
the search is successful (IF file-name is true), result-field contains the table's descriptive data corresponding to the
search argument of search-field. When the search is unsuccessful (IF file-name is false), the contents of result-field are
unchanged.
You can code SEARCH statements any place in a PROGRAM, SCREEN, or JOB activity, and issue any number of
searches against any number of tables.
The file must be in ARG sequence and cannot contain any duplicates. The compare between the WITH field and the ARG
field in the table is a logical compare, that is, the compare ignores the data type and treats both fields as if they have a
data type of A.
When the table file is also an INDEXED file and the ARG field is the key, CA Easytrieve® Report Generator performs
a keyed read of the file. Otherwise, the entire file is read into memory and a binary search is performed. For more
information on table processing, see the Programming Guide.
This statement has the following format:
SEARCH file-name WITH search-field GIVING result-field
937
CA Easytrieve® Report Generator 11.6
• file-name
File-name is the name of the file that describes the table and its source. The file must have the TABLE parameter on
its FILE statement and must be a fixed length.
• WITH search-field
Search-field identifies the field containing the search argument for the binary search. This parameter is defined in any
file, except for files with the TABLE parameter, or it can be defined in working storage.
The length and field type of search-field must match the length and field type of the ARG field defined for file-name.
Search-field cannot be a varying length field or a nullable field.
• GIVING result-field
Result-field identifies the receiving field for the results of the table search. This parameter is defined in any file, except
for files with the TABLE parameter or it can be defined in working storage.
The length and field type of result-field must match the length and field type of the DESC field defined for file-name.
Result-field cannot be a varying length field or a nullable field.
Example
The following example illustrates the retrieval of high school class descriptions based upon class identification codes.
Statements:
DEFINE CODE W 4 A
DEFINE DESCRIPTION W 40 A
FILE CLASSES TABLE INSTREAM
ARG 1 4 A
DESC 10 40 A
1011 ENGLISH I
1012 ENGLISH II
1013 ENGLISH III
1014 ENGLISH IV
ENDTABLE
PROGRAM NAME MYPROG
MOVE '1012' TO CODE
SEARCH CLASSES WITH CODE, GIVING DESCRIPTION
IF CLASSES
DISPLAY DESCRIPTION
ELSE
DISPLAY 'CLASS NOT FOUND'
END-IF
Results:
ENGLISH II
SELECT Statement (File-based SQL)
A SELECT statement issued for an SQL file causes a cursor to be automatically declared and opened as a CA
Easytrieve® Report Generator file. The resulting cursor can then be fetched and updated by subsequent commands for
the file. The cursor can also be the subject of automatic input using the JOB statement.
Notes:
938
CA Easytrieve® Report Generator 11.6
• If no SELECT statement is issued for an SQL file, a default SELECT is used (SELECT all defined columns FROM file-
name).
• If SELECT is the first statement in a JOB activity, the following happens:
– If the SELECT is for an automatic input file, the SELECT overrides the default SELECT.
– If the SELECT is for a file not used for automatic input, a DEFER should be coded on the SQL FILE statement. If
DEFER is not coded, the default SELECT is opened during the initialization processing, then closed, and the coded
SELECT processed. This causes unnecessary processing to occur.
• If a SELECT is specified for a file that has already been opened, either by the default SELECT or another coded
SELECT, then the existing SELECT for the file is closed and the new SELECT is used to open the file again.
SELECT can be coded in a JOB's START procedure. However, since a file is normally opened before invoking the START
procedure, you should specify DEFER on the FILE statement. Otherwise, the default SELECT is opened before the
START procedure, and then the SELECT in the START procedure closes the default SELECT before it opens. This
causes extra processing that is not needed.
This statement has the following format:
SELECT [DISTINCT] [FROM] file-name +
[WHERE search-condition] +
[GROUP BY column-name + ] +
[ [, column-name ...] ]
[HAVING search-condition] +
[ {column-name} [ASC ] ]
[ORDER BY { } [ ] + ]
[ {integer } [DESC] ]
[ ]
[ [ {column-name} [ASC ] ] ]
[ [, { } [ ] ...] ] +
[ [ {integer } [DESC] ] ]
[FOR UPDATE]
• [DISTINCT]
DISTINCT eliminates duplicate rows. If DISTINCT is not specified, all rows are retrieved.
• [FROM] file-name
Optionally, code FROM for statement readability.
file-name must be the name of a CA Easytrieve® Report Generator SQL file.
• [WHERE search-condition]
Search-condition is used to specify conditions for the retrieval of data. The search-condition is applied to create the
result set for the file. For information about the search-condition, see your SQL vendor manuals.
• [GROUP BY column-name]
GROUP BY is used to group data that is fetched into the file. For column-name syntax, see your SQL vendor manuals.
• [HAVING search-condition]
Search-condition is used to specify the data to be provided to the user. HAVING can be used to compare the results
of all the returned data with a specific value in the data provided (such as the minimum or maximum value). For
information about the search-condition, see your SQL vendor manuals.
• [ORDER BY {column-name|integer} [ASC|DESC]]
939
CA Easytrieve® Report Generator 11.6
ORDER BY returns the rows of the result table in the order of the values of the specified column-names. Integer
references a column by its position in the result table rather than by a column-name. ASC returns the rows in
ascending order and is the default. DESC returns the rows in descending order.
• [FOR UPDATE]
Specify FOR UPDATE to allow updates of the updatable fields defined in file-name. If used, FOR UPDATE must be the
last parameter specified on the SELECT statement. If FOR UPDATE is not coded and you attempt to update file-name,
you receive an error at execution.
Examples
The following is a file-based SQL SELECT statement example:
FILE PERSNL SQL (PERSONNEL)
EMPNAME * 20 A
WORKDEPT * 2 P 0
JOB NAME RETRIEVE-PERSONNEL INPUT PERSNL
SELECT FROM PERSNL WHERE WORKDEPT = 921
DISPLAY EMPNAME +2 WORKDEPT
The next example shows a file-based SQL SELECT statement with DEFER:
FILE PERSNL SQL (PERSONNEL) DEFER
EMPNAME * 20 A
WORKDEPT * 2 P 0
JOB NAME RETRIEVE-PERSONNEL INPUT PERSNL START START-PROC
DISPLAY EMPNAME +2 WORKDEPT
START-PROC. PROC
SELECT FROM PERSNL WHERE WORKDEPT = 921
END-PROC
SELECT Statement (Non-file SQL)
The non-file SQL SELECT statement allows CA Easytrieve® Report Generator to retrieve rows without a file. This read-
only method is retained from previous versions of CA Easytrieve® Report Generator.
The SELECT statement identifies the rows and columns that are to be input to the JOB activity. Only one SELECT
statement can be coded in each JOB activity, and it must be coded as the first statement in the JOB activity.
Code the SELECT statement immediately following the JOB INPUT SQL statement.
If this execution is for an SQL/DS system, a CONNECT statement is generated and executed by CA Easytrieve® Report
Generator. This means that the user does not need to include an SQL CONNECT statement when using CA Easytrieve®
Report Generator automatic processing. The user ID and password parameters are those that were specified in the
USERID parameter of the PARM statement.
CA Easytrieve® Report Generator checks the SQLCODE field following each execution of the select-clause. If the
SQLCODE indicates an error, CA Easytrieve® Report Generator issues an error message based on the SQL error and
terminates execution. An SQLCODE value indicating end of data causes CA Easytrieve® Report Generator to initiate end
of input processing: the FINISH PROC (if any) executes, spooled reports are printed, and the current JOB activity ends.
For a description of SQL codes, see your SQL vendor manuals.
The SQL cursor that is automatically defined by a SELECT statement is closed following the JOB activity referencing it.
This statement has the following format:
940
CA Easytrieve® Report Generator 11.6
{ {* }
[DISTINCT] { {expression }
SELECT [ ] { { } +
[ALL ] { {table-name.* }
{ {correlation-name.*}
}
[ {expression } ] }
[, {table-name.* } . ..] } +
[ {correlation-name.*} ] }
}
FROM table-name [correlation-name] +
[,table-name [correlation-name] ...] +
[WHERE search-condition] +
[GROUP BY column-name + ] +
[ [, column-name ...] ]
[HAVING search-condition] +
[ { {* } ]
[ [DISTINCT] { {expression } ]
[UNION SELECT [ ] { { } + ]
[ [ALL ] { {table-name.* } ]
[ { {correlation-name.*} ]
[ ]
[ } ]
[ [ {expression } ] } ]
[ [, {table-name.* } ...] } + ]
[ [ {correlation-name.*} ] } ]
[ } ]
[ ]
[ FROM table-name [correlation-name] + ]
[ [,table-name [correlation-name] ...] + ] +
[ ]
[ [WHERE search-condition] + ]
[ ]
[ [GROUP BY column-name + ] + ]
[ [ [, column-name ...] ] ]
[ ]
[ [HAVING search-condition] ]
[ {column-name} [ASC ] ]
[ORDER BY { } [ ] + ]
[ {integer } [DESC] ]
[ ]
[ [ {column-name} [ASC ] ] ]
[ [, { } [ ] ...] ] +
[ [ {integer } [DESC] ] ]
941
CA Easytrieve® Report Generator 11.6
INTO :host-variable [, :host-variable...]
• [DISTINCT|ALL]
Specify DISTINCT to eliminate duplicate rows. ALL specifies that duplicate rows are not to be eliminated. ALL is the
default.
• {*|expression|table-name.*|correlation-name.*}
These parameters are used to identify the columns to be retrieved from the specified table.
• FROM table-name [correlation-name]
Table-name specifies the table from which data is to be retrieved. Correlation-name can be used to specify an
alternate qualifier for the table-name that immediately precedes it.
• [WHERE search-condition]
Search-condition is used to specify conditions for the retrieval of data. The search-condition is applied to the result of
the FROM clause. For information about the search-condition, see your SQL vendor manuals.
• [GROUP BY column-name]
GROUP BY is used to group data that is fetched into the file. Column-name must name a column in the file-name.
• [HAVING search-condition]
Search-condition is used to specify the data to be provided to the user. HAVING can be used to compare the results
of all the returned data with a specific value in the data provided (such as the minimum or maximum value). For
information about the search-condition, see your SQL vendor manuals.
• [UNION...]
The UNION clause is used to include rows from another table.
• [ORDER BY {column-name|integer} [ASC|DESC]]
ORDER BY returns the rows of the result table in the order of the values of the specified column-names. Integer
references a column by its position in the result table rather than by a column-name. ASC returns the rows in
ascending order and is the default. DESC returns the rows in descending order.
• INTO :host-variable [, :host-variable...]
INTO identifies where the column values are to be placed. The INTO clause must be the last clause coded on the
SELECT statement.
Example
The pseudo-code generated for automatic SQL processing is:
* IF SQL/DS
SQL CONNECT :user-id IDENTIFIED BY :password
* END-IF
SQL DECLARE cursor CURSOR FOR select clause
SQL OPEN cursor
DO WHILE SQLCODE NE 100
SQL FETCH cursor INTO :host-variable-1 +
[, :host-variable-2...]
process <easy> code
END-DO
SQL CLOSE cursor
SELECT Statement (Report Selection)
A SELECT statement can be executed in a REPORT-INPUT procedure to select report input data. If the REPORT-INPUT
procedure is not coded, all records selected with a PRINT statement are used in the report.
SELECT only sets a switch to cause record selection at a later time. If you SELECT a record twice, it appears only once
on the printed report.
942
CA Easytrieve® Report Generator 11.6
If coded, a REPORT-INPUT procedure is performed for each PRINT statement (report input). To cause the data to
continue into report processing, you must execute a SELECT statement for the associated input data. In other words,
input that does not get selected is bypassed for continued processing. See REPORT-INPUT Report Procedure for more
information.
This statement has the following format:
SELECT
Example
REPORT-INPUT. PROC
IF ZIP NE HOLD-ZIP
HOLD-ZIP = ZIP
SELECT
END-IF
END-PROC
SELECT Statement (Sort Selection)
CA Easytrieve® Report Generator supplies input records to your optional sort procedure one at a time. If a BEFORE
procedure is used, a SELECT statement must be executed for each record that you want to sort.
SELECT only sets a switch to cause record selection at a later time. If you SELECT a record twice, it appears only once
on the sorted file. If you SELECT a record and then issue a STOP, the record is not selected.
This statement has the following format:
SELECT
Example
The following example of a SORT activity shows an output file that contains only a reordered subset of the input file. The
output file contains only those records for which the SELECT statement is executed.
FILE PERSNL FB(150 1800)
%PERSNL
FILE SORTWRK FB(150 1800) VIRTUAL
COPY PERSNL
SORT PERSNL TO SORTWRK USING +
(REGION, BRANCH, DEPT, +
NAME-LAST, NAME-FIRST) +
NAME MYSORT BEFORE SCREENER
*
SCREENER. PROC
IF MARITAL-STAT = 'S' AND SEX = 1
SELECT
END-IF
END-PROC
943
CA Easytrieve® Report Generator 11.6
SEQUENCE Statement
The SEQUENCE statement optionally specifies the order of a report. You can order any report based on the content of
one or more fields.
The fields used to SEQUENCE a report do not have to be part of the printed report.
This statement has the following format:
SEQUENCE field-name [D] ...
• field-name
field-name identifies a field on which a report is ordered. You can specify multiple field-names for a report.
field-name must be in an active file or W-type working storage. Each field must be less than 256 bytes. The fields
specified are used as sort keys processed in major to minor order.
NOTE
Varying length, K, and M fields cannot be specified on a SEQUENCE statement.
• [D]
An optional D following a field-name indicates that the field is sequenced into descending order. If you do not code D
after a field-name, by default the field is sorted in ascending order.
Examples
The following example illustrates using the SEQUENCE statement in a report declaration.
REPORT PERSNL-REPORT
SEQUENCE REGION BRANCH PAY-NET D
CONTROL REGION BRANCH
TITLE 'PERSONNEL REPORT'
LINE REGION BRANCH EMPNAME PAY-NET
SET Statement
The SET statement allows you to dynamically change screen attributes and to control the display of screen errors.
You can code the SET statement in a screen procedure or in any procedure performed from a screen procedure, except
for SCREEN TERMINATION. If coded in a SCREEN TERMINATION procedure or if coded in a procedure called from a
SCREEN TERMINATION procedure, the SET statement is ignored at execution time.
The SET statement can be executed any number of times before displaying the screen. The last SET statement for field-
name determines the attributes or messages for that field.
The attributes or error message established by a SET statement remain for only one iteration of the SCREEN activity.
After the SCREEN is displayed, the attribute returns to its default as coded on the ROW statement. For changing field
attributes until they are modified further, use a declared attribute. For an example using dynamic screen attributes, see the
Programming Guide.
When multiple SET statements are coded for multiple field-names before the next display of a screen, the field-name that
is physically displayed first on the screen has its message displayed on the screen. All other field-names have only their
attributes displayed.
The SET statement overrides any ACTION messages defined in the MESSAGE statement, even if the MESSAGE
statement is executed after all SET statements.
944
CA Easytrieve® Report Generator 11.6
The attributes and messages specified on the SET statement are evaluated when the statement is executed. If the
attributes or messages are variable, the value is saved and bound to the field-name when the SET statement is executed.
If the variables are later modified, the attributes or messages are not changed when the screen is redisplayed.
If you code SET field-name ERROR without any other parameters, the attributes and messages for field-name are
determined by the ROW statement. If the attributes and messages on the ROW statement are variable, the values
displayed for the SET statement are the same as the values determined when the ROW statement is evaluated.
When you execute a RESHOW, REFRESH, or GOTO SCREEN statement after a SET statement, the attributes or
messages specified in the SET statement are not affected.
This statement has the following format:
Format 1
SET field-name ERROR +
[ [ {attribute-name } ] [ {'literal' [ ] } ] ]
[ [ATTR { } ] [ { [...] } ] ]
[ [ {(attribute-list)} ] [ {field-name [ ] } ] ]
Format 2
{attribute-name }
SET field-name ATTR { }
{(attribute-list)}
• field-name
Field-name specifies a field on a ROW statement in your screen declaration. Field-name can be indexed or
subscripted. If the index or subscript of field-name is evaluated and is not on the screen, the SET statement is ignored.
• ERROR
Use ERROR to indicate that you want to flag field-name as being in error and to specify attributes or messages for
field-name.
When you specify ERROR, the attributes or messages for field-name are determined by the hierarchy in the following
table. The priority is from highest to lowest.
Statement/ Area Attributes Message
1. SET statement ATTR parameter literal or field-name parameter(s)
2. ROW statement ERROR ATTR parameter ERROR 'literal' or field-name parameter(s)
3. DEFAULT statement FIELD ERROR ATTR parameter Default system message:
Value entered is not allowed. Type an
acceptable value.
4. Site Options Table FIELD ERROR ATTR parameter Default system message: Value entered is
not allowed. Type an acceptable value.
NOTE
If you code SET ERROR without the ATTR, 'literal' or field-name parameters, the attributes and messages are
determined by the next statement or area in the above hierarchy.
• [ATTR {attribute-name|(attribute-list)}]
ATTR specifies either a declared screen attribute name or one or more attribute keywords. For a list of attributes, see
ATTR Parameter. For more information about declared screen attributes, see DECLARE Statement.
The following attributes are invalid for literals and system-defined read-only fields:
945
CA Easytrieve® Report Generator 11.6
– ALARM
– CURSOR
– INVISIBLE
– MUSTENTER
– MUSTFILL
– NUMERIC
– TRIGGER
If you use these attributes, they are ignored, but CA Easytrieve® Report Generator Online issues a warning message
during compilation.
SENDONLY and ASKIP are assumed for literals and system-defined read-only fields.
• {'literal'|field-name}
Use 'literal' to define the text you want displayed in the message. Use field-name to specify a field whose contents you
want displayed as part of the message. A message can consist of a combination of literals and field-names.
The maximum length of a message is 130 characters. If the message exceeds the message area for the screen on
which it is displayed, the message is truncated.
Examples
In the following example, when the department number is not found in the table, the field is flagged in error:
ROW DEPT ERROR 'Department in error'
...
AFTER-SCREEN. PROC
SEARCH DEPTBL WITH DEPT GIVING DEPT-DESC
IF NOT DEPTBL
SET DEPT ERROR
END-IF
END-PROC
In the next example, when a user types a value greater than 50,000 into PAY-GROSS, PAY-GROSS is displayed in
yellow; otherwise PAY-GROSS is displayed in turquoise.
ROW PAY-GROSS
...
AFTER-SCREEN. PROC
IF PAY-GROSS > 50,000
SET PAY-GROSS ATTR (YELLOW)
ELSE
SET PAY-GROSS ATTR (TURQ)
END-IF
END-PROC
In this example, five rows are displayed when the screen is displayed. Row 1 is displayed in blue and the cursor is
positioned in AFIELD. Rows 2 to 5 are displayed in yellow.
REPEAT 5 TIMES VARYING SUB1 FROM 1
ROW AFIELD(SUB1) ATTR (YELLOW)
END-REPEAT
946
CA Easytrieve® Report Generator 11.6
...
BEFORE-SCREEN. PROC
SET AFIELD(1) ATTR (BLUE CURSOR)
END-PROC
SKIP Statement
SKIP is a listing control statement that spaces the printer a designated number of lines before printing the next line of the
statement listing.
You can code a SKIP statement anywhere in CA Easytrieve® Report Generator source code. SKIP must be on a record
by itself. SKIP does not appear in the printed output. However, the requested blank line appears.
This statement has the following format:
SKIP skip-amount
• skip-amount
Skip-amount must be an unsigned integer.
SORT Statement
The SORT statement defines and initiates an activity that sorts any file that can be processed sequentially. SORT
sequences an input file in alphabetical or numerical order based on fields specified as keys.
CA Easytrieve® Report Generator supplies input records to your sort procedure one at a time. If a BEFORE proc-
name procedure is used:
• You must execute a SELECT statement for each record that you want returned to the output file.
• A selected record is written only once, even if selected more than once in the procedure.
• Any record not selected does not get written to the sorted file.
• If the file being sorted is a variable length record file, the output file is generated with a record length equal to the
maximum record length that is specified in the FILE statement.
SORT activities can be executed by PROGRAM and SCREEN activities. If a PROGRAM activity is not coded, JOB and
SORT activities are automatically executed sequentially until a SCREEN activity is encountered.
For more information about sorting files, see the Programming Guide.
This statement has the following format:
SORT input-file-name TO sorted-file-name +
USING (sort-key-field-name [D] ...) +
[ [ACTIVITY ] [TERMINAL ] ]
[COMMIT ([ ] [ ])] +
[ [NOACTIVITY] [NOTERMINAL] ]
[SIZE record-count] +
[WORK number-of-work-data-sets] +
[BEFORE proc-name] +
947
CA Easytrieve® Report Generator 11.6
[NAME sort-name]
• input-file-name
input-file-name is the name of the input file for the SORT activity.
input-file-name must reference a FILE statement that defines a SEQUENTIAL, INDEXED, RELATIVE, or VFM file. The
record length of input-file-name controls the length of records to be sorted, except when both files are fixed length.
When this occurs, the length of the records is equal to that of input-file-name or sorted-file-name, whichever is shorter.
• TO sorted-file-name
sorted-file-name designates the name of the output file of the sort activity. Sorted-file-name must reference a FILE
statement that defines a SEQUENTIAL, INDEXED, RELATIVE, or VFM file.
If sorted-file-name is the same file name as input-file-name, the sorted output is written over the input file.
• USING (sort-key-field-name [D] ...)
USING (sort-key-field-name) specifies key fields for sorting input-file-name.
You can code any number of fields up to the input limit of your installation's sort program. sort-key-field-name can be
any field less than 256 bytes long in the sort input file. (The only exceptions are variable length fields, which cannot be
used as keys.) sort-key-field-name cannot be a nullable field.
Code D to sort output in descending order. The default is ascending order.
NOTE
Varying length, K, and M fields cannot be specified as sort keys.
• [COMMIT [ACTIVITY|NOACTIVITY] [TERMINAL|NOTERMINAL]]
Specify the COMMIT parameter to control the logical unit of work. COMMIT indicates when the activity commits
recoverable work. Each commit point posts all updates, additions, and deletions, and terminates holds. SQL cursors
may or may not be closed, depending on the underlying database and the cursor definition.
Specify ACTIVITY to commit all recoverable work during the normal termination of the activity. Specify NOACTIVITY to
tell CA Easytrieve® Report Generator not to commit at the end of the activity. NOACTIVITY is the default.
Specify TERMINAL to commit all recoverable work during any terminal I/O operation. In CICS, this results in terminal
I/O being performed in a pseudo-conversational mode. Specify NOTERMINAL to tell CA Easytrieve® Report
Generator not to commit during a terminal I/O. TERMINAL is the default.
If this activity is executed by an activity that has NOTERMINAL specified, this activity performs terminal I/O as if
NOTERMINAL was specified.
For more information, see the Programming Guide.
• [SIZE record-count]
Because CA Easytrieve® Report Generator knows the number of records in files created by previous activities, it
automatically supplies that information to the sort program. If the file was not created by a previous activity, you
can enhance sort efficiency by supplying the approximate number of records as record-count on the optional SIZE
parameter. Record-count must be an unsigned integer.
• [WORK number-of-work-data-sets]
Specifies the number of work data sets used by the sort program. Number-of-work-data-sets must be one of the
following:
– A zero -- to indicate that DD statements are supplied
– A value from 1 to 31 -- to indicate the number of work data sets that the sort program dynamically allocates
This parameter overrides the number of work data sets set in the Site Options Table.
• [BEFORE proc-name]
Optionally, specify proc-name to identify your procedure that pre-screens, modifies, and selects input records for the sort.
See SELECT Statement (Sort Selection) for more information.
If you do not specify BEFORE proc-name, CA Easytrieve® Report Generator sorts all records in input-file-name and writes
them to sorted-file-name.
• [NAME sort-name]
Optionally, specify sort-name to identify the SORT activity. Sort-name:
948
CA Easytrieve® Report Generator 11.6
– Can be up to 128 characters in length
– Can contain any character other than a delimiter
– Can begin with A to Z, 0 to 9, or a national character (#, @, $)
– Must not consist of all numeric characters
The sort-name can be used to identify the sort in an EXECUTE statement.
Example
In the following example, the output file contains all of the records of the input file sorted into ascending sequence by the
values of fields REGION and BRANCH:
FILE PERSNL FB(150 1800)
%PERSNL
FILE SORTWRK FB(150 1800) VIRTUAL
COPY PERSNL
SORT PERSNL TO SORTWRK USING +
(REGION, BRANCH) NAME MYSORT
SQL Statement
The SQL statement supports the SQL statements of the following database management systems:
• DB2
• SQL/DS
• CA Datacom/DB SQL
• CA IDMS SQL
• Ingres
• Oracle
• Sybase
• ODBC
This statement has the following format:
SQL native-sql-statement
Usage Notes
For information about syntax for native database statements, see the specific database management system manual.
Listed below are the SQL statements currently supported by the SQL interface. For more information about coding native
SQL statements, see the Programming section.
DB2 SQL Statements:
949
CA Easytrieve® Report Generator 11.6
• ALTER
• CLOSE cursor-name
• COMMENT ON
• COMMIT {work}
• CONNECT
• CREATE
• DECLARE cursor-name {with hold}
• DELETE {where current of cursor-name}
• DROP
• EXPLAIN
• FETCH cursor-name
• GRANT
• INSERT
• LABEL
• LOCK
• OPEN cursor-name
• RELEASE
• REVOKE
• ROLLBACK {work}
• SELECT INTO *(for static-only processing)
• SET CONNECTION
• SET CURRENT DEGREE
• SET CURRENT PACKAGESET
• SET CURRENT SQLID
• SET host-variable
• UPDATE {where current of cursor-name}
Note: See SQLSYNTAX in PARM Statement for more information.
SQL/DS SQL Statements:
950
CA Easytrieve® Report Generator 11.6
• ACQUIRE
• ALTER
• CLOSE cursor-name
• COMMENT
• COMMIT {work}
• CONNECT userid
• CONNECT TO database
• CREATE
• DECLARE CURSOR-NAME
• DELETE {where current of cursor-name}
• DROP
• EXPLAIN
• FETCH cursor-name
• GRANT
• INSERT
• LABEL
• LOCK
• OPEN cursor-name
• PUT
• REVOKE
• ROLLBACK {work}
• UPDATE {where current of cursor-name}
CA Datacom/DB SQL Statements:
• ALTER
• CLOSE cursor-name
• COMMENT
• COMMIT {work}
• CREATE
• DECLARE cursor-name
• DELETE {where current of cursor-name}
• DROP
• FETCH cursor-name
• GRANT
• INSERT
• LOCK
• OPEN cursor-name
• REVOKE
• ROLLBACK {work}
• SELECT INTO
• UPDATE {where current of cursor-name}
CA IDMS SQL Statements:
951
CA Easytrieve® Report Generator 11.6
• ALTER
• CLOSE cursor-name
• COMMIT {work} {continue} {release}
• CONNECT TO dictionary-name
• CREATE
• DECLARE cursor-name
• DELETE*
• DROP
• EXPLAIN
• FETCH cursor-name
• GRANT
• INSERT
• OPEN cursor-name
• RELEASE
• RESUME
• REVOKE
• ROLLBACK {work}
• SUSPEND
• UPDATE*
NOTE
* Note: WHERE CURRENT OF cursor cannot be dynamically processed by the SQL interface for CA IDMS. To
perform SQL updates, you must code native SQL statements using a search WHERE clause.
Ingres SQL Statements:
• CLOSE cursor-name
• COMMIT {work}
• CONNECT
• CREATE
• DECLARE cursor-name
• DELETE
• DISCONNECT
• DROP
• FETCH cursor-name
• INSERT
• OPEN cursor-name
• ROLLBACK {work}
• UPDATE
Oracle SQL Statements:
952
CA Easytrieve® Report Generator 11.6
• CLOSE cursor-name
• COMMIT {work}
• CONNECT
• CREATE
• DECLARE cursor-name
• DELETE
• DISCONNECT
• DROP
• FETCH cursor-name
• INSERT
• OPEN cursor-name
• ROLLBACK {work}
• UPDATE
Sybase SQL Statements:
• CLOSE cursor-name
• COMMIT {work}
• CONNECT
• CREATE
• DECLARE cursor-name
• DELETE
• DISCONNECT
• DROP
• FETCH cursor-name
• INSERT
• OPEN cursor-name
• ROLLBACK {work}
• UPDATE
• USE
ODBC SQL Statements:
• CLOSE cursor-name
• COMMIT {work}
• CONNECT
• CREATE
• DECLARE cursor-name
• DELETE
• DISCONNECT
• DROP
• FETCH cursor-name
• INSERT
• OPEN cursor-name
• ROLLBACK {work}
• UPDATE
• USE
953
CA Easytrieve® Report Generator 11.6
SQL INCLUDE Statement
The CA Easytrieve® Report Generator SQL INCLUDE statement indicates that SQL table information is to be used to
generate CA Easytrieve® Report Generator field definitions. It names the table and gives the location where the field
definitions are generated.
This statement has the following format:
SQL INCLUDE +
[(column ...)] +
[ {starting-position} ]
[ {* [+offset] } ]
[LOCATION { } ] +
[ {W } ]
[ {S } ]
[HEADING] +
[UPDATE] +
[NULLABLE] +
FROM [owner.] table
• [(column ...)]
Specify a list of one or more column names for which field definitions are to be generated. The column name(s) must
be enclosed within parentheses. If no column names are specified, all columns from the table are used.
• [LOCATION {starting-position|* [+offset]|W|S}]
Use this optional parameter to specify the location at which the field definitions are to be generated. This parameter
functions as the starting-location parameter of the DEFINE statement.
Starting-position specifies the starting position relative to position one of the record or file.
The * (asterisk) indicates that the field begins in the next available starting position (highest position assigned so far,
plus 1) within a file. The optional +offset is an offset you want added to the * value. There must be at least one blank
between the * and the optional +offset. Use * when this SQL INCLUDE is used to generate fields within a FILE.
Coding W or S establishes a working storage field. W fields are spooled to report (work) files; S fields are not. W is the
default location if the LOCATION parameter is not coded.
• [HEADING]
Optionally, code HEADING to cause remarks in the DBMS system catalog entry for a column to be copied into a
HEADING parameter on the generated DEFINE statement for the column. This parameter is ignored for Ingres.
• [UPDATE]
Code UPDATE to designate a modifiable column.
When a CA Easytrieve® Report Generator SQL file does not contain the UPDATE parameter, only the specific columns
defined with UPDATE can be modified with an UPDATE statement. If UPDATE is coded on the FILE statement, all
columns in the file can be modified.
NOTE
You can use UPDATE only when the field definitions are generated for a CA Easytrieve® Report
Generator file.
• [NULLABLE]
Optionally, code NULLABLE to cause default indicator fields to be defined for columns that contain NULL.
The indicator field is defined as a 2 B 0 field preceding the field being defined. CA Easytrieve® Report
954
CA Easytrieve® Report Generator 11.6
Generator automatically uses the default null indicator whenever the associated column is referenced. You can
override the use of the default null indicator by explicitly coding and referencing another indicator variable.
The indicator variable precedes the data portion of the field in storage. This field cannot be directly referenced. To
check this indicator variable, you must use the IF NULL statement.
• FROM [owner.] table
FROM identifies the table definition to be defined to CA Easytrieve® Report Generator. Owner is the optional 1- to 18-
character alphanumeric qualifier, and table is the 1- to 32-character alphanumeric name. The period must be used as
the qualification separator for owner-qualified tables.
NOTE
If the owner is not specified, the current authorization ID is used.
Usage Notes
When used, the SQL INCLUDE statements must precede any other SQL or SELECT statements and must be coded in
the library definition section of your CA Easytrieve® Report Generator program.
The generated CA Easytrieve® Report Generator field names are the same as the SQL column names. If a name
matches a reserved word, the field definition is allowed, but all references to it must be qualified, using any applicable
qualification.
Mask information is not retrieved from the DBMS system catalog.
Group qualification structures of owner.table are defined prior to the first included definition. The fields are defined under
the table entity, which is in turn under the owner level entity. This ensures that multiple tables with duplicate column
names do not produce duplicate field names.
Fields with SQL data types that do not have equivalent CA Easytrieve® Report Generator data types are defined as
shown in the following table. Fields of DATE, TIME, TIMESTAMP, and BINARY cannot be used in arithmetic operations.
Fields of FLOAT, DOUBLEPRECISION, REAL, and LONGINTEGER are defined as packed decimal fields. Non-zero
FILE-STATUS and SQLCODE values are returned if the data is truncated.
SQL Data Type CA Easytrieve® Report Length Decimals
Generator Data Type
DATE Alphanumeric 10
TIME Alphanumeric 8
TIMESTAMP Alphanumeric 26
BINARY Alphanumeric Length of SQL field
FLOAT Packed Numeric 10 3
DOUBLEPRECISION Packed Numeric 10 3
REAL Packed Numeric 10 3
LONGINTEGER Packed Numeric 10 0
The DBMS system catalog must be referenced each time the program is compiled or interpreted. Therefore, to reduce
catalog contention and to improve performance, you should always create link-edited programs.
Field Reference
One of the advantages of using the SQL INCLUDE interface is the ability to reference host-variables (CA Easytrieve®
Report Generator fields) using the group level TABLE definition.
When specifying the INTO clause on a native SQL FETCH or non-file SQL SELECT statement or the VALUES clause
of the native SQL INSERT statement, you can substitute the host variable TABLE definition in place of coding all host-
variables in the table.
955
CA Easytrieve® Report Generator 11.6
If you require access to an indicator variable other than its use for NULL checking, you must define your own variable and
reference it with its host-variable. For some DBMSs, the indicator variable is examined to detect truncation.
When the host-variable is a CA Easytrieve® Report Generator group level definition of a table name, an array of type 2 B
0 should be specified immediately following the host-table-name-variable. The number of array elements should match the
number of fields in the CA Easytrieve® Report Generator table name definition. Array elements are matched one-to-one
with the fields defined in the table name.
STOP Statement
The STOP statement terminates activities.
In CA Easytrieve® Report Generator, activities with automatic file input automatically terminate when all input records
have been processed. You can terminate activities prematurely, however, with a STOP statement. You must use STOP to
terminate JOB activities without automatic file input (for example, JOB INPUT NULL).
NOTE
Use the EXIT statement to normally terminate SCREEN activities.
When used in a JOB activity, STOP completes all reports and executes a FINISH procedure, if coded. If you code STOP
EXECUTE, all CA Easytrieve® Report Generator activity procedures are immediately terminated. If STOP is coded in the
START or FINISH procedure, the procedure is terminated.
When used in a SORT activity procedure, a STOP terminates the record selection process and executes the sort
program. If you selected a record, the record is not accepted.
When COMMIT ACTIVITY is specified for the activity, a STOP statement causes a COMMIT of all recoverable work. A
STOP EXECUTE causes a ROLLBACK.
This statement has the following format:
STOP [EXECUTE]
• [EXECUTE]
EXECUTE immediately terminates all CA Easytrieve® Report Generator execution and is considered an abnormal
termination and causes recoverable resources to be rolled back, etc.. STOP without EXECUTE terminates the current
activity only. Subsequent activities (if any) are executed normally.
Examples
The following example illustrates STOP in a SORT activity to limit the number of records being sorted. In this example,
only the first 50 records from PERSNL are sorted, because the STOP statement simulates end-of-file on PERSNL.
FILE PERSNL FB(150 1800)
%PERSNL
FILE SORTOUT FB(150 1800) VIRTUAL
COPY PERSNL
*
SORT PERSNL TO SORTOUT +
USING (PAY-GROSS D) +
NAME MYSORT BEFORE SORT1-PROC
*
SORT1-PROC. PROC
IF PERSNL:RECORD-COUNT GT 50
STOP
956
CA Easytrieve® Report Generator 11.6
ELSE
SELECT
END-IF
END-PROC
Under certain circumstances, you might want to completely terminate all activities using a STOP EXECUTE statement, as
in the next example:
FILE INVENT FB(200 3200)
%INVMSTR
FILE SORTWRK F(200) VIRTUAL
COPY INVENT
*
JOB INPUT INVENT NAME MYPROG1 FINISH FINISH-PROC
PRINT MYREPORT
*
FINISH-PROC. PROC
IF RECORD-COUNT = 0
DISPLAY 'INPUT FILE NOT AVAILABLE'
DISPLAY 'HALTING EXECUTION...'
STOP EXECUTE
END-IF
END-PROC
*
REPORT MYREPORT
LINE PART-NUMBER PART-DESCRIPTION
*
SORT INVENT TO SORTWRK USING +
(LOCATION-STATE, +
LOCATION-CITY) NAME MYSORT
*
JOB INPUT SORTWRK NAME MYPROG2
PRINT MYREPORT
*
REPORT MYREPORT
LINE PART-NUMBER LOCATION-CITY LOCATION-STATE
SUM Statement
The SUM statement is a report definition statement that explicitly specifies the quantitative fields that are totaled for a
control report.
Normally, CA Easytrieve® Report Generator automatically totals all quantitative fields specified on LINE statements. The
SUM statement overrides this process; only the fields specified on the SUM statement are totaled. The fields specified on
a SUM statement do not have to be specified on a LINE statement. The SUM statement is valid only in a Control Report.
This statement has the following format:
SUM field-name ...
• field-name
Field-name is any quantitative field contained in an active file or W storage. You can specify multiple fields.
957
CA Easytrieve® Report Generator 11.6
TERMINATION Report Procedure
A TERMINATION procedure is invoked at the end of the report. This procedure can be used to print report footing
information, including control totals and distribution information.
You must use an END-PROC statement to delimit a TERMINATION procedure. See PROC Statement for more
information.
This statement has the following format:
TERMINATION. PROC
Example
The following is an example of report footing:
FILE FILE1
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
TOTAL-NET S 8 N 2
JOB INPUT FILE1 NAME MYPROG
TOTAL-NET = TOTAL-NET + PAY-NET
PRINT REPORT1
*
REPORT REPORT1 LINESIZE 65 +
SUMMARY SUMCTL DTLCOPY
SEQUENCE STATE ZIP LAST-NAME
CONTROL STATE NEWPAGE ZIP
TITLE 'REPORT FOR THE STATE OF' STATE
LINE 01 LAST-NAME STATE ZIP PAY-NET
*
TERMINATION. PROC
DISPLAY TITLE
DISPLAY SKIP 5 TOTAL-NET 'IS THE Y-T-D COMPANY NET PAY'
DISPLAY SKIP 5 'PLEASE ROUTE THIS REPORT TO CORPORATE OFFICERS'
END-PROC
TERMINATION Screen Procedure
A TERMINATION procedure is invoked once during the end of the screen activity.
The TERMINATION procedure is performed when an EXIT action has been executed either by being assigned to a key or
by being executed in another screen procedure. It is used to perform actions that are to be executed only at the end of the
activity.
If GOTO SCREEN or EXIT is executed in a TERMINATION procedure, the activity is stopped at that point. REFRESH and
RESHOW are invalid in a TERMINATION activity.
You must use an END-PROC statement to delimit a TERMINATION procedure. See PROC Statement for more
information.
This statement has the following format:
958
CA Easytrieve® Report Generator 11.6
TERMINATION. PROC
TITLE Statement (Reports)
One or more TITLE statements define an optional report title. The TITLE statement defines the title items and their
position on the title line.
CA Easytrieve® Report Generator automatically positions the system date and current page count on title line one. This
can be overridden by options on the REPORT statement (NODATE and NOPAGE).
This statement has the following format:
{[ ] field-name}
{[#font-number] }
TITLE [title-number] {[ ] 'literal' } ...
{+offset }
{-offset }
{COL column-number }
• [title-number]
Title-number specifies the position of the title line in the title area. Title-number must be from 1 to 99 (default is 1). You
must specify title numbers in ascending order with no duplicates. The title-number of the first TITLE statement must be
1 or unspecified.
• [#font-number]
#Font-number defines a font index. The value of #font-number identifies a font whose specifications are to be used
for the next display item. You can only specify this option if the report has been associated with an extended reporting
printer. #Font-number identifies the font number of a font defined for the associated extended reporting printer. If you
do not code the font number, then the next display item uses the default font for the assigned extended reporting
printer.
• {field-name}
Field-name specifies a field in any active file, working storage field, or system-defined field.
• {'literal'}
'Literal' specifies a character string for a title item. It must be either a numeric literal, a hexadecimal literal, or an
alphanumeric literal. Alphanumeric literals must be enclosed in single quotes.
By default, each title line is formatted as a list of title items that are separated by the number of spaces defined by the
SPACE parameter of the REPORT statement. The +, -, and COL parameters modify this positioning.
NOTE
You must code at least one title item, specified by field-name or 'literal', on each TITLE statement.
• {+offset|-offset}
The space adjustment parameters, +offset and -offset, modify the normal spacing between title items. Offset is added
to or subtracted from the SPACE parameter on the REPORT statement to get the absolute space between title items.
The absolute space value can range from zero to any amount that still allows the title line to fit within the current
LINESIZE value on the REPORT statement.
• {COL column-number}
The COL parameter specifies the print column number where the next title item is placed. The value of column-number
has a valid range of 1 to nnn, where nnn cannot force the following title item beyond the end of the title line LINESIZE.
Each title line is centered within the title area of the report unless you specify NOADJUST.
When the report is associated with an extended reporting printer, an error results if two or more fields or literals
overlap.
959
CA Easytrieve® Report Generator 11.6
TITLE Statement (Screens)
The TITLE statement is used to automatically center items on a screen.
TITLE items that are not located at a specific column (COL) are centered in the row based on the LINESIZE parameter of
the SCREEN statement.
This statement has the following format:
[[COL column-number] {field-name}
TITLE [row-number] [[ ] { } +
[[+offset ] {'literal' }
[ {attribute-name } ] ]
[ATTR { } ] ] ...
[ {(attribute-list)} ] ]
• [row-number]
Specify the row-number on which you want the TITLE to be displayed. If row-number is not specified, the next screen
row is used for the title. The next screen row is not the highest row used, but the previously-specified row plus one. If
no rows are previously specified, row one is used.
• [COL column-number][+offset]
Use COL to display a title item at a specific column (column-number) on the screen.
Titles are separated by one space on a screen. Use +offset to add additional spaces between titles.
NOTE
A syntax error occurs when a TITLE overlays another screen item.
• {field-name|'literal'}
Specify a field-name or a 'literal' for the title. Field-name is the name of a field to be displayed as a title on the screen.
'Literal' is an alphanumeric string to be displayed as a title on the screen.
• [ATTR {attribute-name|(attribute-list)}]
Specify a declared screen attribute name or a list of attribute keywords. For a list of attributes, see ATTR Parameter.
For procedures to DECLARE screen attributes, see DECLARE Statement.
NOTE
The following attributes are invalid for TITLEs:
If you use these attributes, they are ignored, but CA Easytrieve® Report Generator issues a warning message during
compilation. SENDONLY and ASKIP are assumed for TITLE items.
Example
The following TITLE statement:
TITLE 1 COL 1 'Date:' COL 7 SYSDATE 'Employee Master' +
COL 67 'Time:' COL 73 SYSTIME
produces:
Date: 12/31/09 Employee Master Time: 12:00:00
SYSDATE and SYSTIME are displayed starting in specific columns by using the COL parameter. 'Employee Master' is
automatically centered.
960
CA Easytrieve® Report Generator 11.6
TRANSFER Statement
The TRANSFER statement is used to transfer execution to a target program without returning to the invoking program.
The TRANSFER statement completely terminates the current CA Easytrieve Report Generator program and invokes the
program specified by program-name or the program field-name using the linkage conventions of the operating system
in which the program is executing. Issuing a TRANSFER statement is similar to issuing a STOP statement: reports are
completed and a JOB FINISH procedure is executed (if coded).
The screen is automatically cleared when the current program terminates. In CICS, you can request that the screen
remains displayed on the terminal by using the NOCLEAR parameter. In other environments, NOCLEAR is ignored and
the screen is cleared and left in a ready mode.
NOTE
The target program inherits the execution environment of the program issuing the TRANSFER statement.
TRANSFER can be used to invoke any program written in any language that is supported by the operating system in
which the program is executing; similarly, the program can issue any command supported by the operating system.
When the target program is another CA Easytrieve Report Generator program and you want to pass a parameter, you
must specify the USING parameter on the target program's PROGRAM statement.
When transferring to another CA Easytrieve Report Generator program in a CICS pseudo-conversational environment,
you must specify the TRANSID parameter on the PARM statement of the target program.
NOTE
Using the TRANSFER statement in interpretive execution causes the program execution to terminate. For more
information, see the Programming section.
This statement has the following format:
{field-name } [ {field-name} ]
TRANSFER { } [USING { } ] [NOCLEAR]
{'program-name'} [ {'literal' } ]
• {field-name|'program-name'}
Specify the field-name that contains the name of the target program, or specify the name of the target program as a
'literal' within single quotes. Field-name cannot be nullable.
• [USING {field-name|'literal'}]
Optionally, specify USING to pass a single parameter to the target program.
Specify the name of a field that contains the value to pass to the target program, or specify a 'literal' to pass to the
target program. Field-name cannot be nullable.
• [NOCLEAR]
Use NOCLEAR to specify that you do not want to clear the terminal screen when exiting a CA Easytrieve Report
Generator program in CICS.
Example
CASE OPTION
WHEN 'V'
NEXT-PGM = 'VIEWCUST'
WHEN 'E'
NEXT-PGM = 'EDIT-CUST
WHEN 'D'
NEXT-PGM - 'DEL-CUST'
961
CA Easytrieve® Report Generator 11.6
WHEN 'A'
NEXT-PGM = 'ADD-CUST'
END-CASE
TRANSFER NEXT-PGM USING EMP#
UPDATE Statement
Use the UPDATE statement to update a row from a CA Easytrieve® Report Generator SQL file.
UPDATE issues an UPDATE WHERE CURRENT OF cursor.
When the file is defined with the UPDATE parameter, all defined columns are updated. Otherwise, only the columns that
contain the UPDATE parameter are updated. See SQL INCLUDE Statement>or DEFINE Statement for more information.
Note: UPDATE WHERE CURRENT OF cursor cannot be dynamically processed by the SQL interface for CA IDMS. To
perform SQL updates, you must code native SQL statements using a searched update statement.
This statement has the following format:
UPDATE file-name
• file-name
File-name is the name of a CA Easytrieve® Report Generator SQL file.
Example
The following example changes all employees in department 901 to department 921:
FILE PERSNL SQL PERSONNEL UPDATE
EMPNAME * 20 A
WORKDEPT * 2 P 0
EMPPHONE * 3 P 0
JOB NAME RETRIEVE-PERSONNEL INPUT PERSNL
SELECT FROM PERSNL WHERE WORKDEPT = 901 FOR UPDATE
WORKDEPT = 921
UPDATE PERSNL
WRITE Statement
WRITE is used in the maintenance of SEQUENTIAL, INDEXED, and RELATIVE files (when allowed by the underlying
access method). During random processing of these files, WRITE updates and deletes existing records and adds new
records. Its syntax has two formats.
This statement has the following format:
Format 1
[UPDATE] [ {input-file-name }]
WRITE output-file-name [ ] [FROM { }][STATUS]
[ADD ] [ {input-record-name}]
Format 2
WRITE output-file-name DELETE [STATUS]
962
CA Easytrieve® Report Generator 11.6
• output-file-name
Specify the name of the SEQUENTIAL, INDEXED or RELATIVE file to be updated, added, or deleted. You must also
code UPDATE on the FILE statement for output-file-name.
• [UPDATE|ADD|DELETE]
Specify UPDATE, ADD, or DELETE to designate the type of file maintenance activity to be performed. UPDATE is the
default.
For SEQUENTIAL files, only UPDATE is allowed. For RELATIVE files, only UPDATE and DELETE are allowed.
• [FROM {input-file-name|input-record-name}]
Specify input-file-name or input-record-name to identify an alternative data source for file UPDATE and ADD
operations. FROM is similar to coding a MOVE statement prior to a WRITE statement.
When input-file-name is specified, the current value of output-file-name:RECORD-LENGTH is the length of the
output data. However, if the output file length is greater than the input file or record length, the excess storage is not
initialized. Also, using the FROM parameter does not update the data area of the output file.
• [STATUS]
Specify the STATUS parameter whenever the possibility exists for an unsatisfactory completion of the input/output
request.
STATUS checks input/output processing to see if it was performed properly. STATUS causes the file's FILE-STATUS
field to be set with the appropriate return code. Normally, a zero or non-zero test is sufficient.
NOTE
FILE-STATUS is not defined if you do not specify a file type parameter on the FILE statement.
If you do not code STATUS and the operating system returns a non-zero status, CA Easytrieve® Report Generator
issues an appropriate diagnostic message.
Usage Notes
Format 1
Format 1 of the WRITE statement updates an existing record or adds a new record to the file. When updating, which is the
default, the updated record is the current active record for the file.
Format 2
Format 2 of the WRITE statement deletes the current active record for the file.
Example
The following example illustrates the use of WRITE:
FILE PERSNL INDEXED UPDATE
%PERSNL
PROGRAM NAME MYPROG
READ PERSNL KEY '05807' STATUS
IF PERSNL:FILE-STATUS NE 0
DISPLAY 'FILE-STATUS= ' PERSNL:FILE-STATUS
DISPLAY 'UNSUCCESSFUL READ ON PERSNL FILE'
ELSE
DISPLAY HEX PERSNL
MOVE '3125059599' TO TELEPHONE
WRITE PERSNL UPDATE
IF PERSNL:FILE-STATUS NE 0
DISPLAY 'FILE-STATUS= ' PERSNL:FILE-STATUS
DISPLAY 'UNSUCCESSFUL UPDATE ON PERSNL FILE'
END-IF
963
CA Easytrieve® Report Generator 11.6
END-IF
Symbols and Reserved Words
This section contains a list of CA Easytrieve® Report Generator symbols and reserved words. The reserved words are
listed in alphabetical order. Associated with each symbol is one or more references. The references describe the various
ways you can use the symbol. An R in the column after the symbol indicates it is reserved.
Symbol References
Special Symbol Reserved Reference
. Syntax delimiter (period)
Macro parameter concatenation (period)
< Conditional expression
<= Conditional expression
( Syntax delimiter (left parenthesis)
: Syntax delimiter (colon)
+ Assignment
Continuation of statements and words
DISPLAY
LINE
TITLE
& Macro variable prefix
* Assignment
Comment statement
DEFINE
) Syntax delimiter (right parenthesis)
Ø< Conditional expression POINT
Ø> Conditional expression
Ø= Conditional expression
- Assignment
Continuation of statements and words
DISPLAY
LINE
TITLE
** R Reserved for future use
/ Assignment
' Syntax delimiter (single quote)
% Macro invocation
> Conditional expression
>= Conditional expression
POINT
, Syntax delimiter (comma)
964
CA Easytrieve® Report Generator 11.6
= Assignment
Conditional expression
POINT
@ R Reserved for future use
965
CA Easytrieve® Report Generator 11.6
Reserved Words
The following list includes all CA Easytrieve® Report Generator reserved words:
ACCESS EOF LIST RESTART
AFTER-BREAK EQ LOGICAL-RECORD RETRIEVE
AFTER-LINE ERROR LOW-VALUES RETURN-CODE
AFTER-SCREEN EXECUTE LQ ROLLBACK
AND EXIT LS ROW
ATTR EXTERNAL LT S
BEFORE F1, F2,..F24 MASK SCREEN
BEFORE-BREAK FETCH MATCHED SEARCH
BEFORE-LINE FILE MEND SECONDARY
BEFORE-SCREEN FILE-STATUS MESSAGE SELECT
BREAK-LEVEL FILL MOVE SEQUENCE
BUSHU FINAL MSTART SET
BY FIRST NE SIZE
CALL FIRST-DUP NEWPAGE SKIP
CASE FOR NOMASK SOKAKU
CHECKPOINT GE NOPRINT SORT
CHKP GET NOT SQL
CHKP-STATUS GO NOTE STOP
CLEAR GOTO NOTITLE SUMMARY-INDEX
CLOSE GQ NOVERIFY SUM
COL GR NQ SYSDATE
COLOR GRAPH NULL SYSDATE-LONG
COMMIT GT OF SYSIN
CONTROL HEADING OR SYSIPT
COPY HEX OTHERWISE SYSLST
CURSOR HIGH-VALUES PA1..PA3 SYSPRINT
D IDD PAGE-COUNT SYSSNAP
DECLARE IDMS PAGE-NUMBER SYSTIME
DEFAULT IF PARM-REGISTER SYSUSERID
DEFINE IN PATH-ID TALLY
DELETE INITIATION PATTERN TERM-COLUMNS
DENWA INSERT PERFORM TERM-NAME
DISPLAY JOB POINT TERM-ROWS TERMINATION
DLI JUSTIFY POS TITLE
DO KANJI-DATE PRIMARY TO
DRAW KANJI-TIME PRINT TRANSFER
DUPLICATE KANJI-DATE-LONG PROC TRC
E KEY PROCEDURE UNIQUE
ELSE KEY-PRESSED PROGRAM UNTIL
ELSE-IF KOKUGO PUT UPDATE
ELEMENT-RECORD KUN READ UPPERCASE
END LAST-DUP RECORD VALUE
END-CASE LE RECORD-COUNT VERIFY W
END-DO LEVEL RECORD-LENGTH WHEN
END-IF LIKE REFRESH WORK
END-PROC LINE RELEASE WRITE
ENDPAGE LINE-COUNT RENUM X
END-REPEAT LINE-NUMBER REPEAT XRST
ENDTABLE LINK REPORT 966
ENTER REPORT-INPUT
RESHOW
CA Easytrieve® Report Generator 11.6
Conversion from Old to Current CA Easytrieve Version
This section contains information for sites converting from batch mainframe versions of CA Easytrieve® Report Generator
(Releases 4.0 to 6.4) to the current versions of CA Easytrieve® Report Generator.
Environmental Differences contains a table that helps you easily identify differences in CA Easytrieve® Report Generator
for different environments (mainframe, PC, LINUX, and UNIX). These differences will be resolved in future versions of the
CA Easytrieve® Report Generator language.
In this version of CA Easytrieve® Report Generator, the syntax of several statements has been enhanced for future
use. Wherever possible, older versions of the syntax are supported to allow your current file definitions and programs to
operate.
Supported Syntax
Following are discussions of syntax that is still supported but is not documented in the syntax diagrams contained in this
section. Some of the items in this chapter are ignored in this implementation, while others still function as before but are
replaced by new syntax in this section.
CALL Statement
The NR parameter is ignored.
DISPLAY Statement
The DISPLAY NEWPAGE function has been replaced by the DISPLAY TITLE and DISPLAY NOTITLE functions. The
reason for this change is that previous versions of DISPLAY NEWPAGE did not consistently produce report titles and
headings. For source compatibility, DISPLAY NEWPAGE is accepted and functions the same as DISPLAY TITLE.
END Statement
The END statement is effectively ignored, because CARD input cannot be compiled with the program.
FILE Statement
The VS parameter is replaced with SEQUENTIAL, INDEXED, and RELATIVE. The underlying access method is
determined at execution time. VS is still accepted as valid syntax however, the correct sub-parameter must be specified
for the type of VSAM file being accessed.
The SQL SELECT parameter is replaced with the more powerful SQL file type. SQL SELECT is still supported.
PARM Statement
Current versions of CA Easytrieve® Report Generator ignore the following:
DEVICE
VFM DEVICE (except DISK│MEMORY)
SORT DIAG│NODIAG
SORT ERASE│NOERASE
SORT SYS
SORT TP│NOTP
SORT VIRTUAL│REAL
SORT WORK DA
PRESIZE
EXITSTR
The DBCSCODE parameter is replaced by the CODE parameter, but still supported as valid syntax.
967
CA Easytrieve® Report Generator 11.6
Environmental Differences
The following table identifies differences in CA Easytrieve® Report Generator for different environments (mainframe, PC,
Linux for zSeries, and UNIX). These differences will be resolved in future versions.
Feature Mainframe Online PC, UNIX, Linux for zSeries, MVS Batch
Screen processing X
FILE statement: X X
CODE parameter
KEY parameter
Double Byte Character Set (DBCS) support X MVS Batch Only
968
CA Easytrieve® Report Generator 11.6
Messages and Codes
This section lists the messages and codes that can display during the execution of CA Easytrieve® Report
Generator programs. You can use them to help correct a program error or to help Broadcom Support in case of a system
problem. We list the messages and codes in the following categories:
• EZABXxxxA program abends.
• EZACTxxxA problem when linking, transferring, or calling another program is encountered.
• EZALTxxxA problem in the ETALTSEQ utility is encountered.
• EZCMA Configuration Manager problem is encountered.
• EZDLIxxxA problem accessing DLI is encountered.
• EZEIPxxxA program abends.
• EZIDMxxxA problem accessing IDMS is encountered.
• EZIOExxxAn unrecoverable file I/O error is encountered.
• EZKXxxxxA system initialization problem is encountered.
• EZOPTxxxA problem in the ETOPLOAD utility is encountered.
• EZSHTxxxA system termination problem is encountered.
• EZSQLxxxA problem accessing your SQL database is encountered.
• EZSRTxxxAn error sorting records is encountered.
• EZTCxxxxxCompile warnings and errors occur.
Hundreds of new and explicit messages are available to pinpoint invalid syntax. These messages are designed to
illustrate exactly what is wrong and, where appropriate, the valid syntax you should use to correct the problem.Compiler
messages describe errors and warnings detected during compilation of CA Easytrieve® Report Generator source
programs. In compiler listings, these messages are formatted with a EZTCxxxxx prefix. Warnings are suffixed with W and
errors are suffixed with E. In non-mainframe environments without a listing, the errors show the message number, suffix,
and text.
Starting with r11, the compiler is enhanced to issue messages that are self explanatory. Improvements made are the
following:
• Keyword substitution is often used to insert strings to create tailor-made messages.
• Messages now point exactly to the word in error, not just the line.
• Readability is increased through the use of both upper and lower case where possible.
• Message classes were established, allowing us to issue warnings in addition to errors.
If a message is unclear and you cannot determine the cause of the problem from the message, please contact Broadcom
Support.
The actual message identifier and text issued by CA Easytrieve® Report Generator can change with new product
releases, refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact Broadcom
Support.
Abend codes generally indicate a system error. If one of these abends occurs, review the description to see if it indicates
an installation or security problem. If the cause of the abend is not evident, contact Broadcom Support.
SUPRA Diagnostic Messages
The SUPRA interface provides a comprehensive set of diagnostic messages that describe the types of errors that can
occur when a program is processed.
Diagnostic messages fall into two groups that describe:
969
CA Easytrieve® Report Generator 11.6
• Operational ErrorsErrors that occur in both the preprocessor and in the resulting CA Easytrieve Report Generator
program.
• Syntax ErrorsErrors in SUPRA statements.
Message Format
All SUPRA interface diagnostic messages conform to the following format:
*SUPRA *xnnn m------------m - s----------s
| | |
| | |
\/ \/ \/
Message Diagnostic Message
ID Message Supplement
Message ID
The message ID, a four-character code, identifies each error message. The first character of the message ID designates
the type of error:
• Letter A identifies operational error messages.
• Letter B identifies SUPRA statement syntax error messages.
Diagnostic Message
The diagnostic message is a description of the detected error.
Message Supplement
A message supplement might not be provided, depending on the message type and context. When a message
supplement is provided, it identifies which particular object is in error.
Operational Diagnostic Messages
The following messages identify errors that occur during the execution of the SUPRA preprocessor and the CA
Easytrieve® Report Generator program. The supplemental messages identify:
• Additional diagnostic information
• Current status
A001
ERROR IN SCAN COLUMNS - start-column end-column
Reason:
The column range to scan for input is in error. These columns are set during preprocessor installation. The valid range for
both values is 1 to 80, where start-column is less than end-column.
Action:
Correct the values, recompile the preprocessor, and rerun.
A002
PDM SINON FAILED - status
970
CA Easytrieve® Report Generator 11.6
Reason:
An error occurred when signing on to the physical data manager.
Action:
Consult your Cincom documentation for the PDM SINON command. Correct any system errors and rerun.
A003
PDM OPENX FAILED - status
******EXTENDED STATUS CODE DATA FOLLOWS ******
Reason:
An error occurred opening the directory files. Task extended status data is printed.
Action:
Consult your Cincom documentation for the PDM OPENX command. Correct any system errors and rerun.
A004
PDM CLOSX FAILED - status
******EXTENDED STATUS CODE DATA FOLLOWS******
Reason:
An error occurred while closing the directory files. Task extended status data is printed.
Action:
Consult your Cincom documentation for the PDM CLOSX command. Correct any system errors and rerun.
A005
PDM SINOF FAILED - status
******EXTENDED STATUS CODE DATA FOLLOWS******
Reason:
An error occurred while signing off from the physical data manager. Task extended status data is printed.
Action:
Consult your Cincom documentation for the PDM SINOF command. Correct any system errors and rerun.
A006
PDM READ NAME FILE FAILED - status
******EXTENDED STATUS CODE DATA FOLLOWS******
Reason:
An error occurred while reading the directory name file. The parameter list and task extended status data are printed.
Action:
Consult your Cincom documentation. Correct any system errors and rerun.
971
CA Easytrieve® Report Generator 11.6
A007
PDM READ STRU FILE FAILED - status
******EXTENDED STATUS CODE DATA FOLLOWS******
Reason:
An error occurred while reading the directory structure file. The parameter list and task extended status data are printed.
Action:
Consult your Cincom documentation. Correct any system errors and rerun.
A008
PDM READ DEF# FILE FAILED - status
******EXTENDED STATUS CODE DATA FOLLOWS******
Reason:
An error occurred while reading the directory def# file. The parameter list and task extended status data are printed.
Action:
Consult your Cincom documentation. Correct any system errors and rerun.
A009
PDM READ DATA FILE FAILED - status
******EXTENDED STATUS CODE DATA FOLLOWS******
Reason:
An error occurred while reading the directory data file. The parameter list and task extended status data are printed.
Action:
Consult your Cincom documentation. Correct any system errors and rerun.
A010
PDM SHOWX FAILED - status
Reason:
An error occurred while retrieving the extended status.
Action:
Consult your Cincom documentation for the PDM SHOWX command. Correct any system errors and rerun.
A012
OPEN PARAMETER IS INVALID - parm
Reason:
The value specified for OPEN during installation is invalid. The valid values are YES or NO.
Action:
972
CA Easytrieve® Report Generator 11.6
Correct the value, recompile the preprocessor, and rerun.
A013
OVERRIDE PARAMETER IS INVALID - parm
Reason:
The value specified for OVERRIDE during installation is invalid. The valid values are YES or NO.
Action:
Correct the value, recompile the preprocessor, and rerun.
A101
RDM SIGN-ON ERROR FSI - fsi VSI - vsi message
Reason:
An error occurred while signing on to the relational data manager.
Action:
Consult your Cincom documentation. Correct any system errors and rerun.
A102
RDM SIGN-OFF ERROR FSI - fsi VSI - vsi message
Reason:
An error occurred while signing off of the relational data manager.
Action:
Consult your Cincom documentation. Correct any system errors and rerun.
A103
RDM VIEWS ERRORS FSI - fsi VSI - vsi message
Reason:
An error occurred while opening the logical view.
Action:
Consult your Cincom documentation. Correct any system errors and rerun.
A104
RDM GET ERROR FSI - fsi VSI - vsi message
Reason:
An error occurred while retrieving the logical view.
Action:
Consult your Cincom documentation. Correct any system errors and rerun.
973
CA Easytrieve® Report Generator 11.6
Syntax Diagnostic Messages
The following group of messages describes syntax errors detected in SUPRA statements. The supplemental messages in
this group specify:
• Additional diagnostic information
• Specific object in error
• Word most likely in error
B001
REQUIRED PARAMETER IS NOT CODED - word
Reason:
Additional parameters are required. That is, parameters, subparameters, or their associated values are missing.
Action:
Refer to the statement syntax description, add the appropriate parameters, and rerun.
B002
PARAMETER IS INVALID - word
Reason:
The indicated word is invalid as used in the current statement.
Action:
Refer to the statement syntax description, correct or delete the appropriate parameter, and rerun.
B003
SCHEMA DOES NOT EXIST IN THE DIRECTORY - schema
Reason:
The specified name does not exist in the directory as a schema.
Action:
Correct the schema name and rerun.
B004
VIEW DOES NOT EXIST IN THE DIRECTORY - view
Reason:
The specified name does not exist in the directory as a logical view.
Action:
Correct the view name and rerun.
B005
ACCESS SET DOES NOT EXIST FOR THIS VIEW - view
974
CA Easytrieve® Report Generator 11.6
Reason:
The specified name does not exist in the directory as an access set.
Action:
Correct the access set name and rerun.
B007
FIELD DOES NOT EXIST IN THE DIRECTORY - field
Reason:
The specified name does not exist in the directory as an entity.
Action:
Correct the field name and rerun.
B008
PHYSICAL DETAIL DOES NOT EXIST - field
Reason:
No physical detail records exist in the directory for the field.
Action:
Verify the existence of a physical detail record for the identified field and rerun.
B009
SELECTED FIELD DOES NOT EXIST IN THE VIEW - field
Reason:
The specified name does not exist in the directory as a field in the access set.
Action:
Correct the access set field name and rerun.
B010
INCLUDE FOR THIS VIEW WAS NOT FOUND - view
Reason:
The specified name was not found in the list of INCLUDEd views.
Action:
Check that the view is coded on a SUPRA INCLUDE statement and rerun.
B011
NUMBER OF KEY VALUES EXCEED ACCESS SET - view
Reason:
975
CA Easytrieve® Report Generator 11.6
You specified more key values than exist in the access set for this view.
Action:
Correct the number of key values and rerun.
B012
NO FIELDS ARE FOUND IN THE ACCESS SET - view
Reason:
There are no fields in the access set that the preprocessor can generate into CA Easytrieve® Report Generator DEFINE
statements.
Action:
Verify the access set contains the correct information and rerun.
B014
TOO MANY FIELDS IN THIS ACCESS SET - view
Reason:
There are more fields in the access set than the preprocessor can generate into CA Easytrieve® Report Generator
DEFINE statements. The maximum number of fields is set during the installation of the preprocessor.
Action:
Recompile and link edit the preprocessor with a greater number specified for the FIELDS parameter. Then rerun.
YOU MAY ONLY SELECT 50 FIELDS - view
Reason:
There are more than 50 fields selected for the view.
Action:
Reduce the number of fields in the SELECT clause and rerun.
Program Abend Messages (EZABX)
This section lists the messages and codes that can display if a program abends during the execution of CA Easytrieve®
Report Generator programs. You can use them to help correct a program error or to help CA Support in case of a system
problem.
The actual message identifier and text issued by CA Easytrieve® Report Generator can change with new product
releases, refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA Support.
EZABX000
An error has occurred in program <program name>.The following messages provide diagnostic information.
Please contact the person or persons responsible for maintaining this application. They may want to see this
information. ################## Diagnostic Information ##################
The error occurred at <hh:mm:ss> on <mm/dd/yy>.
Reason:
Your program terminated abnormally. The following messages explain the error. This message indicates the time, the day,
and the program that terminated.
Action:
976
CA Easytrieve® Report Generator 11.6
Examine the messages that follow to determine what the error is.
EZABX008
The error occurred at program statement number <nnn>.
Reason:
This message indicates which statement in your program is in error. The statement number is from the listing of your
program, not the source file.
Action:
Refer to the file with the same name as your source file and the .lst extension. Start the debugging process at the
statement with the number listed.
EZABX009
An index or subscript is out of range.
Reason:
Your program references an array using a subscript or an index that exceeds the bounds of the array.
Action:
Use the other messages to locate the line where the error occurred. Locate every array reference in that line to determine
which array reference has the incorrect subscript or index.
EZABX010
A field of an inactive file has been referenced.
Reason:
Your program references a field in a file that is not active (that is, the file was not opened or was closed and its buffer was
discarded).
Action:
Use the other messages to locate the line where the error occurred. Check each field name in that line to see if the file it
belongs to is still open.
EZABX016
The program executed the following statements most recently: nnn nnn ...
Reason:
This message lists a history of what statements were most recently executed.
Action:
You can use this history to retrace the execution of your program.
EZABX020
The program referred to the following files: File Name State Length Count Status <file_name> <state> <nnn>
<nnn> <status>
Reason:
This message lists the name of each file that was in use at the time of the error:
Field Value Description
state Open The file is open.
Active The file is not open, but a buffer was
allocated for its use.
977
CA Easytrieve® Report Generator 11.6
status Normal The file is not in an error status.
End of File The file is at end of file.
Nonunique key The file is at a non-unique key.
Duplicate key The file attempted to add a record with a
Not found duplicate key.
Locked The last record accessed was not found.
I/O Error The last record accessed was locked and
could not be obtained.
The last access to the file caused an I/O
error.
Action:
We provide this information to assist you in your debugging.
EZABX024
Interrupt trapped: <interrupt>
Reason:
An interrupt was trapped while your program was executing. Following is a list of the possible interrupts:
Hangup
Interrupt from keyboard
Quit
Illegal instruction
Floating point error
Illegal storage access
Write to a pipe with no process to read it
Alarm clock
Software termination signal
User defined signal 1
User defined signal 2
Unexpected Signal
Action:
We provide this information to assist you in your debugging.
EZABX046
A field that is NULL has been accessed.
Reason:
Your program referenced a field that is NULL.
Action:
Use the other messages to locate the line that caused the error. Examine each field on that line to determine which field
caused the error.
EZABX047
MOVE statement specifies an invalid length.
Reason:
Your program specifies an invalid length on a MOVE.
Action:
Use the other messages to locate the line that caused the error. Examine that line and the preceding lines to determine
why the length is not valid.
978
CA Easytrieve® Report Generator 11.6
EZABX048
Length of VARYING string is invalid.
Reason:
The dynamic length of a VARYING string is either greater than the string's static size or is negative.
Action:
Use the other messages to locate the line that caused the errors. Examine each VARYING field on that line to determine
which field is in error.
EZABX049
Error Check invoked with invalid parameter.
Reason:
This is an internal error.
Action:
Contact CA Support if this error is reproducible.
EZABX050
Interpreter Option not recognized: <string>
Reason:
The value of string specifies the option found on the command line. However, this option is not recognized or supported.
Action:
Remove the option from the command line and try again.
EZABX051
You did not specify the name of the file to be executed. The command format is: EZTERP [EZTERP options]
PCodeFileName [program options]
Reason:
The command line did not specify a P-Code filename.
Action:
Specify a P-Code filename on the command line and try again.
EZABX053
Command line token not recognized: <string>
Reason:
The value of string specifies the token found on the command line. However, this token is not recognized or supported.
Action:
Remove the token from the command line and try again.
EZABX054
Unable to open PCode File: <pcode file>
Reason:
The interpreter could not open the P-Code file. This can be due to a misspelled filename or a syntax error during the
compilation. This prevented the creation of a P-Code file.
Action:
Check the spelling of the P-Code file. If that is correct, check for syntax errors in the source (refer to the .lst file).
979
CA Easytrieve® Report Generator 11.6
EZABX055
The PCode File, <pcode file>, is not formatted correctly.
Reason:
The P-code file is not formatted correctly. It could be misspelled or you may have specified a non-P-code file.
Action:
Check the spelling of the P-code file. If the filename does not end in .pco, the filename is most likely not a P-code
filename.
EZABX056
The option <string> was specified more than once.
Reason:
An option (string) appears more than once in the command line.
Action:
Remove the extra occurrences of the option from the command line and try again.
EZABX057
The -t option, has a syntax error at: ... <string>
Reason:
The -t option has a syntax error.
Action:
The -t option is for internal use only.
EZABX058
The Options Table could not be read after it was opened. Check for incorrect EZOPTBL files in your current
directory and in the directories specified in EZTPATH.
Reason:
The options table was opened but could not be read. This occurs when there is a file with a name of EZOPTBL in your
path that is not an options table.
Action:
Search for files with the name of EZOPTBL in your path. Eliminate any file with that name that is not an options table. You
can create an options table with the etopload utility. For more information about creating an options table, see the CA
Easytrieve® Report Generator User Guide.
EZABX059
Internal Error Invalid option update order found.
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.
EZABX060
Illegal Call to IDMS function <function>. IDMS is not installed or the program was linked with the +OI option.
Reason:
A CA IDMS function could not be called.
Action:
980
CA Easytrieve® Report Generator 11.6
Check to see if the EZTPATH environment variable contains a path to the CA IDMS libraries. Compiling with the +OI
option bypasses the inclusion of CA IDMS libraries.
EZABX061
Illegal Call to SQL function <function>. SQL is not installed or the program was linked with the +OS option.
Reason:
An SQL function could not be called.
Action:
Check to see if the EZTPATH environment variable contains a path to the SQL libraries. Compiling with the +OS option
bypasses the inclusion of SQL libraries.
EZABX062
Illegal Call to C-ISAM function <function>. C-ISAM is not installed or the program was linked with the +OC option.
Reason:
A C-ISAM function could not be called.
Action:
Check to see if the EZTPATH environment variable contains a path to the CA Technologies ISAM libraries. Compiling with
the +OC option bypasses the inclusion of CA Technologies ISAM libraries.
Linking, Transferring and Calling Messages
This section lists the messages and codes that can display if CA Easytrieve® Report Generator encounters a problem
when linking, transferring, or calling another program. You can use them to help correct a program error or to help CA
Support in case of a system problem.
The actual message identifier and text issued by CA Easytrieve® Report Generator can change with new product
releases, refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA Support.
EZACT001
Error <error number> detected loading program <program name>
Reason:
CA Easytrieve® Report Generator failed to load your called subroutine. The errornumber indicates the cause.
Action:
For more information, see the link-editing in the CA Easytrieve® Report Generator User Guide.
EZACT002
A LINK failed: Return code <return code>. Error: <text>. Specification: <path to link>
Reason:
Your program attempted to LINK to another program and failed.
return code
Indicates why the LINK failed.
text
Explains why the attempt failed.
path to link
The path to the LINK target program.
Action:
Examine the path to the target program. The program probably is not at that path.
981
CA Easytrieve® Report Generator 11.6
EZACT005
A TRANSFER failed: Return code <return code>. Error: <text>Specification: <path to transfer>
Reason:
Your program attempted to transfer control to another program and failed.
return code
Indicates why the transfer failed.
text
Explains why the attempt failed.
path to link
The path to the target program.
Action:
Examine the path to the target program.
Utility Messages
This section lists the messages and codes that can display if CA Easytrieve® Report Generator encounters a problem
in the ETALTSEQ utility. You can use them to help correct a program error or to help CA Support in case of a system
problem.
The actual message identifier and text issued by CA Easytrieve® Report Generator can change with new product
releases, refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA Support.
EZALT001
The <string> command line option was specified more than once. The successive specifications are ignored.
Reason:
An option (string) appears more than once on the command line.
Action:
Remove all occurrences of the option after the first occurrence. Retry the command.
EZALT002
The <string> command line option is not defined.
Reason:
The string appears on the command line. However, string is not a recognized option.
Action:
Remove string from the command line. Then, retry the command.
EZALT003
Expected a literal for a single character. The violated rule: reposition_order ::= ( literal )
Reason:
The input contains a left paren that is not followed by a literal consisting of a single character.
Action:
If you are redirecting stdin to a file, review your input file. Otherwise, reissue the command and retype your corrected
input.
EZALT004
Expected a right paren. The violated rule: reposition_order ::= ( literal )
Reason:
The input contains a left paren followed by a literal that is not followed by a right paren.
982
CA Easytrieve® Report Generator 11.6
Action:
If you are redirecting stdin to a file, review your input file. Otherwise, reissue the command and retype your corrected
input.
EZALT005
Expected a literal or a string for a collating value.The violated rule: collating_value ::= character_string |
hex_string | octal_string | literal
Reason:
The input contains a reposition order followed by a reposition order.
Action:
If you are redirecting stdin to a file, review your input file. Otherwise, reissue the command and retype your corrected
input.
EZALT006
Expected a single quote for a character literal. The violated rule: A character_literal is a character surrounded by
single quotes.
Reason:
The input is missing a single quote.
Action:
If you are redirecting stdin to a file, review your input file. Otherwise, reissue the command and retype your corrected
input.
EZALT007
Expected a double quote for a character string. The violated rule: A character_string is one or more characters
surrounded by double quotes.
Reason:
The input is missing a double quote.
Action:
If you are redirecting stdin to a file, review your input file. Otherwise, reissue the command and retype your corrected
input.
EZALT008
The value of the decimal literal exceeds the capacity of single character.
Reason:
The input contains a decimal literal with a value greater than 255.
Action:
If you are redirecting stdin to a file, review your input file. Otherwise, reissue the command and retype your corrected
input.
EZALT009
The data does not conform with the syntax rules. It is not a string, a literal, parens, or a comment.
Reason:
The input contains data that does not conform to the syntax rules for defining tokens. The data is not a string, a literal,
parens, or a comment.
Action:
If you are redirecting stdin to a file, review your input file. Otherwise, reissue the command and retype your corrected
input.
983
CA Easytrieve® Report Generator 11.6
EZALT010
Expected a valid octal digit (07). Octal digits always come in triples.
Reason:
The input contains data that initially looked like an octal literal or string. Octal literals and strings begin with a 0 and are
followed by a triple (3) of digits for a literal or multiple triples for a string. The data either does not contain a complete triple
or one of the digits is not an octal digit (0-7).
Action:
If you are redirecting stdin to a file, review your input file. Otherwise, reissue the command and retype your corrected
input.
EZALT011
Expected a valid hex digit (09, af or AF). Hex digits always come in pairs.
Reason:
The input contains data that initially looked like a hex literal or string. Hex literals and strings begin with a 0x or a 0X and
are followed by a pair (2) of digits for a literal or multiple pairs for a string. The data either does not contain a complete pair
or one of the digits is not a hex digit (0-9, a-f, or A-F).
Action:
If you are redirecting stdin to a file, review your input file. Otherwise, reissue the command and retype your corrected
input.
EZALT012
Due to the error, the file will not be updated.
Reason:
The file was not updated due to errors.
Action:
Review the previous messages. Correct any errors that the messages identified and reissue the command.
EZALT013
Empty strings are not allowed.
Reason:
There is a double quote followed by a double quote in the input. To place a double quote in a string, precede it with a back
slash.
Action:
If you are redirecting stdin to a file, review your input file. Otherwise, reissue the command and retype your corrected
input.
EZALT014
File failed to open.
Reason:
The alternate collating sequence file failed to open and you are not attempting to create it.
Action:
If you specified a path on the command line, verify that the path is spelled correctly. If you did not specify a path, a file by
the name of EZTPAQTT could not be found in your current directory or in the path specified by the EZTPATH environment
variable. If you are attempting to create the file, use the -b command line option. For more information, see the Alternate
Collating Sequence Table appendix in the CA Easytrieve® Report Generator User Guide.
984
CA Easytrieve® Report Generator 11.6
Configuration Manager Messages
This section lists the messages and codes that can display if the Configuration Manager detects a problem. You can use
them to help correct a program error or to help CA Support in case of a system problem.
The actual message identifier and text issued by CA Easytrieve® Report Generator can change with new product
releases, refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA Support.
The Configuration Manager issues the following messages when it detects problems.
EZCM001
Empty Document. Error loading XML.
Reason:
The XML configuration file is empty.
Action:
Open a different XML file or create a new one from the File, New menu.
EZCM002
Error on line %d, position %n Reason: %s. Error loading XML.
Reason:
There was an error parsing the XML configuration file.
Action:
Manual editing of the xml file may be necessary to correct the error. You can use the default options table file (eztopt.xml)
or the default printer set definition file (eztpsd.xml) as an example of correct xml format. Or you can use the File – New
menu item and create new xml files that can be used as examples.
EZCM003
Failed to save XML file.
Reason:
There was an error saving the configuration file.
Action:
Check if the xml file you are trying to save already exists and is possibly read-only.
EZCM004
There was an error launching eztgenps.exe or eztgenop.exe. Please make sure the program file exists.
Reason:
You chose to generate a binary PSD or OPT file, but there was an error launching the executable.
Action:
Ensure that the program file exists in the installed bin directory.
EZCM005
eztgenps (or eztgenop) failed with error %u.
Reason:
The eztgenps.exe or eztgenop.exe failed to produce a binary output file from the xml file.
Action:
Improper XML file or a binary file that already exists and is read-only are a couple of items that can cause this error. If
neither of these seems to be the case, contact CA Support.
985
CA Easytrieve® Report Generator 11.6
EZCM006
Printer name cannot be empty
Reason:
You have not specified a printer name.
Action:
Enter a valid printer name.
EZCM007
Printer name cannot start with an asterisk
Reason:
The printer name that you entered is invalid, because it starts with an asterisk .
Action:
Enter a valid printer name.
EZCM008
Printer already exists. Please enter another name
Reason:
The printer name that you entered already exists.
Action:
Enter a new valid printer name.
EZCM009
Font number cannot be empty
Reason:
You have not specified a font number.
Action:
Enter a valid font number, between 1 and 256.
EZCM010
Font number should be between 1 and 256
Reason:
The font number that you entered is invalid; it is outside the allowable range.
Action:
Enter a valid font number, between 1 and 256.
EZCM011
Font width cannot be empty
Reason:
You have not specified a font width.
Action:
Enter a valid font width.
EZCM012
Font already exists. Please enter another number
Reason:
986
CA Easytrieve® Report Generator 11.6
The font name that you entered already exists.
Action:
Enter a new valid font name.
EZCM013
Printer description cannot start with an asterisk
Reason:
The printer description that you entered is invalid, because it starts with an asterisk .
Action:
Enter a valid printer description.
EZCM014
New Line Control field cannot be empty
Reason:
You have not specified a New Line Control value.
Action:
Enter a valid value in the New Line Control field.
EZCM015
New Page Control field cannot be empty
Reason:
You have not specified a new page control value.
Action:
Enter a valid value in the New Page Control field.
EZCM016
Printer Record Maximum Length should be greater than 132
Reason:
The maximum length that you entered for printer records is invalid.
Action:
Enter a valid value, greater than 132, in the Printer Record Maximum Length field.
EZCM017
Printer Record Maximum Bytes should be greater than 132
Reason:
The maximum bytes value that you entered for printer records is invalid.
Action:
Enter a valid value, greater than 132, in the Printer Record Maximum Bytes field.
EZCM018
Default EBCDIC/ ASCII Font cannot be empty
Reason:
You have not specified a default font for EBCDIC and ASCII.
Action:
Enter a valid value in the Default EBCDIC/ ASCII Font field.
987
CA Easytrieve® Report Generator 11.6
EZCM019
Font Height cannot be empty
Reason:
You have not specified a font height.
Action:
Enter a valid value in the Font Height field.
EZCM020
Page Height cannot be empty
Reason:
You have not specified a page height.
Action:
Enter a valid value in the Page Height field.
EZCM021
Please specify an EBCDIC font for the mixed data format
Reason:
You have not specified an EBCDIC font for the mixed data format.
Action:
Enter a valid value for the EBCDIC font.
EZCM022
Please specify a DBCS font for the mixed data format
Reason:
You have not specified a DBCS font for the mixed data format.
Action:
Enter a valid value for the DBCS font.
EZCM023
Enter a value between 0 and %i
Reason:
You have not specified a value between the 2 values above.
Action:
Enter a valid value within the specified range.
EZCM024
Enter a value between 0 and 255
Reason:
You have not specified a value within the allowable range.
Action:
Enter a valid value within the specified range.
IMS_DLI Messages
This section contains the IMS and DLI messages and codes (EZDLI).
988
CA Easytrieve® Report Generator 11.6
EZDLI001
PCB specified on FILE not found in PSB.
Reason:
The PCB list for the PSB specified in the JCL (non-CICS), or on the DLI PCB statement (CICS), does not contain the PCB
identified on the FILE statement.
• If a DBDName was specified on the FILE statement, either that DBDName is not in the PCB list, or the DBDName
occurrence, if specified, is not in the PCB list.
• If just a relative PCB number was specified on the FILE statement, the PCB list is too short to find the specified PCB.
Action:
Correct the PCB specification on the FILE statement, then rerun the program.
EZDLI002
DLI returned status code: xx on function: yyyy for record zzzzzzzz.
Reason:
During automatic input processing, a return code other than GB, GE, or blanks was returned from DLI.
Action:
See your IBM Call DL/I manual to determine the meaning and action indicated by the return code.
EZDLI003
A DL/I file update was attempted and the Site Options Table specified UPDTDLI=NO
Reason:
The global site option for CA Easytrieve® Report Generator does not permit DL/I updates.
Action:
See your system administrator about changing the site option to permit DL/I updates.
Program Abend Messages (EZEIP)
This section lists the messages and codes that can display if a program abends during the execution of CA Easytrieve®
Report Generator programs. You can use them to help correct a program error or to help CA Support in case of a system
problem.
The actual message identifier and text issued by CA Easytrieve® Report Generator can change with new product
releases, refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA Support.
EZEIP001
An internal <opcode> instruction returned the following error: <text>
Reason:
The opcode can be ADD, COMPARE, DIVIDE, MULTIPLY, NEGATE, SHIFT, or SUBTRACT. The supplemental text
explains the type of error that occurred:
• Result of the operation exceeded the maximum number of 30 digits allowed.
• The divisor operand is zero.
• High order digits were truncated.
• Number to convert contained an invalid digit or an invalid sign.
• An invalid argument was detected.
• A negative value was loaded from or stored into a non-quantitative number.
Action:
989
CA Easytrieve® Report Generator 11.6
Use the other messages to locate the line where the error occurred. Examine each field and operation on that line to
determine which field caused the error.
EZEIP003
The following error occurred while converting a field to PACKED DECIMAL: <text>
Reason:
The supplemental text explains the type of error that occurred:
• Result of the operation exceeded the maximum number of 30 digits allowed.
• The divisor operand is zero.
• High order digits were truncated.
• Number to convert contained an invalid digit or an invalid sign.
• An invalid argument was detected.
• A negative value was loaded from or stored into a non-quantitative number.
Action:
Use the other messages to locate the line where the error occurred. Examine each field and operation on that line to
determine which field caused the error.
EZEIP004
Unexpected internal data type, <data type>, encountered.
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.
EZEIP005
The following error occurred while executing an internal branch: <text>
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.
EZEIP006
The internal interface has detected that the internal code structure has been corrupted.
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.
EZEIP007
Internal literal pool area too small.
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.
990
CA Easytrieve® Report Generator 11.6
EZEIP011
The internal interface read past the end of the internal code.
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.
EZEIP015
The following error occurred while converting a PACKED DECIMAL field to BINARY: <text>
Reason:
The supplemental text explains the type of error that occurred:
• Result of the operation exceeded the maximum number of 30 digits allowed.
• The divisor operand is zero.
• High order digits were truncated.
• Number to convert contained an invalid digit or an invalid sign.
• An invalid argument was detected.
• A negative value was loaded from or stored into a nonquantitative number.
Action:
Use the other messages to locate the line where the error occurred. Examine each field and operation on that line to
determine which field caused the error.
EZEIP017
Data found on an internal expression stack was not of the expected type.
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.
EZEIP018
An internally defined stack frame is too small. The next entry will overflow the defined limits. This often means
your program contains a recursive call. Check for recursive procedure calls or activity executions.
Reason:
This message often indicates a recursive call between your CA Easytrieve® Report Generator procedures.
Action:
The trace table can be useful in tracking recursive calls.
EZEIP019
The expression stack does not have enough entries to perform the attempted operation.
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.
991
CA Easytrieve® Report Generator 11.6
EZEIP021
The internal operation being requested is undefined.
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.
EZEIP022
The following error occurred while converting a BINARY field to PACKED DECIMAL: <text>
Reason:
The supplemental text explains the type of error that occurred:
• Result of the operation exceeded the maximum number of 30 digits allowed.
• The divisor operand is zero.
• High order digits were truncated.
• Number to convert contained an invalid digit or an invalid sign.
• An invalid argument was detected.
• A negative value was loaded from or stored into a nonquantitative number.
Action:
Use the other messages to locate the line where the error occurred. Examine each field and operation on that line to
determine which field caused the error.
EZEIP023
Length of mask specified is greater than the length of the output field specified.
Reason:
The number of digit selectors in the mask may be less than the number of significant digits in the corresponding field.
Action:
Use the other messages to locate the line in error. Examine each field on that line for a mask that does not have enough
digit selectors for the value the field can hold.
EZEIP024
Following error occurred while converting a field to ZONED DECIMAL for edit mask processing: <text>
Reason:
The supplemental text explains the type of error that occurred:
• Result of the operation exceeded the maximum number of 30 digits allowed.
• The divisor operand is zero.
• High order digits were truncated.
• Number to convert contained an invalid digit or an invalid sign.
• An invalid argument was detected.
• A negative value was loaded from or stored into a nonquantitative number.
Action:
Use the other messages to locate the line where the error occurred. Examine each field and operation on that line to
determine which field caused the error.
992
CA Easytrieve® Report Generator 11.6
EZEIP025
Following error occurred while storing a PACKED DECIMAL field into another field type: < text >
Reason:
The supplemental text explains the type of error that occurred:
• Result of the operation exceeded the maximum number of 30 digits allowed.
• The divisor operand is zero.
• High order digits were truncated.
• Number to convert contained an invalid digit or an invalid sign.
• An invalid argument was detected.
• A negative value was loaded from or stored into a nonquantitative number.
Action:
Use the other messages to locate the line where the error occurred. Examine each field and operation on that line to
determine which field caused the error.
EZEIP028
A recursive call was made to a procedure.
Reason:
CA Easytrieve® Report Generator does not allow a procedure to call itself directly or indirectly.
Action:
Use the other messages to determine the line in error. The flow table can be useful in determining where the recursion
begins.
EZEIP992
Internal PCode offset: <nnn>
Reason:
This information is useful to CA Support.
Action:
None
EZEIP997
Interpreter terminated abnormally due to above error(s).
Reason:
This message is informational only.
Action:
None
IDMS Messages
This section contains the CA IDMS messages and codes (EZIDM).
EZIDM001
An error occurred loading program xxxxxxxx.
Reason:
The specified CA IDMS interface program could not be found.
Action:
993
CA Easytrieve® Report Generator 11.6
See your CA Easytrieve® Report Generator system administrator to verify that the CA IDMS interface was correctly
installed.
EZIDM002
Unexpected IDMS error encountered: xxxx.
Reason:
During automatic processing, CA Easytrieve® Report Generator encountered an error status from CA IDMS that was not
expected.
Action:
See your CA IDMS documentation for information about the specified status code.
EZIDM003
An IDMS file update was attempted and the Site Options table specified UPDTIDM=NO.
Reason:
An update was attempted to an IDMS file that was not permitted.
Action:
Either change the program to not update the IDMS file or change the Site Options table to permit updates to IDMS files.
File I_O Messages
This section lists the messages and codes that can display if CA Easytrieve® Report Generator encounters an
unrecoverable file I/O error. You can use them to help correct a program error or to help CA Support in case of a system
problem.
The actual message identifier and text issued by CA Easytrieve® Report Generator can change with new product
releases, refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA Support.
EZIOE001
Length of print line exceeds LINESIZE for printer <printer name>.
Reason:
The program attempted to print a line whose length was greater than the LINESIZE of the printer. This error usually
occurs for the SYSPRINT file when the STDOUT entry in the options table has a LINESIZE that is less than the line size
defined when the program was compiled. If the print line is part of a report, the line size was obtained from the LINESIZE
parameter of the REPORT statement. If the print line is not part of a report, the line size was obtained from the LINESIZE
entry in the options table.
Action:
Change the length of the print line.
EZIOE002
This error can occur for multiple reasons. This article describes the various text messages that can be displayed.
Error opening file: <file name> Path: <path name> <text>
Reason:
CA Easytrieve Report Generator could not open the file specified. The supplemental text states the reason.
Action:
None.
Operating System does not support either this type of file or its device type.
Reason:
The file is defined with a type or a device type that is not supported in this operation system.
Action:
994
CA Easytrieve® Report Generator 11.6
See the Language Reference section for supported file types and device types. Specify one that is supported and try
again.
The attempt to open the file failed.
Reason:
CA Easytrieve Report Generator issued a request to the operating environment to open the data set associated with the
specified file. The operating environment returned an error indicating that the open failed.
Action:
None.
The file is not active.
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.
SYSNAME length exceeds maximum.
Reason:
The length of the SYSNAME field exceeds the maximum allowed by the operating environment.
If the FILE statement specifies either SYSNAME fieldname or SYSNAME literal, then the length of fieldname or literal
exceeds the maximum length acceptable to the environment.
If the FILE statement did not specify the SYSNAME parameter, then CA Easytrieve® Report Generator builds a default
SYSNAME parameter of the form SYSNAME filename. The number of characters in the resulting literal exceeds the
maximum number acceptable to the environment.
Action:
Correct the size of SYSNAME.
SYSNAME is invalid.
Reason:
The environment could not find the file at the path SYSNAME specified.
Action:
Check the spelling in the SYSNAME parameter on the FILE statement. If the path is relative to the current directory, the
current directory may be different from where the program was developed, which can cause the problem.
The logical record length could not be determined.
Reason:
The maximum record length for this file was not specified.
The FILE statement for this virtual file did not specify the record length. CA Easytrieve® Report Generator determines the
record length for a virtual file in the following way:
• The record length specified by the record format parameter, if it is coded.
• The value specified by the WORKAREA parameter, if it is coded.
• The number of bytes required to store all fields defined following the FILE statement, if any.
Action:
Specify the maximum record length for the file.
Virtual file was not previously created.
Reason:
The FILE statement for the file specifies the VIRTUAL parameter. The current activity accesses the file for input
processing. The file was never created.
A VIRTUAL file must be opened for output processing before it can be opened for input processing. Possible reasons for
not creating the file are:
• This is the first activity that refers to the VIRTUAL file.
• The activity that creates the VIRTUAL file was not executed.
• The VIRTUAL file was created correctly. However, more than one subsequent activity refers to the file. CA Easytrieve®
Report Generator deleted the file after the first reference. In this case, the FILE statement must specify the RETAIN
parameter.
995
CA Easytrieve® Report Generator 11.6
This condition can also happen in a single activity if the activity contains a CLOSE statement that refers to the VIRTUAL
file. The CLOSE statement deletes the file unless the FILE statement specifies the RETAIN parameter.
Action:
Create the file.
The file type could not be determined from the file descriptor
Reason:
This indexed file did not have a valid file descriptor provided so CA Easytrieve® Report Generator could not determine
which access method to use to process the file.
Action:
Provide a valid file descriptor. For more information, see the Execute a Program article in the CA Easytrieve® Report
Generator Using section.
The log file for this file could not be opened
Reason:
An attempt was made to create or update a C-ISAM INDEXED file and a log file could not be opened.
Action:
Check that CISAMLOG environment variable is set and that it names an existing log file. For more information, see the
Execute a Program article in the CA Easytrieve® Report Generator Using section.
EZIOE003
This error can occur for multiple reasons. This article describes the various text messages that can be displayed.
Error processing file <file name>. <text>
Reason:
CA Easytrieve Report Generator could not process the specified file. Supplemental text states the reason.
Action:
None.
File referenced in FROM parameter is not active.
Reason:
The file specified in the FROM parameter does not have a record associated with it.
This status results from one of the following:
• The file specified in the FROM parameter is not referenced in any other input/output statements in this activity.
• The DEFER parameter was specified for the file referenced in the FROM parameter and no input/output statements
have yet executed for this file.
Action:
Resolve the problem and try again.
GET statement follows a RELEASE statement.
Reason:
A GET statement was executed, but the previous statement issued for this file was a RELEASE statement. The RELEASE
statement loses position for sequential retrieval.
Action:
A POINT or a READ statement must execute before a GET statement can execute.
No records are locked.
Reason:
A WRITE UPDATE or a WRITE DELETE statement executed and the current record is not locked.
This error can be caused by one of the following:
996
CA Easytrieve® Report Generator 11.6
• No record was retrieved. A record must be retrieved with a READ or a GET statement before it can be updated or
deleted.
• The GET or READ statement that retrieved the record specified the NOHOLD parameter.
• A WRITE UPDATE or a WRITE DELETE statement was previously executed for the current record.
• A RELEASE statement was executed for this file. The RELEASE statement unlocks all locked records.
• A COMMIT statement was executed. Terminal input/output and endof-activity processing can cause an implied
COMMIT statement to execute. The COMMIT statement unlocks all locked records.
Action:
Resolve the problem and try again.
Access to the file by the child activity conflicts with how the parent activity opened it.
Reason:
The parent activity opened the file with a specific type of access. The child activity must access the file in a way that
conflicts with the parent. For example, the child activity attempted to create the file after the parent opened the file to read
it.
Action:
Resolve the problem and try again.
Invalid request passed to input/output statement handler.
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.
GET statement issued after endoffile reached.
Reason:
A GET was executed and there is no current record for this file. The previous GET statement for this file detected
endoffile.
Action:
Test the file status to determine if a GET reached end-of-file.
Position for sequential insertion has not been established.
Reason:
A PUT to a relative file was executed without providing a starting record number.
Action:
A PUT to a relative file must be preceded by:
• An OPEN statement
• A POINT statement that specifies the GE parameter
• Another PUT statement
RECORD-LENGTH exceeds the maximum record length of the file. Reason:The record length defined for the
program FILE statement is larger than the LRECL defined for the associated DD statement in the JCL.
Action:Change the incorrect length value. Both length values must be the same.
EZIOE004
This error can occur for multiple reasons. This article describes the various text messages that can be displayed.
Logical I/O error on file <file name> <text>
Reason:
CA Easytrieve® Report Generator could not process the file specified because of a logical I/O error. These errors occurred
for an I/O statement where the STATUS parameter was not specified. If you specified STATUS, these errors are reflected
997
CA Easytrieve® Report Generator 11.6
in the system-defined field FILESTATUS for the program to handle. When this message is issued, supplemental text
states the reason.
Action:
None.
Duplicate record inserted.
Reason:
This error condition indicates that an attempt was made to store a record with a duplicate key or there is a duplicate
record for an alternate index with the unique key option.
This condition can occur following a PUT statement for a RELATIVE file. It indicates that the slot designated by the
relative record number already contains a record (the slot is not empty).
Action:
Correct the logic in your program. You may want to use the STATUS parameter to detect this situation.
Requested record not found.
Reason:
The record designated by the KEY parameter is not present in the file.
This condition can occur following a READ statement or a POINT statement for a RELATIVE file. It indicates that the slot
designated by the relative record number is empty.
Action:
Correct the logic in your program. Use the STATUS parameter to detect this situation.
Record is locked.
Reason:
An attempt was made to access or update a record that has a lock placed on it by another process.
Action:
Correct the logic in your program. You may want to use the STATUS parameter to detect this situation.
Error indicator returned by access method.
Reason:
The access method routines used to access this file detected a logical or physical error condition. The condition detected
was not one of the conditions listed above.
Action:
Correct the logic in your program. You can use the STATUS parameter to detect this situation.
EZIOE005
The file exit for <file name> either did not link or did not load.
Reason:
CA Easytrieve® Report Generator could not locate an entry point for the exit program.
Action:
Verify that your library contains the exit program.
EZIOE007
SQL DBMS status code is <error code>.
Reason:
The SQL DBMS detected an error during the processing of the statement in error. The value of error code is the contents
of the SQLCODE field of the SQL communications area.
Action:
See the appropriate DBMS guide for the meaning of the error code.
EZIOE008
ISAM return code is <return code> with error code of <error code>.
Reason:
998
CA Easytrieve® Report Generator 11.6
The indexed access method detected an error.
Action:
See the appropriate access method guide for the meaning of return code and error code.
EZIOE009
<access method> return code is <return code>.
Reason:
The access method detected an error.
Action:
See the appropriate access method guide for the meaning of return code and error code. When the access method is
RFS the following codes are possible:
Code Meaning
0 No error, operation successful
2 OK duplicate indexed key
4 Read. LRECL does not conform to attribute.
5 Open. Optional file is not present.
7 Open/Close. Tape specification error.
10 End of file (46 if past EOF)
14 Read. Relative record number is too large.
21 Index sequence error
22 Duplicate key
23 Non existent record
24 Disk full (if not SEQUENTIAL)
30 Permanent error, no further info
34 Disk full (if SEQUENTIAL)
35 Open Input or I-O on non-present file
37 Open spec. Error on present file
38 Open on locked file
39 Open. Conflicting attributes
41 Open for an opened file
42 Close for not opened file
43 Rewrite/Delete without prior Read
44 Write/Rewrite. LRECL boundary violation
46 Read. Preceding READ or START failed.
47 Read/Start. Not opened in input or I-O mode.
48 Write. File not in OUTPUT or I-O mode.
49 Rewrite/Delete. File not opened in I-O mode.
91 Access denied
92 Open. Environment variable not set.
96 Insufficient storage
97 Critical error
107 OPEN for NC file (9A)
999
CA Easytrieve® Report Generator 11.6
108 OPEN for JC file (9B)
109 OPEN for JCR file (9C)
110 Dead lock (9D)
115 Invalid operation on logged file (9I)
118 Record or file is locked (9L)
119 Maximum locks exceeded (9L)
124 Roll back forced (9R)
128 Wrong file version (9V)
EZIOE011
The out-of-sequence TABLE ARG is:
Reason:
The file must be in ARG sequence and cannot contain any duplicates.
Action:
Sort the file in ARG sequence.
System Initialization Messages
This section lists the messages and codes that can display if the System Initialization fails. You can use them to help
correct a program error or to help CA Support in case of a system problem.
The actual message identifier and text issued by CA Easytrieve® Report Generator can change with new product
releases, refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA Support.
The Configuration Manager issues the following messages when it detects problems.
EZKX0001
CA EASYTRIEVE INITIALIZATION FAILED AT XX:XX:XX ON XX/XX/XX.
Reason:
The initialization process encountered a major problem that prohibits execution. This message if normally followed with a
EKxx abend code. See
EZSRT013
(see page ).
Action:
Consult the abend code for assistance in determining the underlying cause of the problem.
EZKX0004
CA EASYTRIEVE PROGRAM XXXXXXX CANNOT BE LOADED.
Reason:
An important system component failed to load.
Action:
Contact CA Support.
EZKX0012
HEAP MANAGER DOMAIN INITIALIZATION FAILURE.
Reason:
The memory heap manager failed to initialize.
Action:
1000
CA Easytrieve® Report Generator 11.6
Contact CA Support.
EZKX0013
THE CA EASYTRIEVE RESPONSE CODE IS XXXXXXXX.
Reason:
This message accompanies one of the other EZKX messages and provides a response code.
Action:
Contact CA Support.
EZKX0014
UNABLE TO CONSTRUCT OPTION TABLES.
Reason:
The CA Easytrieve® Report Generator Option Module failed to load.
Action:
Check that the EZTINI file points to the correct data set.
EZKX0016
OPTIONS TABLE LOADER RESPONSE CODE IS XX(XXXX).
Reason:
This message accompanies one of the other EZKX messages and provides a response code.
Action:
If you cannot determine the cause of the previous error message, contact CA Support.
EZKX0017
CA EASYTRIEVE CA90'S COMPONENT IS MISSING.
Reason:
LMP licensing for CA Common Services (CCS, formerly known as CA90) is not available.
Action:
Check licensing components. Contact Broadcom Support.
EZKX0060
LOAD FAILURE WAS DUE TO ABEND SXXX-RC.
Reason:
This message accompanies one of the other EZKX messages and provides a response code.
Action:
Contact CA Support.
EZKX0061
VERSION OF COMPILER GREATER THAN VERSION OF RUNTIME SUPPORT ROUTINES.
Reason:
The CA Easytrieve® Report Generator runtime system is not up to date with the compiler used to compile the program
being executed.
Action:
Ensure that the runtime system being used is current. It must be at least at the same version of the compiler module used.
1001
CA Easytrieve® Report Generator 11.6
ETOPLOAD Utility Messages
This section lists the messages and codes that can display if CA Easytrieve® Report Generator encounters a problem
in the ETOPLOAD utility. You can use them to help correct a program error or to help CA Support in case of a system
problem.
The actual message identifier and text issued by CA Easytrieve® Report Generator can change with new product
releases, refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA Support.
EZOPT001
The line above contains unrecognizable data.
Reason:
The previous line contains data that is meaningless to the program.
Action:
Review the syntax. Correct the errors, such as spelling or using the wrong parameters for a keyword. Reissue the
command.
EZOPT002
Due to the error, the file will not be updated.
Reason:
The file was not updated due to errors.
Action:
Use the other messages to determine the errors and correct them. Reissue the command.
EZOPT003
The <string> command line option was specified more than once. The successive specifications are ignored.
Reason:
The command contains more than one occurrence of the option string.
Action:
The extra options were ignored. No action required.
EZOPT004
The <string> command line option is not defined.
Reason:
The command contains a string that is not recognized.
Action:
Remove or correct the string. Reissue the command.
EZOPT005
File failed to open.
Reason:
The options table file was not opened and you are not attempting to create it.
Action:
If you specified a path on the command line, verify that the path is spelled correctly. If you did not specify a path, a file by
the name of EZOPTBL could not be found in your current directory or in the path specified by the EZTPATH environment
variable. If you are attempting to create the file, use the -b command line option. For more information, see the CA
Easytrieve® Report Generator Installation Guide.
1002
CA Easytrieve® Report Generator 11.6
EZOPT008
SKIP is limited to 255 or PAGESZE, whichever is less.
Reason:
The value of SKIP is not less than or equal to the lesser of 255 and PAGESZE.
Action:
Check your input file for the definition of SKIP and PAGESZE. Correct the values so the relationship defined in this
message is true. Reissue the command.
EZOPT009
TITLSKP is limited to 255 or PAGESZE, whichever is less.
Reason:
The value of TITLSKP is not less than or equal to the lesser of 255 and PAGESZE.
Action:
Check your input file for the definition of TITLSKP and PAGESZE. Correct the values so the relationship defined in this
message is true. Reissue the command.
EZOPT010
SPACE cannot exceed LINESIZ 2.
Reason:
The value of SPACE is greater than the value of LINESIZ - 2.
Action:
Check your input file for the definition of SPACE and LINESIZ. Correct the values so the relationship defined in this
message is true. Reissue the command.
EZOPT011
SCANCOLS must be less than SCANCOLE.
Reason:
The value of SCANCOLS is not less than SCANCOLE.
Action:
Check your input file for the definition of SCANCOLS and SCANCOLE. Correct the values so the relationship defined in
this message is true. Reissue the command.
EZOPT012
Line has extra data.
Reason:
There is more data after the keyword and its value.
Action:
Remove the extra data from the line. Reissue the command.
EZOPT013
Value is out of bounds. The lower bound is <nnn>. The upper bound is <nnn>.
Reason:
The value is not between its minimum and its maximum values (inclusive).
Action:
Correct the value in the input and reissue the command.
1003
CA Easytrieve® Report Generator 11.6
EZOPT014
No value found for the keyword.
Reason:
A value was not found for a keyword. You must type a keyword and its value on the same line.
Action:
If you omitted the value, include a value. If the value appears on another line, move the value to correct line. Reissue the
command.
EZOPT015
Value has more than <nnn> characters.
Reason:
The value has more than the maximum number of characters allowed for the keyword.
Action:
Shorten the value to fit within the maximum. Reissue the command.
EZOPT016
The value is not a 'Y' or an 'N'.
Reason:
The possible values for the keyword are Y and N. The value is not Y or N.
Action:
Correct the value in the input. Reissue the command.
EZOPT017
The value is not in the list of valid choices.
Reason:
The value is not in the list of valid choices for the keyword.
Action:
Review the documentation for the list of valid choices. Correct the input and reissue the command.
EZOPT018
The valid options are <string>, ...
Reason:
This message appears with EZOPT017 and lists the valid choices for the keyword.
Action:
None
EZOPT020
The usermask id is not a single character from 'A' to 'Y'.
Reason:
The usermask identifier must be a single character between A and Y.
Action:
Correct the input and reissue the command.
EZOPT021
The mask is missing.
1004
CA Easytrieve® Report Generator 11.6
Reason:
The mask for a usermask definition is not on the same line as the definition.
Action:
If the mask is omitted, include one. If the mask is on a separate line, move the mask to the correct line.
System Termination Message
This section contains the system termination message.
EZSHT101
System Termination
This message is displayed whenever a serious error occurs that might indicate an internal CA Easytrieve® Report
Generator problem. If the problem reoccurs after recycling the environment (CICS, CMS, or TSO) have a copy of this
screen and the program causing this message ready when you call CA Support.
Reason:
CA Easytrieve® Report Generator encountered an unrecoverable error when executing your program. This message is
normally preceded by one or more of the messages listed in this section.
Action:
You should attempt to recycle the operating environment and retest the program in order to determine if the problem is
being caused by CA Easytrieve® Report Generator.
• For the CICS/VS operating environment, your system administrator should restart the CA Easytrieve® Report
Generator runtime system. Recycling can also require restarting the CICS system.
• For the MVS/TSO operating environment, you should log off your TSO session and log back on.
For the CMS/OS operating environment, you should re-IPL your CMS machine.
SQL Messages
This section lists the messages and codes that can display if CA Easytrieve® Report Generator encounters a problem
accessing your SQL database. You can use them to help correct a program error or to help CA Support in case of a
system problem.
The actual message identifier and text issued by CA Easytrieve® Report Generator can change with new product
releases, refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA Support.
The following codes indicate an unrecoverable error that occurred during an SQL operation.
EZSQL001
An error occurred loading program xxxxxxxx.
Reason:
The specified CA Easytrieve® Report Generator SQL interface program could not be found.
Action:
Check with your CA Easytrieve® Report Generator system administrator to make sure that the SQL interface is properly
installed.
EZSQL002
SQL program xxxxxxxx ended with return code xxxx.
Reason:
The specified CA Easytrieve® Report Generator SQL interface program terminated abnormally with the specified return
code. EZSQL003 follows this message.
Action:
See the appropriate SQL DBMS guide for the meaning of the error code.
1005
CA Easytrieve® Report Generator 11.6
EZSQL003
SQL error code xxxx, xxxxxxxx.
Reason:
The CA Easytrieve® Report Generator SQL interface terminated with the specified error code. The brief explanation
follows the error code. EZSQL002 precedes this message.
Action:
If you cannot detect the cause of the problem from the message, contact CA Support.
EZSQL004
SQL statement not executed; SQL interface not initialized.
Reason:
A request to execute an SQL statement was made when the CA Easytrieve® Report Generator SQL interface was not
initialized.
Action:
This is an internal error. Contact CA Support.
EZSQL005
SQL select not executed before xxxxxxxx statement.
Reason:
The specified FETCH, UPDATE, or DELETE statement was not preceded by a SELECT or OPEN statement. You closed
or released your file after the SELECT or OPEN was executed and before the specified FETCH, UPDATE, or DELETE.
Action:
Either move the CLOSE or RELEASE statement or execute an OPEN or SELECT statement before the specified
statement.
Sort Messages
This section lists the messages and codes that can display if CA Easytrieve® Report Generator detects an error sorting
records. You can use them to help correct a program error or to help CA Support in case of a system problem.
The actual message identifier and text issued by CA Easytrieve® Report Generator can change with new product
releases, refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA Support.
The following codes indicate an unrecoverable error that occurred during a sort operation.
EZSRT008
The input (E15) for the SORT requested an abort. <reason code>.
Reason:
A problem was detected while giving records to the SORT.
Action:
Review the preceding messages for the cause of the problem.
EZSRT009
The output (E35) for the SORT requested an abort. <reason code>
Reason:
A problem was detected while getting ordered records from the SORT.
Action:
Review the preceding messages for the cause of the problem.
1006
CA Easytrieve® Report Generator 11.6
EZSRT013
The sort initialization routine requested an abort. <text>
Reason:
This is an internal error, where text can be any of the following:
• Invoked the sort without initializing the sort.
• Invalid processing request.
• Invalid data type for a key.
• Error in #EVAL comparison.
• Total core must be supplied.
• Record Length must be supplied.
• Pointer to key information is null.
• Record format is not supported.
• Number of keys must be supplied.
• Invalid command type.
• Key length is unintelligible.
• Ascending or Descending indicator is invalid.
• Key information does not agree with # of keys.
• Record length is unacceptable.
• Data in key field does not agree with data type.
• Insufficient core for sort.
• Invalid record count.
• Input procedure failure.
• Merge procedure failure.
• Key construction failure.
• Initialization procedure failure.
• GetBuff procedure failure.
• SORT procedure failure.
1007
CA Easytrieve® Report Generator 11.6
• Put scratch error.
• Get scratch error.
• Delete scratch error.
• Alternate Sequence pointer is NULL.
• Logic error in INPT1400.
• Check Count discrepancy.
• Buffer Check error.
• Error returned by external sort.
• Stack Overflow Error.
• Records in not equals records out.
Action:
If you can reproduce this error, contact CA Support
Compiler Messages
This section lists the warning and error messages that can display if the compiler encounters a problem. You can use
them to help correct a program error or to help CA Support in case of a system problem.
The actual message identifier and text issued by CA Easytrieve Report Generator can change with new product releases,
refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA Support.
EZTC0744E
File not sequential: detail_text
Reason:
CA Easytrieve Report Generator cannot process the file because it is not physically sequential.
detail_text
Describes the specific problem. Valid detail text is:
1. ddname+nnn PDS with no member name
2. ddname+nnn DD DUMMY not allowed
3. ddname+nnn DD is missing
4. ddname+nnn Unacceptable DSORG
5. ddname+nnn Unacceptable RECFM
6. ddname+nnn LRECL exceeds nnnn bytes
7. ddname+nnn Data set is not found on volume
8. ddname+nnn Member name memname not found in library
9. ddname+nnn SWAREQ error for SIOT
10. ddname+nnn SWAREQ error for JFCB
11. ddname+nnn OBTAIN error for DSCB
12. ddname+nnn Dynamic allocation failed
13. ddname+nnn Dynamic unallocation failed
14. ddname+nnn OPEN failed
15. ddname+nnn DESERV GET_ALL failed
16. ddname+nnn Unexpected condition encountered
ddname
Indicates the name of the DD with the problem.
1008
CA Easytrieve® Report Generator 11.6
nnn
Indicates the concatenation sequence number. The number sequence begins at 000.
nnnn
Indicates the number of bytes.
memname
Indicates the member name.
Action:
Perform the action for the corresponding detail text in the previous list.
1. The DD statement has the name of a PDS or PDSE with no member name coded. Correct the data set name or add a
member name for the input and rerun.
2. DD DUMMY is unacceptable in this context. Remove DD DUMMY and rerun.
3. Add the missing DD statement and rerun.
4. The DSORG of this DD cannot be processed sequentially. Correct the DSORG and rerun.
5. The RECFM of this data set cannot be processed sequentially. Correct the RECFM and rerun.
6. The LRECL exceeds the maximum for this processing context. Correct the LRECL and rerun.
7. The data set does not exist. Either it is cataloged to this volume, or UNIT and VOL=SER= was coded and the data set
does not exist. Correct the problem and rerun.
8. The DD specifies a PDS or PDSE with a member name coded but that member does not exist. Correct the DD and
rerun.
NOTE
For detail text numbers 9 through 16, gather all related output and contact Broadcom Support for assistance.
Runtime Error Check Codes
EBND
Code Category:
Runtime Error Check
Reason:
Index or subscript exceeded boundaries.
EBSN
Code Category:
Runtime Error Check
Reason:
Insufficient storage in region to satisfy request.
Runtime Code Generator Codes
ECGO
Code Category:
Runtime Code Generator
Reason:
1009
CA Easytrieve® Report Generator 11.6
Invalid request passed to code generator.
IMS_DLI Interface Codes
EDLI
Code Category:
IMS/DLI Interface
Reason:
Unrecoverable error during IMS/DLI processing.
Dynamic Loader Codes
EDSN
Code Category:
Dynamic Loader
Reason:
Module not found (CICS only).
EDSO
Code Category:
Dynamic Loader
Reason:
Dynamic load table overflowed.
Dynamic Segment Manager Codes
EDSA
Code Category:
Dynamic Segment Manager
Reason:
Segment already defined.
EDSO0
Code Category:
Dynamic Segment Manager
Reason:
Internal procedure stack overflow.
EDSS
Code Category:
Dynamic Segment Manager
Reason:
Segment not defined.
1010
CA Easytrieve® Report Generator 11.6
EDST
Code Category:
Dynamic Segment Manager
Reason:
Invalid Segment.
EDSX
Code Category:
Dynamic Segment Manager
Reason:
Unable to expand segment table.
Heap Manager Codes
EBND0
Code Category:
Heap Manager
Reason:
Bounds check failure.
EBSL
Code Category:
Heap Manager
Reason:
GETMAIN length error.
EFLD
Code Category:
Heap Manager
Reason:
Field check error.
EFML
Code Category:
Heap Manager
Reason:
Invalid MOVE length.
EFNF
Code Category:
Heap Manager
Reason:
Null check failure.
1011
CA Easytrieve® Report Generator 11.6
EFVL
Code Category:
Heap Manager
Reason:
Invalid VARCHAR length.
EHMD
Code Category:
Heap Manager
Reason:
Invalid domain ID (usually means that a Heap Tag is invalid).
EHMF
Code Category:
Heap Manager
Reason:
Invalid freemain request.
EHMH
Code Category:
Heap Manager
Reason:
Invalid heap tag.
EHMI
Code Category:
Heap Manager
Reason:
Invalid storage control request.
EHML
Code Category:
Heap Manager
Reason:
Length error.
EHMN
Code Category:
Heap Manager
Reason:
No storage available.
EHMO
Code Category:
1012
CA Easytrieve® Report Generator 11.6
Heap Manager
Reason:
Internal procedure stack overflow.
EHMQ
Code Category:
Heap Manager
Reason:
Invalid FAD chain.
EHMR
Code Category:
Heap Manager
Reason:
Error reading temporary storage record.
EHMV
Code Category:
Heap Manager
Reason:
Storage overrun detected.
EHMW
Code Category:
Heap Manager
Reason:
Error writing temporary storage record.
EHMX
Code Category:
Heap Manager
Reason:
Error resolving relocatable pointer.
Input_Output Statement Handler Codes
EIO0
Code Category:
Input/Output Statement Handler
Reason:
Invalid request passed to input/output statement handler.
EIO1
Code Category:
1013
CA Easytrieve® Report Generator 11.6
Input/Output Statement Handler
Reason:
An input/output statement referenced a file that had not been activated.
EIO2
Code Category:
Input/Output Statement Handler
Reason:
Load for access method interface routine failed.
EIO3
Code Category:
Input/Output Statement Handler
Reason:
Insufficient main storage.
EIO4
Code Category:
Input/Output Statement Handler
Reason:
Attempt to deactivate a file not on the active file list for current activity.
EIO5
Code Category:
Input/Output Statement Handler
Reason:
File referenced in an illegal statement.
EIO6
Code Category:
Input/Output Statement Handler
Reason:
Invalid file manager call issued. Feature not supported or not implemented.
EIO9
Code Category:
Input/Output Statement Handler
Reason:
Presentation manager error while browsing a printer file.
EIOA
Code Category:
Input/Output Statement Handler
Reason:
File control validity check failed.
1014
CA Easytrieve® Report Generator 11.6
EIDA
Code Category:
Input/Output Statement Handler
Reason:
IDMS could not be found.
EIOX
Code Category:
Input/Output Statement Handler
Reason:
Unexpected response received for a CICS/VS command.
Activity Management Codes
EJA1
Code Category:
Activity Management
Reason:
Insufficient storage.
System Spool Printer Interface Module Codes
EJSO
Code Category:
System Spool Printer Interface Module
Reason:
Spool file open error.
EJSC
Code Category:
System Spool Printer Interface Module
Reason:
Spool file close error.
EJSW
Code Category:
System Spool Printer Interface Module
Reason:
Spool file write error.
Task Execution Control Program Codes
1015
CA Easytrieve® Report Generator 11.6
EKX0
Code Category:
Task Execution Control Program
Reason:
Application request not understood by ETKXCON.
EKX1
Code Category:
Task Execution Control Program
Reason:
CA Easytrieve® Report Generator termination in progress.
EKX2
Code Category:
Task Execution Control Program
Reason:
ETKXCON unable to load runtime system modules.
EKX5
Code Category:
Task Execution Control Program
Reason:
Error reading/writing PLA to auxiliary storage.
EKS6
Code Category:
Task Execution Control Program
Reason:
Resume program version validation error. (Resume program is not the same as the program that quiesced.)
EKX7
Code Category:
Task Execution Control Program
Reason:
Quiesce requested by linked to program.
EKX8
Code Category
Task Execution Control Program
Reason:
Internal stack overflow.
EKX9
Code Category:
1016
CA Easytrieve® Report Generator 11.6
Task Execution Control Program
Reason:
Version mismatch between compiler and runtime system.
EKXB
Code Category:
Task Execution Control Program
Reason:
Unable to load runtime anchor module (TSO only).
EKXC
Code Category:
Task Execution Control Program
Reason:
Error reading options from the EZOPTBL data set (TSO/CMS only).
EKXE
Code Category:
Task Execution Control Program
Reason:
Error initializing the heap global domain (TSO/CMS only).
EKXF
Code Category:
Task Execution Control Program
Reason:
A CA90 component is missing (CICS/TSO).
EKXG
Code Category:
Task Execution Control Program
Reason:
Runtime not authorized to run in Batch (nonTSO) mode.
EKXH
Code Category:
Task Execution Control Program
Reason:
Error writing PLA to auxiliary storage (CICS only).
Task Management Program Codes
EKX3
Code Category:
1017
CA Easytrieve® Report Generator 11.6
Task Management Program
Reason:
Indicates an error initializing heap local domain.
EKX4
Code Category:
Task Management Program
Reason:
Indicates an error terminating heap local domain.
EKX80
Code Category:
Task Management Program
Reason:
Indicates internal register stack overflow.
EKXA
Code Category:
Task Management Program
Reason:
Indicates that previous abend occurred.
EKXD
Code Category:
Task Management Program
Reason:
Indicates that abend complete was called with a diagnostic work area.
EKXI
Code Category:
Task Management Program
Reason:
Indicates an invalid request.
EKXO
Code Category:
Task Management Program
Reason:
Indicates an invalid option update order.
EKXS
Code Category:
Task Management Program
Reason:
Indicates that the (E)STAE exit is taking a SNAP dump.
1018
CA Easytrieve® Report Generator 11.6
Program Link Manager Codes
EPML
Code Category:
Task Management Program
Reason:
Error when linking to another program (CICS only).
Printer File Manager Codes
EPR0
Code Category:
Printer File Manager
Reason:
Invalid function code.
EPR1
Code Category:
Printer File Manager
Reason:
Invalid printer file handle passed to CLOSE or WRITE function.
EPR2
Code Category:
Printer File Manager
Reason:
Error opening the printer file.
EPR3
Code Category:
Printer File Manager
Reason:
Error closing the printer file.
EPR4
Code Category:
Printer File Manager
Reason:
Error writing the printer file.
EPR5
Code Category:
Printer File Manager
Reason:
1019
CA Easytrieve® Report Generator 11.6
Cannot find printer definition.
EPR6
Code Category:
Printer File Manager
Reason:
Error opening the system message file.
EPR9
Code Category:
Printer File Manager
Reason:
Insufficient storage
Reporting Codes
ERP1
Code Category:
Reporting
Reason:
Insufficient storage for report work area.
ERP2
Code Category:
Reporting
Reason:
Insufficient storage for summary work area.
Runtime Initialization Stub Codes
ERS0
Code Category:
Runtime Initialization Stub
Reason:
Runtime system initialization/termination error.
ERS1
Code Category:
Runtime Initialization Stub
Reason:
Transfer of control failure.
Sort Interface Codes
1020
CA Easytrieve® Report Generator 11.6
ESIB
Code Category:
Sort Interface
Reason:
Nonzero return code from Sort.
SQL Interface Codes
ESQ1
Code Category:
SQL Interface
Reason:
The CA Pan/SQL interface has not been initialized.
ESQ2
Code Category:
SQL Interface
Reason:
Cannot process SQL files. One of the following conditions was detected:
• The SQL data block address in the initialization parameter was zero.
• The cursor descriptor block is missing.
ESQX
Code Category:
SQL Interface
Reason:
Critical error detected during execution of an SQL request. Condition code of 16 or more returned from CA Pan/SQL.
ESQY
Code Category:
SQL Interface
Reason:
An SQL request was made and the SQL interface was not initialized.
EZIO
Code Category:
SQL Interface
Reason:
Nonzero return code from SQL on automatic processing.
Terminal Printer Despooler Program Codes
1021
CA Easytrieve® Report Generator 11.6
ETID
Code Category:
Terminal Printer Despooler Program
Reason:
Unsupported printer device.
ETIO
Code Category:
Terminal Printer Despooler Program
Reason:
Internal stack overflow.
ETIS
Code Category
Terminal Printer Despooler Program
Reason:
Invalid spooled report encountered.
ETIX
Code Category:
Terminal Printer Despooler Program
Reason:
Task initialization or termination error.
Terminal Printer Interface Program Codes
ETPS
Code Category:
Terminal Printer Interface Program
Reason:
Unable to start the terminal printer despooler transaction.
Virtual File Manager Codes
EVF0
Code Category:
Virtual File Manager
Reason:
Invalid request passed to virtual file manager.
EVF1
Code Category:
Virtual File Manager
Reason:
1022
CA Easytrieve® Report Generator 11.6
Insufficient main storage.
EVF2
Code Category:
Virtual File Manager
Reason:
The maximum number of VFM data sets allowed for a single program was exceeded.
EVF3
Code Category:
Virtual File Manager
Reason:
Virtual file not found, that is, a runtime component attempted to perform an input/output operation on a system virtual data
set that had not been previously opened.
EVF4
Code Category:
Virtual File Manager
Reason:
Invalid file handle.
EVF5
Code Category:
Virtual File Manager
Reason:
For an input file, the record read from the virtual file was longer than the caller's input area. For an output file, the record to
be written to the virtual file was longer than the maximum logical record length of the file.
EVF6
Code Category:
Virtual File Manager
Reason:
An unrecoverable input/output error occurred on the VFM data set.
EVF7
Code Category:
Virtual File Manager
Reason:
Insufficient space in the VFM data set to contain the file.
EVF8
Code Category:
Virtual File Manager
Reason:
Invalid request returned by the input/output system. This is a general failure category.
1023
CA Easytrieve® Report Generator 11.6
EVF9
Code Category:
Virtual File Manager
Reason:
Leading and trailing record lengths are not equal. EVFAError opening the VFM data set.
EVFA
Code Category:
Virtual File Manager
Reason:
Error opening the VFM data set.
EVFB
Code Category:
Virtual File Manager
Reason:
Out of buffers. Either DEVICE MEMORY was specified or one or more VFM files specified MEMORY. There is not enough
memory to hold all the data that must be held in memory. Add an EZTVFM DD statement or DLBL to the JCL.
EVFC
Code Category:
Virtual File Manager
Reason:
Cannot find block. A READBUFFER request was issued for a MEMORY resident VFM file but the buffer manager could
not find the requested block in the buffer pool.
EVFD
Code Category:
Virtual File Manager
Reason:
Invalid bitmap block read from disk.
EVFE
Code Category:
Virtual File Manager
Reason:
Error reading from or writing to the VFM data set.
EVFF
Code Category:
Virtual File Manager
Reason:
Too much pending work queued.
1024
CA Easytrieve® Report Generator 11.6
EVFG
Code Category:
Virtual File Manager
Reason:
Invalid level number on a read block request.
EVFH
Code Category:
Virtual File Manager
Reason:
Attempt to read a data block that does not exist.
EVFI
Code Category:
Virtual File Manager
Reason:
Load for VFM data set handler failed.
1025
CA Easytrieve® Report Generator 11.6
CA EZ/Key
CA EZ/Key™ is an interactive, menu oriented, full-screen environment that you can use to develop and maintain CA
Easytrieve Plus programs. These programs can range from simple, straightforward reports to complex updates of files
and data bases. CA EZ/Key provides continuous information about your current actions and makes assumptions about
details that you have not specified. A complete syntax and semantic check is performed as each part of the program is
being entered or modified.
Click the following links to download the CA EZ/Key documentation:
• Administrator's Guide
• Installation Guide
• Reference Manual
• Sample Session
1026
CA Easytrieve® Report Generator 11.6
Documentation for Previous Releases
Documentation is available for the following products and releases in PDF format unless otherwise noted.
Product Language Releases Notes
CA Easytrieve® Report English 6.4, 11 SP4, 11.5 The bookshelves for 11 SP4 and
Generator 11.5 include HTML and PDF
files.
Release 6.4 is for CA
Easytrieve® Plus.
BookManager files are also
available for Release 6.4
guides.
CA Easytrieve® Report Japanese 11.6, 11.6 SP4
Generator
CA Easytrieve® Report English 2.0 Installation and Macro
Generator Toolkit Reference guides only.
CA Easytrieve® IQ Online Query English 3.1 Administrator, Installation, and
User guides only.
CA Easytrieve® Online Query English 1.3, 1.4 Introduction to the Language,
Report Generator Language Reference, and
Programmer guides are
available in PDF format.
Other guides are available in
BookManager format only.
1027
CA Easytrieve® Report Generator 11.6
Additional Resources
Product Support
The following resources provide more information about CA Easytrieve Report Generator:
• CA Easytrieve Report Generator Product Information (Knowledge Base Articles and Solutions)
• Service Pack Information Index (Maintenance Grid)
• z/OS Compatibility Matrix
• Mainframe Product Information (All Products)
• Broadcom Support
CA-Pan/SQL PDFs
The following CA-Pan SQL guides are available as PDFs:
• CA-Pan/SQL Cover Letter 2.5
• CA-Pan/SQL Getting Started 2.4c
• CA-Pan/SQL Interface Installation Guide 2.3 (MVS, CMS, VSE)
User Communities and Support
Consult your peers, reach out to subject matter experts, and read the latest technical insights and information in our global
communities:
• CA Easytrieve Community
• CA Mainframe Community
Education and Training
The following educational resources are available:
• Broadcom Mainframe Training
• Broadcom Education YouTube Channel
Social Media
Follow us on social media:
• Facebook
• LinkedIn
• Twitter
1028
CA Easytrieve® Report Generator 11.6
Product Names
This documentation references the following products:
• CA Easytrieve® Report Generator for Linux PC
• CA Easytrieve® Report Generator for Linux zSeries
• CA Easytrieve® Report Generator for UNIX
• CA Easytrieve® Report Generator for Windows
• CA Easytrieve® Report Generator for z/OS
• CA Easytrieve® Report Generator CA Datacom® Option
• CA Easytrieve® Report Generator CA Datacom® Option for SQL
• CA Easytrieve® Report Generator CA Datacom® Option for SQL and NON SQL
• CA Easytrieve® Report Generator CA IDMS™ Option for SQL
• CA Easytrieve® Report Generator CA IDMS™ Option for SQL and NON SQL
• CA Easytrieve® Online Query Report Generator for CICS
• CA Easytrieve® Online Query Report Generator for CICS/SP DB2
• CA Easytrieve® Online Query Report Generator for CICS/XA
• CA Easytrieve® Online Query Report Generator for TSO
• CA Easytrieve® Online Query Report Generator for TSO/XA DB2
• CA Easytrieve® Online Report Generator for z/OS
1029
CA Easytrieve® Report Generator 11.6
Product Accessibility Features
CA Technologies is committed to making sure that all customers can successfully use its products and supporting
documentation to accomplish vital business tasks.
CA Easytrieve® Report Generator provides the following accessibility features support:
Software Applications and Operating Systems
• Most product functions are executable from a keyboard where the function and result can be discerned textually.
However, some functions, like expand and collapse controls on the panel are not in the tab order, and can only be
located by exploration of the panel using the keyboard.
• The products inherit the following operating system accessibility features:
– StickyKeys
– FilterKeys
– ToggleKeys
– MouseKeys
– SerialKeys
• When tabular output is generated as a result of job submission, the output uses visual formatting semantics that are
not programmatically available to Assistive Technology (AT) through the emulator.
• Textual information is provided through a standard text file, which can be edited and viewed using a text editor and
through operating system functions for displaying text.
• The products do not inherit user-selected color, contrast, and font settings from the operating system. However, you
can change color, contrast, and font settings in the emulator and the product inherits these settings.
NOTE
To make more adjustments to your display, and the sound, keyboard, and mouse interactions with the
emulator, refer to your 3270 emulation software documentation. For other changes, refer to your operating
system documentation.
• Some characters (<, +, -, and >) are used to create a graphic indicator. However, these characters might cause
confusion when encountered by a screen reader user when seen individually or in combination within the same or
other applications.
Functional Performance Criteria
• Assistive Technology screen readers and screen magnifiers are supported. The batch products are text-based and
use input and output files that are viewed through text editors. However, some output can include visually formatted,
tabular data that require the user to examine the textual screen content to interpret responses.
• The products can be used in a mouseless (keyboard-only) mode. The products also inherit operating system motor
control accessibility features.
Documentation and Support
• Documentation can be viewed online, or downloaded in PDF and EPUB files.
• Support is available online, by email, and by phone.
1030
CA Easytrieve® Report Generator 11.6
Documentation Legal Notice
This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred
to as the “Documentation”) is for your informational purposes only and is subject to change or withdrawal by Broadcom
at any time. This Documentation is proprietary information of Broadocm and may not be copied, transferred, reproduced,
disclosed, modified or duplicated, in whole or in part, without the prior written consent of Broadcom.
If you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make
available a reasonable number of copies of the Documentation for internal use by you and your employees in connection
with that software, provided that all Broadcom copyright notices and legends are affixed to each reproduced copy.
The right to print or otherwise make available copies of the Documentation is limited to the period during which the
applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your
responsibility to certify in writing to Broadcom that all copies and partial copies of the Documentation have been returned
to Broadcom or destroyed.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “AS IS”
WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL
CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM
THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT,
BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF
THE POSSIBILITY OF SUCH LOSS OR DAMAGE.
The use of any software product referenced in the Documentation is governed by the applicable license agreement and
such license agreement is not modified in any way by the terms of this notice.
The manufacturer of this Documentation is Broadcom Inc.
Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the
restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)
(3), as applicable, or their successors.
Copyright © Broadcom. All Rights Reserved. The term “Broadcom” refers to Broadcom Inc. and/or its subsidiaries. All
trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.
1031
You might also like
- CA-Easytrieve Plus - 6.4 - Reference Guide100% (1)CA-Easytrieve Plus - 6.4 - Reference Guide563 pages
- COBOL & COBOL II Q1) Name The Divisions in ANo ratings yetCOBOL & COBOL II Q1) Name The Divisions in A155 pages
- Restructured Executor Extended Language Is A Highly Versatile ProgrammingNo ratings yetRestructured Executor Extended Language Is A Highly Versatile Programming13 pages
- Syntax Comparison Chart Managed COBOL CSharp JavaNo ratings yetSyntax Comparison Chart Managed COBOL CSharp Java25 pages
- An Analysis and Enhancements To MOOD MetricsNo ratings yetAn Analysis and Enhancements To MOOD Metrics29 pages
- Laboratory Manual: Communication SystemsNo ratings yetLaboratory Manual: Communication Systems12 pages
- Unit Test Report: RS203558 CPAUXREF Design RefNo ratings yetUnit Test Report: RS203558 CPAUXREF Design Ref27 pages
- G.E. Money Bank SWISS: Changeman Handbook Changeman HandbookNo ratings yetG.E. Money Bank SWISS: Changeman Handbook Changeman Handbook18 pages
- Different Tools That We Use For Monitoring (Ca-7, CA-11, $avours)0% (1)Different Tools That We Use For Monitoring (Ca-7, CA-11, $avours)60 pages
- CA Business Intelligence: Installation GuideNo ratings yetCA Business Intelligence: Installation Guide80 pages
- Data Structures & Algorithms in Python John Canning All Chapter Instant Download100% (10)Data Structures & Algorithms in Python John Canning All Chapter Instant Download60 pages
- 15-BISE Lahore - C Language Practicals-StudentNotesNo ratings yet15-BISE Lahore - C Language Practicals-StudentNotes6 pages
- 000-041 - Programming With IBM Enterprise PL/I - Dumps100% (1)000-041 - Programming With IBM Enterprise PL/I - Dumps48 pages
- Fix Cloned Arduino NANO CNC Shield - 10 Steps - InstructablesNo ratings yetFix Cloned Arduino NANO CNC Shield - 10 Steps - Instructables11 pages
- Parameterized Pipelined MapReduce OptimizationNo ratings yetParameterized Pipelined MapReduce Optimization5 pages
- Advantage CA-Easytrieve Plus Report Generator: User GuideNo ratings yetAdvantage CA-Easytrieve Plus Report Generator: User Guide169 pages