Scribd
Upload
226 views987 pages

Ca Easytrieve Report Generator 11 6

Uploaded by

Tube10 r
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
226 views987 pages

Ca Easytrieve Report Generator 11 6

Uploaded by

Tube10 r
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 987

CA Easytrieve® Report Generator 11.

Copyright © 2005-2019 Broadcom. All Rights Reserved. The term 'Broadcom' refers to Broadcom Inc. and/or its subsidiaries.
Contents

Announcements and News......................................................................................................................... 15

Release Notes............................................................................................................................................. 15
New Features.................................................................................................................................... 15
New Features Since Release 6.4......................................................................................................17
Differences Between Releases......................................................................................................... 22
Release Comparison......................................................................................................................... 35
Migration Guidelines........................................................................................................................36
CA SMP/E Internet Service Retrieval............................................................................................. 37
Portfolio Simplification.................................................................................................................... 37
Simplified Design System................................................................................................................39
Documentation Changes...................................................................................................................39

Installing..................................................................................................................................................... 40
Installation Best Practices................................................................................................................ 41
Install CA Easytrieve for Windows.................................................................................................41
Install CA Easytrieve for UNIX and Linux for zSeries.................................................................. 43
Install CA Easytrieve for Linux PC................................................................................................ 45
Install CA Easytrieve for z/OS........................................................................................................ 50
How the Installation Process Works......................................................................................52
Preparing for Installation........................................................................................................53
Install Your Product Using CA CSM....................................................................................53
Installing Your Product Using Pax ESD or DVD................................................................. 90
SAMPJCL and CBAAJCL Contents................................................................................... 104
Upgrade CA Easytrieve for z/OS.................................................................................................. 107
Install CA Easytrieve Packaged with CCS....................................................................................107
Install CA Easytrieve SDS.............................................................................................................108
Install the License Key.................................................................................................................. 108
Maintain Your Product...................................................................................................................109

Configuring............................................................................................................................................... 110
Configuration Best Practices..........................................................................................................110
Configure Your Product................................................................................................................. 111
Configure With CA CSM.................................................................................................... 112
Configure Without CA CSM............................................................................................... 112
Configure Your System..................................................................................................................119
Setting Environment Variables............................................................................................ 120
Updating the Table...............................................................................................................122

Getting Started..........................................................................................................................................160
Programming Lessons.................................................................................................................... 164
Lesson 1 - Library Section, FILE and DEFINE Statements................................................164
Lesson 2 - Activity Section, JOB and IF Statements.......................................................... 167
Lesson 3 - Activity Section, Report Output with PRINT Statement................................... 171
Lesson 4 - Activity Section, REPORT Statement and Report Definition Statements..........175
Library Section - Describe and Define Data................................................................................. 181
Describe Files and Fields..................................................................................................... 184
Activity Section - Processing and Logic....................................................................................... 196
JOB Activities...................................................................................................................... 196
SORT Activities................................................................................................................... 214
PROGRAM Activities..........................................................................................................217
Activity Section - Input and Output.............................................................................................. 218
Activity Section - Reporting.......................................................................................................... 229
Processing of Reports...........................................................................................................234
Label Report......................................................................................................................... 241
Testing Aid Parameters........................................................................................................ 244
Format Determination Parameters........................................................................................244
Multiple Reports................................................................................................................... 246
Report Procedures (PROCs).................................................................................................249
System-Defined Fields................................................................................................................... 260
General Purpose Fields........................................................................................................ 260
File Processing Fields.......................................................................................................... 261
Report Processing Fields......................................................................................................262

Using......................................................................................................................................................... 263
Using Best Practices.......................................................................................................................263
Create and Format a Report...........................................................................................................265
Compile and Link Your Program.................................................................................................. 271
Controlling Compilation.......................................................................................................271
Results of the Compilation...................................................................................................272
Program Compilation and Link-Editing Using JCL............................................................ 275
Submitting Your Program for Non-Mainframe Compilation.............................................. 288
Link-Editing Non-Mainframe Programs.............................................................................. 291
Execute a Program......................................................................................................................... 297
Execute a Program in UNIX and Linux for zSeries............................................................298
Execute a Program in Windows.......................................................................................... 298
Execute a Program in z/OS..................................................................................................299
File Description String (Non-Mainframe Only).................................................................. 300
Execute a Windows Indexed File Program......................................................................... 302
Execute a Btrieve Program.................................................................................................. 303
Execute a C-ISAM Program................................................................................................ 304
Report Display Facility (z/OS Only)................................................................................... 305
Error Analysis Report.......................................................................................................... 309
Execute a Program on a Web Server...................................................................................311
Alternate Collating Sequence Table.............................................................................................. 317
Extended Reporting........................................................................................................................ 320
Printing Concepts................................................................................................................. 322
Printer Characteristics...........................................................................................................336
Font Characteristics.............................................................................................................. 350
Set Up Source Control Supports....................................................................................................357
Workbench...................................................................................................................................... 359
Main Window....................................................................................................................... 360
Opening Windows................................................................................................................ 363
Manage Files and Applications............................................................................................363
Edit Source or Text Files.....................................................................................................368
Build and Run Programs......................................................................................................371
Debug Programs................................................................................................................... 373
Set Preferences..................................................................................................................... 381
Configuration Manager.........................................................................................................383
Workbench Tools and Utilities............................................................................................ 396
Creating Toolkit and Writing Scripts...................................................................................410
Workbench Help...................................................................................................................425
CA Easytrieve/Earl Usage..............................................................................................................425
CA Easytrieve SDS........................................................................................................................ 427
Create a JCL/Submit Prolog Source File.............................................................................427
Create a Project and Host Profile........................................................................................ 428
Import File and Field Definitions........................................................................................ 429
Design and Run a Report.....................................................................................................429

Programming.............................................................................................................................................430
Text Conventions and Field Rules.................................................................................................430
Code Programs............................................................................................................................... 432
Structured Programming.......................................................................................................432
Program Sections..................................................................................................................433
Define Files and Fields........................................................................................................ 434
8-Byte Binary Fields............................................................................................................ 438
Declarations.......................................................................................................................... 440
Literal and Data Formatting Rules...................................................................................... 441
Control Program Flow..........................................................................................................445
Assignments and Moves.......................................................................................................451
Table Processing...................................................................................................................461
Array Processing...................................................................................................................463
Inter-Program Linkage......................................................................................................... 472
Code Efficient Programs...................................................................................................... 488
Code CICS Programs........................................................................................................... 489
Multiple Platform Considerations........................................................................................ 489
SQL Database Processing.............................................................................................................. 490
Programming Methods......................................................................................................... 490
CA Easytrieve SQL Statement Rules.................................................................................. 491
Program Environment...........................................................................................................491
Library Section Definition................................................................................................... 494
CA Easytrieve SQL Files.....................................................................................................501
Automatic Retrieval Without a File.....................................................................................507
Native SQL Processing........................................................................................................ 509
ODBC Data Sources............................................................................................................ 514
CA IDMS Database Processing..................................................................................................... 516
CA IDMS Interface.............................................................................................................. 517
IDD Interface........................................................................................................................531
Sample Database and Logical Record................................................................................. 533
IMS/DLI Database Processing....................................................................................................... 538
Test Database........................................................................................................................539
PCB and PSB Processing.....................................................................................................540
Automatic Input....................................................................................................................541
Controlled Processing Using DLI Statements..................................................................... 547
IMS Fast Path DEDB Processing........................................................................................ 553
CA Datacom/DB Database Processing.......................................................................................... 553
Access the Database............................................................................................................. 554
Access Macros......................................................................................................................554
File Processing................................................................................................................................568
File Processing Modes......................................................................................................... 570
Sequential Files.................................................................................................................... 571
Virtual File Manager............................................................................................................ 574
Indexed Files........................................................................................................................ 575
Relative Files........................................................................................................................ 578
Sorting Files..........................................................................................................................582
Synchronized File Processing.............................................................................................. 584
PRINTER Files.....................................................................................................................589
Non-Mainframe Files........................................................................................................... 590
Report Processing........................................................................................................................... 591
PRINT Statement (Report Processing)................................................................................ 592
Report Formats..................................................................................................................... 594
Report Generation.................................................................................................................596
Standard Reports.................................................................................................................. 597
Label Reports........................................................................................................................604
XML Reports........................................................................................................................607
Sequenced Reports............................................................................................................... 609
CONTROL Reports..............................................................................................................609
Report Procedures.................................................................................................................629
Routing Printer Output......................................................................................................... 641
Use Extended Reporting.......................................................................................................643
Extended Reporting Concepts.............................................................................................. 644
Report Layout Processing.................................................................................................... 656
Screen Processing........................................................................................................................... 663
Screen Format.......................................................................................................................664
Use the SCREEN Statement................................................................................................ 666
Screen Title Area..................................................................................................................668
Screen Work Area................................................................................................................ 669
Format an Item for Display................................................................................................. 671
Screen Message Area........................................................................................................... 685
Screen Function Key Area................................................................................................... 685
Screen Key Processing......................................................................................................... 685
Screen Procedures.................................................................................................................686
Commit Processing...............................................................................................................693
Sample Screen Applications.................................................................................................697
Macro Facility................................................................................................................................ 706
Invoke a Macro.................................................................................................................... 708
Define Macros...................................................................................................................... 709
Process Macros..................................................................................................................... 711
In-stream Macros..................................................................................................................712
SUPRA Interface Option................................................................................................................714
SUPRA Interface Operation.................................................................................................715
TOTAL Interface Option............................................................................................................... 726
%ADDM - Add Master (TOTAL).......................................................................................728
%ADDV - Add Variable (TOTAL).....................................................................................729
%CBLCNVRT...................................................................................................................... 730
%CLOSX - Close TOTAL File........................................................................................... 730
%CONCAT...........................................................................................................................730
%CONVAE...........................................................................................................................731
%CONVEA...........................................................................................................................731
%DATECALC...................................................................................................................... 732
%DATECONV..................................................................................................................... 733
%DATEVAL........................................................................................................................ 734
%DELM................................................................................................................................ 735
%DELVD..............................................................................................................................736
%DFNTOTF......................................................................................................................... 737
%EZSSID..............................................................................................................................737
%EZTINI.............................................................................................................................. 737
%FINDX............................................................................................................................... 738
%GETCALEN...................................................................................................................... 739
%GETJULI........................................................................................................................... 739
%RDNXT............................................................................................................................. 739
%OPENX.............................................................................................................................. 740
%READD............................................................................................................................. 740
%READM.............................................................................................................................741
%READR..............................................................................................................................742
%READV............................................................................................................................. 743
%RGHTJUST....................................................................................................................... 744
%SINOF................................................................................................................................744
%SINON............................................................................................................................... 744
%VERNUMP........................................................................................................................745
%WRITM............................................................................................................................. 745
%WRITV.............................................................................................................................. 746
Example - Retrieve Records Using a Tickler File...............................................................747

Language Reference................................................................................................................................. 749


Character Sets................................................................................................................................. 749
Statements....................................................................................................................................... 751
Statement Overview............................................................................................................. 758
% (Macro Invocation) Statement......................................................................................... 761
* (Comment) Statement....................................................................................................... 762
ACCESS Statement.............................................................................................................. 762
AFTER-BREAK Report Procedure..................................................................................... 763
AFTER-LINE Report Procedure..........................................................................................765
AFTER-SCREEN Screen Procedure....................................................................................767
Assignment Statement.......................................................................................................... 767
ATTR Parameter...................................................................................................................772
BEFORE-BREAK Report Procedure...................................................................................774
BEFORE-LINE Report Procedure....................................................................................... 775
BEFORE-SCREEN Screen Procedure.................................................................................776
CALL Statement...................................................................................................................776
CASE and END-CASE Statements..................................................................................... 777
CLOSE Statement.................................................................................................................779
COMMIT Statement.............................................................................................................780
Conditional Expressions....................................................................................................... 780
CONTROL Statement.......................................................................................................... 791
COPY Statement.................................................................................................................. 792
CURSOR Statement............................................................................................................. 793
DECLARE Statement...........................................................................................................793
DEFAULT Statement........................................................................................................... 795
DEFINE Statement............................................................................................................... 797
DELETE Statement.............................................................................................................. 805
DISPLAY Statement............................................................................................................ 806
DLI Statement...................................................................................................................... 808
DO UNTIL and DO WHILE Statements............................................................................ 811
ENDPAGE Report Procedure.............................................................................................. 813
END-PROC Statement......................................................................................................... 813
ENDTABLE Statement........................................................................................................ 814
EXECUTE Statement........................................................................................................... 814
EXIT Statement.................................................................................................................... 815
FETCH Statement.................................................................................................................815
FILE Statement.....................................................................................................................816
GET Statement..................................................................................................................... 825
GOTO Statement.................................................................................................................. 826
HEADING Statement........................................................................................................... 828
IDD FILE Statement............................................................................................................ 829
IDD NAME Statement......................................................................................................... 829
IDD RECORD Statement.....................................................................................................830
IDD SUBSCHEMA Statement............................................................................................ 831
IDD VERSION Statement................................................................................................... 831
IDMS ACCEPT DBKEY Statement....................................................................................832
IDMS ACCEPT PAGE-INFO Statement............................................................................ 832
IDMS ACCEPT PROCEDURE Statement..........................................................................833
IDMS ACCEPT STATISTICS Statement........................................................................... 833
IDMS BIND Statement........................................................................................................ 833
IDMS BIND FILE Statement.............................................................................................. 834
IDMS BIND PROCEDURE Statement............................................................................... 834
IDMS COMMIT Statement................................................................................................. 835
IDMS CONNECT Statement............................................................................................... 835
IDMS DISCONNECT Statement.........................................................................................835
IDMS ERASE Statement..................................................................................................... 836
IDMS FIND and IDMS OBTAIN Statements.....................................................................836
IDMS FINISH Statement..................................................................................................... 839
IDMS GET Statement.......................................................................................................... 839
IDMS IF Statement.............................................................................................................. 839
IDMS KEEP Statement........................................................................................................840
IDMS MODIFY Statement.................................................................................................. 840
IDMS OBTAIN Statement...................................................................................................841
IDMS READY Statement.................................................................................................... 841
IDMS RETURN Statement..................................................................................................841
IDMS ROLLBACK Statement............................................................................................ 842
IDMS STORE Statement..................................................................................................... 842
IF, ELSE-IF, ELSE, and END-IF Statements..................................................................... 843
INITIATION Screen Procedure........................................................................................... 847
INSERT Statement............................................................................................................... 847
JOB Statement...................................................................................................................... 848
KEY Statement..................................................................................................................... 850
LINE Statement.................................................................................................................... 853
LINK Statement....................................................................................................................854
LIST Statement.....................................................................................................................855
MACRO Statement...............................................................................................................855
MASK Parameter................................................................................................................. 856
MEND Statement................................................................................................................. 860
MESSAGE Statement...........................................................................................................860
MOVE Statement................................................................................................................. 861
MOVE LIKE Statement....................................................................................................... 863
MSTART Statement............................................................................................................. 865
NEWPAGE Statement..........................................................................................................865
PARM Statement..................................................................................................................865
PERFORM Statement...........................................................................................................873
POINT Statement................................................................................................................. 874
POP Statement......................................................................................................................875
PRINT Statement..................................................................................................................875
PROC Statement...................................................................................................................876
PROGRAM Statement......................................................................................................... 877
PUSH Statement................................................................................................................... 879
PUT Statement......................................................................................................................879
READ Statement.................................................................................................................. 880
RECORD Statement (CA IDMS and IMS/DLI)................................................................. 881
REFRESH Statement............................................................................................................882
RELEASE Statement............................................................................................................883
REPEAT and END-REPEAT Statements............................................................................884
REPORT Statement..............................................................................................................885
REPORT-INPUT Report Procedure.................................................................................... 890
RESHOW Statement............................................................................................................ 891
RETRIEVE Statement (CA IDMS and IMS/DLI).............................................................. 892
ROLLBACK Statement........................................................................................................894
ROW Statement....................................................................................................................895
SCREEN Statement..............................................................................................................898
SEARCH Statement............................................................................................................. 899
SELECT Statement (File-based SQL)................................................................................. 901
SELECT Statement (Non-file SQL).................................................................................... 902
SELECT Statement (Report Selection)................................................................................903
SELECT Statement (Sort Selection)....................................................................................904
SEQUENCE Statement........................................................................................................ 904
SET Statement...................................................................................................................... 905
SKIP Statement.................................................................................................................... 907
SORT Statement................................................................................................................... 908
SQL Statement......................................................................................................................910
SQL INCLUDE Statement...................................................................................................913
STOP Statement................................................................................................................... 915
SUM Statement.................................................................................................................... 916
TERMINATION Report Procedure..................................................................................... 916
TERMINATION Screen Procedure..................................................................................... 917
TITLE Statement (Reports)..................................................................................................917
TITLE Statement (Screens)..................................................................................................918
TRANSFER Statement.........................................................................................................919
UPDATE Statement............................................................................................................. 920
WRITE Statement.................................................................................................................921
Symbols and Reserved Words....................................................................................................... 922
Conversion from Old to Current CA Easytrieve Version..............................................................925

Messages and Codes................................................................................................................................ 926


SUPRA Diagnostic Messages........................................................................................................ 926
Operational Diagnostic Messages........................................................................................ 927
Syntax Diagnostic Messages................................................................................................930
Program Abend Messages (EZABX).............................................................................................932
EZABX000........................................................................................................................... 933
EZABX008........................................................................................................................... 933
EZABX009........................................................................................................................... 933
EZABX010........................................................................................................................... 933
EZABX016........................................................................................................................... 934
EZABX020........................................................................................................................... 934
EZABX024........................................................................................................................... 934
EZABX046........................................................................................................................... 935
EZABX047........................................................................................................................... 935
EZABX048........................................................................................................................... 935
EZABX049........................................................................................................................... 935
EZABX050........................................................................................................................... 936
EZABX051........................................................................................................................... 936
EZABX053........................................................................................................................... 936
EZABX054........................................................................................................................... 936
EZABX055........................................................................................................................... 936
EZABX056........................................................................................................................... 937
EZABX057........................................................................................................................... 937
EZABX058........................................................................................................................... 937
EZABX059........................................................................................................................... 937
EZABX060........................................................................................................................... 937
EZABX061........................................................................................................................... 938
EZABX062........................................................................................................................... 938
Linking, Transferring and Calling Messages.................................................................................938
EZACT001............................................................................................................................938
EZACT002............................................................................................................................938
EZACT005............................................................................................................................939
Utility Messages............................................................................................................................. 939
EZALT001............................................................................................................................ 939
EZALT002............................................................................................................................ 939
EZALT003............................................................................................................................ 940
EZALT004............................................................................................................................ 940
EZALT005............................................................................................................................ 940
EZALT006............................................................................................................................ 940
EZALT007............................................................................................................................ 940
EZALT008............................................................................................................................ 941
EZALT009............................................................................................................................ 941
EZALT010............................................................................................................................ 941
EZALT011............................................................................................................................ 941
EZALT012............................................................................................................................ 942
EZALT013............................................................................................................................ 942
EZALT014............................................................................................................................ 942
Configuration Manager Messages..................................................................................................942
EZCM001............................................................................................................................. 942
EZCM002............................................................................................................................. 943
EZCM003............................................................................................................................. 943
EZCM004............................................................................................................................. 943
EZCM005............................................................................................................................. 943
EZCM006............................................................................................................................. 943
EZCM007............................................................................................................................. 944
EZCM008............................................................................................................................. 944
EZCM009............................................................................................................................. 944
EZCM010............................................................................................................................. 944
EZCM011............................................................................................................................. 944
EZCM012............................................................................................................................. 944
EZCM013............................................................................................................................. 945
EZCM014............................................................................................................................. 945
EZCM015............................................................................................................................. 945
EZCM016............................................................................................................................. 945
EZCM017............................................................................................................................. 945
EZCM018............................................................................................................................. 945
EZCM019............................................................................................................................. 946
EZCM020............................................................................................................................. 946
EZCM021............................................................................................................................. 946
EZCM022............................................................................................................................. 946
EZCM023............................................................................................................................. 946
EZCM024............................................................................................................................. 946
IMS_DLI Messages........................................................................................................................947
EZDLI001............................................................................................................................. 947
EZDLI002............................................................................................................................. 947
EZDLI003............................................................................................................................. 947
Program Abend Messages (EZEIP)............................................................................................... 947
EZEIP001..............................................................................................................................948
EZEIP003..............................................................................................................................948
EZEIP004..............................................................................................................................948
EZEIP005..............................................................................................................................948
EZEIP006..............................................................................................................................949
EZEIP007..............................................................................................................................949
EZEIP011..............................................................................................................................949
EZEIP015..............................................................................................................................949
EZEIP017..............................................................................................................................949
EZEIP018..............................................................................................................................950
EZEIP019..............................................................................................................................950
EZEIP021..............................................................................................................................950
EZEIP022..............................................................................................................................950
EZEIP023..............................................................................................................................950
EZEIP024..............................................................................................................................951
EZEIP025..............................................................................................................................951
EZEIP028..............................................................................................................................951
EZEIP992..............................................................................................................................951
EZEIP997..............................................................................................................................952
IDMS Messages..............................................................................................................................952
EZIDM001............................................................................................................................ 952
EZIDM002............................................................................................................................ 952
EZIDM003............................................................................................................................ 952
File I_O Messages..........................................................................................................................952
EZIOE001............................................................................................................................. 953
EZIOE002............................................................................................................................. 953
EZIOE003............................................................................................................................. 954
EZIOE004............................................................................................................................. 955
EZIOE005............................................................................................................................. 956
EZIOE007............................................................................................................................. 956
EZIOE008............................................................................................................................. 956
EZIOE009............................................................................................................................. 957
EZIOE011............................................................................................................................. 958
System Initialization Messages...................................................................................................... 958
EZKX0001............................................................................................................................ 958
EZKX0004............................................................................................................................ 958
EZKX0012............................................................................................................................ 959
EZKX0013............................................................................................................................ 959
EZKX0014............................................................................................................................ 959
EZKX0016............................................................................................................................ 959
EZKX0017............................................................................................................................ 959
EZKX0060............................................................................................................................ 959
EZKX0061............................................................................................................................ 960
ETOPLOAD Utility Messages.......................................................................................................960
EZOPT001............................................................................................................................ 960
EZOPT002............................................................................................................................ 960
EZOPT003............................................................................................................................ 960
EZOPT004............................................................................................................................ 961
EZOPT005............................................................................................................................ 961
EZOPT008............................................................................................................................ 961
EZOPT009............................................................................................................................ 961
EZOPT010............................................................................................................................ 961
EZOPT011............................................................................................................................ 962
EZOPT012............................................................................................................................ 962
EZOPT013............................................................................................................................ 962
EZOPT014............................................................................................................................ 962
EZOPT015............................................................................................................................ 962
EZOPT016............................................................................................................................ 963
EZOPT017............................................................................................................................ 963
EZOPT018............................................................................................................................ 963
EZOPT020............................................................................................................................ 963
EZOPT021............................................................................................................................ 963
System Termination Message........................................................................................................ 963
EZSHT101............................................................................................................................ 964
SQL Messages................................................................................................................................ 964
EZSQL001............................................................................................................................ 964
EZSQL002............................................................................................................................ 964
EZSQL003............................................................................................................................ 965
EZSQL004............................................................................................................................ 965
EZSQL005............................................................................................................................ 965
Sort Messages................................................................................................................................. 965
EZSRT008............................................................................................................................ 965
EZSRT009............................................................................................................................ 966
EZSRT013............................................................................................................................ 966
Compiler Messages.........................................................................................................................967
EZTC0744E.......................................................................................................................... 967
Runtime Error Check Codes.......................................................................................................... 968
EBND....................................................................................................................................968
EBSN.................................................................................................................................... 968
Runtime Code Generator Codes.................................................................................................... 968
ECGO....................................................................................................................................968
IMS_DLI Interface Codes..............................................................................................................968
EDLI..................................................................................................................................... 969
Dynamic Loader Codes..................................................................................................................969
EDSN.................................................................................................................................... 969
EDSO.................................................................................................................................... 969
Dynamic Segment Manager Codes................................................................................................969
EDSA.................................................................................................................................... 969
EDSO0.................................................................................................................................. 969
EDSS.....................................................................................................................................969
EDST.....................................................................................................................................969
EDSX.................................................................................................................................... 970
Heap Manager Codes..................................................................................................................... 970
EBND0..................................................................................................................................970
EBSL.....................................................................................................................................970
EFLD.....................................................................................................................................970
EFML.................................................................................................................................... 970
EFNF.....................................................................................................................................970
EFVL.....................................................................................................................................970
EHMD...................................................................................................................................970
EHMF................................................................................................................................... 971
EHMH...................................................................................................................................971
EHMI.................................................................................................................................... 971
EHML................................................................................................................................... 971
EHMN...................................................................................................................................971
EHMO...................................................................................................................................971
EHMQ...................................................................................................................................971
EHMR................................................................................................................................... 972
EHMV...................................................................................................................................972
EHMW.................................................................................................................................. 972
EHMX...................................................................................................................................972
Input_Output Statement Handler Codes........................................................................................ 972
EIO0...................................................................................................................................... 972
EIO1...................................................................................................................................... 972
EIO2...................................................................................................................................... 972
EIO3...................................................................................................................................... 973
EIO4...................................................................................................................................... 973
EIO5...................................................................................................................................... 973
EIO6...................................................................................................................................... 973
EIO9...................................................................................................................................... 973
EIOA..................................................................................................................................... 973
EIDA..................................................................................................................................... 973
EIOX..................................................................................................................................... 974
Activity Management Codes..........................................................................................................974
EJA1......................................................................................................................................974
System Spool Printer Interface Module Codes..............................................................................974
EJSO..................................................................................................................................... 974
EJSC......................................................................................................................................974
EJSW.....................................................................................................................................974
Task Execution Control Program Codes....................................................................................... 974
EKX0.................................................................................................................................... 974
EKX1.................................................................................................................................... 975
EKX2.................................................................................................................................... 975
EKX5.................................................................................................................................... 975
EKS6..................................................................................................................................... 975
EKX7.................................................................................................................................... 975
EKX8.................................................................................................................................... 975
EKX9.................................................................................................................................... 975
EKXB....................................................................................................................................976
EKXC....................................................................................................................................976
EKXE.................................................................................................................................... 976
EKXF.................................................................................................................................... 976
EKXG................................................................................................................................... 976
EKXH................................................................................................................................... 976
Task Management Program Codes................................................................................................ 976
EKX3.................................................................................................................................... 976
EKX4.................................................................................................................................... 977
EKX80.................................................................................................................................. 977
EKXA................................................................................................................................... 977
EKXD................................................................................................................................... 977
EKXI..................................................................................................................................... 977
EKXO................................................................................................................................... 977
EKXS.................................................................................................................................... 977
Program Link Manager Codes....................................................................................................... 978
EPML.................................................................................................................................... 978
Printer File Manager Codes........................................................................................................... 978
EPR0..................................................................................................................................... 978
EPR1..................................................................................................................................... 978
EPR2..................................................................................................................................... 978
EPR3..................................................................................................................................... 978
EPR4..................................................................................................................................... 978
EPR5..................................................................................................................................... 978
EPR6..................................................................................................................................... 979
EPR9..................................................................................................................................... 979
Reporting Codes............................................................................................................................. 979
ERP1..................................................................................................................................... 979
ERP2..................................................................................................................................... 979
Runtime Initialization Stub Codes................................................................................................. 979
ERS0..................................................................................................................................... 979
ERS1..................................................................................................................................... 979
Sort Interface Codes.......................................................................................................................979
ESIB...................................................................................................................................... 980
SQL Interface Codes...................................................................................................................... 980
ESQ1..................................................................................................................................... 980
ESQ2..................................................................................................................................... 980
ESQX.................................................................................................................................... 980
ESQY.................................................................................................................................... 980
EZIO..................................................................................................................................... 980
Terminal Printer Despooler Program Codes..................................................................................980
ETID..................................................................................................................................... 981
ETIO..................................................................................................................................... 981
ETIS...................................................................................................................................... 981
ETIX..................................................................................................................................... 981
Terminal Printer Interface Program Codes.................................................................................... 981
ETPS..................................................................................................................................... 981
Virtual File Manager Codes...........................................................................................................981
EVF0..................................................................................................................................... 981
EVF1..................................................................................................................................... 981
EVF2..................................................................................................................................... 982
EVF3..................................................................................................................................... 982
EVF4..................................................................................................................................... 982
EVF5..................................................................................................................................... 982
EVF6..................................................................................................................................... 982
EVF7..................................................................................................................................... 982
EVF8..................................................................................................................................... 983
EVF9..................................................................................................................................... 983
EVFA.................................................................................................................................... 983
EVFB.................................................................................................................................... 983
EVFC.................................................................................................................................... 983
EVFD.................................................................................................................................... 983
EVFE.....................................................................................................................................983
EVFF.....................................................................................................................................984
EVFG.................................................................................................................................... 984
EVFH.................................................................................................................................... 984
EVFI......................................................................................................................................984

CA EZ/Key............................................................................................................................................... 984

Documentation for Previous Releases..................................................................................................... 984

Additional Resources................................................................................................................................985

Product Names..........................................................................................................................................986

Product Accessibility Features................................................................................................................. 986

Documentation Legal Notice................................................................................................................... 987


CA Easytrieve® Report Generator 11.6

1 Announcements and News


Includes information about conferences, community events, and product 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.

2 Release Notes
New features, release comparison, and migration guidelines.
Welcome to the CA Easytrieve® Report Generator Release Notes for Release 11.6. This section includes the following
articles:

New Features
This article describes the new features, enhancements, and changes for Release 11.6:
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:
CA Easytrieve® Report Generator 11.6

• 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.
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.
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.
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
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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

• 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).
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
CA Easytrieve® Report Generator 11.6

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:
• 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
CA Easytrieve® Report Generator 11.6

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:
• 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:
• 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.
CA Easytrieve® Report Generator 11.6

• 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 ezt for the UNIX, Linux for zSeries, Windows, and z/OS
platforms.
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
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.
CA Easytrieve® Report Generator 11.6

Example:

FILE FILEA F(80)FLD 1 1 A OCCURS 81R11 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 2DEFINE FLD3 S 16 A VALUE '3333333333333333'DEFINE SUB S 2
NJOB INPUT NULLDISPLAY FLD1 +2 FLD3DO WHILE SUB < 3 FLD2(SUB) =
'2222222222222222' SUB = SUB + 1END-DODISPLAY FLD1 +2 FLD3STOP

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:

FILE CARDIN CARDFLD1 1 3 AJOB INPUT CARDINDISPLAY FLD1ENDABCDEFXYZ

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 CARDINFLD1 1 3 AJOB INPUT CARDINDISPLAY FLD1/*//CARDIN DD


*ABCDEFXYZ/*

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
CA Easytrieve® Report Generator 11.6

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 NULLIF FLDA = FLDV DISPLAY 'TRUE'ELSE DISPLAY 'FALSE'END-
IFIF FLDV = FLDA. * Reverse the subject and object DISPLAY
'TRUE'ELSE DISPLAY 'FALSE'END-IFSTOP

For the previous code example, 6.4 displays the following:

TRUEFALSE

For the previous code example, r11 displays the following:

FALSEFALSE

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',
characters (0E, 0F). X'0F').
The DEFAULTS statement used a DATE parameter to The CODE SYSTEM provides a JAPANYEAR parameter
specify separators in date fields. that 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


CA Easytrieve® Report Generator 11.6

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.

DEFINE FLD1 S 3 AJOB INPUT NULLDEFINE FLD1 S 3 NEZTC0393W >>>


+ type not same as original fieldSTOP

• 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 3DEFINE FLDP-R FLDP 5 PEZTC0715W >>>


+ subscripting not allowed - length greater than overlayed
fieldDEFINE SUB S 1 N VALUE 1JOB INPUT NULLDO WHILE SUB < 4 FLDP
(SUB) = SUB DISPLAY 'FLDP=' FLDP (SUB) SUB = SUB + 1END-DOSUB
= 1DO WHILE SUB < 4 DISPLAY 'FLDP-R=' FLDP-R (SUB) SUB = SUB
+ 1 END-DOSTOP6.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 A3 JOB INPUT NULL4 DISPLAY FLD5


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 5 EXECUTE JOB1 6 JOB INPUT NULL NAME JOB1 7
DISPLAY FLDEZTC0654W >>> + file or file containing field
may not be active 8 STOP
CA Easytrieve® Report Generator 11.6

• 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 NULLDISPLAY HEX FLDV1DISPLAY HEX FLDV2STOP

The following example shows the 6.4 results, in which FLDV2 is not VARYING:

CHAR ABCZONE 00CCC44444NUMR 0312300000 1...5...10CHAR DEFZONE


CCC4444444NUMR 4560000000 1...5...10

The following example, shows r11 results with FLDV2 correctly modeled after FLDV1:

CHAR ABCZONE 00CCC44444NUMR 0312300000 1...5...10CHAR


DEFZONE 00CCC44444NUMR 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
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.
CA Easytrieve® Report Generator 11.6

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 AVFLD2 * 10 AJOB INPUT NULLVFLD1


= '1111111111'VFLD2 = 'ABC'RECORD-LENGTH = 13PUT VFILEVFLD1 =
'2222222222'VFLD2 = 'X'RECORD-LENGTH = 11PUT VFILESTOPJOB INPUT
VFILEDISPLAY HEX VFLD2

The following example shows the 6.4 results:

CHAR ABC 222ZONE CCC0000FFFNUMR 1230F00222 1...5...10CHAR XZONE


E000000000NUMR 7000000000 1...5...10

The following example shows the Release 11.x results:

CHAR ABCZONE CCC4444444NUMR 1230000000 1...5...10CHAR XBCZONE


ECC4444444NUMR 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 VFILEDEFINE SFLD S 10 ADEFINE LEN S 2 NLEN = RECORD-LENGTH


- 10. * Compute length to safely move dataMOVE 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 AVFLD2 * 10 AFILE VFILEOUT VB(20


200)JOB INPUT VFILEVFILEOUT:RECORD-LENGTH = VFILE:RECORD-LENGTHPUT
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 File-based SQL automates the SELECT statement. The old
statement and required a complete INTO list for the columns. style is supported though no longer documented.
CA Easytrieve® Report Generator 11.6

SQL files without the DEFER keyword were SQL files behave like other file types. The cursor is opened
opened before executing the user-defined START procedure, before the user-defined START procedure, unless DEFER
if a procedure was coded. This behavior contradicted the is coded. With DEFER, the cursor is opened after the user-
documented behavior and did not conform to the behavior for specified START procedure. This way, host variables can be
other file types. properly set before the cursor is opened.
The access method for the VS parameter was determined at The VS parameter is replaced with SEQUENTIAL,
execution time. INDEXED, and 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:

FILE KSDS VSFILE ESDS VS ESFILE RRDS VS

The following example shows Release 11.x syntax:

FILE KSDS INDEXEDFILE ESDS SEQUENTIALFILE 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}
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

Title fields were refreshed only when printing titles as the Items on the title line are now always refreshed with the
result of a detail line. current value of fields when produced.
Reports that included a control break had one extra blank line The extra blank line at the end of the report is now omitted.
at the end of the report. This is only at the end of the report, not at the end of every
page.
A single, nonsequenced (nonspooled) report was treated All reports work consistently in their handling of W fields.
differently than other reports. As a result, W (working This change can cause older, miscoded programs to behave
storage) fields were sometimes used instead of S (static) differently due to misuse of W fields.
fields. When that 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 Special named break procedures refer to the last detail record
the new control group. As a result, detail references did not of the control group so that detail references match control
always 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 PERSNLREGION 1 1 ANAME 17 8 AGROSS 94 4 P 2JOBPRINTREPORTSEQUENCE


REGIONCONTROL REGIONLINE REGION NAME GROSSAFTER-BREAK. PROC
DISPLAY 'FINAL NAME WAS ' NAMEEND-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.16FINAL 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.16FINAL NAME WAS WIMN
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
CA Easytrieve® Report Generator 11.6

• 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


REGIONEZTC0092E >>> $ 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 ADEFINE MYDATE-MONTHCHAR MYDATE 1 AJOB INPUT


NULLMYDATE = SYSDATEDISPLAY MYDATEIF MYDATE-MONTHCHAR = ' '
MYDATE-MONTHCHAR = '0'END-IFDISPLAY MYDATESTOP

The previous code provides the following results in Release 11.x:

5/10/1105/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.
CA Easytrieve® Report Generator 11.6

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 VSINPEZTC0252E >>>
$ 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 100006 *
7 JOB INPUT NULL 8
READ VSINP KEY WEMP# STATUS 9 STOP

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.
CA Easytrieve® Report Generator 11.6

The following example compiles and executes cleanly in Release 6.4:

2 FILE VSINP VS(ES) 3 INREC 1 150 A4 *


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
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 PERSNLREGION 1 1 ANAME 17 8 AGROSS 94 4 P 2WFLD W 2


N JOBPRINTREPORT NOADJUSTLINE REGION NAME GROSSAFTER-LINE. PROCWFLD =
WFLD + 1DISPLAY 'SEQ=' WFLDEND-PROC
CA Easytrieve® Report Generator 11.6

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:

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.
CA Easytrieve® Report Generator 11.6

Release Comparison
This article lists the key features added since Release 6.4. Click the link for more information about a
feature.
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 yes no
condition code that the compiler returns
for warning messages
Multiple SSIDs with CA Pan/SQL yes no
BLOCK0 option allows system- yes no
determined data set block size
NEWFUNC option specifies whether to yes no
use the standard Release 11.x compiler
or the compatibility mode compiler
AMODE31 option Specifies the location yes no
of where memory is to be allocated
during the execution of the program
MTVSERR option specifies how an yes no
empty 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 yes no
format C-ISAM file support (UNIX
only)
Output of file statistics containing yes no
activity I/O record counts
Solaris UNIX, Linux, and Windows yes no
support
ODBC environment support for SQL yes no
interface
Date parameter allows date format yes no
override at program level
Report output in XML format yes no
Internal indexed ISAM included with yes no
Windows version
CA Easytrieve® Report Generator 11.6

Windows-Based compiler and runtime yes no


environment
Windows GUI for program yes no
development
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 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.
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 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
CA Easytrieve® Report Generator 11.6

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.
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:
• 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 .
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.
CA Easytrieve® Report Generator 11.6

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.

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- Enables CA Easytrieve to access data stored in CA Datacom
SQL 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.
CA Easytrieve® Report Generator 11.6

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 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 CA Support Online.
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
The following update has been made since the last release of this documentation:
Release Information
CA Easytrieve® Report Generator 11.6

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:
• 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.

3 Installing
Install, upgrade, and maintain the product.
This article describes the installation prerequisites and the CCS version of the product. This section includes the following
articles:

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.
CA Easytrieve® Report Generator 11.6

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 .
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.
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 ezt 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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

Install CA Easytrieve for UNIX and Linux for zSeries


This section describes the steps that are required for installing 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:
• 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.
CA Easytrieve® Report Generator 11.6

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.bndbind dqspsdbx.bnd

10. Install the license key as described in Install the License Key.
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
CA Easytrieve® Report Generator 11.6

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 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.
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:
CA Easytrieve® Report Generator 11.6

• 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.
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_pathif [ -f $EZT/eztprofile ]; then.


$EZT/eztprofilefi

Note: The first line specifies the path that was specified during CA Easytrieve installation. The default path is /opt/CA/ezt.
CA Easytrieve® Report Generator 11.6

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/libexport
EZTPATH=$EZT/bin:$EZT/eztpgms:$USR_PATHexport PATH=$PATH:
$EZTPATHexport LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$EZTPATHexport
EZTOPTS="-W a,--32 -I $EZT/macros"

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/binetopload -b -l >ezoptbl.def</dev/null

Note:
For more information about the options table, see Updating the Table.
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/tempgunzip unixODBC*.tar.gztar xvf unixODBC*.tarcd


unixODBC-2.3.0CFLAGS=-m32 LDFLAGS=-m32 CXXFLAGS=-m32 ./
configuremakemake 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.0DRIVERS............: /usr/local/etc/odbcinst.iniSYSTEM


DATA SOURCES: /usr/local/etc/odbc.iniFILE DATA SOURCES..: /usr/
local/etc/ODBCDataSourcesUSER DATA SOURCES..: /root/.odbc.iniSQLULEN
Size.......: 4SQLLEN Size........: 4SQLSETPOSIROW 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. 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.
CA Easytrieve® Report Generator 11.6

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
CA Easytrieve® Report Generator 11.6

All installation information is written to a log. If you experience problems during installation, this log can help CA Support
troubleshoot the cause.
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 on the mainframe and describes:
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.
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
CA Easytrieve® Report Generator 11.6

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 2 3120
Library
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
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.
CA Easytrieve® Report Generator 11.6

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.0 and 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:
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
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 CA Support or
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.
CA Easytrieve® Report Generator 11.6

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


The following CA Common Services are used with your product:
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.
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.
As a system programmer, your responsibilities include acquiring, installing, maintaining, deploying, and configuring CA
Technologies mainframe products on your system.
CA Easytrieve® Report Generator 11.6

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. Click here to access the CA CSM product documentation.
Use the following scenarios to guide you through the product installation process using CA CSM:
• 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 (CAMSM) 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.
CAMSM 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 CAMSM so that they are ready for installation using
CAMSM.
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:
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:
1.1 Update the product list.
2.1 Download product packages.
3. If you cannot download the product package from Broadcom Support:
1.1 Add external product installation packages.
2.1 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.
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.
CA Easytrieve® Report Generator 11.6

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.
1.1 Select the Edit button in the Filter section and associate one or more site IDs to a filter in the Edit Filter window.
2.1 Select the filter in the Filter section.
3.1 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.
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.
CA Easytrieve® Report Generator 11.6

•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 below 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.
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.
CA Easytrieve® Report Generator 11.6

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
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 (CAMSM) 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 CAMSM.
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.
CA Easytrieve® Report Generator 11.6

Figure 2: Installing_Products
1. (Optional) Configure base installation settings.
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:
CA Easytrieve® Report Generator 11.6

• Create an SMP/E environment:


1.1 Set up the global zone.
2.1 Create a target zone.
3.1 Create a distribution zone.
• Use an existing SMP/E environment from your working set:
1.1 Update the global zone.
2.1 Set up the target zone: Either create a target zone or use an existing target zone.
3.1 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
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
CA Easytrieve® Report Generator 11.6

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:
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.
CA Easytrieve® Report Generator 11.6

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.
1. 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.
2. From the target zone drop-down list, select a target zone within the selected SMP/E environment where the
prerequisites are installed.
3. 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
CA Easytrieve® Report Generator 11.6

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:
• 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.
1. The data set is allocated with one track for both primary and secondary space.
2. CA CSM verifies that the data set has been allocated on the specified volume.
3. 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.
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.
CA Easytrieve® Report Generator 11.6

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)
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.
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

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.
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.
1.1 • 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
Identifies the cross-system sharing option for SMP/E data sets.
• High-Level Qualifier
CA Easytrieve® Report Generator 11.6

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.
• 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
CA Easytrieve® Report Generator 11.6

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
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.
CA Easytrieve® Report Generator 11.6

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
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.
CA Easytrieve® Report Generator 11.6

Start the Installation


After you complete setting up the SMP/E environment and its zones, you are ready to start the installation.
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 (CAMSM) 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. CAMSM 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
CAMSM so that they can be applied using CAMSM.
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.
CA Easytrieve® Report Generator 11.6

1. (Optional) Configure automatic HOLDDATA download.


2. (Optional) Configure CA CSM to reject unneeded maintenance.
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.
1.1 Apply CA RS maintenance.
2.1 (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
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

• 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.
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 at 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.
CA Easytrieve® Report Generator 11.6

2. Select the Add External Maintenance button.


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.
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:
CA Easytrieve® Report Generator 11.6

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.
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:
CA Easytrieve® Report Generator 11.6

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.
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.
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.
CA Easytrieve® Report Generator 11.6

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.

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.
1.1 Connect to the FTP site at the following location:

ftp://ftp.ca.com
CA Easytrieve® Report Generator 11.6

2.1 Log in to ftp.ca.com as follows:

user name: anonymouspassword: your-email-address

3.1 Change to the following directory:

/pub/ASSIGNS

4.1 Change your download mode to ASCII.


5.1 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.
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).
CA Easytrieve® Report Generator 11.6

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 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.
CA Easytrieve® Report Generator 11.6

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.
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:
CA Easytrieve® Report Generator 11.6

Note: Changes in the allocation parameters apply to the current maintenance processing only.
1.1 Select Override for a DDDEF to edit its allocation parameters.
A pop-up window opens.
2.1 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.
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
CA Easytrieve® Report Generator 11.6

• 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.
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:
1.1 Select the installation mode for the selected maintenance.
2.1 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.
3.1 (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.
CA Easytrieve® Report Generator 11.6

• 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 (CAMSM) can help automate acquiring, installing, maintaining,
deploying, and configuring mainframe software. As a system programmer, your responsibilities include
configuring products using CAMSM. A configuration is a CAMSM object that you create to tailor your
installed software or CAMSM deployed software. Configuration makes your software usable in your
environment. A configuration contains the profiles, variables, and resources specific to your environment.
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.
CA Easytrieve® Report Generator 11.6
CA Easytrieve® Report Generator 11.6

1. Determine the source of your configuration based on your site environment:


• 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.
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.
CA Easytrieve® Report Generator 11.6

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).
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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
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
CA Easytrieve® Report Generator 11.6

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:
• 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.
CA Easytrieve® Report Generator 11.6

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:
1.1 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.
2.1 Modify the values in the new configuration as you need.
3.1 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 CA Support or from a product DVD. The DVD contains a folder
that includes the pax file for 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.
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 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:
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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.
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=*
//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.
CA Easytrieve® Report Generator 11.6

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.
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 http://ca.com/support to your PC, and then upload it to your USS file system.
If you download a zip file, you must unzip it before uploading to your USS file system.
• Download the pax files from http://ca.com/support 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 CA 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
CA Easytrieve® Report Generator 11.6

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 setEZA2606W File I/O error 133

2. Log in to CA 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 CA 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.
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.
CA Easytrieve® Report Generator 11.6

Download Using Batch JCL


You download a pax file from CA 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 CA 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.
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.
CA Easytrieve® Report Generator 11.6

*//*
*//* 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
*Hostanonymous YourEmailAddresslcd yourUSSpaxdirectorybinaryget FTP_location
*

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 mainframeuseridpasswordbinlcd C:\PC\folder\for


\thePAXfilecd /yourUSSpaxdirectory/put paxfile.pax.Zquitexit

• 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
CA Easytrieve® Report Generator 11.6

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:
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:

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'
CA Easytrieve® Report Generator 11.6

//*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.
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.
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:
1.1 Change the SMPJHOME DD PATH to your Java runtime directory. This directory varies from system to system.
2.1 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.
CA Easytrieve® Report Generator 11.6

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.
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:

• 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.
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:
CA Easytrieve® Report Generator 11.6

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.
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.
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.
CA Easytrieve® Report Generator 11.6

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 ca 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.
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
• 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 here 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),
CA Easytrieve® Report Generator 11.6

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.
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:
1.1 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

2.1 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.
CA Easytrieve® Report Generator 11.6

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.
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.
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
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
CA Easytrieve® Report Generator 11.6

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 ezt 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.
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.

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 All Pax ESD installation topics where
the product installation JCL. Update editing a job is required
member 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
CA Easytrieve® Report Generator 11.6

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 Apply Preventive Maintenance
from 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.
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
• Set Global Options
table.
Create the Options File and Update Its
Settings

JOB0764L Links CA Easytrieve Report Activate the 6.4 Compatibility IDMS


Generator compatibility library link and IMS Interface Option
edits (only necessary when using IMS or
IDMS feature with NEWFUNC=N set
in the options table).
CA Easytrieve® Report Generator 11.6

JOB08DEM Executes CA Easytrieve Report Lesson 1 - Library section, FILE and


Generator program to verify installation DEFINE statements
and create the sample personnel file.
• Report Output

JOB09URT Compiles and links the User Assemble a User Requirements Table
Requirements Table (URT) for the CA for the CA Datacom/DB Option
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 Printer Set Definition
definition module (only necessary if you
use the Extended Reporting feature). • Create Extended Reporting Printer
Set Definition

JOB15ORA Activates Oracle support by linking the Activate the Oracle Interface Option
Oracle ORASTBL member into the CA
Easytrieve Report Generator compiler.

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.
CA Easytrieve® Report Generator 11.6

Upgrade CA Easytrieve for z/OS


This article explains how to upgrade ezt for z/OS to the current release.
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:

• 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


You can install CA Easytrieve Report Generator that is packaged with CA Common Services.
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 Tech Docs Portal.
CA Easytrieve® Report Generator 11.6

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.
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 here.
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.

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.
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:
1.1 Copy the entire ALP license key and paste it into a new text file.
2.1 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.
CA Easytrieve® Report Generator 11.6

• -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

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.
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.
CA Easytrieve® Report Generator 11.6

4 Configuring
Configure the product.
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 ezt:
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.
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
CA Easytrieve® Report Generator 11.6

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.
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 .
This section describes what you need to do to start CA Easytrieve® Report Generator.
• Configure With CA CSM
• Configure Without CA CSM
CA Easytrieve® Report Generator 11.6

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.
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
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.
Follow these steps to configure your product:

Create the Options File and Update Its Settings


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.
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.

Migrate Options Table Settings (from 6.4)


If you are migrating from 6.4, you can optionally migrate your existing options table settings to the
current release.
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 release 11 SP03, release 11 SP04, or release 11.5 to release 11.6, you can
optionally migrate your existing options table settings to the current release.
CA Easytrieve® Report Generator 11.6

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 , build the Printer Set Definition (PSD). The PSD contains
the definitions for the extended printers used in the application programs.
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.
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.
CA Easytrieve® Report Generator 11.6

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:
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.

Create the DBCS Options Module


If you use the DBCS feature of , build the DBCS options module (PSIDBOPT). This module contains the
DBCS Code System definitions that are available for use in application programs.
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 to process data in an Oracle database by using SQL. If you use this
feature, 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.
CA Easytrieve® Report Generator 11.6

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.
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 sche
name [ OVERRIDE { } ] + [ { N
[ { YES } ] [ FIELDS maxfields ] [ OPEN
[ 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}
CA Easytrieve® Report Generator 11.6

• 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 to process data in a TOTAL database. If you plan to use this feature,
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.
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 ezt 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 .
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.
CA Easytrieve® Report Generator 11.6

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 ezt runtime routines are installed, one module (ETCOBSR) is statically link-edited with the
LE runtime option overrides that are required by ezt. 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 ezt jobs, you can add them in either of these ways:
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.
The section provides additional information and the steps that must be executed for some of the macro interfaces.
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
CA Easytrieve® Report Generator 11.6

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


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 .
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:

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,
CA Easytrieve® Report Generator 11.6

* 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:

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 for a UNIX, Linux for zSeries, and Windows command line-
based system, or for a z/OS 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
CA Easytrieve® Report Generator 11.6

Setting Environment Variables


This section describes environment variables for UNIX, Linux for zSeries, and Windows only and
provides examples.
This section describes environment variables for UNIX, Linux for zSeries, and Windows only and provides examples.
This article includes the following information:

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


CA Easytrieve® Report Generator 11.6

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.
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
openingresoracledb2odbc

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:
CA Easytrieve® Report Generator 11.6

[ 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"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


Explains how to update the options table. Contains a summary of options that are effective at compile
time, execution time, or both.
CA Easytrieve® Report Generator 11.6

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.
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 NCOMPNME ABC COMPANY, INC.DMAP YLONGDTE NPMAP 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
CA Easytrieve® Report Generator 11.6

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

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]


CA Easytrieve® Report Generator 11.6

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//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.
CA Easytrieve® Report Generator 11.6

• 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 no yes


meg line
ASCSIGN Zoned numeric format yes no

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 yes no


lines
ENVIRON Specify the default execution yes no
environment
ERORSYM Error message symbol yes no

FASTSRT Fast sort no yes


CA Easytrieve® Report Generator 11.6

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 no yes


I/O error
NEWFUNC Selects compiler mode of yes no
operation
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


CA Easytrieve® Report Generator 11.6

SCANCOLE End column yes no

SCANCOLS Start column yes no

SEPOTDC Decimal separator character yes no

SEPOTTH Thousands separator yes no


character
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 no yes
name
SQLSYNTX Type of syntax checking for yes no
SQL
SSID Database name yes no

STATE Save statement number yes no

STDERR Standard error destination ID no yes

STDOUT Standard output destination no yes


ID
STORCHK Check storage areas no yes

SUMCTL Print control fields on yes no


summary lines
SUMSPAC Additional positions for yes no
summed 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


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 no yes


only)
USERMSK Mask identifier yes yes
WARNSYM Warning message symbol yes no

WKDSNPF Work data set prefix no yes

WORKFILE Use Report Workfiles instead yes no


of 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.
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.
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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
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:
CA Easytrieve® Report Generator 11.6

PMAP Y and CLIST Y are mutually exclusive options.

PMAP {Y|N}

• Y
Produces the program map.
• N
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.
CA Easytrieve® Report Generator 11.6

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

• 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.
CA Easytrieve® Report Generator 11.6

• 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.
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 = PANDDMAC#LIB = 2

In the JCL, two ddnames are:

PANDD1PANDD2

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.
CA Easytrieve® Report Generator 11.6

• 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.

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}
CA Easytrieve® Report Generator 11.6

• 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 6WS-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
CA Easytrieve® Report Generator 11.6

In the following code, the programmer intends for the file status of PERSONAL to be checked:

FILE IDXF F(4) IDX 1 4 BFILE PERSONAL RELATIVE F 150%PERSNLJOB 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

Execution Options
This article describes the following Execution options that you can configure in the options table:
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.
CA Easytrieve® Report Generator 11.6

• 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
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}
CA Easytrieve® Report Generator 11.6

• 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.
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)
CA Easytrieve® Report Generator 11.6

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.

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
CA Easytrieve® Report Generator 11.6

• 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.

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:
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.
CA Easytrieve® Report Generator 11.6

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

• 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
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

• 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.

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:
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.
CA Easytrieve® Report Generator 11.6

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.
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


storage (MAX).
This is the default. This is the default.

Y 16-4096 Specifies the amount of storage (in


kilobytes) released after the MAX
This is the default. 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.
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.

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.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

• 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:
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.
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.
CA Easytrieve® Report Generator 11.6

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.

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:
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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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
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:
CA Easytrieve® Report Generator 11.6

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

• 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.
CA Easytrieve® Report Generator 11.6

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

• 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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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

• 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
CA Easytrieve® Report Generator 11.6

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.
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.

International Options
This article describes the international options that you can specify in the options table:
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.
CA Easytrieve® Report Generator 11.6

• 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.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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.rptSYSPRINT=\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.

5 Getting Started
Tutorial and overview of program sections.
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
CA Easytrieve® Report Generator 11.6

• 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:
• 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.

Figure 3: easytrieve_program
CA Easytrieve® Report Generator 11.6

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.
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 ...
...
CA Easytrieve® Report Generator 11.6

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

DEPT EMPNAME EMP# GROSS

903 WIMN 12267 373.60


943 BERG 11473 759.20
915 CORNING 02688 146.16
935 NAGLE 00370 554.40
CA Easytrieve® Report Generator 11.6

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
The CA Easytrieve tutorial includes four lessons:
The CA Easytrieve tutorial includes four lessons:

Lesson 1 - Library Section, FILE and DEFINE Statements


In this lesson, we show you a sample 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.
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


CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

DEFINE GROSS 94 4 P 2

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
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 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.
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.
Although you can control input, CA Easytrieve can also provide automatic input capability.
Automatic Input
CA Easytrieve® Report Generator 11.6

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
DEDUCTIONS = .28 * GROSS
NET-PAY = GROSS - DEDUCTIONS
CA Easytrieve® Report Generator 11.6

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
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.
CA Easytrieve® Report Generator 11.6

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.
This lesson introduces the PRINT statement. The PRINT statement activates the report statements that result in a printed
report.
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
CA Easytrieve® Report Generator 11.6

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'
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.
CA Easytrieve® Report Generator 11.6

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
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.
CA Easytrieve® Report Generator 11.6

• 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.
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
CA Easytrieve® Report Generator 11.6

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 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.
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.
CA Easytrieve® Report Generator 11.6

There are six report definition statements in CA Easytrieve. When used, they must occur after the REPORT statement in the
following order:
• 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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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
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.
CA Easytrieve® Report Generator 11.6

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

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


CA Easytrieve® Report Generator 11.6

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.
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 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.
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
CA Easytrieve® Report Generator 11.6

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'

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:
CA Easytrieve® Report Generator 11.6

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 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:
CA Easytrieve® Report Generator 11.6

, 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'

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 ezt program must be described
before they are referenced.
CA Easytrieve® Report Generator 11.6

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.
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).
CA Easytrieve® Report Generator 11.6

• 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):
• 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
CA Easytrieve® Report Generator 11.6

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.
CA Easytrieve® Report Generator 11.6

These types of data can have decimal positions:


• 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
CA Easytrieve® Report Generator 11.6

* 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.
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
CA Easytrieve® Report Generator 11.6

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-

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)


CA Easytrieve® Report Generator 11.6

| 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
... | *
| 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
CA Easytrieve® Report Generator 11.6

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:

# 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.
CA Easytrieve® Report Generator 11.6

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'

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
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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
*
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.
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.
This section contains the following articles:

JOB Activities
2

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
CA Easytrieve® Report Generator 11.6

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
*

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 #
CA Easytrieve® Report Generator 11.6

|
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:

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
CA Easytrieve® Report Generator 11.6

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
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 )
CA Easytrieve® Report Generator 11.6

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

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:
CA Easytrieve® Report Generator 11.6

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 = TRUE
'GA'
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 = FALSE
'FL'
IF (DIVISION = 'A' OR AMOUNT = 15) AND STATE = FALSE
'FL'

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| | + |
[ ] [ ]

Parentheses in Calculations
CA Easytrieve® Report Generator 11.6

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
CA Easytrieve® Report Generator 11.6

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.
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 |
CA Easytrieve® Report Generator 11.6

[ 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

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.
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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
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.
CA Easytrieve® Report Generator 11.6

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 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:
CA Easytrieve® Report Generator 11.6

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 }
[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.
CA Easytrieve® Report Generator 11.6

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


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:
CA Easytrieve® Report Generator 11.6

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

ORDER = 'NO'
END-PROC
CODE2-RTN. PROC
ORDER = 'YES'
END-PROC

Nesting PROCs
CA Easytrieve® Report Generator 11.6

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.
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:
CA Easytrieve® Report Generator 11.6

• 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
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
CA Easytrieve® Report Generator 11.6

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
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 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] ...) +
CA Easytrieve® Report Generator 11.6

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 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 +


CA Easytrieve® Report Generator 11.6

USING (sort-key-field-name [D] ... ) +

NAME sort-name +

[BEFORE proc-name]

• 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.
CA Easytrieve® Report Generator 11.6

PROGRAM Activities
You can use a PROGRAM activity for simple processing activities or to control the execution of JOB,
SORT, and SCREEN 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:

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}


CA Easytrieve® Report Generator 11.6

• {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 ezt (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.
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:

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
CA Easytrieve® Report Generator 11.6

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:
• 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:
CA Easytrieve® Report Generator 11.6

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:
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:
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.
CA Easytrieve® Report Generator 11.6

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

[ ] [ ]

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
CA Easytrieve® Report Generator 11.6

• 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

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)


CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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

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' }
CA Easytrieve® Report Generator 11.6

• 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 **

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.
CA Easytrieve® Report Generator 11.6

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
END-IF

WRITE Format 2
CA Easytrieve® Report Generator 11.6

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 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.
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:
CA Easytrieve® Report Generator 11.6

<######################LINESIZE######################>

######################################################
# 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:
CA Easytrieve® Report Generator 11.6

Statements:

FILE PERSNL FB(150 1800)


DEPT W 3 N VALUE '903'
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
CA Easytrieve® Report Generator 11.6

HEADING
HEADING Heading

HEADING HEADING Area

HEADING HEADING HEADING

line line literal line


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


CA Easytrieve® Report Generator 11.6

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 ...þ
...

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.
CA Easytrieve® Report Generator 11.6

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.
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:
• 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 +
CA Easytrieve® Report Generator 11.6

[PAGESIZE nn] [LINESIZE nn] +


[SKIP nn] [SPACE nn] +
[TITLESKIP nn] +

É ù Spacing

êSPREAD ú Control

êNOSPREAD ú + Parameters

ë û

[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
CA Easytrieve® Report Generator 11.6

EMPLOYEE
NAME EMP# DEPT GROSS

WIMN 12267 903 $373.60

EXAMPLE PROGRAM

EMPLOYEE
NAME EMP# DEPT GROSS

BERG 11473 943 $759.20

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
CA Easytrieve® Report Generator 11.6

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 ú
ë û ë û

• 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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

$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

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.
CA Easytrieve® Report Generator 11.6

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 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:
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.
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


CA Easytrieve® Report Generator 11.6

The following program creates the label report shown:

FILE PERSNL FB (150 1800)


NAME 17 8 A
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
CA Easytrieve® Report Generator 11.6

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.
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]
[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.
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. For more information, see Processing of Reports.

FILE FILE1
LAST-NAME 1 5 A
CA Easytrieve® Report Generator 11.6

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.) 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.
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

Data:

BROWNIL6007612345 BROWNIL6007667890 JONESIL6007709876 JONESIL6007754321 SMI

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 to produce 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)


CA Easytrieve® Report Generator 11.6

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
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
PRINT
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
CA Easytrieve® Report Generator 11.6

[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
*

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.
CA Easytrieve® Report Generator 11.6

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 .
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

• 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
CA Easytrieve® Report Generator 11.6

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:

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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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:

01/31/91 THIS REPORT WILL ILLUSTRATE USE OF PAGE 1


CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

SMITHTX7521866666

Produce:

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. 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
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

Data:

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
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
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:

BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
CA Easytrieve® Report Generator 11.6

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:

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
CA Easytrieve® Report Generator 11.6

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

* EMPLOYEE BROWN EXCEEDED WEEKLY SALARY GOAL *

BROWN IL 60076 123.45


IL 60076 802.35
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

System-Defined Fields
System-defined fields are fields that 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.
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.
This section includes the following articles:

General Purpose Fields


ezt automatically provides the following system-defined fields for general use:
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).
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
CA Easytrieve® Report Generator 11.6

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


ezt automatically provides the following system-defined fields for each of your files:
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:
• 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).
CA Easytrieve® Report Generator 11.6

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.
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


ezt automatically provides the following system-defined fields for report generating:
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.
CA Easytrieve® Report Generator 11.6

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


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.

6 Using
Create a report, compile, link, and execute a program, and use the Workbench.
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 ezt:
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.
CA Easytrieve® Report Generator 11.6

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))+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
CA Easytrieve® Report Generator 11.6

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.
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:
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.
CA Easytrieve® Report Generator 11.6

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

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.
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

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 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.
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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


This section contains the following articles that describe how to compile and link your program:
This section contains the following articles that describe how to compile and link your program:

Controlling Compilation
You can control the compilation of your program using the following statements:
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 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.
CA Easytrieve® Report Generator 11.6

• 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.
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 ezt program, your source code is converted to object code. A compilation results
listing is also produced.
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.
CA Easytrieve® Report Generator 11.6

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.
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


1userid your company namePrograms 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)
CA Easytrieve® Report Generator 11.6

Macro name
• (b)
Statement number
• (c)
Statement
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)
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
CA Easytrieve® Report Generator 11.6

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 . 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 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.
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
//*********************************************
CA Easytrieve® Report Generator 11.6

//************** 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
//EZTVFM DD UNIT=SYSDA,SPACE=(4096,(100,100))
CA Easytrieve® Report Generator 11.6

//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)
CA Easytrieve® Report Generator 11.6

//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
// 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
CA Easytrieve® Report Generator 11.6

//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 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),
CA Easytrieve® Report Generator 11.6

// 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:

//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
CA Easytrieve® Report Generator 11.6

//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
//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
CA Easytrieve® Report Generator 11.6

// 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
//* (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,
CA Easytrieve® Report Generator 11.6

//
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
CA Easytrieve® Report Generator 11.6

// 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,
//
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=*
CA Easytrieve® Report Generator 11.6

//
**********************************************************

//
*

//* 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;
CA Easytrieve® Report Generator 11.6

/
*

//* 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
//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
CA Easytrieve® Report Generator 11.6

// 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
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.
CA Easytrieve® Report Generator 11.6

Submitting Your Program for Non-Mainframe Compilation


To submit your program for compilation on a non-mainframe platform, perform the following steps:
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:
• 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
CA Easytrieve® Report Generator 11.6

-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.
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)
CA Easytrieve® Report Generator 11.6

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)
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.
CA Easytrieve® Report Generator 11.6

• 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)
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 ezt 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:
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.
CA Easytrieve® Report Generator 11.6

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.
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 y

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.
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

• 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)
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.
CA Easytrieve® Report Generator 11.6

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 )
{
...
}
...
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


...
CA Easytrieve® Report Generator 11.6

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.
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:
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.
For more information, see the following articles:
CA Easytrieve® Report Generator 11.6

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.
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. For more information, see Compile and Link Your Program.
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.
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.
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.
CA Easytrieve® Report Generator 11.6

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.
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:

//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


CA Easytrieve® Report Generator 11.6

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
ezt to locate and recognize the file. You can supply the file description string using either of the following
methods:
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:


CA Easytrieve® Report Generator 11.6

set EMPLOYEE=file-description-string

For more information about how to set the variable, see The Environment Manager Utility.
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
CA Easytrieve® Report Generator 11.6

Installable C-ISAM Indexed File Z CISAM


System (UNIX and Linux for zSeries
only)
Installable Btrieve Indexed File System Z EXIT(CARFSWBT)
(Windows only)

Execute a Windows Indexed File Program


In Windows, uses an internal Indexed File Access method.
In Windows, CA Easytrieve® Report Generator uses an internal Indexed File Access method.
Contents

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. For more information, see File Description String (Non-Mainframe Only).
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.
CA Easytrieve® Report Generator 11.6

For example, specify the following to indicate that the file has one primary and two alternate keys.:

B = 4I = (512 / 4) + 3 * 16I = 128 + 48I = 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

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, supports the Btrieve file system as an installable file system [Z]. You must have access to
the Btrieve product from Pervasive Software, Inc.
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
CA Easytrieve® Report Generator 11.6

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. For more information, see File Description String (Non-Mainframe Only).
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
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, supports the C-ISAM file system as an installable file system [Z]. uses
the standard C-ISAM libraries. You must have access to the C-ISAM product from IBM Inc. If your
CA Easytrieve® Report Generator 11.6

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.
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

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. For more information, see File Description String (Non-Mainframe Only).
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.logexport 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 ezt 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.
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:
CA Easytrieve® Report Generator 11.6

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.
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
bottom (or top) of the panel.
CSR

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
CA Easytrieve® Report Generator 11.6

+ indicates more report lines forward or below

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
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
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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.
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:
CA Easytrieve® Report Generator 11.6

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 DECI
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
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.
CA Easytrieve® Report Generator 11.6

Execute a Program on a Web Server


This section describes how to 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 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


CA Easytrieve® Report Generator 11.6

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").
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));
CA Easytrieve® Report Generator 11.6

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.
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>
CA Easytrieve® Report Generator 11.6

<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
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.
CA Easytrieve® Report Generator 11.6

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.

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
CA Easytrieve® Report Generator 11.6

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 = ' '
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
CA Easytrieve® Report Generator 11.6

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.
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.
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:
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

// 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:

// 0 1 2 3 4 5 6 7 8 9 A B C D E F
.
.
.
0x30313233 0x34353637 0x38393A3B 0x3C3D3E3F // 3
.
.
.
CA Easytrieve® Report Generator 11.6

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:
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. For more information, see Configuration Manager.
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:

Figure 7: Printer Definition Components

Printer Support
CA Easytrieve® Report Generator 11.6

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.
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
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
CA Easytrieve® Report Generator 11.6

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:

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
CA Easytrieve® Report Generator 11.6

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.

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.
CA Easytrieve® Report Generator 11.6

• 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
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)
CA Easytrieve® Report Generator 11.6

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
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.
CA Easytrieve® Report Generator 11.6

Figure 10: Seven Categories of Printers

Basic Printing
CA Easytrieve® Report Generator 11.6

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.
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


CA Easytrieve® Report Generator 11.6

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:

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
CA Easytrieve® Report Generator 11.6

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

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.
CA Easytrieve® Report Generator 11.6

• 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.

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.
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)


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.
CA Easytrieve® Report Generator 11.6

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.
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.
Print Data
The format of print data that contains both overprint and function codes are illustrated below:
CA Easytrieve® Report Generator 11.6

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.
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)


CA Easytrieve® Report Generator 11.6

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 uses to generate the correct print data set for the
appropriate extended reporting printer. The three types of printer characteristics are:
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:

Printer Type
CA Easytrieve® Report Generator 11.6

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).

Figure 21: Printer Type

Page Printers
CA Easytrieve® Report Generator 11.6

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.
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
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:
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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.

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.
CA Easytrieve® Report Generator 11.6

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.

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.

Figure 27: Data Format prior Combination onto Single Print Line
CA Easytrieve® Report Generator 11.6

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.

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.
CA Easytrieve® Report Generator 11.6

Figure 29: Data format prior to Being Combined

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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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
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).
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:
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.
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
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

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.
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.
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).
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.
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:
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.
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 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
CA Easytrieve® Report Generator 11.6

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.
CA Easytrieve® Report Generator 11.6

Figure 39: Two Line Line Complex


CA Easytrieve® Report Generator 11.6

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:
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:
• 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.
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
CA Easytrieve® Report Generator 11.6

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.
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:
CA Easytrieve® Report Generator 11.6

• 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.
• 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 ezt
programs.
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
CA Easytrieve® Report Generator 11.6

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


For information about using the Workbench, see the following articles:

Main Window
The main window in a 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:
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 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
CA Easytrieve® Report Generator 11.6

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.
• 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
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

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.
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.
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.)

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 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:
CA Easytrieve® Report Generator 11.6

• 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.
• 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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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:
• 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.
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:
CA Easytrieve® Report Generator 11.6

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.
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.
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. 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.
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:
• 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.
CA Easytrieve® Report Generator 11.6

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.
• 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.
CA Easytrieve® Report Generator 11.6

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.
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.
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.
CA Easytrieve® Report Generator 11.6

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 program. To modify the default behavior,
select the Program Profile menu.
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:
• 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 11.6

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 Changing the Color of Compile Errors.
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.
Compile a Single Program
Follow these steps:
1. Open the source file.
2. Do one of the following:
• For programs within an application:
1.1 Select File, Application, Edit. The Edit Application dialog appears.
2.1 In the lower list box, double-click the files you want to open and click OK.
• When not working within an application:
1.1 Use the File Open dialog to open the source file.
2.1 Select the source file you want to build.
3.1 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.
CA Easytrieve® Report Generator 11.6

2. Click the Step Into debug-button or select the Debug menu and choose Go.

Debug Programs
This section explains how to debug your programs using the debugger. The Debugger uses a Windows
interface for visual presentation while the program itself runs in separate window.
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:
• 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
CA Easytrieve® Report Generator 11.6

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
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.
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.
CA Easytrieve® Report Generator 11.6

• 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
session has not been initiated.
(Light Blue)
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.
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.
CA Easytrieve® Report Generator 11.6

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
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:
CA Easytrieve® Report Generator 11.6

• 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:
• 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
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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.

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:
• 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
CA Easytrieve® Report Generator 11.6

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 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.
CA Easytrieve® Report Generator 11.6

Set Preferences
You can customize ezt to meet your requirements. The Options menu controls global options for the
entire ezt 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 ezt sessions.
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.
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.
CA Easytrieve® Report Generator 11.6

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.
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:
CA Easytrieve® Report Generator 11.6

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
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 lets Windows users create, view, and modify the Options Table
and Printer Set Definition (PSD).
The Configuration Manager tool in the Workbench lets Windows users create, view, and modify the Options Table and Printer
Set Definition (PSD).
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)
More Information:

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 ezt on
Windows NT, UNIX, Linux for zSeries, or z/OS.
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:
1.1 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.
2.1 Click the link in the left pane to display the options page you want to modify.
3.1 Select the appropriate options on the page. See the following sections for option details.
4.1 Click Apply to save the changes.
5.1 Repeat steps b through d for each option page.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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.
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:
CA Easytrieve® Report Generator 11.6

• 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.
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
ezt on the Windows NT, UNIX, Linux for zSeries, and z/OS.
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:
CA Easytrieve® Report Generator 11.6

1.1 Click the plus box for the printer you are defining to show the links. The links are dataset, defaults, fileheaders,
filetrailers, or fonts.
2.1 Click the link in the left pane to display the properties page you want to modify.
3.1 Define the attributes on the page.
4.1 Click Apply to save the changes.
5.1 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).
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.
CA Easytrieve® Report Generator 11.6

• 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
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:
CA Easytrieve® Report Generator 11.6

• 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:
• 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).
CA Easytrieve® Report Generator 11.6

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:
• 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
CA Easytrieve® Report Generator 11.6

• 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 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.
CA Easytrieve® Report Generator 11.6

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.
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
(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.
CA Easytrieve® Report Generator 11.6

• 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.
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 11.6

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

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,


CA Easytrieve® Report Generator 11.6

22, 24, 26, 28, 36, 48, and 72

The default font is font 8.

Workbench Tools and Utilities


This section provides descriptions of 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:
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 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
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:
CA Easytrieve® Report Generator 11.6

1.1 Display the list of pre-programmed file types (*.ezt, *.mac, *.lst) in the File Name combo box.
2.1 Select your file type
3.1 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.
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.
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

• 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.
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.
To abort a transfer
CA Easytrieve® Report Generator 11.6

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.
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
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.
CA Easytrieve® Report Generator 11.6

• 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.
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 ezt program
can be saved and reused. You can define a profile for a specific program or for an entire subdirectory.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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
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:
1.1 Click the variable.
The Add button changes to Remove.
2.1 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.
2. Define the text strings that are to be used as filters:
CA Easytrieve® Report Generator 11.6

1.1 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.
2.1 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:
• 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
ezt has several tools and utilities accessible from the File, Tools, and Options menus including:
CA Easytrieve Report Generator has several tools and utilities accessible from the File, Tools, and Options menus including:

Data Conversion Utility


CA Easytrieve® Report Generator 11.6

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
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')
CA Easytrieve® Report Generator 11.6

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

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.
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.
1.1 Make a selection from the Files of Type combo box.
2.1 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
CA Easytrieve® Report Generator 11.6

• 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.
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
CA Easytrieve® Report Generator 11.6

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.
Follow these steps:
1. Select Tools, Environment Manager.
2. To add a variable, do the following:
1.1 Click New to add an environment variable.
The New Environment Variable dialog is displayed.
2.1 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:
1.1 Click the variable.
2.1 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
CA Easytrieve® Report Generator 11.6

When you submit a job for execution, the values specified on the Submit tab of the Program Profile manager are used by this
utility.
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.
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:
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
CA Easytrieve® Report Generator 11.6

• 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 .
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 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.
CA Easytrieve® Report Generator 11.6

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:

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
CA Easytrieve® Report Generator 11.6

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:
• 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


CA Easytrieve® Report Generator 11.6

• 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.
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
CA Easytrieve® Report Generator 11.6

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.

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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

• 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
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.
CA Easytrieve® Report Generator 11.6

• 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".
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
CA Easytrieve® Report Generator 11.6

* 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$

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.
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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

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:
CA Easytrieve® Report Generator 11.6

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
CA Easytrieve® Report Generator 11.6

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:

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)
CA Easytrieve® Report Generator 11.6

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.
_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",'
CA Easytrieve® Report Generator 11.6

_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.
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 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 /Earl file exit program is an assembly program that performs two functions.
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, +
CA Easytrieve® Report Generator 11.6

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:
• -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® Report Generator 11.6

CA Easytrieve SDS
CA Easytrieve Simplified Design System (CA Easytrieve SDS) is a Windows application that you can
use to create CA Easytrieve reports.
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.
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.
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=*//
CA Easytrieve® Report Generator 11.6

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

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.
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:
CA Easytrieve® Report Generator 11.6

Import File and Field Definitions

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:
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.
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.
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.
CA Easytrieve® Report Generator 11.6

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:
1.1 Right-click in the top blue area of Easytrieve Report Painter and select Report properties.
2.1 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.
3.1 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 OFFPARM 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.

7 Programming
Programming reference for developers.
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.
This article shows the text conventions that are used in the syntax examples, and the rules for signed and unsigned fields.
CA Easytrieve® Report Generator 11.6

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:
• 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.
CA Easytrieve® Report Generator 11.6

• 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:
The organization of this section simulates the way an application program is developed. The basic application development
process steps are:
1. Design the program:
• 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 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.
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
CA Easytrieve® Report Generator 11.6

• 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

Program Sections
A program consists of the following main 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. For information about data
conversions, see Assigning and Moving Varying Length Fields.
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.
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
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.
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

(statements) Activity

(program procedures) Section

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.
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.
CA Easytrieve® Report Generator 11.6

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*
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
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.


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
CA Easytrieve® Report Generator 11.6

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 lengthW 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.
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 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
allows for any other field type. In order to allow an 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.
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
CA Easytrieve® Report Generator 11.6

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:

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
CA Easytrieve® Report Generator 11.6

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
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.
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
CA Easytrieve® Report Generator 11.6

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.
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


Describes rules for literals and data formatting.
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


CA Easytrieve® Report Generator 11.6

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:

'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
CA Easytrieve® Report Generator 11.6

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.
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


CA Easytrieve® Report Generator 11.6

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

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


CA Easytrieve® Report Generator 11.6

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 ezt program with the statements that are coded within
your activities.
You control the flow of execution through your CA Easytrieve Report Generator program with the statements that are coded
within your activities.
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.
CA Easytrieve® Report Generator 11.6

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]

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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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:
• 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.
CA Easytrieve® Report Generator 11.6

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
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.
CA Easytrieve® Report Generator 11.6

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
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'
CA Easytrieve® Report Generator 11.6

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
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.
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:
CA Easytrieve® Report Generator 11.6

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

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.
CA Easytrieve® Report Generator 11.6

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} {+}
{-}

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
in value-1 or value-2.
subtraction
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.
CA Easytrieve® Report Generator 11.6

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

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 }
CA Easytrieve® Report Generator 11.6

{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.
CA Easytrieve® Report Generator 11.6

Numeric field Numeric field, Result is padded on left with zeros to fit
the description of receive-field-name. If
literal, the value of the assignment is too large
to be stored in receive-field-name, it is
or arithmetic expression 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 Indicator for receive-field-name is set to
operands are NOT NULL 0.
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.
CA Easytrieve® Report Generator 11.6

Numeric, Resulting value of receive-field-name


is zoned decimal equivalent of send-
packed, field-name with each byte converted
into the DBCS equivalent. Before the
or binary field 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
the zoned decimal equivalent of send-
packed, field-name with padding or truncation
on left, if necessary.
or binary field
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:
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
CA Easytrieve® Report Generator 11.6

Results:

Resulting
Value

F1N = F2N1 + F2N2 + F2N3 = 6.0


(1 + 2 + 3)

F1N = F2N1 + F2N2 / F2N3 = 1.6


(1 + 2 / 3)
(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:
CA Easytrieve® Report Generator 11.6

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
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


CA Easytrieve® Report Generator 11.6

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:
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.
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.
CA Easytrieve® Report Generator 11.6

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.
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:
CA Easytrieve® Report Generator 11.6

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.
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

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
CA Easytrieve® Report Generator 11.6

ARRAY-ELEMENT = 11
MONTH-INDEX = (ARRAY-ELEMENT - 1) * 10
DISPLAY MONTH
STOP

Results:

NOVEMBER

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- MONTH- MONTH ROW-INDEX-1 COL-INDEX-2 MONTH-CELL


INDEX-1 INDEX-2
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
CA Easytrieve® Report Generator 11.6

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 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
CA Easytrieve® Report Generator 11.6

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 +
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
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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).
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 +
CA Easytrieve® Report Generator 11.6

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)
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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

* . * 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
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
CA Easytrieve® Report Generator 11.6

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'
TITLE 2 'INPUT FIELD FORMAT IS:'
TITLE 3 'LAST-NAME,FIRST-NAME'
LINE REVERSED-NAME DATA-NAME
END

Inter-Program Linkage
The facilities of provide all of the functions necessary to perform standard input/output, data examination,
and data manipulation.
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.
CA Easytrieve® Report Generator 11.6

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

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.
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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:

...
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
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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
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
. . .
CA Easytrieve® Report Generator 11.6

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';
}

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.
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.

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:
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.
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.
CA Easytrieve® Report Generator 11.6

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
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 */
CA Easytrieve® Report Generator 11.6

#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 */
/* 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 */
CA Easytrieve® Report Generator 11.6

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 */
CA Easytrieve® Report Generator 11.6

# 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 */
#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;
CA Easytrieve® Report Generator 11.6

} 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
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).
CA Easytrieve® Report Generator 11.6

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.
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 system ("routine_name using_data")
zSeries, 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.
CA Easytrieve® Report Generator 11.6

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.
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 execl ("/bin/sh", "routine_name
zSeries, Windows) using_data", 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
CA Easytrieve® Report Generator 11.6

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. 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 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.
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.
CA Easytrieve® Report Generator 11.6

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 programs in a CICS environment:
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 Units of Work and Commit Processing.
• 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.

Multiple Platform Considerations


In addition to specific rules for how ezt works on different platforms, tips for migrating programs to non-
mainframe environments or when you have source that can run on multiple platforms follow:
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.
CA Easytrieve® Report Generator 11.6

• 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


ezt provides optional processing facilities for SQL databases. The following SQL databases are
supported:
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:
• 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:
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
CA Easytrieve® Report Generator 11.6

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
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 ezt:
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
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:
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.
CA Easytrieve® Report Generator 11.6

• 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 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.
CA Easytrieve® Report Generator 11.6

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 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.
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.

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.
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:
CA Easytrieve® Report Generator 11.6

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.
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 xPy N N N
DECIMAL (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
CA Easytrieve® Report Generator 11.6

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 xNy N N N
NUMERIC (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 M VARYING Y N N
(x)
x K VARYING

(x > 254)
DATE 10 A *2 Y Y Y
TIME 8A Y Y Y
TIMESTAMP 26 A Y Y Y
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 xPy Y N N
DECIMAL (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
CA Easytrieve® Report Generator 11.6

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 xNy Y N N
NUMERIC (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 M VARYING Y N N
(x)
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 - - -

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
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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)
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)
CA Easytrieve® Report Generator 11.6

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

CA Easytrieve SQL Files


In this method of processing SQL, ezt automates cursor management by associating an SQL cursor with
a ezt file.
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
CA Easytrieve® Report Generator 11.6

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.
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:
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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


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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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 files.
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

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
CA Easytrieve® Report Generator 11.6

• 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

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 +
CA Easytrieve® Report Generator 11.6

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 section.
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.
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.
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

LINE EMPNAME WORKDEPT EMPPHONE

ODBC Data Sources


You can use a to access your ODBC data sources. Because of the processing performed, there are
limitations on the activities you can use with 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 program using ODBC.
Generally, the file supports read access and insert processing only. For more information, see your ODBC
documentation.
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.
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
CA Easytrieve® Report Generator 11.6

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
PRINT
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 program using ODBC.
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.
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:
1.1 Highlight all the rows and columns that are to be part of the SQL table.
2.1 From the Insert dropdown menu, select Name, Define. The Define Name dialog opens.
3.1 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:
1.1 Highlight an entire column by clicking on the Excel-generated column heading.
2.1 From the Insert dropdown menu, select Name, Define. The Define Name dialog opens, showing the default name you
entered for this column in Step
3.1 Click OK to use the default name.
4.1 Repeat for each column.
5. Define the data format for each column:
CA Easytrieve® Report Generator 11.6

1.1 Highlight an entire column by clicking on the Excel-generated column heading.


2.1 From the Format dropdown menu, select Cells. The Format Cells dialog opens.
3.1 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:
1.1 From the Windows Start menu, select Settings, Control Panel, Administrative Tools, Data Sources (ODBC). The
ODBC Data Source Administrator dialog opens.
2.1 Under the User DSN tab, click Add… and then select Microsoft Excel Driver (*.xls).
3.1 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


provides optional processing facilities that interface with CA IDMS databases and with the CA IDMS
Integrated Data Dictionary (IDD).
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
JOB INPUT (file-name-1) ...

Automatic Input
-------------
| |
RETRIEVE file-name-1 ... ---------------->| <IDMS> |
| |
| |
(<idms> records in <----------| | |
path form for automatic input) | |
... -------------

Controlled Processing
-------------
CA Easytrieve® Report Generator 11.6

| |
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.

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.
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.
CA Easytrieve® Report Generator 11.6

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
DEFINE IDMSEREC IDMSCOM + 64 16 A
DEFINE IDMSEAREA IDMSCOM + 80 16 A
DEFINE IDMSPGINFO IDMSCOM + 96 4 B 0,
MASK HEXDEFINE IDMSPGGRP IDMSCOM + 96 2 B 0, MASK HEXDEFINE
IDMSPGDBK IDMSCOM + 98 2 B 0, MASK HEXDEFINE IDMSCON
IDMSCOM + 96 1 A, OCCURS 100, INDEX IDMSCON-INDEXDEFINE
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
CA Easytrieve® Report Generator 11.6

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 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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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 +
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
CA Easytrieve® Report Generator 11.6

... (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.
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
CA Easytrieve® Report Generator 11.6

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.
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


ITEMPRODUCT 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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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.

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
CA Easytrieve® Report Generator 11.6

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:
• 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.
CA Easytrieve® Report Generator 11.6

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
*
* 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)
CA Easytrieve® Report Generator 11.6

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'
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
CA Easytrieve® Report Generator 11.6

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'
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
CA Easytrieve® Report Generator 11.6

* 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) +
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
CA Easytrieve® Report Generator 11.6

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 ezt and the CA IDMS Integrated Data Dictionary (IDD) is accomplished by the use
of IDD statements.
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
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.
CA Easytrieve® Report Generator 11.6

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:

[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
CA Easytrieve® Report Generator 11.6

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:
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.
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
CA Easytrieve® Report Generator 11.6

--------------- --------------- ------------


CUSTOMER-REGION ORDER-REGION ORDER-
REGION

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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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.

ADD PATH-GROUP STORE CUST-SALES-


LR

SELECT
STORE SALES.

Logical Record Definition


CA Easytrieve® Report Generator 11.6

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 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.
CA Easytrieve® Report Generator 11.6

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)

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 Test Database Structure.
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.
CA Easytrieve® Report Generator 11.6

Figure 45: Test Database Structure

PCB and PSB Processing


ezt uses the Call DLI interface to access an IMS/DLI database. ASMTDLI is statically linked with
your ezt program when you run a batch compile. For more information about program linkage, see the
section.
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.
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.
CA Easytrieve® Report Generator 11.6

Automatic Input
Automatic input is a facility whereby ezt 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.
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:
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
CA Easytrieve® Report Generator 11.6

STATUS-
CODE 11 2 A
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)
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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

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 +
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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.
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.
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
CA Easytrieve® Report Generator 11.6

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'
CA Easytrieve® Report Generator 11.6

END-
PROC
TERMPSB. PROC
DLI TERM
END-
PROC.

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 ...'
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

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, +
...)
CA Easytrieve® Report Generator 11.6

END-
PROC
TEST-
STATUS. PROC
IF FILE-
STATUS ...
...
END-
IF
END-
PROC.
...
...

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
CA Easytrieve® Report Generator 11.6

END-
PROC
...

...

IMS Fast Path DEDB Processing


IMS Fast Path DEDBs can be processed by ezt programs.
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 F99DRECORD F99DS1 20 F99DS1K 1 10 A F99DF1D 11


10 ARECORD F99DS2 20 F99DS1 F99DS2K 1 10 A F99DF2D 11 10 ARECORD
F99DS3 20 F99DS1 F99DS3K 1 10 A F99DF3D 11 10 A*DEFINE IMSSTAT
W 8 A*JOB INPUT FPDEDB FINISH TERM-PROCRETRIEVE FPDEDB + SELECT
( F99DS1 ID 'S1' + F99DS2 ID 'S2' + F99DS3 ID
'S3' )DISPLAY F99DS1K ' ' PATH-ID
TERM-PROC. PROC DLI CHKP IMSSTATDISPLAY HEX CHKP-STATUSEND-PROC

CA Datacom/DB Database Processing


The CA Datacom/DB interface option lets you access your CA Datacom/DB database.
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.
CA Easytrieve® Report Generator 11.6

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.
You can access the database with automatic processing or controlled processing, using control macros similar to statements
used in COBOL.
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:
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.
Generating Calls
CA Easytrieve® Report Generator 11.6

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 Automatic only Library section
FILE statement
%DBLREQ Provide Direct Request Controlled only Activity section
Interface 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 Controlled only Activity section
Interface 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
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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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. See Controlled
Processing Examples 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.
Syntax

%DBFILE prfx wrk-area-sz [START strt-val]


CA Easytrieve® Report Generator 11.6

• 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

Usage Notes
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

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

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.
CA Easytrieve® Report Generator 11.6

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 ' '
* 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 '
CA Easytrieve® Report Generator 11.6

' *
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.
Lines 2 and 3 define two other standard parameter areas: the Request Area (RA) and the Element List (EL).
CA Easytrieve® Report Generator 11.6

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


CA Easytrieve® Report Generator 11.6

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).
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
CA Easytrieve® Report Generator 11.6

* 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 ' '
* 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
CA Easytrieve® Report Generator 11.6

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.
*
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
CA Easytrieve® Report Generator 11.6

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 files41 POH-KEY-VAL = X'0000000000' . *
Set initial key value 42 %DBSREQ POH LOCKY . * Locate the
key => start value 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.
CA Easytrieve® Report Generator 11.6

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:
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. 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
CA Easytrieve® Report Generator 11.6

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 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
CA Easytrieve® Report Generator 11.6

VFLD2 * 10 A
FILE VFILEOUT VB(20 200)
JOB INPUT VFILE
VFILEOUT:RECORD-LENGTH = VFILE:RECORD-LENGTH
PUT VFILEOUT FROM VFILE

File Processing Modes


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. file
processing modes are:
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:
• 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
CA Easytrieve® Report Generator 11.6

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 ***

File type must be specified


(none)
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.
See Units of Work and Commit Processing for more information.
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.
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
supports the access of all sequential files that the operating environment in which is running also
supports.
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 11.6

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:

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
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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.
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:
• 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
CA Easytrieve® Report Generator 11.6

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
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, supports the following index access methods:
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
DISPLAY 'FILE-STATUS= ', KSDS:FILE-STATUS
STOP
END-IF
END-PROC

Skip-Sequential Processing

FILE VSAM INDEXED


%PERSNL
JOB INPUT VSAM NAME MYPROG
CA Easytrieve® Report Generator 11.6

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.
Adding a Single Record

FILE PERSNL INDEXED UPDATE


%PERSNL
FILE INKEYS
CA Easytrieve® Report Generator 11.6

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
CA Easytrieve® Report Generator 11.6

You can use the WRITE statement to delete individual records from an indexed file. The deleted record is the file's current
input record.

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
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, supports the following relative access methods:
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

DISPLAY 'FILE-STATUS= ' FILE-STATUS


END-IF
END-PROC
*
REPORT REPORT1 LINESIZE 65
LINE EMP# EMPNAME

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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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

Sorting Files
You can use the SORT statement to sort files. ezt can sort any file that can be processed sequentially.
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
CA Easytrieve® Report Generator 11.6

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

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.
CA Easytrieve® Report Generator 11.6

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 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:
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
CA Easytrieve® Report Generator 11.6

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
...
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
CA Easytrieve® Report Generator 11.6

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
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 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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
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


CA Easytrieve® Report Generator 11.6

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.

PRINTER Files
enables you to create files with a device type of PRINTER to write printed output with the REPORT and/
or DISPLAY statements. See for information about output creation. A PRINTER file can be directed to
one of the following destinations:
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'.
CA Easytrieve® Report Generator 11.6

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.
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.
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*
CA Easytrieve® Report Generator 11.6

• 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.
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 ezt programs is to produce printed reports. The non-procedural nature of ezt
report syntax is readily adaptable to the production of basic and extremely complex reports, both with
minimum programming effort. Two statements generate printed output:
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:
CA Easytrieve® Report Generator 11.6

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.

PRINT Statement (Report Processing)


The PRINT statement activates the report logic that is defined by REPORT declarations. ezt 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:
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 JOB INPUT FILE1 NAME MYPROG PRINT
REPORT1 *
REPORT REPORT1 LINESIZE 65 + DTLCTL EVERY
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

Figure 50: PRINT Work File Processing

Report Formats

There are two basic report formats:

Standard Report
The CA Easytrieve® Report Generator default report format is the standard format illustrated below:
CA Easytrieve® Report Generator 11.6

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.
Label Report
The second report format is used to print labels. The following exhibit illustrates the basic label report page format:
CA Easytrieve® Report Generator 11.6

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 ezt 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 section.
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 ...
...
PRINT ...
...
REPORT
CA Easytrieve® Report Generator 11.6

{ 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.

Standard Reports
The report facility in includes all of the functions necessary to produce most reports very easily. Using
report options, you can produce a report in almost any format. Most reports, however, are variations of a
standard report.
CA Easytrieve® Report Generator 11.6

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
TITLE 01 'TEMPORARY EMPLOYEES'
TITLE 03 'IN DEPARTMENT' DEPT
LINE 01 ' '
CA Easytrieve® Report Generator 11.6

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 ' '
CA Easytrieve® Report Generator 11.6

Results:

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
CA Easytrieve® Report Generator 11.6

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

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)


CA Easytrieve® Report Generator 11.6

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'
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:
CA Easytrieve® Report Generator 11.6

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
............... ...............
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
CA Easytrieve® Report Generator 11.6

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:

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 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:
CA Easytrieve® Report Generator 11.6

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


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
CA Easytrieve® Report Generator 11.6

Results:

xxx xxx xxx xxx


xxx xxx xxx xxx
xxx xxx xxx xxx

xxx
xxx
xxx

(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 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.
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.
CA Easytrieve® Report Generator 11.6

• 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
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>
CA Easytrieve® Report Generator 11.6

</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 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.

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.
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.
CA Easytrieve® Report Generator 11.6

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:

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:
CA Easytrieve® Report Generator 11.6

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

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.
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
SEQUENCE STATE ZIP LAST-
NAME
CONTROL STATE ZIP
LINE 01 LAST-NAME STATE ZIP PAY-
NET

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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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
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


CA Easytrieve® Report Generator 11.6

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
LAST-NAME 1 5 A
STATE 6 2 A
ZIP 8 5 N
PAY-NET 13 5 N 2
JOB INPUT FILE1 NAME MYPROG
CA Easytrieve® Report Generator 11.6

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


CA Easytrieve® Report Generator 11.6

FINAL total TX 75218 2222.09

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
CA Easytrieve® Report Generator 11.6

STATE total 1444.32

SMITH TX 75218 666.66


SMITH 111.11
ZIP total 777.77

STATE total 777.77

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
CA Easytrieve® Report Generator 11.6

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
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
*
CA Easytrieve® Report Generator 11.6

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


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
CA Easytrieve® Report Generator 11.6

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

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
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 +
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
CA Easytrieve® Report Generator 11.6

2222.09

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


CA Easytrieve® Report Generator 11.6

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*

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
CA Easytrieve® Report Generator 11.6

LINE 01 LAST-NAME STATE ZIP T-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 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:
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 .* (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
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
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

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

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 to satisfy this requirement.
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.
CA Easytrieve® Report Generator 11.6

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)
total IL 60076 802.35
(AFTER-
BREAK

(BEFORE-LINE)
detail IL 60077 543.21
CA Easytrieve® Report Generator 11.6

(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:
• 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
CA Easytrieve® Report Generator 11.6

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:

TESTA
TESTB
TESTC
CA Easytrieve® Report Generator 11.6

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:

FILE FILE1
LAST-
NAME 1 5 A
STATE 6 2 A
CA Easytrieve® Report Generator 11.6

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
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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 *
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
CA Easytrieve® Report Generator 11.6

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:

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:
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

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
CA Easytrieve® Report Generator 11.6

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

Data:

BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
SMITHTX7521866666

Results:

...
* CONFIDENTIAL - FOR INTERNAL USE ONLY *
..................................................
CA Easytrieve® Report Generator 11.6

...

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:

BROWNIL6007612345
BROWNIL6007667890
JONESIL6007709876
JONESIL6007754321
SMITHTX7521811111
CA Easytrieve® Report Generator 11.6

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 ezt 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.
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
CA Easytrieve® Report Generator 11.6

JOB INPUT FILE1 NAME MYPROG


IF ZIP EQ 60076, 60077
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:
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.
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


CA Easytrieve® Report Generator 11.6

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
GROSS 94 4 P 2
FILE PRINTFIL01 EXTENDED HTML

JOB INPUT PERSNL NAME BASIC


PRINT
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.
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
CA Easytrieve® Report Generator 11.6

• 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.
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


02 Detail by Branch -- Descending Gross Pay
03
04 Social Current Pay Raise
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
09 9331 CAROLINE AVENU 279.56
10 SEATTLE WA 98003
11

12 558-44-7609 10961 RYAN PAMELA 399.20 7.00


13 1717 R N W # 301 219.70
14 SEATTLE WA 98009
15

16 577-58-0363 05482 WARD MARINA 183.75 7.00


17 1725 H ST NE APT 2 141.47
18 SEATTLE WA 98015
19

20 01 1,043.75 7.67
21 640.73
22
23

24 02 484-30-8293 06239 JOHNSON LISA 712.80 7.00


25 806 CONNECTICUT AVE 451.92
26 SAN DIEGO CA 92045
27

28 104-20-0956 09764 HAFER ARTHUR 121.95 9.00


29 806 CONNECTICUT AVE 96.64
30 SAN DIEGO CA 92041
31

32 02 834.75 8.00
33 548.56
CA Easytrieve® Report Generator 11.6

34
35

36 03 060-26-8978 10949 JONES ALFRED 804.80 9.00


37 2070 BELMONT ROAD N 560.63
38 LOS ANGELES CA 90052
39

40 537-03-4039 11211 WALTERS KAREN 424.00 7.00


41 1022 S KENSINGTON P 282.45
42 LOS ANGELES CA 90030
43
44 03 1,228.80 8.00
45 843.08

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.
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.
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.
CA Easytrieve® Report Generator 11.6

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 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.
CA Easytrieve® Report Generator 11.6

• 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:
• 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.
CA Easytrieve® Report Generator 11.6

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.
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:
• 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.
CA Easytrieve® Report Generator 11.6

• 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.
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.
CA Easytrieve® Report Generator 11.6

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.

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:
CA Easytrieve® Report Generator 11.6

• 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:

• 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:
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:
CA Easytrieve® Report Generator 11.6

Report Layout Processing


You request printed output from a program by using either the TITLE, LINE or DISPLAY statements.
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,
builds the print records that produce the correct lines.
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)

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:
CA Easytrieve® Report Generator 11.6

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.
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.
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.
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.
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
CA Easytrieve® Report Generator 11.6

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


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.
CA Easytrieve® Report Generator 11.6

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 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.
CA Easytrieve® Report Generator 11.6

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.
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.

<easy> Program
FILE
(library section)
CA Easytrieve® Report Generator 11.6

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.
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
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
CA Easytrieve® Report Generator 11.6

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
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 section.
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 DEFAULTDefinition { {


KEYStatements { 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.
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:
CA Easytrieve® Report Generator 11.6

• 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
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.
CA Easytrieve® Report Generator 11.6

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.
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:
• 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'
CA Easytrieve® Report Generator 11.6

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.
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:

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.
CA Easytrieve® Report Generator 11.6

• 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'
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
CA Easytrieve® Report Generator 11.6

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:
You can use the following parameters to customize the display of an item in the screen work area:
• 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
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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
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.
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:
CA Easytrieve® Report Generator 11.6

You can use the SET statement to edit input data. For more information, see SET Statement.
This article contains the following information:

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.
CA Easytrieve® Report Generator 11.6

(m) or (m..n) Represents the repetition of the preceding pattern expression.


The m and n represent numbers and m must be less than
or (m..*) n. A single number within the parentheses indicates the
or (*) exact number of repetitions. (m..n) represents a range of
repetitions, minimum to maximum. An asterisk in a range,
or * (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.
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
CA Easytrieve® Report Generator 11.6

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 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.
CA Easytrieve® Report Generator 11.6

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:

ROW 13 'Name . .' EMPNAME PATTERN 'U(U(*),L(*)) B(*)'


CA Easytrieve® Report Generator 11.6

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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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 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.
CA Easytrieve® Report Generator 11.6

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:
• 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:
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:
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.
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:
CA Easytrieve® Report Generator 11.6

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.
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


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
CA Easytrieve® Report Generator 11.6

Screen Message Area


The message area displays system-issued and programmer-issued messages to the terminal user.
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 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.
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 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.
CA Easytrieve® Report Generator 11.6

The following rules apply to key processing:


• 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:
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.
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
CA Easytrieve® Report Generator 11.6

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.
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:
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.
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
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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 ,
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:
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.
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:

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#
CA Easytrieve® Report Generator 11.6

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.

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:
CA Easytrieve® Report Generator 11.6

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:
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:
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.
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.
CA Easytrieve® Report Generator 11.6

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.

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 Hold/Release Processing for
information about how requests are processed to update records during file 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
WHEN F5
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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'
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.'
CA Easytrieve® Report Generator 11.6

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') 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 +
CA Easytrieve® Report Generator 11.6

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
END-IF
END-CASE END-PROC

Sample Screen Applications


This article contains the following coding examples for several common 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
CA Easytrieve® Report Generator 11.6

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
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)
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

KEY ENTER
KEY F3 NAME 'Exit' EXIT
TITLE 'Employee Edit 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
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
CA Easytrieve® Report Generator 11.6

EXECUTE MENU-HELP
RESHOW
END-IF
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:
CA Easytrieve® Report Generator 11.6

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
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?'
CA Easytrieve® Report Generator 11.6

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

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
CA Easytrieve® Report Generator 11.6

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
+---------------
+
| 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:


CA Easytrieve® Report Generator 11.6

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
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.
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:
CA Easytrieve® Report Generator 11.6

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 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
CA Easytrieve® Report Generator 11.6

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 source program. Macro
invocation statements cause a series of statements to be retrieved from the macro library and included as
source statements in the program. The series of statements can be modified by parameters supplied on the
macro invocation statement.
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
...
macro-1
expanded
statements
...
macro-2
expanded
statements
...
CA Easytrieve® Report Generator 11.6

Define Macros
A macro consists of three parts:
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:
• 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
CA Easytrieve® Report Generator 11.6

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
CA Easytrieve® Report Generator 11.6

Process Macros
Macros are processed whenever a macro invocation statement appears in a program. To designate a
macro invocation, prefix a percent sign (%) to the macro name. Each macro invocation retrieves a copy of
the macro from the library and, if necessary, replaces parameters with their corresponding values from the
macro invocation statement or the prototype statement.
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 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.
CA Easytrieve® Report Generator 11.6

Macro invocation Macro member = FILE

MACRO 0 NAME FILEA +


%FILE NAME TESTIN + TYPE ' ' +
FORMAT 'V (1000)' + FORMAT 'FB(150 1800)'
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 . 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.
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
CA Easytrieve® Report Generator 11.6

****************************************************************
* *
* 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

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:
CA Easytrieve® Report Generator 11.6

27

SUPRA Interface Option


The SUPRA Interface lets you use ezt to retrieve information from a SUPRA database.
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.
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
CA Easytrieve® Report Generator 11.6

SUPRA Interface Operation


This article includes the following information:
This article includes the following information:

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.
CA Easytrieve® Report Generator 11.6

This program accesses the logical records that are defined as CUSTOMER:

SUPRA INCLUDE CUSTOMERJOB 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.
SUPRA Statement Details
For detailed information about SUPRA statements see the following articles:

SUPRA GET
Contents
Contents
CA Easytrieve® Report Generator 11.6

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 DEFINE statements and the associated record and status
data areas for a logical view. You can include a maximum of ten views in a program.
CA Easytrieve® Report Generator 11.6

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.
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
CA Easytrieve® Report Generator 11.6

DEFINE TIS-VSI TIS-CONTROL +37 1 A


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.
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:
CA Easytrieve® Report Generator 11.6

SUPRA INCLUDE CUSTOMER-ORDER-VIEW


SUPRA GET CUSTOMER-ORDER-VIEW

or

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).
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.
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
CA Easytrieve® Report Generator 11.6

SUPRA SIGN-OFF
The SUPRA SIGN-OFF statement informs the RDM that the user no longer wants access to the system.
The SUPRA SIGN-OFF statement informs the RDM that the user no longer wants access to the system.
Syntax

SUPRA SIGN-OFF

SUPRA SIGN-ON
The SUPRA SIGN-ON statement identifies a user to the RDM.
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 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.
CA Easytrieve® Report Generator 11.6

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:

//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.
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.
CA Easytrieve® Report Generator 11.6

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 CUSTVIEWJOB INPUT NULLSUPRA


SIGN-ON 'SMITH'SUPRA GET CUSTVIEWDO WHILE TIS-FSI = '*' DISPLAY
PART-NUMBER PART-COST SUPRA GET CUSTVIEWEND-DOSTOP

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 CARDKEY-BRANCH 1 4 AKEY-PRODUCT 5 9 ASUPRA INCLUDE


STOCKJOB 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-
QNTYEND1241TL-4002-A1241HD-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 CUSTOMERPASSWORD S 8 APARM-DATA S 8 A VALUE '
'*PROGRAM MAINRTN USING(PARM-DATA) EXECUTE JOB1*JOB NAME JOB1 INPUT
CA Easytrieve® Report Generator 11.6

NULL START SIGNON FINISH SIGNOFF SUPRA GET CUSTOMER DO WHILE TIS-
FSI = '*' DISPLAY 'BRANCH=' CUSTOMER-BRANCH SUPRA GET CUSTOMER
END-DOSTOP*SIGNON. PROC IF PARM-DATA = SPACES . * PASSWORD WAS NOT
SUPPLIED DISPLAY '****** PASSWORD MISSING' ELSE PASSWORD =
PARM-DATA END-IFEND-PROC*SIGNOFF. PROC SUPRA SIGN-OFFEND-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 CUSTOMERJOB 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 EXECUTEEND-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 EXECUTEEND-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.
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 INVOICESUPRA INCLUDE CUSTOMERJOB 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
CA Easytrieve® Report Generator 11.6

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 CUSTOMERFILE CUSTFILE F(250)CUSTREC 1 250 AJOB 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

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


ezt, 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.
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 +
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

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

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
The macros described in the articles that follow facilitate the generation of the appropriate calls to TOTAL.

%ADDM - Add Master (TOTAL)


Contents
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, +
CA Easytrieve® Report Generator 11.6

field-2, +
field-3, +
TOTALEND)

%ADDV - Add Variable (TOTAL)


Contents
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
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, +
CA Easytrieve® Report Generator 11.6

TOTALREF, +
TOTALLINK, +
field-2, +
field-3, +
field-4, +
TOTALEND)
field-1 = TOTALREF

%CBLCNVRT
Converts COBOL data definitions to their equivalent.
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.
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
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
Contents
Takes two fields and concatenates them into one, with variable spacing between the fields. The result is placed in the first field.
CA Easytrieve® Report Generator 11.6

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
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
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
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.
CA Easytrieve® Report Generator 11.6

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.
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
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.
CA Easytrieve® Report Generator 11.6

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.
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
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
CA Easytrieve® Report Generator 11.6

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]
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
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
CA Easytrieve® Report Generator 11.6

YYDDD (Julian)
• [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 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
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, +
CA Easytrieve® Report Generator 11.6

field-3, +
TOTALEND)

%DELVD
Contents
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
CA Easytrieve® Report Generator 11.6

%DFNTOTF
Contents
Contents
Use the %DFNTOTF macro to initialize the REALM= (TOTALREALM) values.
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
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
CA Easytrieve® Report Generator 11.6

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]
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
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, +
CA Easytrieve® Report Generator 11.6

TOTALEND)

%GETCALEN
Contents
Contents
Converts an integer into a date in the format CCYYMMDD.
Syntax

%GETCALEN [date-in] [date-out]

• [date-in]
Integer value that represents a Julian day number.
• [date-out]
Returned date in the format CCYYMMDD.

%GETJULI
Contents
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
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
CA Easytrieve® Report Generator 11.6

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, +
TOTALEND)

%OPENX
Contents
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
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.
CA Easytrieve® Report Generator 11.6

• 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, +
field-2, +
field-3, +
field-4, +
TOTALEND)
field-1 = TOTALREF

%READM
Contents
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
CA Easytrieve® Report Generator 11.6

The generated statements are:

TOTALCMND = 'READM'
TOTALFILE = 'literal-1'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALFILE, +
field-1, +
field-2, +
field-3, +
TOTALEND)

%READR
Contents
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

• 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, +
CA Easytrieve® Report Generator 11.6

TOTALSTATUS, +
TOTALFILE, +
TOTALREF, +
TOTALLINK, +
field-2, +
field-3, +
field-4, +
TOTALEND)
field-1 = TOTALREF

%READV
Contents
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
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, +
CA Easytrieve® Report Generator 11.6

field-3, +
field-4, +
TOTALEND)
field-1 = TOTALREF

%RGHTJUST
Contents
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
Contents
Use the %SINOF macro to terminate task activities.
Syntax

%SINOF

%SINOF Macro-Generated Statements


The generated statements are:

TOTALCMND = 'SINOF'
CALL EZTPDBAS, +
USING(TOTALCMND, +
TOTALSTATUS, +
TOTALTASK, +
TOTALEND)

%SINON
Contents
Contents
Use the %SINON macro to initialize task activities.
CA Easytrieve® Report Generator 11.6

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
Contents
Validates user supplied parameters for valid numeric data.
Syntax

%VERNUMP [param]

• [param]
The parameter field to be verified.

%WRITM
Contents
CA Easytrieve® Report Generator 11.6

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
Contents
Use the %WRITV macro to update variable file records.
Syntax

%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.
CA Easytrieve® Report Generator 11.6

• 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.
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
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
CA Easytrieve® Report Generator 11.6

*
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
*
SIGN-OFF. PROC. * WRAP-UP
%CLOSX
%SINOF. * FINAL CALL TO TOTAL
END-PROC
*
CA Easytrieve® Report Generator 11.6

REPORT
SEQUENCE INVN-KEY
CONTROL INVN-KEY
TITLE 'INVENTORY CONTROL LISTING'
LINE INVN-KEY, INVN-NAME, INVN-CODE, +
BVIT-COST, BVIT-AMT, BVIT-RATE

8 Language Reference
Language reference for developers.
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
ezt 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.
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
CA Easytrieve® Report Generator 11.6

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:
• 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 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.
CA Easytrieve® Report Generator 11.6

• The shift-out code is found as part of the identified DBCS data.

Statements
This article contains an alphabetical list of ezt statements and a summary of the statements, categorized
by function.
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.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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.
MESSAGE Define message type and text for messages in a SCREEN
activity.
MOVE Transfer character strings from one storage location to
another.
CA Easytrieve® Report Generator 11.6

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.
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
File Management
• CLOSE
• COMMIT
• DELETE
• DISPLAY
• ENDTABLE
• FETCH
• GET
• INSERT
• JOB
• JOB INPUT NULL
• JOB INPUT SQL
• POINT
• PUT
CA Easytrieve® Report Generator 11.6

• 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
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
CA Easytrieve® Report Generator 11.6

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
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
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
CA Easytrieve® Report Generator 11.6

• 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 ezt programs:
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 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.
CA Easytrieve® Report Generator 11.6

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
----------------------------
FIELD-
NAME W 6 A - VALUE
+ 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:

FIELD-
NAME W 10 K + VALUE '[DBD

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.
CA Easytrieve® Report Generator 11.6

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-COUNTFILEONE: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.
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: FLD1FILEA:FLD1FILEA : FLD1WORK:FLD1

Labels
CA Easytrieve® Report Generator 11.6

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:
• 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.
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:
CA Easytrieve® Report Generator 11.6

%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
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.
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.
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'


CA Easytrieve® Report Generator 11.6

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.
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.
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 +
CA Easytrieve® Report Generator 11.6

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

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


CA Easytrieve® Report Generator 11.6

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.
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:

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 ' +


CA Easytrieve® Report Generator 11.6

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 *

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
CA Easytrieve® Report Generator 11.6

2222.09

AFTER-SCREEN Screen Procedure


An AFTER-SCREEN procedure is invoked after the screen activity receives data from the terminal.
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

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 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.
CA Easytrieve® Report Generator 11.6

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
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 } { }


CA Easytrieve® Report Generator 11.6

{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

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:
CA Easytrieve® Report Generator 11.6

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)

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)
CA Easytrieve® Report Generator 11.6

(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
F1P = F2P XOR F2P
DISPLAY SKIP 2 +
'F1P = F2P XOR F2P = ' F1P
STOP
CA Easytrieve® Report Generator 11.6

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:
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] +
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]
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]
CA Easytrieve® Report Generator 11.6

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.
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:

BEFORE-BREAK. PROC

Example
Consider the following percentage calculation, paying special attention to when and how PERCENT is calculated:
CA Easytrieve® Report Generator 11.6

Statements:

FILE FILE1 FB(80 8000) LAST-


NAME 1 5 A STATE
NET 13 5 N 2 *
NET S 8 N 2 *
JOB INPUT FILE1 NAME MYPROG *
NET = TOTAL-NET + PAY-
NET PRINT REPORT1
REPORT REPORT1 LINESIZE 80 + SUM
NAME CONTROL STATE ZIP
NAME STATE ZIP PAY-
NET PERCENT *
BEFORE-BREAK.
PROC
PERCENT = PAY-NET * 100 / TOTAL-
NET
END-PROC

Data:

BROWNIL6007612345 BROWN

Results:

LAST-NAME STATE ZIP PAY-


NET PERCENT

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.
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.
CA Easytrieve® Report Generator 11.6

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.
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

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 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:
CA Easytrieve® Report Generator 11.6

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 pr

• 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.
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.
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.
CA Easytrieve® Report Generator 11.6

This statement has the following format:

CASE field-name
CASE

The following diagram illustrates CASE statement logic:


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.
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 EMPLOYEEEMPYRS 5 2 N...


CASE
EMPYRS
WHEN 0 THRU 4 DISPLAY 'ONE WEEK VACATION' WHEN 5 THRU 10 DISPLAY 'T
END-
CASE
...

CLOSE Statement
The CLOSE statement closes a file.
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.
CA Easytrieve® Report Generator 11.6

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:

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 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 ROLLBACKEND-IF

Conditional Expressions
Conditional expressions used as parameters of IF and DO statements offer an alternative to the normal
top-to-bottom execution of statements.
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 11.6

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

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.
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
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' DEFIN


NUM W 4 B VALUE X'FF00FF00' DEFINE PATTERN-8
CASE W 1 A VALUE X'81' *
CA Easytrieve® Report Generator 11.6

IF FIELD-1 ON PATTERN-8

DISPLAY 'PERFORM CODE FOR PATTERN 8' EN


IF
IF LOWER-CASE OFF X'40'

DISPLAY 'THIS LETTER IS LOWER CASE' EN


IF
IF FIELD-NUM ON X'FF000000'

DISPLAY '1ST BYTE HIGH VALUES' EN


IF STOP

Field Class Condition


The field class condition determines whether:
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
BREAK} {IF } {MODIFIED
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}
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.
CA Easytrieve® Report Generator 11.6

• {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.
Example
This example illustrates the use of the field class condition:

FILE PERSNL FB(150 1800) REGIO


LAST EMPNAME 8 A NAME-
FIRST EMPNAME +8 12 A *
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-
CA Easytrieve® Report Generator 11.6

IF
IF EMPNAME
ALPHABETIC
TOTAL-ALPHABETIC = TOTAL-
ALPHABETIC + 1 END-
IF *
FINISH-
PROC. PROC DISPLAY T
NUMERIC DISPLAY TOTAL-
NON-
ZEROS DISPLAY TOTAL-
ALPHABETIC END-PROC

Field Relational Condition


The field relational condition compares fields with values.
The field relational condition compares fields with values.
This statement has the following format:

Relational
= } {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
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.
CA Easytrieve® Report Generator 11.6

• 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:
• 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


LAST EMPNAME 8 A NAME-
FIRST EMPNAME +8 12 A PAY-
NET 90 4 P 2 PAY-
GROSS 94 4 P 2 SEX
EMP# W 3 N VALUE 0 TOTAL-
SEX W 3 N VALUE 0 TOTAL-
PAY W 3 N VALUE 0 TOTAL-
CA Easytrieve® Report Generator 11.6

FIRST-
NAME W 3 N VALUE 0 MALE
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 T
EMP# 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.
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
IF } {EQ | = } { }
CA Easytrieve® Report Generator 11.6

• 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) REGIO


STAT 128 1 A *
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 T
REGION DISPLAY TOTAL-
BRANCH DISPLAY TOTAL-
DEPT DISPLAY TOTAL-
MARITAL END-
PROC
CA Easytrieve® Report Generator 11.6

File Presence Condition


The file presence condition determines whether a record of the file is currently available for processing.
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

• Subject
File-name designates the subject of the test.
Example 1
This example illustrates the use of the file presence condition:

FILE PERSNL INDEXED %PERS


IF NOT PERSNL

DISPLAY '00970 NOT ON FILE' ELS


IF STOP

Example 2
This example illustrates the use of the file presence condition in synchronized file processing:

FILE PERSNL FB(150 1800) %PERS


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'


IF
IF NOT PRIMARY

DISPLAY 'NO PERSONNEL RECORD- ' LOCATION-


CA Easytrieve® Report Generator 11.6

STATE END-
IF
IF NOT SECONDARY

DISPLAY 'NO INVENTORY RECORD- ' ADDR-


STATE END-
IF
IF SORT1

* HOW MANY PERSONNEL RECORDS RETURNED


IF
IF SORT2

* HOW MANY INVENT RECORDS RETURNED


IF *
PROC. PROC DISPLAY C
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.
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

• 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) %PERS


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 EN
IF *
CA Easytrieve® Report Generator 11.6

PROC. PROC DISPLAY C


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.
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
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) %PERS


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 EN
IF
IF DUPLICATE SORT2

COUNT-2 = COUNT-2 + 1 EN
IF *
PROC. PROC DISPLAY C
PROC
CA Easytrieve® Report Generator 11.6

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.
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]...
[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.
CA Easytrieve® Report Generator 11.6

Example

CONTROL FINAL NEWPAGE REGION NEWPAGE BRANCH DEPT

COPY Statement
The COPY statement duplicates the field definitions of a named file.
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

• 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) EMP


LAST EMPNAME 8 A HEADING ('LAST' 'NAME') NAME-
FIRST EMPNAME +8 12 A HEADING ('FIRST' 'NAME') FILE SORTWRK F
COPY PERSNL

SORT PERSNL TO SORTWRK USING + (


LAST NAME-
FIRST) NAME MYSORT JOB INPUT SORTWRK NAME MY
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 ARECORD SALES 28 SLS-CUST-
NO 1 10 AFILE DDBASE FB(28 280)
COPY SALES (fields from RECORD SALES
copied)
JOB INPUT (DNASE) NAME MYPROG RETRIEVE DBASE + SELECT (CUSTOMER AREA '
CA Easytrieve® Report Generator 11.6

REGION' + SALES ID 'SA' SET 'CUSTOMER-


SALES') IF PATH-
ID EQ 'SA' MOVE LIKE SALES TO DDBASE PUT DDBASE ELSE GO TO JOB
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.
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:
• 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
CA Easytrieve® Report Generator 11.6

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.
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'


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.
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).
CA Easytrieve® Report Generator 11.6

(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: # R

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.
• 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 ATTRDECLARE 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).
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.
CA Easytrieve® Report Generator 11.6

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 BLUEDEFAULT 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.
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
CA Easytrieve® Report Generator 11.6

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 YELLOWDEFAULT 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.
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:

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
CA Easytrieve® Report Generator 11.6

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]
}

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
CA Easytrieve® Report Generator 11.6

• 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:
• 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'
CA Easytrieve® Report Generator 11.6

• 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-

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


CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
CA Easytrieve® Report Generator 11.6

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
{ 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
CA Easytrieve® Report Generator 11.6

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
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-bytefieldlengthW 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
CA Easytrieve® Report Generator 11.6

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 SQL file.
Use the DELETE statement to delete a specific row from a CA Easytrieve® Report Generator SQL file.
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) UPDATEEMPNAME * 20 AWORKDEPT * 2


PERSONNEL SELECT FROM PERSNL WHERE EMPNAME = 'ROGERS PAT' FETCH FROM PERS
IF
CA Easytrieve® Report Generator 11.6

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.
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-in

Format 2

[display-file-name] [{TITLE|
NOTITLE} ] DISPLAY [ ] [SKIP skip-in

Format 3

[display-file-name] [ ] DISPL

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
CA Easytrieve® Report Generator 11.6

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 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 P


IF
CA Easytrieve® Report Generator 11.6

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 %PERSN

When executed, the statements in this example produce the following output:

CHAR 104 G 01963 7ARNOLD LINDA 1569 COLONIAL TERR ANEW YORK NY1

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.
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' }
DLI { } { } id-field-name +
{XRST} {seg-len-field-name}

[ {'checkpoint-len-literal' } ]
CA Easytrieve® Report Generator 11.6

[ { } 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
CA Easytrieve® Report Generator 11.6

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-
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)
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.
CA Easytrieve® Report Generator 11.6

• {'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.
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 ... statem
END-DO

The following diagram illustrates DO and END-DO statement logic:


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.
CA Easytrieve® Report Generator 11.6

Examples
DO UNTIL statement example:

FILE FILEAELEMENT 1 10 A OCCURS 10CTR W 2 NJOB INPUT FILEA


DO

DO WHILE loop nesting example:

DEFINE COUNT-1 W 3 N VALUE 0 DEFINE


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 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
NET 13 5 N 2 JOB INPUT
REPORT REPORT1 LINESIZE 65 + SUM
NAME CONTROL STATE NEWPAGE ZIP
NAME STATE ZIP PAY-
NET *
PROC *

END-PROC Statement
The END-PROC statement delimits the statements in a procedure. A procedure is a group of user-written
statements designed to accomplish a particular objective.
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.
CA Easytrieve® Report Generator 11.6

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.
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 AR

EXECUTE Statement
The EXECUTE statement invokes a JOB, SORT, or SCREEN activity from either a PROGRAM or
SCREEN activity.
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.
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}
CA Easytrieve® Report Generator 11.6

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.
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

FETCH Statement
The FETCH statement is used to retrieve rows from an SQL file.
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


CA Easytrieve® Report Generator 11.6

• [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 AWORKDEPT * 2 P


PERSONNEL FETCH FROM PERSNL DO UNTIL EOF PERSNL DISPLAY EMPNAME +2 WORKD
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 ezt 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.
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.
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]}
] }
[
CA Easytrieve® Report Generator 11.6

{'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] +

[ASA] +

[EXTENDEDxrpt-printer] +
CA Easytrieve® Report Generator 11.6

[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)
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.
(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)
CA Easytrieve® Report Generator 11.6

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.
• [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
CA Easytrieve® Report Generator 11.6

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).
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)


CA Easytrieve® Report Generator 11.6

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.
• [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
CA Easytrieve® Report Generator 11.6

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:
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]
CA Easytrieve® Report Generator 11.6

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]
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


CA Easytrieve® Report Generator 11.6

To define a printer file to be viewed at the terminal, use:

FILE PRTFILE PRINTER (PAGESIZE 20 LINESIZE 80) + TERMINAL

GET Statement
GET places the next or previous sequential record of the named file into the file's record buffer.
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

• 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.
CA Easytrieve® Report Generator 11.6

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.
Examples
The following code illustrates the use of the GET statement:

FILE PERSNL INDEXED%PERSNLPROGRAM 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.
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:
• Assignment
• CASE
• COMMIT
• DELETE
• DLI
• END-DO
• END-PROC
• EXIT
CA Easytrieve® Report Generator 11.6

• 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}
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.
CA Easytrieve® Report Generator 11.6

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 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 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
CA Easytrieve® Report Generator 11.6

The following example illustrates various report heading options:

Statements: FILE PERSNL FB(150 1800) SSN 4 5 P MASK '999-99-9


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
HEADING PAY-NET ('NET',
'PAY')
LINE EMPNAME SSN '* NO OVERTIME *' PAY-NET

Results:
SOCIAL SECURITY
WIMN GLORIA 025-30-5228 * NO OVERTIME * 251.65 BERG NAN

IDD FILE Statement


The IDD FILE statement identifies a non-CA IDMS file in the IDD and builds file and field definitions.
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 FI

• 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.
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.
CA Easytrieve® Report Generator 11.6

This statement has the following format:

IDD NAME [PROGRAM-


NAME 'program-literal'] + [DBNAME 'db-na

• [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.

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.
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 RE

• 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.
CA Easytrieve® Report Generator 11.6

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.
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 +


[SCHEMA schema-name [VERSION {LOWEST }]]
+ [ [ {nnnn }]]
[RESET] +

• 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.
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
CA Easytrieve® Report Generator 11.6

• [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}]
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.
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 A

Format 2

{NEXT } {set-field-name} IDMS A

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.
The IDMS ACCEPT PAGE-INFO statement transfers database page information to program storage.
CA Easytrieve® Report Generator 11.6

This statement has the following format:

{ } {currency-field-name} IDMS
INFO receive-field-name {RECORD} { }

• 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.
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 A

• {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.
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.
The IDMS BIND statement signs on the activity with the database management system.
CA Easytrieve® Report Generator 11.6

This statement has the following format:

{subschema-name } IDMS BI
NAME { }] + [ {'

• {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.
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
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.
The IDMS BIND PROCEDURE statement establishes communications between a program and a DBA-written database
procedure.
CA Easytrieve® Report Generator 11.6

This statement has the following format:

{proc-field-name} IDMS B

• {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.
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.
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 C

• {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.

IDMS DISCONNECT Statement


The IDMS DISCONNECT statement cancels the relationship between a record and a set occurrence.
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 D


CA Easytrieve® Report Generator 11.6

• 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.
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 ]

Format 2

IDMS E

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)]
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:
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.
CA Easytrieve® Report Generator 11.6

• 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}]
SHR ] IDMS { } DBKEY { } [
EXC] [ PAGE-
INFO { }] [ {'

Format 2

{FIND } [{RECORD} {field-name}] [SHARE|


SHR ] IDMS { } CURRENT [{SET } { }] [
EXC]

Format 3

{FIND }# {NEXT } [ {record-field-name}]


SHR ] { } { } [
EXC]

Format 4

{FIND } {set-field-name} [SHARE|


SHR ] IDMS { } OWNER SET { } [
EXC]

Format 5

{FIND } {CALC } {record-field-name} [SHARE|


SHR ] IDMS { } { } RECORD { } [
EXC]

Format 6
CA Easytrieve® Report Generator 11.6

SHR ] USING ({ }...) [


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'}
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]
CA Easytrieve® Report Generator 11.6

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.
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.
The IDMS GET statement retrieves current data records.
This statement has the following format:

[ {record-field-name}] IDMS G

• 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.
The IDMS IF statement tests the status of a set.
This statement has the following format:

{MEMBER }

• 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:
CA Easytrieve® Report Generator 11.6

• 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.
The IDMS KEEP statement places a shared or exclusive lock on a record.
This statement has the following format:

[{RECORD} {field-name}] IDMS KE

• [{RECORD|SET|AREA} {field-name|'literal'}]
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.
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 M

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
CA Easytrieve® Report Generator 11.6

• 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.
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} IDM

• {FIRST} or {NEXT}
Specify FIRST to retrieve the first occurrence of the logical record. Specify NEXT to retrieve subsequent occurrences.
• RECORD logical-record-name
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.
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.
The IDMS RETURN statement retrieves the database key for an indexed record without retrieving the record itself.
CA Easytrieve® Report Generator 11.6

This statement has the following format:

{set-field-name} IDMS R

• 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]
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.
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.
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 { }


CA Easytrieve® Report Generator 11.6

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)]
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 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] ]
IF

The following diagram illustrates IF, ELSE-IF, ELSE, and END-IF logic:
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
CA Easytrieve® Report Generator 11.6

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
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) %PERS


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'
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
XMAS-BONUS END-
PROC *
LAST XMAS-BONUS

Example 2, with Nested IF Statements:

FILE PERSNL FB(150 1800) %PERS


BONUS W 4 P 2 VALUE 0 TOT-
CA Easytrieve® Report Generator 11.6

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'
ELSE
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
XMAS-BONUS END-
PROC *
LAST XMAS-BONUS

Example 3, with ELSE-IF Statements:

FILE PERSNL FB(150 1800) %PERS


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'
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
CA Easytrieve® Report Generator 11.6

FINISH-
PROC. PROC DISPLAY
XMAS-BONUS END-
PROC *
LAST XMAS-BONUS

INITIATION Screen Procedure


An INITIATION procedure is invoked once during the start of the screen activity.
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 EMPNAMEEND-PROC

INSERT Statement
Use the INSERT statement to insert a row into a SQL file.
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]
CA Easytrieve® Report Generator 11.6

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:

FILE PERSNL SQL (PERSONNEL) UPDATEEMPNAME * 20 AWORKDEPT * 2


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:
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 +
[ { }][ENVIRONMENT{NONE }] +[ {COBOL}]

• [INPUT]
The optional INPUT parameter identifies the automatic input to the activity.
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.
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

Example 1
The following example illustrates the position of the JOB activities in a CA Easytrieve® Report Generator program.

Environment... Library... Activities {JOB......


or { ... SORT { ......

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:

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:
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."
CA Easytrieve® Report Generator 11.6

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 [


[NAME 'literal'] [ ] [IMMEDIATE]

• 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
CA Easytrieve® Report Generator 11.6

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.
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
screen fields into program fields. The AFTER-SCREEN
'CANCEL' IMMEDIATE 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.
CA Easytrieve® Report Generator 11.6

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.
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 }

• [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
CA Easytrieve® Report Generator 11.6

LINE 1 REGION BRANCH +5 DEPT EMPNAMELINE 2 POS 4 ADDRESSLINE 3 'NET==>' -2


NET POS 4 CITY ST ZIP

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.
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.
CA Easytrieve® Report Generator 11.6

Example

LINK 'PROGB' USING EMP# GIVING PROGB-RETURN

LIST Statement
LIST regulates the printing or suppression of all statements in the printed output.
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 OFFPARM LIST(NOPARM)

For more information, see PARM Statement in the chapter "Statements N - R."
This statement has the following format:

[ON ] [MACROS ] LIST

• [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").
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] +

• MACRO
MACRO must be the first word on a prototype statement.
• [positional-count]
CA Easytrieve® Report Generator 11.6

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]
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 ezt statements:
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 })]


CA Easytrieve® Report Generator 11.6

• [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 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:
• 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.
CA Easytrieve® Report Generator 11.6

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.
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:
CA Easytrieve® Report Generator 11.6

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
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
CA Easytrieve® Report Generator 11.6

'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.
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.
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:
• 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:
CA Easytrieve® Report Generator 11.6

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.
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

{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]
CA Easytrieve® Report Generator 11.6

{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 }
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}
CA Easytrieve® Report Generator 11.6

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.
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}
Send-file-name or send-record-name identifies the sending data area.
• {receive-file-name} or {receive-record-name}
CA Easytrieve® Report Generator 11.6

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)
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
CA Easytrieve® Report Generator 11.6

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.
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.
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.
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.
CA Easytrieve® Report Generator 11.6

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 ...


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]
[ ] [ { } ] ) ] +
CA Easytrieve® Report Generator 11.6

[NOSTATE] [NOXREF {SHORT} ] ]


[ {
}][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] +
CA Easytrieve® Report Generator 11.6

[TRANSID 'transid'] +

[USERID ('connect-userid' ['password'])] +

[ [
{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 Options Table


Value Value Table 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
CA Easytrieve® Report Generator 11.6

STATIC-ONLY STATIC-ONLY STATIC-ONLY STATIC-ONLY Invalid -- an error


is the BIND is the BIND is the BIND occurs
parameter parameter parameter
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).

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.
CA Easytrieve® Report Generator 11.6

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.
[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])}]
CA Easytrieve® Report Generator 11.6

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.
[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.
CA Easytrieve® Report Generator 11.6

(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'])]
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
CA Easytrieve® Report Generator 11.6

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
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.
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) %PERSNLXMAS-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.20END-
PROC*STANDARD-BONUS. PROC XMAS-BONUS = PAY-GROSS * 1.05END-
PROC*REPORT MYREPORTLINE NAME-LAST XMAS-BONUS
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.
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:

{= }

• 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:

FILE PERSNL INDEXED %PERS


POINT PERSNL GE '01963' STATUS

IF FILE-
STATUS NE 0 OR EOF PERSNL DISPLAY 'B
CA Easytrieve® Report Generator 11.6

STATUS STOP
IF GET PERSN
STATUS NE 0 DISPLAY 'BA
STATUS ELSE
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 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.
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.
Example

FILE PERSNL FB(150 1800) %PERSNLJOB INPUT PERSNL NAME PRINT-RPT


PRINT REPORT1 REPORT REPORT1 TITLE 'PERSONNEL REPORT' LINE
EMP# SSN EMPNAME
CA Easytrieve® Report Generator 11.6

PROC Statement
The PROC statement is used to begin a procedure. A procedure is a group of user-written statements
designed to accomplish a particular objective. The syntax of a procedure has two statements:
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 st
PROC

Format 2

proc-name PROC
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
CA Easytrieve® Report Generator 11.6

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.
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:
• 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.
CA Easytrieve® Report Generator 11.6

• [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.
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


PANEL1JOB 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.
CA Easytrieve® Report Generator 11.6

Program code:

//COMP EXEC PGM=EZTPA00,PARM='0123456789ABCDEF'//SYSIN DD *PARM


DUMP(PCODE)DEFINE JCL-PARM S 100 A VARYINGPROGRAM NAME TESTPARM
USING(JCL-PARM)EXECUTE TESTPARM1JOB INPUT(NULL) NAME TESTPARM1DISPLAY
'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 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.
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 o
[STATUS] [ {input-record-name}]

• output-file-name
The output-file-name parameter identifies the output file.
CA Easytrieve® Report Generator 11.6

• [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 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 %PERSNLFILE PERSNLCOPY FILEAJOB INPUT PERSNL NAME
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.
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 { } [ ] [STAT


{'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.
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]
CA Easytrieve® Report Generator 11.6

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 %PERS


NET W 5 P 2 JOB INPUT INK
TOTAL
READ PERSNL KEY WHO
STATUS
IF PERSNL:FILE-
STATUS NE 0 DISPLAY 'UNSUCCES
NET = TOTAL-NET + PAY-NET END-
IF DISPLAY-
TOTAL. PROC DISPLAY 'TO
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.
Code RECORD statements (Format 1) following the FILE statement to identify the CA IDMS database records available for
automatic or controlled processing.
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
CA Easytrieve® Report Generator 11.6

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] +

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]
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.
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.
CA Easytrieve® Report Generator 11.6

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 2DEFINE QTY W 4 P 0DEFINE PRICE W 4 P 2SCREEN NAME TEST-
REFRESH KEY F2 NAME 'Reset to zero' KEY F3 EXIT NAME 'Exit' KEY F5 IMMEDIA
PRICE BEFORE SCREEN. PROC MOVE ZERO TO QTY, PRICE, EXT-PRICE END-
PROC AFTER-SCREEN. PROC 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.
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
CA Easytrieve® Report Generator 11.6

READ PERSNL KEY '01193' HOLD... IF ... WRITE PERSNL UPDATEELSE


RELEASE
PERSNL
END-IF

REPEAT and END-REPEAT Statements


The REPEAT/END-REPEAT construct is used to display arrays on a screen.
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
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:
CA Easytrieve® Report Generator 11.6

...
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 ...
LIST TITLE 'List of E
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)
END-REPEAT

Produces:

List of Employees
Name Statuses WIMN, GLORIA F G O B

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.
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-
CA Easytrieve® Report Generator 11.6

file-
name]+ } [SUMSPACE sumfield-addition]+
} [TALLYSIZE tally-
print-
size]+ }
} [ {EVERY}]
} [DTLCTL{FIRST}]+ } Format [ {NONE}]
} Determination } Parameters [ { [ALL] }]
}
[SUMCTL {([HIAR] [DTLCOPY])}]+ } [ { [NONE] [DTLCOPYALL] }]
} [ { [TAG ] }] } }

[ [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]+ }
}
CA Easytrieve® Report Generator 11.6

[NODATE ] }

[LONGDATE ]+ } [SHORTDATE]
} } [NOPAGE]+
} [NOHEADING]+ }
} [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.
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:
• • 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
CA Easytrieve® Report Generator 11.6

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 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.
CA Easytrieve® Report Generator 11.6

• [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.
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.
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
NET 13 5 N 2 HOLD-
ZIP S 5 N VALUE 00000 JOB INPUT
REPORT REPORT1 LINESIZE 65 + SUM
NAME STATE ZIP PAY-
NET *

REPORT-INPUT. PROC
CA Easytrieve® Report Generator 11.6

IF ZIP NE HOLD-
ZIP HOLD-
ZIP = ZIP SELECT
IF END-
PROC *

Data:

BROWNIL6007612345 BROWN

Results:

11/23/09 REPORT FOR THE STATE OF IL PAGE 1


NAME STATE ZIP PAY-
NET BROWN IL 60076 123.45
NAME STATE ZIP PAY-
NET SMITH TX 75218 111.11

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.
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
SCREEN. PROC IF KEY-PRESSED = F1 EXECUTE MENU-
HELP

RESHOW
END-IF CASE OPTION ...
CA Easytrieve® Report Generator 11.6

END-PROCSCREEN NAME MENU-


HELP KEY F3 NAME 'Exit' EXIT 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. processes the automatic input the same
way as non-database input.
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 +
NAME { }] + [
[ {node-name }] [NOD
[ {dictionary-name }] [DICT
[ {dictionary-node-name }] [DIC
SELECT (record-name +

[ID 'path-literal'] +

Format 2 (IMS/DLI)

RETRIEVE file-name +

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.
CA Easytrieve® Report Generator 11.6

• [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
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']
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.
The ROLLBACK statement causes all uncommitted updates in the current logical unit of work to be rolled back.
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:
CA Easytrieve® Report Generator 11.6

ROLLBACK

Example

WRITE PERSNL ADD... IF ... ROLLBACK


ELSE COMMITEND-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.
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] +
[ {RIGHT} ] [JUST
NULL}] +
[MASK ({[mask-identifier] [BWZ] ['mask-literal']|
HEX})] + [NOMASK
[ {pattern-name} ] [PATT
[VALUE (literal [THRU literal] [...])] +

• [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:
CA Easytrieve® Report Generator 11.6

• 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.
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. For information about coding the actual edit
mask see MASK Parameter .
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"
CA Easytrieve® Report Generator 11.6

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 upper-case letter.
The precedence of operators from highest to lowest is:

Grouping: () " "


Set construction: + - Actions: # Repetition:

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) +
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.
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 declar


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


[ROW screen-start-row] [COL screen-start-column] +

[ {attribute-name } ] [BACKGROUND ATTR {

• [NAME screen-name]
Optionally, specify a name for the SCREEN activity. Screen-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
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.
CA Easytrieve® Report Generator 11.6

• [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.
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 pres
REPLY VALUE ('V' 'E' 'D' 'X') + ERROR 'Please type V, E,

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.
The SEARCH statement provides access to table information. Special conditions of the IF statement can be used to validate the
results of SEARCH operations.
CA Easytrieve® Report Generator 11.6

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

• 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 DEFIN


SEARCH CLASSES WITH CODE, GIVING DESCRIPTION

IF CLASSES D
IF

Results:

ENGLISH II
CA Easytrieve® Report Generator 11.6

SELECT Statement (File-based SQL)


A SELECT statement issued for an SQL file causes a cursor to be automatically declared and opened as
a 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.
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:
• 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 +

• [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]]
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:
CA Easytrieve® Report Generator 11.6

FILE PERSNL SQL (PERSONNEL) EMPNAME * 20 AWORKDEPT * 2 P


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) DEFEREMPNAME * 20 AWORKDEPT * 2


PERSONNEL INPUT PERSNL START START-
PROC DISPLAY EMPNAME +2 WORKDEPTSTART-
PROC. PROC
SELECT FROM PERSNL WHERE WORKDEPT =
921
END-PROC

SELECT Statement (Non-file SQL)


The non-file SQL SELECT statement allows to retrieve rows without a file. This read-only method is
retained from previous versions of .
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:

{ {* }
FROM table-name [correlation-name] +
[ { {* } ] [
[ FROM table-name [correlation-name] + ] [

• [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.*}
CA Easytrieve® Report Generator 11.6

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 CONNE
IF SQL DECLA
process <easy> code END-
DO SQL CLOSE

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.
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.
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
CA Easytrieve® Report Generator 11.6

Example

REPORT-INPUT. PROC IF ZIP NE HOLD-ZIP HOLD-


ZIP = ZIP

SELECT
END-IF END-PROC

SELECT Statement (Sort Selection)


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.
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) %PERS


LAST, NAME-
FIRST) + NAME MYSORT BEFORE SC
STAT = 'S' AND SEX = 1
SELECT

END-
IF END-
PROC

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 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.
CA Easytrieve® Report Generator 11.6

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
NET

SET Statement
The SET statement allows you to dynamically change screen attributes and to control the display of
screen errors.
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.
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.
CA Easytrieve® Report Generator 11.6

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 +

Format 2

{attribute-name } SET f

• 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:
• 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}
CA Easytrieve® Report Generator 11.6

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-IFEND-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-IFEND-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... 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.
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.
CA Easytrieve® Report Generator 11.6

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.
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] +

[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
CA Easytrieve® Report Generator 11.6

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:
• 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) %PERSNLFILE SORTWRK FB(150 1800) VIRTUALCOPY


PERSNLSORT PERSNL TO SORTWRK USING + (REGION, BRANCH) NAME MYSORT
CA Easytrieve® Report Generator 11.6

SQL Statement
The SQL statement supports the SQL statements of the following database management systems:
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:
• 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:
• ACQUIRE
• ALTER
• CLOSE cursor-name
CA Easytrieve® Report Generator 11.6

• 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:
• 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
CA Easytrieve® Report Generator 11.6

• 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:
• 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
CA Easytrieve® Report Generator 11.6

• DECLARE cursor-name
• DELETE
• DISCONNECT
• DROP
• FETCH cursor-name
• INSERT
• OPEN cursor-name
• ROLLBACK {work}
• UPDATE
• USE

SQL INCLUDE Statement


The SQL INCLUDE statement indicates that SQL table information is to be used to generate field
definitions. It names the table and gives the location where the field definitions are generated.
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.
CA Easytrieve® Report Generator 11.6

• [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 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.
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.
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) %PERS


GROSS D) + NAME MYSORT BEFO
PROC *
PROC. PROC IF PERS
COUNT GT 50 STOP

ELSE
IF END-
PROC
CA Easytrieve® Report Generator 11.6

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) %INVM


PROC PRINT MYREPORT
PROC. PROC IF RECORD
COUNT = 0 DISPLAY 'INPU
STOP EXECUTE

END-
IF END-
PROC *
NUMBER PART-
DESCRIPTION *
STATE, + LOCATION-
CITY) NAME MYSORT *
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.
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.

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.
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
CA Easytrieve® Report Generator 11.6

Example
The following is an example of report footing:

FILE FILE1 LAST-


NAME 1 5 A STATE
NET 13 5 N 2 TOTAL-
NET S 8 N 2 JOB INPUT F
NET = TOTAL-NET + PAY-
NET PRINT REPORT1
NAME CONTROL STATE NEWPAGE ZIP
NAME STATE ZIP PAY-
NET *
TERMINATION. PROC
DISPLAY TITLE
NET 'IS THE Y-T-
D COMPANY NET PAY' DISPLAY SKIP 5 'PLEASE ROUTE THIS REPORT T
PROC

TERMINATION Screen Procedure


A TERMINATION procedure is invoked once during the end of the screen activity.
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:

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.
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}

• [title-number]
CA Easytrieve® Report Generator 11.6

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.

TITLE Statement (Screens)


The TITLE statement is used to automatically center items on a screen.
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]


[ {attribute-name } ] ] [ATTR {

• [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:
CA Easytrieve® Report Generator 11.6

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 'Ti

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.

TRANSFER Statement
The TRANSFER statement is used to transfer execution to a target program without returning to the
invoking program.
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'}
CA Easytrieve® Report Generator 11.6

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'
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 SQL file.
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 UPDATEEMPNAME * 20 AWORKDEPT * 2


PERSONNEL INPUT PERSNL SELECT FROM PERSNL WHERE WORKDEPT = 901 FOR UPDATE W
UPDATE PERSNL
CA Easytrieve® Report Generator 11.6

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.
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


[STATUS] [ADD ] [ {input-record-name}]

Format 2

WRITE output-file-name DELETE [STATUS]

• 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. 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.
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.
CA Easytrieve® Report Generator 11.6

Example
The following example illustrates the use of WRITE:

FILE PERSNL INDEXED UPDATE %PERS


STATUS NE 0 DISPLAY 'FILE-
STATUS= ' PERSNL:FILE-
STATUS DISPLAY 'UNSUCCESSFUL READ ON PERSNL FILE
WRITE PERSNL UPDATE

IF PERSNL:FILE-
STATUS NE 0 DISPLAY 'FILE-
STATUS= ' PERSNL:FILE-
STATUS DISPLAY 'UNSUCCESSFUL UPDATE ON PERSNL FI
IF
END-IF

Symbols and Reserved Words


This section contains a list of 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.
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
CA Easytrieve® Report Generator 11.6

* 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)
= Assignment

Conditional expression

POINT
@ R Reserved for future use

Reserved Words
The following list includes all CA Easytrieve® Report Generator reserved words:
CA Easytrieve® Report Generator 11.6

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
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 (Releases 4.0 to
6.4) to the current versions of .
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:

DEVICEVFM DEVICE (except DISK#MEMORY) SORT DIAG#NODIAGSORT ERASE#NOERASESORT

The DBCSCODE parameter is replaced by the CODE parameter, but still supported as valid syntax.
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
CA Easytrieve® Report Generator 11.6

Double Byte Character Set (DBCS) X MVS Batch Only


support

9 Messages and Codes


Messages and codes issued by the product.
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.
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:
• Operational ErrorsErrors that occur in both the preprocessor and in the resulting CA Easytrieve Report Generator
program.
• Syntax ErrorsErrors in SUPRA statements.
Message Format
CA Easytrieve® Report Generator 11.6

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 program. The supplemental messages identify:
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
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
PDM SINON FAILED - status
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
CA Easytrieve® Report Generator 11.6

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
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
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
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.

A007
PDM READ STRU FILE FAILED - status
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
PDM READ DEF# FILE FAILED - status
CA Easytrieve® Report Generator 11.6

******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
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
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
OPEN PARAMETER IS INVALID - parm
Reason:
The value specified for OPEN during installation is invalid. The valid values are YES or NO.
Action:
Correct the value, recompile the preprocessor, and rerun.

A013
OVERRIDE PARAMETER IS INVALID - parm
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
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.
CA Easytrieve® Report Generator 11.6

A102
RDM SIGN-OFF ERROR FSI - fsi VSI - vsi message
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
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
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.

Syntax Diagnostic Messages


The following group of messages describes syntax errors detected in SUPRA statements. The
supplemental messages in this group specify:
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
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
PARAMETER IS INVALID - word
Reason:
The indicated word is invalid as used in the current statement.
Action:
CA Easytrieve® Report Generator 11.6

Refer to the statement syntax description, correct or delete the appropriate parameter, and rerun.

B003
SCHEMA DOES NOT EXIST IN THE DIRECTORY - schema
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
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
ACCESS SET DOES NOT EXIST FOR THIS VIEW - view
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
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
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
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.
CA Easytrieve® Report Generator 11.6

Action:
Correct the access set field name and rerun.

B010
INCLUDE FOR THIS VIEW WAS NOT FOUND - view
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
NUMBER OF KEY VALUES EXCEED ACCESS SET - view
Reason:
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
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
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 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 can change with new product releases,
CA Easytrieve® Report Generator 11.6

refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA
Support.
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: Examine the messages that follow to determine what the error is.
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:
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.
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.
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.
A field of an inactive file has been referenced.
CA Easytrieve® Report Generator 11.6

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.
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:
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.
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.
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
CA Easytrieve® Report Generator 11.6

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.
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.
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.

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.
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.
Error Check invoked with invalid parameter.
Reason:
This is an internal error.
Action:
Contact CA Support if this error is reproducible.
CA Easytrieve® Report Generator 11.6

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.
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.
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.
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).
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).

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.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
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 User Guide.
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.
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: 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.
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:
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.
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.
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 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 can change
with new product releases, refreshes, or fixes. If you cannot determine the cause of the problem from the
message, contact CA Support.
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: failed to load your called
subroutine. The errornumber indicates the cause. Action: For more information, see the link-editing in the
User Guide.
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.
CA Easytrieve® Report Generator 11.6

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.

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.
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 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 can change with new product releases,
refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA
Support.
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.
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.
The <string> command line option is not defined.
CA Easytrieve® Report Generator 11.6

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.
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. Action: If you are redirecting stdin to a
file, review your input file. Otherwise, reissue the command and retype your corrected input.
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.
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.
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.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
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.

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.
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.
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:
CA Easytrieve® Report Generator 11.6

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.
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.
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 User Guide.
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.

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 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.
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.
Empty Document. Error loading XML.
CA Easytrieve® Report Generator 11.6

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.
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.
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.
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.
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.

EZCM006
Printer name cannot be empty Reason: You have not specified a printer name. Action: Enter a valid
printer name.
Printer name cannot be empty
Reason:
CA Easytrieve® Report Generator 11.6

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.
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.
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.
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.
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.
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: The font name that you entered already exists.
Action: Enter a new valid font name.
Font already exists. Please enter another number
Reason:
The font name that you entered already exists.
CA Easytrieve® Report Generator 11.6

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.
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.
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.
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.
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.
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.
Default EBCDIC/ ASCII Font cannot be empty
Reason:
CA Easytrieve® Report Generator 11.6

You have not specified a default font for EBCDIC and ASCII.
Action:
Enter a valid value in the Default EBCDIC/ ASCII Font field.

EZCM019
Font Height cannot be empty Reason: You have not specified a font height. Action: Enter a valid value in
the Font Height field.
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.
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.
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.
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.
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. O_889573
Enter a value between 0 and 255
Reason:
You have not specified a value within the allowable range.
CA Easytrieve® Report Generator 11.6

Action:
Enter a valid value within the specified range.

IMS_DLI Messages
This section contains the IMS and DLI messages and codes (EZDLI).
This section contains the IMS and DLI messages and codes (EZDLI).

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.
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.
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 does not permit DL/I updates. Action: See your system administrator about
changing the site option to permit DL/I updates.
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 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 can change with new product releases,
refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA
Support.
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.
CA Easytrieve® Report Generator 11.6

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:
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:
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:
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.
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.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
Internal literal pool area too small.
Reason:
This is an internal error.
Action:
If you can reproduce this error, contact CA Support.

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.
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:
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.
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.
CA Easytrieve® Report Generator 11.6

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 procedures. Action: The trace table
can be useful in tracking recursive calls.
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.
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.

EZEIP021
The internal operation being requested is undefined. Reason: This is an internal error. Action: If you can
reproduce this error, contact CA Support.
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:
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.
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.
CA Easytrieve® Report Generator 11.6

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:
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.

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:
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: 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.
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
Internal PCode offset: <nnn>
Reason:
This information is useful to CA Support.
Action:
None
CA Easytrieve® Report Generator 11.6

EZEIP997
Interpreter terminated abnormally due to above error(s). Reason: This message is informational only.
Action: None
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).
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: See your system administrator to verify that the CA IDMS interface was correctly
installed.
An error occurred loading program xxxxxxxx.
Reason:
The specified CA IDMS interface program could not be found.
Action:
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, encountered an error
status from CA IDMS that was not expected. Action: See your CA IDMS documentation for information
about the specified status code.
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.
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 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 can change with new product releases, refreshes, or fixes. If
you cannot determine the cause of the problem from the message, contact CA Support.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
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:
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.
CA Easytrieve® Report Generator 11.6

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.
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.
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.
CA Easytrieve® Report Generator 11.6

• 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:
• 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.
This error can occur for multiple reasons. This article describes the various text messages that can be displayed.
CA Easytrieve® Report Generator 11.6

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 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: could not locate an entry point for
the exit program. Action: Verify that your library contains the exit program.
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.
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: The indexed access method
detected an error. Action: See the appropriate access method guide for the meaning of return code and
error code.
CA Easytrieve® Report Generator 11.6

ISAM return code is <return code> with error code of <error code>.
Reason:
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:
<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
CA Easytrieve® Report Generator 11.6

97 Critical error
107 OPEN for NC file (9A)
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.
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 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.
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. Seebefore Abend CodeH_2260132after (see page ). Action: Consult
the abend code for assistance in determining the underlying cause of the problem.
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.
CA Easytrieve® Report Generator 11.6

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: Contact CA Support.
HEAP MANAGER DOMAIN INITIALIZATION FAILURE.
Reason:
The memory heap manager failed to initialize.
Action:
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.
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 Option Module failed to load. Action:
Check that the EZTINI file points to the correct data set.
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.
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: A system CA90's component could
not be loaded. Action: Check licensing components. Contact CA Support.
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.
CA Easytrieve® Report Generator 11.6

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 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.
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.

ETOPLOAD Utility Messages


This section lists the messages and codes that can display if 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 can change with new product releases,
refreshes, or fixes. If you cannot determine the cause of the problem from the message, contact CA
Support.
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.
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.
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.
The <string> command line option was specified more than once. The successive specifications are ignored.
Reason:
CA Easytrieve® Report Generator 11.6

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.
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 Installation Guide.
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.

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.
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.
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.
CA Easytrieve® Report Generator 11.6

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.
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.
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.
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.

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.
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.
Value has more than <nnn> characters.
Reason:
The value has more than the maximum number of characters allowed for the keyword.
CA Easytrieve® Report Generator 11.6

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.
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.
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
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.
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. 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.
The mask is missing.
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.
This section contains the system termination message.
CA Easytrieve® Report Generator 11.6

EZSHT101
System Termination This message is displayed whenever a serious error occurs that might indicate an
internal 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:
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 .
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 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 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.
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 SQL interface program could not
be found. Action: Check with your system administrator to make sure that the SQL interface is properly
installed.
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 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.
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.
CA Easytrieve® Report Generator 11.6

Action:
See the appropriate SQL DBMS guide for the meaning of the error code.

EZSQL003
SQL error code xxxx, xxxxxxxx. Reason: The 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.
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 SQL interface was not initialized. Action: This is an internal error. Contact
CA Support.
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.
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 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 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.
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.
CA Easytrieve® Report Generator 11.6

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.
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.

EZSRT013
The sort initialization routine requested an abort. <text> Reason: This is an internal error, where text can
be any of the following:
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.


CA Easytrieve® Report Generator 11.6

• Initialization procedure failure.

• GetBuff procedure failure.

• SORT procedure failure.

• 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.
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
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.
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 CA Support for assistance.

Runtime Error Check Codes


EBND
Code Category: Runtime Error Check Reason: Index or subscript exceeded boundaries.
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.
Code Category:
Runtime Error Check
Reason:
Insufficient storage in region to satisfy request.

Runtime Code Generator Codes


ECGO
Code Category: Runtime Code Generator Reason: Invalid request passed to code generator.
Code Category:
Runtime Code Generator
Reason:
Invalid request passed to code generator.

IMS_DLI Interface Codes


CA Easytrieve® Report Generator 11.6

EDLI
Code Category: IMS/DLI Interface Reason: Unrecoverable error during IMS/DLI processing.
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).
Code Category:
Dynamic Loader
Reason:
Module not found (CICS only).

EDSO
Code Category: Dynamic Loader Reason: Dynamic load table overflowed.
Code Category:
Dynamic Loader
Reason:
Dynamic load table overflowed.

Dynamic Segment Manager Codes


EDSA
Code Category: Dynamic Segment Manager Reason: Segment already defined.
Code Category:
Dynamic Segment Manager
Reason:
Segment already defined.

EDSO0
Code Category: Dynamic Segment Manager Reason: Internal procedure stack overflow.
Code Category:
Dynamic Segment Manager
Reason:
Internal procedure stack overflow.

EDSS
Code Category: Dynamic Segment Manager Reason: Segment not defined.
Code Category:
Dynamic Segment Manager
Reason:
Segment not defined.

EDST
Code Category: Dynamic Segment Manager Reason: Invalid Segment.
Code Category:
Dynamic Segment Manager
Reason:
Invalid Segment.
CA Easytrieve® Report Generator 11.6

EDSX
Code Category: Dynamic Segment Manager Reason: Unable to expand segment table.
Code Category:
Dynamic Segment Manager
Reason:
Unable to expand segment table.

Heap Manager Codes


EBND0
Code Category: Heap Manager Reason: Bounds check failure.
Code Category:
Heap Manager
Reason:
Bounds check failure.

EBSL
Code Category: Heap Manager Reason: GETMAIN length error.
Code Category:
Heap Manager
Reason:
GETMAIN length error.

EFLD
Code Category: Heap Manager Reason: Field check error.
Code Category:
Heap Manager
Reason:
Field check error.

EFML
Code Category: Heap Manager Reason: Invalid MOVE length.
Code Category:
Heap Manager
Reason:
Invalid MOVE length.

EFNF
Code Category: Heap Manager Reason: Null check failure.
Code Category:
Heap Manager
Reason:
Null check failure.

EFVL
Code Category: Heap Manager Reason: Invalid VARCHAR length.
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).
CA Easytrieve® Report Generator 11.6

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.
Code Category:
Heap Manager
Reason:
Invalid freemain request.

EHMH
Code Category: Heap Manager Reason: Invalid heap tag.
Code Category:
Heap Manager
Reason:
Invalid heap tag.

EHMI
Code Category: Heap Manager Reason: Invalid storage control request.
Code Category:
Heap Manager
Reason:
Invalid storage control request.

EHML
Code Category: Heap Manager Reason: Length error.
Code Category:
Heap Manager
Reason:
Length error.

EHMN
Code Category: Heap Manager Reason: No storage available.
Code Category:
Heap Manager
Reason:
No storage available.

EHMO
Code Category: Heap Manager Reason: Internal procedure stack overflow.
Code Category:
Heap Manager
Reason:
Internal procedure stack overflow.

EHMQ
Code Category: Heap Manager Reason: Invalid FAD chain.
Code Category:
Heap Manager
Reason:
Invalid FAD chain.
CA Easytrieve® Report Generator 11.6

EHMR
Code Category: Heap Manager Reason: Error reading temporary storage record.
Code Category:
Heap Manager
Reason:
Error reading temporary storage record.

EHMV
Code Category: Heap Manager Reason: Storage overrun detected.
Code Category:
Heap Manager
Reason:
Storage overrun detected.

EHMW
Code Category: Heap Manager Reason: Error writing temporary storage record.
Code Category:
Heap Manager
Reason:
Error writing temporary storage record.

EHMX
Code Category: Heap Manager Reason: Error resolving relocatable pointer.
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.
Code Category:
Input/Output Statement Handler
Reason:
Invalid request passed to input/output statement handler.

EIO1
Code Category: Input/Output Statement Handler Reason: An input/output statement referenced a file that
had not been activated.
Code Category:
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.
Code Category:
Input/Output Statement Handler
Reason:
Load for access method interface routine failed.
CA Easytrieve® Report Generator 11.6

EIO3
Code Category: Input/Output Statement Handler Reason: Insufficient main storage.
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.
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.
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.
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.
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.
Code Category:
Input/Output Statement Handler
Reason:
File control validity check failed.

EIDA
Code Category: Input/Output Statement Handler Reason: IDMS could not be found.
Code Category:
Input/Output Statement Handler
Reason:
IDMS could not be found.
CA Easytrieve® Report Generator 11.6

EIOX
Code Category: Input/Output Statement Handler Reason: Unexpected response received for a CICS/VS
command.
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.
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.
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.
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.
Code Category:
System Spool Printer Interface Module
Reason:
Spool file write error.

Task Execution Control Program Codes


EKX0
Code Category: Task Execution Control Program Reason: Application request not understood by
ETKXCON.
Code Category:
Task Execution Control Program
Reason:
Application request not understood by ETKXCON.
CA Easytrieve® Report Generator 11.6

EKX1
Code Category: Task Execution Control Program Reason: termination in progress.
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.
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.
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.)
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.
Code Category:
Task Execution Control Program
Reason:
Quiesce requested by linked to program.

EKX8
Code Category Task Execution Control Program Reason: Internal stack overflow.
Code Category
Task Execution Control Program
Reason:
Internal stack overflow.

EKX9
Code Category: Task Execution Control Program Reason: Version mismatch between compiler and
runtime system.
Code Category:
Task Execution Control Program
Reason:
Version mismatch between compiler and runtime system.
CA Easytrieve® Report Generator 11.6

EKXB
Code Category: Task Execution Control Program Reason: Unable to load runtime anchor module (TSO
only).
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).
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).
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).
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.
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).
Code Category:
Task Execution Control Program
Reason:
Error writing PLA to auxiliary storage (CICS only).

Task Management Program Codes


EKX3
Code Category: Task Management Program Reason: Indicates an error initializing heap local domain.
Code Category:
Task Management Program
CA Easytrieve® Report Generator 11.6

Reason:
Indicates an error initializing heap local domain.

EKX4
Code Category: Task Management Program Reason: Indicates an error terminating heap local domain.
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.
Code Category:
Task Management Program
Reason:
Indicates internal register stack overflow.

EKXA
Code Category: Task Management Program Reason: Indicates that previous abend occurred.
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.
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.
Code Category:
Task Management Program
Reason:
Indicates an invalid request.

EKXO
Code Category: Task Management Program Reason: Indicates an invalid option update order.
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.
Code Category:
Task Management Program
Reason:
Indicates that the (E)STAE exit is taking a SNAP dump.
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).
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.
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.
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.
Code Category:
Printer File Manager
Reason:
Error opening the printer file.

EPR3
Code Category: Printer File Manager Reason: Error closing the printer file.
Code Category:
Printer File Manager
Reason:
Error closing the printer file.

EPR4
Code Category: Printer File Manager Reason: Error writing the printer file.
Code Category:
Printer File Manager
Reason:
Error writing the printer file.

EPR5
Code Category: Printer File Manager Reason: Cannot find printer definition.
Code Category:
Printer File Manager
Reason:
CA Easytrieve® Report Generator 11.6

Cannot find printer definition.

EPR6
Code Category: Printer File Manager Reason: Error opening the system message file.
Code Category:
Printer File Manager
Reason:
Error opening the system message file.

EPR9
Code Category: Printer File Manager Reason: Insufficient storage
Code Category:
Printer File Manager
Reason:
Insufficient storage

Reporting Codes
ERP1
Code Category: Reporting Reason: Insufficient storage for report work area.
Code Category:
Reporting
Reason:
Insufficient storage for report work area.

ERP2
Code Category: Reporting Reason: Insufficient storage for summary work area.
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.
Code Category:
Runtime Initialization Stub
Reason:
Runtime system initialization/termination error.

ERS1
Code Category: Runtime Initialization Stub Reason: Transfer of control failure.
Code Category:
Runtime Initialization Stub
Reason:
Transfer of control failure.

Sort Interface Codes


CA Easytrieve® Report Generator 11.6

ESIB
Code Category: Sort Interface Reason: Nonzero return code from Sort.
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.
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:
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.
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.
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.
Code Category:
SQL Interface
Reason:
Nonzero return code from SQL on automatic processing.

Terminal Printer Despooler Program Codes


CA Easytrieve® Report Generator 11.6

ETID
Code Category: Terminal Printer Despooler Program Reason: Unsupported printer device.
Code Category:
Terminal Printer Despooler Program
Reason:
Unsupported printer device.

ETIO
Code Category: Terminal Printer Despooler Program Reason: Internal stack overflow.
Code Category:
Terminal Printer Despooler Program
Reason:
Internal stack overflow.

ETIS
Code Category Terminal Printer Despooler Program Reason: Invalid spooled report encountered.
Code Category
Terminal Printer Despooler Program
Reason:
Invalid spooled report encountered.

ETIX
Code Category: Terminal Printer Despooler Program Reason: Task initialization or termination error.
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.
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.
Code Category:
Virtual File Manager
Reason:
Invalid request passed to virtual file manager.

EVF1
Code Category: Virtual File Manager Reason: Insufficient main storage.
Code Category:
Virtual File Manager
Reason:
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.
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.
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.
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.
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.
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.
Code Category:
Virtual File Manager
Reason:
Insufficient space in the VFM data set to contain the file.
CA Easytrieve® Report Generator 11.6

EVF8
Code Category: Virtual File Manager Reason: Invalid request returned by the input/output system. This is
a general failure category.
Code Category:
Virtual File Manager
Reason:
Invalid request returned by the input/output system. This is a general failure category.

EVF9
Code Category: Virtual File Manager Reason: Leading and trailing record lengths are not equal.
EVFAError opening the VFM data set.
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.
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.
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.
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.
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.
Code Category:
Virtual File Manager
CA Easytrieve® Report Generator 11.6

Reason:
Error reading from or writing to the VFM data set.

EVFF
Code Category: Virtual File Manager Reason: Too much pending work queued.
Code Category:
Virtual File Manager
Reason:
Too much pending work queued.

EVFG
Code Category: Virtual File Manager Reason: Invalid level number on a read block request.
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.
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.
Code Category:
Virtual File Manager
Reason:
Load for VFM data set handler failed.

10 CA EZ/Key
Environment for developing and maintaining CA Easytrieve Plus programs.
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

11 Documentation for Previous Releases


Legacy documentation.

Documentation is available for the following products and releases in PDF format unless otherwise noted.

Product Language Releases Notes


CA Easytrieve® Report Generator 11.6

CA Easytrieve® Report English 6.4, 11 SP4, 11.5 The bookshelves for 11 SP4
Generator and 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 English 3.1 Administrator, Installation,
Query and User guides only.
CA Easytrieve® Online English 1.3, 1.4 Introduction to the Language,
Query Report Generator Language Reference, and
Programmer guides are
available in PDF format.
Other guides are available in
BookManager format only.

12 Additional Resources
Product support, user communities, education, and social media.

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
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 Education Learning Management System Video
• Broadcom Mainframe Training
• Broadcom Education YouTube Channel
Social Media
Follow us on social media:
• Facebook
• LinkedIn
• Twitter
CA Easytrieve® Report Generator 11.6

13 Product Names
Product names referenced in the documentation.
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

14 Product Accessibility Features


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
CA Easytrieve® Report Generator 11.6

• 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.

15 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 CA at any time.
This Documentation is proprietary information of CA and may not be copied, transferred, reproduced, disclosed, modified or
duplicated, in whole or in part, without the prior written consent of CA.
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 CA 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 CA that all copies and partial copies of the Documentation have been returned to CA 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 CA.
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.

You might also like