SC33 0079 2_CICS_VS_Version_1_Release_5_Application_Programmers_Ref_Macro_Level_May80 2 CICS VS Version 1 Release 5 Application Programmers Ref Macro Level May80
SC33-0079-2_CICS_VS_Version_1_Release_5_Application_Programmers_Ref_Macro_Level_May80 SC33-0079-2_CICS_VS_Version_1_Release_5_Application_Programmers_Ref_Macro_Level_May80
User Manual: SC33-0079-2_CICS_VS_Version_1_Release_5_Application_Programmers_Ref_Macro_Level_May80
Open the PDF directly: View PDF 
.
Page Count: 624
| Download | |
| Open PDF In Browser | View PDF |
SC33-0079-2
Customer Information
Control System/Virtual
Storage (CICS/VS)
Version 1 Release 5
Program Product
Application Programmer's
Reference Manual
(Macro ~evel)
Program Numbers
-------- ---- ----------------_
.-
5740-XX1
5746-XX3
(CICS/OS/VS)
(CICS/DOS/VS)
Third Edition (Kay 1980)
This edition applies to Version 1 Release 5 (Version 1.5) of the IBM
program product customer Information Control Systam/Virtual Storage
(CICSjVS), program numbers 5146-XX3 (for DOS/VS) and 5140-XX1 (for
OS/VS). Until the OS/vs version is released, the information applicable
to that version is for planning purposes only.
This edition is based on the CICS/VS Version 1.4.1 edition, and changes
from that edition are indicated by vertical lines to the left of the
changes. Note, however, that the 1.4.1 edition remains current and
applicable for users of Version 1.4.1 of CICS/VS.
Information in this publication is subject to change. Changes will be
published in new editions or technical newsletters. Before using this
publication, consult the latest IBM Systemt370 and 4300 Processors
Bibliography, GC20-0001, to learn which editions and technical
newsletters are current and applicable.
It is possible that this material may contain references to, or
information about, IBK products (machines and programs), programming, or
services that are not announced in your country. Such references or
information must not be construed to mean that IBM intends to announce
such IBK products, programming, or services in your country.
Publications are not stocked at the addresses given below; requests for
copies of IBK publications should be made to your IBM representative or
to the IB! branch office serv ing your locality.
A form for reader's comments is provided at the back of this
publication; if the form has been removed, comments may be addressed
either to:
International Business !achines Corporation,
Department 812BP,
1133 Westchester Avenue
White Plains, New York 10604 •
. 1 or to:
IB! United Kingdom Laboratories Limited,
Programming Publications, !ail Point 095,
Bursley Park,
Winchester, Hampshire S021 2JH, England.
IB! may use or distribute any of the information you supply in any way
it believes appropriate without incurring any obligation whatever. You
may, of course, continue to use the information you supply.
~
Copyright International Business !achines Corporation 1977, 1978, 1979,
1980
t·
'J
Preface
This publication contains detailed information necessary to design and
prepare application programs to execute under either of two IBM program
products: CICS/DOS/VS (5746-XX3) and CICS/OS/VS (5740-XX1).
It is
intended for use mainly by application programmers, but will be useful
also for system programmers and system analysts.
This publication consists of eight parts, the first seven comprising
one or more chapters and the eighth containing appendixes. Each of the
first seven parts (except Part 1) contains information on a particular
topic, both procedural and reference. In general, each chapter consists
of the following:
•
A brief introduction to the facilities available by specifying the
macro instructions that are described in detail in the remainder of
the chapter.
•
The syntax of each macro instruction in the standard form
~escribed in Chapter 1.2).
•
The operands, in alphabetical order, that can be specified with the
macro instructions.
Where appropriate, examples in the three programming languages
(Assembler, COBOL, and PL/I) that can be used with CICS/VS have been
included.
Part 1 is an introduction to macro-level application programming. It
compares the CICS/VS DB/DC system with the conventional batch system of
data processing. It also describes the general format of a CICS/VS
macro instruction and explains the syntax notation used throughout the
publication.
Part 2 describes symbolic storage definition. This, together with
addressability, must be specified in the application program to enable
the application program to be executed under CICS/VS. The preparation
of an applica~ion program for execution is described in the CICS/VS
system Programmer's Guides.
Part 3 describes data base operations:
browsing) and DL/I services.
file control (including
Part 4 describes data communication operations:
basic mapping support, and batch data interchange.
terminal control,
Part 5 describes control operations: interval control, task control,
program control, storage control, transient data control, and temporary
storage control.
Part 6 describes built-in functions:
table search, phonetic
conversion, data field verif£cation, data field edit, bit manipulation,
input formatting, and weighted retrieval.
Part 7 describes error handling, debugging, and recovery/restart
services: trace services, dump services, journal services, and
recovery/restart services.
Part 8 consists of appendixes. These include sample programs, BMS
examples, fields that make up the application programming interface
~PI), and translate tables.
Preface
i.
In this publication, the term VTA~ refers to ACF/VTAM, to ACF/VTAME
(CICSjDOS/VS only), and to the Record Interface of ACF/TCAM (CICS/OS/VS
only). The term TCAM refers both to TCAM and to the DCB Interface of
ACF/TCAK. The term ~ refers to BTAM (CICS/OS/VS only) and to BTAM-ES
(CICS/DOS/VS only). For further details of system requirements, refer
to the publication CICStVS General Information.
For more information about CICS/VS and related subjects discussed in
this manual, the reader is referred to the publications listed in the
Bibliography at the end of this manual. A glossary of terms applicable
to CICS/VS is provided in the publication CI£~~~gn~ral InfQrmat~Q~.
iv
CICS/VS APRM(KL)
Contents
PART 1.
CHAPTER
INTRODUCTION
1.1~
CHAPTER 1.2.
MACRO-LEVEL APPLICATION PROGRAMMING
• 3
MACRO FORMAT AND SYNTAX NOTATION • •
• 9
CHAPTER 1.3.
PROGRAMMING TECHNIQUES AND RESTRICTIONS
Application Program Packaging
Quasi-reenterability • • • •
Storage Definition • • • • • • •
Program Initialization • • • • •
Restrictions • • • • • • • • • • • • • • • • • • • • • •
Assembly-time Service (DFHCOVER Macro) • • • •
Testing Responses to Macro Instructions
·.
PART 2.
13
17
18
18
19
20
23
23
.
STORAGE DEFINITION
CHAPTER 2.1. INTRODUCTION TO STORAGE DEFINITION.
CICS/VS storage Areas
Common System Area (CSA) • • • •
Task Control Area (TCA)
••••
27
27
33
35
CHAPTER
Storage
Storage
Example
37
37
38
44
..
..
2.2.
STORAGE DEFINITION
ASSEMBLER LANGUAGE
••••
Defined During Initialization
• • • • •
• • ••
Defined During Execution • • • • • • • • • • • • • • •
of CICS/VS Assembler-Language Application Program • • •
CHAPTER 2.3. STORAGE DEFINITION - COBOL • •
Storage Defined During Initialization • •
Storage Defined During Execution • •
Addi tional Guidelines • • • • • • •
Example of CICS/VS COBOL Application Program
CHAPTER
Storage
Storage
Example
PART 3.
47
47
49
· ., . . . . .
54
57
59
59
60
66
2.4. STORAGE DEFINITION - PL/I • • • •
Defined During Initialization
Defined During Execution • • • •
of CICS/VS PL/I Application Program
DATA BASE OPERATIONS
CHAPTER 3.1.
INTRODUCTION TO DATA BASE OPERATIONS • •
File Control Macro Instruction •
• • • •
DL/I Services
• • • • • • • • ••••••••
71
71
71
CHAPTER 3.2. FILE CONTROL ~FHFC MACRO INSTRUCTION) • • • • •
Browsing • • • • • •
• • • • •
segmented Records
• • • •
Alternate Indexing •
• •••
• • ••
Indirect Accessing •
•• • • • • • • • • • •
Duplicate Records
Record Identification Field • •
DAM Data Sets • • • • • • •
Direct Retrieval (TYPE=GET)
Direct Update or Addition (TYPE=PUT)
Direct Deletion, VSAM Only (TYPE=DELETE) • • • •
• •
•
Obtain a File Work Area (TYPE=GETAREA) • • • • •
•
Release Storage/Exclusive Control (TYPE=RELEASE)
Initiate Browse (TYPE=SETL)
• • • • • • •
• • • • • • •
Forward Brow se (TY PE=GETNEXT)
••••••••••
73
74
75
76
76
79
81
·.
.
Contents
84
87
96
99
100
103
105
109
Backward Browse, VSAM and Assembler Language Only (TYPE=GETPREV) ••
Terminate Browse (TYPE=ESETL)
.................
• ••
Reset Browse (TYPE=RESETL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Test Response to a Request for File Services (TYPE=CHECK)
File Control Response Codes
• • .. .. • • .. •
• • .. • • •
Operands of DFHFC Kacro
.. ~
114
116
118
121
121
126
CHAPTER 3.3. DL/I SERVICES .. .. .. •
• ..
• ..
Obtaining Addresses of Program Communication Blocks ....
Building Segment Search Arguments .. .. • ..
.. .. .. .. ..
Acquiring an I/O Work Area . . . . . ~ .. .. .. .. • • .. .. • .. •
Requesting DL/I Services .. • .. .. • .. .. • • • .. .. • ..
Releasing a PSB in the CICS/VS Application Program .. ..
DL/I Services Response Codes • • • • .. .. ..
Test Response to a DL/I Request' (TYPE=CHECK) ..
DL/I Requests in an Assembler-Language Program (CICS/OS/VS)
DL/I Requests in a COBOL Program (CICSjOS/VS) .......
DL/I Requests in a PL/I Program (CICS/OS/VS) •
.. • •
Operands of DFHFC Kacro (DL/I) • .. • • • .. .. • •
135
135
137
138
139
141
142
145
146
148
150
152
....
•
.. • • •
....
..
.. ..
.. .. • •
• .....
• • ..
.. .....
........
.. • •
~!RT~~__ DA!!_COMMUliICAT!ON~g~RATIONS
. ..
INTRODUCTION TO DATA COMMUNICATION OPERATIONS
CHAPTER 4.1.
159
CHAPTER 4.2. TERMINAL CONTROL (DFHTC MACRO INSTRUCTION)
•
Facilities for all Terminals and Logical units ., • • • • ..
Facilities for Logical units .. .. .. • .. ..
• .. • ..
Terminal-Oriented Task Identification
.. • .. •
Syntax of the DFHTC Macro Instruction • • ..
System/3 .. .. •
System/370 .. .. .. .. •
• • ..
. ..
System/7
• ..
-. "
..
2260 Display Station .. ..
• •
• .. ..
.,
2265 Display station .. ..
..
2140 Communication Terminal
...
2141 Communication Terminal
2170 Data Communication System ..
..
2180 Data Transmission Terminal ...
.. ..
. ..
2980 General Banking Terminal
3210 Information Display System ~TAM and TCAM) .........
3210 Logical Unit ..... •
3210 LUTYPE2 Logical unit
3210 LUTYPE3 Logical unit . . . . . . . .
.. ..
3210 SCSPRT Logical unit ..
..
3270 in 2260 Compatibility Mode (BTAM only)
.. • ..
• •
3600 Finance Communication System (BTAM)
..
3600 (3601) Logical unit ..
3600 Pipeline Logical Unit • .. .. .. .. .. .. .. •
3600 (3614) Logical Unit ............. ..
.. .. • • .. ..
3630 Plant Communication System . . . ..
..
3650 Host Command Processor Logical 'Unit
.......
3650 Host Conversational (3210) Logical Unit .. • .. ..
.. .
• .. ..
3650 Pipeline Logical Unit . . . . . . . . . . . . . .
3650 Host Conversational (3653) Logical Unit
• ..
3650 Interpreter Logical Unit • • • • •
.. • •
..
3660 Supermarket Scanning System (BTAM)
..
3135 Programmable Buffered Terminal
•••
..
3140 Data Entry System • .. • .. • .. • .. ~
.. .. • ..
3161 Interactive Logical Unit • • • • •
..
3110 Interactive Logical Unit ... .; • .; ......
.. ..
3110 Batch and Batch Data Interchange Logical Unit ....
.. •
3110 Full Function Logical Unit
.. .. •
.. .. .. •
3780 Data Communications Terminal • .. •
3190 Inquiry Logical Unit
........
3190 Full Function Logical Unit
•
j
..
..
..
..
•
. .. ..
.
•
·
· .. .. . .
....
... .
..
..
•
•
..
..
Ii
..
..
•
..
Ii
.
Ii
.
........
.
..
j
j
..
vi
CICS/VS APRM(ML)
•
.........
..
j
..
..
..
161
163
169
111
119
182
182
183
185
186
186
181
190
190
191
197
198
200
201
202
203
205
208
208
208
209
209
209
210
210
211
211
212
214
215
215
216
216
216
211
211
.o..... . . . . . .
. .
3190 (SCS Printer) Logical unit
••
3190 (3210-Display) and 3190 (3210-Printer) Logical Units • • • • •
3190 Batch Data Interchange Logical unit •
•
1110 Audio Response Unit • • .. • • • • • • • • .. ..
LUTYPE4 Logical Unit • .. .. • • .. .. • .. .. .. • .. •
.. • • ..
..
Other CICS/VS-Supported Terminals
.. .. .. •
.. ...
TCAM Supported Logical Units (CICS/OS/VS Only) • .. • •
.. ..
Operands of DFHTC Macro
............
.... .. •
• •
•
211
211
218
219
220
221
221
222
CHAPTER 4.3.
BASIC MAPPING SUPPORT
.. • .. •
•
Advantages of BMS
. . . . .. • • ..
• • • • • .. •
• •
Facilities of BMS
.............
Mapping Concepts and Technigues'..
.......................
Map Definition Macro Instructions
• • • ..
. . . • .. •
Input and Output Operations Using the BMS Macro Instructions •
•
Input Mapping without I/O (TYPE= MAP) • .. .. .. .. •
.. • • ..
Input Operations with Mapping (TYPE=IN)
.... ~ .. .. • ...
• ....
Building output Pages using Maps (TYPE=PAGEBLD)
.......
.. ..
Building Output Pages wi thout Using Maps (TYPE=TEXTBLD)
......
Direct Ou tpu t (TYPE=OUT) • .. • • • • • • • •
.. • .. •
Terminating a Logical Message (TYPE=PAGEOUT) • • .. .. • .. • .. •
..
Deleting a Logical Message (TYPE=PURGE)
...................
•
Message Routing (TYPE=ROUTE) .. .. • • • • .. • • • .. .. • • .. .. ...
Checking the Response to a BMS Request (TYPE=CHECK)
.. ..
.. ..
BMS Response Codes .. • • .. .. .. •
• • .. .. .. .. •
BMS Message Recovery .. .. • • • • .. .. .. .. .. .. • • .. .. • • .. • •
Terminal Code (TC) Table .. • • .. .. • .. .. .. • • • .. .. •
•
Standard Attribute List and printer Control Characters ~PHBMSCA)
•
Standard A tten tion Ident i f ier Li st (DPHA ID)
..................
Programming Considerations for Paging Commands on Display Devices
..
Operands of DFHBM S Macros
. . . . .. • • .. .. • • • .. • .. • .. .. •
•
235
235
236
240
241
214
211
218
280
290
291
293
294
295
300
300
303
303
304
304
305
301
CHAPTER 4.4.
BATCH DATA INTERCHANGE (DFHDI MACRO INSTRUCTION) . . . . .
Addition of Records to a Data Set (TYPE=ADD) • • • ..
..
Deletion of Records from a Data Set (TYPE=ERASE) .. • .. .. • • .. .. • ..
Replacement of Records in a Data Set (TYPE=REPLACE)
....
Interrogation of Data Set (TYPE=QUERY) • • • .. • • • .. .. .. • •
Termination of Operations on a Data Set' (TYPE=END) •
Abnormal Termination of Operations on a Data Set ~IPE=ABORT)
•
Transmission of Data from Host to Output Devices (TYPE=SEND) • •
Transmission of Data from Data Set to Host (TYPE=RECEIVE)
.. • ..
Obtaining the Relative Record Number of Next Record (TYPE=NOTE)
...
Suspension of Execution of Task (TYPE=WAIT)
Testing Response to a Reguest for Data Interchange Services
(TYPE=CHECK)
..................... .
.. • ..
• • .. •
Batch Data Interchapge Response Codes
• • ..
..
• • ..
Operands of DFHDI Macro
• • ~ .. • .. • • .. ..
321
321
328
329
330
330
331
331
332
333
333
.....o....o...
.
.
PART 5.
334
335
336
CONTROL OPERATIONS
CHAPTER 5.1.
INTRODUCTION TO CONTROL OPERATIONS.
.. ..
CHAPTER 5.2.
INTERVAL CONTROL (DFHIC MACRO) .. ..
T ime-of-Day Upda ting (TYPE=GETIM E) .. .. • .. • ~ ..
Delay Processing of a Task (TYPE=WAIT) • .. • .. .. ..
..
Signal Expiration of a Specified Time (TYPE=POST)
.....
Initiate a Task without Data (TYPE=INITIATE) .. .. .. .. .. ..
Task Initiation with Data (TYPE=PUT) .. • .. .. .. ..
Retrieve Time-Ordered Data (TYPE=GET)
• ~ .. • •
.. ..
Cancel a Reguest for Time Services (TYPE=CANCEL) .. .. .. .. •
I/0 Error Retry (TYPE=RETRY) .. .. .. .. .. .. .. .. .. .. • .. ...
Test Response to a Reguest for Time Services (TYPE=CHECK)
Interval Control Response Codes
......
.. •
Operands of D FHIC Macro
. . . . . . . . . . . . . ~ • • .. .. .. .. • .. ..
.
•
• 341
• 343
• .. .. 344
..
• .. • 346
• .. .. 348
.. 350
352
• •
355
.. ..
351
. . . . . . . 359
.. • • 360
• • • .. .. 360
363
..
•
Contents
vii
CHAPTER 5.3. TASK CONTROL (DFBKC MACRO) • • • • • • • •
Initiate a Task (TYPE=A'rTACH)
• • • • • • .o.o •. .o •.
Change Priority of a Task (TYPE=CHAP)
Synchronize a Task (TYPE=WAIT) . . . . . . . . .
..
Enqueue Upon a Resource (TYPE=ENQ) • • • • • • •
Dequeue Upon A Resource (TYPE=DEQ)
Declare a Task to be Purgeable (TYPE=PURGE)
Declare a Task to be Nonpurgeable (TYPE=NOPURGE)
• •
Operands of DFHKC Macro .o.o.....o. • . . • • • • . • • • • •
..
361
• 368
• 313
315
319
381
• 384
• 384
• 386
CHAPTER 5.4. PROGRAM CONTROL (DFHPC MACRO)
Pass Program Control Anticipating Return (TYPE=LINK) • • a •
•
Transfer Program Control (TYPE=XCTL) • •
• •
Load a Program (TYPE=LOAD) • • • • • • • • • • •
•
• • • •
Return Program Control (TYPE=RETURN) ...
Delete a Loaded Program (TYPE=DELETE)
• • • •
•
Abnormally Terminate a Transaction (TYPE=ABE ND)
• • .o.o
•
Activate or Cancel an Exit for Abnormal Termination Processing
(TYPE=SETXIT) • • • • • • • • • • • • • • • • • • • • •
Reactivate an Exit for Abnormal Termination Processing
(TYPE=RESETXIT) a, • • • • • • • • • • • • • • • • • • • • • • • • •
Convert sy mbolic Label to Address (TYPE=COBADDR) • .. .o.
.....
Test Response to a Request for Program Services ~YPE=CHECK)
•
Program Control Response Codes. • •
• •
•
Operands of DFHPC Macro
• .,; • •
• ..
•
CHAPTER 5.5. STORAGE CONTROL (DFHSC MACRO)
Obtain and Initialize Main Storage (TYPE=GETMAIN)
Release Main storage (TYPE=FREEMAIN)
• • • • • • • • • • •
Ope rands of DFHSC Macro
389
391
392
393
395
396
391
399
402
403
404
404
406
• • • 409
• • 410
• • • 412
414
CHAPTER 5.6. TRANSIENT DATA CONTROL (DFHTD MACRO)
Asynchronous Transaction Processing
Dispose of Data (TYPE=PUT) • • • • •
•• • • •
Acquire Queued Data (TYPE=GET) • • •
••••• • •
•
Force End of Volume on an Extrapartition Data Set (TYPE=FEOV)
Purge Intrapartition Data (TYPE=PURGE) • • • • • • • • •
•
Test Response to a Request for Transient Data Services
(TYPE=CHECK)
••••••••
• • • •
•••
Transient Data Response Codes
• • • • • • • • •
Operands of DFHTD Macro
.o...
. •
•
•
•
•
•
•
417
419
421
423
426
427
• 428
• 428
• 431
CHAPTER 5.1. TEMPORARY STORAGE CONTROL (DFHTS MACRO)
..o..
• 433
Store Temporary Data as a Single Unit of Information (TYPE=PUT)
435
Store Data to a Temporary Storage Message Set (TYPE=PUTQ)
• 431
438
Retrieve a Single unit of Temporary Data (TYPE=GET)
•••••
Retrieve Data from a Temporary storage Message Set (TYPE=GETQ)
• 441
Release a Single Unit of Temporary Data (TYPE=RELEASE) . . . . .
• 442
Purge a Temporary Storage Message Set ~YPE=PURGE) . . . . . . . .. • • 443
Test Response to a Request for Temporary Storage Services
(TYPE=CHECK)
••••••
• .. • .. • • • 444
Temporary Storage Response Codes • •
• • • •
• • • • • • • 444
Operands of DFHTS Macro • • • .o
•••
447
PART 6.
CICS/VS BUILT-IN FUNCTIONS
CHAPTER 6.1.
INTRODUCTION TO CICS/VS BUILT-IN FUNCTIONS • • • • • • 453
CHAPTER 6.2. STORAGE DEFINITION FOR BUILT-IN FUNCTIONS
(DFHBFTCA MACRO)
....o...
• . . • • • . •
CHAPTER 6.3.
CICS/VS BUILT-IN FUNCTIONS (DFHBIF MACRO)
Table Search Built-in Function (TYPE=TSEARCH)
...o.o
...
Phonetic Conversion Built-in Function (TYPE=PHONETIC)
•••
Field Verify Built-in Function (TYPE=FVERIFY)
• •
.......o
viii
CICS/VS APRM(ML)
• 455
• 451
• 451
• 460
• 463
Field Edit Built-in Function (TYPE=DEEDIT)
Bit Manipulation Built-in Functions • • •
Input Formatting Built-in Functions
Weighted Retrieval Built-in Functions • • • •
Operands of DFHBIF Macro • • • • • • • •
PART 7.
. .. . . . . .
....
.
.. .
•
•
•
• • •
•
465
466
470
477
486
ERROR HANDLING AND DEBUGGING
CHAPTER 7.1.
INTRODUCTION TO ERROR HANDLING AND DEBUGGING
CHAPTER 7.2.
SEQUENTIAL TERMINAL SUPPORT
•••
CHAPTER 7.3. TRACE CONTROL (DFHTR MACRO)
Trace Table
••••••
Controlling the Trace . . . . . .
Initiate Trace (TYPE=ON) • • • •
Terminate Trace (TYPE=OFF)
Selected Entry Trace (TYPE=ENTRY)
Operands of DFHTR Macro . . . . . . . .
• 499
• • • 501
• • • • 503
• • 504
• 506
• .. • • • • ~ 507
• 508
..
..
508
• • • • • • • 509
CHAPTER 7.4. DUMP CONTROL (DFHDC MACRO)
Dump Transaction Storage ~YPE=TRANSACTION)
••••
Dump CICS/VS Storage (TYPE=CICS) • • • • • • • •
.. • • •
•
Dump Transaction Storage and CICS/VS Storage (TYPE=COMPLETE) • • • •
Dump Partial Storage (TYPE=PARTIAL)
• • • •
• •
Operands of DFHDC Macro • • • • • • • • • •
• • • •
•
513
515
516
517
518
520
CHAPTER 7.5.
JOURNAL CONTROL (DFHJC MACRO)
• 523
Acquire a Journal Control Area (TYPE=GETJCA) . . . . . . . . . . .
525
Create a Journal Record and Wait for Output (TYPE=PUT) • • • •
• 527
Crea te a Journal Record (TYPE=WRITE) • • • • • •
• • .. • 531
Wait for Output of a Journal Record (TYPE=WAIT)
• 536
Test Response to a Request for Journal Services (TYPE=CHECK) • • • • 539
Journal Control Response Codes • .. •
• • • •
• 539
Operands of DFHJC Macro
• • .. • • • • • • • • • • .. •
• 541
CHAPTER 7.6. RECOVERY/RESTART ~YNC POINT) CONTROL ~FHSP MACRO)
• 545
Specify a Synchronization Poin t (TYPE=USER)
• • • • • • • • • • • • 545
Backout Recoverable Resources (TYPE=ROLLBACK) (Assembler Language
Only) • • • • • • • • • • • • • • • • • .. • • • • • • • • • • • • • 546
PART 8.
APPENDIXES
APPENDIX A.
EXAMPLE OF A CICS/VS APPLICATION PROGRAM
APPENDIX B.
BMS MAP DEFINITION EXAMPLE
• • • 565
• • • 565
• • • 565
TRANSLATION TABLES FOR THE 2980
BIBLIOGRAPHY • • • • • • • • .. •
Availability of Publications
INDEX
• 549
• • • 561
APPENDIX C.
INTER-RELEASE COMPATIBILITY •
CICS/VS Macro Instructions • .. • • • • • . • • •
CICS/VS Control Block Fields and Area Prefix Fields
APPENDIX D.
....
........
.
..
• 579
• • • 583
• • • 585
587
contents
ix
Figures
D-3.
conventional Batch Processing
• .. •
• • • •
Transaction Processing of CICS/VS
• • • • • • • •
CICS/VS Data Base Concept • • • • • • •
• • • •
CICS/VS Transaction Flow • • • .. • • • •
• • •
•
A Comparison of Batch and Online Environments • • • •
Register Usage under CICS/VS • •
• • • • • • ...
Summary of CICS/VS Storage Areas • • • • • • • • • • •
CICS/VS system Sections • • • •
• • • • • • • • • • ••
Symbolic Names and Base Addresses of CICS/VS Storage Areas.
Chaining of CICS/VS Storage Areas . . . . . . . . . . . . . .
Example of CICS/VS Assembler-Language Application Program
Example of CICS/VS COBOL Application Program • • •
Example of CICS/VS PL/I Application Program
Indirect Accessing ~wo-Level Index) • • • • • • •
Indirect Accessing (Three-Level Index) • • • ..
Indirect Accessing (Search Argument Field) •
Indirect Accessing (Duplicates Data Set)
• • • •
Indirect Accessing (Message to Terminal) •
Record Identification Field (Block Reference)
...
Record Identification Field (Physical Key) • •
Record Identification Field (Deblocking Argument) • • • • •
Record Identification Field (Adding More than One Record)
Record Identification Field (Adding Single Record)
File Control Response Codes (2 Parts) . . . . . .
•
CICS/VS-DLjI Interface Response Codes (2 Parts)
• • •
Terminal-Oriented Task Identification • • .. • •
•
Use of Trailer Maps in PAGEBLD Mapping Operations
•
Overflow Processing by Application Programs under BMS
•
BMS Status Flags • • •
• • • •
BMS Response Codes • • • • • • .. • • • • • • • • • • • • • •
BMS Terminal Code Table • • • • • • • • • • • • • • • "• • •
3270 Field Attributes and Printer Control Characters • • • •
3270 Attention Identifiers and Functions •
•
Batch Data Interchange Response Codes • • • •
• •
Interval Control Response Codes • • • •
• • •
Task Synchronization under CICS/VS .. • •
• •
Logical Relationship of Application Programs •
• •
ABEND Exit Processing • • • • • • • • •
• • • •
•
Program Control Response Codes. .. • • •
• ••••••
Transient Data Control Response Codes
• • • • •
•
Temporary storage Control Response Codes •
• •
Table Search Response Codes •• .. •
• • • •
Phonetic Conversion Response Codes • .. • • • •
• • •
Field verify Response Codes
• •
Bit Test Response Codes • • • _
• •
Input Formatting Response Codes
• • ••
Selection of Records by Weighted Retrieval • •
Weighted Retrieval Response Codes
Journal Control Response Codes • • •
• • • •
•
2980-1 Character SetjTranslate Table
•
2980-2 Character SetjTranslate Table
2980-4 Character Set/Translate Table
••••
x
CICS/VS APRM (!tL)
1.1-1.
1.1-2 ..
1 Ii 1-3.
1.1-4.
1.3-1.
1.3-2.
2. 1-1~
2.1-2.
2.1-3.
2 .1-LL~
2 ~ 2-1.
2.3-1.
2 ~ 4-1.
3.2-1.
3.2-2.
3.2-3.
3.2-4.
3.2-5.
3.2-6.
3.2-7.
3.2-8.
3.2-9.
3.2-10.
3.2-11.
3.3-1.
4 ~ 2-1.
4.3-1.
4.3-2.
4.3-3.
4.3-4.
" .. 3-5.
4.3-6.
4.3-7.
4.4-1.
5.2-1.
5.3-1.
5.4-1.
5.4-2.
5.4-3.
5.6-1.
5.7-1.
6.3-1.
6.3-2.
6.3-3.
6.3-4.
6.3-5.
6.3-6.
6.3-7.
7.5-1.
D-1.
D-2.
y
•
•
•
•
•
•
•
•
•
•
"
4
5
8
15
20
29
30
32
34
44
57
66
77
79
80
80
81
82
83
84
86
86
122
143
178
288
289
298
301
303
304
305
335
361
371
390
400
404
429
445
458
460
460
469
475
478
483
540
580
581
582
Summary of Amendments for Version 1 Release 5
This edition (SC33-0079-2) provides information about the new or
enhanced features introduced by CICS/VS Version 1 Release 5, as follows:
•
Extensions to the intercommunication facilities, offering:
Multiregion operation (MRO) -- a new mechanism that allows
communication between multiple connected CICS/VS regions within
the same processing system without the use of SNA networking
facilities.
Distributed transaction processing (DTP) -- direct transationto-transaction communication across systems.
(This facility is
not available on MRO.)
Intersystem Communication between CICS/VS and IMS/VS.
Improved throughput by support of SNA parallel sessions.
•
Enhanced mastar terminal facilities for interactive control of
CICS/VS.
•
Command-level interface enhancements: an intaractive command
interpreter, and a new command-level interface with DL/I.
•
Security enhancements, including support for an external security
manager (for example, the Resource Access Control Facility (RACF)
program product).
•
Improved monitoring facilities.
•
Further device support, including:
additional 3270 support.
use of the OS/VS console as a CICSjVS terminal.
networking of TWX and iTTY terminals through the Network
Terminal Option (NTO) program product.
•
Usability and serviceability aids, including a new user exit
mechanism and facilities in CICSjDOS/VS similar to those provided
by the FERS service aid.
Some of the above features are not described in this manual because
they do not directly affect the macro-level application programmer; for
information on these, refer to the other CICS/VS manuals listed in the
bibliography_
Summary of Amendments
xi
Summary of Amendments for Version 1 Release 4.1.
This technical newsletter (SN33-62Q3) provides information about the new
features introduced by CICS/VS Version 1 Release 4.1, as follows:
Chapter 3.2: Reference to fixed block architecture (FBA).
Chapter 4.2: Information about terminal control support for LUTYPE4
terminals.
Chapter 4.3: Information about basic mapping support
terminals.
(B~S)
for LUTYPE4
Chapter 4.4: Information about batch data interchange support for
LUTYPE4 terminals. Information about DFHDI TYPE=SEND
macro instruction for transmitting data to batch data
interchange terminals.
Appendix C:
Changes to clarify IBM's commitment about control block
fields.
In addition to the changes described above, minor editorial
improvements and corrections have been made throughout the publication.
Summary of Amendments for Version 1 Release 4
This edition (SC33-0019-1) provides information about the new features
introduced by CICS/VS Version 1 Release 4, as follows:
Chapter 4.2, Terminal Control: new syntax displays have been added
for the IBM 3210 full function logical unit and the IBM 3210 logical
unit types LUTYPE2, LUTYPE3 and SCSPRT.
Chapter 4.3, Basic Mapping Support: references have been added to
various new devices in the IBM 3210 range; there have been some changes
and additions to operands of the map definition macro instructions
(DFHMSD, DFHMDI, and DFHMDF). In addition, a significant amount of
editorial work has been carried out to improve the usability of the
chapter. There has been some rearrangement of the information; in
particular, the descriptions of all operands of DFHBMS macro
instructions have been grouped together, arranged alphabetically, and
placed at the end of the Chapter.
Chapter 1.6, Recovery/Restart: additions have been made to reflect
the new transaction restart facilities offered by CICS/VS. A new macro
type, DFHSP TYPE=ROLLBACK, is described.
Appendix B, BMS Map Definition Example: this is an entirely new
appendix containing examples of BMS map definition macro instructions.
(The material previously contained in Appendix B, "Trace Tables," has
been moved into the CICSLVS Problem Determination Guide.)
Appendix C, Inter-Release Compatibility: this appendix has been
updated. It defines any incompatibilities that exist between the
application programming interface for CICS/VS Version 1.4 and previous
versions of CICS/VS as well as listing control fields introduced at
Version 1.4 that are guaranteed to be unchanged for future releases of
CICS/VS.
In addition to the changes described above, minor editorial
improvements and corrections have been made throughout the publication.
xii
CICS/VS APRM (!L)
Part 1. Introduction
Chapter 1.1. Macro-Level Application Programming
The IBM customer Information Control system/Virtual storage (CICS;VS) is
a transaction-oriented data base/data communication (DBjDC) system. It
can be applied to most online IBM system/370 systems, since it offers
terminal facilities for many applications: message switching, inquiry,
data collection, order entry, and conversational and batched data entry.
CICS/VS works with either the Disk Operating System/Virtual Storage
Extended (DOS/VSE) or the Operating system/Virtual Storage (OS/VS1 or
OS/VS2). It can be thought of as an extension of the operating system
or as an interface between the operating system and the user's
application programs. The system is modular: at system generation or
initialization, an installation can select the components it needs to
tailor a CICS/VS system for a given application.
In conventional batch processing (see Figure 1.1-1), similar
transactions are grouped for processing, and the application programmer
plans a series of runs to edit input transactions, update data sets, or
write output reports. Because the programmer concentrates on
manipulating data for most efficient handling of each transaction type,
the data in batch processing becomes closely tied to the program logic
and has little value for other applications.
A real-time DB/DC system differs from batch processing primarily in
the number and types of activities taking place in the system at the
same time. A batch-processing system schedules each application
independently and provides data base support unique to each application.
A DB/DC system controls many random nonscheduled transactions for many
applications and provides one integrated data base supporting all the
applications on the system (see Figure 1.1-2).
The CICS/VS program product (either CICS/OS/VS or CICS/DOS/VS)
performs many functions essential to success in real-time DB/DC systems.
Its major functions can be summarized as follows:
•
Provision of rapid response to simultaneously active online
terminals
•
Control of a telecommunication network of mixed devices
•
Management of a wide mixture of transactions being serviced by a
variety of application programs at the same time
•
Control of access to a data base
•
Management of system resources, such as main storage, to keep the
system in continuous operation
•
Assignment of priorities to optimize use of the processor.
with these functions assumed by CICS/VS, application programmers can
concentrate on their particular applications. Programming takes less
time, debugging is easier, and implementation time and costs are reduced
accordingly.
A key consideration in selecting a DB/DC system is its adaptability
to present and future needs. CICS/VS is a family of systems that
provides a DB/DC interface to IBM System/370 at most levels of the
product line, offering a clear path for growth or migration of an
installation.
Chapter 1.1.
Macro-Level Application Programming
3
Card Reader
One
Input
Application
Printer
Output
Figure 1 .. 1-1.
Conventional Batch Processing
Several
Data
Base
Applications
Figure 1.1-2.
Transaction Processing of CICS/VS
Figure 1.1-3 shows how the CICSjVS data base supports the information
needs of multiple applications, independently and concurrently.
CICS/VS APRl'1(ML)
User
File Inquiry
File Change
Report Request
Program A
Program B
Program C
Device
CICS!VS
Application
Programs
CICS!VS
r -
--,-
-
-
-
-
-
-
-
-
I
(
Data Base
..... "I
Data
Set
I
I
I
I
I
........
-
-
-
-
-
-
I
I
I
I
I
l
- -----
)
'"'
I
I
I
Data
Set
B
------'
--,-
-..,
I
I
I
I
I
Figure 1.1-3.
(
I
I
I
A
l
--,--
-
I
I
I
-, - -
)
('
I
I
I
I
I
I
I
I
I
I
I
.,..,.
......
Data
Set
C
"1
I
I
I
I
I
I
l ...... ---. __ ..,J
CICS/VS Data Base Concept
Chapter 1.1.
Macro-Level Application Programming
5
Although application programmers need not be concerned with details
of CICS/VS structure or performance, they should have a general
understanding of how CICS/VS components interact to perform essential
processing steps. CICS/VS consists of six major components, explained
in greater detail in the publication CICStVS Diagnostic Reference. They
are:
•
•
•
•
•
System management
•
Application services
System services
System monitoring
System reliability
System support
Each of these £2mponents is divided into functions which provide
services to CICS/VS users. The components that most directly affect the
application programmer are system management, system monitoring, and
system reliability. To help the application programmer understand some
of the ways in which CICS/VS assists him, the system management
functions are summarized below.
•
Terminal management - provides for communication between terminals
and user-written application programs through the terminal control
program. This function supports automatic task initiation to
process new transactions. The testing of application programs is
accommodated by the simulation of terminals by sequential devices
such as card readers, line printers, tape units, or disk storage
units.
•
File management - provides for the addition, update, direct
retrieval, and selective retrieval (browsing) of data on BDAM,
ISAM, and VSAM data base data sets. Additional capabilities
provided only for VSAM data sets include record deletion, skipsequential processing, key-ordered mass insertion, relative byte
addressing, search key high/equal, generic key, and locate mode
processing for read-only requests. Optional access to the DL/I
facility of the IBM Information Management System/Virtual Storage
(IMS/VS) is provided under CICS/OS/VS. Such use of DL/I requires
installation of the IB~ program product IMS/VS Data Base System.
Note: Users of CICS/DOS/VS can interface with the IBM program
product DOS/VS DL/I through DOS/VS DL/I CALLs, but CICS/VS file
control macro instructions cannot be used.
6
•
Transient data management - provides for optional queuing of data
in transit between user-defined destinations. This function
facilitates message switching and data collection.
•
Temporary storage management - provides an optional general-purpose
"scratch pad" function intended for video display paging,
broadcasting, data collection suspension, conservation of main
storage, retention of control information, and similar. Where
multiple records are used and random access to those records is
required', this function also provides a queuing facility.
•
Storage management - provides control of main storage allocated to
CICS/VS. Storage acquisition, disposition, initialization, and
request queuing are among the services performed by this function.
CICS/VS APRM(ML)
•
Program management - provides a multiprogramming capability through
dynamic program management while offering a real-time program fetch
capability.
•
Time management - provides control of various task functions (for
example, runaway task control, task synchronization, and system
stall detection) based on specified intervals of time or the time
of day.
•
Task management - provides dynamic multitasking necessary for
effective, concurrent transaction processing, such as priority
scheduling, transaction synchronization~ and control of serially
reusable resources. This function controls activities within the
CICS/VS partition or region and is in addition to the multitasking
or multiprocessing capabilities of the host operating system.
•
Journal management - provides for the creation and management of
special-purpose sequential data sets, called journals, during realtime execution of CICS/VS. Journals are intended for recording (in
chronological order) data that the user may need in subsequent
reconstruction of data or events. Examples of such data sets are
an audit trail, a change-file of data base updates and additions,
and a record of system transaction activity (often called a log) •
•
Sync point management - works in conjunction with other CICS/VS
functions such as transient data management and file management, to
provide for an emergency restart of CICS/VS after abnormal
termination. The CICS/VS transaction backout program (DFHTBP) or a
user-written application program can make changes to data base data
sets or transient data intrapartition queues for tasks "in-flight"
at time of failure based on information recorded on a system log
during online execution of CICS/VS.
CICS/VS also provides dump management and trace management, which are
used in program debugging. CICS/VS basic mapping support (BMS)
facilitates information display on a wide variety of terminals and
provides device independence, terminal paging, and message routing. A
number of built-in functions are available for use by application
programs. CICS/VS also provides system service programming to identify
terminal operators, to give control of the entire system to a master
terminal, to display real-time system statistics, to intercept abnormal
conditions not handled directly by the operating system, and to end
operation by collecting statistics, closing data sets, and returning
control to the operating system.
To provide rapid response to terminal users, CICS/VS executes in a
multitasking mode of operation within its own partition or region. Such
multitasking within a partition or region is analogous to
multiprogramming within the total operating-system environment.
Generally, tasks are initiated as a result of transactions entered at
terminals. Whenever a task is forced to wait for completion of an I/O
operation; availability of a resource, or some other cause, processing
of another task within the system is initiated or continued.
The processing of a typical transaction is shown in Figure 1.1-4.
Some general characteristics of application programs to be run under
CICS/VS and the use of other functions that it provides are explained in
subsequent parts of this manual.
Chapter 1.1.
Macro-Level Application Programming
7
I
I
I
I
(
(
I
\~--~~\
I
I
I
PROGRAM
LIBRARY
\
TERMINAL
CONTROL
DATA
BASE
\
\
TASK
CONTROL
PROGRAM
CONTROL
I
MESSAGE
LOG
(
\~--~~\
~ ~.
USER
PROGRAM
STORAGE
CONTROL
FILE
CONTROL
JOURNAL
CONTROL
TRANSLATE MSG
+
INITIATE TASK
---i~VALIDATE
TRANSACTION
t
REQUEST
WORKSTORAGE
----------~----------~GETSTORAGE
SCHEDNEWTASK~----------~----------~----~
t
DISPAT1H TASK
SELECT PGM
+
LOAD PGM
WAIT4-------t----~1
BUILD DATA
~------~----------~SETSEARCH
KEY
I
'-----t-------I~
REQUEST
INPUT AREA
I
READ FILE
RECORD
l
WAIT ...
"""-I------t-----------t--------_+--------+-----l
I
REQUEST
TERMTAL AREA
GET
STORAGE
I
BUILD TERMINAL
OUTPUT 4It---t--_....J
t
BUILD ACTIVITY
RECORD
PUT ACTIVITY
I'----~------_+-----~RECORDTO
WAIT4---~-------~~-------~------+--------~-L-O-G~1
r --
-
-
-
-REQUEST ..."""-~-+_------~------_+--~I
TERMINAL WRITE
-
t
I
RErURN
TERMINATE .-t-_....J
TRANSACTION
I
I
STORAGE
I
TERMINATE
TASK 4 - - - - r - - - - - - - + - - - - - - 4 - - - J
I
I
T
SCHEDULE
WRITE
Figure 1.1-4.
8
FREE
'----I-------i~TRANSACTION
I
CICS/VS Transaction Flow
CICS/VS APR! (ML)
Chapter 1.2. Macro Format and Syntax Notation
Application programs to be executed under CICS/VS can be written at the
macro level in assembler language, COBOL, or PL/I. Regardless of the
language used, it is strongly recommended that CICS/VS is allowed to
perform all supervisory and data management services for applications.
Such services can be invoked by using CICS/VS macro instructions.
CICS/VS macro instructions can also be used to request dump and trace
facilities when testing or debugging an application program. Although
an application program is not precluded from direct communication with
the operating system, the results of such action are unpredictable and
performance may be affected. Such action also has a limiting effect on
migration from CICS/DOS/VS to CICS/OS/VS, a growth path that may become
highly advisable for the CICS/DOS/VS user.
CICS/VS macro instructions are written in a format similar to
assembler-language macro instructions:
Name
Operation
blank I DFHxxxxx
or I
symboll
Operands
Comments
One or more operands
separated by commas
Comments for
program documentation
The name field must not contain a label if the macro instruction is
used in a COSOL or PL/I program; however, if a label is desired for the
macro instruction, it may be placed on the line preceding the macro
instruction. For COBOL programs, the first six positions may contain a
sequence number.
The operation field must begin before column 16 and must contain the
three-character combination "DFH" in the first three positions of the
operation field. Up to five additional characters can be appended to
DFH to complete this symbolic name for the appropriate program or table.
Since DFH is reserved for CICS/VS macro instructions, no other line may
begin with this three-character combination.
The operands field is used to specify
performed.
th~
services and options to be
The following general rules apply to the macros described in this
manual:
1.
Operands that are written in uppercase letters (for example,
TYPE=INITIAL) are to be coded exactly as shown.
2.
Operands that are written as a combination of uppercase and
lowercase letters separated by an equal sign are to be coded with
the keyword on the left as it appears and an appropriate
substitution for the general class of elements on the right. For
example, if the format description contains NORESP=symbolic
address, the user may code NORESP=NORMROUT.
Chapter 1.2.
Macro Format and Syntax Notation
9
3~
Commas and parentheses are coded as shown. However, the
parentheses are required only when more than one operand is
specified. For example, the following coding is correct:
TYPE=READ
TY PE= (RE AD, WA IT)
The commas are used as separators, but no comma should precede the
first operand entry or follow the last one inside parentheses.
Similarly, no comma should follow the last operand coded for a
particular macro instruction.
4.
Since a blank character indicates the end of the operand field, the
operand field must not contain blanks except after a comma on a
line to be continued or after the last operand of the macro
instruction. The first operand on a continuation line must begin
in column 16.
5.
When a CICS/VS macro instruction is coded on more than one line,
each line containing part of the macro instruction (except the last
one) must contain a nonblank character (for example, an asterisk)
in column 72 indicating that the macro instruction has been
continued on the next line.
6.
If a macro that has positional operands is coded with an invalid
operand, the operand will be ignored. An error message will not be
issued.
7.
If a keyword is spelt incorrectly, the operand
invalid positional operand as in point 6.
8.
The rules for writing CICS/VS macro instruction operands are the
same as those for assembler-language macros.
~y
be treated as an
SYNTAX NOTATION
Throughout this manual, wherever a CICS/VS macro instruction is
presented, the sym boIs ( }, I, [ ], and • ~ • are used in de fining the
instruction format. These symbols are not part of the macro instruction
and are not coded by the programmer~ Their purpose is to indicate how
the macro instruction may be written, and they should be interpreted as
follows:
1.
Braces ( } are used to delimit parameters from which choices are
made. For example,
SEGSET={symbolic addresslYESIALL}
which indicates that the coding SEGSET= must be followed by a
programmer-selected symbolic address, the keyword YES, or the
keyword ALL.
2.
The vertical stroke I indicates that a choice is to be made.
the same as the use of the word "or." For example,
It is
[,INTRVAL=(numeric value I YES} ]
means that either "numeric value" or "YES", but not both, can be
specified in the macro instruction.
10
CICS/V S APRM (11L)
3.
Square brackets [ ] denote options. Anything enclosed in square
brackets mayor may not be coded, depending on whether or not the
associated option is desired. For example,
!ODE=[ {11~1 LOCATE} ]
If a default value is assumed by CICS/VS in the case of an omitted
operand, that default value is indicated by underscoring.
4.
An ellipsis ••• (three dots) denotes that the immediately preceding
unit may appear one or more times in succession in the macro
instruction.
Chapter 1.2.
!acro Format and Syntax Notation
11
Chapter 1.3. Programming Techniques and Restrictions
Application programs to be run under CICS/VS may be coded at the macro
level in assembler language, COBOL, or PL/I. Writing a program to be
run under CICSjVS is not significantly different from writing a program
to be run on any of numerous computing systems. However, the CICS/VS
user should be aware that CICS/VS is an online system and that programs
running under CICS/VS operate in an online environment. Some of the
basic differences between online systems and the traditional batchprocessing environment are summarized in Figure 1.3-1.
Single threading is the execution of a program to process inputs to
completion, sequentially. Processing of one input is completed before
another input is acted upon.
In contrast, multithreading is the capability of using various
sections of a single program concurrently. Under CICS/VS, for example,
the first section of an application program may be executing to process
one transaction. When that section is completed (in general, signaled
by the execution of a CICS/VS macro instruction that causes a wait),
processing of another transaction using a different section of code in
the same program may ensue.
Just as there is not usually one clearly superior, correct way to
solve a problem, so there is not usually one correct way to write a
program to implement that solution. Nevertheless, there are good and
bad techniques of programming undec CICS/VS. How much time and thought
should be given to programming style when writing a program? The answer
depends largely on the expected usage of the program. will it be used
once a day or once a year? When used, will it run for two minutes or
five hours? The frequency and length of use are important factors to
consider when deciding how much time to spend on programming techniques
(that is, to devising the optimum solution to a problem).
Some of the basic characteristics of application programs to be run
under CICS/VS are summarized below.
These characteristics should be
viewed as essential to successful operation under CICSjVS (although some
are not mandatory, they are highly advisable).
1.
Programs must be quasi--i:"een terable
later in this chapter) •
2.
CICS/VS macro instructions (rather than programming-language
statements such as READ, GET, PUT, or WRITE) are included to
control the functions required in application programs.
(See
Chapter 1.2. "Macro Format and syntax Notation lt . )
3.
Input/output areas, temporary storage areas, and work areas are not
included in an application program.
Allor portions of these areas
are defined outside of application programs. The application
programmer must work with CICS/VS system programmers in defining
these areas by means of tables within CICSjVS.
(See "storage
Definition", later in this chapter and Part 2.)
4.
Files are not defined within application programs. As in item 3,
the application programmer works with CICS/VS system programmers in
esta blishing these def ini tions.l
(See the CICS/VS system
Programmer's Reference Manual and applicable operating-system
publications. )
Chapter 1.3.
(see tlQuasi-Reenterabili ty",
Programming Techniques and Restrictions
13
5.
The application programmer must establish addressability in his
program to eIeS/Vs storage areas accessed by his program.
6.
Working storage should not be tied up, for example, awaiting a
reply from a terminal user.
7.
Programs should be as efficient as possible, to work with eIeS/VS
in providing rapid response to terminals.
8.
Any feature, option, or statement that will transfer control to
the operating system should not be used in a eIes/Vs program.
14
eIes/vs
APR~(ML)
Batch Processing
Online Application
Input
Generally sequential
from cards, tape, or a
direct access storage
device ~ASD); submitted
as groups of related
data, edited, and
verif ied
Random, multiple,
concurrent but unrelated entries from
terminals; immediate
edit and verification
of each entry
Processing
sequential, generally
single-thread, with
updating of sequential
master files
Random, multithreading, as one aspect of
multitasking within a
partition or region;
for inquiry or updating purposes or both
Output
Generally in the form of
updated master files and
printed reports
Messages to terminals,
updated files, and
system log of
activities
Sequence of
operations
start program
Read transaction
Read master
Process
System is initialized,
then transactions are
processed as they
occur, with data
rather than program as
driver
End of job
signaled by last
transaction
Generally, end of
shift or day
Amount of
activity
Predictable, known
before run
Not predictable, can
fluctuate widely
Master files/
data sets
Applications
master files
DASD; placed
required for
Files accessible to
multiple, authorized
applications; must be
online; are on DASD
Response
time
Varies widely; usually
involves manual
procedures
Figure 1.3-1.
"own"
on tape or
online when
run
Measured in seconds;
generally occurs as
message to terminal
A Comparison of Batch and Online Environments
The general structure of a CICS/VS application program can be
summarized as follows:
•
Storage definition statements
•
Program initialization statements
•
Processing statements
Chapter 1.3.
Programming Techniques and Restrictions
15
•
Termination statements
No attempt is made in this text to teach the use of typical
programming-language statements or general programming techniques within
assembler language, COBOL, or PL/I. Documentation for these languages
should be consulted for such information ~ee the Bibliography at the
end of this manual).
CICS/VS operates in a virtual storage environment. The key objective
of programming in this type of environment is the reduction of page
faults--those cases in which a program refers to an instruction or data
that does not reside in real storage. When this occurs, the page in
virtual storage that contains the referenced instruction or data must be
transferred waged) into real storage. The more paging required, the
lower the overall system performance.
The application programmer who writes programs to be run in a virtual
storage environment should understand the following concepts:
•
locality of reference - the consistent reference, during the
execution of the application program, to instructions and data
within a relatively small number of pages (compared to the total
number of pages in a program) for relatively long periods
•
validity of reference - the consistent reference to valid data.
This ensures that few storage references retrieve useless data
•
working set - the number and combination of pages of a program
needed for satisfactory performance (low paging rate) during a
given period
In general, the application program should use techniques to improve
the locality and validity of reference and to minimize the size of the
working set at any time during execution of the program, as follows:
1.
2.
16
To achieve locality of reference, processing should be sequential
for both code and data, as far as possible.
a.
Initialize data as close as possible to its first use.
b.
Define new data items as close as possible to the items that
use them.
c.
Define arrays or other data structures in the order in which
they will be referred to; refer to elements within structures
in the order in which they are stored, for example, rowwise
rather than columnwise when using PL/I.
d.
separate error-handling or unusual-situation routines from the
main section of a program; they should be subprograms.
e.
Subprograms that are short and used only once or twice (other
than those in d above) should be coded inline in the calling
program.
To achieve validity of reference.
a.
Avoid long searches for data.
b.
Use data structures that can be addressed directly, such as
arrays, rather than structures that must be searched, such as
chains.
c.
Avoid indirect addressing and any methods that simulate
indirect addressing.
CICS/VS APRM(ML)
3.
To reduce the size of the working set, the amount of storage that a
program refers to in a given period should be as low as possible.
a.
write modular programs and then structure the modules according
to frequency and anticipated time of reference.
b.
Use separate subprograms whenever the flow of your program
suggests that execution will not be s9quential.
When all page frames in a real storage environment are filled and
another page must be loaded into storage, a page replacement operation
is required. The operating system replaces first those pages that have
not been referred to for the longest period of time. If a page to be
replaced has been modified, that page must be paged out onto virtual
storage before the required page can be read in. The more page-out
operations required, the lower the overall performance of the system.
To avoid the necessity for page-out operations, the application
program should be coded so that page-out operations are not required
when a page containing a portion of the program must be replaced in real
storage. The program need only avoid modifying instructions or data
within itself. A program in which neither instructions nor data are
modified is said to be reenterable. As noted earlier, programs to be
run in a CICS/VS environment must be quasi-reenterable. For performance
reasons, it may be wise to make them truly reenterable programs.
The application program should not attempt to use overlays, that is,
to incorporate paging techniques. System paging is automatic and
generally more efficient.
Application Program Packaging
The design of an application program for a virtual environment is
similar to the design of an application program in a real environment.
The system should have all modules resident so that code on unreferenced pages need not be paged in. If the program is dynamic, the
entire program must be loaded across adjacent pages before execution
begins. Dynamic programs can be purged from storage if not in use and
an unsatisfied storage request exists. Allowing sufficient dynamic area
to prevent purging is less efficient than making the programs resident
since a dynamic program will not share unused space on a page with
another program.
The reference pattern of the application should touch the fewest
concurrent pages during its execution.
1.
The main line execution should be as straight a line as possible.
The ideal program executes sequentially with no branch logic
referencing beyond a small range of address space.
2.
Literals and subroutines should be coded as close to their use as
possible. This would include LTORG statements at appropriate
locations in the program. Place constants that are used only once
near to the place where they are used. Executed instructions
should be near the EX instruction. Perform and GO TO routines
should be placed near the caller.
3.
Avoid use of COBOL EXAMINE or VARIABLE MOVE operations since these
expand into subroutine executions.
4.
Do not alter anything within the program module.
module is reenterable and is not paged out.
Chapter 1.3.
An unchanged
Programming Techniques and Restrictions
11
5.
Use the TWA for changeable data during execution, that is counters,
switches, parameter passing, basic mapping support output area (use
Bl'IS SAVE).
6.
Do few or no user GETMAINS to minimize the task's reference
pattern.
7.
Avoid LINKs since it will cause a GETMAIN for a RSA and will search
the PPT.
8.
Try to keep the execution path straight line by using XCTL.
9.
If specifying data for a CICS/VS service request by explicitly
assigning a value to a CICS/VS field (for example, in the task
control area), assign the value immediately prior to issuing the
service request, with no other service requests intervening. Also,
reassign the value immediately before issuing any subsequent
request that needs it.
Quasi-reenterability
Application programs must be coded so that they are "serially reusable"
between entry and exit points of the program. A serially reusable
portion of an application program is executed by only one transaction at
a time, and must initialize and/or restore any instructions or data that
it alters within itself during execution.
(It is recommended, however,
that all applications be truly reenterable to minimize paging.) Entry
and exit points coincide with the use of CICS/VS macro instructions,
since an application program loses control only upon execution of a
CICS/VS macro instruction.
This required quality of application programs written to run under
CICS/VS is called "quasi-reenterability," since the programs need not
meet System/370 specifications for true reenterability. Quasireenterability allows a single copy of a user-written application
program to be used to process several transactions concurrently, thereby
reducing the number of copies of a program that must be in main storage.
Intermediate exits may be taken during execution of an application
program. Such exits constitute a transfer of control from the program.
All switches, data, and intermediate results needed upon subsequent
return to the program must be retained in a unique storage area such as
the transaction work area (TWA). The application programmer must
provide that unique intermediate storage area by symbolically defining
it in his program ~s described in Part 2).
A serially reusable application program that has no intermediate
exits also has the quality of quasi-reenterability.
Storage Definition
The macro library supplied with CICS/VS contains symbolic storage
definitions of CICS/VS control areas, work areas, and I/O areas. It is
strongly recommended that the application programmer use these
definitions rather than develop actual or direct displacements in his
program. This protects the application program in the event of any
relocation of CICS/VS.
18
CICS/VS APRM (11L)
The assembler-language programmer includes symbolic storage
definitions in his program by means of assembler-language COpy
statements.
For the PLjI programmer, the macro library contains
numerous BASED structures, in the form of dummy control sections
~SECTS), that describe CICS/VS control areas.
These DSECTs are
available to the user through the use of %INCLUDE statements. The COBOL
programmer uses similar definitions through COpy statements in the
Linkage section of the Data Division of his application program.
These
definitions are discussed in Part 2.
Program Initialization
In the initialization section of the application program, the assemnlerlanguage programmer must establish a symbolic base address for his
program, because this is not done by CICS/VS prior to entry.
In doing
so, he identifies a base register.
Register 12 is reserved by CICS/VS
for the address of the task control area (TCA) for this task.
Register
13 is reserved for the address of the common system area (CSA). Both
these registers are initialized by CICS/VS prior to entry and their
contents must be preserved throughout execution of the program. For
COBOL and PL/I, this preservation of registers is done automatically by
CICS/VS.
Registers 15 through 11 are available to the user and their contents
are preserved when a CICS/VS macro instruction is executed; the contents
of register 14 are destroyed whenever a CICS/VS macro instruction is
executed.
The contents of register 1 are destroyed if parameters are
specified on a DL/I call.
The different types of the DFHPC macro instruction that can be issued
to transfer control from or to an application program are listed in the
left-hand column of Figure 1.3-2. The status of all registers upon
program entry or upon return to a program is as shown in the remaining
columns.
Although register 14 contains the program entry address, it is not
advisable to use register 14 as the base register since it is used by
CICS/VS to service requests for CICS/VS supervisory and data management
services.
Chapter 1.3.
Programming Techniques and Restrictions
19
,I
At program entry
because of:
Initial
Program Entry
1
Registers
15, and 0-11
12
13
Unknown
TCA
CSA
User-program
address
14
LINK
Registers of
program issuing
the LINK
TCA
CSA
User-program
address
XCTL
Reg isters of
program issuing
the XCTL
TCA
CSA
User-program
address
LOAD
Unchanged
TCA
CSA
Next seq uential
instruction
RETURN (issued
by a linked-to
program)
Unchanged (from
point-of-view of
program issuing
the LINK)
TCA
CSA
Next sequentiall
inst ruct ion
I
I
I
Following
execution of:
I
Figure 1.3-2.
Register Usage under CICS/VS
Restrictions
There are language and other restrictions that the application
programmer should be aware of when writing programs to be run under
CICS/VS.
ASSEMBLER
If CICS/VS macro instructions are included in an assembler-language
application program, the assembler instruction COM (define blank common
control section) must not be used.
COBOL
The use of CICS/VS macro instructions in a COBOL application program
pr~cludes the use of the following COBOL features:
1.
Environment and Data Division entries normally associated with data
management services.
2.
File Section of the Data Division.
20
CICS/VS APRM(ML)
3.
Special features:
ACCEPT,DISPLAY,EXHIBIT,REPORT WRITER,
SEGMENTATION,SORT,TRACE, and UNSTRING.
Any feature that requires an operating system GETMAIN.
4.
DOS compiler options:
OS compiler options:
TEST.
COUNT,FLOW,STATE,STXIT, or SYMDMP.
COUNT,ENDJOB,FLOW,DYNAM,STATE,SYMDMP,SYST, or
Any option that requires operating system services.
5.
COBOL statements:
READ, WRITE, OPEN, CLOSE.
6.
QUOTE option, which signifies that literals are to be delineated by
quotation marks (for example, "74 11 ) . Because CICS/VS macro
instructions generate COBOL code using apostrophes to delineate
literals (for example, 1741), the APOST option must be in effect.
7.
The OPTIMIZE option of DOS Full COBOL Version 3 (5736-CB2.)
SERVICE RELOAD statements must be coded in programs compiled under
the following compilers when the OPTIMIZE option is active:
•
as
•
OSjVS COBOL Release 1 (5740-CB1)
•
DOS/VS COBOL (5746-CB 1)
Full COBOL Version 4 (5734-CB2)
If the NOOPTIMIZE option is used, SERVICE RELOAD can, but need not,
be used.. Further details of SERVICE RELOAD appear in "Additional
Guidelines ll in Chapter 2.3.
CICS/VS macro instructions should not be coded within a COBOL
statement, since each COBOL statement generated by a CICS/VS macro
instruction is terminated by a period.
CICS/VS macro instructions generate COBOL statements which use an
apostrophe (I) to delineate literals. Code written by the application
programmer cannot utilize quotes (n) to delineate literals.
Duplicate names may not be used. This requirement is a result of
preprocessing by the translator before COBOL statements are generated.
Any COBOL program that is to run under CICS/VS must contain at least
one CICS/VS macro instruction (for example, DFHPC TYPE=RETURN) for
proper operation.
Users of the OS/VS COBOL Release 2 compiler must specify LANGLVL(l),
and must not use the INSPECT or USE FOR DEBUGGING statements.
The macro level interface will not support a COBOL program with a TGT
larger than4K. If a program generates a TGT greater than 4K the
command level interface must be used.
Chapter 1.3.
Programming Techniques and Restrictions
21
PL/I
The following restrictions apply to programs compiled by the PL/I F
Compiler for CICS/OS/VS. However, if the PL/I Optimizing Compiler is
used with the PLjI support supplied by CICS/VS, not all the restrictions
apply. Refer to the PL/I Optimizing compiler Programmer's Guide for
more information on the applicable restrictions.
The use of CICS/VS macro instructions in a PL/I application program
precludes the use of the following PL/I features:
1.
The multitasking built-in functions:
COMPLETION, STATUS, PRIORITY.
2.
The multitasking options:
3.
The PL/I statements: READ, WRITE, GET, PUT, OPEN, CLOSE, DISPLAY,
DELAY, REWRITE, LOCATE, DELETE, UNLOCK, STOP, HALT, EXIT, and, for
the PL/I Optimizing Compiler, FETCH and RELEASE.
4.
PL/I Sort/merge.
S.
PL/I error handling.
6.
A declaration for a nonstring element variable with the attributes
STATIC EXTERNAL but without the INITIAL attribute.
(This
declaration will generate a common CSECT that cannot be handled by
CICS/VS).
PRIORITY, TASK, EVENT.
The use of CICS/VS macro instructions in a PL/I application program
to be compiled on the PL/I Optimizing Compiler also precludes the use of
the following compiler options:
REPORT, FLOW, GONUMBER, GOSTMT.
An application program written in PL/I must consist of an external
(MAIN) procedure. Internal procedure CALLs are allowed in a PL/I
program to be run under CICS/VS, but external CALLs are not.
Floating-point operations can be used, but CICS/VS does not dump the
contents of floating-point registers, and programmers should be aware
that a floating-point interrupt will cause the task to be abnormally
terminated.
Any CICS/VS macro instruction operand which defines a name or label
of a storage area or routine should comply with the Assembler language
restrictions of eight characters or less. This requirement is a result
of preprocessing by the Assembler before PL/I statements are generated.
LINK-EDITING
Separate COBOL routines cannot be link-edited together. Neither can
separate PL/I routines. Assembler-language routines may be link-edited,
but routines invoked by CALL statements must conform to CICS/VS
application program requirements. Facilities comparable to link-editing
are provided under CICS/VS through DFHPC TYPE=LINK and DFHPC TYPE=XCTL
(transfer control) macro instructions, which can be used to set up
communication between programs. For details of the job control required
to compile and link-edit application programs refer to the CICS/VS
~st§.!!!. Program!!!§!'~.2-Guifl~.
22
CICS/VS APRM{ML)
OBJECT PROGRAM SIZE
The object module resulting from any application program must not occupy
more than 262,136 bytes of storage~
Assembly-time Service (DFHCOVER Macro)
In addition to knowing the execution-time considerations discussed in
this chapter, the application programmer should be aware of an assemb1ytime (or compile-time) service available under CICS/VS: the DFHCOVER
macro instruction. This macro instruction specifies that the assembler
or compiler in use print a cover page on tvo consecutive pages, which
ensures that the application program listing can be torn off with one of
the cover pages face up. Useful information (program name, date, time
of assembly, remarks, and so on) may then be written on the cover page.
The DFHCOVER macro instruction requires no operands and nothing else
should appear on the same coding line.
If the DFHCOVER macro instruction is coded as part of an Assemb1erlanguage application program, it should be coded as the first
instruction in the program. If desired, hovever, this macro instruction
may be coded after anything that is not vital to the listing (such as
the TITLE line).
The first line of a PL/I source program is printed as a header on
each page of the source listing. This means that when the DFHCOVER
macro instruction is part of a PL/I application program, the first line
should be a comment containing information that the application
programmer wants printed as a header. The second line should contain
the DFHCOVER macro instruction. The actual PL/I code should begin with
the third line.
Since column 1 is used by the DFHCOVER macro for line and page
spacing under PL/I, column 1 must be defined as reserved for control
characters and columns 2-72 must be defined as available for data. For
information concerning PL/I compile-time services, see the DOS PL/I
QEtimizinq ComEiler Prog~~~ Guide, the OS P1L!-1l1 programmerts
~uide, and the OS PL/I Optimizing Compiler Programmerts Guide.
The example in Appendix A shows how the DFHCOVER macro instruction is
used.
Testing Responses to Macro Instructions
As a result of issuing CICS/VS macros, certain error conditions may be
raised. A programmer can test for these conditions in any of the
following ways:
•
Code the appropriate operands in the macro being issued.
macro syntax display lists the operands available.
•
Code a DFHXX TYPE=CHECK macro immediately following the particular
macro by which the service is requested.
•
Code instructions, following the macro by which the service was
requested, that test the contents of certain CICS/VS control areas.
The relevant control areas and the meaning of the returning bit
patterns are discussed in each chapter that describes the services.
Chapter 1.3.
Each
Programming Techniques and Restrictions
23
If the programmer does not c},eck the response to a request, program
flow continues with the next sequential instruction.
24
CICS/VS APR!(ML)
Part 2. Storage Definition
25
Chapter 2.1. Introduction to Storage Definition
CICS/VS provides symbolic storage definitions in the form of dummy
sections ~SECTs) that describe the layouts of a number of'storage
areas. These storage definitions are contained in the CICS/VS libraries
and can be copied into application programs where, in combination with
user-defined layouts of the user1s sections of the storage areas, they
provide symbolic addressing (addressability) to the storage areas.
CICS/vS Storage Areas
The storage areas for which symbolic storage definitions are provided
consist of control areas, for example the Common system Area (CSA), work
areas, for example the File Work Area (FWA), and input/output areas, for
example the Terminal Input/Output Area (TIOA). CICS/VS storage areas
are summarized in Figures 2.1-1 and 2.1-2.
Some of these storage areas are acquired by CICS/VS during system
initialization, others are acquired and released during execution of the
system. Some areas are acquired by CICS/VS; some by the application
program; and some by either CICS/VS or the application program.
All CICS/VS storage areas, vith the exception of the journal control
area (JCA) and VSAM work areas (VSWAs), consist of two sections. The
first is the system section, used primarily by CICS/VS; the second is
the user section, defined and used exclusively by the application
program. This division exists whether the storage areas are acquired
during system initialization (for example, the common system area) or
acquired during execution (for example, a terminal input/output area).
All CICS/VS pointers (areas containing addresses) are four bytes in
length.
A storage accounting field comprising eight bytes preceding and eight
bytes following each storage area is built by CICS/VS for every storage
area acquired for the user. If this field is altered or destroyed,
CICS/VS may be abnormally terminated.
The common system area (eSA) and the task control area (TCA) must be
defined in every application program; other areas are defined as needed.
It is the user1s responsibility to define the CSA and TCA as veIl as
other storage areas required by the application program.
Identifiers such as CSA and TCA, used in this manual, are also used
in symbolic names, or labels, within CICS/VS modules and must be used by
the application programmer to refer to the data that they represent.
Names of fields within a storage area generally begin vith the
characters of the label for that area. For example, TCA stands for Task
Control Area, TCAFCAAA is a field in the TCA that points to a Facility
Control Area, TCASCSA is a field in the TCA that points to a Storage
Control Storage Area, and so on.
Chapter 2.1.
Introduction to Storage Definition
27
The letters A through G in Figure 2.1-1 denote the following:
A
Assembler language only.
B
Alternatively, the TCAFCAAA may point to the address of a DCT
entry or to the address of an automatic initiate descriptor
(AID).
C
COBOL equivalent:
01 DFHTCTTE COpy DFHTCTTE.
MOVE TCAFCAAA TO TCTTEAR.
PL/I equivalent:
%INCLUDE DFHTCTTE;
D
EOB = End of Block.
E
TCAFCAA, TCATSDA, and TCATDAA: The same location within the
TCA is used for these three pointers, only one of which is
current at any given time.
F
TCASCSA may also point to an area to be released by a DFHSC
TYPE=FREEMAIN macro instruction.
G
After a DFHPC TYPE=LOAD macro instruction, TCAPCLA points to
the beginning address of the loaded program.
Throughout Figure 2.1-1, the characters LL~~ represent a four-byte
field in which the first two bytes define the length of the area.
28
CICS/VS APRM(ML)
CSA
COpy DFHCSADS
System Section
POinters to CICS/VS Modules and Tables. Save Areas.
CWA Common Work Area· User's Section
Allocated at sysgen,
Default:. 512. MdXlrTlUm " 3584.
Inltlatly binary leros.
Exists for duration of CICS/VS.
Usable by multiple tasks for statistics, to pass data, etc.
Statlsllcs, Constants. Pdrarneters, TII'Tle of Day
CSACDTA(current task)
L
CSACBAR II1EG.131
I CICSIVS'acquired
LCSAWABA
TeA
TCACBA~(REG.
•
Q
121
TCTTE
COpy DFHTCADS
System Section
Proqram Control Information,
Task PriOrity. RSA
POinters, etc.
~L
I
System Section
g~:~~~~:~~~rmatlon
TCTTEDA
COPY DFHTCTTE
L TCTTEAR, TCAFCAAA
User's
SectlQ~
1 per terminal
~:: ::~~:~a~~p'T~TCWA.
+-__-Lr-____________________- '__________- ;
~~Se~cu~,,~,y~K~e~Y'~________
L
TCTTEAR
I CICSIVS·acquired
TCTTECIA
COPY DFHTIDA
L TIOABAR, TCTTEDA
TIOA
TCAFCAAA
User's Section
Terminal Input or output messages.
Sile defined in TeT, and obtained as needed by CICS/VS. Also obtainable
.hrough DFHSC TYPE" GETMAIN, CLASS' TERMINAL (da.a leng.h only!.
LTiOABAR
..L - TIOADBA
FIOA
~+
System Sec.ion
aS: 64 bytes + 16.t ISAM
DOS: 80 bytes
I
I CICS/VS or user·acqulred
COPY DFHF lOA
L FIDABAR, TCAFCAA
User', SPc"on
For h.le records. Size defined in Fer. Aut~maticallY acq~'red by FC?, as
required. All records (f::xcept VSAM) read Into FIOA initially. Only one type
(Inquiry. unblocked) processed here. All others moved to FWA.
I CICSIVS'acQuired
+L - FIOADBA
L - FIOABAR
COPY DFHFWADS
L FWACBAR, TCAFCAA
FWA
System
.fu-ctlon
16 by'es
TCAPCLA
User's Section
For file records. Size defined In FeT, and acquired by FCP, as reqUired, or through
DFHFC TYPE" GETAREA. Records moved here from FIOA or VSAM buffer for
InquirY, Blocked; Updating; Browse; Segmented. Also, new records assembled here.
H
(<)
+L - FWACBAR +L - - FCUWA
ICICS/VS or user-acquired
COPY DFHVSWA
L VSWABAR, TCAFCAA
VSWA
System Sec.ion for VSAM 1/0
96 bytes for baSIC 1/0 and 136 bytes + I<.ey length for browse liD.
Y+
Automatically aCClulred by FCP as required, and passed to user only for locate mode operations.
•L-VSWAREA
L - - VSWABAR
4L-VSWALEN
COpy DFHSAADS
L SAACBAR, TCASCSA
SAA
System
Section
B by.e,
TCASCSA
r
LSAACBAR
8
TCATSDA
User's Section
User's work area.
Area acqulled .hrough DFHSC TYPE
L
~
GETMAIN, CLASS'USER (da.a leng.h only!.
SAASACA
(E)-t-----..
I
I
User-acquired
COpy DFHTSIOA
L TSIOABAR, TCATSDA
TSIOA
)I..
\CICSIVS-acqulled
S,/stem
SectIon
12 by'e,
User's Section
Temporary storage 1/0 area.
Automatically acqUired by TSP on OFHTS TYPE = GET, or by user through
DFHSC TYPE· GETMAIN, CLASS ~ TEMPSTRG (da.a + 4 by'es for LLbb!.
'---'--t---in-cIW'fL Lbb
LTSIOABAR
L
TSIOADBA
COpy DFHTDOA
L TDOABAR, TCATDAA
TOOA
TCA TDAA
( E)
-+---.,.---"
•
User's Section
Intrapartltlon output only. V/L records only. User-specified area_ May be obtained
.hrough DFHSC TYPE = GETMAIN, CLASS = TRANSDATA (da.a + 4 byte, for
LLbbl.
I........--+-__..
y
incl LLbb
LTDOABAR
TWA - Transaction Work Area
User's Section
Size defined in peT
Default· O.
Work area:
task duration only.
I
Figure
CICS/vS-acquired
2~1-1~
L
TDOADBA
System
SectIon
OS: 40 by.e,
DOS: 12 by'es
incl LLbb
TDIABAR
I
User-acquired
COpy DFHTDIA
L TDIABAR, TCATDAA
TOIA
L
ICICS/VS or user-acqUired
USN'S Section
IntrapartltlOn input only. V/L records only. Size = size of largest record in queue.
Automatically acquired by TOP, as required.
+L - TDIADBA
I C ICSIVS-acquired
Summary of CICS/VS Storage Areas
Chapter 2.1 ..
Introduction to storage Definition
29
TIOA
TIOABAR
X'S5'
Terminal Input/Output Area IDFHTIOA)
WORO
HALFWORO
BYTE
BYTE
'---:.;...;.......;.......;...._ I__....;T...;.IO;;,;A....;;S;;,;C~A.;..-.
I
MESSAGE OATA
~--~-----r~~~~=-r--------------------+----------+---~~---4------------~
TI OA TDL
TI OADBA
BYTE
I
Ir'--------------~~--~
~
TIOALAC
TIOACLCR
TlOAWCI
TIOABAR
TIOACLCR
TIOADBA
TIOALAC
-
TIOA
TIOA
TIOA
TIOA
TIOASAL
TIOASCA
TIOATDL
TlOAWCI
Base Address Register
Control write - Line or Copy Request Isame as TIOALACI
Data Begin Address
Line Address Control Isame as TIOACLCRI
-
TlOA
TlOA
TlOA
TlOA
Storage Accounting - area Length
Storage Chain Address
Terminal - message Data Length
Write Control Indicator
FIOA File Input/Output Area IDFHFIOAI
FIOABAR
_ x'sF'1
,~(~11_______~_~_~___W=O=R=D______~I~J )~,~l~_______w_O_R_D____~-1/
TWO WORDS
t
t
t
FCFIOLRA
FCFIOLRA - FCFIO Logical Record Address
FIOADBA - File Input/Output Area Data Begin Address IDOSI
FCDSOID
- File Control Data - area lOS variablel
FWA
I
File Work Area IDFHFWADSI
t:X='B=F='=================T=W~O:=W=O=R=D=S==============~~~::~~W~O~R~D
storage ac~ounting area
FWACBAR - File Work Atea Control Base Address Register
FCUFCTA - File Control Update File Control Table Address
VSWABAR
________
Jf~~::~~W~O~R~D~-------t_:~~DATA~
FCUPDRA
FCUFCTA
FCUWA
FCUPDRA - File Control UPDate Record Address
FCUWA
- File Control Update Work Area Idata begin addressl
VSWA VSAM Work Area IDFHVSWAI
t
FCFIOFCT
FCDS01D
storage accounting control information
FIOABAR - File Input/Output Area Base Address Register
FCFIOxxx - File Control File Input/Output xxx
FCFIOfCT - FCFIO File Control Table - entry address
FWACBAR
T:. .;W:.:.:O: :. . :.:W:.: O:. :. R:.: D:.: S~_ _ _ _ _...L_J/
I
.f
L._.::.X..!:'B:.:..F_'L.I__________
,
WORD
,
(
VSWAREA
)~(~lL. . r ~
___________w==o=R=D==_ _ _
,
VSWALEN
VSWABAR - VSAM Work Area Base Address Register
VSWAREA - VSAM Work Area REcord Address
VSWAL~N - VSAM Work Area Record LENgth
SAA
SAACBAR
BYTE
X'BC'
BYTE
I
HALFWORD
Storage Accounting Area IDFHSAADSI
I
WORD
~~~~~~++-~SA.::.A~S~A:.:.:D~~+-------~~~-------i------------------------~7
SAASAFI
DATA
./
SAASACA
SAASACI
SAASAFI - SAA Storage Accounting Format Identification
SAASAD - SAA Storage Accounting Displacement (length I
SAACBAR - SAA Control Base Address Register
SAASACA - SAA Storage Accounting Chain Address
SAASACI - SAA Storage Accounting Class Identification
TSIOABAR
TSIOA
Temporary Storage Input/Output Area IDFHTSIOAI
DATA
WORD
X'SE'
)
TSIOASCA - TSIOA Storage Chain Address
TSIOAVRL - TSIOA Variable Record Length ILLbbl" •
TSIOABAR - TSIOA Base Address Register
TSIOADBA - TSIOA Data Begin Address
TSIOASAL - TSIOA Storage Accounting - area Length
TDOABAR
TOOA Transient Data Output Area IDFHTDOAI
X'BD'
DATA
WORD
TDOASCA - TDOA Storage Chain Address
TDOAVRL- TDOA Variable Record Length ILLbbl"
TDOABAR - TDOA Base Address Register
TD,OADBA - TDOA Data Begin Address
TDOASAL - TDOA Storage Accounting - area Length
TOIA
Transient Data Input Area IDFHTDIAI
DATA
WORD
TDIADBA
TDIASCA
TDIABAR - TDIA Base Address Register
TDIADBA - TDIA Data Begin Address
TDIAIRL - TDIA Intrapartition Record Length ILLbbl"
• Length is "Message Data" only
Idoes not include TlOATDL itself, or the EOB byte).
•• Length includes LLbb and data.
Figure 2 .. 1-2 ..
I
TDOADBA
TDOASCA
30
/
TSIOADBA
TSIOASCA
TDIASAL - TDIA Storage Accounting - area Length
TDIASCA - TDIA Storage Chain Address
••• Length includes LLbb and data unless
STORCLS=TERMINAL in which case
length is length of data only.
CICS/VS System Sections
CICS/VS APR! (ftL)
;'
L-~)'ATA~
Copying Symbolic Storage Definitions
Depending on the programming language used, a statement of one of the
forms shown below is required to copy a symbolic storage definition into
an application program.
1.
Assembler-language COpy statement of the form:
COpy name
2.
COBOL COpy statement of the form:
01 name COpy name.
specified in the Linkage Section of the Data Division.
3.
PLjI preprocessor statement of the form:
%INCLUDE library
or
%INCLUDE member;
~ember);
Por example, assume that one or more terminal input/output areas
(TIOAs) are to be acquired during program execution. One of the
statements below must be included:
COpy DPHTIOA
Assembler:
COBOL:
01 DPHTIOA COpy DPHTIOA.
PL/I:
%INCLUDE DFHTIOA;
This statement copies the storage definition as a description or map
of the storage area into the application program, but does not aquire
storage for it. As pointed out above, sometimes CICS/VS acquires the
area; in other cases, the user acquires it.
Addressability
The storage definition that has been copied into the application program
must be mapped over the storage area acquired. This is done by moving
the address of the area (stored in a particular location by CICS/VS)
into a base locator for that area. Addressability through this base
locator is limited to 4096 (0 through 4095) bytes. Depending on the
programming language, a statement of one of the following forms vill
normally be used to establish addressability to the area:
1.
Assembler-language statement of the form:
L
2.
base-locator,location-containing-address
COBOL statement of the form:
MOVE location-containing-address TO base-locator.
3.
PLjI based pointer assignment of the form:
base-locator = location-containing-address;
Chapter 2.1.
Introduction to Storage Definition
31
For example, assume that a terminal input/output area (TIOA) has been
acquired during program execution. TCASCSA is a four-byte field in the
TCA that contains the address of the storage area that 'has been
acquired. TIOABAR is the TIOA base address register. One of the
statements below must be executed:
Assembler:
L TIOABAR,TCASCSA
COBOL:
MOVE TCASCSA TO TIOABAR.
PL/I:
TIOABAR=TCASCSA;
FiguDe 2~1-3 contains the names used in copying CICS/VS-provided
symbolic storage definitions into an application program and the names
that represent base addresses used in establishing addressability.
These symbolic names are used in Figures 2.1-1 and 2.1-2, which show how
the areas are related and give a summary of the contents of each area.
,I
~----------------------------~---------------"~-----------~I------------~
I
Storage Area
I
I
Symbolic Name ,IBase LocatorlGeneral
for
I
or
IPurpose
Defined StoragelBase AddresslRegister
Register IAssignment
I------------------------~~------------~----------~I------------
ICommon System Area (CSA)
ITask Control Area (TCA)
ITerminal Control Table
I Terminal Entry ~CTTE)
ITerminal Input/Output Area
I (TIOA)
IFile Input/Output Area
I (FIOA)
IFile Work Area (FWA)
VSAM Work Area (VSWA)
Storage Accounting Area
(SAA)
Temporary Storage Input/
Output Area (TSIOA)
Transient Data Output Area
(TDOA)
Transient Data Input Area
(TDI! )
Journal Control Area (JCA)
DFHCSADS
DFHTCADS
CSACBAR
TCACBAR
13
12
DFHTCTTE
DFHTIOA
TCTTEAR
TIOABAR
*
DFHFIOA
FIOABAR
DFHFWADS
DFHVSWA
DFHSAADS
FWACBAR
VSWABAR
S!ACBAR
*
*
DFHTSIOA
TSIOABAR
*
DFHTDOA
TDOABAR
*
DFHTDIA
TDIABAR
*
DFHJCADS
JCABAR
*
*
*
*
*Any register except 12, 13, or 14 (which are used by CICS/VS)
or 0 (which cannot be used as a base or index register)
Figure 2.1-3. Symbolic Names and Base Addresses of CICS/VS Storage
Areas
Chaining of CICS/VS Storage Areas
Storage acguired by the application program through CICS/VS storage
management is controlled by chaining together all storage associated
with a task. This chaining allows CICS/VS to release all storage
associated ~ith the task, either upon reguest from the user or when the
task is terminated, normally or abnormally.
32
CICS/VS APRM (ML)
The common system area (CSA), whose address is provided by CICS/VS,
points to the task control area (TCA) which in turn points to the other
storage areas required by the task. The TCA is the head of the chain of
storage associated with each task, except for TIOAs, which are chained
from the TCTTE. Figure 2.1-4 illustrates the chaining of CICS/VS
storage areas and indicates the symbolic base address used to locate
each storage area.
Required Storaqe Areas
At least two storage area definitions, namely, those for the CSA and the
TCA, are required in every application program to be run under CICS/VS.
The following sections describe these areas. Services performed by
CICS/VS components are mentioned as necessary. Some tables that are
basic to CICS/VS operation are also mentioned. These tables are
explained in greater detail in the CICSLVS System Programmer's Reference
Manual.
Common System Area (eSA)
The Common system Area (CSA) contains areas and data required for the
operation of CICS/VS. It can be extended to include a user-defined
common work area (CWA) that can be referred to by application programs.
Data in the CSA that is required for the operation of CICS/VS
includes:
•
CICS/VS save areas
•
Addresses of CICS/VS management programs
•
Control system and user statistics accumulators
•
Addr.esses of CICS/VS system control tables
•
Common system constants
o
System control parameters
Chapter 2.1.
Introduction to Storage Definition
33
CICSIVS
- . CSACBAR
FACILITIES FOR TASK C
FACILITIES FOR TASK B
COMMON
WORK
AREA
CWA.
FACI LITI ES CONTROL
AREA ASSOCIATED
ADDRESS
1----._ TIOABAR
~---------~
t~
~1_'2__
BY_T_E_S~I______~______~
STORAGE CONTROL
STORAGE ADDRESS
(SAACBAR)
+
DFHSAADS
~
~1_8_BY_T_ES-LI____~~__~~
FWACBAR
+~
~1
~I________~.~
FILE CONTROL
AREA ADDRESS
___
'6_B_YT_E_S__
FIOABAR
~
I
DFH~IDA
OSIVS-64 BYTES
I,
I
~~DO~S~/~VS~~~O~B~Y~T~E~S__-+~
__.~r__~~
VSWABAR
+I ~i DFH~SWA
----"----------.
I
96 BYTES
I
L - -_ _--J,~
TRANSIENT DATA
AREA ADDRESS
TEMPORARY STORAGE
DATA AREA
I
I
I
I
TRANSACTION WORK AREA
I
I
TWA·
~
Figure 2.1-4.
34
THIS AREA IS DEFINED AFTER THE DFH.xxxx. THE PUI AND COBOL
PROGRAMMER MUST COMPLETE THE BASED STRUCTURE (SYMBOLIC
STORAGE DEFINITIONS) BY WRITING DECLARATIONS WITH A LEVEL
NUMBER GREATER THAN 1. THE ASSEMBLER LANGUAGE
PROGRAMMER MUST WRITE OS STATEMENTS'
•• TCAFCAA. TCATDAA. AND TCATSDA ARE OVERLAYED IN SAME STORAGE.
Chaining of CICS/VS storage Areas
CICS/VS APRH (ML)
Common Work Area (CWAl
4 .
The Common Work Area ~WA) is an area within the CSA that can be used by
application programs for user data that needs to be accessed by any task
in the system. This area is acguired during system initialization and
its size is determined by the system programmer at system generation.
It is initially set to binary zeros. Its contents can be accessed and
altered by any task during CICS/VS operation.
Addressability for the CWA is provided when copying the CICS/VS
storage definition for the CSA. However, addressability is limited to a
combined total of 4096 (0 through 4095) bytes for the CSA and CWA.
Addressability for any portion of the CWA extending beyond the 4096-byte
limit is the responsibility of the user.
Since the CWA is available to any task while it has control of the
system, it is not advisable fo~ an application program to use this area
for retention of data when requesting CICS/VS services; instead, it
would be better to use the transaction work area (TWA) which has been
designed to be used by individual tasks for their own purposes. The TWA
is described later in this chapter.
Task Control Area (TCA)
The Task Control Area (TCA) is an area of main storage acquired by
CICS/VS when a task is initiated by the task control program. Once
acguired, the TCA exists until the task is terminated. It contains the
current status of the task, its relative dispatching priority, and
parameters and information being passed between CICS/VS and the
application program. During execution of the task, the user can change
the priority through task management services; further processing of the
task is scheduled accordingly.
The TeA provides the following items for its associated task:
•
Register save areas
•
Unigue fields (parameter areas) for communicating requests to
CICS/VS
•
Address of the related Facility Control Area (FCA)
•
Task storage chain addresses
The TCA makes no provision for residual data such as statistics.
However, the TCA can be extended to include a transaction work area
(TWA), the size of which is determined by the user to meet the needs of
the transaction.
(See "Transaction work Area", later in this chapter .. )
The TCA consists of three parts:
•
CICS/VS system section
•
communication section
•
Optional Transaction Work Area (TWA)
The CICS/VS system section contains addresses and data needed by
CICS/VS to control the task. Access to this section is limited to
CICS/VS management and service programs.
The communication section is used by CICS/VS and by user-written
application programs for communication between the application program
Chapter 2.1.
Introduction to Storage Definition
35
and CICS/VS management and service programs, CICS/VS functions
sometimes overwrite some of the fields in the communication section of
the TCA. The assignment of required fields in the TCA for a particular
CICS/VS request must therefore be done immediately prior to issuing the
request, with no other requests intervening.
The optional transaction work area is reserved for the exclusive use
of the application program.
In those cases in which a task is initiated from a terminal (nearly
always the case) , CICS/VS places into the TCA the address of the
terminal control table terminal entry (TCTrE) associated with the
terminal. The TCTTE, in turn, contains the address of the terminal
input/output area (TIOA).
T~an2acti2n-!ork
Area (TWAt
The Transaction Work Area (TWA) is an extension of the TCA and is
created at the option of the user to provide a work area for a given
task. The TWA can be used for the accumulation of data and intermediate
results during the execution of the task. It can also be used when the
amount of working storage for a task is relatively static, when data
must be passed between user-written application programs, or when data
must be accessed by different programs during transaction p~ocessing.
During multiple entries of data for a transaction, the application
programs might retain the data in the TWA. This approach cannot be used
for multiple transactions; the 'rWA is released automatically at task
termination.
The size of the TWA for the task must be determined by the
application designer and must be specified in the program control table
by the system programmer at system generation. The TWA must be defined
immediately following the definition of the TCA in the application
program. The sizes of TWAs within the system vary according to the
needs of the transaction. The TWA is initially set to binary zeros.
(For a discussion about establishing the TWA, see the explanation of the
program control table in the CICStVS System Programmer's Reference
Manual.
Addressability of the TWA is provided when copying the CICS/VS
storage definition for the TCA. However, addressability is limited to a
combined total of 4096 (0 through 4095) bytes for the TCA and TWA.
Addressability for any portion of the TWA extending beyond the 4095-byte
limit is the responsibility of the user.
36
CICS/VS APRM (ML)
Chapter 2.2. Storage Definition - Assembler Language
The Assembler-language programmer must define storage for the CICS/VS
control areas and any other storage areas required for the processing of
the application program~ This is done by using the Assembler-language
COPY statement to (1) copy the appropriate symbolic storage definitions
into the application program and (2) specify the names of the storage
areas being defined. All registers are available, except registers 12,
13, and 1~ (which are used by CICS/VS).
All application programs must contain statements to copy the symbolic
storage definitions for the common system area (CSA) and the task
control area (TCA). If a terminal is to be used, the storage definition
of a TCTTE must be copied also. The expansions of the CICS/VS macro
instructions used in an application program refer to fields within these
areas, so their locations must be identified. Whether additional
definitions must be copied depends on the processing requirements
(storage areas and macro instructions used) of the application program.
Storage Defined During Initialization
During CICS/VS initialization, the CSA is allocated as part of the
CICS/VS nucleus. For each terminal that is to be used, a terminal
control table terminal entry (TCTTE) must be included in the terminal
control table (TCT).
COMMON SYSTEM AREA
~SA)
The statement
COPY DFHCSADS
copies the symbolic storage definition for the CSA and assigns register
13 as its base register.
If CICS/VS is generated to include a common work area (CiA), a
symbolic definition for that area must be included immediately following
the COpy DFHCSADS statement. In the following example, a total of 16
bytes of storage are defined by the three DS statements. It is assumed
that a CWA of at least 16 bytes has been defined.
COpy
BUCKET1 DS
BUCKET2 DS
TEMPNAME DS
DPHCSADS
F
F
cta
Chapter 2.2.
Storage Definition - Assembler Language
37
TERMINAL CONTROL TABLE
TER~INAL
ENTRY (TCTTE)
The statement
COPY DFHTCTTE
copies the symbolic storage definition for the TCTTE. This definition
can be used to obtain the address of the current terminal I/O area (the
current terminal control table terminal entry data address, or TCTTEDA)
or to request a terminal control service via the DFHTC macro
instruction. An EQU statement must be included to set up a base
register for the TCTTE, equating the label TCTTEAR to a general-purpose
register. Addressability must also be established for the TCTTE by
loading the address at TCAFCAAA into TCTTEAR. The following is an
example of the coding required:
TCTTEAR EQU 5
COpy DFHTCTTE
L
TCTTEAR,TCAFCAAA
Storage Defined During Execution
During execution of a task, the TCA, TIOA, and other storage areas
required by the task are allocated by CICS/VS storage management upon
request from either the application program or CICS/VS. The application
program must include symbolic storage definitions for these storage
areas by using COpy statements as described below.
TASK CONTROL AREA (TCA)
The statement
co PY
DFHTCADS
copies the symbolic storage definition for the communication section
only of the TCA and assigns register 12 as the base register for the
whole of the TCA. If the application program requires the use of a
transaction work area (TWA), DS statements for the TWA must immediately
follow the COpy statement. The following is an example of the coding
required to symbolically define storage for both the TCA and TWA. In
the example, a total of 53 bytes of storage are defined by the four DS
statements. It is assumed that a TWA of at least 53 bytes has been
defined in the PCT for the transaction.
STREET
CITY
STATE
COPY
DS
DS
DS
DS
DFHTCADS
CL20
CL20
CL10
CL3
CICS/VS
APR~
(ML)
NA~E
38
TERMINAL INPUTjOUTPUT AREA (TIOA)
The statement
COPY DFHTIOA
copies the symbolic storage definition for the CICS/VS system section of
the TIOA~ This storage definition should precede the user's definition
of a terminal input or output message. The user must code an EQU
statement to set up a base register for the TIOA, equating the label
TIOABAR to a general-purpose register~ Any action that requires a TIOA
can then be specified. For example, a DFHSC TYPE=GETMAIN macro
instruction requesting CICS/VS storage control to obtain dynamic storage
for a TIOA for the program can be specified, as follows:
TIOABAR EQU
COpy
NAME
DS
STREET DS
DS
9
DFHTIOA
CL20
CL20
CLS
DFHSC TYPE=GETMAIN,NUMBYTE=4S,CLASS=TERMINAL
L
TIOABAR,TCASCSA
For additional information about obtaining storage, see "Obtain and
Initialize Main storage (TYPE=GETMAIN)" in Chapter 5.5.
FILE INPUT/OUTPUT AREA (FIOA)
The statement
COpy DFHFIOA
copies the symbolic storage definition for the CICS/VS system section of
the FIOA. This storage definition should precede the user's defined
layout of a file input or output area when reading an unblocked record
without updating or segmenting, or when reading DAM blocked records
without deblocking. If desired, the user can identify that the area
returned in response to a user file request is an FIOA, rather than an
FWA or VSWA, by testing label FIOAIND for a mixed condition using mask
PIOAM.
The user must code an EQU statement to set up a base register for the
PIOA, equating the label FIOABAR to a general-purpose register. The
FIOA is automatically acquired 'by CICSjVS file management whenever a
request is made by the user to access a data base data set. If data is
retrieved using the Indexed Sequential Access Method (ISAM) under
CICS/OS/VS, a 16-byte filler must be defined prior to the user's data
definition. The user must establish addressability for an PIOA acquired
in response to a DFHFC macro instruction before referring to the FIOA.
The following is an example of the coding required; it includes the
optional test for FIOA identification.
Chapter
2.2~
Storage Definition - Assembler Language
39
FIOABAR EQU
COPY
DS
DS
NAME
STREET DS
7
DPHFIOA
16X
CL20
CL5
OS/VS ISAM FILLER
PIOABAR,TCAFCAA
FIOAIND,FIOAM
GOTPIOA
WAS FIOA RETURNED?
YES
.l.
~
],
Tr!
BM
PILB WORK AREA (FWA)
The statement
COpy DPHPWADS
copies the symbolic storage definition for the CICSjVS system section of
the FWA. This storage definition should precede the user's defined
layout of a file record area when reading or updating an existing
blocked or segmented record, when adding a new record to a file, or when
retrieving records using the browse feature. If desired, the user can
identify that the area returned in response to a user file request is an
PWA, rather than an FIOA or VSWA, by testing label FWAIND for a ones
condition using mask PWAM.
The user must code an EQU statement to set up a base register for the
FWA, equating the label FWACBAR to a general-purpose register. The user
must also establish addressability for an FWA acquired in response to a
DPHPC macro instruction prior to any reference to the PiA. The
following is an example of the coding required; it includes the optional
test for FWA identification:
FWACBAR EQU
COPY
NAME
DS
STREET DS
ZIPCODE DS
7
DFHFWADS
CL20
CL30
CL5
•J
~
TM
BO
VSAM iORK AREA
PiACBAR,TCAFCAA
FiAIND,FWAM
GOTPWA
WAS FiA RETURNED?
YES
~SWA)
The statement
COpy DPHVSWA
copies the symbolic storage definition for the CICS/VS system section of
the VSA! work area (VSiA) and must be present in all programs using
locate mode I/O.
(See "Direct Retrieval (V SAM Locate Mode) II in Chapter
3.2.) If desired, the user can identify that the area returned in
response to a user file request is a VSWA, rather than an PIOA or PWA,
by testing label VSWAID for a zero condition using mask VSWA!.
40
CICS/VS APRr! (ML)
The user must code an EQU statement to set up a base register for the
VSWA, equating the label VSWABAR to a general-purpose register. After a
VSWA is acquired by CICS/VS in response to a DPHPC macro instruction
using locate mode I/O, the user must establish addressability for the
VSWl prior to any reference to that area. The following is an example
of the coding required; it includes the optional test for VSWA
identification:
VSWABAR EQU
COPY
L
TM
BZ
7
DPHVSWA
VSWABAR,TCAPCAA
VSWAID, VSWAM
GOTVSWA
WAS VSWA RETURNED?
YES
TRANSIENT DATA INPUT AREA (TDIA)
The statement
COpy DFHTDIA
copies the symbolic storage definition for the CICS/VS system section of
the intrapartition TDIA. This storage definition should precede the
user's defined layout of the message area used for data obtained from an
intrapartition destination by means of a DPHTD TYPE=GET macro
instruction.
~ee "Acquire Queued Data (TYPE=GET)" in Chapter 5.6.).
The user must code an EQU statement to set up a base register for the
TDIl, equating the label TDIABAR to a general-purpose register. The
user must also establish addressability for the TDIA following a DPHTD
macro instruction. The following is an example of the coding required:
TDIABAR EQU
COpy
NAKE
DS
STREET DS
9
DPHTDIA
CL20
CL20
TDIABAR,TCATDAA
TRANSIENT DATA OUTPUT lREA (TDOA)
The statement
COpy DFHTDOA
copies the symbolic storage definition for the CICS/VS system section of
the intrapartition TDOA. This storage definition should precede the
user's defined layout of the message area for transient data to be
directed to an intra partition or extrapartition destination by means of
a DPHTD TYPE=PUT macro instruction.
(See "Dispose of Data (TYPE=PUT)"
in Chapter 5.6.)
The user must code an EQU statement to set up a base register for the
TDOA, equating the label TDOABAR to a general-purpose register. The
address of the data to be output (including the four-byte length field
Chapter 2.2.
Storage Definition - Assembler Language
41
in the case of variable-length records) must be given to transient data
control either through the TDADDR operand of the DFHTD macro instruction
or by placing it in TCATDAA. The following is an example of the coding
required:
TDOABAR EQU
COpy
DS
TIME
DS
DATE
INTERM DS
OUTTERM DS
9
DFHTDOA
CL4
PL3
CL4
CL4
DFHSC TYPE=GETMAIN,CLASS=TRANSDATA,NUMBYTE=19
L
TDOABAR,TCASCSA
DFHTD TYPE=PUT,DESTID=POST,TDADDR=TDOAVRL
TDOAVRL is a name associated with the first byte of the output
message (LL~~ for variable-length records).
TEMPORARY STORAGE INPUT/OUTPUT AREA
(TSIOA)
The statement
COPY DFHTSIOA
copies the symbolic storage definition for the CICS/VS system section of
the TSIOA. This storage definition should precede the user's defined
data fields.
The user must code an EQU statement to set up a base
register for the TSIOA, equating the label TSIOABAR to a general-purpose
register. The address of the data, which always includes a length field
(LL~~) for temporary storage must be given to temporary storage control
either through the TSDADDR operand of the DFHTS macro instruction or by
placing it in TCATSDA. The following is an example of the coding
required:
TSIOABAR EQU
COPY
PAGENO
DS
TITLE
DS
LINE1
DS
6
DFHTSIOA
PL2
CL30
CL70
~
~
DFHTS TYPE=GET
TSIOABAR,TCATSDA
L
sa
TSIOABAR,=H'8'
Upon execution of the DFHTS TYPE=GET macro instruction, CICS/VS
returns the address of the data portion (LL~~ field) of the temporary
storage record which is read in TCATSDA. To establish addressability to
the TSIOA (that is, to use the DFHTSIOA'DSECT), the application program
must subtract eight from this address to point to the storage accounting
field of the storage area acquired by CICS/VS. If the TSDADDR operand
is included in the DFHTS TYPE=GET macro instruction, this is not
required,
42
CICS/VS
APRM(M~
STORAGE ACCOUNTING AREA
(SAA)
The statement
COpy DFHSAADS
copies the symbolic storage definition for the SAA. This storage
definition should precede the user's defined layout of a unique work
area that is used within the application program. The user must code an
EQU statement to set up a base register for the SAAt equating the label
SAACBAR to a general-purpose register. The following is an example of
the coding required:
SAACBAR
SYMBLA
NAME
SlREET
SYMBLB
EQU
COPY
EQU
DS
DS
EQU
9
DFHSAADS
*
CLSO
CL1S
*-SYMBLA
DFHSC TYPE=GETMIIN,INITIMG=OO,NUMBYTE=SYMBLB,
CLASS=USER
L
SAACBAR,TCASCSA
Having copied the symbolic storage definition for the SAA, the
application program can specify a DFHSC TYPE=GETMAIN instruction
requesting CICS/VS storage control to obtain main storage for use by the
program. The address returned by CICS/VS in TCASCSA should be moved to
SAACBAR, the base address register for the SAA.
JOURNAL CONTROL AREA (JCA)
The statement
COpy DFHJCADS
copies the symbolic storage definition for the CICS/VS system section of
the journal control area (JCA) and must be present in all programs
requesting journal services. (See "Journal Control", Chapter 7.5.) The
user must code an EQU statement to set up a base register for the'JCI ,
equating the label JCABAR to a general-purpose register~ The following
is an example of the coding required:
JCABAR
EQU
COPY
9
DFHJCADS
A JCA is acquired by means of a DPHJC TYPE=GETJCA macro instruction.
Addressability to the JCA is automatically provided through the macro
expansion, which loads the JCA address into JCABAR.
Chapter
2~2.
storage Definition - Assembler Language
43
Example of CICS/VS Assembler-language Application Program
Pigure 2.2-1 is an Assembler-language program written to run under
CICS/VS. The program asks a question of the terminal operator, receives
a reply, dynamically acquires some storage, and sends the operator's
message back to the terminal. In effect, an echo test is performed.
(The line numbers in the figure are not part of the program.)
01
02
03
04
05
06
01
08
09
10
11
12
13
14
15
16
11
18
19
20
21
22
23
24
25
26
21
28
29
30
31
BASEREG EQU
TCTTE1R EQU
TIOAB1R EQU
COPY
COpy
LENGTH DS
MESSAGE DS
COPY
COpy
MESSG
DS
CSECT
BALR
USING
Pigure
L
L
8VC
8VC
DPHTC
L
8VC
MVC
DPHSC
L
ST
MVC
MVC
DPHTC
DPHPC
END
2~2-1.
2
11
10
DPHCSADS
DPHTCADS
H
CL32
DPHTCTTE
DPHTIOA
CL32
BASEREG,O
* ,BASEREG
TCTTEAR,TCAPCAAA
TIOABAR,TCTTEDA
MESSG,=CIENTER MESSAGE TO BE ECHOED I
TIOATDL,=H I 26 1
TYPE=(WRITE,READ,WAIT,ERASE)
TIOABAR,TCTTEDA
LENGTH,TIOATDL
MESSAGE,MESSG
TYPE=GETMAIN,
CLASS=TERMIHAL,
NUMBYTE=32
TIOABAR,TCASCSA
TIOABAR,TCTTEDA
MESSG ,KESSAGE
TIOATDL,LENGTH
TYPE=WRITE
TYPE=RETURN
*
*
Example of CICSjVS Assembler-Language Application Program
A discussion of the significance of each of the lines of Figure 2.2-1
follows.
44
CICS/VS APRM(ML)
Line Number
01
02-03
04-05
06-01
08-09
10
11-13
14
15
16
11
18
19
20-21
22-24
25
26
21
28
29
30
31
Chapter 2.2.
Description
Assigns base register for program.
Assigns base registers for TCTTE and
TIOA symbolic storage definitions.
Copies CSA and TCA symbolic storage
definitions.
Defines fields in TWA as save areas to
provide for quasi-reenterability.
Copies TCTTE and TIOA symbolic storage
definitions.
Defines message area in TIOA.
Begins program; establishes addressability
for program.
Establishes addressability for TCTTE.
Establishes addressability for TIOA.
Moves message to output area of TIOA.
Moves length of message to data length
field of TIOA.
CICS/VS macro instruction that writes message
to terminal, waits for operator's reply,
and reads operator's reply.
Establishes addressability for new TIOA,
using address in TCTTE.
Saves the message and the length of the
message in the TWA save areas.
CICS/VS macro that requests 32 bytes
of terminal type storage.
Establishes addressability for new TIOA
(address of newly acquired storage area is
in TCASCSA field of the TCA).
Places address of new TIOA in TCTTE.
Moves the message from TWA save area to
new TIO!.
Moves the message length to data length
field of new TIOA.
CICS/VS macro instruction that writes message
to terminal.
CICS/VS macro instruction that returns control
to CICS/VS and terminates this task.
Required for Assembler language.
Storage Definition - Assembler Language
45
Chapter 2.3. Storage Definition - COBOL
The COBOL programmer must define storage for the CICS/VS control areas
and any other storage areas required for the processing of the
application program. This is done by using (1) the COpy statement in
the Linkage section of the Data Division to copy the symbolic storage
definitions into the program and specify the names of the storage areas
being defined, and (2) the MOVE statement in the Procedure Division to
establish addressabi1ity by moving symbolic storage addresses from one
location to another.
The working storage section of a COBOL program should contain only
data constants. Variable data should be placed in a TWA or in an area
of storage acquired by a DFHSC TYPE=GETMAIN macro instruction.
(See
"Obtain and Initialize Main storage (TYPE=GETMAIN)" in Chapter 5.5.)
The statement
01 DFHBLLDS COpy DFHBLLDS.
must be the first statement in the Linkage section of the Data Division
of an COBOL program that is run under CICS/VS. This statement copies
the symbolic storage definition for the Linkage section base locator
(BLL), which provides the means by which a COBOL program can address
dynamically acquired CICS/VS storage areas. Included in this definition
are the symbolic base addresses for the common system area (CSA), common
system area optional features list (CSAOPFL), and task control area
(TCA). Symbolic storage definitions for these areas must be copied into
every COBOL program.
If other CICS/VS storage areas are needed, the COpy statement for the
BLL must be followed immediately by statements of the form
02 name PICTURE S9 (8) USAGE IS COMPUTATIONAL.
where name is the symbolic base address used to locate a specific
storage area. There must be one of these statements for each additional
type of storage needed by the application program. Furthermore, these
02-1eve1 statements must be coded in the same order as the corresponding
01-1eve1 COpy statements coded subsequently to copy the symbolic storage
definitions for the areas into the application program.
If the user is going to communicate with the system by means of a
terminal, a terminal input/output area (TIOA) and a terminal control
table terminal entry (TCTTE) are needed. Assuming that only the
required control areas (CSA and TCA), a TIOA, and a TCTTE are needed for
a particular application, the following example shows coding required in
the linkage section of the Data Division:
01 DFHBLLDS COPY DFHBLLDS.
02 TCTTEAR PICTURE S9(8) USAGE IS COMPUTATIONAL.
02 TIOABAR PICTURE S9(8) USAGE IS COMPUTATIONAL.
01 DFHCSADS COpy DFHCSADS.
01 DFHTCADS COpy DFHTCADS.
01 DFHTCTTE COpy DFHTCTTE.
01 DFHTIOA COpy DFHTIOA.
Chapter 2.3.
storage Definition - COBOL
47
Storage Defined During Initialization
During CICS/VS initialization, the common system area (CSA) is allocated
as part of the CICS/VS nucleus. For each terminal that is to be used, a
terminal control table terminal entry (TCTTE) must be included in the
terminal control table (TCT). The COBOL programmer must provide
symbolic storage definitions ,for the CSA and TCTTE (if needed) as
follows.
COMMON SY STEM AREA (CSA)
The statement
01 DFHCSADS COPY DFHCSADS.
copies the symnolic storage definition for the CSA.
the CSA is included.
Addressability for
If CICS/VS is generated to include a common work area ~iA), a
symbolic definition of that area must be included immediately following
the COPY statement in the linkage section of the application program.
The following is an example of the coding required:
01 DFHCSADS COPY DFHCSADS.
02 CiA.
03 FIELD1 PIC 1(4).
TERMINAL CONTROL TABLE TERaINAL ENTRY (TCTTE)
The statement
01 DFHTCTTE COpy DFHTCTTE.
copies the symnolic storage definition for the TCTTE and must be present
in all programs requesting communication with a terminal. The user must
code the statement
MOVE TCAFCAAA TO TCTTEAR.
in the appropriate place in the Procedure Division to establish
addressability for the TCTTE. TCAFCAAA contains the address of the
facility that initiated the transaction. TCTTEAR is the terminal
control table terminal entry address register.
48
CICS/VS APRM(ML)
Storage Defined During Execution
During the execution of a task, the task control area (TCA), the
terminal input/output area (TIOA), and other storage areas required by
the task are allocated by CICS/VS storage management upon request from
either the application program or CICSjVS. Symbolic storage definitions
for these storage areas must be provided as follows.
TASK CONTROL AREA (TCA)
The statement
01 DFHTCADS COPY DFHTCADS.
copies the symbolic storage definitions for the CSA optional features
list and the TCA. The user must code the statement
KOVE CSACDTA TO TCACBAR.
and can optionally code the statement
MOVE CSAOPFLA TO CSAOPBAR.
at the appropriate place in the Procedure Division to establish
addressability for the TCA and the CSA optional features list. CSACDTA
contains the address of the storage area obtained for the TCA (the
common system area currently dispatched task address). This address is
stored in TCACBAR, the TCA control base address register.
If the application program requires the use of a transaction work
area (TWA), the record layout of the TWA must be defined immediately
following the COpy statement in the linkage section of the application
program. The following is an example of the coding required:
01 DFHTCADS COPY DFHTCADS.
02 TWA PIC X(40).
TERMINAL INPUT/OUTPUT AREA (TIOA)
The statement
01 DFHTIOA COPY DFHTIOA.
copies the symbolic storage definition for the CICS/VS system section of
the TIOA and must be present in all programs that use terminal input
records or that. provide output records to a terminal. The following is
an example of the coding required to define the record(s) in the TIOA:
01 DFHTIOA COpy DFHTIOA.
02 TRANSID PIC XXXX.
02 TIOAMSG PIC X(20).
Chapter 2.3.
Storage Definition - COBOL
49
The user must establish addressability for the TIOA in the Procedure
Division by coding in the appropriate place either the statement
MOVE TCTTEDA TO TIOABAR.
or the statement
MOVE TCASCSA TO TIOABAR.
The former statement is used to establish addressability to a TIOA
acquired by CICS/VS during execution for data entered from a terminal.
The latter statement is used to establish addressability for a new TIOA
acquired by a DFHSC TYPE=GETMAIN macro instruction and should be coded
immediately following that macro instruction~
FILE INPUTjOUTPOT AREA (FIOA)
The statement
01 DFHFIOA COpy DFHFIOA.
copies the symbolic storage definition for the CICS/VS system section of
the FIOA and must be present in all programs requesting a read of an
unblocked record without updating or segmenting, or a read of blocked
records without deblocking. If desired, the user can identify that the
area returned in response to a file request is an FIOA, rather than an
FiA or VSWA, by testing FIOAM. If data is retrieved using the Indexed
Sequential Access Method (ISAM) under CICS/OS/VS, a 16-byte filler must
be defined prior to the user's data definition. The following is an
example of the coding required to define records in the FIOA:
01 DFHFIOA COPY DFHFIOA.
02 FILLER PIC X(16).
02 KEYF PIC X (6).
02 NAME PIC X(20).
02 FIOAREC PIC X(74).
NOTE OS/VS ISAM FILLER.
The user must code the statement
MOVE TCAFCAA TO FIOABAR.
prior to any reference to the FIOA following a DFHFC macro instruction
in the Procedure Division to establish addressability for the FIOA.
To identify the area returned as an FIOA, the following instruction
can be used:
IF FIOAM
THEN GO TO GOTFIOA.
50
CICS/VS APRM (ML)
FILE iORK AREA (FiA)
The statement
01 DFHFiADS COPY DFHPiADS.
copies the symbolic storage definition for the CICS/VS system section of
the FiA and must be present in all programs performing file operations
wi th the exception of a "read without update" from an unblocked,
unsegmented data set. If desired, the user can identify the area
returned in response to a file request as an FiA, rather than an PIOA or
VSil, by testing PiAM. The following is an example of the coding
required to define records in the FiA:
01 DFHFiADS COpy DFHPWADS.
02 KEYF PIC X(6).
02 NAME PIC X(20).
02 FWAREC PIC X (24).
The user must code the statement
MOVE TCAPCAA TO PiACBAR.
prior to any reference to the FiA following a DPHFC macro instruction in
the Procedure Division to establish addressability for the FiA.
To identify the area returned as an PHA, the following instruction
can be used:
IF FiAM
THEN GO TO GOTFiA.
VSAM WORK AREA (VSiA)
The statement
01 DFHVSWA COpy DFHVSiA.
copies the symbolic storage definition for the CICS/VS system section of
the VSAM work area and must be present in all programs using VSAM locate
mode I/O.
(See "Direct Retrieval (VSAM Locate Mode) II in Chapter 3.2.)
If desired, the user can identify that the area returned in response to
a file request is a VSiA, rather than an FIOA or FHA, by testing VSWAM.
The user must code the statement
MOVE TCAFCAA TO VSiABAR.
prior to any reference to the VSWA acquired by CICS/VS in response to a
DFHFC macro instruction using locate mode I/O.
To identify the area returned as a VSWA, the following instruction
can be used:
IF VSWAM
THEN GO TO GOTVSiA.
Chapter 2.3.
storage Definition - COBOL
51
TRANSIENT DATA INPUT AREA (TDIA)
The statement
01 DFHTDIA COpy DFHTDIA.
copies the symbolic storage definition for the CICS/VS system section of
the intra partition TDIA and must be present in all programs requiring a
message area for transient data obtained by issuing a DFHTD TYPE=GET
macro instruction that refers to an intrapartition destination. (See
"Acquire Queued Data (TYPE=GET)" in Chapter 5.6.) The following is an
example of the coding required to define records in the TDIA:
01 DFHTDIA COPY DFHTDIA.
02 MESSAGE PIC 1(25).
The user must code the statement
MOVE TCATDAA TO TDIABAR.
prior to any reference to the TDIA following a DFHTD macro instruction
in the Procedure Division to establish addressability for the TDIA.
TRANSIENT DATA OUTPUT AREA (TDOA)
The statement
01 DFHTDOA COpy DFHTDOA.
copies the symbolic storage definition for the CICSjVS system section of
the intrapartition TDOA and should be present in all programs issuing a
DFHTD TYPE=PUT macro instruction to provide transient data as output.
(See "Dispose of Data (TYPE=PUT)" in Chapter 5.6.) The following is an
example of the coding required to define records in the TDOA:
01 DFHTDOA COpy DFHTDOA.
02 MESSAGE PIC 1(20).
The user must code the statement
MOVE TCASCSA TO TDOABAR.
prior to any reference to the TDOA following a DFHSC macro instruction
in the Procedure Division to establish addressability for the TDOA.
TEMPORARY STORAGE INPUT/OUTPUT AREA (TSIOA)
The statement
01 DFHTSIOA COpy DFHTSIOA.
copies the symbolic storage definition for the CICS/VS system section of
the TSIOA and should be present in all programs using temporary storage.
The following is an example of the coding required to define records in
the TSIOA:
52
CICS/VS APRl! (l!L)
01 DFHTSIOA COpy DFHTSIOA.
02 DATA PIC 1(10).
To establish addressability for the TSIOA, the user must code the
statements
MOVE TCATSDA TO TSIOABAR.
SUBTRACT 8 FRO! TSIOABAR.
if the request is a GET or GETQ from temporary storage and the TSDADDR
operand is not specified. The subtraction of eight ensures that
TSIOABAR points to the storage accounting field (that is, to the
beginning) of the storage area acquired by CICS/VS. The user must code
the statement
MOVE TCASCSA TO TSIOABAB.
if an I)O area has been acquired during execution. In the case of a PUT
or PUTQ, the symbolic address of the data is located at TSIOAVRL.
Either statement must appear in the appropriate place in the Procedure
Division of the COBOL program.
STORAGE ACCOUNTING AREA
~AA)
The statement
01 DFHSAADS COpy DFHSAADS.
copies the symbolic storage definition for the SAA. This storage
definition should precede the definition of user storage acquired
through the DFHSC TYPE=GETMAIN,CLASS=USER macro instruction. The
following is an example of the coding required to define records in the
SAA:
01 DFHSAADS COpy DFHSAADS.
02 NAME PIC 1(20).
02 SAAREC PIC 1(10).
The user must code the statement
MOVE TCASCSA TO SAACBAR.
prior to any reference to the SAA following a DFHSC macro instruction in
the Procedure Division to establish addressability for the SAl.
JOURNAL CONTROL AREA (JC1)
The statement
.01 DFHJCADS COpy DFHJCADS.
copies the symbolic storage definition for the CICS/VS system section of
the journal control area (JCA) and must be present in all programs
requesting journal services. (See "Journal Control", Chapter 7.5.)
Chapter 2.3.
storage Definition - COBOL
53
A JCA is acquired by means of a DFHJC TYPE=GBTJCA macro instruction.
Addressability to the JCA is provided automatically through the macro
expansion, which loads the address of the area into JCABAR.
Additional Guidelines.
If the object of an OCCURS DEPENDING ON clause is defined in the linkage
section, special consideration is required to ensure that the correct
value is used at all times. In the following example, FIELD-COUNTER is
defined in the linkage section. The !OVE FIELD-COUNTER TO FIELD-COUNTER
statement is needed to ensure that unpredictable results do not occur
when referencing DATA.
LINKAGE SECTION.
01 DFHFiADS COpy DFSFiADS.
02 FIELD-COUNTER PIC 9(4) CO!P.
02 FIELDS PIC X(5) OCCURS 1 TO 5 TI!ES
DEPENDING ON FIELD-COUNTER.
02 DATA PIC X(20).
PRO~EDURE
DIVISION.
DFHFC TYPE=GET, etc.
~OVE TCAFCAA TO FWACBAR.
~OVE FIELD-COUNTER TO FIELD-COUNTER.
!OVE DATA TO TWA-FIELD.
The ~VE statement referring to FIELD-COUNTER causes COBOL to
reestablish the value it uses to compute the current number of
occurrences of FIELDS and ensures that it can correctly determine the
displacement of DATA.
If an area greater than 4096 bytes is defined in the linkage section,
special considerations arise. An additional 02-level statement under
DFHBLLDS and an ADD statement following the ~OVE statement to establish
addressability to the area are required for each additional 4096 bytes.
For example, if a file work area (PiA) exceeds 4096 bytes, the following
code can be used.
54
CICS/VS APR! (!L)
LINKIGE SECTION.
01 DFHBLLDS COpy DFHBLLDS.
02 FiACBAR PIC S9(8) CO!P
02 FiABR1 PIC S9(8) CO!P
•
01 DFHFWADS COpy
02 FIELD1 PIC
02 FIELD2 PIC
02 FIELD3 PIC
DFHFWADS.
1(4000).
1 (1000) ..
X (400) •
PROCEDURE DIVISION.
DPHFC TYPE=GET,
*
ftOVE TCAFCAA TO PWACBAR.
ADD 4096 TO FWACBAR GIVING FWIBR1.
If the size of the COBOL working storage is close to, or greater than
64K then execution errors may occur.
If an application program is to be compiled for execution under
CICS/OSjVS using the full COBOL V4 Compiler (5734-CB2), the OS/VS COBOL
Compiler (5740-CB1) with the optimization feature, or the DOS/VS COBOL
Compiler (5746-CB1) with the optimization feature, a special translator
control statement must be inserted at appropriate places within the
program to ensure addressability to a particular area defined in the
linkage section. This control statement has the form:
SERVICE RELOAD fieldname.
where fieldname is the symbolic name of a specific storage area, and is
also defined in an 01-level statement in the linkage section. The first
four statements of the Procedure Division must be:
SERVICE RELaID DFHBLLDS.
SERVICE RELOAD DPHCSADS.
MOVE CSAOPPLA TO CSAOPBIR.
SERVICE RELOAD CSAOPFL.
Statements such as:
MOVE TCIFCIII TO TCTTEAR.
SERVICE RELOAD DPHTCTTE.
or
SUBTRACT 8 PROM TCASCSA GIVING TSIOABAR.
SERVICE RELOAD DPHTSIOA.
Chapter 2.3.
storage Definition - COBOL
55
can be used to establish addressability for a particular storage area.
~ote that the SERVICE RELOAD statement must be used following each
statement which modifies addressability to an area defined in the
linkage section, that is, whenever an address is moved to a field named
in an 02-1evel statement under 01 DPHBLLDS or the address in the 02level statement is changed in any way.)
To establish addressability to the TCA, the following statements must
be coded:
!OVE CSACDTA TO TCACBAR.
SERVICE RELOAD DPHTCA.
Note that the RELOAD statement specifies DPHTCA, not DPHTCADS.
Certain COBOL features cannot be used in an application program to be
run under CICS/VS. Generally, these features are replaced by CICS/VS
services~
They are identified under "Restrictions" in Part 1.
56
CICS/VS APRM(ML)
Example of CICS/VS COBOL Application Program
Figure 2~3-1 is a COBOL program written to run under CICS/VS. The
program asks a question of the terminal operator, receives a reply,
acquires storage, and sends the operator's message back to the terminal.
In effect, an echo test is performed. (The line numbers in the figure
are not part of the program.)
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
IDENTIFICATION DIVISION.
PROGRAM-ID.
'CBLSPRB' •
ENVIRONMENT DIVISION.
DATA DIVISION.
LINKAGE SECTION.
01 DFHBLLDS COpy DFHBLLDS.
02 TCTTEAR PIC S9(8) COMP.
02 TIOABAR PIC S9(8) COMP.
01 DFHCSADS COPY DFHCSADS.
01 DFHTCADS, COPY DFHTCADS.
02 SAVE-LENGTH PIC S9(8) COMP.
02 SAVE-MESSAGE PIC X (36) •
01 DFHTCTTE COpy DFHTCTTE.
01 DFHTIOA COpy DFHTIOA.
02 TIOAMSG PIC X (36) •
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
MOVE CSAOPFLA TO CSAOPBAR.
MOVE TCAFCAAA TO TCTTEAR.
MOVE TCTTEDA TO TIOABAR.
MOVE 'ENTER MESSAGE TO BE ECHOED' TO TIOAMSG.
MOVE 26 TO TIOATDL~
DFHTC TYPE=(WRITE,READ,WAIT)
MOVE TCTTEDA TO TIOABAR.
MOVE TIOATDL TO SAVE-LENGTH.
MOVE TIOAMSG TO SAVE~ESSAGE.
DFHSC TYPE=GETMAIN,
NUMBYTE=36,
CLASS=TERMINAL
MOVE TCASCSA TO TIOABAR.
MOVE TIOABAR TO TCTTEDA.
MOVE SAVE-MESSAGE TO TIOA!SG.
MOVE SAVE-LENGTH TO TIOATDL.
DFHTC TYPE=WRITE
DFHPC TYPE=RETURN
GOBACK.
Figure 2.3-1.
*
*
Example of CICS/VS COBOL Application Program
Chapter 2.3.
storage Definition - COBOL
57
A discussion of the significance of each of the lines of Figure 2.3-1
follows.
Line Number
01-05
06
01
08-09
10
11
12-13
14
15
16
11
18-21
22
23
24
25
26
21
28-30
31
32
33
3I.J
35
36
31
58
CICS/VS APRM(ML)
Description
Required for COBOL.
start of linkage ssction.
Copies symbolic storage definition for BLL;
contains addresses of CICS/VS storage areas.
Adds addresses for TCTTE and TIOA (required
for statements 14 and 15).
Copies symbolic storage definition for CSA.
Copies symbolic storage definitions for TCA
and CSA optional features list.
Defines save areas in TWA to ensure quasireenterability (SAVE-LENGTH and SAVE-MESSAGE
are used to save operator's reply).
Copies symbolic storage definition for TCTTE.
Copies symbolic storage definition for TIOA.
Defines message area in TIOA.
Required for COBOL (start of Procedure
Division) •
Establishes addressability for TCA, CSA optional
features list, TCTTE, and TIOA (CICS/VS establishes
addressability for BLL and CSA) •
Moves message to output area of TIOA.
Moves length of message to data length field of
TIOA.
CICS/VS macro instruction that writes message to
terminal, waits for operator's reply, and reads
operator's reply.
Establishes addressability for new TIOA using
address in TCTTE.
Saves length of message in TWA.
Saves message in TWA.
CICS/VS macro instruction that requests 36 bytes
of terminal storage (terminal storage is
chained to terminal control table) •
Establishes addressability for new iTIOA ~ddress
of newly acquired storage area is in TCASCSA
field of the TCA).
Places address of new TIOA in terminal control
table.
Moves message to output area (TIOA).
Moves length of message to output area (TIOA).
CICS/VS macro instruction that writes message to
terminal.
CICS/VS macro instruction that returns control
to CICS/VS.
COBOL statement that marks the end of the
program.
Chapter 2.4. Storage Definition - PL/I
The PL/I programmer must define storage for the CICS/VS control areas
and other storage areas required for the processing of the application
program. This is done by using a statement of the form
%INCLUDE library (member) ;
or
%INCLUDE member;
to (1) copy the appropriate symbolic storage definition into the
application program at the place where the %INCLUDE statement appears,
and (2) specify the name of the storage area being defined.
The PL/I source code provided by CICS/VS in response to %INCLUDE
statements is in the form of based structures. These structures
describe the attributes of the storage areas and include pointer
variables that provide the addresses of the actual locations in storage
that the structures describe.
All application programs must contain statements to copy the symbolic
storage definitions for the common system area (CSA) and task control
area (TCA). The expansions of the CICS/VS macro instructions used in an
application program refer to fields within these areas, so their
locations must be identified. Whether additional storage d~finitions
must be copied depends on the processing requirements (storage areas and
macro instructions used) of the application program. The statements to
copy the symbolic storage definitions must be in the order CSA, TCA,
TCTTE, TIOA; this is because addressability for the last three areas
mentioned depends on the previous area already having been copied.
A PL/I program to be run under CICS/VS must contain the REENTRANT
option in the first PROCEDURE statement to satisfy the CICS/VS
requirement that code be quasi-reenterable. See "Programming Techniques
and Restrictions" in Part 1 for a list of PLjI features that cannot be
used.
Storage Defined During Initialization
During CICS/VS initialization, the common system area (CSA) is allocated
as part of the CICS/VS nucleus. For each terminal that is to be used, a
terminal control table terminal entry (TCTTE) must be included in the
terminal control table (TCT). The PL/I programmer must provide symbolic
storage definitions for the CSA and TCTTE (if needed) as follows.
COMMON SYSTEM AREA (CSA)
The statement
%INCLUDE DFHCSADS;
copies the based structures that symbolically define the CSA and the CSA
optional features list. Addressability for both areas is included.
Chapter
2~4.
Storage Definition - PL/I
59
If CICS/VS is generated to support a common work area (CiA), coding
such as the following must be provided immediately following the
%INCLUDE DFHCSADS macro:
DECLARE 1 DFHCSAWK BASED (CSACBAR),
2 CSAFILL CHAR(512),
2 USERLBL1 attributes,
2 USERLBLn attributes;
TERMINAL CONTROL TABLE TERMINAL ENTRY (TCTTE)
The statement
%INCLUDE DFHTCTTE;
copies the based structure that symbolically defines the TCTTE and must
be present in all programs requesting communication with a terminal.
Addressability for the TCTTE is included.
Storage Defined During Execution
During execution of a task, the task control area (TCA), terminal
input/output area (TIOA), and other storage areas required by the task
are allocated by CICS/VS storage management upon request from either the
application program or CICS/VS. Symbolic definitions for these storage
areas must be provided as follows.
TASK CONTROL AREA (TCA)
The statement
%INCLUDE DFHTCADS;
copies the based structure that defines the TCA and establishes
addressabili ty.
The latter part of the based structure consists of a DECLARE
statement that is not terminated by a semicolon. The declaration of the
TCA structure must be completed by supplying an ending (for example, a
semicolon) or, if a transaction work area (TiA) is desired, by supplying
further declaration~ The following is an example of the coding
required:
%INCLUDE DFHTCADS;
2 TW A CH AR (40 ) ;
60
CICS/VS APR!(!L)
TERMINAL INPUTjOUTPUT AREA (TIOA)
The statement
%INCLUDE DFHTIOAi
copies the based structure that defines the CICS/VS system section of
the TIOI and establishes addressability. This statement must be present
in all programs that use terminal input 'records or that write output
records to a terminal~ The declaration of the TIOA structure must be
completed by supplying further declaration of the input/output area,
which could be merely a dummy element. An action that requires a TIOA
can be requested. For example, a DFHSC TYPE=GETMAIN macro instruction
to obtain storage for a TIOI for the application program. The following
is an example of the coding required
%INCLUDE DFHTIOA;
2 NAME CHAR(20),
2 STREET CHAR(20);
*
DFHSC TYPE=GETMAIN,
NUMBYTE=40,
CLASS=TERMINAL
TIOABAR=TCASCSA; /* TCASCSA FIELD OF TCA CONTAINS ADDRESS
OF NEWLY ACQUIRED STORAGE */
*
For additional information about GETMAIN, see uObtain and Initialize
Main Storage (TYPE=GETMAIN)" in Chapter 5.5.
FILE INPUT/OUTPUT AREA (FIOA)
The statement
%INCLUDB DFHFIOA:
copies the based structure that defines the CICS/VS system section of
the FIOA and must be present in all programs requesting a read of an
unblocked record without updating or segmenting, or a read of blocked
records without deblocking. If desired, the user can identify that the
area returned in response to a file request is an FIOA, rather than an
FWA or VSWA, by testing FIOAIND for a bit value of 01. The declaration
of the FIOA must be completed, and addressability must be established
for the FIOA using the statement
FIOABAR=TCAFCAA;
following the DFHFC macro instruction. If data is retrieved using the
Indexed Sequential Access Method (ISAK) under CICS/OS/VS, a 16-byte
filler must be defined prior to the user1s data definition. The
following is an example of the coding required; it includes the optional
coding for FIOA identification:
Chapter 2.4.
Storage Definition - PL/I
61
%INCLUDE DFHFIOA;
2 PILL CHAR (16) ,
2 NAME CHAR(20),
2 ADDR CHAR (20) ;
/*OS/VS ISAM FILLER*/
FIOABAR=TCAFCAA;
IF FIOAIND=101 I B THEN GO TO GOTFIOAi
FIL E WORK AREA (FW A)
The statement
%INCLUDE DFHFWADS;
copies the based structure that defines the CICS/VS system section of
the FWA. This statement should precede a user-declared file record area
when reading or updating an existing blocked or segmented record, when
adding a new record to a data set, or when retrieving records using the
browse technique. If desired, the usp.r can identify that the area
returned in response to a file request is an FWA, rather than an FIOA or
VSWA, by testing FWAIND for a bit value of 11. The declaration of the
FiA must be completed, and addressability must be established for the
FWA using the statement
FWACBAR=TCAFCAA;
following a DFHFC macro instruction. The following is an example of the
coding required; it includes the optional test for FWA identification:
%INCLUDE DFHFWADS;
2 NAME CHAR (20),
2 ADDR CHAR (20);
FWACBAR=TCAFCAA;
IF FiAIND='llIB THEN GO TO GOTFWA;
VSAM WORK AREA (VSiA)
The statement
%INCLUDE DFHVSWA;
copies the based structure that defines the CICS/VS system section of
the VSAM work area and must be present in all programs using locate mode
I/O ~
(See "Direct Retrieval (VSAM Locate Mode) II in Chapter 3.2.) If
desired, the user can identify that the area returned in response to a
file request is a VSWA, rather than an FIOA or PWA, by testing VSWAID
for a bit value of 00000000. Addressability must be established for the
VSWA using the statement
62
CICS/VS APftM(ML)
VSWABAR=TCAFCAAi
following the DFHFC macro instruction using locate mode I/O which causes
CICS/VS to acquire the VSWA.
To identify the area returned as a VSWA, the following instruction
can be used:
IF VSWAID='O'B THEN GO TO GOTVSWA;
TRANSIENT DATA INPUT AREA (TDIA)
The statement
%INCLUDE DPHTDIA;
copies the based structure that defines the CICS/VS system section of
the intrapartition TDIA and must be present in all programs requiring a
message area for transient data obtained by issuing a DPHTD TYPE=GBT
macro instruction that references an intr,apartition destination.
(See
"Acquire Queued Data (TYPE=GET) It in Chapter 5.6.) The declaration of the
TDIA must be completed, and addressability must be established for the
TDIA using the statement
TDIABAR=TCATDAA;
following a DPHTD macro instruction.
coding required:
%1 NCLUDE (OFHTDIA)
2 MSG CHAR(40);
The following is an example of the
i
TDIABAR=TCATDAA;
TRANSIENT OATA OUTPUT AREA (TDOA)
The statement
%INCLUDE DPHTDOA;
copies the based structure that defines the CICS/VS system section of
the intrapartition TOOA and should be present in all programs issuing a
DFHTC TYPE=PUT macro instruction to provide transient data as output.
(See "Dispose of Data (TYPE=PUT) It in Chapter 5.6.). The declaration of
the TDOA must be completed, and addressability must be established for
the TOOA using the statement
TOOABAR=TCASCSA;
following a DFHSC macro instruction.
coding required:
Chapter 2.4.
The following is an example of the
Storage Definition - PL/I
63
%INCLUDE DPHTDOA;
2 TI!E CHAR (2) ,
2 DATA CHAR (3) ,
2 INTER! CHAR (4) ,
2 OUTTER! CHAR ~):
•
DPHSC TYPE=GET!AIN,
NU!BYTE=XX,
CLASS=USER
TDOABAR=TCASCSA;
*
*
TE!PORARY STORAGE INPUT/OUTPUT ARBA (TSIOA)
The statement
%INCLUDE DPHTSIOA:
copies the based structure that defines the CICS/VS system section of
the TSIOA and must be present in all programs using temporary storage.
The declaration for the TSIOA must be completed. If the request is a'
GET or GETQ from temporary storage and the TSDADDR operand is not
specified, addressability must be established for the TSIOA using coding
such as:
DCL TSIOABAA FIXED BIN (31) BASED(TSIOABAB):
TSIOABAR=TCATSDA;
TSIOABAB=ADDR (TSIOABAR) ;
TSIOABAA=TSIOABAA - 8:
The subtraction of eight ensures that TSIOABAA points to the storage
accounting field (that is, to the beginning) of the storage area
acquired by CICS/VS. The statement
TSIOABAR=TCASCSA;
must be coded if the I/O area has been acquired during execution. In
the case of a PUT or PUTQ, the symbolic address of the data is located
at TSIOAVRL.
STORAGE ACCOUNTING AREA (SAA)
The statement
%INCLUDE DFHSAADS;
copies the based structure that defines the SAA and must be present in
all programs requesting storage through use of the DPHSC
TYPE=GETMAIN,CLASS=USER macro instruction. This statement must precede
the definition of user storage. The declaration for the SAA must be
completed, and addressability must be established for the SAA using the
statement:
64
CICS/VS APR! (!L)
SAACBAR=TCASCSA;
The following is an example of the coding required:
%INCLUDE DPHSAADS;
2 MSG CHAR (40) ;
DPHSC TYPE=GETMAIN,
NUM BYTE=60,
CLASS=USER
SAACBAR=TCASCSA;
*
*
JOURNAL CONTROL AREA (JCA)
The statement
%INCLUDE DPHJCADS;
copies the based structure that defines the CICS/VS system section of
the journal control area (JCA) and must be present in all programs
reguesting journal services ~
(See "Journal Control", Chapter 1.5.)
A JCA is acquired dynamically by means of a DPHJC TYPE=GETJCA macro
Addressability to the JCA is provided automatically
through the macro expansion, which loads the address of the area into
JCABAR.
instruction~
Chapter 2.4.
storage Definition - PL/I
65
Example of CICS/VS PL/I Application Program
Figure 2~q-1 is a PL/I program written to run under CICS/VS. The
program asks a question of the terminal operator, receives a reply,
acquires storage, and sends the operator's message back to the terminal.
In effect, an echo test is performed. (The line numbers are not part of
the program.)
01
02
03
Oq
05
06
07
08
09
10
11
12
13
1q
15
16
17
18
19
20
21
22
23
PL1PROG: PROCEDURB OPTIONS (!AIN,REBNTRANT);
%INCLUDE DFHCSADS;
%INCLUDE DFHTCADS;
2 SAVE LENGTH BINARY FIXBD (15),
2 SlVE:!SG CHlR (36);
%INCLUDE (DFHTCTTB);
IINCLUDB (DFHTIOl);
2 TIOA!SG CHAR (36);
TIOA!SG='BNTBR !BSSAGB TO BB BCHOBD';
TIOATDL=26;
DFHTC TIPE=(WRITB,READ,WAIT)
TIOABlR=TCTTEDA;
SAVB_LBNGTH=TIOATDL;
SlVE_!SG=TI01!SGi
DFHSC TIPE=GBT!AIN,
NU! BIT E= 36 ,
CL1SS=TER!INAL
TIOABAR=TCASCSAi
TCTTEDA=TIOABAR;
TIOA!SG=SAVB_!SG;
TIOATDL=SAVB_LBNGTH;
DFHTC TIPE=WRITE
END;
Figure 2.q-1.
*
*
Example of CICS/VS PL/I Application Program
A discussion of the significance of each of the lines of Figure 2.q-1
follows.
Line Number
01
02
03
Oij-05
06
07
08
09
10
11
12
13-1ij
15-17
18
19
20-21
22
23
Description
Required for PL/I. REENTRANT option specified to meet
requirement of CICS/VS that code be guasi-reenterable.
Copies symbolic storage definitions for CSA and CSA
optional features list and establishes addressability.
Copies symbolic storage definition for TCA and
establishes addressability.
Defines the TWA and terminates the DECLARE statement.
SAVE_"SG and SAVE_LENGTH are used to preserve the
operator's reply.
Copies symbolic storage definition for TCTTE and
TCTTE and establishes addressability.
Copies symbolic storage definition for TIOA and
establishes addressability.
Describes I/O area for terminal message and terminates
the DECLARE statement.
Places message to be sent to operator in the TIOA.
Places the message length in the terminal data length
field of the TIOA.
CICS/VS macro instruction that writes the message to the
terminal, waits for, and reads, the operator's reply.
Reestablishes addressability for the TIOA using address
in the TCTTE.
saves the operator's message and its length in the TCA.
CICS/VS macro instruction that requests 36 bytes of
terminal storage (terminal storage is chained to the TCT).
Establishes addressability for the new TIOA (address of
the newly acquired storage is in TCASCSA).
Places address of new TIOA in terminal control table.
Moves message and length of message to output area (TIOA).
CICS/VS macro instruction that sends operator's message
back to the terminal.
PL/I statement that marks the end of the procedure.
Chapter 2.ij.
Storage Definition - PL/I
67
Part 3. Data Base Operations
69
Chapter 3.1. Introduction to Data Base Operations
The following two chapters in this part are concerned with the control
of files within a user data base. Two main methods are described: the
direct handling of records by the file control macro instruction; and
the indirect handling by the DL/I interface.
File Control Macro Instruction
Chapter 3.2 describes how an application program handles records in a
user data base by means of the file control program. Records in the
data base are operated on by the file control macro instruction (DFHFC),
according to the various TYPE operands; for example, records can be
retrieved by the DFHFC TYPE=GET macro instruction.
The file control program can be used only with direct-access data
sets. sequential data sets are handled by the transient data program
and the DFHTD macro instruction, as descrihed in Chapter 5.6.
An application program can also browse a data set in a user data base
by means of the file control macro instruction. Browsing is defined as
the retrieval of records in a direct-access data set, starting and
ending at specified records, in ascending or descending sequence.
DL/I Services
Chapter 3.3 describes the macro instructions and calls available to a
CICS/VS application program that enable that program to use a DL/I data
base.
The method of invoking DL/I differs for the two operating systems
used with CICS/VS.. For CICS/OS/VS, the DL/I interface is invoked by
either a DL/I CALL statement or by a DFHFC macro instruction. For
CICS/DOS/VS, however, the DL/I interface is invoked only by a DL/I CALL
statement.
DL/I is a general-purpose data base control system that executes in a
virtual storage environment. When used online, it simplifies the task
of creating and maintaining large data bases that are to be accessed by
various application programs. For more information about DL/I, refer to
the DL/I publications listed in the bibliography and to the CICSL!§
system/Application Design Guide.
Chapter 3.1.
Introduction to Data Base Operations
71
Chapter 3.2. File Control (DFHFC Macro Instruction)
The file control program processes fixed- or variable-length, blocked or
unblocked, undefined, or segmented records of a data set that is stored
in a direct-access storage device.
File control uses standard access methods of the host operating
system, namely:
•
Direct Access Method (DAM)
•
Indexed Sequential Access Method (IS AM)
•
virtual storage Access Method (VSAM)
Application programs can access DAM data sets on a logical record
level, deblocking services being provided by file control. If an ISAM
data set is converted to a VSAM data set organization, using VSAM data
set conversion utilities, no alteration to application programs that
access the data set is necessary, but the file control table (FCT) must
be changed. Data sets on fixed block architecture (FBA) devices can be
accessed by VSAM only.
Through the file control macro instruction (DFHFC), an application
program can perform file inquiry, that is, read a record from a data
set; update a record in a data set; or add a record to a data set~ In
the last case the application program must obtain sufficient main
storage for the record by means of the DFHFC TYPE=GETAREA macro
instruction. The application program can also release the main storage
that has been acquired. For VSAM key-sequenced or relative-record data
sets only, the DFHFC macro can be used to delete records, singly or in
groups~
General file-handling capabilities available to application programs
include indirect access to data sets, handling of IIduplicates ll data
sets, and use of segmented records. These capabilities are explained
later in this chapter.
All buffers and work areas needed for data set operations are
acquired by file control in accordance with the data set descriptions
supplied in the FCT by the system programmer. All data sets and all
segment sets referred to in DFHFC macro instructions must have been
defined in the FCT. The application programmer should work with the
system programmer in setting up these data set descriptions. However,
the application program need deal only with logical records; it is not
directly involved with other characteristics of the data set.
For a DAM or ISAM data set, all data is read into or written from one
of two main storage areas: (1) a file input/output area (FIOA) or (2) a
file work area (FiA). An FIOA is required to handle records that are
read-only, unsegmented, and unblocked~ An FWA is required to handle
records that are segmented, blocked, to be added, or to be updated. In
addition, an FWA is always used in a browse operation.
For a VSAM data set, all data is read into or written from an FWA
with two exceptions: a locate mode read-only request for an unsegmented
record, and when operating in ISAM compatibility mode.
(ISAM
compatibility mode is indicated by the system programmer specifying
RECFORM=(UNBLOCKED) in the file control table entry for tha data set.)
In the first case, the address of the retrieved record, as it is
positioned in the VSAM buffer, is made available to the application
Chapter 3.2.
File Control (DFHFC Macro Instruction)
73
program at VSWAREA within the VSWA. The record remains in the VSAM
buffer, and must not be modified. In the second case, the retrieved
record is moved to an FIOA for a read-only request for an unsegmented,
unblocked record. A symbolic storage definition must be provided for
this area (for example, an assembler-language DSECT) and addressability
must be established to it. When operating in ISAM compatibility mode, a
16-byte filler must be defined (for OSjVS only) prior to the user's data
(as in normal IS~M mode).
CICS/VS permits the sharing of VSAM resources by means of the DFHFCT
TYPE=SHRCTL system macro instruction as explained in the CIC2L!S~~t~
Programmer's Reference Manual. When a task requires resources in
several VSAM data sets at the same time and these data sets are sharing
resources, the possibility of a lockout increases.
New VSAM data sets, and existing ones that are to be reused, must be
loaded with at least one record before a CICS/VS file control macro can
be used for normal addition and update. This may be done either online
by a CICS/VS application program or offline by a batch program. In the
case of a CICS/VS program, certain restrictions must be observed; these
are explained in the CICStVS System Programmer's Reference Manual.
If an error occurs while accessing a VSAM data set, a DFHFC
TYPE=RELEASE macro must be issued after the error has occurred.
to issue a TYPE=RELEASE may result in a permanent wait.
Failure
The user can determine which area (FIOA, FWA, or VSWA) is returned in
response to a file request. Refer to Chapter 2.2, 2.3, or 2.4
(depending on the programming language being used) for details.
File control executes at the priority of the requesting program,
under control of the TCA of the requesting program, saving and restoring
registers from this TCA~ The CICS/VS response to a request for file
serv ices can be checked as explained under "Test Response to a Request
for File Services," later in this chapter. Control can be routed to any
of various user-written exception-handling routines based on the outcome
of the file operation.
Parameter values must be specified, when using the file control macro
instruction, in either of two ways:
•
By including the parameters in operands of the DFHFC macro
instruction by which file services are requested, or
•
By coding instructions that place the parameter values in fields of
the TCA prior to issuing the DFHFC macro instruction.
The second of these approaches is provided to allow the application
program to specify parameters which can only be determined during
execution, for example, input messages from a-terminal.
Browsing
The application program can browse a data set. This browsing is
comparable to a visual, sequential search of a file. The file control
macro instruction is used to specify a starting point for the browse,
request each succeeding, or preceding record, reset the starting point
for the browse (if desired), and terminate the browse.
The browse operations are requested by the appropriate TYPE operands
of the DFHFC macro. The TYPE operands are SETL, GETNEXT, GETPREV,
RESETL, and ESETL. The capabilities associated with each are summarized
74
CICS/VS APRM(ML)
below. Keyword operands to request checking of a CICS/VS response can
be specified with these macro instr~ctions as with other DPHPC macro
instructions (see "Test Response to a Request for Pile Services," later
in this chapter.) Specific operands for each macro instruction are
discussed in detail at the end of the chapter.
When accessing a VSAM data set, the browse facility can be used to
perform random skip-sequential processing in a forward direction only.
The following steps are required:
1.
Group several random requests into ascending key sequence.
2.
Issue a DPHPC TYPE=SETL macro instruction which finds the first
required record. To achieve this, the record identification field
pointed to by the RDIDADR operand should be initialized to the key
of the required record.
3.
Prior to each DFHFC TYPE=GETNEXT macro instruction, place the key
of the next required record into the record identification field.
This procedure allows quick random access to a VSAM data set by
reducing index search time. When the record having the highest key has
been retrieved, an ESETL or RESETL should be issued to terminate or
reset the operation.
A browsing operation should always be terminated by issuing an ESETL
macro, but will also be terminated by a normal or abnormal end of task.
Segmented Records
An optional feature of CICS/VS file management allows the user to create
and define a data set containing segmented records. A segmented record
is one in which the components of the record have been identified
symbolically and then grouped according to some logical relationship
such as function or frequency of use.
The identifiable groups are called segments. A segment is one or
more adjacent fields within a record. Some segments appear in all
records (for example, segments containing identification or major record
control fields), while other segments apply to, and appear in, only
certain records. If it is planned to use segmented records in a
program, the structure and individual segments of the data set must have
been defined in the file control table by the system programmer. The
maximum number of segments allowed is 99.
The following general rules apply to the use of segmented records:
1.
Segmented records can be used with VSAM, ISAM, or DAM data sets.
2.
Segmented records can be used with any record format (that is,
fixed, fixed blocked, variable, undefined) but are primarily
advantageous when processing variable-length records.
3.
A data set that contains segmented records cannot be an index data
set in an indirect accessing hierarchy. The two CICS/VS features
are mutually exclusive for anyone data set. However, the primary
data set in an indirect accessing hierarchy may contain segmented
records if it is not defined also as an index data set.
(See
"Indirect Accessing" later in this chapter.)
Chapter 3.2.
File Control (DPHPC !acro Instruction)
75
4.
Every segment that may appear in a record, whether or not it
actually exists in a particular record, must be defined in the file
control table.
5.
The user must create and maintain the control information that
governs the segments in a record.
For further information on segmented records see the CICS/VS
System/Application Design Guide.
Alternate Indexing
Alternate indexing, an optional data base feature in CICS/VS under VSAM,
allows a data set to have more than one index. The second and
subsequent indexes are called alternate indexes and these enable a data
set to be accessed by one or more alternate paths. These alternate
paths can be specified by multiple keys.
Also, a data set with the alternate index feature can have two or
more records with the same alternate key~ To retrieve the first record
with the same key the DFHFC TYPE=GET macro with the DUPKEY operand is
sufficient. However, to continue retrieving the remaining records with
the same key, a browse operation must be initiated. The DUPKEY operand
also must be specified on the appropriate macro. The records will be
retrieved in the order in which they were added to the data set, the
duplicate key condition being raised for each record except the last.
When changing to the browse operation, the first record will be
retrieved twice, once by the TYPE=GET and once by the browse.
Defining the alternate indexes as part of an update group will
elimate the possibility of one or more indexes becoming invalid whenever
the data set is updated.
Indirect Accessing
Indirect accessing, an optional data set feature in CICS/VS, provides
for the use of cross-index data sets to access another data set. The
data set that is accessed by an index data set is known as the primary
(or target) data set. The user can include the search argument for an
index data set in the identification of the primary data set. CICS/VS,
using the user-defined index structure, carries out the search,
involving as many levels (index data sets) as defined by the user, and
ultimately retrieves the primary data set.
The following general rules apply to indirect accessing:
1.
A primary data set can have any number of index data sets. This is
useful when many cross references to a master record exist.
2.
Any data set can be both an index and a primary data set. The
logical record content of any data base data set is user~defined
and constructed, and therefore may contain certain master record
information as well as a search argument for another data set.
3~
There is no logical limit to the number of index levels (data sets)
that the user may define in an index hierarchy. For example, data
set A is an index to data set B, which is an index to data set C,
and so on.
76
CICS/VS APR! (ML)
4.
An index hierarchy can be any combination of YSAM, ISAM, and DAM
data sets.
5.
An index data set cannot contain segmented records~ The two
CICS/YS features are mutually exclusive for anyone data set.
However, a primary data set can have segmented records if it is not
defined also as an index data set.
6.
An index data set cannot reference more than one primary data set
unless the index data set is multiply defined in the file control
table.
7.
If the index data set is a BDAM data set, it cannot be defined as
blocked. However, the primary data set can be defined as blocked
BDAM.
Figure 3.2-1 shows a simple two-level index hierarchy for indirect
accessing. The search begins with the index data set CATLOG#. The
primary data set being accessed (and from which data is to be returned
to the application program) is PARTNO. The search argument to be used
in accessing the index data set (CATLOG#) is CN222. The contents of the
record located by the search of the index data set (CATLOG#) contains
the search argument for the next data set (12345 for search of PARTNO).
The primary data set (PARTNO) is searched and the data record returned
to the requesting program.
TRANSACTION
PROCESSING
PROGRAM
CATLOG~
DFHFC TYPE=GET,
INDEX=CATLOG#,
DATASET=PARTNO,
RDIDADR=~
PARTNO
CN222
FIOA or FWA
Figure 3.2-1.
Indirect Accessing (Two-Level Index)
An installation must create and maintain all data sets in its data
base, and define all data sets (both index and primary) in the file
control table. Each data set, whether index and/or primary, is first
described as a primary data set. That is, its basic physical
characte~istics (BLKSIZE, LRECL, KEYLEN, and so on) are defined so that
CICS/VS file management can access it. If the data set is to be used as
an index data set, the following information must also be specified:
1.
The primary data set for which this data set is an index.
2.
The location of the search argument, within the logical record of
this data set, to be used for accessing the primary data set (or
the next index data set) •
If the user creates and defines an index hierarchy for indirect
accessing, CICS/VS file management services any request requiring use of
Chapter 3.2.
File Control (DFHFC Macro Instruction)
77
that hierarchy, provided the requesting application program adheres to
the following general rules and considerations:
1.
The symbolic name of the first index data set to be searched in the
retrieval process must be specified in the INDEX operand of the
DFBFC macro instruction. This data set can be any index data set
in a hierarchy of indexes, not necessarily the highest level index
data set.
2.
The symbolic name of the primary data set from which data is to be
ultimately retrieved and returned to the requesting program must be
specified through the DATASET operand of the DFHFC macro
instruction. Any number of intervening data sets can be used in
the search; however, the user specifies only the first and the last
data set. The user can limit a search to only a portion of an
index hierarchy; that is, it is not necessary to search an entire
index hierarchy, because the user can specify that the search begin
at other than the highest-level index. Indexing levels cannot be
omitted from within the hierarchical chain.
3.
The search argument to be used by CICS/VS file management to access
the first referenced data set must be specified through the RDIDADR
operand of the DFHFC macro instruction. This operand points to a
record identification field containing a VSA~ key or relative byte
address, an ISAM key, or DA~ block reference information. If
multiple levels of index data sets are involved, CICS/VSfile
management acguires a search argument for the next data set from
the logical record of each successive data set.
When stepping through a series of index data sets, CICS/VS file
management uses the record identification field (specified in the
RDIDADR operand) to store the search argument for each successive data
set to be searched. This field must be as large as the largest search
argument that is likely to be used in any given retrieval operation.
Figure 3.2-2 is an example of the above consideration in a threelevel index hierarchy for indirect accessing. The search argument
provided by the processing program is used to access the first index
data set (CATLOGt) that provides the search argument for a second index
data set (PARTNO) that provides the search argument for the primary data
set {VENDOR) from which the data record is retrieved and returned to the
application program. Since the search argument retrieved from the
second index data set (PARTNO) is eight bytes in length (V0000996), the
record identification field (RDIDADR) must be at least eight bytes in
length, even though it initially contains only the five-byte search
argument (CN222) for the first index data set.
78
CICS/VS APRM(ftL)
TRANSACTION PROCESSING
PROGRAM
CATLOG#
DFHFC TYPE=GET,
INDEX=CATLOG#,
DATASET=VENDOR,
PARTNO
J
RDIDA
CN222
FIOA or FWA
Figure 3.2-2.
Indirect Accessing (Three-Level Index)
Duplicate Records
An optional feature of the indirect accessing approach to data base
retrieval is the capability to indicate that a search argument in an
index data set, which normally refers to the primary data set, instead
refers to a "duplicates" data set. The need for or use of duplicates
data sets may best be described as follows.
Assume that the application program requires access to an index data
set organized by street address to obtain the name of the occupant at
that address. The occupant's name is then used to access a primary data
set organized by name.
For single occupancy, no problem exists. However, if multiple
occupancy is possible, the index data set cannot directly equate a
street address to a primary data set record. In this case, the search
argument field in the index record must indicate that mul tiple occupants
(duplicates) exist and that the search argument refers to a duplicates
data set rather than the primary data set.
CICS/VS file management retrieves the referenced record from the
duplicates data set and returns it to the application program with a
response code indicating a duplicate record. The duplicate record may
contain further information, which the application program can use to
more accurately retrieve the appropriate record from the primary data
set.
If an index data set is to indicate that there can be duplicate keys
for entries in the primary data set to which it refers, this information
must also be noted in the file control table entry which describes the
index data set. The index data set record must contain a unique onebyte duplicates indicator (user-defined) in the first byte of the search
argument field. Care must be taken to ensure that this indicator is a
unique code; it cannot be the same as the first byte of a normal search
argument for the primary data set.
The rest of the search argument field contains the search argument
used by CICS/VS file management to retrieve a record from the duplicates
data set~ This record may contain user-defined and user~constructed
information that the application program can use to select the
appropriate primary data set record. Figure 3.2-3 is an example of a
search argument field in an index record that reflects duplicates:
Chapter 3.2.
File Control (DFHFC Macro Instruction)
79
SEARCH ARGUMENT FOR
DUPLICATES RECORD
-------------~--------------OR
SEARCH ARGUMENT FOR
NEXT LEVEL OF INDEX
3~2-3.
Figure
Indirect Accessing (Search Argument Field)
The search argument for the duplicates data set must meet the same
search argument format requirements as a normal cross-index data set.
The length of the search argument used to access a duplicates data set
is one byte smaller than a normal search argument because of the
duplicates indicator.
Figure 3.2-4 is an example of an index hierarchy that includes a
duplicates data set. The application program begins the retrieval by
accessing the index data set (PARTNAM) and ultimately accesses the
primary data set (PARTNO). The search argument (GISMO) provided by the
application program is a valid one for the index data set (PARTNAM), but
it provides a record containing a duplicates flag.
When the duplicates
indicator is detected, CICS/VS file management uses the new search
argument (from the PARTNAM data set) to access the duplicates data set
(DUPLNAM), returning the duplicates record to the application program.
In this example, the part name (GISMO) is not unique since there are
several types of GISMOs in the part number (PARTNO) data set. The
requesting program must provide qualifying data that indicates which
GISMO is desired.
PARTNO
PARTNAM
TRANSACTION PROCESSING
PROGRAM
DFHFC TYPE=GET,
INDEX=PARTNAM,
DATASET=PARTNO,
RDIDA~
GISMO
DUPLNAM
FIOA or FWA
RECORD RETRIEVED FROM DUPLNAM
I
ILARGE
1-------1-------- ------ ---------
IPARTNAMIDESC
Figure 3.2-4.
80
1 9123
IGISMO
1
IPARTNO
MED
DESC
Indirect Accessing
CICS/VS APRM(ML)
9872
PARTNO
SMALL
DESC
(Duplicates Data Set)
9944
PARTNO
Pigure 3.2-5 shows the message the application program might
formulate to be routed to the inquiring terminal asking the terminal
operator to make a choice.
PLEASE SELECT SPECIPIC PART NUMBER
PART NAME
GISMO
Pigure 3.2-5.
DESCRIP
PART NUMBER
LARGE
9123
MED
9872
SMALL
9944
Indirect Accessing (Message to Terminal)
Once the terminal operator has made a selection, the program can make
a direct retrieval from the primary (PARTNO) data set.
If the index record in the example in Pigure 3.2-4 had not contained
a duplicates indicator, CICS/VS file management would have used the
search argument to access the primary data set (PARTNO) and retrieve the
requested data.
Record Identification Field
The record identification field is used by the application program to
communicate to CICS/VS file control the identity, in the form of a key
or address, of a specific record, or the starting point of a set of
records, required in input/output operations. This field is identified
by the RDIDADR operand of the DPHPC macro instruction.
If multiple browse operations are performed concurrently by a single
application program, a unique record identification field must exist for
each operation. The application program must provide the storage area
for the record identification field. Generally, this storage can be
allocated within the transaction work area ~WA) of the task contro1
area (TCA), or some area acquired dynamically by the application
program. Because CICS/VS application programs must be quasireenterable, it is not advisable to set up the record identification
field within the application program.
Por an ISAM data set, the record identification field simply contains
the key of the logical record. Por CICS/OS/VS systems, the contents of
the record identification field may have been changed following the
addition of a new record when using ISAM; this point is worth
considering in CICS/DOS/VS systems also, to avoid subsequent DOS to OS
conversion difficulties.
Por a VSAM data set, the record identification field contains either
the logical record key or the relative byte address of the desired
record. If the generic key option is used, the first byte of the field
must contain the key length, in binary, and the remainder of the field
must contain the generic key.
A partial key may be used as a search argument in a browse operation
referring to either an ISAM or a VSAM data set. The IS!M partial key is
Chapter 3.2.
pile Control (DPHPC Macro Instruction)
81
an implied generic key, recognized as such because of padding with
binary zeros or blanks in insignificant positions of the key. In
contrast, a VSA~ generic key is defined to be a generic key, with its
length explicitly specified in the first byte of the record
identification field. The ISAM implied generic key applies only to
browse operations. The VSA~-defined generic key can be specified in
many DFHFC macro instructions.
For a DAM data set, the record identification field structure is more
complex. The application program must supply the block reference
information, the physical key (if keyed data sets are being used), and
the deblocking argument (if blocked data sets are being used). The
record identification field is really a concatenation of three
subfields, as follows:
1.
Block reference
The block reference for the data set in the DAM block is specified
by the RELTYPE operand of the DFHFCT TYPE=DATASET system macro and
may be one of the following:
a.
Relative block (CICS/OS/VS only) three-byte binary
(RELTYPE=BLK)
b.
Relative track and record - two-byte TT, one-byte R
(RELTYPE=HEX)
c.
Relative track and record (zoned decimal format) siX-byte
TTTTTT, two-byte RR (RELTYPE=DEC)
d.
Actual address - eight-byte MBBCCHHR (RELTYPE omitted)
Figure 3.2-6 shows examples of the four ways of specifying the block
reference information for a DAM data set.
Byte I 0
1
2
3
4
5
6
1
8
RELBLK#
Relative block (OS/VS only)
(three byte binary)
T
T
R
Relative track and record
(two byte hex, one byte hex)
T
T
T
T
T
T
R
R I
I
M
B
B
C
C
H
H
R I
Relative track and record
(zoned decimal)
-l
Figure 3.2-6.
2.
Actual address (eight bytes)
Record Identification Pield (Block Reference)
Physical key
The physical key is required only if the data set being accessed is
written with recorded keys. This key must be the same length as
specified in the BLKKEYL operand for the file control table entry
which defines the data set. It must immediately follow the block
reference information, which can be any of the above.
82
CICS/VS APRM (ML)
Figure 3.2-7 shows examples of the addition of the physical key for a
DAM data set.
By tel
--I
I
I
I
I
I
I
,I
Figure 3.2-7.
3.
0
1
2
3
5
4
RELBLKt ,I KEy •••
6
7
8
(CICS/OS/VS only)
T
T
R IKEY •••
T
T
T
T
T
R
R
KEY •••
M
B
B
C
C H H
R
KEY •••
T
Record Identification Field (Physical Key)
Deblocking argument
The deblocking argument is required only if the data set contains
blocked records and specific logical records are to be retrieved
from within a block. It is not mandatory that every physical
record of a blocked 'data set be deblocked. If the application
programmer does not specify a deblocking argument, an entire ~lock
is read into an FIOA. The deblocking argument may be either a key
or a relative record nu~er. The user's choice is specified in the
RETMBTH (retrieval method) operand of the DFHFC macro instruction.
If present, the deblocking argument must immediately follow the
physical key (if present) or the block reference (if the physical
key is not present).
If the deblocking argument is a key, it must be the same length as
specified in the KEYLEN operand of the file control table entry
which describes the data set. The key used for deblocking need not
be the same size as the physical record key ~LKKEYL). If the
deblocking argument is a relative record number, it is represented
by a one-byte binary number, with a value of zero representing the
first logical record of a block.
Figure 3~2-8 shows examples of the addition of a deblocking argument
to the record identification field for a DAM data set.
Chapter 3.2.
File Control (DFHFC Macro Instruction)
83
key = 6 bytes, deblocking key = 3 bytes)
~hysical
Byte
o
1
2
3
4
5
6
1
8
9 10 11 12 13 14 15
RELBLK
RN
RELBLK
KEY I (CICS/OS/VS only)
I (CICS/OS/VS only)
KEY
T
T
R
K
B
B C
C
KEY
H H R IRNI
T
T
T
T
T
R
R
Search by relative block;
deblock by key
Search by relative track
and record and key;
deblock by key
Search by actual address;
deblock by relative record
'-I
T
Search by relative block;
deblock by relative record
KEY
KEY
Search by zoned decimal
relative track and record
and key; deblock by key
T
Figure 3.2-8.
T
R
I
KEY
Search by relative track and
record; deblock by key
Record Identification Field (Deblocking Argument)
DAM Data Sets
Records in a nonkeyed DAM data set may be updated using either of two
methods. One method is to issue a DFHFC TYPE=GET,TYPOPER=UPDATE to read
the record, change the data in the FWA, and issue a DFBFC TYPE=PUT to
physically update the record. This is the normal way that records are
updated and should be used when portions of the record are to be changed
and the actual contents of the record are unknown.
An alternative method may be used when the contents of the record to
be updated are known, or when the entire record is to be changed,
regardless of its contents. A DFHFC TYPE=GETAREA macro instruction is
used to acquire an FWA, the record is built in the FWA, and a DFHFC
TYPE=PUT,TYPOPER=UPDATE is issued to write the data at the location
specified in the record identification field, destroying whatever vas
previously recorded at that location. This approach requires that both
DAM update and DAM add capabilities be generated into the CICS/VS file
control program (see the CIcstVS System pro~ammer's Reference Manual).
Automatic logging must not be specified for files to be updated by this
method.
When adding new records to a DAM data set, the following
considerations and restrictions apply:
84
CICS/VS APRM (ML)
1.
When adding undefined or variable-length records (keyed or
nonkeyed), the application programmer must indicate the track on
which each new record is to be added. If space is available on the
track, the new record is uritten following the last previously
written record, and the record number is placed in the "R" portion
of the record identification field of the record. The track
specification may be in any of the acceptable formats except
relative block. If zoned decimal relative format is used, the
record number is returned as a two-byte zoned decimal number in the
seventh and eighth positions of the record identification field.
In the CICSjDOS/VS system, an attempt to add a variable-length or
undefined record is limited to the single track specified by the
application programmer. If insufficient space is available on that
track, a nno space available" error is returned, and the
application programmer may then try to add the record on another
track. Under these circumstances, the record is returned to the
application program in an FWA, the address of which is at TCAFCAA.
The programmer need only modify the track identification and issue
another DFBFC TYPE=PUT,TYPOPER=NEWREC macro instruction to add the
record on another track.
In the CICSjOS/VS system, the extended search option allows the
record to be added to another track if no space is available on the
specified track. Under these circumstances, the location at which
the record vas added is returned to the application program.
2.
The addition of keyed fixed-length records to DAM data sets
requires that the data set first be formatted with dummy records or
"slots" into vh ich nell records may be added.
(The first byte of a
dum~y record is a key of hexadecimal FFsi in CICS/OS/VS, the first
byte of data contains the record number.) A pre-formatted DAM data
set cannot be added to by a COBOL batch program.
3.
For nonkeyed, fixed-length records, the exact physical block
reference must be given in the record identification field. The
data in the new records is aritten in the exact location specified,
destroying the previous contents of that location.
4.
For keyed, fixed-length record additions, only the track
information is used as a starting location for the search of a
dummy key and record. Hhen a dummy key and record are found, the
new key and record replace it. The exact location at which the new
record is located is returned to the application program in the
block reference sub field of the record identification field.
For example, suppose a user wishes to add a keyed, fixed-length
record to a DAM data set. First, some algorithm determines that
the search is to start at relative track 3. The record
identification field of the new record might appear as follows:
o 3 0
ALPHA
T T R
KEY
When control is returned to the application program, the record
identification field might reflect the fact that the record was
added on relative track 4, record 6.
o
4 6
ALPHA
T T R KEY
Chapter 3.2.
File Control (DFHFC Macro Instruction)
85
5.
When adding records of undefined length, the length of the physical
record must be placed in two-byte binary format at TCAFCORL. When
an undefined record is retrieved, the application program must
determine its length.
6.
When making additions to a BDA! data set containing variable-length
blocked or unblocked records, the application program must include
a record descriptor field (RDF) which contains the length (LL~~) of
the entire block to be written. Also, for each logical record
within that block, an RDF must be included which contains the
length of the logical record. Effectively, this allows the
application to add a block containing multiple logical records as
shown in Figure 3.2-9.
I
1
I
1
FWAIPREFIXI 961 541<
I
I
I
1
•
1\
1
BLOCK
RDF
Figure 3.2-9.
1
I
1
I
50-->1 241<--20-->1 141<-10->
I
I
I
I
I
I
1\
1\
1\
I
LOG
REC
RDF
I
LOG
REC
RDF
I
LOG
REC
RDF
Record Identification Field (Addition of More than
One' Record)
If only a single logical record is to be added, the block RDF is
still required, as shown in Figure 3.2-10.
1
1
1
1
I
FWAIPREFIXI10811041<-------------------100------------------->1
1
1
1
1
I
L
I
1\
1
BLOCK
RDF
Figure 3.2-10.
1\
I
LOG
REC
RDF
Record Identification Field
Record)
~ddition
of Single
When updating records on a DAM dataset, the following restriction
applies:
If the file is blocked, and if two or more records are to be
updated, a DFHFC TYPE=GET macro to retrieve a record must be
followed by a DFHFC TYPE=POT macro to write the updated record (or
a DFHFC TYPE=RELEASE macro if the updated record is not required)
before any further record in the same block is retrieved for
update. Failure to do so will result either in one or more updates
being lost or in a lockout.
86
CICS/VS APR!! (ML)
Direct Retrieval (TYPE=GET)
The format of the DFHFC macro instruction to retrieve single records
directly from a data set is as follows:
DFHFC
TYPE=GET
[ ,DATASET=symbolic name]
[,RDIDADR=symbolic address]
[ ,SEGSET={symbolic nameIYESIALL} ]
[,INDEX={symbolic nameIYES})
[,TYPOPER=UPDATE]
<----------------------DAM
[,RETMETH={RELRECIKEY}]
[,ARGTYP={KEYIRBA}]
<
VSAM
[,SRCHTYP={FKEQIFKGEIGKEQIGKGE}]
<
VSAM
[ , MODE= {MOVE I LOCATE} ]
<
VSAM
[,DUPKEY=symbolic address]
<------VSAM & assembler
[,NORESP=symbolic address]
[,ERROR=symbolic address]
[ ,DSIDER=symbolic address]
[ ,SEGIDER=symbolic address]
[ ,NOTFND=symbolic address]
[,INVREQ=symbolic address]
[ , IOERROR=symbolic address]
[,DUPDS=symbolic address]
[,NOTOPEN=symbolic address]
[,ILLOGIC=symbolic address]
<-------------------VSAM
This macro instruction is used for direct read-only (inquiry) or
update (DFHFC TYPE=GET, TYPOPER=UPDATE) operations. The requested
record is returned in:
•
a file input/output area (FIOA) for read-only operations with
unsegmented, unblocked records from a DAM or ISAM data set or VSAM
data set in move mode
•
a file work area (FWA) for update operations, read-only operations
with segmented or blocked records, or for read-only operations with
a blocked VSAM data set
•
in a VSAM buffer area for locate mode read-only operations on
unsegmented records of a VSAM data set
Before this macro is used, instructions must be provided that define
symbolically the required FIOA, FWA and/or VSWA by:
1.
copying the appropriate storage definitions (DFHFIOA, DFHFWADS,
and/or DFHVSWA) provided oy CICS/VS
2.
providing storage definitions for the user's part of the FIOA, FWA,
and/or the user's record in the VSAM buffer
Hote: Under CICS/OS/VS, if ISAM data is to be read into in an FIOA, a
16-byte filler must be defined following the statement that copies
DFHFIOA and preceding the user's data definition.
CICS/VS performs the following services in response to a DFHFC
TYPE=GET macro instruction:
1.
Acquires the main storage areas required to read a record
Chapter 3.2.
File Control (DFHFC Macro Instruction)
87
2.
Reads the requested record
3.
Makes the requested record available to the application program.
The record required in an input/output operation is identified in a
record identification field. The format of this field, as required for
the various access methods, is described under "Record Identification
Pield", earlier in this chapter.
When a DAM data set is referenced, the record identification field
should contain a block reference. When an ISAM data set is referenced,
the record identification field should contain a key. When a VSAM data
set is referenced, the required record is accessed by either a relative
byte address or a key. A search by key may be for a key equal to the
search key, or for one equal to or greater than the search key, or for
one equal to or less than the search key. A search may also be for a
partial key (the first two bytes, or any number specified by the
programmer), which may serve as a generic key. The generic or partial
key search may, again, be either for an equal key or for an equal or
greater key, or for an equal or less than key, but only the number of
bytes specified will be compared. A protected, key-sequenced VSAM data
set can be updated only by a full key equal search.
In addition, CICS/VS can perform the following services, depending on
the operands included in this macro instruction:
•
Retrieve a record indirectly
•
segment a record for inquiry (read-only) and return the requested
segments in a work area
•
Acquire a file work area when the record is to be updated, or when
records are blocked or segmented
•
Unpack a segmented record into a work area of the same length as
the requested record
The length of an acquired FWA depends on whether or not the record is
to be updated. If the record is to be updated, the PWA acquired will be
sufficient to contain a record of the maximum length specified by the
system programmer in the PCT; otherwise, the PWA will be sufficient to
contain the requested record.
When an unsegmented record of a VSAM data set is retrieved in
response to a read-only request, move mode or locate mode processing can
be specified. In move mode, the record is handled in the same way as
any DAM or ISAM record. In locate mode, the record is made available to
the application program in the VSAM buffer. The application programmer
must have copied the symbolic storage definition for the VSWA (DPHVSWA)
and must also provide a symbolic storage definition for the record that
is retrieved.
After requesting file services, the programmer must establish
addressability for any required PIOA or PWA. The address of the area
involved, provided by CICS/VS at TCAPCAA, must be placed in PIOABAR or
PWACBAR. In locate mode, the address of the VSWA is in TCAPCAA and must
be placed in VSWABAR. The address of the area that holds the requested
record is at VSWAREA within the VSWA and must be moved to the base
locator that has been established for the symbolic storage definition of
the area.
When retrieving variable-length records from a VSAM data set in move
mode, the file control program creates a length field and places it
preceding the record in the PiA. The format of this length field is
LL~, where LL is a two-byte binary length (including the q bytes for
88
CICS/VS APRM(ML)
the length field itself) and ~~ is two bytes of binary zeros. In locate
mode, the length is not included in the record itself but is placed at
VSWALEN in the VSWA.
When a VSAM record is retrieved for update,VSAM maintains exclusive
control of the control interval containing that record. A task should
not attempt to retrieve (for update) a second record from the same
control interval as a record it is already holding for update, otherwise
a permanent wait will occur. The update should first be completed, by a
DFHPC TYPE=PUT macro, or if it cannot be completed, terminated by a
DPHPC TYPE=RELEASE macro.
A DFHFC TYPE=RELEASE macro instruction frees an FIOA or FWA acquired
in response to a request for file services, or a VSWA and VSAM string
established for a VSA! read-only request using locate mode I/O. Any of
these areas that are not freed by the application program are freed by
CICS/VS at task termination.
Direct Retrieval @ead-only)
The following examples show how to retrieve a single record directly
from a master data set, assuming blocked records.
For Assembler language:
COpy
KEYF
DS
FWACBAR EQU
COpy
RECORD DS
COpy TCA SYMBOLIC STRG DEPN
RECORD IDENT PIELD IN TWA
ASSIGN BASE REGISTER FOR PWA
SYMBOLICALLY DEFINE FWA
RECORD LAYOUT FOLLOWS CONTROL
FIELD AND HAS SAME BASE REGISTER
DFHTCADS
CL8
1
DFHPWADS
OCL350
MVC
KEYF,ACCTNO
READREC DFHFC TYPE=GET,
DATASET=MASTERA,
RDIDADR=KEYF
L
FWACBAR,TCAPCAA
Chapter 3.2.
MOVE RECORD IDENT TO KEY FIELD
GET RECORD FROM MASTER DATA SET
*
*
ESTABLISH ADDRESSABILITY FOR FWA
File Control (DFHFC Macro Instruction)
89
For COBOL:
02
FWACBAR PIC S9(8) CO!P.
NOTE DEFINE BASE REGISTER FOR FWA.
01
DFHTCADS COPY DFHTCADS.
02 KEYF PIC X(8).
NOTE COpy SYMBOLIC STRG DEFN FOR TCA.
NOTE DEFINE KEY FIELD IN TWA.
01
DFHFWADS COPY DFHFWADS.
02 RECORD PIC X(350).
NOTE COpy SYMBOLIC STRG DEFN FOR FWA.
NOTE DEFINE RECORD LAYOUT IN FiA.
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
MOVE ACCTNO TO KEYF.
READREC.
DFHFC TYPE=GET,
DATA SET=MAS TERA,
RDIDADR=KEYF
MOVE TCAFCAA TO FWACBAR.
NOTE ESTABLISH TCA ADDRESSABILITY.
NOTE MOVE RECORD IDENT TO KEY.
GET RECORD FROM MASTER DATA SET
*
*
NOTE ESTABLISH FWA ADDRESSABILITY.
For PL/I:
~INCLUDE
DFHTCADS;
KEYF CHAR (8) ;
~INCLUDE DFHFWADS;
02 RECORD CHAR (350) ;
/*COPY SYMBOLIC STRG DEFN FOR TCA*/
/*DEFINE KEY FIELD IN TWA*/
/*COPY SYMBOLIC STRG DEFN FOR FWA*/
/*DEFINE RECORD LAYOUT IN FiA*/
KEYF=ACCTNO;
READREC:
DFHFC TYPE=GET,
DATASET=MASTERA,
RDIDADR=KEYF
FWACBAR=TCAFCAA;
/*ASSIGN RECORD IDENT TO KEY FIELD*/
02
90
CICS/V 5 APRM
(~L)
GET RECORD FROM MASTER DATA SET
*
*
/*ESTABLISH ADDRESSABILITY FOR FWA*/
The following examples show how to retrieve a single record directly
from a VSAM data set using locate mode I/O. If the record is variable
length, the LL~_ field will not be part of the record. The length of
the record can be found in VSiALEN in the VSiA.
For Assembler language:
COPY
DS
KEYF
VSWABAR EQU
RECBAR EQU
COpy
DSECT
RECDS
DFHTCADS
CL8
7
8
DFHVSWA
USIl~G
*,RECBAR
OCL350
RECORD
DS
COpy TCA SYMBOLIC STORAGE DEFN
DEFINE KEY FIELD IN TWA
ASSIGN BASE REGISTER FOR VSiA
ASSIGN BASE REGISTER FOR RECORD
COpy VSiA SYMBOLIC DEFN
DUMMY SECTION FOR RECORD
MAKE RECORD ADDRESSABLE
DEFINE RECORD LAYOUT
lIVC
KEYF,ACCTNO
READREC DFHFC TYPE=GET,
DATASET=MASTVSAM,
RDIDADR=KEYF,
HODE=LOCATE
VSWA BA R, TCAFCAA
L
RECBAR,VSUAREA
L
3, VSWALEN
L
MOVE RECORD ID TO KEY FIELD
GET A RECORD FROM MASTER
VSAM DATA SET USING
LOCATE MODE
*
*
*
ESTABLISH VSWA ADDRESSABILITY
ESTABLISH RECORD ADDRESSABILITY
LOAD RECORD LENGTH INTO WORK REG
For COBOL:
02
VSWABAR PIC S9(8) COMP.
02
RECBAR PIC S9 (8)
NOTE DEFINE BASE REGISTER FOR VSiA.
COMP.
NOTE DEFINE BASE REGISTER FOR RECORD.
01
DFHTCADS COpy DFHTCADS.
02 KEYF PIC X(8).
02 RECLEN PIC S9(8) COMP.
NOTE COpy SYMBOLIC STRG DEFN FOR TCA.
NOTE DEFINE KEY FIELD IN TWA.
NOTE DEFINE RECORD LENGTH WORK AREA.
01
01
DFHVSiA COpy DFHVSWA.
RECDS SYNCHRONIZED.
02 RECORD PIC X (350) •
NOTE COpy SYMBOLIC STRG DEFN FOR VSiA.
NOTE DEFINE SYMBOLIC STRG DEFN FOR RECORD.
NOTE DEFINE RECORD LAYOUT.
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
MOVE ACCTNO TO KEYF.
READREC.
DFHFC TYPE=GET,
DATASET=MASTVSAM,
RDIDADR=KEYF,
MODE=LOCATE
MOVE TCAFCAA TO VSWABAR.
MOVE VSWAREA TO RECBAR.
MOVE VSWALEN TO RECLEN.
Chapter 3.2.
NOTE ESTABLISH TCA ADDRESSABILITY.
NOTE MOVE RECORD ID TO KEY FIELD.
GET A RECORD FROM MASTER
VSAM DATA SET USING
LOCATE MODE
*
*
*
NOTE ESTABLISH VSiA ADDRESSABILITY.
NOTE ESTABLISH RECORD ADDRESSABILITY.
NOTE MOVE RECORD LENGTH TO aORK AREA.
File Control (DFHFC Macro Instruction)
91
For PL/I:
%INCLUDE DFHTCADS;
02 KEYF CHAR(S),
02 RECLEN FIXED BINARY (31) 1
%INCLUDE DFHVSWA;
DCL 01 RECDS BASED (RECBAR),
02 RECORD CHAR(350)1
/*COPY SYMBOLIC STRG DEFN FOR TCA*/
/*DEFINE KEY FIELD IN TWA*/
/*DEFINE RECORD LENGTH WORK AREA*/
/*COPY SYMBOLIC STRG DEFN FOR VSWA*/
/*DEFINE SYMB STRG DEFN FOR RECORD*/
/*DEFINE RECORD LAYOUT*/
KEYF=ACCTN01
READREC:
DFHFC TYPE=GET,
/*MOVE RECORD ID TO KEY FIELD*/
DA~ASET=MASTVASM,
RDIDADR=KEYF,
MODE =LOCATE
VSWABAR=TCAFCAA;
RECBAR=VSWAREA1
RECLEN=VSWALEN;
GET A RECORD FROM MASTER
VSAM DATA SET USING
LOCATE MODE
*
*
*
/*ESTAB ADDRESSABILITY FOR VSWA*/
/*ESTAB ADDRESSABILITY FOR RECORD*/
/*MOVE RECORD LENGTH TO WORK AREA*/
Direct Retrieval (for Update)
The following examples show how to retrieve a single record directly
from a master data set for update.
For Assembler language:
COpy
KEYF
DS
FWACBAR EQU
COPY
RECORD DS
DFHTCADS
CLa
7
DFHFWADS
OCL350
•
.MVC
KEYF,ACCTNO
READREC DFHFC TYPE=GET,
DATASET=MASTERA,
RDIDADR=KE YF ,
TYPOPER=UPDATE
FWACBAR,TCAFCAA
L
92
CICS/VS APRM (ML)
COpy TCA SYMBOLIC STRG DEFN
DEFINE KEY FIELD IN TWA
ASSIGN BASE REGISTER FOR FiA
SYMBOLICALLY DEFINE FWA
RECORD LAYOUT FOLLOWS CONTROL
FIELD AND HAS SAME BASE REGISTER
MOVE RECORD IDENT TO KEY FIELD
GET RECORD FROM MASTER DATA SET
FOR UPDATE
*
*
*
ESTABLISH ADDRESSABILITY FOR FiA
For COBOL:
02
FUACBAR PIC S9(8) COMP.
NOTE DEFINE BASE REGISTER FOR FiA.
01
DFHTCADS COpy DFHTCADS.
02 KEYF PIC X (8).
NOTE COpy SYMBOLIC STRG DEFN FOR TCA.
NOTE DEFINE KEY FIELD IN TWA.
01
DFHFWADS COpy DFHFWADS.
02 RECORD PIC X~50).
NOTE COpy SYMBOLIC STRG DEFN FOR FiA.
NOTE DEFINE RECORD LAYOUT IN FiA.
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
MOVE ACCTNO TO KEYF.
READREC.
DFHFC TYPE=GET,
DATASET=MASTERA,
RDIDADR=KEYF,
TY PO PER=UPDA TE
MOVE TCAFCAA TO FWACBAR.
NOTE ESTABLISH TCA ADDRESSABILITY.
NOTE MOVE RECORD IDENT TO
KEY~
GET RECORD FROM MASTER DATA SET
*
*
*
NOTE ESTABLISH FWA ADDRESSABILITY.
lor Pka:
%INCLUDE DFHTCADS;
02 KEYF CHAR (8) ;
%INCLUDE DFHFWADS;
02 RECORD CHAR(350);
/*COPY SYMBOLIC STRG DEFN FOR TCA*/
/*DEFINE KEY FIELD IN TWA*/
/*COPY SYMBOLIC STRG DEFN FOR FWA*/
/*DEFINE RECORD LAYOUT IN FWA*/
KEYF=ACCTNO;
READREC:
DFHFC TYPE=GET,
DATASET=MASTERA,
RDIDADR=KEYF,
TYPOPER=UPDATE
FWACBAR=TCAFCAA;
/*ASSIGN RECORD IDENT TO KEY FIELD*/
Chapter
3~2.
GET RECORD FROM MASTER DATA SET
*
*
*
/*ESTABLISH ADDRESSABILITY FOR FWA*/
File Control (DFHFC Macro Instruction)
93
Indirect Retrieval (Indirect Access)
The following examples show how to retrieve a single record for update
when its kay is unknown. A cross-index data set containing the master
key is available, making it possible to access the record indirectly.
(See "Indirect Accessing", earlier in this chapter) •
For Assembler
la~~:
COpy
KEYF
DS
FWACBAR EQU
COpy
RECORD DS
DFHTCADS
CL25
1
DFHFWADS
OCL350
MVC
KEYF,INDEXA
READING DFHFC TYPE=GET,
DATASET=MASTERA,
RDIDADR=KEYF,
TYPOPER=UPDATE,
IN DEX =IN DIR ECT
L
FWACBAR,TCAFCAA
COpy TCA SYMBOLIC STRG DEFN
DEFINE KEY FIELD IN TWA
ASSIGN BASE REGISTER FOR FiA
SYMBOLICALLY DEFINE FWA
RECORD LAYOUT FOLLOWS CONTROL
FIELD AND HAS SAME BASE REGISTER
MOVE INDEX IDENT TO KEY FIELD
GET RECORD FROM MASTER DATA SET
BY FIRST ACCESSING A CROSS-INDEX
DATA SET NAMED INDIRECT
*
*
*
*
ESTABLISH ADDRESSABILITY FOR FiA
For COBOL:
02
FWACBAR PIC S9(8) COMP.
NOTE DEFINE BASE REGISTER.
01
DFHTCADS COpy DFHTCADS.
02 KEYF PIC X(25).
NOTE COPY SYMBOLIC STRG DEFN FOR TCA.
NOTE DEFINE KEY FIELD IN TWA.
01
DFHFWADS COpy DFHFWADS.
02 RECORD PIC X(350).
NOTE COpy SYMBOLIC STRG DEFN FOR FiA.
NOTE DEFINE RECORD LAYOUT IN FiA.
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR •
•
MOVE,PARTNAME TO KEYF.
READREC.
DFHFC TYPE=GET,
DATASET=MASTERA,
RDIDADR=KEYF,
TYPOPER=UPDATE,
INDEX=INDEXAB
MOVE TCAFCAA TO FiACBAR.
9 ij
CICS/V S APR! (ML)
NOTE ESTABLISH TCA ADDRESSABILITY.
NOTE MOVE INDEX IDENT TO KEY.
GET RECORD FROM MASTER DATA SET
BY FIRST ACCESSING A CROSS-INDEX
DATA SET NAMED INDEXAB
*
*
*
*
NOTE ESTABLISH FWA ADDRESSABILITY.
For PL/I:
%INCLUDE DFHTCADS;
02 KEYF CHAR(25);
%INCLUDE DFHFWADS;
02 RECORD CHAR (350) ;
/*COPY SYMBOLIC STRG DEFN FOR TCA*I
/*DEFINE KEY FIELD IN TWA*/
/*COPY SYMBOLIC STRG DEFN FOR FWA*/
I*DEFINE RECORD LAYOUT IN FWA*I
KEYF=PARTNAME;
READREC:
DFHFC TYPE=GET,
DATASET =MASTER A,
RDIDADR=KEYF,
TYPOPER=UPDATE,
INDEX=INDEXAB
FWACBAR=TCAFC1A;
I*ASSIGN INDEX IDENT TO KEY FIELD*I
Chapter 3.2.
GET RECORD FROM MASTER DATA SET
BY FIRST ACCESSING A CROSS-INDEX
DATA SET NAMED INDEXAB
*
*
*
*
I*ESTABLISH lDDRESSABILITY FOR FWA*I
File Control (DFHFC Macro Instruction)
95
Direct Update or Addition (TYPE=PUT).
The format of the DFHFC macro instruction to update or add single
records to a data set is as follows:
DFHFC
Note:
TYPE=PUT
[,RDIDADR=symbolic address]
[ ,SEGSET=YES]
[,TYPOPER={NEWRECIUPDATEIDELETE}] (See note)
[,ARGTYP={KEI.IRBA}]
<------------VSAM
[ ,NORESP=symbolic address]
[,ERROR=symbolic address]
[,DUPREC=symbolic address]
(,INVREQ=symbolic address]
[,IOERROR=symbolic address]
[,NOSPACE=symbolic address]
[,NOTOPEN=symbolic address]
[,ILLOGIC=symbolic address]
<------------------VSA!
DELETE can be used only with a VSA! KSDS or RRDS
This macro instruction is used to:
•
update an existing record that has been retrieved through the DFHFC
TYPE=GET,TYPOPER=UPDATE macro instruction
•
add a new record to an existing data set
•
update an existing record in a nonkeyed DAM data set without first
reading the record for update
A DFHFC TYPE=PUT macro instruction must never be issued without first
issuing a DFHFC TYPE=GET,TYPOPER=UPDATE or DFHFC TYPE=GETAREA macro
instruction, because the results of such action are unpredictable.
When a VSAM key-sequenced or relative~record data set is being
processed, a DFHFC TYPE=PUT,TYPOPER=DELETE macro instruction can be used
to delete a record previously retrieved by a DFHFC
TYPE=GET,TYPOPER=UPDATE macro instruction~
A file work area (FiA) is used to contain the record or segments to
be written or updated. The first 16 bytes of the FiA form the CICS/VS
system section, which is followed by the actual record or segments to be
written to a data set.
CICS/VS performs the following services in response to a DFHFC
TYPE=PUT macro instruction:
•
writes updated or new records in user-defined data sets
•
Acquires or locates the main storage and control blocks required to
write the record
•
Releases all data set storage associated with the request to write
•
Packs a segmented record, depending on the data set organization
and the operands included in this macro instruction
96
CICS/VS APRM (ML)
Before file services can be requested by means of the DFHFC TYPE=PUT
macro instruction, the application program must include instructions
that do the following:
1.
Symbolically define the FWA by (1) copying the appropriate system
section storage definition (DFHFWADS), and (2) providing a storage
definition for the user1s section of the FWA.
2.
Establish addressability for the new FWA by specifying a symbolic
base address for the FWA.
3.
Place the address of the PWA in TCAFCAA. This address was made
available to the application program by CICS/VS in response to the
DFHFC TYPE=GET or DFHFC TYPE=GETAREA request by which the FWA was
acquired. It must have been stored by the application program at
that time, and should be moved to TCAFCAA immediately preceding the
DFHFC TYPE=PUT request, with no intervening requests that could
cause the contents of TCAFCAA to be altered.
If the records being written to a data set are undefined, the length
of the record being written must be placed in TCAFCURL.
For records written to a variable-length VSAM data set, the length of
the record should be placed in an LL~~ field in the beginning of the
record. The field is four bytes long, the first two bytes containing
the length in binary (including the 4-bytes for the length field) and
the last two bytes set to binary zeros. This field is used by CICS/VS
to determine the length of the record and is not written to the data
set.
VSAM does not allow an update operation on a control interval from
which a record has already been retrieved for update. If a task
attempts to perform an update operation on such a control interval
before a previous record already held by the same task is updated by a
DFHFC TYPE=PUT, or before the update is terminated by a DFHFC
TYPE=RELEASE, the program will go into a permanent wait.
The programmer who is adding records to a DAM data set should also
refer to "DAM Data sets" earlier in this chapter~
The following examples show how to retrieve a record at random,
update it, and return it to the data set.
For Assembler language:
COPY
KEYF
DS
FWACBAR EQU
COpy
RECORD DS
DFHTCADS
CLa
COPY TCA SYMBOLIC STRG DEFN
DEFINE KEY FIELD IN TWA
ASSIGN BASE REGISTER FOR FWA
SYMBOLICALLY DEFINE FWA
RECORD LAYOUT FOLLOWS CONTROL
FIELD AND HAS SAME BASE REGISTER
7
DFHFWADS
OCL350
READUPD DFHFC TYPE=GET,
DATASET=MASTERB,
RDIDADR=KEYF,
TYPOPER=UPDATE
L
FWACBAR,TCAFCAA
READ RECORD FOR UPDATE
*
*
*
ESTABLISH ADDRESSABILITY FOR FWA
(update record)
ST
FWACBAR,TCAFCAA
WRITEUP DFHFC TYPE=PUT,
RDIDADR=KEYF
Chapter 3.2.
PLACE FWA ADDRESS IN TCA
WRITE THE UPDATED RECORD
File Control
(DFHFC Macro Instruction)
*
97
For COBOL:
02
FWACBAR PIC S9(8)
COMP.
NOTE DEFINE BASE REGISTER FOR FWA.
01
01
DFHTCADS COpy DFHTCADS.
02 KEYF PIC X (8) •
NOTE COpy SYMBOLIC STRG DEFN FOR TCA.
NOTE DEFINE KEY FIELD IN TWA.
DFHFWADS COpy DFHFWADS.
RECORD PIC X(350).
NOTB COpy SYMBOLIC STRG DEFN FOR FWA.
NOTE DEFINE RECORD LAYOUT IN FWA.
02
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
READUPD.
DFHFC TYPE=GET,
DATASET=MASTERB,
RDIDADR=KEYF,
TYPOPER=UPDATE
MOVE TCAFCAA TO FWACBAR.
NOTE ESTABLISH TCA ADDRESSABILITY.
READ RECORD FOR UPDATE
*
*
*
NOTE ES'rABLISH FWA ADDRESSABILITY.
(upda te recor d)
MOVE FWACBAR TO TCAFCAA.
WRITEUP.
DFHFC TY PE=PUT ,
RDIDADR=KEYF
NOTE MOVE ADDRESS OF FWA TO TCA.
WRITE THE UPDATED RECORD
*
IQ.~~:
%INCLUDE DFHTCADS;
02 KEYF CHAR (8) ;
%INCLUDE DFHFWADS;
02 RECORD CHAR (350);
/*COPY SYMBOLIC STRG DEFN FOR TCA*/
/*DEFINE KEY FIELD IN TWA*/
/*COPY SY~BOLIC STRG DEFN FOR FWA*/
/*DEFINE RECORD LAYOUT IN FWA*/
READUPD:
DFHFC TYPE=GET,
DATASET=MASTERB,
RDIDADR=KEYF,
TYPOPER=UPDATE
FWACBAR=TCAFCAAi
READ RECORD FOR UPDATE
*
*
*
/*ESTABLISH ADDRESSABILITY FOR FWA*/
(upda te record)
TCAFCAA=FWACBARi
WRITEUP:
DFHFC TY PE=PUT ,
RDIDADR=KEYF
98
CICS/VS APRM(ML)
/*PLACE ADDR OF WORK AREA IN TCA*/
WRITE THE UPDATED RECORD
*
Direct Deletion. VSAM Only (TYPE = DELETE)
The format of the DpHpC macro instruction to delete a record or group of
records directly from a VSAM KSDS or RRDS is as follows:
DpHpC
TYPE=DEL ETE
[,DATASET=symbolic name]
[,RDIDADR=symbolic address]
[ , ARGTYP=KEY ]
[,SRCHTYP={pKEQIGKEQ} ]
[,NORESP=symbolic address]
[,ERROR=symbolic address]
[ ,DSIDER=symbolic address]
[,NOTPND=symbolic address]
[ ,INVREQ=symbolic address]
[,IOERROR=symbolic address]
[,NOTOPEN=symbolic address]
[,ILLOGIC=symbolic address]
DpHpC TYPE=DELETE can be used to perform the following functions on
VSAM key-sequenced and relative-record data sets only.:
•
Delete a single record.
•
Delete a group of records that share the same partial key; that is
where the first part of the keys is the same. This is called
generic delete.
To delete a single record, the key must be placed in an area pointed
to by the RDIDADR operand.
To delete a group of records with the same partial key, that is where
the first part of the keys is the same, the partial key must be placed
in an area pointed to by the RDIDADR operand. The binary length of the
key must be placed in the first byte of the area pointed to by the
RDIDADR operand. SRCHTYP=GKEQ must be specified.
Group deletes must not be attempted on data sets for which automatic
logging has been specified, (DpHpCT TYPE=DATASET,LOG=YES). An attempt
to do so will result in an invalid request condition.
Neither an pIOA nor an pWA is required for a delete operation.
Note that a DELRTE operation is an update operation, and therefore
the control interval concerned is held under exclusive control.
Exclusive control is released either by successful completion of the
DELETE operation, or failing this, by issuing a DpHpC TYPE=RELEASE
macro.
Chapter 3.2.
Pile Control (DpHpC Macro Instruction)
99
Obtain a File Work Area {TYPE =GET AREA)
The format of the DFHFC macro instruction to obtain a file work area
(FiA) for the application program is as follows:
~-----~-------r----------------------------------------------------------~
DFHFC
TYPE=GETAREA
[,DATASET=symbolic name]
[ , INITIMG= {value I YES} ]
[,TYPOPER=MASSINSERT]
<------------------------VSAM
[ , ARGTYP= {KEY I RBA} ]
<
VSAM
[,NORESP=symbolic address]
[ ,ERROR=symbolic address]
[,DSIDER=symbolic address]
[,INVREQ=symbolic address]
[ ,NOTOPEN=symbolic address]
The new main storage area is a file work area (FiA) and can be
obtained only by this macro.
(A storage control DFHSC TYPE=GETMAIN
request cannot be used for file operations~)
CICSjVS performs the following services in response to a DFHFC
TYPE=GETAREA macro instruction:
~n
1.
Acquires main storage
FiA) for the creation of a new record
2.
Includes and initializes the FWA control fields
to the FiA) required by file control
(a 16-byte prefix
If several new records whose keys are in ascending sequence are to be
added to a VSAM data set, the TYPOPER=MASSINSERT operand should be used,
in which case, the FWA is retained and made available to the application
program after each DFHFC TYPE=PUT macro instruction that adds a record
to the data set. A mass insert operation is terminated by a DFHFC
TYPE=RELEASE macro instruction. A lockout condition will occur if more
than one transaction is simultaneously attempting to perform a mass
insert to the same control interval of a protected data set. A lockout
will occur also if a transaction uses keys that are not in ascending
sequence.
In a DFHFC TYPE=GETAREA macro, the ARGTYP operand is only applicable
when TYPOPER=MASSINSERT has been specified.
When the DFHFC TYPE=GETAREA macro instruction is used, the
application program must include instructions that do the following:
•
Symbolically define the FWA by (1) copying the appropriate CICS/VS
system section storage definition (DFHFWADS), and (2) providing a
storage definition for the user's section of the FiA.
o
Establish addressaoility for the new FWA by specifying a symbolic
base address for the FWA~
(The address of the area involved,
returned by CICS/VS at TCAFCAA, must be placed in FWACBAR.)
The following examples show how to obtain an FWA, build a new record
in the FiA, and write that record to a data set.
100
CICS/VS APRM (ML)
For Assembler language:
COpy
KEYF
DS
FWACBAR EQO
COPY
RECORD DS
NEWREC
COpy TCA SYMBOLIC STRG DEFN
DEFINE KEY FIELD IN TWA
ASSIGN BASE REGISTER FOR FWA
SYl!BOLICALLY DEFINE FiA
RECORD LAYOUT FOLLOWS CONTROL
FIELD AND HAS SAME BASE REGISTER
DFHTCADS
CL8
7
DFHFWADS
OCL350
DFHFC TYPE=GETAREA,
DATASET=I1ASTERC
L
FWACBAR,TCAFCAA
OBTAIN A FWA TO CREATE A NEW
RECORD FOR A DATA SET
ESTABLISH ADDRESS ABILITY FOR FWA
*
(build new record)
ST
FWACBAR,TCAFCAA
WRITNEW DFHFC TYPE=PUT,
TYPOPER=NEWREC,
RDIDADR=KEYF
PLACE ADDR OF NEW RECORD IN TCA
WRITE THE NEW RECORD
*
*
For COBOL:
02 FWACBAR PIC S9(8) COMP.
NOTE DEFINE BASE REGISTER FOR FWA.
NOTE COpy SYMBOLIC STRG DEFN FOR TCA.
NOTE DEFINE KEY FIELD IN TWA.
01 DFHTCADS COPY DFHTCADS.
02 KEY F PIC X (8) •
01 DFHFWADS COPY DFHFiADS.
02 RECORD PIC X (350) •
NOTE COPY SYMBOLIC STRG DEFN FOR FWA.
NOTE DEFINE RECORD LAYOUT IN FWA.
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
NOTE ESTABLISH TCA ADDRESSABILITY.
NEWREC.
DFHFC TYPE=GETAREA,
DATASET=l!ASTERC
MOVE TCAFCAA TO FWACBAR.
OBTAIN A FWA TO CREATE A NEW
RECORD FOR A DATA SET
NOTE ESTABLISH PiA ADDRESSABILITY.
*
(build new record)
l!OVE FWACBAR TO TCAFCAA.
WRITNBW.
DFHFC TYPE=PUT,
TYPOPER=NEWREC,
RDIDADR=KEYF
Chapter 3.2.
NOTE ADDRESS OF NEW RECORD TO TCA.
WRITE THE NEW RECORD
File Control (DFHFC Macro Instruction)
*
*
101
For PL/I:
%INCLUDE DFHTCADS;
02 KEYF CHAR(S):
%INCLUDE DFHFWADS;
02 RECORD CHAR(350);
/*COPY SYMBOLIC STRG DEFN FOR TCA*/
/*DEFINE KEY FIELD IN TWA*/
/*COPY SYMBOLIC STRG DEFN FOR FWA*/
/*DEFINE RECORD LAYOUT IN FWA*/
J
NEWREC:
DFHFC TYPE=GETAREA,
DATASET=r!ASTERC
FWACBAR=TCAFCAA;
OBTAIN A FWA TO CREATE A NEW
*
RECORD FOR A DATA SET
/*ESTABLISH ADDRESSABILITY FOR FWA*/
(build new record)
TCAFCAA=FWACBAR;
WRITNEW:
DFHFC TYPE=PUT,
TYPOPER=NEWREC,
RD IDADR=KEYF
102
CICS/VS APRr! (ttL)
/*PLACE ADDR OF NEW RECORD IN TCA*/
WRITE THE NEW RECORD
*
*
Release Storage/Exclusive Control (TYPE=RELEASE)
The format of the DPHPC macro instruction to release a record from
exclusive control, if applicable, and to release storage areas acquired
for a record is as follows:
I
I
I
I
I
I
I
IL _______
DPHPC
~
TYPE=RBLEASE
[ ,NORESP=symbolic address]
[,ERROR=symbolic address]
[,INVREQ=symbolic address]
[,IOERROR=symbolic address]
[,ILLOGIC=symbolic address]
<------------------VSAM
_______ ____________________________________________________________
~
~
If the storage area to be released contains a record that has been
read for update (by means of a DPHPC TYPE=GET,TYPOPER=UPDATE macro), and
the update is no longer required, this macro will release the record
from exclusive control as well as free the storage areas associated with
it.
Before the DFHPC TYPE=RELEASE macro instruction is executed, the
address of the PWA, PIOA, or VSWA to be released must be moved to
TCAFCAA. Any associated areas are also released.
A mass insert operation on a VSAM data set (initiated by the
TYPOPER=MASSINSERT operand, followed by DFHPC TYPE=PUT,TYPOPER=NEWREC
macro instructions) is terminated by a DFHFC TYPB=RELEASE macro
instruction.
A DFHPC TYPE=RELEASE macro instruction should also be used to release
the VSWA established by CICS/VS in response to a read-only request for a
VSAM data set record retrieved in locate mode. Failure to release the
VSWA may cause significant performance degradation or task suspension if
sUbsequent accesses are made to the file.
The DFHFC TYPE=RELEASE macro instruction should not be specified if
the DPHPC TYPE=PUT,TYPOPER=UPDATB macro instruction is used to perform a
successful write of an updated record back to a data set. CICS/VS
automatically releases all storage associated with the write operation.
However, if an error condition occurs, preventing successful completion
of the write, a DFHFC TYPE=RELEASE macro instruction should be issued to
release the storage.
DPHPC TYPE=RELEASE must be issued whenever a DUPREC, ILLOGIC,
IOERROR, or NOTFND condition occurs. For further details of these
conditions, see "Operands of DPHFC ~acro" at the end of this chapter.
CICS/VS performs the following services in response to a DFHFC
TYPE=RELEASE macro instruction:
•
Releases an PWA, FIOA, and/or VSWA
•
Releases a VSAM string, if a VSWA is released
•
Releases exclusive control of a record retrieved for update (if
appl icable)
Note, though, that for a file with auto-logging specified (by the
system programmer), the resource remains under the task control enqueue
until either a sync point is issued or end of task is reached.
Chapter 3.2.
Pile Control (DFHPC Macro Instruction)
103
There is a limit to the number of VSAM strings that may be in use at
anyone time, determined by the STRNO operand of the DFHFCT TYPE=DATASET
system macro instruction. If strings are not released when no longer
required, tasks may have to wait unnecessarily owing to the strinqs all
being in use.
Any FWAs, FIOAs, VSiAs, and VSAM strings acquired during execution of
a task are automatically released at termination of the task, if not
released earlier in response to to a DFHFC TYPE=RELEASE macro
instruction.
The following examples show how to request the release of an FWA.
For Assembler language:
FiACBAR EQU
COpy
RECORD DS
7
ASSIGN BASE REGISTER FOR PiA
SYMBOLICALLY DEFINE FiA
RECORD LAYOUT FOLLOWS CONTROL
FIELD AND HAS SAME BASE REGISTER
DFHFiADS
OCL350
ST
FWACBAR,TCAFCAA
RLSEREC DFHFC TYPE=RELEASE
ADDRESS OF FiA TO BE RELEASED
IN TCA AND ISSUE RELEASE REQUEST
For COBOL:
02 FiACBAR PIC S9 (8)
COMP.
NOTE DEFINE BASE REGISTER FOR FiA.
I 01 DFHFWADS COpy DFHFWADS.
02 RECORD PIC 1(350).
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR •
•
MOVE FWACBAR TO TCAFCAA.
RLSEREC.
DFHFC TYPE=RELEASE
NOTE COpy SYMBOLIC STRG DEFN FOR FiA.
NOTE DEFINE RECORD LAYOUT IN FiA.
NOTE ESTABLISH TCA aDDRESSABILITY.
NOTE ADDR OF FWA TO BE RELEASED.
ISSUE RELEASE REQUEST
For PL/I:
DFHTCADS;
/*COPY SYMBOLIC STRG DEFN FOR TCA*/
~INCLUDE
DFHFWADS;
02 RECORD CHAR(350);
/*COPY SYMBOLIC STRG DEFN FOR FWA*/
/*DEFINE RECORD LAYOUT IN FWA*/
TCAFCAA=FWACBAR;
RLSEREC:
DFHFC TYPE=RELEASE
/*ADDRESS OF FWA TO BE RELEASED*/
~INCLUDE
104
CICS/VS APRM(ML)
ISSUE RELEASE REQUEST
Initiate Browse (TYPE=SETL)
The format of the DFHFC macro instruction to initiate a browse operation
on a data set is as follows:
DFHFC
TYPE=SETL
[,DATASET=symbolic name]
[,RDIDADR=symbolic address]
[ , SEG SET= {sym bolic name I YES I ALL} ]
[,RETMETH={RELRECIKEY} ]
<-----------DAM
[ ,ARGTYP= {KEY I RBA} ]
<
VSAM
[,SRCHTYP={FKEQIFKGEIGKEQIGKGE}]
<
VSAM
[ , MODE= {MOVE I LOCATE} ]
<
VSAM
[,NORESP=symbolic address]
[,ERROR=symbolic address]
[,DSIDER=symbolic address]
[,SEGIDER=symbolic address]
[,NOTFND=symbolic address]
[,INVREQ=symbolic address]
[,IOERROR=symbolic address]
[,NOTOPEN=symbolic address]
[,ILLOGIC=symbolic address]
<-----------------VSAM
This macro instruction is used to establish the position within the
data set where the browse operation is to begin. It must be issued
before any DFHFC TYPE=GETNEXT macro instruction; however, no data is
available until a DFHFC TYPE=GETNEXT is used.
The starting point within a data set for a browse operation is
identified by a record identification field established for the data
set. (See "Record Identification Field", earlier in this chapter.)
For an ISAM data set, the browse operation begins at the first record
with a key equal to or greater than the key provided in the record
idantification field. This key may be either a specific ~omplete) key
or a generic (partial) key. For example, a complete key of D6ij2BR17
causes sequential processing to begin at the first record with a key
equal to or greater than that key.
A generic key is one in which the application programmer supplies
only the significant characters of a desired group of keys, padding the
remainder of the key field with blanks or binary zeros. Considering a
data set whose records had eight byte key fields, then a generic key of
96ij2~~~~ would cause sequential processing to begin at the first record
with a key whose first four characters were equal to or greater than
96ij2. A key field of all binary zeros causes sequential processing to
begin at the first record of the data set.
For a DAM data set, the record identification field must contain a
block reference (for example, TTR or MBBCCHBR) which conforms to the
addressing method defined for that data set. Processing begins with the
specified block and continues with each subsequent block until the
browse operation is terminated. If the data set contains blocked
records, processing begins at the first record of the first block and
continues with each subsequent record.
For a VSAM data set, the contents of the record identification field
may be either a key, a relative byte address, or a relative record
number. If the field contains a relative byte address, the browse
Chapter 3.2.
File Control (DFHFC Macro Instruction)
105
operation begins at the specified address. If the field contains a key,
it may be either specific or generic. If the key is generic, the length
of the partial key is specified in the first byte of the record
identification field. In either case, the application program can
specify that the browse operation is to begin at the first" record having
a key (1) equal to the key in the record identification field (for
generic, compared on only the number of bytes specified), or (2) equal
to or greater than the key in the record identification field (again,
for generic, compared on only the bytes specified).
When the DPHFC TYPE=SETL macro instruction is used, the application
programmer must provide instructions that do the following:
•
Symbolically define the PWA by (1) copying the appropriate CICS/VS
system section storage definition (DPHPWADS), and (2) providing his
own storage definition for the user's section of the PiA.
•
Establish addressabi1ity for the PWA by specifying a symbolic base
address for the PiA, typically following the DPHPC macro
instruction ~
(The address of the FiA, provided by CICS/VS at
TCAPCAA, must be placed at FWACBAR upon normal return from
execution of the SETL macro instruction.)
\.0
In most cases, records retrieved during a browse operation are
returned to the application program in a file work area ~WA). However,
in locate mode the addresses of the record are passed in the VSWA. The
PWA allocated by CICS/VS following a SETL request is unique for the
duration of that particular browse operation. If the application
program issues another SETL request, for the same or another data set, a
different PWA is created by CICS/VS. Thus it is possible for a single
application program to concurrently : browse the same data set at several
different locations.
During a browse operation on a segmented data set, the original PWA
(that is, the one allocated by CICS/VS in response to the SETL request)
may be replaced with a different PWA if a se~ent set specified in a
GETNEXT request requires a larger PWA than the segment set specified in
the SETL request. In this situation, the application programmer should
not assume that the same PWA is used for all GETNEXT requests. The
address of the utilized FWA is available at TCAFCAA upon return from a
GETNEXT request.
CICSjVS performs the following services in response to a DPHPC
TYPE=SETL macro instruction:
1.
Acquires the main storage I/O areas and work areas to be associated
with this browse operation
2.
Preserves the segment set name (if any) as the default segment set
name to be used if none is specified in subsequent GETNEXT requests
3.
Returns the address of the allocated FWA in TCAPCAA for other than
locate-mode nonsegmented VSAM data set processing; returns the
address of the allocated VSWA that will contain the VSAM buffer"area address of each retrieved record for locate-mode nonsegmented
VSAM data set processing
The information supplied by the user in the record identification
field is preserved by CICS/VS for use when GETNEXT requests are issued.
Since CICS/VS places into this field the identification of each record
retrieved in response to a subsequent GETNEXT request, the field should
not be released by the application program.
The information placed into the record identification field by
CICSjVS is always in a form which completely identifies the record.
106
CICS/VS APRM(ML)
Por
example, assume a browse operation is to start with the first record of
a blocked, keyed DAM data set. Before issuing the DFHFC TYPE=SETL macro
instruction, the application programmer should place the TTR (assuming
that is the addressing method) of the first block into the record
identification field. After executing each DPHPC TYPE=GETNEXT macro
instruction, CICS/VS places the complete record identification into the
record identification field. After the first GETNEXT, the record
identification field might contain
X'0000010504'
where 000001 represents the TTR value, 05 represents the block key, and
04 represents the record key.
As another example, if the application program is browsing a blocked,
nonkeyed DAM data set and the second record from the second physical
block on the third relative track is read in response to a GETNEXT
request, the record identification field contains
X'00020201'
upon return to the application program, where 0002 represents the track,
02 represents the block, and 01 represents the record within the block.
The following examples show how to initiate a browse operation.
Por Assembler language:
COpy
DS
KEYP
PWACBAR EQU
COPY
RECORD DS
DPHTCADS
CL8
COpy TCA SYMBOLIC STORAGE DEPN
7
ASSIGN BASE REGISTER POR PWA
DEPINE SYSTEM SECTION OP PiA
RECORD LAYOUT
DPHFiADS
OCL350
CSECT
START
ERROR
MVC
KEYP (5) ,=C'JONES'
XC
KEYP+5 (3) , KEYP+5
DPHPC TYPE=SETL,
DATASET=MASTER,
RDIDADR=KEYP,
NOTOPEN=ERROR
FWACBAR,TCAFCAA
L
GO TO ERROR LABEL IP ERROR
ESTABLISH ADDRESSABILITY POR PiA
•
ENTRY TO ERROR ROUTINE
DS
OH
INITIALIZE KEY PIELD
INITIATE BROWSE
Chapter 3.2.· Pile Control (DPHPC Macro Instruction)
*
*
*
107
For COBOL:
02 FWACBAR PIC 59(8) COMP.
NOTE DEFINE BASE REGISTER FOR FWA.
01 DFHTCAD5 COPY DFHTCADS.
02 KEYF PIC X ~).
01 DFHFWADS COpy DFHFWADS.
02 RECORD PIC X(350).
NOTE
NOTE
NOTE
NOTE
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
NOTE ESTABLISH TCA ADDRESSABILITY.
MOVE 'JONES' TO KEYF.
START.
DFHFC TYPE=SETL,
DATA5ET=MASTER,
RDIDADR=KEYF,
NOTOPEN=ERROR
MOVE TCAFCAA TO FW1CBAR.
COpy SYMBOLIC STRG DEFN FOR TCA.
DEFINE KEY FIELD IN TWA.
COPY SYMBOLIC STRG DEFN FOR FiA.
DEFINE RECORD LAYOUT IN FWA.
INITIATE BROWSE
GO TO ERROR LABEL IF ERROR
*
*
*
ERROR.
For PLII:
%INCLUDE DFHTCADS;
02 KEYF CHAR(8);
/*COPY SYMBOLIC STRG DEFN FOR TCA*/
•
%INCLUDE DFHFWADS;
02 RECORD CHAR (350) ;
/*COPY SYMBOLIC 5TRGDEFN FOR FWA*/
/*DEFINE RECORD LAYOUT IN FWA*/
KEYF= 'JONES' ;
START:
DFHFC TYPE=SETL,
DATASET=MASTER,
RDIDADR=KEYF,
NOTOPEN=ERROR
FWACBAR=TCAFCAA;
ERROR:
108
CICS/VS APRM (ML)
INITIATE BROWSE
GO TO ERROR LABEL IF ERROR
*
*
*
Forward Browse (TYPE=GETNEXT)
The format of the DFHFC macro instruction to retrieve the next record in
ascending sequence during a browse operation is shown below.
~-----r--------r--------------------------------------------------------------'
DFHFC
TYPE=GETNEXT
[ , SEGSET= {symbolic name I YES I ALL} ]
[,DUPKEY=symbolic address]
<---VSAM & assembler
[,NORESP=symbolic address]
[,ERROR=symbolic address]
[,SEGIDER=symbolic address]
[ ,NOTFND=symbolic address]
[,INVREQ=symbolic address]
[ ,IOERROR=symbolic address]
[,NOTOPEN=symnolic address]
[ ,ENDFILE=symbolic address]
[,ILLOGIC=symbolic address]
This instruction can also be used to perform skip-sequential
processing upon a VSAM data set. After a DPHPC TYPE=SETL macro
instruction has been issued to initiate a browse operation, the next (or
first) record in ascending sequence can be obtained by issuing the DPHPC
TYPE=GETNEXT macro instruction. When the first GETNEXT request is
issued following a SETL request for an ISAM data set, CICS/VS acquires
the first record with a key equal to or greater than the key presented
by a previous SETL; for a DAM data set, CICS/VS acquires the first
record specified by the user. Each subsequent GETNEXT request, whether
for an ISAM or a DAM data set, causes CICS/VS to acquire the next record
in ascending sequence. When ISAM is used, records that are flagged for
deletion are presented to the application program, which must be able to
recognize them.
When VSAM is used, a browse operation can be specified to begin at a
particular relative byte location or with a record identified by a key.
In the former case, the first GETNEXT request retrieves that record.
Each succeeding GETNEXT retrieves the next record in ascending sequence.
If a key is specified for a VSAM data set, it may be either specific
or generic, and the application programmer can specify that the search
begin (1) at a record having a key equal to the specific or generic key,
or (2) at a record having a key equal to or greater than the specific or
generic key. The effects of GETNEXT macro instructions are as described
below.
Before issuing the DPHPC TYPE=GETNEXT macro instruction, the
application programmer must place the address of the PWA associated with
the particular operation in TCAPCAA.
If the application program has
initiated multiple browse operations, it must keep track of the PWA
associated with each operation and refer to a specific PWA when
requiring services related to that browse. Similar requirements apply
to the address of a specific VSWA in locate-mode processing of VSAM
nonsegmented records.
CICS/VS performs the following services in response to a DPHPC
TYPE=GETNEXT macro instruction referring to an ISAM, VSA!, or DAM data
set:
1.
Retrieves the next sequential record and places it in the PWA
specified by the user at TCAPCAA
Chapter 3.2.
File Control
(DPHFC Macro Instruction)
109
2.
P1aces the identification (key, block identification, or the like)
of the record just retrieved into the record identification field
specified in the DFHFC TYPE=SETL request initiating the browse
If the user issues a DFHFC TYPE=GET,TYPOPER=UPDATE request on the
record returned in response to a DFHFC TYPE=GETNEXT request, the address
of the record identification field can be specified in the DFHFC
TYPE=GET request.
The first DFHFC TYPE=GETNEXT macro instruction referring to a VSAM
data set retrieves the record located in response to the DFHFC TYPE=SETL
instruction initiating the browse. On a subsequent GETNEXT, CICS/VS
checks the contents of the record 'identification field set aside for
records of the data set. If this field contains the identification of
the record previously received, CICS/VS retrieves the next logical
record in sequence and places the identification of that record in the
record identification field. Sequential retrieval such as described
above for ISAM and DAM data 'sets then occurs.
It is possible, however, when using VSAM data sets, for the
application programmer to utilize a skip-sequential processing
capability. All that is needed is to place the identification of the
next record desired into the record identification field prior to
issuing a GETNEXT request. If, upon checking this field, CICS/VS
determines that its contents have been changed by the application
program, CICS/VS accesses the record having the identification currently
stored in the record identification field. This record need not be the
next sequential record in the data set. This skip-sequential processing
capability is available only for VSAM data sets.
When VSAM skip-sequential processing is used, the record
identification placed in the record identification field before issuing
the GETNEXT request must be of the same form as that specified in the
SETL or last RESETL request for this browse operation. That is, if the
SETL or last RESETL specified a generic key, then the new record
identification must be a generic key. It need not be the same length as
that specified in the SETL or last RESETL. If the SETL or last RESETL
specified an RBA, the new identification must be an RBA. Note that if
the SETL or last RESETL specified an equal search (FKEQ'or GKEQ), a
GETNEXT request using skip-sequential processing may result in a NOTFND
(record not found) condition.
In addition, CICS/VS can perform the following services, depending on
the operands included in the DFHFC TYPE=GETNEXT macro instruction.
1.
Present the user with segments as specified in the GETNEXT request.
2.
Present the user with segments as specified in the SETL request if
no segment set is specified in the GETNEXT request.
3.
If the FWA is not large enough to process a segment set specified
in the GETNEXT request, dispose of the old FWA and acquire a new
one large enough to process the new request.
If the NOTFND condition occurs during a browse operation, the
application program must issue either a RESETL macro to reset the browse
or an ESETL macro to terminate the browse. Both these macros are
discussed later in this chapter.
The following examples show how to initiate a browse operation and
retrieve selected segments from successive records of the data set.
110
CICS/VS APaM (ML)
For Assembl er lalliluaqe:
COpy
KEYF
DS
FWACBAR EQU
COpy
RECORDA DS
COpy TCA SYMBOLIC STRG DEFN
DEFINE KEY FIELD IN TWA
ASSIGN FWA BASE REGISTER
COpy CICS/VS CONTROL SECTION OF FWA
DEFINE RECORD LAYOUT IN FWA.
DFHTCADS
8X
7
DFHFWADS
OCL350
~
J
C:SECT
MVC
KEYF (8) ,=8X' 00'
INITIAL DFHFC TYPE=SETL,
DATASET=MASTER,
SEGSET=A,
RDIDADR=KEYF
FWACBAR,TCAFCAA
L
START AT BEGINNING OF DATA SET
INITIATE BROWSE
SET DEFAULT SEGMENT SET
*
*
*
ESTABLISH FiA BASE REGISTER
~
ST
FWACB AR, TCAFCAA
DFHFC TYPE=GETNEXT
FWACBAR,TCAFCAA
L
RESTORE FWA ADDRESS
GET NEXT SEQUENTIAL RECORD
·ASSURE ADDRESS ABILITY IF SEGMENTED
ST
FWACBAR,TCAFCAA
DFHFC TYPE=GETNEXT,
SEGSET=B
L
FWACBAR,TCAFCAA
RESTORE FWA ADDRESS
GET NEXT RECORD
WITH SEGMENT B
ASSURE ADDRESSABILITY IF SEGMENTED
Chapter 3.2.
File Control (DFHFC Macro Instruction)
*
111
For COBOL:
02 FiACBAR PIC S9(8) COMP.
NOTE DEFINE BASE REGISTER FOR FWA.
01 DFHTCADS COpy DFHTCADS.
02 KEYF PIC S9 (18) COMP.
NOTE COpy SYMBOLIC STRG DEFN FOR
TCA~
NOTE DEFINE KEY FIELD IN TiA •
•
01 DFHFiADS COPY DFHFWADS.
02 RECORD PIC X(350).
NOTE COpy SYMBOLIC STRG DEFN FOR FWA.
NOTE DEFINE RECORD LAYOUT IN FiA.
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
NOTE ESTABLISH TCA ADDRESSABILITY.
!OVE 0 TO KEYF.
NOTE START AT BEGINNING OF DATA SET.
INITIAL.
DFHFC TYPE=SETL,
DATASET=MASTER,
SEGSET=A,
RDIDADR=KEYF
MOVE TCAFCAA TO FiACBAR.
112
INITIATE BROWSE
SET DEFAULT SEGMENT SET
NOTE ESTABLISH FiA ADDRESSABILITY.
MOVE FWACBAR TO TCAFCAA.
DFHFC TYPE=GETNEXT
MOVE TCAFCAA TO FiACBAR.
GET NEXT SEQUENTIAL RECORD.
MOVE FiACBAR TO TCAFCAA.
DFHFC TYPE=GETNEXT,
SEGSET=B
MOVE TCAFCAA TO FiACBAR.
GET NEXT RECORD
WITH SEGMENT B
NOTE POSSIBLE NEW FiA.
CICS/VS APRM(ML)
*
*
*
*
For PL/I:
%INCLUDE DFHTCADS;
02 KEYF CHAR (8) i
/*COPY SYMBOLIC STRG DEFN FOR TCA*/
/*DEFINE KEY FIELD IN TWA*/
%INCLUDE DFHFWADSi
02 RECORD CHAR (350) ;
/*COPY SYMBOLIC STRG DEFN FOR FWA*/
/*DEFINE RECORD LAYOUT IN FWA*/
KEYF=LOW (8) ;
/*START AT BEGINNING OF DATA SET*/
INITIAL:
DPHFC TYPE=SETL,
DATASET=MASTER,
SEGSET=A,
RDIDADR=KEYF
FWACBAR=TCAFCAA;
TCAFCAA=PWACBAR;
DFHFC TYPE=GETNEXT
FWACBAR=TCAFCAA:
SET DEFAULT SEGMENT SET
*
*
*
/*ESTABLISH FWA ADDRESSABILITY*/
GET NEXT SEQUENTIAL RECORD
TCAFCAA=FWACBAR;
DFHFC TYPE=GETNEXT,
SEGSET=B
FWACBAR=TCAFCAAi
Chapter 3.2.
INITIATE BROWSE
GET NEXT RECORD
WITH SEGMENT B
/*POSSIBLE NEW FWA*/
File Control (DFHFC Macro Instruction)
*
113
Backward Browse. VSAM and Assembler Language Only
TYPE=GETPREV)
The format of the DFHFC macro instruction to retrieve the next record in
descending sequence during a browse operation is shown below. The DFHFC
TYPE=GETPREV macro can be used only in an assembler language application
program and on a VSAM data set.
DFHFC
TYPE=GETPREV
[,SEGSET={symbolic nameIYESIALL)]
[,DUPKEY=symbolic address]
[,NORESP=symbolic address]
[,ERROR=symbolic address]
[,SEGIDER=symbolic address]
[,NOTFND=symbolic address]
[,INVREQ=symbolic address]
[,IOERROR=symbolic address]
[,NOTOPEN=symbolic address]
[,ENDFILE=symbolic address]
[,ILLOGIC=symbolic address]
After a DFHFC TYPE=SETL macro instruction has been issued to initiate
a browse operation, the next (or first) record in descending sequence
can be obtained by issuing the DFHFC TIPE=GETPREV macro instruction.
A browse operation can be specifed to begin at a particular relative
byte location or with a record identified by a key. In the former case,
the first GETPREV request retrieves that record. Each succeeding
GETPREV retrieves the next record in descending sequence.
If a key is specified for a VSAM data set, it must be specific, and
the application programmer can specify that the search begin at a record
having a key equal to the specified key. The effects of GETPREV macro
instructions are as described below.
Before issuing the DFHFC TYPE=GETPREV macro instruction, the
application programmer must place the address of the FiA associated with
the particular operation in TCAFCAA.
If the application program has
initiated multiple browse operations, it must keep track of the FiA
associated with each operation and refer to a specific FiA when
requiring services related to that browse. Similar requirements apply
to the address of a specific VSiA in locate-mode browsing of VSAM
nonsegmented records.
CICS/VS performs the following services in response to a DFHFC
TIPE=GETPREV macro instruction referring to a VSAM data set:
1.
Retrieves the next record in descending sequence and places it in
the FWA specified by the user at TCAFCA~
2.
Places the identification (key, or relative byte address) of the
record just retrieved into the record identification field
specified in the DFHFC TYPE=SETL request initiating the browse
If the user issues a DFHFC TIPE=GET,TYPOPER=UPDATE request on the
record returned in response to a DFHFC TYPE=GETPREV request, the address
of the record identification field can be specified in the DFHFC
TYPE=GET request.
114
CICS/VS APRM(ML)
The first DFHFC TYPE=GETPREV macro instruction retrieves the record
located in response to the DFHFC TYPE=SETL instruction initiating the
browse. On a subsequent GETPREV, CICS/VS checks the contents of the
record identification field set aside for records of the data set. If
this field contains the identification of the record previously
received, CICS/VS retrieves the next logical record in sequence and
places the identification of that record in the record identification
field.
If the DFHFC TYPE=GETPREV macro instruction is issued following a
DFHFC TYPE=SETL macro instruction using a generic key, an invalid
request will be indicated.
In addition, CICS/VS can perform the following services, depending on
the operands included in the DFHFC TYPE=GETPREV macro instruction.
1.
Present the user with segments as specified in the GETPREV request.
2.
Present the user with segments as specified in the SETL request if
no segment set is specified in the GETPREV request.
3.
If the FWA is not large enough to process a segment set specified
in the GETPREV request, dispose of the old FWA and acquire a new
one large enough to process the new request.
Chapter 3.2.
File Control (DFHFC Macro Instruction)
115
Terminate Browse (TYPE=ESETL)
The format of the DFHFC macro instruction to terminate a browse
operation on a data set is as follows:
------~------r--------------------------------------------------------~
I
DFHFC I
I
I
I
I
TYPE=ESETL
[,NORESP=symbolic address)
[,ERROR=symbolic address]
[,INVREQ=symbolic address]
[,ILLOGIC=symbolic address]
<------------------VSAK
I
~----_~------_I~------------------------------------------------------~
Before this macro is issued, the programmer must ensure that TCAFCAA
contains the address of the file work area (FWA) associated with the
browse operation he wishes to terminate. When locate-mode processing of
VSAM nonsegmented records is utilized, TCAFCAA must contain the address
of the VSWA associated with the browse operation being terminated. In
response to an ESBTL request, CICS/VS releases all I/O and work areas
associated with the browse operation.
The following examples show how to terminate two concurrent browse
operations.
For Assem bIer lanQU2:g§l:
COpy
FWACELL1 DS
*FWACELL2 DS
*
FWACBAR
BQU
RECORD
COPY
DS
DFHFWADS
OCL350
COpy TCA SYMBOLIC STRG DEFN
CONTAINS ADDR OF FWA USED
FOR FIRST BROWSE OPERATION
CONTAINS ADDR OF FWA USED
FOR SECOND BROWSE OPERATION
ASSIGN FWA BASE REGISTER
DEFINE PiA SYMBOLIC STORAGE DEFN
DEFINE RECORD
TCAFCAA,FWACELL1
TYPE=ESETL
TCAFCAA,FCACELL2
TYPE=ESETL
MOVE BROiSE
ISSUE ESETL
MOVE BROWSE
ISSUE ESETL
DFHTCADS
A
A
7
CSECT
MVC
DFHFC
MVC
DFHFC
116
CICS/VS APRM(ML)
1 FiA
MACRO
2 FWA
MACRO
ADDR TO TCA
INSTRUCTION
ADDR TO TCA
INSTRUCTION
02 FiACBAR PIC S9(8)
COMP~
NOTE DEFINE BASE REGISTER FOR FWA.
01 DFHTCADS COPY DFHTCADS.
02 FWACELL1 PIC S9 (8) ~OMP.
02 FiACELL2 PIC S9 (8) COMP.
01 DFHFWADS COpy DFHFiADS.
02 RECORD PIC X(350).
NOTE COPY SYMBOLIC STRG DEFN FOR TCA.
NOTE COpy SYMBOLIC STRG DEFN FOR FiA.
NOTE DEFINE RECORD LAYOUT IN FWA.
MOVE FWACELL1 TO TCAFCAA.
DFHFC TYPE=ESETL
NOTE PREPARE TO END FIRST BROWSE.
TERMINATE FIRST BROWSE
MOVE FWACELL2 TO TCAFCAA.
DFHFC TYPE=ESETL
NOTE PREPARE TO END 2ND BROWSE.
TERMINATE SECOND BROWSE.
For PL/I:
%INCLUDE DFHTCADS;
/*COPY SYMBOLIC STRG DEFN FOR TCA*/
02 FiACELL1 POINTER;
02 FWACELL2 POINTER;
%INCLUDE DFHFWADS;
02 RECORD CHAR (350) ;
/*COPY SYMBOLIC STRG DEFN FOR FHA*/
/*DEFINE RECORD LAYOUT IN FWA*/
TCAFCAA=FWACELL1;
DFHFC TYPE=ESETL
TCAFCAA=FWACELL2;
DFHFC TYPE=ESETL
/*MOVE BROWSE1 FWA ADDR TO TCA*/
Chapter 3.2.
/*MOVE BROiSE2 FWA ADDR TO TCA*/
File Control (DFHFC Macro Instruction)
117
Reset Browse (TYPE=RESETL)
The format of the DFHFC macro instruction to reset the search argument,
default segment set name, and/or type of search argument (VSAM only) for
a browse operation is as follows:
DFHFC
TYPE=RESETL
[ ,SEGSET={symbolic nameIYESIALL}]
<,-------------VSAM
[,ARGTYP={KEYIRBA}]
[,SRCHTYP={FKEQI~IGKEQIGKGE}]
<
VSAM
[,NORESP=symbolic address]
[,ERROR=symbolic address]
[,SEGIDER=symbolic address]
[,NOTFND=symbolic address]
[,INVREQ=symbolic address]
[,IOERROR=symbolic address]
[,NOTOPEN=symbolic address]
[,ILLOGIC=symbolic address]
<
---------------VSAM
Once a browse operation has been initiated, the application
programmer may, at any time prior to issuing an ESETL request for the
browse, reset the search argument to some record other than the next
sequential record in the data set. The default segment set name and
(for a VSAM data set) the type of search argument used in retrieving
records can also be reset by issuing the DFHFC TYPE=RESETL macro
instruction. Prior to issuing the request, the application programmer
should place the address of the appropriate FWA into TCAFCAA and the new
record identification in the record identification field specified in
the original SETL request~
The use of the RESETL maCro instruction allows the application
programmer to avoid issuing an ESETL request followed by another SETL
request, and causes CICS/VS to use the same I/O and work area. Upon
return from the RESETL request, TCAFCAA contains the address of a new
FWA that the user can use for the browse operation.
The RESETL request allows the user to "skip" through his data set in
a browse operation with ease. A similar capability is available to VSAM
Users through the GETNEXT instruction.
A browse operation should be terminated by issuing a TYPE=ESETL
macro, but a normal or abnormal end of task will also terminate a
browse.
The following examples show how to reset the search argument and the
default segment set for a browse operation.
For Assembler
lagg!!~§.:
COpy
KEYF
DS
FWACBAR EQU
COpy
RECORD1 DS
DPHTCADS
D
DPHFW ADS
OCL350
COpy TCA SYMBOLIC STRG DEPN
DEFINE KEY PIELD IN TWA
ASSIGN FWA BASE REGISTER
COpy FWA DSECT
DEFINE RECORD WITH SEGSET A
ORG
RECORD2 DS
RECORD 1
OCL250
DEPINE RECORD WITH SEGSET B
118
7
CICS/VS APRM (ML)
CSECT
MVC
KEYF(8) ,=8X I OOI
DFHFC TYPE=SETL,
DATASET=MASTER,
RDIDADR=KEYF,
SEGSET=A
L
FWACBAR ,TCAFCAA
INITIALIZE KEY FIELD
ISSUE INITIAL SETL MACRO
FOR DATA SET "MASTER"
INITIAL SEARCH ARG=O
FOR SEGSET=A
ESTABLISH ADDRESSABILITY TO FWA
*
*
*
ST
FWACBAR,TCAFCAA
MVC
KEYF(8),=CL8 I SMITHI
DFHFC TYPE=RESETL,
SEGSET=B
L
FWACBAR,TCAFCAA
STORE FWA ADDR IN TCA
ESTABLISH NEW SEARCH ARGUMENT
ISSUE RESETL MACRO
NEW SEGSET ID
ESTABLISH ADDRESSABILITY TO FWA
*
02 FWACBAR PIC S9(8) COMP.
NOTE DEFINE BASE REGISTER FOR FiA.
01 DFHTCADS COPY DPHTCADS.
02 KEYF PIC S9(18) CaMP.
NOTE COpy SYMBOLIC STRG DEFN paR TCA.
NOTE DEFINE KEY FIELD IN TWA.
02 PILLER REDEFINES KEYP.
03 KEYC PIC X (8) •
01 DFHFWADS COpy DFHFWADS.
02 RECORD1 PIC X (350) •
NOTE COpy SYMBOLIC STRG DEFN FOR FWA.
NOTE DEFINE RECORD WITH SEGSET A.
01 DFHFWA REDEFINES DFHFWADS.
02 FILLER PIC X(16).
02 RECORD2 PIC X (250) •
NOTE CREATE STRG DEFN FOR FWA.
NOTE LENGTH OP FWA.
NOTE DEFINE RECORD WITH SEGSET B.
MOVE 0 TO KEYF.
DFHFC TYPE=SETL,
DATASET=MASTER,
RDIDADR=KEYF,
SEGSET=A
MOVE TCAFCAA TO PWACBAR.
ISSUE INITIAL SETL MACRO INSTR
*
FOR DATA SET "MASTER"
*
INITIAL SEARCH ARG=O
*
FOR SEGSET =A
NOTE ESTABLISH ADDRESSABILITY TO FiA.
MOVE FWACBAR TO TCAFCAA.
MOVE 'SMITHI TO KEYC.
DFHFC TYPE=RESETL,
SEGSET=B
MOVE TCAFCAA TO FWACBAR.
NOTE STORE FWA ADDRESS IN TCA.
NOTE Es'rABLISH NEi SEARCH ARGUMENT.
ISSUE RESETL MACRO INSTRUCTION
*
NEW SEGSET ID
NOTE ESTABLISH ADDRESSABILITY TO FiA.
Chapter 3.2.
File Control
(DFHFC Macro Instruction)
119
For PL/I:
IINCLUDE DFHTCADS;
02 KEYF CHAR(S);
/*COPY SY!BOLIC STRG DEFN FOR TCA*/
/*DEFINE KEY*/
•
~INCLUDE
DPHPWADS;
/*COPY SYftBOLIC STRG DEFN POR FWA*/
02 RECORD1 CHAR (350);
/*DEFINE RECORD WITH SEGSET A*/
DECLARE 01 DPHXFWA BASED (FWACBAR),
02 PILL CHAR (16) ,
/*LENGTH OF PWA*/
02 RBCORD2 CHAR (250) ;
/*DEPINE RECORD WITH SEGSET B*/
KEYP=LOW(S);
DPHFC TYPE=SETL,
DATASET=MASTER,
RDIDADR=KEYP,
SEGSET=A
PWACBAR=TCAFCAA;
/*SET KEY VALUE TO ZERO*/
ISSUE INITIAL SETL !ACRO INSTR
*
POR DATA SET "MASTER"
*
INITIAL SEARCH ARG EQUALS ZERO
*
FOR SEGSET A
/*ESTABLISH ADDRESSABILITY FOR PWA*/
TCAFCAA=PWACBAR;
KEYP= 'SftITH';
DFHPC TYPE=RESETL,
SEGSET=B
PWACBAR=TCAPCAA;
/*STORE FWA ADDR IN TCA*/
/*ESTABLISH NEW SEARCH ARGUMENT*/
ISSUE RESETL !ACRO INSTRUCTION
*
NEW SEGSET ID
I*ESTABLISH ADDRESS ABILITY TO FWA*/
120
CICS/VS APR!(!L)
Test Response to a Request for File Services (TYPE=CHECK)
The format of the DFHFC macro instruction to test the CICS/VS response
to a preceding DFHFC request for file services is as follows:
DFHFC
TYPE =CHECK
[,NORESP=symbolic address]
[,ERROR=symbolic address]
[ ,DSIDER=symbolic address]
[,SEGIDER=symDolic address]
[,NOTFND=symbolic address]
[,DUPKEY=symbolic address]
[,DUPREC=symbolic address]
[,INVREQ=symbolic address]
[,IOERROR=symbolic address]
[,DUPDS=symbolic address]
[,NOSPACE=symbolic address]
[,NOTOPEN=symbolic address]
[,ENDFILE=symbolic address]
[,ILLOGIC=symbolic address]
<--------VSAM & assembler
<------------------VSAM
I File Control Response Codes
To test a response code the application programmer must know (1) the
CICS/VS response codes and their meanings, and (2) the symbolic labels
by which he can refer to the response codes. These are shown in Figure
3.2-11. If the Assembler-language or PL/I programmer elects to check
for a particular response-code bit pattern, he can access the response
code at TCAFCTR. The COBOL programmer who elects to check for a
particular response-code bit pattern, can access the response code at
TCAFCRC.
Because the multipunch codes to be checked in a COBOL program
commonly correspond to unprintable characters, an alternative facility
is provided in CICS/VS for use by the COBOL programmer. He can evaluate
the response by referring to the condition names generated by CICS/VS
(for example, FCNORESP). Use of this approach is illustrated in the
examples at the end of this discussion.
Chapter 3.2.
File Control (DFHPC Macro Instruction)
121
File Services
Request by
DFHFC Macro
Instruction
Response Code
Condition
-----.
. . .------r=-----Assembler COBOLt
PL/I
All
NORESP
(Normal
Response)
X'OO'
LOW-VALUES
(FCNORESP)
00000000
GET,DELETE,GETAREA,
SETL,CHECK
DSIDER
(Data set
identification error)
X'01'
12-1-9
(FCDSIDER)
00000001
GET,PUT,DELETE,SETL,
GETNBXT,RESETL,CHECK,
GETPREV
ILLOGIC
(VSAM only;
error not
covered by
any other
code)
XI 02 1
12-2-9
(FCILLOGIC)
00000010
GET,SETL,GETNEXT,
RESETL,CHECK,GETPREV
SEGIDER2
(Segment
set identification
error)
X I 04 1
12-4-9
(FCSEGIDER )
00000100
All
INVREQ
(Invalid
Request)
X'08 1
12-8-9
(FCINVREQ)
00001000
GET ,CHECK
DUPDS3
(Duplicate
data set)
X'OA'
12-2-8-9
(FCDUPDS)
00001010
GET, pu'r ,DELETE,
GETAREA,SETL,GETNEXT,
RESETL,CHECK,GETPREV
NOTOPEN
(Data set
not open)
X'OC'
12-4-8-9
(FCNOTOPEN)
00001100
GETNEXT,CHECK,GETPREV
ENDFILE
(End of
file during
browse)
XIOF'
12-7-8-9
(FCENDFILE)
00001111
GET,PUT,DELETE,SETL,
GETNEXT,RESETL,CHECK,
GETPREV
IOERROR
(Error not
covered by
any other
code)
X I 80 1
12-0-1-8
(FC IOERROR)
10000000
GET,DELETE,SETL,
GETNEXT,RESETL,CHECK,
GETPREV
NOTFND.
(Record not
found)
X l 81 1
12-0-1
(FCNOTFND)
10000001
PUT, CHECK
DUPREC
(Duplicate
records)
XI 82 1
12-0-2
(FCDUPREC)
10000010
Figure 3.2-11.
122
(Part 1 of 2)
CICS/VS APRM (ML)
File Control Response Codes
File Services
Request by
DFHFC Macro
Instruction
Response Code
r
Condition
Assembler
PUT, CHECK
NOSPACEs
(No DASD
space for
adding
record)
X'83'
GET,GETNEXT,GETPREV,
CHECK
DUPKEY
(VSAH &
assembler
only; duplicate key
in alternate index)
X1841
All
ERROR
(Any
response
other than
NOR ESP)
See Note
6
COBOLl
PL/I
12-0-3
(FCNOSPACE)
10000011
See Note 6
See Note 6
Notes:
1.
The names enclosed in parentheses in the COBOL column
indicate the condition names generated by CICS/VS. These
names may be used in testing for the respective
conditions in a COBOL program.
2.
The SEGIDER condition can occur only when the SEGSET operand
is specified.
3.
The DUPDS condition can occur only when the INDEX operand is
specified.
4.
For SETL, GETNEXT, GETPREV, or RESETL, the NOTFND condition
can occur only for VSAM files.
5.
The NOSPACE condition can occur only when TYPOPER=NEWREC is
specified.
6.
The test for the ERROR response is satisfied by a not equal
condition; that is, not X'OO-, not LOW-VALUES, or not 00000000
for Assembler, COBOL, and PL/I, respectively.
Figure
3~2-11
..
(Part 2 of 2)
File Control Response Codes
The keyword operands that can be used to reguest tests of the
response to a request for file services (that is, a DFHFC macro
instruction) are identified in the discussions of the instruction
formats. The condition expressed by each keyword is explained in detail
and should be referred to by the application programmer when using any
of the checking methods described above.
When certain exception conditions (for example, HOTFND, IOERROR, OR
DUPREC) occur, the FIOA or VSWA that has been acquired for the file
control request, is retained. Its address is available to the
application program. Before other file control requests are issued, the
Chapter 3.2.
File Control (DFHFC Macro Instruction)
123
storage occupied by the FIOA or VSWA should be freed by a DFBFC
TIPE=RELEASE macro instruction. When the exception conditions DSIDER,
SEGIDER, INVREQ, or NOTOPEN occur no storage areas are acquired for the
associated file control request.
The following examples show how to examine the response code provided
by ClCS/VS at TCAFCTR (for Assembler language or PL/I) or TCAFCRC ~or
COBOL) and transfer control to an appropriate user-written errorhandling routine. The alternative approach available to COBOL
programmers is also shown.
For Assembler language:
DFBFC TYPE=GET,
DATASET=MASTER,
RDIDADR=KEYF
CLI
TCAFCTR,X'OO'
GOOD
BE
CLI
TCAFCTR,X'SO'
ERROR
BE
CLI
TCAFCTR,X'OS'
ERROR
BE
GOOD
DS
ERROR
DS
OR
DFHPC TYPE=ABEND
*
*
NORMAL RESPONSE
I/O ERROR
INVALID REQUEST
OB
For COBOL:
DFHFC TYPE=GET,
DATASET=MASTER,
RDIDADR=KEYF
IF TCAFCBC = LOW-VALUES GO TO GOOD. NOTE LOW-VALUES NORESP.
IF TCAFCRC = , , GO TO ERROR.
NOTE 12-0-1-8 IOERROR.
NOTE 12-8-9
lNVREQ.
IF TCAFCRCY=' • GO TO ERROR.
*
*
GOOD.
ERROR.
DFHPC TYPE=ABEND
where the value specified within single quotation marks is an
unprintable multipunch code for the required hexadecimal value.
For example, a hexadecimal SO has a multipunch code of 12-0-1-'
S.
124
CICS/VS APRM(ML)
The alternative approach to response code checking, which is
available to COBOL programmers as described earlier, is
generally a coding convenience and provides concise code
documentation. When this approach is used, the IF statements
above are replaced by statements of the form shown below, using
the CICS/VS generated condition names:
IF FCNORESP THEN GO TO GOOD.
IF FCIOERROR THEN GO TO ERROR.
IF FCINVREQ THEN GO TO ERROR.
For P1L!.:
DFHFC TYPE=GET,
DATASET=MASTER,
RDIDADR=KEYF
IF TCAFCTR=IOOOOOOOO'B THEN GO TO GOOD;
IF TCAFCTR=110000000 1B THEN GO TO ERROR;
IF TCAFCTR='OOOO1000'B THEN GO TO ERROR;
*
*
/* NORMAL RESPONSE */
/* I/O ERROR */
/* INVALID REQUEST */
GOOD:
ERROR:
DFHPC TYPE=ABEND
Chapter 3 .. 2..
File Control (DFHFC Macro Instruction)
125
Operands of DFHFC Macro
ARGTYP=
describes the contents of the record identification field when
operating on a VSAM data set.
KEY
indicates that the record identification field contains a
search key or a relative record number.
RBA
indicates that the record identification field contains a
relative byte address.
In a DFHPC TYPE=GETAREA macro, the ARGTYP operand can only
be used when TYPOPER=MASSINSERT is also specified. ARGTYP
describes the record identification fields of the records
to be mass-inserted by DFHPC TYPE=PUT macros. When used in
a mass-insert operation, the ARGTYP operand cannot be
overriden.
DATASET=symbolic name
is the symbolic name of the data set to be accessed. When
indirect accessing is involved, this is the name of the primary
data set (see "Indirect Accessing" earlier in this chapter).
The name must appear in the file control table (FCT). If this
operand is omitted, the symbolic name is assumed to be in
TCAFCDI.
DSIDER=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the data set specified by the
DATASET operand (or at TCAFCD~ cannot be located in the FCT.
The error also occurs if the data s~t specified in the INDEX
operand of a DFHFC TYPE=GET macro instruction (or at TCAFCAI) ,
or any of the lower-level data sets in the indirect accessing
hierarchy, cannot be found in the FCT. DSIDER signifies "data
set identification error." The contents of TCAFCAA are not
meaningful.
DUPDS=symbo1ic address
specifies the entry label of the user-written routine to which
control is to be passed if the record retrieved on an indirect
access is from a duplicates data set rather than from the
primary data set. The user's routine can include provisions
for processing the duplicate record. DUPDS signifies
"duplicates data set ...
TCAFCAA contains:
• The address of an PIOA if the duplicates data set is
unblocked and its records are non-V SAM
•
126
The address of an PiA if the duplicates data set is blocked
or in all cases where records are VSAM.
CICS/VS APRM(ML)
DUPKEY=symbolic address
• valid only for assembler language application programs and
VSAM data sets.
specifies the entry label of the user-written routine to which
control is to be passed if the duplicate key condition is
raised. This can only occur with VSAM data sets where records
are being accessed by alternate indexes. This condition
indicates that a record has been retrieved but that there are
other records in the data set which have the same (alternate)
key. These records can be retrieved by a browse.
DUPREC=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an attempt is made to add a record
to a data set in which a record with the same key already
exists. DUPREC signifies "duplicate record."
TCAFCAA contains:
•
The address of an FIOA if the PUT request is against an
ISAM data set
•
The address of a VSWA if the PUT request is against a VSAM
data set
The FWA will be released by the File Control Program.
After
any interrogation of the FlO! or VSWA returned is complete, the
program should issue a DFHFC TYPE=RELEASE macro instruction.
ENDFILE=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an end-of-file condition is detected
during the sequential retrieval (browse) of records in a data
set. This condition can occur only in response to a GETNEXT
request. TCAFCAA contains the address of the FWA for the
browse operation if move mode is specified or implied in the
SETL request. TCAFCAA contains the address of the VSWA that
represents the browse if locate mode is specified.
ERROR=symbolic address
specifies the entry label of the user-written routine to uhich
control is to be passed if any error occurs on a file
operation. The CICS/VS response code should be further
interrogated in this user-written routine.
ILLOGIC=symbolic address
specifies the entry label of the user-written routine to which
control is to be transferred if a VSAM error that does not fall
within one of the other CICS/VS response categories occurs.
TCAFCAA contains the address of a VSWA. The user's routine may
check the actual logical error codes in the RPL which is at
VSWARPL. The error code is at VSWAERRC, and the return code is
at VSWARTNC.
After an interrogation of the area returned, the program should
issue a DFHFC TYPE=RELEASE macro instruction.
Chapter 3.2.
File Control
(DFHFC Macro Instruction)
127
INDEX=
indicates that indirect accessing is to be used and specifies
the symbolic name of the highest level index data set to be
used.
(This index data set is the first data set accessed in
the hierarchy.)
symbolic name
is the symbolic name of the highest level index data set to
be accessed. The name must have been defined in the FCT.
YES
indicates that the symbolic name of the highest level index
data set has been placed in TCAFCAI.
If the data set identified by this operand is a OAK data set,
it cannot be blocked~
INITIKG=
specifies a one-byte (two-digit) hexadecimal initialization
value for the FWA.
value
is a two-digit hexadecimal numeral to be used as the
initialization value.
YES
indicates that the hexadecimal initialization value has
been placed in TCASCIB.
If this operand is omitted, the FWA is initialized to EBCDIC
blan ks (X' 40' ) •
INVREQ=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the attempted file operation is not
provided for or allowed according to the data set entry
specification in the FCT ~ INVREQ signifies" invalid request. II
TCAFCAA contains:
•
A non-zero value if the request is not allowed according to
the FCT entry for the file.
•
Zero if the request is invalid or if the code to support
the request has not been generated into the CICS/VS file
control program.
IOERROR=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an input/output error occurs during
a file operation. When an I/O event error code is not covered
by one of the CICS/VS error classes (for example, by NOSPACE or
NOTFND), it is considered to be an I/O error.
TCAFCAA contains:
•
128
The address of an FIOA if the request is against an ISAK or
a DAM data set
CICS/VS APRK(KL)
•
The address of a VSiA if the request is against a
VSA~
data
s~
The application programmer should be aware of the following
considerations:
•
Por an IS!M or DAM data set, the actual error codes may be
checked in the PIOA by the user's routine (PCPIOEX for ISAM
and PCPIOBEX for DAM). Because of access method and
operating system dependencies, checks for these codes may
have a limiting effect on the usability of an application
program in varying environments, particularly if migration
from CICSjDOS/VS to CICS/OS/VS becomes desirable.
•
Por a VSAM data set, the actual error codes may be checked
in the request parameter list (RPL) located at VSWARPL.
The error code is at VSiAERRC, and the return code is at
VSiARTNC. Because of access method and operating system
dependencies, checks for these codes may have a limiting
effect on the usability of an application program in
varying environments, particularly if migration from
CICS/DOS/VS to CICS/OS/VS becomes desirable.
•
For RBSETL or GETNBXT the browse operation is still active,
but the position in the data set may have been lost. A
RESETL using the record identification for the next record
required should be issued to reestablish the position in
the data set. If move mode is specified or implied in the
initiating SETL request, the FiA representing the browse
operation must be used for the RESETL; if locate mode is
specified in the SBTL request, the VSWA must be used.
•
For PUT, the FiA will have been released.
Except for RESETL or GETNEXT, after any interrogation of
the area returned is complete, the program should issue a
DFHFC TYPE=RELBASE macro instruction.
MODE=
is used to specify the processing mode for a read-only or
browse request to a VSAM data set.
KOVE
specifies move mode processing. Upon return to the
application program, TCAFCAA contains the address of the
PiA acquired for the read-only or browse operation. If the
data set referred to contains variable-length records, the
LL~~ length field is included as part of the record.
LOCATE
specifies locate mode processing. Upon return to the
application program, TCAFCA! contains the address of a
VSWA. The address of the retrieved record is at VSWAREA.
If the data set referred to contains variable-length
records, the LL~~ length field is not retrieved as part of
the record; instead, the length of the record is placed in
VSWALEN. This parameter cannot be specified if
TYPOPER=UPDATB is specified and/or segmented records are
being retrieved.
Chapter 3.2.
File Control (DFHFC Macro Instruction)
129
NORESP=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if no error occurs on a file operation.
NORESP signifies "normal response."
The field TCAFCAA in the TCA of the task contains:
•
The address of an FIOA after a read-only unsegmented GET
against an unblocked non-VSAM data set or a blocked DAK
data set if deblocking is not requested
•
The address of an FWA after a GET against a blocked data
set, a GET segmented, a GET for update, a GETAREA, SETL,
GETNEXT, or RESETL. An FWA is always acquired for VSAM
move mode operations, regardless of blocking
•
The address of a VSWA after a locate-mode GET or SETL
against a VSAM data set and after a GETNEXT or RESETL for a
browse operation initiated by a locate-mode SETL
•
Meaningless information aftar a PUT, DELETE, RELEASE, or
ESETL
NOSPACE=symbolic address
specifies the entry label of the user-written routine to which
control is to be transferred if no direct access space is
available for adding records to a data set. This error
condition is not applicable when adding records to a fixedlength DAK data set that does not contain keys. TCAFCAA
contains the address of an FWA containing the record to be
added. This FWA may be at a different storage location than
the FWA passed with the PUT request.
NOTFND=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an attempt to retrieve or delete a
record based on the search argument provided is unsuccessful.
NOTFND signifies "record not found."
TCAFCAA contains:
•
The address of an FIOA if the request was a GET against an
ISAM or a DAM data set
•
The address of a VSWA if the request was a GET, DELETE,
SETL, RESETL, or GETNEIT request using skip-sequential
against a VSAM data set
The application programmer should be aware of the following
considerations:
130
•
Except for RESETL or GETNEXT, the program should issue a
DFHFC TYPE=RELEASE macro instruction when any interrogation
of the area is complete.
•
For SETL, the browse operation was not initiated.
CICSjVS APRM (ML)
o
For RESETL or GETNEXT, the browse operation is still
active, but the position in the data set has been lost.
A
RESETL should be issued to reestablish the position in the
data set. If move mode is specified or implied in the SETL
request initiating the browse operation, the FWA
representing the browse must be used for the RESETL; if
locate mode is specified in the SETL request, the VSWA must
be used.
NOTOPEN=symbolic address
specifies the entry label of the user-writ ten routine to which
control is to be transferred if the requested data set is not
open. This error condition can occur in response to any file
service request (except RELEASE and ESETL), because a data set
can be closed dynamically at any time without regard to
outstanding activity on the data set. The contents of TCAPCAA
are not meaningful.
RDIDADR=
specifies the symbolic address of the record identification
field for a record, or the relative record number of a record.
symbolic address
is the symbolic address of the record identification field
that contains the key (for ISAM), the block reference (for
DAM), or the key, relative byte address, or the relative
record number (for VSAM) of the record to be processed. If
this operand is omitted, the address is assumed to be in
TCAFCRI. This field is used when adding a new record (for
ISAM, DAM, and VSAM) or when updating an existing record in
a nonkeyed DAM data set without previously reading it for
update.
1.
This operand must not refer to a field in the FWA,
because the FWA might be freed before the write occurs.
2.
The DPHFC TYPE=PUT,TYPOPER=NEWREC macro instructions
for a VSAM mass-insert operation may specify the same
record identification field or different record
identification fields.
3.
The key field (for ISAM) may be altered by the access
method during the file operation. If a new key is to
derived by modifying the old key, the old key must
be saved elsewhere before issuing the DPHPC macro.
4.
i :~
When adding a new record to a VSAM entry-sequence
data set, there is no need to supply a relative byte
address (RBA).
However, a field must be provided to
receive the RBA after the record has been added; the
address of the field must be supplied either in
TCAFCRI or by using the RDIDADR operand.
Chapter 3.2.
File Control (DPHPC Macro Instruction)
131
relative record number
is the number of the required record in a VSAM relativerecord data set (RRDS). If this operand is omitted, the
address of the field which contains the record number is
assumed to be in TCAFCRI.
1.
The SRCHTYP operand is assumed to be FKEQ on all DFHFC
macros except SETL and RSETL when only FKEQ and FKGE
will be accepted.
2.
In skip sequential operation, if the relative record
number refers to a non-existent or deleted record, the
NOTFND condition will be raised, even if SETL or RESETL
included SRCBTYP=FKGE.
RETMETH=
applies only to blocked DAM data sets and is used to specify
the argument type (retrieval method) for deblocking the data
sets. It is also used to specify the format of the information
placed in the record information field each time a record is
retrieved in a browse operation. It is invalid if INDEX is
specified, because a blocked DAM data set cannot be an index
data set for indirect accessing.
RELREC
specifies that retrieval is to occur by relative record,
with the first record in a block considered to be record
zero. It also specifies that a one-byte binary relative
record number is provided in a browse operation.
KEY
specifies that retrieval is to occur by key or that in a
browse operation, a key is to be provided.
If TYPOPER=UPDATE is specified for a DAM data set, this operand
is required. If this operand is omitted and a request to read
a blocked DAM data set is issued, the entire physical record
(block) is returned in the FIOA to the application program.
The block reference field, required by DAM, contains the
criteria for deblocking the data set. If a retrieved record is
"undefined," the application program must determine the length
of the record.
SEGIDER=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the segment set specified by the
SEGSET operand (at TCAFCSI) cannot be located for this data set
in the FCT. SEGIDER signifies "segment set identification
error."
The field TCAFCAA contains:
•
Zero for GET, SETL, or RESETL
•
The address of the FiA for GETNEXT
For RESETL, the browse operation will have been terminated.
132
CICS/VS APRM (ML)
SBGSBT=
indicates that the data set specified in the DATASET operand
contains segmented records and identifies the segment set to be
retrieved, or specifies a new default segment set name to be
used in a browse operation. When used in a browse operation,
it also indicates the default segment set to be retrieved if no
segment set name is specified in a subsequent TYPE=GETNEXT
macro. This segment set name is used as the default throughout
the browse unless altered by a TYPE=RESETL macro. If locate
mode is specified in a TYPE=SETL macro initiating a browse,
SEGSBT is invalid and including it will raise the invalid
request (INVREQ) condition.
symbolic name
is the symbolic name of the segment set to be retrieved, or
the symbolic name of the default segment set. The name
must have been defined in tIle associated segment control
section of the FCT.
YES
indicates that the symbolic name of the segment set to be
retrieved, or of the default segment set, has been placed
in TCAFCSI. When used with a TYPE=PUT macro it specifies
that the data set contains segmented records.
ALL
indicates that the entire record in an unpacked and aligned
format is required. SEGSBT=ALL is assumed by CICS/VS when
updating a segmented record no matter what is specified in
the SEGSET operand; the entire record is unpacked and
returned to the application program.
If this operand is omitted, and the DFHFC TYPE=GET or TYPE=SETL
macro instruction refers to a data set containing segmented
records, the record is returned in its packed unaligned format.
Also, if this operand is omitted, the segment set name
specified in a preceding SETL or RESETL macro instruction for a
browse operation continues to be the segment set name.
SRCHTYP=
specifies how the search key in the record identification field
is to be used (VSAM records only). This operand is meaningful
only when ARGTYP=KEY is specified or implied by default.
FKEQ
indicates that the search key is a full key and that only a
record with an equal key satisfies the search. When used
with TYPB=DELETB, all records whose keys match the search
key are deleted.
FKGB
indicates that the search key is a full key and that the
first record with a key equal to or greater than the search
key satisfies the search.
Chapter 3.2.
File Control (DFHFC Macro Instruction)
133
GKEQ
indicates that the search key is a generic (partial) key,
the binary length of which is specified in the first byte
of the record identification field. A record whose key is
equal to the search key (compared on only the number of
bytes specified in the first byte of the record
identification field) satisfies the search. When used with
TYPE=DELETE, all records whose keys begin with the search
key are to be deleted. A count of the number of records
deleted is returned in TCAFCNRD.
GKGE
indicates that the search key is a generic key and that the
first record with a key equal to or greater than the search
key (compared on only the number of bytes specified in the
first byte of the record identification field) satisfies
the search.
TYPOPER=
describes the file operation to be performed.
NEWREC
indicates that a new record is to be added to an existing
data set.
UPDATE
when used with a TYPE=PUT macro, it indicates that a record
retrieved previously by a DFHFC TYPE=GET,TYPOPER=UPDATE
instruction is to be updated (in effect, rewritten to the
data set). When used with a TYPE=GET macro, it indicates
that a record is to be obtained for updating, or, if a VSAM
key-sequenced data set is referred to, for either updating
or deletion. If records in a protected VSAM key-sequenced
data set are to be updated or deleted, ARGTYP=KEY must be
specified and SRCHTYP must be FKEQ. If the record is from
a blocked DAM data set, the RET!ETH operand must be
specified. If TYPOPER=UPDATE is omitted, a read-only
operation is assumed.
The UPDATE parameter can also be used with TYPE=PUT to
write a record to a DAM data set after building the record
in an area obtained by a DFHPC TYPE=GETAREA macro. This
technique is described in detail in the section "DAM Data
Sets" earlier in this chapter.
DELETE
is valid only when a VSA! key-sequenced data set is being
accessed and indicates that a record previously retrieved
for update by a DPHPC TYPE=GET,TYPOPER=UPDATE request is to
be deleted from the data set.
MASSINSERT
is applicable only to VSAM data sets and specifies that the
acquired FWA is to be used for a mass-insert operation.
This ensures that the same PiA is used for subsequent DPBPC
TYPE=PUT macro instructions adding new logical records with
keys or relative byte addresses in ascending sequence to
the data set. The PWA is made available to the application
program after each DPHPC TYPE=PUT macro instruction. The
PiA is reinitialized, before each return to the application
program, to the value specified in the INITIMG operand (if
specified) or otherwise to EBCDIC blanks ~·40·). A massinsert operation is terminated by a DPHPC TYPE=RELEASE
macro instruction.
134
CICS/VS APRM(ML)
Chapter 3.3. DLtI Services
The CICS/VS application programmer can request Oata Language/I
services in two ways:
~L/I)
1.
By issuing a OL/I CALL statement, written according to OL/I
specifications. This method is available to both CICS/OS/VS and
CICS/OOS/VS users.
This OL/I CALL is mandatory if the user wishes
to access remote OL/I data bases using ISC.
2.
By issuing a OFHFC macro instruction.
CICS/OS/VS users only.
This method is available to
In both cases, control is passed to a routine that acts as an
interface between the CICS/VS application program and the OL/I request
handler. This routine performs validity checks on the CALL list,
prepares OL/I to handle the request, and passes control and the CALL
list to OL/I. After OL/I has handled the request, it returns control to
the calling program unless a OL/I pseudo-abend has occurred, in which
case the CICS/VS task is abnormally terminated.
Under CICS/VS, two or more transactions (tasks) may require the same
application program at any given time during system operation. Because
CICS/VS application programs must be quasi-reenterable (see IIQ uasiReenterability," in Chapter 1.1), OL/I areas that may be modified under
CICSjOS/VS (such as PCB pointers, I/O work areas, and segment search
arguments) should not be placed in static storage. They should also not
be placed in working storage (unless the application program contains
one or more command-level statements, in which case working storage is
dynamic). Storage for such areas must be obtained from CICS/VS dynamic
storage by each transaction using the program.
Four steps must be performed by an application program requesting
OL/I data base services. These steps are listed below and explained in
the sections that follow.
1.
Obtain addresses of program communication blocks
by the application program.
(PCBs) to be used
2.
Building segment search arguments
the CALL.
3.
Acquire I/O work areas for OL/I segments processed by the program.
4.
Issue the OL/I CALL.
(SSAs) if they are to be used in
Obtaining Addresses of Program Communication Blocks
An application program that uses the CICS/VS-OL/I interface accesses
data bases by means of program communication blocks (PCBs). One PCB for
each data base is included in the program specification block (PSB) for
the program. To process OL/I CALLs within a CICS/VS transaction, the
PSB for the transaction must be scheduled and the PCB addresses obtained
before any OL/I CALLs are made.
Scheduling involves, for example, that
all the required OL/I control blocks exist and are in main storage, and
that the processing options associated with this PSB permit it to be
scheduled concurrently with those PSBs already scheduled. If they are
not obtained, an INVREQ (invalid request) indicator is returned in
response to any OL/I CALL within the program.
Chapter 3.3.
OL/I Services
135
A transaction may schedule only one PSB at a time. An attempt to
schedule a second PSB while one is still scheduled causes the INVREQ
indicator to be returned.
A sync point request (refer to the DFHSP macro instruction in Chapter
7.5) by a task that is scheduled to use DL/I resources implies the
release of those resources. This means that if, after issuing a DFHSP
TYPE=USER macro instruction, access to a DL/I data base is required, the
desired PSB must be rescheduled. The previous position of that data
base has been lost.
I/O PCBs (a type of control block used by I"S/VS) are not passed to
CICS/VS programs, even though they may be included in a transaction's
PSB, either explicitly or implicitly by means of the COMPAT=YES option.
DFHFC MACRO INSTRUCTION (CICS/OS/VS ONLY)
To schedule the desired PSB and obtain PCB addresses, the CICS/OS/VS
application programmer may use a special form of the DFHFC macro
instruction:
r------~------·r----------------------------------------------------------,
I
I
I
I
I
I
I
I
I
I _______
L
DFHFC
TYPE=~L/I,PCB)
[,PSB={'psbname'lsymbolic addressIYES}]
[,NORESP=symbolic address]
[,DLINA=symbolic address]
[,PSBSCH=symbolic address]
[,PSBNF=symbolic address]
[,PSBFAIL=symbolic address]
[,INVREQ=symbolic address]
~
_______ ________________________________________________________
~
~
where:
TYPE=(DL/I,PCB)
indicates that PCB addresses are to be acquired.
~:
DL/I in the TYPE= operand may also be coded as DLI or
DL1.
If the PSB has been located, TCADLPCB contains the address of a list
of PCB addresses in the sequence in which the PCB addresses were
specified during the PSBGEN of this PSB. If the PSB cannot be found,
TCADLPCB contains zero. If the PSB pool or DMB pool is too small to
hold the requested blocks even when no other PSBs or DMBs are in their
pools, the transaction is terminated with the ADLA ABEND code.
136
CICS/VS APRM(ML)
DL/I CALL STATEMENT (CICS/DOS/VS OR CICS/OS/VS)
Upon receiving control from CICS/VS, a CICS/VS application program must
issue a DL/I call to perform scheduling before attempting to access DL/I
data bases. If the scheduling call is successful, the address of the
PCB list is returned in the field TCADLPCB and TCAFCTR is set to zeros.
If the call is unsuccessful, TCADLPCB contains zeros and TCAFCTR
~ontains a one-byte return code.
Before continuing with subsequent DLjI
calls, it is the application programmer's responsibility to test these
indicators to determine whether scheduling was successful.
The format of the CALL statement to request scheduling is as follows:
For Assembler language:
CALLDLI {ASMTDLIICBLTDLI}, [parmcount, ]function,[psb])
For COBOL:
CALL 'CBLTDLI' USING [parmcount,]function,[psb].
For PL/I:
CALL PLITDLI [parmcount, ]function,[ psb ]) ;
where:
parmcount
is the name of a binary fullword containing the parameter count
(value of one or two). This parameter is optional.
function
is the name of the field containing the four-character function
'PCBJt' •
psb
is the name of the eight-byte field containing the PSB
generation name which the application program accesses.
(This
name is one to eight bytes long under CICSjOS/VS, or one to
seven bytes long under CICSjDOS/VS, and is left justified and
padded on the right with blanks as appropriate.) This parameter
is optional. Under CICS/DOS/VS if it is omitted, the PSB name
is assumed to be the first PSB name associated with the
application program name in the DL/I application control table
generation. Under CICS/OS/VS if it is omitted, the PSB name is
assumed to'be the name of the application program associated
with the task in the PCT.
Building Segment Search Arguments
Both CICSjOS/VS and CICS/DOS/VS application programmers can use segment
search arguments (SSAs) in a DL/I CALL to identify a specific segment,
or, if qualified, to identify the range of values within which a segment
exists. In addition, the CICS/OS/VS programmer can specify SSAs in a
DFHFC TYPE=DL/I macro instruction. If used, SSAs must be built by the
application programmer before a DL/I CALL is issued. (For information
concerning how to build an SSA, CICSjOS/VS application programmers
should refer to the IMSIYS Application Programming Reference Manual;
Chapter 3.3.
DL/I Services
131
CICSjDOS/VS users should refer to the DL/I DOS/yS Application
ProqramminqReference Manual.)
In a DL/I application program, SSAs are built in fixed storage within
the program. In a CICS/VS application program, SSAs must be built in
dynamic storage to maintain the quasi-reenterability of the program.
The storage acquired to build the SSAs is addressed as follows:
•
For Assembler-language programs, the address should be placed in
the register that establishes addressability for the SSA dynamic
storage.
•
For COBOL programs, the address is moved to the BLL pointer for
this storage. The BLL pointer is defined under the COpy DFHBLLDS
statement in the Linkage section and must be in the same relative
position in the BLL list as the 01 statement for the SSA dynamic
storage is among the 01 statements in the Linkage Section.
• - For PL/I, the address is stored in the variable upon which the SSA
dynamic storage is based.
After the storage has been acquired and the SSAs built, DL/I CALLs in
which the SSAs are used can be issued by the application program. The
names of the SSAs to be used, if any, are specified in the parameter
list of the CALL. Under CICS/OSjVS, a DFHFC TYPE=DL/I macro instruction
can also be used. In a DFHFC TYPE=DL/I macro instruction, the
application programmer can specify the number and names of the SSAs in
different ways:
1.
SSAS=NO indicates that there are no SSAs in this CALL.
2.
SSAS=(ssacount,ssa1,ssa2, ••• ), where ssacount is optional,
represents either the fixed-point number of SSAs in the CALL or the
symbolic address of the fullword that contains the number of SSAs.
Specifying a field to contain the number of SSAs provides the
application programmer with flexibility in writing one DFHFC
statement to be used in many different CALLs. ssa1, ssa2, ••• , are
the symbolic names of the SSAs.
3.
SSALIST=YES indicates that the application programmer has built a
list of fullwords, optionally containing the number of SSAs ~hich
may be zero) in the first word, and the addresses of the SSAs in
the following words, and that he has stored the address of this
list at TCA DLSS A.
4.
SSALIST=symbolic address indicates that the address of an SSA list
built by the application programmer as indicated in item 3 is at
the location specified.
In Assembler-language programs, ssacount,ssa1,ssa2, ••• , can be
contained in registers if the specifications are enclosed in
parentheses"
Acquiring an I/O Work Area
When issuing a request for DL/I services, the address of a work area,
either that in which a current segment is contained or that in which
DL/I is to place the segment in a retrieval CALL, is required. This
area must be specified by the CICSjOSjVS or CICS/DOS/VS programmer who
issues a DL/I CALL. It may be provided by the interface, if the
programmer desires, for a retrieval-type DFHFC macro instruction.
138
CICS/VS APRM(!L)
If the CICS/OS/VS application programmer knows the address of the
work area to be used in the DFHFC macro instruction, including the case
for which storage is acquired for a retrieval-type (GXXX) request, he
specifies the name of the pointer to that storage in the WRKAREA=name
operand, or he places the address of the storage in TCADLIO before
issuing the request and specifies WRKAREA=YES.
If the application programmer wishes to allow the interface to obtain
the work area for a retrieval-type request, he does not include the
WRKAREA operand in the DFHFC macro request. If the request was serviced
successfully, the address of an acquired I/O work area is in TCADLIO.
The address at TCADLIO is the address of the storage accounting area
(SAA) preceding the retrieved data. The area becomes the responsibility
of the programmer and is not freed until he frees it or until the
transaction terminates. If the application programmer elects to free
the work area, he must use a DFHSC TYPE=FREEMAIN macro instruction.
Note: The address of the I/O area is specified as the address of the
storage accounting area preceding the data when a DFHFC macro
instruction is used; the address of the first byte of the data area is
required when a DL/I CALL is used.
Requesting DL/I Services
The application program request for DL/I services may be either a
CICS/VS DFHFC macro instruction (CICS/OS/VS) or a DL/I call (CICS/OS/VS
or CICSjDOS/VS).
DFBFC MACRO INSTRUCTION (CICS/OS/VS)
The format of the DFHFC macro instruction to request that a particular
DL/I function be performed is as follows:
r-------~-------~-----------------------------------------------------------------------------,
DFHPC
TYPE= (OL/I [,function])
[,PCB={symbolic addressl (register)}]
[,WRKAREA={symbolic addresslYESI (register)}]
[, SSAS= {NOI ([ ssacount][ ,ssa 1][ ,ssa2, ••• ]) I
([ (register1) ][ , (register2) , ~ •• ])} ]
[,SSALIST={YESINOlsymbolic address I (register)}]
[,NORESP=symbolic address]
[,NOTOPEN=symbolic address]
[,OLINA=symbolic address]
[,FUNCNS=symbolic address]
[,INVREQ=symbolic address]
where:
TYPE=(DL/I [,function])
specifies the two- to four-byte name of the function to be
performed. If the function is not specified, it is assumed to
be in TCAOLPUN.
Note:
OL1.
OL/I in the TYPE= operand may also be coded as OLI or
Chapter 3.3.
OL/I Services
139
DL/I CALL STATEMENT (CICS/OS/VS OR CICS/DOS/VS)
DL/I data base services are available to CICS/VS application programs
through CALL statements. The CALL statement formats for COBOL and PL/I
are similar. Por Assembler-language application programs, a CALLDLI
macro instruction is used. The formats of the DL/I calls are as
follows:
Por Assembler language:
CALLDLI {ASMTDLIICBLTDLI}[ , ([parmcount, ]function,pcb,workarea[,ssa, ••• ])]
Por COBOL:
CALL ICBLTDLII USING [parmcount,]function,pcb,workarea[,ssa, ••• ].
For PL/I:
CALL PLITDLI Warmcount,function,pcb,workarea[,ssa, ••• ]);
where:
parmcount
is the name of a binary fullword containing the parameter count
or argument count of the arguments which follow; this is
optional for Assembler language and COBOL.
function
is the name of the field containing the four-character DL/I
input/output CALL function desired.
pcb
is the program communication block (PCB) name (or DSECT name if
Assembler) •
workarea
is the name of the I/O work area.
ssa1 to ssan
are the names of the segment search arguments (SSAs); these are
optional.
Notes:
1.
If no parameters are specified in an Assembler-language CALLDLI
macro instruction, register 1 is assumed to contain the address of
a parameter list.
2.
In Assembler language, an alternative format may be used:
CALLDLI (AS!TDLIICBLTDLI},!F=(E,(register) or address)
where:
address
is the address of the parameter list, or register that contains
the address of the parameter list.
140
CICS/VS APRM(!L)
Releasing a PSB in the CICS/VS Application Program
To reduce pool and intent contention, the CICS/OS/VS application program
can release the PSB after a DL/I service has been requested.
It is recommended that conversational programs release the PSB before
writing to a terminal so that other transactions can use the PSB while
the conversational program is waiting for an operator response.
To ensure data-base integrity, a request to release a PSB other than
a read-only PSB implies the end of a logical unit of work for the entire
task. This means that a DFHSP TYPE=USER is issued on behalf of a task
that is releasing a PSB, unless the PSB is read-only and is resident on
the system that issued the call.
DFHFC MACRO INSTRUCTION (CICS/OS/VS ONLY)
To release a PSB for use by other transactions, the CICS/OS/VS
application programmer may issue a macro instruction of the following
format:
i
I
I
I
I
I
LI ______
DFHFC
~
______
TYPE=(DL/I,{TERMIT})
[,DLINA=symbolic address]
[,TERMNS=symbolic address]
[,INVREQ=symbolic address]
.~
__________________________________________________________
where:
TYPE= (DL/I,TERM)
specifies that the PSB is to be released for use by other
transactions, or, if not required, its pool space and
associated DMB pool space may be released for other purposes.
1.
DL/1 in the TYPE= operand may also be coded as DL1 or DLI.
2.
TERM may be abbreviated as T.
Before issuing any other DL/I CALls or DFHFC macro instructions
requesting DL/I access to a data base, the application programmer must
again issue a schedule request. All positioning in data bases referred
to by the transaction is lost when the PSB is released. Thus, if the
program was processing a hierarchy through GNxx requests before
releasing the PSB, it is necessary to explicitly reposition the data
bases after issuing another schedule request, to continue the GNxx
requests.
DL/I CALL STATEMENT (CICS/DOS/VS OR CICS/OS/VS)
If the CICS/VS application program desires to relinquish control of the
PSB, it must issue a terminal call to DL/1. The format of the CALL
statement to request termination is as follows:
Chapter 3.3.
DL/I Services
141
For Assembler language:
CALLDLI {AS!TDLI ICBLTDLI} , ([parmcount, )function)
For COBOL:
CALL ICBLTDLII USING [parmcount,]function.
For PL/I:
CALL PLITDLI [parmcount, ]function);
where:
parmcount
is the name of a binary fullword containing the parameter count
value of one.
function
is the name of the field containing the four-character function
'TER~' or ·T~~~·.
When a termination call is issued for a previously scheduled PSB, the
resources acquired for the task are releas8d, and tasks awaiting the
resources are given an opportunity to be scheduled.
DL/I Services Response Codes
To test a response code, the application programmer must know the
CICS/VS response codes and their meanings. If the Assembler-language or
PL/I programmer elects to use this approach, he can access the response
codes for NORESP, INVREQ, and NOTOPEN at TCAFCTR; the response codes for
all other conditions can be accessed at TCADLTR. The COBOL programmer
can access the response codes for NORESP, INVREQ, and NOTOPEN at
TCAFCRC; the response codes for all other conditions can be accessed at
TCADLTR. The possible response codes and the conditions to which they
correspond are identified in the right-hand column of Figure 3.3-1.
CICS/VS-DL/I interface requests for which the conditions are applicable
are shown at the left.
142
CICS/VS
APR~(!L)
I
I
Response Code
Assembler
COBOL
DL/I Interface Request
Condition
(DL/I, PCB) , (DL/!
[,function]) ,CHECK
NORESP
(Normal
Response)
X'OO'
LOW-VALUES
(FCNORESP)
00000000
(DL/I[ , function]) ,
CHECK
NOTOPEN
(Not open)
X'OC'
12-4-8-9
(FCNOTOPEN)
00001100
All
INVREQ
(Invalid
Request)
X'08 1
12-8-9
(FCINVREQ)
00001000
PL/I
Codes returned in TCADLTR after NOTOPEN condit10n
(DL/![ function]) ,
CHECK
r
Data base
not open;
request
issued in
X'OO'
LOW-VALUES
00000000
oS/vs
system
Data base
not open;
request
issued in
DOS/VS
system
X'01
1
12-1-9
00000001
Intent
scheduling
conflict
XI 02 1
12-2-9
00000010
Codes returned in TCADLTR after INVREQ condition
ALL
D/Base not
in FCT, or
D/Base not
open according to I
FCT, or in-I
valid argument passed
toDL/I
x·oo·
LOW-VALUES
00000000
(DL/! ,PCB) , CHECK
PSBNF
(PSB Not
Found)
XI Ol l
12-.1-9
(DLPSBNF)
00000001
CHECK
TASKNA
(Task Not
Authorized)
X' 02 1
12-2-9
(DLTASKNA)
00000010
(DL/I,PCB) , CHECK
PSBSCH
(PSB. Already Sche-I
duled
I
X1 03'
12-3-9
(DLPSBSCH)
00000011
Figure 3.3-1.
(Part 1 of 2)
CICS/VS-DL/I Interface Response Codes
Chapter 3.3.
DL/I Services
143
Response Code
DL/I Interface Request
Condition
Assembler
CHECK
LANGCON
(Language
Conflict)
X'04'
12-4-9
(DLLANGCON)
00000100
(DL/I,PCB) , CHECK
PSBFAIL
(PSB Initialization
Failed)
X'OS'
12-5-9
(DLPSBFA IL)
00000101
CHECK
PSBNA
(PSB Not
Authorized)
X'06'
12-6-9
(DLPSBNA)
00000110
(DL/I,T) ,CHECK
TER!NS
(Termination Not
Scheduled)
X'01'
12-1-9
(DLTER!NS)
00000111
FUNCNS
(Function
Not Scheduled)
X'OS'
12-8-9
(DLFUNCNS)
00001000
Any DL/I access CALL
(except TER! and PCB)
on a remote system
Invalid PCB
adddress
X'10'
12-11-1-8-9
00010000
All
DLINA
(DL/I Not
Active)
X'FF'
HIGH-VALUES
11111111
(DL/I[,function]),
CHECK
COBOL
PL/I
(DLIN A)
Notes:
1.
The TASKNA and LANGCON conditions apply only to CICS/DOS/VS.
2.
PSBNA occurs only when the data base is on a DOS/VS system.
3.
The names enclosed in parentheses in the COBOL column
indicate the condition names generated by CICS/VS. These
names may be used in testing for the respective conditions
in a COBOL program.
Figure 3.3-1.
144
(Part 2 of 2)
CICS/VS APR! (!L)
CICS/VS-DL/I Interface Response Codes
I Test Response to a DL/I Request (TYPE=CHECK)
The format of the DFHFC macro instruction to test the CICSjVS response
to a preceding DLjI request is as follows:
~-------------r----------------------------------------------------------'
DFHFC
TYPE=CHECK
[,NORESP=symbolic address]
[,DLINA=symbolic address]
[ ,PSBSCH=symbolic address]
[,PSBNF=symbolic address]
[,PSBFAIL=symbolic address]
[,FUNCNS=symbolic address]
[,TERMNS=symbolic address]
[,LANGCON=symbolic address]
[,TASKNA=symbolic address]
[,PSBNA=symbolic address]
[ , INVREQ=symbolic address]
[ ,NOTOPEN=symbolic address]
CICS/DOS/VS only
CICS/DOSjVS only
CICS/DOS/VS only
where:
TYPE=CHECK
indicates that the CICS/VS-DL/1 interface response is to be
checked.
The application programmer may use the DFHFC TYPE=CHECK macro
instruction following a DL/I CALL statement or a DFHFC
TYPE=(DL/I[,function)) macro instruction. This macro instruction does
not check the DL/I return codes in the PCB. If DL/I issues a pseudoabend during processing of the request, control is not returned to the
application program. The transaction is terminated with CICS/VS abend
code ADLA. For CICS/DOS/VS, if DL/I issues a pseudo-abend during a
call, the transaction is terminated with a Dnnn abend code where nnn is
the DL/I pseudo-abend code.
If the application programmer does not provide for the checking of a
particular response, and if the exception condition corresponding to
that response occurs, program flow proceeds to the instruction following
the DL/I request in the application program.
Chapter 3.3.
DL/1 Services
145
DL/I Requests in an Assembler-language Program (CICS/OSNS)
The application programmer must first get the addresses of the PCB.
When CICS/OS/VS returns from servicing the PCB request, if the
programmer loads register 1 from TCADLPCB, his program is in the same
state as after an ENTRY DLITCBL statement has been executed in an IMS/YS
DL/I application program.
The examples that follow show the options available to the
application programmer in a few of the acceptable combinations. The
application program must be guasi-reenterable. If a DFBFC macro
instruction is issued, the PCB and MRKAREA operands are used to specify
the addresses of pointers to fields rather than the addresses of fields
desired.
COpy DFHTCADS
*
PSBNAME
DC
CLS'PSBNAME'
PCBFUN DC
CL4'PCBb'
PCBPTRS DSECT
*
PCB1PTR
OS
PCB2PTR DS
F
F
WORKAPTR DS
F
COPY TCA DEFINITION - INCLUDES
DL/I FIELDS
NAME OF PSB TO BE USED
PCB FUNCTION
PCB POINTERS RETURNED BY
INTERFACE
STORAGE FOR PCB POINTERS
*PCB1
DSECT
STORAGE FOR POINTER IN I/O WORK
AREA
PCB DSECT
PCB2
DSECT
PCB DSECT
WRKAREA DSECT
DS
2F
WORKA1 DS
CL40
SSAREA DSECT
DS
2F
SSA1
DS
CL40
SSA2
DS
CL20
DFHFC TYPE= (DL/!, PCB)
DFHFC TYPE=(DL/I,PCB),
PSB='PSB14'
DFHFC TYPE= (DL/I,PCB) ,
PSB=PSBNAME
MVC TCADLPSB,=CLS'PSBA'
DFHFC TYPE=(DL/I,PCB),
PSB=YES
R1,TCADLPCB
L
USING PCBPTRS,R 1
*
**
*
DL/I WORK AREA DSECT
STORAGE PREFIX
WORK AREA
SSA DSECT
STORAGE PREFIX
SSA1 LAYOUT
SSA2 LAYOUT
USE PSB FOR THIS PROGRAM
GET PCB'S IN 'PSB14 '
GET PCB'S IN SPECIFIED PSB
PUT PSB NA!!E IN TCA
GET PCB'S OF PSg NAftED IN TCA
GET ADDRESS OF PCB ADDR LIST
REG 1 IS BASE OF PCB POINTERS
USER ftUST PROVIDE ADDRESSABILITY
TO PCB'S WHEN USING THEft
ISSUE A PCB REQUEST VIA CALLDLI
CALLDLI CBLTDLI, (PCBFUN)
USE PSB FOR THIS PROGRAM
CALLDLI CBLTDLI,(PCBFUN,PSBNAftE)GET PCB'S IN SPECIFIED PSB
L
R1,TCADLPCB
GET ADDRESS OF PCB ADDRESS LIST
ACQUIRE STORAGE FOR WORK AREA
146
CICS/VS APRM(ML)
*
*
*
*
*
**
**
*
**
*
**
*
DFHSC TYPE=GETMAIN, •••
L
R2,TCASCSA
USING WRKAREA ,R2
ACQUIRE STORAGE FOR SSA'S
DFHSC TYPE=GETMAIN, •••
L
R3,TCASCSA
USING SSAREA ,R3
GET STORAGE FOR SSA'S
REG 3 IS BASE FOR SSA'S
INDICATE TO ASSEMBLER
CALLDLI CBLTDLI, (function,PCB1,WORKA1,SSA1,SSA2)
CALL DL/I VIA DFHFC MACRO -- VARIOUS EXAMPLES
EXAMPLE 1
DFHFC TYPE=(DL/I,function),
PCB=PCB1PTR,
WRKAREA=WORKAPTR,
SSAS=(2,SSA1,SSA2),
NORESP=GOODl
PCB IS POINTED TO
WORK AREA IS POINTED TO
SSA COUNT AND SSAS SPECIPIED
NORMAL RESPONSE BRANCH
**
*
*
EXAMPLE 2
MVC
LA
ST
DFHFC
TCADLPCB,PCB1PTR
RO,WRKAREA
RO,TCADLIO
TYPE=(DL/I,DLET),
WRKAREA=YES,
SSAS=NO
PRELOAD PCB POINTER
PICK UP WORK AREA ADDRESS
STORE IN TCA
FUNCTION SPECIFIED
WORK AREA ADDRESS PRELOADED
NO SSAS
*
*
EXAMPLE 3
MVC
DFHSC
L
LA
LA
ST
LA
ST
ST
TCADLFUN,=CL4'GU'
TYPE=GETMAIN, •••
R4,TCASCSA
R4,8 (R4)
RO,l
RO,O (R4)
RO,SSAl
RO,4 (R4 )
R4, TCADLSSA
01
4 (R 4) , X• 80 '
DFHFC TYPE=DL/I,
PCB=PCB lPTR,
L
*
GET STORAGE FOR WORK AREA
REG 2 IS BASE FOR WORK AREA
TELL ASSEMBLER
SSALIST=YES
R3,TCADLIO
PRELOAD FUNCTION
GET STORAGE FOR SSA LIST
PICK UP STORAGE ADDRESS
BYPASS PREFIX
GET COUNT OF SSA'S
STORE IN SSA LIST
GET ADDRESS OF 'SSA1'
STORE IN SSA LIST
STORE LIST ADDRESS IN TCA
SET ON THE END-OF-LIST BIT
DL/I CALL, FUNCTION PRELOADED
*
POINTER TO PCB TO BE USED
*
INTERFACE WILL PROVIDE WORK AREA*
PROBLEM PGM PROVIDES SSA LIST
PICK UP ADDRESS OF SUPPLIED
WORK AREA
Chapter 3.3.
DL/I Services
147
DL/I Requests in a COBOL Program (CICS/OS/VS)
Upon program entry, the COBOL programmer should obtain PCB addresses by
issuing a DFHFC TYPE=(DL/I,PCB) request or a DL/I IPCBI call~
After
CICS/OS/VS returns control, the programmer moves the contents of
TCADLPCB to the BLL pointer which, is the base for the layout of the PCB
pointers in the Linkage section. He then moves the addresses of the
PCBs to their BLL pointers to provide the base addresses for the PCBs.
When this is done, the program is in the same state as after an ENTRY
'DLITCBLI USING PCB1,PCB2 statement has been executed in an IftS/VS DLjI
application program.
For an explanation of how BLL pointers to 01 statements in the
Linkage Section are defined, see the discussion of COBOL application
programming in Chapter 2.3~
Examples showing how to write DLjI requests are given below. Only
some combinations of operands are shown, but other combinations are
acceptable. Note that, in a DFHFC request, BLL pointers to the PCB and
work area are used rather than actual field names. This is the only way
the addresses can be passed to DL/I.
WORKING-STORAGE SECTION.
11 PSBNAME PIC X(8) VALUE IPSBNAMEI.
11 PCB-FUNCTION PIC X(4) VALUE IPCB~I.
17 FUNCTION-l PIC X(4) VALUE IDLET'.
11 SSA-COUNT PIC 59(8) COMP VALUE 2.
LINKAGE SECTION.
01 DFHBLLDS COpy DFHBLLDS
02
NOTE POINTERS TO OTHER CICS/VS
AREAS NEEDED
02 B-PCB-PTRS PIC S9 (8) COl:!P.
02 B-PCBl PIC 59 (8) COMP.
02 B-PCB2 PIC S9 (8) COMP.
02 B-WORKAREA PIC S9 (8) COMP.
02 B-SSAS PIC 59 (8) COMP.
01 DFHC5ADS COPY DFHCSADS.
01 DFHTCADS COPY DFHTCADS.
NOTE TWO DEFINITIONS.
NOTE OTHER AREA DEFINITIONS.
*
01
01
PCB-P TRS •
02 PCB1-PTR PIC S9(8) COMP.
02 PCB2-PTR PIC S9 (8) COMP.
PCB1.
01
PCB2.
01
WORKAREA.
02 FILLER PIC X(8).
02 WORKA 1 PIC X (40)' •
01
148
SSAREA.
02 FILLER PIC X(8).
02 SSA1 PIC X(40).
02 SSA2 PIC X(60).
CICS/VS APRM(ML)
NOTE STORAGE PREFIX.
PROCEDURE DIVISION.
GET PCB ADDRESSES
DFHFC TYPE=(DL/I,PCB)
GET PSB FOR THIS PROGRAM
GET PCB ADDRESSES VIA CALL
CALL 'CBLTDLII USING PCB-FUNCTION,PSBNAME.
NOTE GET PCB'S FOR SPECIFIED PSB.
* SAVE PCB ADDRESSES IN BLL TABLE SO PCB'S CAN BE ADDRESSED
MOVE TCADLPCB TO B-PCB-PTRS.
MOVE PCB1-PTR TO B-PCB1.
MOVE PCB2-PTR TO B-PCB2.
OPTIONALLY, ACQUIRE STORAGE FOR WORK AREA
DFHSC TYPE=GETMAIN, •••
MOVE TCASCSA TO B-WORKAREA.
OPTIONALLY, ACQUIRE STORAGE FOR SEGMENT SEARCH ARGUMENTS
DFHSC TYPE=GETMAIN, •••
MOVE TCASCSA TO B-SSAS.
CALL DL/I VIA CALL
CALL 'CBLTDLI' USING FUNCTION-l,PCB1,WORKA1,SSA1,SSA2.
EXAMPLE 1 OF DFHFC MACRO INSTRUCTION
DFHFC TYPE=(DL/I,GHU),
FUNCTION
*
PCB=B-PCB1,
PCB POINTER
*
WRKAREA=B-WORKAREA,
WORK AREA POINTER
*
SSAS=(SSA-COUNT,SSA1,SSA2) SSA COUNT AND NAMES
EXAMPLE 2 OF DFHFC MACRO INSTRUCTION
MOVE 'GNP I TO TCADLFUN.
NOTE PRELOAD FUNCTION.
MOVE B-PCBl TO TCADLPCB.
NOTE PRELOAD PCB ADDRESS.
DFHFC TYPE=DL/I,
FUNCTION PRELOADED
*
SSAS=NO
PCB ADDRESS PRELOADED
WORK AREA TO BE ACQUIRED
NO SSA'S
MOVE TCADLIO to B-WORKAREA.
NOTE SAVE ACQUIRED HORK AREA ADDR.
*
*
*
*
*
*
*
*
*
Chapter 3.3.
DL/I Services
149
DL/I Requests in a PL/I Program (CICS/OSNS)
Upon entry to his program, the PL/I application programmer should get
PCB addresses through a DFHFC TYPE=(DL/I,PCB) statement or a DL/I IPCBI
call. When CICS/VS returns, the base address of a structure of PCB
pointers is in TCADLPCB. The PL/I programmer must move the value from
TCADLPCB to the based variable for his declared structure of PCB
pointers. He then loads the pointers to all PCBs from this structure.
When this has been done, the program is in the same state as an IMS/VS
DL/I application program in which the
DLITPLI: PROCEDURE (pcbname 1 ,
~ ~
.) OPTIONS
(REENTRA NT, MA IN);
statement has been executed.
The PL/I programmer may then make DL/I requests, either through CALLs
or DL/I DFHFC macro instructions. Note that the PCB and WRKAREA
operands in a DFHFC request specify the addresses of pointers to fields
rather than of the fields desired.
/* CSA DEFINITION */
/* TCA DEFINITION - INCLUDES */
/* DL/I FIELDS */
1 PCB POINTERS BASED (B_PCB_PTRS),
2 PCB1 PTR POINTER,
2 PCB2:PTR POINTER;
%INCLUDE DFHCSADS;
%INCLUDE DFHTCADS;
DECLARE 1 PCBl BASED (BPCB1),
/* PCB DEFINITIONS */
2 •••
2 ••• ;
DECLARE 1 PCB2 BASED (BPCB2),
2 •••
2 •••
;
DECLARE 1 DLI_IOAREA BASED (BDLIIO), /* DL/I I/O AREA */
2 STORAGE_PREFIX CHAR (8),
2 IOKEY CHAR (6) ,
2
tit.. ;
DECLARE 1 DLI_SSADS BASED (BSSADS),
2 STORAGE_PREFIX CHAR (8) ,
2 SSA1,
3 SSA 1 KEY CHAR (6) ,
/* DL/I SSA LIST */
3 •••
2 SSA2,
3 •••
3 ,j • • ;
/*
/*
/*
/*
/*
/*
150
DECLARE PSBNAME CHAR~) INIT ('PSBNAMEI);
DECLARE PCB_FUNCTION CHAR (8) IN IT (IPCB I);
OBTAIN PCB POINTERS */
DFHFC TYPE=(DL/I,PCB)
GET PSB FOR THIS PROGRAM
OBTAIN PCB POINTERS VIA CALL */
CALL PLITDLI (PARM_CT,PCB_FUNCTION,PSBNAME): /* GET SPECIFIED PSB */
SAVE POINTERS IN PCB BASES */
B_PCB_PTRS=TCADLPCB;
BPCB1=PCBl PTR;
BPCB2 =PCB 2:PTR ;
ACQUIRE STORAGE FOR DL/I I/O AREA */
DFHSC TYPE=GETMAIN,CLASS=USER, •••
BDLIIO=TCASCSA;
OPTIONALLY, ACQUIRE STORAGE IN WHICH TO BUILD SSA'S */
DFHSC TYPE=GETMAIN,CLASS=USER, •••
BSSADS=TCASCSA;
OPTIONALLY, BUILD SEGMENT SEARCH ARGUMENTS */
SSA1KEY=TERMKEY;
CICS/VS APRM
~L)
/*
CALL DL/I */
CALL PLITDLI(PARM_CT,DLI_FUNCTION,PCB1,IOKEY,SSA1,
SSA2) ;
/* EXAMPLE 1 OF DFHFC MACRO INSTRUCTION */
DFHFC TYPE=(DL/I,ISRT),
PCB=BPCB1,
PCB POINTER
WRKAREA=BDLIIO,
WORK AREA POINTER
SSAS=(2,SSA1,SSA2)
SSA COUNT AND NAMES
/* EXAMPLE 2 OF DFHFC MACRO INSTRUCTION */
TCADLPCB=BPCB1;
DFHFC TYPE=(DL/I,GU),
PCB PRELOADBD
SSAS=(SSA_COUNT,SSA1,SSA2)
WORK AREA TO BE ACQUIRED
SSA COUNT AND NAMES
BDLIIO=TCADLIO;
/* SAVE WORK AREA ADDRESS */
/* EXAMPLE 3 OF DFHFC MACRO INSTRUCTION */
TCADLFUN='GN';
/* PRELOAD FUNCTION */
TCADLIO=BDLIIO;
/* PRELOAD WORK AREA ADDRESS */
DFHFC TYPE=DL/I,
FUNCTION PRELOADED
PCB=BPCB1,
PCB POINTER
WRKAREA=YES,
WORK AREA ADDRESS PRELOAD ED
SSAS=NO
NO SSA'S
*
*
*
*
*
*
*
*
When using the PL/I Optimizing Compiler, all SSAs used in DFHFC calls
and all parameters used in CALLs must be defined as elementary items.
This can be done by defining structures based on the same pointers as
the structures containing the nonelementary definitions.
DECLARE 1 DLI_CALL_SSADS BASED (BSSADS),
2 STORAGE_PREFIX CHAR(8),
2 CALL_SSA1
CHAR( ••• ),
2 CALL_SSA2
CHAR( ••• );
/* SET UP SSA1 AND USE IN CALL */
SSA1KEY=SEARCH_KEY;
DFHFC TYPE=DL/I,
SSAS=(SSA_COUNT,CALL_SSA1)
CALL PLITDLI (PARM_CT,FUNCTION,PCB1,IOKEY,CALL_SSA1);
Chapter 3.3.
DL/I Services
151
Operands of DFHFC Macro (DLtI)
DLINA=symbolic address
specifies the entry label of the user-written routine to which
control is passed i f the CICS/VS-DL/I interface is inactive.
FUNCNS=symbolic address
specifies the entry label of the user-written routine to which
control is passed if a DL/I function request (a request other
than PCB or TERM) is made and the task has no PSB scheduled.
INVREQ=symbolic address
specifies the entry label of the user-written routine to which
control is passed if: (1) a DLINA, FUNCNS, LANGCON, PSBFAIL,
PSBNA, PSBNF, PSBSCH, TASKNA, or TERMNS condition occurs and
the associated operand is omitted, or (2) an error condition is
detected. The errors which may be detected are: (a) the
required data base is not in the PCT, (b) the required data
base is not open according to the PCT, or (c) an invalid
argument was passed to DL/I. If an INVREQ condition occurs and
the INVREQ and an associated expansion operand(s) are both
omitted, processing continues with the next sequential
instruction in the application program.
LANGCON=symbolic address (CICS/DOS/VS only)
specifies the entry label of the user-written routine to which
control is passed if the calling program is in a different
source language than the called PSB.
NORESP=symbolic address
specifies the entry label of the user-written routine to which
control is passed upon normal execution of the request, that
is, if the PSB is located and the PCB addresses are returned,
or when the application program regains control. The CICS/VSDL/I interface must have been able to pass control to DL/1 and
a DL/I pseudo-ABEND of the transaction cannot have occurred.
The return code in the PCB must be checked to determine whether
DL/1 was able to service the request. NORESP signifies "normal
resp onse. II If this operand is omitted, but a described
condition applies, processing continues with the next'
sequential instruction in the application program.
NOTOPEN=symbolic address
specifies the entry label of the user-written routine to which
control is passed if the data base specified in the PCB used in
this request is logically (not necessarily physically) closed.
The PCB does not contain a DL/I AI status code.
PCB=
specifies the field that contains the address of the PCB.
symbolic address
is the symbolic address of the field containing the address
of the PCB.
152
CICS/VS APRM .(1'1L)
~egister)
is valid only when Assembler language is used and is the
number of a register that contains the address of the PCB.
PSB=
specifies the name of the PSB to be scheduled for the
transaction.
'psbname '
is the name of the PSB to be used.
symbolic address
is the symbolic address of an eight-byte field containing
the name of the PSB, padded to the right with blanks.
YES
indicates that the name of the PSB has been placed in
TCADLPSB by the application program.
If this operand is omitted, the name of the program
associated with the transaction in the CICS/VS program
control table (PCT) is used as the PSB name.
PSBFAIL=symbolic address
specifies the entry label of the usee-written routine to which
control is passed if the PSB fails to initialize.
PSBNA=symbolic address (CICS/DOS/VS only)
specifies the entry label of the usee-written routine to which
control is passed if the task is not authorized to access this
PSB.
PSBNF=symbolic address
specifies the entry label of the user-written routine to which
control is passed if the PSB cannot be found in the PSB
directory.
PSBSCH=symbolic address
specifies the entry laoel of the usee-written routine to which
control is passed if a PSB is already scheduled for this task.
SSALIST=
indicates whether or not segment seaech arguments are used in
this request and if so, identifies the list containing these
arguments.
YES
indicates that a list of segment search arguments is used
and that the address of the list has been placed in
TCADLSSA by the application progeam.
NO
indicates that no SSA list is used in this request.
symbolic address
is the symbolic address of a field that contains the
address of the SSA list.
Chapter 3.3.
DL/I Services
153
(register)
is valid only when Assembler language is used and is the
number of a register that contains the address of the SSA
list.
If this operand is specified, SSAS cannot be specified.
SSAS=
indicates whether or not segment search arguments are used in
this request and, if so, identifies them.
NO
'indicates that no SSAs are used in this request.
([ ssacount ][ ,ssa 1 ][ ,ssa2 , ..... ])
specifies the names of segment search arguments used in
this request (thereby creating an SSA list). The ssacount
parameter specifies the number of SSAs to be used; it is
the address of a fullword containing the count, or, in the
case of Assembler language, may be expressed as a numeric
value. Each ssa specification represents an element of the
SSA list. The first element of an SSA list, or it may
point to.a fullword containing this count; the remaining
elements represent addresses of SSAs. If the first element
of an SSA list is not a count; all elements of the SSA list
are assumed to be addresses of SSAs; the high-order bit of
the last element of the list must be set on to indicate the
end 0 f the list.
([ (register 1) ][ , (register2) , ~ •• ])
is interpreted as described above; that is, register1
contains a count of the SSAs in the list or is the first
~ist entry, register2 is the first or second list entry
(depending on whether a count has been specified), and so
on.
If this operand is specified, SSALIST cannot be specified.
TASKNA=symbolic address (CrCS/DOS/VS only)
specifies the entry label of the user-written routine to which
control is passed if the calling task is not authorized to
access DL/I data bases.
TERMNS=symbolic address
specifies the entry label of the user-written routine to which
control is passed if a termination request is made and the task
has no PSB scheduled.
WRKAREA=
specifies the address of the work area to be used.
symbolic address
is the symbolic address of a field that contains a pointer
to the work area.
YES
indicates that the address of the work area to be used has
been placed in TCADLIO by the application program.
154
CICS/VS APRM(ML)
(register)
is valid only when Assembler language is used and is the
number of a register that contains the address of the work
area.
If this operand is omitted and a Gxxx function is to be
performed, the CICS/VS-DL/I interface acquires storage for
the work area and returns the address of the work area at
TCADLIO~
The application program must save this address
upon return. If any other type of function is requested,
the application program must provide the work area. A work
area whose address is specified in a DPHPC macro
instruction or placed at TCADLIO prior to execution of the
DFHPC macro instruction includes the CICS/VS storage
accounting area prefix. A work area specified in a CALLDLI
or CALL statement does not.
Chapter 3.3.
DL/I Services
155
Part 4. Data Communication Operations
157
Chapter 4.1. Introduction to Data Communication Operations
This part describes the data communication operations Terminal Control
(Chapter 4.2), Basic Mapping Support (Chapter 4.3), and Batch Data
Interchange (Chapter 4.4).
The essential differences between these data communication facilities
is that terminal control is the basic method of communicating with
devices whereas both Basic Mapping Support (BMS) and Batch Data
Interchange (BDI) extend the facilities of terminal control to simplify
further the manipulation of data streams. In fact, both BMS and BDI use
terminal control facilities.
Terminal Control provides specific macros and options for particular
devices so that the application programmer can tailor his input and
output requests according to the requirements of the devices. However,
application programs written in this way are dependent on data
formatting requirements of devices and therefore the application
programmer must have detailed knowledge of the devices.
Basic Mapping Support provides macros and options that the
application programmer can use to format data in a standard manner. BMS
performs the conversion of data streams provided by the application
program to conform to the requirements of particular devices.
Conversely, data received from a device is converted by BMS to a
standard form. However, not all devices supported by CICS/VS can be
used with BMS and therefore TC must be used. Also, in some cases, the
overhead incurred to achieve data stream independence may outweigh the
advantages. The choice as to whether BMS should be used is a matter for
application design and is discussed more fully in the CICS/yS
System/Application Design Guide.
Batch Data Interchange is a set of macros that may be used either
instead of Terminal Control macros, or in conjunction with Basic Mapping
Support macros to communicate with the batch logical units of the 3190
and 3110 subsystems_
Chapter 4.1.
Introduction to Data Communication Operations
159
Chapter 4.2. Terminal Control (DFHTC Macro Instruction)
CICS/VS terminal control uses the standard access methods available with
the host operating system. The basic telecommunications access method
~TAM) is used by CICS/VS'for most start-stop and BSC terminals.
As an
option for OSjVS, the telecommunications access method (TCAM) can be
specified. The sequential access method (SA~) is used where keyboard
terminals are simulated by sequential devices such as card readers and
line printers. The virtual telecommunications access method (ACF/VTAM)
or the telecommunications access method (TCA~) is used for systems
network architecture (SNA) terminal systems.
Terminal control polls terminals to see if they have any data to
transmit, and addresses terminals by having the computer check whether
terminals are ready to receive data. Terminal control is responsible
for code translation, transaction initiation, synchronization of input
and output operations, and the line control necessary to read from or
write to a terminal. Thus, the application program is freed from having
to physically control terminals~ During processing, an application
program is connected to one terminal for one task and terminal control
monitors which task is associated with which terminal. The algorithm
used by terminal control to determine which task should be initiated is
described later in this chapter under the heading "Terminal-oriented
Task Identification." Terminal control detects and logs errors, and
also, where appropriate, inserts a default.
Terminal control can, as its name suggests, be used for communication
with terminals. In SNA systems, however, it is used to control
communication with logical units. A logical unit (LU) represents either
a terminal directly, or a program stored in a subsystem controller which
in turn controls one or more terminals. The CICS/VS application program
communicates, by means of the logical unit, either with a terminal or
with the stored program. For example, a 3161 terminal is represented by
a single logical unit without any associated user-vritten application
program. In contrast, a 3190 SUbsystem is represented by a 3191
controller, user-written 3190 application programs, and one or more 3190
terminals; when the subsystem is configured, one or more logical units
are designated by the user.
Facilities that apply specifically to logical units are described
later in this chapter under "Facilities for Logical units".
To request terminal control services, the application programmer uses
the CICS/VS DFHTC (terminal control) macro instruction.
Among the services that can be requested by the DFHTC macro
instruction are some that are of interest to most, if not all, terminal
types supported by CICS/VS such as:
•
Write data to a terminal.
•
Read data from a terminal.
•
Synchronize
•
Converse with a terminal.
te~minal
Chapter 4.2.
input/output for a transaction.
Terminal Control (DFHTC Macro Instruction)
161
•
Read or write records to a card reader, disk data set, magnetic
tape unit, or a line printer defined by the system programmer as a
card-reader-in/line-printer-out (CRLP) terminal. This facility
allows transactions to be tested when normal communications
terminals are not available.
For additional information concerning the last of these services, see
"Sequential Terminal Support" in Chapter'7.2.
Other services available in response to DFHTC macro instructions
apply to specific types of terminal. Because many types of terminal are
supported by CICS/VS, many special services are provided.
(For a list
of terminals supported by CICSjVS, see the publication CICS/VS General
Information.) The following list is representative of the terminaloriented input/output services available:
•
Read the entire contents of a buffer (3270 Information Display
System) •
•
Read a message containing both uppercase and lowercase data (3270
Information Display System).
•
Print out the contents of an information display buffer on a
printer (3270 Information Display System) •
•
Transmit a message to a common buffer (2980 General Banking
System) •
•
Read or write data in transparent mode, that
translation (System/?, System/370, System/3,
Communication System, 2780 Data Transmission
Communication System ~TAM), 3740 Data Entry
Communications Terminal) •
•
Use the attention key to interrupt a write operation or signal a
read attention request (for example, on the 2741 Communication
Terminal) •
is, without
2770 Data
Terminal, 3600 Finance
System, 3780 Data
The general form of the terminal control macro instruction (DFHTC)
resembles that of other CICS/VS macro instructions. Keyword operands
are specified separated by commas. Although most CICS/VS macro
instructions use only one entry following the keyword TYPE, the DFHTC
macro instruction can contain several. The
DFHTC TIPE=(WRITE,READ)
macro instruction, for example, causes a write to the terminal, a wait
for that write to be completed (an implied wait), and a read from the
terminal to which data has just been written.
Another example is the
DFHTC TIPE=(ERASE,WRITE,READ,WAIT)
macro instruction, which causes an erase and then a write to a terminal,
followed by an implied wait, followed by a read and a requested wait.
The latter wait ensures that the read is complete before control is
returned to the application program.
Two separate DFBTC macros must be used when two options that would be
incompatible for the same macro are needed. Examples of incompatible
options are:
162
CICS/VS APRM (ML)
DFHTC TYPE=(READ,WRITE)
DFHTC TYPE=(WRITE,PRINT)
DFHTC TYPE=(WRITE,READB)
DFHTC TYPE=(PRINT,READ)
In such cases, the first macro should include the WAIT option; for
example:
DFHTC TYPE=(WRITE,WAIT)
DPHTC TYPE=READB
As in other CICS/VS macro instruction operands, if only one entry is
given in the TYPE operand, no parentheses are necessary.
The application programmer must determine the combination of keywords
that follow TYPE=, depending on the terminal (and sometimes, access
method) used and the operations required. Additional operands may be
required or desired, again depending upon the terminal and access method
used. Some common input/output requests are discussed later in this
chapter ..
Before using the DFHTC macro instruction to request terminal
services, the application program must include instructions that:
1.
Symbolically define the TCTTE and TIOA by copying the appropriate
storage definitions (DPHTCTTE and DFHTIOA) provided by CICS/VS.
(It is assumed that the storage definitions for the CSA and TCA
have already been copied, as described in Part 2.)
2.
Establish addressability for the TCTTE by specifying a symbolic
base address.
If using the Assembler-language or COBOL, the
application programmer must obtain the base address of the TCTTE
from TCAPCAAA and place it in TCTTEAR; with PL/I, addressability
for the TCTTE is established automatically.
Any field in the TCTTE
can then be accessed by field name. Addressability for the TIOA
must be established each time a DFHTC TYPE=READ or TYPE=WRITE macro
is issued. The ways of doing this are described in the following
section.
Facilities for all Terminals and Logical Units
The facilities described in this section apply to all terminals and
logical units. There may, however, be additional facilities that apply
to specific devices. If this is so, details are given later in this
chapter under headings for the relevant device types.
READ DATA FROM A TERMINAL OR LU
The application programmer can request that data be read from a terminal
or logical unit by issuing the
DPHTC TYPE=READ
macro instruction. This causes a read to be issued to the terminal and
the transaction to be placed in a wait state until the read completes.
Chapter
ij.
2.
Terminal Control (DPHTC Macro Instruction)
163
The incoming data is placed in a 'rIOA acquired by terminal control,
which places the address of the TIOA in TCTTEDA. On completion of the
read operation, the application program must copy the address from
TCTTEDA to the TIOA base address register (TIOABAR): any field in the
TIOA can then be accessed by field name.
The length of the data read into the TIOA is stored in TIOATDL.
Terminal control attempts to reuse TIOAs that have been used in
previous operations. For this purpose, it maintains a chain of TIOA
addresses anchored in the TCTTE. If no TIOA is attached to the chain,
or if the existing TIOAs are too short or are otherwise unsuitable,
terminal control acquires a new TIOA. The current TIOA, as addressed by
TCTTEDA, may be freed by terminal control unless the SAVE operand is
specified.
A new TIOA is also acquired by terminal control for the read when the
DFHTC TYPE=(READ,SAVE)
macro instruction is issued. All TIOAs currently chained off the TCTTB
are retained and may subsequently be reused; a new TIOA is dynamically
acquired for this read and is added to the chain.
A write, followed by a read operation, can be specified in a single
request. See "Write DATA and READ Response", later in this chapter.
When a TIOA which was previously obtained as a line input-output area
(LIOA) by the terminal control program (TCP) is passed to a user task,
the contents of the data part cannot be guaranteed beyond the data
length supplied in TIOATDL. Therefore users should not attempt to
interrogate the contents of a TIOA beyond this supplied length.
When the contents of a 3210 buffer are read (by using DFHTC
TYPE=READB), the programmer should be aware that the attention
identifier byte and the cursor address are made available at TCTTEAID
and TCTTECAD respectively_ A set of standard symbolic names for testing
the 3210 attention identifier is provided in a copy book called DFHAID.
For further details refer to "Standard Attention Identifier List
(DFHAID)" in Chapter q.3. "Basic Mapping Support".
WRITE DATA TO A TERMINAL OR LU
A request for data to be written to a terminal or logical unit can be
issued using the
DFHTC TYPE=WRITE
macro instruction. Before issuing this macro instruction, the
application program must acquire a TIOA in which to build the data to be
transmitted, and must place the address of the TIOA in TCTTEDA and the
length of the data to be written in TIOATDL. The maximum data length is
32,761 bytes which includes the length of the function management header
~MH) when writing to a logical unit.
The required TIOA is acquired by a DFHSC TYPE=GETMAIN,CLASS=TEBKIHAL
macro instruction. CICS/VS places the address of the TIOA in TCASCS!,
from where it must be copied into the TIOA base address register
(TIOABAR) •
164
CICS/VS APRM(ML)
The application program must not change the contents of TCTTEDA until
after the I/O operation has completed. The operation will only be
complete when another terminal control request has been issued (that is,
TYPE=WAIT or TYPE=READ) •
If WAIT is not specified on a terminal control TYPE=WRITE operation,
the operation may be deferred until the next terminal control request.
When the next terminal control request is issued, the SNA flows are
optimized before the actual I/O is issued. For example, a terminal
control write followed by a terminal control read could cause two flo~s
to be sent, whereas only one flow is sent if it can be determined that
the next operation is a read request.
When writing data to a 3600 (non-pipeline) or 3790 inquiry logical
unit, the CICS/VS application program must not put data into the first
three bytes of the TIOA, unless it is building its own FMH (see
ItFunction Management Header" later in this chapter). The FMH is built
either by CICS/VS or by the CICS/VS application program.
When the write operation is completed by terminal control, the TIOA
is released to a dynamic storage pool (unless SAVE is specified) •
Subsequent reference to this TIOA by the application program will
produce unpredictable results.
However, a TIO! can be reused by the application program after a
write if the request to write data to a terminal uses the
DFHTC TYPE=(WRITE,SAVE,WAIT)
macro instruction~ In this case, the TIOA is not released by terminal
control. The WAIT parameter ensures that the write of the TIOA is
complete before the area is reused. Note that the SAVE operand does not
guarantee that the field TCTTEDA addresses the TIOA saved, but only that
the TIOA is not freed.
If a dump of the TIOA is required following a terminal control write,
the SAVE and WAIT operands should be included with the DFHTC TYPE=WRITE
macro instruction that precedes the DFHDC macro instruction.
WRITE DATA AND READ REPLY
As stated earlier, a write followed by a read operation can be specified
in a single request by issuing the
DFHTC TYPE=(WRITE,READ)
macro instruction. A typical use for this macro instruction occurs in a
conversational environment in which the application program writes a
question to the terminal, waits for a reply, and subsequently reads the
reply. Because the SAVE parameter is not specified, terminal control
can reuse the TIOA (from which data is written) as a TIOA for the input
data. Under certain conditions, however, a new TIOA is obtained for the
read operation, for example:
•
Local 3270 terminals.
•
PSEUDOBIN specified with READ, WRITE.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
165
•
The TIOA length for the WRITE instruction less than that specified
by the system programmer in the DFHTCT TYPE=TERMINAL,TIOAL=length
specification (binary synchronous terminals) or in the DFHTCT
TYPE=LINE,INAREAL=length specification (all other terminals).
•
Certain error conditions.
•
A 3270 terminal used in 2260 compatibility mode.
The user should alway§ reload TIOABAR from TCTTEDA following the
(WRITE,READ) macro instruction.
For a terminal connected to the 7770 Audio Response Unit, a read
request that does not include the WRITE parameter causes the "ready"
message (defined in the terminal control table by the system programmer)
to be written to the terminal before the read operation occurs.
If both a write and a read operation are specified in a single
request by issuing
DFHTC TYPE=(WRITE,READ,SAVE)
the TIOA used for writing is saved; a new TIOA is then acquired by
terminal control for the read. The size of the TIOA is determined by
the system programmer when specifying the TCTTE for the terminal (rather
than by the size of the TIOA used for the write). If the saved TIOA is
reused later for either writing or reading, the application program must
place the address of the TIOA into TCTTEDA prior to issuing the request
to use the area.
The manner in which the address of a TIOA is "remembered" is the
application programmer's responsibility.
Upon completion of a (WRITE,READ,SAVE) , place the value at TCTTEDA
into TIOABAR to establish addressability for the newly-acquired TIOA.
SYNCHRONIZE TERMINAL I/O
(WAIT)
In a task under which more than one terminal or logical unit operation
is performed, the application programmer must ensure that a current
terminal operation is complete before another begins. Therefore, after
a terminal control write has been issued, but before another terminal
control write can be issued, a terminal control wait must be issued.
TcrTEDA can be changed to point to the new TIOA for output, and the next
terminal control write can be issued. For SNA logical units, after a
terminal control write has been issued, the next operation may be either
a terminal control wait, or a terminal control read, according to
whether a subsequent write, or terminal control read is to be issued.
To do this the
DFHTC TYPE=W AIT
macro instruction is issued, where the WAIT parameter is coded
separately, as shown, or in combination with READ or WRITE. A PUT can
be coded in place of a (WRITE,WAIT); a GET can be coded in place of a
(READ ,WAIT) • A terminal control read operation forces a wait to occur
before the transaction is resumed, that is, the data will be available
in the TIOA addressed by TCTTEDA at completion of the terminal control
read operation.
166
CICS/VS APRM(ML)
A wait may cause execution of a task to be suspended. If suspension
is necessary, control is returned to CICS/VS. Execution of the task is
resumed when the write is posted complete~
A wait need not be coded for a write if the write is the last
terminal operation of the transaction~ The TIOA is retained until the
data is written, even if the transaction and its associated storage are
deleted from the system before the write occurs.
CONVERSE WITH A TERMINAL OR LU
To request a conversational mode of communication with a terminal or
loqical unit, issue the
DFHTC TYPE=CONVERSE
macro instruction, where CONVERSB (or CONV) is the same as
(WRITE,READ,WAIT). This instruction is always executed in the sequence:
WRITE, implied wait, READ, WAIT.
It is possible, for most devices, to use this macro instruction
rather than TYPE=READ, but it must not be used for the 3600 or 3650
pipeline logical units. However, its use is recommended for all other
logical units.
DISCONNECT A SWITCHED LINE
To break a line connection between a terminal or logical unit and a host
CPU, the
DFHTC TYPE=DISCONNECT
macro instruction is used. This applies only to devices operating on
switched lines or to logical units. When used with logical units,
DISCONNECT, which does not become effective until the task has been
terminated, terminates the session, without causing a physical
disconnection.
Note: CICS/OS/VS implements DISCONNECT for World Trade Teletype
Terminals by writing a message to the terminal indicating that the
terminal operator should manually disconnect.
Examples
The following examples show the coding required to:
1.
Acquire storage for use as a terminal input/output area through the
DPHSC macro instruction.
2.
Place the address of the acquired area into TCTTEDA.
3.
Place the length of the data to be written into TIOATDL.
Chapter 4.2.
Terminal Control
~PHTC
Macro Instruction)
167
ij.
Issue a terminal control macro instruction to a 3270 terminal, thus
erasing the screen, returning the cursor to the upper left corner
of the screen, writing to the terminal, and reading from the
terminal (allowing terminal control to manage storage for the
TIOA) •
5.
Establish addressability to the
~IOA
into which the data was read •
...,
For Assembler Language
J,
DFHSC
L
ST
MVC
MVC
TCTTEAR,TCAFCAAA
TYPE=GETMAIN,
NUMBYTE=80,
CLASS=TERMINAL
TIOABAR ,TCASCSA
TIOABAR,TCTTEDA
TIOADBA ~O),DATA
TIOATDL,=H '80'
TYPE=(WRITE,ERASE,
READ, WAIT)
TIO AB AR, TCTTEDA
DFHTC
L
ESTABLISH ADDRESSABILITY FOR TCTTE
OBTAIN TIOA FOR OUTPUT DATA
*
*
ADDRESS OF TIOA
PLACE OUTPUT ADDRESS IN TCTTE
PLACE DATA IN TIOA
PLACE DATA LENGTH IN TIOATDL
ERASE SCREEN, WRITE TO
TERMINAL, THEN READ
ESTABLISH ADDRESSABILITY FOR TIOA
*
For COBOL:
MOVE TCAFCAAA TO TCTTEAR.
DFHSC
TYPE=GETMAIN,
NUMBYTE=80,
CLASS=TERMINAL
TCASCSA TO TIOABAR.
MOVE
TIOABAR TO TCTTEDA.
MOVE
DATA TO TIOADATA.
MOVE
NOTE EST ADDRESSABILITY FOR TCTTE.
OBTAIN TIOA FOR OUTPUT DATA
*
*
NOTE
NOTE
NOTE
USER
NOTE
ADDRESS OF
PLACE ADDR
PLACE DATA
DEFINED) •
PLACE DATA
TIOA
OF TIOA IN TCTTE.
IN TIOA ~IOADATA IS
LENGTH IN TIOATDL.
MOVE
80 TO TIOATDL.
DFHTC
TYPE=(WRITE,ERASE, ERASE SCREEN, WRITE TO
READ,WAIT)
TERMINAL, THEN READ
TCTTEDA TO TIOABAR. NOTE EST ADDRESSABILITY FOR TIOl.
MOVE
*
1:QLPL/I.=..
TCTTEAR=TCAFCAAA;
DFHSC
TYPE=GETMAIN,
NUMBYTE=80,
CLASS=TERMINAL
TIOABAR=TCASCSA;
TCTTEDA=TIOABAR;
TIODATA=DATA;
TIOATDL=80;
/*EST ADDRESSABILITY FOR TCTTE*/
OBTAIN TIOA FOR OUTPUT DATA
*
*
/*ADDRESS OF TIOA*/
/*PLACE ADDR OF TIOA IN TCTTE*/
/*PLACE DATA IN TIOA (TIODATA IS
USER-DEFINED)*/
I*PLACE DATA LENGTH IN TIOATDL*I
..
DFHTC
TYPE=(WRITE,ERASE,
READ ,WAIT)
TIOBAR=TCTTEDA;
168
CICS/VS APR!! (ML)
ERASE SCREEN, WRITE TO
TERMINAL, THEN READ
/*EST ADDRESSABILITY FOR TIOA*/
*
Facilities for Logical Units
A CICS/VS application program communicates with a TCAM, VTAM, or EXTM
logical unit in much the same way that it does with BTAM or TCAM
terminals (that is, by using the various forms of the DFHTC macro
instruction described above). However, communication with logical units
is governed by the conventions (protocols) that apply to each type of
logical unit. This section describes the additional facilities provided
by CICS/VS to enable the application programmer to comply with these
protocols.
The types of logical units and the related protocols for each of the
SNA subsystems supported by CICS/VS are described in the CICS/VS
subsystem guides for the IBM 3270, IBM 3600/3630, IBM 3650, IBM
3767/3770 and the IBM 3790 (see Bibliography).
SEND/RECEIVE MODE
Por SNA logical units, a transaction conversing with such a logical unit
must conform to the send/receive protocols of SNA, unless the read-ahead
queueing feature has been specified.
However, a transaction is normally in send mode and can issue any
terminal control request. For displays (for example, the 3270), the
send/receive mode is transparent to the application program, but for
logical units that perform chaining, or make use of the full SNA
.
protocols (for example, the 3767), the send/receive mode should be taken
into account.
If the application program is in receive mode, flag TCTEURCV in field
TCTERCVI is set on, and the application program must continue to issue
terminal control READ requests.
For compatibility, the read-ahead queueing feature (RAQ=YES specified
in the DFHSG PROGRAM=TCP system macro) is provided so that the
application program is independent of the send/receive mode. However,
it is recommended that application programs be changed to use SNA
send/receive protocols and that, wherever possible, they specify RAQ=NO.
OVERLAPPING LOGICAL-UNIT OUTPUT
Write operations are not initiated until a subsequent terminal control
operation to the logical unit is issued, a syncpoint is taken, or the
task terminates.
If a terminal control write operation is awaiting completion, a
terminal control wait should be issued unless the next operation is a
read request, in which case a terminal control read can be issued
directly.
A terminal control write and wait request causes the operation to be
initiated immediately. If only a terminal control write is issued, the
operation is delayed until the next operation so that SNA flow handling
can be improved.
The point at which a wait is satisfied depends upon whether task
protection, message integrity, or DEFRESP=YES is requested for the task.
Task protection and message integrity are specified, by the system
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
169
in the DFBPCT macro instruction; if data is sent with task
protection or message integrity, a wait is completed when a logical unit
responds to the write request; otherwise, the wait is completed after
VTAM has accepted the output request.
program~er,
If a task is operating under task protection or message integrity and
an exception response is returned for an output request, the output
message is still available in the TIOA. The node error program (NEP)
can therefore request that the operation be retried as many times as
specified by the installation.
CHAINING OF INPUT DATA
For transmission purposes, data handled by a logical unit is divided
into request/response units (RUs). The data may be transmitted as one
or more RUs, called a chain, depending on the length of the data, and on
the ~aximum size of the RU defined for the logical unit or that has been
defined for the terminal network in general.
Each RU contains a set of indicators that specify whether the RU is
the first, middle, or end, of the chain (FOC, MaC, or EOC,
respectively). If the chain consists of only one RU, this RU contains
both the FOC and the EOC indicators.
Data is transmitted as a chain of one or more RUs from a logical unit
to the application program. If the chain contains more than one RU,
further read requests are required, one for each RU, unless chain
assembly has been specified. (Chain assembly is described later in this
chapter.) The length of each RU must be less than or equal to the
maximum RU size.
The EOC operand of the DFHTC TYPB=RBAD macro is used to test for the
presence of the EOC indicator. If it is present, that is, the complete
chain has been received, control is passed to a user-written routine
that provides additional processing.
For some logical units, the data transmitted may contain a function
management header (FMH), in which case, inbound-FMH processing will take
precedence over BOC processing. (Inbound FMH is described later in this
chapter.)
Furtlier, if the FMH indicates the end of the data set, control will
be passed to the BODS routine instead of to the INBFMH or EOC routines.
THe DFHTC TYPB=WAIT macro with the BOC operand specifies that control is
to be passed to an EOC routine from within either the inbound FMH or the
EODS routine.
An PMH may also occur in the first RU of a chain that contains more
than one RU. In this case, control is passed to the INBFMH routine when
a DFHTC TYPE=READ is satisfied by that RU.
The application program must read all the data from the logical unit,
that is, it should not terminate ~xcept abnormally) before BOC has been
received. Application programs should also ensure that the complete
data stream has been received from the logical unit; this will be
ensured as long as the application program is not in receive mode when
it terminates.
170
CICS/VS APRM(ML)
CHAINING OF OUTPUT DATA
As in the case of input data, output data is transmitted as
request/response units (RUs)~ If the length of the data supplied in the
TIOA exceeds the RU size, CICS/VS automatically breaks up the data into
RUs and transmits these RUs as a chain. During transmission from
CICS/VS to the logical unit, the RUs are marked FOC, MOC, or EOC to
denote their position in the chain. An RU that is the only one in a
chain is marked OC (only-in-chain).
If the system programmer specified that the application program can
control the chaining of outbound data, the application program can
inhibit the end-of-chain marker on the last (or only) RU resulting from
the write request by including the CCOMPL=NO operand (specifying that
the chain is not yet complete). The data supplied in the TIOA for the
next write request is treated as a continuation of the chain.
CHAIN ASSEMBLY
Chain assembly, which is specified by the system programmer in the
TC'rTE, is the proce ss of assembling RU s together to form a chain which
is transmitted as an entity to the application program in a single TIOA
in response to a single read request. This ensures the integrity of the
whole chain prior to presentation to the application program. If the
EOC operand is specified in the read request, the EOC routine receives
control for every read request (except when an FMH is received and the
appropriate EODS or INBFMH routine is specified, as described earlier in
this chapter under "Chaining of Input Data".)
The length of the TIOA required to accommodate a chain is unknown
since a chain can consist of any number of RUs. To allow for this, two
TIOA lengths can be specified in the TCTTE by the system programmer.
The first length specifies a TIOA that will normally be provided. The
second specifies a larger TIOA for use when the normal TIOA is not large
enough. If the larger TIOA cannot hold the complete chain, the node
abnormal condition program ~FHZNAC) is invoked and the task is
terminated abnormally. Additional processing of the chain can, however,
be initiated by the node error program (DFHZNEP) when a further read
request will ne needed to cause transmission of the rest of the chain.
The use of two TIOA sizes minimizes storage requirements.
Chain assembly is recommended for most interactive applications,
since the input data is usually made up of a chain of more than one RU.
In many cases the application program logic is simplified by use of this
option.
LOGICAL RECORD PRESENTATION
Normally a chain contains the data to be processed and this chain is
presented to the application program in a TIOA as specified in the
TCTTE.
In some cases, however, the chain contains many logical entities for
processing. These may be each RU itself, or the RUs may be further
subdivided into logical records delimited by inter-record separator
control characters, or new line characters.
Chapter ij.2.
Terminal Control (DFHTC Macro Instruction)
171
The entire RU will be presented to the application program if chain
assembly is not specified in the TCTTE. However, if the data stream is
delimited by separators into logical records, the system programmer can
specify in the PCT that logical records will be presented to the
application program instead of RUs or chains, so overriding on an
application basis the TCTTE options for the logical unit.
If the RU contains more than one logical record, the records will be
separated by NL (new line), IRS (inter-record separator), or TRN
~ransparent) characters.
Except in the case of LUTYPE4, one logical
record cannot be transmitted in more than one RU; the end of the RU is
always the end of the logical record. Data from an LUTYPE4 unit may
contain logical records that span RUS, in which case chain assembly
should be specified.
Since a card reader inserts an IRS character after the last non-blank
character on the card, the user may receive card images that are less
than 80 characters in length. Conversely, a series of full cards will
begin at 81-character intervals~
For those application programs for which this option is specified,
each read request results in one logical record being presented to the
application program in a TIO!, regardless of whether chain assembly is
specified or not. If the logical records are separated by IRS or TRN
characters, these are removed, and do not appear in the TIOA.
Therefore, a blank card will appear as a TIOA with a length of zero. If
NL characters are used to separate the logical records, they are not
removed, and the NL character from the end of each logical record
appears at the end of the TIOA. All the previously-described
communication features are still in operation. That is, notification of
end-of-chain conditions, and ~or batch logical units only) notification
of end-of-data-set conditions and presentation of the inbound FMH at the
beginning of a chain, still occurs.
If chain assembly has been specified, a logical record ends with a
delimiter (either NL, IRS, or TRN), or the end of the assembled chain.
The end of chain notification is given with the last logical record of
the chain.
DEFINITE RESPONSE
The type of response requested by CICS/VS for outbound data is generally
determined by the system programmer whe"n generating the PCT. The system
programmer can specify that all outbound data for an application program
will require a definite response, or allow the exception-response
protocol to be used, which means that a response will be made only if an
error situation occurs.
The use of definite-response protocol has some performance
disadvantages, but may be necessary for some application programs. To
provide a more flexible method of specifying the protocol to be used,
the DEFRESP operand is provided for use on the DFHTC TYPE=WRITE macro
instruction~
One example of the use of this operand is to request a
definite response for every tenth write request, exception response
being the general rule.
Because a response cannot be received until the whole chain has been
sent, the DEFRESP operand and the CCO!PL=NO operand are mutually
exclusive. The DEFRESP operand and the ERASE operand are also mutually
exclusive.
112
CICS/VS APRM (ML)
FUNCTION MANAGEMENT HEADER (FMH)
A function management header (FMH) is a field that can be included at
the beginning of an input or output message. It is used to convey
information about the message and how it should be handled.
For some logical units, the use of an FMH is mandatory, for others it
is optional, and in some cases FMRs cannot be used at all.
For output, the FMH can be built by the application program or by
CICS/VS. For input, the FHH can be passed to the application program or
it can be suppressed by CICS/VS.
The rules governing the use of FMRs for each type of logical unit,
and the formats of the FMHs, are given in the CICS/VS subsystem guides
(for example, the CICSIVS IBM 3790 Guide), which are listed in the
Bibliography.
Inbound FMR
The CICS/VS application program can request notification when an FMH is
included in the data received during a read from a logical unit; when
present, the FMR is at the start of the TIOA.
Whether or not inbound FMHs will be passed to the application program
is specified by the system programmer in the PCT. It can be specified
that no inbound FMHs will be passed, or that only the FHR indicating end
of data set (EODS) will be passed, or that all inbound FMHs will be
passed, or that the data interchange program ~FRDIP) will process the
FMH ..
The INBFMR operand of the DFHTC TYPE=READ or WAIT macro instruction
specifies that control is to be passed to a user-written routine
whenever an inbound FMH is received.
Use of the INBFMR operand implies
that the WAIT option of the TYPE operand is in effect.
The user-written routine can
depending on, for example, from
routine then scans the TIOA for
the data is initial data from a
identification will start after
examine the FMR and take some action
which device the data has come. The
input data, starting after the FMH. If
logical unit, the transaction
the FMR.
When input data is received as a chain of RUs, only the first (or
only) RU of the chain contains an FMR.
Some logical units require or
by means of an FMH. For 3600
units, CICS/VS will build the
reserve space in the TIOA for
other type of logical unit.
allow control information to be specified
(non-pipeline) and 3790 inquiry logical
FMH, but the application program must
it. CICS/VS will not build on FMH for any
If the FMH is to be built by the application program, the write
request must specify FMR=YES. The FMR must start at the beginning of
the TIOA.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
173
END OF DATA SET (EODS)
The DFHTC TYPE=EOOS macro specifies that an FMH containing an EODS
indicator is sent to a 3650 interpreter logical unit. This FMH delimits
the output. The end of the input is detected similarly by the EODS
operand of a OFHTC TYPE=READ macro.
LOGICAL DEVICE CODE (LDC)
A logical device code (LDC) is a code that can be included in an
outbound FMH to specify the disposition of the data (for example, to
which subsystem terminal it should be sent) •
An LDC is a CICS/VS-supported and installation-defined logical device
code. Each code can be represented by a unique LOC mnemonic. The
installation can specify up to 256 two-character mnemonics for each
TCTTE, and two or more TCTTEs can share a list of these mnemonics.
Corresponding to each LDC mnemonic for each TCTTE is'a numeric value
(the LOC itself whose code value can range from 0 to 255). A device
type and a logical page size are also associated with each LDC. "LDC"
or "LDC value" is used in this publication to refer to the code
specified by the use r. .. LOC mnemonic" ref ars to th e two-character
symbol that represents the LDC numeric value.
Within the 3601 subsystem, a user-written application program
provides the function of the logical unit. For batch and batch data
interchange logical units the functions of the logical unit are built in
and in general cannot be modified further by the user. The following
paragraphs discuss some of the functions that may be provided in a userwritten application program
When a CICS/VS application program issues a write request with the
LDC operand specified, the numeric value associated with the mnemonic
for the particular TCTTE is inserted in the FMH. The numeric value
associated with the LDC mnemonic is chosen by the installation; the
interpretation of that numeric value is the responsibility of the
subsystem application program.
As a minimum, the installation can choose a different LDC to
correspond to each device attached to the logical unit. The values
(codes) chosen for the LDC can correspond exactly to the logical device
address (LDA) for each device. The subsystem application program can
then take the CICS/VS output data and write it directly to the indicated
LDA.
LDCs can be used to provide support for multiple-form printers. When
used for these printers, each LDC within a specified range corresponds
to a particular type of form. Whenever the subsystem application
program receives data with an LDC that indicates a particular printer
and a particular form, the application program can check the device to
determine whether the correct form is currently on the printer. If the
correct form is on the printer, the application program proceeds with
the output operation. If the correct form is not on the printer, the
application program ean request the operator to load the appropriate
form and to signal when the load is completed.
Some LDCs can be used to indicate certain standard actions to be
undertaken by the application program. Using the LDC in this way can
reduce the overhead of writing messages to the subsystem application
program. An example of this use of LDCs is an instruction to the
application program to turn on specific indicator lights on a device.
174
CICS/VS APRM(ML)
A
range of LDCs can be specified for each device, each LDC within this
range corresponding to a specific light. Upon receipt of such an LDC,
the application program determines the appropriate device and indicator
and issues the commands necessary to turn on the light. Other standard
actions that can be invoked by LDCs are dumping operator totals,
checking diskettes for transaction backlogs, or indicating a change in
operational mode.
The LDC operand of the DFHTC TYPE=WRITE macro is only for use with
3600 (3601) non-pipeline logical units and provides a symbolic way of
conveying to CICS/VS the type of F~H it is to build on behalf of the
application program. Alternatively, the application program may build
its own FMH (which may be greater than three bytes) and indicate this by
means of the FMH operand.
Component or destination selection for batch and batch data
interchange logical units is accomplished by means of an F~H, the length
of which depends on the type of logical unit. The application program
must build its own FMH, or use the LDC operands of the basic mapping
support (BMS) macros DFHMSD or DFHBMS TYPE=OUT or TYPE=STORE to instruct
BMS to build the correct F~H. If the FMH is to be built by the
application program the DFHTC CTYPE=LOCATE, LDC=YES macro may be used to
symbolically obtain the component selection value to be inserted in the
appropriate FMH field. Refer to the IBM 3110 and IBM 3190 guides for a
further discussion of component selection.
UNSOLICITED INPUT
If a task is in progress and unexpected data (that is, data from a
terminal for which a read request has not been issued) arrives from a
start-stop or BSC terminal, CICSjVS ignores the data and it is lost.
If, however, unexpected data arrives from a 3600, 3650, 3161 or 3110
interactive (contention only), or 3190 inquiry logical unit, it is
queued and is used to satisfy any future input requests for that logical
unit. For the 3210 logical unit ~ut not for the 3210 LUTYPE2 logical
unit, data is queued only if PUNSOL=NO is specified in the DFHSG
PROGRAM=TCP macro; otherwise it is lost. Unsolicited input does not
occur for the other logical units.
SIGNAL COMMANDS FROM LOGICAL UNITS
Signal
by the
allows
signal
in the
entry
data-flow-control commands from the logical unit must be handled
application program. The DFHTC TYPE=SIGNAL macro instruction
an address to be specified to which control will pass when a
command is received. The associated signal code will be stored
four-byte field TCTESIDI in the terminal contro~ table terminal
(TCTTE).
If a hard reguest-change-direction (RCD) signal is received from an
LUTYPE4 unit ~ignal code = X' 00010000 ' ), the transaction should either
end or read data from the logical unit. Any attempt to write to the
unit immediately following a hard RCD would be an error, indicated by
the flag TCTERCD in the TCTTE. If a further attempt to write to the
logical unit is made, CICSjVS will abnormally terminate the transaction
with an abend code of ATCL.
Most logical units that can send a signal command with a code of
X'00010000' do so when an attention key is pressed.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
115
BRACKET PROTOCOL
The use of bracket protocol is a means of preventing interruption of the
exchange of data between CICS/VS and a logical unit. CICS/VS or the
logical unit may send begin-bracket, but only CICS/VS may send the endbracket. Brackets can delimit a conversation between CICS/VS and the
logical unit or merely the transmission of a series of data chains in
one direction.
Bracket protocol is used when CICS/VS communicates with a logical
unit. The use of brackets is usually transparent to the CICS/VS
application program.
Only on the last write operation of a task to a logical unit does the
bracket protocol become apparent to the CICS/VS application program. On
the last output request to a logical unit, the CICS/VS application
program may specify LAST in the DFHTC TYPE=WRITE macro instruction. The
last output request is defined as either the last DFHTC TYPE=WRITE macro
specified for a task without chain control; or as the write operation
that transmits the FOC or OC marker of the last chain of a transaction
with chain control.
The LAST specification causes CICS/VS to transmit an end-bracket
indicator with the final output message to the logical unit. This
indicator notifies the logical unit that tpe current transaction is
ending. If the LAST operand is not specified, CICS/VS waits until the
task detaches before sending the end-bracket indicator. Since an endbracket indicator is transmitted only with the first RU of a chain, the
LAST operand is ignored for a transaction with chain control unless FOC
or OC is also specified. Refer to the publication VTAM Concepts and
Planning for more details on bracket protocol.
116
CICS/VS APRM(ML)
Terminal-Oriented Task Identification
When CICS/VS receives input from a terminal to which no task is
attached, it has to determine which transaction should be initiated.
The methods by which the user can specify the transaction to be
initiated and the sequence in which CICS/VS checks these specifications
are as follows (see also Figure 4.2-1).
Test 1:
Is the input from a PA key (of a 3270 terminal) that has been
defined at system initialization as the print request key?
If yes, printing of the data displayed on the screen is
initiated.
Test 2:
a)
b)
Is this terminal of a type supported by the basic mapping
support terminal paging facility?
Is the input a paging command?
(The terminal operator can
enter paging commands defined by the system programmer in
the DFHSIT macro instruction. See the CICS/VS
System Programmer's Reference Manual.)
If yes to both (a) and (b), the transaction CSPG, which
processes paging commands, is initiated.
Test 3:
If an attach FMH is present in the data stream and Tests 4 and
5 are not fulfilled, the transaction specified in the attach
FHH is initiated. The architectured attach names are converted
to "CSMI".
Test 4:
Does the terminal control table entry for the terminal include
a transaction identification (specified by the TRANSID
operand of the DFHTCT macro)?
If yes, the specified transaction is initiated.
Test 5:
Is a transaction specified by the TRANSID operand of a DFHPC
TYPE=RETURN macro instruction (or by the application program
moving the transaction name into TCANXTID)?
If yes, the specified transaction is initiated.
Test 6:
a)
b)
c)
Is the terminal a 3270 (including 3270 logical unit and
3650 host-conversational (3270) logical unit, connected
via VTAM?)
Is the input from a PA key, PF key, light pen attention
(lPA) , or magnetic stripe card reader (OPID)?
Is this input ~A, PF, LPA, or OPID) specified by the
TASKREQ operand of a DFHPCT TYPE=ENTRY macro instruction?
(See the CICS/VS system Programmer's Reference Manual.)
If yes to (a), (b), and (c), the program specified by the
PROGRAM operand of same DFHPCT TYPE=ENTRY macro instruction
is given control.
Test 7:
Is a valid transaction identification specified by the first
one to four characters of the terminal input?
If yes, the specified transaction is initiated.
For all PA keys and some LPAs there cannot be terminal input.
If there is no terminal input an ninvalid transaction
identification" message is sent to the terminal.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
177
If none of the above tests is met, an invalid transaction
identification exists. Message DFH2001 is sent to the terminal.
Note: The 3735 Programmable Buffered Terminal makeS an exception to
this sequence when operating in inquiry mode. The test of input from
the terminal ~est 7 above) is given highest priority.
Initiate
Printing
Initiate CSPG
No
Initiate transaction
specified in
Attach FMH
Initiate specified
transaction
Yes
Initiate specified
transaction
Yes
Initiate transaction
Yes
specified by
terminal input AID
Send "invalid
transaction ident."
message to terminal
Figure 4.2-1.
178
Initiate transaction
specified by
terminal input
Terainal-oriented Task Identification
CICS/VS APRM(ML)
Syntax of the DFHTC Macro Instruction
This section shows the syntax of the DFHTC macro instruction available
for use with each type of device or logical unit, arranged in numerical
order.
The syntax displays for each device and for the 3270 logical unit are
followed by information specific to that device or logical unit.
However, information about 3600, 3650, 3767, 3770, and 3790 logical
units is given in the CICS/VS subsystem guides.
TCAM SUPPORTED TERMINALS AND LOGICAL UNITS (CICS/OS/VS ONLY)
Under CICS/OS/VS only, because TCAM permits many applications to share a
single network, the CICS/VS TCAM interface supports data streams rather
than specific terminals or logical units.
Operations for terminals and logical units connected through TCAM use
the same operands as the terminals and logical units connected through
the other access methods used with CICS/VS.
For input, TCAM supports only the READ And READL operations. For
output, TCAM supports only the WRITE and WRITEL operations with the
optional use of ERASE. The DEST operand can be specified for all TCAM
output operations.
(The syntax of the DFHTC macro for TCAM operations
is given later in this chapter.)
The 2260 compatibility option is not available for 3270 connected
through TCAM.
3650 logical units cannot be connected through TCAM.
BTAM PROGRAMMABLE DEVICES
When BTAM is used by CICS/VS for programmable binary synchronous
communication line management, CICS/VS initializes the communication
line with a BTAM read initial (TI); the terminal response must be a
write initial (TI) or the equivalent. If a user-written application
program then issues a read, CICS/VS issues a read continue (TT) to that
line; if the application program issues a write, CICS/VS issues a read
interrupt (RVI) to that line. If end of transmission (EOT) is not
received on the RVI, CICS/VS issues a read continu-e (TT) until the EOT is
received. When TCAM is used, all of this line control is handled by the
MCP rather than by CICS/VS.
The programmable terminal response to a read interrupt must be nend
of transmission" (EOT). The EOT response may, however, be preceded by
writes, in order to exhaust the contents of output buffers; this is
provided the input Duffer size is not exceeded by this data. The input
buffer size is specified by the system programmer during preparation of
the terminal control table. CICS/VS issues a read continue until it
receives an EOT, or until the input message exceeds the size of the
input buffer ~n error condition).
After receiving an EOT, CICS/VS issues a write initial (TI) or the
equivalent (depending on the type of line). The programmable terminal
response must be a read initial (TI) or the equivalent.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
179
If another write is issued by the application program, CICS/VS issues
a write continue (TT) to that line. If the application program issues a
read after it has issued a write, CICS/VS turns the line around with a
write reset (TR).
(CIeS/VS does not recognize a read interrupt.)
When CICS/VS initiates a transaction using the automatic transaction
initiation facility, it first of all issues a write initial (TI) or the
equivalent. The terminal must respond with a read initial (TI) or the
equivalent. Reading from or writing to the terminal can then continue
as if the write initial had been caused by a write instruction in the
application program.
To ensure that binary synchronous terminals (for example, System/310,
1130, 2180) remain coordinated, CICS/VS processes the data collection or
data transmission transaction on any line to completion, before polling
other terminals on that line.
The programmable terminal actions required for the above activity,
with the corresponding user application program macro instructions and
CICS/VS actions, are summarized as follows:
CICS/VS (note 1)
Programmable
Terminal Program
Read initial (TI)
write initial (TI)
DFHTC TYPE=READ
Read continue (TT)
Write continue (TT)
DFHTC TYPE=WRITE (note 2)
(note 3)
Read interrupt (RVI)
Read continue (TT)
write initial (TI)
write reset (TR) , or
write continue
write reset
Read initial (TI)
DFHTC TYPE=WRITE
Wr i te cont in ue (TT)
Read continue (TT)
DFHTC TYPE=READ (note 4)
write reset (TR)
Read initial (TI)
Read continue (TT)
Write initial (TI)
Application Program
Notes:
1.
CICS/VS issues the macro instruction shown, or, if the line is
switched, the equivalent. The user-written programmable terminal
program must issue the equivalent of the BTAM operation shown.
2.
An RVI sequence is indicated by the DECFLAGS field of the data
extent control block (DECB) being set to X'02' and a completion
code of X'1FI being returned to the event control block (ECB).
3.
The read continue is issued only if the EOT character is not
received on the read interrupt.
4.
write reset is issued only for point-to-point terminals.
Input data is deblocked to ETX, ETB, RS, and US characters. These
characters are moved with the data to the TIOA but are not included in
the data length (TIOATDL). The CICS/VS application programmer should be
aware that characters such as NL, CR, LF, and EM are passed in the TIOA
as data.
180
CICS/VS APRM(ML)
TELETYPEWRITER PROGRAMMING
The teletypewriter (World Trade only) uses two different control
characters for print formatting:
ex
<
carriage return,
-
line feed, (X128 1 in ITA2 code or XI 25 1 in EBCDIC)
I
22' in ITA2 code or X115' in EBCDIC)
The application programmer should always use < first; that is <= or
<===., but never =.<, otherwise following characters (data) may be printed
while the typebar is moving to the left.
Message Format
aessage B~in: To start a message on a new line at the left margin, the
message text must begin with XI 1511 1 (EBCDIC). CICS/VS recognizes the
XI 17' and changes it to XI 25' (X '17 1 is an idle character).
Message Body: To write several lines with a single transmission, the
lines must be separated by X1 1525 1 , or if multiple blank lines are
required, by XI 152525 ••• 25'.
Message End before Next Input: To allow input of the next message on a
line at the left margin, the preceding message must end with X'1511'.
CICSjVS recognizes X'15 1 and changes the character following it to
XI 25' •
Message End before Next Output: In the case of two or more successive
output messages, the message begin and the message end look the same;
that is XI 1511', except for the last message ~ee above). To make the
message end of the preceding message distinguishable from the message
begin of the next message, the penultimate character of the message end
must not be X115 1 •
Message Length.
It is recommended that messages for teletypewriter terminals, do not
exceed a length of about 3000 bytes or approximately 300 words.
CONNECTION THROUGH VTAM
Both the TWX Model 33/35 Common Carrier Teletypewriter Exchange and the
WTTY Teletypewriter (World Trade only) can be connected to CICS/VS
through BTAM, or through VTAM using NTO.
If a device is connected through VTAM using NTO, the protocols used
are the same as for the 3167 logical unit, and the application program
can make use of these protocols. However, the data stream is not
translated to a 3167 data stream but remains as that for a TWX iTTY.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
181
System/3
r-
r--------------.---------------------------------------~
I
I
I,
I
DFHTC I TYPE=(READ[,SAVE])
,I
I
I
,
I
I
I ______
L
DFHTC
I~
_____
TYPE=(WRITE[,WAITX ,SAVE][,TRANSPARENT])
[ ,DEST= {symbolic address I YES} ]->TCA! only
[,ENDMSG=NO]
~
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~
I
I
I
DFHTC
IL ______ '--______
TYPE= {DISCONNECT IRESET}
,~
_______________________________________________________'
TYPE=DISCONNECT applies to switched line System/3s only.
System/370
Support and macro instruction syntax identical to System/3.
182
CICS/VS APRM
~L)
System/7
DFHTC
L _______
~
_______
TYPE=(READ[,WAIT][,SAVE]
[ , {TRANSPARENT IPSEUDOBIN} ])
~
________________________________________________________
DFHTC
~
TYPE=(WRITE[,WAIT][,SAVE]
[ , {TRANSPARENT I PSEUDOBIN} ])
[,DEST={symbolic addresslYES} }-->TCAM only
CICSjVS treats the Systemj7 as any other programmable terminal.
Transactions are normally initiated from the System/7 by issuing a fourcharacter transaction code as in the following example:
TRNID
*
*
O>XMIT
PBER
PLEX
TRNID
ERROR
#IOLT
.IOLT
3,CHECK,/0000,TRAN,2
3,
*
*
CHECK,
/0000,
TRAN,
2
*
*
*
TRAN
CHECK
PEQU
PDC
PDC
*
/A6D2
/CAOE
PEQU
*
TRANSMIT TRANSACTION CODE
BRANCH IF CONDITION ERROR CODE
WAIT FOR COMPLETION
GENERATE I/O LIST
RETURN CONTROL ON INTERRUPT
LEVEL 3
RETURN CONTROL AT LOCATION CHECK
TRANSMIT MESSAGE IN BCD MODE
MESSAGE LOCATED AT TRAN
MESSAGE TWO HORDS LONG
TRANSACTION 10
= 'TR'
='N7'
TEST FOR SUCCESSFUL COMPLETION
As shown above, the transaction identification is transmitted in BCD
mode. Pseudo binary mode can be used only while communicating with an
active CICS/VS transaction; it cannot be used to initiate the
transaction. Note that the message length is given as the number of
words to be transmitted (not as the number of characters) •
When a transaction is initiated on a system/7, CICS/VS services that
System/7 only for the duration of the transaction; that is, to ensure
efficient use of the line, any other Systemj7s on the same line are
locked out for the duration of the transaction. Therefore, CICS/VS
application programs for the multipoint System/7 should be designed with
the shortest possible execution time.
It is an MSPj7 standard that the first word (two characters) of every
message received by the System/7 be an identification word. Note,
however, that all identification words beginning with "m" (X'20') are
reserved by CICS/VS for future use.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
183
When the PSEUDOBIN parameter is specified as part ot an input request
(for example, DPHTC TIPE=(READ,PSEUDOBIN», the length of the TIOA
provided by the application program must be at least twice that of the
data to be read. If for example, twenty System/1 words (40 bytes) are
to be read, the data area of the TIOA must be at least 80 bytes in
length.
When the PSEUDOBIN parameter is specified as part of an output
request, terminal control always obtains a new TIOA and frees the old
TIOA unless SAVE is specified. Therefore, on a DPHTC
TIPE=(WRITE,READ,PSEUDOBIN) request, the application program must reload
the TIOA address (from TCTTEDA) to access the input data from the
Systemj7.
In the case of a System/1 on a dial-up (switched) line, the system/7
application program must, initially, transmit a four-character terminal
identification.
(This terminal identification is generated during
preparation of the TCT through use of the DPBTCT TIPE=TERMINAL,
TR!IDNT=parameter specification.) CICS/VS responds with either a
"ready" message, indicating that the terminal identification is valid
and that the System/7 may proceed as if it were on a leased line, or an
INVALID TERMINAL IDENTIFICATION message, indicating that the terminal
identification sent by the System/7 did not match the TRMIDNT=parameter
specified.
Whenever CICS/VS initiates the connection to a dial-up System/7,
CICS/VS writes a null message, consisting of three idle characters,
prior to starting the transaction. If there is no program resident in
the System/1 capable of supporting the Asynchronous Communication
Control Adapter (ACCA), BTA! error routines cause a data check message
to be recorded on the CICS/VS (host) system console. This is normal if
the task initiated by CICS/VS is to IPL the System/7. Although the data
check message is printed, CICS/VS ignores the error and continues normal
processing. If a program capable of supporting the ACCA is resident in
the System/7 at the time this message is transmitted, no data check
occurs.
When a disconnect is issued to a dial-up System/7, the 'busy' bit is
sometimes left on in the interrupt status word of the ACCA. If the line
connection is reestablished by dialing from the System/1 end, the 'busy'
condition of the ACCA prevents message transmission from the System/7.
To overcome this problem, the System/7 program must reset the ACCA after
each disconnect and before message transmission is attempted. This can
be done by issuing the following instruction:
PiRI
0,8,3,0
RESET ACCA
This procedure is not necessary when the line is reconnected by
CICS/VS (that is, by an automatically initiated transaction).
184
CICS/VS APRM(KL)
2260 Display Station
DFHTC
TYPE= ({READIREADL} [,WAIT][ ,SAVE])
DFHTC
TYPE= ({WRITE IWRITEL} [,WAIT][ ,SAVE][ ,ERASE])
[,LINEADR={numberIYES} ]
[,DEST={symbolic addresslYES} ]-->TCAM only
I
I
I
I
I
IL_______
~
_______ ________________________________________________________
~
~
The following is an example of the coding required to write data to a
2260 terminal screen and specify the screen line address at which the
write is to begin:
DFBTC TYPE=WRITE,
LINEADR=10
WRITE DATA TO A TERMINAL SCREEN
STARTING AT THIS SCREEN LINE
*
The LINEADR operand specifies on which line writing is to begin. The
hexadecimal equivalent of a line number in the range 1-12 ~O-FB) must
be provided in the application program. This can be done in either of
two ways:
1.
By including the LINEADR=number operand in the DFHTC macro
instruction, as shown above.
2.
By coding a single instruction, prior to issuing the DFHTC macro
instruction, that places the line number in the TIOALAC field of
the current TIOA. If the latter method is used, the LINEADR=YES
operand must be included in the DFHTC macro instruction.
The following are examples of the coding required to write data to a
2260 terminal screen and dynamically determine the screen line address
at which the write is to begin.
Chapter 4.2.
Terminal Control
~FHTC
Macro Instruction)
185
I
IFor Assembler Language
1
I MVI
TIOALAC,X'FO'
WRITE STARTING AT SCREEN LINE 1
1
I
I
I
1
I
DFHTC TYPE=WRITE,
LINEADR=YES
WRITE DATA TO A TERMINAL SCREEN
STARTING LINE ALREADY SPECIFIED
*
1---------------------------------------------------------------------IFor COBOL
STARTIN~
MOVE 240 TO TIOALAC.
NOTE: PLACE
LINE IN TIOA.
DFHTC TYPE=WRITE,
LINEADR=YES
WRITE DATA TO A TERMINAL SCREEN
STARTING LINE ALREADY SPECIFIED
*
For PL/I
TIOALAC=240;
/*START WRITE AT SCREEN LINE 1*/
DFHTC TYPE=WRITE,
LINEADR=YES
WRITE DATA TO A TERMINAL SCREEN
STARTING LINE ALREADY SPECIFIED
*
2265 Display Station
Support and macro instruction syntax as for 2260 Display Station except
that the hexadecimal equivalent of a line number can be in the range 1
through 15 (pO through FE).
2740 Communication Terminal
I
1
DFHTC 1 TYPE=(READ[,W!IT])
~
____
~
DFHTC
186
I
_____ L _______________________________________________________
TYPE= (WRITE[ ,WAIT][ ,SAVE])
[,DEST=symbolic addresslYES} ]-->TCAM only
CICS/VS APRM(ML)
2741 Communication Terminal
DFHTC
TYPE= (READ[ ,WAIT])
,RDATT=symbolic address
DFHTC
TYPE= (WRITE[ , WAIT][ , SAVE])
,WRBRK=symbolic address
[,DEST=symbolic addressIYES}]-->TCAM only
If 2741 read attention support is included by the system programmer at
system generation, a 2741 terminal operator can signal Read Attention by
pressing the ATTN key after typing a message. To provide for this, the
application programmer must issue a
DFHTC TYPE=READ,
RDATT=symbolic address
*
macro instruction, where symbolic address is the label of a routine to
which control is passed if the terminal operator terminates the input by
pressing the AT'rN key.
(See "Read Attention" below.)
If 2741 write break support is included by the system programmer at
system generation, a 2741 terminal operator can terminate the receipt of
a message by pressing the ATTN key. To provide for this, the
application programmer must issue a
DFHTC TYPE=WRITE,
WRBRK=symbolic address
*
macro instruction, where symbolic address is the label of a routine to
which control is passed if the terminal operator presses the ATTN key
while a message is being received.
(Write Break support, described
below, is not available under CICS/DOS/VS.)
Read Attention support may be generated in any CICS/OSjVS or
CICS/DOS/VS system to permit a response to the terminal operator
pressing the ATTN key (rather than the return key) after typing a
message, or without typing a message if no data is to be entered. Write
Break support may be generated in any CICS/OSjVS system to permit a
response to the terminal operator pressing the ATTN key while receiving
a message. The following features must be installed on the 2741:
•
For Read Attention:
•
For write Break:
Chapter 4.2.
Transmit Interrupt (7900).
Receive Interrupt (4708).
Terminal Control (DFHTC Macro Instruction)
187
REA D ATTE NTIO N
If the terminal operator presses the Attention key after typing a
message, it is recognized as a Read Attention if:
•
Read Attention support is generated into the system (CICS/OS/VS or
CICS/DOS/VS) •
•
The message is read by a DFBTC TYPE=READ,RDATT=symbolic address
macro instruction (which has an implied WAIT).
When this occurs, control is transferred to a CICS/VS read attention
exit routine, if it has been generated into the system. This routine is
a skeleton program that can be tailored by the system programmer to
carry out actions such as the following:
•
Perform some data analysis or modification on a Read Attention.
•
Return a common response to the terminal operator following a Read
Attention.
•
Return a response and request additional input that can be read
into the initial input area or into a new area.
•
Request new I/O without requiring a return to the task to request
additional input.
When the Read Attention exit routine is completed, control is
returned to the application program at the address specified in the
DFHTC TYPE=READ macro instruction. The return is made whenever one of
the following occurs:
•
The exit routine issues no more requests for input.
•
The exit routine issues a DFHTC TYPE=READ macro instruction and the
operator terminates the input with a carriage return. (If the
operator terminates the input with an Attention, the exit routine
is reentered and is free to issue another READ.)
If the terminal operator presses the Attention key during a read, it
is recognised as a read attention only if read attention support is
generated and if the RDATT operand is included in the DFBTC macro
instruction requesting the input. If either or both of these conditions
do not exist, the "Attention" is treated as a normal read completion,
that is, as if the return key had been pressed.
WRITE BREAK (CICS/OS/VS ONLY)
If the terminal operator presses the Attention key while a message is
being received, it is recognized as a write Break if:
•
Write Break support is generated into the system (available only in
CICS/OS/VS) by the system programmer.
•
The write was initiated by a DFBTC TYPE=WRITE,WRBRK=symbolic
address macro instruction (which has an implied WAIT).
When this occurs, the remaining portion of the message is not sent to
the terminal. The write is terminated as though it were successful, and
a new-line character (XI1SI) is sent to cause a carrier return. control
188
CICS/VS APR!! (!L)
is returned to the application program at the address specified in the
DFHTC TYPE=WRITE macro instruction.
If the Attention key is pressed and the write Break feature is
generated in CICS/OS/VS, but the DFHTC TYPE=WRITE macro instruction does
not have the WRBRK=symbolic address operand, the write break is treated
as an I/O error. The same is true if the Attention key is pressed, but
the Write Break feature is not generated in CICSjOS/VS. A write can be
interrupted only if both conditions identified above are satisfied.
~:
TYPE=WAIT and/or SAVE can be coded with READ and/or WRITE, but
only RDATT or WRBRK (not both) can be specified in one DFHTC macro
instruction.
Chapter 4.2.
Terminal Control (DFHTC
~acro
Instruction)
189
2770 Data Communication System
Support and macro instruction syntax identical to System/3. The 2770
Data Communication System recognizes a read interrupt and responds by
transmitting the contents of the I/O buffer. After the contents of the
buffer have been transmitted, the 2770 responds to the next read
continue with an EDT. If the I/O buffer is empty, the 2770 transmits an
EOT. CICS/VS issues a read interrupt and read continue to relinquish
use of the line and to enable the application program to write to the
2770.
Input from a 2770 consists of one or more logical records. CICS/VS
provides one logical record for each read request to the application
program. Note that the size of a logical record cannot exceed the size
of the I/O buffer. If the input spans multiple buffers, multiple reads
must be issued by the application program.
The 2265 component of the 2770 Data Communication System is
controlled by data stream characters, not BTAM macro instructions.
Therefore, the user should provide the appropriate screen control
characters in the TIOA.
For 2770 input, data is deblocked to ETI, ETB, RS, and US characters.
These characters are moved with the data to the TIOA but are not
included in the data length (TIOATDL). The application programmer
should be aware that such characters as NL, CR, and LF are passed in the
TIOA as data.
2780 Data Transmission Terminal
Support and macro instruction syntax identical to system/3. The 2780
Data Transmission Terminal recognizes a read interrupt and responds by
transmitting the contents of the I/O buffer. After the contents of the
buffer have been transmitted, the 2780 responds to the next read
continue with an EDT. If the I/O buffer is empty, the 2780 transmits an
EOT. CICS/VS issues a read interrupt and read continue to relinquish
use of the line and to enable the application program to write to the
2780.
Input from a 2780 consists of one or more logical records.
CICS/VS
provides one logical record for each read request to the application
program.
Note that the size of a logical record cannot exceed the size
of the I/O buffer. If the input spans multiple buffers, multiple reads
must be issued by the application program.
Output to a 2780 requires that the application programmer insert the
appropriate "escape sequence" for component selection associated with
the output message.
(For programming details, see the publication
Component Descriotion: IBM 2780 Data Transmission Terminal.)
For 2780 input, data is deblocked to ETI, ETB, RS, and US characters.
These characters are moved with the data to the TIOA but are not
included in the data length (TIOATDL). The application programmer
should be aware that such characters as NL, CR, and LF are passed in the
TIOA as data.
190
CICSjVS APRM(ML)
2980 General Banking Terminal
.------,-I
I
I DFHTC I TYPE=(READ[,WAIT][,SAVE])
I __________________________________________________________
_ _ _ II
L
~
DFHTC
~
TYPE={CBUFPIPASSBK}
[,DEST={symbolic addresslYES} ]-->TCAM only
PASSBOOK CONTROL
Two one-byte fields of the terminal control table terminal entry (TCTTE)
may be interrogated by an application program servicing passbook
requests from the 2980. These fields are:
•
TCTTETAB, which contains the binary representation of the number of
tabs necessary to position the print element to the correct
pa ssbook ar ea.
•
TCTTEPCF, which contains the indicators ~lags) necessary for
passbook control operations. The indicators TCTTEPCR and TCTTEPCH
indicate whether or not the passbook is present on a read or a
write operation, respectively. The same indicators are used to
show the presence of the Auditor key on the 2980 Model 2.
By testing indicators TCTTEPCR and TCTTEPCW, the application program
can maintain positive control with regard to the absence or presence of
a passbook during an update operation. Care must, however, be taken not
to alter these indicators, otherwise unpredictable results may occur.
If the passbook is present on a read (entry) operation, the TCT'rEPCR
indicator is turned on (set to a binary one) by CICS/VS. In this case,
the application program generally issues a write operation back to the
passbook area to update the passbook. After the write operation, the
application program must check the TCTTEPCW indicator to ensure that the
passbook was present at the time the write occurred. If the TCTTEPCW
indicator is off (set to a binary zero), the passbook was not present
and the write operation did not occur. The data sent to the terminal
(and not printed because of the "no passbook" condition) is, however,
returned to the application program in its original form for subsequent
retransmission.
When the "no passbook" condition occurs on a write, CICS/VS allows an
immediate write to the terminal. The application program should write
an error message to the journal area of the terminal to inform the 2980
operator of this error condition. To allow the operator to insert the
required passbook, CICS/VS automatically causes the transaction to wait
23.5 seconds before continuing.
After regaining control from CICS/VS following the writing of the
error message, the application program can attempt another write to the
passbook area when it has ensured that the print element is positioned
correctly in the passbook area. This is generally accomplished by
issuing two carrier returns followed by the number of tabs required to
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
191
move the print element to the correct position.
tabs can be acquired from TCTTETAB.)
(The correct number of
If the TCTTEPCW indicator is off following the second attempt to
write to the passbook area, the application program can send another
error message or take some alternative action (for example, place the
terminal "out of service").
In summary, all writes to the passbook area are conditional on a
passbook being present before a write can be executed successfully.
Therefore, a read operation cannot be combined with a passbook write.
For example, a DFHTC TYPE=(WRITE,READ,WAIT) macro instruction is an
invalid request for 2980 terminal services involving the passbook area.
A DFHTC TYPE=PASSBK macro instruction is permissible because it implies
only WRITE,WAIT.
Hote: The application programmer should not insert shift characters in
output data, because this is done automatically by CICS/VS. CICS/VS
removes shift characters from input data.
SEGMENTED WRITES CONTROL
Segmented writes are supported for both the journal area and the
passbook area. Journal area segmented writes are limited in. length by
the hexadecimal halfword value that the user stores in TIOATDL.
Passbook segmented writes are limited to a one-line logical write to
ensure positive control when spacing (indexing) past the bottom of the
passbook.
.
For example, consider a 2972 buffer length of q8 and a 2980 Model q
logical write (print) area of 100 characters per line. The application
program can write a logical record (DFHTC TYPE=PASSBK) of 100 characters
to this area; CICS/VS automatically segments the record to adjust to the
buffer size. The application program must insert the passbook indexing
character (X'25 1 ) as the last character written in one logical write to
the passbook area. This is done to control passbook indexing and
thereby achieve positive control of passbook presence.
If the message contains embedded passbook index characters and
segmentation is necessary because of the logical length of the message,
the write terminates if the passbook spaces beyond the bottom of the
passbook; the remaining segments are not printed.
192
CICS/VS APRM(ML)
DATA HANDLING
SHIFT CHARACTERS: Shift characters are handled by the terminal control
program and are of no concern to the application programmer. They are
stripped from input messages and added to output messages as required.
Data can be written in any mix of uppercase, lowercase, or special
characters.
(See the 2980 Translate Tables in Appendix D.)
JOURNAL INDEXING: Journal indexing is the responsibility of the
application programmer. Carriage returns (XI 151) may be inserted
anywhere in the logical message. For futher information, see the
appropriate SNA Guide.
PASSBOOK INDEXING:
Passbook indexing necessitates special consideration
by the application programmer to control bottom-line printing on the
passbook. (See "Passbook Control" and "Segmented writes Control"; the
two preceding sections.)
TAB CHARACTERS: The tab character (XIOSI) is controlled by the
application programmer. As stated above, the number of tabs required to
position the print element to the first position of the passbook is
available at TCTTETAB. This value is specified by the system programmer
when generating the terminal control table and may be unique to each
terminal. Other tab characters are inserted as needed to control output
format.
MISCELLANEOUS CHARACTERS: Turn page, message light, openchute, and
special banking characters can be used by the application programmer as
needed.
(See the 2980 Translate Tables in Appendix D.)
AUDITOR KEY MODEL 2: Presence of the Auditor key is controlled through
use of the DFHTC TYPE=PASSBK macro instruction and may be used in a
manner similar to that for passbook control. (See "Passbook Control",
earlier in this Chapter.)
2980 MODEL NUMBER: TCTTETM contains the 2980 model number expressed as
a hexadecimal value (X I 01 1 , XI 021, X I 04 1 ) . Since CICS/VS uses the model
number to select the correct translate table for each of the 2980
models, the application program should not alter this field.
COMMON BUFPER: Common buffer writes (DFHTC TYPE=CBUFF) are translated
to the receiving TCTTE model character set. If more than one 2980 model
type is connected to the 2972 Control Unit, the lengths are
automatically truncated if they exceed the buffer size.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
193
Por COBOL
DATA DIVISION
WORKING STORAGE SECTION.
01 DPH2980 COpy DPH2980.
LINKAGE SECTION.
01 DPHBLLDS COpy DFHBLLDS.
02 TCTTEAR PIC S9(8) COMP.
02 TIOABAR PIC 59(8) COMP.
01 DFHTCTTE COpy DFHTCTTE.
01 DFHTIOA COpy DFHTIOA.
02 DATA PIC X (20) •
02 FILLER REDEFINES DATA.
03 TAB1-1 PIC X.
03 DATA1 PIC X(19).
02 FILLER REDEPINES DATA.
03 TAB1-2 PIC X.
03 TAB2-2 PIC X.
03 DATA2 PIC X(18).
.
.
PROCEDURE DIVISION.
IF TCTTETAB = TAB-ONE GO TO ONETBCH.
IF TCTTETAB = TAB-TWO GO TO TWOTBCH.
ONETBCH.
MOVE TABCHAR TO TAB1-1.
MOVE TOTAL TO DATA1.
TWOTBCH.
MOVE TABCHAR TO TAB1-2, TAB2-2.
MOVE TOTAL TO DATA2.
194
CICS/VS APRM(ML)
For PL/I:
%INCLUDE DFHTIOAi
2 DATA CHAR (20);
DECLARE 1 USERTIOA 1 BASED (TIOABAR),
2 TIOAFILL CHAR (12),
2 TAB1_l CHAR (1),
2 DATAl CHAR (19),
DECLARE 1 USERTIOA 2 BASED (TIOABAR),
2 TIOAFILL CHAR (12),
2 TAB1_2 CHAR (1),
2 TAB2_2 CHAR (1),
2 DATA2 CHAR (18):
.
%INCLUDE DFH2980;
IF (TCTTETAB = TAB_ONE) THEN GO TO ONETCBHi
IF (TCTTETAB = TAB_TWO) THEN GO TO TWOTBCH;
ONETBCH:
TAB1_l = TABCHAR:
DATAl = AMOUNT:
TWOTBCH:
TAB1_2 = TABCHAR;
TAB2_2 = TABCHAR;
DATA2 = AMOUNT;
In the COBOL example, the structure DFH2980 is copied in the Working
storage Section; in the PL/I example, DFH2980 is included following the
%INCLUDE statements for the based structures. DFH2980 contains
constants that may be used when writing application programs for the
2980.
The application program is also expected to test the TCTTEPCF field
to determine whether a passbook was present on a read or write.
TCTTEPCR and TCTTEPCW are located in DFH2980 to aid in this testing.
To test the TCTTEPCF field in COBOL, statements such as the follouing
might be used:
MOVE TCTTEPCF TO HOLDPCF.
IF HOLDPCFB = (HOLDPCFB / TCTTEPCW)
THEN GO TO BOOK-FOR-PRESENT-WRITE.
*
TCTTEPCW
Substituting TCTTEPCR for TCTTEPCW allows the COBOL programmer to
test for the presence of a passbook on a read.
(HOLDPCF and HOLDPCFB
are also part of DFH2980.)
To test the TCTTEPCF field in PL/I, statements such as the following
might be used:
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
195
IF (TCTTEPCF I TCTTEPCi) THEN GO TO
BOOK_PRESENT_iRITE;
substituting TCTTEPCR for TCTTEPCi allows the PL/I programmer to test
for the presence of a passbook on a read.
To test the station identification and to determine whether the
normal station or alternate station is being used, values of the forms
shown below are predefined in DFH2980:
STATION-#-A OR STATION-4-N (for COBOL)
STATION_#_A OR STATION_#_N (for PL/I)
where # is an integer (0 through 9) and A and N signify alternate and
normal stations. The values are one-byte character values and can be
compared to TCTTESID in an IF statement.
To test the teller identification on a 2980 Model 4, the TCTTETID
field is defined as a one-byte character value. It can be tested in an
IF statement.
Thirty special characters are defined in DFH2980. Twenty-three of
these can be referred to by the name SPECCHAR-X or SPECCHAR_X (for COBOL
or PL/I) where X is an integer (0 through 23). The seven other
characters are defined with names that imply their usage, for example,
TABCHAR. For further information on these thirty characters, see
Appendix D.
The names defined in DFH2980 for COBOL follow:
STATION-O-N
STATION-O-A
STATION-1-N
STATION-1-A
STATION-2-N
STATION-2-A
STATION-3-N
STATION-3-A
STATION-4-N
STATION-4-A
STATION-S-N
STATION-S-A
STATION-6-N
STATION-6-A
STATION-7-N
STATION-7-A
STATION-8-N
STATION-8-A
STATION-9-N
STAT ION-9-A
TAB-ZERO
TAB-ONE
TAB-TWO
TAB-THREE
TAB-FOUR
TAB-FIVE
TAB-SIX
TAB-SEVEN
TAB-EIGHT
TAB-NINE
HOLDPCFB
DFHFILL
HOLDPCF
TCTTEPCR
TCTTEPCi
TABCHAR
OPENCH
JRNLCR
PSBKCR
MSGLITE
BCKSPACE
TRNPGE
SPECCHAR-1
SPECCHAR-2
SPECCHAR-3
SPECCHAR-4
SPECCHAR-5
SPECCHAR-6
SPECCHAR-7
SPECCHAR-8
SPECCHAR-9
SPECCHAR-10
SPECCBAR-11
SP ECCHA R-12
SPECCHAR-13
SPECCHAT-14
SPECCHAR-1S
SPECCHAR-16
SPECCHAR-17
SPECCHAR-18
SPECCHAR-19
SPECCBAR-20
S PE CCHAR-21
SPECCHAR-22
SPECCBAR-23
The names defined in DFH2980 for PL/I follow:
STATION 0 N
STATION:O:A
STATION 1 N
STATION-1-A
STATION-2-N
STATION:2:A
STATION 3 N
STATION:3:)
STATION_4_N
STATION 4 A
STATION:S:N
STATION 5 A
STATION-6-N
STATION:6:A
STATION_7_N
196
STATION 7 A
STATION:8:N
STAT ION_8_A
STATION_9_N
STATION_9_A
TAB_ZERO
TAB_ONE
TAB_TiO
TAB_THREE
TAB_FOUR
TAB-FIVE
TAB_SIX
TAB_SEVEN
TAB_EIGHT
TAB_NINE
CICS/VS
APRM(~L)
TCCTEPCR
TCTTEPCW
TABCHAR
OPENCB
JRNLCR
PSBKCR
MSGLITE
BCKSPACE
TRNPGE
SPECCHAR 1
SPECCHAR-2
SPECCHAR-3
SPECCHAR-4
SPECCHAR-S
SPECCHAR:6
SPECCHAR_7
SPECCBAR_B
SPECCBAR 9
SPECCHAR-10
SPECCHAR: 11
SPECCBAR 12
SPECCHAR -13
SPECCBAR:14
SPECCHAR_1S
SPECCHAR 16
SPECCHAR -17
SPECCHAR 18
SPECCHAR -19
SPECCBAR:20
SPECCBAR_21
SPECCHAR_22
SPECCBAR_23
3270 Information Display System (BTAM and TeAM)
DFHTC
TYPE= ( {READ I REA DB} [ , WAIT ][ , SAVE ][ ,TEXT ])
READB not available under TCAM
DFHTC
TYPE=({WRITEICOPYIPRINTIERASEAUP}
[,WAIT][,SAVE][,ERASE],[STRFIELD])
[ ,CTLCHAR= {hexadecimal number I YES} ]
[,DEST={symbolic addresslYES} ]-->TCAM only
COpy and PRINT not available under TCAM
When input is to be received from a terminal of the 3270 Information
Display System, the application programmer can use
DFHTC TYPE=(RBAD,TEXT)
or
DFHTC TYPE=TEXT
DFHTC TYPB=RBAD
DFHTC TYPE=WAIT
to request a temporary override of the uppercase translation features of
CICS/VS, thus allowing a message containing both uppercase and lowercase
data to be received from a terminal.
If the 3270 print request facility was included in the terminal
control program at CICS/VS system initialization, the application
program can issue a DFHTC TYPE=PRINT macro instruction to cause the data
currently displayed on a 3270 display to be printed on the first
available eligible 3270 printer.
For a printer to be available for printing from a display, it must be
in service and not currently attached to a task. For it to be eligible,
it must be attached to the same control unit as the display, must have a
buffer capacity equal to or greater than that of the display, and must
have had FEATURE=PRINT specified for it in the TCT by the system
programmer.
If the 3270 display is a 3275 with an attached printer, and
FEATURE=PRTADAPT has been specified in the TCTTE; the data will be
printed on the attached printer.
Some 3270 displays have the facility to copy a screen image to a
printer that is attached to the same control unit, without host
intervention. This is a hardware facility, and is not under the control
of CICS/VS. For further details see "printer authorization matrix", IBM
3270 Information Display System Component Description.
For those devices with switchable screen sizes, the size of the
screen that can be used and the size to be used for a particular
transaction are defined at CICS/VS system generation. These values are
available to the application programmer in fields in the TCTTE. These
fields are listed in Appendix C.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
197
3270 Logical Unit
DFHTC
TYPE= ({READ IREADB} [ ,WAIT][ ,SAVE][ ,TEXT])
[,EOC=symbolic address]
r------r-------r----------------------------------------------------------I
DFHTC I TYPE=({WRITEIPRINTICOPYIERASEAUP]
[,WAITX,SAVEX ,ERASE],[STRFIELD])
I
[,CTLCHAR={hexadecimal numberIYES}]
I
[ ,CCOMPL=NO]
I
[ ,DEFRESP=YES ]
I
[,DEST={symbolic addressIYES}]-->TCAM only
I
L -_ _ _ _ _
~
_______
I
,~
________________________________________________________
~
In general, programming for a 3270 logical unit is the same as
for a 3270 via BTA~, that is, the COPY, PRINT, READB, ERASE,
and ERASEAUP are supported as before. The additional operand (DEFRESP)
has been added to the DFHTC terminal control macro instruction, and
there are some restrictions:
programm~ng
•
2260 Compatibility is not supported.
•
ASCII code is not supported (but, for BSC 3270, code translation
can be carried out by NCP translation tables in the 370Q/3705
communications controller).
•
DFHTC TYPE=COPY must specify a symbolic terminal identification; a
physical device address cannot be specified.
If the 3270 print request facility is included at system
initialization, the DFHTC TYPE=PRINT macro will enable the data
displayed on the screen to be printed on the first available printer
that is eligible.
An available printer is one that is in service and that is not
attached to a task.
An eligible printer is one for which the PRINTTO or ALTPRT option has
been specified in the TCT.
If COpy has also been specified with these options, the printer must
I be attached to the same 3270 control unit as that used for the display.
If an eligible printer is unavailable, the data in the display buffer
is captured, a message is sent to the master terminal operator by the
terminal abnormal or node abnormal condition program ~FHZNAC) and
control is passed to a user-written terminal or node error program which
provides an appropriate action, for example, if the printer is already
attached to a task, the user-written error program can direct the data
to another printer or hold the data until the busy printer becomes
available.
If the 3270 display is a 3275 with an attached printer, and
FEATURE=PRTADAPT has been specified in the TCTTEi the data will be
printed on the attached printer.
Some 3270 displays have the facility to copy a screen image to a
printer that is attached to the same control unit, without host
198
CICS/VS APR! (!L)
intervention. This is a hardware facility, and is not under the control
of CICS/VS. Por further details see "printer authorization matrix", IBM
3210 Information Display System Component Description.
Por those devices with switchable screen sizes, the size of the
screen that can be used and the size to be used for a particular
transaction are defined at CICS/VS system generation. These values are
available to the application programmer in fields in the TCTTE. These
fields are listed in Appendix C.
Chapter ij.2.
Terminal Control (DP8TC Macro Instruction)
199
3270 LUTYPE2 Logical Unit
DFHTC
TYPE= ({READ I READB) [ , WAIT ][ ,SAVE][ ,TEXT])
[,EOC=symbolic address]
DFHTC
TYPE=({WRITBIPRINTIERASEAUP}
[,WAIT][,SAVE][,ERASE][,STRFIELD])
[ ,CTLCHAR= {hexadecimal number I YES} ]
[ , CCOr!PL=NO ]
[,DBFRESP=YES]
[,DEST={symbolic addresslYES} ]-->TCAr! only
DFHTC
TYPE=SIGNAL
{,SIGADDR=symbolic address I,WAIT=YES}
Logical unit type 2 (LUTYPE2) is a logical unit defined by SNA, and
which accepts a 3210 display data stream.
Support and macro syntax are the same as for the 3270 logical unit
except that TYPE=COPY is not supported.
Some 3270 displays have the facility to copy a screen image to a
printer that is attached to the same control unit, without host
intervention. This is a hardware facility, and is not under the control
of CICS/VS. For further details see "printer authorization matrix", in
the IBr! 3210 Information Display System Component Desc~iption.
For those devices with switchable screen sizes, the size of the
screen that can be used and the size to be used for a particular
transaction are defined at CICSjVS system generation. These values are
available to the application programmer in fields in the TCTTE. These
fields are listed in Appendix C.
200
CICS/VS APRr!(!L)
3270 LUTYPE3 Logical Unit.
I
I
DPHTC t TYPE=({WRITEIPRINTIERASBAUP}
I
[ , WAIT][ , SA VE ][ , BRASE][ , STRPIBLD ])
I
[,CTLCHAR={hexadecimal numberIYES}]
I
[,CCO!PL=HO]
I
[,DEPRBSP=YES]
I
[,DEST= {symbolic addressl YES} ]->TCA! only
I
I
DPHTC
TYPE=SIGNAL
{,SIGADDR=symbolic address I,WAIT=YES}
Logical unit type 3 (LUTYPE3) is a logical unit defined by SNA, and
which accepts a 3270 display data stream.
Support and macro syntax are the same as for the 3270 logical unit
except that TYPB=READ, READB and COpy are not supported, but
TYPE=WRITE,WAIT,READ is supported for STRPIELD to issue QUERY.
Chapter 4.2.
Terminal Control (DPHTC Kacro Instruction)
201
-3270 SCSPRT Logical Unit
DPHTC
TYPE= (WBITE[ , WAIT][ , SAVE ][ ,LAST ])
[ , CCOMPL=NO]
[,DEPBESP=YES]
[,DEST={symbolic addresslYES} ]-->TCA! only
DPHTC
TYPE=(BEAD[,WAITI,SAVE])
[,EOC=symbolic address]
r------·~------~------------------------------------------------------
I
I
I
IL ______
DPHTC
.~
______
TYPE=SIGNAL
{,SIGADDB=symbolic address I,WAIT=YES}
~
____________________________________________________
~
The SCS printer logical unit (SCSPBT) accepts an SCS data stream. SCS
is defined by SK1. certain devices connected as SCSPBT have input
capability (for example, PA keys on 3287), in which case TYPB=SIGNAL
should be used to detect operator input, followed by TYPE=READ to obtain
the input. Alternatively, TYPE=(READ,WAIT) can be issued alone, in
which case the program viII wait for operator input.
202
CICS/VS APBM(!L)
3270 in 2260 Compatibility Mode (BTAM only)
r-------~-------~----------------------------------------------------------~
I
I
IL _______
DFHTC
~
TYPE= ({READ I READL} [ , WAIT ][ ,SAVE][ , TEXT])
_______ ~_____________________________________________________________~
DFHTC
TYPE= ({WRITE IWRITEL} ,WAIT ][SAVE][ ,ERASE])
[,CTLCHAR={hexadecimal numberIYES}]
[,LINEADR={numberIYES}]
[ ,DEST= {symbol ic address I YES} ]-->TCAM only
If required, the 3270 may be used in 2260 compatibility mode. This
means that a 3270 terminal is used in place of a 2260 terminal but uses
2260-based transactions developed for earlier versions of CICS/VS. To
make this support available, the system programmer must, during system
generation, have requested that 2260 compatibility be included in the
CICS/VS system. This generates the code necessary to convert 2260 data
streams from user-written application programs to the appropriate 3270
data stream format, or 3270 to 2260. 2260--compatibility support is not
available for a 3270 connected to CICS/VS via VTAH (3270 logical unit or
3650 host--conversational (3270) logical unit).
When a write to a 3270 terminal (operating in 2260 compatibility
mode) is specified, that is, by issuing the
DFHTC TYPE=(WRITE,ERASE)
macro instruction, the screen is erased and the cursor is returned to
the upper left corner of the screen before writing starts. If the ERASE
parameter is omitted, writing begins wherever the cursor is located at
the time the write is issued.
To simply erase the screen, the application programmer can
1.
Place at TCTTEDA the address of a TIOA.
2.
Place at TIOATDL a data length of
3.
Issue a DFHTC TYPE=(WRITE,ERASE) macro instruction. If operating
in 2260 compatibility mode, the TID A" should only contain a start
symbol. Set the data length in TIDATDL to 1 before issuing the
DFHTC TYPE=(WRITE,ERASE).
o.
The following example shows how to write data to a 3270 terminal
operating in 2260 compatibility mode, and how to specify the screen line
address at which the write is to begin:
DFHTC TYPE=WRITE,
LINEADR=10
WRITE DATA TO A TERMINAL SCREEN
STARTING AT THIS SCREEN LINE
*
The following examples show how to write data to a 3270 terminal
operating in 2260 compatibility mode, beginning at a screen line address
placed in TIOALAC prior to issuing the write request.
Chapter 4.2.
Terminal Control (DFBTC Macro Instruction)
203
Por Assembler Language:
!tVI
TIOALAC,X'PO'
WRITE STARTING AT SCREEN LINE 1
DPHTC
TYPE=WRITB,
LINBADR=Y BS
WRITB DATA TO A TER!tINAL SCREEN
STARTING LINE ALREADY SPECIPIED
*
Por COBOL:
!tOVE 240 TO TIOALAC.
NOTE PLACE STARTING LINE IN TIOA.
DPHTC TYPE=WRITE,
LINEADR=YES
WRITB DATA TO A TERMINAL SCREEN
STARTING LINE ALREADY SPECIPIED
*
Por PL/I:
204
TIOALAC=240,
/*START WRITE AT SCREEN LINE 1*/
DPHTC TYPE=WRITE,
LINEADR=YES
WRITE DATA TO A TERMINAL SCREEN
STARTING LINE ALREADY SPECIPIED
CICS/VS APR!t(!L)
*
3600 Finance Communication System (BTAM)
DFHTC
TYPE=(READ[,WAIT][,SAVE])
DFHTC
TYPE=(WRITE[,WAIT][,SAVE][,TRANSPARENT])
INPUT
The unit of transmission from a 3601 to CICS/VS is a segment consisting
of data link control characters, the one-byte identification of the 3600
logical unit that issued the CPU write, and the data written. The units
received can be in the following forms:
5
E
T
X
id data
T
B
or
5
E
T id data
X
T
X
where STX means "start of text", ETB means "end of block" and ETX means
"end of text".
A logical unit sends a message either in one segment, as follows:
,
5
T id data
X
E I
T I
X I
or in more than one segment, as follows:
S
E
T id data
X
T
B
S
T id data
X
E
T
B
5
E
T id data
X
T
X
The input TIOA passed to the user-written application program
consists of the data only. The one-byte field TCTTEDLM contains flags
describing the data-link control character (ETB, BTX, or IRS) that ended
the segment. The application program can issue terminal control macro
instructions to read the data until it receives a segment ending with
ETX. If blocked data is transmitted it is received by CICS/VS as
follows:
r--------·------~
I 5
I T id1 data
IL ______________
X
R
~
I
I
S
id2 data
E
idn data
R
T
X
5
l
Chapter 4.2.
Terminal Control (DFBTC ftacro Instruction)
205
For nlocked input, the flags in TCTTEDLM only indicate end of
segment, not end of message. The CICS/V5 application program still
receives only the data, but user-defined conventions may be required to
determine the end of the message.
The field TCTTEDLM also indicates the mode of the input, either
transparent or non-transparent. Blocked input is non-transparent.
The terminal control program does not pass input containing a "start
of header" (50H) data link control character to a user-written
application program. If it receives an 50H it sets an indicator in
TCTTEDLM, passes the input to the user exit in the terminal control
program, and then discards it.
OUTPUT
When an application program issues a terminal control write, the
terminal control program determines, from the value specified in the
BUFFER parameter of the DFBTCT TYPE=TERMINAL system macro, the number of
segments to be built for the message. It sends the message to the 3600
logical unit in one segment, as follows:
r
I 5
I T
I X
data
E
T
X
or in multiple segments, as follows:
5
T
X
data
E
T
B
5
T
X
data
E
T
B
5
T
X
data
E
T
X
-I
The host input buffer of the 3600 controller and the input segment of
the receiving logical unit must be large enough to accommodate the data
sent by CIC5/V5. However, space for the data link control characters
need not be included. The 3600 application program reads the data from
the host, by means of an LREAD, until it has received the entire
message.
The terminal control program sends data in transparent mode when the
user-written application program issues a DFHTC TYPE=TRANSPARENT macro.
Otherwise, data is sent in non-transparent mode.
CIC5/V5 system output messages begin with "DFH" followed by a fourbyte message number and the message text. These messages are sent in
non-transparent mode. It is suggested that CIC5/V5 user-written
application programs do not send messages starting with "DFH" to the
3601.
206
CIC5/V5 APRM(!L)
RESEND MESSAGE
When a logical unit sends a message to the host and a short-on-storage
condition exists or the input is unsolicited (the active task associated
with the terminal has not issued a read), the terminal control program
sends a "resend" message to the logical unit. The format of this
message is DFH1033 RE-ENTER followed by Xl 1S 1 (a 3600 new line
character) followed by the first eight bytes of the text of the message
being rejected. No message is sent to the destinations CSMT or CSTL.
The first eight bytes of data sent to CICS/VS can be used by the 3600
application program to define a convention to associate responses
received from CICS/VS with transactions sent to the host, for example,
sequence numbers could be used.
If a CICS/VS user-written application program has already issued a
terminal control write when a resend situation occurs, the resend
message is not sent to the 3601 until the user-written application
program message has been sent. 1 3600 logical unit cannot receive a
resend message while receiving a segmented message.
Only one resend message at a time can be queued for
If a second resend situation occurs before CICS/VS has
first, a resend message, containing the eight bytes of
accompanied the second input transaction from the 3600
sent.
a logical unit.
written the
data that
logical unit, is
The res end message is sent in transparent mode if the input data from
the 3601 to be re-transmitted is received by CICS/VS in transparent
mode. Otherwise it is sent in non-transparent mode.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
207
3600 (3601) Logical Unit
i
I
I
I
I
I
DFBTC
TIPB=(RBAD[ ,WAIT][ ,SAVE])
[,EOC=syabolic address]
[,IHBF!H=symbolic address]
DFBTC
TYPE=(WRITB[,WAIT][SAVB][LAST])
[ ,LDC= {mnemonic I YES} ]
[ ,F! B= {HO I YBS} ]
[ , CCO!PL=HO ]
[,DEFRESP=YES]
[ , DBST= {symbolic address I YES} ]->TCA!l only
DFHTC
TIPE=SIGNAL
{,SIGADDR=symbolic addressl,WAIT=YES}
I
3600 Pipeline Logical Unit
DFBTC
TIPB= (WRITB[ , WAIT][ ,SAVE][ ,LAST])
3600 (3614) Logical Unit
DFBTC
TIPE= (READ[ ,WAIT][ ,SAVE ])
I
I
DFBTC I TIPE=(WRITE[,iAIT][,SAVB])
~----
208
_______IL.__________________________________________________
CICS/VS APR!! (!L)
~
3630 Plant Communication System
The 3630 Plant Communication System is supported as a 3600. Two types
of logical unit can be defined for a 3630: the 3600 (3601) logical unit
and the 3600 pipeline logical unit. The macro instruction syntax is as
shown above for these logical units.
3650 Host Command Processor Logical Unit
r------r--------r---------------------------------------------------------,
I
I
I
I
I
I DFHTC
I
I
L
TYPE= (READ[ , WAIT ][ , SAVE ])
[,EOC=symbolic address]
I
I
I
~
_____ ~
DFHTC I TY PE= (WRITE[ , WAIT][ ,SAVE ])
I
[,FMH=YES]
I
[,CCOMPL=NO]
_______ LI ________________________________________________________
~
3650 Host Conversational (3270) Logical Unit
I
I
I
I
L
I _______
DFHTC
~
_______
DFHTC
TYPE= (READ[ ,WAIT][ ,SAVE])
[,EOC=symbolic address]
~
______________________________________________________
~
TYPE=({WRITEIPRINTIERASEAUP}
[,WAIT][ ,SAVE][ ,ERASE][ ,LAST])
[,CTLCHAR={hexadecimal numberlYES}]
[ , CCOMPL=NO ]
[ ,DEFRESP=YES ]
[,FMH=YES]
OUTPUT DEVICE CONTROL
Device control characters for 3650 devices can be inserted by CICS/VS
application programs into output data streams. To avoid designing such
device-dependent CICS/VS application programs, device responsibility can
be moved to the 3650 application programs. Thus, the CICS/VS
application programs would be concerned with data content, while data
format would be the responsibility of the 3650 application program.
Another alternative is available for handling device-dependent
matters. Basic mapping support (BMS) can be used to write data to
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
209
logical units (except for pipeline). BftS can be used to format data and
insert the necessary 3650 device control characters.
THE ERASE FUNCTION
The erase option is supported by the DFHTC macro instruction when this
sacro is issued for a host conversational (3270) logical unit. The
erase function for this logical unit is controlled as a device-dependent
character. The erase function can be obtained using BftS.
3650 Pipeline Logical Unit
DFHTC
TYPE= (WRITE[ , WAIT][ ,SAVE][ ,LAST])
3650 Host Conversational (3653) Logical Unit
DFHTC
TYPE=(READ[,WAIT)[,SAVE)
[,EOC=symbolic address]
r------_-------_----------------------------------------------------------------------,
DFHTC
TYPE=(WRITE[,WAIT][ ,SAVE)[,LAST])
[ ,CCOMPL=NO ]
[ ,DEFRESP=YES ]
I
I
I
I
I
•
210
CICS/VS APRM(HL)
3650 Interpreter Logical Unit
r-----~-----r------------------------------------------------------~
I
DPHTC I TYPE=PROGRAM
I
,PRGNAME=name
I
[,VALID=address]
I
[,NONVAL=address]
I
[,CONNECT={ACTIVATEICONVERSE}]
I
[,NORESP=address]
I
~-----~------'~----------------------------------------------------~
DFHTC
TYPE=(READ[,WAIT][ ,SAVE])
[,EODS=symbolic address]
[,EOC=symbolic address]
[,INBPMH=symbolic address]
DPHTC
TYPE=(WRITE[,WAIT][,SAVE][,LAST])
[ ,FMH={YESINO}
[,DEPRESP=YES]
DFHTC
TYPE=EODS-->VTAM only
3660 Supermarket Scanning System (BTAM)
Support and macro instruction syntax identical to System/3, except that
the 3660 cannot initiate communications; the host system initiates all
transactions.
Chapter 4.2.
Terminal Control (DPHTC Macro Instruction)
211
3735 Programmable Buffered Terminal
DFHTC
I
I
I
I
I
IL _______
TYPE=(READ[,WAITX,SAVE])
[,EOF=symbo1ic address]
I
~
DFHTC I TYPE=(WRITE[,WAIT][,SAVE][,NOTRANSLATE])
I
[ , DEST= {symbolic address I YES} ]->TCAI! only
_______
'I
LI_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~
The 3735 Programmable Buffered Terminal may be serviced by CICS/VS in
response to terminal-initiated input, or as a result of an automatic or
time-initiated transaction. Both are explained below.
AUTOANSWER
The 3735 transaction is attached by CICS/VS upon receipt of input from a
3735. Data is passed to the application program in 476-byte blocks;
each block (one buffer) may contain multiple logical records. The final
block may be shorter than 476 bytes; zero-length final blocks are not,
however, passed to the application program. If the block contains
multiple logical records, the application program must perform any
necessary deblocking functions and the gathering of partial logical
records from consecutive reads.
It is recommended that the user spool input data from a 3735 to an
intermediate data set (for example, an intrapartition destination) to
ensure that all data has been captured before deblocking and processing
that data.
The application program must follow 3735 conventions and read to endof-file before attempting to write FDPs (form description programs) or
data to the 3735. For this reason, the EOF=symbolic address operand
must be used with each DFHTC TYPE=READ request. When the EOF branch is
taken, the user may begin to write FDPs or data to the 3735, or,
optionally, request CICS/VS to disconnect the line.
It is possin1e that the 3135 will transmit the end-of-file condition
immediately upon connection of the line. For this reason the user must
code the initialization request (DFHTC EOF=symbolic address) before
issuing any other terminal control requests.
The user is responsible for formatting all special message headers
for output to the 3135 (for example, SELECTRIC, POWERDOWN). If FDPs are
to be transmitted to a 3735 with ASCII transmission code, the
NOTRANSLATE operand must be included in the DFHTC TYPE=WRITE request for
each block of FDP records.
The user must issue a DFHTC TYPE=DISCONNECT macro instruction when
all output has been transmitted to the 3735. If the application program
ends during batch write mode prior to issuing the DISCONNECT request,
CICS/VS forces a 3735 "receive abort" condition and all data just
transmitted is ignored by the 3735.
212
CICS/VS APRM(I!L)
AUTOCALL AND TIME-INITIATED
In automatic and time-initiated transactions, all considerations stated
above except use of the DFHTC EOF=symbolic address macro instruction
apply when CICS/VS dials a 3735. The DFHTC EOF=symbolic address macro
instruction is not used.
CICS/VS connects the line and allows the user to indicate the
direction of data transfer by means of the first terminal control
reguest. If this first reguest is a WRITE and the 3735 has data to
send, the 3735 causes the 1ine to be disconnected.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
213
3740 Data Entry System
I
I
~
_____ ~
DFHTC I TYPE= (READ[ ,WAIT][ ,SAVE ])
I
[ , ENDFILE=symbolic address] ---->.except TCAM
I
[,ENDINPT=symbolic address]
>except TCAM
_______ L
I ________________________________________________________
DFHTC
~
TYPE=(WRITE[,WAIT][,SAVE]
[ ,ENDFILE ][ ,ENDOUTPUT ][ ,TRANSPARENT D
[ , DEST= {sym bolic address I YES) }-->TCAM only
The 3740 Data Entry System may be serviced by CICS/VS as a batch or
inquiry mode application. Considerations for both modes are described
in the following paragraphs.
BATCH MODE APPLICATIONS
In batch mode, the 3740 sends multiple files of data to CICSjVS during a
single transmission. All input data files must be sent to CICS/VS
before the 3740 is able to receive data from CICS/VS. When able to
receive, the 3740 accepts multiple files of data in a single
transmission. To communicate in this manner, a means is provided in the
DFHTC macro instruction for identifying end-of-file, end-of-input, and
end-of-output conditions.
When sending data to the 3740, the DFHTC TYPE=ENDFILE macro
instruction must be issued after each file to signal the end-of-file
(EXT) condition to the 3740. The DFHTC TYPE=ENDOUTPUT macro instruction
should be issued after all data has been sent to the 3740 (EOT) and must
be immediately preceded by a DFHTC TYPE=ENDFILE macro instruction. Once
end-of-output is signalled in this manner, no additional WRITEs should
be issued. The WRITE, ENDFILE, and ENDOUTPUT parameters may be combined
in the DFBTC macro instruction. For example, a DFHTC
TYPE=(WRITE,ENDFILE) causes a write operation followed by an end-of-file
signal. A DFHTC TYPE=(WRITE,ENDFILE,ENDOUTPUT) causes a write
operation, an end-of-file signal, and then an end-of-output signal. A
DFHTC TYPE=~NDFILE,ENDOUTPUT) causes an end-of-file signal followed by
an end-of-output signal. The placement of the parameter within the
macro instruction has no effect on the sequence.
!ote: If ENDFILE is combined with any other parameter and SAVE is also
present, the TIOA used to write the end-of-file record will be current
TIOA after return from terminal control.
214
CICS/VS APRM(ML)
3767 Interactive Logical Unit
DFHTC
TYPE=(READ[,WAIT][,SAVE])
[ ,EOC=symbolic address]
DFHTC
TYPE= (WRITE[ ,WAIT][ ,SAVE][ ,LAST ])
[,FORCE=YES]
[,CCOMPL=NO]
[,DEFRESP=YES]
[,DEST={symbolic addresslYES} ]-->TCAM only
j
I
I
I
I
I
I
IL_____
~
____________________________________________________________
~
~-----~-------r----------------------------------------------------------------------
DFHTC I TYPE=SIGNAL
I
{,SIGADDR=symbolic address I, WAIT=YES}
I
I
3770 Interactive Logical Unit
DFHTC
TYPE= (READ[ ,WAIT][ ,SAVE])
[,EOC=symbolic address]
DFHTC
TYPE= (WRITE[ , WAIT][, SAVE][ ,LAST])
[ , FORCE=YES ]
[ , CCOMPL=NO ]
[ ,DEFRESP=YES]
[ ,DEST= {symbolic addresslYES} J-->TCAM only
DFHTC
TYPE=SIGNAL
{,SIGADDR=symbolic address I,WAIT=YES}
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
215
3770 Batch and Batch Data Interchange Logical Unit
DPHTC
TYPE=(READ[,WAITI,SAVE)
[ ,EODS=symbolic address]
[,EOC=symbolic address]
[,INBP~H=symbolic address]
,
i
DPHTC
TYPE=(WRITE[,WAIT][,SAVE][,LAST])
[ , F~H= Ui.Q I YES} )
[ ,CCO~PL=NO]
[ ,DEFRESP=YES ]
[ , DEST= {sy mbolic address I YES}
]->TCA~
only
,
,
,
I
I
I
I
3770 Full Function Logical Unit
i
I
I
DPHTC
TYPE= (READ[ ,WAIT][ ,SAVE])
I
[,EOC=symbolic address]
I
[,INBFMH=symbolic address]
IL ________________________________________________________________~
r------------------------------------------------------------------,
I
I
I
I
I
I
I
I
DFHTC
TYPE=(WRITE[,WAITX,SAVEI,LAST])
[ ,FMH= lliQl YES} ]
[ , CCOMPL=NO]
[,DEFRESP=YES]
[ , DEST= {symbolic address I YES} ]-->TCAM only
3780 Data Communications Terminal
Support and macro instruction syntax identical to System/3.
216
CICS/VS
APR~(!L)
3790 Inquiry Logical Unit
DFHTC
TYPE=(READ[,WAIT][,SAVE])
[,EOC=symbo1ic address]
I
i
I
I
I
I
I
I
IL______
I
I
I
I
I
I
I
DFHTC
~
TYPE=(WRITE[,WAIT][,SAVE][,LAST])
[,FMH=U!QIYES} ]
[ ,CCOMPL=NO]
[ , DEFRESP=YES]
[,DEST={symbo1ic addresslYES} ]-->TCAM only
______ I _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _,
3790 Full Function Logical Unit
DFHTC
TYPE= (READ[ ,WAIT][ ,SAVE])
[,EOC=symbo1ic address]
[,INBFMH=symbo1ic address]
DFHTC
TYPE= (WRITE[ ,WAIT][ ,SAVE][ ,LAST])
[,FMH={NO I YES} ]
[,CCOMPL=NO]
[ , DEFRESP=YES ]
[,DEST={symbo1ic address I YES} ]-->TCAM only
3790 (SCS Printer) Logical Unit
I
I
I
I
I
I
IL______
DFHTC
~
______
TYPE= (WRITE[ ,WAIT][ ,SAVE][ ,LAST])
[,CCOMPL=NO]
[,DEFRESP=YES]
[,DEST={symbo1ic addresslYES} ]->TCAM only
I~
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _• _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~
3790 (3270-Display) and 3790 (3270-Printer) Logical Units
These logical units are sometimes referred to collectively as the 3270
compatibility logical unit. Support and macro instruction syntax are
the same as for the 3270 logical unit, apart from the following
exceptions:
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
217
•
DPBTC TYPE=READB is not supported for the 3270-printer logical
unit.
•
DPBTC TYPE=COPY is not supported for the 3270-display logical unit.
•
When using the DPHTC TYPE=PRINT macro, if PEATURE=PTRADAPT has been
specified in the TCT, allocation of the printer is controlled by
the 3790. If PEATURE=PTRADAPT has not been specified, allocation
of printers is governed by the PRINTTO and ALTPRT options specified
in the TCT.
3790 Batch Data Interchange Logical Unit
Support and macro instruction syntax identical to 3770 Batch Logical
Unit.
218
CICS/VS APRM(ML)
7770 Audio Response Unit
DFHTC
TYPE= (READ[ ,WAIT][ ,SAVE])
DFHTC
TIPE=(WRITE[ ,WAIT][ ,SAVE])
Although CICS/VS does not distinguish between special codes (characters)
entered at an audio terminal (for example, the 2721 Portable Audio
Terminal), an application program is not precluded from performing
special functions upon encountering these codes. For example, the
following special hexadecimal codes may be entered from a 2721:
I
IKey
I
C~LL
ICode
END
CNCL
#
VERIFY
RPT
EXEC
F1
F2
F3
F4
F5
00
000
I IDENT
137
118
13B
12D
13D
126
IB1
IB2
IB3
IB4
IB5
lAO
13B
111,
(see note)
(see note) or 7B
(see note)
(see note) or BO
12, 13, or 14 plus two other characters
L
Note: These codes cause a hardware interrupt and are in the terminal
input/output area (TIOA) immediately following the data; the codes are
not included in the data length.
For fUrther information concerning the 2721, see the publication 2721
Portable Audio Terminal Component Description.
The following special hexadecimal codes may be entered from a TouchTone telephone (Touch-Tone is the trademark of the American Telephone
and Telegraph Company.)
I
IKey
ICode
I
1*
1#
lAO
13B or BO
The * and # characters of a Touch-Tone telephone correspond to the 00
and 000 characters, respectively, on a 2721 Portable Audio Terminal.
The # and 000 characters cause an end-of-inquiry (EOI) hardware
interrupt (X' 3B') unless the EOI Disable feature ('3540) is installed on
the 7770 Audio Response Unit !odel 3. If this feature is installed, the
user can elect that neither, or only one, of the # and 000 characters
Chapter 4.2.
Terminal Control (DFHTC !acro Instruction)
219
viII cause a hardware interrupt. At the option of the user, either or
both of the • and 000 characters do not cause a hardware interrupt, are
presented in the TIOA with the rest of the data, and are included in the
data length.
If, after receiving at least one character from a terminal, no other
characters have been received by the 1110 for a period of five seconds,
the 1110 automatically generates an EOI hardware interrupt that ends the
read operation.
LUTYPE4 Logical Unit
DFHTC
TYPE= (READ[, WAIT][ ,SAVE])
[,EODS=symbolic address]
[,EOC=symbolic address]
[,INBF~B=symbolic address]
DFHTC
TYPE= (WRITE[ ,WAIT][ ,SAVE][ ,LAST])
[ , F~H= {NO I YES} ]
[,CCOMPL=NO]
[ ,DEFRESP=YES]
L
DFHTC I• TYPE=SIGNAL
I
{,SIGADDR=symbolic address I ,WAIT=YES}
~
I
_____ ~_______ L ________________________________________________________~
The TYPE=SIGNAL macro instruction is required to detect a hard
request change direction (RCD) signal from the terminal. The
application program should not issue a TYPE=WRITE macro instruction
following such a signal.
LUTYPE4 terminals can operate in unattended mode. The application
programmer can detect unattended mode by testing the TCTTE field TCTEMOP
under the mask TCTEMOPU.
220
CICS/VS APRM(ML)
Other CICS/VS-Supported Terminals
DFHTC
TYPE= (READ[, WAIT][ , SAVE])
DFHTC
TYPE=(WRITE[,WAIT][ ,SAVE])
[ , DEST= {symbolic address I YES} ]->TCAl! only
TCAM Supported Logical Units (CICS/OS/VS Only)
~----~-----r'--------------------------------------------------~
I
DFHTC I TYPE= ({READI READL} [ ,WAIT][ ,SAVE])
I
[,INBFMH=symbo1ic address]
,I
r-
I
I DFHTC
I
I
I
I
I
I,
TYPE=({WRITEIWRITEL}[,WAIT][,SAVE][,ERASE][,LAST]
[ ,ERASEAUP])
[ , FHR= {NO I YES} ]
[ ,CTLCHAR= {hex number IYES} ]
[,LINEADR={numberIYES} ]
[ ,DEST= {symbolic address I YES} ]
Chapter 4.2.
Terminal Control
(DFHTC Macro Instruction)
221
Operands of DFHTC Macro
CCOKPL=NO
•
Used with VTA! logical units only.
indicates that the last request/response unit ~U) sent as a
result of this write request will not complete the chain. If
this operand is omitted, the last RU will terminate the chain.
Before this operand may be used, the system programmer must
have specified that the application program may control
outbound chaining indicators by coding a DFHPCT TYPE=OPTGRP
macro instruction with the CCONTR=YES operand. If CCOKPL=NO is
used without this support, the task will be abnormally
terminated.
There are a number of restrictions on the use of the CCO!PL=NO
operand; these restrictions are as follows:
•
If CCOKPL=NO is used without the authority (CCONTR) of the
system programmer, the task will be abnormally terminated.
•
CCO!PL=NO cannot be used if the DEFRESP=YES operand is
specified.
•
If CCOMPL=NO is specifiec, the application program must not
issue a read request until a write request that does not
specify CCO!PL=NO has been issued; failure to observe this
restriction will lead to abnormal termination of the task.
•
CCOMPL=NO is not valid for a combined write and read
request, including conversational write operations.
TYPE=LAST ~s ignored if it is not FOC or OC.
•
Used with 3650 interpreter logical units only.
CONNECT=
This operand specifies the type of connection to be
establish ed.
ACTIVATE
specifies that the 3650 application program will not
communicate with the host cpu.
CONVERSE
specifies that the 3650 application program will
communicate with the host CPU.
222
CICS/VS APRM (ML)
CTLCHAR=
•
Used for 3270 logical units, 3650 host-conversational
(3270) logical units, 3790(3270-display), and 3790 (3270printer) logical units only.
This operand is used (1) in a DPHTC TYPE=WRITE macro
instruction to provide the hexadecimal representation of the
write control character (WCC) that controls the requested write
operation, or (2) except for the 3650 host conversational
(3270) LU, in a DPHTC TYPE=COPY macro instruction to provide
the hexadecimal representation of the copy control character
(CCC) that controls and defines the copy function to be
performed.
hexadecimal number
is the hexadecimal representation of the WCC or CCC
required for the operation specified in the TYPE= operand
of this DPHTC macro instruction.
YES
indicates that the appropriate bit configuration has been
placed in TIOACLCR.
Por DPHTC TYPE=WRITE, if the functions defined by the WCC only
are to be performed (that is, no data stream is to be
supplied), TIOATDL must contain zero. If the CTLCHAR operand
is omitted, all modified data tags are reset to zero, and the
keyboard is restored. Por DFHTC TYPE=COPY, if the CTLCHAR
operand is omitted, the contents of the entire buffer
(including nulls) are copied and the start printer flag is not
on.
DEPRESP=YES
•
Used with VTAM logical units only.
indicates that a definite response is required when the write
operation has been completed. DEPRESP=YES cannot be specified
if the CCOMPL=NO operand is used.
This operand specifies, for this write operation only, that a
definite response is required, even if neither the MSGINTEG
operand nor the PROTECT operand has been specified in the
DPHPCT TYPE=OPTGRP macro instruction by the system programmer.
DEST=
indicates that the output message is to be sent to a TCAM
destination other than the source TCAM terminal.
This operand is meaningful only for TCAM-supported terminals.
symbolic name
is the symbolic address of the storage area containing the
TCAM destination to which the message must be sent.
YES
indicates that the application program has placed the fourbyte message destination in TCTTEDES before issuing the
WRITE. This can be used to allow dynamic selection of the
message destination.
Chapter q.2.
Terminal Control (DPHTC Macro Instruction)
223
ENDFILE=symbolic address
•
Used for 3740 Data Entry System only.
indicates the label of the routine that is to receive control
when end-of-file is encountered on batch input. It is set when
a null block is received, indicating the end of a physical
file. The task must continue reading.
ENDINPT=symbolic address
•
Used for 3740 Data Entry System only.
indicates the label of the routine that is to receive control
when end-of-input is reached on batch processing. It is set by
CICS/VS when an end of transmission signal is received and the
ENDPILE indicator was set. After this condition the task must
not issue any further reads to the device but must return to
CICS so that the 3740 can be set to receive a new batch of
input.
ENDMSG=NO
indicates that the block sent as a result of the write request
does not complete the message. If this operand is omitted, the
message will be regarded as complete when the write reguest has
been fulfilled.
Before this operand may be used, the system programmer must
have specified that the application program m~y control
outbound chaining by coding a DFHPCT TYPE=OPTGRP macro
instruction with the MSGPREQ=CCONTRL operand. If ENDMSG=NO is
used without this support, the task will be abnormally
terminated.
There are a number of restrictions on the use of the ENDMSG=NO
operand; these restrictions are as follows:
224
o
If ENDMSG=NO is used without the authority
(MSGPREQ=CCONTRL) of the system programmer, the task will
be abnormally terminated.
•
If ENDMSG=NO is specified, the application program·must not
issue a read request until a write reguest that does not
specify ENDMSG=NO has been issued; failure to observe this
restriction will lead to abnormal termination of the task.
•
ENDMSG=NO is not valid for a combined write and read
request, including conversational write operations.
CICS/VS APRM(ML)
BOC=symbolic address
o
Used for logical units only.
specifies the label of the routine that is to receive control
if the request/response unit (RU) is received with the end-ofchain (BOC) indicator set. If this operand is specified, the
WAIT parameter of the TYPB operand is assumed. If an inbound
FMH is received, the INBFMH operand will override this operand.
If an end-of-data-set FHH is also received, the BODS operand
will override both this operand and the INBFMH operand.
(Overridden operands can be specified in a DFHTC TYPE=WAIT
macro.)
EODS=symbolic address
•
Used for 3650 interpreter logical units, batch logical
units, and LUTYPE4 logical units only.
•
Cannot be used for 3650 Host Command Processor logical
units.
Indicates the label of a user-written routine that is to
receive control if an end-of-data-set FHH is received. The
TIOA contains the BODS indicators. If EODS is specified, the
WAIT parameter of the TYPE operand is assumed. If EODS is
specified, and end-of-data-set is received, the EOC and INBFMH
operands are overridden; they can be specified in a DFHTC
TYPE=WAIT macro within the end-of-data-set routine.
Symbolic address is the address to which control is to be given
if the CICS EODS indicator is set on. The indicator is set
when a READ is issued and there is no data remaining for this
data set.
EOF=symbolic address
indicates the label of the routine that is to receive control
when end-of-file is encountered on batch input. This operand
can be used in a special initialization macro instruction,
DFHTC EOF=symbolic address, to test for the end-of-file
condition upon initial connection to a 3735. It must be
included in the initialization section of the application
program that handles 3735 input, preceding other DFHTC macro
instructions.
Note: When the EOF condition occurs, TIOATDL is set to binary
zeros to indicate that the TIOA for the input operation
contains no valid data.
FMH=
•
Used for 3600 (3601), 3650 host-conversational (3270), 3650
host-command processor, LUTYPE4, 3770 batch, 3790 full
function, 3790 inquiry, and 3790 batch data interchange
logical units only.
This operand indicates whether the function management header
(FMR) has been placed in the TIOA by the application program.
If FMH is omitted, NO is assumed.
For the 3600 (3601) and 3790 inquiry logical units, an FMH is
required and is provided as described belove For the 3650
host-conversational (3270) logical unit, the FMH is required i f
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
225
outboard maps are to be used; the FMH in such cases can be
provided by BMS, if BMS is being used, or otherwise, by the
application program. For LUTYPE4 and batch logical units, the
FMH is required for device-selection and is provided as
described below.
NO
indicates that the application program has not placed the
FMH in the TIOA. For the 3600 (3601) and 3790 inquiry
logical units, CICS/VS is responsible for placing the FMH
in the TIOA; if NO is specified, space must be reserved in
the TIOA for the FMH. For the 3650 host-conversational
(3210) logical unit, CICS/VS does not build an FMH, and the
data is transmitted unmodified. For all other logical
units, no FMH is sent; refer to the appropriate CICSjVS
subsystem guides for details of when an FMH is necessary.
YES
indicates that the application program has placed the FMH
into the TIOA. Refer to the appropriate CICS/VS subsystem
guides for size and format of the FMH for a specific
terminal. The FMH=YES and LDC=YES options are mutually
exclusive.
FORCE=YES
•
Used for interactive logical units only.
This operand indicates that the write operation is to be
preceded by an outbound SIGNAL data-flow-control command to
force the terminal into receive mode. This operand is used
only for interactive logical units operating in contention
mode, and is ignored otherwise.
INBFMB=symbolic address
specifies the label of the routine that is to receive control
if the request/response unit (RU) contains an FMH, and CICS/VS
has passed this FMH to the application program. The presence
of an inbound FMH means that, if this operand is specified, the
EOC operand is overridden. If an end-of-data-set FMH is
received, the EODS operand will override the INBFMH operand.
(Overridden operands can be specified in a DFBTC TYPE=WAIT
macro.)
For this operand to be effective, the system programmer must
have specified INBFMH=ALL or EODS in the PCT entry for the
transaction. If INBFaH=NO is specified, inbound FMHs will not
be passed to the application program, and the INBFMH operand
will never be operative.
LDC
•
Used for the 3601 logical unit (but not for the 3614, even
if attached to the 3601) only.
This operand specifies the mnemonic to be used by CICS/VS to
determine the logical device code (LDC) that is to be
transmitted to the logical unit in the function management
header.
226
CICS/VS APRM
~L)
mnemonic
is the two-character mnemonic used to determine the
appropriate LDC numeric value. The mnemonic represents a
LDC entry in the DFHTCT TYPE=LDC macro instruction.
YES
indicates that the application program has placed the
mnemonic in TCATPLDH. The LDC=YES and FMH=YES options are
mutually exclusive.
LINEADR=
•
Used for 3270 in 2260 Compatibility Mode only.
This operand specifies that writing is to begin on a specific
line of a 2260/2265 screen simulated on a 3270 operating in
2260 compatibility mode.
number
is the hexadecimal equivalent of the starting line number.
For the 2260, X'FO' through XIFBI correspond with line
numbers 1 through 12 respectively. For the 2265, XIFOI
through XIFEI correspond with line numbers 1 through 15
respectively.
YES
indicates that the hexadecimal equivalent of the line
number has been placed in TIOALAC.
NONVAL=address
•
Used with 3650 application programs only.
This operand indicates the label of the user-coded routine to
receive control if the name specified in the PRGNAME operand is
invalid.
NORESP=address
•
Used with 3650 logical units only.
This operand indicates the label of a user-coded routine to
receive control if there is a no error response.
PRGNAME=name
o
Used with 3650 logical units only.
This operand indicates the name of the 3650 application
program. The name (up to eight characters) is transmitted to
the 3651 for verification by the 3650 control program.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
221
RDATT=symbolic address
indicates the label of the routine to which control is to be
transferred if the read operation that responds to a DPHTC
TYPE=READ macro instruction is terminated by pressing the
attention (ATTN) key rather than the return key.
This operand is meaningful only if 2741 Read Attention
support has been generated in the CICS/VS system. See "Read
Attention" and "Write Break" under "2741 Communication
Terminal" earlier in this chapter.
~:
SIGADDR=symbolic address
•
VTAM only
specifies the symbolic address of the routine to be given
control if SIGNAL is received.
TYPE=
describes the terminal or logical unit operations required, as
follows:
TYPE=CBUPP
•
Used with 2980 General Banking Terminal only.
This is a stand-alone parameter used to place a message in the
common buffer of the 2972 terminal control unit; the 2972
associated with the current TCTTE receives the output message.
Both write and wait are implied.
The output message is translated according to the model
of 2980 described by the current TCTTE. If more than one model
is attached to a 2972 Terminal Control Unit, the contents of
the common buffer are intelligible only to the model for which
the message was translated. Since shift characters are added
to the message by CICS/VS during translation, the length of the
message is dependent upon the contents of the message. Up to
23 characters, including shift characters, can be transmitted.
~:
TYPE=COPY
•
Valid only for BSC-connected devices which have the copy
feature, that is, BTAM remote connection, or VTAM non-SNA
remote connection.
This parameter is used to copy the format and data contained in
the buffer of one terminal into the buffer of another terminal
attached to the same remote 3270 control unit. The terminal
from which data is to be copied can be identified in either of
tvo ways:
1. Set TIOATDL to a value of 1, and the first byte of the
output data area (TIOADBA) to the physical address of the
terminal to be copied; or
228
CICS/VS APRM(ML)
2. Set TIOATDL to a value of 4 and the first four bytes of the
output data area (TIOADBA) to the terminal identification
of the terminal to be copied. If the terminal
identification is less than four bytes, it must be leftjustified with blank padding on the right.
The copy control character (CCC), which controls and defines
the copy function to be performed, must be supplied in the
CTLCHAR operand of the DFBTC macro instruction.
Note: For VTAM-supported 3270 logical units, it is not
possible to supply the physical address of the terminal to be
copied; the terminal identification must be supplied.
TYPE=DISCONNECT
•
Switched lines and logical units only.
For switched lines, DISCONNECT is used to break the line
connection between the terminal and the computer; if the
terminal is a buffered device, the data in the buffer(s) is
lost.
•
CICS/VS does not automatically disconnect a 3270 display at
the end of a transaction. A disconnection occurs at the
request of a terminal operator, at the request of the
application program (through this macro instruction), or
after a specified number of time-outs are encountered by
DFHTEP for the terminal.
(Refer to the CICSIYS~tem
f£Qgrammer's Reference Manual for information about
DFHTEP.)
•
When used with a TCAM terminal or logical unit, DISCONNECT
sets the X'08' bit in the communication control byte (CCB)
sent to TCAM. The message handler should provide the
necessary function (that is, issue IEDH~LT, to terminate
the logical-unit session) for disconnect.
•
When used with VTAM logical units, DISCONNECT, uhich does
not become effective until the task has been terminated,
terminates the session, without causing a physical
disconnection.
TYPE=ENDFILE
•
Used for 3740 Data Entry system only.
indicates that an end-of-file record is to be written to the
terminal.
TYPE=ENDOUTPUT
•
Used for 3740 Data Entry System only.
indicates that an end-of-output record is to be written to the
terminal.
TYPE=EODS
•
Used with 3650 interpreter logical units only.
causes an end of data set FMH to be sent on behalf of the task.
An I/O area need not be supplied by the CICS/VS application
program.
Refer to the CICS/yS 3650 Guide for details about
communicating with a 3650 application program.
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
229
Note: If the application receives the FMH, the FMH may have
been presented on completion of a previous read request. The
actual end of the data set is not until the CICS EODS indicator
is set on.
TYPE=ERASE
•
Used with 2260 Display station, 3270 Information Display
System, 3270 logical units, 3650 host-conversational
logical units, 3790 (3270-display), and 3790 (3270-printer)
logical units only.
This parameter is used with the WRITE or WRITEL operand. It
blanks out the screen and sets the cursor to the upper left
corner. Normally, TYPE=ERASE would be used on the first output
request of a transaction to prepare the screen for new output
data.
TYPE=ERASE also sets the screen size to that specified for the
transaction that issues the command. Therefore when switching
from one screen size to another between transactions, a
TYPE=BRASE must be issued to set the screen size of a new
transaction. If one is not issued, the screen size will remain
unchanged from a previous transaction's setting.
The CLEAR key, if used within a transaction, sets the screen
size to its default. However, CICS/VS will reset the
transaction specified size following a CLEAR operation.
Note:
To erase the screen,
1. place the address of a TIOA into TCTTEDA,
2. place a data length of 0 into TIOADTL, and
3. issue a DFHTC TYPE=(WRITE, ERASE) macro instruction.
If operating in 2260 compatibility mode, the TIOA should
contain only a start symbol and the data length in TIOATDL
should be set to 1 before issuing the OFHTC TYPE=(WRITE,
ERASE).
TYPE=ERASE and OEFRESP=YES are mutually exclusive.
TYPE=ERASEAUP
•
Used with 3270 logical units, 3650 host-conversational
(3270) logical units, 3790 (3270-display) and 3790 (3270printer) logical units only.
This parameter issues an "erase all unprotected" command
command and causes the following functions to be performed:
1. All unprotected fields are cleared to nulls (X'OO).
2. The modified data tags (MOTs) in each unprotected field are
reset to zero.
3. The cursor is positioned to the first unprotected field.
4. The keyboard is restored.
Neither WRITE, ERASE, nor COpy can be specified in a DFHTC
macro instruction that includes the ERASEAUP parameter. No
data stream is supplied.
230
CICS/VS APRM(ML)
•
This parameter is not meaningful for a 3270 operating in
2260 compatibility mode.
TYPE=LAST
signals CICS/VS that the WRITE is the last output for a
transaction and, therefore, the end of a bracket. Specifying
this parameter can improve system performance for VTAM logical
units except when used with the 3270 logical unit.
•
This parameter has no effect when used with a 3270 logical
unit.
TYPE=NOTRANSLATE
prevents translation of form description program ~DP) records
which are to be transmitted to a 3735 using ASCII transmission
code.
(For further information, see 113735 Programmable
Buffered Terminal", earlier in this chapter.)
TYPE=PASSBK
•
Used with 2980 General Banking Terminal only.
This is a stand-alone parameter used to cause output to be
printed on a banking passbook. Both WRITE and WAIT are
implied. If a passbook is not present, no printing occurs.
error message can be sent to the operator of the terminal
associated with the requesting task.
An
TYPE=PRINT
o
Used with 3270 logical units, 3650 host-conversational
(3270) logical units, 3790 (3270-display) , and 3790(3270printer) logical units only.
This parameter specifies that the data currently displayed on a
3270 display is to be printed on an eligible 3270 printer.
TYPE=PROGRAM
•
Used with 3650 devices only.
This parameter is used to request the loading of a 3650
application program. If the program is loaded, control is
returned to the next sequential instruction following the DFHTC
TYPE=program macro instruction unless NORESP=program is
specified. Otherwise, control is returned to an address
specified by one of the other operands of the macro instruction
as listed below.
TYPE=PSEUDOBIN
indicates that the data being read is. to be translated from
System/7 pseudobinary representation to hexadecimal.
(For more
information about System/7 programming, see "System/7 11 , earlier
in this chapter.)
TYPE=READ
indicates that the data is to be read from a terminal or
logical unit.
When the contents of a 3270 buffer are read the programmer
should be aware that the attention identifier byte and the
cursor address are made available at TCTTEAID and TCTTECAD
respectively. A set of standard symbolic names for testing the
3270 attention identifier is provided in a copy book called
DFHAID. Por further details refer to "Standard Attention
Chapter 4.2.
Terminal Control (DFHTC Macro Instruction)
231
Identifier List (DFHAID)
Support ...
II
in the chapter "Basic Mapping
TYPE=READB
•
Used with BTAM 3270 and 3270 and 3790(3270-display) logical
units only.
This parameter reads the contents of the 3270 buffer, beginning
at buffer location 0 and continuing until all contents of the
buffer have been read. All character and attribute sequences
(including nulls) appear in the input data stream in the same
order that they appear in the 3270 buffer. READB cannot be
specified for TCAM-supported terminals nor can it be used for
3790 (3270-printer) logical units.
Note: Because of the relatively long transmision times
required to transmit the entire contents of a remote 3270
buffer, the READB parameter should be used primarily for
testing and diagnosing; the COpy parameter, which permits a
selective transfer of buffer contents should be used in all
other cases.
TYPE=READL
•
Used with 2260, or 3270 operating in 2260 compatibility
mode, only.
indicates that the keyboard is to remain locked at the
completion of a data transfer. This parameter is applicable
only to CICS/OS/VS, but may be used on a CICS/DOS/VS
application if compatibility with CICS/OS/VS is desired.
TYPE=RESET
•
Used with binary synchronous devices only.
This operand is used to relinquish use of a communication line;
the next BTAM operation will be a read or write initial. RESET
is not supported by TCAM, because line control is performed by
TCAM in the MCP.
TYPE=SAVE
in the case of a read operation, it indicates that the TIOA
used in a previous terminal operation is not to be used as an
input area; a new TIOA is acquired. For a write operation, it
indicates that the TIOA whose address is in TCTTEDA is not to
be released upon completion of the write operation; however,
there is no guarantee that TCTTEDA will remain unchanged.
TYPE=SIGNAL
•
Used with VTAM interactive and LUTYPE2, LUTYPE3, LUTYPE4
and SCSPRT logical units, and VTAM 3600 (3601) logical
units, only.
Indicates that this macro instruction specifies the action to
be taken by the application program when an inbound SIGNAL
data-flow-control command is received from the logical unit.
The four-byte field TCTESIDI in the terminal control table
terminal entry (TCTTE) is set to the signal code received from
the logical unit. If a hard request change direction (RCD)
signal is received (signal code X'00010000') from an LUTYPE4
232
eICS/VS APRM(ML)
unit, the transaction should either end or read from the unit.
An attempt to follow the signal with a write would be an error.
Most logical units will send a signal with a code of
X'00010000' when an attention key is pressede
TYPE=STRFIELD
•
Assembler language only.
specifies that the TIOA contains structured fields.
If this
operand is specified, the contents of all structured fields
must be handled by the application program.
(Structured fields
are described in the CICS/yS IBM 3270 Guide.)
CTLCHAR and
ERASE are mutually exclusive with STRFIELD and their use will
generate an MNOTE.
TYPE=TEXT
•
Used with 3270 only.
is meaningful only when used in conjunction with a READ
request. It specifies a temporary override of the uppercase
translation feature of CICS/VS to allow the task to receive a
message containing both uppercase and lowercase data.
TYPE=TRANSPARENT
•
Applicable to System/3 when it indicates that output is to
be sent in transparent mode (with no recognition of control
characters, and accepting any of the 256 possible
combinations of eight bits as valid transmittable data).
•
Applicable to System/1 when it indicates that the data
being read is not to be translated.
TYPE=WAIT
ensures that the terminal or logical unit operation requested
in the macro instruction is completed before starting
subsequent processing. WAIT can be coded separately from a
READ to accomplish overlapping of logical unit I/O operations;
or with the EOC, EODS, or INBFMH operand, for example, to give
control to user-written routines from within an end-of-data-set
routine entered as a result of specifying the EODS operand.
TYPE=WRITE
indicates that data is to be written to a terminal or logical
unit.
TYPE=WRITEL
•
Used for a 3210 operating in 2260 compatibility mode only.
This parameter indicates that the keyboard is to remain locked
if locked previously, or to remain unlocked if unlocked
previously, at the completion of data transfer.
Chapter 4.2.
Terminal Control
(DFHTC Macro Instruction)
233
If DFHTC macro instructions are issued in the following
sequence, the keyboard is locked or unlocked as indicated:
READ
WRITEL
READL
READL
WRITEL
WRITEL
WRITE
WRITEL
WRITEL
READ
WRITE
READL
READ
WRITEL
L
L
L
L
L
L
U
U
U
L
U
L
L
L
VALID=address
•
Used with 3650 devices only.
This operand indicates the label of a user-coded routine to
receive control if the name specified in the PRGNAME operand is
valid but sufficient resources are not available in the 3651 to
initiate the 3650 application program. This routine can
determine whether a DFHIC TYPE=INITIATE or DFHIC TYPE=PUT macro
instruction is to be issued in order to restart the 3650
application program later.
WAIT=YES
specifies that the task is to be suspended until SIGNAL is
received. This request is ignored if the logical unit cannot
send a SIGNAL command; the contents of field TCTESIDI will be
set to X'OOOOOOOO' in these circumstances.
WRBRK=symbolic address
is the symbolic address to which control is transferred if a
write operation started in response to this DFHTC TYPE=WRITE
macro instruction is interrupted by the terminal operator
pressing the Attention (ATTN) key.
•
234
This operand is meaningful only if 2141 write Break support
has been generated into the system, an option available
only under CICS/OS/VS. See "Read Attention" and "Write
Break" under "2141 Communication Terminal" earlier in this
chapter.
CICS/VS APRM(ML)
Chapter 4.3. Basic Mapping Support
Basic mapping support (BMS) provides the CICS/VS application programmer
with various formatting services that assist in interpreting input data
streams from and preparing output data streams to the terminal network.
These formatting services are provided by BMS modules that act as an
interface betveen the user's application program and the CICS/VS
terminal control program.
The application program passes data to BMS and receives data from BMS
in a device-independent format.
BMS macro instructions are issued by
the application program to control formatting of the data and to
initiate input from and output to the terminal network.
Advantages of BMS
The two principal advantages to be obtained by using BMS are device
independence and format independence.
DEVICE INDEPENDENCE
Device independence permits the application program to send data to a
terminal or to receive data from a terminal without regard for the
physical characteristics of the terminal. BMS can be used for
communication uith any of the following devices and logical units:
1050
2740
2741
2770
2780
2980 Models 1 and 2
2980-4 (keyboard and printer only)
3270
3780
TttX
Tape storage devices
Disk storage devices
CRLP (a device declared as card-reader-in/line-printer-out)
TCAM-connected terminals (defined by TRMTYPE=TCAM in DFHTCT
TYPE=TERMINAL macro)
TCAM logical units (defined by TCAMFET=SNA in DFHTCT TYPE=LINB macro
and SESTYPE=36001376713770137901BCHLUIINTLU in DFHTCT
TYPE=TERMINAL macro)
VTAM logical units:
3270
LUTYPE2
LUTYPE3
LUTYPE4
SCSPRT
3600
3650 ~ost-conversational ~270) and interpreter LUs only)
3767
3770
3790 (all except inquiry LU)
Chapter 4.3.
Basic Mapping Support
235
Some special BMS programming considerations that apply only to
particular terminal sUbsystems are described in the various CICSjVS
subsystem guides (for example, the IBM 3600/3630 Guide). These guides
are listed in the Bibliography.
With BMS, a CICS/VS installation with more than one type of terminal
need provide only one program for each application transaction to
support all terminal types in the installation. BMS identifies which
terminal type is requesting use of the application program and provides
for the conversion of the device-dependent data stream to and from the
device-independent format used by the application program. A CICS/VS
installation using only one type of terminal may nevertheless wish to
use the formatting services of BMS to facilitate the addition of other
terminal types or the conversion to another terminal type in the future.
FORMAT INDEPENDENCE
Format independence permits the application program to provide data to
one or more terminals or to receive data from a terminal without regard
for the physical placement of fields within the data stream or on the
terminal.
All references to data by the application program are through
symbolic field names. The placement of fields within the data stream is
accomplished by BMS through the use of information stored in data format
tables called maEs. A CICS/VS installation in which BMS is used may
rearrange the fields to be included in a terminal message by simply
changing some values stored in the map that defines the format of the
message. The application program that causes the message to be written
need not be modified. Programming maintenance can thus be considerably
simpler than if BMS were not used.
Format independence also permits certain constant information, such
as headings, field-identifying keywords, and 3270 screen formats, to be
stored in maps. These constants can be modified simply by changing
their values in the maps. Any programs that refer to the maps benefit
from the changes, but none of the programs themselves need be modified.
The format independence provided by BMS may be compared with the
independence provided by DL/I for data bases. Both remove from the
application program the requirement to know the physical placement of
fields within the data record or message.
Fields may be physically
rearranged, removed, or added without necessitating program maintenance
on all application programs using the record or message.
Facilities of BMS
The facilities that BMS provides are data mapping and formatting,
terminal paging, and message routing.
236
CICS/VS APRM (ML)
DATA MAPPING AND FORMATTING
Data mapping is the technique used by BMS to convert the standard
device-independent data format that the application program uses to and
from the device-dependent data stream required for the particular
terminal type in use. Device-dependant control characters are embedded
or removed by BMS during this processing.
The application program may select any of three standard data formats
in which to provide or accept data from BHS: field data format, block
data format, or text data format.
When field data format is used, data is passed to BMS as separate
fields. Each field is given a symbolic field name by the application
programmer. This name is used when passing data to, or retrieving data
from, BMS. Each field consists of a two-byte length area (used by BMS
on input), a single attribute byte (used for 3270 output operations
only, but present for all terminal types), and the data area.
A map
describing the position of the field when displayed or printed, the data
length, and other information about each field is created to control the
mapping function.
When block data format is used, data is passed to BMS as line
segments. Fields positioned within the line segments may be given
symbolic field names to aid the application program in positioning the
fields. Each field provides for a single attribute byte and the data
area. A gap consisting of several blanks may separate consecutive
fields in the line segment. A map is used to describe the number and
lengths of line segments, the field positions when displayed or printed,
data lengths, and other necessary information.
When text data format is used, output data consisting of a data
stream with optional new-line (XI lSI) characters is passed to BMS.
BMS
divides the data stream into lines no longer than those defined for the
particular terminal to which the data stream is related. BMS will only
allow a line break to occur where it encounters a blank (X'40').
If a
word will not fit into the space remaining in a line, BMS places the
Whole word on a new line. If new-line characters are included in the
data stream, they too are honored. CICS/VS inserts the appropriate
leading characters, carrier returns, and inle characters, and eliminates
trailing blanks from each line. If tab control characters are contained
in the data stream, the user should also supply all the necessary newline characters. Maps are not used with text data format.
Field data format is the commonest data format for both display and
printer terminals.
Block data format may be used with both display and
printer terminals, but it is more useful for input operations on printer
terminals. Text data format is used with both display and printer
terminals and is especially convenient for handling data that is not
divided into fields. When text data format is used with a 3270 device,
an attribute byte appears on the 3270 as a blank at the beginning of
each line and in front of each new piece of data.
Chapter 4.3.
Basic Mapping support
237
TERMINAL PAGING
Terminal paging permits the application program to (1) combine several
small mapped data areas into one or more pages of output, or (2) prepare
more output than can be contained in one page of output. By definition,
a ~ is the physical area of a terminal on which data is displayed or
printed at one time. The size of the area (in numbers of lines and
columns) is specified for the particular terminal in the CICS/VS
terminal control table by the system programmer.
Since a page of output may be constructed by BMS from several small
maps, it is convenient to generate these maps together in a map set. A
map set is a collection of maps generated and stored together in the
CICS/VS program library. A reference to one map in the map set causes
the entire map set to De loaded into storage for the duration of the
task or until another map set is referred to by the task. DFHMSD,
DFHMDI, and DFHMDF macro instructions, described later in this chapter,
are used in constructing the map set.
During execution, the application program issues DFHBMS TYPE=PAGEBLD
macro instructions to position portions of an output page. If all the
data cannot be contained on one page, BMS recognizes an overflow
condition and can transfer control to an overflow routine Hithin the
application program. This routine normally causes the current page to
be written to temporary storage, a new paga to be started, a heading to
be placed on the new page, and the data causing the overflow to be
mapped on the new page. As each page of the output message is
completed, the page is written to temporary storage to await completion
of the 10qic~!_mg§2~~. A logical message is the result of one or more
BMS requests for output services all of which have the same disposition
(OUT, STORE, or RETURN, as explained later in this chapter). To cause
the logical message to be completed, the application program issues a
DFHBMS TYPE=PAGEOUT macro instruction. Alternatively, the logical
message is completed upon termination of the application program unless
a short-on-storage condition exists, in which case the logical message
is deleted.
Terminal paging provides the additional function of building a
logical message without the use of maps. A DFHBMS TYPE=TEXTBLD macro
instruction is issued to request this type of page building. The data
is passed to BMS as text data, which BMS places on succeeding lines (and
pages, if necessary) without reference to maps. A word is not split
between lines; any word that cannot fit on the remaining portion of a
line is placed on the next line. The formatting of the logical message
can be controlled through the data itself by embedding neW-line
characters (XI1SI) within the data. To cause the TEXTBLD logical
message to be completed, the application program issues a DFHBMS
TYPE=PAGEOUT macro instruction or terminates execution.
DFHBMS TYPE=PAGEBLD and TYPE=TEXTBLD macro instructions cannot be
used to build portions of the same logical message. The process of
building a logical message can be discontinued by means of a DFHBMS
TYPE=PURGE macro instruction. This instruction deletes the portions of
the message already built in main storage or on temporary storage.
MESSAGE ROUTING
Message routing permits an application program to build and route a
logical message to one or more terminals. The message is automatically
scheduled for each designated terminal, to be delivered as soon as the
terminal is available to receive messages or at some future time.
238
CICS/VS APRM (ML)
The page building facil~ty of BMS is used for message routing, so the
design of application programs is very similar for the two facilities.
Message routing allows application-built messages to be sent to any
prescribed terminals.
To initiate a routing operation, the application program issues a
DFHBMS TYPE=ROUTE macro instruction followed by DFHBMS
TYPE=(PAGEBLD,STORE) or TYPE=(TEXTBLD,STORE) instructions to build the
logical message that is to be routed. A DFHBMS TYPE=PAGEOUT macro
instruction terminates the page building and causes the message to be
routed. When individual logical messages are routed to a terminal, they
are not necessarily delivered in the sequence in which they were issued.
If a specific sequence is required, the pages must be output as one
message.
A parameter of the DFHBMS TYPE=ROUTE macro instruction points to a
list of terminals to receive the routed message. The list may contain
the terminal identification and operator identification of each terminal
designated to receive the message. If only a terminal identification is
specified, the message is routed to that terminal, regardless of who is
signed on at the terminal. If both the terminal identification and the
operator identification are specified, the message is routed to the
terminal but delivered only when the specified operator is signed on.
If only the operator identification is specified, BMS scans the terminal
control table and delivers the message to the first terminal at which
the operator is signed on.
Another paramet8r of the DFHBMS TYPE=ROUTE macro instruction is a
specific operator class code. If specified, only an operator signed on
with that class code may receive the routed message. One to twenty-four
class codes may be assigned to operators in the CICS/VS sign-on table.
The DFHBMS TYPE=ROUTE macro instruction further designates whether
the message is to be delivered as soon as possible or at a specific time
or after some inte~val of time. If the routed message cannot be
delivered within a specified length of time, an error message may be
returned to the terminal sending the message or to some designated
alternative terminal. The message may be deleted, or it may be retained
indefinitely -- until delivered or until deliberately deleted by an
operator at the receiving terminal.
If a message is to be routed to more than one terminal type, BMS
builds a device-dependent message for each terminal type. Each such
message is stored on temporary storage until all terminals for which it
is destined have received the message. If a terminal is scheduled to
receive a message but is not eligible, the message is stored until one
of the following conditions occurs:
o
A change in terminal status allows the message to be sent.
o
A time period (specified at system generation) has elapsed, causing
the message to be deleted by BMS.
o
The message is deleted by the destination terminal.
Another consideration of routing to different terminal types is the
handling of overflow conditions. since different terminal types may
have different page sizes, the overflow condition is apt to occur at
different times in page building. BMS returns control to an overflow
routine in the application program, indicating which terminal type
caused the overflow and how many pages have been created for that
terminal type.
If a message is routed to terminals with alternate screensize
capabilities, the selection of the screensize to be used is taken from
Chapter 4.3.
Basic Mapping Support
239
the SCRNSZE parameter in the PCT for the routing transaction.
(The
SCRNSZE parameter is described in the CICS/VS System Programmer's
Reference Manual.)
The message routing facility of BMS is an ideal tool for developing
message switching and broadcasting applications. CICS/VS provides a
generalized message switching transaction that uses the message routing
facility of BMS. Use of the message switching transaction is described
in the CICSIVS Operator's Guide.
Mapping Concepts and Techniques
Most of the facilities of BMS (text data format is the exception)
require two forms of map to be defined by CICS/VS macro instructions and
assembled offline in advance of running the application program. The
(1) a physical map used by BMS to convert data to or
two forms are:
from the format desired by the application programmer, and (2) a
symbolic description map used by the application programmer to
symbolically refer to the data in the terminal buffer. The physical map
is a table of information about each field, and is stored in the CICS/VS
program library to be loaded by BMS at execution time. The symbolic
description map is a set of source statements that are cataloged into
the appropriate source library (Assembler, COBOL, PL/I, or RPG II) and
copied into the application program when it is assembled or compiled.
The programmer defines and provides names for fields and groups of
fields that may be written to and received from the devices supported by
BMS. The symbolic description map can be copied into each application
program that uses the associated physical map. Data can thus be passed
to and from the application program under the field names in the
symbolic description map. since the application program is written to
manipulate the data under the field names, altering the map format by
adding new fields or rearranging old fields does not necessarily alter
the program logic.
If the map format is altered, it is necessary in most cases to make
the appropriate changes to the macro instructions that describe the map
and then reassemble both the physical map and the symbolic description
map. The new symbolic description map must then be copied into the
application program and the program reassembled. There are certain map
alterations that can be made without necessitating reassembly of the
symbolic description map.
An application program has access to the input and output data fields
using the names supplied to the fields when the maps were generated.
The application logic should be dependent upon the named fields and
their contents but should be independent of the relative positions of
the data fields within the terminal format. If it becomes necessary to
reorganize or add to a map format, the existing application program must
be reassembled to gain access to the new positions of these data fields.
Reprogramming is not necessary to account for new fields or for the
changed terminal format of those fields.
By using BMS to construct and interpret data streams, application
programmers can insulate application programs from the device-dependent
considerations required to handle the data streams. If necessary, the
application program has the facility to temporarily modify the
attributes or the initial data of any named field in an output map. A
collection of named attribute combinations is supplied within BMS so
that the application program remains essentially independent of the data
stream format.
240
CICS/VS APRM
~L)
The ability to progressively add to map definitions without
obsoleting existing application programs permits the design and
implementation of systems in a modular fashion with a progressive
expansion of the screen formats. Design and programming of the first
stages of applications can begin before later stages have been designed.
These early implementations are protected from updates in the terminal
formats.
Note: To use pre-VS application programs requiring the BMS functions,
the application programs must be reassembled. However, physical maps
and symbolic description maps need not be reassembled provided that the
COMPAT=PRE-VS operand is specified in the DFHSG PROGRAa=Bas system
generation macro (descrioed in the CICSIYS System Programmer's Reference
~~!)
.
MAP DEFINITION
All maps must be generated as members of a map set; a single map must be
generated as the only member of such a map set. A map set is a
collection of related maps that are generated and stored together in the
CICS/VS libraries.
Map definition is accomplished through the use of three different
macro instructions: DFHMSD, DFH~DI, and DFHMDF.
The DFHMSD macro instruction
o
defines a map set
•
indicates whether a particular set of macros is for a physical map
or for a symbolic description map
o
specifies whether the map is for input, output, or both
•
can specify the data format:
field or block.
The DFHMDI macro instruction
o
defines a map
•
defines the position of the map on the page, either absolutely or
in relation to other maps
•
specifies the size of the map
•
can specify the data format:
field or block.
The DFHMDF macro instruction
•
defines a field within a map
•
specifies the position of the field
•
specifies the length of the field.
The formats of these macro instructions are given later in this
An example of their use and of the symbolic storage
definitions generated is given in Appendix B.
chapter~
The map definition macro instructions are assembled twice, once to
produce the map used by BMS, and once to produce the symbolic storage
definition (or DSECT) that will be copied into the application program.
Chapter 4.3.
Basic Mapping Support
241
Mote: In pre-VS versions of CICS, BMS provided support for the 3270
Information Display System through OFHMOI and DFHMOF macro instructions
only. For compatibility, OPHMOI and OFHMOP macro instructions written
to use this support will be assembled correctly under CICS/VS BMS;
however, maps requiring functions that were not available in pre-VS
versions of CICS cannot be defined in this way.
INPUT MAPPING
For an input map, the maximum data length and the starting position of
each field must be defined.
The TIOA symbolic storage definition contains an area for the length
of each input data field, followed by a flag byte and an area for the
data itself. Space is reserved for the maximum number of bytes defined
for each field.
The program can access the length, flag, and data areas of any field
by symbolic labels. The length area is a halfword binary field and is
addressed by the name Ifieldname.L" or "groupname.L". The flag is a
one-byte field and is addressed by the name "fieldname.FfI or
"groupname.F". The data portion of each field (or group of fields) is
contiguous with the length and flag areas. A group of fields, or a
single field not within any group of fields, has one data portion
addressed by the name "groupname.IfI or "fieldname.IfI. For fields
contained within a group, there are no intervening length or flag areas
(only "groupname .L" exists) but each field is addressed by a name
flfieldname.I".
In assembler language programs, the first byte of the first
occurrence of a field defined by the OFHMOF operand OCCURS=n (where n is
greater than 1) is named "fieldname 0", and the first byte of the next
occurrence of the field is named "fieldname N". These names refer to
the first oyte of the length area if OATA=FIELO is specified, and to the
first byte of the attribute data if DATA=BLOCK is specified.
In COBOL and PL/I programs, "fieldname Oil is the name of the array of
minor structures containing the length, flag, and data areas of the
field.
(For a description of the effects of the OCCURS operand in RPG
programs, refer to the CICSIYS Application programmer's Reference Manual
for RPGII.)
Note that "." is a concatenation symbol used here
the symbolic names are suffixed; the period is never
Por example, in the case of field name XIZ, the data
XIZI; the data length is referenced as XYZL; and the
as XYZF.
only to show how
actually coded.
is referenced as
flag is referenced
The length specified for a field may differ from the number of
characters that are entered for the field at program execution time. If
more data is keyed than specified in the map, the data is truncated on
the right to the number of characters specified. The length that is
returned to the application program is the truncated length. If less
data is keyed than specified, the remaining character positions are
filled with blanks or zeros and the length of the keyed data is returned
in the length field.
The flag byte is normally set to X'OO'. However, if the field has
been modified but no data has been sent (as, for example, if it has been
modified to all nulls), the flag byte is set to X'SO' and the length
area is set to zeros.
242
CICS/VS APRM(ML)
Any fields that are entered as input but are not defined in the map
are discarded. The length and data areas of any fields defined but not
keyed are set to nulls (X·OO·).
Por a pen-detectable field, although no data is passed, a single data
byte is reserved. This byte contains X'FP' if the field is selected or
X'OO' if the field is not selected. The length area of a pen-detectable
field contains a binary one if selected or a binary zero if not
selected.
OUTPUT MAPPING
Por each output field, the starting location, length, field
characteristics, and default data (if desired) must be defined.
The fields of an output map are assigned names in the DPHMDP macro
instruction. The characteristic or attribute byte is named
"fieldname.A" or "groupname.A". Por a field contained \lithin a group,
the data area is given the name IIfieldname.O Il , but there is no separate
attribute byte for the field.
(Only the group name has the attribute
byte.) Por a group name, or a field not contained within a group, the
data area is given the name "groupname.O" or "fieldname.O."
In assembler language programs, the first byte of the first
occurrence of a field defined by OCCURS=n (where n is greater than 1) is
named IIfieldname D", and the first byte of the next occurrence of the
field is named "fieldname Nil. These names refer to the first byte of
the length area if DATA=FIELD is specified, and to the first byte of the
attribute data if D~TA=BLOCK is sPecified.
In COBOL and PL/I programs, "fieldname D" is the name of the array of
minor structures containing the attribute byte and data area of the
field, together with the unused two-byte length field (described below).
(For a description of the effects of the OCCURS operand in RPG programs,
refer to the CICS/VS Application Programmer's Reference Manual for
~PGII.)
A field not contained within a group is treated as a group
containing one field entry. An unused two-byte length field precedes
each attribute byte and data field to provide a format similar to an
input symbolic storage description TIOA. Application programs written
to use pre-VS data formats are source compatible if all references to
TIOA data are symbolic.
Note that "." is a concatenation symbol used here only to show how
the symbolic names are suffixed; the period is never actually coded.
For example, in the case of field name XYZ, the data is referred to as
XYZO; the attribute byte is referred to as XYZA.
If output maps are to be used by application programs coded at
command level, the TIOAPFX=YES operand must be specified in the DPHMSD
or DFHMDI macros that create the maps. Also, if the symbolic
description maps are referred to by a PL/I program, the STORAGE=AUTO
operand must be specified in the DPHMSD macro.
When defining fields, the user may provide a name for any field that
he wishes to refer to at execution time. Such names are associated with
the fields in the symbolic storage definition of the TIDA to allow
symbolic references to be made to them. The user may specify not only
the characteristics of the field but also the default data to be written
as output for a field when no data is supplied for that field by an
application program. This facility permits the specification of titles,
headers, and so forth, for output maps. The user may temporarily
override the field characteristics, the data, or both field
Chapter 4.3.
Basic Mapping Support
243
characteristics and data of any field for which he has specified a name.
The desired changes are simply inserted into the TIOA under the
specified field name in the symbolic storage definition (symbolic
description map) in the program.
Note: Output field data supplied by the application program must not
begin with a null character (X'OO'), or the entire field will be ignored
by BMS.
A suitable character to use in the first position is blank
(X'40') •
Pen-detectable fields should be "auto skip" to prevent data from
being keyed into them. Because of the nature of pen-detectable fields,
in most instances, they should not be modified.
If the data field is
modified, the application program must ensure that the first character
is a "?II, ">", U&II, or blank character; otherwise, the field is no
longer pen-detactable.
Fields that can be keyed should be delimited by a stopper field to
ensure that all the data keyed and transmitted can be mapped.
INPUT/OUTPUT MAPPING
Input/output (INOUT) maps combining all the functions of input and
output maps can also be created using the DFHMSD, DFHMDI, and DFHMDF
macro instructions.
The number of fields which can be specified for a COBOL or PL/I
input/output map is limited. These limits are stated in the description
of the DFHMDF macro instruction later in this chapter.
MAP RETRIEVAL
Map sets placed in the CICS/VS program library are accessed by BMS
through program control DFHPC TYPE=LOAD macro instructions. Therefore,
each map set name must be entered in the processing program table (PPT)
by the system programmer.
When device-dependent map sets are placed in
the CICS/VS program library, they must be identified by the devicedependent suffixed name, and a corresponding entry of the same name must
appear in the PPT.
(Device-dependent suffixes are described below under
the 'mapset' name of the DFHMSD macro instruction and under the SUFFIX
and TERM operands of that macro.)
To avoid having to load a map set during execution, an assemblerlanguage programmer using the macro level interface may include the map
set in the program, place the address of the map set at TCAMSMSA, and
code MSETADR=YES in the DFHBMS macro. Alternatively, the programmer may
code MSETADR=symbolic-address, where the symbolic address is the label
of the map set. The MAP=map-name specification must also be provided
with the MSETADR parameter to locate a specific map within the map set.
similarly, the MAPADR operand enables an assembler-language programmer
to specify, directly or indirectly, the address of an individual map.
244
CICS/VS APRM(ML)
COPYING SYMBOLIC DESCRIPTION MAPS
The B~S ~y~bclic description maps must be copied into the application
program as shown in the following examples. These examples use the
macro level interface, examples using the command level interface are
given in CICUVS AEElication Prog,~!!t2£.2-!!ef~1:~~ l1a!lllLJCoyand
Level). In the following examples, mapsetname1, mapsetname2, and
mapsetname3 are the names of members that contain the assembly of a BKS
symbolic storage definition.
1.
Assembler-language COPY instructions for each symbolic storage
definition. To ensure that each definition overlays the same area,
the second and subsequent COpy instructions must be preceded by an
ORG instruction to reposition the Assembler to the start of the
TIOA data area.
COpy
COpy
ORG
COpy
ORG
COPY
2.
DFHTIOA
mapsetname1
TIOADBA
mapsetname2
TIOADBA
mapsetname3
COBOL COpy statements for each symbolic storage definition.
Note
that mapname1I, mapname2I, and mapname3I in this example are the
names of the first maps in the map sets.
LINKAGE SECTION.
01 DFHBLLDS COpy DFHBLLDS.
02 TIOABAR PIC S9(8) COMP.
01
01
01
01
01
01
Note:
is:
DFHCSADS COPY DFHCSADS.
DFHTCADS COPY DFHTCADS.
DFHTIOA COpy DFHTIOA.
mapnamelI COPY mapsetnamel.
mapname2I COpy mapsetname2.
mapname31 COpy mapsetname3.
For MODE=IN and MODE=INOUT the format of the COPY statement
01 mapname1I COpy mapsetname1
For 110DE=OUT the format of the COpy statement is:
01 mapnamel0 COPY mapsetnamel
3.
PLII %INCLUDE statements.
%INCLUDE DFHTIOA;
2 DUMMY CHAR (1) ;
%INCLUDE mapsetnamel;
%INCLUDE mapsetname2;
%INCLUDE mapsetname3;
Chapter 4.3.
Basic Mapping Support
245
In addition to providing the BMS symbolic storage definition for the
TIOA, the application programmer must establish addressability for this
storage definition. Depending on the programming language used, this is
accomplished as follows:
1.
Assembler-language L instruction to set up TIOABAR, normally from
TCASCSA. For example:
COpy
COpy
ORG
COpy
ORG
COpy
DFHTIOA
mapsetname1
TIOADBA
mapsetname2
TIOADBA
mapsetname3
DFHSC
*
TYPE=GET~AIN,
NU~BYTE=mapname.E-TIOADBA,
CLASS=TER~INAL,
L
INITIMG=OO
TIOABAR,TCASCSA
*
*
ESTABLISH TIOA ADDRESSABILITY
~:
BMS offline macros generate a label at the end of each map
description and a label at the end of each mapset description;
these labels have the form Imapname.EI and 'mapsetname.T',
respectively, where ' . ' is a concatenation symbol used only for
documentational purposes. The start of each map, or mapset, can be
referred to by the label TIOADBA. Thus an Assembler-language
programmer can specify the amount of storage required in the way
shown in the example above.
2.
COBOL 02 level statements immediately following the COpy statement
for the Linkage section Base Locator (BLL). These 02 statements
must be coded in the same order as the corresponding 01 statements.
For example:
LINKAGE SECTION.
01 DFHBLLDS COPY DFHBLLDS.
02
02
02
02
01
01
01
01
TIOABAR PIC S9(8) COMP.
MAPBASE1 PIC S9(8) COMP.
MAPBASE2 PIC S9 (8) COMP.
MAPBASE3 PIC S9 (8) COMP.
DFHTIOA COPY DFHTIOA.
mapname1 COPY mapsetname1.
mapname2 COPY mapsetname2.
mapname3 COpy mapsetname3.
PROCEDURE DIVISION.
DFBse TYPE=GETMAIN,NUMBYTE=120,CLASS=TERMINAL,INITIMG=OO
~OVE TCASeSA TO TIOABAR.
ADD 12 TIOABAR GIVING MAPBASE1.
MOVE MAPBASE1 TO MAPBASE2 MAPBASE3.
246
CICS/VS APRM(ML)
3.
Set up the PL/I based pointer variable
structures are based. For example:
%lNCLUDE
%INCLUDE
%INCLUDE
%INCLUDE
DFHTIOA;;
mapsetnamel;
mapsetname2;
mapsetname3;
~MSMAPBR)
on which the map
/*EACH OF THESE MAPS IS*/
/*BASED ON THE SAME POINTER*/
/*VARIABLE - BMSMAPBR*/
DFHSC TYPE=GETMAIN,
NUMBYTE=120,
CLASS=TERMINAL,
INITIMG=OO
TIOABAR=TCASCSA;
BHSMAPBR=ADDR(TIOADBA);
*
*
*
Note that this code assumes that the TIOAPFX operand of the DFHMSD
and DFHMDI macro instructions has been omitted or coded as TIOAPFX=NO.
Map Definition Macro Instructions
The syntax and operand descriptions of the three map definition macro
instructions (DFHMSD, DFHMDI, and DFHHDP) are given belove
Chapter 4.3.
Basic Mapping Support
247
DEFINING A MAP SET (DFHMSD MACRO INSTRUCTION)
B!S
the
map
for
the
generates and stores map sets in the CICS/VS program library under
names selected by the application programmers. A reference to one
in the map set causes the entire map set to be loaded into storage
the duration of the task, or until another map set is referred to by
task.
Information pertaining to an entire map set is specified in the
DFHMSD macro instruction, whiCh always appears at the beginning and end
of each map set generation. The one at the beginning indicates whether
physical maps or symbolic description maps are being generated; the one
at the end indicates the end of the map set.
All operands other than the TYPE operand of a DFHMSD macro
instruction are the same for a physical map generation run and for the
corresponding symbolic description map generation run. The application
programmer should specify TYPE=MAP for the former, and TYPE=DSECT for
the latter. Alternatively, physical maps and symbolic description maps
can be assembled in the same job by the use of job control language
options, as described in the CICS/VS-2Y§tem Programmer's Guide.
The format of the
I
I
DFH~SD
I~------'r----------------------------------------------------------'
1
mapsetlDFHMSD
1
1
1
I
I
1
,
TYPE={DSECTIMAPIFINAL}
[ ,BASE=name ]
[ ,COLOR={DEFAULTIBLUEIREDIPINKIGREENITURQUOISEI
YELLOW 1NEUTRAL} ]
[ ,CTRL= ([ PRINT][ , {L40 IL641 L80 1HONEOM} ]
[ ,FREEKB][ , ALARM ][ , FR SET ]) ]
[,DATA={FIELDIBLOCK}]
[ , EXTATT= {NO 1YES 1MAPONLY} ]
[,HILIGHT={~IBLINKIREVERSEIUNDERLINE} ]
[ ,HTAB=tab[,tab] ••• ]
[ ,LANG= {ASM 1COBOL I PLI 1RPG} ]
RPG: DOS only
[ , LDC=m nemonic ]
[ , HODE= {IN 1OUT 1INOUT} ]
[ ,OBFMT= {YES I NO} ]
[ , PS= {BASE 1psid} ]
[ , STORAGE=AUTO ]
[ , SUFFIX=n ]
[,TERM=terminal-type]
[ ,TIOAPFX={YESI!!Q} ]
[ , VALIDN= ([ MUSTFILL][ ,~USTENTER]) ]
[,VTAB=tab[,tab] ••• ]
where:
248
macro instruction is as follows:
CICS/VS APRM(ML)
is the one- to seven-character name of the map set, to be
specified in the MAP SET operand of any DFHBMS macro instruction
that refers to the map set. The name must begin with an
alphabetic character and, if the map is to reside in the
CICSjVS program library, must differ from other map names or
program names.
A suffix specified by the SUFFIX operand, or based on the
terminal type specified in the TERM operand of the DFHMSD macro
instruction is appended to the map set name during assembly.
This suffixed name is the name that should be used in the NAME
card (OS) or the PHASE card (DOS) in cataloging the mapset (see
the appropriate CIC~L!~_liYstem Programmer's Guide for further
details) , and the name that should be specified by the system
programmer in the PPT entry (see the CICS/VS System
Programmer's Reference Manual). The suffixes are tabulated in
the description of the TERM operand, below.
When a mapping operation is r~guested by means of a DFHBMS
macro instruction in an application program, CICSjVS
automatically appends a similar suffix to the map set name
specified in that instruction, and attempts to load a map set
with the suffixed name. If the load is unsuccessful, that is,
the suffixed map set name cannot be found in the library,
CICS/VS will load a map set with an unsuffixed name (equivalent
to being suffixed with a blank). CICSjVS obtains the suffix
from the TCT terminal entry for the appropriate terminal
(either the terminal associated with the transaction or, for
routing, the destination terminal), and this suffix depends on
the terminal type specified in the TRMTYPE operand (together
with the SESTYPE operand for VTAM terminals) of the DFHTCT
TYPE=TERMINAL (or TYPE=LINE) macro.
If the alternate page size is being used, as specified by the
ALTPGE operand of the DFHTCT TYPE=TERMINAL system macro, and
the ALTSFX operand of that same system macro has also been
specified, an attempt will be made to load the map set that has
the alternate suffix specified in the SUFFIX operand of the
DFHMSD macro. If this load is unsuccessful, normal map set
selection will occur.
For example, if two maps are assembled, one with TERM=CRLP and
the other with TERM=ALL, the first will be suffixed with A and
the second with blank (that is, unsuffixed). The system
programmer should use these suffixed names in the PHASE/NAME
cards and in the PPT entry. If a CICS/VS transaction now
routes a message to two terminals, one of which has
TRMTYPE=CRLP and the other TRMTYPE=L3277, TRMMODL=2, BMS will
attempt to load mapset.A and mapset.M to do the mapping in the
two cases. The second of these will be unsuccessful, so Bas
will then look for the unsuffixed map set name for routing to
the 3277.
TYPE=
indicates the generation function of the macro instruction.
Chapter 4.3.
Basic Mapping Support
249
DSECT
-----indicates that this is a symbolic description map
generation run to create the list of field names to be
copied into an application program. If a single map set is
to be used by application programs written in different
languages, a separate DFHMSD TYPE=DSECT macro instruction
must be written for each language to put the table of field
names into the copy library of the language.
MAP
indicates that this is a physical map generation run to
create the control information block used by BMS to perform
mapping. This physical map is stored in the CICS/VS
program library and loaded as required by BMS. The
assembler-language application programmer can,
alternatively, generate the map in his program and pass the
address of the map to BMS instead of using this facility to
generate and store the map beforehand in the CICS/VS
program library.
FINAL
must be coded in the DFHMSD macro instruction that marks
the end of the map set. If other parameters are coded in
the DFHMSD TYPE=FINAL macro instruction, they will be
ignored.
BASE=name
is used to indicate that the same storage base will be used for
the symbolic description maps from more than one map set. The
same name is coded in the BASE operand for each map set that is
to share the same storage base. Since all map sets with the
same base describe the same storage, data related to a
previously-used map set may be overwritten when a new map set
is used. Furthermore, different maps within the same map set
will also overlay one another.
This operand is not valid for assembler-language or RPG II
programs.
As an example, assume that the following DFHMSD macro
instructions are used to generate symbolic description maps
(symbolic storage definitions) for two map sets.
MAP1
DPHMSD TYPE=DSECT,
TERM=2780,
LANG=COBOL,
BASE=DATAREA1,
MODE=IN
*
*
*
*
MAP2
DPHMSD TYPE=DSECT,
TERM=3270,
LANG=COBOL,
BASE=DATAREA1,
MODE=OUT
*
*
*
*
The symbolic storage definitions of this example might be
referred to in a COBOL application program as follows:
250
CICS/VS APRM (ML)
LINKAGE SECTION.
01 DFHBLLDS COpy DFHBLLDS.
02 TIOABAR PIC S9(8) CaMP.
02 MAPBASE1 PIC S9(8) CaMP.
01
01
01
01
DFHTIOA COpy DFHTIOA.
DATAREA1 PIC 1(1920).
name COPY MAP1.
name COPY MAP2.
MAP1 and HAP2 multiply redefine DATAREA1; only one 02 statement
is needed to establish addressability.
However, the program
can only use the fields in one of the symbolic map areas at a
time.
If BASE=DATAREA1 is deleted from this example, an additional 02
statement is needed to establish addressability for MAP2; the
01 DATAREAl statement is not needed. The program could then
refer to fields concurrently in both symbolic map areas.
In PLjI application programs, the name specified in the BASE
operand is used as the name of the pointer variable on which
the symbolic storage definition is based.
If this operand is
omitted, the default name (BMSMAPBR) is used for the pointer
variable. The PL/I programmer is responsible for establishing
addressability for the based structures.
COLOR=
specifies the default color for all fields in all maps in a map
set unless overridden explicitly by the COLOR option of a
DFHMDI or DFHMDF macro. If this option is specified when
EXTATT=NO, a warning will be issued and the option ignored. If
this option is specified, but EXTATT is not, EXTATT=MAPONLY
will be assumed.
CTRL=
is used to specify device characteristics related to terminals
of the 3270 Information Display System. CTRL=ALARM is valid
for TCAM 3270 SDLC and VTAM-supported terminals (except
interactive and batch logical units): all other parameters for
CTRL are ignored. To be effective, this operand must be
specified on the last (or only) map of a page unless the CTRL
operand of the DFHBMS macro is being used to override the
corresponding operand in the DFHMSD macro. If the CTRL operand
is specified in the DFHMDI macro, it cannot be specified in the
DFHMSD macro.
PRINT
must be specified if the printer is to be started; if
omitted, the data is sent to the printer buffer but is not
printed. This operand is ignored if the map set is used
with 3270 displays without the Printer Adapter feature.
Chapter 4.3.
Basic Mapping Support
251
L40, L64, LBO, HONEOM
are mutually exclusive options that control the line length
on the printer. L40, L64, and LBO force a carrier
return/line feed after 40, 64, or BO characters,
respectively. HONEOM causes the printer to honor all newline (NL) characters and the first end-of-message (EM)
character that appear in displayable fields of the data
stream. If the latter option is specified, the application
program must insert the NL and EM characters into the data
stream. If the NL character is omitted, a carrier
return/line feed occurs at the physical end of the
carriage. If the EM character is omitted, printing stops
at the end of the 3270 buffer.
FREEKS
specifies that the keyboard should be unlocked after this
map is written out. If omitted, the keyboard remains
locked; further data entry from the keyboard is inhibited
until this status is changed.
ALARM
activates the 3270 audible alarm feature. For a VTAM
terminal ALARM signals SMS to set the alarm flag in the
function management header; this feature is not supported
by interactive and batch logical units.
FRSET
indicates that the modified data tags (MDTs) of all fields
currently in the 3270 buffer are to be reset to a notmodified condition (that is, field reset) before any map
data is written to the buffer. This allows the DFHMDF
ATTRB specification for the requested map to control the
final status of any fields written or rewritten in response
to a DFHBMS macro instruction.
DATA=
specifies the format of the data as seen by the application
program.
FIELD
----Indicates that the data is passed as contiguous fields in
the following format:
ILLIAldata fieldlLLIAldata field
ILLIAletc.
I
LL is two bytes specifying the length of the data as input
from the terminal (this field is ignored in output
processing). A is a byte into which the programmer may
place an attribute to override that specified in the map
used to process this data (see "Standard Attribute List and
Printer control Characters (DFHBMSCA)," later in this
chapter).
252
CICS/VS APRM(ML)
BLOCK
indicates that the data is passed as a continuous stream
which is processed as line segments of the length specified
in the map used to process this data set. The data is in
the form that it appears on the terminal; that is, it
contains data fields and interspersed blanks corresponding
to any spaces that are to appear between the fields on
output. The first byte of each line is the attribute byte;
it is not available for data. EXTATT=YES cannot be used if
DATA=BLOCK is specified.
A Idata fieldlspacel A Idata fieldlspacel A Idata fieldletc.
The data type associated with any map depends on the DATA
specifications, or lack thereof, in both the DFHMSD and DFHMDI
macro",...i,.nstructions:
1. A DATA operand in a DFHMDI macro will always override that
in a DFHMSD macro.
2. If no DATA operand is coded in the DFHMDI macro, the DATA
operand in the DFHMSD macro will apply.
3. If no DATA operand is coded in either macro, DATA=FIELD is
the default.
EXTATT=
specifies whether the extended attributes
and VALIDN) are supported.
(COLOR, HILIGHT, PS,
NO
specifies that the extended attributes are not supported;
the physical and symbolic description maps will be the same
as those generated under Version 1 Release 4. "NO" is the
default unless COLOR, HILIGHT, PS, or VALIDN is specified
in the DFHMSD macro, in which case EXTATT=MAPONLY will be
assumed. If the TERM operand is specified and is other
than 3270, 3270-1, 3270-2, or ALL, EXTATT=MAPONLY or
EXTATT=YES will be invalid, and the COLOR, HILIGHT, PS, and
VALIDN operands on the DFHMSD, DFHMDI, and DFHMDF macros
will be invalid.
YES
specifies that the extended attributes can be specified in
a map, and that they can be modified dynamically. The
symbolic description map (DSECT) will contain subfields for
the attributes, identified by suffixes C (for COLOR), H
(for HILIGHT), P (for PS) , and V (for validation) •
MAPONLY
specifies that the extended attributes can be specified in
a map, but that the resulting symbolic description map will
contain no fields for them, and that it will be the same as
one generated under Version 1, Release 4. This operand can
be used to add the extended attributes to an existing map
without recompiling the application program.
HILIGHT=
specifies the default highlighting attribute for all fields in
all maps in a map set.
Chapter 4.3.
Basic Mapping Support
253
is the default and means that no hiqhlighting is used.
BLINK
specifies that the field is to "blink" at a set frequency.
REVERSE
specifies that the field is displayed in "reverse video",
for example, on a 3218, black characters on a green
background.
UNDERLINE
specifies that a field is underlined.
If this option is specified when EXTATT=NO, a warning will be
issued and the option ignored. If this option is specified,
but EXTATT is not, EXTATT=MAPONLY will be assumed.
HTAB=tab[ ,tab] •••
specifies one or more tab positions for use with interactive
and batch logical units having horizontal forms control.
LANG=
specifies the language in which the application program
referring to a symbolic description map is written and, hence,
is applicable for only a DFHMSD TYPE=DSECT macro instruction.
indicates that the symbolic description map is to be
referred to by an assembler-language program.
COBOL
indicates that the symbolic description map is to be
referred to by a COBOL program.
PLI
indicates that the symbolic description map is to be
referred to by a PL/I program.
RPG
indicates that the symbolic description map is to be
referred to by an RPG II program. This parameter is valid
for CICS/DOS/VS only.
LDC=mnemonic
specifies the mnemonic to be used by CICS/VS to determine the
logical device code that is to be used for a BMS output
operation and transmitted in the function management header to
the logical unit if no LDC operand has been specified on any
previous BMS output in the logical message. This operand is
used only for TCAM and VTAM-supported 3600 terminals, and batch
logical units.
MODE=
IN
indicates an input map generation.
indicates an output map generation.
254
CICS/VS APRM(!L)
INOUT
indicates that the map definition is to be used for both
input and output mapping operations.
Not~:
Input mapping is not available for VTAM-supported 3600
terminals. However, INOUT may be specified for map generation.
The map can then be used as a dummy input map for input
operations using the DFHBMS TYPE=IN macro instruction.
OBFMT=
specifies whether outboard formatting is to be used. This
operand is available only for 3650 logical units. Refer to the
CICSt'S 3650 Guide for details of 3650 logical units and of
outboard formatting.
YES
indicates that all maps within this mapset are eligible for
use in outboard formatting, except those for which OBFMT=NO
is specified in the DFHMDI macro instruction.
indicates that no maps within this mapset are eligible for
use in outboard formatting, except those for which
OBFMT=YES is specified in the DFHMDI macro instruction.
PS=
specifies that programmed symbols are to be used.
BASE
specifies that only the basic symbols are used.
psid
specifies a single EBCDIC character or a hexadecimal code
on the form X'nnl, that identifies the set of programmed
symbols.
If this option is specified when EXTATT=NO, a warning will be
issued and the option ignored. If this option is specified,
but EXTATT is not, EXTATT=MAPONLY will be assumed.
STO RA GE =A UTO
o
This operand is not valid for RPG programs.
specifies, for COBOL programs, that the symbolic storage
definitions of the maps in the map set are to be separate (that
is, not redefined) areas. This operand is used when the
symbolic storage definitions are copied into the WORKINGSTORAGE section of a program using the command-level ,interface
and the storage for the separate maps in the map set is to be
used concurrently. (For information about the command-level
interface, see the £ICSL!L!£El.icatiQ.!!LPr~~ruru!ler·§_RefergnQg
Manual (Command Level).)
specifies, for PL/I programs, that the symbolic storage
definitions are to be declared as having the AUTOMATIC storage
class. If not specified, the symbolic storage definitions are
declared as having the BASED storage class.
specifies, for assemoler language programs, that separate maps
within a map set are to occupy separate storage,. not to overlay
one another.
Chapter 4.3.
Basic Mapping Support
255
If STORAGE=AUTO is specified, BASE=name cannot be used.
STORAGE=AUTO is specified and TIOAPFX is not specified,
TIOAPFX=YES is assumed.
If
SUFFIX=n
specifies a one-character map set suffix that overrides any
suffix implied by the TERM operand. A message will indicate
that the TERM operand has been ignored. The user should
catalog the map set, with this suffixed name, in the program
library, and ensure also that there is no conflict with a
generated name of another version of the map. The use of
numeric suffixes would help prevent conflict.
TERM=terminal type
indicates the type of output device or logical unit associated
with the map set. The parameters that may be coded after TER8=
are given in the left-hand column of the table below.
TERM=
Remarks
CRLP
TAPE
DISK
TWX
1050
2740
2141
2710
2180
3180
3210-1
3210-2
INTLUI316713170IISCS
Card-Reader-In/Line-Printer-Out
2980
2980-4
3210
3601
3653
3650UP
3650/3210
BCHLU 13170B
ALL
256
CICS/VS APRM(ML)
Map Set
Suffix
A
B
C
D
E
F
G
I
J
K
Use for 40-column displays
L
Use for 80-column displays
M
These four parameters are
synonymous. They cover all
interactive logical units,
including the 3790 fullfunction LU and the
SCS-printer LUs (3270 and 3790) • P
Excluding the 2980 Model 4
Q
R
For use when it is not
important to distinguish
between different models.
This parameter is synonymous
with ALL, and is the default
applied if the operand is not
coded.
blank
U
Use for the host-conversational
(3653) LU
Use for the interpreter LU
Use for the host-conversational
(3270) LU
These two parameters are
synonymous. They cover all
batch and batch data interchange logical units.
Covers all the above
V
W
X
Y
blank
For TCAM-connected terminals pther than 3270 or SNA devices),
use either CRLP or ALL; for TCAM-connected 3270s or SNA
devices, select the appropriate parameter in the normal way.
The application programmer who specifies ALL in the TERM
operand must be certain that device-dependent characters are
not included in the map set and must ensure that format
characteristics such as page size are suitable for all
input/output operations (and all terminals) in which the map
set will be applied. For example, some terminals are limited
to 480 bytes, others to 1920 bytes; the 3604 is limited to six
lines of 40 characters each. within these guidelines, use of
ALL can offer important advantages. Since an assembly run is
required for each map generation, a specification of ALL,
indicating that one map is to be used for multiple terminals,
can result in significant time and storage savings.
However, better run-time performan~e for maps used by single
terminal types will be achieved if the terminal type (rather
than ALL) is specified in the TERM operand. Alternatively, the
BMS support for device-dependent map sets can be left
ungenerated by specifying BMSDDS=NO in the DFHSG PROGRAM=BMS
system generation macro instruction.
(See the CICS/VS System
Programmer's Reference Manual for further details.)
TIOAPFX=
specifies whether BMS should include a filler in the symbolic
TIOA description(s) to allow for the unused TIOA prefix. If
this operand is coded, the same storage address may be used for
TIOABAR and the map base.
YES
indicates that the filler should be included in the
symbolic TIOA description~). This operand is ignored
unless TYPE=DSECT is coded. If TIOAPFX=YES is coded, all
maps within the map set have the filler, except when'
TIOAPFX=NO is coded on the DFHHDI macro instruction.
TIOAPFX=YES is the default where LANG=RPG.
is the default (except for RPG) and indicates that the
filler is not to be included. The filler may still be
included for a specific map if TIOAPFX=YES is coded on the
DFHMDI macro instruction.
Note: In previous versions of CICS/VS, it has not been valid
to code TIOAPFX=YES for an assembler language application
program. If this operand was coded in this way, CICS/VS
disregarded it and applied the default specification
(TIOAPFX=NO). In CICS/VS Version 1.4, it is valid to code
TIOAPFX=YES for an assembler program: doing so will thus
produce a different object program under CICS/VS 1.4 from that
which would be produced under earlier versions.
VALIDN=
MUSTFILL
specifies that the field must be filled completely with
data. An attempt to move the cursor from the field before
it has been filled, or to transmit data from an incomplete
field, will raise the inhibit input condition.
Chapter 4.3.
Basic Happing Support
257
MUSTE8TER
specifies that data must be entered into the field. An
attempt to move the cursor from an empty field will raise
the ~nhibit input condition.
VTAB=tab[ ,tab] •••
specifies one or more tab positions for use with interactive
and batch logical units having vertical forms control.
258
CICS/VS APRM
~L)
DEFINING A MAP (DFHMDI MACRO INSTRUCTION)
The DFHMDI macro instruction is used to define a single map. It defines
the size of the data to be mapped and its position within the input or
output. When defining more than one map within a map set, the
corresponding number of DFHMDI macro instructions must be used. If the
maps are for use in a COBOL program, and STORAGE=AOTO has been specified
in the DFHMSD macro, they must be specified in descending size sequence
(size refers to the generated 01 level COBOL data areas and not to the
size of the map on the screen). The format of tha DFHMDI macro
instruction is as follows:
I
map
I
DFHMDI
[,COLOR={DEFAULTIBLUEIREDIPINKIGREENITURQUOISEI
YELLOW I NEUTRAL} ]
[,COLUMN={numberINEXTI~} ]
[ ,CTRL= ([ PRINT][ , {L40 I L64 I L80 I HONE OM} ]
[ ,FREEKB][ ,ALARK][ ,FRSET]) ]
[ ,DATA= {FIELD IBLOCK} ]
[,HEADER=YES]
[,HILIGHT={OFFIBLINKIREVERSEIUNDERLINE} ]
[, JUSTIFY= ([ {LEFTI RIGHT} ][, {FIRST I LAST} ]) ]
[,LINE={numberINEXTISAME} ]
[,OBFMT={YESINO} ]
[ ,PS={BASEIPsid}]
[ ,SIZE= (line,column) ]
[ ,TIOAPFX= {YES I NO} ]
[ , TRAILER=YES]
[ , VALIDN= ([ MUSTFILL ][ ,MUST ENTER]) ]
where:
map
is the one- to seven-character name of the map, to be specified
in the MAP operand of any DFHBMS macro instruction that refers
to the map. Note, however, that for RPG programs the map name
must not exceed 5 characters.
COLOR=
specifies the default color for all fields in a map unless
overridden explicitly by the COLOR operand of a DFHMDF macro.
If this option is specified when EXTATT=NO, a warning will be
issued and the option ignored. If this option is specified,
but EXTATT is not, EXTATT=MAPONLY will be assumed.
COLUMN=
specifies the column in a line at which the map is to be
placed, that is, it establishes the left or right map margin.
The JUSTIFY specification controls whether map and page margin
selection and column counting are to be done with reference to
the left or right side of the page. The columns between the
specified map margin and the page margin are not available for
subsequent use on the page for any lines included in the map.
number
is the column from the left or right page margin where the
left or right map margin is to be established.
Chapter 4.3.
Basic Mapping Support
259
NEXT
indicates that the left or right map margin is to be placed
in the next available column from the left or right on the
current line.
SAME
----indicates that the left or right map margin is to be
established in the same column as the last map used that
specified COLUMN=number and the same JUSTIFY parameters as
this macro instruction.
Refer to the section "Map Positioning," later in this chapter,
for a more detailed discussion.
CTRL=
is used to specify device characteristics related to terminals
of the 3270 Information Display System. CTRL=ALARM is valid
for TCAM SNA 3270 SDLC and VTAM-supported terminals (except
interactive and batch logical units); all other parameters for
CTRL are ignored. To be effective, this operand must be
specified on the last (or only) map of a page unless the CTRL
operand of the DFHBMS macro is being used to override the
corresponding operand in the DFHMSD macro. If the CTRL operand
is specified in the DFHMDI macro, it cannot be specified in the
DFHMSD macro.
PRINT
must be specified if the printer is to be started; if
omitted, the data is sent to the printer buffer but is not
printed. This operand is ignored if the BMS output request
is directed to a 3270 display without the Printer Adapter
feature.
L40, L64, LBO, HONEOM
are mutually exclusive options that control the line length
on the printer. L40, L64, and LBO force a carrier
return/line feed after 40, 64, or BO characters,
respectively. HONEOM causes the default line printer
length to be used.
PREEKB
specifies that the keyboard should be unlocked after this
map is written out. If omitted, the keyboard remains
locked; further data entry from the keyboard is inhibited
until this status is changed.
ALARM
activates the 3270 audible alarm feature. For a VTAM
terminal, ALARM signals BMS to set the alarm flag in the
function management header; this feature is not applicable
to interactive and batch logical units.
FRSET
indicates that the modified data tags (MDTs) of all fields
currently in the 3270 buffer are to be reset to a notmodified condition (that is, field reset) before any map
data is written to the buffer. This allows the DFHMDP
ATTRB specification for the requested map to control the
final status of any fields written or rewritten in response
to a DPHBMS macro instruction.
260
CICS/VS APRM(ML)
DATA=
specifies the format of the data as seen by the application
program.
FIELD
----indicates that the data is passed as contiguous fields in
the following format:
ILLIAldata fieldlLLIAldata field
ILLIAletc.
LL is two bytes specifying the length of the data as input
from the terminal (this field is ignored in output
processing). A is a byte into which the programmer may
place an attribute to override that specified in the map
used to process this data.
(See "Standard Attribute List
and Printer Control Characters (DFHBMSCA), II later in this
chapter. )
BLOCK
indicates that the data is passed as a continuous stream
which is processed as line segments of the length specified
in the map used to process this data set. The data is in
the form that it appears on the terminal; that is, it
contains data fields and interspersed blanks corresponding
to any spaces that are to appear between the fields on
output. The first byte of each line is the attribute byte;
it is not available for data.
A I data field I space I A I data field
space I A I data field I etc.
A DATA specification in a DFHMDI macro instruction overrides a
DATA specification in a DFHMSD macro instruction.
HEADER=YES
allows this map to be used during PAGEBLD overflow without
terminating the overflow condition (see "PAGEBLD Overflow
Processing," later in this chapter). This operand may be
specified for more than one map in a map set.
HILIGHT=
specifies the default highlighting attribute for all fields in
a map.
is the default and means that no highlighting is used.
BLINK
specifies that the field is to "blink" at a set frequency.
REVERSE
specifies that the field is displayed in "reverse video",
for example, on a 3278, black characters on a green
background.
Chapter 4.3.
Basic Mapping Support
261
UNDERLINE
specifies that a field is underlined.
If this option is specified when EXTATT=NO, a warning will be
issued and the option ignored. If this option is specified,
but EXTATT is not, EXTATT=MAPONLY will be assumed.
JUSTIFY=
describes the margins on a page in which a map is to be
formatted.
LEFT
----indicates that the map is to be positioned starting at the
specified column from the left margin on the specified
line.
RIGHT
indicates that the map is to be positioned starting at the
specified column from the right margin on the specified
line.
FIRST
indicates that the map is to be positioned as the first map
on a new page. Any partially formatted page from preceding
DFHBMS requests is considered to be complete. This operand
can be specified for only one map per page.
LAST
indicates that the map is to be positioned at the bottom of
the current page. This operand can be specified for
multiple maps to be placed on one page. However, maps
other than the first map for which it is specified must be
able to be positioned horizontally without requiring that
more lines be used.
LEFT and RIGHT are mutually exclusive, as are FIRST and LAST.
If neither LEFT nor RIGHT is specified, LEFT is assumed. If
neither FIRST nor LAST is specified, the data is mapped at the
next available position as determined by other parameters of
the map definition and the current mapping operation. FIRST
and LAST are ignored unless PAGEBLD is specified, since
otherwise only one map is placed on each page.
Refer to the section "Map Positioning," later in this chapter,
for a more detailed discussion.
LINE=
specifies the starting line on a page in which data for a map
is to be formatted.
number
is a value from 1 to 240, indicating a starting line
number. A request to map data on a line and column that
has been formatted in response to a preceding request
causes the current page to be treated as though complete.
The new data is formatted at the requested line and column
on a new page.
NEXT
----indicates that formatting of data is to begin on the next
available completely empty line. If LINE=NEXT is specified
in the DFHMDI macro, it is ignored for input operations and
LINE=1 is assumed.
262
CICS/VS APRM(ML)
SAME
indicates that formatting of data is to begin on the same
line as that used for a preceding DPHBMS request. If the
data does not fit on the same line, it is placed on the
next available completely-empty line.
Refer to the section "Map Positioning," later in this chapter,
for a more detailed discussion.
OBPMT=
specifies whether outboard formatting is to be used. This
operand is available only for 3650 logical units. Refer to the
CICS/VS 3650 Guide for details of 3650 logical units and of
outboard formatting.
If OBFMT is not coded in the DPHMDI macro instruction, the
OBPMT specification in the DPHMSD macro instruction is used.
YES
indicates that this map is to be used with outboard
forma tting.
NO
indicates that this map is not to be used with outboard
formatting.
PS=
specifies that programmed symbols are to be used.
BASE
specifies that only the basic symbols are used.
psid
specifies a single EBCDIC character or a hexadecimal code
on the form X'nn', that identifies the set of programmed
symbols.
If this option is specified when EXTATT=NO, a warning will be
issued and the option ignored. If this option is specified,
but EXTATT is not, EXTATT=MAPONLY will be assumed.
SIZE=
gives the dimensions of a map in terms of length and width.
line
is a value from 1 to 240, indicating the length of a map as
a number of lines.
column
is a value from 1 to 240, indicating the width of a map as
a number of characters per line. Space for the attribute
byte should be included in the column specification.
The SIZE operand is required in the following cases:
•
A POS=(line,column) specification is given in a DPHMDP
macro instruction defining a specific field within this
map.
•
This map is to be referred to in a DPHBMS TYPE=PAGEBLD
macro instruction.
Chapter 4.3.
Basic Mapping Support
263
•
This map is to be used when referring to input data from
other than a 3270 terminal in a DFHBKS TYPE=IN or DFHBKS
TYPE=KAP macro instruction.
TIOAPFX=
specifies whether or not BKS should include a filler in the
symbolic TIOA description to allow for the unused TIOA prefix.
If this operand is coded, the same storage address may be used
for TIOABAR and the map base. If this operand is not coded,
the TIOAPFX specification derived from the DFHKSD macro is
used.
YES
indicates that the filler should be included in the
symbolic TIOA description for this map. This operand is
ignored unless TYPE=DSECT is coded on the DFHMSD macro
instruction.
NO
indicates the filler is not to be included for this map.
In previous versions of CICS/VS, it has not been valid
to code TIOAPFX=YES for an assembler language application
program. If this operand was coded in this way, CICS/VS
disregarded it and applied the default specification
(TIOAPFX=NO). In CICS/VS Version 1.4, it is valid to code
TIOAPFX=YBS for an assembler program: doing so will thus
produce a different object program under CICS/VS 1.4 from that
which would be produced under earlier versions.
~:
TRAILER=YES
allows this map to be used during PAGEBLD overflow without
terminating the overflow condition (see "PAGEBLD Overflow
Processing," later in this chapter). This operand may be
specified for more than one map in a map set. If a trailer map
is used other than in the overflow environment, the space
normally reserved for overflow trailer maps is not reserved
while mapping the trailer map.
VALIDN=
KUSTFILL
specifies that the field must be filled completely with
data. An attempt to move the cursor from the field before
it has been filled, or to transmit data from an incomplete
field, will raise the inhibit input condition.
KUSTENTER
specifies that data must be entered into the field. An
attempt to move the cursor from an empty field will raise
the inhibit input condition.
264
CICS/VS APRK(KL)
DEFINING A FIELD (DFHMDF MACRO INSTRUCTION)
The DFHMDF macro instruction is used to define one field in a map. One
DFHMDF macro instruction is required for each field, giving information
such as symbolic field name, field position, field length, attribute
byte (for 3270 terminals), initial constant data, justification of
input, and COBOL or PL/I data picture.
The maximum number of named fields that can be defined for a COBOL or
PL/I input/output map is 1023:
The format of the macro instruction is as follows:
i
[fld]
I
DFHMD.F
[ , POS= {number, (line,column)} ]
[ , ATTRB= ([ {ASKIP IPROT IUNPROT[ , NUM]} ][ , {BRT I NORM I DRK} ]
[,DET][ ,IC][ ,FSET]) ]
[,COLOR={DEFAULTIBLUEIREDIPINKIGREENITURQUOISEI
YELLOWINEUTRAL} ]
[ ,GRPNAME=group-name]
[,HILIGHT={OFFIBLINKIREVERSEIUNDERLINE} ]
[,INITIAL='character data"XINIT=hexadecimal data]
[ ,JUSTIFY= ([ {LEFT IRIGHT} ][ , {BLANKI ZERO} ]) ]
[ , LENGTH=number ]
[ ,OCCURS=number]
[,PICIN='value']
[,PICOUT=lvalue l ]
[ , PS= {BASE I psid} ]
[,VALIDN=([MUSTFILL][,MUSTENTBR]) ]
where:
fld
is the one- to seven-character name of the field, used as a
symbolic reference to the field by the application program.
Note, however, that for RPG programs, the field name must never
exceed 5 characters, and if OCCURS= is specified, the field
name must not exceed 3 characters.
Although specification of a field name is not required for
every field within a map, a field name must be specified for at
least one field of any map to be compiled under COBOL or PL/I.
All fields within a group must have names.
If no name is specified for a field, an application program
cannot access the field map to change its attributes or alter
its contents. For an output map, omitting the field name may
be appropriate when the INITIAL operand is used to specify
field contents. If a field name is specified and the map that
includes the field is used in a mapping operation, any data
supplied by the user overlays data supplied by initialization
~nless DATA=NO is specified or assumed by default).
Chapter 4.3.
Basic Mapping Support
265
POS=
is used to specify the individually addressable character
location in a map at which the attribute byte that precedes
this field is positioned. Specification of the DFHMDF macro
instruction must be sequenced by the POS operand except for
output mapping operations using DATA=FIELD.
The POS operand defines the location of fields in a map. The
location of data on the output medium is dependent on DFH~DI
macro parameters as well.
For each field definition (DFHMDF macro instruction), the first
position is reserved for an attribute byte. When supplying
data for input mapping from non-3270 devices, the actual input
data must allow space for this attribute byte. Input data must
not start in column 1 but may start in column 2.
The POS operand always contains the location of the first
position in a field, which is normally the attribute byte when
communicating with the 3270. For the second and subsequent
fields of a group, the POS operand points to an assumed
attribute-byte position, ahead of the start of the data, aven
though no actual attribute byte is necessary. If the fields
follow on immediately from one another, the POS operand should
point to the last character position in the previous field in
the group.
When a position number is coded which represents the last
character position in the 3270, then two special rules apply:
•
The IC attribute should not be coded on that DFHMDF macro.
The cursor may be set to location zero by using the cursor
operand of the DFHBMS macro.
•
If the field is to be used in an output mapping operation
with the DATA=ONLY specification, an attribute byte for
that field must be supplied in the TIOA by the application
program.
number
is an absolute displacement (relative to zero) from the
beginning of the map being defined.
Uine,column)
are line and column specifications (relative to one)
the map being defined.
266
CICS/VS APRM(ML)
~ithin
ATTRB=
is applicable only to fields to be displayed on a 3270 and
specifies device-dependent characteristics and attributes, such
as the capability of a field to receive data or the intensity
to be used when the field is output. If the ATTRB operand is
specified within a group of fields, it must be specified in the
first field entry. A group of fields appears as one field to
the 3270. Therefore, the ATTRB specification refers to all of
the fields in a group as one field rather than as individual
fields.
(Refer to the IBM 3270 Information Display System
Component Description for a full explanation of the effects of
the attribute byte settings.)
This operand applies only to 3270 data stream devices; it will
be ignored for other devices, including the SCS Printer Logical
Unit. It will also be ignored if PROPT=NLEOM is specified on
the DFHBMS TYPE=PAGEBLD macro for transmission to a 3270
printer. In particular, ATTRB=DRK should not be used as a
method of protecting secure data on output. It could, however,
be used for making an input field non-display for secure entry
of a password from a screen.
For input map fields, DET and NUM are the only valid options;
all others are ignored.
ASKIP
indicates that data cannot be keyed into the field and
causes the cursor (current location pointer) to
automatically skip over the field.
PROT
indicates that data cannot be keyed into the field.
If data is to be copied from one device to another attached
to the same 3270 control unit, the first position (address
0) in the buffer of the device to be copied from must not
contain an attribute byte for a protected field. When
preparing maps for 3270s, ensure that the first map of any
page does not contain a protected field starting at
position o. Refer to the publication IBM 3270 Information
Dispi~_System Component Description for further
information.
UNPROT
indicates that data can be keyed into the field.
NUM
ensures that the data entry keyboard is set to numeric
shift for this field unless the operator presses the alpha
shift key, and prevents entry of nonnumeric data if the
Keyboard Numeric Lock feature is installed.
BRT
specifies that a high-intensity display of the field is
required. By virtue of the 3270 attribute character bit
assignments, a field specified as BRT is also potentially
detectable. However, for the field to be recognized as
detectable by BMS, DET must also be specified.
NORM
specifies that the field intensity is to be normal.
DRK
specifies that the field is nonprint/nondisplay.
cannot be specified if DET is specified.
Chapter 4.3.
DRK
Basic Mapping Support
267
DET
specifies that the field is potentially detectable.
The first character of a 3210 detectable field must be a
"1", ">", "S", or blank. If the first character is liS" or
blank, the field is an attention field; if the first
character is "?" or ">", the field is a selection field.
(See the publication IBM 3210 Information Display System
ComEQagnt D~scriptiQ~ for further details of detectable
fields. )
A field for which BRT is specified is potentially
detectable to the 3210, by virtue of the 3210 attribute
character bit assignments, but is not recognized as such by
BMS unless DET is also specified.
DET and DRK are mutually exclusive options.
If DET is specified for an input field, only one data byte
is reserved for each input field. This byte is set to
X'OO', and remains unchanged if the field is not selected.
If the field is selected the byte is set to X'FF'.
No other data is supplied, even if the field is a selection
field and the ENTER key has been pressed.
If the data in a detectable field is required, all of the
following conditions must be fulfilled:
1.
The field must begin wi th either a "?" n>", or
"S" and DET must be specified in the output map.
2.
The ENTER key (or some other attention key) must be
pressed after the field has been selected, although for
detectable fields beginning with US" the ENTER key is
not required.
3.
DET must not be specified for the field in the input
map. DET must, however, be specified in the output
map.
IC
indicates that the cursor is to be placed in the first
position of this field. The IC attribute for the last
field for which it is specified in a map is the one that
takes effect. If not specified for any fields in a map,
the default location is zero. Specifying IC with ASKIP or
PROT causes the cursor to be placed in an unkeyable field.
This option may be overridden by specifying the CURSOR
operand for the BMS request that causes the write
operation. See the descriptions of the DFHBMS
TYPE=PAGEBLD, TEXTBLD, and OUT macros, later in this
chapter.
268
CICS/VS APRM(ML)
FSET
specifies that the modified data tag (MDT) for this field
should be set when the field is sent to a terminal.
Specification of FSET causes the 3270 to treat the field as
though it has been modified. On a subsequent read from the
terminal, this field is read, whether or not it has been
modified. The "DT remains set until the field is rewritten
without ATTRB=FSET or until an output mapping request (for
example, DFHMSD CTRL=PRSET or DFBBMS CTRL=FRSET) causes the
r!DT to be reset.
Either of two sets of defaults may apply when a field to be
displayed on a 3270 is being defined but not all parameters are
specified. If no ATTRB parameters are specified, ASKIP and
NORM are assumed. If any parameter is specified, UNPROT and
NORM are assumed for that field unless overridden by a
specified parameter.
COLOR=
specifies the color to be used. If this option is specified
when EXTATT=NO, a warning will be issued and the option
ignored.
If this option is specified, but EXTATT is not,
EXTATT=MAPONLY will be assumed.
GRPNAME=group name
is the name used to generate symbolic storage definitions and
to combine specific fields under one group name. The group
name has a maximum length of five characters for RPG II
programs, and seven characters for other languages. The same
group name must be specified for each field that is to belong
to the group.
The fields in a group must follow oni there can
be intervening gaps between them, but not other fields from
outside the group. A field name must be specified for every
field that belongs to the group, and the pas operand must be
also specified to ensure the fields follow each other.
All the DFHMDF macros defining the fields of a group must be
placed together, and in the correct order (upward numeric order
of the pas operand). For example, the first 20 columns of the
first six lines of a map can be defined as a group of six
fields, so long as the remaining columns on the first five
lines are not defined as fields.
The ATTRB= operand specified on the first field of the group
applies to all of the fields within the group. The lengths of
the fields within the group must not collectively exceed 256
bytes. If this operand is specified, the OCCURS operand canno.t
be specified.
Appendix B contains examples showing, amongst other things, the
effect of the GRPNAME operand.
HILIGHT=
specifies the type of highlighting to be used.
is the default and means that no highlighting is used.
BLINK
specifies that the field is to "blink" at a set frequency.
Chapter 4.3.
Basic Mapping Support
269
REVERSE
specifies that the field is displayed in "reverse video",
for example, on a 3218, black characters on a green
. background.
UNDERLINE
specifies that a field is underlined.
If this option is specified when EXTATT=NO, a warning will be
issued and the option ignored. If this option is specified,
but EXTATT is not, EXTATT=MAPONLY will be assumed.
INITIAL=lcharacter data'IXINIT=hexadecimal data
is used to specify constant or default data for an output
field. The INITIAL operand is used to specify data in
character form; the XINIT operand is used to specify data in
hexadecimal form. INITIAL and XINIT are mutually exclusive.
For fields with the DET attribute, initial data that begins
with a blank character, "&", ">", or "1" should be supplied.
The number of characters that can be specified in the INITIAL
operand is restricted to the continuation limitation of the
assembler to be used or to the value specified in the LENGTH
operand (whichever is the smaller ••
Hexadecimal data is written as an even number of hexadecimal
digits, for example, XINIT=C1C2. If the number of valid
characters is smaller than the field length, the data will be
padded on the right with blanks. For example, XINIT=C1C2 might
result in an initial field of lAB
•
If hexadecimal data is specified that corresponds with line or
format control characters, the results will be unpredictable.
The XINIT operand should therefore be used with care.
JUSTIFY=
indicates the field justifications for input operations. This
operand is ignored for TCAM-supported 3600 and 3190, and for
VTAM-supported 3600, 3650, and 3190 terminals, as input mapping
is not available.
LEFT
specifies that data in the input field is left-justified.
RIGHT
specifies that data in the input field is right-justified.
BLANK
specifies that blanks are to be inserted in any unfilled
positions in an input field.
ZERO
specifies that zeros are to be inserted in any unfilled
positions in an input field.
LEFT and RIGHT are mutually exclusive, as are BLANK and ZERO.
If certain parameters are specified but others are not,
assumptions are made as follows:
210
CICS/VS APRM(ML)
specified
LEFT
RIGHT
BLANK
ZERO
BLANK
ZERO
LEFT
RIGHT
If JUSTIFY is omitted, but the NUM attribute is specified,
RIGHT and ZERO are assumed. If JUSTIFY is omitted, but
attributes other than NUM are specified, LEFT and BLANK are
assumed.
Note: If a field is initialized by an output map or contains
data from any other source, data that is keyed as input may not
be justified and the additional data may remain in the field.
LENGTH=number
indicates the length (from 1 to 256 bytes) of this field. This
specified length should be the maximum length required for
application-program data to be entered into the field; it
should not include the one-byte attribute indicator appended to
the field by CICS/VS for use in subsequent processing. The sum
of the lengths of the fields within a group must not exceed 256
bytes. LENGTH can be omitted if PICIN or PICOUT is specified
but is required otherwise.
The map dimensions specified in the SIZE operand of the DFHMDI
macro instruction defining a map may be smaller than the actual
page size or screen size as defined for the terminal. The
LENGTH specification in a DFBHDF macro instruction cannot cause
the map-defined boundary on the same line to be exceeded. That
is, the length declared for a fiel~ cannot exceed the number of
positions available from the starting position of the field to
the final position of the map-defined line. For example, given
an aO-position page line, the following map definition and
field definition are valid:
DFHMDI
DFHMDF
SIZE=(2,40), •••
POS=22,LENGTH=11, •••
but the following definitions are not acceptable:
DFHMDI
DFHMDF
SIZE=~,40), •••
POS=22,LENGTH=30, •••
OCCURS=number
specifies that the indicated number of entries for the field
are to be generated in a map and that the map definition is to
be generated in such a way that the fields are addressable as
entries in a matrix or an array. This permits several data
fields to be addressed by the same name (subscripted, of
course) without generating a unique name for each field.
OCCURS and GRPNAME are mutually exclusive; that is, OCCURS
cannot be used when fields have been defined under a group
name. If this operand is omitted, a value of 1 is assumed.
Appendix B contains examples showing, amongst other things, the
effect of the OCCURS operand.
Chapter 4.3.
Basic Mapping Support
211
PICIN='value'
specifies a picture to be applied to an input field in an IN or
INOUT map; this picture serves as an editing specification
which is passed to the application program, thus permitting the
user to exploit the editing capabilities of COBOL or PLIT. The
PICIN operand is not valid for assembler or RPG programs. BMS
checks 'value' to ascertain that the specified characters are
valid picture specification characters for the language of the
map. However, no validity checking of the input data is
performed by BMS or the high-level language when the map is
used, so any desired checking must be performed by the
application program. The length of the data associated with
'value' should be the same as that specified in the LENGTH
operand if LENGTH is specified. If both PICIN and PICOUT (see
below) are used, an error message is produced if their
calculated lengths do not agree; the shorter of the two lengths
is used. If PICIN or PICOUT is not coded for the field
definition, a character definition of the field is
automatically generated regardless of other operands that are
coded, such as ATTRB=NUM.
As an example, assume the following map definition is created
for reference by a COBOL application program:
MAPX
MAP
P1
P2
P3
DFHMSD
DFHMDI
DPHMDF
DFHMDP
DFHMDP
DPHMSD
TYPE=DSECT,LANG=C0BOL,MODE=INOUT
LINE=1,COLUMN=1,SIZE=(1,80)
POS=0,LENGTH=30
POS=40,LENGTH=10,PICOUT='$$$,$$0.00'
POS=60,LENGTB=6,PICIN='9999V99',PICOUT='ZZ9.99'
TYPE=PINAL
The following DSECT is generated:
01
01
272
MAPI.
02 F1L
COMP PIC S9(4).
02 P1A
PICTURE x.
02 PILLER REDEPINES P1A.
03 P1F
PICTURE x.
02 P11
PIC X(30).
02 FILLER PIC X.
02 P2L
COMP PIC S9(4).
02 P2A
PICTURE X.
02 PILLER REDEPINES P2A.
03 F2P
PICTURE X.
02 F21
PIC X(10).
02 PILLER PIC X.
02 P3L
COMP PIC S9(4).
02 F31
PICTURE X.
02 PILLER REDEFINES F3A.
03 F3P
PICTURE X.
02 F31
PIC 9999V99.
02 FILLER PIC X.
MAPO REDEFINES MAPI.
02 PILLER PICTURE X (3) •
02 F10
PIC X~O).
02 FILLER PIC X.
02 FILLER PICTURE X(3).
02 F20
PIC $$$,$$0.00.
02 FILLER PIC X.
02 FILLER PICTURE X(3).
02 F30
PIC ZZ9.99.
02 FILLER PIC X.
CICS/VS APRM(ML)
PICOUT='value'
is similar to PICIN, except that a picture to be applied to an
output field in the OUT or INOUT map is generated.
Like PICIN, PICOUT is not valid for assembler or RPG programs.
PS=
specifies the programmed symbol set to be used for the display
of the field.
BASE
specifies that only the basic symbols are used.
psid
specifies a single EBCDIC character or a hexadecimal code
on the form Xlnnl, that identifies the set of programmed
symbols.
If this option is specified when EXTATT=NO, a warning will be
issued and the option ignored. If this option is specified,
but EXTATT is not, EXTATT=MAPONLY will be assumed.
VALIDN=
MUSTFILL
specifies that the field must be filled completely with
data. An attempt to move the cursor from the field before
it has been filled, or to transmit data from an incomplete
field, will raise the inhibit input condition.
MUSTENTER
specifies that data must be entered into the field. An
attempt to move the cursor from an empty field vill raise
the inhibit input condition.
Chapter 4.3.
Basic Mapping Support
213
Input and Output Operations Using the BMS Macro Instructions
Input and output operations using the facilities of BMS are requested by
issuing DFHBMS macro instructions. Parameters provided by the
application program indicate whether an input or an output operation is
needed, the name of the map to be used by BMS, and other information to
control the mapping function. Control is passed to BMS, which performs
any required input/output operations through terminal control.
Initial terminal input, which causes a task to be initiated, is
stored in the initial TIOl of the task as a native-mode data stream.
The initial input data can be mapped into a particular format by·issuing
a DFHBMS TYPE=MAP macro. The format of this initial input data must
correspond to that of the requested map. Input data to be mapped from a
3270 must contain 3270 device-dependent code (in particular, the data
stream must contain an SBA). Similarly, the DFHBMS TIPE=MAP macro can
be used to map further input data, obtained by means of a terminal
co"ntrol RElD request, into a particular format.
Alternatively, the DFHBMS TYPE=IN macro can be issued; this macro
causes a terminal control READ/WAIT operation to occur, and the
resulting terminal input is mapped into a particular format. The data
returned from an input mapping operation is in TIOA format. The address
of the TIOA containing the mapped data is placed in TCTTEDA for a
TYPE=IN operation: for a TYPE=MAP operation, or an output operation, the
address will be placed in the location (TCTTEDA or TCAMSIOA) used to
specify the input data area.
(See the section, nAddressing InputjOutput
Areas," below, for details of specifying input data areas.)
For an output mapping operation, if data is to be passed from the
TIOA of an application program, the application program must have
obtained, through storage control, a TIOA large enough to contain the
symbolic storage definition of the map being used. Any fields for which
data is not to be passed to the mapping operation must be set to nulls
(X100I); this is best achieved through use of the INITIMG=OO operand of
the DFHSC TYPE=GETMAIN macro instruction. The first position of a field
to be sent must not contain a null; if it does, the field will be
ignored.
Maps are defined ·in a map set, which permits the formatting of a page
of output using one or more of the maps in the map set. If the map set
has been placed in the CICS/VS program library, the user should specify
MAPSET=map-set-name and MAP=map-name in any DFHBMS macro instruction
requesting an operation in which the map is required. If preferred, the
user may place the seven-character name of the map set at TCAMSMSN and
the name of the map at TCABMSMN; the MAPSET=YES and MAP=YES operands
inform BMS that the names have been supplied in this way.
(~:
Map
sets did not exist in pre-VS BMS. For pre-VS application programs, BMS
takes the name of the map to be the name of the map set.)
Implied READ/WRITE
DFHBMS TYPE=IN or TYPE=OUT macro instructions result in a terminal
control READ or WRITE, respectively. ·Therefore, the user does not need
to code any terminal control (DFHTC) macro instructions.
However, nothing prevents the user from intermingling native-mode and
BMS operations. A DFHBMS TYPE=MlP instruction can be used to format a
native-mode input TIOl. If a MAP operation is requested for input from
an unformatted 3270 buffer, mapping is not performed and the unformatted
native-mode TIOl is returned to the application program.
274
CICS/VS APRM(ML)
It is nevertheless possible to use DFHBMS TYPE=MAP for the TIOA
containing a transaction-initiating data stream. All that is necessary
to do so is to format the screen uith the preceding task.
Addressinq
Input/Oyt~t-!~
Before a task issues a DFBBMS TYPE=MAP, or any BMS output macro, the
address of the data being passed must be set up in either TCTTEDA or
TCAMSIOA. The rules for deciding which area to use are:
•
If the task is not terminal-oriented, the address of the TIOA-like
area being used must be put in TCAMSIOA. TCTTEDA cannot be
referenced as the task has no TCTTE.
•
If the task is terminal-oriented, but a TIOA is not being used, the
address of the TIOA-like area containing the user data must be put
into TCAMSIOA and TCTTEDA must be filled with binary zeros.
•
If the task is terminal-oriented and the data is in a TIOA, the
address of the TIOA may be put into either TCTTEDA or TCAMSIOA.
the address is put into TCAMSIOA, TCTTEDA must be filled with
binary zeros. If the address is put into both TCTTEDA and
TCAMSIOA, the address in TCTTEDA is used.
If
TCTTEDA is altered by BMS; the user must not assume that its contents
are unchanged.
A BMS input operation places the data into a TIOA, and the address of
the TIOA is returned in TCTTEDA.
Terminal-oriented tasks need not use actual TIOAs. Any task may pass
data to BMS in any portion of dynamically acquired storage which looks
like a TIOA in all respects except two:
o
The storage class need not be terminal.
o
The storage chain address need not refer to a TCTTE or other
terminal storage.
Non-Terminal-Oriented Tasks
These tasks do not have a TIOA or a TCTTE; therefore such tasks cannot
issue any BMS macro instructions that use information in these areas.
They can issue only DFHBMS TYPE=ROUTE, DFHBMS TYPE=PAGEBLD with a
disposition of STORE or RETURN, and DFHBMS TYPE=TEXTBLD with a
disposition of STORE or RETURN.
The NULL built-in function cannot be used to set TCTTEDA to binary zeros
because this places hexadecimal IFFI in the high-order byte of the
address. Instead, the following statement can be used:
UNSPEC(TCTTEDA)=32 I OI B;
Chapter 4.3.
Basic Mapping Support
275
DFHBMS Macro Instructions
BMS macro instructions are provided to enable the application programmer
to:
•
Map data that is already in a TIOA
place) (DFHBMS TYPE=MAP)
•
Read in and map data from a terminal (DFHBMS TYPE=IN)
•
Cumulatively build one or more pages of output data using maps
~FHBMS TYPE=PAGEBLD)
•
Cumulatively build one or more pages of output data without using
maps (DFHBMS TYPE=TEXTBLD)
•
Terminate the accumulation of output data that has been logically
combined and write it to an output device (DFHBMS TYPE=PAGEOUT)
•
Write data (without accumulation) to an output device (DFHBMS
TYPE=OUT)
•
Discontinue the process of building a logical message (DFHBMS
TYPE=PURGE)
•
Define the terminal(s) or operator(s) that are to receive an output
message (DFHBMS TYPE=ROUTE)
•
Check the response to a BMS request (DFHBMS TYPE=CHECK)
~ithout
any terminal I/O taking
In the sections that follow, the syntax of each type of DFHBMS macro
Parameters of the
TYPE= operand are discussed separately under each macro. Descriptions
of all other operands for the DFHBMS macros are gathered into a single
section, arranged in alphabetical order, at the end of the chapter.
is shown, and the use of the macro is explained.
There are a variety of ways in which the various DFHBMS macros can be
used, and combined, for output operations.
The simplest case is DFHBMS TYPE=OUT (without PAGEBLD or TEXTBLD).
This macro instruction results in a simple output operation similar to
that resulting from a DFHTC TYPE=WRITE macro, but with a mapping
operation probably, but not necessarily, included.
When an application programmer wishes to output data which may occupy
more than one device output buffer he can build a single logical message
using a series of DFHBMS TYPE=PAGEBLD macros (if he wants mapping to be
included) or DFHBMS TYPE=TEXTBLD (if mapping is not required). When the
logical message is complete, he terminates the process of accumUlation
and causes physical output to occur by issuing a DFHBMS TYPE=PAGEOUT
macro.
The DFHBMS TYPE=ROUTE macro does not itself cause any output
operation to occur; it defines the destination for ensuing BMS output
macros. The effect of a ROUTE macro should be terminated by a PAGEOUT
macro before another ROUTE macro is issued.
Output operations that do not send user-supplied data (TYPE=PAGEBLD,
DArA=NO or TYPE=OUT, DATA=NO) do not require TIOAs.
276
CICS/VS APRM
~L)
Input Mapping without I/O (TYPE=MAP)
To request that data already in an input TIOA is mapped according to a
specified map.
i
I
I
IDFHBMS
I
I
I
I
1
I
1
,I
1
TYPE=(MAP[,SAVE])
I
[ , MAP= {map-name IYES} ] I[ ,MAPADR= {symbolic-address 1YES) ]1
[,MAPSET={mapset-nameIYES} ]I[,MSETADR=
1
{symbolic-addressIYES)]
I
[ ,ERROR=symbolic-address]
1
[ ,INVMPSZ=symbolic-addre ss]
1
[,MAPFAIL=symbolic-address]
I
[,NORESP=symbolic-address]
1
1
I
TYPE=MAP
specifies an input mapping operation without any associated
terminal I/O operation. The application program must have
placed the address of an input TIOA containing data to be
mapped into TCTTEDA or TCAMSIOA. The data in the TIOA is
positioned into a new TIOA using the map specified in the MAP
operand of the DFHBMS macro instruction, but no terminal I/O
operation occurs. An example of such a TIOA is the initial
TIOA given to a transaction upon entering a transaction code.
If data is included with the transaction code, the screen must
have been formatted previously by another transaction, or the
data is not mapped. The address of the new TIOA is returned to
the application program in the location in which the original
data area was specified ~CTTEDA or TCAMSIOA) •
The following types of data are not mapped, but are left in the
TIOA unaltered.
•
data from TCAM-supported 3600 or 3790
•
data from VTAM-supported 3600 or 3650 (except 3650 host
conversation (3270) logical unit)
•
data from 3790
•
word processing data streams, that is, data received from a
word processing medium type 1, 2, 3 or 4.
SAVE
When used with MAP, SAVE specifies that the user-supplied data
area addressed by TCTTEDA or TCAMSIOA is not to be altered, and
that a new TIOA is to be acquired for the operation. The
address of the new TIOA is returned to the application program
in the location in which the original data area was specified
(TCTTEDA or TCAMSIOA) •
The use of the SAVE operand merely stops CICS/VS overwriting a
data area that you want to retain. It is still necessary to
store the address of any such area elsewhere, so that it can be
accessed later, because the location containing the address is
overwritten.
Chapter 4.3.
Basic Mapping support
277
Input Operations with Mapping (TYPE=IN)
To request BMS services for input operations, a DPHBMS macro instruction
of the following format is used:
r------~i-------r-
I
DFHBMS
~_____ ~_______ L
--------------------------------------------------------,
TY PE= (IN[ , SA VE )[ , TEXT ))
[,MAP={map-nameIYES} ]1[,MAPADR={symbolic-addressIYES})
[,MAPSET={mapset-nameIYES} ]I[,MSETADR=
{symbolic-addressIYES} ]
[,EOC=symbolic-address]
[ ,EODS=symbolic-address]
[,ERROR=symbolic-address]
[ ,INVMPSZ=symbolic-address]
[,MAPPAIL=symbolic-address]
[,NORESP=symbolic-address]
[ ,RDATT=symbolic-address]
_______________________________________________________~
TYPE=IN
specifies an input mapping operation. Input is accepted from
the terminal through a terminal control READ/WAIT request. The
input data is then mapped into the TIOA and made available to
the application program by placing the TIOA address at TCTTEDA.
The fields entered as part of the input data stream are
available to the application program under the field names
specifie.d in the DPHMDP macro instructions by which they are
defined, suffixed with the letter I to correspond to the name
generated by CICS/VS in the definition of the area.
The following types of data are not mapped, but are left in the
TIOA unaltered.
•
data from TCAM-supported 3600 or 3790
•
data from VTAM-supported 3600 or 3650 (except 3650 host
conversation (3270) logical unit)
•
data from 3790
•
word processing data streams, that is, data received from a
word processing medium type 1, 2, 3 or 4.
If DPHBMS TYPE=IN macro instructions are used to read data
from a VTAM batch logical unit, the inbound function
management headers (PMHs) will be removed before the data
is placed in the TIOA. If an PMH is required, the
application programmer should issue a DPHTC TYPE=READ macro
instruction, deal with the PMH, and then issue a DPHBMS
TYPE=MAP macro instruction to map the data. Inbound PMHs
are applicable only to batch logical units.
278
CICS/VS APRM(ML)
SAVE
when used with IN, specifies that the data area addressed by
TCTTEDA is not to be altered; a new TIOA is to be acquired for
the operation, and its address returned in TCTTEDA.
The use of the SAVE operand merely stops CICS/VS overwriting a
data area that you want to retain. It is still necessary to
store the address of any such area elsewhere, so that it can be
accessed later, because the location containing the address is
overwritten.
TEXT
indicates that uppercase and lowercase characters are contained
in the input data stream.
This parameter is used to override a FEATURE=UCTRAN
specification in the DFHTCT macro instruction used by the
system programmer for the input terminal.
(See the CICS/VS
System Programmer's Reference Manual.)
Chapter 4.3.
Basic Mapping Support
279
Building Output Pages Using Maps (TYPE=PAGEBLD)
To build an output page cumulatively, using maps, the application
program uses the DPHBMS TYPE=PAGEBLD macro instruction. This causes the
data in the area defined by a specified symbolic description map to be
mapped according to the physical map. The mapped data is positioned
within an area large enough to contain one page of output. The
application programmer issues another DPHBMS TYPE=PAGEBLD macro
instruction to map and position the next portion of the output page.
The mapping operation continues until the application program has
completed the message to be sent to the terminal.
Because of CICSjVS terminal paging facilities, the application
programmer need not keep track of when a page is full. He can either
let BMS force a new page automatically or include the OPLOW operand in
the DPHBMS TYPE=PAGEBLD macro instructions to cause BMS to transfer
control to an overflow routine (which the programmer must provide) when
a page of data cannot contain the data to be mapped.
The format of the DFHBMS TYPE=PAGEBLD macro instruction is as
follows:
i
I
DFHBMS
TYPE= (PAGEBLD[, {OUT[ ,WAIT)I STORE IRETURN} ]
[,SAVE][,ERASEX,ERASEAUP][,LAST])
[ ,DATA= {NOIYES IONLY} ]
[,MAP={map-nameIYES} ]
[,MAPSET={mapset-nameIYES} ]1
[ , MSETADR= {symbolic-address I YES} ]
[,CTRL=([PRINT][,{L40IL64IL80IHONEOM} ]
[ ,PREEKB][ , ALARM ][ ,FRSET]) ]
[,CURSOR={number IYES} ]
[,FMHPARM={parameterIYES} ]
[,LDC={mnemonicIYES} ]
[ , PROPT=NLEOM ]
[ ,REQID= {prefix IYES} ]
[,ERROR=symbolic-address]
[ ,IGREQID=symbolic-address]
[,INVLDC=symbo1ic-address]
[ ,INVMPSZ=symbolic-address]
[,INVREQ=symbo1ic-address]
[,NORESP=symbolic-address]
[ ,OFLOW=symbo1ic-address]
[,RETPAGE=symbo1ic-address]
[,TSIOERR=symbolic-address]
[,IGREQCD=symbolic-address] ---->Assembler only
[,WRBRK=symbolic-address]
>CICS/OS/VS only
where:
TYPE=PAGEBLD
indicates that one page of data is to be accumulated and
formatted from data submitted through multiple PAGEBLD
requests. In each PAGEBLD request, a map defines the
number of lines and columns that the data is to occupy on
the page. When a page is complete, as defined by one or
more maps, it is written according to an OUT, STORE, or
RETURN disposition.
280
CICS/VS APRM(ML)
HAP POSITIONING
The position of a map on a screen is determined by two major factors:
the current contents of the screen, and the values coded for the LINE,
COLUMN, and JUSTIFY operands of the DFHMDI macro. Positioning is also
affected if the DFHMDI macro specifies HEADER=YES or TRAILER=YES, and by
the depth of the deepest trailer map in the map set.
The Screen Contents
At any instant, the part of the screen which is still available for maps
is in the form of either an L, a reversed L, a rectangle or an inverted
T, as shown by the unshaded area in the following diagram.
next column
from left
current line
left reference
column
next column
from right
right reference
column
------<~
next free line - - - - + I
free
area
trailer size
Chapter 4.3.
Basic Mapping Support
281
The shape and size of this area is represented internally by four
variables: current line, next free line, next column from left, and
next column from right.
Three other pointers are maintained that are relevant to map
placement though they do not affect the area available: left reference
column and right reference ~lumn, which are used when ~OL=SAME is
specified, and trailer size.
The Trailer Area
The trailer size is equal to the number of lines that would be occupied
by the deepest trailer map in the map set currently in use. It is
determined when the map set is assembled, and is copied from the map set
whenever one is loaded.
The area defined by trailer size is not available for mapping unless
no overflow routine has been specified or the map has TRAILER=YES
specified in its DFHMDI macro.
JUSTIFY=FIRST and JUSTIFY=LAST
If JUSTIFY=FIRST is specified, the map is placed on a new page, so that
the only maps above it are the header maps used in overflow processing.
The LINE operand may also be used with JUSTIFY=FIRST to place the map
below the top of the page.
If JUSTIFY=LAST is specified, the map is placed as low as possible on
the page. For a non-trailer map, this is immediately above the trailer
area; for a trailer map, it is at the bottom of the page.
A map defined with JUSTIFY=LAST cannot be used in input operations
unless it was previously put out without PAGEBLD, in which case
JUSTIFY=LAST is ignored and the map is positioned at the top of the
page.
The LINE Operand
The LINE operand specifies the line of the screen on which the first
line of the map is to be placed. The initial determination of this line
is made without regard to the specification of the COLUMN operand or the
columns available on the screen on that particular line. If it
transpires that the map will not fit on the chosen line, the first
subsequent line that will satisfy the column requirements is selected.
If LINE=SAME or LINE=NEXT is specified, the initial line selected for
the start of the map is the current line or the next free line ,
respectively. If a number is specified in the LINE operand, the line
with that number is selected, provided the number is greater than or
equal to the number of the current line; if not, the overflow condition
is raised so that the map can be placed on the next page.
The line selected becomes the new current line and, if it is below
the next free line, the next free line is reset to the same line; the
next column from the left and right are also reset, to the left and
right margins respectively.
282
CICS/VS APRM(ML)
If the line selected is such that the end of the map extends into the
trailer area for a non-trailer map or beyond the end of the page for a
trailer map, the overflow condition is raised and the map will be placed
on the first available line of the next page when the reguest is
reissued after handling the overflow.
The COLUKN and JUSTIFY
O£~~2
The COLUMN specification may be either NEXT, SAME, or a number and is
processed in conjunction with the LEFT or RIGHT specification of the
JUSTIFY operand. JUSTIFY=LEFT is the default and implies that the
column specification is related to the left-hand margin. Conversely,
JUSTIFY=RIGHT implies that the column specification is related to the
right-hand margin. For the purposes of this explanation, it is assumed
hereafter that JUSTIFY=LEFT has been specified (or applied by default).
If COLUKN=NEXT is specified, the column chosen for the map is the
next column from the left. If a numeric value is specified, the column
with that number is chosen, counting from the left. If COLUMN=SAME is
specified, the left reference column is chosen.
(The left reference
column is the one that was most recently specified by number with
JUSTIFY=LEFT. )
The map is then checked to ensure that its right margin is not to the
right of the next column from the right. If it is, the map will not fit
in the leg of the inverted T, so a new line must be selected. This will
be either the next full line or, if the map is too deep, the first
available line on the next page.
Finally, the column pointers are updated by setting the next column
from the left to the right margin of the map, and, if COL=number was
specified, by setting the left reference column to the specified column
number.
Pagebuilding Examples
The effects of the mechanisms described above are illustrated by the
following examples. The examples show the interactions between SIZE,
LINE, COLUMN, and JUSTIFY=LEFT or RIGHT; header and trailer maps and
JUSTIFY=FIRST or LAST are not brought into the examples.
In processing a PAGEBLD reguest, BKS determines whether the area of
the page required by the map is wholly available or whether any part of
it has been used by an earlier PAGEBLD reguest. "Used" means actually
filled by a map or rendered unavailable as described below.
Chapter 4.3.
Basic Mapping Support
283
1.
When the LINE operand of the DFHMDI macro is coded, all lines above
the specified line are rendered unavailable.
Example:
A DFHMDI
••• ,LINE=3, •••
3
2.
When JUSTIFY=LEFT is coded ~r applied by default), all columns to
the left of the leftmost map column, for the full depth of the map,
are rendered unavailable.
ExamRle:
A DFHMDI
••• ,LINE=3,COLUMN=5,JUSTIFY=LEFT, •••
5
3.
When JUSTIFY=RIGHT is coded, all columns to the right of the
rightmost map column, for the full depth of the map, are rendered
unavailable.
Example:
A DFHMDI
••• ,LINE=3,COLUMN=35,JUSTIFY=RIGHT, •••
35
3
284
CICS/VS APRM(ML)
1
4.
When two or more maps are placed so that they share certain lines,
all columns beneath a map that ends higher are rendered unavailable
to the depth of the map that ends lowest. Similarly rendered
unavailable are all columns to the left (if the higher map is left
justified) or to the right (if the higher map is right justified)
of the 'used' area beneath the higher map.
Example (a):
A DFHMDI
B DFHMDI
••• ,LINE=3,COLUMN=2 ,JUSTIFY=LEFT, •••
••• ,LINE=4,COLU~N=20,JUSTIFY=LEFT, •••
A DFHMDI
B DFHMDI
••• ,LINE=3,COLUMN=2,JUSTIFY=LEFT, •••
••• ,LINE=4,COLUMN=20,JUSTIFY=RIGHT, •••
A DFHMDI
B DFHMDI
••• ,LINE-=3,COLUMN=40,JUSTIFY=RIGHT, •••
••• ,LIN-E=3,COLUMN=1 ,JUSTIFY=LEFT, •••
3
Example (b):
3
Example
(C):
3
Chapter 4.3.
Basic Mapping Support
285
MapC
Map 0
JUSTIFY
= RIGHT
JUSTIFY
= LEFT
If BMS discovers that an area of the page directly specified for a
map has already been used by a previous map, it raises the overflow
condition, described below under "PAGEBLD Overflow Processing."
Handling Returned Pages
Whenever one or more pages have been completed and the programmer has
specified TYPE=RETURN, TCAMSRLA contains the address of a list of
completed pages. since more than one page of output may result from a
single BMS output request, there may be more than one entry in the list
for a given terminal type. All entries for a particular terminal type
immediately follow one another in the list. The list is laid out as
follows:
TC I Page Buffer
I TC I page Buffer
4 bytes
4 bytes
XIFF ••• FFI
4 bytes
TC = Terminal code (see "Terminal Code (TC) Table," later in this
chapter).
The page buffer pointer points to an area of USER-class storage which
has a 12-byte prefix similar to that of a terminal input/output area
(TIOA), as follows:
CICS/VS storage Acctng
8 bytes
286
CICS/VS APRM
Buffer Length
2 bytes
~L)
Reserved
Data
2 bytes
x bytes
At this point, page buffers are on the USER-class storage chain and
are disassociated from BMS control blocks; it is therefore the user's
responsibility to release page buffers when they are no longer needed.
The storage containing the list of buffers should not be freed by the
programmer; it is the intention of BMS to reduce processing time by
reusing the list. This list will be altered by the next BMS request.
Therefore, the programmer must save the contents before issuing the next
BMS request.
Subsequent output of pages should normally be done using BMS. The
use of the OFHTC macro to handle the output of paqes is not recommended.
However, if a OFHTC TYPE=WRITE macro is used, st\ ~ Je must be obtained
by a DFHSC TYPE=GETMAIN macro with the CLASS=TERM operand included, and
the output pages moved to the TIOA so acquired. The DFHTC TYPE=WRITE
macro can then be used to transmit the pages from this new TIOA.
When terminals of the 3270 Information Display System are used, the
write control character (WCC) containing the CTRL specification can be
found at TIOACLCR in the page buffer after addressability to the area
has been established.
~IOACLCR is a defined field in OFHTIOA and is
addressable if the buffer address is loaded into TIOABAR.)
PAGEBLO Overflow
Processi~
Overflow occurs when the number of lines in the requested map plus the
number of lines in the largest trailer map in the map set (if there are
any trailer maps) is greater than the number of lines remaining in the
page being built for the terminal involved in an output operation. For
TCAM and VTAM terminals having LOC support, pages are accumulated
individually by LOC mnemonic. Therefore, overflow may occur at end of
page for each different LDC mnemonic used in different BMS requests.
The LDC mnemonic is passed to the user's overflow routine in TCAMSLOM,
and the LOC numeric value is passed in TCAMSLOC. PAGEBLO overflow can
occur on a logical message being built for a ROUTE environment. If the
ROUTE environment was created with a route list containing more than one
LOC mnemonic, then the returned LOC mnemonic and numeric value is the
first LDC mnemonic resolved in the route list.
The routine to which control is transferred must be in the
application program, but no special considerations apply. ~he data
which was to have been mapped, but which caused the overflow, is not
mapped by BMS and remains unaltered in the TIOA.
If a DFHBMS TYPE=ROUTE macro instruction has not been previously
issued, there is only one destination. If a DFHBMS TYPE=ROUTE macro
instruction has been issued, the logical message is probably being built
for a multiple-destination environment. Since the application
programmer has the capability of concurrently building pages for
terminals that have different-sized output, overflow may occur at
different times for different terminal groups. The overflow routine
gets control every time anyone of the destinations or groups of
destinations encounters an overflow condition, that is, every time a
specified map will not fit a page. The application program overflow
routine must determine which destination or group of destinations has
encountered the overflow.
Upon return to the application program from a DFHBMS TYPE=ROUTE macro
instruction, a count (relative to one) of the number of destinations or
groups of destinations is available in TCAMSOCN. This overflow control
count tells the application programmer how many overflow ~ontrol areas
(for example, accumulators) he may want to keep. Whenever the overflow
Chapter 4.3.
Basic Mapping Support
287
routine gets control, TCAMSOCN indicates the relative overflow control
number of the destination that has encountered the overflow. This
number indicates which control area should be output, perhaps through
one or more trailer maps. In addition to the relative control count,
BMS returns the current page number for the destination that has
encountered the overflow. This page number is located at TCAMSPGN.
To place trailer data on a page, the programmer codes DFHBMS
TYPE=PAGEBLD request(s) to process the trailer data.' The map(s) used to
format the data must contain TRAILER=YES so that the amount of space on
the page to reserve for overflow can be calculated. More than one
trailer map may be placed on a page. There should be a dummy trailer
map (not otherwise used) in the map set specifying the number of lines
to be reserved for trailer data if no single trailer map extends over
the total number of lines required for trailer data (see Figure 4.3-1).
Maps used to map trailer data may contain JUSTIFY=LAST to force their
placement at the bottom of the page. If the programmer tries to place
more lines of trailer data on the page than are available, that trailer
data is placed on a separate page by itself. Still another page is
built to continue mapping with or without a header map.
L____________________________
__
TRl
TR2
TR3
Dummy trailer required.
Figure 4.3-1 •
Use of Trailerl!aps in PAGEBLD Mapping Operations
To place header data on a page, the programmer codes DFHBKS
TYPE=PAGEBLD request(s) to process the header data. The map~) used to
map header data must specify JUSTIFY=FIRST to complete processing of the
previous page if that has not been done, and to begin a new page.
(JUSTIFY=FIRST is ignored if BMS is positioned at the top of a new
page.) If the programmer tries to place more header data on the page
than the page can contain, multiple pages are created.
After overflow has been raised, the first map to be used in a
TYPE=PAGEBLD request must be one that specified JUSTIFY=FIRST. Failure
to do this will result in overflow being raised again immediately.
When all trailer and/or header data has been processed, the
programmer must reissue the DFHBMS request that caused the overflow,
since this data has not yet been mapped for all destinations.
If the user does not specify an overflow routine while issuing
PAGEBLD requests, no overflow occurs and new pages will be forced
automatically. If a header is to be placed on the first page and a
trailer on the last, the OFLOW parameter would not be used.
288
CICS/VS APRM(ML)
A general overview of overflow processing is given in the flowchart
in Figure 4.3-2.
Application program prepares & issues a
PAGEBLD request and includes an
OFLOW routine address
DFHBMS macro expansion BALRs to
BMS program
APPLICATION PROGRAM'S
OVERFLOW ROUTINE
1) Save sufficient information to be able
to reissue the request that just caused
an overflow.
BMS programs process the request
2)
DFHBMS macro expansion
checks to see if an
overflow occurred
Using the overflow control number in
TCAMSOCN, determine the appropriate
control area to map its contents via
PAGEBLD requests, specifying trailer
map(s).
3) The current page number is available at
TCAMSPGN and could be supplied with
the data to be mapped by the trailer
map(s); and/or this page number could
be incremented and supplied with the
data to be mapped by header map(s).
Yes
4) At this point, do not update any control
areas to reflect the original PAGEBLD
request that caused the overflow.
5) Do reinitialize the control areas that just
supplied the data for overflow processing.
DFHBMS macro expansion has returned
control to application program and the
PAGEBLD request has been mapped for
all of the desti nations.
6) Do return to the logic(@)that issued
the original PAGEBLD request and
reissue that request.
The application program updates ~
overflow control areas to reflect the last
PAGEB LD request (which mayor may
not have caused an overflow).
••
•
Figure 4.3-2.
Overflow Processing by Application Programs under BMS
Chapter 4.3.
Basic Mapping Support
289
Building Output Pages without Using Maps (TYPE=TEXTBLD)
To request the building of pages of data without the use of maps, the
application program issues DFHBMS TYPE=TEXTBLD macro instructions.
These macro instructions cause BMS terminal paging to create pages
containing application-program-supplied text data. The length of the
data each macro instruction is to process must be supplied in TIOATDL,
prior to issuing the macro instruction. Completion of a logical message
is signaled by a DFHBMS TYPE=PAGEOUT macro instruction. The beginning
and ending of pages are handled by BMS and need be of no concern to the
application program.
The format of the DFHBKS TYPE=TEXTBLD macro instruction is as
follows:
DFHBMS
TYPE=(TEXTBLD[, rOUTE ,WAIT]ISTOREIRETURN} ]
[,SAVE)[ ,ERASE)[ ,LAST])
[,HEADER={symbolic-addressIYES} ]
[ ,JUSTIFY={FIRSTILASTlline-numberIYES})
[,TRAILER={symbolic-andressIYES} ]
[,CTRL=([PRINT][,{L40IL64IL80IHONEOM} ]
[,FREEKBli,ALARM) ]
[ ,CURSOR= {number I YES} )
[,FMHPARM={parameterIYES} )
[,LDC={mnemonicIYES} ]
[ , PROPT=NLEOM]
[ ,REQID= {prefix I YES} ]
[,ERROR=symbolic-address)
[,IGREQID=symbolic-address]
[,INVLDC=symbolic-address]
[,INVREQ=symbolic-address]
[,NORESP=symbolic-address)
[,RETPAGE=symbolic-address]
[,TSIOERR=symbolic-address]
[,IGREQCD=symbolic-address]
)Assembler only
[,WRBRK=symbolic-address]
>CICS/OS/VS-2741 only
where:
TYPE=TEXTBLD
indicates that (1) one page of output is to be formed from
data submitted through multiple TEXTBLD requests, or (2)
multiple pages of output are to be formed from one TEXTBLD
request. When TEXTBLD is specified, no map is used. When
no mora data can fit on a page, the page is written
according to the OUT, STORE, or RETURN disposition (see
below), and another page is started if necessary.
290
CICS/VS APRM(ML)
Direct Output (TYPE=OUT)
An output request in which neither TEXTBLD nor PAGEBLD is specified can
be issued by the application program. Such a request may cause multiple
pages to be written as output, but multiple requests cannot be issued to
accumulate and format data within one page. One map may be used to
format data on one page, and that page may be written directly to the
terminal (TYPE=OUT). The rules governing this type of output are as
follows:
.
•
Multiple requests cannot be accumulated to build one page, whether
mapped or unmapped.
•
When using maps, one request cannot build more than one page.
•
When not using maps, a single request can result in more than one
page.
•
If the disposition is STORE, multiple requests can cause multiple
pages (each request starting a new page) to be included in one
logical message.
•
For both mapping and nonmapped operations, if the disposition is
STORE, a DFHBMS TYPE=PAGEOUT request must be issued to terminate
the logical message.
r------~-------r--------------------------------------------------------~
DFHBHS
TYPE= ([ {CUTe , tiA IT] I STORE I RETURN} ][ ,NOEDIT][ , SAVE]
[ , ERASE][ , ERASEAUP][ , LAST])
[,DATA={NOIYESIONLY} ]
[,MAP={map-nameIYES} ]1,MAPADR={symbolic-addressIYES}]
[,MAPSET={mapset-nameIYES} ]I[,MSETADR=
{symbolic-addressIYES} ]
[,CTRL=([PRINT][ ,{L40IL64IL80IHONEOM}]
[ ,FREEKB][ , ALARM ][ , FR SET ]) ]
[,CURSOR=(numberIYES} ]
[,FMHPARH=(parameterIYES} ]
[,LDC={mnemonicIYES}]
[ ,PROPT=NLEOM]
[,REQID={prefixIYES} ]
[ , ERROR=sy mbolic-address ]
[,IGREQID=symbolic-address]
[,INVLDC=symbolic-address]
[ ,INVMPSZ=symbolic-address]
[ ,INVREQ=symbolic-address]
[ ,NORESP=symbolic-address]
[,RETPAGE=symbolic-address]
[,TSIOERR=symbolic-address]
[ ,IGREQCD=symbolic-address]
)Assembler only
[ , WRBRK=symbolic-address]
>CICSjOS/VS only
where:
Chapter 4.3.
Basic Mapping Support
291
TYPE=OUT
indicates that the output is to be written to the
originating terminal at once if that terminal is to receive
it.
Once a DFHBMS macro with OUT disposition has been issued,
the application program must not issue a DFHSC
TIPE=FREEMAIN,RELEASE=ALL macro until either a DFHBMS
TYPE=PAGEOUT or DFHBMS TYPE=PURGE macro has been issued.
292
CICS/VS APRM(ML)
Terminating a Logical Message (TYPE=PAGEOUT)
When the combining of pieces of data to form a logical message has been
requested by means of DFHBMS TYPE=PAGEBLD or TYPE=TEXTBLD macro
instruction(s), such combining must be terminated by means of a DFHBMS
TYPE=PAGEOUT macro instruction. A logical message created by means of
one or more noncumulative output requests with STORE disposition must be
terminated by a DFHBMS TYPE=PAGEOUT macro instruction. The format of
this macro instruction is as follows:
r------r-------rDFHBMS
~
--------------------------------------.------------------~
TYPE=(PAGEOUT[,LAST])
[ ,CTRL= ([ {PAGE I AUTOPAGE} ], {RETAINI RELEASE} ])
[ , EODPURG= fA UTO lOPER} ]
[,FMHPARM={parameterlYES}]
[ ,TRAILER= {symbolic-address I YES} ]
[,TRANSID=transaction code]
[,WRBRK={symbolic-addresslcURRENTIALL} ]
[,ERROR=symbolic-address]
[,NORESP=symbolic-address]
[,RETPAGE=symbolic-address]
[,IGREQCD=symbolic-address]
>Assembler only
[ ,TSIOERR=symbolic-address]
_____ ~_______ L- ______________________________________________________~
where:
TYPE=P~GEOUT
specifies the termination of a logical message. No data is
formatted in response to this request. Any remaining data
in the page buffer is processed according to the OUT,
STORE, or RETURN described in the previous macro
instruction. If a logical message is being built for a
routing environment, PAGEOUT completes the logical message
under route. An additional PAGEOUT macro instruction is
required to complete-a-logical message to the originating
terminal.
If an error occurs during PAGEOUT processing, control is
returned to the application program, and the RETAIN or
RELEASE specifications are ignored. The logical message is
not considered complete. The application program should
either retry the PAGEOUT operation or PURGE the message.
Any logical message that has been started but not completed
when a DFHSP (sync point) macro is issued is forced to
completion by an implied TYPE=PAGEOUT macro.
Chapter 4.3.
Basic Mapping Support
293
Deleting a Logical Message (TYPE =PURGE)
To discontinue the process of building a logical message, a DFHB!S
TYPE=PURGE macro instruction is issued. This instruction causes the
portions of the message already built in main storage or on temporary
storage to be deleted and returns control to the applica~ion program at
the instruction following the DFHBMS TYPB=PURGB macro expansion.
(The
TYPE=PURGE instruction is not to be used if TYPB=RBTURN was us'ed in the
BMS PAGEBLD or TEXTBLD request.) The format of the macro instruction is
as follows:
I
I
DFBBKSI
TYPE=PURGE
I,
where:
TYPE=PURGE
specifies that all data prepared for a logical message but not
yet transmitted to a terminal is to be deleted from the system.
294
CICS/VS APRM CML)
Message Routing (TYPE=ROUTE)
A DPHB!S TYPE=ROUTE request defines the terminal and/or operator to
receive the message created by ~ubsequent DPHBMS output requests. The
message may be directed to any or all BMS-supported terminals. The
ROUTE macro defines the destination of the message; it does not cause
transmission to occur. The ROUTE macro must thus be followed by one or
more BMS ouput macros. A DPHBMS TYPE=PAGEOUT request causes the logical
message to be completed and terminates the effect of the DPHBMS
TYPE=ROUTE macro instruction.
If a ROUTE request followed by one or more BMS output requests is not
terminated by a PAGEOUT request before a subsequent ROUTE request is
issued or before the application program terminates, the message is
forced to completion. since the application program did not issue the
PAGEOUT request, BMS applies the PAGBOUT defaults to the message. A
ROUTE request may be issued immediately following another ROUTE request.
In this case, the first ROUTE request is nullified, and the second one
determines the routing environment.
A message is considered undeliverable to a destination if it cannot
be delivered within a certain interval after the requested delivery
time. This interval is specified in the PRGDLAY operand of the DPHSG
PROGRAM=BMS macro instruction by the system programmer. If the PRGDLAY
operand is not included, no action is taken for undelivered messages and
the message awaits delivery indefinitely. If PRGDLAY is specified, the
transient data destination CSMT is notified of the number of
undeliverable messages purged for a destination; the application
programmer can ensure that additional documentation is provided for an
undeliverable message by including the BRRTERM operand in the DPHBMS
TYPE=ROUTE macro instruction. Bxamples of situations causing
undeliverable messages might occur, for example, when a message is
routed to a terminal that is out of service, or when an operator
identification is specified with a terminal identification and that
operator is not signed on that terminal at the time the message is to be
delivered.
If operating in a DL/I environment, a message should not be routed to
more than 40 terminals by using only one TYPE=ROUTE macro. If it is
required to route to more than 40 terminals, several TYPE=ROUTE macros
must be issued, each with a LIST operand that specifies a list of
terminals with more than 40 entries. Each TYPB=ROUTE macro must be
issued with all other DPHBMS macros relevant to the message.
The format of the DPHBMS TYPB=ROUTB macro instruction is as follows:
Chapter 4.3.
Basic Mapping Support
295
OFHB8S
~
TYPE=ROUTE
[,ERRTERM={termidIORIGIYES} ]
[,LIST={symbolic addressIYESIALL}]
[,OPCLASS={decimal-value, ••• IYES}]
[,TITLE={symbolic-addressIYES} ]
[,INTRVAL={numeric-valueIYES} ]I[,TIME=
{numeric-valueIYES} ]
[ , LOC= {mnemonic I YES} ]
[ ,PROPT=NLEOM ]
[ ,REQIO={prefix IYES} ]
[,ERROR=symbolic-address]
[ ,IGREQID=symbolic-address]
[,INVET=symbolic-address]
[,NORESP=symbolic-address]
[,RTEFAIL=symbolic-address]
[,RTESOME=symbolic-address]
_____ L-~______,L-________________________________________________________~
where:
TYPE=ROU'l'E
specifies the initiation of an output page routing operation.
~isposition
and Message Routing
A routed logical message can be built using either of two dispositions:
STORE or RETURN. The first BMS output request issued following the
ROUTE request· (with some exceptions noted below) determines the
disposition of the logical message. This first request may specify
STORE or RETURN; if neither is specified, the default is STORE. Once
established, the disposition remains unchanged until the logical message
is completed ~AGEOUT). It need not be repeated for subsequent
requests. An output request specifying a disposition that is not in
effect results in a return code of INVREQ.
A disposition of STORE is the normal disposition and finally results
in the message either being delivered or deleted. A disposition of
RETURN causes the routed logical message to be returned to the
application program. It is the responsibility of the application
program to deliver the logical message.
A task can converse with the terminal to which it is currently
attached (assuming the task is terminal-oriented) during the time that
it is building the logical message. That attached terminal is known as
the direct terminal; a terminal to which the message is to be routed is
known as a routing terminal. If any input requests (DFHBMS TYPE=IN or
TYPE=MAP) are encountered while the message is being built, they are
processed as usual. To transmit output to the direct terminal while the
routed logical message is being built, the task can issue non-TEXTBLO,
non-PAGEBLD requests with an explicit disposition of OUT. The
disposition of OUT isolates the output request to the direct terminal
from the requests that are building the routed logical message.
The following points summarize rules for conversation with the direct
terminal while a routed logical message is being built:
•
296
OUT must be specified in any output request that is to go to the
direct terminal.
CICS/VS APRM(ML)
•
TEXTBLD and PAGEBLD ~equests with a disposition of OUT
and ~esult in a ~etu~n code of INVREQ.
a~e
•
The di~ect te~minal may be included in the routing environment
without impai~ing the ability to converse with it while under
ROUTE.
Data routed to the direct terminal will be delivered as
though the ROUTE had been issued from another terminal.
invalid
A list of nabridged" requests, in order of execution, is gi ven below.
The action taken by BMS for each is indicated.
Action Taken by BMS
di~ect
DFHBMS TYPE=OUT
Transmit to
DFHBMS TYPE=ROUTE
Establish routing environment.
DFHBMS TYPE=OUT
Transmit to direct terminal.
DFHBMS TYPE=IN
Receive from direct terminal.
DFHBMS TYPE=TEXTBLD
First output request eligible for routing
establishes default disposition of STORE
and TEXTBLD as mode of page building.
DFHBMS TYPE=OUT
Transmit to direct terminal.
DFHBMS TYPE=TEXTBLD,RETURN
INVREQ - routed logical message has
already established a disposition of STORE.
DFHBMS TYPE=TEXTBLD
continue building routed logical message.
DFHBMS TYPE=PAGEBLD,STORE
INVREQ - routed logical message being
built with TEXTBLD requests cannot
tolerate PAGEBLD request.
DFHBMS TYPE=PAGEBLD,OUT
INVREQ - cannot issue PAGEBLD or TEXTBLD
request to direct terminal while building
a routed logical message.
DFHBMS TYPE=TEXTBLD,STORE
Continue building routed logical message.
DFHBMS TYPE=PAGEOUT
Terminate routed logical message and
routing operation.
DFHBMS TYPE=OUT
Transmit to direct terminal.
status
Fl~yte
terminal.
in User-Supplied Route List
Each route list entry contains a status flag byte used by BMS to
indicate to the application program the status of the destination at the
time the DFHBMS TYPE=ROUTE macro instruction was issued. Upon return,
the application program can investigate the status byte for each route
list entry and take appropriate action.
The status flag byte settings are shown in Figure 4.3-3. Their
meanings are explained in greater detail in the text that follows.
Chapter 4.3.
Basic Mapping Support
297
Status Flag
Condition
(See explanation below.)
Assembler
COBOL
PL/I
ENTRY SKIPPBD
X '80'
12-0-1-8
10000000
INVALID TERMINAL
IDENTIFICATION
X'40'
no punches
01000000
TERMINAL NOT SUPPORTED
UNDER BMS
X'20'
11-0-1-8-9
00100000
OPERATOR NOT
SIGNED ON
X'10'
12-11-1-8-9
00010000
OPERATOR SIGNED ON
UNSUPPORTED TERMINAL
X'OS'
12-8-9
00001000
INVALID LDC MNEMONIC
X'04 1
12-4-9
00000100
Figure 4.3-3.
BMS Status Flags
ENTRY SKIPPED
A route list entry that is flagged as skipped was not included
in the resolved routing environment. If an entry has been
skipped, another flag indicating why the entry was skipped may
be on in the status byte. This second flag could be 2n~ of the
following:
•
INVALID TERMINAL IDENTIFICATION
•
TERMINAL NOT SUPPORTED UNDER BMS
•
OPERATOR NOT SIGNED ON - only an operator identification
was specified in the route list entry and that operator was
not signed on any terminal
•
OPERATOR SIGNED ON UNSUPPORTED TERMINAL
•
INVALID LDC MNEMONIC
If only the ENTRY SKIPPED flag is on, neither a terminal
identification nor an operator identification was specified in
the route list entry.
INVALID TERMINAL IDENTIFICATION
This flag indicates that the terminal identification specified
in the route list entry does not have a corresponding TCTTE in
the terminal control table. This entry is also flagged as
ENTRY SKIPPED.
TERMINAL NOT SUPPORTED UNDER BMS
This flag indicates that the terminal identification specified
in the route list entry is for a terminal type that is not
supported under BMS or the terminal table entry indicated that
the terminal identification was not eligible for routing. This
entry is also flagged as ENTRY SKIPPED.
298
CICS/VS APRM(ML)
OPERATOR NOT SIGNED ON
This flag indicates that the specified operator is not signed
on. Any ~ of the following conditions causes this flag to be
set:
1. An operator identification was specified with a terminal
identification, but the specified operator was not signed
on the terminal. This entry is not skipped.
2. An operator identification was specified without a terminal
identification, and the operator was not signed on any
terminal. This entry is also flagged as ENTRY SKIPPED.
3. The OPCLASS operand was specified with the DFHBMS
TYPE=ROUTE macro instruction and a terminal identification
was specified in the route list entry, but the operator
signed on the terminal did not qualify under OPCLASS. This
entry is not skipped.
OPERATOR SIGNED ON UNSUPPORTED TERMINAL
This flag indicates that only an operator identification was
specified in the route list entry, and that operator vas signed
on a terminal not supported by BMS. This entry is also flagged
as ENTRY SKIPPED. The unsupported terminal identification is
returned in that route list entry at URLTRMID for informational
purposes only.
INVALID LDC MNEMONIC
This flag indicates that one of the following conditions
occurred:
1. The LDC mnemonic specified in the route list does not
appear in the LOC list associated with the TCTTE.
2. The device type generated in the system LDC table for the
specified or implied Loe mnemonic is not the same as the
device type for the first LDC specified in the route
environment.
A symbolic storage definition of the user-supplied route list
is available on the source library (s) under the member name
DFHURLDS. This symbolic storage definition can be used as an
aid in building the route list, and if necessary, in testing
the status flag byte for each entry upon return from aDFHBMS
TYPE=ROOTE request that refers to a list. The symbolic base
register is URLBAR.
Chapter 4.3.
Basic Mapping Support
299
Checking the Response to a BMS Request (TYPE=CHECK)
The format of the DFHBMS TYPE=CHECK macro instruction is as follows:
r------.r-------'r----------------------------------------------------------,
I
DFHBMS
TYPE=CHECK
[,EOC=symbolic-address]
[,EODS=symbolic-address]
[ ,ERROR=symbolic-address]
[,IGREQID=symbolic-address]
[,INVET=symbolic-address]
[,INVLDC=symbolic-address]
[,INVMPSZ=symbolic-address]
[,INVREQ=symbolic-address]
[,KAPFAIL=symbolic-address]
[,NORESP=symbolic-address]
[,RETPAGE=symbolic-address]
[,RTEFAIL=symbolic-address]
[,RTESOME=symbolic-address]
[ , IGREQCD=symbolic-address ] ----->Assembler only
[,TSIOERR=symbolic-address]
where:
TYPE=CHECK
indicates that the BMS response to a request for BMS services
is to be checked.
Some response codes may appear in combination with other response
codes. These combinations are: RTEFAIL and INVET, and RTESOME and
INVET. The order used by BMS in checking for all conditions that the
application programmer specifies is as follows:
NORESP, TSIOERR,
INVREQ, RETPAGE, MAPFAIL, RTEFAIL, RTES03E, INVET, IGREQID, INVLDC,
INVMPSZ, EODS, EOC, and ERROR. Thus, if the application programmer has
specified INVET and RTEFAIL and both of these responses apply, BMS
transfers control to the user-written exception-handling routine
identified in the RTEFAIL operand. In this situation, the INVET operand
is not acted upon.
BMS Response Codes
To test a BMS response code the application programmer must know the
codes and their meanings. For this approach, the application programmer
can access the response code(s) at TCAMSRC1, TCAMSRC2, and TCAMSRC3.
The possible response codes and the conditions to which they correspond
are identified in the right-hand columns of Figure 4.3-4. DFHBMS
service requests for which the conditions are applicable are shown at
the left. The keywords are explained in detail at the end of this
chapter (see "Operands of DFHBMS Macros") •
300
CICS/VS APRM(ML)
i
1 DFHBMS
1 Service
1 Reguest
Condition
IROUTING,CHECK
1
(Normal
response)
1
Response Code
Response
Code
1----------------------------IAssemblerl COBOL
PL/I
Location
1---------------------------------------------------------------------1 INPUT ,OUTPUT, NORESP
LOW-VALUES 1000000001TCAMSRC1,
X'OO'
1
OUTPUT,CHECK
OUTPUT,CHECK
INPUT,CHECK
INPUT,CHECK
INPUT,OUTPUT,
CHECK
INPUT,CHECK
OUTPUT ,CHECK
OUTPUT,
ROUTING,CHECK
ROUTING,CHECK
ROUTING,CHECK
ROUTING,CHECK
INPUT,OUTPUT
ROUTING,CHECK
OUTPUT,CHECK
OUTPUT,CHECK
IUVREQ
X'Ol'
(Invalid
request)
RETPAGE
X'02'
(R eturn Page)
MAPFAIL
X'04'
(Mapping a ttempt failure)
EODS
X'04'
(End of data
set)
INVMPSZ
X'OS'
(Invalid map
size)
EOC
X'OS'
(End of
chain)
INVLDC
X' 10'
(In valid LDC
mnemonic)
IGREQID
X '10'
(Ignore REQID
specifica tion)
INVET
X'20'
(In valid error terminal)
RTE SOME
X'40'
(Routing to
only some
terminals)
RTEFAIL
X'80'
(Routing
failure)
See note
ERROR
(Any re sponse
other than
NORESP)
TSIOERR
X'80'
(Temporary
storage I/O
error)
IGREQCD
X'40'
(Request
change
direction
ignored)
12-1-9
12-2-9
12-4-9
1
1
ITCAMSRC2,and
1TCAMSRC3
1
1
100000001 TCAMSRCl
1
1
100000010 TCAMSRCl
1
00000100 TCAMSRCl
12-4-9
00000100 TCAMSRC3
12-8-9
00001000 TCAMSRC1
12-8-9
00001000 TCAMSRC3
12-11-1-8-9 00010000 TCAMSRC2
12-11-1-8-9 00010000 TCAMSRC3
11-0-1-8-9
00100000 TCAMSRC1
no punches
01000000 TCAMSRCl
12-0-1-8
10000000 TCAMSRC1
See note
See note TCAMSRC1,
TCAMSRC2,and
TCAMSRC3
12-0-1-8
10000000 TCAMSRC2
No punches
01000000 TCAMSRC2
Note: The test for the ERROR response is satisfied by a not~gual
condition; that is, not X'OO', not LOW-VALUES, or not 00000000 for
Assembler, COBOL, and PL/I, respectively.
Figure 4.3-4.
BMS Response Codes
Chapter 4.3.
Basic Mapping Support
301
The following examples show how to examine the response code provided
by BMS at TCAMSRC1,TC1MSRC2, and TCAMSRC3, and transfer control to the
appropriate user-written routine accordingly.
Por Assembler
ERROR
GOOD
DFHBMS
CLI
BNE
CLI
BNE
CLI
BE
DS
DFHPC
DS
Languag~:
TYPE=(TEXTBLD,STORE)
TCAMSRC1,X I OO I
ERROR
TCAMSRC2,X I OOI
ERROR
TCAMSRC3,X I OO'
GOOD
OH
TYPE=ABEND
OS
BUILD OUTPUT
ANY UNUSUAL CONDITIONS, TEST 1
•• YES, GO TERMINATE THE TASK
•• NO, ANY UNUSUAL CONDITIONS, TEST 2
•• YES, GO TERMINATE THE TASK
•• NO, ANY UNUSUAL CONDITIONS, TEST 3
•• NO, GO CONTINUE PROCESSING
YES, TERMINATE THE TASK
TERMINATE THE TASK
For COBOL:
DFHBMS TYPE=(TEXTBLD,STORE)
BUILD OUTPUT
IP TCAMSRCl NOT = I I THEN GO TO ERROR.
IP TCAMSRC2 NOT = I I THEN GO TO ERROR.
IF TCA!SRC3 = , , THEN GO TO GOOD.
ERROR.
DPHPC TYPB=ABEND
TERMINATE THE TASK
GOOD.
where the value specified within the single quotation marks is an
unprintable multipunch code for the required hexadecimal value.
Por PLII:
DPHBMS TYPE= (TEXTBLD ,STORE)
BUILD OUTPUT
IP TCAMSRC1 = 'OIB & TCAMSRC2 = 'OIB
& TCAMSRC3 = 10'B THEN GO TO GOOD;
ERROR:
DPHPC TYPE=ABEND
TERMINATE THE TASK
GOOD:
302
CICS/VS APRM (!L)
BMS Message Recovery
BMS provides message recovery for routed and non-routed messages.
recoverable, messages must satisfy the following requirements:
To be
•
The DPHBMS TYPE=STORE operand must have been specified on the BMS
output requests that built the logical message.
•
The BMS default REQID (**) or the specified REQID for the logical
message must have been identified to Temporary storage Program (via
the TST) as recoverable.
•
The task that built the message must have reached its logical end
of task.
G
The Temporary storage Program (TSP) and the Interval Control
Program (lCP) must also support recovery.
Terminal Code (TC) Table
A terminal code table is established within BMS for reference in
servicing BMS-supported terminals. There is one entry in this table for
each terminal supported under BMS. The terminal codes that appear in
the table are given in Pigure 4.3-5. This code appears in the list of
completed pages available at TCAMSRLA when the application programmer
has specified that pages of output be returned (that is, RETURN is the
disposition parameter in the output request). The code is available at
TCAMSRI1 when an invalid map size (INVMPSZ) response is returned.
Codg,
Character
A
B
C
D
E
P
G
H
I
J
K
L
!
P
Q
R
U
V
W
X
Y
pigure 4.3-5.
Terminal
~
CRLP or TRMTYPE=TCAM terminals
Magnetic Tape
Sequential Disk
TWX Model 33/35
1050
2140 Models 1 and 2 (Without Buffer Receive)
2141
2740 Model 2 (With Buffer Receive)
2110
2780
3180
3270 models with 40-column displays
3210 models with 80-column displays
Interactive LU P167, 3110 Interactive);
3790 Pull Punction LU; and SCS Printer LUs
(3210 and 3190)
2980 Models 1 and 2
2980 Model 4
3601
Host Conversational (3653)
3650 User Program
3650/3210 Host Conversational (3210)
Batch LU (3110 Batch), Batch Data
Interchange LU (3110, 3190, LUTYPE4)
BMS Terminal Code Table
Chapter 4.3.
Basic Mapping support
303
Standard Attribute List and Printer Control Characters (DFHBMSCA)
The application programmer can obtain a set of commonly used 3270 field
attributes and printer control characters by copying DFHBMSCA into his
program. For COBOL, this definition must be copied into the Working
storage Section. DFHBMSCA consists of a set of EQU statements in the
case of Assembler language, a set of 01 statements in the case of COBOL,
and DECLARE statements defining elementary character variables in the
case of PL/I. One possible use for DFHBMSCA is for the purpose of
temporarily changing attribute characters in a map.
The field attributes/printer control characters and corresponding
symbolic names are listed in Figure 4.3-6. These attributes cannot be
combined by the application programmer in any manner. If any
combinations other than those listed are required, the application
programmer must either use the ATTRB operand of the DFHMDF macro
instruction to obtain the desired combinations or generate new attribute
combinations offline.
Symbolic
Name
Field Attributel
Printer Control Character
DFHBMPEK
DFHBMPNL
DFHBMASK
DFHB8UNP
DFHBPlUNN
DFHBMPRO
DFHBMBRY
DFHB8DAR
DFHB8FSE
DFHB8PBF
DFHBMASF
DFHBMASB
3270 Printer end of message
3270 Printer new-line character
Autoskip
Unprotected
Unprotected and numeric
Protected
High intensity
Dark, nonprint
8DT on
Protected and MDT on
Autoskip and MDT on
Autoskip and high intensity
Figure 4.3-6.
3270 Field Attributes and Printer Control Characters
Standard Attention Identifier List (DFHAID)
To test the method of initiating an incoming READ from the 3270
Information Display System, the application programmer is provided with
a set of 3270 attention identifiers (single-character variables called
AIDs) that can be used to test the value at TCTTEAID. He can obtain
this set of attention identifiers by copying DFHAID into his program.
For COBOL, this definition must be copied into the Working Storage
Section.
DFHAID consists of a set of EQU statements in the case of Assemnler
language, a set of 01 statements in the case of COBOL, and DECLARE
statements defining elementary character variables in the case of PL/I.
The symbolic names for the attention identifiers and the corresponding
3270 functions are given in Figure 4.3-7.
304
CICS/VS APRM(8L)
Symbolic Name
3270 Function
DFHENTER
DFHCLEAR
DFHOPID
DFHPEN
DFHPA 1
DFHPA2
DPHPA3
DFHPF1
Enter key
Clear key
Operator Identification Card Reader
Immediately detectable field
PA 1 key
PA2 key
PA3 key
PP1 key
DFHPP24
Figure 4.3-7.
PF24 key
3270 Attention Identifiers and Functions
Programming Considerations for Paging Commands on Display Devices
The commands used by terminal operators to communicate with CICS/VS BMS
are collectively known as terDinal paging commands, or simply as paging
commands. They are defined by the system programmer through the DPHSIT
macro, which is described in the CICSLVS2yst~~~gra!!!!ru~r's-I!g!~g,
Manual. Their format and use are discussed in detail in the CICS/VS
Q.E.~rator's Guide.
The application programmer must be auare of the terminal paging
commands in order to write applications that involve terminal operators.
The use of BMS at map definition time and in executable programs can
have a significant effect on terminal operator procedures.
It is important to note that uhen in a page retrieval session, that
is, when using paging commands, all PA and PF keys are treated as paging
commands, regardless of whether or not they have been defined in the
SKRXXXX operand of the DFHSIT macro.
Cursor placement is an important consideration in programming for
paging commands. Any of the follouing items can cause a paging command
not to be the first data read by CICS/VS and therefore not to be
interpreted as a paging command.
•
After a print operation on a 3270 display, the cursor is set to
position zero. A paging command entered at this location is not
recognized unless the last position of the buffer contains an
attribute byte or the buffer has been cleared.
o
A field sent with DATA=ONLY and no attribute byte in the TIOA is
uritten into the buffer uithout an attribute byte. If the
application programmer places the cursor in this field and the
operator keys a paging command beginning at the cursor location,
the paging command is not recognized.
Since the field has no attribute byte, the hardware considers the
data to be an extension of the previously defined field. When the
operator keys into the middle of the hardware-recognized field and
presses the enter key, the field is transmitted from the beginning
of the previously defined field. The data at the beginning of the
field is examined for a paging command and responded to
accordingly.
Chapter 4.3.
Basic Mapping Support
305
•
306
Cursor specification in the DFHBMS macro instruction can adversely
affect operator action if the cursor is not set at the beginning of
a field. Paging commands entered at a cursor location that is not
the beginning of a field are not recognized by BMS because data
transmission starts at the beginning of the field if the field is
not set to nulls X'OO'.
CICS/VS APRM(ML)
Operands of DFHBMS Macros
CTRL=
PAGEBLD~XTBL~and
OUT Macros
In DFHBMS TYPE=PAGEBLD, TEXTBLD, and OUT macros, CTRL= is used
to specify device characteristics related to terminals of the
3270 Information Display System (including VTAM 3270 logical
units, 3650 host-conversational (3270) logical units, and 3790
(3270-displayand 3270-printer) logical units). CTRL=ALARM is
also valid for TeAM SDLC and VTAM-supported terminals (except
interactive and batch logical units), for which all other
parameters for CTRL are ignored. To be effective, this operand
must be 'specified in the DFHBMS TYPE=PAGEBLD macro that causes
a page of output to be completed, or in the DFBMDI macro for
the associated map, or in the DFBMSD macro for the associated
mapset. If the operand is specified in more than one of these
macros, the specification in a DFBBMS macro will override that
in a DFHMDI macro, which in turn overrides that in a DFHMSD
macro. If CTRL is not specified in a request for a 3270, an
appropriate WCC for the 3270 should be placed in TIOACLCR
before the request is issued. If this is not provided, the
default WCC will be used.
PRINT
must be specified if the printer is to be started; if
omitted, the data is sent to the printer buffer but is not
printed. This operand is ignored for 3270 displays without
printer features.
L40,L64,L80,HONEOM
are Llutually exclusive options that control the line length
on the printer. L40, L64, and L80 force a carrier
return/line feed after 40, 64, or 80 characters,
respectively. HONEOM causes the default printer line
length to be used.
FREEKB
specifies that the keyboard should be unlocked after this
map is written out. If omitted, the keyboard remains
locked; further data entry from the keyboard is inhibited
until thi s status is changed.
ALARM
activates the 3270 audible alarm feature. For TCAM and
VTAM terminals supporting function management headers
(FMHs) (except interactive and batch logical units), ALARM
signals BMS to set the alarm flag in the FMH.
Chapter 4.3.
Basic Mapping Support
307
FRSET
is valid only when mapping is used. FRSET indicates that
the modified data tags (MDTs) of all fields currently in
the 3270 buffer are to be reset to a not-modified condition
(that is, field reset) before any map data is written to
the buffer. This allows the DFHMDF ATTRB specification for
the requested map to control the final status of any fields
written or rewritten in response to a DFHBMS macro
instruction.
PAQ~QQ!
MaQro
In the DFHBMS TYPE=PAGEOUT macro, CTRL= specifies how pages are
to be displayed at the terminal (when the disposition is OUT or
STORE) and whether or not control is to be returned to the
application program.
PAGE
specifies that pages are to be paged one at a time to the
terminal. BMS writes the first page to the terminal when
the terminal becomes available or upon request of the
operator. All subsequent pages are written to the terminal
in response to a terminal operator request (see the
description of paging commands in the CICSIVS Operator's
Guide). If automatic paging was specified for the terminal
at system generation, this specification overrides the
automatic paging for this logical message. For TCAM SNA
and VTAM-supported terminals, PAGE applies to all LDC page
sets accumulated within the logical message.
AUTOPAGE
specifies that pages are to be paged automatically to the
terminal. BMS writes each page of the logical message to
the terminal when it becomes available. If paging upon
request was specified for the terminal at system
generation, this specification overrides it for this
logical message, provided that the terminal is not a 3270
video terminal (AUTOPAGE cannot be specified for a 3270
video terminal). For TCAM SNA and VTAM-supported
terminals, AUTOPAGE applies to all LDC page sets
accumulated in the logical message.
A specification of PAGE for 3284 or 3286 devices is ignored.
That is, AUTOPAGE is assumed for these devices. If neither
PAGE nor AUTOPAGE is specified, the paging status specified for
the terminal at system generation determines how pages are to
be written to the terminal. For TCAM SNA and VTAM-supported
terminals with LDC support, paging status for each LDC is
obtained from the system LDC table.
308
CICS/VS APRM(ML)
RETAIN
indicates that BHS is to return control to the application
program for further processing after it has written the
page(s) to the terminal and has received data other than a
purge, copy, or paging command from the operator.
RETAIN is intended to be used for a combination of page
display from the page file (logical message built using the.
STORE disposition) and operator data entry. BMS issues a
GET to the terminal after writing the appropriate pagels)
to the terminal. BtIS issues the GET only if the logical
message was built with STORE disposition.
If the logical
message lias not built l1ith STORE disposition, BMS returns
control to the appJ.ication program after the last page is
written to the terminal, and without issuing a GET to the
terminal.
The operator may enter any page, purge, or copy commands
that are valid for the particular message. Any other
entered data is passed back to the application program
after the current message is purged. The address of the
newly acguired TIOA is in TCTTEDA. A chaining command is
not valid at this point because it requests the creation of
a new task for the terminal to which a task is already
attached.
RELEASE
indicates that control is to be returned to the program at
the next higher logical level after BMS has written the
pagels) to the terminal. When RELEASE is specified, LAST
is assumed for TCAM SNA and VTAM-supported terminals,
except when the PAGEOUT is for a route operation.
Note:
To ensure that a logical message appears at the
receiving terminal at once, before any other transaction is
initiated from the terminal and before any other messages
that may have been routed to it, CTRL=RELEASE should be
specified.
If neither RETAIN nor RELEASE is specified, and STORE is the
disposition for the logical message, a new task is scheduled by
CICS/VS task control for uriting the pages to the terminal, and
control is returned to the application program at this time
rather than after the pages are written. After the application
program has terminated, the pages will be written to the
terminal in response to terminal operator reguests (see the
description of paging commands in the CICS/VS Operator's
Guigg).
If pages are being routed, a specification of either
RELEASE or RETAIN is ignored.
If messages are being chained, and the second transaction uses
BMS in paging mode, the use of RETAIN will prevent further
chaining.
RELEASE must be used to allow more than two
transactions to be chained together.
CURSOR=
is used to position the cursor upon completion of a write
operation to a 3270 device. This operand is valid in TYPE=OUT
macros only when maps are used.
Chapter 4.3.
Basic Mapping Support
309
number
is an integer indicating a particular position relative to
zero on the screen; the range of values that may be
specified depends upon the screen size of the 3210 being
used.
y~
indicates that a value indicating the desired cursor
position has been placed in TCABMSCP.
(Note, though, that
TCABMSCP may be used by CICS/VS for other purposes. The
user should not rely on the cursor position specification
remaining intact throughout a transaction.)
This operand overrides the IC option of the !TTRB operand of
the DFHMDF macro instruction, if it is specified in a macro
that completes a pagebuilding operation and thus causes a write
operation. Previous specifications' of the IC option and of the
CURSOR operand for the other maps making up the page are
ignored.
Similarly, a CURSOR operand on a later TEXTBLD macro always
overrides a CURSOR operand on an earlier TEXTBLD macro.
An alternate method may be used to dynamically position the
cursor on the output screen. This method is called symbolic
cursor positioning (SCP). SCP allows a field in the TIO! to be
marked, symbolically, such that the cursor is placed under the
first data byte of the field on the output screen.
Requirements for SCP use are as follows:
•
MODE=INOUT must be specified on the DFBMSD macro for maps
and DSECTs which will be used with SCP.
•
CURSOR=YES must be specified on the DFHBMS macro.
o
Field TCABMSCP must be initialized ~ith hexadecimal Fs; for
example, MVC TCABMSCP,=X'FFFF'.
(In COBOL move minus'one
into TCABMSCP which has been defined as PIC S9(4) COMP.)
•
The length field, suffix "L", associated with the field
under which the cursor is to be placed must be initialized
with hexadecimal Fs. For example, MVC FIELD3L,=X'FFFF'.
The remainder of the TIOA may be built as desired by the user.
SCP is operable only for devices which allow cursor placement
to be performed independent of data placement; for example,
3604 and 3210. SCP specification is ignored for other devices.
DATA=
indicates one of the following three output mapping data
selection modes.
specifies that only default data is to be written from the
selected map.
YES
specifies that data placed in the TIOA by the application
programmer is to be merged with default data from the map.
The user-supplied data and/or attribute character (3210
only) supplied for a given field replaces the corresponding
default data and/or attribute character from the map.
310
CICS/VS APRM(ML)
ONLY
specifies that only data placed in the TIO! by the
application programmer is to be uritten. The attribute
characters (3270 only) must be specified for each field in
the TIOA. Any default data or attributes from the map are
ignored.
This operand is valid only when mapping is used. If it is
omitted, DATA=NO is assumed. The first position of each field
in data placed in the TIOA by the application program must
contain a non-null character. A suitable replacement character
for a null character is a blank (XI401).
EOC=symbolic address
specifies the symbolic address of the routine to be given
control if the request/response unit (RU) is received, during a
BMS input operation, vith the end-of-chain indicator set. This
operand is used only for VTAM interactive and batch logical
units.
EODPURG=
specifies the manner in which CICS/VS deletes the current
message.
AUTO
specifies that CICS/VS is to delete the message
automatically if the operator enters a transaction that is
not a paging command. Alternatively, the operator may
delete the message uith a purge command (see the CICS/yS
oEe£~1Qrls_Guide) •
OPER
specifies that CICS/VS is not to delete the message until
the terminal operator explicitly requests deletion with a
purge command.
Note: If temporary storage is reinitialized, all messages are
lost, regardless of any other specifications.
EODS=symbolic address
indicates the label of a user-ffritten routine to receive
control if end-of-data-set (EODS) has been received during a
BMS input operation. If this condition occurs, no data has
been received (only a standalone function management header).
No data is mapped and TCTTEDA is set to zero. This operand
applies only to VTAM batch logical units.
ERROR=symbolic address
specifies the entry label of the user-written routine to which
control is passed if any of the response conditions except
NORESP occurs.
ERRTERM=
indicates the terminal to be notified if the message is purged
because it is undeliverable. The message number, title
identification, and destination of the message are indicated.
termid
is the terminal identification of the terminal to be
notified.
Chapter 4.3.
Basic Mapping Support
311
ORIG
indicates that the originating terminal is to be notified.
YES
indicates that the terminal identification of the terminal
to be notified has been placed in TCAMSTI prior to issuing
the DFHBMS TYPE=ROUTE macro instruction.
This operand is operative only if the PRGDLAY operand was
specified in the DFHSG PROGRAM=BMS macro instruction by the
system programmer. If PRGDLAY was not specified, this operand
has no effect.
FMHPARM=
specifies information to be included in a function management
header (FMH) being transmitted to a 3650 logical unit. Refer
to the CICS/VS 3650 Guide for details of the FMH and of 3650
logical units.
This operand applies only to VTAM-supported 3650 logical units
with outboard formatting. It specifies the name of the map to
be used with this BMS request.
parameter
specifies the eight-character name of the map.
YES
indicates that the map name has been stored in the eightcharacter TCAMSFMP field.
HEADER=
specifies that header data is to be placed at the beginning of
each output page and points to that data.
symbolic address
is the symbolic address of the header record that will be
used to place header information at the beginning of each
page.
YES
indicates that the application programmer has placed the
address of the header record in TCAMSHDR prior to issuing
this DFHBMS macro instruction.
If this operand is used in a DOS COBOL program, the label must
not be longer than eight characters.
The record pointed to by HEADER or TRAILER operands has the
following format:
I
I I I
I
ILLpIC<--------~Data------PPPpp--------------------------->1
I
,
I I I
where:
LL
is a two-byte field containing the length of the header or
trailer information.
~12
CICS/VS APRM(ML)
I
I
P
is a one-byte field containing a character of the userls
choice that indicates which, if any, are the embedded page
number positions in the data area. The character chosen
must, obviously, be one that does not otherwise appear in
the data area. The embedded page number positions will
initially contain this same character. The character must
not be any of the following, which are reserved: XIOCI,
X11s l , X1171, X126 1 , and XIPPI. If page-numbering is not
required, P should be set to blank (X'40 1 ).
C
is a reserved one-byte field.
Data and PPPPP
is the header or trailer information to be placed at the
beginning or end of each page of output. This information
consists of a constant character string with, optionally, a
page-number field of up to five characters embedded within
it.
The placement of the page-number field within the data area
is entirely at the user's choice. If such a field is
defined, BM5 will place the current page number in it for
each page built. The number is padded on the left with
zeros if it does not fill the defined field; it is
truncated on the left if it is too large for the defined
field.
Page numbering starts at 1 and can run up to
32,767. It is automatically reset to 1 after each DFHBMS
TYPE=PAGEOUT request or if the output disposition is
changed. The legibility of the code will be improved if
the page-number field is separated from the constant data
by blanks or other suitable characters, though such
separation is not required by BM5.
New-line characters (XI1SI) may be included in the constant
data if a multiple-line header or trailer is required.
IGREQCD=symbo1ic address
specifies the entry label of a user-written routine to which
control is passed if an output operation is attempted after a
signal command with a hard request change direction (RCD) code
(X I 000100001) has been received from an LUTYPE4 logical unit.
Applies to output operations only. Valid in assembler language
only.
IGREQID=symbolic address
specifies the entry label of a user-coded routine to which
control is to be passed if the prefix specified is different
from the established (via a previous specification or default)
REQID for this logical message.
INTRVAL=
specifies the interval of time after which data being routed to
the page file is to be transmitted to the terminal(s).
numeric value
is of the form HHMM55, where HB represents hours from 00 to
99, MM represents minutes fro~ 00 to 59, and 55 represents
seconds from 00 to 59.
Chapter 4.3.
Basic Mapping Support
313
YES
indicates that the interval of time has been placed in
packed decimal form (OHHMMSS+) in TCAMSRTI prior to issuing
the DPRBMS TYPE=ROUTE macro instruction.
INVET=symbolic address
specifies the entry label of the user-written routine to which
control is passed i f the terminal identification specified by
the ERRTERM operand of a DPHBMS TYPE=ROUTE macro instruction is
invalid or is assigned to a terminal of a type not supported
under BMS.
INVLDC=symbolic address
specifies the entry label of the user-written routine to which
control is passed if the LDC mnemonic specified by the LDC
operand does not appear in the LDC list associated with the
TCTTE.
INVMPSZ=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed i f (1) the specified map is too wide
for a receiving' terminal, or (2) OPLOW has been requested and
the specified map is too long for the receiving terminal. Upon
entry to the user-written routine, TCAMSRI1 contains a terminal
code that further identifies the receiving terminal (see
"Terminal Code (TC) Table," earlier in this chapter).
INVREQ=symbolic address
specifies the entry label of the user-written routine to which
control is passed if the request for BMS services is invalid.
This response may be caused by any of the following conditions:
•
Changing the disposition of a routed logical message prior
to its completion, through DFHBMS TYPE=PAGEOUT
•
Issuing a separate TYPE=TEXTBLD or TYPE=PAGEBLD request to
the direct (originating) terminal while in the process of
building a routed logical message
•
Mixing TYPE=TEXTBLD and TYPE=PAGEBLD requests when building
a logical message
•
Specifying NOEDIT with a TYPE=PAGEBLD or TYPE=TEITBLD
request
•
Specifying the TRAILER operand with TYPE=PAGEOUT when
terminating a logical message built using TYPE=PAGEBLD
requests
•
Issuing a DFHBMS request with DATA=YES or DATA=NO and
specifying a map with no field specifications
•
Issuing a DPHBMS request with TYPE=STORE from a CICS/VS
application program communicating with a host
conversational (3653) logical unit.
I JUSTIFY=
describes the pOSitioning of the text data.
314
CICS/VS APRM(ML)
FIRST
indicates that this TEXTBLD data is to be positioned at the
top of the page. Any partially formatted page from
preceding DFHBMS requests is considered to be complete. If
the HEADER operand is specified, the header precedes the
TEXTBLD data.
LAST
indicates that this TEXTBLD data is to be positioned at the
bottom of the page. If the TRAILER operand is specified,
the trailer appears after the TEXTBLD data. The page is
considered to be complete after the request is processed.
line number
indicates that this TEXTBLD data is to be positioned at
line nnn of the page.
YES
indicates that the application programmer has placed a
binary value from 1 to 255 in TCAMSJ prior to issuing this
DFHBMS TYPE=TEXTBLD macro instruction. A value in the
range from 1 through 240 represents a line number; 254
represents LAST; and 255 represents FIRST. The values from
241 through 253 are reserved and should not be specified.
LDC=
specifies the mnemonic to be used by CICS/VS to determine the
logical device code that is to be used for the BMS operation
and transmitted in the function management header (FMH) to the
logical unit. This operand is meaningful only for TCAM and
VTAM terminals with LDC support.
mnemonic
is the two-character mnemonic used to determine the
appropriate LDC numeric value. The mnemonic represents an
LDC entry in the DFHTCT TYPE=LDC macro instruction.
Chapter 4.3.
Basic Mapping Support
315
YES
indicates that the application program has placed the LDC
mnemonic in TCAMSLDM.
When an LDC is specified, BMS uses the device type, the page
size, and the page status associated with the LDC mnemonic to
format the message. These values are taken from the extended
local LDC table for the LU, if it has one. If the LU has only
a local (unextended) LDC table, the values are taken from the
system LDC table. The numeric value of the LDC is obtained
from the local LDC table, unless this is an unextended table
and the value is not specified, in which case it is taken from
the system table.
If the LDC operand of the DFHBMS macro is omitted, the LDC
mnemonic specified in the DFHMSD macro is used, (except in
TEXTBLD operations, when maps do not apply). If the LDC
operand has also been omitted from the DFHMSD macro, the action
depends on the type of the logical unit.
For a 3601 LU, the first entry in the local or extended local
LDC table is used, if there is one. If a default cannot be
obtained in this way, a null LDC numeric value (X'OO') is used.
The pagesize used is the value that was specified in the DFHTCT
TYPE=TERMINAL macro, or (1,40) if such a value was not
specified.
For a batch or batch data interchange LU, the local LDC table
is not used to supply a default LDC; instead, the message is
directed to the LU console ~hat is, to any medium that the LU
elects.to receive such messages. Note that for a batch data
interchange LU, this does not imply sending an LDC in an FMH) •
The pagesize is obtained in the manner described for the 3601
LU.
For DFHBMS TYPE=ROUTE operations, the LDC operand of the ROUTE
macro takes precedence over all other sources. If this operand
is omitted and a route list is specified (LIST=symbolic address
or YES), the LDC mnemonic in the route list is used; if the
route list contains no LDC mnemonic, or no route list is
specified, a default LDC is chosen as described above.
LIST=
specifies the terminals and/or operators to which paged data is
to be directed.
symbolic address
is the label of a list of terminals and/or operators to
which data is to be directed. If this parameter is used on
a DOS COBOL program the label must not be longer than eight
characters.
YES
indicates that the address of the list of terminals and/or
operators to which data is to be directed has been placed
in TCAMSRLA prior to issuing the DFHBMS TYPE=ROUTE macro
instruction.
ALL
indicates that all terminals supported by Bas are to
receive the paged data.
The list of destination terminals and/or operators consists of
16-byte entries as follows:
316
CICS/VS APRM(ML)
contents
1-4
contain a four-character (including trailing
blanks) terminal or logical unit identification,
or blanks
5-6
contain the two-character LDC mnemonic for TCAM
and VTAM-supported terminals with LDC support, or
blanks
7-9
contain the operator identification, or blanks
10
serve as a status flag for the route entry (see
"Status Flag Byte in User-Supplied Route List, II
earlier in this chapter.)
11-16
reserved; must contain blanks
The end of the list is designated as folIous:
Assembler:
COBOL:
PL/I:
DC
AL2 (-1)
PIC S9 (4) CaMP VALUE -1.
DECLARE FIXED BINARY (15) INITIAL (-1);
It may be necessary for the application program to supply this
list of destinations in noncontiguous areas called segments.
If the list is supplied in segments, every segment except the
last is terminated with ~t least) an eight-byte entry as
follows:
Bytes
Contents
1-2
Assembler:
COBOL:
PL/I:
DC AL2 (-2)
PIC S9(4) CaMP VALUE -2.
DECLARE FIXED BINARY (15) INITIAL (-2);
3-4
reserved
5-8
contain the chain address to the first entry of
the next segment
The end of the list is designated as described above for an
unsegmented list.
If, for any entry in the list,
1. The terminal identification is specified but the operator
identification is omitted, the data is routed to that
terminal without regard to operator identification.
2. The operator identification is specified but no terminal
identification is given, the data is routed to the 'first'
terminal at which the operator is signed on under the
specified operator identification. The 'first- is
determined by the physical location of the terminal entry
in the CICS/VS terminal control table. If no operator is
signed on under the specified operator identification when
the DFHBMS TYPE=ROUTE macro instruction is executed, the
route list entry is ignored.
Chapter 4.3.
Basic Mapping support
317
3. Both terminal identification and operator identification
are specified, the data is routed to that terminal.
For either 2 or 3 above, the data is displayed only if the
operator with the specified identification is signed on at the
terminal when the data is ready to be displayed, or when the
operator signs on after the data is ready to be displayed.
Entries of all three types may be included in one segmented or
unsegmented list.
It should be noted that the status flag in each route list
entry is used to notify the application program of certain
status conditions for that requested destination. Therefore,
if the route list is contained within the application program
and Bes alters the status flag, the application program can no
longer be considered reentrant.
MAP=
specifies the name of the map to be used when mapping formatted
pages.
map name
is the one- to seven-character name of the map within a map
set.
YES
indicates that the application programmer has placed the
name of the map in TCABMSMN prior to issuing this DFHBMS
macro instruction. The name must be left-justified and
padded with trailing blanks to eight characters.
Because map sets did not exist in pre-VS BMS, pre-VS
application programs will not specify a MAPSBT or MSBTADR
parameter. In this case, BMS takes the name specified in the
MAP operand as the name of the map set. It does not suffix
this name with a terminal type suffix, as described under the
DFHMSD macro instruction, because the concept of devicedependent map sets was also inapplicable in pre-VS BMS.
~:
MAPADR=
specifies the address of the map to be used when mapping
formatted pages. This operand is valid only when the map has
been coded within an assembler-language program.
symbolic address
is the one- to seven-character symbolic label that has been
assigned to the map.
YES
indicates that the application programmer has placed the
address of the map in TCABMSMA prior to issuing this DFHBMS
macro instruction.
If KAPADR is specified, MAP, MAPSET, and MSETADR should not be
used.
318
CICS/VS APRM(ML)
MAPFAIL=symbolic address
specifies the entry label of the user-written routine to which
control is passed if the data to be mapped has a length of zero
or does not contain a SBA (start buffer address) seguence.
This response can occur only if TYPE=IN or TYPE=MAP is
specified and data is mapped from a 3270 device. For TYPE=IN,
the address of the erroneous TIOA is available at TCTTEDA. For
TYPE=MAP, this address is wherever the user placed it prior to
the reguest (either in TCTTEDA or TCAMSIOA) •.
MAPSET=
specifies the name of the map set to be used in the mapping
operation.
map set name
is the one- to seven-character name of the map set.
YES
indica testhat the application programmer has placed the
name of the map set in TCAMSMSN prior to issuing the DFHBMS
macro instruction. The name must be left-justified and
padded with trailing blanks to eight characters.
The map set established by this operand must reside in the
CICS/VS program library, and a corresponding entry for the map
set must exist in the processing program table (PPT).
If MAPSET is coded, MAP must also be coded.
MSETADR=
specifies the address of the map set to be used in the mapping
operation. This operand is valid only when the map has been
coded within an assembler-language program.
symbolic address
is the one- to eight-character symbolic label that has been
assigned to the map set.
YES
indicates that the appli6ation programmer has placed the
address of the map set in TCAMSMSA prior to issuing this
DFHBMS macro instruction.
MAPSET and MSETADR are mutually exclusive operands.
is coded, MAP must also be coded.
If MSETADR
NORESP=symbolic address
specifies the entry label of the user-written routine to which
control is passed i f none of the other response conditions
~hether checked for or not) occurs.
NORESP signifies "normal
response."
OFLOw=symbolic address
specifies the symbolic address of a routine to which control is
to be transferred if the mapped data does not fit on the
current page ~ee "PAGEBLD Overflow Processing," earlier in
t his chap ter) •
OPCLASS=
specifies the operator class (es) to which data is to be routed.
Chapter 4.3.
Basic Mapping Support
319
decimal value, •••.
consists of one or more decimal values in the range from 1
through 24, separated by commas, specifically identifying
the operator class (es) •
YES
indicates that values identifying operator classes have
been placed in TCAKSOC (three-byte field) prior to issuing
the DFHBMS TYPE=ROUTE macro instruction.
A bit position corresponding to each value from 1 through 24 is
established in a three-byte field which is matched against the
three-byte operator class field in the CICS/VS terminal control
table terminal entry (TCTTEOCL) for a terminal. At least one
pair of corresponding bits must match in order for the message
to be routed to the terminal. The value in TCTTEOCL is set
during sign-on according to the OPCLASS operand of the DFRSNT
TYPE=ENTRY macro instruction specified by the system
programmer.
If data is to be routed to an operator class, the application
programmer may do one of the following:
1. Specify OPCLASS and omit LIST. Data is routed to each
terminal at which an operator is signed on with the
specified OPCLASS at the time the DFHBMS macro instruction
is issued.
2. Specify OPCLASS and LIST=ALL.
terminals.
Data is routed to all
In both cases, the data is not displayed on a terminal until an
operator is signed on with the specified OPCLASS. In general,
LIST=ALL is specified with OPCLASS only when it is anticipated
that someone will eventually sign on with the specified OPCLASS
at g~~ supported terminal.
If the application programmer specifies OPCLASS and
LIST=symbolic address, and the list contains operator
identifications, a specified operator identification overrides
OPCLASS for that entry.
320
CICS/VS APRM(ML)
PROPT=NLEOH
requests BMS to build a logical message specifically for a 3270
printer or a 3270 display with the Printer Adapter Feature. If
used, this operand must be specified in the first DFHBMS macro
for each logical message. If routing, this operand must be
specified on the TYPE=ROUTE request. Specification of this
operand overrides the CTRL operand, if present;
CTRL=(PRINT,HONEOM,FREEKB,PRESET) is assumed.
specification of this operand will cause the page to be
formatted using new line (NL) characters as for the other hard
copy devices. An end-of-message (EM) character is placed at
the end of the data. As the data is printed, a new line
character causes printing to continue on the next line. The
end-of-message character terminates printing. The next print
operation will start on a new line.
The following restrictions apply when using this parameter:
Buffer updating and attribute modification of fields previously
written into the buffer are not allowed. BMS issues an ERASE
with every write to the terminal.
When building a logical message, BHS will insert a new line
(NL) character at the end of each line and an end-of-message
(EM) character at the end of the text. Each NL and the EM
character occupies a 3270 buffer position; therefore, to avoid
possible wrap-around due to excessive data in the buffer, the
PGESIZE values defined in the DFHTCT system macro should be
such that the remainder of the 3270 buffer will contain these
additional characters.
This operand is ignored if the direct or a routing terminal is
not a 3270 printer or display with the Printer Adapter Feature.
RDATT=
specifies the address of a routine to receive control if the
operator presses the ATTN key on a 2741 when input is being
entered from the terminal in response to a DFHBMS TYPE=IN
request. This operand can be specified only if 2741 Read
Attention support, an option available under either CICS/DOS/VS
or CICS/OS/VS, has been generated into the system (see "2741
Read Attention and write Break Support .. in Chapter 4.2) •
REQID=
specifies the prefix to be used with the temporary storage
identification. The identification (including the prefix) is
used by CICS/VS when attempting message recovery.
BMS message recovery is provided for a logical message only if
the STORE operand is specified in the BHS output request and if
the logical end of task has been reached.
Only one prefix can be specified for each logical message. If
the REQID operand is not specified, CICS/VS assigns the prefix
** (two asterisks).
prefix
indicates the alphanumeric prefix to be used as the first
two characters of a temporary storage identification.
Chapter 4.3.
Basic Mapping Support
321
YES
indicates that the prefix has been stored at
TCA~SRID.
RETPAGE=symbolic address
specifies the entry label of the user-written routine to which
control is passed if one or more completed pages are returned
to the application program. This response can occur only if
TYPE=RETURN is specified in the DFHB~S macro instruction (see
the description of TYPE=RETURN for further information).
RTEFAIL=symbolic address
specifies the entry label of the user-written routine to which
control is passed if a DFHBMS TYPE=ROUTE request results in a
null routing environment (that is, the message will be sent, by
default, to only the originating terminal).
(To determine why
route list entries were skipped, refer to "status Flag Byte in
User-Supplied Route List", earlier in this chapter.)
RTESOME=symbolic address
specifies the entry label of the user-written routine to which
control is passed if (1) some of the entries in the userspecified route list named in the LIST operand of a DFHBMS
TYPE=ROUTE macro instruction are excluded from the routing
environment, or (2) LIST=ALL is specified and not all of the
entries in the terminal control table are included in the
routing environment.
(To determine why some route list entries
were skipped, refer to "Status Flag Byte in User-Supplied Route
List", earlier in this chapter.)
TIME=
specifies the time of day at which data being routed to the
page file is to be transmitted to the terminal(s).
numeric value
is of the form HHMMSS, where HH represents hours from 00 to
99, MM represents minutes from 00 to 59, and SS represents
seconds from 00 to 59.
YES
indicates that the time of day has been placed in packed
decimal form (OHH~MSS+) in TCAMSRTI prior to issuing the
DFHBMS TYPE=ROUTE macro instruction.
TITLE=
specifies the symbolic address of a record that contains a
title to be associated with the logical message created under
this routing environment.
symbolic address
is the symbolic address of the title length field that
precedes the title in the title record. If this parameter
is used in a DOS COBOL program the label must not be longer
than eight characters.
322
CICS/VS APRB(ML)
YES
indicates that the address of the title length field in the
title record has been placed in TCAMSTA prior to issuing
the DFHBMS TYPE=ROUTE macro instruction.
The title pointed to by the TITLE operand is displayed with the
logical message ID when the terminal paging query command is
entered (see the CICS/VS Operator1s Guide). This title serves
as an additional message identifier, displayed upon request
with the message ID, not on the logical message. The value in
the two~byte length field preceding the title includes the
bytes used for the length field. The length field and title,
in total, may be up to 64 bytes long. For example:
IX'001AI
IMONTHLY~INVENTORY~REPORTI
I
I
2-byte
length
field
24-byte
title field
TRAILER=
specifies that user-defined trailer data is to be placed at the
foot of each page completed by the TEXTBLDmacro in which the
operand is coded, or at the foot of the last page if the
operand appears on a PAGEOUT macro. The operand is ignored if
no page is completed by the macro in which it appears. The
operand is invalid in a PAGEOUT macro that is completing a
message built using PAGEBLD macros; if TRAILER= is used in such
circumstances, BMS returns an INVREQ return code.
The format of trailer data is the same as that for header data,
described above (see "HEADER="). Page numbering can be
accomplished automatically, as with header data.
symbolic address
is the symbolic address of the trailer record that will be
used to place trailer data at the bottom of the last page.
If this parameter is used in a DOS COBOL program, the label
must not be longer than eight characters.
YES
indicates that the application programmer has placed the
address of the trailer record in TCAMSTRL prior to issuing
this DFHBMS macro instruction.
TRANSID=transaction code
specifies a one- to four-character transaction identification
to be used with the next input message entered from the
terminal to which this task is attached.
This operand is valid only when CTRL=RELEASE is specified.
TSIOERR=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an unrecoverable temporary storage
input/output error occurs.
Chapter 4.3.
Basic Mapping Support
323
TYPE=
The following TYPE= parameters distinguish
with distinct purposes. As such, they are
operands and so described in this section;
explained individually in earlier sections
CHECK
IN
MAP
PAGEBLD
macro instructions
not treated as
instead, they are
in this chapter.
PAGE OUT
PURGE
ROUTE
TEXTBLD
The SAVE and TEXT parameters have special meaning for TYPE=IN
~oth) and TYPE=MAP (SAVE only) macros, and are described with
the individual macros.
The following four TYPE= parameters indicate the disposition of
output data:
OUT
indicates that the output is to be written to the
originating terminal when the page is complete.
Once a DFHBMS macro with OUT disposition has been issued,
the application program must not issue a DFHSC
TYPE=FREEMAIN,RELEASE=ALL macro until either a DFHBMS
TYPE=PAGEOUT or DFHBMS TYPE=PURGE macro has been issued.
When the OUT parameter is not preceded by either PAGEBLD or
TEXTBLD, it effectively distinguishes a macro with a
different purpose. This usage is described earlier in this
chapter under the heading "Direct Output (TYPE=OUT)."
RETURN
indicates that the complete pagels) is to be returned to
the application programmer.
(See "Handling Returned
Pages," earlier, for further information.) The application
program regains control (1) immediately following the BMS
instruction if the current page is not yet completed, or
(2) at an alternative entry point specified through the
RETPAGE operand of this macro instruction if one or more
pages have been completed.
STORE
indicates that the output is to be placed in temporary
storage to be displayed in response to paging commands
entered by the terminal operator (for more information
about these commands, see the CICSLVS QEg£B1Q£~§_2uide) •
If STORE is specified with a REQID that is defined in the
Temporary Storage Table (TST), CICSjVS provides message
recovery for logical messages if the task has reached
logical end. The CICSjVS Temporary Storage facility is
needed to hold messages awaiting delivery to terminals.
WAIT
indicates that BMS is to wait until all output operations
are complete before returning control to the application
program. WAIT must be specified uith every output request
except the following:
324
CICS/VS APRM(aL)
The last output request prior to task termination
The last output request prior to an input operation
The last output request prior to issuing a DFHBMS
TYPE=PAGEOUT macro instruction that precedes task
termination or an input operation
If no disposition is specified, the output is sent to the
originating terminal. Once the disposition has been
established for a logical message, it is not necessary to
repeat the disposition for that logical message. Any change of
disposition specified while in the process of building a
logical message forces that logical message to completion with
its original disposition. Then a new logical message is
started vith a nev disposition. The disposition parameter is
handled differently under DFHBMS TYPE=ROUTE (see "Disposition
and !essage Routing").
The remaining TYPE= parameters are:
ERASB
specifies that a 3270 buffer or 3604 screen is to be erased
before this page of output is displayed. A printer buffer
will contain meaningless data from prior messages if all
positions are not filled vith current data. The first
output operation in any transaction, or in a series of
pseudo-conversational transactions, should alvays specify
BRASB. For transactions attached to 3278 screens, this
will also ensure that the correct screen size is selected
as defined for the transaction in the PCT.
BRASBAUP
specifies that all unprotected character locations in a
3270 buffer are to be erased before this page of output
data is displayed. There are no further effects of
specifying this parameter.
LAST
signals to CICS/VS that this is the last output for a
transaction and, therefore, the end of a bracket operation.
This operand is meaningful only for TCAM SNA terminals and
for VTAM-supported terminals and is applicable only when
OUT is the specified disposition. For TCAM, an indicator
is set in the communication control byte (CCB) requesting
that the message handler send end-of-bracket.
ROBDIT
specifies that CICS/VS need not insert device-dependent
control characters ~arrier return, line feed, idle
characters, and so on) into the output data stream. The
application program, therefore, assumes responsibility for
providing any required control characters. This parameter
is ignored for all output operations specifying maps. This
parameter cannot be uSed vith 3601 devices.
SIVE
specifies that the user-supplied data area addressed by
TCTTBDA or TCAMSIOA is to be saved. The location
containing the address of the data area viII be changed by
B!S, so the address should be stored elsewhere before
issuing the macro.
Chapter 4.3.
Basic Mapping Support
325
WRBB~=
is used to specify the action that is to occur i f the ATTN key
on a 2741 is pressed while data is being written to the
terminal.
symbolic address
specifies the symbolic address of the routine to receive
control when the ATTN key on a 2741 is pressed during the
actual write to the terminal. This operand is operative
when 2741 write Break support has been generated into
CICS/VS (available only under OS/VS) and when the task
would normally have regained control. It is not valid on
B!S macros where TYPE=STORE or TYPE=RETURN is specified, or
on a PAGEOUT macro when CTRL=BELEASE is specified.
CURRENT
specifies that transmission of the current page to the
terminal is to cease, but, if autopaging has been
requested, transmission of the next page ~f any) begins.
ALL
specifies that transmission of the current page to the
terminal is to cease and that no additional pages are to be
transmitted. The logical message is purged.
Both CURRENT and ALL are meaningful only if 2741 Write Break
support has been generated into CICS/VS ~vailable only under
OS/VS), and if TYPE=STORE was specified in preceding DPBB!S
requests, or data has been sent to terminals other than the
originating terminal. In these cases, data has been placed in
temporary storage and is being displayed by a program other
than the one associated with the originating terminal.
326
CICS/VS APR8(8L)
Chapter 4.4. Batch Data Interchange (DFHDI Macro Instruction)
The CICS Batch Data Interchange program provides for communication
between an application program and a named data set (or destination) or
a selected output medium. Tbe named data set (or destination) must be
part of a batch data interchange logical unit in an outboard controller;
the selected output medium must be part of either such a logical unit or
an LUTYPE4. The term "outboard controller" is a generalized reference
to a programmable subsystem, such as the IBK 3770 Data Communication
system or the IBM 3790 Data Communication System, which uses SMA
protocols.
(Details of SNA protocols and the data sets that can be used
are given in the CICSt'S 3767, 3770 and 6610 Guide and the CICStVS 3790
§uide. )
The batch data interchange macro instruction (DFHDI) is used to
specify ADD, ERASE, REPLACE, QUERY, END, ABORT, SEND, RECEIVE, and CHECK
operations on data sets in an outboard controller. Where the controller
is an LUTYPE4 logical unit, only the END, ABORT, SEND, RECEIVE and CHECK
operations are supported.
The DPHDI macro instruction can be used only with assembler language
application programs. It is not available for COBOL or PL/I programs,
which must use the command level interface if they require these
facilities.
Addition of Records to a Data Set (TYPE=ADD)
The format of the DPHDI macro instruction to add records to a data set
is as follows:
r------~-------r--------------------------------------------------------~
DFHDI
TYPE= (ADD[ , {SAVE INOSAVB} ][, {WAIT INOWAIT} ])
,DNADDR={symbolic addresslYES}
[,NUMREC={integerIYBS} ]
[ ,DEFRBSP=YBS]
[,VOLADDR={symbolic addresslYES}]
[,NORBSP=symbolic address]
[,FUNCBRR=symbolic address]
[,SELNBRR=symbolic address]
[,UNEXPIN=symbolic address]
This macro specifies that a record in the current TIOA, as indicated
by the TCTTBDA, is to be added to the sequential or keyed direct data
set corresponding to the destination name specified in the DNADDR
operand.
The SA VB parameter specifies that the contents of the TIOA is to be
saved; however, there is no guarantee that TCTTBDl viII remain
unchanged.
The WAIT parameter indicates that task activity is to be suspended
until the DFHDI macro has been executed.
Chapter 4.4.
Batch Data Interchange (DFHDI Macro Instruction)
327
Deletion of Records from a Data Set (TYPE=ERASE)
The format of the DFHDI macro instruction to delete records from a data
set is as follows:
DFHDI
TYPE= (BRASE[ , {WAIT I NOWAIT} ])
,DNADDR={symbolic addresslYES}
{,KEYADDR={symbolic addresslYBS} I,RBNADDR=
{record-idIYES}}
[,DEFRESP=YES]
[,VOLADDB={symbolic addressIYES}]
[,NORESP=symbolic address]
[,FUNCERR=symbolic address]
[,SELNERR=symbolic address]
[,UNEXPIN=symbolic address]
This macro specifies that a record, identified by the KEYADDR or
RRNADDR operand, is to be deleted from the keyed direct data set
corresponding to the destination name specified in the DNADDR operand.
The WAIT parameter indicates that task activity is to be suspended
until the DFHDI macro has been executed.
328
CICS/VS APR!(!L)
Replacement of Records in a Data Set (TYPE=REPLACE)
The format of the DFHDI macro instruction to replace records in a data
set is as follows:
DFHDI
TYPE=(REPLACE[ ,SAVEINOSAVE}][, {WAITINOWAIT}])
,DNADDR={symbolic addresslYES}
{,KEYADDR={symbolic addresslYES} I,RRNADDR=
{record-idIYES}}
[,NUMREC={integerIYES} ]
[ ,DEFRESP=YES]
[,VOLADDR={symbolic addressIYES}]
[,NORESP=symbolic address]
[,FUNCERR=symbolic address]
[,SBLNERR=symbolic address]
[ ,UNEXPIN=symbolic address]
This macro specifies that a record identified by the RRNADDR xor
KEYADDR operand, in the current TIOA, is to replace a record in the
addressed direct data set corresponding to the destination name
specified in the DNADDR operand.
Where more than one record is to be replaced, the second and
subsequent records are replaced consecutively, starting with the one
specified in the RRNADDR or KBYADDR operand. The number of records to
be replaced is specified in the NUMREC operand.
The SAVE parameter specifies that the contents of the TIOA are to be
saved; however, there is no guarantee that TCTTEDA will remain
unchanged.
The WAIT parameter indicates that task activity is to be suspended
until the DFHDI macro has bean executed.
Chapter 4.4.
Batch Data Interchange (DFHDI ftacro Instruction)
329
Interrogation of Data Set {TYPE=QUERY} ,
The format of the DFHDI macro to interrogate a data set is as follows:
DFRDI
TYPE=QUERY
,DNADDR={symbolic addresslYES}
[,VOLADDR={symbolic addressIYES}]
[,NORESP=symbolic address]
[,FUNCERR=symbolic address]
[,SELNERR=symbolic address]
[,UNEXPIN=symbolic address]
This macro specifies that the name of the data set corresponding to
the destination name specified in the DNADDR operand is to be solicited
to allow the outboard batch program to transmit the data set to the
host. The program must issue input requests to receive the records fro.
the data set.
Termination of Operations on a Data Set (TYPE=END)
The format of the DFHDI macro to terminate operations on a data set is
as follows:
r------·r-------·~--------------------------------------------------------,
DFBDI
TYPE=END
{{,DNADDR={symbolic addressIYES}}
I {,SELECT={(CONSOLEIPRINTICARDIWPMEDIA1IWPMEDI121
WPMEDIA3tWPMEDIA4[,nn]) tYES}}}
[,VOLADDR={symbolic addresslYES}]
[,NORESP=symbolic address]
[,FUNCERR=symbolic address]
[,SELNERR=symbolic address]
[,UNEXPIN=symbolic address]
This macro specifies that operations on a data set are to be
terminated normally. The current outboard destination is de-selected
normally.
330
CICS/VS APRM(KL)
Abnormal Termination of Operations on a Data Set (TYPE=ABORT)
The format of the DFHDI macro to terminate operations abnormally is as
follows:
DFHDI
TYPE=ABORT
{{,DNADDR={symbolic addressIYES}}
I {,SELECT={(CONSOLEIPRINTICARDIWPMEDIA1IWPMEDIA21
WPMEDIA3IWPMEDIA4[,nn]) IYES}}}
[,VOLADDR={symbolic addressIYES}]
[,NORESP=symbolic address]
[,FUNCERR=symbolic address]
[,SELNERR=symbolic address]
[,UNEXPIN=symbolic address]
This macro specifies that operations on a data set are to be
terminated abnormally. The current outboard destination is de-selected
abnormally.
Transmission of Data from Host to Output Devices (TYPE=SEND)
The format of the DFHDI macro instruction to send data to an output
device controlled by a logical unit is as follows:
DFHDI
TYPE= (SEND( , {SAVE I NOSAVE} ][ , {WAIT I NOWAIT} ])
{{,DNADDR={symbolic addressIYES}}
I {,SELECT={(CONSOLEIPRINTICARDIWPMEDIA1IWPMEDIA21
WPMEDIA3IWPMEDIA4[,nn]) IYES}}}
(,VOLADDR={symbolic addressIYES}]
[ , DEFRESP=YES ]
( ,FUNCERR=symbolic address]
[,SELNERR=symoolic address)
(,UNEXPIN=symbolic address)
[,NORESP=symbolic address)
Data for an output medium is transmitted to the logical unit from the
TIOA, as indicated by the TCTTEDA. The SAVE parameter indicates that
the TIOA is to be saved; however, there is no guarantee that TCTTEDl
will remain unchanged.
The WAIT parameter indicates that task activity is to be suspended
until the previous DFHDI macro has been executed.
Chapter 4.4.
Batch Data Interchange
~FHDI
Macro Instruction)
331
Transmission of Data from Data Set to Host (TYPE = RECEIVE)
The format of the DFHDI macro to enable the host to accept records is as
follows:
DFHDI
TYPE= (RECEIVE[ , {SAVE I NOSAVE} ])
[,NORESP=symbolic address]
[,EODS=symbolic address]
[,DSSTAT=symbolic address]
[,UNEXPIN=symbolic address]
This macro specifies that DPHTC TYPE=READ macro instructions are to
be generated to obtain records from the inbound data stream. These
records are returned to the application program in a TIOA addressad by
TCTTEDA. The number of records returned by the TYPE=READ macro depends
upon whether the chain assembly or logical read options have been
specified by the system programmer, which in turn depend upon the data
format transmitted by the outboard controller.
When an FKH is encountered it is removed from the data stream and a
response code is set to inform the application program of the change in
destination selection status (see "Response Codes" later in this
chapter).
When the FKH is for BEGIN or RESUME DESTINATIONi and no data is
obtained from the READ, a further READ is issued so that the request can
complete with user data.
When the FKH is for SUSPEND, END or ABORT destination, the data, if
present, is presented first to the application program .with a normal
response code; on the next request, the appropriate response code is
set. The response code indicating the change of destination status is
presented to the application program with no user data. If a name was
sent, TCADIDNA is set, on completion of each request, to point to a
field describing the host destination as a one byte length field
followed by the destination name. If no destination name was sent, the
field TCADISEL is set to the medium and sub-address sent. For
descriptions of the formats and codes used, see the desciption of the
SELECT operand later in this chapter.
When reading from multiple data sets on an LUTYPE4, the DSSTAT
condition will be raised by any attempted read after an end-of-data-set
FKH has been received. The condition indicates that the logical unit
has currently no more data to send.
The SAVE operand specifies that the contents of the TIOA are to be
saved; however, there is guarantee that the TCTTEDA will remain
unchanged.
332
CICS/VS APRK(ML)
Obtaining the Relative Record Number of Next Record (TYPE=NOTE)
The format of the DPHDI macro to return the relative record number of
the next record is as follows:
r------r-------r----------------------------------------------------------,
I
I
I
I
I
I
I
I
I
I
DFHDI I TYPE=NOTE
I ,DNADDR={symbo1ic addresslYES}
I [,VOLADDR={symbo1ic addressIYES}]
I [,NORESP=symbolic address]
I [ ,PUNCERR=symbo1ic address]
I [,SELNERR=symbolic address]
I [,UNEXPIN=symbolic address]
I
~,----------------------~--------------------------------~
,
This macro specifies that the relative record number of the position
in the data set of the next available record is to be returned to the
application program in a fullword field whose address is placed in the
TCA at TCADIRNA after execution of the macro. The outboard destination
is a user-defined addressed direct data set.
Suspension of Execution of Task (TYPE=WAIT)
The format of the DPHDI macro to suspend the execution of a task is as
follows:
r------r-
.r----------------------------------------------------------,
I
I
I DFHDI I TYPE=WAIT
I,
IL__________________________________________________________
~
This macro specifies that task activity is to be suspended until the
previous DFHDI macro has been executed. This macro is meaningful only
following a DPHDI TYPE=ADD, TYPE=ERASE, TYPE=REPLACE or TYPE=SEND.
Chapter 4.4.
Batch Data Interchange (DPHDI Macro Instruction)
333
Testing Response to a Request for Data Interchange Services (TYPE = CHECK)
The format of the DFHDI macro to test the response code for a request
for data interchange services is as follows:
DFHDI
TYPE=CHECK
[,NORESP=symbolic address]
[,EODS=symbolic address]
[,DSSTAT=symbolic address]
[,FUNCERR=symbolic address]
[,SELNERR=symbolic address]
[,UNEXPIN=symbolic address]
This macro specifies that the
macro is to be tested and, where
written routine whose address is
operands: NORESP, EODS, DSSTAT,
334
CICS/VS APRM(ML)
response code from the previous DFHDI
necessary, a branch made to the userspecified in one of the following
FUNCERR, SBLNERR, or UBEIIN.
Batch Data Interchange Response Codes
Response codes are grouped into categories according to the operands.
Each category is given a code, for example NORESP has category code
X'OO' which is placed in field TCADIRC1 in the TCA. Each category is
subdivided into response codes that indicate the success or failure of a
specified operation, for example "End destination Fr!H received" in
category X'04 1 is 11. These response codes are placed in field TCIDIRC2
in the TCA.
The categories, operands, response codes and their causes are shown
in Figure 4.4-1.
r----------~------------~-----------------------------------~--------~
category
Operand
Condition
X'OO'
RORBSP
Successful
Begin destination FHH received
Resume destination FMH received
X'04'
DSSTAT,EODS
End destination FHH received
I
Suspend destination FMH received
Abort destination FMH received
Currently no data to send
X'OS'
FUHCERR
Request invalid for data set
organization
Record too long
Data set full
Invalid keyvord or record
identifier
Resource not available
Invalid NUMREC
Insufficient resource
Request for change direction
(RCD) signalled
Transient Data error during
logging
X'OC •
X' 10'
SBLNERR
UNEXPIN
Figure 4.4-1.
Chapter 4.4.
Response
Codg
00
01
02
r
Data set not found
Destination does not exist
Media not supported'
Invalid destination name
Transient Data error during
logging
Unexpected sense
Unexpected FMB
Unsupported input
11
12
13
15
21
22
23
24
25
26
2S
2B
60
r
I
I
I
I
I
I
29
41
43
44
60
r
I
I
I,
F1
F2
F3
Batch Data Interchange Response Codes
Batch Data Interchange (DFHDI Macro Instruction)
335
Operands of DFHDI Macro
DEPRESP=YES
All DPHTC TYPE=WRITE macros issued as a result of the current
invocation of DPHDI will request a definite response from the
outboard patch program, irrespective of the specification of
message integrity for the CICS/VS task.
DNADDR=
specifies the name of an outboard destination. If a
destination with a different name is currently selected, it is
de-se1ected before this one is selected. If the current
destination is being re-specified then no selection is
performed. This operand cannot be used with the SELECT
operand.
symbolic-address
is the address of a field defining the destination name.
This field consists of a one byte name length followed by
the name itself.
YES
indicates that the application program has set this address
into the word field TCADIDNA. The current implementation
gives a maximum length of 8 characters for the destination
name.
DSSTAT=srmbolic address
specifies the entry label of the user-vritten routine to which
control is passed when testing of the return code indicates a
discontinuity in the inbound data stream. Return codes are
described earlier in this chapter.
EODS=symbolic address
specifies the entry label of the user-written routine to which
control is passed when testing of the response code indicates
the end of the data stream. Return codes are described earlier
in this chapter.
PUNCERR=symbo1ic address
specifies the entry label of the user-written routine to which
control is passed when testing of the return code indicates a
function error. Return codes are described earlier in this
chapter.
KEYADDR=
This identifies a record of a keyed direct data set.
symbolic address
specifies the address of a field defining the primary key
of the record in a keyed direct data set to be erased.
This field consists of a one byte key length followed by
the key itself.
336
CICS/VS APR! (!L)
YES
indicates that the application has set this address into
fullword TCADIKYA. The current implementation gives a
maximum length of 24 characters for the record key.
Note: This operand is not required when adding records to a
3790 keyed direct data set as the key value is embedded in the
data specified by the DATA operand.
See 3790 Host System Programmer's Guide for a specification of
valid keys.
HUMREC=
specifies the number of records affected by the current
request. The 3790 will accept values greater than 1 only for
the REPLACE operation on an addressed direct data set. The
value is not meaningful to CICS/VS but is conveyed to the
outboard batch program as part of the function selection
information. Records are replaced sequentially starting with
the one identified by the RRNADDR operand.
integer
specifies the number of records, in the range 1 thru 255,
that are to be replaced.
YES
specifies that the application has set the binary value
into the one byte field TCADINRS. If omitted this operand
defaults to the value 1.
NORESP=symbolic address
specifies the entry label of the user-written routine to which
control is passed when testing of the return code indicates
normal response, that is, no errors have occurred during the
processing specified by a DPHDI macro. Return codes are
described earlier in this chapter.
RRNADDR=
identifies a record of an addressed direct data set for the
function REPLACE.
record-id
is the address of a one word field containing the relative
record number of the record being replaced.
YES
indicates that the application has set this address into
the full word TCADIRNA.
Note:
Record identifiers begin with the value 1.
SELECT=
specifies the type of output medium for the function SEND.
This operand cannot be used with the DNADDR operand.
CONSOLE
specifies the medium provided for messages to the operator.
PRINT
specifies a printer.
Chapter 4.4.
Batch Data Interchange (DPHDI Macro Instruction)
337
CARD
specifies a card reader/punch.
iPMEDIA1 through WP!EDIA4
specify, respectively, word processing media 1, 2, 3 and 4.
nn
specifies a medium sUb-address in the range 00 to 15, where
15 means any available subaddress. The default is 00.
YES
specifies the medium code and sub-address have been placed
in the one.-byte field TCADISEL by the application program.
The first half of this field must contain a hexadecimal
code indicating the type of medium, as shown below. The
second half must contain the hexadecimal value of the subaddress (X'OO' through X'1S').
Code
Meaning
X'OO'
X' 20'
X '30'
X'SO'
X'90'
X'lO'
X'CO'
CONSOLE
CARD
PRINT
WP!EDIA1
WPl'lEDIA2
WPl'lEDIA3
WPl'lEDIA4
SELNERR=symbolic address
specifies the entry label of the user-written routine to which
control is passed when testing of the return code indicates
errors during destination selection. Return codes are
described earlier in this chapter.
UNEXPIN=symbolic address
specifies the entry label of the user-written routine to which
control is passed when testing of the return code indicates
that unexpected or unrecognizable input or response is received
in reply to a DFHDI macro. Return codes are described earlier
in this chapter.
VOLADDR=
specifies, for the 3110 programmable subsystem only, the name
of the diskette volume containing the data set named in the
DNADDR operand. This name is used to qualify the data set name
for destination selection. Subsequent specifications of the
same data set name without a diskette volume name, or with a
different diskette volume name, will cause a new destination to
be selected. In the former case, all mounted diskette volumes
will be searched for the data set named in the DNADDR operand.
symbolic address
specifies the address of the field defining the diskette
volume name (to a maximum of six characters). The field
consists of a one-byte name length followed by the name
itself.
YES
indicates that the application program has set this address
into the fullword field TC1DIVNA.
338
CICS/VS APRM(l'lL)
Part 5. Control Operations
339
Chapter 5.1. Introduction to Control Operations
This part of the manual describes the CICS/VS macro instructions that
control the execution of tasks within a CICS/VS system. The macros are
associated with appropriate control programs and the specification of
the various TYPE= operands invokes a range of operations.
The control programs and the macro instructions associated with each
are as follows:
•
Interval Control Program (DFHIC Macro). This macro specifies
operations that depend on the time of day and can have nine types
of operations associated with it: GETIMB, WAIT, POST, INITIATE,
PUT, GET, CANCEL, RETRY, and CHECK. These operations are described
in Chapter 5.2.
•
Task Control Program (DFHKC Macro). This macro specifies
operations that affect task activity or the control of resources.
It can have eight types of operation associated with it: ATTACH,
SCHEDULE, CHAP, WAIT, ENQ, DEQ, PURGE, and NOPURGE. These
operations are described in Chapter 5.3.
•
Program Control Program (DFHPC ~acro). This macro specifies
operations that affect the flow of control between application
programs. It can have ten types of operation associated with it:
LINK, XCTL, LOAD, RETURN, DELETE, ABEND, SETXIT, RESETXIT, COBADDR,
and CHECK. These operations are described in Chapter 5.4.
•
Storage Control Program (DFHSC Macro). This macro specifies
operations that affect the acquisition and release of areas of main
storage. It can have two types of operation: GETMAIN and FREEMAIN.
These operations are described in Chapter 5.5.
•
Transient Data Control Program (DFHTD Macro). This macro specifies
operations that affect the queuing and retrieval of data in main
storage or auxiliary storage. It can have five types of operation:
PUT, GET, FEOV, PURGE, and CHECK. These operations are described
in Chapter 5.6.
•
Temporary Storage Control Program (DFHTS Macro). This macro
specifies operations that affect the temporary storage of data in
main storage or auxiliary storage. It can have seven types of
operation: PUT, PUTQ, GET, GETQ, RELEASE, PURGE, and CHECK. These
operations are described in Chapter 5.7.
Chapter 5.1.
Introduction to Control Operations
341
Chapter 5.2. Interval Control (DFHIC Macro)
CICS/VS maintains the current time of day in two formats: a binary
value, in CSACTODB, which is updated automatically during task
dispatching to reflect the time of day maintained by the operating
system, and a packed value, in CSATODP, which is updated when control
returns from an operating system WAIT or when a DFHIC
TYPE=GETIME,FORM=PACKED macro is executed. The accuracy of these values
at a given moment depends upon the task mix and the frequency of task
switching operations.
Time management
fuv=tions based on
services available
programmer through
(DFHIC, •
provides the capability of controlling various task
the time of day or on intervals of time. The time
are listed below and are available to the application
use of the interval control macro instruction
1.
Provide the time of day in binary or packed decimal representation.
2.
Provide task synchronization based on time-dependent events.
3.
Provide automatic time-ordered task initiation with associated data
retention and recovery support.
The application programmer must specify parameter values when using
the DFHIC macro instruction. The values can be specified in either of
two lIays:
1.
By including the parameters in operands of the DFHIC macro
instruction by which time services are requested, or
2.
By coding instructions that place the parameter values in fields of
the TCA prior to issuing the DFHIC macro instruction.
The second of these approaches provides flexibility in that the
parameter values of a single DFHIC macro instruction can be altered at
execution time.
The application programmer can check the CICS/VS response to a
request for time services as explained under "Test Response to a Request
for Time Services," later in this chapter. If the programmer does not
check for a particular response, and the condition corresponding to that
response occurs, program flow proceeds to the next sequential
instruction in the application program. All operands that can be
included in the DFHIC macro instruction are discussed in detail at the
end of the chapter.
Chapter 5.2.
Interval Control (DFBIC Macro)
343
Time-of-Day Updating (TYPE=GETIME)
The format of the DFHIC macro instruction to request updating of
CICS/VS-maintained time-of-day values to the current clock time is as
follows:
DFHIC
TY PE=GET IME
[ , FORM= {BINAR!.I PACKED} ]
[,TIMADR={symbolic addresslYES})
[,NORESP=symbolic address]
[,INVREQ=symbolic address]
[,ERROR=symbolic address]
In the course of normal operation, CICS/VS maintains the current time
of day in binary form at CSACTODB and in packed decimal form at CSATODP.
The binary representation is expressed as a four-byte positive value in
hundredths of a second. The packed decimal representation is expressed
as a four-byte positive signed value of the form HHMMSSt+ where the
seconds are truncated to tenths of a second. The binary value is
updated periodically during task dispatching, and the packed decimal
value is updated when returning from an operating system WAIT. The
accuracy of these values at any given moment depends on the task mix and
the frequency of task switching operations.
The application programmer can ensure that one or both of these timeof-day values are updated to a current setting by issuing the DFHIC
TYPE=GETIME macro instruction. This macro instruction causes one or
both forms of the time of day to be updated in the CSA and, optionally,
places the requested form of the time of day in a four-byte field
specified by the application programmer. When the programmer wants the
time of day to be returned in a field other than those of the eSA i
either the symbolic label of the four-byte field must be specified in
the DFHIC TYPE=GETIME macro instruction or the address of the field must
be placed in TCAICDA prior to issuing the DFHIC TYPE=GETIME macro
instruction.
Bote: For performance reasons, it should be recognized that lengthy
conversion routines must be executed whenever updating of the packed
decimal representation of time of day is requested.
The following example shows how to request that the time of day be
placed at the storage locations represented by the symbolic label CLOCK.
DFHIC TYPE=GETIME,
FORM=PACKED,
TIMADR=CLOCK
REQUEST CURRENT TIME--OF-DAY
PACKED DECIMAL FORM
SYMBOLIC ADDRESS FOR RESPONSE
The following examples show how to request that the time of day be
placed in a field selected prior to (and independent of) execution of
the DFHIC TYPE=GETIME macro instruction.
For Assembler
lanqua~:
MVC TCAICDA,=A (CLOCK)
344
CICS/VS APRM (ML)
MOVE ADDR FOR RESPONSE TO TCA
*
*
DFHIC TYPE=GETIME,
FORM=PACKED,
TIMADR=YES
•
REQUEST CURRENT TIME-OF-DAY
PACKED DECIMAL FORM
RESPONSE ADDRESS GIVEN
*
For COBOL:
MOVE CLOCKADR TO TCAICDA.
NOTE MOVE ADDR FOR RESP TO TCA.
DFHIC TYPE=GETIME,
FORM=PACKED,
TIMADR=YES
REQUEST CURRENT TIME-DF-DAY
PACKED DECIMAL FORM
RESPONSE ADDRESS GIVEN
•
*
For PL/I:
TCAICDA=ADDR(CLOCK);
I*MOVE ADDR FOR RESP TO TCA*I
DFHIC TYPE=GETIME,
FORM=PACKED,
TIMADR=YES
REQUEST CURRENT TIME-oF-DAY
PACKED DECIMAL FORM
RESPONSE ADDRESS GIVEN
Chapter 5.2.
Interval Control (DFHIC Macro)
•
*
345
Delay Processing of a Task (TYPE=WAIT)
The format of the DFHIC macro instruction to delay processing of a task
until a specified time occurs is as follows:
~-----~-------r-
---------------------------------------------------------
I
DFHIC I TYPB=WAIT
I [,INTRVAL={numeric valuelYBS} ]I[,TIMB={numeric
I
valueIYBS}]
t [,RBQID={name IYBSI'prefix'} ]
I [,NORBSP=symbolic address]
I [,INVRBQ=symbolic address]
I [,BXPIRD=symbolic address]
I [,BRROR=symbolic address]
~_____ ~_______ I
L- ______________________________________________________~
The task synchronization feature of CICS/VS time management provides the
capability either of delaying the processing of a requesting task until
a specified time occurs or of signaling the requesting task when a
specified interval of time has elapsed. It also supports the
cancellation of a pending time-ordered synchronization event by another
task.
(See nTime-Ordered Request Cancellation (CANCEL), It later in this
chapter .)
This macro instruction causes the requesting task to temporarily
suspend processing, and to resume control at a specified time of day or
after a specified interval of time has elapsed. The INTRVAL and TI!B
operands are mutually exclusive. It supersedes and cancels any
previously initiated DFHIC TYPE=POST request for the task.
A numeric value specified in, or before issuing, the DPBIC TYPB=WAIT
macro instruction is used by CICS/VS to calculate the time at which the
requested time service is to be providede If the calculated ti~e of day
is the same as the current clock time, or up to and including six hours
preceding the current clock "time, the specified time is considered to
have elapsed (occurred) and the requested service is provided
immediately. If the calculated time of day is earlier than the current
clock time, the requested service is provided when the specified time
occurs. If the calculated time of day precedes the current clock time
by lIore than six hours, the requested service is provided the next day
at the specified time.
To identify the request and any data associated with it, a unique
identification is assigned to each time-ordered request. The
application programmer can specify a request identification to be
assigned to his DFHIC TYPB=WAIT macro by the RBQID operand. If none is
assigned by the programmer, CICS/VS assigns a unique request
identification. A request identification should be specified by the
application programmer if he wishes to provide another task with the
capability of canceling the unexpired WAIT request.
(See the section
"Time-ordered Request Cancellation (CANCEL)," later in this chapter.)
The following example shows bow to temporarily suspend the processing
of a task for a specified period of time:
DFHIC TYPE=WAIT,
INTRVAL=500,
REQID=GXLBZQKR
346
CICS/VS APRM(KL)
DELAY TASK PROCESSING,
WAIT 5 MINUTBS 0 SBCONDS
UNIQUE BEQUEST ID
*
*
The following examples show how to request the suspension of a task
until the time of day stored previously in TCAICRT is reached. A
request identification previously selected by the user is stored in
TCAICQID as a unique identifier for this request for time service.
IQr Assembler langyage:
MVC TCAICRT,=PL4 1 124500 1
HVC TCAICQID,UNIQCODE
MOVE 12:45 TO TCA
UNIQUE REQUEST ID TO TCA
DFHIC TYPE=WAIT,
TIME=YES,
REQID=YES
DELAY TASK PROCESSING
EXPIRATION TIME GIVEN
UNIQUE ID GIVEN
*
*
For COBOL:
MOVE 124500 TO TCAICRT.
MOVE UNIQCODE TO TCAICQID.
NOTE MOVE 12:45 TO TCA.
NOTE UNIQUE REQUEST ID TO TCA.
DFHIC TYPE=WAIT,
TIl'!E=YES,
REQID=YES
DELAY TASK PROCESSING
EXPIRATION TIME GIVEN
UNIQUE ID GIVEN
*
*
For PL/I:
TCAICRT=124500;
TCAICQID=UNIQCOOE;
/*MOVE 12:45 TO TCA*/
/*UNIQUE REQUEST IO TO T:A*/
DFHIC TYPE=WAIT,
TIME=YES,
REQIO=YES
DELAY TASK PROCESSING
EXPIRATION TIME GIVEN
UNIQUE ID GI VEN
Chapter 5.2.
Interval Control
~FHIC
Macro)
*
*
341
Signal Expiration of a Specified Time (TYPE=POST)
The format of the DFHIC macro instruction to request that CICS/VS signal
when a specified time has expired is as follows:
DFHIC
TYPE=POST
[,INTRVAL={numeric valuelYES} 11[,TIME={numeric
val ue I YES} ]
[,REQID={nameIYESI 'prefix'}]
[,NORESP=symbolic address]
[,INVREQ=symbolic address]
[,EXPIRD=symbolic address]
[,ERROR=symbolic address]
In response to this macro instruction, CICS/VS makes a timer event
control area available to the user for testing. This four-byte storage
area is initialized to binary zeros and its address is returned to the
requesting task in TCAICTEC.
When CICS/VS determines that the time specified in a DFHIC TYPE=POST
macro instruction has expired, byte 0 of the,timer event control area is
set to X'40' and byte 2 is set to X'80'. This form of posting is
compatible with the completion code postings performed by the operating
systems. The timer event control area can be used as the event control
area referred to in a DFHKC TYPE=WAIT macro instruction.
(See the
discussion of task synchronization in Chapter 5.3.)
The timer event control area provided to the user is not released or
altered (except as described above) until one of the following events
occurs:
o
The task issues a subseguent DFHIC TYPE=WAIT, DFHIC TYPE=POST,
DFHIC TYPE=INITIATE, or DFHIC TYPE=PUT macro.
•
The task issues a DFHIC TYPE=CANCEL macro request to nullify the
DFHIC TYPE=POST macro (this releases the storage area occupied by
the timer event control area).
•
The task terminates, normally or abnormally.
A task can have only one DFHIC TYPE=POST request active at any given
time. Any DFHIC TYPE=WAIT, DFHIC TYPE=POST, DFHIC TYPE=INITIATE, or
DFHIC TYPE=PUT request supersedes and cancels a previously issued DFHIC
TYPE=POST request by the task.
Note: The expiration of any CICS/VS time-ordered event is determined by
CICS/VS when it is performing its task dispatching function. Therefore,
for "posting" to occur, the application programmer must ensure that the
task relinquishes control of CICSjVS before each testing of the timer
event control area. This can be done directly by issuing the DFHKC
TYPE=WAIT or DFHKC TYPE=CHAP macro instruction (see the discussion of
task synchronization in Chapter 5.3.) or indirectly by requesting a
CICSjVS service that in turn initiates a task service on behalf of the
task.
A numeric value specified in, or before iSSUing, the DFHIC TYPE=POST
macro instruction is used by CICS/VS to calculate the time at which the
requested time service is to be provided. If the calculated time of day
is the same as the current clock time, or up to and including six hours
348
CICS/VS APRM(ML)
preceding the current clock time, the specified time is considered to
have elapsed (occurred) and the requested service is provided
immediately. If the calculated time of day is in advance of the current
clock time, the requested service is provided uhen the specified time
occurs. If the calculated time of day precedes the current clock time
by more than six hours, the requested service is provided the next day
at the specified time.
The application programmer can specify a request identification to be
assigned to a posting request by the REQID operand. If none is assigned
by the programmer, CICS/VS assigns a unique request identification,
which is returned to the application program in TCAICQID. In either
case, the request identification provides a means of symbolically
identifying the request.
This macro indicates that CICS/VS is to make a
four-byte timer event control area available to the application program
for testing. The area is initialized to binary zeros, and its address
is returned in TCAICTEC to the application program. This area is
available to the application program for the duration of the task and is
overridden if the application program issues another DFHIC request of
the follouing types: POST, WAIT, PUT, or INITIATE.
The follouing example shows how to request that CICS/VS provide a
signal for the task uhen a specified interval of time has elapsed:
DFHIC 'rYPE=POST,
INTRVAL=30
SIGNAL HHEN INTERVAL PASSES
INTERVAL IS 30 SECONDS
*
The following examples show how to dynamically request that CICS/VS
provide a signal for the task when the time of day previously stored in
TCAICRT is reached. Since no request identification is specified by the
application programmer, CICS/VS automatically assigns one and returns it
to the application program at TCAICQID.
For Assembler language:
MVC TCAICRT,PACKTIME
STORE CALCULATED EXPIR TIME
DFHIC TYPE=POST,
TIME=YES
HVC UNIQCODE,TCAICQID
SIGNAL WHEN TIME OCCURS
EXPIRATION TIME GIVEN
SAVE CICS/VS UNIQUE REQUEST ID
MOVE PACKTIME TO TCAICRT.
NOTE STORE CALC EXPIR TIME.
DFHIC TYPE=POST,
TIHE=YES
MOVE TCAICQID TO UNIQCODE.
SIGNAL WHEN TIME OCCURS
EXPIRATION TIME GIVEN
NOTE SAVE UNIQUE REQUEST ID.
*
*
For PLL!:
TCAICRT=PACKTIME;
/*STORE CALCULATED EXPIR TIME*/
DFHIC TYPE=POST,
TIHE=YES
UNIQCODE=TCAICQID;
SIGNAL WHEN TIME OCCURS
EXPIRATION TIME GIVEN
/*SAVE UNIQUE REQUEST ID*/
Chapter 5.2.
Interval Control
(DFHIC Macro)
*
349
Initiate a Task without Data (TYPE = INITIATE)
The format of the DFBIC macro instruction to request that CICS/VS
initiate a task at some future time is as follows:
r------~-------r- --------------------------------------------------------~
DFHIC
TYPE=IN ITIATE
[,INTRVAL={numeric valuelYES} ]I[ ,TIME={numeric
val ue I YES} ]
[,REQID={nameIYESI 'prefix'}]
[ , TRANSID=name]
[ ,TRMIDNT= {name IYES} ]
[,NORESP=symbolic address]
[,INVREQ=symbolic address]
[,TRNIDER=symbolic address]
[,TRMIDER=symbolic address]
[,ERROR=symbolic address]
~_____ ~_______ L-
________________________________________________________~
Through this macro instruction, the application programmer provides
the transaction identification of the task to be initiated at some
future time and other information pertaining to the task. CICS/VS
queues the request until the specified time occurs. When the necessary
resources are available (for example, a terminal), the task is
initiated. Only one task is initiated if multiple DFHIC TYPE=INITIATE
requests for the same transaction and terminal expire at the same time
or prior to terminal availability. No data can be passed to the future
task by means of the DFHIC TYPE=INITIATE macro instruction. (To do so,
see "Task Initiation with Data (PUT)," which follows.) This request
supersedes and cancels any previously initiated DFHIC TYPE=POST request
by the initiating task.
A numeric value specified in or before issuing the DPHIC
TYPE=INITIATE macro instruction is used by CICS/VS to calculate the time
of day at which the requested time service is to be provided. If the
calculated time of day is the same as the current clock time, or up to
and including six hours preceding the current clock time, the specified
time is considered to have elapsed (occurred) and the requested service
is provided immediately. If the calculated time of day is in advance of
the current clock time, the requested service is provided when the
specified time occurs. If the calculated time of day precedes the
current clock time by more than six hours, the requested service is
provided the next day at the specified time.
As stated earlier, a unique request identification is assigned to
each time-ordered request as a means of symbolically identifying the
request and any data associated with it. The application programmer can
specify an identifier for his initiation request, or he can let CICS/VS
assign one, in which case it is returned to the application program in
TCAICQID.
The application programmer must specify the transaction
identification of the future task, either in the DFHIC TYPE=INITIATE
macro instruction or by placing it in TCAICTI before issuing the macro
instruction. CICS/VS validates the transaction identification by
scanning the program control table (PCT). If the specified identifier
is not found in the table, CICS/VS does not provide the requested
service; a response code is placed at TCAICTR (for Assembler language or
PL/I) or at TCAICRC (for COBOL) to ind.icate that the transaction
identification is not valid.
350
CICS/VS APRM(ML)
If the future task must communicate with a terminal, the application
programmer must also specify a terminal identification, either in the
macro instruction or by placing it beforehand in TCAICTID. CICS/VS
validates the terminal identification by scanning the terminal control
table (TCT); if it fails to locate the terminal identification in the
TCT, CICS/VS provides a response code at TCAICTR ~or assembler language
or PL/I) or at TCAICRC (for COBOL) without servicing the request.
The following example shows how to request automatic initiation of a
specified task not associated with a terminal:
DFHIC
TYPE=INITIATE~
INTRVAL=10000,
TRANSID=TRNL
REQUEST TASK INITIATION
IN ONE HOUR
TRANSACTION IDENTIFICATION
*
*
The following examples show how to dynamically request automatic
initiation of a task associated with a terminal. The task initiation
time, transaction identification, and terminal identification are moved
to fields of the TCA before the DFHIC TYPE=INITIATE macro instruction is
issued. Since no request identification is specified by the application
programmer, CICS/VS automatically assigns one and returns it to the
application program at TCAICQID.
For Assembler language:
MVC TCAICRT,=PL4'10000',
MVC TCAICTI,=CL4'TRNl l
MVC TCAICTID,=CL4'STASI
MOVE ONE HOUR TO TCA
TRANSACTION ID TO TCA
TERMINAL ID TO TCA
DFHIC TYPE=INITIATE,
INTRVAL=YES,
TRMIDNT=YES
HVC UNIQCODE,TCAICQID
REQUEST TASK INITIATION
INTERVAL OF TIME GIVEN
TERMINAL ID GIVEN
SAVE CICS/VS UNIQUE REQUEST ID
*
*
For COBOL:
MOVE 10000 TO TCAICRT.
HOVE 'TRN1' TO TCAICTI.
MOVE 'STASi TO TCAICTID.
NOTE MOVE ONE HOUR TO TCA.
NOTE TRANSACTION ID TO TCA.
NOTE TER!INAL ID TO TCA.
DFHIC TYPE=INITIATE,
INTRVAL=YES,
TRMIDNT=YES
MOVE TCAICQID TO UNIQCODE.
REQUEST TASK INITIATION
INTERVAL OF TIME GIVEN
TERMINAL ID GIVEN
NOTE SAVE UNIQUE REQUEST ID.
*
*
For PL/I:
TCAICRT=10000;
TCAICTI=ITRN1';
TCAICTID=ISTASli
/*MOVE ONE HOUR TO TCA*/
/*TRANSACTION ID TO TCA*/
/*TERMINAL ID TO TCA*/
DFHIC TYPE=INITIATE,
INTRVAL=YES,
TRMIDNT=YES
UNIQCODE=TCAICQIDi
REQUEST TASK INITIATION
INTERVAL OF TIME GIVEN
TERMINAL ID GIVEN
/*SAVE UNIQUE REQUEST ID*/
Chapter 5.2.
Interval Control (DFBIC Macro)
*
*
351
Task Initiation with Data (TYPE=PUT)
The format of the DFHIC macro instruction to request automatic task
initiation and/or request that data be made available to a task is as
follows:
r---- r - - - - - r DFHIC
~
TYPE=PUT
[,INTRVAL={numeric valuelYES} 11[,TIME={numeric
val ue I YES} ]
[,REQID={nameIYESI 'prefix'}]
[ , TRANSID=name]
[ ,TRMIDNT= {name IYES} ]
[,ICDADDR={symbolic addressIYES}]
[,NORESP=symbolic address]
[,INVREQ=symbolic address]
[,TRNIDER=symbolic address]
[,TRMIDER=symbolic address]
[,IOERROR=symbolic address]
[,ERROR=symbolic address]
_____ •_______ L - ________________________________________________________~
This macro indicates that CICS/VS is to initiate a nonterminaloriented task at some future time and makes one data record available to
that task, or provides time-ordered data to be made available to a
terminal-oriented task that is to be initiated at some future time.
This macro instruction is used to provide the transaction
identification, the location of the data to be stored, and oth6r
information applicable to the task to be initiated. CICS/VS stores the
data and queues the request until the specified time occurs. As soon as
all necessary resources are available (for example, a terminal), the
task is initiated. CICS/VS temporary storage management facilities
support this facility of time management.
The DFHIC TYPE=PUT macro instruction is used only when data is to be
passed to a task to be initiated at some future time. It supersedes and
cancels any previously initiated DFHIC TYPE=POST request of the task.
If only task initiation at a future time is needed, the DFHIC
TYPE=INITIATE macro instruction should be used.
If the task to be initiated is associated with a terminal, the
initial DFHIC TYPE=PUT request causes the task to be initiated at the
specified time. Subsequent PUTs with the same terminal itlentification~
transaction identification, and expiration time are used to store data
for subsequent retrieval by the initiated task. If the task to be
initiated is not associated with a terminal, each DFHIC TYPE=PUT request
results in a task being initiated at the specified time. That is, only
one physical data record can be passed to a task not associated with a
terminal.
(See the section "Retrieve Time-Ordered Data (GET),n which
follows.)
Most operands of the DFHIC TYPE=PUT macro instruction are analogous
to similar operands of the DFHIC TYPE=INITIATE macro instruction. The
discussions of time calculation, request identification, transaction
identification, and terminal identificatit)n given in the section "Task
Initiation without Data (INITIATE)," which precedes this section, apply
to DFHIC TYPE=PUT in the same manner as they apply to DFHIC
352
CICS/VS APRM(ML)
TYPE=INITIATE. In addition, because the DFHIC TYPE=PUT macro
instruction permits data to be passed, the application programmer must
specify the symbolic address of the field containing the data. The
label may be provided as a parameter of the macro instruction or move
the address to TCAICDA prior to issuing the macro instruction.
The data passed to an initiated task must have the standard variablelength format, with the first four bytes containing LL~~. LL is a twobyte binary length field (the value of which includes the length of the
data plus the first four bytes), and ~~ is a two-byte field containing
binary zeros.
Note: An IOERROR will occur if there is not enough auxiliary temporary
storage available to hold the data being passed. See the CICS/VS System
Programmer's Reference Manual discussion of temporary storage for
further details of auxiliary temporary storage requirements.
The following example shows how to request automatic task initiation
and/or request that time-ordered data be made available to a task
associated with a terminal:
DFHIC TYPE=PUT,
TIME=173000,
TRANSID=TRN2,
TRMIDNT=STA3,
ICDADDR=DATAFLD
REQUEST TASK INITIATION
TIME IS 5:30 PM
TRANSACTION IDENTIFICATION
TERMINAL IDENTIFICATION
DATA ADDRESS
*
*
*
*
The following examples show how to dynamically request automatic task
initiation and/or request that time-ordered data be made available to a
task associated with a terminal. Values for time, request
identification, transaction identification, and terminal identification,
as well as the address of data to be passed, are moved to appropriate
fields of the TCA before issuing the DFHIC TYPE=PUT macro instruction.
For Assembler language:
avc
MVC
MVC
MVC
MVC
TCAICRT,PACKTIHE
TCAICQID,UNIQCODE
TCAICTI,=CL4'TRN2'
TCAICTID,=CL4'STA3'
TCAICDA,=A ~ATAFLD)
DFHIC TYPE=PUT,
TIME=YES,
TRMIDNT=YES,
REQID=YES,
ICDADDR=YES
Chapter 5.2.
CALCULATED EXPIR TIME TO TCA
UNIQUE REQUEST ID TO TCA
TRANSACTION ID TO TCA
TERMINAL ID TO TCA
ADDRESS OF DATA TO TCA
REQUEST TASK INITIATION
EXPIRATION TIME GIVEN
TER~INAL ID GIVEN
UNIQUE REQUEST ID GIVEN
DATA ADDRESS GIVEN
Interval Control (DFHIC Macro)
*
*
*
*
353
MOVE
MOVE
MOVE
MOVE
MOVE
PACKT1ME TO TCAICRT.
UN1QCODE TO TCAICQID.
'TRN2' TO TCAICTI.
'STA3' TO TCAICTID.
DATADDR TO TCAICDA.
DFHIC TYPE=PUT,
TIME=YES,
TRM IDNT=YES,
REQID=YES,
ICDADDR=YES
NOTE
NOTE
NOTE
NOTE
NOTE
CALC EXPIR TIME TO TCA.
UNIQUE REQUEST ID TO TCA.
TRANSACTION ID TO TCA.
TERMINAL ID TO TCA.
ADDRESS OF DATA TO TCA.
REQUEST TASK INITIATION
EXPIRATION TIME GIVEN
TERMINAL ID GIVEN
UNIQUE REQUEST ID GIVEN
DATA ADDRESS GIVEN
*
*
*
*
For PL/I:
354
TCAICRT=PACKTIME;
TCAICQID=UNIQCODE;
TCAICTI='TRN2' ;
TCAICT1D='STA3';
TCAICDA=ADDR(DATAFLD) ;
/*CALC EXP1R TIME TO TCA*/
/*UNIQUE REQUEST ID TO TCA*/
/*TRANSACT10N ID TO TCA*/
/*TERMINAL ID TO TCA*/
/*ADDRESS OF DATA TO TCA*/
DFHIC TYPE=PUT,
TIME=YES,
TRM1DNT=YES,
REQID=YES,
ICDADDR=YES
REQUEST TASK INITIATION
EXPIRATION TIME GIVEN
TERMINAL ID GIVEN
UNIQUE REQUEST 1D GIVEN
DATA ADDRESS GIVEN
CICS/VS APRM (ML)
*
*
**
Retrieve Time-Ordered Data (TYPE=GET)
The format of the DFHIC macro instruction to retrieve data stored by a
DFHIC TYPE=PUT macro instruction (issued by another task) is as follows:
DFHIC
TYPE=GET
[,ICDADDR={symbolic addressIYES}]
[ , RELEASE=NO ]
[,NORESP=symbolic address]
[,INVREQ=symbolic address]
[,NOTFND=symbolic address]
[,ENDDATA=symbolic address]
[,IOERROR=symbolic address]
[,TSINVLD=symbolic address]
[,ERROR=symbolic address]
Only data from an expired DFHIC TYPE=PUT request can be accessed
using the DFHIC TYPE=GET macro instruction. To retrieve data stored by
use of a DFHIC TYPE=PUT request, the DFHIC TYPE=GET macro instruction
must be used.
When time-ordered data is to be retrieved by means of a DFHIC
TYPE=GET macro instruction, the application programmer may specify the
address of a storage area into which the data is to be placed. The
address is specified either by including the address in the macro
instruction or by storing it in TCAICD! prior to issuing the macro
instruction. In either case, the storage area must be large enough to
contain the four-byte length field (LL~) at the beginning of the data
record as well as the data portion of the record. If the application
programmer does not select a storage area, CICS/VS automatically
acquires an area of sufficient size and returns the address of that area
in TCAICD!.
Each originating DFHIC TYPE=PUT request provides the transaction
identification of the task to receive the data, and if applicable,
symbolically identifies the terminal associated with the task's
operation. When CICS/VS services a DFHIC TYPE=PUT request, it does so
in two steps; it first queues the request for automatic task initiation
at a specified time and then stores the data. When the specified time
occurs, the task is ready to be initiated, and the stored data is then
available for retrieval.
A task not associated with a terminal that is initiated as a result
of an expired DFHIC TYPB=PUT request can access only the single physical
data record associated with the original request. It does this by
issuing one DFHIC TYPE=GBT macro instruction. The storage occupied by
the data associated with the task is released upon execution of the
DFBIC TYPE=GET request, or upon termination of the task (normally or
abnormally) if no DFHIC TYPE=GET macro instruction is executed prior to
termination.
A task associated with a terminal that is initiated as the result of
an expired DFHIC TYPE=PUT request, or that is active at the time of
expiration of a DFHIC TYPE=PUT request, can access all data records
associated with expired DFBIC TYPE=PUT macro requests having the same
transaction identification and terminal identification. Therefore, a
task associated with a terminal can retrieve all data made available to
the terminal and the task up to the current time by issuing consecutive
DFHIC TYPE=GET requests. Expired data records are presented to the task
Chapter 5.2.
Interval Control (DFHIC !acro)
355
upon request in expiration time sequence. The storage occupied by the
single data record associated with a DPHIC TYPE=PUT request is released
after the data has been retrieved by a DPHIC TYPE=GET request or upon
termination of CICS/VS. Data passed in subsequent expired DPHIC
TYPE=PUT requests specifying the same terminal identification and
transaction identification can be retrieved in response to DPHIC
TYPE=GET requests by the same task if that task is still active at their
expiration times. Otherwise, such a DPHIC TYPE=PUT request causes a new
task to be initiated.
When all passed data for which specified times have expired has been
retrieved, CICS/VS provides an end-of-data response at TCAICTR (for
Assembler language or PL/I) or TCAICRC (for COBOL) in response to a
DPHIC TYPE=GET macro instruction.
The following example shows how to request retrieval of a timeordered data record into a data area specified in the request:
DPHIC TYPE=GET,
ICDADDR=DATAPLD
RETRIEVE TIME-ORDERED DATA
USER-PROVIDED DATA AREA
•
The following examples show bow to dynamically request retrieval of a
time-ordered data record. The address of the storage area reserved for
the data record is placed in TCAICDA prior to the issuance of the DPBIC
TYFE=GET macro instruction.
Por Assembler language:
MVC TCAICDA,=A(D1T1PLD)
DATA PIELD ADDR TO TCA
DPHIC TYPE=GET,
ICDADDR=YES
RETRIEVE TIME-ORDERED DATA
DATA PIELD ADDRESS GIVEN
•
Por COBOL:
MOVE DATADDR TO TCAICDA.
NOTE DATA PIELD ADDR TO TCA.
DPHIC TYPE=GET,
ICDADDR=YES
RETRIEVE TIME-ORDERED DATA
•
For PL/I:
356
TCAICDA=ADDR(DATAFLD) ;
/*DATA PIELD ADDR TO TCA./
DFHIC TYPE=GET,
ICDADDR=YES
RETRIEVE TIME-ORDERED DATA
CICS/VS APRM(ML)
•
Cancel a Request for Time Services (TYPE=CANCEL)
The format of the DFHIC macro instruction to cancel a DFHIC TYPE=WAIT,
DFHIC TYPE=POST, DFHIC TYPE=INITIATE, or DFHIC TYPE=PUT request is as
follows:
r------~-------r----------------------------------------------------------~
I
I
I
I
I
I
I
L
I _______
I
DFHIC I TYPE=CANCEL
I [,REQID={nameIYES}]
I [,NORESP=symbolic address]
I [,INVREQ=symbolic address]
I [,NOTFND=symbolic address]
I [,ERROR=symbolic address]
~
I
_______ ~I_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~
This macro specifies that a request of one of the following types is
to be acted upon as follows:
1.
DFHIC TYPE=WAIT issued by another task
treated as though expired.
(now suspended) is to be
2.
DFHIC TYPE=POST issued by this task is to be removed from the
system.
3.
DFHIC TYPE=POST issued by another task is to be treated as though
expired.
4.
DFHIC TYPE=INITIATE is to be removed from the system.
5.
DFHIC TYPE=PUT is to be removed from the system.
The effect of the cancellation is dependent on whether a request
identification is specified for the DFHIC TYPE=CANCEL request and on the
type of service request being canceled.
£~acel
an Interval Control POST Request
A DFHIC TYPE=POST request can be canceled by the originating task or by
another task through use of the DFftIC TYPE=CANCEL macro instruction.
When the originating task cancels a DFHIC TYPE=POST request, no
request identification should be specified for the cancellation request.
This cancellation request can be made either before or after expiration
of the original request. In either case, the storage reserved for the
timer event control area is released, and all references to the original
request are removed from the system.
When a task other than the originating task cancels a DFHIC TYPE=POST
request, the request identification of that request must be specified.
The effect of the cancellation is the same as an early expiration of the
original DFBIC TYPE=POST request. That is, the timer event control area
for the originating task is posted as though the original expiration
time had been reached.
Chapter 5.2.
Interval Control (DFHIC Macro)
357
Cancel an Interval Control WAIT Reguest
A DFHIC TYPE=WAIT request can only be canceled prior to its expiration,
and only by a task other than the task that issued the DFHIC TYPE=WAIT
(the originating task is suspended for the duration of the request).
The request identification of the suspended task must be specified. The
effect of the cancellation is the same as an early expiration of the
original DFHIC TYPE=WAIT or DFHKC TYPE=CHAP request. That is, the
originating task resumes control (based on its normal dispatching
priority) as though the original expiration time had been reached.
Cancel an Interval Control INITIATE or PUT Reguest
A request identification must be specified when the DFHIC TYPE=CANCEL
macro instruction is used to cancel a DFHIC TYPE=INITIATE or DFHIC
TYPE=PUT request. The effect of the cancellation is to remove the
original request from the system, treating the original request as
though it had never been made. The cancellation request is effective
only prior to expiration of the original request.
358
CICS/VS APRM(ML)
I/O Error Retry (TYPE=RETRY)
The format of the DFHIC macro instruction to retry an operation
requested by a DFHIC TYPE=GBT Dacro instruction uhen an I/O error occurs
is as follows:
DFHIC
TYPE=RETRY
[ ,RELEASE=NO]
[,NORESP=symbolic address]
[,INVREQ=symbo1ic address]
[ ,NOTFND=symbolic address]
[,IOERROR=symbo1ic address]
[,ERROR=symbolic address]
CICS/VS attempts to retrieve the data record whose symbolic eightcharacter identification is specified at TCAICQID, and place it into the
data area specified at TCAICDA. These fields are praset by CICS/VS at
the time the I/O error responsa vas returned to the application prograDe
Chapter 5.2.
Interval Control (DPHIC Hacro)
359
Test Response to a Request for Time Services (TYPE=CHECK)
The format of the DFHIC macro instruction to test the CICS/VS response
to a request for time services is as folJ,ovs:
DFHIC
TYPE=CHECK
[ ,NORESP=symbolic address]
[,INVREQ=symbolic address]
[,EXPIRD=symbolic address]
[,TRNIDER=symbolic address]
[ ,TRMIDER=symbolic address]
[,NOTFND=symbolic address]
[,ENDDATA=symbolic address]
[ ,IOERROR=symbolic address]
[,TSINVLD=symbolic address]
[,ERROR=symbolic address]
Interval Control Response Codes
The Assembler-language or PL/I programmer can access interval control
response codes at TCAICTR; the COBOL programmer can access interval
control response codes at TCAICRC. The possible response codes and the
conditions to which they correspond are identified in the right-hand
columns of Figure 5.2-1. DFHIC macro instructions for which the
conditions are applicable are shown at the left.
360
CICS/VS APRM (HL)
Time Services
Request by
DFHIC Macro
Instruction
I
Response Code
I
I
IAssemblerl COBOL
Condition
ALL
NORESP
I
(Normal response) I
I
ENDDATA
I
(End of data condition)
GET ,CHECK
PL/I
X'OO'
LOW-VALUES
(ICNORESP)
00000000
X'Ol'
12-1-9
(ICENDDATA)
00000001
PUT,GET,RETRY,
CHECK
IOERROR
(INPUT/Outpu t
error)
X' 04'
12-4-9
(ICIOERROR)
00000100
INITIATE, POT,
CHECK
TRNIDER
(Transaction
identification
error)
X' 11'
11-1-9
(ICTRNIDER)
00010001
INITIAT E ,PUT,
CHECK
TRMIDER
(Terminal identification error)
X'12·
11-2-9
(ICTRMIDER)
00010010
GET,CHECK
TSINVLD
(No temporary
storage support)
X'14 I
11-4-9
(ICTSINV LD)
00010100
WAIT, POST ,CHECK
EXPIRD
(Expired)
X120'
11-0-1-8-9
(ICEXPIRD)
00100000
GET,CANCEL,
RETRY,CHECK
NOTFND
(Not found)
X'81 1
12-0-1
(ICNOTPND)
10000001
ALL
INVREQ
(Invalid request)
X'FP'
ALL
ERROR
(Any response
other than
NORESP)
(Note 2)
12-11-0-7-8-9
(ICINVREQ)
(Note 2)
11111111
(Note 2)
1. The names enclosed in parentheses in the COBOL column indicate
the condition names generated by CICS/VS. These names may be usedl
in testing for the conditions in a COBOL program.
I
I
2. The test for the ERROR response is satisfied by a not equal
I
condition; that is, not X'OOI, not LOW-VALUES, or not 00000000
I
for Assembler, COBOL, and PL/I, respectively.
_____________________________________________________________________
- - - - JI
~
Figure 5.2-1.
Interval COutrol Response Codes
If the application programmer does not check for a particular
response to his service request, and the exception condition
corresponding to that response occurs, program flow proceeds to the next
sequential instruction in the application program.
The following examples show how to examine the response code provided
by CICS/VS at TCAICTR (for Assembler language or PL/I) or TCAICRC (for
COBOL) and transfer control to the appropriate user-written exceptionChapter 5.2.
Interval Control (DPBIC Macro)
361
handling routine. The alternative approach available to COBOL
programmers is also shown.
For Assembler
DFHIC
GOOD
CLI
BE
DFHPC
DS
langugg~:
TYPE=GET ,
ICDADDR=DATAFLD
TCAICTR,X'OO'
GOOD
TYPE=ABEND,ABCODE=TIME
OH
*
NORMAL RESPONSE
For COBOL:
DFHIC
IF
THEN
ELSE
DFHPC
TYPE=GET,
ICDADDR=DATAFLD
TCAICRC = LOW-VALUES
GO TO GOOD
NEXT SENTENCE. NOTE LOW-VALUES NORESP.
TYPE=ABEND
*
GOOD.
Alternatively, the COBOL programmer may make use of the CICS/VS
generated condition names to test responses. For example:
IF ICNORESP THEN GO TO GOOD.
For PL/I:
DFHIC
TYPE=GET,
ICDADDR=DATAFLD
IF TCAICTR='O'B THEN GO TO GOODi/*NORMAL RESPONSE*/
DFHPC
TYPE=ABEND
GOOD:
362
CICS/VS APRM(ML)
*
Operands of DFHIC Macro
ENDDATA=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if no more data is stored for the task
issuing a DFHIC TYPE=GET request. It can be considered a
normal end-of-file response when retrieving sequential timeordered data records.
ERROR=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if any of the response conditions other
than NORESP occurs.
EXPIRD=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the time specified in a DFHIC
TYPE=POST or DFHIC TYPE=HAIT request has expired at the time
the request is issued.
FOR~I=
indicates which time-of-day representation is desired.
BINARY
specifies that a binary representation of time of day ~
four-byte positive value in hundredths of a second) is to
be updated and retained in CSACTODB.
PACKED
specifies that the binary representation of time of day
(described above) and the packed decimal representation (a
four-byte positive value of the form HHMMSSt+ where seconds
are truncated to tenths of a second) are to be updated and
retained in CSACTODB and CSATODP respectively.
Note:
COBOL and PL/I programmers should be aware that the
portion of the low-order byte of this positive number
contains hexadecimal F rather than C or D.
zone
ICDADDR=
specifies the location of the data to be stored for the task to
be initiated at some future time.
symbolic address
is the symbolic address of the storage area containing the
data to be made available to the task.
YES
indicates that the symbolic address of the storage area
containing the data has been placed in TCArCDA.
If no data is to be passed, DFHIC TYPE=INITIATE rather than
DFHIC TYPE=PUT should be used.
INTRVAL=
specifies the interval of time that is to elapse before CICS/VS
initiates a task, or before CICS/VS posting is to occur, or for
which a task is to be suspended.
Chapter 5.2.
Interval Control (DFHIC Macro)
363
numeric value
is of the form HHMMSS, where HH represents hours from 00 to
99, MM represents minutes from 00 to 59, and SS represents
seconds from 00 to 59. This numeric value is added to the
current clock time by CICS/VS when the associated macro
instruction is executed to calculate the time of day (clock
time) when the task is to be initiated or posted, or when
processing of the task is to be resumed. When used with
TYPE=INITIATE, if the specified interval is zero, or if
both INTRVAL and TIME are omitted, the task is initiated
immediately.
YES
indicates that the interval of time (in packed decimal
form, HRMMSS+) has been placed in TCAICRT.
If this operand is specified, the TIME operand cannot be
specified.
INVREQ=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an invalid type of request was
received for processing by the interval control program.
IOERROR=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an input/output error occurs during
a DFHIC TYPE=GET or DFHIC TYPE=PUT operation on auxiliary
storage. The DFHIC TYPE=RETRY macro instruction can be used in
the routine for handling DFHIC TYPE=GET input/output errors.
One of the causes of this error is during a TYPE=PUT if there
is insufficient auxiliary temporary storage available to hold
any data which is to be passed. See the CICS/VS System
Programmer's Guide discussion of temporary storage for further
details of auxiliary temporary storage requirements.
NORESP=symoolic address
specifies the entry label of the user-written routine to which
control is to be passed if no error occurs. NORESP signifies
"normal response. II
NOTFND=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the request identification specified
in a DFHIC TYPE=CANCEL macro instruction fails to match an
unexpired time-ordered request. It is also applicable to DFHIC
TYPE=GET or DFHIC TYPE=RETRY requests and signifies that the
time-ordered data stored for retrieval through the DFHIC
TYPE=PUT macro instruction cannot be located using the unique
request identification contained in TCAICQID at the time of
this request. This condition occurs on a retrieval operation
if some prior task retrieved the data stored under the request
identification directly through temporary storage facilities
and then released the data area. It also occurs if the request
identification associate~ with the original DFHIC TYPE=PUT
request fails to remain a unique identification.
364
CICS/VS APRM(ML)
RELEaSE=NO
indicates that CICS/VS is not to release the record from
temporary storage after obtaining the record for the
application program.
Upon completion of a successful DF8IC TYPE=GET,RELEASE=NO
request, CICS/VS places the identification of the temporarystorage record in TCAICQID. Using this identification, the
user can retrieve or release the record from temporary storage
through the DFHTS macro instruction; the record is not
available to any subsequent DFHIC get requests.
This operand is valid only for a retry of a DFHIC TYPE=GET
request.
REQID=
is an optional operand used to assign a unique request
identification to this request, as a means of symbolically
identifying the request. It should be used if the application
programmer wishes to provide another task with the capability
of canceling an unexpired WAIT request (see the discussion of
DFHIC TYPE=CANCEl, later in this chapter). The data is put in
temporary storage with this identification.
name
is a unique identifier, up to eight characters in length,
selected for this request by the application programmer.
YES
indicates that an eight-character request identification
has been placed in TCAICQID by the application program.
'prefix'
is a two-character (including blanks) prefix to be affixed
to the Request Identification generated by CICS/VS. If
REQID=" is specified, the prefix is assumed to be in the
two-byte field TCAICQPX.
If this operand is omitted, CICS/VS generates a unique request
identification in the form "DFNNNHNN"; the prefix is DF.
TIMADR=
is used when the time of day is to be returned in an
application programmer-selected four-byte field. For
FORM=BINARY, the binary representation is returned; for
FORM=PACKED, the packed decimal representation is returned.
symoolic address
is the symbolic ad~ress of the field in which the time of
day is to be made available to the application program.
YES
indicates that the symbolic address of the field for the
time of day is in TCAIeDA.
If this operand is omitted, the fields of the CSA are updated,
but the time of day is not placed in another field for
reference by the application program.
Chapter 5.2.
Interval Control (DFHIC Macro)
365
TIME=
specifies the time of day at which CIC~/VS is to initiate the
requested service. If the specified ti,me of day is the same as
the current clock time or up to and including six hours
preceding the current clock time, the specified time is
considered to have occurred, and the requested service is
provided immediately.
numeric value
is of the form HHMMSS, where HH represents hours from 00 to
99, MM represents minutes from 00 to 59, and SS represents
seconds from 00 to 59.
YES
indicates that the time of day (in packed decimal form,
HHMMSS+) has been placed in TCAICRT.
If this operand is specified, the INTRVAL operand cannot be
specified.
TRANSID=name
is the symbolic transaction identification of the task to be
initiated. If this operand is omitted, the transaction
identification is assumed to be in TCAICTI.
TRMIDER=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the symbolic terminal identification
specified in the DFHIC TYPE=INITIATE or DFHIC TYPE=PUT request
cannot be found in the terminal control table (TCT).
TRMIDNT=
is the symbolic terminal identification of the terminal
associated with the task to be initiated. This ooerand is
required when the task to be initiated must communicate with a
terminal; it s~ould be omitted otherwise.
TRNIDER=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the symbolic transaction
identification specified in a DFHIC TYPE=INITIATE or DPHIC
TYPE=PUT request cannot be found in the program control taole.
TSINVLD=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the CICS/VS temporary storage
program does not support a DFHTS TYPE=GET request issued by the
CICS/VS interval control program. This situation can occur
when a dummy temporary storage program is included in the
current CICS/VS system ill place of a functional temporary
storage program.
366
CICS/VS APRM(ML)
Chapter 5.3. Task Control (DFHICC Macro)
Task management provides the capability to process transactions ~asks)
concurrently. Transactions are scheduled, through task control, and
processed according to priorities assigned by the user. Control of the
processor is given to the highest priority task that is ready to be
processed. Control of the processor is returned to the operating system
when no further work can be done by CICS/VS or by user-written
application programs.
Rhen a transaction is initiated in CICS/VS, task control dynamically
allocates storage for the task control area (TCA), places the task on
the dispatching priority queue, obtains the program identification of
the program initialJy required to process the task from the program
control table (PCT), and transfers control to program control.
The Task ~anagement macro instruction (DPHKC) is used to request any
of the following services:
0
Initiate a task
0
Change the priority of a task
•
Synchronize a task
•
Synchronize the use of a resource by a task
0
Purge a task on system overload
The application programmer must specify parameter values uhen using
the DPHKC macro instruction. The values can be specified in either of
two ways:
1.
By including the parameters in operands of the DFHKC macro
instruction by which task control services are requested, or
2.
By coding instructions that place the parameter values in fields of
the TCA prior to issuing the DPHKC macro instruction.
The second method adds flexibility by letting the programmer vary the
parameter values of a single DPHKC macro instruction to meet the needs
of a given program.
Chapter 5;3.
Task Control
~FHKC
Macro)
367
Initiate a Task (TYPE=ATTACH)
The format of the DFHKC macro instruction to initiate a task is as
follows:
r------~-------~----------------------------------------------------------~
I
I
I
I
I _______
L
DFHKC
~
TYPE=ATTACH
[ ,FCADDR=symbolic address]
[ ,TRANSID=name]
_______ L __________________________________________________________
~
This macro instruction causes task control to obtain the task control
area (TCA) for a task and insert the task in the dispatching priority
queue according to the overall transaction processing priority of the
task.
This macro instruction is intended to be used by other CICS/VS
control modules, but it is also available for use by the application
programmer to initiate additional tasks.
Any additional tasks initiated
by the application programmer must terminate themselves through use of
the program control DFHPC TYPE=RETURN macro instruction.
Most tasks running under CICS/VS are initiated at a terminal and are
thus associated with a terminal. Tasks initiated by CICS/VS management
programs (for example, automatic task initiation by transient data
control) mayor may not be associated with a terminal. The contents of
TCAFCAAA varies depending upon whether the attached task is associated
with a terminal, a'~ discussed in th e section "Task Control Area (TCA),"
in Chapter 2.1.
The number of tasks that can be active within the system at a given
time is limited by the availability of main storage and/or by the
"maximum number of tasks" control established by the system programmer
at system generation or initialization. A new task is not initiated by
CICS/VS unless sufficient main storage is available to process it.
Instead, the request to initiate a task is queued (stored) until
sufficient main storage becomes available.
Tasks initiateJ by CICS/VS
management modules (for example, terminal control) are subject to the
maximum number of tasks limitation. Application program requests for
attachment of tasks are not subject to this limitation and therefore are
allowed to exceed the maximum.
If the DFHKC TYPE=ATTACH macro instruction is used by the application
programmer, he must provide the facility control area address and
transaction identification required by CICS/VS to initiate a new task.
The address and identification can be specified in two ways.
1.
By coding two instructions that assign a facility control area
address to TCAKCFA and a transaction identification to TCAKCTI
Erio~ to issuing the DFHKC TYPE=ATTACH macro instruction, or
2.
By including the FCADDR=symbolic address operand and
TRANSID=symbolic name operand in the DFHKC TYPE=ATTACH macro
instruction, which then stores the assigned values in TCAKCFA and
TCAKCTI, respectively.
For all transactions associated with a terminal, the facility control
area address in TCAKCFA is the address of the TCTTE for the terminal.
This address provides access to control information necessary for
communication netween the program and the terminal. The first byte is
an X·01·.
If the attaching task owns a terminal, ownership of that
terminal (but of no other terminal) may be passed in TCAKCFA.
When
368
CICS/VS APRM(ML)
attaching a task and passing ownership of the terminal to that task, the
address of the TCA must be stored in TCTTECA.
If a task is not associated with a terminal, the facility control
area address can serve as a pointer to additional facility control
information required for execution of the task. For example, it can be
the address of an entry in the destination control table (DCT) that is
associated with a hardware resource (for example, a data set) •
The transaction identification is used only for the current ATTACH;
it is not carried in the TCA for the duration of the task.
The specified task is not attached if the transaction identification
is not in the PCT or the program name is not in the Processing Program
Table (PPT). If this situation exists or the attached task ABENDs, a
message is sent to the terminal operator, but the attaching task is not
notified of the condition. Therefore, the DPHKC TIPE=ATTACH macro
instruction must De used with extreme caution by the application
programmer.
Although the application programmer has the capability of attaching a
task directly to a terminal by means of the DFHKC TIPE=ATTACH macro,
this procedure is not recommended.
(The DPHKC TYPE=ATTACH macro ~ot
be used to attach a task to a VTAM logical unit.) Instead, one of the
following approaches should be used:
•
Automatic task initiation through transient data management
•
Automatic task initiation through time management (interval control
program); for example, a DFHIC TYPE=INITIATE macro with a zero
interval
o
Identification of the transaction identification to be used with
the next input message frohl the terminal by means of a DFHPC
TYPE=RETURN,TRANSID= macro instruction.
The flowchart in Figure 5.3-1 shows Task A attaching Task Band
synchronizing the processing steps of both tasks through use of the
facility control address passed to the newly created task at attach
time. Since Task B is a nonterminal-oriented task, it is unable to use
terminal control macro instructions. FCADDR specifies the address of
Task A's TCA; ECBl and ECB2 are fields in the TWA for Task A.
Figure 5 .. 3-1 includes steps labeled "POST ECB". Posting an ECB
entails setting on the appropriate bit in the EeB, which is a 4-byte
field. In CICS/OS/VS, the bit to be set on (that is, set to '1') is bit
1 of byte 0; in CICS/DOS/VS, it is bit 0 of byte 2. The following
examples show how to set bits on for each programming language. These
examples set on both the bit required for CICS/OS/VS and that required
for CICS/DOS/VS, so they may be used for hoth systems.
Chapter 5.3.
Task Control
~FHKC
Macro)
369
Por Assembler
ECBl
la~y~~:
DC
HiC
P'O'
BCB1(3)
,=X ' Q00080'
Por COBOL:
77 ECBl PIC 59(8) COMP VALUE ZERO.
PROCEDURE DIVISION.
COBPUTE ECBl = 2
**
15 + 2
**
30.
Eor PL/I:
DCL ECBl BIT(32) ALIGNED INIT(IOIB);
ECBl = '01000000000000001'B;
370
CICS/VS APRM(ML)
TASK A
TASK B
Attach Task B
and Point FCADDR
toTCA
Obtain Address of
ECB1 and ECB2 by
Use of Address
Now in TCAFCAAA
-
If Task 'B' is lower
in priority it becomes
active here.
"
Processing Step 1
"
Wait on ECB1
(Note 1)
Post ECB1 to Make
Task 'A' Dispatchable
If Task 'B' is hiltaer
in priority it becomes
active here.
Task 'B' gives up
control here.
Wait on ECB2
(Note 2)
Task 'A' is aware if
Task 'B' completed
Processing Step 1.
Processing Step 2
Task 'B' is aware
of completion
of both Step 1
and Step 2.
Task 'B' regains
control here.
,
Post
ECB2
Processing Step 3
Note:
Give Up Control
By a Wait or PC Return
If Task B is not attached
(e.g. Trans ID not in PCT),
or if Task B ABEND, ECB 1
may never be posted.
Note 2: If Task A ABEND, ECB2
may never be posted.
Figure 5.3-1.
Task Synchronization under CICS/VS
The DFHPC TYPE=RETURN macro instruction can be used to terminate any
tasks initiated by the application programmer through use of the task
control DFHKC TYPE=ATTACH macro instruction.
The following example illustrates the coding reguired to statically
provide a facility control area address and transaction identification:
Chapter 5.3.
Task Control (DPHKC Macro)
311
DFHKC TYPE=ATTACH,
FCADDR=FACCTL,
TRANSID=TRNl
INITIATE NEi TASK
USER'S FCA ADDRESS
TRANSACTION IDENTIFICATION
The following examples illustrate the coding required to dynamically
provide a facility control area address and transaction identification.
For Assembler language:
MVC TCAKCTI,=CL4'TRN1'
MVC TCAKCFA,=A(FACCTL)
TRANSACTION IDENTIFICATION
USER'S FCA ADDRESS
DFHKC TYPE=ATTACH
INITIATE NEi TASK
For COBOL:
312
MOVE 'TRN1' TO TCAKCTI.
MOVE FACADR TO TCAKCFA.
NOTE TRANSACTION IDENTIFICATION.
NOTE USER'S FCA ADDRESS.
DFHKC TYPE=ATTACH
INITIATE NEW TASK
TCAKCTI='TRN1'i
TCAKCFA=FACADR;
/*TRANSACTION IDENTIFICATION*/
/*USER'S FCA ADDRESS*/
/*FACADR IS A POINTER VARIABLE*/
DFHKC TYPE=ATTACH
INITIATE NEW TASK
CICS/VS APRM(ML)
*
*
Change Priority of a Task (TYPE = CHAP)
The format of the DFBKC macro instruc~ion to change the dispatching
priority of a task is as follows:
r'------~------'r---------------------------------------------------------~
I
I
I
IL_______
DFHKC
~
TYPE=CHAP
[,PRTY=priority value]
_______ L ________________________________________________________
~
The overall transaction processing priority of a task is the sum of
related transaction, terminal, and operator priorities as specified or
established by default at system generation. This priority determines
the position of the task in the dispatching priority queue and,
therefore, its scheduling under CICS/VS. The priority of an existing
task can be changed by issuing the DFHKC TYPE=CHAP macro instruction.
The specified priority value must be in the range from 0 through 255,
where 255 represents the highest priority. This task is placed below
all other tasks of equql or higher priority in the dispatching priority
queue.
The application programmer can include the PRTY=priority value
operand in the DFHKC TYPE=CHAP macro instruction to assign a new
dispatching priority to a task. Alternatively, the programmer can
assign a priority value to the dispatching priority field ~CATCDP)
Erio~ to issuing the DFHKC TYPE=CHAP macro instruction.
A task can relinquish control to all tasks of equal or higher
priority by issuing a DFHKC TYPE=CHAP macro instruction. No priority
value need be specified, and the current priority value of the taSK as
stored in TCATCDP is not changed. However, the fact that the macro
instruction is issued permits control to be transferred from the task
issuing the instruction to an equal or higher priority task within
CICS/VS. This capability is designed particularly for compute-bound
tasks which, by continually demanding inordinate amounts of processor
time, can sign1iicantly affect overall system performance.
The following example ShOWS how to statically assign a new task
dispatching priority value:
DFHKC TYPE=CHAP,
PRTY=255
CHANGE PRIORITY OF THIS TASK
NEW PRIORITY VALUE
*
The following examples illustrate the coding required to assign a
dynamically selected priority value. This value can be specified as a
binary, decimal, or hexadecimal number, depending on the programming
language used.
Chapter 5.3.
Task control (DFHKC Kacro)
373
For Assembler language:
MVI TCATCDP,X'FF'
ASSIGN NEW PRIORITY VALUE
DFHKC TYPE=CHAP
CHANGE PRIORITY OF THIS TASK
For COBOL:
MOVE HIGH-VALUES TO TCATCDP.
NOTE ASSIGN NEW PRIORITY VALUE.
DFHKC TYPE=CHAP
CHANGE PRIORITY OF THIS TASK
For PL/!:
374
TCATCDP='11111111'B;
I*ASSIGN NEW PRIORITY VALUE*/
DFHKC·TYPE=CHAP
CHANGE PRIORITY OF THIS TASK
CICS/VS APRM (ML)
Synchronize a Task (TYPE=WAIT)
The format of the DFHKC macro instruction to synchronize the execution
of a task with the completion of an event, or to relinquish control to a
task of higher priority, is as follows:
r------r-------r------------------------------------------------------------,
~
I
I
I DFHKC I TYPE=WAIT
I
I [, DCI= {SINGLE I LIST I DISP I CICS} ]
I
I [,ECADDR=symbolic address]
I __________________________________________________________
_____ I'
L
~
The application programmer can synchronize a task with the completion
of an event or one of a list of events initiated by the same task or by
another task, or relinquish control to a task of higher dispatching
priority, by issuing the DFHKC TYPE=WAIT macro instruction. In the
first case, this macro instruction provides a method of directly
relinquishing control to some other task until the event being waited on
is completed. In the latter case, the task remains dispatchable. That
is, execution of the task is resumed if no task of higher priority is
ready to be processed.
The application programmer must specify the circumstances under which
synchronization of a task is to occur by including the DCI=keyword
operand (dispatch control indicator) •
If the task is to be synchronized with the completion of a single
event or an event in a list of events, the application programmer must
specify the symbolic address of either the single event control area or
the list of event control areas. The address can be specified by
including the ECADDR=symbolic address operand in the DFHKC TYPE=W1IT
macro instruction, or by coding a single instruction that place~ the
event control address in TCATCEA prior to issuing the DFHKC TYPE=WAIT
macro instruction. In either case, the referenced event control area(s)
must conform to the format and standard posting conventions of ECBs.
Examples showing how to post ECBs are given in the section "Initiate a
Task (AT'rACH)," earlier in this chapter. An event control area can also
be the timer event control area referred to in a DFHIC TYPE=POST macro
instruction.
(See the discussion of task synchronization in Chapter
5.2.) In a CICS/OS/VS system, if two tasks are allowed to wait on the
same event control area, CICS/VS may terminate abnormally.
The DFHKC TYPE=WAIT,DCI=SINGLE macro instruction is used by the
application programmer to synchronize a task with the completion of a
single event initiated by the same task or by another task.
The following example shows how to synchronize a task with a single
event, statically providing the symbolic address of the appropriate
event control area:
DFHKC TYPE=WAIT,
DCI=SINGLE,
ECADDR=EVENTCTL
Chapter 5.3.
RELINQUISH CONTROL OF CICSjVS
WAIT ON SINGLE EVENT
ADDRESS OF EVENT CONTROL AREA
Task Control (DFHKC Macro)
*
*
375
The following examples show how to synchronize a task with a single
event, dynamically providing the symbolic address of the appropriate
event control area.
For Assembler language:
ST
SINGADDR,TCATCEA
DFHKC TYPE=WAIT,
DCI=SINGLE
PLACE
SY~BOLIC
ADDRESS IN TCA
RELINQUISH CONTROL OF CICS/VS
WAIT ON SINGLE EVENT
*
For COBOL:
376
MOVE SINGADDR TO TCATCEA.
NOTE PLACE SYMBOLIC ADDR IN TCA.
DFHKC TYPE=WAIT,
DCI=SINGLE
RELINQUISH CONTROL OF CICS/VS
WAIT ON SINGLE EVENT
TCATCEA=SINGADDR;
/*PLACE SYMBOLIC ADDRESS IN TCA*/
/*SINGADDR IS A POINTER VARIABLE*/
DFHKC TYPE=WAIT,
DCI=SINGLE
RELINQUISH CONTROL OF CICS/VS
WAIT ON SINGLE EVENT
CICS/VS APRM
(aL)
*
*
The DFHKC TYPE=WAIT,DCI=LIST macro instruction is used by the
application programmer to synchronize a task with the completion of one
event of a list of events. This list consists of a series of contiguous
four-byte fields, each field containing the symbolic address of a single
event control area. The last four-byte field of the list contains
binary ones, hexadecimal IFF's, or the card code ~ultipunch) 12-11-0-18-9.
The following example shows how to synchronize a task with one of a
list of events, statically providing the symbolic address of the
appropriate list of events:
RELINQUISH CONTROL OF CICS/VS
WAIT ON ~ LIST OF EVENTS
ADDRESS OF LIST OF EVENTS
DFHKC TYPE=WAIT,
DCI=LIST,
ECADDR=TOPOLIST
*
*
The following examples show how to synchronize a task with one of a
list of events, dynamically providing the symbolic address of the
appropriate list of events.
For Assembler lanquagg:
ST
LISTADDR,TCATCEA
PLACE
SY~BOLIC
ADDRESS IN TCA
RELINQUISH CONTROL OF CICS/VS
WAIT ON A LIST OF EVENTS
DFHKC TYPE=WAIT,
DCI=LIST
*
For COBOL:
MOVE LISTADDR TO TCATCEA.
NOTE PLACE SYMBOLIC ADDR IN TCA.
DFHKC TYPE=WAIT,
DCI=LIS'r
RELINQUISH CONTROL OF CICS/VS
WAIT ON A LIST OF EVENTS
*
f2f:~1L!:
TCATCEA=LISTADDR;
/*PLACE SYMBOLIC ADDRESS IN TCA*/
/*LISTADDR IS A POINTER VARIABLE*/
DFHKC TYPE=WA IT,
DCI=LIST
RELINQUISH CONTROL OF CICS/VS
WAIT ON A LIST OF EVENTS
*
,Relin9,.Yish Control to a Task of-1!llher Prioriil
The DFHKC TYPE=WAIT,DCI=DISP macro instruction is used by the
application programmer to voluntarily relinquish control to a task of
higher dispatching priority. Control is returned to the-task issuing
the macro instruction if no other task of a higher priority is ready to
be processed.
Chapter 5.3.
Task Control
CDFHKC MaCro)
317
When binary synchronous communication lines are part of the user's
configuration, these lines may time out if excessive processor time is
required by an application program. One way to avoid this condition is
to include one or more DFHKC TIPE=WAIT,DCI=DISP macro instructions in
the application program to voluntarily relinquish control before the
line time-out can occur.
The following example shows how to voluntarily relinquish control to
a task of higher dispatching priority:
DFHKC TIPE=WAIT,
DCI=DISP
RELINQUISH CONTROL OF CICS/VS
AND REMAIN DISPATCHABLE
*
No~~:
The DFHKC TIPE=UAIT macro instruction differs from a TYPE=CHAP
macro instruction that does not indicate a priority in that the former
relinquishes control only to a task of higher priority, while the latter
may relinquish control to a task of either equal or higher priority.
378
CICS/VS APRM (ML)
Enqueue Upon a Resource (TYPE=ENQ)
The format of the DFHKC macro instruction to enqueue upon a resource,
causing execution of a task to be synchronized with the availability of
that resource, is as follows:
DFHKC
TYPE=ENQ[,COND=YESINO]
[,QARGADR=symbolic address]
[,QARGLNG=number]
In the CICS/VS environment, where tasks are processed concurrently,
it is sometimes desirable to protect a given resource from concurrent
use by multiple tasks. In effect, the resource can be treated as
serially reusable. To provide this resource protection, an installation
convention must be estaDlished for all application program4ers to
follow.
The convention is based on use of the DFHKC TYPB=ENQ macro
instruction, identifying the resource by a symbolic address or a
character-string argument. When executed, this macro instruction causes
further execution of the task issuing the instruction to be synchronized
with the availability of the specified resource; control is returned to
the task when the resource is available. When all tasks accessing a
resource adhere to the convention of enqueuing upon the resource, the
resource is afforded tlsingle-serverll protection.
When a single-server resource is being used by a task and other tasks
concurrently enqueue upon the same resource, the first task to issue the
DFHKC TYPE=ENQ macro instruction receives the resource when it becomes
available. The other tasks obtain the resource, in turn, in the order
in which they enqueue upon it.
For assembler-language application programs only, wh6n COND=YES is
specified, control is returned to the requesting transaction whether or
not the requested resource is availanlei task control places a return
code in TCATCTR indicating the result of the enqueue request. The
return codes and their meanings are:
TCATCOK
The requested resource has been given to the requestor
TCATCONQ
The requested resource is not available
TCADUPQ
The requestor already has the requested resource
COND=NO is the default, and when this is specified, either explicitly
or by default, the normal enqueue mechanism operates (that is, the
requestor is enqueued upon the resource if it is not immediately
available) •
Chapter 5.3.
Task control (DFHKC Macro)
379
~
When issuing the DFHKC TYPE=ENQ macro instruction, the application
programmer must identify the single-server resource he is enqueuing upon
by one of the following methods:
1.
Specify a symbolic main storage address that represents the singleserver resource. The application programmer must provide the
symbolic main storage address in the DFHKC TYPE=ENQ macro
instruction or by coding instructions (prior to issuing the DFHKC
TYPE=ENQ macro instruction) that place the address in the low-order
three bytes of TCATCQA, a ~our-byte field. He must place binary
zeros in the high-order byte.
2.
Specify a symbolic main storage address that contains a unique
character-string argument (for example, an employee name) that
represents the single-server resource. The unique argument may be
up to 255 bytes in length, beginning at the location pointed to by
the contents of the specified address. The application programmer
must provide the symbolic main storage address and the length in
the DFHKC TYPE=ENQ macro instruction or by coding instructions
(prior to issuing the DFHKC TYPE=ENQ macro instruction) that place
the symbolic address in the low-order three bytes of TCATCQA, a
four-byte field, and the length (in bytes) in the high-order byte.
CICS/VS task control makes a copy of this pointer in its storage
for use in controlling the resource.
380
CICS/VS APRM(aL)
Dequeue Upon A Resource (TYPE=DEQ)
The format of the DFHKC macro instruction to dequeue upon a resource
(effectively, to revoke a preceding enqueue request upon that resource)
is as follows:
DFHKC
TYPE=DBQ
[ ,QARGADR=symbolic address]
[,QARGLNG=number]
When issuing the DFHKC TYPE=DBQ macro instruction, the application
programmer must identify the resource he is dequeuing by the method that
was used in enqueuing. The COBOL programmer may find it convenient to
use the program control DFHPC TYPB=COBADDR macro instruction (see the
example below) if preloading of the address is desired.
If a task enqueues upon a resource but does not dequeue it, task
control automatically de queues the single-server protection request upon
termination of the task.
The following examples show how to enqueue upon a single-server
resource using method 1, above. Substituting "DEQ" for "ENQ" in these
examples illustrates the ways in which the application programmer can
release single-server protection from a resource prior to termination of
the associated task.
COpy DFHCSADS
DS
F
CSAWABA
DFHKC TYPE=ENQ,
QARGADR=CSAWABA
ENQ ON SINGLE-SERVER RESOURCE
SPECIFY SYMBOLIC ADDRESS
*
OR
LA
ST
WORKREG,CSAWABA
WORKREG,TCATCQA
DFHKC TYPE=ENQ
Chapter 5.3.
Task control (DFHKC Macro)
381
For COBOL:
01
DFHCSADS COpy DFBCSADS.
02 CSAWABA PIC X(50).
MOVE ZEROS TO TCATCQA.
DFHKC TYPE=ENQ,
QARGADR=CSAWABA
ENQ ON SINGLE-SERVER RESOURCE
SPECIFY SYMBOLIC ADDRESS
*
OR
DFHPC TYPE=COBADDR,
LABBL=CSAWABl
MOVE TCAPCLA TO TCATCQA.
*
DFHKC TYPE=ENQ
%INCLUDE DFBCSADS;
DECLARE 1 DFHEXCSA BASED (CSACBAR),
2 FILLER CHAR ~12),
2 CSAWABA CHAR (50);
DF HKC TYPE=ENQ,
QARGA DR=CSAWABA
ENQ ON SINGLE-SERVER RESOURCE
SPECIFY SYMBOLIC ADDRESS
*
OR
TCATCQA=ADDR(CSAWABA);
DFHKC TYPE=ENQ
The following examples show how to enqueue upon a single-server
resource using method 2. The resource to be enqueued upon is identified
by the nine-character social security number in a field labeled
SOCSECNO. Task control makes a copy of this field for its use in
controlling the resource.
Substituting "DEQ" for "ENQ" in these examples illustrates the ways
in which the application programmer can release single-server protection
from a resource prior to termination of the associated task.
For Assembler
lanqu~~:
DFHKC TYPE=ENQ,
QARGADR=SOCSECNO,
QARGLNG=9
OR
LA WORKREG,SOCSECNO
ST WORKREG,TCATCQA
MVI TCATCQAL,X'09'
382
CICS/VS APRM(ML)
*
*
DFHKC TYPE=ENQ
DFHKC TYPE=ENQ,
QARGADR=SOCSECNO,
QARGLNG=9
*
*
For PL/I:
DFHKC TYPE=ENQ,
QARGADR=SOCSECNO,
QARGLNG=9
*
*
OR
%INCLUDE DFHTCADS;
DECLARE 1 DFHEXTCA BASED (TCACBAR),
2 FILLER CHAR (20),
2 TCATCQAL BIT(S);
TCATCQA=ADDR(SOCSECNO);
TCATCQAL=I00001001 I B;
DFHKC TYPE=ENQ
Chapter 5.3.
Task Control (DFHKC Macro)
383
Declare a Task to be Purgeable (TYPE = PURGE)
The format of the DFHKC macro instruction to declare that a task may be
purged if a system stall condition occurs is as follows:
r------r--------~--------------------------------------------------·----------,
I
I
I
I
I DFHKC
I
L
TYPE=PURGE
I
certain overload conditions, where all of a given system resource
(for example, main storage) has been allocated and where each task
requires still more of that resource, can occur in CICS/VS. The result
is a situation in which no task is able to continue processing and no
new task can be initiated; the system stalls.
CICSjVS has the capability of detecting certain system stall
conditions and taking corrective action. Corrective action consists, in
part, of purging (deleting) the lowest priority task in the system that
is designated a.s stall purgeable.
A task is initially defined as purgeable or not purgeable in the
program control table (PCT) entry associated with the transaction
identification for that task. This ent~y is established by the system
programmer at system generation. The application programmer can
dynamically change the purgeability status of a task by issuing the
DFHKC TYPE=PURGE
macro instruction to indicate that the task is purgeable, or the
DFHK~
TYPE=NOPURGE
macro instruction to indicate that the task is not purgeable. The
designated status remains in effect for that task until another change
is initiated or until the task is terminated. For example, a longrunning task may issue a DFHKC TYPE=NOPURGE macro instruction prior to
critical processing, then issue a DFHKC TYPE=PURGE macro instruction
after that processing is completed. This ensures that the task is not
stall-purged during the critical processing.
Declare a Task to be Nonpurgeable (TYPE=NOPURGE)
The format of the DFHKC macro instruction to declare that a task cannot
be purged if a system stall condition occurs is as follows:
~-------r--------'-------------------------------------------------------------'
~
I
I DFHKC
_______ •I
TYPE=NOPURGE
L__________________________________________________________
~
Note: The PURGE and NOPURGE options of the DFHKC macro are intended to
be used as temporary overrides to the SPURGE specification in the DFHPCT
TYPE=ENTRY macro for a task. For example, if a DFHKC ·rYPE=NOPURGE macro
is issued in a program for a task, the task cannot be purged even though
SPURGE=YES is specified in the DFHPCT TYPE=ENTRY macro for the task at
384
CICS/VS APRM(ML)
system generation. Refer to the publication CICS/yS System PrQg~r's
Reference Manual for details about the SPURGE option of the DPHPCT
TYPE=ENTRY macro.
Chapter 5.3.
Task Control (DFHKC Macro)
385
Operands of DFHKC Macro
COND=
specifies whether or not an enqueue is to be conditional
(assembler language only).
YES
the enqueue request is conditional~ Control is returned to
the requestor whether or not the requested resource is
available. A return code at TCATCTR indicates the result
of the request:
TCATCOK
TCATCONQ
TCADUPQ
The resource has been given to the requestor
The resource is not available
The requestor already has the resource
NO
the enqueue is not conditional. If the requested resource
is not immediately available, the requesting transaction
will be enqueued upon it. COND=NO is the default.
DCI=
specifies when synchronization is to occur.
SINGLE
indicates that the task is to be synchronized with the
completion of a single event.
LIST
indicates that the task is to be synchronized with the
completion of one event in a list of events.
indicates that the task wishes to give up control to any
higher priority task that is ready to be processed; if none
exists, control is to be returned to this task.
CICS
•
CICS/OS/VS only and assembler language only
indicates that the ECB will be posted by another
transaction rather than by the operating system. This
option means that the ECB will not be added to the
operating system WAIT macro issued by CICS/VS. ECBs to be
posted by other transactions should reside in permanent
storage.
Tasks that wish to synchronize with each other as
illustrated in figure 5.3-1, may do so by using either
DCI=CICS or DCI=SINGLE (CICS/DOS/VS must use DCI=SINGLE
only). DCI=CICS must be used if more than one
synchronizing task is going to wait on the same ECB. In
all other cases it is preferable to use DCI=SINGLE.
386
CICS/VS APRM(ML)
ECADDR=symoolic address
is used with DCI=SINGLE or DCI=LIST to specify the symbolic
address of the single event control area or list of event
control areas identifying the event with which this task is to
be synchronized; if omitted when SINGLE or LIST is specified,
the address is assumed to be in TCATCEA.
FCADDR=symbolic address
is the symbolic address of the facility control area (FCA)
associated with this task; if omitted, the address is assumed
to be in TCAKCFA.
PRTY=priority value
is a decimal numeral in the range from 0 through 255 to be
taken as the priority value for this task; if omitted, the
priority value is assumed to be in TCATCDP.
QARGADR=symbolic address
is either the symbolic address of the resource to be enqueued
or dequeued, or the symbolic address of a location that
contains a unique argument (for example, an employee name) that
represents the resource. If this operand is omitted, the
address is assumed to be in the three low-order bytes of
TCATCQA, a four-byte field.
QARGLNG=number
is the length, in bytes, of the resource to be enqueued upon or
to be dequeued. This operand is needed only if the QARGADR
operand is a unique argument that represents the resource to be
enqueued. If omitted in such a case, the contents of the highorder byte of TCATCQA are assumed to be the length of the
argument. COBOL programs must not use this operand unless the
QARGADR operand is used.
TRANSID=name
is the transaction identification for the task; if omitted, the
transaction identification is assumed to be in TCAKCTI.
Chapter 5.3.
Task Control (DFHKC Kacro)
387
Chapter 5.4. Program Control (DFHPC Macro)
All program communication within CICS/VS is accomplished by program
management. The program management macro instruction (DFHPC) is used to
request any of the following services:
•
Link one user-written application program to another, anticipating
subsequent return to the requesting program (TYPE=LINK).
•
Transfer control from one user-written application program to
another, anticipating no return to the requesting program
(TYPE=XCTL) •
o
Load a designated application program, table, or map (generally,
for use with basic mapping support) into main storage and return
control to the requesting program (TYPE=LOAD).
•
Return control from one user-written application program to another
or to CICS/VS (TYPE=RETURN).
o
Delete a previously loaded application program from main storage
(TYPE=DELET E) •
•
Abnormally terminate a transaction and its related task
(TYPE=ABEND) •
•
Activate, cancel, or reactivate an exit that permits user-uritten
abnormal termination processing (TYPE=SETXIT or TYPE=RESETXIT) •
•
Convert a symbolic label in a COBOL program into an address which
is returned in TCAPCLA (TYPE=COBADDR).
Application programs running under CICS/VS are executed at various
logical levels. For example, where one user-written application program
is linked to another, the linked-to program is considered to reside at
the next lower logical level.
Where control is simply transferred from
one application program to another, the two programs are considered to
reside at the same logical level. A DFHPC TYPE=LINK macro instruction
is used for the former; a DFHPC TYPE=XCTL macro instruction (where XCTL
means transfer control) is used for the latter.
Figura 5.4-1
illustrates this difference between program linkage and transfer of
program control. Each of the programs shown in this figure may have
been written in any of the CICS/VS-supported languages (Assembler
language, COBOL, and PL/I). Use of LINK, XCTL, RETURN, and ABEND is
explained in greater detail below.
Tasks can share the use of common work areas. However, each task
requires the use of a unique intermediate storage area, such as the
transaction work area (TWA), to retain information needed upon
SUbsequent return to that task. The application programmer must provide
addressability to that intermediate storage area by symbolically
defining it in his program.
Parameters can be passed from one program to another in the same task
through user-defined storage areas, for example, the transaction work
area (TWA), the terminal input/output area (TIOA), the terminal control
table terminal entry ~CTTE), or the file work area (FWA).
CICS/VS automatically saves program control information and generalpurpose registers, when applicable, in the task control area (TCA).
CICS/VS automatically restores general-purpose registers, as necessary,
Chapter 5.4.
Program Control (DFHPC Macro)
389
to return control to a program. The name of any program referred to in
a request for program services must have been placed in the processing
program table (PPT) prior to execution of CICS/VS.
!
CICS/vS
Program
Control
I
t
---.
Application
Program
A
LINK
/" ~
RETURN
XCTL
~
-.
Application
Program
Application
Program
LINK
C
B
-
f-
. /~
XCTL
RETURN
~
Appl i cati on
Program
Appl ication
Program
D
E
-
RETURN
Figure 5.4-1.
390
Logical Relationship of Application Programs
CICS/VS APRM(ML)
Pass Program Control Anticipating Return (TYPE=LINIC)
The format of the DFHPC macro instruction to pass control to an
application program at the next lower logical level is as folIous:
DFHPC
TYPE=LINK
[ ,PROGRAM=name ]
[ , COND=YES ]
[,NORESP=symbolic address]
[,PGMIDER=symbolic address]
When a DFHPC TYPE=RETURN macro is executed in the linked-to program,
control is returned to the first program at the next sequential
~xecutable) instruction.
The application programmer must specify the name of the program to
which control is to be passed in the PROGRAM operand or in a single
instruction that places the program name in TCAPCPI prior to issuing
this macro instruction. The COND operand specifies that control vill be
returned to the first program if the specified program is disabled or
its name cannot be found in the PPT.
The following example shovs hoy to request a link to an application
program:
DFHPC TYPE=LINK,
PROGRAM=PROG1
*
The following examples shou how to link to an application program
specified by an instruction executed prior to DFHPC TYPE=LIUK.
For Assembler language:
MVC
TCAPCPI ,=CL8 'PROG1'
DFHPC TYPE=LINK
PLACE LINKED-TO PROGRAH lIAHE In TCA
LINK TO PROGRAH AT nEXT LOIIER LEVEL
For COBOL:
MOVE 'PROG1' TO TCAPCPI.
NOTE LINKED-TO PROGRAM NAME TO TCA.
J
DFHPC TYPE=LINK
LINK TO PROGRAM AT NEXT LoaER LEVEL
TCAPCPI= 'PROG1';
/*PLACE LINKED-TO PRGH NAHE IN TCA*/
DFHPC TYPE=LINK
LINK TO PROGRAM AT NEXT LOUER LEVEL
Chapter 5.4.
Program Control (DFHPC Macro)
391
Transfer Program Control (TYPE=XCTL)
The format of the DFHPC macro instruction to pass (transfer) control to
an application program at the same logical level is as follows:
r------~-------~----------------------------------------------------------~
I
I
I
,I
DFHPC
TYPE=XCTL
[ ,PROGR Aii=name ]
This macro specifies that program control is transferred from one
user-written application program to another at the same logical level.
The program from which control is transferred is released. Any return
from the transferred-to program is to a program from which there was an
exit at the next higher logical level. If there is no user-written
application program at the next higher logical level, control is
returned to CICS/VS.
.
The application programmer must specify the name of the program to
which control is to be transferred in the PROGRAM operand or in a single
instruction that places the program name in TCAPCPI prior to issuing
this macro instruction. The field TCAPCPI is eight bytes in length. If
the program name is less than eight bytes, the field must be padded on
the right with blanks.
The following example shows how to request a transfer of control to a
particular application program:
DFHPC TYPE=XCTL,
PROGRAM=PROG2
*
The following examples show how to transfer control to an application
program specified by an instruction executed prior to DFuPC TYPE=XCTL.
For Assembler language:
MVC
TCAPCPI,=CLSIPROG2 1
PLACE TRANSFERRED-TO PRGM NAME IN TCA
DPHPC TYPE=XCTL
TRANSFER PROGRAM CONTROL
MOVE IPROG2 1 TO TCAPCPI.
NOTE TRANSFERRED-TO PRGM NAME TO TCA.
DFHPC TYPE=ICTL
TRANSFER PROGRAM CONTROL
For PL/I:
TCAPCPI=IPROG2 1
;
/*PLACE PROGRAM NAME IN TCA*/
DFHPC TYPE=ICTL
392
CICS/VS APRM(ML)
TRANSFER PROGRAM CONTROL
Load a Program (TYPE=LOAD)
The format of the DFHPC macro instruction to load a program, table, or
map from its location in a CICS/VS program library is as follows:
r------r-------r----------------------------------------------------------,
I
I
I
I
I
I
I
I
.L
I
DFHPC I TYPE=LOAD
I [ ,PROGRAM=name]
I [ , LOADLST=NO]
I [ ,COND=YES]
I [,NORESP=symDolic address]
I [,PGMIDER=symbolic address]
IL __________________________________________________________
~
This macro specifies that programs, tables, or maps are to be fetched
from the library where they reside and loaded into main storage. This
facility is used to (1) load a program that will De used repeatedly,
thereby reducing system overhead through a one-time load, (2) load a
table to which control is not to be passed, or (3) load a map to be used
in a mapping operation (see Chapter 4.3). CICS/VS returns the address
of the loaded program in TCAPCLA.
The loaded program remains in main storage until the DFHPC
TYPE=DELETE macro instruction is issued or until the task that issued
the DFHPC TYPE=LOAD is terminated, either normally or abnormally (unless
LOADLST=NO is specified). If LOADLST=NO is specified, the loaded
program remains resident until it is deleted by this, or another, task.
The application programmer must provide the name (identification) of
the program to be loaded in the DFHPC TYPE=LOAD macro instruction or in
a single instruction that places the program name in TCAPCPI prior to
issuing the DFHPC TYPE=LOAD macro instruction.
The following example shows how to load a user-written application
program:
DFHPC TYPE=LOAD,
PROGRAM=PROG3
The follo~ing examples show how to load an application program
specified dynamically by an instruction executed prior to DFHPC
TYPE=LOAD.
For Assembler language:
MVC
TCAPCPI,=CLS'PROG3'
PLACE PROGRAM NAME IN TCA
DFHPC TYPE=LOAD
LOAD THE SPECIFIED PROGRAM
MOVE 'PROG3' TO TCAPCPI.
NOTE PLACE PRGM NAME IN TCA.
DFHPC TYPE=LOAD
LOAD THE SPECIFIED PROGRAM
Chapter 5.4.
Program Control (DFdPC Macro)
393
For PL/I:
394
TCAPCPI=' PROG3';
/*PLACE PROGRAM NAME IN TCA*/
DFHPC TYPE=LOAD
LOAD THE SPECIFIED PROGRAM
CICS/VS APRM (KL)
Return Program Control (TYPE=RETURN)
The format of the DFHPC macro instruction to return control from an
application program to the program at the next higher logical level is
as follows:
r------~-------r------------------------------------------------------------,
I
I
I
IL_______
I
DFHPC I
I
~
TY PE=R ET URN
[,TRANSID=transaction code]
_______ ILI_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
~
When this macro instruction is executed in a lower level (linkea-to)
program, it restores the registers of the higher level (linked-from)
program to their contents at the time the DFHFC TYPE=LINK was issued and
releases save areas for the lower-level program. In general, the
program to which control is returned must have relinquished control by
execution of a DFHPC TYPE=LINK macro instruction and must reside one
logical level higher than the program returning control. Upon normal
termination of transaction processing, control is returned to CICS/VS.
If no default transaction code has been assembled into the terminal
control table terminal entry (TCTTE) for a particular terminal, the
application programmer can specify the transaction identification for
the next program to be associated with that terminal in either of two
ways:
(1) by including the desired transaction identification in the
DFHPC TYPE=RETURN macro instruction, or (2) by coding a single
instruction that places the desired transaction identification in
TCANXTID prior to issuing the DFHPC TYPE=RETURN macro instruction. By
doing so, the programmer ensures that subsequent unsolicited input can
be entered from the terminal without the specification of a transaction
identification. A flexible means of starting the next task is thus
provided.
Note, however, that the methods of specifying the transaction
described above may be overridden by issuing BMS paging commands.
(See
ItTerminal-Oriented Task Identification," in Chapter 4.2, for a precise
description .)
Chapter 5.4.
program Control
~FHPC
Macro)
395
Delete a Loaded Program (TYPE=DELETE)
The format of the DFHPC macro instruction to delete a previously loaded
program is as follows:
r----------------------------------------------------------,
I
DFHPC I
I
I
TIPE=DELETE
[,PROGRAM=name]
~-----~------_~I--------------------------------------------------------~
This macro specifies that a program previously loaded through use of
the DFHPC TIPE=LOAD macro instruction with or without the LOADLST=NO
operand is to be deleted. If the DFHPC TIPE=LOAD macro instruction
contained LOADLST=NO, the loaded program is deleted only in response to
a DFHPC TYPE=DELETE macro instruction. If LOADLST=NO is not specified,
the loaded program can be deleted by a DFHPC TYPE=DELETE request, or it
will be automatically deleted when the task that issued the load request
is terminated.
The application programmer must specify the name (identification) of
the program to be deleted in the DFHPC TIPE=DELETE macro instruction or
in an instruction that places the program name in TCAPCPI prior to
issuing the DFHPC TYPE=DELETE macro instruction.
The following example shows how to delete a user-written application
program loaded in response to a DFHPC TYPE=LOAD macro instruction.
DFHPC TYPE=DELETE,
PROGRAM=PROG4
The following examples show how to dynamically delete an application
program loaded in ~esponse to a DFHPC TYPE=LOAD macro instruction.
For Assembler
MVC
la~~:
TCAPCPI,=CLS'PROG4'
DFHPC TIPE=DELETE
PLACE PROGRAM NAME IN TCA
DELETE THE SPECIFIED PROGRAM
£:or COBOL:
MOVE 'PROG4' TO TCAPCPI.
NOTE PLACE PRGM NAME IN TCA.
DFHPC TYPE=DELETE
DELETE THE SPECIFIED PROGRAM
For PL/I:
396
TCAPCPI='PROG4';
/*PLACE PROGRAM NAME IN TCA*/
DFHPC TIPE=DELETE
DELETE THE SPECIFIED PROGRAM
CICS/VS APRM(ML)
Abnormally Terminate a Transaction (TYPE=ABEND)
The format of the DFHPC macro instruction to abnormally terminate a
transaction (task) is as follows:
r------r-
.r----------------------------------------------------------,
I
I
I
I
I
I
I DFHPC I
I
I
I
I
I
I
I
I
TYPE=ABEND
[,ABCODE={valueIYES} ]
[ ,CANCEL=YES]
IL________________________________________________________
~
This macro specifies that a transaction and its related task is to be
terminated abnormally. If a task is attached by another task, only the
task that issues the ABEND is terminated.
The main storage associated
with the terminated transaction is released. If CANCEL=YES is
specified, all exits established by DFHPC TYPE=SETXIT macro instructions
at any level in the task are canceled.
The application programmer can request a dump of main storage related
to the terminated transaction. The request must specify a fourcharacter abnormal termination code that dump control will place in the
formatted storage dump to identify the ABEND condition. This code can
be specified in either of two ways:
1.
It can be specified in the TYPE=ABEND macro instruction, as
follows:
DFHPC TYPE=ABEND,
ABCODE=1234
2.
It can be placed in TCAPCAC before issuing the macro instruction,
as follows:
For Assembler language:
MVC
TCAPCAC,=CLij'1234'
DFHPC TYPE=ABEND,
ABCODE=YES
PLACE TERMINATION CODE IN TCA
TERMINATE PGRM, TRANS, & TASK
USE ABCODE ALREADY SPECIFIED
*
For COBOL:
MOVE '1234' TO TCAPCAC.
NOTE TERMINATION CODE TO TCA.
DFHPC TYPE=ABEND,
ABCODE=YES
TERMINATE PGRM, TRANS, & TASK
USE ABCODE ALREADY SPECIFIED
Chapter 5.4.
Program Control (DFHPC Macro)
*
397
For PLtI:
TCAPCAC=11234 1 ;
I*PLACE TERMINATION CODE IN TCA*/
DFHPC TYPE=ABEND,
ABCODE=YES
TERMINATE PGRM, TRANS, & TASK
USE ABCODE ALREADY SPECIFIED
*
!Qte: The DFHPC macro will preserve the original contents of the two
bytes starting at TCAPCTR by moving them to TCACCSV1. Thus a dump will
contain the response codes from the last CICS/VS service call. If
ABCODE (but not ABCODE=YES) is specified, the original contents of
TCAPCAC will also be preserved in TCACCSV2. If ABCODE=YES is specified,
and you wish the original contents of TCAPCAC to appear in the dump,
they must be stored elsewhere before you store the ABEND code there.
It
is therefore preferable to use method 1 above when specifying a dump
code.
398
CICS/VS APRM
~L)
Activate or Cancel an Exit for Abnormal Termination Processing (TYPE=SETXIT)
The format of the DFHPC macro instruction to activate or cancel an exit
to a user-written routine or program to be executed upon abnormal
termination of a task is as follows:
r------r-
I
r- ----------------------------------------------------------,
I
I
I DFHPC I
I
I
I
I
I
I
f
I
I
I
I
I
I
I
I
I
I
IL_
TYPE=SETXIT
[,PROGRAM={nameIYES} ]I[,ROUTINE={symbolic
addressIYES})
[,NORESp=symbolic address]
[ ,PGHIDER=symbolic address]
________________________________________________________~
This macro specifies that a user exit is to be:
1.
Activated, if the PROGRAM or ROUTINE operand is specified
2.
Canceled, if no additional operands are specified
During abnormal termination of a task, a program-level ABEND exit
facility is provided in CICS/VS program control so that a user-uritten
exit routine can be executed if desired. One example of a function
performed by such a rout ine is the "clean-up" of a program tha t has
started but not completed normally. An ABEND exit within an application
program is activated in response to the DFHPC TYPE=SETXIT macro
instruction. The application programmer must specify the name of a
program, or (for Assembler-language and COBOL programs) the address of a
routine, to be given control when an abnormal termination condition
occurs. The program name or routine address can be specified in the
DFHPC TYPE=SETXIT macro, or placed in the appropriate field in the TCA
before the macro is issued. A program name is placed in TCAPCPI; a
routine address is placed in TCAPCERA. The PROGRAM and ROUTINE operands
are mutually exclusive.
A DFHPC TYPE=SETXIT macro instruction in which a program or routine
name is specified overrides (effectively, replaces) any preceding DFHPC
TYPE=SETXIT macro instruction in any application program at the same
logical level. (Logical levels are illustrated in Figure 5.4-1.) Thus,
each application program of a transaction can have its own exit, but
only one exit at each logical level can be active. To cancel a
previously established exit at the logical level of the application
program in control, the application programmer can issue a DFHPC
TYPE=SETXIT macro instruction in which neither the program name nor the
routine name operand is specified.
When a task ABEND occurs, CICS/VS searches for an active exit,
starting at the logical level of the application program in which the
ABEND occurred, and proceeding, i f necessary, to successively higher
levels. The first active exit found, if any, is given control. This
procedure is shown in Figure 5.4-2, which also shows how subsequent
ABEND exit processing is determined by the user's exit routine or
program.
Chapter 5.4.
Program Control
~FHPC
Macro)
399
Task ABEND
- -
--,
I Action taken
_-"'"T-r--=-_A"T"B..,.E_N_D_ I in ex it program
__ J or routine
Figure 5.4-2.
ABEND Exit Processing
Note: When a DFHPC TYPE=XCTL macro is to be used to transfer control
from an application program, there is a potential problem if an exit
routine (rather than a program) has been specified within that
application program, and the exit for the routine is still active when
control is transferred. If, later, a short-on-storage condition occurs,
the storage occupied by the application program may be re-used, and any
attempt to refer to the re-used storage, as a result of a subsequent
task ABEND, will have unpredictable results. This situation will not
occur if an exit program is specified, instead of a routine. Routines
can be used without risk in .application programs that do not use a DFHPC
TYPE=XCTL macro.
To prevent recursive ABENDs in an exit routine, CICS/VS deactivates
an exit upon entry to the exit routine. If attempting a retry of the
operation, the programmer can branch to a point in the program that was
in control at the time of the ABEND and issue the DFHPC TYPE=RESETXIT
macro instruction to reactivate the exit. The user can also use this
macro instruction to reactivate an exit that was canceled previously as
described above. No additional parameters are required.
Upon entry to an exit program, no addressability can be assumed other
than that normally assumed for an application program coded in the
400
CICS/VS APRM (ML)
language.
If the exit logic is in the form of a routine, the amount of
addressability varies with the source language, as detailed under
"creating a Tas}c ABEND Exit" in the CICS/VS System Programller's
Reference Han.Ytl. For additional information concerning preparation of
the exit routine, see that manual.
The follouing example shows how to establish a program as an exit:
DFHPC
TYPE=SETXIT,PROGRAM=EXITPGM
The follouing examples show how to establish a program as an exit by
dynamically storing the program name prior to executing the DFHPC
TYPE=SETXIT macro instruction.
HVC
TCAPCPI,=CLS'EXITPGM'
DFHPC TYPE=SETXIT,PROGRAM=YES
For COBOL:
HOVE
'EXITPGM' TO TCAPCPI.
DFHPC TYPE=SETXIT,PROGRAM=YES
For PL/I:
TCAPCPI=IEXITPGMI;
DFHPC TYPE=SETXIT,PROGRAM=YES
The following examples show how to establish a routine as an exit by
dynamically storing the address of the routine prior to executing the
DFHPC TYPE=SETXIT macro instruction.
(Note that routines cannot be
established as exits in PL/I application programs.)
For Assembler language:
LA
ST
14 , EX IT RTN
14,TCAPCERA
DFHPC TYPE=SETXIT,ROUTINE=YES
For COBOL:
DFHPC TYPE=COBADDR,LABEL=EXITRTN
MOVE TCAPCLA TO TCAPCERA.
DFHPC TYPE=SETXIT,ROUTINE=YES
Chapter 5.4.
Program Control (DFHPC
~acro)
401
Reactivate an Exit for Abnormal Termination Processing (TYPE=RESETXIT)
The format of the DPHPC macro instruction to reactivate an exit to a
user-written routine or program to be executed upon abnormal termination
of a transaction (task) is as follows:
DPHPC
TYPE=R ESETXIT
This macro specifies that an exit to user-written abnormal
termination processing is to be reactivated after a preceding
application program cancellation or CICS/VS cancellation upon execution
of the exit routine.
402
CleS/VS APRM
~L)
Convert Symbolic Label to Address (TYPE=COBADDR)
The format of the DFHPC macro instruction to convert a symbolic label
appearing in a COBOL program to an address is as follows:
DFHPC
TYPE=COBADDR
,LABEL=symbolic label
This macro specifies that the address of the location represented by
a symbolic label is to be returned in TCAPCLA to the application
program. The first byte of TCAPCLA can be non-zero, and should
therefore be initialized if necessary.
A comparable facility is availaole within both PLjI and Assembler
language; this macro instruction is designed to provide the capability
for COBOL programmers. COBOL support must have been generated within
CICS/VS to support COBOL programs.
Chapter 5.4.
Program Control (DFHPC Macro)
403
Test Response to a Request for Program Services (TYPE=CHECK)
The format of the DFHPC macro instruction to test the CICS/VS response
to a request for program management services is as follows:
DFHPC
~
_____
~
TYPE=CHECK
[,NORESP=symbolic address]
[,PGMIDER=symbolic address]
_______ L ______________________________________.____________________
~
Program Control Response Codes
To test the response code the application programmer must know (1) the
CICS/VS response codes and their meanings, and (2) the symbolic label by
which he can refer to the response code. If the Assembler-language or
PL/I programmer elects to check for a particular response-code bit
pattern, he can access the response code at TCAPCTR. The COBOL
programmer who elects to check for a particular response-code bit
pattern can access the response code at TCAPCRC. The possible response
codes and the conditions to which they correspond are identified in the
right-hand columns of Figure 5.4-3. DFHPC macro instructions for which
the conditions are applicable are shown at the left.
r
, Program
,Services Request
, by DFHPC Macro
I Instruction
,
1
I
1
Condition
1
Response Code
1----------------------------------1
IAssemblerl COBOL
PL/I
I
-----------------------------------------------------------------------1
LINK,LOAD,
NORESP
LOW-VALUES , 00000000
SETXIT,CHECK
(Normal response)
LINK ,LOAD,
SETXIT,CHECK
PGMIDER
(Program iden tification error)
(PCARCNR)
1
1
X' 0 l'
12-1-9
, 00000001
(PCPGMIDER) I
I
I
Note:
The names enclosed in parentheses in the COBOL column indicate
the condition names generated by CICS/VS. These-names may be used
in testing for the conditions in a COBOL program.
Figur,e 5.4-3.
Program Control Response Codes
Note: Because the multipunch codes to be checked in a COBOL program
commonly correspond to unprintable characters, an alternative facility
is provided in CICS/VS for use by the COBOL programmer. In COBOL the
response code can be referred to by a condition name, formed as a twocharacter identification of the CICS/VS management module providing the
requested service, followed by the keyword for the condition being
checked (for example, PCNORESP). Use of this approach is illustrated in
the examples at the end of this discussion.
To provide for the possibility of failure to find a requested program
in the processing program table (PPT), or finding a disabled program in
response to DFHPC TYPE=LINK or TYPE=LOAD, the COND operand must be
404
CICS/VS APRM(ML)
included in these macros. This operand causes control to be passed to
the user-specified exception-handling routine specified in the PGHIDER
operand if the error occurs. If the COND operand is not specified and
the error occurs, the requesting program is apnormally terminated uith
an APCT ABEND code.
The following examples show how to'examine the response code provided
by CICS/VS at TCAPCTR (for Assembler language or PL/I) or TCAPCRC (for
COBOL) and transfer control to an appropriate user-written errorhandling routine. The alternative approach available to COBOL
program~ers is also shown.
For Assembler language:
DFHPC
GOOD
CLI
BE
DFHPC
DS
TYPE=SETXIT,
PROGRAM=MYPROG
TCAPCTR,X·OO·
GOOD
TYPE=ABEND
OB
*
NORMAL RESPONSE
TYPE=SETXIT,
PROGRAM=MYPROG
IF TCAPCRC = • • THEN GO TO GOOD.
DFHPC
TYPE=ABEND
*
DFHPC
NOTE 12-0-1-8-9 NORESP.
GOOD.
Alternatively, the COBOL programmer may test responses by using the
CICS/VS generated condition names.
IF PCNORESP THEN GO TO GOOD.
For PL/I:
DFHPC
TYPE=SETXIT,
PROGRAM=MYPROG
IF TCAPCTR=IO·B THEN GO TO GOOD;
DFHPC
TYPE=ABEND
*
/* NORMAL RESPONSE */
GOOD:
Chapter 5.4.
Program Control (DFHPC aacro)
405
Operands of DFHPC Macro
ABCODE=
indicates that main storage related to the transaction is to be
dumped and prov1des a four-character abnormal termination code
to identify the output dump.
value
is a combination of four alphabetic, numeric, and/or
special characters to be printed as the abnormal
termination code.
YES
indicates that the abnormal termination code has been
placed in TCAPCAC.
Note: If a dump is requested, any information in the common
control area of the application program communication section
of the TCA is likely to be different in the dump. The DFHPC
TYPE=ABEND macro preserves the original contents of the
overwritten fields in the TCA by moving the tHO bytes starting
at TCAPCTR to TCACCSV1.
If an explicit abnormal termination
code is specified, the macro viII also move the original
contents of TCAPCAC to TCACCSV2.
If ABCODE=YES is specified,
and the original contents of TCAPCAC are required in the dump,
the information must be stored elsewhere before storing an
abnormal termination code there. If the ABCODE operand ·is not
specified, the macro does not use the TCAPCAC field.
CANCEL=YES
indicates that all exits established by DFHPC TYPE=SETXIT macro
instructions at any level in the task are to be canceled; in
effect, they are ignored.
COND=YES
indicates that control is to be returned to the program issuing
the macro instruction if the program specified in the PROGRAM
operand cannot be found in the PPT or is disabled. If this
operand is omitted and the requested program cannot be found or
is disabled, the task is abnormally terminated with the ABEND
code "A PCT II •
LABEL=symbolic label
is the symbolic label that represents the location in the COBOL
program for which the address is required.
LOADLST=NO
indicates that the loaded module is not to be deleted when the
task issuing the load request is terminated; that is, the
loaded module remains resident until deleted at the request of
this task or of another task.
NORESP=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if no errors occur during program
control processing. NORESP signifies "normal response. 1I
406
CICS/VS APRM (ML)
PGMIDER=sy£bolic address
specifies the entry label of the user-uritten routine to which
control is to be passed if the requested program cannot be
found in the PPT or is disabled. Control will not be passed
unless the COND operand is specified also in the TYPE=LINK or
TYPE=LOAD macros, or unless the PROGRAM operand is specified
also in the TYPE=SETXIT macro.
PROGRAM=name
is the name of the program to lIhich control is to be passed or
the name of the program, table, or map to be loaded; if
omitted, the name is assumed to be in TCAPCPI. TCAPCPI is an
eight-character field; names less than eight characters must be
padded right with blanks. If the requested program cannot be
found or is disabled, the task is abnormally terminated with
the ABEND code "APCTIt.
For the TYPE=SETXIT macro only, PROGRAM=name specifies the
name, in the PPT, of the program to receive control if abnormal
termination occurs. PROGRAM=YES specifies that the name of the
program to receive control has been placed in TCAPCPI.
ROUTINE=
identifies the routine to receive control if abnormal
termination occurs.
(This operand applies only to Assemblerlanguage and COBOL programs.)
There is a risk involved in the use of this operand if the
application program transfers control using a DPHPC TYPE=XCTL
macro. The occurrence of a short-on-storage condition could
lead to the storage used by this application program being reused, and any reference to the re-used storage ~10uld have
unpredictable results.
symbolic address
is the symbolic address of the routine to receive control.
YES
indicates that the address of the routine to receive
control has been placed in TCAPCERA.
TRANSID=transaction code
is the transaction identification to be used with the next
input message entered from the terminal with which this
requesting task has been associated prior to this request for
return of control.
Chapter 5.4.
Program Control
(DFHPC Macro)
401
Chapter 5.5. Storage Control (DFHSC Macro)
storage
written
storage
storage
management controls all main storage for CICS/VS and for userapplication programs. Requests to acquire or release main
are communicated to CICS/VS storage control by means of the
management macro instruction (DPHSC).
CICSjVS management programs automatically issue requests for main
storage to provide input/output areas, program load areas, and userdefined work areas needed to process a task. An application program can
also issue requests for main storage to provide intermediate work areas
and any other main storage area not automatically provided by CICS/VS
but needed to process a task. Main storage acquired by an application
program can be initialized to any bit configuration, for example, binary
zeros or EBCDIC blanks.
Main storage associated with a task is controlled and accounted for
by CICS/VS. This allows CICS/VS to release all main storage associated
with a task upon request or when the task is normally or abnormally
terminated. Main storage is account8d for as follows:
•
Task control areas (TCAs) are accounted for through pointers in the
dispatch control areas (DC As). The DCAs are chained from the
common system area (CSA).
•
Task storage is chained off the task control area
•
Terminal storage is chained off the TCTTE (the TCTTESC field is the
origin of the terminal input/output area (TIOA) chain; the TCTTEDA
field contains the address of the current TIOA regardless of the
position of that TIOA on the chain).
•
Program storage is accounted for in the processing program table
(TCA).
(PPT) •
•
Suspended tasks are accounted for by the suspending CICS/VS
management program (task control, storage control, or temporary
storage control).
If there is insufficient main storage to satisfy a storage
acquisition request, TCASCSA is filled with binary zeros. All activity
within the task is suspended until sufficient dynamic storage becomes
available and its address is placed in TeASCSA, unless the application
programmer has specified in his request that control is to be returned
to the application program. Lack of storage will cause a short-onstorage condition. The initiation of new tasks is restricted by CICS/VS
until the short-on-storage condition is alleviated. Normally, this
occurs as a result of some other task releasing storage currently
reserved for it.
(See IIDeclare a Task to be Purgeable ll in Chapter 5.3.,
for corrective action that can be taken if the snort-on-storage
condition continues.)
Chapter 5.5.
Storage Control
(DPHSC Macro)
409
Obtain and Initialize Main Storage
(TYPE=GETl\~AIN)
The format of the DFHSC macro instruction to obtain main storage and
initialize the area obtained, if required, is as follows:
r------r-------r---------------------------'---------------------------------
I
i
,
DFHSC
I
I
I
IL______
L -_ _ _ _ _ _ _
TY PE=G E'r HIt IN
[,INITIMG={numberIYES} ]
[,NUHBYTE=number]
[,COND={YESI (YES,symbolic addr) I (NO,symbolic addr)}]
(,CLASS={TERMINALIUSERITRANSDATAITEMPSTRG} ]
~
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~
This macro instruction is used to obtain main storage of a specified
size and class and, optionally, to initialize that storage to a
specified bit configuration. The address of the storage area obtained
is placed in TCASCSA on a doubleuord boundary by CICS/VS. TERMINAL,
TRANSDATA, and TEMPSTRG can be abbreviated to TERM, TD, and TS
respectively.
When using this macro instruction, the application programmer should:
o
Check whether any existing storage that is no longer required by
the task should be released, to avoid causing a short-on-storage
condition to occur, or if it may be left for CICS/VS to release
when the task is terminated.
•
Specify the class of storage required using the CLASS operand.
o
Calculate the number of bytes required and either specify that
amount in the NUMBYTE operand, or place it in TCASCNB, in binary
form, before issuing the DFHSC macro instruction. A zero data
length is not allowed for a DFHSC TYPE=GETMAIN macro instruction.
o
Specify the COND operand if control is to be returned to the
application program, irrespective of whether the requested storage
has been acgu~lired or not ..
o
Specify a symbolic base address for the storage area.
o
Hove the storage address located at TCASCSA to the symbolic Oase
address.
(This address points to the storage accounting area of
the storage area.)
o
Copy the symbolic storage definition for the appropriate
input/output area or storage accounting area Erio~ to the symbolic
definition of the user's program storage area.
The following example shoHS hOH to request a 1024-byte area of main
storage:
DFHSC TYPE=GETMAIN,
IN ITII1 G=OO ,
NU~IBY'rE= 1 024,
CLASS=TERHINAL
OBTAIN NEW STORAGE AREA
INITIALIZE WITH BINARY ZEROS
SIZE OF STORAGE REQUESTED
CLASS OF STORAGE REQUESTED
The follolTing examples shon hOll to specify the size of a required
storage area and the value to \Thich it is to be initialized and then
request that the storage be acquired.
410
CICS/VS AP RM
(~lL)
*
*
*
For Assembler
MVI
MVC
lafr[Qa~:
TCASCIB,B'O'
TCASCNB,=H'1024'
INITIALIZE WITH BINARY ZEROS
SIZE OF STORAGE REQUESTED
DFHSC TYPE=GETMAIN,
INITIMG=YES,
COND=YES,
CLASS=TERMINAL
CLC
TCASCSA,=F'O'
BE
NOSTRG
L
TIOABAR,TCASCSA
OBTAIN NEW STORAGE AREA
INITIALIZE WITH BINARY ZEROS
RETURN CONTROL
CLASS OF STORAGE REQUESTED
W1S STORAGE AVAILABLE?
BRANCH IF NOT
LOAD REGISTER IF STORAGE FOUND
*
*
*
For COBOL:
NOTE INITIALIZE WITH BLANKS
NOTE SIZE OF STORAGE REQUESTED.
MOVE • • TO TCASCIB.
MOVE 1024 TO TCASCNB.
DFHSC TYPE=GETMAIN,
OBTAIN NEW STORAGE AREA
INITIMG=YES,
INITIALIZE WITH BLANKS
COND=YES,
RETURN CON TROL
CLASS OF STORAGE REQUESTED
CLASS=TERMINAL
IF TCASCSA EQUAL 0 GO TO NOSTRG.
MOVE TCASCSA TO TIOABAR.
*
*
*
For PL/I:
TCASCIB=O;
TCASCNB=1024 ;
/*INITIALIZE WITH BINARY ZEROS*/
/*SIZE OF STORAGE REQUESTED*/
DFHSC TYPE=GETMAIN,
INITIMG=YES,
COND=YES,
CLASS=TERMINAL
IF UNSPEC(TCASCSA)
TIOABAR=TCASCSA;
chapter
o
OBTAIN NEW STORAGE AREA
INITIALIZE WITH BINARY ZEROS
RETUR N CON TR OL
CLASS OF STORAGE REQUESTED
THEN GO TO NOSTRG;
/*LOAD REGISTER IF STORAGE FOUND*/
5.~.
Storage Control
(DFHSC Macro)
*
*
*
411
Release Main Storage (TYPE=FREEMAIN)
The format of the DFHSC macro instruction to release main storage is as
follows:
r------r-------r----------------------------------------------------------,
I
DFHSC I TYPE=FREEMAIN
I [,RELEASE=ALL]
I
•
If the task itself does not release acquired storage, the storage is
released by CICS/VS upon termination of the task.
When this macro instruction is used to release a single storage area,
the address of that area must be placed in TCASCSA prior to execution of
the macro instruction. If all terminal storage acquired by means of
DFHSC TYPE=GETMAIN,CLASS=TERMINAL macro instructions in the application
program or by CICS/VS on pehalf of the task is to be released, the
RELEASE=ALL operand will achieve that result; in this case, it is not
necessary to place an address in TCASCSA.
The following example shows how to release all main storage currently
allocated to a terminal:
DFHSC TYPE=FREEMAIN,
RELEASE=ALL
RELEASE ALL TERMINAL STORAGE
The use of the RELEASE=ALL operand is restricted during basic mapping
support (BMS) output operations having "OUT" disposition, to preserve
the terminal storage used by BMS. Once a DFHBMS macro with "OUT"
disposition has been issued, the application program must not issue a
DFHSC TYPE=FREEMAIN,RELEASE=ALL macro until either a DFHBMS TYPE=PAGEOUT
or DFHBMS TYPE=PURGE macro has been issued.
The use of the RELEASE=ALL operand is also restricted during data
interchange output operations (ADD, ERASE, REPLACE, NOTE, QUERY, END,
and ABORT) to preserve the terminal storage used by the data interchange
program (DFHDIP). Once a destination has been selected, RELEASE=ALL
must not be specified until TYPE=END, TYPE=QUERY, or TYPE=ABORT has been
specified in the DFHDI macro for that destination.
The following examples show how to release a single main storage
area, placing the address of the area to be released in TCASCS! before
issuing the release request.
ST
TIOABAR,TCASCSA
DFHSC TYPE=FREEMAIN
q12
CICS/VS APRM(ML)
PLACE STORAGE AREA ADDRESS IN TCA
RELEASE STORAGE AREA
*
~or
COBOL:
MOVE TIOABAR TO TCASCSA.
NOTE PLACE STRG AREA ADDR IN TCA.
DFHSC TYPE=FREEMAIN
RELEASE STORAGE AREA
For PL/I:
TCASCSA=TIOABARi
/*PLACE STORAGE AREA ADDRESS IN TCA*/
DFHSC
RELEASE STORAGE AREA
TYPE=FREEM~IN
Chapter 5.5.
Storage Control
(DFHSC Macro)
413
Operands of DFHSC Macro
CLASS=
specifies the class of the storage to be acquired.
TERMINAL or TERM
indicates that the storage area is to be used as a terminal
input/output area (TIOA), which is chained to the terminal
control table terminal entry ~CTTE). All requests for
storage related to terminal input/output must specify this
class.
If storage other than TERMINAL class is used as a TIOA for
subsequent terminal control input/output operations,
storage violations may occur.
USER
indicates that the storage area is to be associated with
the application program and used by that program. This
area is chained to the TCA associated with the requesting
task.
TRANSDATA or TD
indicates that the storage area is to be used for transient
data record storage (a TDIA or TDOA). This area is chained
to the TCA associated with the requesting task and is use~
by transient data control.
TEMPSTRG or TS
indicates that the storage area is to be used as a
temporary storage input/output area (TSIOA). This area is
chained to the TCA associated with the requesting task and
is used by temporary storage control.
Note: USER, TRANSDATA, and TEMPSTRG specifications have
essentially the same effect. The advantage of using
CLASS=TRANSDATA or CLASS=TEMPSTRG when either is appropriate is
that the specification serves as documentation Doth in the
program and in the class code of the storage accounting field
for the area.
COND=
is an optional operand that ensures that control is returned to
the application program, whether or not the requested storage
area is acquired.
YES
indicates that control is to be given to the instruction
immediately following the macro expansion for the DFHSC
TYPE=GETMAIN macro instruction in the application program.
To determine whether the reguested storage area was
acquired, the application program must examine TCASCSA,
which is set to binary zeros if the request cannot be
satisfied.
414
CICS/VS APRM(ML)
(YES,symbolic address)
causes a branch to the location specified by the symbolic
address if the requested storage Has acquired; otheruise,
cont~ol is returned to the instruction immediately
follouing the macro expansion for the DPHSC TYPE=GETMAIN
macro instruction in the application program.
(NO ,symbolic address)
causes a branch to the location specified by the symbolic
address if the requested storage vas not acquired;
othervise, control is returned to the instruction
immediately follouing the macro expansion for this macro
instruction in the application program.
INITIl1G=
is an optional operand that can be used to initialize the
acquired storage area to the bit configuration desired.
number
is a tuo-digit hexadecimal numeral indicating the bit
configuration desired.
YES
indicates that the desired bit configuration is in TCASCIB.
NUMBYTE=number
is a decimal nuoeral up to 65520 (32767 when CLASS=TERllINAL)
specifying the size, in bytes, of the storage area being
requested; if omitted, the number of bytes is assumed to be
stored in binary form in TCASCNB. n zero data length is not
alloued for a DPHSC TYPE=GETMAIN macro instruction.
In BMS
mapping operations, the number of bytes can be specified as an
Assembler language expression, for example:
NUMBYTE=mapname.E-TIOADBA
Not~:
Depending upon the class of storage specified (see the
CLASS operand), CICS/VS storage management automatically
increments the amount of storage requested to allou for the
storage accounting field and other control information. For
CLASS=USER and CLASS=TERMINAL ~IOn) storage, the exact number
of bytes required should be specified. For CLASS=TRANSDATA
(TDIA and TDOA) and CLASS=TEHPSTRG (TSIOA) storage, the amount
requested must include four additional bytes to allow for a
portion of CICS/VS control information, namely, the length
(LL~)zf) field at the beginning of the area.
(See also the
section II Tldditional Guidelines" in Chapter 2.3 that apply uhen
programming in COBOL.)
Chapter 5.5.
Storage Control
~FHSC
Macro)
415
RELEASE=ALL
indicates that all main storage acquired by means of DFHse
TYPE=GETMAIN,CLASS=TERMINAL macro instructions is to be
released.
The use of the RELEASE=ALL operand is restricted during ba~ic
mapping support (BMS) output operations that have an OUT
disposition; this restriction preserves the terminal storage
used by BMS. Once a DFHBMS ~acro instruction with an OUT
disposition has been issued, the application program must not
issue a DFHSC TYPE=FREEMAIN,RELEASE=ALL macro instruction until
either a DFHBMS TYPE=PAGEOUT or DFHBMS TYPE=PURGE macro
instruction has been issued.
If this operand is not specified, only one storage area can be
released by a DFHSC TYPE=FREEMAIN macro instruction; the
address of that area must be in TCAseSA and must be the main
storage address returned as a result of a previously issued
DFHse TYPE=GETMAIN macro instruction.
416
CICS/VS APRM(ML)
Chapter 5.6. Transient Data Control (DFHTD Macro)
Transient data management provides, through transient data control, a
generalized queuing facility.
Data can be queued (stored) for
subsequent internal or external processing. Selected units of
information, as specified by the application programmer, can be routed
to or from predefined symbolic destinations, either intrapartition or
extrapartition. The definitions for tha destinations must be contained
in a destination control table (DCT) established by the system
programmer at system generation.
Intrapartition destinations are queues of data on direct access
storage devices developed for input to one or more programs running
asynchronously (concurrently) as separate tasks; they are internal to
the CICS/VS partition/region. Data directed to or from these internal
destinations is called intrapartition data and must consist of variablelength records. Intrapartition destinations can be associated with
either a terminal or an output data set.
Intrapartition data may be
ultimately transmitted upon request to a destination terminal or
retrieved sequentially from the output data set. Typical uses of this
facility involve message suitching, broadcasting, data base access and
routing of output to multiple terminals (for example, for order
distribution), queuing of data (for example, for assignment of order
numbers or priority by arrival), and data collection (for example, for
batched input from 2180 Data Transmission Terminals).
An intrapartition queue is reusanle. The system programmer can
indicate, by symbolic destination, "hether (1) transient data space
management is to control the reuse of tracks associated with a
particular destination identification (DESTID), or (2) the releasing of
track space is to be controlled through use of the transient data PURGE
macro instruction. If transient data space management is not used, an
intrapartition queue continues to grou, irrespective of whether the data
has been read, until the application programmer purges it.
Extrapartition destinations are queues (data sets) external to the
CICS/VS partition/region, residing on any sequential device (DASD, tape,
printer, and so on). In general, sequential extrapartition destinations
a~e used for storing data 8xternal to the CICS/VS partition/region or
for retrieving data from outside the partition/region. For example, one
task may read data from a remote terminal, edit the data, and write the
results to a data set for subsequent processing in another
partition/region. Logging data, statistics, and transaction error
messages are examples of data that can be written to extrapartition
destinations. In general, extrapartition data created by CICS/VS is
intended for subsequent batched input to non-CICS/VS programs. Data can
also be routed to an output device such as a line printer.
Data directed to or from an external destination is called
extrapartition data and consists of sequential records that are fixedor variable-length, blocked or unblocked. The record format for a
particular extrapartition destination must be described by the system
programmer when setting up the destination control table (see the
f!~~Y~~~i~~~£Q~£~mmQr·s Refg£gn£g Manual) •
Intrapartition and extrapartition destinations can be used as
indirect destinations, uhich are symbolic references to still other
destinations. This facility provides some flexibility in program
maintenance in that data can be routed to a destination known by a
different symbolic name, uithout the necessity for recompiling existing
programs that use the original name. Only the destination control table
Chapter 5.6.
Transient Data Control
(DFHTD Macro)
417
n6ed be changed. The application programs can route data to the
destination using the previous symbolic name; however, the previous name
is now an indir8ct destination that refers to the new symbolic name.
Since indirect destinations are established by means of destination
control table entries, the application programmer need not usually be
concerned with how this is done. Further information is available in
the £ICS/VS System Programmer's Reference Manual.
For intra partition destinations, CICS/VS provides the option of
automatic task initiation. A basis for automatic task initiation is
established by the system programmer by specifying a nonzero trigger
level for a particular intrapartition destination in the DCT.
(See the
discussion of the DFHDCT TYPE=INTRA macro instruction in 'the CICSIYS
2Ystem Programmer's Reference Manual.) When the number of entries (PUTs
from one or more programs) in the queue (destination) reaches the
specified level, a transaction specified in the definition of the
destination is automatically initiated. Control is passed to a program
that processes the data in the queue; the program must issue repetitive
GETs to deplete the queue.
Once the queue has been depleted, a new automatic task initiation
cycle begins. That is, a new task is scheduled for initiation when the
specified trigger level is again reached, whether or not execution of
the prior task has terminated.
If an automatically initiated task does not deplete the queue, access
to the queue is not inhibited. The tas~ may be normally or abnormally
terminated before the queue is emptied (that is, before a QUEZERO
response is returned in response to a DFHTD TYPE=GET macro instruction).
If the destination is a terminal, the same task is reinitiated
regardless of the trigger lev8l. If the destination is a data set, the
task is not reinitiated until the specified trigger level is reached.
If the trigger level of a queue is zero T no task is automatically
initiated. To ensure that termination of an automatically initiated
task occurs when the queue is empty, the application program should test
for a QUEZERO condition rather than for some application-dependent
factor such as an anticipated number of records. It is the QUEZERO
condition only that indicates a depleted queue.
Requests for transient data services are communicated to transient
data control through CICS/VS macro instructions. Transient data control
then executes as a service program under control of the TCA of the
requesting program. It runs at the priority of the reques,ting program
and saves and restores registers from its TCA. After the requested
transient data service has been provided (or attempted), control is
returned to the next executable instruction in the requesting program.
The transient data management macro instruction
request any of the following services:
~FHTD)
is used to
1.
Direct data to a predefined symbolic destination which references a
data set or a terminal
2.
Acquire data from a predefined symbolic source which references a
data set or a terminal
3.
Control the processing of an extrapartition data set
4.
Purge data associated with an intrapartition data set
5.
Check the response to a request for transient data services
The application programmer must specify the parameters required when
requesting transient data services. Parameters can be specified in tvo
ways:
(1) by including the parameters in operands of the DFHTD macro
418
CICS/VS APRM(ML)
instruction by whLch the service is requested, or (2) by coding
instructions that move the required parameters to fields of the TCA
2rior to issuing the DFHTD macro instruction. The latter approach
provides some degree of flexibility in that a single DPHTD macro
instruction can be tailored according to current logic needs uithin the
application program.
The application programmer can check the CICS/VS response to a
request for transient data services as described under "Test Response to
a Request for Transient Data Services," later in this chapter. The
operands that can be specified in DPHTD macro instructions are explained
in detail at the end of the Chapter.
CICS/VS routes a variety of messages generated by CICS/VS programs or
tasks to transient data control.
For example, terminal control detects
a line or terminal problem (not related to a user-provided task) and
routes control to the CICS/VS terminal abnormal condition program
(DPHTACP). DPHTACP then generates a message to the control system
terminal log (CSTL) and/or to the control system master ter~inal (CSMT).
Destination definitions for all user and CICS/VS destinations must be
included in the destination control table (DCT).
Lack of a destination
definition leads to an IDERROR (identification error) response to a
DPHTD macro instruction.
Asynchronous Transaction Processing
Typically, a task to be run under CICS/VS is initiated from a terminal
and processed at regular intervals until completion, according to system
service patterns established for CICS/VS. This mode of operation is
sometimes referred to as §Ynch£Qgous transaction processing, because the
task has complete control of the terminal uhich initiated it.
Support for aSYn£hronou~ transaction processing can also be generated
into a CICS/VS system.
This capability is designed primarily to permit
a type of batch processing uithin CICS/VS. A task is initiated from a
terminal as described above, but the specified transaction code causes a
CICS/VS-provided asynchronous transaction processing program to read the
data to an intrapartition data set. In effect, data collection from a
device such as the 2780 Data Transmission Terminal is possible. When
the data has been read, the device is freed for other activity. An
application program processes the data, and, upon operator request,
output is queued for subsequent transmission to a specified terminal.
If the automatic task-initiation feature is generated into CICSjVS, that
application program can be initiated automatically when a specified
trigger level is reached ~hat is, uhen a specified number of inputs
have been entered in the intrapartition data set) •
The asynchronous transaction processing (A'rp) facility is designed
specifically for handling input from batch terminals like the 2780 and
2770.
Generally, ATP can also be used for other, interactive terminals
like the 2741. Hovever, ATP is not intended for, and will not support,
input from the 2980, 3270, 3600 BTAM, 3735, or 3740; ATP is not
available for VTAM logical units. Another consideration is that
application programs intended to execute under control of ATP must not
contain basic mapping support (BMS) macro instructions requesting BMS
terminal paging facilities.
Additional information concerning the creation of user exits for
asynchronous transaction processing and the coding of the exit routines
is given in the CICS/VS System Programmer's Reference Manual. The
Chapter 5.6.
Transient Data Control
(DFHTD Macro)
419
init~ation
of ATP by means of terminal commands is described in the
CI£~~-.Q:eera tor 's Quid~.
Q20
CICS/VS APRM (ML)
Dispose of Data (TYPE=PUT)
The format of the DFHTD macro instruction to direct transient data to a
predefined symbolic destination is as folIous:
r------r-------r------------------------------------------------------------,
TYPE=PUT
[ , DE 5TiD=symbolic name]
[,TDADDR=symbolic address]
[,NORESP=symbolic address]
[,IDERROR=symbolic address]
[,IOERROR=symbolic address]
[,NOTOPEN=symbolic address]
[,NOSPACE=symbolic address]
DFHTD
Destinations are intrapartition if associated with a facility
allocated to the CICS/VS partition/region and extrapartition if the data
is directed to some destination that is external to the CICS/VS
partition/region. If intrapartition data is to be placed in the
transient data output area, the symbolic storage definition for this
area (DFHTDOA) should be copied in the application program. The first
four bytes of this definition are a length field.
All references to the
output area should be made through the use of a register (TDOABAR) \Thich
points to the beginning of the area.
The address of the output area containing the data to be uritten,
must either be specified in the TDADDR operand or placed in TCATDAA
prior to issuing the macro instruction. For variable-length records or
intrapartition data, the first four bytes of the output area must
contain the length of the record. For fixed length records, the start
of the output area must be the start of the data.
The format of the
length field is LL~~, where LL is a tvo-byte binary length (the value of
which includes the length of the data plus the four bytes for the length
field) and ~~ should be two bytes containing binary zeros. Transient
data control does not release this area after the data is uritten as
output.
If the destination is extrapartition, TYPEFLE=OUTPUT·must be
specified in the appropriate DFHDCT TYPE=SDSCI system macro, otherwise
unpredictable results or an abnormal termination nill occur.
The following examples show how to write data to a predefined
symbolic destination, in this cas~, the control system message log
(CSHL). The address of TDOAVRL, the four-byte length field at the
beginning of the transient data output area (TDOA), is a pointer to the
start of the variable-length data to be written.
For Assembler language:
TDOABAR
DATA
EQU
COpy
DS
7
DFHTDOA
CL10
DFHSC
TYPE=GETMAIN,
CLASS=TRANSDATA,
NUMBYTE=14
TDOABAR,TCASCSA
TDOAVRL,LENGTH
L
Mve
Chapter 5.6.
Transient Data Control
*
*
(DFHTD Macro)
421
HVC
DATA,MESSAGE
MVC
TCATDDI,=C'CSML'
DFHTD TYPE=PUT,
TDADDR=TDOAVRL
*
For COBOL:
02 TDOABAR PIC
S9~)
COMP.
01 DFHTDOA COPY DFHTDOA.
02 SDATA PIC X (10) •
DFHSC
TYPE=GETMAIN,
CLASS=TRANSDATA,
NUMBYTE=14
MOVE TCASCSA TO TDOABAR.
MOVE SLENGTH TO TDOAVRL.
MOVE SMESSAGE TO SDATA.
MOVE 'CSML' TO TCATDDI.
DFH'rD TY PE=PUT ,
TDADDR=TDOAVRL
*
*
*
For PL/I:
%INCLUDE DFHTDOA;
2 DATA CHAR (10) ;
DFHSC
TYPE=GETMAIN,
CLASS=TRANSDATA,
NUMBYTE=14
TDOABAR=TCASCSA;
TDOAVRL=LENGTH;
DATA=MESSAGE;
TCATDDI= 'CSML';
DFHTD TYPE=PUT,
TDADDR=TDOAVRL
422
CICS/VS APRM(ML)
*
*
*
Acquire Queued Data (TYPE=GET)
The format of the DFHTD macro instruction to retrieve queued data from
an extrapartition or ~ntrapartition destination is shown below. The
address of the retrieved data is returned at TCATDAA.
DFHTD
TYPE=GET
[,DESTID=symbolic name]
[,QUEBUSY=symbolic address]
[,NORESP=symbolic address]
[,QUEZERO=symbolic address]
[,IDERROR=symbolic address]
[,IOERROR=symbolic address]
[,NOTOPEN=symbolic address]
If the data is extrapartition, TCATDAA points to the first word of
the data area. For variable-length records, the first four bytes of
this area contain the length (LL~~) as specified for variable-length
data sets. TYPEFLE=INPUT or TYPEFLE=RDBACK must be specified in the
appropriate DFHDCT TYPE=SDSCI system macro, and DESTID must not indicate
a system spool file, otherwise unpredictable results or an abnormal
termination will occur.
If the data is intrapartition, the symbolic storage definition for
the transient data input area (DFHTDIA) must have been copied in the
application program. TCATDAA points to a CICS/VS input area defined by
DFHTDIA. TDIAIRL contains the length (data length plus the length of
the length field) of the area.
Transient data (either intrapartition or extrapartition) must be
moved from the input area before it can be used in any other
input/output operation.
If the application programmer issues a DFHTD TYPE=GET macro
instruction, the input area acquired for the previous GET is reused if
it is long enough to contain the input record. If it is not, CICS/VS
acquires a new input area of sufficient length and releases the input
area previously used. If the application programmer issues a DFHTD
TYPE=PUT macro instruction, the input area acquired for a previous GET
may also be changed or released. The application programmer should
always move data to be saved from the input area to a user area to
ensure that it is not overlaid with new data. Addressability to the
area should also be reestablished following each GET.
The application programmer should not attempt to free storage
acquired by the transient data control program in response to a DFHTD
TYPE=GET macro instruction. This storage is freed by CICS/VS in the
case of intrapartition data, or by the operating system in the case of
extrapaLtition data. An attempt to free storage acquired for
extrapartition data may result in an abnormal termination of CICS/VS,
since the storage area address returned by transient data control points
to storage that is not part of the CICS/VS dynamic storage subpool.
The following examples show hou to read a variable-length record from
an intrapartition data set specified prior to issuing the DFHTD TYPE=GET
macro instruction.
In these examples, the data set is the control
system message log (CSML).
Chapter 5.6.
Transient Data Control (DPHTD Macro)
423
For Assembler language:
TDIABAR
EQU
COpy
7
DFHTDIA
MVC
DFHTD
TCATDDI,=C'CSKL'
TYPE=GET
TDIABAR,TCATDAA
L
02
01
TDIABAR PIC S9 (8)
COMP.
DFHTDIA COpy DFHTDIA.
MOVE 'CSML' TO TCATDDI.
DFHTD TYPE=GET
MOVE TCATDAA TO TDIABAR.
For PL/I:
%INCLUDE DFHTDIA;
2
DUMMY CHAR (1) ;
TCATDDI=' CSML' ;
DFHTD TYPE=GET
TDIABAR=TCATDAA;
Assume that,' in the above examples, the variable-length record is
read from an extrapartition data set. The address placed at TCATDAA by
CICS/VS is the address of the l8ngth (LL~~) field that precedes the
actual data. Since the DFHTDIA symbolic storage definition is being
used, the address must be adjusted to point to the CICS/VS system
section preceding the actual data. Therefore, an instruction to adjust
the address should be inserted immediately following the instruction
that moves the contents of TCATDAA to TDlABAR. The following examples
apply to CICS/OS/VS but are applicable to CICS/DOS/VS if '36' is
replaced by '8'.
For Assembler lanqusgg:
SH TDIABAR,=H I 36'
424
CICS/VS APRM(ML)
SUBTRACT 36 FROM TDIABAR.
For PL/I:
DCL TDIABAA FIXED BIN(31) BASED(TDIABAB);
TDIABAB=ADDR(TDIABAR);
/* OVERLAY POINTER */
TDIABAA=TDIABAA-36
/* DO POINTER ARITHMETIC */
Since these examples deal with variable-length records, the first
byte of the data is assumed to be the length field ~L~~). If the
examples dealt with fixed-length records, appropriate values would be qO
and 12 for CICS/OS/VS and CICS/DOS/VS, respectively.
Note: These values are subject to change in future versions of CICS/VS,
because this DSECT is intended only for intrapartition data sets. No
DSECT is provided for extrapartition data. Each user should define the
extrapartition DSECT so as not to use the absolute values in the above
example.
Chapter 5.6.
Transient Data Control
(DFHTD Macro)
425
Force End of Volume on an Extrapartition Data Set (TYPE=FEOV)
The format of the DFHTD macro instruction to create a '~orced end of
volume" situation on an extrapartition magnetic tape data set is as
follows:
I
I
I DFHTD
I
I
I
I
I
TY PE=FEOV
[,DESTID=symbolic name]
[,NORESP=symbolic address]
[,IDERROR=symbolic address]
[,NOTOPEN=symbolic address]
I
This macro specifies that a magnetic tape reel is to be rewound and
unloaded; output labels are to be created as required and new input
labels verified according to host operating system forced-end-of-volume
processing. CICS/VS operation is halted, and the next tape reel must be
loaded before CICS/VS operation is resumed.
!ote: This facility should be used with caution, since CICS/VS
operation is halted until the new tape reel has been loaded.
The following examples show how to create a "forced end of volume"
situation on an extrapartition magnetic tape data set.
MVC
TCATDDI,=C'CSML'
DFHTD TYPE=FEOV
MOVE 'CSML' TO TCATDDI.
DFHTD TYPE=FEOV
For PL/I:
TCATDDI='CSML' i
DFHTD TYPE=FEOV
426
CICS/VS APRM(ML)
Purge Intrapartition Data (TYPE=PURGE)
The format of the DFHTD macro instruction to purge all data associated
with a particular intrapartition destination (queue) is as follous:
r
I
I
I
I
I ______
L
DFHTD
~
TYPE=PURGE
[,DESTID=symbolic name]
[,NORESP=symbolic address]
[,IDERROR=symbolic address]
_______
~
__________________________________________________________
~
When transient data associated with a particular intrapartition
destination (queue) is no longer needed, the application programmer can
purge the data associated with that destination by issuing this macro
instruction, which causes all storage associated with the destination to
be freed (deallocated).
This macro instruction must be used to free storage associated with a
destination designated as nonreusable in the destination control table.
Otheruise, the storage remains allocated to the destination; the data
and amount of storage associated with the destination continue to groy
whenever a DFHTD TYPE=PUT macro instruction refers to the d~stination.
Chapter 5.6.
Transient Data Control (DFHTD Macro)
q27
Test Response to a Request for Transient Data Services (TYPE=CHECK)
The format of the DFHTD macro instruction to test the CICS/VS response
to a request for transient data services is as follows:
r------~------~-----------------------------------------------------------,
I
I
,,,
,
I
I
I
DFHTD
TYPE=CHECK
t,NORESP=symbolic address]
[,QUEZERO=symoolic address]
[,IDERROR=symbolic address]
[ ,IOERROR=symbolic address]
[,NOTOPEN=symbolic address]
[,NOSPACE=symbolic address]
I
Transient Data Response Codes
The Assembler-language or PL/I programmer accesses transient data
response codes at TCATDTR; the COBOL programmer accesses these response
codes at TCATDRC. In addition, the COBOL programmer can refer to the
response codes by means of condition names (for example, TDNORESP,
TDQUEZERO etc.). The possible response codes and their meanings are
shown in Figure 5.6-1.
If the application programmer does not check for a particular
response to a service request, and the exception condition corresponding
to that response occurs, program flow proceeds to the next sequential
instruction in the application program.
428
CICS/V 5 APRM (ML)
Transient Data
Request by
DFHTD liacro
Instruction
I
I
I
Condition
Response Code
IAssembler I COBOL
PL/I
NORESP
(Normal response)
x·oo·
GET ,CHECK
QUEZERO
(Queue is zero)
X'OlD
12-1-9
(TDQUEZ ERO)
00000001
ALL
IDERROR
(Identification
error)
X'02'
12-2-9
(TDIDERROR)
00000010
PUT ,GET ,CHECK
IOERROR
(Input/Output
error)
X'04'
12-4-9
(TDIOERROR)
00000100
PUT ,GET ,FEOV,
CHECK
NOTOPEN
(Journal not open)
X'OS'
12-S':"'9
(TDUOTOPEN)
00001000
PUT,CHECK
NOSPACE
(Uo space on
intrapartition
queue, or urite
not serviceable)
X' 10'
12-11-1-8-9
(TDNOSPACE)
00010000
ALL
LOU-V~LUES
00000000
(TDNORESP)
Note:
The names enclosed in parentheses in the COBOL column indicate
the condition names generated by CICS/VS. These names may be
used in testing for the respective conditions in a COBOL program.
Figure 5.6-1.
Transient Data Control Response Codes
The following examples sholl how to examine the response code provided
by CICSjVS and transfer control to the appropriate user-uritten
exception-handling routine.
For Assembler language:
DFHTD TYPE=GET,
*
DESTID=CS~lL
CLI
TCATDTR,X '00'
GOOD
DFHPC TYPE=ABEND,ABCODE=GETE
DS
OH
NORMAL RESPONSE
BE
GOOD
Chapter 5.6.
Transient Data Control
(DFHTD l1acro)
429
For COBOL:
DFHTD TYPE=GET,
DESTID=CSML
IF TCATDRC = , , THEN GO TO GOOD.
DFHPC TYPE=ABEND,ABCODE=GETE
*
NOTE
12-0-1-8-9
NORESP.
GOOD.
Alternatively, the COBOL programmer may test responses by using the
CICS/VS generated condition names.
IF TDNORESP THEN GO TO GOOD.
DFHTD TYPE=GET,
DESTID=CSML
IF TCATDTR='O'B THEN GO TO GOOD;
DFHPC TYPE=ABEND,ABCODE=GETE
GOOD:
430
CICS/V S APRM (ML)
*
1*
NORMAL RESPONSE */
Operands of DFHTD Macro
DESTID=symbolic name
specifies the symbolic name of the destination to which the
data is to be routed and queued, or from which queued data is
to be read. This name must appear in the destination control
table (DCT). If this operand is omitted, the symbolic name of
the destination is assumed to be in TCATDDI. For a TYPE=GET
macro, DESTID must not indicate a system spool file.
IDERROR=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the symbolic destination referred to
by a DFHTD macro instruction cannot be found.
IOERROR=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an input/output error occurs on a
data record and the data record in error is skipped. Transient
data returns an IOERROR indication as long as the queue can be
read; a QUEZERO response is returned when the queue cannot be
read, in vhich case, the user may attempt a restart. This
condition can also be raised if an attempt is made to write a
zero length record to an intrapartition data set. This
condition can also be raised under VSAM if the record is too
large to fit in a control interval.
NORESP=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if no error occurs during a data set
(file) operation. NORESP signifies "normal response."
NOSPACE=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if no more space exists on a particular
intrapartition queue or if the write request cannot be
serviced. If the NOSPACE response is received, no more data
should be written to the queue, because it may be lost.
NOTOPEN=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if a destination is closed.
QUEBUSY=symbolic address
specifies the symbolic address of the routine to receive
control if the input request attempts to access a record on an
input intrapartition queue that has been enqueued upon for
output by a PUT or PURGE request. If this operand is omitted,
the task issuing the request waits until the queue is no longer
being used for output.
QUEZERO=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed when the destination (queue) accessed
by a DFHTD TYPE=GET macro instruction is empty.
Chapter 5.6.
Transient Data Control (DFHTD Macro)
431
TDADDR=symbolic address
specifies the symbolic address of the output area containing
data to be written (for intrapartition data and variable-length
extrapartition data, the first four bytes of this area must
contain the length of the record). If this operand is omitted,
the address of the output area is assumed to be in TCATDAA.
432
CICS/VS APRM(aL)
Chapter 5.7. Temporary Storage Control (DFHTS Macro)
Temporary storage control enables user-written application programs to
store temporary data in main storage or in auxiliary storage on a direct
access storage device.
Temporary data is stored, retrieved, and released using a symbolic
name (up to eight characters) assigned to the data by the originating
task.
(The symbolic name must not consist solely of binary zeros.)
The data ~ay be a single record or records retrieved from or added to
a temporary storage message set. The former provides a typical "scratch
pad" facility. The latter is designed primarily for terminal paging.
It is used in conjunction with basic mapping support (see Chapter 4.3)
and page supervision programs to achieve random access to generalpurpose storage files. In general, the paging facility of temporary
storage should be used only when multiple records are involved and
random access to those records is necessary. This queuing of message
sets should not be used for sequential data. Transient data management
provides facilities for efficient handling of sequential data sets. If
data contained in a message set is to be updated and retrieved by
multiple tasks, it may be necessary to protect i t by means of the task
control enqueuing facility.
Data placed in temporary storage can remain intact beyond the time
that the originating task is active in the system. That is, even after
the originating task is terminated and its transaction storage released,
data placed in temporary storage can be accessed by other tasks through
references to the symbolic name under which it was stored. Temporary
data remains intact until released by the originating task or by any
other task. Prior to release, it can be accessed any number of times.
When temporary data is released, the space that it occupied is
reusable. If the data was in main storage, the storage area becomes
part of available dynamic storage. If the data was on auxiliary
storage, the physical space that the data occupied becomes available and
can be reused for other data •.
Temporary data can be retrieved by the originating task or by any
other task using the symbolic name assigned to it. The name assigned to
a single record should be unique. If more than one record has the same
name, the record is queued in temporary storage. If an attempt is made
to retrieve a record from the queue, the records will De presented on a
first in first out basis. All information moved to or from a temporary
storage message set is referred to by a unique name assigned to the
message set. Specific entries (logical records) within a message set
are referred to by relative position numbers. To avoid conflicts caused
by duplicate names, a naming convention should be established and
followed by all programmers. For example, the operator identification,
terminal identification, or transaction identification could be appended
as a prefix or suffix to each programmer-supplied symbolic name.
Temporary data can be stored in either main or auxiliary storage.
Generally, main storage should be used if the data is needed for only
short periods of time; auxiliary storage should be used if the data must
De kept for extended periods of time. Another consideration is that
data stored on auxiliary storage is maintained after CICS/VS termination
and can be recovered in a subsequent restart. No attempt is made to
recover data in main storage. Main storage might be used to pass data
from task to task or for unique storage that allows programs to meet the
requirement of CICS/VS that they be quasi-reenterable.
Chapter 5.7.
Temporary storage Control (DFHTS Macro)
433
Some uses of the page queuing facility follow:
1.
Terminal paging. A task could retrieve a large master record from
a direct access data set, format it into several screen images,
store the screen images temporarily in auxiliary storage, and then
ask the terminal operator which "page" (screen image) is desired.
The application programmer can provide coding (as a generalized
routine or unique to a single application) to advance page by page,
advance or back up a relative number of pages, and the like. This
facility is provided by CICS/VS Basic ~apping Support as described
in Chapter 4.3.
2.
A suspend data set. Assume a data collection task is in progress
on a certain terminal. The task reads in one or more units of
input and then allows the terminal operator to interrupt the
process. If no interruption occurs (some kind of coded input), the
task repeats the data collection process. If the operator
interrupts the data collection stream with coded input, the data
collection task writes its "incomplete" data to temporary storage
and terminates the task. The terminal is now free for entry of a
different transaction (perhaps a high-priority inquiry). When the
terminal is available to continue the dat'a collection operation,
the operator initiates the task in a "resume" mode, causing the
task to recall its suspended data from temporary storage and
continue as though it had not been interrupted.
3.
An application that accepts input data to be written as output on a
preprinted form.
The DFHTS macro is used to:
•
Acquire data from main or auxiliary storage
•
Send data to main or auxiliary storage
•
Update data in main or auxiliary storage
•
Release temporary data in main or auxiliary storage
•
Check the response to a request for temporary storage services
Parameters can be specified in either of two ways:
•
By including the parameters in operands of the DFHTS macro
instruction by which temporary storage services are requested, or
•
By coding instructions that place the parameter values in fields of
the TCA prior to issuing the DFHTS macro instruction
The second of these approaches provides flexibility in that the
parameters of a single DFHTS macro instruction can vary to meet the
logic needs of the application program.
The CICS/VS response to a request for temporary storage services can
be checked, as explained under" "Test Response to a Request for Temporary
Storage Services," later in this chapt~r. If the programmer does not
check for a particular response, and the condition corresponding to that
response occurs, program flow proceeds to the next sequential
instruction in the application program. All operands that can be
included in the DFHTS macro instruction are discussed at the end of the
chapter.
434
CICS/VS APRM (ML)
Store Temporary Data as a Single Unit of Information (TYPE=PUT)
The format of the DFHTS macro instruction to store a single unit of
information as temporary data in main or auxiliary storage (that is, as
though using a "scratch pad") is as follows:
DFHTS
TYPE=PUT
[,TYPOPER=REPLACE]
[ ,DATAID=name]
[,TSDADDR={symbolic addressIYES}]
[,STORFAC={AUXILIARYIMAIN} ]
[ ,COND=YES]
[,NOSPACE=symbolic address
[,NORESP=symbolic address]
[,IOERROR=symbolic address]
[,INVREQ=sym~olic address]
[,ERROR=symbolic address]
This macro causes data to be written to temporary storage as a single
unit of information (logical record) •
Temporary data may be written from a temporary storage input/output
area (TSIOA) or from a main storage area identified by the application
programmer.
It must have the standard variable-length format, with the
data length specified in the first four bytes. These bytes should
contain LL~~, where LL is a two-byte binary length field (the value of
which includes the length of the data plus the four bytes for the length
field) and ~~ is a two-byte field of binary zeros. The maximum
temporary storage record size is based on user-specified data set
characteristics.
(See temporary storage in the CICS/OS/VS syste,!!!
g£Q~~m~r's_Quide or CI£S/DO~L!~_~ystem Programmer's Guide.)
Existing temporary storage data can be updated by adding the
TYPOPER=REPLACE operand. This causes the current data identified by the
DATAID operand to be released and replaced with the data provided.
If
the data cannot be found, the TYPOPER=REPLACE operand is ignored.
The following examples show how to write a single record of
information to temporary storage.
For Assembler
TSIOABAR
DATA
langua~:
EQU
COPY
DS
7
DFHTSIOA
CL'11
DFHSC TY PE=GET MA IN,
CLASS=TEMPSTRG,
NUMBYTE=15
L
TSIOABAR,TCASCSA
MVC
TSIOAVRL ,LENGTH
MVC
DATA,MESSAGE
DFHTS TYPE=PUT,
DATAID=UNIQNME,
TSDADDR=TSIOAVRL
Chapter 5.7.
Temporary Storage Control (DFHTS Macro)
*
*
*
*
435
'DC
DC
LENGTH
HESSAGE
AL2(L'HESSAGE+4)
C'HELLO THERE'
WORKING-STaRAGE SECTION.
77 SMESSAGE
PIC X (11)
77 SLENGTH
PIC 9(8)
LINKAGE SECTION.
VALUE 'HELLO THERE'.
CaMP
VALUE 15
02 TSIOABAR PIC S9(8) caMP.
01
DFHTSIOA COpy DFHTSIOA.
02 SDATA PIC X(11).
DFHSC TYPE=GETMAIN,
CLASS=TEMPSTRG,
NU~IBYTE=15
MOVE TeASCSA TO TSIOABAR.
MOVE SLENGTH TO TSIOAVRL.
HOVE SMESSAGE TO SDAT!.
DFHTS TYPE=PUT,
DATAID=UNIQNME,
TSDADDR=TSIOAVRL
*
*
*
*
For PL/I:
%INCLUDE DFHTSIOA;
2 DATA CHAR(ll);
DFHSC TYPE=GETMAIN,
CLASS=TEl'IPSTRG,
NUHBYTE=15
TSIOABAR=TCASCSA;
TSIOAVRL=LENGTH;
DATA=MESSAGE;
DPHTS TYPE=PUT,
DATAID=UUIQNME,
TSDADDR=TSIOAVRL
DCL MESSAGE CHAR(1l) INIT ('HELLO THERE');
DCL LENGTH FIXED BIN(15) INIT(1S);
436
CICS/VS APRM (ML)
*
*
*
*
Store Data to a Temporary Storage Message Set (TYPE=PUTQ)
The format of the DFHTS macro instruction to cause an entry to be
uritten to a tellporary storage message set is as follows:
~-----r-------~----------------------------------------------------------~
DFHTS
TYPE=PUTQ
[ ,TYPOPER=REPLACE]
[ ,DATAID=name]
[ , TSDADDR= {symbolic address I YES} ]
[,STORFAC={AUXILIARYIMAIN} ]
[,EUTRY= {nIYES}]
[,COND=YES]
[,NOSPftCE=symoolic address]
[,NORESP=symbolic address]
[,IOERROR=symbolic address]
[,INVREQ=symbolic address]
[,ENERROR=symbolic address]
[,ERROR=symbolic address]
This macro causes a unit of iDformation to be written to a message
set, or queue, in temporary storage. The unit is written in a relative
position that is one beyond the last entry ~ritten to the message set.
Follouing a PUTQ request, the relative record number is returned to the
user in TCATSRN, a tvo-byte field.
Temporary data may be uritten from a temporary storage input/output
area (TSIOA) or from a main storage area identified by the application
programmer. It must have the standard variable-length format, with the
data length specified in the first four bytes. These bytes should
contain LL):1):1, uhere LL is a tllo-byte binary length field (the value of
uhich includes the length of the data plus the four bytes for the length
field) and )1)1 is a tuo-byte field of binary zeros. The maximum
temporary storage record size is based on user-specified data set
characteristics.
(See temporary storage in the £IC~S System
Proqrammer1s Guides.)
Existing temporary storage data can be updated by specifying the
TYPOPER=REPLACE and ENTRY operands. The specified record within the
message set is released and replaced uith the data provided. If the
data cannot be found an invalid entry number error occur~, and the
TYPOPER=REPLACE and ENTRY operands are ignored.
Chapter 5.1.
Temporary Storage Control (DFHTS Macro)
437
Retrieve a Single Unit of Temporary Data (TYPE=GET)
The format of the DFHTS macro instruction to retrieve a single unit of
temporary data is as follows:
r------r-------·r---------------------------------------------------------~
DFHTS
TYPE=GET
[,STORCLS={TERMINALITERMITEMPSTRGITS} ]
[ ,DATAID=name]
[,TSDADDR={symbo1ic addressIYES}]
[ ,RELEASE= {YES I!QJ ]
[,NORESP=symbo1ic address]
[,IDERROR=symbo1ic address]
[ ,IOERROR=symbo1ic address]
[ ,INVREQ=symbo1ic address]
[,ERROR=symbo1ic address)
This macro instruction causes a single record to be retrieved from
temporary storage. A record stored in temporary storage by a DFHTS
TYPE=PUT macro can be retrieved only by this macro instruction. A
record, once retrieved, can be released by the RELEASE=YES operand. If
RELEASE=NO is specified, or is assumed by default, the record is
retained until released by another task or when CICS/VS is terminated.
The STORCLS and TSDADDR operands are mutually exclusive.
If the TSDADDR operand is specified, the record, including its length
field ~L~~), is placed either in storage at the symbolic address
specified, or at the address in TCATSDA if YES is specified.
If STORCLS=TEMPSTRG is specified, the record, including its length
field (LL~~), is placed in a temporary storage class storage area whose
address is returned in TCATSDA. Before this area can be used as a
TSIOA, the application program must reduce the address in TCATSDA by
eight bytes to include the storage accounting area. This makes it
addressable by TSIOABAR.
If STORCLS=TERMINAL is specified, the record, including its length
field (LL~~, is placed in a terminal class storage area. This area is
prefixed by CICS/VS with an 8 byte storage area. The address of the
prefixed area is returned in TCATSDA.
If neither STORCLS nor TSADDR is specified, STORCLS=TEMPSTRG is
assumed by default and processing is as described above.
The following examples show how to read a single record from
temporary storage with the required addressability and adjustments. The
examples show the use of the DFHTS TYPE=GET macro with STORCLS=TEMPSTRG
assumed by default.
438
CICS/VS
APRM(~L)
TSIOABAR
EQU
COpy
7
DFHTSIOA
DFHTS TYPE=GET,
DATAID=UNIQNME
L TSIOABAR,TCATSDA
SH TSIOABAR,=HISI
*
For COBOL:
02
01
TSIOABAR PIC S9(8) COMP.
DFHTSIOA COpy DFHTSIOA.
DF HTS TYPE=GET,
DATAID=UNIQNME
MOVE TCATSDA TO TSIOABAR.
SUBTRACT 8 FROM TSIOABAR.
*
For PL/I:
%INCLUDE DFHTSIOA;
2 DATA CHAR(10);
DFHTS TYPE=GET,
DATAID=UNIQNME
DCL TSIOBAA FIXED BIN (30) BASED (TSIOBAD);
TSIOABAR=TCATSDA;
TSIOBAB=ADDR (TSIOABAR) ;
TSIOBAA=TSIOBAA-S;
The following examples show the use of the DFHTS
STORCLAS=TERMINAL specified explicitly_
TIOABAR
EQU
COpy
TtPE=GI~
eacro with
7
DFHTIOA
DFHTS TYPE=GET,
STORCLS=TERM,
DATAID=UNIQNME
L TIOABAR,TCATSDA
Chapter 5.7.
Temporary Storage Control
*
*
~FHTS
Bacro)
439
02
01
TIOABAR PIC S9 (8)
COMP.
DFHTIOA COPY DFHTIOA
DFHTS TYPE=GET,
STORCLS=TERM,
DATAID=UNIQNME
MOVE TCATSDA TO TIOABAR.
*
*
For PL/I:
%INCLUDE DFHTIOA;
2 DATA CHAR (10) ;
DFHTS TYPE=GET,
STORCLS=TERM,
DATAID=UNIQNME
TIOABAR=TCAT SD!;
440
CICS/VS APRM(aL)
*
*
Retrieve Data from a Temporary Storage Message Set (TYPE=GETQ)
The format of the DFRTS macro instruction to retrieve a logical record
from a temporary storage message set is as follous:
DFHTS
TYPE=GETQ
[,STORCLS={TERMINALITEMPSTRG} ]
[ , DATAID=name ]
[,TSDADDR={symbolic addresslYES}]
[ , ENTRY= {n I YES} ]
[ , NORESP=symbolic address]
[,IDERROR=symbolic address]
[,IOERROR=symbolic address]
[,INVREQ=symbolic address]
[,ENERROR=symbolic address]
[,ERROR=symbolic address]
This macro causes an entry previously written to a temporary storage
message set, or queue, to be retrieved. A record stored in temporary
storage by a DFHTS TYPE=PUrQ macro can only be retrieved by a TYPE=GETQ
macro. The record to be retrieved from a queue is identified by the
ENTRY operand which indicates its relative position within the queue.
The position of an entry is determined by its order of creation.
Chapter 5.7.
Temporary storage Control (DFHTS Macro)
qq1
=
Release a Single Unit of Temporary Data (TYPE RELEASE)
The format of the DFHTS macro instruction to release a single unit of
data placed in temporary storage by means of a DFHTS TYPE=PUT macro
instruction is as follows:
r------~------r----------------'------------------------------------------,
I
I
I
I
I
I
I
I
I
DFHTS I
I
I
I
I
I
TYPE=RELEASE
[,DATAID=name]
[, NORESP=symbolic address]
[,IDERROR=symbolic address]
[,INVREQ=symbolic address]
[,ERROR=symbolic address]
I
IL_ _ _ _ _ _ _ _ _ _ _ _~------------------------------------------~
I
This macro causes the main or auxiliary storage area used for a
single record of temporary data (created by means of a DFHTS TYPE=PUT
macro instruction) to be released.
If temporary data named in a DFHTS TYPE=RELEASE macro instruction is
in main storage, the area that it occupies is released and returned to
the available dynamic storage area. If the data is in auxiliary
storage, the space is made available for reuse.
A single unit of data should be released at the earliest possible
time to a void using excessive amounts of 'storage for this purpose.
The following examples show how to release a single record from
temporary storage.
For Assembler language:
MVC
TCATSDI,=C!UNIQNME!
DFHTS TYPE=RELEASE
For COBOL:
MOVE 'UNIQNME' TO TCATSDI.
DFHTS TYPE=RELEASE
For PL/I:
TCATSDI='UNIQNME'~
DFHTS TYPE=RELEASE
ijij2
CICS/VS APRM(KL)
Purge a Temporary Storage Message Set (TYPE=PURGE)
The format of the DFHTS macro instruction to purge, or free, data saved
as a temporary storage message set (that is, in response to DFHTS
TYPE=PUTQ macro instructions) is as follows:
r------~------r-----------------------------------------------------------~
I
I
I
I
I
I
I
I
I
DFHTS I TYPE=PURGE
I [, DATAID=name]
I [,NORESP=symbolic address]
I [,IDERROR=symbolic address]
I [,INVREQ=symbolic address]
I [,ERROR=symbolic address]
IL__________________________________________________________
~
I
This macro causes all existing entries in a temporary storage queue
(created by means of DFHTS TYPE=PUTQ macro instructions) to be freed.
There is no way to free selected records from a temporary storage
message set; in particular, a DFHTS TYPE=RELEASE macro instruction
cannot be used to free a record that is part of a message set created by
means of DFHTS TYPE=PUTQ.
If the temporary data is in main storage, the area that it occupies
is freed and returned to the available dynamic storage area. If the
data is in auxiliary storage, the space is made available for reuse.
A temporary storage message set should be purged at the earliest
possible time to avoid using excessive amounts of storage for this
purpose.
Chapter 5.7.
Temporary storage Control
(DFHTS Macro)
443
Test Response to a Request for Temporary Storage Services (TYPE = CHECK)
The format of the DFHTS macro instruction to test the CICS/VS response
to a request for temporary storage services is as folIous:
i
I
I
I
I
I
I
I
I
I
IL_______
DFHTS
~
_______ L
TIPE=CHECK
[,NOSPACE=symnolic address]
[ ,NORESP=symbolic address]
[,IDERROR=symbolic address]
[,IOERROR=symbolic address]
[,INVREQ=symbolic address]
[,ENERROR=symbolic address]
[,ERROR=symbolic address]
________________________________________________________
~
Temporary Storage Response Codes
The Assembler-language or PL/I programmer can access temporary storage
response codes at TCATSTRi the COBOL programmer can access temporary
storage response codes at TCATSRC. In addition, the COBOL programmer
can refer to the response codes by means of condition names (TSNORESP,
TSIDERROR, and so on).
(See the examples at the end of this
discussion~) The possible response codes and the conditions to which
they correspond are identified in the right-hand columns of Figure 5.71. DFHTS macro instructions for which the conditions are applicable are
shouu at the left~
44q
CICS/VS
APR~l
(ML)
Temporary
Storage
Request by
DFHTS Hacro
Instruction
Condition
I
I
Response Code
I
I
IAssemblerl COBOL
PL/I
ALL
NOR ESP
(Normal response)
X '00'
LOH-VALUES
(TSllORESP)
00000000
GET,GETQ,
RELEASE,PURGE,
CHECK
IDERROR
(Identifica tion
error)
X'02'
12-2-9
(TSIDERROR)
00000010
PUT ,PUTQ, GET,
GETQ,CHECK
IOERROR
(Input/Output
error)
X'04 1
12-4-~
00000100
All
INVREQ
(Invalid request)
X'20'
11-0-1-8-9
(TSINVREQ)
00100000
PUTQ,GETQ,
CHECK
ENERROR
X110'
12-1-9
(TSEUERROR)
00010000
PUT ,pu'rQ
NOSPACE
(No space on
auxiliary storage)
X'OSI
12-8-9
(TSNOSPACE)
00001000
All
ERROR
(Any of above but
unspecified)
(Uote 2)
(Note 2)
(En~ry
(TSIOERROR)
error)
(Note
2)
l!otes:
1. The names enclosed in parentheses in the COBOL column indicate
the condition names generated by CICS/VS. These names cay be used
in testing for the conditions in a COBOL program.
2. The test for the ERROR response is satisfied by a not equal
condition; that is, not X'OO', not LOW-VALUES, or not 00000000
for Assembler, COBOL p and PL/I, respectively.
Figure 5.7-1.
Temporary Storage Control Response Codes
If the application programmer does not check for a particular
response to a service request, and the exception condition corresponding
to that response occurs, program flou proceeds to the next seqaential
instruction in the application program.
The following examples show how to examine the response code provided
by CICS/VS and transfer control to the appropriate user-written
exception-handling routine.
For Assembler language:
GOOD
DFHTS TYPE=GET,
DATAID=UNIQNHE,
TSDADDR=YES
CLI
TCATSTR,X'OOI
BE
GOOD
DFHPC TYPB=ABEND
DS
OH
Chapter 5.7.
*
*
NORMAL RESPONSE
Temporary Storage Control
~FHTS
Macro)
445
For COBOL:
DFHTS TYPE=GET,
DATAID=UNIQNME,
TSDADDR=YES
IF TCATSRC = , , THEN GO TO GOOD.
DFHPC TYPE=ABEND
*
*
NOTE
12-0-1-8-9 NORESP.
GOOD.
Alternatively, the COBOL programmer may test responses by using the
CICS/VS generated condition names.
IF TSNORESP THEN GO TO GOOD.
For PLII:
DFHTS TYPE=GET,
DATAID=UNIQNME,
TSDADDR=YES
IF TCATSTR='OIB THEN GO TO GOOD;
DFHPC TYPE=ABEND
GOOD:
446
CICS/VS APRM (liL)
*
*
/*
NOR~AL
RESPONSE */
Operands of DFHTS Macro
COND=YES
indicates that control is to be returned to the application
program when the request cannot be satisfied immediately
because sufficient space is not available on the temporary
storage data set. If this operand is omitted, the requesting
task is suspended when no space is available and is resumed
when the space becomes available.
Space becomes available as
it is released by other tasks in the system.
DATAID=name
specifies the unique alphameric name, up to eight characters in
length, to be assigned to the temporary data to be stored.
If
this operand is omitted, the name is assumed to be in TCATSDI.
Note: The application program should not construct a DATAID
beginning with any of the hexadecimal characters FA through FF.
Use of these characters for this purpose is reserved for
CICS/VS.
ENERROR=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the entry number specified or
implied is invalid (that is, not within the limits of the
message set).
ENTRY=
specifies the number, relative to one, of the logical record to
be retrieved from the message set.
n
is a decimal numeral to be taken as the relative number of
the logical record to be retrieved. This number may be the
number of any entry that has been written to the temporary
storage message set.
YES
indicates that the number (in binary) of the logical record
to be retrieved is in TCA'rSR N, a two-byte field.
If this operand is omitted, CICS/VS retrieves (1) the first
logical record from the message set, for the first retrieval
request, or (2) the next sequential logical record following
the last-retrieved record, for other than the first request.
In the latter case, the relative record number is returned in
TCATSRN.
ERROR=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an error occurs and the
corresponding specific error routine operand (for example,
IDERROR) has not been specified.
Chapter 5.7.
Temporary storage Control
~FHTS
Macro)
447
IDERROR=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the symbolic destination
identification referred to by a GET, GETQ, RELEASE, or PURGE
request cannot be found in either main storage or auxiliary
storage.
INVREQ=symbolic address
.
specifies the entry label of the user-written routine to which
control is to be passed if (1) a PUT or PUTQ request refers to
data whose length is equal to zero or greater than the control
interval size of the auxiliary data set minus 84 bytes for
control information, or (2) the request is otherwise determined
to be invalid.
IOERROR=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an unrecoverable input/output error
occurs.
NORESP=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if no errors occur during temporary
storage processing. NORESP siJnifies "normal response."
"NOSPACE=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed when insufficient space is available on
the temporary storage data set to contain the data in a POT or
PUTQ request. The user-written NOSPACE routine is passed
control only if COND=YES is also specified in the PUT or PUTQ
request.
RELEASE=
specifies the disposition of the temporary data following the
move operation.
YES
the data and storage area used for the data are to be
released after this operation.
NO
the data is to be retained, available for subsequent
similar reference.
STORCLS=
specifies the class of storage to be obtained for the temporary
data. This operand is ignored if TSADDR is specified.
TERMINAL (TERM)
specifies that the data is to be placed in a TERMINAL class
storage area.
448
CICS/VS APRM(ML)
TEMPSTRG(TS)
specifies that the data is to be placed in a temporary storage
area.
If this operand is omitted, TEMPSTRG is assumed.
STORFAC=
specifies the type of storage to be used for the temporary
data.
AUXILIARY
indicates that the data is to be placed in auxiliary
storage on a direct access storage device.
MAIN
indicates that the data is to be placed in main storage.
If this operand is omitted, AUXILIARY is assumed.
TSDADDR=
specifies the symbolic address of the data portion
(including the LL~~ field) of the area in which the temporary
data is stored.
symbolic address
is the symbolic address of the data portion of the storage
area that contains the temporary data.
YES
indicates that the symbolic address of the data portion of
the storage area has been placed in TCATSDA by the
application programmer~
If this operand is omitted, the appropriate symbolic address is
assumed to be in TCATSDA.
TYPOPER=REPLACE
indicates that the specified record within the data set or
message set is to be released and replaced with the record or
data provided. If the message set does not exist (DATAID
cannot be found), an invalid entry number error occurs, and the
data provided is placed in temporary storage as in a normal
PUTQ without TYPOPER=REPLACE specified.
For TYPE=PUTQ, whenever REPLACE is specified the ENTRY operand
must also be coded.
Chapter 5.7.
Temporary Storage Control (DFHTS Macro)
449
Part 6. CICS/VS Built-In Functions
tJ51
Chapter 6.1. Introduction to CICS/VS Built-In Functions
Several commonly used functions are available to the application
programmer through CICS/VS macro instructions. These are functions
which would otherwise have to be coded as separate subroutines by the
programmer. These functions, referred to as built-in functions, provide
the following services:
•
Table search
•
Phonetic conversion
•
Verification of a data field
o
Editing of a data field
•
Bit manipulation
•
Input formatting
•
Weighted retrieval
Requests for these services ars communicated to the CICS/VS built-in
functions program (DFHBFP) through the DFHBIF macro instruction.
DFHBFP
is then executed, at the priority of the requesting task, under control
of the common control communication area ('rCACCCA) of the TCA of the
requesting task.
Normally, control is returned to the next sequential
instruction following the macro expansion in the requesting program;
however, conditional branch options can be specified in the macro
request if desired.
Since DFHBFP uses TC~CCCA, the application program must issue the
DFHBFTCA macro instruction to copy the symbolic storage definition for
t~is area and store any required information therein before issuing the
DFHBIF macro instruction. Chapter 6.2 explains how to do this.
The formats and operands of the DFHBIF macro instruction are
described in Chapter 6.3.
Chapter 6.1.
Introduction to CICS/VS Built-in Functions
453
Chapter 6.2. Storage Definition for Built-In Functions
(DFHBFTCA Macro)
When CICS/VS built-in functions (BIFs) are used in an application
program, the symbolic storage definition for the TCACCCA used by these
built-in functions must be copied into the application program. This
copying is achieved by means of a DFBBFTCA macro instruction, which must
im~ediately follow the statement that copies the TCA and the user1s
definition of a TWA, if any.
The format of the DFHBFTCA macro instruction is as follows:
I
I
IDFHBFTCAI [OPTION=(BASICIWTRET}]
I
I
where:
OPTION=
indicates which built-in functions are to be used.
BASIC
is required if any of the following functions are used:
table search, phonetic conversion, field verification,
field editing, bit manipulation, or input formatting.
WTRET
is required if weighted retrieval is used.
If the OPTION operand is omitted, both BASIC and WTRET are
assumed ..
The following examples show the statements n8eded to copy the
symbolic storage definitions referred to by the built-in functions,
positioned as required.
NAME
STREET
CITY
STATE
COP Y DFHTCADS
DS
CL20
DS
CL20
DS
CL10
DS
CL3
DFHBFTCA
·:rWA
TWA
TWA
TWA
For COBOL:
01 DFHTCADS COpy DFBTCADS.
02 NAME PICT X(20).
02 STREET PIC X ~O).
02 CITY PIC X (10) •
02 STATE PIC X(3).
DFHBFTCA
Chapter 6.2.
NOTE
NOTE
NOTE
NOTE
TWA
TWA
TWA
TWA
storage Definition for Built-in Functions
455
%INCLUDE (DFHTCADS);
2 NAME CHAR (20) ,
2 STREET CHAR (20) ,
2 CITY CHAR(10),
2 STATE CHAR (3) ;
DFHBPTCA
456
CICS/VS APRM (ML)
/*TWA*/
/*TWA*/
/*TWA*/
/*TWA*/
Chapter 6.3. CICS/VS Built-In Functions (DFHBIF Macro)
Table Search Built-in Function (TYPE=TSEARCH)
The format of the DFHBIP macro instruction to request the search of a
table is as follows:
~-----r-------~---------------------------------------------------------'
DFHBIF
~
_____ L-_______
TYPE=TSEARCH
[ ,ARG=symbolic address]
[,TARGET=symbolic address]
[ ,ATABLE= ([ sa 1 ][ ,sa21 YES} ][ , n 1][, {n21 YES} ][ , n3]) ]
[, FTABLE= ([ {sa 11 YES} ][ , {sa21 YES} ][ , {n 11 YES} ]
[, {n2IYES}]) ]
[,ORDER={ASCENDINGIDESCENDING} ]
[,SUBST={symbolic addressl 'literal value'}]
[ ,NOMATCH=symbolic address]
[,INDEX=symbolic address]
[ ,RANGE=YES]
[,ERROR=symbolic address]
~
________________________________________ .________________
~
This macro specifies that a table is to be searched for a given
entry, causing a corresponding value within that table or a second
table, the address of the corresponding value, and the index of the
selected entry (relative to one) to be returned. The search argument is
compared on a byte-for-byte basis with a specified field of entries in
the table being searched. Optionally, a default value can be returned
in lieu of a corresponding value if the searched-for entry is not found.
If an index is requested, but the entry is not found, an index value of
zero is returned.
Hote: In the syntax display, symbolic address and numeric value have,
in some cases, been shortened to "xa" and linn respectively.
Returned Values
An entry in the argument table that matches the search argument
satisfies the table search built-in function. If such an entry is
,found, the address of the corresponding entry in the function table is
returned in TCATSA5, a fullword field.
If the TARGET operand is specified, the function value is returned in
the location identified by that operand.
If the function table contains
more than one matching entry, the address (and the function value, if
requested) of the first matching entry encountered during the search is
returned.
If the ORDER operand is specified, a binary search is performed, and
the address returned is that of the first matching entry found.
Chapter 6.3.
CICS/VS Built-in Functions (DFHBIF Macro)
457
If the ORDER operand is omitted, a sequential search is performed,
starting at the last entry in the table, and the address returned is
that of the last matching entry in the table~ The index of the matching
entry is returned in TCATSH4 and in the field identified by the INDEX
operand if specified.
If the RANGE=YES operand is specified, a matching entry satisfies the
search as described above. If no matching entry is found, the search is
satisfied in an alternative manner:
o
If ORDER=ASCENDING is specified, the argument table entry having
the largest argument value less than the search argument satisfies
the search.
•
If ORDER=DESCENDING is specified, the argument table entry having
the smallest argument value greater than the search argument
satisfies the search.
Figure 6.3-1 defines the conditions that may occur during a table
search and defines the possible return codes.
r
,,
Condition
,,Match
,, Pound
JATABLE Field Address < Entry Address
, (symbolic address2 < symbolic
, address 1)
J
,,
-,
Response Code
JAssembler, COBOL
PLjI
X '00'
LOW-VALUES 'OOOOOOOO'B
(TCATSMH)
X '04 '
12-4-9
'OOOOO100'B
(rCATSER2)
'OOOO1000'B
12-8-9
(TCATSER 1)
PTABLE Field Address < Entry Address
(symbolic address2 < symbolic
address 1)
X
'08 '
No Match Pound
X
'FO'
'0 '
'0 '
Note: The names enclosed in parentheses in the COBOL column
indicate the condition names generated by CICS/VS. These names may
be used in testing for the respective conditions in a COBOL program.
Figure 6.3-1.
~~~mple
Table Search Response Codes
- Separate Tables
The following example shows how the DFHBIF TYPE=TSEARCH macro
instruction can be used in an Assembler-language program. A fourcharacter argument is matched against fields in a seven-entry argument
table. If the search is satisfied, the address of a two-character
corresponding field in the function table is placed in TCATSA5 and the
index value of the matching entry is placed in TCATSH4. If no matching
entry is found, a branch to BR1 occurs.
458
CICS/VS APRM(ML)
DFHBIF
TYPE=TSEARCH,
ARG=ARG 1,
ATABLE=(ATBL,AFLD,9,4,7),
FTABLE=(PTBL,FFLD,5,2),
ERROR=ERROR1,
NOMATCH=BRl
*
*
*
*
*
ERRORl
BRl
ATBL
AFLD
FTBL
FFLD
ARGl
DS
DS
DS
DS
DS
DS
DS
DS
DS
Example -
FIRST ENTRY OF ARG TABLE
OXL9
XL5
XL4
6XL9
OXL5
XL3
XL2
6XL5
XL4
FIRST ARGUMENT FIELD
SPACE FOR SIX MORE ENTRIES
FIaST ENTRY OF FUN TABLE
FIRST FUNCT ION PIELD
SPACE FOR SIX MORE ENTRIES
SEARCH ARGUMENT
Complex Table
The following example shows hov the TYPE=TSEARCH macro is used for a
complex table, that is, a table which contains both argument and
function values. The search is similar to that above, except that only
one table is described.
DFHBIP
TYPE=TSEARCH,
ARG=ARG1,
ATABLE=(TBL1,PLDA,S,2,3),
PTABLE= (TBL 1 ,PLDF, 5,3),
ERROR=ERROR1,
NOMATCH=BR1
*
*
**
*
ERROR1
BRl
TBLl
FLDA
FLDF
ARG1
DS
DS
DS
DS
DS
OCLS
CL2
CL3
2CL5
CL2
Chapter 6.3.
FIRST ENTRY OF ARG/FUN TABLE
FIRST ARGUMENT FIELD
FIRST FUNCTION FIELD
SPACE FOR TWO MORE ENTRIES
SEARCH ARGUMENT
CICS/VS Built-in Functions (DFHBIF Macro)
459
Phonetic Conversion Built-in Function (TYPE=PHONETIC)
The format of the DFHBIF macro instructions to request that a 16-byte
field of data be encoded phonetically is as follows:
r-------~-------·t------------------------------------------------------------~
I
I
I
I
I
I
DFHBIFI TYPE=PHONETIC
I [,FIELD=symbolic address]
I [,ERROR=symbolic address]
I
This macro converts a name into a key, which can be used to access
data in a data base data set. The key that is generated is based upon
the sound of the name; names that sound alike, even though spelled
differently, produce identical keys.
For example, the names SMITH,
SMYTH, and SMYTHE produce a phonetic key of SS30.
In addition to the phonetic conversion built-in function, a CICS/VS
subroutine that performs similar conversion of keys is available for use
by offline user-written programs. Together, these facilities allow the
CICS/VS user to organize his file according to name ~r any similar
alphabetic key) and access the file using search arguments that may be
misspelled or misunderstood to retrieve the required data.
The returned value is placed at TCAPHON. This valu~ is the four-byte
phonetic equivalent of the data passed to the built-in function.
It
consists of the first character of the data and three EBCDIC numbers
representing the characters in the remainder of the data.
If an error is det6cted during execution of the phonetic conversion
macro, an error code is placed in TCAPHNR.
Figure 6.3-2 shows the
conditions that cause an error, and the codes that are returned.
r----------------------------------------------------------------------------~
Response Code
Assembler
Condition
1st character not alphabetic
COBOL
X'SO'
'& '
PL/I
'& •
(TCAPINN)
Note:
Th e names enclosed in parentheses in the COBOL column are the
condition-names generated by CICS/VS.
Figure 6.3-2.
460
Phonetic Conversion Response Codes
CICS/V S AP RM (I.'1L)
Phonetic Coding Method
The application programmer need not be familiar \lith the CICS/VS method
of phonetic coding to use the phonetic conversion function. Remember
that the first character of the field to be coded is not changed; it
becomes the first character of the returned value. Three digits are
selected to represent the remaining characters in accordance with the
following rules:
Code Value
B, P, F,
V
C, G, J, K, Q,
s, X,
1
2
3
4
5
6
Z
D, T
L
M,
N
R
A, E, H, I, 0, Y, H, U,
Bypassed, no
code value
blanks, and nonalphabetic
characters
o
Lowercase letters are translated to uppercase.
o
Double letters are coded as a single letter.
o
Two or more adjacent letters with the same value are coded as a
single lett·er.
o
If more than three EBCDIC numbers can be computed from the data,
only the first three are used.
o
If fewer than three numbers can be computed from the name, the
result is padded on the right \lith EBCDIC zeros to form a four-byte
result.
Examples
DFHBIF
TYPE=PHONETIC,
FIELD=NAME
*
where NAME is a 16-byte field, yields results as follows:
LEHMICKE
WONG
sao
yields
yields
yields
L520
W520
SOOO
A CICS/VS subroutine that performs phonetic conversion of 16-character
names in the same manner as the phonetic conversion built-in function is
available for use by offline user-written programs. The subroutine can
be called by a program running under any of the operating systems under
which CICS/VS can be run. A 16-character name to be converted is
provided as input to the subroutine; the four-byte phonetic equivalent
of that name is returned as a result. The rules given above under
"Phonetic Coding Method" are applied in the conversion process.
Chapter 6.3.
CICSjVS Built-in Functions (DFHBIF Macro)
461
The general form of the macro instruction to invoke the subroutine is
as follows:
For Assembler language:
CALL DFHPHN,(lang,name,phon)
For COBOL:
CALL 'DFHPHN' USING lang name phon.
For PL/I:
CALL DFHPHN (lang,name,phon);
where:
lang
is the symbolic address of a one-byte code indicating the
programming language being used: XIFO' indicates COBOL or
Assembler language; X'F1~ indicates PL/I. If an error occurs
during processing of this request, X·SO· is returned in this
location. If no error occurs, X'OO' is returned, and the
location must be reset to indicate the programming language
before the location can be reused.
name
is the symbolic address of the field that contains the 16character name to be converted.
phon
is the symoolic address of the field in which the four-byte
phonetic equivalent of the name passed to the subroutine is
returned to the calling program.
462
eICS/VS APRH (ML)
Field Verify Built-in Function (TYPE=FVERIFY)
The format of the DFHBIF macro instruction to verify the contents of a
data field is as follows:
I
I
I
I
I
I
I
I
I
I
I _______
L
~
DFHBIFI
I
I
I
I
I
_______ I
TYPE=FVERIFY
[, FIELD=symbolic address]
[, LENGTH= {symbolic address Inumeric value} ]
[, ALPHA=symbolic address]
[, NUMER IC=symbolic address]
[,PACKED=symbolic address]
LI_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~
This macro verifies that the contents of a data field are:
o
Entirely alphabetic:
blanks or A-Z
o
Entirely EBCDIC numbers, with or without trailing sign:
through X IF9')
o
Entirely packed decimal (COMPUTATIONAL-3 in American National
standard CANS) COBOL or FIXED DECIMAL in PL/I)
0-9 (XIFOI
A branch is made to an appropriate user-written routine accordingly.
The ALPHA, NUMERIC, and PACKED operands may be specified in any
combination or order, but at least one of them must be specified. The
conditions specified are tested upon request in the order ALPHA,
NUMERIC, P~CKED, irrespective of the order of the operands. If none of
the test conditions is met, control goes to the instruction following
the DFHBIF TYPE=FVERIFY macro instruction in the application program.
Returned Values
The purpose of the field verify built-in function is to determine what
kind of data must be processed and cause control to be transferred to an
appropriate routine in the application program accordingly. The results
of the verify built-in function can be tested by examining the response
code at TCACHKR. Figure 6.3-3 indicates the conditions and response
codes.
Chapter 6.3.
CICS/VS Built-in Functions (DFHBIF Macro)
463
Response Code
Assembler
Condition
COBOL
PL/I
Packed field
X·20·
11-4-9
(TCACKPK)
00100000
Numeric field
X·40·
No punches
(TCACKNM)
01000000
Alphabetic field
X·SO·
12-0-1-8
(TCACKAL)
10000000
Mixed field
X·EO·
0-2-S
(TCACKMX)
11100000
!iote:
The names in parentheses in the COBOL column indicate the
condition names generated by CICS/VS. These names may be used
in testing for the respective conditions in a COBOL program.
I Figure 6.3-3.
DFHBIF
Field Verify Response Codes
TYPE=FVERIPY,
FIELD=CONT,
LENGTH=16,
ALPHA =MYROUT
*
*
*
Execution of the DFHBIF macro instruction above causes the contents
of CaNT, a 16-byte field, to be checked to determine whether it contains
only alphabetic characters and/or blanks. If it does, control is
transferred to MYROUT.
Otherwise, control returns to the instruction
following this DFHBIF instruction in the application program.
464
CICS/VS APRM(ML)
Field Edit Built-in Function (TYPE=DEEDIT)
The format of the DPHBIP macro instruction to edit a data field is as
follows:
,
I
I
I
I
I
L
,r-------------------------------------------------------------,
I
DPHBIPI TYPE=DEEDIT
I [,FIELD=symbolic address]
I [, LENGTH= {symbolic address I numeric value} ]
L--_________ I _______________________________________________________________
II~
This macro specifies that alphabetic and/or special characters, are
to be removed from an EBCDIC data field.
The remaining, numeric
characters, are right-justified with zero padding at the left as
necessary. If the field ends with a minus sign or 'CRI, a negative zone
is placed over the low--order byte.
Returned Values
All bytes (except the rightmost byte) containing other than EBCDIC
numeric characters are deleted from the data field. The remaining
characters are right-justified in the field with zero padding at the
left as necessary.
If the field ends with a minus sign or a ICR', a
negative zone (XIDI) is placed over the rightmost (low-order) byte. The
zone portion of the rightmost byte may contain any hexadecimal character
from X'AI through XIPI. The digit portion of this byte may contain one
of the hexadecimal digits from XIO' through Xigi. Where this is the
case, the rightmost byte is returned unaltered (see the example below).
This permits the application program to operate on a zoned numeric
field. In any case, the returned value is in the field that initially
contained the unedited data.
Example
DPHBIP
TYPE=DEEDIT,
FIELD=CONTG,
LENGTH=9
*
*
Execution of this macro instruction removes all characters other than
EBCDIC numbers from CONTG, a nine-byte field, and returns the edited
result in that field to the application program. Say, for example, the
field contains 14-6704/B before the DFHBIF TYPE=DEEDIT macro instruction
is issued. After editing, it contains 00146704B.
Chapter 6.3.
CICS/VS Built-in Functions (DFHBIF Macro)
465
Bit Manipulation Built-in Functions
The bit manipulation built-in functions are designed to change or test
the state of specified bits in a given area of main storage. They are
particularly useful for COBOL application programs, which are otherwise
unable to manipulate bits.
The built-in functions are invoked by different versions of the
DFHBIF macro instruction, as follows:
TYPE=BITSETON
ensures that all bits selected by a specified bit
pattern are on after execution of the macro.
TYPE=BITSETOFF ensures that all bits selected by a specified bit
pattern are off after execution of the macro.
TYPE=BITFLIP
causes the state of each bit selected by a specified
bit pattern to be changed.
TYPE=BITEST
causes the state of each bit, selectad by a specified
bit pattern, to be tested, and an indicator to be set.
TYPE=BITSETON
The format of the DFHBIF macro instruction to set bits in a byte to an
on-condition is as follows:
~-----.--------.------------------------------------------------------------,
I
DFHBIFI
I
I
I
I
I
TYPE=BITSETON
[,FIELD=symbolic address]
[,BIT={symbolic addresslvalue}]
[,BITON=symbolic address]
[,BITOFF=symbolic address]
I
This macro specifies that all bits selected by a specified bit
pattern are on after execution of the macro. The application programmer
specifies the eight-bit mask (nit pattern) to be applied against the
byte containing bits to be operated on. The mask can be described by a
single EBCDIC character within single quotation marks: for example,
or -M-. Alternatively, the symbolic address of a one-byte field
containing the mask can be specified. If desired, control can be
transferred to a specified location if all affected bits (or all bits in
the byte) are on after completion of the bit manipulation.
-5-
The returned value is the contents of the byte specified in the FIELD
operand, with selected bits modified as specified.
466
CICS/VS APRM(ML)
The macro instruction
DFHBIF
TYPE=BITSETON,
FIELD=DATAP,
BIT=PATERN,
BITON=BLABEL
*
**
PATERN DC X IFFI
ensures that all bits of the one-byte field DATAF are set on and causes
a branch to BLABEL.
TYPE = BI TS ETOFF
The format of the DFHBIF macro instruction to set bits in a byte to an
off-condition is as follows:
r------~------Ir------------------------------------------------------------,
I
I
I
I
I
I
IL
I
DFHBIFI TYPE=BITSETOFF
I [,PIELD=symbolic address]
I [,BIT= {symbolic address t value} ]
I [,BITON=symbolic address]
t [, BITOFF=symbolic address]
tL__________________________________________________________
~
This macro specifies that all bits selected by a specified bit
pattern are off after execution of this macro. The application
programmer specifies the eight-bit mask (bit pattern) to be applied
against the byte containing bits to be operated on. The mask can be
described by a single EBCDIC character within single quotation marks:
for example, lSI or IMI.
Alternatively, the symbolic address of a onebyte field containing the mask can be specified. If desired, control
can be transferred to a specified location if all affected bits (or all
bits in the byt~) are off, after completion of the bit manipulation.
The returned value is the contents of the byte specified in the FIELD
operand, with selected bits modified as specified.
TYPE=BITFLIP
The format of the DFHBIF macro instruction to change the state of bits
in a byte is as follows:
Chapter 6.3.
CICSjVS Buiit-in Functions (DPHBIF Macro)
467
~-----r--------r----------------------------------------------------------~
L ______
I
DFHBIFI TYPE=BITFLIP
I [,FIELD=symbolic address]
I [,BIT={symbolic addresslvalue}]
I [,BITON=symbolic address]
I [,BITOFF=symbolic address]
_______ .II_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
~
~
This macro specifies that the state of each bit selected by a
specified bit pattern is changed. The application programmer specifies
the eight-bit mask ~it pattern) to be applied against the byte
containing bits to be operated on. The mask can be described by a
single EBCDIC character within single quotation marks: for example, '5'
or 'M'. Alternatively, the symbolic address of a one-byte field
containing the mask can be specified. If desired, control can be
transferred to a specified location if all affected bits (or all bits in
the byte) are on, or if all affected bits (or all bits in the byte) are
off, after completion of the bit manipulation.
The returned value is the contents of the byte specified in the FIELD
operand, with selected bits modified as specified.
TYPE=BITEST
The format of the DFHBIF macro instruction to test the state of specific
bits in main storage is as follows:
I
I
I
I
I
I
I
IL ______
I
I
DFHBIFI
I
I
I
I
I
______ L
TYPE=BITEST
[,FIELD=symbolic address]
[,BIT={symbolic addresslvalue}]
[,BITON=symbolic address]
[,BITOFF=symbolic address]
~
This macro specifies that the state of each bit in a specified bit
pattern is to be tested and an indicator is to be set accordingly. The
BIT operand specifies the eight-bit mask (bit pattern) that is to be
applied against the byte containing bits to be operated on. The mask
can be described by a single EBCDIC character within single quotation
marks: for example, '5' or 'M'.
Alternatively, the symbolic address of
a one-byte field containing the mask can be specified.
If desired,
control can be transferred to a specified location if all affected bits
(or all bits in the byte) are on, or if all affected bits (or all bits
in the byte) are off, after completion of the bit manipulation. This
built-in function is particularly useful for COBOL programs, which are
otherwise unable to carry out bit manipulation.
468
eICS/VS APRM(ML)
Returned Values
For BITEST, the result of the test is returned in TCABITR as shown in
Figure 6.3-4. If BITON, BITOFF, or both BITON and BITOFF are specified,
and if certain conditions are met as described in the explanations of
these operands, control is transferred.
I
1
I Condition
1
I Testad Bits Are Off
I
I Tested Bits Are On
I
Response Code in TCABITR
Assembler
COBOL
PLjI
X'OO'
LOW-VALUES
(TCABIFOF)
'OOOOOOOO'B
XIFO'
'a'
'0'
(TCABIFON)
1-------------------------------------------------I Note:
I The-names enclosed in parentheses in the COBOL column indicate
I the condition names generated by CICS/VS. These names may be
IL______________________________
used in testing for the conditions
in
a COBOL program.
________
.________________________
___
~
Figure 6.3-4.
Bit Test Response Codes
The macro instruction
DFHBIF
TYPE=BITEST,
BIT='!',
BITOFF=CLABEL
*
*
causes a bit pattern of 110000u1 to be applied to the one-byte field
whose address is stored in TCABITF.
If all tested bits are off, control
is transferred to CLABEL.
Chapter 6.3.
CICS/VS Built-in Functions (DFHBIF Macro)
469
Input Formatting Built-in Functions
There are two versions of the DFHBIF built-in function to handle input
formatting, as follows:
TYPE=DEFLDNM defines keywords in free-format input
TYPE=INFORMAT specifies formatting of terminal input
Both these versions are described later in this chapter.
The input formatting built-in function allows free-format terminal
input to be converted into a predefined fixed format that can be
processed by the application program •. The application program can
accept any of three forms of input from the terminal. These forms are
discussed in order of increased flexibility oelow.
FIXED FORMAT
This is the simplest case, but it requires a rigid adherence to form.
The input transaction must be identical in format to the fixed internal
format established by statements in the application program.
For
example, assume the fixed internal format for data consisting of a
transaction iden tification'; last name, first name, and middle initial;
and identification number is as follows:
£ols
1-4
.2 1
TRANS )t1}f LAST
ID
NAME
12 £1
)6)6
FIRST
NAME
1.1
33
34
36
42
JzIJzI
M
)6)1
ID
NO
EOB
I
The input transaction must be formatted as shown by the following
example:
INQR
HUGHES
.JOHN
Q
096556
EOB
Each input field must be entered by the terminal operator in the
positions established for it in the fixed internal format.
POSITIONAL FORMAT
This option allows the terminal operator to enter a systeru-program~er
selected field-separator character to indicate the end of a field or the
absence of a field. The order of the fields on input must be the same
as the order established for the fixed internal format; the field
lengths need not be the same. If other fields follow, the end of a
field or the absence of a field within the input must be indicated by a
field-separator character.
Assume that input consisting of a transaction identification; last
name, first name, and middle initial; and id~ntification number is to be
entered from a terminal. Further assume that the input formatting
built-in function is invoked by the application program to process this
input, recognizing the slash (/) as a field-separator character. The
following examples show permissible free-format positional input. Each
input transaction is terminated by an end-of-block (EOB) character.
410
CICS/V S APRM (ML)
•
Complete input
INQR/HUGHES/JOHN/Q/096556 EOB
•
Middle initial unknown
INQR/HUGHES/JOHN//096556 EOB
•
Middle initial and identification number unknown
INQR/HUGHES/JOHN EOB
KEYWORD FORMAT
The keyword format provides an even greater degree of flexibility in
that terminal input can be entered in any order. The terminal operator
need only be familiar with the keyword identifiers that have been
established for the input fields.
Each keyword identifier consists of
up to four characters selected by the application programmer. The
keyword identifier must be preceded by a field-name start character and
followed by a field-separator character, both of which must be specified
at system initialization by the system programmer. If either of these
characters is not specified, the default assumed is a blank; however,
since the field-name start character must be different from the fieldseparator character, it is invalid to take both defaults.
As an example, assume that keyword identifiers are established by use
of the TYPE=DEFLDNM macro (described later in this chapter) as follows:
LN
FN
MI
ID
last name field
first name field
middle initial field
identification number
Further assume that the period has been specified as the field-name
start character and the equal sign has been specified as the fieldseparator character. The following examples show permissible freeformat keyword input.
•
Complete input
INQR.FN=JOHN.MI=Q.ID=096556.LN=HUGHES EOB
•
First name unknown
INQR.LN=HUGHES.MI=Q.ID=096556 EOB
•
First name and identification number unknown
INQR.LN=HUGHES.MI=Q EOB
The first entry in each of these examples is the transaction
identification. Since CICS/VS expects this identification, it must be
first and no keyword identifier is required for it.
Succeeding data
fields are ent8red in any order. The input is t~rminated by the end-ofblock (EOB) character.
Chapter 6.3.
CICS/VS Built-in Functions (DFflBIF Macro)
471
COMBINATION INPUT
CICS/VS DFHBIF macro instructions can be included in an application
program to permit a combination of fixed, positional, and keyword input.
For example, the following variations may be allowed.
•
Complete input
INQR.LN=HUGHES.FN=JOHN/Q/096556 EOB
INQR.FN=JOHN.LN=HUGHES.MI=Q/096556 EOB
INQR/HUGHES/JOHN/Q 096556 EOB
•
First name unknown
INQR.LN=HUGBES//Q/096556 EOB
INQR/HUGHES//Q.ID=096S56 EOB
INQR HUGHES//Q 096556 EOB
•
First name and identification number unknown
INQR.LN=HUGHES//Q EOB
INQR/HUGHES.MI=Q EOB
INQR HOGHES.MI=Q EOB
The application programmer can write a program to handle free-format
input entered from a terminal.
The free-format input may be either
p0sitional or keyword-oriented, or both, and may be entered in
combination with fixed-format input.
Examples are:
INQR/HUGHES/JOHN/Q/0965S6 EOB
positional
INQR.FN=JOHN.MI=Q.ID=096556.LN=HUGHES EOB
key word-orien ted
A task that issues DFHBIF macro instructions to provide input
formatting must be attached to a terminal.
Storage Definition
As a first step in defining storage, the programmer must copy the
CICS/VS control section of the terminal input/output area (TIOA) into
his program.
Definitions of the fields for whiCh input data may be
entered should follow the definition of the CICS/VS control section.
For example, the Assembler-language programmer may write the following
code:
*
TIOATI
TIOALN
TIOAFN
TIOAMI
TIOA ID
COpy
DFHTIOA
DS
DS
DS
DS
DS
CL4
CL15
CL9
CLl
CL6
BEGINNING OF TIOA
TRANS ID
LAST NAME
FIRST NAME
MIDDLE INITIAL
IDENTIFICATION
TIOADBA is the CICS/VS-established name representing the first byte
of the user's section of the TIOA for Assembler language only.
Succeeding names are application-programmer-selacted identifiers of the
input fields.
(The copying of symbolic storage definitions is described
in Part 2.)
472
CICS/VS APRM(ML)
TYPE=DEFLONM
The format of the DFHBIF macro instruction that defines keywords in
free-format input is as follows:
I
I
DFHBIFI TYPE=DEFLDNM
I , NAMES= (keyword[ ,keyword, ••• ])
I ,LABEL=symbolic address
I
If this macro instruction is used in a COBOL program; it must appear
in the Working storage section of the program.
It must app~ar with
other data definitions in an Assembler-language or PL/I program. This
macro instruction is not needed if only free-format positional input is
to be handled by a program.
For example, a DFHBIF TYPE=DEFLDNM macro instruction defining
keywords that the user can entar to refer to fields of the TIOA in the
previous section, "storage Definition," is:
DFHBIF
TYPE=DEPLDNM,
NAMES= (TI ,LN ,FN ,MI,ID) ,
LABEL=DEFI
*
*
In this example, the keywords are formed by taking the last two
characters of the TIOA field names. Use of similar names within the
DFHBIF macro instruction and the TIOA definition is wise programming
practice, but not a requirement. Thus, the following macro instruction
is also acceptable.
DFHBIF
TYPE=DEFLDNM,
NALi E S = (TR AN, LAS T , FIR, M10 , IDE N) ,
LABEL=MYIN
*
*
In both of these examples, the first keyword is a dummy name, because
the first field will contain the transaction identification.
The
keyword for this field is provided to obtain the correlation betw68n the
TIO! definition and the macro instruction, but would not appear in the
free-format input from the terminal.
When providing free-format keyword-oriented input capabilities to
terminal users, the application programmer, working with system
programmers, must define a field-name start character and a fieldseparator character for the system before initialization.
~ee the
CICS/VS System Proqrammer1s Reference Manual for details.)
Chapter 6.3.
CICS/VS Built-in Functions (DFHBIF Macro)
473
TYPE=INFORMAT
The format of the DFHBIF macro instruction that specifies formatting of
terminal input is as follows:
I
I
DFHBIFI
I
I
I
I
I
TYPE=INFORMAT
,FIELDS=(symbolic address [,symbolic address, ••• ])
[,NAMES={symbolic addressIYES}]
[,LENGTH={symoolic addresslnumeric value}]
[,ERROR=symbolic address]
Data entered as free-format input (keyword-oriented or positional) is
read into a TIOA in the same manner as other data entered from a
terminal.
CICS/VS places the address of the TIO! into TCTTEDA (as it
must be for a formatting operation). To provide for the formatting of
this free-format input, a DFHBIF TYPE=INFORMAT instruction should be
issued immediately following the terminal control (DFHTC) macro
instruction that causes data to be moved into the TIOA to make sure that
the address of the TIOA containing data to be formatted is in TCTTEDA.
This built-in function reformats data from the input TIOA into a
CICS/VS-acguired TIOA. Data is moved from the input TIOA into locations
in the output TIOA named in the FIELDS operand. The length of the data
moved is the difference between displacements of the field being
processed and the next field named in the FIELDS operand. All data is
treated as alphameric, is left justified in each output field, and is
padded on the right with blanks, or is truncated, as necessary.
If, however, the form of input is positional and an input data item
is longer than the internal field defined for it, the data item is not
truncated unless it is for the last field.
Instead, a response code of
4 is set, as described below, and the data is treated as fixed-format
input.
(The reason for this treatment is that mixed formats are
allowed, so it is impossible for the built-in functions program to
distinguish between an intentional fixed-format input for more than one
field and a positional input of excessive length for a single field.)
The input TIOA supplied by the user is released by the built-in
function program (DFHBFP). The address of the fixed-format TIOA is
returned in TCTTEDA to the application program. The application
program~er sho~d establish addressability to this TIOA immediately,
just as for any TIOA used in the program.
(See the instructions for
copying symbolic storage definitions in Part 2.)
If the DFHBIF TYPE=INFORMAT macro instruction is issued immediately
following the read instruction, the address of the TIOA containing the
data to be formatted will be stored in TCTTEDA. If any intervening
macro instructions are issued, the application programmer is responsible
for saving and restoring the contents of TCTTEDA. For COBOL, TIOABAR
must be loaded before a DFHBIP because the expansion will contain "CALL
DFHCBLI USING fields."
414
CICS/VS APRM(ML)
The address of the fixed-format TIOA containing the reformatted data is
availanle in TCTTEDA. This address must be loaded into TIOABAR, the
base register for the area.
Certain error conditions may be detected during execution of the
DFHBIP TYPE=INFORMAT macro instruction. In such cases, an error
indication (response code) is return8d to the application program in
TCAINRC, a one-byte field. The error conditions that may occur and the
response code for each are shown in Figure 6.3-5. For error conditions
other than XIF41, no reformatted data is returned; that is, TCTTEDA does
not contain the address of a fix~d-format TIOA containing the
reformatted data.
r--------------'-------------------------- ,
Response Code in TCAINRC
1-------------------------------,Assembler, COBOL
PL/I
Condition
No Error
, X·OO·
I
The input data does not contain
,X'20'
field-name start or field-separator' ,
characters.
(Such data may not be
,
erroneous, if deliberately entered
,
in this manner.)
,
I
The input data contains two field- , XIF1'
name start characters with no fieldseparator character between them.
LOW-VALUES
(TCAINNOE)
11-0-1-8-9
(TCAINALS)
The input data contains an invalid
name.
X'F2 1
'2 I
(TCAINER2)
12'
A field name is specified in the
input data, but no DFHBIF TYPE=
DEFLDNM macro instruction is
contained in the ~pplication
program.
X'F3 1
13'
(TCAINER3 )
'3 I
The length of an input data field
exceeds defined internal field size.
X'F4 1
141
(TCAINER4)
The subparameters of the FIELDs
operand are not specified in
order of ascending displacem~nt
within the TIOA.
X'F5'
'51
(TCAINERS)
I
1•
(TCA INER 1 )
00000000
00100000
• 1'
• 4'
15'
Note:
The names enclosed in parentheses in the COBOL column indicate
the condition names generated by CICS/VS. These names may be
used in testing for the conditions in a COBOL program.
Figure 6.3-5.
Input Formatting Response Codas
Note: Application programmers and terminal operators should be aware
that if fixed-format input is provided to an application program
designed to accept free-format input, field overrun (X'F41) errors are
apt to occur.
Chapter 6.3.
CICS/VS Built-in Functions (DFHBIF Macro)
475
Assume the TIOA definition and the first DFHBIF TYPE=DEFLDNM macro
instruction above. Further assume that the period has been ~stablished
as the field-name start character and the egual sign and the slash as
field-separator characters.
The free-format positional input
INQR/HUGHES/JOHN/Q/096556 EOB
can be processed by issuing the following macro instruction:
DFHBIF TYPE=INFORMAT,
FIELDS=(TIOAIN,TIOALN,TIOAFN,TIOAMI,TIOAID)
*
The free-format keyword input
INQR.FN=JOHN.MI=Q.ID=096556.LN=HUGHES EOB
can be processed by issuing the following macro instruction:
DFHBIF TYPE=INFORMAT,
FIELDS=(TIOAIN,TIOALN,TIOAFN,TIOAMI,TIOAID) ,
NllMES=DEFI
*
*
A mixture of free-format positional and keyword input can be handled
by this latter form of DFHBIF TYPE=INFORMAT macro instruction.
For
example,
INQR.LN=HUGHES//Q/096556 EOB
will be handled correctly.
476
CICS/VS APRM (ML)
Weighted Retrieval Built-in Functions
The weighted retrieval built-in function allows the application
programmer to search a group of records in a VSAM key sequenced data
set, selecting only those records that satisfy or are closest to the
selection criteria provided.
In general, a series of DFHBIF macro instructions is involved.
1.
A DFHBIF TYPE=WTRETST macro instruction indicates the start of a
weighted retrieval operation.
2.
One or more DFHBIF TYPE=WTRTPARM macro instructions provide the
specifications to be used by CICS/VS in the weighted retrieval
process.
3.
One or more DFHBIF TYPE=WTRETGET macro instructions retrieve one or
mor9 selected records.
4.
A DFHBIF TYPE=WTRETREL macro instruction releases the VSAM work
area (VSWA) and other main storage used for the weighted retrieval
process.
5.
A DFHBIF TYPE=WTRETCHK macro instruction performs a check on the
success of a phase of the weighted retrieval process.
Each of these macro instructions is discussed more fully below.
Each record with a specified partial key (beginning with the first
one, or with the one having a specified relative number) is examined to
see whether entries in certain other fields of the record match the
values specified for those fields as selection criteria. Matching may
be on exact comparison or within a given range.
Differentiating among individuals is one example of an area in which
weighted retrieval processing is advantageous. In federal and state
governments, the banking industry, and many other application areas
dealing with large populations, name alone does not provide unique
identification. A number of people may have the same name, so
additional identifying characteristics are required. Such attributes as
sex, race, birth date, address, relatives, and employment tend to permit
unique identification. A basic example showing weighted retrieval on
the basis of last name, fir.st initial, and mother's maiden name is given
later in this chapter.
Each comparison performed during weighted retrieval causes a match
value to be added to a current total counter maintained automatically by
CICS/VS. If the comparison yields a match, the match value is also
added to a weighted counter. If the compared fields do not match, the
no-match value is subtracted from the weighted counter.
Fields in the
search criteria or in a record being examined that contain a predefined
null character may be ignored (not included in the search) if desired.
When all fields to be considered in the selection process have been
examined, a weighted qualification percentage (WQP) is calculated for
the record.
If this percentage is within the limits of acceptability
established in the application program, the percentage and complete key
of the record are saved in a key-save storage block.
After all records with the specified partial key have been examined,
the saved keys are sorted into descending percentage-value order. Under
normal processing, the records whose keys have been saved are retrieved
one at a time and made available to the application program in order of
decreasing acceptability.
A further judgment as to acceptability or
Chapter 6.3.
CICSjVS Built-in Functions (DFHBIF Macro)
477
verification of identifiers is then made by the application program,
which may involve the terminal operator in the final selection.
If the number of saved keys exceeds a maximum established in the
application program (say, n), all keys having a weighted qualification
percentage (WQP) equal to or lower than that of the "n+1"th key are
dropped. If this dropping causes less than the application programspecified maximum number of keys to be saved but some keys are saved (as
in Figure 6.3-6), no indication is given to the application program.
However, if all percentages are the same so that all keys are dropped
thereby, control is passed to an overflow routine (if one is specified
in the application program). If the amount of storage reguired for
saved keys exceeds the amount of storage available for keys, an overflow
also occurs, and the application program is notified.
An alternative,
lower maximum can he established by the application program.
The
maximum number of records that can be retrieved is restricted by the
maximum size of a key-save block (64K). This maximum is calculated as
storage size divided by saved key length plus one.
N
[N+1
o
20
10
WOP of these records is
less than that
of N+1
WOP of these records
(including N) is equal
to that of N+ 1
wOP of these records is
greater than that
of N+1
30
40
50
\~----~V~------------------~/\~---
70
60
VKeys dropped
Keys of records made
available to application
program
v
80
90
/
~
Keys of
records evaluated
by Weighted Retrieval
Figure 6.3-6.
Selection of Records by Weighted Retrieval
1.
Because of the potential effect of weighted retrieval operations on
system performance, this function should not be used
indiscriminately. The amount of file accessing and the use of main
storage should be taken into account.
2.
The computations applied by CICS/VS in weighted retrieval
processing can be expressed as follows:
478
CICS/VS APRM(aL)
Let
a.
MV
NMV
match value
= no-match value
The weighted counter (WC), which holds the sum of all match
values that had a match minus the sum of all no-match values
that had no match:
WC = (MV
b.
+
••• + MV )
-
(NMV
+ NMV
+
•••
+ NMV
The sum of all match values specified in WTRTPARM macro
instructions for the weighted retrieval operation; the
pot&ntial count (Pq:
PC
c.
+ MV
= MV
+ MV
+ ••• MV
The sum of all match values generated by the record comparisons
(excludes those comparisons bypassed because the null character
is pres8nt); the current total counter (eTC):
CTC = MV
+ MV
+ •••
+ MV
n$k
d.
The weighted potential
e.
The weighted qualification percentage (WQP):
WQP
(riP):
WC
WP
An overall effect of this method of computation is to provide a
minimum weighting penalty for records having absent fields but yet
prevent them from being chosen in preference to records that have all
identifiers present.
INITIATE WEIGHTED RETRIEVAL
(TYPE=WTRETST)
The format of the DFHBIF macro instruction to indicate the start of a
weighted retrieval operation is as follows:
Chapter 6.3.
CICS/VS Built-in Functions (DFHBIF Macro)
479
r
r---------------------------------------
r-
I
DFHBIFI TYPE=WTRETST
I [,DATASET=symbolic name]
[,RDIDADR=symholic address]
[ , INPUTNO= {symbolic address I numeric value I YES} ]
[,INPUTST={symholic addresslnumeric valueIYES}]
[ , INPUTPC= ([ suboperand 1 ][ , suboperand2]) ]
[,NRECDS={symbolic addresslnumeric valueIYES}]
[ ,NORESP=symbolic address]
(,DSIDER=symbolic address]
[,NOTOPEN=symbolic address]
(,NOTFND=symbolic address]
(,INVREQ=symbolic address]
(,IOERROR=symbolic address]
[,OFLOW=symbolic address]
[,ILLOGIC=symbolic address]
Returned Values
The address of a VSAM work ar8a (VSWA) to be used by weighted retrieval
throughout this series of weighted retr5_eval operations is returned in
TCAWRAA, a four-byte field. Since any CICS/VS macro instruction issued
within the application program may cause the contents of TCAWRAA to be
changed, the application programmer should save this address. It must
be restored in TCAWRAA prior to any subsequent DFHBIF macro instruction
included in this series of weighted retrieval operations. A response
code indicating how CICS/VS has responded to this request is returned in
TCAWTRC, a one-byte field (see "Test Response to a Request for Weighted
Retrieval," later in this chapter.)
ESTABLISH SELECTION CRITERIA
(TYPE=WTRTPAR~)
The format of the DFHBIF macro instruction to pass selection criteria to
CICS/VS is as follovs:
DFHBIF
TYPE=WTRTPARfi
[ , FIELD 1 = «( sy mbolic address][, numeric value][ ,char]) ]
[ , FIELD2= «( symbolic address1][ ,symbolic address2]) )
[,NULL={symbolic addresslcharacter valueIYES}]
[,MATCH={symbolic addresslnumeric value}]
(,NO~ATCH={symbolic addresslnumeric value}]
[,RANGE={suboperand1,suboperand2(,suboperand3]) ]
One of these macro instructions must be coded for each field that is
to be examined during the selection process. ~atch and no-match values
are established separately for each field. Then, during weighted
retrieval processing, the applicable match and no-match values for
examined fields of a record are used to determine a weighted
qualification percentage for the record.
480
CICS/VS APRM(ML)
RETRIEVE SELECTED RECORDS (TYPE=WTRETGET)
The format of the DPHBIP macro instruction to retrieve a record that has
been saved by the weighted retrieval built-in function is as follows:
r------r-------r-------------------------------------I
DFHBIFI
I
I
I
I
I
I
I
I
I
TYPE=WTRETGET
[,NORESP=symbolic address] .
[,ENDPILE=symDolic address]
[,NOTOPEN=symbolic address]
[,NOTPND=symbolic address]
[,INVREQ=symbolic address]
[,IOERROR=symbolic address]
[,OPLOW=symbolic address]
[,ILLOGIC=symbolic address]
I
This macro specifies that next record saved by weighted retrieval (as
ordered according to decreasing weighted qualification percentage) is to
be retrieved.
Before this macro instruction is executad, TCAWRAA must contain the
address of the VSAM work area (VSWA) used in this series of weighted
retrieval operations.
Returned Values
A record saved as the result of weighted retrieval is returned to the
application program. The address of this record is contained in VSWAREA
within the VSWA provided by the WTRETST macro instruction.
The length
of the record is returned in VSWALEN.
In addition, the contents of several halfword fields are significant.
TCAWGH1 contains the highest percentage of acceptability for this
weighted retrieval operation, TCAWGH2 contains the lowest percentage of
acceptability for this weighted retrieval operation, TCAWGH3 contains
the percentage of acceptability of this record, and TCAWGH4 contains the
number of records left to be presented to the user.
After the first
DFHBIP TYPE=WTRETGET macro instruction, TCAWGHS contains a count of any
records dropped to remain within the maximum specified in the NRECDS
operand of the WTRETST macro instruction. On succeeding WTRETGETs,
TCAWGH5 contains zero. The full key of the returned record is returned
at the location specified in the RDIDADR operand of the DPHBIP
TYPE=WTRETST macro instruction initiating this weighted retrieval
operation.
TCABFTR, a one-byte field, contains the response code that describes
the CICS/VS response to this DPRBIF TYPE=WTRETGET macro instruction.
This response code can be interrogated as described under "Test Response
to a Request for Weighted Retrieval," later in this chapter.
Chapter 6.3.
CICS/VS Built-in Functions
(DPRBIP Macro)
481
RELEASE WEIGHTED RETRIEVAL STORAGE AREAS
(TYPE=WTRETREL)
The format of the DFBBIF macro instruction to specify that the VSWA
established when the DFHBIF TYPE=WTRETST macro instruction is issued and
the main storage used for saving the records is released is as follows:
r------~------~---------------------------------------------------------,
I
I
I
I
I
IL
I
DFHBIFI TYPE=WTRETREL
I [,NORESP=symbolic address]
I [,INVREQ=symbolic address)
I [,ILLOGIC=symno1ic address]
IL________________________________________________________
L-
~
TEST RESPONSE TO A REQUEST FOR WEIGHTED RETRIEVAL
(TYPE=WTRETCHK)
The general format of the DFHBIF TYPE=WTRETCHK macro instruction is as
follows:
r------~------·r---------------------------------------------------------~
DPHBIF
TYPE=WTRETCHK
[,NORESP=symbo1ic address]
[,DSIDER=symbo1ic address]
[,NOTOPEN=symbo1ic address]
[,NOTFND=symbolic address]
[,INVREQ=symbo1ic address]
[,ENDFILE=symbolic address]
[,IOERROR=symbolic address]
[,OFLOW=symbolic address]
[,ILLOGIC=symbolic address]
WEIGHTED RETRIEVAL RESPONSE CODES
The response codes and the conditions to which they correspond are
identified in the right-hand columns of Figure 6.3-7. DFHBIF macro
instructions for which the conditions are applicable are shown at the
left.
If checking for a response to a weighted retrieval macro instruction
is not provided, and if the exception condition corresponding to that
response occurs, program flow proceeds to the instruction following the
weighted retrieval macro instruction in the application program.
482
CICS/VS APRM(ML)
-,
I
Condition
NORESP
(Normal response)
RE:sponse Codes in TCAWTRC
I
I
IAssemblerl COBOL
x·oo·
LOW-VALUES
PL/I
I
I
000000001
I
I
.
DSIDER
(Data set identifica tion error)
X'Cl'
, A'
)
NOTOP EN
(Data set not
open)
X'C2'
'B'
'B'
NOTPND
(Record not found)
X'CS'
, H'
D
ENOFILE
(End of file)
X'C4'
'0'
'D'
INVREQl
(Invalid request)
X'C3'
'C •
IOERROR
(Input/Output
error)
X'CS'
, E'
OPLOW2
(Overflow)
X'C6'
ILJ.. OGIC3
(VSAM error)
X'C7'
\~
:\
I
I
I
il •
{: ;
• G'
Notes:
T:It
the data set is not a VSAM file, the field TCAWRAA i:; set to
zero. CICS/VS file control handles other errors of thi; type,
in vh ich case, rCAW RAA contains the address of the PCT~n try
for the data set.
2. Por WTRETST, this response indicates that the system-d2tined
maximum storage GETMAIN (64K) is insufficient to hold all
retrieved record keys and these records have the same percentage
of acceptability. In this case, the terminal operator must
specify a relative record number (the relative position of the
first record to be retrieved among the retrieval records) and a
number of records (NRECDS) to be presented.
Por WTRETGET, this
response means that no records were returned because all had
identical percentages of match and not all could be returned
because of the limit specified in NRECOS.
3. This response indicates that a VSAM error that does not fall into
one of the above categories has occurred. The VSWA contains the
VSAM request parameter list that contains the VSAM logical error.
error.
Pigure 6.3-7.
Weighted Retrieval Response Codes
Chapter 6.3.
CICS/VS Built-in Punctions (DPHBIP Macro)
4S3
Example
Assume that, for purposes of state welfare applications, a VSAM file
labeled SRCHFILE is maintained on magnetic disk. SRCRRECD is an area of
storage that holds individual records retrieved from the file. The file
is to be searched to retrieve up to 100 records that satisfy (or come
closest to satisfying) the criteria:
last name = SMITH, first initial =
J, and mother's name = MARY.
LNAME
FINIT
MOM
COpy
DFHTCADS
DS
CL18
DS
CLl
DS
CL7
DFHBFTCA OPTION=WTRET
SRCHRECD DSECT
USING
LAST
DS
FIRST
DS
MOTHER DS
*,RCDBASE
CL18
CLl
CL7
DFHBIF TYPE=WTRETST,
DATASET=SRCRFILE,
RDIDADR=KEYFLD,
INPUTNO=lOO,
INPOTST=10,
INPUTPC=(10O,80),
NRECDS=50,
NORESP=STARTOK
*
*
*
*
*
*
*
(error processing)
STARTOK DS
OR
L
VSWABAR,TCAWRAA
DFHBIF TYPE=WTRTPARM,
FIELD1=(LNAME,18,C) ,
FisLD2=(SRCHRECD,LAST),
MATCH=50
DFHBIF TYPE=WTRTPARM,
FIELD1=(FINIT,1,C) ,
FIELD2=(SRCHRECD,FIRST) ,
MATCH=30
DFHBIF TYPE=WTRTPARM,
FIELD1=(MOM,7,C) ,
FIELD2=(SRCHRECD,MOTHER),
MATCH=20
WRGET
DS
OH
ST
VSWABAR,TCAWRAA
DFHBIF TYPE=WTRETGET,
NORESP=GETOK,
ENDFILE=ENDPROC
~rror
GETOK
DS
L
484
processing)
OH
RCDBASE,VSWAREA
CICS/VS APRM(ML)
GET ADDRESSABILITY TO RECORD
*
*
*
*
**
*
*
*
*
*
·
(on first WTRETGET, check to see whether too many
records have been skipped, enough records returned,
acceptable range of ~ returned, and the like)
(process retrieved record)
B
WRGET
ENDPROC DS
OH
ST
VSWABAR,TCAWRAA
DFHBIF TYPE=WRETREL
Chapter 6.3.
CICS/VS Built-in Functions (DFHBIF Macro)
485
Operands of DFHBIF Macro
ALPHA=symbolic address
is the address to which control is to be passed if the field
consists entirely of alphabetic characters (A through Z) and/or
blanks.
ARG=symbolic address
is the symbolic address of the field that contains the search
argument; if omitted, the address is assumed to be in TCATSA1,
a fullword field.
ATABLE=
is a description of the table to be searched (the argument
table).
symbolic addressl
is the address of the first entry in the argument table; if
omitted, the address is assumed to be in TCATSA2, a
fullword field.
symbolic address2 or YES
is the address of the field in the first entry of the
argument table to be compared with the search argument. If
YES is specified, the field address is assumed to be in
TCATSA4, a fullword field. If this operand entry is
omitted, symbolic address2 is assumed to be the same as
symbolic addressl.
If specified, the address represented
by symoolic address2 must be equal to or greater than the
address represented by symbolic addressl. If it is not,
bit 4 of TCATSRC is set on and no search is made.
numeric value1
is the length of each entry in the argument table
(including any other fields in the entry or slack bytes
required for boundary alignment). A value in the range
from 1 through 32767 may be specified.
If this operand
entry is omitted, the length is assumed to be in TCATSH2, a
halfword field.
numeric value2 or YES
is the length of the field in the argument table to be
compared with the search argument. If YES is specified,
the length is assumed to be in TCATSAF, a one-byte field.
If this operand entry is omitted, numeric value2 is assumed
to be the same as numeric value1. If specified, the value
must be between 1 and 255 inclusive. If numeric valuel is
not within this range, numeric value2 must be specified.
numeric value3
is the maximum number of entries to be s.earched.
A value
in the range from 1 through 32767 may be specified. If
this operand entry is omitted, the numeric value is assumed
to be in TCATSH1, a halfword field.
If one or more of these operand entries are omitted, but other
operand entries follow, the comma that ordinarily follows an
omitted entry must be included in the operand.
486
CICS/VS APRM(ML)
BIT=
specifies the bit pattern (mask) to be applied to the specified
byte.
symbolic address
is the address of a byte that contains the bit pattern.
value
is a single EBCDIC character enclosed in single quotation
marks.
If this operand is omitted, the bit pattern is assumed to be in
TCABITV, a one-byte field.
BITOFF=symbolic address
is the symbolic address to which control is transferred if-•
For BITSETON,
BI~SBTOFF,
or BITFLIP:
All bits in the specified byte are off after the operation
is completed
•
For BITEST:
All bits that are on in the bit pattern are off in the
field that is tested
BITON=symbolic address
is the symbolic address to which control is transferred if-•
For BITSBTON, BITSBTOFF, or BITFLIP:
All bits in the specified byte are on after the operation
is completed
•
For BITEST:
All bits that are on in the bit pattern are on in the field
that is tested
DATASET=symbolic name
is the one- to eight-character identification of the VSAM data
set from which the retrieval is to be made; if omitted, the
data set identifier is assumed to be in TCAWTDI, an eight-byte
field.
DSIDER=symbolic address
spec~fies the entry label of the user-written routine to which
control is to be passed if the data set specified by the
DATASET operand cannot be located. DSIDER signifies "data set
identifica~ion error".
ENDFILE=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an end-of-file condition is
detected.
Chapter 6.3.
CICS/VS Built-in Functions (DFHBIF Macro)
481
ERROR=symbolic address
is the address to which control is to be passed if
occurs. This branch is taken, for example, if the
specified for the function field to be examined is
the address specified for the first function table
an error
address
lower than
entry.
FIELD=symbolic address
is the symbolic address of the byte or field to be processed;
if omitted, the address is as'sumed to be in the fullword field
TCANAME (for TYPE=PHONETIC) , TCACKFD (for TYPE=FVERIFY), TCAFLD
~or TYPE=DEEDIT), or TCABITF (for TYPE=BITSETON).
FIELDS=(symbolic address[,symbolic address, ••• ])
are the labels of fields defined within the internal fixedformat TIDA to which the input data is to be transferred. The
fields must be named in order of increasing displacement from
the start of the TIOA, and there must be a one-to-one
correspondence between the field names in this macro
instruction and the fields in the TIOA. The length of each
field is determined by calculations based on the location
represented by the symbolic address of the following field.
Each field should be at least one byte in length. For
positional input, each field for which data may be entered
~hat is, each position in the receiving area of storage) must
be defined.
FIELD1=
specifies the characteristics of the search field to be
compared against a corresponding field in records of the data .
set on which the weighted retrieval function is to operate.
symbolic address
is the symbolic address of the field. If omitted, the
address of the field is assumed to be in TCAWPA1, a fourbyte field.
numeric value
is the length of the field in bytes and may range from 1 to
32161. If omitted, the length of the field is assumed to
be in TCAWPH1, a halfword field.
char
is one character indicating the format of the data in the
field as follows:
C
Z
P
H
F
EBCDIC characters
Zoned decimal numbers
Packed decimal numbers
Halfword binary ~
Fullword binary
If this parameter is omitted, the character is assumed to
be in TCAWPB1, a one-byte field.
If one of these operand entries is omitted but succeeding
operand entries follow, the comma that otherwise follows the
entry must be included in the operand.
488
CICS/VS APRM (ML)
1. The application programmer must ensure that the integrity
of PIELD1 is not destroyed prior to the first DFHBIP
TYPE=WTRETGET macro instruction. These values are used by
the built-in functions program (DPHBPP) at that time. In
particular, it is not advisable to utilize an area within a
TIDA for this value.
2. The largest decimal number that can be contained in a zoned
decimal (Z) or packed decimal (P) field cannot exceed 16
digits, including the sign.
PIELD2=
specifies the location of the data in the field of each record
of the data set involved in the comparison with the search data
in PIELD1.
symbolic addressl
is the symbolic address (label) of the first byte of the
storage area that will contain the record to be examined.
If omitted, the address of the main storage area is assumed
to be in TCAWPA3, a four-byte field.
symbolic address2
is the symbolic address (label) of the field within the
storage area identified by symbolic address1 to be used in
the weighted retrieval comparison. If omitted, the address
of the field is assumed to be in TCAWPA4, a four-byte
field.
If the first operand entry is omitted but the second is
specified, the comma that otherwise follows the first entry
must be included in the operand.
PTABLE=
is a description of the table from which ~ value is to be
retrieved (the function table).
If no function value is to be
retrieved (for example, if only the index of a matching
argument table entry is needed), this operand can be omitted.
If this operand is specified, but some entries are omitted, the
values of the corresponding entrias in the ATABLE operand are
assumed to apply.
If a complex table (where each table entry contains both an
argument and a function value) is being searched, the argument
table and function table, as defined for this macro
instruction, are actually within the same table in storage.
Alternatively, two separate tables, one containing search
fields and one containing function values, may be used.
symbolic addressl or YES
is the address of the first function table entry. If YES
is specified, the address is assumed to be in TCATSA3, a
fullword field.
symbolic address2 or YES
is the address of the function field within the first
function table entry. If YES is specified, the address is
assumed to be in TCATSA5, a fullword field. This address
must be equal to or greater than symbolic addressl.
If it
is not, bit 5 of TCATSRPC is set on and no search is made.
Chapter 6.3.
CICSjVS Built-in Punctions (DPHBIF Macro)
489
valuel or YRS
is the length of each entry in the function table
(including any other fields in the entry or slack bytes
required for boundary alignment). A value in the range
from 1 through 32767 may be specified. If YES is
specified, the value is assumed to be in TCATSH3, a
halfword field.
numer~c
numeric value2 or YES
is the length of the field to be retrieved from the
function table. If YES is specified, the length is assumed
to be in TCATSFF, a one-byte field. The length must be
between 1 and 255 inclusive. If this operand is omitted,
the default is the corresponding entry in the ATABLE, or
its default if the corresponding entry is not specified in
the ATABLE. The default for this operand is not numeric
valuel above.
ILLOGIC=symbolic address
specifies the entry label of the user-written routine to
which control is to be passed if a VSAM error that does not
fall within one of the other CICS/VS response categories
occurs.
INDEX=symbolic address
specifies the address of a halfword field in which an index
value relative to one, identifying the matching argument-table
entry, is to be returned to the application program. In
addition, the index value is placed in TCATSH4, a halfword
field, whether or not the INDEX operand is specified. Both
fields contain zero if no matching entry is found.
INPUTNO=
specifies the maximum number of records that can be examined.
A value from 1 to 32767 may be specified.
symbolic address
is the address of a halfword field that contains the
maximum number of records that can be examined.
numeric value
is a decimal numeral indicating the maximum number of
records that can be examined.
YES
indicates that the maximum num,ber of records to be examined
has been placed in TCAWTH1, a halfword field.
If this operand is omitted, a default value of 512 is placed in
TCAWTH1.
INPUTPC=
specifies the percentages to be used by the weighted retrieval
built-in function to determine the limits of acceptability.
suboperandl
specifies the maximum percentage, a value from 0 to 100;
this value can be indicated by the symbolic address of a
halfword field containing the maximum value, a decimal
numeral, or YES, which indicates that the value has been
placed .in TCAWTH3. If omitted, the maximum percentage is
assumed to be 100.
490
CICS/VS APRM(ML)
suboperand2
specifies the m~n~mum percentage, a value from 0 to 100;
this value can be indicated by the symbolic address of a
halfuord field containing the minimum value, a decimal
numeral, or YES, which indicates that the value has been
placed in TCAWTH4. If omitted, the minimum percentage is
assumed to be o.
If the first suboperand is omitted, but the second is
specified, the comma that otheru ise follo\l s the first
suboperand must be included. If only one suboperand is given,
it is assumed to be the first suboperand (the maximum
percentage, 100).
INPUTST=
indicates the number of records with the specified partial key
to be skipped before examination of records begins.
The
maximum value that can be specified is 32767.
symbolic address
is the address of a halfword field that contains the
relative numDer of the record that is to be examined first.
numeric value
is a decimal numeral indicating the relative number of the
record that is to be examined first.
YES
indicates that the relative number of the desired record
has been placed in TCAUTH2, a halfuord field.
If this operand is omitted, a default value of 0 is placed in
TCAWTH2. The weighted retrieval begins \lith the first record
having the specified partial key.
INVREQ=symbolic address
specifies the entry label of the user-\lrit ten routine to uhich
control is to be passed if an invalid type of request is
received.
IOERROR=symbolic address
specifies the entry label of the user-urit ten routine to uhich
control is to be passed if an input/output error occurs.
LABEL=symbolic address
is the label to be assigned to the list of keywords. This
label must be unique \lithin the application program and may be
from one to eight characters in length.
LENGTH=
specifies the length of the field to be processed or the size
of the TIOA to be acquired.
symbolic address
is the address of a halfword field that contains the length
val ue •
Chapter 6.3.
CICSjVS Built-in Functions (DFHBIF Hacro)
491
numer1c value
is the length, in bytes, of the field to be processed, or
the area to be acquired for the TIOA. .
The maximum length of a field is 32767 bytes. The length of
the TIOA must be suffici6nt to accomodate all fields specified
in the FIELDS operand.
If this operand is omitted, the length is assumed to be in the
halfword field TCACKLN «for TYPE=FVERIFY), TCAFLN (for
TYPE=DEEDIT), or in TCAINH1 (for TYPE=INFORMAT).
MATCH=
specifies a value to be added to the current total counter if
the comparison is performed and to the weighted counter if the
compared fields are equal. The value may range from -32768
through +32767.
symbolic address
is the symbolic address of a halfword field containing the
value.
numeric value
is a decimal numeral in the range stated above.
If this parameter is omitted, the value is assumed to be in
TCAWPH2.
Note: All match and no-match values specified for a weighted
retrieval operation must have like signs.
NAMES=
indicates that field names may be present as keywords in the
input data stream.
symbolic address
is the LABEL parameter specified in a DFHBIF TYPE=DEFLDNM
macro instruction in which the keywords that may be
specified are defined.
YES
indicates that the label specified in the DFHBIF
TIPE=DEFLDNM macro instruction defining the field names is
in TCAINA2, a fullword field.
••• ])
is a list of the Keywords that may be entered by the
terminal user to indicate which fields are to receive input
data. Each keyword may be from one to four characters in
length. Any combination of alphabetic, numeric, and/or
special characters may be specified. The keywords must be
specified in the order in which the corresponding fields
that will hold the data are defined in the fixed-format
TIOA.
~eyword[,keyword,
NOMATCH=
specifies a value to be used during weighted retrieval, or the
address to which control is to be passed if matching is
unsuccessful.
492
CICS/VS
APRM(M~
symbolic address
is the symbolic address of a halfuord field containing the
value to be subtracted from the ueighted counter if the
compared fields are not equal, or it is the address to
which control is to be passed if no table entry matching
the search argument is found.
numeric value
is a decimal numeral in the range -32768 through +32767.
If this parameter is omitted, the value is assumed to be in
TCAWPH3.
Note: All match and no-match values specified for a weighted
retrieval operation must have like signs.
If this operand is specified, the SUBST operand cannot be
specified.
NORESP=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if no error occurs. NORESP signifies
"normal response".
NOTFND=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an attempt at weighted retrieval is
unsuccessful. NOTFND signifies "record not found".
NOTOPEN-symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if the requested data set is not open.
NRECDS=
indicates the maximum number of records to be made available to
the application program. A value from 1 to 32761 can be
specified.
symbolic address
is the address of a halfuord field that contains the
maximum number of records.
numeric value
is a decimal numeral indicating the maximum number of
records.
YES
indicates that the maximum number has been placed in
TCAWGCNT, a halfword field.
If this operand is omitted, a default value of 200 is assumed.
NULL=
specifies a one-byte "null character" which, if present in
either FIELD1 or FIELD2, indicates that no comparison is to be
performed.
symbolic address
is the symbolic address of a one-byte field containing the
null character.
Chapter 6.3.
CICSjVS Built-in Functions (DFHBIF Macro)
493
character value
is a single EBCDIC character within single quotation marks.
YES
indicates that the null character has been placed in
TCAWPNL, a one-byte field.
The null character cannot be a binary zero (that is, XIOOI);
such a specification is ignored.
NUMERIC=symbolic address
is the address to which control is to be passed if the field
consists entirely of EBCDIC numbers (X'FO' through XIF9') with
an optional trailing minus sign or 'CRI.
OFLOW=symbolic address
specifies the entry label of the user-written routine to which
control is to be passed if an overflow condition occurs.
ORDER=
describes the sequence used in ordering the entries of the
argument table and is optional if RANGE is not specified. The
sequence must be EBCDIC; packed, fullword and halfword binary,
and floating-point tables cannot oe searched.
When this
parameter is specified, a quick binary search is used (rather
than a sequential search).
ASCENDING
indicates that table entries are organized in ascending
order according to the entries in the field to be compared
with the search argument.
DESCENDING
indicates that table entries are organized in descending
order according to the entries in the field to be compared
with the search argument.
In either case, the field
representations. If this
argument table is assumed
sequentially, starting at
values are interpreted as EBCDIC
operand is not specified, the
to be unordered and is searched
the last entry of the table.
PACKED=symbolic address
is the address to which control is to be passed if the field
consists entirely of packed decimal characters, that is, of
half-bytes with hexadecimal values in the range 0 through 9,
except for the rightmost half-byte, which must contain a
hexadecimal value in the range A through F.
RANGE=YES
is an optional operand indicating that, if no field compared
with the search argument is an exact match, an existing table
entry that would be adjacent to such an entry is to be taken as
the function value. When this operand is specified, ORDER must
be specified; otherwise, a sequential search of the table is
made, starting at the last entry.
RANGE=
indicates that the compared fields are to be considered equal
if FIELD2 falls vithin a given range of FIELD1.
494
CICS/VS APRM (ML)
suboperand1
specifies the type of range used in the comparison. This
entry can be a single character or YES, uhich indicates
that the single character specifying type has been placed
in TCAWPTR. The valid characters are as follows:
Character
~e
of Range
Percentage
units
Value
P
U
V
suboperand2
specifies the upper limit, exceeding the value in FIELD1,
which is to be considered a match. ~his entry can be a
positive numeric value up to 32767 or YES, which indicates
that the upper limit has been placed in TCAWPH4.
suboperand3
specifies the lower limit, below the value in FIELD1, which
is to be considered a match. This entry can be a positive
numeric value up to 32767 or YES, which indicates that the
lower limit has been placed in TCAWPH5.
If suboperand3 is omitted, suboperand2 is assumed to apply both
above and below the value in FIELD1. For example, if the value
in FIELD1 is 165 and RANGE=(U,5) is specified, then any value
from 160 through 170 is considered a match. If RANGE=(U,5,10)
is specified, then any value between 155 and 170 is considered
a match. If RANGE=(P,20) is specified, then any value between
132 and 198 {165*(1±20%)} is acceptable. If RANGE=(V,190,160),
then any value between 160 and 190 is acceptable. If the data
field contains EBCDIC characters (that is, C is specified in
the FIELD1 operand), the RANGE operand is ignored.
Notg: The upper bound and lower bound values are computed
using the following formulas (where K is the value of FIELD1):
1.
For P-type range, specified
UB
K
LB =
2.
K
*
(1 +
*
(1
x/l00)
UB
K
*
(1
+ x/l 00)
LB
K
*
(1
x/l00)
or
y/100)
For o-type range,
UB = K + x
specif~ed
or (P,x):
~,x,y)
(O,x ,y) or (U ,x) :
UB = K + x
or
LB = K
3.
y
LB
K- x
Por V-type range, specified (V,x,y):
UB
=
x
LB = Y
Chapter 6.3.
CICS/VS Built-in Functions (DFHBIF Macro)
495
RDIDADR=symbol1c address
is the symbolic address of the record identification field that
contains ~~e partial key of the record at which the data set is
to be positioned prior to the retrieval process~ if omitted,
the. address is assumed to be in TCAWTRI, a fullword field.
(The format of the record identification field for a VSAK data
set is described under "Record Identification Field" in'Chapter
3. 1 .)
SUBST=
specifies a value to be stored in TARGET if no entry matching
the search argument is found in the argument table.
symbolic address
is the address of a field that contains the value to be
stored.
'literal value'
is the value to be stored; single quotation marks must
enclose the value in this specification but are not stored
as part of the data.
If this operand is specified, the TARGET operand must be
specified, and the NOMATCH operand cannot be specified.
TARGET=symbolic address
is the symbolic address of the field in which the built-in
function value is to be returned to the application program.
The address of the function value is placed in TCATSAS, a
fullword field, regardless of whether TARGET is specified.
496
CICS/VS APRM(ML)
Part 7. Error Handling and Debugging
497
Chapter 7.1. Introduction to Error Handling and Debugging
A number of aids to testing, monitoring, and debugging are provided by
CICSjVS, as follows:
o
Sequential Terminal support - provides a method in which sequential
devices, such as a card reader or disk unit, can be made to
simulate the online interactive terminals or subsystems of a
CICS/VS netuork. This enables early testing to be carried out
without the need for remote terminals or subsystems in the network
to be active.
Sequential terminal support is described in Chapter
7.2.
o
Trace Management - provides a trace table containing entries that
reflect the execution of CICS/VS macro instructions by user-written
application programs and by CICS/VS management programs. The trace
table can be stored also in auxiliary storage on a sequential
device through the' CICSjVS Auxiliary Trace facili ty. The trace
table and the DFHTR macro instruction by \'lhich it is invoked are
described in Chapter 7.3.
o
Dump Management - provides a dump of main storage that can be
analysed to locate errors in application programs or in CICS/VS.
'Areas of main storage can De dumped onto a sequential data set,
either tape or disk, for subsequent offline formatting and printing
by a CICS/VS utility program. The types of dumps and the DFHDC
macro instruction that produces them are described in Chapt8r 7.4.
o
Journal Hanagement ~ provides a journal or log of the real-time
activity that occurs during the execution of the CICS/VS system.
This journal is stored in a sequential data set and the information
it contains is essential for the reconstruction of that real-time
activity. The contents of a journal, and the DFHJC macro
instruction used to control these contents, are described in
Chapter 7.5.
o
Recovery/Restart (Sync Point) Management - provides for the
emergency restart of CICS/VS after it has terminated abnormally and
also allows for erroneous operations to be backed out. The setting
up of the sync points and the DFHSP macro instruction used to do
this are described in Chapter 7.6.
Chapter 7.1.
Introduction to Error Handling and Debugging
499
Chapter 7.2. Sequential Terminal Support
Even at the simplest level of program testing, the implementer faces
problems.
It is not efficient to test a program from a terminal if all
test data must be keyed into the system from that terminal for each test
shot. The programmer cannot easily retain a backlog of proven test data
and quickly test programs through the key-driven terminal as changes are
made. There is also the risk that a fault developing in a test
procedure being used in an operational system could affect the whole
system.
CICS/VS allows the application programmer to begin testing programs
without the use of a telecommunication device. It is possible to
specify through the terminal control table that sequential devices be
used as terminals. These sequential devicss may be card readers, line
printers, disk units, or magnetic tape units.
In fact, a terminal
control table can include combinations of sequential devices such as:
card reader and line printer, one or more disk or tape data sets as
input, one or more disk or tape data sets as output.
A table that
contains references to these card-reader-in/line-printer-out (CRLP)
terminals can also include references to other terminals on the system.
The input data submitted from a sequential device must be prepared in
the form that it would come from a telecommunications device.
A one- to
four-character transaction identification only, or if data is included,
a one- to four-character transaction identification (followed by a
system-defined transaction code delimiter or a blank if lass than four)
must appear in the first one to four positions of the first input for a
transaction.
If a sequential device is being uSed as a terminal, an
end-of-data indicator, a 0-2-8 punched card code (XIEOI) or th~
equivalent as specified at system generation, must follow the input
message or the system-defined data termination character. The input is
processed sequentially and must be unblocked. The Sequential Access
Method (SAM) is used to read and write the necessary inputs and outputs.
The operating system utilities can be used to create the input data sets
and print the output data sets.
Using this approach, it is possiole to prepare a stream of
transaction test cases to do the basic testing of a program module.
As
testing progresses, the user can generate additional transaction streams
to validate the multiprogramming capabilities of his programs or to
allow transaction test cases to be run concurrently.
At some point in testing, it is necessary to use telecommunication
devices to ensure that the transaction formats are satisfactory, the
terminal operational approach is satisfactory, and the transactions can
be processed on the terminal. The terminal control table can be altered
to contain more and different devices as the testing requirements
change.
When the testing has proven that transactions can be processed
concurrently and the necessary data sets (actual or duplicate) for
online operation have been created, the user begins testing in a
controlled environment with the telecommunication uevices. In this
environment, the transaction test cases should represent all functions
of the eventual system, but on a smaller, measurable scale. For
example, a company whose information system will work with 15 district
offices may select one district office for the controlled test, during
which all transactions, data set activity, and output activity from the
system should be measured closely.
Chapter 7.2.
Sequential Terminal support
501
Requests for input or output from a sequential terminal are specified
in terminal control macro instructions (DFHTC), just as other requests
for input/output operations.
In response to a DFHTC TYPE=READ, where the terminal has been
described in the terminal control table as a CRLP, DISK, or TAPE
terminal, data is read from the input data set until any of the
following occurs:
•
An end-of-data indicator is detected in the input stream.
(The
indicator must be defined by the user at system generation time.)
•
sufficient input has been read to fill the input area associated
with the line used for transmission. If an end-of-data indicator
is not detected before the input area is filled, all further data
preceding an end-of-data indicator is bypassed and treated as a
system error, which is passed to the user-installation terminal
error program (DFHTEP).
o
End of file (EOF) is detected. The READ is considered complete.
Any subsequent READ is treated as a system error, which is passed
to the user-installation terminal error program (DFHTEP) with a
response code of 4.
Wnder CICS/DOS/VS, EOF applies to a card
reader only.)
In response to a DFHTC TYPE=WRITE from a CRLP terminal, multiple
lines are written in print format as follows:
o
If there is no new-line (XI 151) character within the number of
characters contained in one print line of the specified line size
~s found in TCTTELPL, a field in the TCTTE), the output is written
in fixed-length lines of the size specified.
o
If new-line characters are encountered, a new line is begun for
each. writing of output continues until the end of the terminal
input/output area (TIOA) is reached.
For additional information about the DFHTC macro instruction, see
Chapter 4.2.
502
CICS/VS APRM(ML)
Chapter 7.3. Trace Control (DFHTR Macro)
The CICS/VS trace facility is a debugging aid for application
programmers and IBM field engineers. It maintains in main storage a
trace table consisting of standard CICS/VS entries and entries defined
by the user. The table is filled in a wrap-around manner: when it is
full, subsequent entries begin to overwrite the entries at the beginning
of the table.
Tracing can be activated and deactivated by a DFHTR macro instruction
in an application program or by the master terminal transaction caST.
The macro instruction can also be used to specify the events to be
recorded in the table.
The trace entries can also be stored in auxiliary storage on a
sequential data set, as well as recorded in the trace table, by the
CICS/VS auxiliary trace facility, which is activated and deactivated
only by the the master terminal transaction CSKT. The auxiliary-trace
data set does not wrap around: all entries are preserved so that a
complete history is obtained. The CICSjVS trace utility program
(DFHTUP), the use of which is described in the ~ICS/V~_§yst~m
~£2grammer's Guides, can be used to print the contents of the auxiliarytrace data set or selected entries from it.
Standard entries can·be recorded in the trace table each time one of
the following macro instructions is issued by an application program or
by a CICSjVS management or service program.
(This list does not cover
all entries; refer to the CICS/VS Problem Determination Guide for
further details.)
•
DFHKC (Task Control)
•
DFHSC (storage Control)
o
DFHPC (Program Control)
•
DFHIC (Interval Control)
•
DFHDC (Dump Control)
o
DFHFC (File control)
•
DFHTD (Transient Data Control)
•
DFHTS (Temporary Storage Control)
•
DFHJC (Journal Control)
•
DFHBMS (Basic Mapping Support)
•
DFHBIF (Built-In Functions)
•
DFHTC (Terminal Control for VTAM-supported terminals only)
•
DFHSP (Sync Point Program)
•
DFHDI (Data Interchange Program)
•
CICS/VS-DL/I Interface (OS only)
Chapter 7.3.
Trace Control (DFHTR Macro)
503
In addition to these standard entries, other entries produced by the
terminal abnormal condition program can be recorded in the trace table.
These entries, termed field engineering (FE) entries, are normally
inhibited but can be activated by the DFHTR macro instruction.
A third class of entry, the user entry, can be defined by the
application programmer with the DFHTR macro instruction.
Trace control is branched to by the requesting program and executes
as a service routine under the TCA of the requesting program. Registers
are saved and restored. Return after the requested service has been
performed is to the next sequential instruction in the requesting
program.
Trace Table
The CICS/VS trace table consists of a trace header and a number of
fixed-length entries that can be used to trace the flow of transactions
through the system. Assuming that the trace program has been generated,
the trace table will be built during system initialization if the number
of entries specified in the TRP parameter of the DFHSIT system macro is
other than zero.
The trace table can be initially disabled by specifying OFF in the
TRP parameter. The master terminal can be used to turn trace or
auxiliary trace on or off during CICS/VS execution.
If a nonzero number
of entries in the trace table is specified, the address of the trace
header is placed at CSATRTBA.
The address of the trace table header is held in field CSATRTBA
(contents of R13 plus X'11C').
Each entry in the trace table is 16 bytes in length and aligned on a
double-doubleword boundary. The table is used in a wraparound manner so
that when the last entry is used, the next entry is placed at the
neginning of the table. The first three words of the trace table
contain "HEADER AT" and the fourth word contains the address of the
trace header. The trace header format is:
lrlte§.
0-3
4-7
8-11
12-15
.£Ql!ten.i§
Address of the last-used entry
Address of the beg inning of the table
Address of the end of the table
Reserved
The format of an entry in the trace table is:
Contents
504
o
Trace identification of entry.
See "Trace Identification" later in this Chapter.
1-3
If byte 0 contains other than one of the values from
X-FO' througn X'FC', these bytes contain the contents of
registe~ 14 at entry to the trace control program.
If byte 0 contains a value from X'FO' through X'FC',
these bytes contain the contents of register 14 at entry
to the CICS/VS management or service program involved.
4 and 5
For user entries, these bytes are unused.
CICS/VS APRM(ML)
~its
0-3) If byte 0 contains one of the values from X'PO' through
X'PC' or X'CS' through X'ES', these bytes generally
contain the type of request code as it relates to the
CICS/VS management or service program involved as
follows:
Program
Trace
Identification
Task control
Storage Control
Program control
Interval control
Dump control
Pile control
Transient data control
Temporary storage control
CICS/VS-OL/I interface
Journal control
Basic mapping support
Built-in functions
Terminal control
Sync point
Data interchange
Trace control
Dynamic transaction backout
EXEC interface
Pield Engineering
User exit interface
X'PO',X'OO'
X'Pl',X'C8',X'C9 1 ,X'CA'
X 'P2'
X'P3'
X 'P4'
X 'PS'
X 'P6'
X'P7'
X'P8'
X'P9 1
X'PA',X'CO',X'CP'
X'PB'
X'PC'
X'OSI
X '07 I
X'FO',X'PE',X'PF'
X'CBI
X'El'
X'E6' through X'EF'
X'OS'
Indicate the type of entry, as follows:
5
(bits 4-7)
X'8' Reserved
X '0 ' Reserved
X'9' Reserved
X'l' FE entry
X'2' User entry
X'A' Reserved
X'B' Reserved
X'3' LIPO system entry
X'C' Reserved
X'4 ' System entry
X'5 I LIPO response/return
X'D' On/off entry
X' 6' Reserved
X'E' Aux trace entry
X'F' Extended entry
X'7' Reserved
6-7
Transaction identification as found in TCAKCTTA, a field
in the system section of the TCA. This identification is
either a user task sequence number from 1 to 9999,
assigned by CICS/VS and stored in packed decimal form in
the rightmost (low-order) bytes, or the system task
identification (KC for task control, TC for terminal
control, or JC for journal control) stored in the
leftmost bytes.
8-11
Data field A.
12-15
Data field B.
The contents of byte 0 and the two data fields (bytes B through 15)
of application program-requested entries are determined by the OFHTR
TYPE=ENTRY macro instruction.
The contents of trace table entries for CICS/VS programs are fully
described in the £IC~LY2-~roblem Det~min~~!Qll-~~id~.
If consecutive, identical entries are generated, the first entry only
is entered into the table. In these cases, a special trace control
entry with trace identification X'PO' is created, and a count of the
Chapter 7.3.
Trace Control (OPHTR Macro)
505
nu~ber of times the previous entry is repeated is stored therein.
Trace
control entries with trace identification X'FEI or X'FF' indicate the
turning on or turning off of the trace facility, respectively.
Some of the functions required for recovery/restart as available
under CICS/OS/VS are performed by the sync point program. The trace
table entry for this program is described in Figure 8.B-16.
An entry with a trace identification in the range from X'E6' through
X'EF' is a special Field Engineering (FE) entry. The trace
identification X'E6' is included in all entries produced by the terminal
abnormal condition program. The contents and format of these entries
are described in the CICSIVS Problem Determination Guide.
If the entry is written to the auxiliary-trace data set, a 4-byte
prefix is appended to the entry. This prefix contains the time that the
entry was written to that data set.
Auxiliary trace writes the time, to
the data set, in units of 128 microseconds. The trace utility programs
convert this time to hours: minutes: seconds: microseconds, when
formatting the auxiliary trace output.
The contents of any fields characterized as IINot used ll in the
descriptions should be ignored during the analysis of a trace table
entry.
Trace Identification
Each standard entry contains in byte zero a unigue trace identification
from 240 through 0 (XIFOI through XIOOI) and information to aid the
application programmer in determining where the macro instruction was
issued and what type of reguest was made to the management program.
The application programmer can make direct, nonstandard entries in
the trace table by using the DFHTR macro instruction. A trace
identification number from 0 through 199 (XIOOI through X'C7') and
accompanying data is assigned for each trace entry. Thus, by defining
several unique trace entries, the programmer can trace the logical path
through a particular application or group of application programs.
Controlling the Trace
The trace control macro instruction DFHTR is used to activate and
deactivate tracing, and to insert user-defined entries in the trace
table. The trace can be activated and deactivated for the entire
CICS/VS system or for the issuing task alone.
The tracing facility can be controlled at various levels, as follows:
1. Master trace control
2. System, FE, or user control
3. (a) Within System, class control
(b) With User, single task control
To make a user trace entry, the master trace control flag must be on,
together with either the user control flag on or the single task trace
flag on. The first is accomplished by issuing DFHTR TYPE=ON,
STYPE=USER; the second is done by DFHTR TYPE=ON, STYPE=SINGLE.
506
CICS/VS APRM (ML)
To activat8 all tracing functions, issue
DFHTR TYPE=ON, STYPE=ALL
To activate system trac6 entries only, issue
DFHTR TYPE=ON, STYPE=SYSTEM followed by
DFHTR TYPE=ON, STYPE=(appropriate class name)
or use
DFHTR TYPE=ON, STYPE=ALL as above.
Tracing of eaCh event specified in a DFHTR TYPE=ON macro instruction
continues until terminated by a DFHTR TYPE=OFF macro instruction. The
STYPE operand in the DFHTR TYPE=OFF macro instruction specifies which
events are no longer to be logged.
The STYPE operand of the DFHTR macro instruction is used to specify
whether the instruction applies to the entire CICS/VS system or only to
the issuing task (SINGLE and SYSTEM parameters).
The application programmer can use the DFHTR TYPE=ENTRY macro
instruction to place his own entries in the trace table.
The following example illustrates how to activate the trace facility
for the issuing task and then to initiate tracing for all classes of
event except FE.
It also shows how to suppress tracing of user entries
and finally to deactivate the trace facility.
DFHTR TYPE=ON,STYPE=SINGLE
ACTIVATE TRACE FOR THIS TASK
DFHTR TYPE=ON,STYPE=ALL
START LOGGING ALL CLASSES EXCEPT FE
DFHTR TYPE=OFF,STYPE=USER
STOP LOGGING USER ENTRIES
DFHTR TYPE=OFF,STYPE=SINGLE
DEACTIVATE TRACE
Initiate Trace (TYPE=ON)
The format of the DFHTR macro instruction to start logging entries into
the trace table is as follows:
r------r-------r------------------------------------------------------------,
,
DFHTR , TYPE=ON
I [ ,STYPE= {SINGLE I ALL I (sy stem symbo11[, sys ••• ]) I
SY STEM, USER, FE} ]
L._ _ _ _ L.-._ __ _
,,
L__________________________________________________. ________
Chapter 7.3 •. Trace Control
(DFHTR Macro)
~
507
Terminate Trace (TYPE=OFF)
The format of the DFHTR macro instruction to stop logging entries into
the trace table is as follows:
I
I
I
I
DFHTR
TYPE=OFF
I
[ ,STYPE= {SINGLE I ALL I (system symboll[, sys ••• ]) I
I
SYSTEMIUSERIFE}]
IL______. L -_ _ _ _ _ _ L -_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
I
I
I
I
I
~I
Selected Entry Trace (TYPE=ENTRY)
The format of the DFHTR macro instruction to cause a given entry to be
logged is as follows:
DFHTR
508
TYPE=ENTRY
[ ,STYPE= {SYSTEM IUSER I FE} ]
,ID=number
[ , DATA 1= {symbol I (symbol)} ]
[ ,RDATA 1= {register I (register)} ]
[,DATA2={symboll ~ymbol)}]
[ ,RDATA2= {register I (register)} ]
[,DATA1TP={HBINIFBINICHARIPACKIPOINTER} ]
[,DATA2TP={HBINIFBINICHARIPACKIPOINTER} )
CICS/VS APRM(ML)
Operands of DFHTR Macro
DATA1=
specifies the address of the data to be placed in the first
data field (bytes 8 to 11) of the trace table entry.
symbol
is the symbolic address of the data to be placed in the
first data field of the table entry.
(symbol)
is the symbolic address of an area that contains the
address of the data to be placed in the first data field.
When this operand is included in a high-level language program,
DATA1TP is required.
DATA1TP=
specifies the format of the data to be placed in the first data
field of the trace table entry. The meanings of the keyword
parameters are as stated below:
Specification
Data Pormat
Field Definition
DATA1TP=HBIN
Halfword, binary
COBOL: 9 (4) .COMP
PL/I: BIN PIXED(15)
DATA1TP=PBIN
Fullword, binary
COBOL: 9(8) COMP
PL/I: BIN FIXED (31)
DATA1TP=CHAR
1 to 4 characters
COBOL: X (4)
PL/I: CHAR (4)
DATA1TP=PACK
1 to 4 bytes,
packed decimal
COBOL: 9 (7) COMP-3
PL/I: DEC FIXED (7)
DATA lTP=POINTER
PL/I pointer
variable
PL/I:
POINTER
This operand is valid only for COBOL and PL/I programs.
omitted, the default is PBIN.
If
DATA2=
is similar to DATAl except that it is used for the second data
field ~ytes 12 to 15) of the trace table entry.
When this operand is included in a high-level language program,
DATA2TP is required.
DATA2TP=
is similar to DATA1TP except that it is used for the second
data field of the trace table entry.
Chapter 7.3.
Trace Control (DPHTR Macro)
509
ID=number
specifies the trace identification number for this entry and
must be coded as a self-defining term.
A number from 0 through
199 may be specified when STYPE=USERi a number from 200 through
229 may be specified when STYPE=SYSTEM; and a number from 230
through 239 may be specified when STYPE=FE.
(The number 230 is
included in all entries produced by the terminal abnormal
condition program.) Numbers 240 through 253 (XIFO' through
X'FD') are reserved for system macro instruction trace entries.
The numbars 254 ~IFE') and 255 (X'FF') indicate TYPE=ON and
TYPE=OFF entries, respectively.
RDA'l~A
1=
(Assembler-language programs only)
specifies the register whose contents are to be placed in the
first data field of the trace table entry.
register
the number of the register whose contents are to be placed
in the first data field.
(register)
the number of the register whose contents are the address
of the data to be placed in the first data field.
RDATA2=
(Assembler-language programs ~nly)
is similar to RDATA1 except that it is used for the second data
field of the trace table entry.
STYPE=
indicates the type of entries to be logged or for which logging
is to be discontinued.
If this operand is omitted, USER is
assumed.
SINGLE
when included in the DFHTR TYPE=ON macro, specifies that
the tracing of user entries is to be turned on for the task
issuing the macro for the duration of the task or until
turned off by a DFHTR TYPE=OFF, STYPE=SINGLE macro.
when included in the DFHTR TYPE=OFF macro, specifies that
the tracing of user entries is to be turned off for the
task issuing the macro.
ALL
specifies that all tracing facilities (except Field
Engineering) are to be turned on. This parameter turns on
the master system trace flag and all of the individual
system trace flags, in addition to performing the function
of the USER parameter. It also, when used in the DFHTR
TYPE=OFF macro, specifies that all tracing facilities
(including Field Engineering) are to be stopped.
(system symbol1[ ,sys ••• ])
specifies ona or more system symbols that turn on or off
appropriate system macro trace facilities. The valid
system symbols are as follows:
510
CICS/VS APRM(ML)
KC
SC
PC
IC
DC
FC
TD
TS
BM
SF
TC
SP
DI
UE
Task Control (DFHKC)
Storage Control (DFHSC)
Program Control (DFHPC)
Interval Control (DFHIC)
Dump Control (DFHOC)
File Control (DFHFC)
Transient Data Control (DFHTD)
Temporary Storage Control (DFHTS)
Journal Control (DFHJC)
Basic Mapping Support (OFHBMS)
Built-In Functions (OFHBIF)
Terminal Control (OFHTC) (for VTA M-supported
terminals only)
Sync Point Control (DFHS~
Data Interchange Control (DFHDI)
User Exit Interface
For TYPE=ON, each symbol turns on a single system trace
flag.
Before tracing of any system macros occurs, the
master systam trace flag must also be turned on by means of
the SYSTEM parameter. Note that two DFHTR macros must be
issued to accomplish this; SYSTEM and system symbols cannot
both be specified on the same macro.
SYSTEM
sp~cifies
that the entry is a CICS/VS entry. This
parameter turns on or off the system master trace flag,
which must be on in addition to the individual system trace
flags before tracing of any system macros occurs.
When
used to turn off the master trace flag it does not turn off
the individual system trace flags.
See also the
description of the system symbols above.
Therefore,
although all tracing activities for the system macros are
suppressed, the previous pattern of activity could be
reinstated by issuing a OFHTR TY~E=ON,STYPE=SYSTEM macro
instruction, without the need to issue a DFdTR TYPE=ON
macro with the various system symbols defined.
USER
specifies that the entry is a user entry and that when
included in a DFHTR TYPE=ON macro specifies that the trace
facility is to be turned on for all user entries for all
active tasks; that is, causes the trace facility to begin
logging user entries to the trace table for all tasks
currently active in the system, and for all tasks becoming
active subsequently, until the user trace facility is
turned off.
FE
(Assembler-language programs only)
specifies that the entry is a Field Engineering (FE) entry.
This is the only parameter that will turn on the FE tracing
facilities.
Chapter 7.3.
Trace Control
~FHTR
Macro)
511
Chapter 7.4. Dump Control (DFHDC Macro)
Dump management provides the capability of dumping specified areas of
main storage onto a sequential data set, either tape or disk.
This data
set contains information about the user's transaction or application
program, and can be subsequently formatted and printed offline (or while
the dump data set is closed) using a CICS/VS dump utility program
(DFHDUP) •
Requests for dump services are communicated to dump control through
the DFHDC macro instruction. A CICS/VS Snap dump can also be req~ested
by the master terminal operator. Dump control executes at the priority
of the requesting program, under control of the TCA of the requesting
program saving and restoring registers from this TCA.
After a requested
dump service has been provided, control is returned to the next
executable instruction in the requesting program.
Dump control operates as a serially reusable program resource. Only
one service request is processed at a time. If additional requests for
dUmp services are made while a dump is in progress, the tasks associated
with those service requests are delayed (suspendad) and placed in a
"hold" status until the dump is completed. Remaining dump request5 are
serviced on a first-in first-out (PIFO) basis.
The dump management macro instruction
of the following services:
(DPHDC)
is used to request any
•
Dump ~ain storage areas related to a transaction and its associated
task (or any other main storage areas)
•
Dump the following CICS/VS control taDles:
program control table
WCT), processing program table (PPT), system initialization table
(SIT), terminal control table (TCT), file control table (FCT), ando
destination control table (DCT)
•
Dump transaction-oriented storage areas and CICS/VS control tables
•
Dump selected main storage areas.
•
For CICS/OS/VS only, dump DL/I control blocks.
To ensure a dump of the TIOA following a terminal control write that
precedes a DFHDC macro instruction, the application programmer must
issue a SAVE and WAIT with the DFHTC TYPE=WRITE macro instruction.
When the DFHDC macro instruction is executed, information is stored
in °fields TCADCTR and TCADCDC of the common communication area of the
TCA, which is used for CICS/VS sarvice requests. Before doing so,
however, the macro preserves the previous contents of the fields by
copying TCADCTR (2 bytes) to TCACCSV1, and TCADCDC (4 bytes) to
TCACCSV2. The previous contents can therefore be seen in the dump. The
field TCADCDC is saved only if DMPCODE=value is specified. If
DMPCODE=YBS is specified, the user must preser'Te the contents of TCADCDC
(if they are to appear in the dump) before storing the dump code in that
field.
The Dump Control module will use the register save area, TCACCRS, of
the common communication area. To see the previous contents in a dump
the application program must obtain 14 words of storage into which to
copy the contents of TCACCRS before issuing the DFHDC macro.
Chapter 7.4.
Dump Control (DFHDC Macro)
513
CICS/VS control tables will be dumped only if the CICSDMP=YES operand
is specified in the DFHSG PROGRAM=DCP macro instruction at system
generation.
(See the CICS/VS System~rammer's Ref~ce Ma~al.)
Every dump request will include the TCA, CSA, and trace table, unless
one or more of these are suppressed with the SUPPR operand. The trace
table will also be suppressed if the trace facility is not currently
active.
514
CICS/VS APRM(!L)
Dump Transaction Storage (TYPE=TRANSACTION)
The format of the DFHDC macro instruction to specify a
follows:
~ump
is as
r-------~-------ri---------------------------------------
I
I
I
I
I ______
~I
I
DFHDC I TYPE=TRANSACTION
I [, DMPCODE= {val ue I YES} ]
I [, SUPPR= ([ CSA ][ , TCA][ ,TRT]) I ALL]
______ IL__________________________________________________________
~
~
This macro specifies a dump of all main storage areas related to a
transaction and its associated task.
This dump is normally used during
the testing and debugging of user-written application programs.
(CICS/VS automatically provides this service if the related task is
abnormally terminated.)
For CICS/OS/VS only, DL/I control blocks will also be dumped.
folloaing main storage areas can be dumped:
The
u~rl~
1.
Task control area (TCA) and, if applicable, the transact iop
area (T{'i A)
2.
Common system area (CSA), including the user's portion of th9 CSli
(CriA )
3.
Trace table
4.
Contents of general-purpose registers upon entry to dump control
from requesting task
5.
Either the terminal control table terminal entry (TCTTE) or the
destination control table entry associated with the requesting task
6.
All transaction storage areas chained off the TCA storage
accounting field
7.
All program storage areas containing user-written application
program(s) active on behalf of the requesting task
8.
Register save areas
9.
All terminal input/output areas (TIOAs) chained off the terminal
control table terminal entry (TCTTE) for the terminal associated
with the requesting task (if any)
~SAs)
indicated by the RSA chain off the TCA
Whenever the TCTTE is dumped (see 5 above), the terminal control
table user area ~f any) and the message control blocks (if any)
associated uith the TCTTE are dumped. The latter are used by basic
mapping support.
The following example illustrates the coding required to request a
dump of transaction storage:
DFHDC TYPE=TRANSACTION,
DMPCODE=D010
REQUEST TRANSACTION STORAGE DUMP
USER-SPECIFIED DUMP CODE
Chapter 7.4.
Dump Control (DFHDC Macro)
*
515
Dump CICS/VS Storage (TYPE=CICS)
The format of the DFHDC macro instruction to specify a dump of system
tables is:
r------~------~I-------------------------------------
I
I
I
I
I
~
I
DFHDC I TYPE=CICS
I [,DMPCODE={valuelYES}]
I [, SUPPR= ([ CSA][ , TCA ][ ,TRT]) I ALL]
LI ________________________________________________________
_____ L _______
~
The application programmer can request a dump of PCT, PPT, TCT, FCT,
and DCT by issuing the DFHDC TYPE=CICS macro instruction. This facility
is available if the CICSDMP=YES operand is specified in the DFHSG
PROGRAM=DCP macro instruction at system generation (see the CICS/VS
~ystem Programmer's Reference Manual).
This dump is typically the first
dump taken in a testing situation in which the base of the test must be
established; subsequent dumps are usually of the TRANSACTION type.
This macro specifies that PCT, PPT, SIT, TCT, FCT, and DCT are to be
dumped. The TCA (and the TWA, if applicable), CSA (and CiA), and trace
table ar9 also dumped.
The following example illustrates the coding required to request a
dump of PCT, PPT, SIT, TCT, FCT, DCT, CSA, TCA, and the trace table:
DFHDC 'rYPE=CICS,
DMPCODE=D020
516
CICS/VS APRM (riL)
REQUEST CICS/VS STORAGE DUMP
USER-SPECIFIED DUMP. CODE
*
Dump Transaction Storage and CICS/VS Storage (TYPE=COMPLETE)
The format of the DFHDC macro instruction to specify a complete dump is:
r-----,--
I
I DFHDC
I
I
L______ I ______
~
TYPE=COMPLETE
[ ,DMPCODE= (value I YES} ]
[ , SUPPR= ([ CSA][ ,TCA ][ , TRT]) I ALL]
~
______________________________________________________
~
The application programmer can request a dump of both
transaction/task-related storage and PCT, PPT, SIT, TCT, FCT, and DCT by
issuing the DFHDC TYPE=COMPLETE macro instruction. The PCT, PPT, SIT,
TCT, FCT, and DCT will be dumped if CICSDMP=YES was specified in the
DFHSG PROGRAM=OCP macro instruction at system generation (see the
CICS/VS Syste~~ro~rammer's Reference Manual). For CICS/OS/VS only,
DL/I control blocks will also be dumped.
To request a complete dump is sometimes appropriate during execution
of a task, but this macro instruction should not be used excessively.
CICS/VS control tables are primarily static areas; therefore, requesting
one CICS dump and a number of TRANSACTION dumps is generally more
efficient than requesting a comparable number of COMPLETE dumps.
This
macro specifies that transaction/tasK-related storage and PCT, PPT, SIT,
TCT, FCT, and DCT are to be dumped.
The following example illustrates the coding required to request a
dump of both transaction storage and PCT, PPT, SIT, TCT, FCT, and OCT:
DFHDC TYPE=COMPLETE,
DMPCODE=D030
Chapter 1.4.
REQUEST COMPLETE STORAGE DUMP
USER-SPECIFIED DUMP CODE
Dump Control (OFHDC Macro)
*
517
Dump Partial Storage (TYPE=PARTIAL)
The format of the DFHDC macro instruction to specify a partial dump is:
DFHDC
TYPE=PARTIAL
,LIST= ([TERMINAL][ ,PROGRAM][ ,TRANSACTION][ ,SEGMENT])
[,DMPCODE={valueIYES} ]
[ ,SUPPR= ([ CSA][ ,TCA][ ,TRT]) I ALL]
The application programmer can request a dump of selected main
storage ar~as related to the requesting task by issuing the DPHDC
TYPE=PARTIAL macro instruction. This type of dump can be used during
the testing and debugging of user-written application programs. It
includes only the storage areas specified.
If SEGMENT is specified in the LIST operand, the application
programmer must code two instructions that place the address of thd main
storage area to be dumped into TCADCSA and the length (in binary) of the
area to be dumped into TCADCNB prior to execution of the DPHDC
TYPE=PARTIAL macro instruction. The maximum length that can be
specified in TCADCNB is 32,767 bytes. The specified area must be a
valid area, that is, storage allocated by the operating system within
the CICS/VS region/partition boundaries.
It is possible to dump several user areas rather than just one. The
application programmer must construct a table of the user areas to be
dumped, and their lengths, and place the address of the table ~n
TCADCSA. Also, TCADCNB must be set to zero. Both of these actions must
precede the DFHDC TYPE=PARTIAL macro. The table must consist of eightbyte entries, each entry containing a four-byte length field followed by
a four-byte address field. The table should then be completed by adding
an extra four-byte field containing X'FFFFFFFP'.
The following example shows how to request a PARTIAL storage dump
that includes, along with all program storage areas, all transaction
storage areas associated with this task:
DPHDC TYPE=PARTIAL,
LIST=(TRANSACTION,
PROGRAM) ,
DMPCODE=DT3P
REQUEST PARTIAL STORAGE DUMP
AREAS ASSOCIATED WITH TRANSACTION
PROGRAM STORAGE AREAS
USER-SPECIFIED DUMP CODE
*
*
*
This example is applicable to Assembler language, COBOL, or PL/I
programs. All values passed to CICS/VS are specified in the DFHDC macro
instruction. As noted above, when SEGMENT is specified, certain values
must be stored in fields of the TCA prior to execution of the DFHDC
macro instruction. The programmer can also store the dump code in the
TCA prior to execution of the macro instruction.
The following examples show how to request a PARTIAL dump of a
selected main storage area, using either Assembler language, COBOL, or
PL/I.
ST
HVC
518
R5,TCADCSA
TCADCNB,=H'16384'
CICS/VS APRM
~L)
PLACE STORAGE ADDRESS IN TCA
PLACE LENGTH OF AREA IN TCA
MVC
TCADCDC,=CL4 t AB12
DFHDC TYPE=PARTIAL,
LIST=SEGMENT,
DMPCODE=YES
t
PLACE DUMP CODE IN TCA
REQUEST PARTIAL STORAGE DU~P
DUMP AREA PREVIOUSLY SPECIFIED
DUMP CODE PREVIOUSLY SPECIFIED
*
NOTE PLACE STRG ADDRESS IN TCA.
NOTE PLACE LENGTH OF AREA IN TCA.
NOTE PLACE DUMP CODE IN TCA.
REQUEST PARTIAL STORAGE DUMP
DU~P AREA PREVIOUSLY SPECIFIED
DUMP CODE PREVIOUSLY SPECIFIED
*
*
For COBOL:
MOVE DATADDR TO TCADCSA.
MOVE 16384 TO TCADCNB.
MOVE IAB121 TO TCADCDC.
DFHDC TYPE=PARTIAL,
LIST=SEGMENT,
DMPCODE=YES
*
For PL/I:
TCADCSA=ADDR(DATA);
TCADCNB=16384 ;
TCADCDC=IAB12 1 ;
DFHDC TYPE=PARTIAL,
LIST=SEGMENT,
DMPCODE=YES
/*PLACE STORAGE ADDRESS IN TCA*/
/*PLACE LENGTH OF AREA IN TCA*/
/*PLACE DUMP CODE IN TCA*/
REQUEST PARTIAL STORAGE DUMP
DUMP AREA PREVIOUSLY SPECIFIED
DUMP CODE PREVIOUSLY SPECIFIED
Chapter 7.4.
Dump Control (DFHDC Macro)
*
*
519
Operands of DFHDC Macro
DMPCODE=
is a four-character dump code to be printed out with the
requested dump to identify iti this code should be unique so
that it is informative concerning the condition that caused the
dump.
value
is a combination of four alphabetic or numeric characters
to be printed as the dump code.
YES
indicates that the dump code has been placed in TCADCDC.
LIST=
identifies specific areas to be dumped.
TERMINAL
indicates that all storage areas associated with the
terminal are to be dumped. These storage areas are as
follows:
1.
Task control area (TCA) and, if applicable, the
transaction work area (TWA)
2.
Common system area (CSA), including the user's portion
of the CSA (CiA)
3.
Trace table
4.
All terminal input/output areas ~IOAs) chained off the
terminal control table terminal entry (TCTTE) for the
terminal associated with the requesting task
5.
contents of general-purpose registers upon entry to
dump control from the requesting task
6.
Either the terminal control tahle terminal entry (TCTTE)
or the destination control table entry associated
with the requesting task
Whenever the TCTTE is dumped, the terminal control table
user area (if any) and the message control blocks (if any)
associated with the TCTTE are dumped. The latter are used
by basic mapping support.
PROGRAM
indicates that all program storage areas associated with
this task are to be dumped. These storage areas include:
520
CICS/VS APRM(ML)
1.
Task control area (TCA) and, if applicable, the
transaction work area (TWA)
2.
Common system area
of the CSA (CWA)
3.
Trace table
4.
All program storage areas containing user-vritten
application program(s) active on behalf of the requesting
task
5.
Register save areas (RSAs) indicated by the RSA chain
off the TCA
6.
Contents of general-purpose registers upon entry to
dump control from the requesting task
7.
Either the terminal control table terminal entry (TCTT~
or the destination control table entry associated with
the requesting task
~SA),
including the user's portion
Whenever the TCTTE is dumped, the terminal control table
user area (if any) and the message control blocks (if any)
associated with the TCTTE are dumped.
TRANSACTION
is typically used in combination with other types of
PARTIAL dump requests to include all transaction storage
areas associated with the task. These areas include:
1.
Task control area (TCA) and, if applicable, the
transaction work area (TWA)
2.
Common system area
of the CSA (CWA)
3.
Trace table
4.
Contents of general-purpose registers upon entry to
dump control from the requesting task
5.
All transaction storage areas chained off the TCA
storage accounting field
6.
Either the terminal control table terminal entry (TCTTE)
or the destination control table entry associated
with the requesting task
7.
DL/I control blocks
~SA),
including the user's portion
(CICS/OS/VS only)
Whenever the TCTTE is dumped, the terminal control table
user area (if any) and the message control blocks (if any)
associated with the TCTTE are dumped.
SEGMENT
is used to include in the PARTIAL dump any area of main
storage specified. In addition to the selected area, the
contents of the following storage areas are displayed:
Chapter 7.4.
Dump Control
~FHDC
Macro)
521
1.
Task control area (TCA) and, if applicable, the
transaction work area (TWA)
2.
Common system area (CSA), including the user's portion
of the CSA (CWA)
3.
Trace table
4.
Contents of general-purpose registers upon entry to
dump control from the requesting task
5.
Either the terminal control table terminal entry (TCTTE)
or the destination 'control table entry associated
with the requesting task
Whenever the TCTTE is dumped, the terminal control table
user area (if any) and the message control blocks (if any)
associated with the TCTTE are dumped.
These parameters are not mutually exclusive. They can be
specified in any combination and any order. The
parentheses are optional when only one parameter is
specified. At least one parameter is required.
No storage
area is dumped more than once as a 'result of a single DFHDC
TYPE=PARTIAL request. Thus, for example, if DFHDC
TYPE=PARTIAL,LIST=(TERMINAL,TRANSACTION) is specified, the
contents of the TeA and CSA are displayed only once.
SUPPR=
indicates that one or more CICS control tables will not be
dumped. The dumps to be suppressed are determined by coding
one or more of the following:
CSA
TCA
TRT
Common system area
Task control area
Trace table
These parameters are not mutually exclusive. They can be
specified in any combination and any order.' The parentheses
are optional when only one parameter is specified. At least
one parameter is required. Alternatively, all three of the
above areas can be suppressed by coding SUPPR=ALL.
522
CICS/iS APRM(ML)
Chapter 7.5. Journal Control (DFHJC Macro)
~ournal management provides facilities for creating and managing
'special-purpose sequential data sets, called 'journals,' during realtime CICS/VS execution. Journals may contain data the user needs to
facilitate subsequent reconstruction of events or data changes. For
example, a journal might act as an audit trail, a change-file of database updates and additions, or a record of transactions passing through
the system (often called a 'log').
In addition to the output services described in this chapter, journal
management also provides support for:
•
Operational control and disposition of volumes (see the CICS/VS
Programmer's Guide (DOS/VS) or the £ICS/VS System
~stem
PrQ[~~~~2-Q~~de_(OS~
•
Requests to switch volumes and/or read journal data sets during
real-time CICS/VS execution (see the CICStyS system Progr~!§
Reference Manual)
Requests for journal output services are made by issuing the journal
control macro instruction (DFHJC), either directly from a user task or
from a CICS/VS management program on behalf of a user task. Data may be
directed to any journal data set specified in the journal control table
(JCT), which defines the journals available during a particular CICS/VS
execution. The JCT may define one or more journals on tape or direct
access storage. Each journal is identified by a number, in the range 2
through 99, known as the journal file identification. The value of 1 is
reserved for a journal known as the system log.
All buffer space and other work areas needed for journal data set
physical operations are acquired and managed by the journal control
program (JCP). The user task supplies only the address and length of
the data to be output. The data is moved to journal buffer space by JCP
when building a journal record. The user task retains the use and
control of the data and its CICS/VS storage area.
Journal output requests are serviced by JCP. Journal records are
built into blocks compatible with standard variable-blocked format.
JCP
uses the sequential access method of the host operating system to write
the blocks to auxiliary storage.
Each logical journal record begins with the standard four-byte length
field, a user-specified identifier, and a system-supplied prefix. This
data is followed in the journal record by any user-supplied prefix data
(optional), and finally by the user-specified data.
Journal control is
designed so that the application programmer requesting output services
need not be concerned further with the detailed layout and precise
contents of journal records. He needs to know only which journal to
use, what user data to specify, and what unique user-identifier to
supply. Normally, he obtains this information from the application
system analyst or the person(s) responsible for programs for reading
journal data sets.
(See the CICS/VS System Programmer's Reference
Manual.)
JCP builds journal records for output requests at the priority of the
requesting program, under control of the TCA of the requesting program.
However, the TCA is not used to communicate requests and to save/restore
registers. Instaad, a separate control area called a journal control
Chapter 7.5.
Journal Control (DFHJC Macro)
523
area (JCA) is used; this area must be acquired by the task before any
journal output requests are issued.
If no other event is in-process to the journal, output to a journal
data set is also initiated under the requestor's TCA. However, output
event completion is always processed under a different TCA--that of a
high-priority journal task associated with the journal data set.
Journal tasks are activated when CICSjVS execution begins, but are
suspended when there are no output events outstanding. In a heavy load
situation, where many user tasks request journal output while one output
is in-process, a journal task initiates more output immediately after
completion of the in-process output event.
The application programmer may specify parameter values for journal
control requests in either of two ways:
•
By including the parameters in oparands of the DFBJC macro
instruction by which journal services are requested, or
•
By coding instructions that place the parameter values in fields of
the JCA prior to issuing the DFHJC macro instruction
The second of these methods provides greater economy, in that the
parameter values can be varied to meet the logic needs of the
application, but only a single DFHJC macro instruction need be coded.
Journal output services that may be requested through the journal
control macro instruct10n are introduced and explained in the following
paragraphs.
524
CICS/VS APRM(ML)
Acquire a Journal Control Area (TYPE=GETJCA)
The format of the DFHJC macro instruction to acquire a journal control
area (JCA) is as follows:
r------r-------r'------------------------------------------------------------,
I
L -_ _ _ _ _
~
DFHJC I TYPE=GETJCA
_______I
L __________________________________________________________
~
This macro specifies that an area to be used for communication
between the application program and the CICS/VS journal control program
is to be acquired.
The address of the JCA is returned in TCAJCAAD to
the application program.
If journal output services are requested in an application program
through DFHJC macro instructions, the application programmer must
provide the symbolic definition of the JCA by copying the CICS/VS
storage area map DFHJCADS. The JCA must be acquired for the task prior
to any journal output requests by issuing the macro instruction:
DFHJC TYPE=GETJCA
The JCA may be acquired separately, as shown above, in which case no
other operands are needed. Alternatively, the JCA may be acquired by
and with the program's first journal output request; for example:
DFHJC TYPE= (GETJCA,PUT)
If the latter approach is chosen, then it is not possible to place
additional parameter values for the output request directly into the JCA
prior to the request, because the JCA does not exist prior to this
request.
If any such request is attempted, warning messages are issued
and the request is not processed.
In addition to acquiring the JCA for the task, the DFHJC TYPE=GETJCA
macro instruction establishes addressability to the area by moving the
contents of the JCA address field (TCAJCAAD) to JCABAR, the base locator
specified for the area. Once acquired for the task, the JCA is reused
for all subsequent journal requests issued by or on behalf of the task.
Subsequent TYPE=GBTJCA requests only cause JCABAR to be reloaded with
the same value. The JCA may not be released by the user.
The following examples show how to acquire the journal control area
(JCA) for the task:
For Assembler language:
COpy
DFHTCADS
COpy TCA SYMBOLIC DEFINITIONS
JCABAR EQU
CO PY
10
DFHJCADS
ASSIGN BASE REGISTER FOR JCA
COpy JCA SYMBOLIC DEFINITIONS
GETJCA DFHJC TYPE=GETJCA
Chapter 7.5.
REQUEST ACQUISITION OF THE JCA
Journal Control
(DFHJC Macro)
525
For COBOL:
02 JCABAR PIC S9 (8) COMP.
NOTE DEFINE BASE LOCATOR FOR JCA.
01 DFHTCADS COPY DFHTCADS.
NOTE COPY TCA SYMBOLIC DEFINITIONS.
01 DFHJCADS COpy DFHJCADS.
NOTE COpy JCA SYMBOLIC DEFINITIONS.
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
NOTE LOAD TCA BASE LOCATOR VALUE.
GETJCA.
DFHJC TYPE=GETJCA
REQUEST ACQUISITION OF THE JCA
For PL/I:
%INCLUDE DFHTCADS;
/*COPY TCA SYMBOLIC DEFINITIONS*/
%INCLUDE DPHJCADS;
/*COPY JCA SYMBOLIC DEPINITIONS*/
GETJCA:
DFHJC TYPE=GETJCA
REQUEST ACQUISITION OF THE JCA
526
CICS/VS APRM(ML)
Create a Journal Record and Wait for Output (TYPE=PUT)
The format of the DFHJC macro instruction to create a journal record,
initiate its output, and wait for completion is as follows:
r------~------~-----------------------------------------------------------,
DFHJC
TYPE= {PUT I (WRITE ,WAIT)}
,JFILElD={nnISYSTEMIYES}
,JTYPElD={nnnnIYES}
,JCDADDR={symbolic addresslYES}
,JCDLGTH={decimal valuelYES}
[,PFXADDR={symbolic addressIYES}]
[,PFXLGTH={decimal valueIYES}]
[ , STARTlO= {YES I NO} ]
[,NORESP=symbolic address)
[,lDERROR=symbolic address]
[,LERROR=symbolic address]
[,lOERROR=symbolic address]
[,NOTOPEN=symoolic address)
[,lNVREQ=symbolic address]
[,STATERR=symbolic address]
This macro specifies that a journal record is to be created in the
journal buffer area and then written out; the requesting task will wait
until the physical record has been written. TYPE=(WRITE,WAlT) implies,
and is equivalent to, TYPE=PUT.
Because the maximum buffer length that can be used to write a journal
record is 32,767 bytes, the combined length specified by JCDLGTH and
PFXLGTH (or stored in JCALD~TA and JCALPRFX, respectively) cannot exceed
32,767.
The STARTlO=YES operand specifies that the journal record is to be
written out immediately. This is also the default. If STARTIO=NO is
specified, initiation of output will be delayed until either the journal
buffer is full, output is initiated by another request to the same
journal, or one second elapses.
Use of this macro ensures that the journal record is written on the
auxiliary storage device associated with the journal before processing
continues; the task is said to be 'synchronized' with the output event.
Most ClCSjVS-provided data output service is performed in a synchronous
manner.
The application programmer may request synchronous journal output
services either by a DFHJC TYPE=PUT macro instruction as above, or by
specifying DFHJC TYPE= ~RlTE,WAIT). In both cases, certain additional
keyword operands are mandatory. These keywords are JPILEID (the journal
data set to receive data), JCDADDR (the address of the 'lSer data to be
included in the journal record), JCDLGTH (the length of the user data) ,
and JTYPElD (the two-byte user-specified hexadecimal identifier for the
journal record). optional accompanying keywords are PFXADDR (the
address of user prefix data for inclusion in the journal record) and
PFXLGTH (the length of the user prefix data); the application programmer
may also include keyword operands to direct control to exceptionhandling routine s in the program. (See "Test Response to a Request for
Journal Services," later in this chapter.)
The following examples show how to request and wait for journal
output service.
Chapter 7.5.
Journal Control (DFHJC Macro)
521
COpy
DFHrt1CADS
COpy TCA SYMBOLIC DEFINITIONS
EQU
COpy
10
DFHJCADS
ASSIGN BASE REGISTER FOR JCA
COpy JCA SYMBOLIC DEFINITIONS
FWACBAR EQU
COpy
RECORD DS
KEYDATA DS
ACCNTNO DS
AMOUNT DS
DS
NAME
ADDRESS DS
9
DFRFWADS
OCL90
OCL8
PL4
PL4
CL20
CL40
ASSIGN BASE REGISTER FOR FWA
COpy FWA SYMBOLIC DEFINITIONS
JCABAR
DFRJC TYPE=PUT,
JFILEID=2,
JCDADDR=KEYDATA,
JCDLGTH=8,
JTYPEID=OFO 1,
NORESP=OK
OR
OK
DS
528
CICS/VS APRM(ML)
REQUEST SYNCHRONOUS OUTPUT
TO JOURNAL ID 2,
OF TRE 'KEY' DATA,
OF LENGTH=8 BYTES.
(IDENTIFIER FOR JOURNAL RECORD)
BRANCH ADDR FOR NORMAL RESPONSE
*
*
*
*
*
For COBOL:
02 J CA BA R PIC S 9 (8) Cali P •
nOTE DEFINE BASE LOCATOR FOR JCA.
01 DFHTCADS COpy DFHTCADS.
NOTE COPY TCA SYMBOLIC DEFINITIONS.
01 DFHJCADS COpy DFHJCADS.
NOTE COpy JCA SYMBOLIC DEFINITIONS.
01 DFHFWADS COpy DFHFHADS.
NOTE COPY FWA SYMBOLIC DEFINITIONS.
02 RECORD.
03 KEYDATA.
04 ACCNTNO PIC S9(7) COMP-3.
04 AMOUNT PIC S9(7) COMP-3.
03 NAME PIC X (20) •
03 ADDRESS PIC X(40).
PROCEDURE DIVISION.
HOVE CSACDTA TO TCACBAR.
DFHJC TYPE=PUT,
JFILEID=2,
JCDADDR=KEYDATA,
JCDJ.. GTH=8,
JTYPEID=OFO 1,
NORESP=OK
NOTE LOAD TCA BASE LOCATOR VALUE.
REQUEST SYNCHRONOUS OUTPUT
TO JOURNAL ID 2,
OF THE IKEY I DATA,
OF LENGTH=8 BYTES.
(IDENTIFIER FOR JOURNAL RECORD)
BRANCH ADDR FOR NORMAL RESPONSE
*
*
*
*
*
OK.
Chapter 7.5.
Journal Control
(DFHJC Macro)
529
lQ~~L/I:
%INCLUDE DFBTCADS;
/*COPY TCA SYMBOLIC DEFINITIONS*/
IINCLUDE DFBJCADS;
/*COPY JCA SYMBOLIC DEFINITIONS*/
..
IINCLUDE DFHFWADS;
/*COPY FWA SYMBOLIC DEFINITIONS*/
02 RECORD,
03 KEYDATA,
/*8-BYTE aINOR STRUCTURE*/
04 ACCNTNO FIXED DECIMAL (7),
04 AMOUNT FIXED DECIMAL n),
03 NAME CBAR (20),
03 ADDRESS CHAR ~O),
DFHJC TYPE=PUT,
JFILEID=2,
JCDADDR=KEYDATA,
JCDLGTH=8,
JTYPEID=OFO 1,
NORESP=OK
OK:
530
CICS/VS APRM(ML)
REQUEST SYNCHRONOUS OUTPUT
TO JOURNAL ID 2,
OF THE 'KEY' DATA,
OF LENGTH=8 BYTES.
(IDENTIFIER FOR JOURNAL RECORD)
BRANCH ADDR FOR NORMAL RESPONSE
*
*
*
*
*
Create a Journal Record (TYPE=WRITE)
The general format of the DFHJC macro instruction to create a journal
record for subsequ~nt output is as follows:
DFHJC
TYPE=WRITE
,JFILEID={nnISYSTE~IYES}
,JTYPEID={nnnnIYES}
,JCDADDR={symbolic addresslYES}
,JCDLGTH={decimal valuelYES}
[,PFXADDR=(symbolic addresslYES}]
[,PFXLGTH={decimal valueIYES}]
[ ,STARTIO= {YES I NO} ]
[ ,COND= ( (YES, symbolic address) 11!Q}
[,NORESP=symbolic address]
[,IDERROR=symbolic address]
[,LERROR=symbolic address]
[,NOTOPEN=symoolic address]
[,INVREQ=symbolic address)
[,STATERR=symbolic address]
]
This macro causes a journal record to be created in the journal
buffer area, but allows the requesting task to retain control and thus
to continue with other processing.
At some later time, the task may wish to ensure that the journal
record has been written. If the JCA is to be used for any other journal
requests, that task should save the event control number (four bytes)
returned in JCAECN after a journal record is successfully created in
response to the DFHJC TYPE=WRITE request. The event control number must
be restored to the JCA immediately before the DFHJC TYPE=WAIT request
used to check and wait for output. If the JCA is not used in the
interim for any other journal requests for the task, there is no need to
save and restore the event control number.
However, restoring the event control number prior to issuing a DFHJC
TYPE=WAIT macro is a good programming practice. CICS/VS management
modules also u~e the JCA of the task for journal requests. For example,
automatic journaling is used in the file control program, and logging
can be performed for recovery purposes at the user's option.
Additional keyword operands applicable to TYPE=WRITE requests are as
described above under "Create a Journal Record and Wait for Output."
The basic process of building journal records in the buffer space of
a given journal continues until such time as one of the following
situations occurs:
•
A request is made for synchronous output of a journal record.
•
A request is rejected because of insufficient journal buffer spaceo
•
The available buffer space is reduced below a user-specified level
(see the CICS/VS System Programmer's Reference Manual) ~
At that time, all journal records present in the buffer, including
any 'deferred' output resulting from asynchronous requests, are written
to external storage, as one block.
Chapter 7.5.
Journal Control (DFHJC Macro)
531
If a task creates deferred output and delays synchronizing, the
deferred output may be written 'for free' along with other requests;
when the task attempts to synchronize, there will be no need for it to
wait. Thus, the advantages that may be gained by deferring journal
output are:
(1) transactions may get better response times by waiting
less, (2) the load of physical I/O requests on the host system may be
reduced, and P) journal data sets may contain fewer but larger blocks
and so better utilize external storage devices.
However, these advantages are achievable only at the cost of more
buffer space and greater programming complexity. It is necessary to
plan and program to coutrol synchronizing with journal output.
Additional decisions which depend on the data content of the journal
record and how it is to be used must be made in the application program.
In any case, the full benefit of deferring journal output is obtain8d
only when the load on the journal data set is high.
The STARTIO keyword governs whether output is to be initiated (YES)
or not (NO). The default option is NO for WRITE requests and YES for
PUT, (WRITE,HAIT), or WAIT requests. The option NO should be used
uhenever possible because, if every journal request uses STARTIO=YES, no
improvement over synchronous output requests, in terms of reducing the
number of physical I/O operations and increasing the average block size,
is possible.
The COND keyword governs what happens if the journal buffer space
available at the time is not sufficient to contain the journal record
for the request. If the default option COND=NO is taken, the requesting
task loses control. The contents of the current buffer are written out,
and the journal record for this request is built in the resulting freed
buffer space before control returns to the requesting task.
If the requesting task is not willing to lose control, for example,
if some housekeeping must be performed before other tasks get control,
than COND=(YES,symbolic address) should be specified. If buffer space
is momentarily insufficient, no journal record is built for the request,
and control is returned directly to the requesting program at the
location identified by symbolic address.
The requesting program can
perform any housekeeping needed before reissuing the journal output
request.
The following example shows how to request deferred journal output,
but ensure that the requesting task retains control to perform
housekeeping, if necessary.
For Assembler 1anquagQ:
COPY
DS
DFHCSADS
CL10
COPY CSA SYMBOLIC DEFINITIONS
AND COMMON WORK AREA
COpy
SAVEDATA DS
MYDATA
DS
DFHTCADS
CL10
CL10
COPY TCA SYMBOLIC DEFINITIONS
SAVE AREA FOR COMMON DATA
AREA FOR MY DATA
JCABAR
EQU
COpy
10
DFHJCADS
ASSIGN BASE REGISTER FOR JCA
COPY JCA SYMBOLIC DEFINITIONS
MVC
SAVEDATA,COMDATA
SAVE
COMDATA
532
CICS/VS APRM(ML)
CO~MON
DATA
liVC
COM DATA ,MYDATA
DFHJC TYPE=WRITE,
JCDADDR=COMDATA,
JCDLGTB=10,
J FILEID=SYSTEM,
JT!PEID=0101,
STARTIO=NO,
COND=(YES,RETRY),
NORESP=OK
OK
DS
OB
RETRY
DS
MVC
MVC
DFHJC
OH
MYDATA,COMDATA
COMDATA,SAVEDATA
TYPE=WRITE,
JCDADDR=MYDATA,
JCDLGTB=10,
JFILEID=SYSTEM,
JTYPEID=0101,
COND=NO,
STARTIO=NO,
NORESP=OK
Chapter 1.5.
REPLACE WITH MY DATA FOR WORKING
REQUEST ASYNCHRONOUS OUTPUT
OF COMMON DATA AREA,
LENGTH=10 BYTES,
TO SYSTEM LOG.
~DENTIFIER FOR JOURNAL RECORD)
REQUEST DEFERRED OUTPUT,
BUT RETAIN CONTROL IF ~UFFER FULL.
BRANCH ADDR FOR GOOD RESPONSE
*
*
*
*
*
*
*
HOUSEKEEPING:
MOVE DATA, THEN
RESTORE COMMON DATA.
REQUEST ASYNCHRONOUS OUTPUT
OF DATA,
LENGTH=10 BYTES,
TO SYSTEM LOG.
(IDENTIFIER FOR JOURNAL RECORD)
IF BUFFER FULL, WE'LL WAIT.
DEFER OUTPUT.
BRANCH ADDR FOR GOOD RESPONSE
*
*
*
*
*
*
*
Journal Control
(DFHJC Macro)
533
02 JCABAR PIC
S9~)
COMP.
NOTE DEFINE BASE LOCATOR FOR JCA.
01 DFHCSADS COpy DFHCSADS.
02 COMDATA PIC X(10).
NOTE COpy CSA SYMBOLIC DEFINITIONS.
NOTE DEFINE COMMON DATA AREA.
01 DFHTCADS COPY DFHTCADS.
02 SAVEDATA PIC X(10).
02 MYDATA PIC X(10).
NOTE COpy TCA SYMBOLIC DEFINITIONS.
NOTE SAVE AREA FOR COMMON DATA.
NOTE AREA FOR MY DATA.
01 DFHJCADS COpy DFHJCADS.
NOTE COpy JCA SYMBOLIC DEFINITIONS.
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
NOTE LOAD TCA BASE LOCATOR VALUE.
MOVE COMDATA TO SAVEDATA.
MOVE MYDATA TO COMDATA.
DFHJC TYPE=WRITE,
JCDADDR=COMDATA,
JCDLGTH=10,
JFILEID=SYSTEM,
JTYPEID=0101,
STARTIO=NO,
COND=(YES,R3TRY),
NORESP=OK
NOTE SAVE COMMON DATA.
NOTE REPLACE WITH MY DATA FOR WORKING.
REQUEST ASYNCHRONOUS OUTPUT
OF COMMON DATA AREA,
LENGTH=10 BYTES,
TO SYSTEM LOG.
(IDENTIFIER FOR JOURNAL RECORD)
REQUEST DEFERRED OUTPUT,
BUT RETAIN CONTROL IF BUFFER FULL.
BRANCH ADDR FOR GOOD RESPONSE
*
*
*
*
*
*
*
NOTE DO HOUSEKEEPING, THEN RETRY.
NOTE MOVE DATA, THEN.
NOTE RESTORE COMMON DATA.
REQUEST ASYNCHRONOUS OUTPUT
OF MY DATA,
LENGTH=10 BYTES,
TO SYSTEM LOG.
(IDENTIFIER FOR JOURNAL RECORD)
REQUEST DEFERRED OUTPUT,
BUT IF BUFFER FULL, WE CAN WAIT.
BRANCH ADDR FOR GOOD RESPONSE
*
*
*
*
*
*
*
OK.
RETRY.
MOVE COMDATA TO MYDATA.
MOVE SAVEDATA TO COMDATA.
DFHJC TYPE=WRITE,
JCDADDR=MYDATA,
JCDLGTH=10,
JFILEID=SYSTEM,
JTYPEID=0101,
STARTIO=NO,
COND=NO,
NORESP=OK
534
CICS/VS APRM(ML)
!Q.!:~:
%INCLUDE DFHCSADSj
DCL 01 DFHCSAWK BASED (CSACBAR)
02 FILL CHAR (512),
02 COMDATA CHAR (10);
I*COPY CSA SYMBOLIC DEFINITIONS*I
I*AND COHaON WORK AREA*I
%INCLUDE DFHTCADSj
02 SAVEDATA CHAR (10),
02 MYDATA CHAR (10),
I*COPY TCA SYMBOLIC DEFINITIONS*I
%INCLUDE DFHJCADS;
I*COPY JCA SYMBOLIC DEFINITIONS*I
SAVEDATA=COMDATA;
COMDATA=MYDATA;
I*SAVE COMMON DATA*I
I*REPLACE WITH MY DATA FOR WORKING*I
DFHJC TYPE=WRITE,
JCDADDR=COMDATA,
JCDLGTH= 10,
JFILEI D=SY STEM,
JTYPEID=0101,
STARTIO=NO,
COND=(YES,RETRY),
NORESP=OK
I*SAVE AREA FOR COMMON DATA*I
I*AREA FOR MY DATA*/
REQUEST ASYNCHRONOUS OUTPUT
OF COMMON DATA AREA,
LENGTH=10 BYTES,
TO SYSTEM LOG.
~DENTIFIER FOR JOURNAL RECORD)
REQUEST DEFERRED OUTPUT,
BUT RETAIN CONTROL IF BUFFER FULL.
BRANCH ADDR FOR GOOD RESPONSE
*
**
*
*
*
*
OK:
RETRY:
MYDATA=CO MDATA;
COMDATA=SAVEDATA;
DFBJC TYPE=WRITE,
JCDADDR=MYDATA,
JCDLGTH=10,
JFILEID=SYSTEM,
JTYPEID=0101,
STARTIO=NO,
COND=NO,
NORESP=OK
Chapter 7.5.
I*HOUSEKEEPING:*I
I*MOVE DATA, TBEN*I
I*RESTORE COM!ON DATA.*I
REQUEST ASYNCHRONOUS OUTPUT
OF MY DATA,
LENGTH=10 BYTES,
TO SYSTEM LOG.
(IDENTIFIER FOR JOURNAL RECORD)
REQUEST DEFERRED OUTPUT,
BUT IF BUFFER FULL, WE CAN WAIT.
BRANCH ADDR FOR GOOD RESPONSE
Journal Control (DFHJC Ha cro)
*
*
*
*
*
*
*
535
Wait for Output of a Journal Record (TYPE = WAIT)
The general format of the DFHJC macro instruction to wait for output of
a previously created journal record is as follows:
DFHJC
TYPE=WAIT
,JFILEID={nnISYSTEMIYES}
[ , STARTIO= {YES I NO} ]
[,NORESP=symbolic address]
[,IDERROR=symbolic address]
[,IOERROR=symbolic address]
(,NOTOPEN=symbolic address]
[,INVREQ=symbolic address]
This macro specifies that the requesting task is to be placed in a
wait state until the block containing a journal record has been written
as output (that is, the journal operation is to be synchronized with
continued execution of the task issuing the journal write request). If
the block containing the journal record has not been written, the
requesting task is placed in a" wait state until the write is completed.
The operand can be specified if the user has restored the event control
number, because JCAJFID is part of the event control number.
Before issuing a synchronizing request, the task must ensure that the
event control number (four bytes) corresponding to the journal record in
question is in field JCAECN of the JCA. An event control number is
returned in JCAECN after every successful journal output request. Since
the JCA is used for every journal request issued by the task (or by
CICS/VS on its behalf), the requesting program must save the event
control number immediately after an asynchronous output request if it is
to be used later. This is necessary because the particular event
control number may be overwritten during reuse of the JCA.
If the JCA is not reused between the output request and the
synchronize request, the requesting program need not save and restore
the event control number. It is the user's responsibility to determine
whether or not he needs to save and restore it.
If the requesting program has made a succession of successful
asynchronous output requests to the same journal data set, it is only
necessary to synchronize on the last of these requests to ensure that
all of the journal records have reached the external storage device.
This may be done either by issuing a stand-alone DFHJC TYPE=WAIT
request, or by making the last output request itself synchronous, a
DFHJC TYPE=PUT or TYPE=(WRITE,WAIT).
The following examples show a typical sequence of instructions to
request synchronization with the output of a journal record.
For Assembler language:
COpy
SAVEDECN DS
JDATA
DS
DFHTCADS
CL4
CL36
COpy TCA SYMBOLIC DEFINITIONS
SAVED EVENT CONTROL NUMBER
DATA TO WRITE TO JOURNAL
JCABAR
10
ASSIGN BASE REGISTER FOR JCA
536
EQU
CICS/VS APRM(ML)
COpy
DFHJCADS
DFftJC TYPE=WRITE,
JCDADDR=JDATA,
OK1
DS
MVC
DS
REQUEST ASYNCHRONOUS OUTPUT
OF DATA AT JDATA,
ETC.
NORESP=OK 1
BRANCH TO OK1 IF GOOD RESPONSE
OH
SAVEDECN,JCAECN
SAVE EVENT CONTROL NUMBER
HVC
JCAECN,SAVEDECN
DFHJC TYPE=HAIT,
NORESP=OK2
OK2
COPY JCA SYMBOLIC DEFINITIONS
*
*•
*
*
RESTORE EVENT CONTROL NUMBER,
AND SYNCHRONIZE WITH OUTPUT.
BRANCH TO OK2 IF GOOD RESPONSE
*
OH
02 JCAB!R PIC S9(8) COMP.
NOTE DEFINE BASE LOCATOR FOR JCA.
01 DFHTCADS COPY DFHTCADS.
02 SAVEDECN PIC X(q).
02 JDATA PIC X(36) •
NOTE COpy TCA SYMBOLIC DEFINITIONS.
NOTE SAVED EVENT CONTROL NUMBER.
NOTE DATA TO WRITE TO JOURNAL.
01 DFHJCADS COpy DFHJCADS.
NOTE COpy JCA SYMBOLIC DEFINITIONS.
PROCEDURE DIVISION.
MOVE CSACDTA TO TCACBAR.
NOTE LOAD TCA BASE LOCATOR VALUE.
DFHJC TIPE=WRITE,
JCDADDR=JDATA,
NORESP=OK1
OK1.
KOVE JCAECN TO SAVEDECN.
MOVE SAVEDECN TO JCAECN.
Chapter 7.5.
REQUEST ASYNCHRONOUS OUTPUT
OF DATA AT JDATA,
ETC.
BRANCH TO OK1 IF GOOD RESPONSE
*
*
*
*
*
NOTE SAVE EVENT CONTROL NUMBER.
NOTE RESTORE EVENT CONTROL NUMBER.
Journal Control (DFHJC Macro)
537
DFHJC TY PB=W AIT ,
NORESP=OK2
AND SYNCHRONIZE WITH OUTPUT.
BRANCH TO OK2 IF GOOD RESPONSE.
*
OK2.
For PL/I:
%INCLUDE DFHTCADS;
02 SAVEDECN CHAR (4),
02 JDATA CHAR (36);
/*COPY TCA SY~BOLIC DEFINITIONS*/
/*SAVED EVENT CONTROL NO~BER*/
/*DATA TO WRITE TO JOURNAL*/
%INCLUDE DFHJCADS;
/*COPY JCA SYMBOLIC DEFINITIONS*/
DFHJC TYPE=WRITE,
JCDADDR=JDATA,
NORESP=OK 1
REQUEST ASYNCHRONOUS OUTPUT
OF DATA AT JDATA,
ETC.
BRANCH TO OKl IF GOOD RESPONSE
OK1:
SAVEDECN=JCAECN;
/*SAVE EVENT CONTROL NUMBER*/
JCAECN=SAVEDECN;
DFHJC TYPE=WAIT,
NORESP=OK2
/*RESTORE EVENT CONTROL NUMBER,*/
AND SYNCHRONIZE WITH OUTPUT.
BRANCH TO OK2 IF GOOD RESPONSE
OK2:
538
CICS/VS APRM (ML)
*
*
*
*
*
*
Test Response to a Request for Journal Services (TYPE=CHECK)
The general format of the DFHJC macro instruction to check the CICS/VS
response to a request for journal services is as follows:
r------r-------·r-----------------------------------------------------------,
DFHJC
TYPE=CHECK
[,NORESP=symbolic address]
[ ,IDERROR=symoolic address]
[,LERROR=symbolic address]
[,IOERROR=symbolic address]
[,NOTOPEN=symbolic address]
[,INVREQ=symbolic address]
[,STATERR=symbolic address]
Journal Control Response Codes
To test a response code the application programmer must know the actual
settings of the response code, which is returned at JCAJCRC. The
possible response codes and the requests, conditions, and keyword
operands to which they correspond are identified in Figure 7.5-1.
Chapter 7.5.
Journal Control (DFHJC Macro)
539
Journal Requestl
by DFHJC Macro I
Instruction
I
Condition
I Response codes in JCAJCRC
I
IAssembler I COBOL
PL/I
PUT,WRITE,WAIT,
CHECK
NORESP
(Normal response)
X'OO'
LOW-VALUES
(JCARCNR)
00000000
PUT,WRITE,WAIT,
CHECK
IDERROR
(Journal identifica tion error)
X'Ol'
12-1-9
(JCARCIDE)
00000001
PUT,WRITE,CHECK
LERROR
(Journal record
length error)
X'06'
12-6-9
(JCARCLE)
00000110
PUT,WAIT,CHECK
IOERROR
(Output I/O error)
X '07'
12-7-9
(JCARCIOE)
00000111
PUT,WRITE,WAIT,
CHECK
NOTOPEN
(Journal not open)
X '05'
12-5-9
(JCARCNOE)
00000101
PUT,WRITE,WAIT,
CHECK
INVREQ
(Invalid request)
X'02'
12-2-9
(JCARCIRE)
00000010
PUT,WRITE,CHECK
STATERR
(Request incompat-I
ible with current
status of journal
X'03'
12-3-9
(JCARCSE)
00000011
I
I Note:
I The names enclosed in parentheses in the COBOL column indicate
I the condition names generated by CICS/VS. These names may be
IL______________
used in testing
for the conditions in a COBOL program.
.__________________________________________________________
Figure 7.5-1.
~
Journal Control Response Codes
If the application programmer does not provide for checking a
particular response code and the corresponding condition occurs, program
execution resumes at the instruction immediately following the DFHJC
macro instruction which requested the journal service.
540
CICS/VS APRM(ML)
Operands of DFHJC Macro
COND=
specifies that control is to be returned to the application
program if the request cannot be satisfied immediately because
insufficient journal buffer space is available. If control is
to be returned, the point of return must be specified as a
second parameter of this operand.
(YES,symnolic address)
indicates that control is to be returned to the location
represented by symbolic address in the application program
if the request cannot be satisfied immediately.
No journal
record will have been created for the request.
NO
indicates that the contents of the current buffer are to be
written out and the requesting task placed in a wait state
until its request has been satisfied (by the building of a
record in buffer space freed by the write operation).
IDERROR=symbolic address
is the address to which control is to be returned if the
specified journal file identification does not exist in the
journal control table (JCT).
INVREQ=symbolic address
is the address to whiCh control is to be returned if the TYPE
operand is invalid.
IOERROR=symbolic address
is the address to which control is to be returned if the
physical output of a journal record was not accomplished
because of an unrecoverable I/O error. This operand is
applicable only to requests that may cause a Hait for
completion of output, that is, to TYPE=PUT, TYPE=(WRITE,WAIT),
or TYPE=WAIT.
JCDADDR
is the address of the user data to be built into the journal
record.
symbolic address
is the symbolic address of the user data.
YES
indicates that the address of the user data has been placed
in JCAADATA prior to issuing this macro instruction.
JCDLG'rH=
is the length of the user data to be built into the journal
record.
decimal value
is a decimal numeral in the range from 1 to 32000 ~r a
lower maximum, because of the journal buffer size),
indicating the length, in bytes, of the user data.
Chapter 7.5.
Journal Control (DFBJC Macro)
541
YES
indicates that the length, in binary, of the user data has
been placed in JCALDATA prior to issuing this macro
instruction.
JFILEID=
is the one-byte identification of the journal file (data set)
referred to in this journal operation.
nn
is a decimal value in the range from 2 through 99 to be
taken as the journal file identification.
SYSTE"
indicates that the system log data set is the journal for
this operation.
YES
indicates that the journal file identification has been
placed in JCAJFID prior to issuing this macro instruction.
JTYPEID=
is an identifier to be placed in the journal record to identify
its origin.
nnnn
is a one- to four-character hexadecimal value to be taken
as the identifier for the journal record; if fewer than
four characters are specified, padding with zeros occurs on
the right.
YES
indicates that the journal record identification has been
placed in JCAJRTID prior to issuing this macro instruction.
LERROR=symbolic address
is the address to which control is to be returned if the
computed length for the journal record exceeds the total buffer
space allocated for the journal data set, as specified in the
JCT entry for the data set.
NORESP=symbolic address
is the address to which control is to be returned if the
requested operation was performed successfully.
NOTOPEN=symbolic address
is the address to which control is to be returned if the
journal request cannot be satisfied because the specified
journal data set has been disabled and is not available.
PFXADDR=
is the address of user prefix data to be included in the
journal record.
symbolic address
is the symbolic address of the user prefix data.
542
CICS/VS APR"
~L)
YES
indicates that the address of the user prefix data has been
placed in JCAAPRFX prior to issuing this macro instruction.
PFXLGTH=
is the length of the user prefix data to be included in the
journal record.
decimal value
is a decimal numeral in the range from 1 to 32000 (or a
lower maximum, because of the journal buffer size),
indicating the length, in bytes, of the user prefix data.
YES
indicates that the length, in binary, of the user prefix
data has been placed in JCALPRFX prior to issuing this
macro instruction.
STARTIO=
specifies whether output of the journal record is to be
initiated immediately.
YES
indicates that output of the journal record is to be
initiated.
NO
indicates that no output operation is required at this
time.
The default value is YES if a synchronizing request is
issued, namely PUT, (WRITE,WAIT), or WAIT. The default is
NO for a simple WRITE request. If STARTIO=NO is specified
with a synchronizing request the maximum delay allowed
before output is initiated is one second.
srATERR=
is the address to which control is to be passed if the current
status of the journal precludes the requested operation. For
example, a status error will occur if a DFHJC TYPE=PUT macro is
issued for a journal file that has been closed and then opened
for input. This is because closing the file gave exclusive
control to the requesting task but opening for input has not
released exclusive control.
(For further details, refer to the
CI£§L!~~y~tem P~gra~g~§~uig~.)
Chapter 7.5.
Journal Control (DFHJC Macro)
543
Chapter 7.6. Recovery IRestart (SYNC Point) Control
(DFHSP Macro)
Sync point management works in conJunction with other CICS/VS
components, such as transient data management and file management, to
provide the user with facilities needed for an emergency restart after
an abnormal termination of CICS/VS. In an emergency restart, changes
made in protected resources (for example, in transient data
intrapartition queues) can be backed out for tasks that were "in flight"
at the time of failure. This backout is based upon information about
the tasks recorded on a system log during execution.
Each synchronization point in an application program marks the
completion of a logical unit of work. By definition, a logical unit of
work (LUW) is an application programmer-defined unit of work that
performs a complete processing function. One task may perform one LUi,
or several LUWs, generally delimited by conversational terminal
operations (a terminal write, followed by a terminal read).
Specify a Synchronization Point (TYPE=USER)
The format of the DFHSP macro that specifies completion of a logical
unit of work, or sync point, is as follows:
~-----r-------~-----------------------------------------------------------'
I
I DFHSP
I
TYPE=USER
A sync point is always requested by CICS/VS at termination of a task.
The completion of a logical unit of work indicates to CICS/VS that:
•
All updates or modifications performed by the task are logically
complete, and should not be backed out if a system failure occurs.
•
Functions requested prior to the synchronization point, but
deferred until the end of the logical unit of work, are to be
processed, even if a subsequent system failure occurs. An example
of such an operation is a purge of a transient data intrapartition
queue, as requested by the application program.
•
All resources protected aatomatically on behalf of the task up to
this point are to be released. An example of such a resource may
be a transient data intrapartition destination that is logically
associated with the task or a resource previously enqueued by the
user.
•
All resources previously enqueued by the user are dequeued.
The location of a sync point for a task on the system log data set,
relative to other logged activity for that task, determines the extent
to which CICSjVS (or user programs) may need to provide transaction
backout. Generally, sync points are not needed for short-duration
tasks.
Chapter 7.6.
Recovery/Restart Control (DFHSP Kacro)
545
Sync points are also used by C1CS/VS to delimit the extent to which
user data set modifications may need to be backed out for a task.
During emergency restart, C1CS/VS collects all user data set
modifications for tasks that were engaged in a LUW at the time of
uncontrolled shutdown and copies them in a restart data set. The
modifications can then be read by the C1CS/VS transaction backout
program or by user-written programs executed during the postinitialization phase of restart.
Through these facilities, sync point management not only permits
emergency restart but also provides the means by which the activity
required for such restart can be controlled by the user. The functions
performed by other C1CS/VS programs involved in sync point/uncontrolled
shutdown/emergency restart activities are explained in greater detail in
the C1CS/VS~stem Programmer's Reference Manual and £1CS~
system/Application Design Guide.
A sync point request for a task that is scheduled to use a OL/1
resource implies the release of that resource. This means that if,
after issuing a OFHSP TYPE=USER macro instruction, access to a OL/1 data
base is required, the desired PSB must be rescheduled through the DFHFC
TYPE=(OL/I,PSB) macro ~nstruction. The previous position of that data
base has been lost. conversely, when a OL/1 termination instruction is
issued, CICS/VS will issue a DFHSP TYPE=USER instruction on behalf of
the task that is releasing a PSB.
Any BMS logical message that has beeu started but not completed when
a DFHSP macro is issued is forced to completion by means of an implied
DFHBMS TYPE=PAGEOUT instruction.
!ote: If sync points are to be issued in a transaction that is eligible
for transaction restart, the application programmer must seek advice
from the systems programmer.
I Backout Recoverable Resources (TYPE=ROLLBACK) (Assembler Language Only)
The format of the DFHSP macro that restores recoverable resources is as
follows:
~-----~-------r------------------------------------------------------------'
I
I
IL______
I
DFHSP I TYPE=ROLLBACK
~
_______ III_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
~
This macro causes all changes to recoverable resources made by the
task since its last sync point to be backed out so that those resources
are then in the state that they were at the time the sync point was
taken.
After the recoverable resources have been restored, a sync point is
taken and control is passed to the user.
546
CICS/VS APRM(ML)
Part 8. Appendixes
547
Appendix A. Example of a CICS/VS Application Program
This appendix contains an executable application program that performs a
limited message switching function; that is, data collection, message
entry, and message retrieval.
The program is shown in each of the
languages supported under CICSjVS: Assembler language, COBOL, and PL/I.
***********************************************************************
*
ASS E M B L E R E X AMP L E
PRO B L E M
*
*
***********************************************************************
*
TITLE 'CICS/VS MESSAGE SWITCHING PROGRAM EXAMPLE'
DFHCOVER
**********************************************************************~
** * *
A P P L I CAT ION
PRO G RAM
* ** *
***********************************************************************
* * *
DUM M Y
SEC T ION S
* * *
***********************************************************************
TWA'rSRL
TWATDDI
TWAREAI
TWAQEMCI
Tc'rTEAR
TIOABAR
TIOADATA
T IOATID
TIOARRI
TIOARAIl
TIOADID
TIOASSF
TIOAMBA
TIOARAI2
COpy
EJECT
COpy
DS
DS
DS
DS
DS
EJECT
EQU
COpy
EQU
COpy
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DFHCSADS
DFHTCADS
H
H
CL4
CL4
C
11
DFHTCTTE
10
DFHTIOA
OCLaO
CL4
C
OC16
OCL3
CL4
OCL4
C
OC
CL3
COPY COMMON SYSTEM AREa DSECT
LISTING CONTROL CARD - EJECT
COPY TASK CONTROL AREA DSECT
TEMPORARY STORAGE RECORD LENGTH
DESTINATION IDENTIFICATION
RETRIEVE ALL INDICATOR
QUEUE EMPTY MESSAGE CONTROL IND
LISTING CONTROL CARD - EJECT
TERM CONT TABLE TERM ENT ADR RG
COPY TERM CONT TABLE TERM ENTRY
TERM I/O AREA BASE AOOR REG
COpy TERMINAL I/O AREA OSECT
DATA AREA
TRANSACTION IDENTIFICATION
DELIMITER
RESUME REQUEST IDENTIFICATION
RETRIEVE ALL INDICATOR 1
DESTINATION IDENTIFICATION
SUSPEND STORAGE FACILITY IDENT
DELIMITER
TER~INAL MESSAGE BEGINNING ADDR
RETRIEVE ALL INDICATOR 2
***********************************************************************
TDIABAR
SPACE a
EQU
9
COpy DFHTDIA
EJECT
App&ndix A.
LISTING CONTROL CARD - SPACE a
TRANS DATA IN AREA BASE ADDR RG
COPY TRANS DATA INPUT AREA
LISTING CONTROL CARD - EJECT
Example of a CICS/VS Application Program
549
***********************************************************************
* * * *
A P P L I CAT ION
PRO G RAM
* * * *
***********************************************************************
CICSATP CSECT
CONTROL SECTION - APPL TEST PGM
USING *,3
USING REGISTER 3 AT *
LOAD PROGRAM BASE REGISTER
LR
03,14
B
ATPIPIN
GO TO INIT PROG INSTR ENTRY
***********************************************************************
EJECT
LISTING CONTROL CARD - EJECT
***********************************************************************
* * *
DEC L A RAT I V E S
* * *
***********************************************************************
MCPDIEM DC
Y~CPDEML-4)
TERMINAL MESSAGE LENGTH
DC
H'O'
NEW LINE SYMBOL CONSTANT
DC
X'lS'
DC
08X'17'
HARDCOPY TERM IDLE CHARACTERS
DC
C'DESTINATION IDENTIFICATION ERROR - PLEASE RESUBMIT'
NEW LINE SYMBOL CONSTANT
DC
X'lS'
TERMINAL MESSAGE TOTAL LENGTH
MCPDEML EQU
*-MCPDIEM
***********************************************************************
***********************************************************************
*
D A T A
COL L E C T ION
*
***********************************************************************
DCPDCAML DC
DATA COLL ACKNOWLEDGMENT LEN
Y ~'DCPDCAMD)
DC
H'O'
C' DATA COLLECTION HAS BEEN REQUESTED AND IS ABOUT TO BE*
DCPDCAMD DC
GIN
DATA COLLECTION ACKNOWLEDGMENT
DCPEODML DC
Y(L'DCPEODMD)
END OF DATA MESSAGE LENGTH
DC
H'O'
DCPEODMD DC
C' THE DATA HAS BEEN RECEIVED AND DISPATCHED TO THE DESI*
GNATED DESTINATION
END OF DATA MESSAGE
DCPEOVML DC
Y(L'DCPEOVMD)
DC
HIO'
DCPEOVMD DC
CI END OF VOLUME REQUEST HAS BEEN RECEIVED
DCPSRAM DC
Y{DCPSRAL-4)
TERMINAL MESSAGE LENGTH
DC
alo'
NEW LINE SYMBOL CONSTANT
DC
X'lS'
HARD COPY TERM IDLE CHARACTERS
DC
08X I 17 1
DC
C'DATA COLLECTION SUSPENSION HAS BEEN REQUESTED I
NEW LINE SYMBOL CONSTANT
DC
X'ls'
TERMINAL MESSAGE TOTAL LENGTH
DCPSRAL EQU
*-DCPSRAM
DCPRRAM DC
Y{DCPRRAL-4)
TERMINAL MESSAGE LENGTH
DC
H'O'
DC
X'ls'
NEW LINE SYMBOL CONSTANT
DC
OSX'17'
HARDCOPY TERM IDLE CHARACTERS
DC
C'DATA COLLECTION RESUMPTION HAS BEEN REQUESTED AND IS I
DC
C'ABOUT TO BEGIN'
DC
X'ls'
NEW LINE SYMBOL CONSTANT
DCPRRAL EQU
*-DCPRRAM
TERMINAL MESSAGE TOTAL LENGTH
***********************************************************************
SPACE 4
LISTING CONTROL CARD - SPACE 4
***********************************************************************
*
M E S SAG E
E N TRY
*
***********************************************************************
MEPMEAML DC
Y(LIMEPMEAMD)
MSG ENTRY ACKNOWLEDGMENT LNGTH
DC
HIO'
MEPMEAMD DC
C' YOUR MESSAGE HAS BEEN RECEIVED AND DISPATCHED TO THE *
DESIGNATED DESTINATION
• MESSAGE ENTRY ACKNOWLEDGMENT
**~********************************************************************
SP'C~ 4
LISTING CONTROL CARD - SPACE 4
***********************************************************************
*
M E S SAG E R E T R I E V A L
*
***************~*******************************************************
MRPNMMM
550
DC
DC
Y ~RPNMML-4)
HIO'
CICS/VS
~PRM(ML)
TERMINAL MESSAGE LENGTH
MRPNIH1L
MRPNMQM
MRPNQML
NET,~ LINE SYMBOL CONS'rANT
qARDCOPY TERM IDLE CHARACTERS
X '15'
OSl'17'
DC
DC
DC
CITHERE ARE
DC
C"~SSAGZS
DC
EQU
DC
DC
DC
DC
DC
DC
EQU
X'15 1
*-MRPNMMM
Y(MRPNQML-4)
~O
~ORE
QUEJ~D
I
¥OR fHIS DESTINATION'
NEW LINE SYMBOL CONSTANT
TER~INAL MESSAGE TOTAL LENGTH
TERMINAL MESSAGE LENGTH
H '0 '
NEW LINE SYMBOL CONSTANT
HARDCOPY TERM IDLE CHARACTERS
C'THERE ARE NO MESSAGES QUEUED FOR THIS DESTINATION'
NEW LINE SYMBOL CONSTANT
X '15 '
TERMINAL MESSAGE TOTAL LENGTH
*-MRPNMQI1
X '15
'
OSX '17'
***********************************************************************
EJECT
LISTING CONTROL CARD - EJECT
***********************************************************************
* * *
IMP ERA T I V E S
*
* *
***********************************************************************
* *
* *
***********************************************************************
ATPIPIN
DS
DC
DS
L
L
CLC
BE
CLC
BE
CLC
BE
DPHPC
OD
STORAGE ALIGNMENT - DOUBLEWORD
CL32'MESSAGE CONTROL PROGRAM'
OD
INITIAL PROGRAM INSTRUCTION ENT'
TCTTEAR,TCAFCAAA
LOAD TERM CONT AREA ADDR REG
TIOABAR,TCTTEDA
LOAD TERM I/O AREA ADDR REG
=C'DSDC',TIOATID
COMPARE TRANSACTION IDENT
ALPDCPN
GO TO DATA COLLECTION PROG IF =
=CIDSME',TIOATID
COMPARE TRANSACTION IDENT
ALPMEPN
GO TO MESSAGE ENTRY PROG IF =
=C'DSMR',TIOATID
COMPARE TRANSACTION IDENT
ALPMRPN
GO TO MESSAGE RETRIEVAL PROG
TYPE=ABEND,
*
ABCODE=XAPT
EJECT
LISTING CONTROL CARD - EJECT
***********************************************************************
* *
* *
A P P L I CAT ION
LOG I C
* *
* *
***********************************************************************
D A T A
COL
L
E C T ION
***********************************************************************
DC
CL32'DATA COLLECTION PROGRAM'
***********************************************************************
ALPDCPN
DCPFEOV
DS
CLC
BNE
MVC
MVC
MVC
DFHTS
OH
DATA COLLECTION PROGRAM ENTRY
=C'RESUME',TIOARRI
COMPARE FOR RESUME REQUEST
DCPRRBN
GO TO RESUME REQUEST BYPASS
TIOATDL (DCPRRAL),DCPRRAM MOVE TERMINAL MESSAGE TO OUTPUT
TCATSDI(4) ,=C'DSDC'
MOVE TEMP STRG DATA IDENT
TCATSDI+4(4) ,TCTTETI
MOVE TEMP STRG DATA IDENT
TYPE=GET,
*
TSDADDR=TWATSRL,
*
NORESP=DCPRRNR,
*
RELEASE=YES
DFHPC TYPE=ABEND,
*
ABCODE=XDCR
EQU
*
FORCED END OF VOLUME ROUTINE
DFHTD TYPE=FEOV
ISSUE TRANSIENT DATA MACRO
MVC
TIOATDL«4+L'DCPEOVMD» ,DCPEOVML
DFHTC TYPE= (WRITE)
B
RETURN
***********************************************************************
DCPRRBN
EQU
MVC
MVC
CLC
BE
MVC
*
RESUME REQUEST BYPASS ENTRY
TWATDDI,TIOADID
MOVE DESTINATION IDENTIFICATION
TCATDDI,TWATDDI
TIOAMBA(4),=C'FEOV'
CHECK FOR FORCED END OF VOL REQ
DCPFEOV
BRANCH TO END OF VOLUME ROUTINE
TIOATDL«(4+LIDCPDCAMD» ,DCPDCAML
Appendix A.
Example of a CICSjVS Application Program
551
DCPRRNR
*
EQU
DFHTC rYPE=(WRITE)
DFHTC TYPE=(READ)
RESOME REQUEST NORMAL RESPONSE
***********************************************************************
DCPTEWN
DCPSRMB
DCPSRAB
DCPSRNR
DCPSRBN
SPACE
DS
DFHTC
L
CLC
BE
CLC
BE
CLC
BNE
HVC
MVC
MVC
CLC
BNE
DFHTS
4
OH
TYPE=(WAIT)
TIOABAR,TCTTEDA
=C'DUMP',TIOATID
DCPDPTS
=C'EOD',TIOADBA
DCPEXIT
=C'SUSPEND',TIOADBA
DCPSRBN
TWATSRL,=H'32 1
TCATSDI ~),=C'DSDCt
TCATSDI+4(4) ,TCTTETI
=CtMAIN',TIOASSF
DCPSRMB
TYPE=PUT,
TSDADDR=TWATSRL,
STORFAC=MAIN
DCPSRAB
B
EQU
DFHTS TYPE=PUT,
TSDADDR=TWATSRL,
STORFAC=AUXILIARY
EQU
*
DPHTS rYPE=CHECK,
NORESP=DCPSRNR
DFHPC TYPE=ABEND,
ABCODE=XDCS
EQU
*
TIOATDL (DCPSRAL),DCPSRAM
HVC
DFHTC TYPE=(WRITE)
B
RETURN
EQU
HVC
TCATDDI,rWATDDI
XC
TCTTEDA,TCTTEDA
DFHTC TYPE=(RE~D)
14,TIOATDL
LH
LA
lij,4(O,14)
STH
14,TIOATDL
DFHTD TYPE=PUT,
TDADDR=TIOATDL,
NORESP=DCPNRCN,
IDERROR=DCPDIEN
DFHPC TYPE=ABEND,
ABCODE=XDCP
*
*
LISTING CONTROL CARD - SPACE 4
TERMINAL EVENT WAIT ENTRY
LOAD TERM I/O AREA ADDR REG
GO TO DUMP TRANSACTION STORAGE
COMP DATA FOR EOD INDICATION
GO TO EXIT IF EQUAL
CO~PARE FOR SUSPEND REQUEST
GO TO SUSPEND REQUEST BYPASS
MOVE TEMP STRG RECORD LENGTH
MOVE TEMP STRG DATA IDENT
MOVE TEMP STRG DATA IDENT
GO TO MAIN STRG FACILITY BYPASS
*
*
GO TO AUX STRG FACILITY BYPASS
MAIN STORAGE FACILITY BYPASS
*
*
AUX STORAGE FACILITY BYPASS
*
*
SUSPEND REQUEST NORMAL RESPONSE
MOVE TERMINAL MESSAGE TO OUTPUT
GO TO RETURN ENTRY
SUSPEND REQUEST BYPASS ENTRY
MOVE DESTINATION IDENTIFICATION
RESET TERMINAL DATA ADDRESS
LOAD TERMINAL DATA LENGTH
INCREMENT TERMINAL DATA LENGTH
STORE TERMINAL DATA LENGTH
*
*
*
*
***********************************************************************
DCPNRCN
D~
OH
ST
TIOABAR,TCASCSA
DFHSC TYPE=FREEMAIN
B
DCPTEWN
NORMAL RESP CODE ENTRY ADDRESS
STORE TERM I/O AREA ADDRESS
GO TO TERM EVENT WAIT ENTRY
***********************************************************************
SPACE 4
LISTING CONTROL CARD -
SPACE 4
***********************************************************************
DCPDPTS
EQU
DFHDC
XC
DFHTC
B
*
DUMP TRANSACTION STOR ROUTINE
TYPE=TRANSACTION,DMPCODE=TRAN
TCTTEDA,TCTTEDA
CLEAR TERMINAL DAT~ AREA ADDR
TYPE=(READ)
DCPNRCN
RETURN TO MAINSTREAM LOGIC
************.**********************************************************
SPACE 4
***********************************************************************
552
CICS/VS APRM(ML)
DCPEXIT
*
EQU
EXIT
MVC
TIOATDL (~+L'DCPEODMD»,DCPEODML
DFHTC TYPE=(WRITE)
B
RETURN
GO TO RETURN ENTRY
***********************************************************************
EJECT
LISTING CONTROL CARD -
EJECT
***********************************************************************
*
M E S SAG E
*
E N TRY
***********************************************************************
DC
CL32'MESSAGE ENTRY PROGRAM'
***********************************************************************
ALPMEPN
DS
MVC
MVC
LH
LA
STH
DFHTD
OH
TCATDDI,TIOADID
TIOATID,TCTTETI
14,TIOATDL
14,~(0,14)
14,TIOATDL
TYPE=PUT,
TDADDR=TIOATDL,
NORESP=MEPNRCN,
IDERROR=MEPDIEN
DFHPC TYPE=ABEND,
ABCODE=XMEP
MESSAGE ENTRY PROGRAM ENTRY
MOVE DESTINATION IDENTIFICATION
MOVE SOURCE IDENTIFICATION
LOAD TERMINAL DATA LENGTH
INCREMENT TERMINAL DATA LENGTH
STORE TERMINAL DATA LENGTH
*
*
*
*
*****************~*****************************************************
KEPNRCN
DS
MVC
DFHTC
B
OR
NORMAL RESP CODE ENTRY ADDRESS
TIOATDL«4+L'MEPMEAMD»,MEPMEAML
TYPE= ~RITE)
RETURN
GO TO RETURN ENTRY
***********************************************************************
EJECT
LISTING CONTROL CARD EJECT
***********************************************************************
*
*
M E S SAG E R E T R I E V A L
***********************************************************************
DC
CL32'MESSAGE RETRIEVAL PROGRAM'
***********************************************************************
SPACE 4
LISTING CONTROL CARD -
SPACE 4
***********************************************************************
ALPMRPN
MRPAI1B
MRPDEBN
DS
MVC
MVC
CLC
BNE
BVC
B
DS
CLC
BE
MVC
DS
OH
TWAREAI,TIOARAI2
TWATDDI,TCTTETI
=C'ALL',TIOARAI1
MRPAI1B
TWAREAI,TIOARAI1
MRPDEBN
OH
=CL4'
',TIOADID
MRPDEBN
TWATDDI,TIOADID
OH
MESSAGE RETRIEVAL PROGRAM ENTRY
MOVE RETRIEVE ALL INDICATOR
MOVE DESTINATION IDENTIFICATION
COMPARE ALL INDICATOR FOR ALL
MOVE RETRIEVE ALL INDICATOR
ALL INDICATOR 1 BYPASS
COMPARE DEST IDENT TO BLANKS
GO TO DEST ID = BL IF EQUAL
MOVE DESTINATION IDENTIFICATION
DESTINATION IDENT EQUALS BLANKS
********.**************************************~***********************
SPACE 4
LISTING CONTROL CARD -
SPACE 4
******************************************~****************************
MRPGTDN
DS
OH
MVC
TCATDDI,TWATDDI
DFHTD TYPE=GET,
NORESP=MRPNRCN,
QUEZERO=MRPQERN,
IDERROR=MRPDIEN
DFHPC TYPE=ABEND,
ABCODE=XMRP
GET TRANSIENT DATA ENTRY
MOVE DESTINATION IDENTIFICATION
*
*
*
*
***********************************************************************
SPACE 2
LISTING CONTROL CARD -
SPACE 2
***********************************************************************
MRPNRCN
DS
L
OH
TDIABAR,TC~TDAA
Appendix A.
NORMAL RESP CODE ENTRY ADDRESS
LOAD TRANS DATA AREA ADDRESS
Example of a CICSjVS Application Program
553
MRPMTDI
DFHTC TYPE= (WAIT)
MRPMTDI+1 (1) ,TDIAIRL+1
MVC
TIOATDL (0) ,TDIAIRL
MVC
LH
14,TIOATDL
14,=H'4 1
SH
STH
14,TIOATDL
DFHTC TYPE=(WRITE,
SAVE)
=CL3'ALLI,TWAREAI
CLC
BNE
RETURN
MVI
TWAQEMCI,XIFF'
MRPGTDN
B
MOVE DATA LENGTH TO MOVE INSTR
MOVE TRANS DATA TO TERM AREA
LOAD TERMINAL DATA LENGTH
SUBTRACT 4 FROM LENGTH
STORE TERMINAL DATA LENGTH
*
COMPARE RETRIEVE ALL IND TO ALL
GO TO RETURN ENTRY IF NOT EQUAL
MOVE MESSAGE CONTROL INDICATOR
GO TO GET TRANSIENT DATA ENTRY
***********************************************************************
SPACE 4
LISTING CONTROL CARD -
SPACE 4
***********************************************************************
MRPQERN
DS
CLI
BE
MVC
B
MRPNMQMB DS
DFHTC
MVC
OH
TWAQEMCI,X'FF'
MRPNMQMB
TIOATDL(MRPNQML),MRPNMQM
MRPWRCS
OH
TYPE=(WAIT)
TIOATDL(MRPNMML),MRPNMHM
DESTINATION QUEUE EMPTY ENTRY
COMPARE MESSAGE CONTROL IND
GO TO 80 MSG QUEUED MSG BYPASS
MOVE TERMINAL MESSAGE TO OUTPUT
GO TO WRITE & RETURN TO C S
NO MESSAGES QUEUED MSG BYPASS
MOVE NO MORE MESSAGE TO T 0 A
***********************************************************************
MRPWRCS
DS
OH
DFHTC TYPE=(WRITE)
B
RETURN
WRITE AND RETURN TO CONT SYS
GO TO RETURN ENTRY
***********************************************************************
EJECT
LISTING CONTROL CARD - EJECT
***********************************************************************
************************************************************************
*
**
DCPDIEN
HEPDIEN
MRPDIEN
DS
ST
DS
DS
MVC
DFHTC
OH
TIOABAR,TCTTEDA
OB
OB
TIOATDL(MCPDEML),MCPDIEM
TYPE= (WRITE)
DESTINATION IDENT ERROR ENTRY
STORE TERM 1/0 AREA ADDRESS
DESTINATION IDENT ERROR ENTRY
DESTINATION IDENT ERROR ENTRY
MOVE TERMINAL MESSAGE TO OUTPUT
***********************************************************************
RETURN
SPACE 4
DS
OH
DFHPC TYPE=RETURN
LISTING CONTROL CARD - SPACE 4
RETURN TO CONTROL SYSTEM
***********************************************************************
LTORG
*
LITERAL ORIGIN AT
CICSATP
END OF ASSEMBLY -
*
***********************************************************************
END
554
CICS/VS APRM(ML)
APPL TEST PGM
***********************************************************************
COB 0 L E X A H P L E
PRO B L E M
***********************************************************************
ID DIVISION.
PROGRAM-ID.
CICSATP.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
*77
77
77
77
DCPDCAML
DCPDCAMD
PIC 99
PIC X(58)
, BEEN REQUESTED AND IS
DCPEODML
PIC 99
DCPEODMD
PIC X(73)
'ECEIVED AND DISPATCHED
,
77
77
77
77
77
*01
MELMEAML
MEPMBAMD
.
C0I1P
VALUE 58.
, DATA COLLECTION HAS
VALUE
ABOUT TO BEGIN '.
COMP
VALUE 73.
VALUE
• THE DATA HAS BEEN R
TO THE DESIGNATED DESTINATION
PIC 99
COMP
VALUE 77.
PIC X(77)
VALUE
'YOUR MESSAGE HAS BEE
'N RECEIVED AND DISPATCHED TO THE DESIGNATED DESTINAT
'ION
PIC 99
MRPNMML
COliP
VALUE 68.
PIC 99
COliP
VALUE 63.
MRPNQML
PIC 99
COMP
VALUE 64.
MCPDEHL
MESSG1.
PIC 99
COMP
VALUE 60.
03 MCPDIEli
PIC 99
VALUE ZERO.
03 FILLER
COMP
VALUE
DESTINAT ION
03 MESSAGE1
PIC X (60)
, IDENTIFICATION ERROR - PLEASE RESUBMIT
,.
*01
*01
MESSG2.
03 MRPNHMM
PIC 99
PIC ~9
03 FILLER
03 11ESSAGE2
PIC X (64)
'0 MORE MESSAGES QUEUED
COliP
VALUE 64.
VALUE ZERO.
CaMP
VALUE
THERE ARE N
FOR THIS DESTINATION'
MESSG3.
03 MRPNMQM
PIC 99
03 FILLER
PIC 99
03 MESSAGE3
PIC X(59)
'0 MORE MESSAGES QUEUED
CaMP
VALUE 59.
CaMP
VALUE ZERO.
VALUE
THERE ARE N
FOR THIS DESTINATION '
*LINKAGE
*
01
* 01
*01
*01
*01
SECTION.
DFHBLLDS COpy DFHBLLDS.
PIC S9 (8)
03 TCTTEAR
03 TIOABAR
PIC S9 (8)
PIC S9 (8)
03 TDIABAR
CaMP.
COHP.
CaMP.
DFHCSADS COpy DFHCSADS.
DFHTCADS COPY DFHTCADS.
PIC X (4) •
03 TWATDDI
03 TWAREAI
PIC X (4) •
PIC S9
03 TWAQEMCI
COMP.
DFHTCTTE COpy DFHTCTTE.
DFHTIOA COpy DFBTIOA.
03 TIOADATA
PIC X (80) •
03 FILLER
REDEFINES TIOADATA.
05 EODTEST
PIC X(3).
05 FILLER
PIC X (77) •
03 FILLER
REDEFINES TIOADATA.
Appendix A.
Example of a CICS/VS Application Program
555
05
05
05
05
05
05
05
*01
TIOATID
PIC X(4).
FILLER
PIC X.
TIOADID
PIC X(4).
FILLER
REDEFINES TIOADID.
07 TIOARAI1
PIC X (3) •
07 FILLER
PIC X.
TIOARAI2
PIC X(3).
FILLER
REDEFINES TIOARAI2.
07 TIOAMBA
PIC X.
07 FILLER
PIC XX.
FILLER
PIC X (68) •
DFHTDIA COpy DFHTDIA.
02 TDIADBA
PIC X (80).
* PROCEDURE
DIVISION.
**************
ATPIPIN.
**************
MOVE
MOVE
MOVE
CSACDTA TO TCACBAR.
TCAFCAAA TO TCTTEAR.
TCTTEDA TO TIOABAR.
IF
THEN
TIOATID = 'BSDC'
GO TO ALPDCPN.
IF
THEN
TIOATID = 'BSME'
GO TO ALPMEPN.
IF
THEN
TIOATID = 'BSMR'
GO TO ALPMRPN.
DFHPC
TYPE=ABEND,
ABCODE=XAPT
*
***************
ALPDCPN.
**************
*
*
DATA COLLECTION
MOVE
MOVE
MOVE
TIOADID TO TiATDDI.
DCPDCAML TO TIOATDL.
DCPDCAMD TO TIOADATA.
DFHTC
TYPE=(WRITE,READ,WAIT)
DCPTEWN.
MOVE
TCTTEDA TO TIOABAR.
IF
THEN
EODTEST = IEDO'
GO TO DCPEXIT.
MOVE
MOVE
ADD
TWATDDI TO TCATDDI.
ZEROES TO TCTTEDA.
4 TO TIOATDL.
DFHTD
TYPE=PUT,
TDADDR=TIOATDL,
NORESP=DCPNRCN,
IDERROR=DCPDIEN
*
DFHPC
TYPE=APEND,
ABCODE=XDCP
*
DCPNRCN.
556
CICS/VS APRM (ML)
*
*
MOVE
DFHSC
DFHTC
GO TO
DCPEXIT.
MOVE
ADD
MOVE
DFHTC
GO TO
TIOABAR TO TC~SCSA.
TYPE=FREEMAIN
TYPE= (READ,liAIT)
DCPTEUU.
DCPEODML TO TIOATDL.
4 TO TIOATDL.
DCPEODMD TO TIOADATA.
TYPE=WRITE
RETURN1.
*
**************
ALP8EPN.
**************
*
MESSAGE ENTRY
*
MOVE
MOVE
ADD
TIOADID TO. TCATDDI.
TCTTETI TO TIOATID.
4 TO TIOATDL.
DFHTD
TYPE=PUT,
TDADDR=TIOATDL,
NORESP=MEPNRCN,
IDERROR=MEPDIAN
*
*
*
DFHPC
TYPE=ABEND,
ABCODE=XMEP
*
MEPNRCN.
MOVE
ADD
MOVE
DFIlTC
GO TO
MEPMEAHL TO TIOATDL.
4 TO TIOATDL.
MEPMEAMD TO TIOADATA.
TYPE=WRITE
RETURN1.
*
**************
ALPMRPN.
*****lIJ********
*
MESSAGE RETRIEVAL
*
MOVE
MOVE
TIOARAI2 TO TWAREAI.
TCTTETI TO TWATDDI.
IF
THEN
TIOARAIl NOT = 'ALL'
GO TO MRPAI1B.
MOVE
GO TO
TIOARAIl TO THAREAI.
MRPDEBN.
MRPAI1B.
IF
THEN
TIOADID = SPACES
GO TO MRPDEBN.
MOVE
TIOADID TO TWATDDI.
MRPDEBN.
MRPGTDN.
MOVE
TWATDDI TO TCATDDI.
DFHTD
TYPE=GET,
NORESP=MRPNRCN,
QUEZERO=MRPQERN,
IDERROR=MRPDIEN
Appendix A.
Example of a CICS/VS Application Program
*
*
'"
557
DFHPC
TYPE=ABEND,
ABCODE=XMR P
MRPNRCN.
MOVE
TDIAIRL TO TIOATDL.
MOVE
TDIADBA TO TIOADATA.
SUBTRACT 4 FROM TIOATDL.
DFHTC
TYPE=(WRITE,HAIT,SAVE)
IF
THEN
TWAREAI NOT = 'ALL'
GO TO RETURN1.
HOVE
GO TO
255 TO TWAQEMCI.
MRPGTDN.
MRPQERN.
IF
THEN
TWAQEMCI = 255
GO TO MRPNMQMB.
MOVE
MOVE
GO TO
HRPNMQM TO TIOATDL.
MESSAGE3 TO TIOADATA.
MRPr7RCS.
MRPNMQMB.
MOVE
MOVE
MRPNMMM TO TIOATDL.
MESSAGE2 TO TIOADATA.
MRPHRCS.
DFHTC
GO TO
TYPE=WRITE
RETURN1.
DCPDIEN.
110VE
MEPDIEN.
MRPDIEN.
MOVE
MOVE
DFHTC
TIOABAR TO TCTTEDA.
MCPDIEM TO TIOATDL.
MESSAGEl TO TIOADATA.
TYPE=WRITE
*
**************
RETURN1.
**************
*
558
DFHPC
TYPE=RETURU
CICS/VS aPRM (ML)
*
***********************************************************************
P L I
I
E X AMP L E
PRO B L E M
***********************************************************************
1* PL/I EXAMPLE PROBLEM *1
DFHCOVER
CICSATP:
PROCEDURE OPTIONS (MAIN,REENTRANT);
%INCLUDE DFHCSADS;
%INCLUDE DFHTCADS;
2 TWATDDI CHAR (4),
2 TWAREAI CHAR (4),
2 TWAQEMCI BINARY FIXED (8);
~INCLUDE DFHTCTTEi
%INCLUDE DFHTIOA;
2 TIOADATA CHAR (80);
DECLARE 1 TIOA 1 BASED (TIOABAR),
2 FILL1 CHAR (12),
2 TIOATID CHAR (4),
2 FILL2 CHAR (1),
2 TIOARAI1 CHAR (3),
2 FILL3 CHAR (2),
2 TIOAMBA CHAR (1);
DECLARE 1 TIOA2 BASED (TIOABAR),
2 FILL1 CHAR (12),
2 EODTEST CHAR (3),
2 FILL2 CHAR (2),
2 TIOADID CHAR (4),
2 FILL3 CHAR (1),
2 TIOARAI2 CHAR (3);
%INCLUDE DFHTDIAi
2 TDIADBA CHAR (80);
DCL MCPDEML FIXED BIN INIT (56), MCPDIE~ CHAR(56) INITIAL
('
DESTINATION IDENTIFICATION ERROR - PLEASE RESUBMIT');
DCL DCPDCAML FIXED BIN INIT(57), DCPDCAMD CHAR (57) INITIAL
(' DATA COLLECTION HAS BEEN REQUESTED AND IS ABOUT TO BEGIN ') ;
DCL DCPEODML FIXED BIN INIT(72), DCPEODMD CHAR (72) INITIAL
(. THE DATA HAS BEEN RECEIVED AND DISPATCHED TO THE DESIGNATED DESTINAT
ION .) ;
DCL MEPMEAML FIXED BIN INIT(76), MEPEAMD CHAR (76) INITIAL
(I YOUR MESSAGE HAS BEEN RECEIVED AND DISPATCHED TO THE DESIGNATED DEST
INATION') ;
DCL MRPNMML FIXED BIN INIT(60), MRPNMKM CHAR (60) INITIAL
('
THERE ARE NO MORE MESSAGES QUEUED FOR THIS DESTINATION');
DCL MRPNQML FIXED BIN INIT (55), MRPNMQN CHAR (55) INITIAL
(.
THERE ARE NO MESSAGES QUEUED FOR THIS DESTINATION');
ATPIPIN: TCTTEAR = TCAFCAAA;
TIOABAR = TCTTEDAi
IF TIOATID = 'PSDC' THEN GO TO ALPDCPNi
IF TIOATID = 'PSME' THEN GO TO ALPMEPN;
IF TIOATID = 'PSMR' THEN GO TO ALPMRPN;
DFHPC TYPE=ABEND,
*
ABCODE=XAPT
1* DATA COLLECTION PROGRAM *1
ALPDCPN:
TWATDDI = TIOADIDi
TIOATDL = DCPDCAHL;
TIOADATA = DCPDCAHD;
DFHTC TYPE= (WRITE,READ,WAIT)
DCPTEWN:
TIOABAR = TCTTEDA;
IF EODTEST = 'EODt THEN GO TO DCPEXIT;
TCATDDI = TWATDDli
UNSPEC (TCTTEDA) = 0;
TIOATDL = TIOATDL + 4;
DFHTD TYPE=PUT,
*
TDADDR=TIOATDL,
*
Appendix A.
Example of a CICS/VS Application Program
559
DFHPC
NORESP=DCP NRCN,
IDERROR=DCPDIEN
*
TYP~~ABEND,
*
ABCODE=XDCP
DCPNRCN: TCASCSA = TIOABAR;
DFHSC TYPE=FREEMAIN
DFHTC TYPE= (READ ,WAIT)
GO TO DCPTEWN;
DCPEXIT: TIOATDL = DCPEODML;
TIOADATA = DCPEODMD;
DFHTC TYPE=HRITE
GO TO RETURN;
/* MESSAGE ENTRY PROGRAM */
ALPMEPN:
TCATDDI = TIOADID;
TIOATID = TCTTETI;
TIOATDL = TIOATDL + 4;
DFHTD TYPE=PU'r,
TDADDR=TIOATDL,
NOR ESP=MEPNRCN,
IDERROR=MEPDIEN
DFHPC TYPE=ABEND,
ABCODE=XMEP
MEPNRCN: TIOATDL = MEP~EAML; TIO~DATA = MEPEAMD;
DFHTC TYPE=WRITE
GO TO RETURN;
/* MESSAGE RETRIEVAL PROGRA~ */
ALPMRPN:
TWAREAI = TIOARAI2; THATDDI = TCTTETI;
IF TlOARAIl
~= 'ALL' THEN GO TO MRPAI1B;
TWAREAI = TIOARAI1;
GO TO MRPDEBN;
MRPAI1B:
IF TIOADID = , , THEN GO TO MRPDEBN;
TWATDDI = TIOADID;
MRPDEBN:
MRPGTDN: TCATDDI = TWATDDI;
DFHTD TYPE=GET,
NORESP=MRPNRCN,
QUE ZERO=MR PQ ER N,
IDERROR=MRPD IEN
DFHPC TYPE=ABEND,
ABCODE=XMRP
MRPNRCN:
TDlABAR = TC~TD~A;
TIOATDL = TDIAIRL - 4;
TIOADATA = TDIADBA;
DFHTC TYPE=(WRITE,WAIT,SAVE)
IF TWAREAI ~= 'ALL' THEN GO TO RETURN;
TWAQEMCI = '11111111'B;
GO TO MRPGTDN;
MRPQERN:
IF TWAQEMCI = '11111111'B THEN GO TO MRPNMQMB;
TIOATDL = MRPNQML;
TIOADATA = MRPNMQN;
GO TO MRPWRCS;
MRPNMQMB: TIOATDL = MRPNMML; TIOADATA
MRPN~MM;
MRPWRCS:
DFHTC TYPE=WRITE
GO TO RETURN;
DCPDIEN:
TCTTEDA = TIOABAR;
MEPDIEN: MRPDIEN: TIOATDL = MCPDEML;
TIOADATA = MCPDIEM;
DFHTC TYPE=WRITE
RETURN:
END CICSATP;
560
CICS/VS APRM(ML)
*
*
*
*
*
*
*
*
Appendix B. BMS Map Definition Example
This appendix shows the BMS map definition macro instructions used to
generate the symbolic storage definition associated with an input map
for a display with the format shown below. The appendix also shows, for
each programming language, the symbolic storage definition that is
generated by the macro instructions.
0
PAYROLL
D
NAME:
D
DATE:
0
MMDDYY
0
SEX:
0
? MALE
0
SKILLS:
0
0
PAY:
0
0
The following map definition macro instructions would be used to
create the symbolic storage definition (DSECT) assoc1ated with an input
map for an assembler language application program.
(To create the map
itself, the TYPE=DSECT operand would be replaced by a TYPE=MAP operand.)
l1APSET
DFHMSD TYPE=DSECT,MODE=IN,CTRL=(FREEKB,FRSET),
MAP1
DFHMDI LINE=1,COLUMN=1,JUSTIFY= (LEFT,FIRST)
DFHMDF POS=9,LENGTH=7,INITIAL='PAYROLL',ATTRB=BRT,
HILIGHT=UNDERLINE
DFHMDF POS=40,LENGTH=8,INITlaL='NAME:'
DFHMDF POS=49,LENGTH=20,ATTRB=IC,COLOR=RED
DFHMDF POS=80,LENGTH=8,INITIAL='DATE:'
DFHMDF POS=89,LENGTH=2,GRPNAME=DATE,INITIAL='MM',ATTRB=NUM
DFHMDF POS=91,LENGTH=2,GRPNAME=DATE,INITIAL='DD',
JUSTIFY=(LEFT,BLANK)
DFHMDF POS=93,LENGTH=2,GRPNAME=DATE,INITIAL=IYY'
DFHMDF POS=120,LENGTH=8,INITIAL='SEX:'
DFHMDF POS=129,LENGTH=5,ATTRB=DET,INITIAL='?MALE'
DFHMDF POS=160,LENGTH=8,INITIAL='SKILLS:'
DFHMDF POS=169,LENGTH=4,ATTRB=UNPROT,OCCURS=3
DFHMDF POS=200,LENGTH=8,INITIAL=IPAY:I
DFHMDF POS=209,LENGTH=6,ATTRB=NUM,COLOR=BLUE
DFHMSD TYPE=FINAL
END
LANG=ASM,EXTATT=~APONLY'
NAME
MONTH
DAY
YEAR
SEX
SKILLS
PAY
Appendix B.
BMS Map Definition
Examp~e
561
The assembler DSECT produced as a result of the above statements
would be as follows:
DS
OC
SPACE
NAMEL
DS
CL2
OC
NAMEF
DS
DS
C
NAMEI
DS
CL2D
SPACE
DATA GROUP DATE
* START NEW
DATEL
DS
CL2
DATEF
DS
OC
DS
C
DATEI
DS
DC
SPACE 2
MONTHI
DS
CL2
SPACE
DAYI
DS
CL2
SPACE
YEARI
DS
CL2
SPACE
SEXL
DS
CL2
SEXF
DS
DC
DS
C
SEXI
DS
CL 1
SPACE
SKILLSD DS
OC
SKILLSL DS
CL2
SKILLSF DS
OC
DS
C
Cl4
SKILLSI DS
SKILLSN EQU
*
ORG
SKILLSD+3* (3+4 )
SPACE
PAYL
DS
CL2
DS
PAYF
DC
DS
C
PAYI
DS
CL6
SPACE
* * * END OF MAP DEFINITION * * *
SPACE 3
ORG
MAPSETT EQD *
* END OF MAPSET
* * * END OF MAP SET DEFINITION * * *
SPACE 3
MAPII
562
CICS/VS APRM(ML)
INPUT DATA FIELD LENGTH
DATA FIELD FLAG
DATA FIELD ATTRIBUTE
DATA FIELD
INPUT
GROUP
GROUP
GROUP
GROUP
FIELD
FIELD
FIELD
FIELD LENGTH
FLAG
ATTRIBUTE
ORIGIN
DATA FIELD
DATA FIELD
DATA FIELD
INPUT DATA FIELD LENGTH
DATA FIELD FLAG
DATA FIELD ATTRIBUTE
DATA FIELD
FIRST OCCURRING FIELD
INPUT DATA FIELD LENGTH
DATA FIELD FLAG
DATA FIELD ATTRIBUTE
DATA FIELD
NEXT OCCURRING FIELD
ALLOCATE OCCURRING FIELD SPACE
INPUT DATA FIELD LENGTH
DATA FIELD FL~G
DATA FIELD ATTRIBUTE
DATA FIELD
By changing LANG=ASM to LANG=COBOL in the DFHHSD macro, the following
symbolic storage definition could be produced.
01
MAPII.
02 NAM.EL COr!P PIC S9 (4) •
02 NAMEF PIC X.
02 NAMEI PIC X (20) •
02 DATEL COMP PIC S9(4).
02 DATEF PIC X.
02 DATEI.
03 MONTHI PIC X(2).
03 DAYI PIC X(2).
03 YEARI PIC X (2) •
02 SEXL COMP PIC S9 ~) •
02 SEXF PIC X.
02 SEX I PIC X (1) •
02 SKILLSD OCCURS 3 TIMES.
03 SKILLSL COMP PIC S9 (4).
03 SKILL SF PIC X.
03 SKILLSI PIC X(4).
02 PAYL COMP PIC S9(4).
02 PAYP PICE X.
02 PAYI PIC X(6).
Similarly, changing LANG=ASM to LANG=PLI in the DFHMSD macro would
produce the following symbolic storage definition:
DECLARE
2
2
2
2
1 MAPII BASED(BMSMAPBR) UNALIGNED,
NAMEL FIXED BIN (15,0),
NAMEP CHAR(l),
NAMEI CHAR (20) ,
DATEL FIXED BIN(lS,O),
2 DATEF CHAR (1) ,
2 DATEI ,
3 MONTHI CHAR (2) ,
3 DAYI CHAR(2),
3
YEARI CHAR (2) ,
2 SEXL FIXED BIN(15,0),
2 SEX F CHAR (1) ,
2 SEXI CHAR(l),
2 SKILLS D (3) ,
3 SKILLSL FIXED BIN(15,0),
3 SKILLSF CHAR(1),
3 SKILLSI CHAR (4),
2 PAYL FIXED BIN(15,O),
2 PAYF CHAR (1) ,
2 PAYI CHAR (6) ,
2 FILL0024 CHAR (1 ) ;
1* END OF MAP DEFINITION *1
Appendix B.
BM.S aap Definition Example
563
Appendix C. Inter-Release Compatibility
This appendix defines any incompatibilities that exist between the
application programming interface (API) for CICS/VS Version 1.5 and
Versions 1.1.0, 1.1.1, 1.2, 1.3, 1.4, and 1.4.1. Such incompatibilities
can be divided into two categories: source incompatibilities, that is,
input code that CICS/VS Version 1.5 will treat differently from previous
versions of CICS/VS, thus producing a different object program; and
object incompatibilities, that is, differences in the results that will
be obtained when the same object program is executed under CICS/VS
Version 1.5 from those obtained running under earlier versions.
There are no incompatibilities between Versions 1.4 and 1.4.1.
Source Incompatibilities
In versions of CICS/VS previous to 1.4, it has not been valid to code
TIOAPFX=YES in the DFHMSD or DFHMDI macro instruction for an assemoler
language application program. If this operand was coded in this way,
CICS/VS disregarded it and applied the default specification
(TIOAPFX=NO).
In CICS/VS Versions 1.4, 1.4.1, and 1.5, it is valid to
code TIOAPFX=YES for an assembler program: doing so will thus produce a
differ&nt object program under CICS/VS 1.4, 1.4.1, or 1.5 from that
which would be produced under earlier versions.
There are no other source incompatibilities.
~bject
Incompatibilities
There are no object incompatibilities.
Definition of the Application Programmer Interface
The remainder of this appendix defines the application programming
interface that applies to users converting from Versions 1.1.0, 1.1.1,
1.2, 1.3, 1.4, or 1.4.1 of CICS/VS to Version 1.5 of CICS/VS.
The API is defined as the CICS/VS macro instructions, control block
fields, and area prefix fields that are available for use by a userwritten application program. With the exception of the single source
incompatibility (TIOAPFX=YES when LANG=ASM) described above, application
programs using these macros or fields will execute successfully under
Versions, 1.4, 1.4.1, and 1.5 without recompilation.
The macros and fields of the API that are valid for a given release
are those documented in the CICSIYS Application Programmer's Reference
Manual (Macro Levell for that release. References to fields or macros
other than those documented in the manual, or to fields marked "unused"
or "reserved" in former releases, may cause problems.
Application
programs containing such references should be recompiled, tested, and
where necessary modified to ensure correct execution.
Appendix C.
Inter-Release Compatibility
565
Users should also refer to the "Memorandum to Users" distributed with
Version 1.5 for a further discussion of compatibility, particularly with
respect to BMS maps.
CICS/VS Macro Instructions
The following macro instructions are those that are valid for Version
1.4 and 1.4.1 of CICS/VS, and for which compatibility can be guaranteed
for Version 1.5 for uses that were valid in Versions 1.4, and 1.4.1.
They are documented in the CICS/VS Version 1, Release 4 Application
Programmer's Reference Manual (Macro-Level), Order No. SC33-Q079-1.
DFHBIF
DFHBMS
DFHDC
DFHDI
DFHFC
DFHIC
DFHJC
DFHKC
DFBMDF
DFHPC
DFHSC
DFHSP
DFHTC
DFHTD
DFH'rR
DFHTS
The CICS/OS/VS CALLDLI macro is also part of the API for Versions 1.4
and 1.4.1.
Only the operands and parameters of the macros described in the
publication cited above are supported by CICS/VS for use by user-written
application programs.
CICS/VS Control Block Fields and Area Prefix Fields
Many of the fields in CICS/VS areas, for example, the CSA, or prefixes
to user I/O areas, for example, a TIOA, are referred to directly when a
CICS/VS macro is executed and it is essential that their location, type,
and meaning remain unchanged across releases.
The following fields form the API for Version 1.5 of CICS/VS. Those
marked with an asterisk were introduced in Version 1.5. Those that are
not marked with an asterisk form the API for Version 1.4 and are
referred to throughout the APRM for Version 1.4.
566
CICS/VS APRM(ML)
CSABFNAC
Address of built-in functions
CSABMS
BMS address
CSACD'rA
Common System Area Currently Dispatched Task Address
CSACTODB
Common System Area Current Time of Day in Binary format
CSADCNAC
Dump Control Entry Address
CSAPCNAC
Pile Control Entry Address
CSAICNAC
Time Control Entry Address
CSAICRNX
NOP/Branch Flush Routine Interface
CSAJCNAl
Journal Control Macro Entry Pointer 1
CSAJCNA2
Journal Control Macro Entry Pointer 2
CSAJYDP
Common System Area Date in Packed decimal format
(OOOYYDDD)
CSAKCNAC
Task Control Entry Address
CSAOPFLA
Common System Area Optional Peatures List Address
CSAPCNAC
Program Control Entry Address
CSASCNAC
storage Control Entry Address
CSASPNAC
Sync Point Program Entry Address
CSATCNAC
Terminal Control Entry Address
CSATCRWE
Terminal Control Read/Write Entry Address
CSATDNAC
Transient Data Control Entry Address
CSATODP
Common System Area Time of Day in Packed decimal format
(four bytes)
CSATRMFl
Trace Haster Flags
CSATRMP2
Trace System Flags
CSATRMF3
Trace System Flags
CSATRNAC
Trace Control Entry Address
CSATRTBA
Common System Area TRace TaBle Address
CSATSNAC
Temporary storage Entry Address
CSAWABA
Common System Area Work Area Beginning Address
FCDSOID
Beginning Address Data Area
FCFIOBEX
File Control File Input/Output BDAM Error Code
(four bytes)
FCFIOEX
File Control File Input/Output ISAM Error Code
(four bytes)
FCFIOFCT
File Control Entry Table Address
Appendix C.
Inter-Release Compatibility
567
PCPIOLRA
Logical Record Address
FCUPCTA
File Control Table Entry Address
FCUPDRA
File Input/Output Area Address
PCUWA
File Control Update Work Area
PIOADBA
Data Beginning Address
FIOAIND
File I/O Area Indicator
FWAIND
File Work Area Indicator
JCAADATA
Journal Control Area Address of DATA to be written to
journal data set
JCAAPRFX
Journal Control Area Address of User-Prefix Data
JCAECN
Journal Control Area Event Control Number
(four bytes)
JCAJCRC
Journal Control Area Journal Control Response Code
(one byte)
JCAJFID
Journal Control Area Journal File IDentification
~ne byte)
JCAJRTID
Journal Control Area Journal Record Type IDentification
~wo
(data begin address)
bytes)
JCALDATA
Journal Control Area Length of DATA to be written to
journal data set (two bytes)
JCALPRFX
Journal Control Area Length of user PReFiX
~wo bytes)
JCANOTE
Note Request Returned-Data
JCARST
Run Start Time
JCATR1
Type Request Byte1
JCATR2
Type Request Byte2
JCATR3
(Reserved for CICS usage)
JCAVCD
Volume Creation Date (YYDDD+)
JCAVSN
Volume Sequence Number (NNN+)
SAASACA
storage Accounting Area Storage Accounting Chain
Address
SAASAD
Storage Area Displacement
SAASCI
Storage Class Identification
SAASFI
Storage Format Identification
TCAATAC
Abnormal Termination Abend Code
TCABFPA!
Address Pointer Initialization (Built-In Functions)
568
CICS/VS
APRM~L)
(HHMMSSS+)
TCABFTR
Task Control Area Built-in Function Type of Request
(one byte)
TCABITF
Task Control Area BIT Manipulation address of one-byte
bit Field to be operated on
TCABITR
Task Control Area BIT Manipulation Result of BITEST
operation ~ne byte)
TCABITTP
Bit Function Type Indicator
TCABITV
Task Control Area BIT Manipulation address of bit pattern
(mask) to be applied to a specified byte
TCABMSCP
Task Control Area basic mapping support Cursor position
(two bytes)
TCABMSMA
Task Control Area basic mapping support Map Address
TCABMSMN
Task Control Area basic mapping support Map Name
(eight bytes)
TCACCCA
Task Control Area Common Control Communication Area
TCACCSV 1
Save Area for Bytes Overlaid by DFHDC
TCACCSV2
Save Area for Bytes Overlaid by DFHDC
TCACHKR
Response Indicator (Built-In Function)
TCACKFD
Task Control Area Field Verify address of FielD to be
ChecKed
TCACKLN
Task Control Area Field Verify LeNgth of field to be
ChecKed (two bytes)
TCADCDC
Task Control Area Dump Control Dump Code
TCADCNB
Task Control Area Dump Control Number of Bytes in area to
be dumped ~wo bytes)
TCADCSA
Task Control Area Dump Control storage
be dumped
TCADCTR
Task Control Area Dump Control Type of Request (Assembler
or PL/Ii two bytes)
TCADIDNA
Task Control Area Batch Data Interchange Destination
Name Address
TCADIKYA
Task Control Area Batch Data Interchange Key Address
TCADINRS
Task Control Area Batch Data Interchange Number of
Records in Request (one byte)
TCADIRNA
Task Control Area Batch Data Interchange Relative
Record Number Address
TCADIVNA
Task Control Area Batch Data Interchange Volume
Name Address
TCADLFUN
Task Control Area DL/1 FUNction (four bytes)
TCADLIO
Task Control Area DL/I Input/Output area address
Appendix C.
(four bytes)
Addre~s
of area to
Inter-Release Compatibility
569
TCADLPCB
Task Control Area DL/1 Program Control Block address
TCADLPSB
Task Control Area DL/1 program specification block name
(eight bytes)
TCADLSSA
Task Control Area DL/I address of segment search argument
list
TCADLTR
DL/1 Type of Invalid Response
TCAFCAA
Task Control Area File Control Area Address
TCAFCAAA
Task Control Area Facility Control Area Associated
Address
TCAFCAI
Task Control Area File Control indirect Access data set
Identification (eight bytes)
TCAFCDI
Task Control Area File Control Data set Identification
(eight bytes)
TCAFCI
Facility Control Indicator
TCAFCNRD
Task Control Area File Control Number of Records
Deleted (two bytes binary)
TeAFCRI
Task Control Area File Control record identification
(eight bytes)
TCAFCSI
Task Control Area File Control Segment Identification
(eight bytes)
TCAFCTR
Task Control Area File Control Type of Request/Response
~ssembler or PL/I: one byte)
TCAFCURL
Task Control Area File Control Undefined Record
Length (two bytes)
TCAFLD
Task Control Area Field Edit address of FieLD to be edited
TCAFLN
Task Control Area Field Edit LeNgth of Field to be
edited (two bytes)
TCAICCLS
Unique Identification of Request Identification
TCAICDA
Task Control Area Interval Control Data Area
TCAICQID
Task Control Area Interval Control reQuest
IDentification (eight bytes)
TCAICQPX
Task Control Area Interval Control
reQuest Prefix ~wo bytes)
TCAICRT
Task Control Area Interval Control Request Time
(four bytes)
TCAICTEC
Task Control Area Interval Control Timer Event Control
area address
TCAICTI
Task Control Area Interval Control Transaction
Identification (four bytes)
TCAICTID
Task Control Area Interval Control Terminal
IDentification (four bytes)
570
CICS/VS APRM(ML)
TCAICTR
Task Control Area Interval Control Type of Request/Response
(Assembler or PL/I; one byte)
TCAINAM
Name List Indicator
TCAINA1
Task Control Area INput Formatting Address of list
of offsets for the internal fixed-format TIOA
TCAINA2
Task Control Area INput Formatting Address of list
of field names that may appear in input stream
TCAINH1
Task Control Area INput Formatting length of the TIOA
to be acquired for the internal fixed-format representation
of data (Halfword field)
TCAINRC
Task Control Area INput Formatting Response Code
(one byte)
TCAJCAAD
Task Control Area Journal Control Area ADdress
TCAKCFA
Task Control Area Task Control (KCP) Facility control
area Address
TCAKCRC
system Macro Return Code
TCAKCTA
Task Control Area Task Control (KCP) TCA Address
TCAKCTI
Task Control Area Task Control (KCP) Transaction
Identification (four bytes)
TCAMSFMP
Task Control Area Mapping Support Function
Management Parameter
TCAMSFSC
Field Separator Characters
TCAMSHDR
Task Control Area Happing support HeaDeR address
(four bytes)
TCAMSIOA
Task Control Area Mapping Support Input/Output Area
Address
TCAMSJ
Task Control Area Mapping support Justification
(one byte)
TCAMSLDC
Logical Device Code
TCAMSLDM
LDC Mnemonic
TCAMSMSA
Task Control Area Happing support Map Set Address
TCAMSMSN
Task Control Area Mapping Support Map Set Name
(eight bytes)
TCAKSOC
Task Control Area Mapping Support Operator Class
(three bytes)
TCAMSOCN
Overflow Control Number
TCAMSPGN
Task Control Area Mapping Support PaGe Number
(current page; two bytes binary)
TCAMSRC1TCAMSRC3
Task Control Area Mapping Support Response Code (one
byte each)
TCAMSRID
Task Control Area Mapping Support Request IDentification
Appendix C.
Inter-Release
Comp~tibility
571
TCAMSRIl
Task Control Area Mapping Support Return Information
(one byte)
TCAMSRLA
Task Control Area Mapping Support Routing List
Address, or Returned page List Address
TCAMSRTI
Task Control Area Mapping Support Routing
Time or Tiae interval Indicator ~our bytes packed decimal)
TCA!!STA.
Task Control Area Mapping Support Title Address
TCAMSTI
Task Control Area Mapping Support error Terminal
Identification (four bytes)
TCAMSTRL
Task Control Area Mapping Support TRaiLer address
(four bytes)
TCAMSTR1TCAMSTR7
Task Control Area Mapping Support Type Request (one
byte each)
TCAMSWCC
Write Control Characters
TCANAME
Task Control Area Phonetic Conversion 16-byte field
containing data (NAME) to be phonetically encoded
TCANXTID
Task Control Area NeXt Transaction IDentification
(four bytes)
TCAOCLA
Open/Close List Address
TCAOCTR
Open/Close Type of Request
TCAPCAC
Task Control Area Program Control ABEND Code
(four bytes)
TCAPCARO
Abend Recovery option
TCAPCERA
Task Control Area Program Control Exit Routine Address
TCAPCLA
Loaded Program Beginning Address
TCAPCPI
Task Control Area Program Control Program Identification
(eight bytes)
TCAPCPSW
System Recovery Program PSW
TCAPCSR
Program Control Secondary Request
TCAPCTR
Type of Request/Response
TCAPHNR
Task Control Area PHoNetic Conversion error Response
indicator (contains X'54' if invalid name was
encountered; one byte)
TCAPHON
Task Control Area PHONetic Conversion 4-byte returned
value
TCAPURGI
Task Purge Indicator
TCASCIB
Task Control Area Storage Control Initialization Byte
TCASCNB
Task Control Area Storage Control Number of Bytes
of storage requested ~wo bytes)
TCASCSA
Task Control Area Storage Control Storage Address
572
CICS/VS APRM(ML)
of area acquired or to be freed
TCASCTR
storage Control Type of Request
TCASPTR
Sync Point Request
TCASV!fID
service Module Control Indentification
TCATCDC
Task Control Area Task Control Dispatcher Control
indicator (one byte)
TCATCDP
Task Control Area Task Control Dispatching Priority
(one byte)
TCATCEA
Task Control Area Task control Event control area
Address (ECB or CCB or list)
TCATCEI
Task Control Event Control Indicator
TCATCQA
Task Control Area Task Control enQueued resource length
(high-order byte) and Address (three low-order bytes)
TCATCTR
Task Control Type of Request
TCATDAA
Task Control Area Transient Data Area Address
TCATDDI
Task Control Area Transient Data Destination
Identification (four bytes)
TCATDTR
Task Control Area Transient Data Type of Request/Response
(Assembler or PL/I; one byte)
TCATPAPR
Application Reqaest Response Code
TCATPCON
Connection Type Flag
TCATPCS1
External Control Request Byte 1
TCATPCS2
External Control Request Byte 2
TCATPLDA
Logic Device Code Entry Address
TCATPLDC
Logical Device Code
TCATPLDM
Logical Device Mnemonic
TCATPLRC
Locate Return Code
TCATPOC2
Operation Control Byte 2
TCATPOC3
Operation Control Byte 3
TCATPOS1
External Operation Request Byte 1
TCATPOS2
External Operation Request Byte 2
TCATPPN!f
Program Name Field
TCATPTA
Terminal Address or Identification
TCATRFl
Trace Entry Data Area 1
TCATRF2
Trace Entry Data Area 2
TCATRID
Trace Entry Identification
Appendix C.
Inter-Release Compatibility
573
TCATRIDl
Trace Entry Identification Extension
TCATRBP
TCA Trace Control (Single Task)
TCATRTR
Type of Trace Request
TCATSAP
Task Control Area Table Search length of Pield in
Argument table entry to be compared with search argument
(one byte)
TCATSAl
Task Control Area Table Search Address of search arguaent
TCATSA2
Task Control Area Table Search Address of first entry in
arg ument table
TCATSA3
Task Control Area Table Search Address of first function
table entry
TCATSA4
Task Control Area Table Search Address of field in first
entry in argument table to be compared with search
argument
TCATSA5
Task Control Area Table Search Address of (1) function
field within first function table entry,on input, or (2)
function field within function table entry which
contained value retrieve~, on output
TCATSDA
Task Control Area Temporary Storage Data Address
TCATSDI
Task Control Area Temporary Storage Data Identification
(eight bytes)
TCATSPC
Function Code (Built-In Function)
TCATSFF
Task Control Area Table Search length of Field in
Function table entry to be retrieved ~ne byte)
TCATSH1
Task Control Area Table Search maximum number of entries
to be searched (halfword)
TCATSH2
Task Control Area Table Search length of each argument
table entry (halflford)
TCATSH3
Task Control Area Table Search length of each function
table entry (halfword)
TCATSH4
Task Control Area Table Search index value (relative to
1) identifying the matching argument table entry returned
to application program; if zero, no matching entry was
found (halfword)
TCATSRN
Task Control Area Temporary Storage Record Number
TCATSRPC
Task Control Area Table Search ResPonse Code
TCATSTR
Task Control Area Temporary Storage Type of
Request/Response (Assembler or PL/Ii one byte)
TCATSTR2
Type of Request (Secondary)
TCAWGAA
Task Control Area WeiGhted Retrieval VSWA pointer
TCAWGCNT
Task Control Area Weighted Retrieval Count of maximum
number of records to be made available to application
514
CICS/VS APRM(ML)
program; NRECDS parameter
~alfword
field)
TCAHGH1
Task Control Area WeiGhted Retrieval highest percentage
of acceptability for a ~eighted retrieval function
(halfword)
TCAWGH2
Task Control Area WeiGhted Retrieval lowest percentage of
acceptability for a weighted retrieval function
(halfword)
TCAWGH3
Task Control Area WeiGhted Retrieval percentage of
acceptability of this record saved as the result of a
weighted retrieval operation (Halfword field)
TCAW,GH4
Task Control Area WeiGhted Retrieval number of records
left to be presented to user (Halfword field)
TCAW"GH5
Task Control Area WeiGhted Retrieval number of records
dropped to remain within user-specified maximum (NRECDS)
(Halfword field)
TCAWPAA
VSWA Pointer
TCAWPA1
Task Control Area Weighted Retrieval Address of search
argument
TCAWPA3
Task Control Area Weighted Retrieval Address of area
containing record to be examined
TCAWPA4
Task Control Area Weighted Retrieval Address of field
within area containing record to be examined
TCAWPB1
Task Control Area Weighted Retrieval character indicating
format of search argument ~ne byte)
TCAW PH 1
Task Control Area Weighted Retrieval length of search
argument (halfword)
TCAHPH2
Task Control Area Heighted Retrieval match value
(halfword)
TCAHPH3
Task Control Area Weighted Retrieval no match value
(halfword)
TCAWPH4
Task Control Area Weighted Retrieval upper limit of
comparison range (halfword)
TCAWPH5
Task Control Area Weighted Retrieval lower limit of
comparison range (halfword)
TCAWPNL
Task Control Area Weighted Retrieval Null character
(one byte)
TCAWPTR
Task Control Area Weighted Retrieval Type of Range
(one byte)
TCAiRAA
Task Control Area weighted Retrieval VSWA pointer
TCAWTDI
Task Control Area Weighted ReTrieval Data Identif ication
(eigh t bytes)
TCAWTH1
Task Control Area Weighted ReTrieval maximum number
of records to be retrieved (halfword)
Appendix C.
Inter-Release Compatibility
575
TCAWTH2
Task Control Area Weighted ReTrieval relative number
of record with same partial key to be examined first
(halfword)
TCAWTH3
Task Control Area Weighted ReTrieval maximum percentage
of acceptability for retrieved records (halfword)
TCAWTH4
Task Control Area Weighted ReTrieval minimum percentage
of acceptability for retrieved records (halfword)
TCAWTRC
Task Control Area Weighted Retrieval Response Code
(one byte)
TCAWTRI
Task Control Area Weighted ReTrieval address of partial
key of Record at which retrieval is to begin (fullword)
TCTEASCC
3210 Alternate Screen Size (Columns)
TCTEASCL
3270 Alternate Screen Size
TCTEASCZ
3210 Alternate Screen Size
TCTEDSCC
3210 Default Screen Size
TCTEDSCL
3210 Default Screen Size (Rows)
TCTEDSCZ
3210 Default Screen Size
TcrEEOCI
EOC or OC Received Indicator
TCTEFMHI
FMR Area for 3600 Devices
TCTESIDI
Field containing inbound SIGNAL data (4 bytes)
TCTESIDO
Area for Outbound Signal Data
TCTETDST
Data Stream Type Byte
TCTETXTF
3210 Text Feature Flag byte
TCTEVLDC
Logical Device Code
TCTE32EF
*
~ows)
(Columns)
~PL/TEXT)
3210 Data Stream Extensions Flag
TCTE32SF
3210 Screen Size Flag
TCTTEAID
Terminal Control Table Terminal Entry Attention
IDentifier (used with the 3270 Information Display
System; one byte)
TCTTEBMN
Name of Format Image in Buffer
TCTTECAD
Cursor Address in Binary
TCTTECIA
Terminal Control Table Terminal Entry Control
Information Area pointer
TCTTECIL
Length of User Area
TCTTECR
Request Completion Analysis
TCTTECRE
Request Completion Extension
TCTTEDA
Terminal Control Table Terminal Entry Data Address
576
CICS/VS APRM (ML)
TC'fTEDES
TCAa Destination Name
TCTTEFIB
Terminal Feature Flag Byte
TCTTEOCL
Operator Class Code
TCTTEPCF
Terminal Control Table Terminal Entry Passbook Control
Field (2980 General Banking Terminal System; one byte)
TCTTESC
Terminal Storage Chain Address
TCTTESID
Terminal Control Table Terminal Entry station
IDentification (2980 General Banking Terminal System;
one byte)
TCTTETAB
Terminal Control Table Terminal Entry TABs needed to
position print element (2980 General Banking Terminal
System; one byte)
TCTTETCM
TCAM Operation Code Flag
TCTTETI
Terminal Identification
TCTTETID
Terminal Control Table Terminal Entry Teller
IDentification (2980 General Banking Terminal; one byte)
TCTTETM
Terminal Control Table Terminal Entry Terminal
(one byte)
TCTTETS
Terminal Status
TCT'rETT
Terminal Control Table Terminal Entry Terminal Type
(one byte)
TDIADBA
Transient Data Input Area Data Begin Address
TDIAIRL
Transient Data Input Area Intrapartition Record
Length (two bytes)
TDIASAL
Storage Accounting Area Length
TDIASCA
Transaction storage Chain Address
TDOADBA
Transient Data Output Area Data Begin Address
TDOASAL
Storage Accounting Area Length
TDOASCA
Transaction Storage Chain Address
TDOAVRL
Transient Data Output Area Variable Record Length
(two bytes)
TIOACLCR
Terminal Input/Output Area ControL CharacteR
TIOALAC; one byte)
TIOADBA
Terminal Input/Output Area Data Begin Address
TIOALAC
Terminal Input/Output Area Line Address Control
(same as TIOACLCR; one byte)
TIOATDL
Terminal Input/Output Area Transmission Data Length
(two bytes)
TIOAWCI
Write Control Indicator
Appendix C.
~odel
(same as
Inter-Release Compatibility
511
TSIOADBA
Temporary storage InputjOutput Area Data Begin Address
TSIOASAL
storage Accounting Area Length
TSIOASCA
Transaction storage Chain Address
TSIOAVRL
Temporary Storage InputjOutput Area Variable Record
Length (two bytes)
VSWAERRC
Error Code
VSWAID
RPL Identifier
VSWALEN
VSA~
VSWAREA
VSAK Work Area REcord Address
VSWARTNC
RPL Return Code
578
CICS/VS
Work Area record LENgth (four bytes)
APR~(ML)
Appendix D. Translation Tables for the 2980
This appendix contains translation tables for the following components
of the IBM 2980 General Banking Terminal System:
•
2980 Teller Station Model 1
•
2980 Administrative Station Model 2
•
2980 Teller station Model 4
The line codes and processor codes listed in these tables are unique
to CICS/VS and are represented as standard EBCDIC characters.
Appendix D.
Translation Tables for the 2980
579
580
CICS/VS APRM (ML)
1
-,
KEI
No.
ENGRAVING
Top (tC)
Front (UC)
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
53
= 1
Q
A
2
1
F1
D8
C1
F2
E9
E6
E2
F3
E7
C5
C4
F4
C3
D9
C6
F5
E5
E3
C7
F6
C2
E8
C8
F7
D5
E4
D1
F8
04
C9
D2
F9
6B
D6
D3
FO
4B
D7
53
60
61
5C
7B
50
05
36
06
16
15
06
40
26-ETB
03-ETX
Z
if
S
;
3
X
E
D
4
C
R
F
% 5
V
T
G
• 6
B
I
H
> 7
N
U
J
*
M
8
I
K
( 9
I
a
,
t
)
-,
0
.
P
$
?
tINE I
CPU CODE
Code Numeric (LC)
Alpha (UC)
/
¢I
" #:
+ &
TAB
LOCK
SHIFT
BACKSPACE
RETURN
SHIFT
(SPACE)
SEND
F1
98
81
F2
A9
A6
A2
F3
A7
85
84
F4
83
99
86
F5
AS
A3
87
F6
82
A8
88
F7
95
A4
91
F8
94
89
92
F9
6B
96
93
FO
4B
97
5B
60
61
70
7B
50
05
36
06
10
15
06
40
(1)
(q)
(a)
(2)
(z)
(w)
(s)
(3)
(x)
(e)
(d)
(4)
(c)
(r)
(f)
(5)
(v)
(t)
(g)
(6 )
(b)
(y)
(h)
(7)
(0)
(u)
(j)
(8)
(m)
(i)
(k)
(9 )
(, )
(0 )
(1)
(0 )
.
( )
(p)
($)
(-)
V)
(I)
(#)
(& )
7E
D8
C1
4C
E9
E6
E2
5E
E7
C5
C4
7A
C3
D9
C6
6C
E5
E3
C7
70
C2
B8
C8
6E
D5
E4
01
5C
04
C9
02
4D
4F
06
D3
50
5F
08
SA
6D
6F
4A
7F
4E
05
36
06
16
15
06
40
BtL
ID
(=)
CQ)
(A)
«)
(Z)
(W)
( S)
(;)
(X)
(E)
(D)
(:)
(C)
(R)
(F)
(%)
(V)
(T)
(G)
(. )
(B)
(I)
(H)
(»
(N)
(U)
(J)
(*)
(M)
(I)
(K)
(0
(I)
(0)
(L)
0)
(-,)
(P)
(!)
LJ
( 1)
(¢)
( ")
(+)
BCKSPACE
No keyfroot engraving on a 2980 Administration Station Model 2
Figure D-2.
2980-2 Character Set/Traoslate Table
Appendix D.
Translation Tables for the 2980
581
KEY
No.
0
1
2
3
4
5
6
7
ENGRAVING
Top (LC)
Front (UC)
CK $
Q
A
CK #
0
Z
W
S
1
IMD 2
8
X
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
E
D
2
C
R
F
3
V
T
G
4
B
Y
H
5
N
U
48
49
50
51
Il!D 1
CODE
AMT
OB
J
ACCT #'
K
7
7
4
1
8
0
5
2
9
0
L
8
P
$
9
6
3
VAL
TAB
ALPHA
NUMERIC
SEND
RETURN
NUMERIC
SPACE
FEED OPEN
Figure D-3.
582
6
N
I
*#
&
LINE I
CPU CODE
Code Numeric (LC)
Alpha (UC)
D9
D3
C1
C9
E9
E6
E2
5B
E7
C5
C4
4B
C3
60
C6
E8
E5
E3
C7
5C
C2
61
D7
D8
D5
E4
D1
C8
D4
D6
D2
F7
6B
F4
P1
F8
FO
F5
F2
F9
7B
F6
F3
50
05
36
06
26-ETB
03-ETX
15
06
40
04
BC
D3
C1
B7
4B
5C
5B
4F
AE
C5
6F
BF
C3
60
C6
BB
AO
A1
C7
BE
C2
61
D7
B2
D5
AF
D1
7B
E7
D6
D2
F7
BLANK
F4
F1
F8
FO
F5
F2
F9
BO
F6
F3
50
05
60
D8
C1
C9
E9
E6
E2
F1
E7
C5
C4
P2
C3
D9
C6
F3
E5
E3
C7
P4
C2
E8
C8
F5
D5
E4
D1
F6
D4
C9
D2
F7
6B
D6
D3
F8
4B
D7
5B
F9
7B
5C
7B
50
05
15
15
40
40
2980-4 Character Set/Translate Table
CICS/VS APRM(ML)
BLL
ID
19
14
5
22
23
21
9
6
7
OPENCH
Bibliography
For further information on the Customer Information Control
System/Virtual Storage (CICS/VS), the reader of this manual is
to the following IBM publications:
Customer Information Control
referr~d
SystemLvirt~!_~~Q£~g-1£ICSL!~L Ve~§i~~
1, Release 5:
General Information, GC33-0066
SystemLApplication Design Guide, SC33-0068
~stem
Programmer's
R~,erence
llstem Prog ra mmer' s Guide
Manual, SC33-0069
(DOSLVS1, SC33-0070
System Programmer's Guide (OSIVS), SC33-0071*
!2plication Programmer's Reference Manua1-j£ommand Levell,
SC33-0077
Application Programmer's Reference Manual (RPG II), SC33-0085
IBM 3270 Guide, SC33-0096
3650/3680 Guide, SC33-0073
3767L3770L6670 Guide, SC33-0074
3790/3730 Guide, SC33-0075
Operator's Guide, SC33-0080
Messages and Codes, SC33-0081
Entry Level System User's Guide (DOSLVS), SC33-0086
Problem Determination Guide, SC33-0089
Di~nostic
Reference, LC33-0105
Data Areas (DOSIYS) "
Data Areas
Applicgtion
GX33-6012
LI33-6033
roS/VS), LI33-6035*
P~Qg£~~r's
Refgrence Summary (Command Level),
Master Terminal 02erator's Reference Summa£y, 5X33-6010
Master Index, 5C33-0095*
*Available at the same time as CICS/OS/V5 version 1 Release 5
Bibliography
583
The reader of this manual may also want to refer to the following
publications:
IB~_2!stgmL360
IB~
Disk Operating System:
Subset American National Standard COBOL Compiler and Library
Programmer's Guide, SC28-6439
Full American National Standard COBOL compiler and Libra£y,
Version 3, Programmer's Guide, SC28-6441
Full American Nati~nal Standard COBOL Programmer's Guide,
GC28-6398
IBM System/360 Operating System:
Full American National Standard COBOL Compiler and Library,
Version 4, Programmer's Guide, SC28-6456
Full American National Standard COBOL Compiler and Library,
Version 3~grammer's Guide, SC28-6437
Full
A.!!lg£i£~1LNational_st~ndard
Versi~~rogrammer's
COBOL Compil~-ill!g Library,
Guide, GC28-6399
System Network Architecture:
Functional Description of Logical unit Types, GC20-1868
1Ypes of Logical Unit to Logical Unit Sessions, GC20-1869
DOS/yS COBOL Compiler and Library Programmer's Guide, SC28-6478
OS/yS COBOL Com2!ler and Library Programmer's Guide, SC28-6483
OS-f1LI Optimizing Compiler Programmer's Guide, SC33-0006
DOS PL/I Optimizing Compiler Programmer's Guide, SC33-0008
IBM system/360 Operating System PLII (F) Programmer's Guide,
GC28-6594
IMS/VS Application Programming Reference Manual, SH20-9026
DLtI D~S Application Programming Reference Manual,
SH12-5411
DLtI DOS/yS utilities and Guide for the System Programmer, S812-5412
IBM 3270 Information Display System Component Description, GA27-2749
Component Description:
IBM 2721 Portable Audio Terminal, GA27-3029
IBM 2780 Data Transmission Terminal Component Description, GA27-3035
584
CICS/VS APRM(ML)
Availability of Publications
The availability of a publication is indicated by its use key, vhich is
the first letter in the order number. The use keys and their meanings
are:
G
Generally available: Provided to users of IBM systems,
products, and services without charge, in quantities to meet
their normal requirements. Can also be purchased by anyone
through IBM branch offices.
S
Sold:
L
Licensed material, property of IBK: Available only to
licensees of the related program products under the terms of
the license agreements.
Can be purchased by anyone through IBM offices.
Bibliography
585
Index
Each page number in this index refers to the start of the paragraph containing the
indexed item.
%INCLUDE statement
19
ABCODE operand
DFBPC 406
ABEND
exit processing 399
ABEND type of DFHPC macro 397
abnormal termination
ABEND exit processing 399
activate ABEND exit 399"
cancel ABEND exit 399
reactivate ABEND exit 400
transaction 397
abnormal termination on data set
(DFHDI)
331
addition of records (DFHDI macro)
327
address of TIOA 164
addre ssabili ty
application program 19
BMS operation 275
common system area (CSA)
Assembler language 37
COBOL 48
PL/I 59
common work area (CWA)
Assembler language 37
COBOL 48
PL/I 60
file input/output area (FIOA)
Assembler language 39
COBOL 50
PL/I 61
file uork area (FWA)
Assembler language 40
COBOL 51
PL/I 62
journal control area (JCA)
Assembler language 43
COBOL 53
PL/I 65
storage accounting area (SA!)
Assembler language 43
COBOL 53
PL/I 64
storage area 31
task control area (TCA)
COBOL 49
PL/I 60
temporary storage input/output area
(TSIOA)
Assembler language 42
COBOL 53
PLjI 64
terminal control table terminal entry
(TCTTE)
Assembler language 38
COBOL 48
PL/I 60
terminal input/output area (TIOA)
Assembler language 39
COBOL 50
addressability
(continued)
terminal input/output area (TIOA) (continue
PL/I 61
transaction work area (TWA)
COBOL 49
PL/I 60
transient data input area (TDIA)
Assembler language 41
COBOL 52
PL/I 63
transient data output area (TDOA)
Assembler language 41
COBOL 52
PL/I 63
VSAM work area (VSWA)
Assembler language 40
COBOL 51
PL/I 62
addressability for DFHTC macro 163
AID byte 164,231
alternate index 76
alternate key 76
APLHA operand
DFHBIF 486
application programs
addressability 19
basic characteristics 13
CICS/VS macro instruction 9
communication and logical
relationships 389
communication with operating system
restrictions 9
considerations of virtual storage 16
CWA restriction 35
deleting 396
general structure 15
initialization 19
languages 13
link-editing 22
linking programs 391
need for CSA and TCA 27
object module size restriction 23
overlay restriction 17
packaging 17
quasi-reenterability 18
register usage 19
rest rictions 20
storage definition 27
system environment 13
techniques 13,16,17
testing and debugging 496
transfer of control 19
ARG operand
DFHBIF 486
ARGTYP operand
DFHFC 126
Assembler language
addressability of storage areas 31
addressability requirement 19
CSA, common system area 37
CSW, common work area 37
FIOA, file I/O area 39
Index
587
Assembler language
(continued)
FWA, file work area 40
JCA, journal control area 43
link-editing 22
program examples (see program examples)
register usage 19
SA!, storage accounting area 43
storage definitions 37
example of copying 44
TCT~E, terminal control table terminal
entry 38
TDIA, transient data input area 41
TDOA, transient data output area 41
TIOA, terminal I/O area 39
transfer of control
19
TSIOA, temporary storage I/O area 42
TWA, transaction work area 38
VSWA, VSAM work area 40
Assembler languages
restrict ions 20
assembly-time service 23
asynchronous journal output 531
asynchronous transaction processing 419
ATABLE operand
DFHBIF 486
ATI (automatic task initiation)
418
ATTACH type of DFHKC macro 368
attaching tasks 368
ATTRB operand
DFHMDF 267
attributes, symbolic 304
autoanswer (3735)
212
autocall (3735)
213
automatic task initiation (ATI)
418
auxiliary trace 506
backout recoverable resources 546
base addresses 31
BA SE operand
DFHMSD 250
basic mapping support (BMS)
abnormally terminating a logical
message 294
address of data 275
address of TIOA 275
advantages 235
block data format
237
condition codes 297
copying symbolic maps 245
data mapping and formatting
237
data, address of 275
device independence 235
DFHAID 304
DFHBMSCA 304
disposition and message routing 296
establishing addressability 275
facilities 236
field data format 237
field definition macro 265
format independence 236
implied read/write
274
input mapping 242
input operations 278
input/output mapping 244
introduction to 235
map building 241
map definition macro 259
588
CICS/VS APRM(ML)
basic mapping support (BHS)
(continued)
map positioning 281
map retrieval 244
map set definition macro 248
message recovery 303
message routing
238
non-cumulative page building 291
non-terminal-oriented tasks 275
output mapping 243
page building examples 283
page building with mapping 280
page building without mapping 290
PAGEBLD overflow processing 287
paging commands on video devices 305
physical map 240
printer control characters 304
program examples
map definition 561
test response code
302
programming considerations 240
response codes 301
specifying maps 242
standard attention identifier list 304
standard attribute list 304
status flag byte 297
symbolic description map 240
terminal code table 303
terminal paging 238
terminating a logical message 293
test response
300
text data format 237
TIOA address 275
trailer maps 288
using maps 274
Batch Data Interchange (DFHDI macro)
DFHDI macro 327
Batch Data Interchange LU (3770)
216
Batch Data Interchange LU (3790)
218
Batch LU (3770)
216
batch mode (3740)
214
batch processing 3
bit manipulation
macro instruction 466
returned values 469
BIT operand
DFHBIF 487
BITEST type of DFHBIF macro 468
BITFLIP type of DFHBIF macro 468
BITO FF op e ra nd
DFHBIF 487
BITON operand
DFHBIF 487
BIT SETOFF type of DFHBIF macro 467
BITSETON type of DFHBIF macro 466
BHS (see basic mapping support)
bracket 176
bracket protocol
176
browsing
abnormal condition handling 110
backwards 114
description of 74
error handling
110
examples
initiate browse operation 107
reset sequential retrieval
118
retrieve next sequential record 110
terminate sequential retrieval 116
forward
109
browsing (continued)
generic key 105
initiate 105
multiple browse
record identification field 81
operation 7 q
partial key 105
reset 118
sequential retrieval 105
skip-sequential processing 75
start browse 105
terminate 116,118
BTAM programmable devices 179
built-in functions 453
bit manipulation 466
copying storage referred to by BIF 455
field edit 465
field verify 463
input formatting 470,472
listing of 453
phonetic conversion 460
table search 457
example using complex table 459
example using separate tables 458
weighted retrieval 477
cancel INITIATE or PUT request 358
CANCEL operand
DFHPC 406
cancel POST request 357
CANCEL type of DFHIC macro 357
cancel WAIT request 358
card-reader-in/line-printer-out (CRLF)
501
CCOMPL operand
DPHTC 222
CCOMPL=NO operand 171
chain 170
chain assembly 171
for LUTYPE4 172
chaining of input data 170
chaining of output data 171
chaining of storage areas 32
CHAP type of DPHKC macro 373
CHECK type of DPHBMS macro 300
CHECK type of DPHPC macro 121
DL/I form 145
CHECK type of DPHIC macro 360
CHECK type of DPBJC macro 539
CHECK type of DPHPC macro 404
CHECK type of DPHTD macro 428
CHECK type of DPHTS ma.,·o 444
CICS type of DPHDC macro 516
CICS/VS (see Customer Information Control
system)
CLASS operand
DFHSC 414
COBADOR type of DFHPC macro 403
COBOL
addressability and optimization
feature 55
addressability of storage areas 31
area size restriction in linkage
section 54
CSA, common system area 48
CWA, common work area 48
data constant location 47
PIOA, file I/O area 50
COBOL
(continued)
PWA, file work area 50,51
guidelines, storage definition 54
JCA, journal control area 53
link-editing 22
OCCURS DEPENDING ON clause usage 54
optimization feature restrictions 55
program examples ~ee program examples)
register usage 19
restrictions 20
SA!, storage accounting area 53
SERVICE RELOAD 55
storage definitions 47
example of copying 57
TCTTE, terminal control table terminal
entry 48
TDIA, transient data input area 52
TOOA, transient data output area 52
TIOA, terminal I/O area 49
transfer of control 19
TSIOA, temporary storag~ I/O area 52
TWA, transaction work area 49
variable data location 47
VSWA, VSAM work area 51
working storage size restriction 55
working storage, use of 47
code translation 161
COLOR operand 251
OPHMDP 269
DFHMDI 259
DFHMSD 251
COLUMN operand
DPHMDI 259
common system area (CSA)
addressability of
Assembler language 37
COBOL 48
PL/I 59
contents of 33
CWA 35
storage definition
Assembler language 37
COBOL 48
PL/I 59
common work area (CWA)
address ability of
Assembler language 37
COBOL 48
PL/I 60
addressability restriction 35
size 35
storage definition
Assembler language 37
COBOL 48
PL/I 60
uses of 35
COMPLETE type of DFHDC macro 517
component of CICS/VS 6
CONO operand
DPHJC 541
DPHKC 386
DFHPC 406
DPHSC 414
DFHTS 447
CONNECT opera nd
DPHTC 222
converse with a terminal or LU 161
convert label to address 403
Index
589
COpy statement 19
copying storage definitions (see storage
definitions)
CRlP (card-reader-in/line-printer-out)
501
cross-index data set 76
CSA (see co mmon sy st em area)
CTlCHAR operand
DFHTC 223
CTRl operand
DFHBMS 301
DFHMSD 251,260
cursor address 164,231
CURSOR operand
DFHBMS 309
Customer Information Control
System/Virtual Storage
assembly-time service 23
batch vs online 15
built-in functions 453
data base concept 4
dump services 513
execution mode 7
macro instructions 9
major components 6
major functions 3
online environments 13
sample programs 549
sequential terminal support 501
storage dump 516
system management functions 6
transaction flow 1
virtual storage environment 16
CiA (see common work area)
DAM data set
adding records 84
fixed, keyed 85
fixed, non-keyed 85
formatting data set 85
RDF, record descriptor field 86
undefined 85,86
variable 85,86
block reference 82
browse operation 105
deblocking 83
direct retrieval 81
extended search option 85
physical key 82
record identification field 82
retrieval method 132
update a record 86
updating nonkeyed 84
logging restriction 84
data base concept 4
data base/data communication ~B/DC) 3
data handling (2980)
193
Data Language/I (DL/I)
acquiring an I/O work area 138
building segment search arguments 137
call statement 140
PSB, schedule the 137
release PSB 141
Dl/I requests
Assembler language 146
COBOL 148
Pl/I 150
message routing restriction 295
590
CICS/VS APRM(ML)
Data language/I (Dl/I)
(continued)
PCB, obtain addresses 136
program communication blocks (PCB)
135
program examples
Assembler language 146
COBOL 148
PL/I 150
programming requirements 135
PSB, schedule the 136
quasi-reenterability considerations 135
releasing a PSB 141
requesting services 139
requesting services of 135
response codes 143
data length for write to terminal or
LU 164
data mapping and formatting ~MS) 231
DATA operand
DFHBMS 310
DFHMDI 261
DFHMSD 252
data set
cross-index 16
index 16
primary 76
target 16
data set name
DATASET operand 126
DATAID operand
DFHTS 441
DATASET operand
DFtlBIF 487
DFHFC 126
DATAl operand
DFHTR 509
DATA1TP operand
DFHTR 5~9
DATA2 operand
DFHTR 509
DATA2TP operand
DFHTR 509
DCI operand
DFHKC 386
DCT (destination control table)
417
DEEDIT type of DFHBIF macro 465
deferred journal output 531
definite response 112
DEFLDNM type of DFHBIF macro 413
DEFRESP operand 112
DFHDI 336
DFHTC 223
delay task 346
delete a program 396
DELETE type of DFHFC macro 99
DELETE type of DFHPC macro 396
deletion of records CDFHDI macro) 328
DEQ type of DFHKC macro 381
DEST operand
DFHTC 223
DESTID operand
DFHTD macro 431
destination control table (DCT)
411
destination of data 114
DFBAID 164,231,304
DFHBFTCA macro instruction
operands 455
operation of 455
DFHBIF macro instruction
examples (see program examples)
operands 486
prerequisites 453
TYPE=BITEST
operands 468
TYPE=BITFLIP
operands 468
TYPE=BITSETOFF
operands 467
TYPE=BITSETON
operands 466
returned values 469
TYPE=DEEDIT
operands 465
returned values 465
TYPE=DEFLDNM
operands 413
operation of 473
required delimiters 413
TYPE=FVERIFY
operands 463
returned values 463
TYPE=INFORMAT
operands 474
operation of 474
returned values 475
TYPE=PHONETIC
error codes 460
operands 460
phonetic coding method 461
returned value 460
TYPE=TSEARCH
complex table 459
operands 457
returned values 457
separate tables 458
TY PE=WTR ETCHK
operands 482
TYPE=HTR ETGET
operands of 481
operation of 481
returned values 481
'r!PE=RTRETREL
operands 482
operation of 482
TYPE=HTRETST
operands 480
returned values 480
TYPE=WTRTPARM
operands 480
operation of 480
DFHBMS macro instruction 276
examples (see program examples)
operands, list of 307
TYPE=CHECK
operands 300
TYPE=IN
operands 278
operation of 278
TYPE=MAP
operands 277
TYPE=OUT
operands 291
operation of 291
TYPE=PAGEBLD
operands 280
opera tion of 280
DFHBMS macro instruction
(continued)
TYPE=PAGEOUT
operands 293
operation of
293
TYPE=PURGE
operands 294
operation of 294
TYPE=ROUTE
operands 296
operation of 295
TYPE =TEXTBLD
operands 290
operation of 290
DFHBM SCA 304
DFHCOVER macro instruction 23
DFBDC macro instruction
examples (see program examples)
listing of services 513
operands 520
requirements 513
TYPE=CICS
operands 516
operation of 516
TYPE=COMPLETE
operands 511
operation of 517
TYPE=PARTIAL
operands 518
operation of 518
TYPE=TRANSACTION
operands 515
operation of 515
DFHDI macro
abnormal termination operations on data
set 331
addition of records 321
deletion of records 328
interrogation of data set 330
operand s
336
relative record number 333
replacement of records 329
response codes 335
suspend execution of task 333
terminate operations on data set 330
test response 334
transmission of data 331,332
TYPE=ABORT 331
TYPE =ADD 327
TYPE=CHECK 334
TYPE=END 330
TYPE=ERASE 328
TYPE=NOTE 333
TYPE=QUERY 330
TYPE=RECEIVE 332
TYPE=REPLACE 329
TYPE=SEND 331
TYPE =WAIT 333
DFHFC macro instruction
examples (see program examples)
listing of services 73
operands 126
segmented records 133
TYPE= (DL/I ,PCB)
operands 136
TYPE= (DL/I,T)
operands 141
TYPE=CHECK
operands 121,145
Index
591
DPBPC macro instruction
(continued)
TYPE=CBECK (continued)
response codes 121
TYPE=DELETE
operands 99
operation of 99
TYPE=DL/I
operands 139
TYPE=ESETL
operands 116
operation of 116
TYPE=GET 87
CICS/VS services for 87
data set name 126
index identification 128
operands 87
prerequisites 81
segment set identification 133
TYPE=GETAREA
CICS/VS services for 100
operands 100
operation of 100
prerequisites 100
TYPE=GETNEXT
CICS/VS services for 109
operands 109
operation of 109
prerequisites 109
TYPE=GETPREV
CICS/VS services for 114
operands 114
operation of 114
prerequisites 114
TYPE=PUT 96
CICS/VS services for 96
operands 96
requirements 97
TYPE=RELEASE
CICS/VS services for 103
operands 103
operation of 103
prerequisites 103
TYPE=RESETL
operands 118
operation of 118
TYPE=SETL
CICS/VS services for 106
operands 105
opera tion of 105
prerequisites 106
DPHIC macro instruction
examples (see program examples)
listing of services 343
operands 363
TYPE=CANCEL
operands 351
operation of 357
TYPE=CHECK
operands 360
TYPE=GET
operands 355
operation of 355
TYPE=GETIME
operands 344
operation of 344
TYPE=INITIATE
operands 350
operation of 350
592
CICS/VS APRM(ML)
DPHIC macro instruction
(continued)
TYPE=POST
operands 348
operation of 348
TYPE=PUT
operands 352
operation of 352
TYPE=RETRY
operands 359
operation of 359
TYPE=WAIT
operands 346
operation of 346
DPHJC macro instruction
examples (see program examples)
operands 541
TYPE=CHECK
operands 539
TYPE=GETJCA
operands 525
operation of 525
TYPE=PUT
operands 527
operation of 521
TYPE=WAIT
operands 536
operation of 536
TYPE=WRITE
operands 531
operation of 531
DF8KC macro instruction
examples (see program examples)
listing of services 361
operands 386
TYPE=ATTACH
caution of use 369
operands 368
operation 368
requirements for 368
TYPE=CHAP
operands 373
operation of 373
TYPE=DEQ
operands 381
operation of 381
requirements for 381
TYPE=ENQ
operands 379
operation of 379
requirements for 380
TYPE=NOPURGE
operands 384
operation of 384
TYPE=PURGE
operands 384
operation of 384
TYPE=WAIT
operands 315
operation of 315
requirements for 375
DFHMDF macro instruction
operands 265
operation of 265
DFHMDI macro instruction
operands 259
operation of 259
DFH!SD macro instruction
operands 248
DPHHSD macro instruction
(continued)
operation of 248
)PHPC macro instruction
examples (see program examples)
listing of services 389
operands 406
TYPE=ABEND
operands 397
operation of 397
TYPE=CHECK
operands 404
TYPE=COBADDR
operands 403
operation of 403
TYPE=DELETE
operands 396
opera tion of 396
requirements for 396
TYPE=LINK
operands 391
operation of 391
requirements for 391
TYPE=LOAD
operands 393
operation of 393
prerequisites 393
TYPE=RESETXIT
operands 402
operation of 400
TYPE=RETURN
operands 395
operation of 395
requirements for 395
TYPE=SETXIT
operands 399
operation of 399
TYPE=XCTL
operands 392
operation of 392
requirements for 392
DFHSC macro instruction
examples (see program examples)
operand 414
TYPE=PREEMAIN
operands 412
operation of 412
prerequisites 412
TYPE=GETMAIN
operands 410
operation of 410
prerequisites 410
DFHSP macro instruction
backout recoverable resources 546
operation of 545
TYPE=ROLLBACK 546
TYPE=USER 545
DPHTC macro instruction 220
addressability to the TCTTE and
TIOA 163
data length 164
examples (see program examples)
FHH length 164
incompatible options 162
list of services 161
LUTYPE4 logical unit 220
operands 222
other CICS/VS supported terminals 221
DFHTC macro instruction
(continued)
printer authorization
matrix 197,198,200
program testing and debugging 502
storage definition for TCTTE and
TIOA 163
syntax 179
System/3 182
System/370 182
System/7 183
TCAM supported LUs 221
TIOA acquisition for vrite 164
TIOA address 166
TIOA dumping 165
2260 Display station 185
2265 Display Station 186
2740 Communication Terminal 186
2741 Communication Terminal 187
2770 Data Communication System 190
2780 Data Transmission Terminal 190
2980 data handling 193
2980 General Banking Terminal 191
2980 passbook control 191
2980 segmented writes control 192
3270 (2260 compatibility)
203
3270 BTAM 197
3270 compatibility logical unit 217
3270 local copy 197,198,200
3270 logical unit 198
3270 LUTYPE2 logical unit 200
3270 LUTYPE3 logical unit 201
3270 SCSPRT logical unit 202
3270 switchable screen
sizes 197,199,200
3600 (3601) LU 208
3600 (3614) LU 208
3600 BTAM 205
3600 pipeline logical unit 208
3600 Supermarket System 211
36 50 (3 653) LU 2 10
3650 host command processor LU 209
3650 host conversational (3270) LU 209
3650 Interpreter LU 211
3650 output device control 209
3650 pipeline logical unit 210
3650(3270) erase function 210
3735 Programmable Buffered Terminal 212
3740 Data Entry System 214
3767 Interactive LU 215
3770 Batch Data Interchange LU 216
3770 Batch LU 216
3770 full function LU 216
3770 Interactive LU 215
3780 Data Communications Terminal 216
3790 (3270-Oisplay) LU 217
3790 (3270-Printer) LU 217
3790 batch data interchange LU 218
3790 Full Function LU 217
3790 Inquiry LU 217
3790 SCS Printer LU 217
7770 Audio Response unit 219
DFHTD macro instruction
examples (see program examples)
listing of services 418
operands 431
TYPE=CHECK
operands 428
Index
593
DFHTD macro instruction (continued)
TYPE=FEOV
operands 426
operation of 426
TYPE=GET
operands 423
operation of 423
TYPE=PURGE
operands 427
operation of 427
TYPE=PUT
operation of 421
requirements of 421
DFHTR macro instruction
operands 509
TYPE=ENTRY
opera nds 508
TYPE=OFF
operands 508
TYPE=ON
operands 507
DFHTS macro instruction
examples (see program examples)
listing of services 434
operands, list of 447
TYPE=CHECK
operands 444
TYPE=GET
operands 438
operation of 438
TYPE=GETQ
operands 441
opera tion of 438
TYPE=PURGE
operands 443
operation of 442
TYPE=PUT
operands 435
operation of 435
TYPE=PUTQ
operands 437
operation of 435
TYPE=RELEASE
operands 442
operation of 442
disconnect a logical unit 167
disconnect a switched line 167
DL/I (see Data Language/I)
DL/I type of DFHFC macro
DLINA operand
DFHFC DL/I services 152
DM PCODE operand
DFHDC 520
DNADDR operand
DFHDI 336
DSECT type of DFHMSD macro 248
DSIDER operand
DFHBIF 487
DFHFC 126
DSSTAT operand
DFHDI 336
dump of TIOA 165
dump services 513
CICS/VS storage dump 516
macro instruction 513
partial storage dump 518
examples 518
594
CICS/VS APRM(ML)
dump services (continued)
transaction and CICS/VS storage
dump 517
transaction storage dump 515
DUPDS operand
DFHFC 126
DUPKEY operand
DFHFC 127
duplicate record 79
DUPREC operand
DFHFC 127
ECADDR operand
DFRKC 387
ECBs 369
end of data set (EODS)
174
ENDDATA operand
DFHIC 363
ENDFILE operand
DFHBIF 487
DFRFC 127
DFHTC 224
ENDINPUT operand
DFHTC 224
ENDMSG operand
DFRTC 224
ENERROR operand
DFHTS 447
ENQ type of DFHKC macro 379
ENTRY operand
DFRTS 447
ENTRY type of DFRTR macro 508
EOC indicator 170
EOC operand 170
DFHBMS 311
DFRTC 225
EODPURG operand
DFHBMS 311
EODS ~nd of data se~
174
EODS operand
DFHBMS 311
DFHDI 336
DFHTC 225
EOF operand
DFdTC 225
error codes
DFHBIF
TYPE=PHONETIC 460
phonetic conversion 460
ERROR operand
DFHBIF 488
DFHBMS 311
DFHFC 127
DFHIC 363
DFHTS 447
ERRTERM operand
DFHBMS 311
ESETL type of DFRFC macro 116
examples of programs (see program
exception response 172
exclusive control, release 103
expiration of specified time 348
EXPIRD operand
DFHIC 363
EXTATT operand 253
DFHMSD 253
exa~ples)
extended search option
extrapartition data sets
alignment requirements 424
data 417
forced end of volume 426
indirect destinations 411
queue 411
facilities for logical units 169
FCADDR operand
DFHKC 387
FEOV type of DFHTD macro 426
field definition macro (BMS)
265
field edit
macro instruction 465
operation 465
returned values 465
FIELD operand
DFHBIF 488
field verify
macro instruction 463
operation 463
returned values 463
FIELDS operand
DFHBIF 488
FIELD1 operand
DFHBIF 488
FIELD2 operand
DFHBIF 489
file I/O area (PIOA)
addressability of
Assembler language 39
COBOL 50
PL/I 61
storage definition
Assembler language 39
COBOL 50
PL/I 61
use in file services 73
file serv ices
access methods 73
accessing a record 88
browsing 74
data york areas 73
delete data 99
direct retrieval B7
file control 73
file management 73
generic delete 99·
group delete 99
introduction to 73
mass insert 103
obtain a file work area 100
priority of 74
program examples
building a new record 100
check response code 124
initiate browse operation 107
obtaining an PHA 100
random read-only operation 89
random retrieval for update 92
random retri~val via indirect
access 94
random update or add data 97
releasing an PiA 104
reset sequential retrieval 118
retrieve next sequential record
file services
(continued)
program examples (continued)
terminate sequential retrieval 116
VSAH locate mode IIO 91
read-only retrieval 87
release file storage 103
reset sequential retrieval 118
response codes 121
retrieval for update 87
retrieval via indirect access 94
retrieve next sequential record 109
retrieve previous sequential record 114
sequential retrieval 105
summary of 6
terminate sequential retrieval 116
update or add data 96
file work area (PWA)
addressability of
Assembler language 40
COBOL 51
PL/I 62
obtaining 100
release file storage 103
storage definition
Assembler language 40
CaBO L 51
PL/I 62
use in file services 73
PINAL type of DFHMSD macro 248
FIOA (see file IIO area)
fixed block architecture (PBA)
73
PMH (function management header)
173
FMH length 164
PHH operand
DFHTC 225
PHH, inbound 173
FHH, outbound 173
PI1HPARM operand
DPHBMS 312
POC indicator 170
force end of volume (transient data)
426
PORCE operand
DFHTC 226
FORH operand
DPHIC 363
format notation of macros 10
forms, different types 174
FREEMAIN type of DPHSC macro 412
PTABLE operand
DFHBIF 489
FUNCERR operand
DFHDI 336
FUNCNS operand
DFHFC DL/I services 152
function management header (PMH)
173
functions of CICS/VS 3
PVERIFY type of DFHBIF macro 463
FW A (se e file work area)
110
generic key 81,105
GET type of DPHFC macro 87
GET type of DPHIC macro 355
GET type of DFHTC macro 166
GET type of DFHTD macro 423
GET type of DFHTS macro 438
GETAREA type of DFHPC macro 100
GETIME type of DFHIC macro 344
Index
595
GETJCA type of DPHJC macro 525
GETMAIN type of DPBSC macro 410
GETNEXT type of DPBPC macro 109
GETPREV type of DPBPC macro 114
GETQ type of DPHTS macro 441
GRPNAME operand
DPBMDP 269
hard request-change-direction signal
HEADER operand
DPHBI!S 312
DPHMDI 261
BILIGHT operand 253,269
DPHMDP 269
DPHMDI 261
DPHMSD 253
HTAB operand
DPHMSD 254
175
I/O PCB (input/output program control
blocks)
136
ICDADDR operand
DPHIC 363
ID operand
DPHTR 510
IDERROR operand
DPHJC 541
DPHTD macro 431
DPHTS 448
IGREQCD ope rand
DPHBMS 313
IGR EQID operand
DPHBMS 313
ILLOGIC operand
DPHPC 127
IN type of DPBBMS macro 278
INBPMH operand 173
DPBTC 226
inbound PMH 173
incompatible options on DFHTC macro 162
index data set 76
index identification
INDEX operand 128
INDEX operand
DFHBIF 490
DFHPC 128
index, alternate 76
indirect accessing 76
duplicate record 79
INPORMAT type of DPHBlF macro 474
INITIAL operand
DFHMDF 270
initiate a task 368
INITIATE type of DFHIC macro 350
INITIMG operand
DPHFC 128
DFBSC 415
input formatting
combination input 472
fixed format 470
keyword format
macro instructions 473,474
opera tion 471
required delimiters 473
returned values 475
;96
CICS/VS APRM(ML)
input formatting
(continued)
positional format
macro instruction 474
operation 470
returned values 475
storage definition 472
input mapping (BMS)
242
input/output mapping (BMS)
244
input, unsolicited
175
INPUTNO operand
DPBBIF 490
INPUTPC operand
DFHBIF 490
INPUTST operand
DPHBIP 491
inter~ecord separator (IRS) character
interrogation of data set (DPHDI
macro)
330
intrapartition data sets
data 417
indirect destinations 417
purge 427
queue 417
INTRVAL operand
DPHBMS 313
DFHIC 363
INVET operand
DFHBMS 314
INVLDC operand
DPHBMS TYPE=CHECK 314
IN VM PSZ operand
DFHBMS 314
INVREQ operand
DPHBlF 491
DFHBMS 314
DPHFC 128
DFHPC DL/I services 152
DFHIC 364
DFHJC 541
DPHTS 448
IOERROR operand
DPHBIP 491
DFllPC 128
DFHIC 364
DFHJC 541
DFHTD macro 431
DPHTS 448
IRS (inter-record separator) character
ISAM data set
record identification field 81
JCA (see journal control area)
JCDADDR operand
DPHJC 541
JCDLGTH operand
DPHJC 541
JCP (journal control program) 523
JCT (journal control table)
523
JPILEID operand
DPHJC 542
journal control area (JCA)
addressability of
Assembler language 43
COBOL 53
PL/I 65
storage definition
Assembler language 43
172
172
journal control area (JCA)
(continued)
storage definition (continued)
COBOL 53
PL/I 65
journal control program (JCP)
523
journal control table (JCT)
523
journal record 523
journal services
acquire the journal control area 525
asynchronous journal output 531
create a journal record 521,531
asynchronous journal output 531
synchronous journal output 521
deferred journal output 531
introduction to 523
journal management 523
journal record 523
journal record synchronization 536
priority of 523
program examples
acq~ire the journal control
a:t'ea 525
asynchronous journal output 532
journal record synchronization 536
synchronous journal output 521
requests for 523
response codes 539
summary of 1
synchronous journal output 527
test response 539
JTYPEID operand
DFBJC 5~2
JUSTIFY operand
DFHBMS 314
DFBMDF 210
DFHMDI 262
key, alternate 16
KEYADDR operand
DFBDI 336
LABEL operand
DFHBIF 491
DFHPC 406
LANG operand
DFHMSD 254
LANGCON operand
DFHFC DL/I services 152
LAST parameter
DFHBMS TYPE=PAGEOUT 294
LDA (logical device address)
174
LDC (logica 1 device code)
114
LDC operand
DFHBMS 315
DFHMSD 254
DFHTC 226
LENGTH operand
DFHBIF 491
DFHMDF 211
LERROR operand
DFHJC 542
line control 161
~INE operand
DFHMDI 262
INEADR operand
DFHTC 227
LINK type of DFHPC macro 391
link-editing 22
linking programs 391
LI ST op erand
DFHBKS 316
DFBDC 520
load a VSAM data set 14
LOAD type of DFHPC macro 393
loading a program 393
LOADLST operand
DFHPC 406
locality of reference 16
locate mode 88,106
logical device address (LDA)
114
logical device code (LDC)
114
logical record presentation 111
logical unit (LU)
161
logical unit (TCAM-supported)
221
logical unit facilities 169
logical unit of work (LUW)
545
logical units supported by TCAM 119
LU (log ical unit)
161
LUTYPE2 logical unit 200
LUTYPE3 logical unit 201
LUTYPE4
chain assembly of response units 172
LUTYPE4 logical unit 220
LUW (logical unit of work)
545
macro instruction
DFHFC 13
macro instructions
DFHBF 450
DFHBFTCA macro instruction 455
DFHBMS macro instruction 276
DFHDC macro instruction 513
DFHFC macro instruction
DL/1 forms 135
DFHIC macro instruction 343,344
DFHJC macro instruction 523
DFHKC macro instruction 367,369
DFH~DF macro instruction
265
DFHMDI macro instruction 259
DFHMSD macro instruction 248
DFHPC macro instruction 389,391
DFHSC macro instruction 409,410
DFHSP macro instruction 5~5
DFHTC 162
DFHTD macro instruction 418,421
DFHTS macro instruction 434,437
general format 9
name field restriction 9
operand field rules 9
operation field rules 9
syntax notation 10
map building ~MS)
241
map definition macro 259
MAP operand
DFHBMS 318
map positioning 281
map retrieval ~aS)
244
map set definition macro 248
MAP type of DFHBKS macro 217
KAP type of DFBMSD macro 248
MAPADR operand
DFHBM~
318
Index
597
MAPFAIL operand
DFHBMS 319
maps, copying symbolic 245
MAPSET operand
DFHBMS 319
mass insert 103
MATCH operand
DFBBIF 492
media selection in logical unit 331
message integrity 169
message recovery, BMS 303
message routing 295
disposition and message routing 296
DL/I restrictions 295
macro instruction 296
status flag byte 297
MOC indicator 170
MODE operand
DFHFC 129
DFHMSD 254
move mode 88
MSETADR operand
DFHBMS 319
multiple form printers 174
multithreading 13
NAMES operand
DFHBIF 492
new line (NL) character 172
NL (new line) character 172
node abnormal condition program 171
node error program 171
NOMATCH operand
DFHBIF 492
NONVAL operand
DFHTC 227
NOPURGE type of DPHKC macro 384
NORESP operand
DPHBIF 493
DFHBMS 319
DPHDI 337
DFHPC 130
DFBPC DL/I services 152
DPHIC 364
DFHJC 542
DFHTC 227
DFHTD macro 431
DPHTS 448
NOSPACE operand
DFBPC 130
DPHTD macro 431
DFHTS 448
NOTPND operand
DPHBIF 493
DFHFC 130
DPHIC 364
NOTOPEN operand
DPHFC 131
DFHFC DL/I services 152
DFHJC 542
DFHTD ma~ro 431
NOTOPEN operands
DFHBIF 493
NRECDS operand
DFHBIP 493
NULL operand
DFHBIP 493
598
CICS/VS APRM (ML)
NUMBYTE operand
DPBSC 415
NUMERIC operand
DFHBIF 494
NUMREC operand 337
DPHDI 337
OBPMT operand
DFHM DI 263
DFHMSD 255
OCCURS operand
DPHMDP 271
OFP type of DPHTR macro 508
OFLOW operand
DFHB IF 494
DPHBMS 319
ON type of DFHTR macro 507
OPCLASS operand
DPHBMS 319
operands of DPHDI macro 336
operands of DFHTC macro 222
OPTION operand 455
DFHBFTCA 455
ORDER operand
DFHBIF 494
OUT type of DFHBMS macro 291
outbound FMH 173
output mapping (BMS) 243
overlapping logical unit output
169
PACKED operand
DFHBIF 494
page building
COLUMN operand 283
examples 283
JUSTIFY operand 283
justify operands 282
LINE operand 282
map positioning 281
message routing 295
non-cumulative 291
operation 238
overflow processing 287,289
paging commands on video devices 305
returned pages 286
screen contents 281
terminating a logical message 293
trailer area 282
trailer maps 288
with mapping 280
without mapping 290
page queuing facility 434
page-out operations 17
PAGEBLD type of DPHBMS macro 280
PAGEOUT type of DPHBMS macro 293
paging commands on video devices 305
partial key 81,105
partial storage dump 518
PARTIAL type of DPHDC macro 518
passbook control (2980) 191
passing program control 391
PCB (program communication blocks)
135
PCB operand
DPHFC DL/1 services 152
PPXADDR operand
DPHJC 542
PFXLGTH operand
DFHJC 543
PGMIDER operand
DFHPC 407
phonetic conversion
error codes U60
macro instruction 460
operation 460
phonetic coding method 461
returned value 460
subroutine 461
PHONETIC type of DFHBIF macro 460
physical map ~MS)
240
PICIN operand
DFHMDF 272
PICOUT operand
DFHMDF 273
pipeline logical unit (3600)
208
pipeline logical unit (3650)
210
PL/I
addressability of storage areas 31
CSA, common system area 59
CWA, common work area 60
FIOA, file I/O area 61
FWA, file work area 62
JCA, journal control area 65
link-editing 22
program examples (see program examples)
REENTRANT requirements 59
register usage 19
restrictions 22
SAA, storage accounting area 64
storage definitions 59
example of copying 66
required order of definition 59
TCA, task control area 60
TCTTE, terminal control table terminal
entry 60
TDIA, transient data input area 63
TDOA, transient data output area 63
TIOA, terminal I/O area 61
transfer of control 19
TSIOA, temporary storage I/O area 64
TWA, transaction work area 60
VSWA, VSAM work area 62
polling of terminals 161
POS operand
DFHMDF 266,274
POST type of DFHIC macro 348
posting ECBs 369
PRGNAME ope rand
DFHTC 227
primary data set 76
print requast facility (3270)
198
printer authorization matrix 197,198,200
printer control characters (BMS)
304
priority of a task 373
program communication blocks (PCB) 135
program examples
basic mapping support (BMS)
561
map definition 561
test response code 302
built-in functions
copying storage referred to by
BIP 455
table search using complex
table 459
program examples
(continued)
built-in functions (continued)
table search using separate
tables 458
copying storage definitions
Assembler language 44
COBOL 57
PL,/I 66
Data Language/I (DL/I)
Assembler language 146
COBOL 148
PL/I 150
executable CICS/VS sample program
Assembler language 549
COBOL 555
PL/I 559
file services
building a new record 100
check response code 124
initiate browse operation 107
obtaining an FWA 100
random read-only operation 89
random retrieval for update 92
random retrieval via indirect
access 94
random update or add data 97
releasing an FWA 104
reset sequential retrieval 118
retrieve next sequential record 110
terminate sequential retrieval 116
VSAM locate mode I/O 91
journal services
acquire the journal control
area 525
asynchronous journal output 532
journal record synchronization 536
synchronous journal output 527
partial dump request 518
posting ECBs 369
storage services
abnormally terminate a
transaction 397
check response code 405
deleting a program 396
establish program exit 401
linking programs 391
loading a program 393
obtain and initialize main
storage 410
release main storage 412
transferring program control 392
task services
attaching tasks 371
change priority of a task 373
multiple events task
synchronization 377
relinquish control to higher
priority task 378
single event task
synchronization 375
single-server resource
synchronization 381
temporary storage services
check response code 445
free temporary data 442
retrieve temporary data 438
store temporary data 435
Index
599
program examples (cont5.nued)
tille services
check response code 361
retrieval of time-ordered data 356
signal for time expired 349
suspend task processing 346
task initiation with data 353
task initiation without data 351
time-of-day services 344
transient data services
acquire queued data 423
check response code 429
dispose of data 421
extrapartition alignment
requirements 424
forced end of volume 426
weighted retrieval 484
program initialization 19
PROGRAM operand
DFBPC
401
program services
abnormally terminate a transaction 391
communication and logical
relationships 389
convert label to address 403
delete a program 396
introduction to 389
load a program 393
logical levels 389
macro instruction 391
pass control anticipating return 391
program management 389
response codes 404
return program control 395
summary of 1
test response 404
transfer control 392
program specification blocks (PSB) 135
program testing and debugging
card-reader-in/line-printer-out
(CRLP)
501
dump services 513
introduction to 496
sequential terminal support 501
trace services 503
programming considerations
data base considerations
adding records to DAM data sets
PROPT operand
DFHBMS 321
PRTI operand
DFHKC 381
PS operand 255
DFHKDF 213
DFHMDI 263
DFHMSD 255
PSB (program specification blocks)
PSB operand
DFHFC DL/I services 153
PSBFAIL operand
DFHFC DL/I services 153
PSBNA operand
DFHFC DL/I services 153
PSBUF operand
DFHFC DL/I services 153
PSBSCH operand
DFHFC DL/I services 153
PURGE type of DFHBMS macro 294
600
CICS/VS APRM (ML)
84
135
PURGE type of DFHKC macro 384
PURGE type of DFHTD macro 421
PURGE type of DFHTS macro 443
PUT type of DFHFC macro 96
PUT type of DFHIC macro 352
PUT type of DFHJC macro 521
PUT type of DFHTC macro 166
PUT type of DFHTD macro 421
PUT type of DFHTS macro 435
PUTQ type of DFHTS macro 431
QARGADR operand
DFHKC 381
QARGLNG operand
DFHKC 381
quasi-reenterability
QUEBUSY operand
DFTD macro 431
QUEZERO operand
DFHTD macro 431
18
random
retrieval for update
example of 92
retrieval via indirect access
update or add data
example of 91
RANGE operand
DFHBIF 494
RCD signal 115
RDATAl operand
DFHTR 510
RDATA2 operand
DFHTR 510
RDATT operand
DFHBl!S 321
DFHTC 228
RDIDADR operand 81
DFHBIF 496
DFHFC 131
structure 81
read attention (2141)
94
188
read from a terminal or LU 163
read-ahead queueing 169
ready message for 1110 166
record 15
duplicate 19
segmented 15
record identification
address of 131
record identification field
DAM data set 82
ISAM data set 81
multiple browse 81
RDIDADR operand 81
VSAM data set 81
recovery/restart services
summary of 1
sync point management 545
reenterable program 11
register usage 19
relative record number (DFHDI macro)
RELEASE operand
DFHIC
DFHSC
DFHTS
365
416
448
333
RBLBASE type of DFHFC macro 103
UELBASE type of DFHTS macro 442
alinquish control to higher priority
task 377
replacement of records (DFHDI macro)
329
REQID operand
DFHBMS 321
DFHIC 365
request-change-direction signal 175
requestjresponse unit (RU)
170
RBSETL type of DFHFC macro 118
RES&TXIT type of DFHPC macro 402
response codes
DL/I services 143
file control 121
interval control 360
journal control 539
methods of testing 23
program control 404
temporary storage control 444
transient data control 428
response codes (DFHDI macro)
335
restart ~ee recovery/restart)
restore recoverable resources 546
restrictions
Assembler language 20
COBOL 20
link-editing 22
object module size 23
overlays in application programs 17
PL/I 22
RETMETH ope rand
DFHFC 132
RETPAGE operand
DFHBMS 322
retrieve time-ordered data 355
RETRY type of DFHIC macro 359
return program control 395
RETURN type of DFHPC macro 395
ROLLBACK type of DPHSP macro 546
ROUTE type of DFHBMS macro 296
ROUTINE operand
DFBPC 407
RRNADDR ope rand
DFHDI 337
RTEFAIL operand
DFHBMS 322
RTESOME operand
DFHBMS 322
RU (request/response unit)
170
RU indicators (POC,MOC,EOC)
110
SAVE parameter
DFHBMS TYPE=IN 279
DFHBMS TYPE=MAP 277
scratch pad (temporary storage)
SCSPRT logical unit 202
SEGIDER operand
DFHFC 132
segment 75
segment set identification
SEGSET operand 133
segmented record 75
general rules 75
segmented writes control (2980)
SEGSET operand
DPHFC 133
6
192
SELECT operand
DPHDI 337
selecting media in logical unit 331
SELNERR operand
DFHDI 338
SEND/RECEIVE mode
169
sequential
terminal support 501
sequential retrieval
reset sequential retrieval 118
retrieve next sequential record 109
retrieve previous sequential record 114
skip-sequential processing 15
start browse 105
terminate sequential retrieval 116
service invocation
file services 73
journal services 523
program services 389
recovery/restart services 545
storage services 409
task services 367
temporary storage services 433
terminal services 161
time services 343
transient data services 417
SERVICE RELOAD 55
SETL type of DPHPC macro 105
SETXIT type of DPHPC macro 399
SIGADDR operand
DFHTC 228
signal commands from logical units 175
LU (logical unit)
signal command
175
single event task synchronization 375
single threading 13
SIZE op erand
DFHMDI 263
skip-sequential processing 75,110
SNA (Systems Network Architecture)
system 161
SNA protocols 169
SRC HTYP operand
DFHFC 133
SSALIST operand
DFHFC DL/I services 153
SSAS operand
DFBFC DL/I services 154
standard attribute list (BMS)
304
STARTIO operand
DFRJC 543
STATERR operand
DFHJC 543
storage accounting area (SAA)
addressability of
Assembler language 43
COBOL 53
PL/I 64
storage definition
Assembler language 43
COBOL 53
PL/I 64
storage areas
addressability of (see addressability)
base addresses 31
chaining 32
definitions (see storage definition)
required 33
Index
601
storage areas
(continued)
summary 29
symbolic names 32
storage definition
addressability 31
base addresses 31
chaining of storage areas 32
common system area (CSA)
Assembler language 37
COBOL 48
PL/I 59
common work area (CWA)
Assembler language 37
COBOL 48
PL/I 60
copying 31
file input/output area (FIOA)
Assembler language 39
COBOL 50
PL/I 61
fi Ie work area (FW A)
Assembler language 40
COBOL 51
PL/I 62
journal control area (JCA)
Assembler language 43
COBOL 53
PL/I 65
recommendation 18
required storage areas 33
storage accounting area (SAA)
43
Assembler language 43
COBOL 53
PL/I 64
storage accounting field 27
task control area (TCA)
Assembler language 38
COBOL 49
PL/I 60
temporary storage input/output area
(TSIOA)
Assembler language 42
COBOL 52
PL/I 64
terminal control table terminal entry
(TCTTE)
Assembler language 38
COBOL 48
PL/I 60
terminal input/output area (TIOA)
Assembler language 39
COBOL 49
PL/I 61
transaction work area (TWA)
Assembler language 38
COBOL 49
PL/I 60
transient data input area ~DIA)
Assembler language 41
COBOL 52
PL/I 63
transient data output area (TDOA)
Assembler language 41
COBOL 52
PL/I 63
VSAM work area (VSW~
40
Assembler language 40
COBOL 51
602
CICS/VS APRM (ML)
storage definition
(continued)
VSAM work area (VSWA) (continued)
PL/I 62
storage definition for DFHTC macro 163
storage definitions
Assembler language 37
COBOL 47
PL/I 59
STORAGE operand
DFHMSD 255
storage services
accounting for storage 409
activate ABEND exit 399
cancel ABEND exit 399
introduction to 409
macro instruction 410
obtain and initialize main storage 410
program examples
abnormally terminate a
transaction 397
check response code 405
deleting a program 396
establish program exit 401
linking programs 391
loading a program 393
obtain and initialize main
storage 410
release main storage 412
transferring program control 392
reactivate ABEND exit 400
release main storage 412
storage control 409
storage management 409
summary of 6
STORCLS op erand
DFHTS 448
STORFAC operand
DFBTS 449
strings, VSAM 104
STIPE operand
DFHTR 510
SUBST operand
DFHBIF 496
SUFFIX operand 256
DFHMSD 256
SUPPR operand
suspend data set 434
suspend execution of task (DFHDI
macro)
333
switchable screen sizes 197,199,200
symbolic description map (BMS) 240
sync point management
summary of 7
sync point 545
sync point, specify 545
synchronization of I/O 161
synchronize a task 375
synchronize terminal I/O
DFBTC TIPE=WAIT 166
return of control 166
synchronous journal output 527
syntax notation of macros 10
syntax of DFHTC macro 179
system management functions
file services 73
program services 389
recovery/restart services 545
storage services 409
system management functions
(continued)
sUIlcary of 6
task services 361
temporary storage services 433
time services 343
transaction flow 1
transient data services 411
System/3 182
System/310 182
system/1 183
systems network architecture (SNA)
system 161
table searc h
complex table 459
macro instruction 457
operation 457
returned values 457
separate tables 458
target data set 76
TARGET operand
DFHBIF 496
task control area (TCA)
addressability
COBOL 49
P;L/I 60
contents of 35
logical sections 35
storage definition
Assembler language 38
COBOL 49
PL/I 60
-task identification, sequance 177
task protection 169
task services
attaching tasks 368
change priority of a task 373
initiate a task 368
listing of 367
macro instruction 369
multiple events task
synchronization 371
program examples
attaching tasks 371
change priority of a task 373
multiple events task
synchronization 377
relinquish control to higher
priority task 378
single event task
synchronization 375
single-server resource
synchronization 381
relinquish control to higher priority
task 377
single event task synchronization 375
single-server resource
synchronization 379
summary of 7
synchronize a task 375
task control 367
task management 367
task purgeability on system
overload 384
task synchronization 375
task synchronization 346
TASKNA operand
DFHFC OL/I services 154
TCA (see task control area)
TCAM supported logical units 179
TCAM supported LO 221
TCAM supported terminals 179
TCTTE (see terminal control table terminal
entry)
TOADOR operand
OPHTD macro 432
TDIA (see transient data input area)
TOOA ~ee transient data output area)
teletypewriter programming 181
temporary storage I/O area (TSIOA)
addressability of 42
Assembler language 42
COBOL 53
PL/I 64
obtaining a 414
storage definition
Assembler language 42
COBOL 52
PL/I 64
temporary storage services
free temporary data 442
introduction to 433
macro instruction 437
page queuing facility 434
program examples
check response code 445
free temporary data 442
retrieve temporary data 438
store temporary data 435
response codes 444
retrieve temporary data 438
scratch pad 6
store temporary data 43S
summary of 6
temporary storage control 433
temporary storage management 433
test response 444
TERM operand
DFHMSD 256
terminal code table 303
terminal control table terminal entry
(TCTTE)
addressability of
Assembler language 38
COBOL 48
PL/I 60
storage definition
Assembler language 38
COBOL 48
PL/I 60
terminal I/O area (TIO!)
addressability of
Assembler language 39
COBOL 50
PL/l 61
data length warning 164
obtaining a 414
storage definition
Assembler language 39
COBOL 49
PL/I 61
terminal paging
BMS :l38,280
temporary storage services 434
Index
603
terminal services
accesS methods 161
code translation 161
line control 161
logical unit 161
polling 161
requests for 161
sequential devices 161
SNA system 161
summary of 6
synchronization of I/O 161
terminal control 161
transaction initiation 161
terminals supported by TCAM 179
terminate operations on data set (DFHDI
macro)
330
TERMNS operand
DFHFC DL/I services 154
test response
BMS services 300
journal services 539
methods of 23
program services 404
temporary storage services 444
time services 360
transient data services 428
weighted retrieval 482
test response (DFHDI macro)
334
TEXT parameter
DFHBMS TYPE=IN 279
TEXTBLD type of DFHBMS macro 290
TIMADR operand
DFHIC 365
time of day 344
Tn! E operand
DFBBMS 322
DFHIC 366
time services
cancel INITIATE or PUT request 358
cancel POST request 357
cancel WAIT request 358
delay task 346
expiration of specified time 348
introduction to 343
listing of 343
macro instruction 344
program examples
check response code 361
retrieval of time-ordered data 356
signal for time expired 349
suspend task processing 346
task initiation with data 353
task initiation without data 351
time-of-day services 344
response codes 360
response codes 360
retrieve time-ordered data 355
retry capability 359
summary of 7
task initiation with data 352
task initiation without data 350
task synchronization 346
test response 360
time of day format 344
time-of-day services 344
time-ordered data 355
time-ordered request cancellation 357
time-ordered task initiation 350
604
CICS/VS APRM(ML)
time-initiated (3735)
213
TIOA (see terminal I/O area)
TIOA acquisition for read 164
TIO! acquisition for write
164
TIOA address 164,166
TIOA for a chain 171
TIOA, reuse of 164,165
TIOAPFX operand
DFHMDI 264
DFHMSD 257
TITLE operand
DFHBMS 322
trace services
auxiliary trace 506
introduction to 503
trace control 504
trace entry format 504
trace ENTRY function 508
trace OFF function 508
trace ON function 507
trace table
duplicate entries 505
loca tion of 503
trace entry general format 504
trace header 504
TRAILER operand
DFHBMS 323
DFBMDI 264
transaction
flow 7
transaction and CICS/VS storage dump 517
transaction initiation 161
transaction storage dump 515
TRANSACTION type of DFHDC macro 515
transaction work area (TWA)
addressability of
COBOL 49
PL/I 60
addressability restriction 36
description of 36
size of 36
storage definition
Assembler language 38
COBOL 49
PL/I 60
transfer of control 19,392
TRANSID operand
DFHBMS 323
DFHIC 366
DFHKC 387
DFBPC 407
transient data input area (TDIA)
addressability of
Assembler language 41
COBOL 52
PLI 63
obtaining a 414
storage definition
Assembler language 41
COBOL 52
PL/I 63
transient data output area (TDOA)
addressability of
Assembler language 41
COBOL 52
PL/I 63
obtaining a 414
transient data output area (TDOA)
(continued)VALIDN operand (continued)
storage definition
DFHMDF 273
Assembler language 41
DFBMDI 264
COBOL 52
DFHMSD 257
PL/I 63
virtual storage
transient data services
concepts 16
acquire queued data 423
locality of reference 16
automatic task initiation (ATI) 418
techniques 16,18
dispose of data 421
validity of reference 16
extrapartition data 417
working set 16
forced end of volume 426
VOLADDR operand
indirect destinations 417
DFHDI 338
intrapartition data 417
VSAM data set
introduction to 417
access error requirement 74
macro instruction 421
adding several records at once 100
program examples
alternate index 76
acquire queued data 423
browse operation 105
check response code 429
browsing
dispose of data 421
random access 75
extrapartition alignment
skip-sequential processing 75
requirements 424
termination requirement 75
forced end of volume 426
direct retrieval 87
purge intrapartition data 427
exclusive control 89
response codes 428
ISAM compatibility mode 73
loading 74
summary of 6
test response 428
locate mode 73,106
transient data control 417
lockout 89
transient data management 417
mass insert 100,131
translation tables for the 2980 579
record identification field 81
transmission of data (DFHDI) 331,332
reusing 74
transparent ~RN) character 172
shared resources 74
TRMIDER operand
skip-sequential processing 110
DFHIC 366
strings limited in number 104
TRMIDNT operand
TYPE=RELEASE after error 74,89
DFHIC 366
TYPE=RELEASE requirements 97
TRN (transparent) character 172
variable-length records 88
TRNIDER operand
VSAM work area (VSWA)
DFHIC 366
addressability of
TSDADDR operand
Assembler language 40
DFHTS 449
COBOL 51
TSEARCH type of DPHBIF macro 457
PL/I 62
TSINVLD operand
storage definition
DFHIC 366
Assembler language 40
COBOL 51
TSIOA (see temporary storage I/O area)
TSIOERR operand
PL/I 62
DPHBMS 323
VSWA (see VSAM work area)
TWA (see transaction work area)
VTAB operand
TYPE operand
DFBMSD 258
DFHBMS 324
DFHMSD 249
TYPE= parameter
WAIT operand
DPHTC 228
DPHTC 234
TYPOPER operand
WAIT type of DFBIC macro 346
WAIT type of DFBJC macro 536
DFHPC 134
WAIT type of DPHKC macro 375
DPHTS 449
weighted retrieval
initiate 479
UNEXPIN operand
macro instructions 477
DPHDI 338
operation 477
unsolicited input 175
program example 484
USER type of DPHSP macro 545
release storage areas 482
using maps (BMS) 274
retrieve selected records 481
selection criteria 480
test response 482
VALID operand
working set 16
DPHTC 234
WRBRK operand
validity of reference 16
DPHBKS 326
VALIDN operand 257
DPHTC 234
Index
605
write break (2741) 188
write followed by a read 165
write to a terminal or LU 164
WRITE type of DFHJC macro 531
WRKAREA operand
DFHFC DL/I services 154
WTRETCHK type of DFHBIF macro 482
WTRETGET type of DFHBIF macro 481
WTRETREL type of DFHBIF macro 482
WTRETST type of DFHBIF macro 480
WTRTPARM type of DFHBIF macro 480
3270 local copy
197,198,200
3270 logical unit
198
3270 LUTYPE2 logical unit
200
3270 LOTYPE3 logical unit
201
3270 printer request facility
XCTL type of DFHPC macro
3270 read buffer
2260 compatibility (3270)
164,231
203
3270 SCSPRT logical unit
2260 Display station
202
185
3270 switchable screen sizes
2740 Communication Terminal
186
2741 Communication Terminal
read attention 188
write break 188
187
2741 read attention
2741 write break
198
392
188
3600 (3601) LO
208
3600
208
(3614) LO
3600 BTA!!
188
205
3600 pipeline logical unit
2770 Data Communication System
190
2780 Data Transmission Terminal
2980 General Banking Terminal
190
191
197,199,200
3600 Supermarket system
3650 P653) LU
208
211
210
3650 host command processor LO
209
3270 (2260 compatibility)
203
3650 host conversational (3270) LU
3270 attention identifier
164,231
3650 Interpreter LO
3270 BTA!!
197
3270 compatibility logical units
3270 data stream
217
164,231
3270 field attributes
30Q
3270 information display system
2260 compatibility mode ~ee 2260
compatibility mode (3270»
211
3650 output device control
209
3650 pipeline logical unit
210
3650(3270) erase function
3735 Programmable Buffered
Terminal 212,213
autocall 213
time-initiated 213
3740 Data Entry system
batch mode 214
606
CICS/VS
APRM(ML)
214
210
209
3753 Programmable Buffered Terminal
autoansuer 212
3767 Interactive LU
215
3770 Batch Data Interchange LU
3770 Batch tu
216
216
3770 full function LU
3770 Interactive tU
216
215
3780 Data Communications Terminal
3790 (3270-Display) tU
217
3790
217
(327 o-Prin ter) LU
3790 Batch Data Interchange tU
3790 Full Function LU
3790 Inquiry tU
212
216
218
217
217
3790 SCS Printer LU
217
7770 Audio Response unit
ready message 166
219
Index
607
SC33·0079·2
Q
(")
en
<
en
»
"0
"9..
~r
.-+
0'
::J
..,"'t:I
o
co
..,
Q)
3
3
en
..,
VJ~
:JJ
en
-+I
..,en
en
::J
"Sen
Q)
::J
C
Q)
s
Q)
..,"
o
r
en
<
~
..,
"'t:I
:;'
.-+
en
0-
:;'
C
en
~
en
(")
w
w
---- .=:®
___
-- - - -----9_
-
- --
-~-
6
o-...J
CD
"->
READER'S
COMMENT
FORM
Customer Information Control System/Virtual Storage (CICS/VS)
Application Programmer's Reference Manual (Macro Level)
SC33-0079-2
This manual is part of a library that serves as a reference source for systems analysts, programmers, and operators
of IBM systems. This form may be used to communicate your views about this publication. They will be sent
to the author's department for whatever review and action, if any, is deemed appropriate. Comments may be
written in your own language; use of English is not required;
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring
any obligation whatever. You may, of course, continue to use the infomlation you supply.
Note: Copies of IBM publications are /lot stocked at the location to which this form is addressed. Please direct
any requests for copies of publications, or for assistance in using your IBM system, Iv your IBM representative
or to the IBM branch office serving your locality.
Number of your latest Tedmical Newsletter for this publication ......................................... .
<1l
'"<1l
::,
'"'1l<1l
Ci:
...;
c:
<1l
E:
.9-
::,
t:t
<1l
tJ)
g
'2.... ~
0 .
'" s
~
.~
E:
~
<1l
CII
r::
"tJ
~
8'"
:::i
'1l
<1l
"C
E
8 ~
::J
'1l
"tJ
<1l
S E
.~
E:
::,
tJ)
-0
e
'0
Cl
r::
0
~
<1l
...
S
U
E ....
~
.c!l
0
0
::J
....
Q. 0
<1l
<1l
'"'1l::J '5
';;;
(.)
c: c:
<1l
'1l
'"
'"<1l ::J~
~ '"'"~
C/)
(.)
Q.
CII
'0
z
If you want an acknowledgement, give your name and address below.
Name
Job Title
Company
Address.
Zip
Thank you for your cooperation. No postage stamp is necessary if mailed in the U.S.A. (Elsewhere, your IBM
representative or I BM branch office will be happy to forward your comments.)
SC33-0079-2
Reader's Comment Form
and tape
Please do not staple
Fold and tape
. . . .... . . ..Fold. ........................................................................................................
,
No postage
necessary
if mailed
in the
United States
Q
(')
Cf)
<
BUSINESS REPLY MAIL
FIRST CLASS
PERMIT 40
Cf)
»
'0
~
Q'
ARMONK, NEW YORK
r-+
0'
::J
-u
...,
o
Postage will be paid by addressee:
,
International Business Machines Corporation
Department 812HP
1133 Westchester Avenue
White Plains, New York 10604
,,'if........
..
..).
to
...,
Q)
'''' ""'"
3
3
ctl
...,
I/l~
:0
ctl
ctl
...,
ctl
::J
n
ctl
~
Q)
Fold and tape
Please do not staple
Fold and tape
::J
C
Q)
~
Q)
n
...,
o
r
ctl
<
~
-.::®
... - . .- - ---....
_..--._
.. --
-
_
-~-y-
~
::J
r-+
ctl
a.
3'
c
en
~
Cf)
(')
w
w
6
o
......
c.o
~
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.3 Linearized : No XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37 Producer : Adobe Acrobat 9.31 Paper Capture Plug-in Modify Date : 2010:03:20 11:32:40-08:00 Create Date : 2010:03:20 11:32:40-08:00 Metadata Date : 2010:03:20 11:32:40-08:00 Format : application/pdf Document ID : uuid:59ad1df3-84d1-4eaa-a5c5-daee860e144f Instance ID : uuid:1e800ce0-b3f6-4d8a-ad90-a65470ccb0ec Page Layout : SinglePage Page Mode : UseNone Page Count : 624EXIF Metadata provided by EXIF.tools