TXSeries For Multiplatforms C++ Foundation Classes Programming Guide and Reference Version 6.2

TXSeries for Multiplatforms
C++ Foundation Classes Programming

Guide and Reference
Version 6.2
SC34-6633-02
C++ Foundation Classes Programming

Guide and Reference
Version 6.2
SC34-6633-02
Note
Before using this information and the product it supports, be sure to read the general information under Notices on page
193.
Third Edition (January 2008)

Order publications through your IBM representative or through the IBM branch office serving your locality.
Copyright International Business Machines Corporation 2001, 2008. All rights reserved.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures
. . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
About this book . . . . .
Who should read this book . .
Document organization . . .
Related information . . . .
Conventions used in this book
How to send your comments .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xi
xi
xi
xi
xi
. . . . . . . . . . . . . . . . . . . xiii
Chapter 1. What are the CICS

Base and derived classes . .
Resource classes . . . . .
Resource identification classes
Record index classes . . . .
Foundation Classes?
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 2. Writing an object-oriented CICS server .

Including the main function . . . . . . . . . . .
Using CICS resources. . . . . . . . . . . . .
Creating a resource object . . . . . . . . . .
Singleton classes . . . . . . . . . . . . .
Calling methods on a resource object . . . . . .
Support Classes . . . . . . . . . . . . . . .
Memory management . . . . . . . . . . . . .
Parameter passing conventions . . . . . . . . .
Polymorphic behavior . . . . . . . . . . . .
Polymorphism in the IccResource class . . . . .
Example of polymorphic behavior . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 3. Buffer objects . . . . . . . .

Data area manipulation . . . . . . . . . .
Data area ownership . . . . . . . . . .
Data area extensibility . . . . . . . . .
IccBuf constructors . . . . . . . . . . .
IccBuf methods and operators . . . . . . .
Using buffer objects with IccResource classes .
Scope of data in IccBuf references returned from
Chapter 4. Using CICS Services . .
APPC and DTP. . . . . . . . .
File control . . . . . . . . . .
Reading records . . . . . . .
Writing new records . . . . . .
Updating existing records . . . .
Deleting records . . . . . . .
Browsing records . . . . . . .
Example of file control . . . . .
Program control . . . . . . . .
Starting transactions asynchronously .
Starting transactions . . . . . .
Accessing start data . . . . . .
Canceling unexpired start requests
Copyright IBM Corp. 2001, 2008
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. .
. .
. .
. .
. .
. .
. .
read
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
1
2
3
4
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 5
. 5
. 6
. 6
. 7
. 7
. 8
. 9
. 10
. 10
. 10
. 11
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
methods .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13
13
13
13
13
15
15
16
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
19
19
19
20
21
22
22
22
23
24
26
26
26
27
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
iii
Example of starting transactions . . . . . .

Transient data . . . . . . . . . . . . . .
Reading transient data . . . . . . . . . .
Writing transient data . . . . . . . . . .
Deleting transient data queues . . . . . . .
Example of managing transient data . . . . .
Temporary storage . . . . . . . . . . . .
Reading items from temporary storage queues .
Writing items to temporary storage queues . .
Updating items . . . . . . . . . . . . .
Deleting items . . . . . . . . . . . . .
Example of using temporary storage . . . . .
Terminal control . . . . . . . . . . . . .
Sending data to a terminal . . . . . . . .
Receiving data from a terminal . . . . . . .
Finding the characteristics and current state of a
Example of terminal control . . . . . . . .
Time and date services . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
27
30
31
31
31
31
32
32
32
32
32
33
34
34
34
34
35
36
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
39
39
39
42
42
43
44
44
44
45
45
45
Classes Reference Pages .

. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 5. Conditions, errors, and exceptions

Foundation Class Abend codes . . . . . . .
C++ Exceptions and the Foundation Classes . .
CICS conditions . . . . . . . . . . . .
Manual condition handling (noAction) . . . .
Automatic condition handling (callHandleEvent)
Exception handling (throwException) . . . .
Severe error handling (abendTask) . . . .
Platform differences . . . . . . . . . . .
Object level . . . . . . . . . . . . .
Method level . . . . . . . . . . . . .
Parameter level. . . . . . . . . . . .
Chapter 6. CICS Foundation
IccAbendData . . . . . .
IccAbsTime . . . . . . .
IccAlarmRequestId . . . .
IccBase . . . . . . . .
IccBuf . . . . . . . . .
IccClock . . . . . . . .
IccCondition structure . . .
IccControl . . . . . . . .
IccConvId . . . . . . . .
IccDataQueue . . . . . .
IccDataQueueId . . . . .
IccEvent . . . . . . . .
IccException . . . . . . .
IccFile . . . . . . . . .
IccFileId . . . . . . . .
IccFileIterator . . . . . .
IccGroupId . . . . . . .
IccJournalId . . . . . . .
IccJournalTypeId . . . . .
IccKey . . . . . . . . .
IccLockId . . . . . . .
IccMessage . . . . . .
IccProgram . . . . . . .
iv
.
.
.
.
.
.
.
.
.
.
.
.
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
terminal
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
TXSeries for Multiplatforms: C++ Foundation Classes Programming Guide and Reference
.
.
.
.
.
.
.
.
.
.
.
.
. 47
. 47
. 48
. 51
. 53
. 56
. 65
. 70
. 70
. 73
. 74
. 76
. 76
. 78
. 82
. 92
. 93
. 95
. 96
. 97
. 98
. . . . . . . . 101
. . . . . . . . 102
. . . . . . . . 103
IccProgramId . .
IccRBA . . . .
IccRecordIndex .
IccRequestId . .
IccResource . .
IccResourceId . .
IccRRN . . . .
IccSemaphore . .
IccSession . . .
IccStartRequestQ
IccSysId . . . .
IccSystem . . .
IccTask . . . .
IccTempStore . .
IccTempStoreId .
IccTermId . . .
IccTerminal . . .
IccTerminalData .
IccTime . . . .
IccTimeInterval .
IccTimeOfDay . .
IccTPNameId . .
IccTransId . . .
IccUserId . . .
IccValue . . . .
Main Function . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
106
107
108
109
110
116
117
119
121
130
135
136
140
149
153
154
155
166
169
171
172
173
174
175
176
177
Appendix A. CICS Foundation Class abend codes . . . . . . . . . . 179

Appendix B. Compiling, executing,
Compiling programs . . . . . .
CICS for AIX . . . . . . . .
CICS for Windows . . . . . .
Executing programs . . . . .
Debugging programs . . . . .
and debugging
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Appendix C. Mapping Foundation Class methods to EXEC CICS calls
183
183
183
183
184
184
187
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Trademarks and service marks . . . . . . . . . . . . . . . . . . 194
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Contents
vi
Figures
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.
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
Code
example: main function . . . . . . . . . . . . . . . . . . .

example: Memory management . . . . . . . . . . . . . . .
example: Signature of IccStartRequestQ::start method . . . . . . .
example: Passing parameters . . . . . . . . . . . . . . . .
example: Defining virtual clear, get, and put methods in the IccResource
example: Polymorphic behavior . . . . . . . . . . . . . . .
example: Using an external data area . . . . . . . . . . . . .
example: Using the copy constructor . . . . . . . . . . . . .
example: Using a buffer with a temporary storage queue . . . . . .
example: Using a buffer with a transient data queue . . . . . . .
example: Copying returned data to a local buffer object . . . . . .
example: Maintaining a reference to a buffer object . . . . . . . .
example: File control . . . . . . . . . . . . . . . . . . .
example: Program control (ICCPRG1) . . . . . . . . . . . . .
example: Starting transactions (ISR1) . . . . . . . . . . . . .
example: Starting transactions (ISR2) . . . . . . . . . . . . .
example: Managing transient data . . . . . . . . . . . . . .
example: Managing temporary storage queues . . . . . . . . .
example: Controlling CICS terminals . . . . . . . . . . . . .
example: Using CICS time and date services . . . . . . . . . .
example: Throwing and catching exceptions . . . . . . . . . .
example: Output from exception handling example . . . . . . . .
example: Throwing an invalidArgument exception . . . . . . . .
example: Manual condition handling . . . . . . . . . . . . .
example: Automatic condition handling . . . . . . . . . . . .
example: Condition exception handling . . . . . . . . . . . .
example: Severe error handling . . . . . . . . . . . . . . .
example: Method level enforcement . . . . . . . . . . . . .
example: Parameter level enforcement . . . . . . . . . . . .
. . .
. . .
. . .
. . .
class .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . 6
. . 9
. . 10
. . 10
. . 10
. . 12
. . 14
. . 14
. . 15
. . 16
. . 16
. . 16
. . 23
. . 25
. . 25
. . 26
. . 28
. . 29
. . 31
. . 33
. . 35
. . 37
. . 40
. . 41
. . 41
. . 43
. . 43
. . 44
. . 44
. . 45
. . 46
vii
viii
Tables
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.
Conventions that are used in this book . . . . . . . . . . . . . . . . . . . . . . . xi

Classes derived from IccResource . . . . . . . . . . . . . . . . . . . . . . . . . 2
Classes derived from IccResourceId . . . . . . . . . . . . . . . . . . . . . . . . 3
Classes derived from IccRecordIndex . . . . . . . . . . . . . . . . . . . . . . . . 4
Implementation of get, clear, and put methods in IccResource subclasses . . . . . . . . . . 10
Example of starting transactions . . . . . . . . . . . . . . . . . . . . . . . . . 27
EXEC CICS calls for IccAbendData class methods . . . . . . . . . . . . . . . . . . 187
EXEC CICS calls for IccAbsTime class methods . . . . . . . . . . . . . . . . . . . 187
EXEC CICS calls for IccClock class methods . . . . . . . . . . . . . . . . . . . . 187
EXEC CICS calls for IccConsole class methods . . . . . . . . . . . . . . . . . . . 188
EXEC CICS calls for IccControl class methods . . . . . . . . . . . . . . . . . . . 188
EXEC CICS calls for IccDataQueue class methods . . . . . . . . . . . . . . . . . . 188
EXEC CICS calls for IccFile class methods. . . . . . . . . . . . . . . . . . . . . 188
EXEC CICS calls for IccFileIterator class methods . . . . . . . . . . . . . . . . . . 189
EXEC CICS calls for IccJournal class methods . . . . . . . . . . . . . . . . . . . 189
EXEC CICS calls for IccProgram class methods . . . . . . . . . . . . . . . . . . . 189
EXEC CICS calls for IccResource class methods . . . . . . . . . . . . . . . . . . 189
EXEC CICS calls for IccSemaphore class methods . . . . . . . . . . . . . . . . . . 189
EXEC CICS calls for IccSession class methods . . . . . . . . . . . . . . . . . . . 189
EXEC CICS calls for IccStartRequestQ class methods . . . . . . . . . . . . . . . . 190
EXEC CICS calls for IccSystem class methods . . . . . . . . . . . . . . . . . . . 190
EXEC CICS calls for IccTask class methods . . . . . . . . . . . . . . . . . . . . 190
EXEC CICS calls for IccTempStore class methods . . . . . . . . . . . . . . . . . . 191
EXEC CICS calls for IccTerminal class methods . . . . . . . . . . . . . . . . . . . 191
EXEC CICS calls for IccTerminalData class methods . . . . . . . . . . . . . . . . . 192
EXEC CICS calls for IccUser class methods . . . . . . . . . . . . . . . . . . . . 192
ix
About this book

This document describes the use of the CICS Foundation Classes, which can be
used to write CICS servers in the C++ language. The document contains a
programming guide, which describes the classes and demonstrates their use, and
reference pages for the classes, which provide details about the structure of the
classes.
Who should read this book

This guide is intended for CICS developers who are interested in using the C++
language to write CICS applications. Readers should be familiar with CICS and with
program development in the C++ programming language.
Document organization
This document has the following organization:
v Chapter 1, What are the CICS Foundation Classes?, on page 1 gives an
overview of the CICS Foundation Classes.
v Chapter 2, Writing an object-oriented CICS server, on page 5 discusses how
use the Foundation Classes to write a CICS server.
v Chapter 3, Buffer objects, on page 13 describes how to work with buffers.
v Chapter 4, Using CICS Services, on page 19 describes the services classes.
v Chapter 5, Conditions, errors, and exceptions, on page 39 describes condition,
exception, and abend handling.
v Chapter 6, CICS Foundation Classes Reference Pages, on page 47
v Appendix A, CICS Foundation Class abend codes, on page 179
v Appendix B, Compiling, executing, and debugging, on page 183
Related information
For further information on the topics that are discussed in this manual, see the
following documents:
v TXSeries for Multiplatforms Application Programming Guide
Conventions used in this book

TXSeries for Multiplatforms documentation uses the following typographical and
keying conventions.
Table 1. Conventions that are used in this book
Convention
Meaning
Bold
Indicates values that you must use literally, such as commands,

functions, and resource definition attributes and their values. When
referring to graphical user interfaces (GUIs), bold also indicates
menus, menu items, labels, buttons, icons, and folders.
Monospace
Indicates text that you must enter at a command prompt. Monospace

also indicates screen text and code examples.
Italics
Indicates variable values that you must provide (for example, you
supply the name of a file for file_name). Italics also indicates
emphasis and the titles of books.
xi
Table 1. Conventions that are used in this book (continued)
xii
Convention
Meaning
<>
Encloses the names of keys on the keyboard.
<Ctrl-x>
Where x is the name of a key, indicates a control-character

sequence. For example, <Ctrl-c> means hold down the Ctrl key
while you press the c key.
<Return>
Refers to the key labeled with the word Return, the word Enter, or
the left arrow.
Represents the UNIX command-shell prompt for a command that

does not require root privileges.
Represents the UNIX command-shell prompt for a command that

requires root privileges.
C:\>
Represents the Windows command prompt.
>
When used to describe a menu, shows a series of menu selections.

For example, Select File > New means From the File menu,
select the New command.
Entering commands
When instructed to enter or issue a command, type the command

and then press <Return>. For example, the instruction Enter the ls
command means type ls at a command prompt and then press
<Return>.
[]
Encloses optional items in syntax descriptions.
{}
Encloses lists from which you must choose an item in syntax

descriptions.
Separates items in a list of choices enclosed in { } (braces) in syntax

descriptions.
...
Ellipses in syntax descriptions indicate that you can repeat the

preceding item one or more times. Ellipses in examples indicate that
information was omitted from the example for the sake of brevity.
IN
In function descriptions, indicates parameters whose values are used

to pass data to the function. These parameters are not used to
return modified data to the calling routine. (Do not include the IN
declaration in your code.)
OUT
In function descriptions, indicates parameters whose values are used

to return modified data to the calling routine. These parameters are
not used to pass data to the function. (Do not include the OUT
declaration in your code.)
INOUT
In function descriptions, indicates parameters whose values are

passed to the function, modified by the function, and returned to the
calling routine. These parameters serve as both IN and OUT
parameters. (Do not include the INOUT declaration in your code.)
$CICS
Indicates the full path name of the location in which the CICS
product is installed; for example, /usr/lpp/cics on AIX. If the CICS
environment variable is set to the product path name, you can use
the examples exactly as shown in this book; otherwise, you must
replace all instances of $CICS with the CICS product path name.
CICS on Open
Systems
Refers collectively to the CICS product for all supported UNIX

platforms.
TXSeries for
Multiplatforms
Refers collectively to the CICS for AIX, CICS for HP-UX, CICS for
Solaris, and CICS for Windows products.
Table 1. Conventions that are used in this book (continued)

Convention
Meaning
CICS
Refers generically to the CICS for AIX, CICS for HP-UX, CICS for
Solaris, and CICS for Windows products. Other CICS products in the
CICS Family are distinguished by their operating system (for
example, IBM mainframe-based CICS for the z/OS platform).
How to send your comments

Your feedback is important in helping to provide the most accurate and highest
quality information. If you have any comments about this book or any other
TXSeries for Multiplatforms documentation, send your comments by e-mail to
idrcf@hursley.ibm.com. Be sure to include the name of the book, the document
number of the book, the version of TXSeries for Multiplatforms, and, if applicable,
the specific location of the information about which you are commenting (for
example, a page number or table number).
About this book
xiii
xiv
Chapter 1. What are the CICS Foundation Classes?

The CICS Foundation Classes are an application programming interface (API) for
writing CICS servers in the C++ programming language. The following sections give
an overview of the Foundation Classes:
v Base and derived classes
v Resource identification classes on page 3
v Resource classes on page 2
v Record index classes on page 4
Every class that belongs to the CICS Foundation Classes is prefixed by Icc.
Base and derived classes

All CICS Foundation Classes are derived, directly or indirectly, from the IccBase
base class. These classes enable common interfaces to be defined for categories
of classes. Application programmers can also use them to create their own derived
classes.
The foundation classes are listed below.
IccBase
Base class that enables memory management and allows objects to be
interrogated to discover which type they are.
IccBuf
Class for manipulating buffers.
IccEvent
Class that contains information on specific CICS calls, or events.
IccException
Class for creating exceptions that are thrown to CICS programs.
IccMessage
Class that holds message descriptions. It is primarily used by the
IccException class to describe why an exception object was created.
Programmers can also use this class to create messages.
IccRecordIndex
The base class for all CICS Foundation Classes that work with CICS file
control records. See Record index classes on page 4 for more
information, including a list of the classes that are derived from the
IccRecordIndex class.
IccResource
The base class for all CICS Foundation Classes that access CICS
resources or services. See Resource classes on page 2 for more
information, including a list of the classes that are derived from the
IccResource class.
IccResourceId
The base class for all table entry (resource name) classes. All resource
identification classes, such as IccTermId and IccTransId, inherit from the
IccResourceId class. These classes typically represent CICS table entries.
See Resource identification classes on page 3 for more information,
including a list of the classes that are derived from this class.
Resource classes
All CICS resources and any class that accesses CICS services inherit from the
IccResource class. These classes model the behavior of major CICS resources,
including:
v Terminals, which are modeled by the IccTerminal class
v Programs, which is modeled by the IccProgram class
v Temporary storage queues, which are modeled by the IccTempStore class
v Transient data queues, which are modeled by the IccDataQueue class
For example, any operation on a CICS resource can raise a CICS condition; the
condition method of IccResource (see page condition) can interrogate it.
Table 2 contains a complete listing of the CICS Foundation Classes that are derived
from the IccResource class and the resource that each class represents.
Table 2. Classes derived from IccResource
Resource class name
CICS resource
IccAbendData
Task abend data
IccClock
CICS time and date services
IccConsole
CICS console
IccControl
Control of executing program
IccDataQueue
Transient data queue
IccFile
Files
IccFileIterator
Browsing (iterating) files
IccJournal
User or system journal
IccProgram
Outside executing program
IccSemaphore
Locking services (semaphore)
IccSession
Session
IccStartRequestQ
Start request queue; asynchronous

transaction starts
IccSystem
CICS system
IccTask
Current task
IccTempStore
Temporary storage queue
IccTerminal
Terminal belonging to current task
IccTerminalData
Attributes of terminal objects
IccTime
Base class for time services. Its derived

classes are:
IccAbsTime
Specifies the absolute time in
milliseconds since January 1, 1900.
IccTimeInterval
Specifies a time interval.
IccTimeOfDay
Specifies the time of day.
IccUser
User security attributes
Resource identification classes

CICS resource identification classes define CICS resource identifiers; typically
entries in one of the CICS tables. For example, an IccFileId object represents a
CICS file name (that is, an FCT (file control table) entry or, in an AIX environment,
an FD stanza entry).
All concrete resource identification classes have the following properties:
v The name of the class ends in Id.
v The class is a subclass of the IccResourceId class.
v The constructors ensure that any supplied table entry meets CICS standards. For
example, an IccFileId object must contain a one- through eight-byte character
field; a nine-byte field is not tolerated.
The resource identification classes improve type checking; for example, methods
that expect an IccFileId object as a parameter do not accept an IccProgramId
object instead. If character strings that represent the resource names are used
instead, the compiler cannot check for validity; it cannot check whether the string is
a file name or a program name.
Many of the resource classes that are described in Resource classes on page 2
contain resource identification classes. For example, an IccFile object contains an
IccFileId object. Use the resource object to operate on a CICS resource, not the
resource identification object. For example, you must use IccFile (not IccFileId) to
read a record from a file.
The CICS resource identification classes are listed in Table 3. In an AIX
environment, CICS resources are stored in the regions permanent database by
using stanzas.
The equivalent stanza class name is shown in after the CICS table name.
Table 3. Classes derived from IccResourceId
Resource ID class
name
CICS resource
identified
CICS table name
AIX stanza class

name
IccAlarmRequestId
Alarm request
IccConvId
Conversation
IccDataQueueId
Data queue
DCT
TDD
IccFileId
File
FCT
FD
IccGroupId
Group
IccJournalId
Journal
JCT
JD
IccJournalTypeId
Journal type
IccLockId
Not applicable
IccPartnerId
APPC partner
definition files
IccProgramId
CICS program
PPT
PD
IccRequestId
Request
IccSysId
Remote system
IccTempStoreId
Temporary storage
TST
TSD
IccTermId
Terminal
TCT
WD
Chapter 1. What are the CICS Foundation Classes?
Table 3. Classes derived from IccResourceId (continued)

IccTPNameId
Remote APPC TP
name
IccTransId
transaction
PCT
TD
IccUserId
user
SNT
UD
Record index classes

The record index classes are derived from the IccRecordIndex base class and are
used to identify records in CICS files. They specify the record access method and
identify which record in a file is to be retrieved, modified, or deleted.
The classes that are derived from the IccRecordIndex class are listed in Table 4.
Table 4. Classes derived from IccRecordIndex
Record index class name
Type of record
IccKey
Holds a search index for an indexed (KSDS)

file.
IccRBA
Holds a relative byte address that is used for

accessing VSAM and ESDS files.
IccRRN
Holds a relative record number that is used

for accessing records in VSAM RRDS files.
Chapter 2. Writing an object-oriented CICS server

This section talks about items that are related to writing a CICS server with the
Foundation Classes. It is organized as follows:
v Including the main function
v Using CICS resources on page 6
v Support Classes on page 8
v Memory management on page 9
v Parameter passing conventions on page 10
v Polymorphic behavior on page 10
Including the main function

The main function initializes the CICS Foundation Classes correctly, provides
default exception handling, and releases allocated memory after it is finished. It is
recommended that you include this code in your application. You can substitute
your own variation of this main function, but this should rarely be necessary.
Source file: iccmain.cpp
The stub has three functions:
1. It initializes the Foundation Classes environment. You can customize
initialization by using #define statements that control the following:
v Memory management (see Memory management on page 9)
v Family subset enforcement (see Platform differences on page 44)
v EDF enablement (see Executing programs on page 184)
2. It provides a default definition of a class IccUserControl, which is derived from
IccControl, that includes a default constructor and run method.
3. It invokes the run method of the users control object by using a try-catch
construct.
The functional part of the main code is shown in Figure 1 on page 6.
void main(void)
{
Icc::initializeEnvironment(ICC_CLASS_MEMORY_MGMT,
ICC_FAMILY_SUBSET,
ICC_EDF_BOOL);
try
{
ICC_USER_CONTROL control;
control.run();
}
catch(IccException& exc)
{
Icc::catchException(exc);
}
catch(...)
{
Icc::unknownException();
}
Icc::returnToCICS();
}
(1)
(2)
(3)
(4)
(5)
(6)
(7)
(8)
(9)
(10)
Figure 1. Code example: main function
(1) This is the main C++ entry point. On CICS for OS/2, this entry point is faamain
instead of main.
(2) This call initializes the environment and is essential. The three parameters have
previously been defined to the defaults for the platform.
(3) Run the users application code, using try and catch, in case the application
code does not catch exceptions.
(4) Create control object.
(5) Invoke run method of control object (defined as pure virtual in IccControl).
(6) Catch any IccException objects that are not caught by the application.
(7) Call this function to abend task.
(8) Catch any other exceptions that are not caught by application.
(9) Call this function to abend task.
(10) Return control to CICS.
Using CICS resources

To use a CICS resource, such as a file or program, you must first create an
appropriate object, then call methods on the object.
Creating a resource object

When you create a resource object, you create a representation of the actual CICS
resource (such as a file or program). You do not create the CICS resource; the
object is simply the applications view of the resource. The same is true of
destroying objects.
You are recommended to use an accompanying resource identification object when
creating a resource object. For example:
IccFileId
IccFile
id("XYZ123");
file(id);
This allows the C++ compiler to protect you against doing something wrong such
as:
IccDataQueueId
IccFile
id("WXYZ");
file(id);
//gives error at compile time
The alternative of using the text name of the resource when creating the object is
also permitted:
IccFile
file("XYZ123");
Singleton classes
Many resource classes, such as IccFile, can be used to create multiple resource
objects within a single program:
IccFileId
IccFileId
IccFile
IccFile
id1("File1");
id2("File2");
file1(id1);
file2(id2);
However, some resource classes are designed to allow the programmer to create
only one instance of the class; these are called singleton classes. The following
CICS Foundation Classes are singleton classes:
v IccAbendData provides information about task abends.
v IccConsole, or a derived class, represents the system console for operator
messages.
v IccControl, or a derived class, such as IccUserControl, controls the executing
program.
v IccStartRequestQ, or a derived class, allows the application program to start
CICS transactions (tasks) asynchronously.
v IccSystem, or a derived class, is the application view of the CICS system in
which it is running.
v IccTask, or a derived class, represents the CICS task under which the executing
program is running.
v IccTerminal, or a derived class, represents your tasks terminal, provided that
your principal facility is a 3270 terminal.
Any attempt to create more than one object of a singleton class results in an error;
a C++ exception is thrown.
A class method, instance, is provided for each of these singleton classes, which
returns a pointer to the requested object and creates one if it does not already
exist. For example:
IccControl* pControl = IccControl::instance();
Calling methods on a resource object

Any of the public methods can be called on an object of that class. For example:
IccTempStoreId id("TEMP1234");
IccTempStore
temp(id);
temp.writeItem("Hello TEMP1234");
Method writeItem writes, to the CICS Temporary Storage queue TEMP1234, the
contents of the string that it is passed (here Hello TEMP1234).
Support Classes
The support classes complement the resource classes and provide functions that
simplify programming. They are described as follows:
IccAbsTime
Absolute time (milliseconds since January 1, 1900).
IccBuf
Data buffer (makes manipulating data areas easier).
IccEvent
Event (the outcome of a CICS command).
IccException
Foundation Class exception (supports the C++ exception handling model).
IccTimeInterval
Time interval (for example, five minutes).
IccTimeOfDay
Time of day (for example, five minutes past six).
IccAbsTime, IccTimeInterval, and IccTimeOfDay classes make it simpler for the
application programmer to specify time measurements as objects within an
application program. IccTime is a base class: IccAbsTime, IccTimeInterval, and
IccTimeOfDay are derived from IccTime.
Consider the delay method in class IccTask, whose signature is as follows:
void delay(const IccTime& time, const IccRequestId* reqId = 0);
To request a delay of 1 minute and 7 seconds (that is, a time interval), an

application programmer can do this:
IccTimeInterval time(0, 1, 7);
task()->delay(time);
Note: The task method is provided in class IccControl and returns a pointer to the
applications task object.
Alternatively, to request a delay until 10 minutes past twelve, the application
programmer can do this:
IccTimeOfDay lunchtime(12, 10);
task()->delay(lunchtime);
The IccBuf class allows easy manipulation of buffers, such as file record buffers,
transient data record buffers, and COMMAREAs. For more information about the
IccBuf class, see Chapter 3, Buffer objects, on page 13).
The IccMessage class is used primarily by the IccException class to encapsulate
a description of why an exception was thrown. The application programmer can
also use the IccMessage class to create message objects.
IccException objects are thrown from many of the methods in the CICS
Foundation Classes when an error is encountered.
The IccEvent class allows a programmer to gain access to information that relates
to a particular CICS event (command).
Memory management
C++ objects are usually stored on the stack or heap. Objects that are on the stack
are automatically destroyed when they go out of scope, but objects that are on the
heap are not.
Many of the objects that the CICS Foundation Classes create internally are created
on the heap rather than on the stack. This can cause a problem in some CICS
server environments.
On CICS for MVS/ESA, CICS and Language Environment manage all task
storage so that it is released at task termination (normal or abnormal). However, in
a CICS for Windows, CICS for OS/2, or CICS for AIX environment, storage that is
allocated on the heap is not automatically released at task termination. This can
lead to memory management problems (memory leaks) if the application
programmer forgets to delete an object on the heap explicitly, or if the task abends.
This problem has been overcome in the CICS Foundation Classes by providing two
operators, new and delete, in the base Foundation Class, IccBase. These
operators can be configured to map dynamic storage allocation requests to CICS
task storage, so that all storage is automatically released at task termination. The
disadvantage of this approach is that application performance is not as good,
because the Foundation Classes typically issue a large number of small storage
allocation requests rather than a single, larger allocation request.
This facility is affected by the Icc::initializeEnvironment call that must be issued
before the Foundation Classes are used. (This function is called from the default
main function; see main function.)
The first parameter that is passed to the initializeEnvironment function is an
enumeration that takes one of these three values:
cmmDefault
The default action is platform dependent:
v Open Systems, Windows and OS/2: Same as cmmCICS.
v MVS/ESA: Same as cmmNonCICS.
cmmNonCICS
The new and delete operators in class IccBase do not map dynamic
storage allocation requests to CICS task storage; instead the C++ default
new and delete operators are invoked.
cmmCICS
The new and delete operators in class IccBase map dynamic storage
allocation requests to CICS task storage, which is automatically released at
normal or abnormal task termination.
The default main function that is supplied with the Foundation Classes calls
initializeEnvironment with a value of cmmDefault. You can change this in your
program without changing the supplied header file iccmain.cpp as shown in
Figure 2.
#define ICC_CLASS_MEMORY_MGMT Icc::cmmNonCICS
#include "iccmain.cpp"
Figure 2. Code example: Memory management
Alternatively, use the -D option of your compiler.

Parameter passing conventions

The convention that is used for passing objects on CICS Foundation Classes
method calls is as follows:
v If the object is mandatory, pass by reference.
v If the object is optional, pass by pointer.
For example, the start method of the class IccStartRequestQ has the signature
that is shown in Figure 3.
const IccRequestId& start( const IccTransId& transId,
const IccTime* time=0,
const IccRequestId* reqId=0 );
Figure 3. Code example: Signature of IccStartRequestQ::start method
Using the standard CICS Foundation Class convention, an IccTransId object is

mandatory, while an IccTime and an IccRequestId object are both optional. This
enables an application to use this method in the ways that are shown in Figure 4.
IccTransId
trn("ABCD");
IccTimeInterval int(0,0,5);
IccRequestId
req("MYREQ");
IccStartRequestQ* startQ = startRequestQ();
startQ->start( trn );
startQ->start( trn, &int );
startQ->start( trn, &int, &req );
startQ->start( trn, 0, &req );
Figure 4. Code example: Passing parameters
Polymorphic behavior
Polymorphism is the ability to treat many different forms of an object as if they were
the same. Polymorphism is achieved in C++ by using inheritance and virtual
methods. Limited polymorphic behavior through the use of virtual methods is
available in the CICS Foundation Classes.
Polymorphism in the IccResource class

Three virtual methods are defined in the base class IccResource, as shown in
Figure 5.
Figure 5. Code example: Defining virtual clear, get, and put methods in the IccResource class
// clear function
virtual void clear();
// get function
virtual const IccBuf& get();
// put function
virtual void put(const IccBuf& buffer);
These methods are implemented differently in the classes that are derived from the
IccResource class. Table 5 shows where the get, clear, and put methods have
been implemented in the subclasses of IccResource. Each implemented method is
marked with an in the table.
Table 5. Implementation of get, clear, and put methods in IccResource subclasses
Class name
10
clear method
get method
put method
Table 5. Implementation of get, clear, and put methods in IccResource

subclasses (continued)
IccConsole
IccDataQueue
IccJournal
IccSession
IccTempStore
IccTerminal
These virtual methods are not supported by any subclasses of IccResource except
those that are shown in Table 5 on page 10.
Note: The default implementations of the clear, get, and put methods in the base
class IccResource throw an exception to prevent the user from calling an
unsupported method.
Example of polymorphic behavior

Figure 6 on page 12 shows an example of how polymorphic behavior is
implemented in the CICS Foundation Classes. This code example can be found in
the samples directory (see Sample source code) in the file iccres2.cpp. It is
presented here without the terminal IO requests.
11
#include "icceh.hpp"
// Sample data items
char* dataItems[] =
{
"Hello World - item 1",
"Hello World - item 3"
};
// Application code
void IccUserControl::run()
{
IccBuf buffer( 50 );
IccResource* pObj[2];
pObj[0] = new IccDataQueue("ICCQ");
pObj[1] = new IccTempStore("ICCTEMPS");
for ( short index=0; index <= 1 ; index++ )
{
pObj[index]->clear();
}
for ( index=0; index <= 1 ; index++ )
{
for (short j=1 ; j <= 3 ; j++)
{
buffer = dataItems[j-1];
pObj[index]->put( buffer );
}
}
for ( index=0; index <= 1 ; index++ )
{
buffer = pObj[index]->get();
while (pObj[index]->condition() == IccCondition::NORMAL)
{
buffer = pObj[index]->get();
}
delete pObj[index];
}
return;
}
Figure 6. Code example: Polymorphic behavior
The string dataItems contains sample data. Application code is contained in the run
method of the IccUserControl class.
An IccBuf object (50 bytes initially) holds data items. An array of two pointers to
IccResource objects is also declared. The sample program also creates two
objects whose classes are derived from IccResource: IccDataQueue and
IccTempStore .
For both objects, the program invokes the clear method. This is handled differently
by each object in a way that is transparent to the application program (showing the
methods polymorphic behavior).
Next, the program puts three data items into each resource object. Again, the put
method responds to the request in a way that is appropriate to the object type. The
data items are read back in from each resource object by using the get method.
The program the deletes the resource objects and returns control to CICS.
12
Chapter 3. Buffer objects

The CICS Foundation Classes make extensive use of IccBuf objects; that is, buffer
objects that simplify the task of handling pieces of data or records. You need to
understand how to use buffer objects to write CICS servers with the foundation
classes successfully. This section discusses the following topics that apply to buffer
objects:
v Data area manipulation
v IccBuf constructors
v IccBuf methods and operators on page 15
v Using buffer objects with IccResource classes on page 15
v Scope of data in IccBuf references returned from read methods on page 16
For more information about the IccBuf class, see its reference page.
Data area manipulation

The IccBuf class provides generalized manipulation of data areas. Two important
attributes of an IccBuf object are data area ownership and extensibility, which are
described in the remainder of this section.
Data area ownership

The IccBuf class has an attribute that indicates whether the data area has been
allocated inside or outside the object. The possible values of this attribute are
internal and external. The data area ownership attribute can be interrogated by
using the dataAreaOwner method.
Data area extensibility

This attribute defines whether the length of the data area within the IccBuf object
can be increased after it has been created. The possible values of this attribute are
fixed and extensible. The data area extensibility attribute can be interrogated by
using the dataAreaType method.
By default, buffer objects have a data area extensibility value of extensible. The
data areas of these buffers can be increased in size after being created. This type
of buffer must also have a data area ownership attribute of internal.
A buffer object that has a data area extensibility value of fixed cannot have its data
area size increased. The length of the data (for example, a file record) that is
assigned to the IccBuf object must not exceed the data area length, otherwise a
C++ exception is thrown.
IccBuf constructors
Several forms of the IccBuf constructor are use when IccBuf objects are created.
Because it can be used in several ways, several IccBuf constructors can affect the
behavior of the object. Some examples are shown here.
IccBuf buffer;
This creates an internal and extensible data area that has an initial length of
zero. When data is assigned to the object, the data area length is automatically
extended to accommodate the data that is being assigned.
13
IccBuf buffer(50);
This creates an internal and extensible data area that has an initial length of 50
bytes. The data length is zero until data is assigned to the object. If 50 bytes of
data are assigned to the object, both the data length and the data area length
return a value of 50. When more than 50 bytes of data are assigned into the object,
the data area length is automatically (that is, without further intervention) extended
to accommodate the data.
IccBuf buffer(50, IccBuf::fixed);
This creates an internal and fixed data area that has a length of 50 bytes. If an
attempt is made to assign more than 50 bytes of data into the object, the data is
truncated and an exception is thrown to notify the application of the error condition.
Figure 7 creates an IccBuf object that uses an external data area called
myRecord.
struct MyRecordStruct
{
short id;
short code;
char data[30];
char rating;
};
MyRecordStruct myRecord;
IccBuf buffer(sizeof(MyRecordStruct), &myRecord;);
Figure 7. Code example: Using an external data area
By definition, an external data area is also fixed. Data can be assigned by using
the methods on the IccBuf object or by using the myRecord structure directly.
IccBuf buffer("Hello World");
This creates an internal and extensible data area that has a length that is equal
to the length of the string Hello World. The string is copied into the objects data
area. This initial data assignment can then be changed by using one of the
manipulation methods (such as insert, cut, or replace) that are provided.
In Figure 8, the copy constructor creates the second buffer with almost the same
attributes as the first has.
IccBuf buffer("Hello World");
buffer << " out there";
IccBuf buffer2(buffer);
Figure 8. Code example: Using the copy constructor
The exception is the data area ownership attribute. The second object always
contains an internal data area that is a copy of the data area that is in the first. In
the above example, buffer2 contains Hello World out there and has both data
area length and data length of 21.
14
IccBuf methods and operators

An IccBuf object can be manipulated by use of several supplied methods; for
example you can append data to the buffer, change the data in the buffer, cut data
out of the buffer, or insert data into the middle of the buffer. The operators const
char*, =, +=, ==, !=, and << have been overloaded in class IccBuf. Also, two
methods allow the IccBuf attributes to be queried. For more details, see the
reference page for the IccBuf class.
Using buffer objects with IccResource classes

The resource classes that pass data to CICS (for example, by writing data records)
and get data from CICS (for example, by reading data records) use the IccBuf
class. These classes include IccConsole, IccDataQueue, IccFile, IccFileIterator,
IccJournal, IccProgram, IccSession, IccStartRequestQ, IccTempStore, and
IccTerminal.
Figure 9 shows an example of writing a queue item to CICS temporary storage
using IccTempstore class.
IccTempStore store("TEMP1234");
IccBuf
buffer(50);
buffer = "Hello Temporary Storage Queue";
store.writeItem(buffer);
Figure 9. Code example: Using a buffer with a temporary storage queue
The IccTempStore object that is created is the applications view of the CICS
temporary storage queue named TEMP1234. The IccBuf object that is created
holds a 50-byte data area (it also happens to be extensible).
The character string Hello Temporary Storage Queue is copied into the buffer.
This is possible because the operator = has been overloaded in the IccBuf class.
The IccTempStore object calls its writeItem method, and passes a reference to the
IccBuf object as the first parameter. The contents of the IccBuf object are written
out to the CICS temporary storage queue.
Now consider the inverse operation, reading a record from the CICS resource into
the application programs IccBuf object:
buffer = store.readItem(5);
The readItem method reads the contents of the fifth item in the CICS Temporary
Storage queue and returns the data as an IccBuf reference.
The C++ compiler actually resolves the above line of code into two method calls,
readItem, which is defined in class IccTempStore, and operator =, which has been
overloaded in class IccBuf. The second method takes the contents of the returned
IccBuf reference and copies its data into the buffer.
Finally, Figure 10 on page 16 shows how to write code, using a similar style to the
above example, but this time accessing a CICS transient data queue.
15
IccDataQueue queue("DATQ");
IccBuf
buffer(50);
buffer = queue.readItem();
buffer << "Some extra data";
queue.writeItem(buffer);
Figure 10. Code example: Using a buffer with a transient data queue
The readItem method of the IccDataQueue object is called, returning a reference

to an IccBuf object, which it then assigns (by way of the operator =, overloaded in
class IccBuf) to the buffer object. The character string Some extra data is
appended to the buffer (by way of the operator <<, overloaded in class IccBuf). The
writeItem method then writes back this modified buffer to the CICS transient data
queue.
The sample programs in Chapter 4, Using CICS Services, on page 19 show
further examples of this syntax.
Refer to the reference section for further information about the IccBuf class. The
sample program iccbuf.cpp is also helpful for understanding buffers.
Scope of data in IccBuf references returned from read methods

Many of the subclasses of IccResource have read methods that return const
IccBuf references; for example, IccFile::readRecord, IccTempStore::readItem
and IccTerminal::receive.
Take care if you choose to maintain a reference to the IccBuf object, rather than
copy the data from the IccBuf reference into your own IccBuf object.
For example, in Figure 11, the data in the IccBuf reference that is returned from
IccTempStore::readNextItem is immediately copied into the applications own
IccBuf object
IccBuf
buf(50);
IccTempStore store("TEMPSTOR");
buf = store.readNextItem();
Figure 11. Code example: Copying returned data to a local buffer object
It does not matter if the data is later invalidated.

However, in Figure 12, the IccBuf reference that is returned from
IccTempStore::readNextItem is not copied into the applications own storage.
IccTempStore store("TEMPSTOR");
const IccBuf& buf = store.readNextItem();
Figure 12. Code example: Maintaining a reference to a buffer object
Note: This style of programming is not recommended, because the reference can
be pointing to an IccBuf object that does not contain valid data.
The returned IccBuf reference typically contains valid data until one of the following
conditions is met:
v Another read method is invoked on the IccResource object (for example,
another readNextItem or readItem method in the above example).
v The resource updates are committed (see method IccTask::commitUOW).
16
v The task ends normally or abnormally.
17
18
Chapter 4. Using CICS Services

This chapter describes how to use CICS services. The following services are
considered in turn:
v APPC and DTP
v File control
v Program control on page 24
v
v
v
v
v
Starting transactions asynchronously on page 26

Transient data on page 30
Temporary storage on page 32
Terminal control on page 34
Time and date services on page 36
APPC and DTP

This section will not be available for the Technology Release.
Refer to samples iccses1.cpp and iccses2.cpp for ideas about how to use the
Foundation Classes to write an APPC/DTP program.
File control
The file control classes IccFile, IccFileId, IccKey, IccRBA, and IccRRN allow you
to read, write, update, and delete records in files. In addition, the IccFileIterator
class allows you to browse through all the records in a file.
An IccFile object is used to represent a file. It is convenient, but not necessary, to
use an IccFileId object to identify a file by name.
An application program reads and writes its data in the form of individual records.
Each read or write request is made by a method call. To access a record, the
program must identify both the file and the particular record.
Virtual storage access method (VSAM) files are of the following types:
Key Sequenced Data Set (KSDS)
In KSDS files, each record is identified by a key, which is a field that is in a
predefined position in the record. Each key must be unique in the file. The
logical sequence of records within a file is determined by the key. The
physical location is held in an index that is maintained by VSAM. In a
browse operation, records are found in their logical sequence.
Entry Sequenced Data Set (ESDS)
In ESDS files, each record is identified by its relative byte address (RBA).
Records are held in an ESDS file in the sequence in which they were first
loaded into the file. New records are always added at the end and records
cannot be deleted or have their lengths changed. In a browse operation,
records are found in the sequence in which they were originally written.
Relative Record Data Set (RRDS)
In RRDS files, records are written in fixed-length slots. A record is identified
by the relative record number (RRN) of the slot that holds it.
19
Reading records
A read operation uses two classes: IccFile to perform the operation, and either
IccKey, IccRBA, or IccRRN to identify the particular record. (The class that you
use depends on whether the file access type is KSDS, ESDS, or RRDS.)
The readRecord method of IccFile class actually reads the record.
Reading KSDS records

Before reading a KSDS record, you must use the registerRecordIndex method of
the IccFile class to associate an object of class IccKey with the file.
You must use a key, which is held in the IccKey object, to access records. A
complete key is a character string of the same length as the length of the physical
files key. Every record can be separately identified by its complete key.
A key can also be generic. A generic key is shorter than a complete key, and is
used for searching for a set of records. The IccKey class has methods that allow
you to set and change the key.
Other IccFile methods that are useful when reading KSDS records include:
v isReadable
v
v
v
v
keyLength
keyPosition
recordIndex
recordLength
Reading ESDS records

To access the beginning of an ESDS record, you must use a relative byte address
(RBA) that is held in an IccRBA object.
Before reading a record, use the registerRecordIndex method of the IccFile class
to associate an object of class IccRBA with the file.
Other IccFile methods that are useful when reading ESDS records include:
v isReadable
v recordFormat
v recordIndex
v recordLength
Reading RRDS records

To access an RRDS record, you must use a relative record number (RRN) that is
held in an IccRRN object.
Before reading a record, use the registerRecordIndex method of the IccFile class
to associate an object of class IccRRN with the file.
Other IccFile methods that are useful when reading RRDS records include:
v isReadable
v recordFormat
v recordIndex
v recordLength
20
Writing new records

The writing of new records is also known as adding records. This topic describes
how to write records that have not previously been written. You cannot write records
that already exist unless they have been previously been put into update mode.
See Updating existing records on page 22 for more information.
A write operation uses two classes: IccFile to perform the operation, and either
IccKey, IccRBA, or IccRRN to identify the record (depending on whether the file
access type is KSDS, ESDS, or RRDS). Before writing a record, you must use the
registerRecordIndex method of the IccFile class to associate an object of class
IccKey, IccRBA, or IccRRN with the file. The writeRecord method of IccFile class
actually writes the record.
If you have more than one record to write, you can improve the speed of writing by
using mass insertion of data. Begin and end this mass insertion by calling the
beginInsert and endInsert methods of the IccFile class.
Writing KSDS records

You must use a key, which is held in an IccKey object, to access KSDS records. A
complete key is a character string that uniquely identifies a record.
The writeRecord method of IccFile class actually writes the record.
Other IccFile methods that are useful when writing KSDS records include:
v isAddable
v
v
v
v
recordLength
recordIndex
keyLength
keyPosition
v registerRecordIndex
Writing ESDS records

You must use a relative byte address (RBA) that is held in an IccRBA object to
access the beginning of an ESDS record.
IccFile methods that are useful when writing ESDS records include:
v
v
v
v
v
isAddable
recordFormat
recordLength
recordIndex
registerRecordIndex
Writing RRDS records

Use the writeRecord method to add a new RRDS record. After writing the record,
you can use the number method on the IccRBA object to discover the assigned
relative byte address for the record that you have just written.
IccFile methods that are useful when writing RRDS records include:
v isAddable
v recordFormat
v recordLength
v recordIndex
21
v registerRecordIndex
Updating existing records

The updating of an existing record is also known as rewriting a record. Before
updating a record, you must first read it by using the readRecord in update mode.
This locks the record so that nobody else can change it.
Next, use the rewriteRecord method to update the record. Note that the IccFile
object remembers which record is being processed and this information is not
passed in again.
For an example, see Figure 13 on page 23.
The following restrictions apply to updating records:
v The base key in a KSDS file must not be changed when the record is modified.
v If the file definition allows variable-length records, the length of the record can be
changed.
v The length of records in an ESDS, RRDS, or fixed-length KSDS file must not be
changed on update.
v For a file that is defined to CICS as containing fixed-length records, the length of
record that is being updated must be the same as the original length.
v The length of an updated record must not be greater than the maximum that is
defined to VSAM.
Deleting records
Normal and locked records can be deleted from KSDS and RRDS files. Records
can never be deleted from ESDS files.
Deleting normal records

The deleteRecord method of the IccFile class deletes one or more records,
provided that they are not locked. (Records are locked when they are read by the
readRecord method in update mode.) The records that are to be deleted are
defined by the IccKey or IccRRN object.
Deleting locked records

The deleteLockedRecord method of IccFile class deletes a record that has been
previously locked. (That is, the record is currently being accessed by the
readRecord method in update mode.)
Browsing records
Browsing, or sequential reading of files uses another class: IccFileIterator. An
object of this class must be associated with an IccFile object and an IccKey,
IccRBA, or IccRRN object. After this association has been made, the
IccFileIterator object can be used without further reference to the other objects.
Browse forward in the file by using the readNextRecord method. Browse backward
by using the readPreviousRecord method.
The reset method resets the IccFileIterator object to point to the record that is
specified by the IccKey or IccRBA object.
Examples of how to browse files are shown in Figure 13 on page 23.
22
Example of file control

Figure 13 shows how to use the IccFile and IccFileIterator classes. The source for
this sample can be found in the samples directory (see Sample source code) in
the file iccfil.cpp. The example code is presented without any of the terminal
input and output that can be found in the source file.
// Foundation class header files
const char* fileRecords[] =
{
// Data used by the sample program
// NAME
KEY PHONE
USERID
"BACH, J S
003 00-1234
BACH
",
"BEETHOVEN, L
007 00-2244
BEET
",
"CHOPIN, F
004 00-3355
CHOPIN
",
"HANDEL, G F
005 00-4466
HANDEL
",
"MOZART, W A
008 00-5577
WOLFGANG "
};
{
short
recordsDeleted = 0;
IccFileId
id("ICCKFILE");
IccKey
key(3,IccKey::generic);
IccFile
file( id );
file.registerRecordIndex( &key );
key = "00";
recordsDeleted = file.deleteRecord();
IccBuf
buffer(40);
key.setKind( IccKey::complete );
for (short j = 0; j < 5; j++)
{
buffer = fileRecords[j];
key.assign(3, fileRecords[j]+15);
file.writeRecord( buffer );
}
IccFileIterator fIterator( &file, &key );
key = "000";
buffer = fIterator.readNextRecord();
while (fIterator.condition() == IccCondition::NORMAL)
{
buffer = fIterator.readNextRecord();
}
key = "\xFF\xFF\xFF";
fIterator.reset( &key );
buffer = fIterator.readPreviousRecord();
while (fIterator.condition() == IccCondition::NORMAL)
{
buffer = fIterator.readPreviousRecord();
}
key = "008";
buffer = file.readRecord( IccFile::update );
buffer.replace( 4, "5678", 23);
file.rewriteRecord( buffer );
buffer = file.readRecord();
return;
}
Figure 13. Code example: File control
23
The first two lines include the header files for the Foundation Classes and the
standard main function that sets up the operating environment for the application
program.
The run method of the IccUserControl class contains the user code for this
example. Because a terminal is to be used, the example starts by creating a
terminal object and clearing the associated screen.
The key and file objects are first created and then used to delete all the records
whose key starts with 00 in the KSDS file ICCKFILE. Key is defined as a
generic key that has three bytes, only the first two of which are used in this
example.
The next section of code writes into records in the file all the data that is provided.
The data is passed by means of an IccBuf object that is created for this purpose.
setKind method is used to change key from generic to complete.
The for loop between these calls loops round all the data, and passes the data into
the buffer by using the operator= method of IccBuf. From there, it passes the data
into a record in the file, by way of writeRecord. On the way, the key for each record
is set, using assign, to be a character string that occurs in the data (three
characters that start 15 characters in).
The loop that is shown here uses sendLine to list to the terminal all the records in
ascending sequence of key. It uses an IccFileIterator object to browse the records.
It starts by setting the minimum value for the key, which does not actually exist in
this example. Also, it relies on CICS to find the first record in key sequence.
The loop continues until any condition other than NORMAL is returned.
The next loop is nearly identical to the last, but lists the records in reverse
sequence of key.
The program reads a record for update, and locks it so that others cannot change
it. It then modifies the record in the buffer and writes the updated record back to the
file.
The same record is read again and sent to the terminal, to show that it has been
updated.
Program control
This section describes how to access and use a program other than the one that is
currently executing. Program control uses the IccProgram class, one of the
resource classes.
You can load, unload and link to programs by using an IccProgram object. An
IccProgram object can be interrogated to obtain information about the program.
See the reference page for the IccProgram class for more details.
The example that is shown in Figure 14 on page 25 shows one program calling
another two programs in turn, with data passing between them by way of a
COMMAREA. One program is assumed to be local, the second is on a remote
CICS system. The programs are in two files, iccprg1.cpp and iccprg2.cpp, which
are in the samples directory (see Sample source code).
24
Most of the terminal I/O in these samples has been omitted from the code that
follows.
{
IccSysId
sysId( "ICC2" );
IccProgram
iccprg2( "ICCPRG2" );
IccProgram
remoteProg( "ICCPRG3" );
IccBuf
commArea( 100, IccBuf::fixed );
iccprg2.load();
if (iccprg2.condition() == IccCondition::NORMAL)
{
term->sendLine( "Loaded program: %s <%s> Length=%ld Address=%x",
iccprg2.name(),
iccprg2.conditionText(),
iccprg2.length(),
iccprg2.address() );
iccprg2.unload();
}
commArea = "DATA SET BY ICCPRG1";
iccprg2.link( &commArea );
remoteProg.setRouteOption( sysId );
commArea = "DATA SET BY ICCPRG1";
remoteProg.link( &commArea );
return;
};
Figure 14. Code example: Program control (ICCPRG1)
The code for both programs starts by including the header files for the CICS
Foundation Classes and the stub for the main method. The user code is located in
the run method of the IccUserControl class for each program.
The first program (ICCPRG1) creates an IccSysId object that represents the
remote region, and two IccProgram objects that represent the local and remote
programs that will be called from this program. A 100 byte, fixed length buffer object
is also created to be used as a communication area between programs.
The program then attempts to load and interrogate the properties of program
ICCPRG2.
The communication area buffer is set to contain some data that is to be passed to
the first program that ICCPRG1 links to (ICCPRG2). ICCPRG1 is suspended while
ICCPRG2 is run.
The called program, ICCPRG2, is a simple program, the main point of which is
shown in Figure 15.
IccBuf& commArea = IccControl::commArea();
commArea = "DATA RETURNED BY ICCPRG2";
return;
ICCPRG2 gains access to the communication area that was passed to it. It then
modifies the data in this communication area and passes control back to the
program that called it.
25
The first program (ICCPRG1) now calls a third program, ICCPRG3, this time on
another system. The setRouteOption requests that calls on this object are routed
to the remote system. The communication area is set again (because it will have
been changed by ICCPRG2), and it then links to the remote program (ICCPRG3 on
system ICC2).
The called program uses CICS temporary storage. The three important lines in
ICCPRG3 are shown in Figure 16.
IccBuf& commArea = IccControl::commArea();
commArea = "DATA RETURNED BY ICCPRG3";
return;
Again, the remote program (ICCPRG3) gains access to the communication area
that was passed to it. It modifies the data in this communication area and passes
control back to the program that called it.
Finally, the calling program ends and returns control to CICS.
Starting transactions asynchronously

The IccStartRequestQ class enables a program to start another CICS transaction
instance asynchronously (and optionally pass data to the started transaction). The
same class is used by a started transaction to gain access to the data that the task
that issued the start request passed to it. Finally, start requests (for some time in
the future) can be canceled.
Starting transactions
You can use any of the following IccStartRequestQ methods to establish what data
will be sent to the started transaction:
v registerData or
v setData
v setQueueName
v setReturnTermId
v setReturnTransId
v setTermId
v setUserId
The start of the transaction is requested by using the start method.
Accessing start data

A started transaction can access its start data by invoking the retrieveData method.
This method stores all the start data attributes in the IccStartRequestQ object such
that the individual attributes can be accessed using the following methods:
v data
v queueName
v returnTermId
v returnTransId
26
Canceling unexpired start requests

Unexpired start requests (that is, start requests for a future time that has not yet
been reached) can be canceled by using the cancel method.
Example of starting transactions

Table 6 shows the transactions and CICS systems that are involved in the example
scenario.
Table 6. Example of starting transactions
CICS system
ICC1
ICC2
Transaction
ISR1/ITMP
ISR2
Program
ICCSRQ1/ICCTMP
ICCSRQ2
Terminal
PEO1
PEO2
Transaction ISR1 starts on terminal PEO1 on system ICC1. It issues two start
requests; the first is canceled before it has expired. The second starts transaction
ISR2 on terminal PEO2 on system ICC2. This transaction accesses its start data
and finishes by starting transaction ITMP on the original terminal (PEO1 on system
ICC1).
The programs can be found in the samples directory (see Sample source code) in
the files iccsrq1.cpp and iccsrq2.cpp. Here, the code is presented without the
terminal IO requests.
Transaction ISR1 runs program iccsrq1.cpp on system ICC1. It is shown in
Figure 17 on page 28.
27
// Header files for CICS Foundation Classes

// Method that contains user code for this example
{
// Empty IccRequestId object to ID start requests
IccRequestId
req1;
// User-supplied identifier
IccRequestId
req2("REQUEST1");
// Time interval for starting transaction
IccTimeInterval
ti(0,0,5);
// Remote terminal on system where transaction starts
IccTermId
remoteTermId("PE02");
// Transaction started on remote system
IccTransId
ISR2("ISR2");
// Transaction started on local terminal
IccTransId
ITMP("ITMP");
// Buffer to hold start data
IccBuf
buffer;
// Prepares the start data
startQ->setRouteOption( "ICC2" );
startQ->setTermId( remoteTermId );
startQ->registerData( &buffer );
startQ->setReturnTermId( terminal()->name() );
startQ->setReturnTransId( ITMP );
startQ->setQueueName( "startqnm" );
// Sets data to be sent on start requests
buffer = "This is a greeting from program iccsrq1!!";
// Specifies delay for starting transaction ISR2
req1 = startQ->start( ISR2, &ti );
// Cancels transaction request
startQ->cancel( req1 );
// Resubmit transaction request and allow it to complete
req1 = startQ->start( ISR2, &ti, &req2 );
return;
}
Figure 17. Code example: Starting transactions (ISR1)
The program in Figure 17 first creates the following objects:

req1
An empty IccRequestId object that is ready to identify a particular start

request.
req2
An IccRequestId object that contains the user-supplied identifier

REQUEST1.
ti
An IccTimeInterval object that represents 0 hours, 0 minutes, and 5

seconds.
remoteTermId
An IccTermId object; the terminal on the remote system where you start a
transaction.
ISR2
An IccTransId object; the transaction that you start on the remote system.
ITMP
An IccTransId object; the transaction that the started transaction starts on

this programs terminal.
buffer
An IccBuf object that holds start data.
28
Next, the startRequestQ method of IccControl class returns a pointer to the single
instance (singleton) class IccStartRequestQ.
The program prepares the start data, which is passed when a start request is
issued. The setRouteOption method specifies that the start request is issued on
the remote system, ICC2. The setTermId method specifies on which terminal the
started transaction will run. The registerData method associates an IccBuf object
that contains the start data. (The contents of the IccBuf object are not actually
extracted until the start request is issued.) The setReturnTermId and
setReturnTransId methods allow the start requester to pass a transaction and
terminal name to the started transaction. These fields are typically used to allow the
started transaction to start another transaction (as specified) on another terminal;
that is, your terminal, in this case.
The setQueueName method passes the queue name to the started transaction.
Next, the program sets the data that is passed on start requests. Transaction ISR2
starts after an interval ti (5 seconds). The request identifier is stored in req1. Before
the five seconds has expired (that is, immediately), the program cancels the start
request.
Again, the program starts transaction ISR2 after an interval ti (5 seconds). This time
the request is allowed to expire, so transaction ISR2 is started on the remote
system. The program then ends and returns control to CICS.
Figure 18 shows an excerpt from the started program, iccsrq2.cpp (transaction
ISR2).
IccBuf
buffer;
IccRequestId
req("REQUESTX");
IccTimeInterval
ti(0,0,5);
// Check whether program was started correctly
if ( task()->startType() != IccTask::startRequest )
{
term->sendLine(
"This program should only be started via the StartRequestQ");
task()->abend( "OOPS" );
}
// Retrieve start data
startQ->retrieveData();
// Copy start data to buffer
buffer = startQ->data();
// Display start data to terminal
term->sendLine( "Start buffer contents = [%s]", buffer.dataArea() );
term->sendLine( "Start queue= [%s]", startQ->queueName() );
term->sendLine( "Start rtrn = [%s]", startQ->returnTransId().name());
term->sendLine( "Start rtrm = [%s]", startQ->returnTermId().name() );
// Delay 5 seconds
task()->delay( ti );
// Start a request on calling terminal
startQ->setTermId( startQ->returnTermId().name() );
startQ->setRouteOption( "ICC1" );
// Start transaction
startQ->start( startQ->returnTransId().name() );
return;
Figure 18. Code example: Starting transactions (ISR2)
Here, as in iccsrq1.cpp, it creates several objects:
29
buffer
An IccBuf object to hold the start data that you were passed by the calling
program (iccsrq1.cpp).
req
An IccRequestId object to identify the start that you will issue on your
callers terminal.
ti
An IccTimeInterval object that represents 0 hours, 0 minutes, and 5

seconds.
The startRequestQ method of the IccControl class returns a pointer to the

singleton class IccStartRequestQ.
The startType method of the IccTask class checks whether iccsrq2.cpp was started
by the start method, and not in any other way (such as by typing the transaction
name on a terminal). If it was not started as intended, it abends with an OOPS
abend code.
The program then retrieves the start data that was passed by iccsrq1.cpp and
stored within the IccStartRequestQ object for subsequent access.
The start data buffer is copied into the IccBuf object. The other start data items
(queue, returnTransId, and returnTermId) are displayed on the terminal.
The program delays for five seconds, then uses the setTermId method to signal
that a start request is being issued on the calling programs terminal. The
setRouteOption method indicates that the transaction starts on the callers system
(ICC1).
The program starts a transaction called ITMP (the name of which was passed by
iccsrq1.cpp in the returnTransId start information) on the originating terminal (where
iccsrq1.cpp completed as it started this transaction). Having issued the start
request, iccsrq1.cpp ends, by returning control to CICS.
Finally, transaction ITMP runs on the first terminal. This is the end of this
demonstration of how transactions are started asynchronously.
Transient data
The transient data classes, IccDataQueue and IccDataQueueId, allow you to store
data in transient data queues for subsequent processing.
You can:
v Read data from a transient data queue (readItem method)
v Write data to a transient data queue (writeItem method)
v Delete a transient data queue (empty method)
An IccDataQueue object is used to represent a temporary storage queue. An
IccDataQueueId object is used to identify a queue by name. When the
IccDataQueueId object is initialized, it can be used to identify the queue as an
alternative to using its name, with the advantage of additional error detection by the
C++ compiler.
The methods that are available in IccDataQueue class are similar to those that are
in the IccTempStore class. For more information, see Temporary storage on page
32.
30
Reading transient data

The readItem method is used to read items from the queue. It returns a reference
to the IccBuf object that contains the information.
Writing transient data

The writeItem method adds a new item of data to the queue, taking the data from
the buffer that is specified.
Deleting transient data queues

The empty method deletes all items on the queue.
Example of managing transient data

The sample program in Figure 19 demonstrates how to use the IccDataQueue and
IccDataQueueId classes. It can be found in the samples directory (see Sample
source code) in the file iccdat.cpp. Here, the code is presented without the
// Header files
// Buffer for the example
const char* queueItems[] =
{
};
// Example code
{
short itemNum =1;
IccBuf
buffer( 50 );
IccDataQueueId
id( "ICCQ" );
IccDataQueue
queue( id );
queue.empty();
for (short i=0 ; i<3 ; i++)
{
buffer = queueItems[i];
queue.writeItem( buffer );
}
while ( queue.condition() == IccCondition::NORMAL )
{
}
return;
}
Figure 19. Code example: Managing transient data
The example first defines a data buffer. The run method of the IccUserControl
class contains the user code for this example.
The program first creates an identification object of type IccDataQueueId that
contains ICCQ. It then creates an IccDataQueue object that represents the
transient data queue ICCQ, which it empties of data.
The for loop writes the three data items to the transient data object. The data is
passed by way of an IccBuf object that was created for this purpose.
31
Having written out three records, the program now reads them back in to show that
they were successfully written. The program then ends and returns control back to
CICS.
Temporary storage
The temporary storage classes, IccTempStore and IccTempStoreId, allow you to
store data in temporary storage queues.
You can:
v Read an item from the temporary storage queue (readItem method)
v Write a new item to the end of the temporary storage queue (writeItem method)
v Update an item in the temporary storage queue (rewriteItem method)
v Read the next item in the temporary storage queue (readNextItem method)
v Delete all the temporary data (empty method)
An IccTempStore object is used to represent a temporary storage queue. An
IccTempStoreId object is used to identify a queue by name. When the
IccTempStoreId object is initialized, it can be used to identify the queue as an
alternative to using its name, with the advantage of additional error detection by the
C++ compiler.
The methods that are available in IccTempStore class are similar to those that are
in the IccDataQueue class. For more information about these, see Transient data
on page 30.
Reading items from temporary storage queues

The readItem method of IccTempStore reads the specified item from the
temporary storage queue. It returns a reference to the IccBuf object that contains
the information.
Writing items to temporary storage queues

The writing of items to a temporary storage queue is also known as adding items.
This section describes how to write items that have not previously been written. You
can write items that already exist by using the rewriteItem method. See Updating
items for more information.
The writeItem method of theIccTempStore class adds a new item at the end of the
queue, taking the data from the buffer that is specified. If this is done successfully,
the item number of the record added is returned.
Updating items
The updating of an item in a temporary storage queue is also known as rewriting an
item. The rewriteItem method of the IccTempStore class is used to update the
specified item in the temporary storage queue.
Deleting items
You cannot delete individual items in a temporary storage queue. To delete all the
temporary data that is associated with an IccTempStore object, use the empty
method of the IccTempStore class.
32
Example of using temporary storage

The sample program in Figure 20 demonstrates how to use the IccTempStore and
IccTempStoreId classes. This program can be found in the samples directory (see
Sample source code) in the file icctmp.cpp. The sample is presented here without
the terminal I/O requests.
// Header files
#include <stdlib.h>
// Defines buffer for example
const char* bufferItems[] =
{
};
// Method containing temporary storage queue example
{
short itemNum = 1;
// Identification object for temporary storage queue
IccTempStoreId id("ICCSTORE");
// Temporary storage queue
IccTempStore
store( id );
IccBuf
buffer( 50 );
store.empty();
for (short j=1 ; j <= 3 ; j++)
{
buffer = bufferItems[j-1];
store.writeItem( buffer );
}
// Read buffer from temporary storage queue
buffer = store.readItem( itemNum );
// Write data to temporary storage queue
while ( store.condition() == IccCondition::NORMAL )
{
// Modify data
buffer.insert( 9, "Modified " );
store.rewriteItem( itemNum, buffer );
itemNum++;
// Overwrite data in buffer
}
// Verify that temporary storage items are updated
itemNum = 1;
while ( store.condition() == IccCondition::NORMAL )
{
term->sendLine( " - record #%d = [%s]", itemNum,
(const char*)buffer );
buffer = store.readNextItem();
}
return;
}
Figure 20. Code example: Managing temporary storage queues
The example first creates an identification object, IccTempStoreId, that contains

the field ICCSTORE. It then creates an IccTempStore object that represents the
temporary storage queue ICCSTORE, which it empties of records. The loop writes
33
the three data items to the Temporary Storage object. The data is passed by way of
an IccBuf object that was created for this purpose.
The program in Figure 20 on page 33 then reads the items back in, modifies the
item, and rewrites it to the temporary storage queue. First, the readItem method is
used to read the buffer from the temporary storage object. The data in the buffer
object is changed by using the insert method of the IccBuf class. Then, the
rewriteItem method overwrites the buffer. The loop continues and the next buffer
item is read.
The next loop reads the temporary storage queue items again to verify that they
have been updated. The program then ends and returns control to CICS.
Terminal control
The terminal control classes, IccTerminal, IccTermId, and IccTerminalData, allow
you to send data to, receive data from, and get information about, the terminal that
belongs to the CICS task.
An IccTerminal object is used to represent the terminal that belongs to the CICS
task. It can be created only if the transaction has a 3270 terminal as its principal
facility. The IccTermId class is used to identify the terminal. IccTerminalData,
which is owned by IccTerminal, contains information about the terminal
characteristics.
Sending data to a terminal

The send and sendLine methods of IccTerminal class are used to write data to
the screen. Alternatively, you can use the << operators to send data to the terminal.
Before sending data to a terminal, you can set parameters, such as the position of
the cursor on the screen or the color of the text, by using the set... methods. You
can also erase the data that is currently displayed at the terminal, by using the
erase method, and free the keyboard to receive input, by using the freeKeyboard
method.
Receiving data from a terminal

The receive and receive3270data methods of IccTerminal class are used to
receive data from the terminal.
Finding the characteristics and current state of a terminal

You can get information about the characteristics of the terminal and about its
current state.
The data object points to the IccTerminalData object, which contains information
about the characteristics of the terminal. The IccTerminalData class methods allow
you to discover, for example, the height of the screen or whether the terminal
supports Erase Write Alternative. Some of the methods in IccTerminal also give
you information about characteristics, such as how many lines a screen holds.
Other methods that give you information about the current state of the terminal
include line, which returns the current line number, and cursor, which returns the
current cursor position. For more information about the IccTerminalData class and
its methods, see the class reference page.
34
Example of terminal control

The sample program in Figure 21 shows how to use the IccTerminal, IccTermId,
and IccTerminalData classes. This program can be found in the samples directory
(see Sample source code) in the file icctrm.cpp.
// Header files
// Terminal control example
#include "iccmain.cpp"void IccUserControl::run()
{
// Create terminal object and clear screen
IccTerminal& term = *terminal();
term.erase();
// Send data to the terminal
term.sendLine( "First part of the line..." );
term.send( "... a continuation of the line." );
term.sendLine( "Start this on the next line" );
term.sendLine( 40, "Send this to column 40 of current line" );
term.send( 5, 10, "Send this to row 5, column 10" );
term.send( 6, 40, "Send this to row 6, column 40" );
// Send a blank line to the terminal
term.setNewLine();
// Change text color to red
term.setColor( IccTerminal::red );
term.sendLine( "A Red line of text.");
// Change highlight color to blue and text to reverse video
term.setColor( IccTerminal::blue );
term.setHighlight( IccTerminal::reverse );
term.sendLine( "A Blue, Reverse video line of text.");
// Using I/O style interface to terminal
term << "A cout sytle interface... " << endl;
term << "you can " << "chain input together; "
<< "use different types, eg numbers: " << (short)123 << " "
<< (long)4567890 << " " << (double)123456.7891234 << endl;
term << "... and everything is buffered till you issue a flush."
<< flush;
// Wait for F12 keystroke to end program
term.send( 24,1, "Program icctrm complete: Hit PF12 to End" );
term.waitForAID( IccTerminal::PF12 );
term.erase();
return;
}
Figure 21. Code example: Controlling CICS terminals
The run method of the IccUserControl class contains the user code for this
example. Because a terminal is to be used, the example starts by creating a
terminal object and clearing the associated screen. The send and sendLine
methods are used to send data to the terminal. All these methods can take IccBuf
object references (const IccBuf&) instead of string literals (const char*). The
setNewLine method is then used to send a blank line to the screen.
Next, the setColor method is used to set the color of the text on the screen. The
setHighlight method is used to set the background highlighting and specify that the
text is displayed in reverse video.
Figure 21 also shows how to use the iostream-like interface. The endl command
starts new data on the next line. To improve performance, you can buffer data in the
terminal until a flush command is issued, which sends the data to the screen.
35
The waitForAID method causes the terminal to wait until the specified key is hit,
before calling the erase method to clear the display. The program then ends and
returns control to CICS.
Time and date services

The IccClock class controls access to the CICS time and date services.
IccAbsTime holds information about absolute time (the time in milliseconds that
has elapsed since the beginning of the year 1900), which can be converted to other
date and time formats. The methods that are available on IccClock objects and on
IccAbsTime objects are very similar.
The sample program in Figure 22 on page 37 demonstrates how to use the
IccClock class. The source for this program can be found in the samples directory
(see Sample source code) in the file iccclk.cpp. The sample is presented here
without the terminal I/O requests.
36
// Header files
{
// Create a clock object
IccClock clock;
// Display current system date on terminal
term->sendLine( "date() = [%s]",
clock.date() );
// Display current date in various formats
// without using a separator character
term->sendLine( "date(DDMMYY) = [%s]",
clock.date(IccClock::DDMMYY) );
term->sendLine( "date(MMDDYY) = [%s]",
clock.date(IccClock::MMDDYY));
term->sendLine( "date(YYDDD) = [%s]",
clock.date(IccClock::YYDDD));
// Display current date using a colon as a separator
term->sendLine( "date(DDMMYY,:) = [%s]",
clock.date(IccClock::DDMMYY,:));
// Display the number of days since 1900
term->sendLine( "daysSince1900() = %ld",
clock.daysSince1900());
// Display current day of week
term->sendLine( "dayOfWeek() = %d",
clock.dayOfWeek());
if ( clock.dayOfWeek() == IccClock::Friday )
term->sendLine( 40, "Today IS Friday" );
else
term->sendLine( 40, "Today is NOT Friday" );
// Display current day of month
term->sendLine( "dayOfMonth() = %d",
clock.dayOfMonth());
// Display current month of year
term->sendLine( "monthOfYear() = %d",
clock.monthOfYear());
// Display current time in various format
term->sendLine( "time() = [%s]",
clock.time() );
term->sendLine( "time(-) = [%s]",
clock.time(-) );
// Display current year
term->sendLine( "year() = [%ld]",
clock.year());
return;
};
Figure 22. Code example: Using CICS time and date services
In this example, the date method is used to return the date in the format that is
specified by the format enumeration. In sequence, the formats are system,
DDMMYY, MMDDYY, and YYDDD. The character that is used to separate the fields
is specified by the dateSeparator character, which defaults to nothing if it is not
specified. A colon (:) is used as the separator character in the example, to display
the date in DD:MM:YY format.
Next, the sample demonstrates the use of the daysSince1900, dayOfWeek,
dayOfMonth, and monthOfYear methods. The dayOfWeek method returns an
enumeration that indicates the day of the week. If the day is Friday, a message is
sent to the screen, Today IS Friday; otherwise the message Today is NOT Friday
is sent.
37
Figure 22 on page 37 also shows how to use the time method of the IccClock
class. The current time is sent to the terminal, first without a separator (that is
HHMMSS format), then with - separating the digits (that is, HH-MM-SS format).
The current year is also sent. The program then ends and returns control back to
CICS.
38

This chapter describes how the Foundation Classes have been designed to
respond to various error conditions that they might encounter. These are discussed
under the following headings:
v Foundation Class Abend codes
v C++ Exceptions and the Foundation Classes
v CICS conditions on page 42
v Platform differences on page 44
Foundation Class Abend codes

For serious errors (such as not enough storage to create an object), the Foundation
Classes immediately terminate the CICS task.
All CICS Foundation Class abend codes are of the form ACLx. If your application is
terminated with an abend code that starts with ACL, refer to Appendix A, CICS
Foundation Class abend codes, on page 179.
C++ Exceptions and the Foundation Classes

C++ exceptions are managed by using the reserved words try, throw, and catch.
Refer to your compilers documentation or to one of the C++ books in the
bibliography for more information.
Figure 23 on page 40 shows an example of how to throw exceptions. The sample
program is from the file iccexc1.cpp (see Sample source code):
39
class Test {
public:
void tryNumber( short num ) {
IccTerminal* term = IccTerminal::instance();
*term << "Number passed = " << num << endl << flush;
if ( num > 10 ) {
*term << ">>Out of Range - throwing exception" << endl << flush;
throw "!!Number is out of range!!";
}
}
};
{
IccTerminal* term = IccTerminal::instance();
term->erase();
*term << "This is program iccexc1 ..." << endl;
try {
Test test;
test.tryNumber(
test.tryNumber(
test.tryNumber(
test.tryNumber(
}
1 );
7 );
11 );
6 );
catch( const char* exception )

{
term->setLine( 22 );
*term << "Exception caught: " << exception << endl << flush;
}
term->send( 24,1,"Program iccexc1 complete: Hit PF12 to End" );
term->waitForAID( IccTerminal::PF12 );
term->erase();
return;
}
Figure 23. Code example: Throwing and catching exceptions
The example first declares class Test, which has one public method, tryNumber.
This method is implemented inline so that if an integer that is greater than ten is
passed, an exception is thrown. It also displays information on a CICS terminal.
The run method of IccUserControl class contains the user code for this example.
After erasing the terminal display and writing some text, the program begins a try
block (which can scope any number of lines of C++ code). The program creates a
Test object and invokes its only method, tryNumber, with various parameters. The
first two invocations (1, 7) succeed, but the third (11) causes tryNumber to throw
an exception. The fourth tryNumber invocation (6) is not executed because an
exception causes the program execution flow to leave the current try block.
The program leaves the try block and looks for a suitable catch block. A suitable
catch block is one with arguments that are compatible with the type of exception
that is being thrown (in this case, a char* exception). The catch block writes a
message to the CICS terminal, then execution resumes at the line after the catch
block.
The output from this CICS program is shown in Figure 24 on page 41:
40
This is program iccexc1 ...

Number passed = 1
Number passed = 7
Number passed = 11
>>Out of Range - throwing exception
Exception caught: !!Number is out of range!!
Program iccexc1 complete: Hit PF12 to End
Figure 24. Code example: Output from exception handling example
The CICS Foundation Classes do not throw char* exceptions as shown in

Figure 23 on page 40. Instead, they throw IccException objects. Several types of
IccException objects exist. The type method returns an enumeration that indicates
the type. Supported exception types include the following:
objectCreationError
An attempt to create an object was invalid. This happens, for example, if an
attempt is made to create a second instance of a singleton class, such as
IccTask.
invalidArgument
A method was called with an invalid argument. This happens, for example,
if an IccBuf object with too much data is passed to the writeItem method of
the IccTempStore class by the application program.
This exception is also thrown when a program attempts to create a
subclass of IccResourceId (such as IccTermId ) with a string that is too
long.
Figure 25 shows how an invalidArgument exception is thrown. This code
sample can be found in the samples directory (see Sample source code)
in the file iccexc2.cpp. The sample is presented here without many of the
{
try
{
IccTermId id1( "1234" );
IccTermId id2( "12345");
}
catch( IccException& exception )
{
terminal()->send( 21, 1, exception.summary() );
}
return;
}
Figure 25. Code example: Throwing an invalidArgument exception
In Figure 25, the first IccTermId object is successfully created, but the
second caused an IccException to be thrown, because the string 12345
is five bytes where only four are allowed.
invalidMethodCall
A method cannot be called. A typical reason is that the object cannot honor
the call in its current state. For example, a readRecord call on an IccFile
object is honored only if an IccRecordIndex object, to specify which record
is to be read, has already been associated with the file.
41
CICSCondition
A CICS condition that is listed in the IccCondition structure has occurred in
the object, and the object was configured to throw an exception.
platformError
An operation is invalid because of limitations of this particular platform. For
example, an attempt to create an IccJournal object would fail under CICS
for OS/2 because no CICS journal services exist on this server.
A platformError exception can occur at three levels:
1. An object is not supported on this platform.
2. An object is supported on this platform, but a particular method is not.
3. A method is supported on this platform, but a particular positional
parameter is not.
See Platform differences on page 44 for more information.
familyConformanceError
Family subset enforcement is on for this program and an operation that is
not valid on all supported platforms has been attempted.
internalError
The CICS foundation classes have detected an internal error. Please
contact your customer service representative for assistance.
CICS conditions
The CICS foundation classes provide a powerful framework for handling conditions
that happen when you are running an application. Accessing a CICS resource can
raise several CICS conditions as documented in the reference pages for the
foundation classes.
A condition can represent either an error, or information that is being returned to the
calling application. The deciding factor is the context in which the condition is
raised.
The application program can handle the CICS conditions in several ways. Each
CICS resource object, such as a program, file, or data queue, can handle CICS
conditions differently if required.
A resource object can be configured to take one of the following actions for each
condition that it can encounter:
v noAction : No action is taken if a condition is encountered (the default). See
Manual condition handling (noAction).
v callHandleEvent: Handles conditions automatically. See Automatic condition
handling (callHandleEvent) on page 43.
v throwException: Throws an exception if a condition is encountered. See
Exception handling (throwException) on page 44.
v abendTask: Throws a CICS abend if a condition is encountered. See Severe
error handling (abendTask) on page 44.
Manual condition handling (noAction)

This is the default action for all CICS conditions. It applies to any resource object
and can be explicitly activated as shown in Figure 26 on page 43.
42
IccTempStore
temp("TEMP1234");
temp.setActionOnCondition(IccResource::noAction,
IccCondition::QIDERR);IccTempStore
IccBuf
buf(40);
temp("TEMP1234");
temp.setActionOnCondition(IccResource::noAction,
IccCondition::QIDERR);
buf = temp.readNextItem();
switch (temp.condition())
{
case IccCondition::QIDERR:
//do whatever here
·
default:
//do something else here
}
Figure 26. Code example: Manual condition handling
The noAction setting means that when CICS raises the QIDERR condition as a
result of action on the temp object, no action is taken. The condition must be
handled manually using the condition method.
Automatic condition handling (callHandleEvent)

You can activate automatic condition handling for any CICS condition, such as
QIDERR, as shown in Figure 27.
IccTempStore
temp("TEMP1234");
temp.setActionOnCondition(IccResource::callHandleEvent,
class MyTempStore : public IccTempStore
{
public:
MyTempStore(const char* storeName) : IccTempStore(storeName) {}
void HandleEventReturnOpt handleEvent(IccEvent& event);
};
IccResource::HandleEventReturnOpt handleEvent(IccEvent& event)
{
switch (event.condition())
{
case ...
·
case IccCondition::QIDERR:
//Handle QIDERR condition here.
·
//
default:
return rAbendTask;
}
}
Figure 27. Code example: Automatic condition handling
When a call to any method on object temp causes CICS to raise the QIDERR
condition, the handleEvent method is automatically called. Because the
handleEvent method is only a virtual method, this call is useful only if the object
belongs to a subclass of IccTempStore and the handleEvent method has been
overridden. In the code example, a subclass of IccTempStore declares a
constructor and overrides the handleEvent method. It then implements the
43
handleEvent method. This code is called for any MyTempStore object that is
configured to callHandleEvent for a particular CICS condition.
Exception handling (throwException)

Activate this for any CICS condition, such as QIDERR, as shown in Figure 28.
Exception handling is by way of the C++ exception handling model and using try,
throw, and catch.
IccTempStore
temp("TEMP1234");
temp.setActionOnCondition(IccResource::throwException,
...
try
{
buf = temp.readNextItem();
·
}
catch (IccException& exception)
{
//Exception handling code
·
}
Figure 28. Code example: Condition exception handling
An exception is thrown if any of the methods inside the try block raise the QIDERR
condition for object temp. When an exception is thrown, C++ unwinds the stack
and resumes execution at an appropriate catch block. It is not possible to resume
within the try block. For a fuller example of the above, see sample iccexc3.cpp.
Note: Exceptions can be thrown from the CICS Foundation Classes for many
reasons other than those that are shown in Figure 28. See C++ Exceptions
and the Foundation Classes on page 39 for more information.
Severe error handling (abendTask)

This option allows CICS to terminate the task when particular conditions are raised.
Activate this for any CICS condition, such as QIDERR, as shown in Figure 29.
IccTempStore
temp("TEMP1234");
temp.setActionOnCondition(IccResource::abendTask,
Figure 29. Code example: Severe error handling
If CICS raises the QIDERR condition for object temp, the CICS task terminates with
an ACL3 abend.
Platform differences
The CICS Foundation Classes are designed to be independent of the CICS
platform on which they are running. However, some differences exist between
platforms; these differences and ways of handling them are described in this
section.
Applications can be run in one of two modes:
44
fsAllowPlatformVariance
Applications that are written using the CICS Foundation Classes can
access all the functions that are available on the target CICS server.
fsEnforce
Applications are restricted to the CICS functions that are available across
all CICS Servers (MVS, Open Systems, Windows and OS/2).
The default is to allow platform variance and the alternative is to force the
application to use only features that are common to all CICS platforms.
The class headers are the same for all platforms and they support (that is, define)
all the CICS functions that are available through the Foundation Classes on any of
the CICS platforms. The restrictions for each platform are documented in the
reference pages. Platform variations exist at the object level, the method level and
the parameter level.
Object level
Some objects are not supported on particular CICS server platforms. For example,
IccJournal objects cannot be created on CICS for Windows, because CICS for
Windows does not support journaling services. Similarly, IccConsole objects cannot
be created on CICS for AIX because these platforms do not support console
services.
If you initialize your application with fsAllowPlatformVariance selected, any attempt
to create an IccJournal object on CICS for Windows or an IccConsole object on
CICS for AIX causes an IccException object of type platformError to be thrown.
However, these objects can be created successfully on other CICS platforms.
If you initialize your application with fsEnforce selected, the previous examples
cause an IccException object of type familyConformanceError to be thrown on all
platforms.
Method level
Use of an objects methods can be restricted on particular platforms. For example,
the programId method in the IccControl class (shown in Figure 30) executes
correctly on CICS for Windows but throws an IccException object of type
platformError on CICS for AIX.
{
if (strcmp(programId.name(), "PROG1234") == 0)
//do something
}
Figure 30. Code example: Method level enforcement
Alternatively, if you initialize your application with family subset enforcement on (see
the initializeEnvironment function of the Icc structure), method programId throws an
IccException object of type familyConformanceError on any CICS server platform.
Parameter level
At this level a method is supported on all platforms, but a particular positional
parameter has some platform restrictions. Consider the abend method in the
IccTask class, shown in Figure 31 on page 46.
45
task()->abend();
(1)
task()->abend("WXYZ");
(2)
task()->abend("WXYZ", IccTask::respectAbendHandler);
(3)
task()->abend("WXYZ", IccTask::ignoreAbendHandler);
(4)
task()->abend("WXYZ", IccTask::ignoreAbendHandler,
IccTask::suppressDump);
(5)
Figure 31. Code example: Parameter level enforcement
Abends (1) to (4) run successfully on all CICS server platforms.

If family subset enforcement is off, abend (5) throws an IccException object of type
platformError on a CICS for AIX platform, but not on a CICS for Windows, CICS
for OS/2, or CICS for MVS/ESA platform.
If family subset enforcement is on, abend (5) throws an IccException object of type
familyConformanceError on all target CICS platforms.
46
Chapter 6. CICS Foundation Classes Reference Pages

IccAbendData
Purpose
Retrieves diagnostic information from CICS about program abends.
Synopsis
#include <iccabdeh.hpp>
class IccAbendData
{
public:
IccAbendData();
const char* abendCode(Icc::GetOpt opt=Icc::object);
static IccAbendData* instance();
};
Description
The IccAbendData class is a singleton class that is used to retrieve diagnostic
information from CICS about program abends. It is derived from the IccResource
class.
Class Members
IccAbendData constructor
IccAbendData();
This constructor creates an IccAbendData object.

IccAbendData::abendCode
const char* abendCode(
IN Icc:GetOpt opt=Icc::object
);
opt
An enumeration, which defined in the Icc structure, that indicates whether a
value should be refreshed from CICS or whether the existing value should be
retained. The possible values are described under the Icc::GetOpt
enumeration.
Returns the current four-character abend code.
Equivalent EXEC CICS call: ASSIGN ABENDCODE
Conditions: INVREQ
IccAbendData::instance
static IccAbendData* instance();
Returns a pointer to the single IccAbendData object. If the object does not already
exist, it is created by this method.
47
Related Information
Icc class
IccBase class
IccResource class
IccAbsTime
Purpose
Specifies the absolute time.
Synopsis
#include <icctimeh.hpp>
class IccAbsTime
{
public:
IccAbsTime(const char* absTime);
IccAbsTime(const IccAbsTime& time);
const char* date(IccClock::DateFormat format=IccClock::defaultFormat,
char dateSeparator=/0);
unsigned long dayOfMonth();
IccClock::DayOfWeek dayOfWeek();
unsigned long daysSince1900();
virtual unsigned long hours();
long double milliSeconds();
virtual unsigned long minutes() const;
IccClock::MonthOfYear monthOfYear();
IccAbsTime& operator=(const IccAbsTime& absTime);
const char* packedDecimal() const;
virtual unsigned long secons() const;
const char* time(char timeSeparator=/0)
unsigned long timeInHours();
unsigned long timeInMinutes();
unsigned long timeInSeconds();
unsigned long year();
};
Description
The IccAbsTime class holds information about absolute time; that is, the time that
has elapsed since the beginning of the year 1900. The methods of this class return
the time in various formats. The IccAbsTime class is derived from the IccTime
class.
Class Members
IccAbsTime constructor (1)
IccAbsTime(const char* absTime);
absTime
The eight-byte value of time, in packed decimal format.
This constructor creates an IccAbsTime object.
IccAbsTime constructor (2)
IccAbsTime(const IccAbsTime& time);
48
Copy constructor for the IccAbsTime class.

IccAbsTime
const char* date(IccClock::DateFormat format=IccClock::defaultFormat,
char dateSeparator=/0);
format
An enumeration, which is defined in the IccClock class, that indicates the
format of the date. It defaults to the value that was set when the CICS region
was initialized.
dateSeparator
The character that separates the different fields of the date. The default is no
separator.
Returns the date as a character string.
Equivalent EXEC CICS call: FORMATTIME YYDDD/YYMMDD/and so on
Conditions: ERROR (Open Systems only)
IccAbsTime::dayOfMonth
Returns the day of the month (in the range 1 through 31).
Equivalent EXEC CICS call: FORMATTIME DAYOFMONTH
IccAbsTime::dayOfWeek
unsigned long dayOfWeek();
Returns an enumeration, which is defined in the IccClock class, that indicates the
day of the week.
Equivalent EXEC CICS call: FORMATTIME DAYOFWEEK
IccAbsTime::daysSince1900
Returns the number of days since the beginning of the year 1900.
Equivalent EXEC CICS call: FORMATTIME DAYCOUNT
IccAbsTime::hours
virtual unsigned long hours() const;
Returns the hours component of the time.

IccAbsTime::milliSeconds
49
Returns the number of milliseconds that have elapsed since the beginning of the
year 1900.
IccAbsTime::minutes
Returns the minutes component of the time.

IccAbsTime::monthOfYear
IccClock::MonthOfYear monthOfYear();
Returns an enumeration, which is defined in the IccClock class, that indicates the
month of the year.
Equivalent EXEC CICS call: FORMATTIME MONTHOFYEAR
IccAbsTime::operator=
IccAbsTime& operator=(const IccAbsTime& absTime);
Assigns one IccAbsTime object to another.

IccAbsTime::packedDecimal
const char* packedDecimal() const;
Returns the time as an eight-byte packed decimal string that expresses the number
of milliseconds that have elapsed since the beginning of the year 1900.
IccAbsTime::seconds
virtual unsigned long seconds() const;
Returns the seconds component of the time.

IccAbsTime::time
const char* time (char timeSeparator /0);
timeSeparator
The character that delimits the time fields. The default is no separator.
Returns the time as a text string.
Equivalent EXEC CICS call: FORMATTIME TIME
IccAbsTime::timeInHours
unsigned long timeInHours();
Returns the number of hours that have elapsed since the day began.
IccAbsTime::timeInMinutes
unsigned long timeInMinutes();
Returns the number of minutes that have elapsed since the day began.
50
IccAbsTime::timeInSeconds
unsigned long timeInSeconds();
Returns the number of seconds that have elapsed since the day began.
IccAbsTime::year
Returns the year as a four-digit integer (for example, 2000).

Equivalent EXEC CICS call: FORMATTIME YEAR
Related Information
IccClock class
IccTime class
IccAlarmRequestId
Purpose
Represents a unique alarm request.
Synopsis
#include <iccrideh.hpp>
class IccBase
{
IccAlarmRequestId();
IccAlarmRequestId(const char* name,
const void* timerECA);
IccAlarmRequestId(const IccAlarmRequestId& id);
Icc::Bool isExpired();
IccAlarmRequestId& operator=(const IccRequestId& id);
IccAlarmRequestId& operator=(const IccAlarmRequestId& id);
IccAlarmRequestId& operator=(const char* requestName);
void setTimerECA(const void* timerECA);
const void* timerECA() const;
};
Description
An IccAlarmRequestId object represents a unique alarm request. It contains the
eight-character name of the request identifier and a pointer to a four-byte timer
event control area. IccAlarmRequestId is used by the setAlarm method of
IccClock class when setting an alarm, and the waitOnAlarm method of IccTask
when waiting for an alarm. The IccAlarmRequestId class is derived from the
IccRequestId class.
Class Members
IccAlarmRequestId constructor (1)
IccAlarmRequestId();
This constructor creates a new object with no information present.

51

IccAlarmRequestId(const char* name,
const void timerECA);
name
The eight-character name of the request.
timerECA
A pointer to a four-byte timer event control area.
This constructor creates an object with information already set.
IccAlarmRequestId(const IccAlarmRequestId& id);
id
A reference to an IccAlarmRequestId object.
This is the copy constructor.

IccAlarmRequestId
Icc::Bool isExpired();
This method returns a boolean, which is defined in Icc structure, that indicates
whether the alarm has expired.
IccAlarmRequestId (1)
IccAlarmRequestId& operator=(const IccRequestId& id);
id
A reference to an IccRequestId object.
This method copies information into an IccAlarmRequestId object.

IccAlarmRequestId& operator=(const IccAlarmRequestId& id);
id
A reference to an IccRequestId object.

IccAlarmRequestId& operator=(const char* requestName);
requestName
The eight-character name of the alarm request.
IccAlarmRequestId::setTimerECA
void setTimerECA(const void* timerECA);
timerECA
A pointer to a four-byte timer event control area.
This method sets the timer.
IccAlarmRequestId::TimerECA
const void* timerECA() const;
52
This method returns a pointer to the four-byte timer event control area.
Related Information
IccRequestId class
IccClock class
IccTask class
IccBase
Purpose
Base class for CICS Foundation Classes.
Synopsis
#include <iccbaseh.hpp>
class IccBase
{
public:
ClassType classType() const;
const char* className(NameOpt opt=customName);
unsigned short customClassNum() const;
void operator delete(void* object);
void* operator new(size_t size);
typedef enum {
cAbendData,
cAlarmRequestId,
cBuf,
cClock,
cConsole,
cControl,
cConvId,
cCUSTOM,
cDataQueue,
cDataQueueId,
cEvent
cException,
cFile,
cFileId,
cFileIterator,
cGroupId,
cJournal,
cJournalId,
cJournalTypeId,
cLockId
cMessage,
cPartnerId,
cProgram,
cProgramId,
cRecordIndex,
cRequestId,
cSemaphore,
cSession,
cStartRequestQ,
cSysId,
cSystem,.
cTask
cTempStore,
cTermId
cTerminal,
cTerminaData,
53
cTime,
cTPNameId,
cTransId,
cUser,
cUserId
} ClassType;
typedef enum {
baseName,
customName,
} NameOpt;
protected:
IccBase(ClassType type);
void setClassName(const char* className);
void setCustomClassNum(unsigned short number);
};
Description
The IccBase class is the base class from which all CICS Foundation Classes are
derived. The methods that are associated with the IccBase class are described
here although they can be called only on objects of the derived classes.
Class Members
IccBase constructor
IccBase(ClassType type);
type
An enumeration that indicates the subclass type.
This constructor creates an IccBase object.
IccBase::classType
public ClassType classType() const;
Returns an enumeration that indicates the subclass type. For example, this method
returns cTempStore for the IccTempStore class. The possible values are listed
under the ClassType enumeration.
IccBase::className
public const char* className(NameOpt opt=customName);
opt
An enumerator, which is defined in the IccBase class, that indicates whether to
return the base name of the class or the name as customized by the class. For
example, this method returns IccTempStore for an IccTempStore object.
Returns the name of the class. For example, suppose a class called MyDataQueue
inherits from the IccDataQueue class. If a MyDataQueue object calls the method
setClassName(MyDataQueue), a subsequent call to the method
MyDataQueue::className(IccBase::customName) returns MyDataQueue as the
class name. A subsequent call to the method
MyDataQueue::className(IccBase::baseName) returns IccDataQueue as the
base class name. In contrast, calling the className method on an IccDataQueue
object returns IccDataQueue for both opt values.
IccBase::customClassNum
public unsigned short customClassNum();
54
Returns the number that an application designer has associated with a class that
inherits from the IccBase class or any of its subclasses.
IccBase::operator delete
public void operator delete(void* object);
object
A pointer to an object that is to be destroyed.
Destroys an object.
IccBase::operator new
public void* operator new(size_t size);
size
The size of the new object in bytes.
Creates a new object of the given size. This operator enables the CICS Foundation
Classes to use CICS storage allocation.
IccBase::setClassName
protected void setClassName(const char* className);
className
The name of the new class.
Creates a string representation of the name of a class. For example, if you create a
class called MyDataQueue that inherits from the CICS Foundation Class
IccDataQueue, you can call setClassName(MyDataQueue) to create a string
representation of the class name. This is useful for diagnostic purposes.
IccBase::setCustomClassNum
protected void setCustomClassNum(unsigned short number);
number
The number that an application designer associates with a subclass for
identification purposes.
Assigns an identification number to new subclasses that inherit from the CICS
Foundation Classes.
IccBase::ClassType
public
typedef enum {
cAbendData,
cAlarmRequestId,
cBuf,
cClock,
cConsole,
cControl,
cConvId,
cCUSTOM,
cDataQueue,
cDataQueueId,
cEvent
cException,
cFile,
cFileId,
cFileIterator,
cGroupId,
cJournal,
55
cJournalId,
cJournalTypeId,
cLockId
cMessage,
cPartnerId,
cProgram,
cProgramId,
cRecordIndex,
cRequestId,
cSemaphore,
cSession,
cStartQequestQ,
cSysId,
cSystem,
cTask
cTempStore,
cTermId
cTerminal,
cTerminaData,
cTime,
cTPNameId,
cTransId,
cUser,
cUserId
} ClassType;
An enumeration that specifies the subclass types that can be returned by the
IccBase::ClassType method. The values are derived by deleting the first two
characters from the name of each CICS Foundation Class. cCustom allows the class
library to be extended by application developers.
IccBase::NameOpt
public typedef enum {
baseName
customName
} NameOpt;
baseName
Returns the default name that is assigned to the CICS Foundation Class.
customName
Returns the name that is assigned to a class by using the setClassName
method. If this method has not been invoked, it returns the default class name.
An enumeration that specifies whether the base name of the class or the name that
is assigned by an application developer is returned by the IccBase::className
method. It applies to subclasses that are derived from the CICS Foundation
Classes.
Related Information
IccDataQueue class
IccTempStore class
IccBuf
Purpose
Used for the general manipulation of buffers.
56
Synopsis
#include <iccbufeh.hpp>
class
{
IccBuf(unsigned long length=0,
DataAreaType type=extensible);
void* dataArea);
IccBuf(const char* text,
IccBuf(const IccBuf& buffer);
IccBuf& append(unsigned long length,
const void* dataArea);
IccBuf& append(const char* format,
...);
IccBuf& assign(unsigned longlength,
IccBuf& assign(const char* format,
...);
IccBuf& cut(unsigned long length,
unsigned long offset=0);
const void* dataArea(unsigned long offset=0) const;
unsigned long dataAreaLength() const;
DataAreaOwner dataAreaOwner() const;
DataAreaType dataAreaType() const;
unsigned long dataLength() const;
IccBuf& insert (unsigned long length,
const void* dataArea,
Icc::Bool isFMHContained() const;
operator const char*() const;
IccBuf& operator=(const IccBuf& buffer);
IccBuf& operator=(const char* text);
IccBuf& operator+=(const IccBuf& buffer);
IccBuf& operator+=(const char* text);
Icc::Bool operator==(const IccBuf& buffer) const;
Icc::Bool operator!=(const IccBuf& buffer) const;
operator<<(const IccBuf& buffer);
operator<<(const char* text);
operator<<(char ch);
operator<<(signed char ch);
operator<<(unsigned char ch);
operator<<(const signed char* text);
operator<<(const unsigned char* text);
operator<<(short num);
operator<<(unsigned short num);
operator<<(long num);
operator<<(unsigned long num);
operator<<(int num);
operator<<(float num);
operator<<(double num);
operator<<(long double num);
IccBuf& overlay(unsigned long length,
void* dataArea);
IccBuf& replace(unsigned long length,
unsigned long setDataLength(unsigned long length);
void setFMHContained(Icc::Bool yesNo=Icc::yes);
typedef enum {
internal,
external,
} DataAreaOwner;
typedef enum {
57
extensible,
fixed,
} DataAreaType;
};
Description
IccBuf class is supplied for the general manipulation of buffers. This class is used
by other classes that make calls to CICS, but does not itself call CICS services.
The IccBuf class is derived from the IccBase class. See also Buffer Objects.
Class Members
IccBuf constructor (1)
length
The initial length of the data area, in bytes. The default length is zero (0).
type
An enumeration that indicates whether the data area can be dynamically
extended. Possible values are extensible or fixed. The default is extensible.
This constructor creates an IccBuf object, allocating its own data area with the
given length and with all the bytes within it set to NULL.
void* dataArea);
length
The length of the supplied data name, in bytes.
dataArea
The address of the first byte of the supplied data area.
This constructor creates an IccBuf object that cannot be extended, and adopts the
given data area as its own.
IccBuf(const char* text,
text
A null-terminated string that is to be copied into the new IccBuf object.
type
An enumeration that indicates whether the data area can be extended. Possible
values are extensible or fixed. The default is extensible.
This constructor creates an IccBuf object, allocates its own data area with the
same length as the text string, and copies the string into its own data area.
IccBuf(const IccBuf& buffer);
buffer
A reference to an object that is to be copied into the new object.
58
This copy constructor creates a new IccBuf object that is a copy of the given
object. The created IccBuf object always has an internal data area.
IccBuf::append (1)
IccBuf& append(unsigned long length,
length
dataArea
This method appends data from the given data area to the data area in the object.
IccBuf::append (2)
IccBuf& append(const char* format,
...);
format
The null-terminated format string.
... The optional parameters.
This method appends data, in the form of format string and variable argument, to
the data area in the object. This is the same as the form that is used by printf in
the standard C library. It is the responsibility of the application programmer to
ensure that the optional parameters are consistent with the format string.
IccBuf::assign (1)
IccBuf& assign(unsigned longlength,
length
dataArea
This method assigns data from the given data area to the data area in the object.
IccBuf::assign (2)
IccBuf& assign(const char* format,
...);
format
The null-terminated format string.
... The optional parameters.
This method assigns data, in the form of format string and variable argument, to the
data area in the object. This is the same as the form that is used by printf in the
standard C library. It is the responsibility of the application programmer to ensure
that the optional parameters are consistent with the format string.
IccBuf::cut
IccBuf& cut(unsigned long length,
59
length
The number of bytes that are to be cut from the data area.
offset
The offset into the data area. The default is no offset.
This method makes the specified cut to the data in the data area and returns a
reference to the IccBuf object.
IccBuf::dataArea
const void* dataArea(unsigned long offset=0) const;
offset
The offset into the data area. The default is no offset.
This method returns the address of the data at the given offset into the data area.
IccBuf::dataAreaLength
unsigned long dataAreaLength() const;
This method returns the length of the data area in bytes.

IccBuf::dataAreaOwner
DataAreaOwner dataAreaOwner() const;
This method returns an enumeration that indicates whether the data area has been
allocated by the IccBuf constructor or has been supplied from elsewhere. The
possible values are listed under the DataAreaOwner enumeration.
IccBuf::dataAreaType
DataAreaOwner dataAreaType() const;
This method returns an enumeration that indicates whether the data area can be
extended. The possible values are listed under the DataAreaType enumeration.
IccBuf::dataLength
unsigned long dataLength() const;
This method returns the length of data in the data area. This cannot be greater than
the value that is returned by dataAreaLength.
IccBuf::insert
IccBuf& insert (unsigned long length,
length
The length of the data, in bytes, that is to be inserted into the IccBuf object.
dataArea
The start of the source data that is to be inserted into the IccBuf object.
offset
The offset in the data area where the data is to be inserted. The default is no
offset.
This method inserts the given data into the data area at the given offset and returns
a reference to the IccBuf object.
60
IccBuf::isFMHContained
Icc::Bool isFMHContained() const;
whether the data area contains Function Management Headers (FMHs).
IccBuf::operator const char*
operator const char*() const;
This method casts an IccBuf object to a null-terminating string. See the following
example:
IccBuf data("Hello World");
cout << (const char*) data;
IccBuf::operator= (1)
IccBuf& operator=(const IccBuf& buffer);
buffer
A reference to an IccBuf object.
This method assigns data from another buffer object and returns a reference to the
IccBuf object.
IccBuf::operator= (2)
IccBuf& operator=(const char* text);
text
The null-terminated string that is to be assigned to the IccBuf object.
This method assigns data from a null-terminating string and returns a reference to
the IccBuf object. See also the assign method.
IccBuf::operator+= (1)
IccBuf& operator+=(const IccBuf& buffer);
buffer
This method appends data from another buffer object and returns a reference to the
IccBuf object.
IccBuf::operator+= (2)
IccBuf& operator+=(const char* text);
text
The null-terminated string that is to be appended to the IccBuf object.
This method appends data from a null-terminated string and returns a reference to
the IccBuf object. See also the append method.
IccBuf::operator==
Icc::Bool operator==(const IccBuf& buffer) const;
buffer
61
whether the data that is contained in the buffers of the two IccBuf objects is the
same. It is true if the current lengths of the two data areas are the same, or if the
contents are the same.
IccBuf::operator!=
Icc::Bool operator!=(const IccBuf& buffer) const;
buffer
A reference to a IccBuf object.
whether the data that is contained in the buffers of the two IccBuf objects is
different. It is true if the current lengths of the two data areas are different, or if the
contents are different.
IccBuf::operator<< (1)
operator<<(const IccBuf& buffer);
This method appends another buffer.

operator<<(const char* text);
This method appends a string.

operator<<(char* ch);
This method appends a character.

operator<<(signed char ch);

operator<<(unsigned char ch);

operator<<(const signed char* text);

operator<<(const unsigned char* text);

operator<<(short num);
This method appends a short.
62
operator<<(unsigned short num);
This method appends an unsigned short.

operator<<(long num);
This method appends a long.

operator<<(unsigned long num);
This method appends an unsigned long.

operator<<(int num);
This method appends an integer.

operator<<(float num);
This method appends a float.

operator<<(double num);
This method appends a double.

operator<<(long double num);
This method appends a long double.

Note: The operator methods (1 through 15) append data of various types to the
IccBuf object. The types are converted to a readable format; for example,
from a long to a string representation.
IccBuf::overlay
IccBuf& overlay(unsigned long length,
void* dataArea);
length
The length of the existing data area.
dataArea
The address of the existing data area.
This method makes the data area external and fixed. Any existing internal data area
is destroyed.
IccBuf::replace
IccBuf& replace(unsigned long length,
63
length
The length of the source data area, in bytes.
dataArea
The address of the start of the source data area.
offset
The position where the new data is to be written, relative to the start of the
IccBuf data area. The default is no offset.
This method replaces the current contents of the data area at the given offset with
the data that is provided, and returns a reference to the IccBuf object.
IccBuf::setDataLength
unsigned long setDataLength(unsigned long length);
length
The new length of the data area, in bytes.
This method changes the current length of the data area and returns the new
length. If the IccBuf object is not extensible, the data area length is set to either the
original length of the data area or length, whichever is less.
IccBuf::setFMHContained
void setFMHContained(Icc::Bool yesNo=Icc::yes);
yesNo
A boolean, which defined in Icc structure, that indicates whether the data area
contains FMHs. The default value is yes.
This method allows an application program to indicate that a data area contains
FMHs.
IccBuf::DataAreaOwner
typedef enum {
internal,
external,
} DataAreaOwner;
internal
The data area has been allocated by the IccBuf constructor.
external
The data area has been allocated externally.
This enumeration indicates whether the data area of an IccBuf object has been
allocated outside the object.
IccBuf::DataAreaType
typedef enum {
extensible,
fixed,
} DataAreaType;
extensible
The data area can be automatically extended to accommodate more data.
fixed
The data area cannot grow in size. If you attempt to assign too much data, the
data is truncated, and an exception is thrown.
64
This enumeration indicates whether the data area of an IccBuf object can be made
longer than its original length.
Related Information
IccBase class
IccClock
Purpose
Controls access to the CICS time and date services.
Synopsis
#include <iccclkeh.hpp>
class
{
IccClock(UpdateMode update = manual);
IccAbsTime& ansTime();
void cancelAlarm(const IccRequestId* reqId= 0);
const char* date (DateFormat format= defaultFormat;
char dateSeparator=\0);
DayOfWeek dayOfWeek();
MonthOfYear monthOfYear();
const IccAlarmRequestId& setAlarm (const IccTime& time,
const IccRequestId* reqId= 0);
const char* time(char timeSeparator= \0);
void update();
typedef enum{
defaultFormat,
DDMMYY,
MMDDYY,
YYDDD,
YYDDMM,
YYMMDD,
DDMMYYYY,
MMDDYYYY,
YYYYDDD,
YYYYDDMM,
YYYYMMDD,
} DateFormat;
typedef enum {
Sunday,
Monday,
Tuesday,
Wednesday,
Thursday,
Friday,
Saturday,
} DayOfWeek;
typedef enum {
January,
February,
March,
April,
May,
June,
July,
August,
September,
65
October,
November,
December,
} MonthOfYear;
typedef enum {
manual,
automatic,
} UpdateMode;
};
Description
The IccClock class controls access to the CICS time and date services.
Class Members
IccClock constructor
IccClock(UpdateMode update = manual);
update
An enumeration, which is defined in this class, that indicates whether the clock
is to update its time automatically whenever a time or date service is used, or
whether it is to wait until an explicit update method call is made. If the time is
updated manually, the initial clock time is the time when the IccClock object is
created.
IccClock::absTime
IccAbsTime& ansTime();
This method returns a reference to an IccAbsTime object that contains the

absolute time as provided by CICS.
IccClock::cancelAlarm
void cancelAlarm(const IccRequestId* reqId= 0);
reqId
An optional pointer to the IccRequestId object that holds information about an
alarm request.
This method cancels a previous setAlarm request if the alarm time has not yet
been reached; that is, the request has not expired.
Equivalent EXEC CICS call: CANCEL
Conditions: ERROR
IccClock::date
const char* date (DateFormat format= defaultFormat;
char dateSeparator=\0);
format
An enumeration, which is defined in this class, that indicates in which format
you want the date to be returned.
dateSeparator
The character that is used to separate different fields in the date. The default is
no separation character.
This method returns the date as a string.
66
Equivalent EXEC CICS call: FORMATTIME YYDDD/YYMMDD/and so on.

Conditions: ERROR
IccClock::dayOfMonth
This method returns the day component of the date, in the range 1 through 31.
Equivalent EXEC CICS call: FORMATTIME DAYOFMONTH
Conditions: ERROR
IccClock::dayOfWeek
DayOfWeek dayOfWeek();
This method returns an enumeration, which is defined in this class, that indicates
the day of the week.
Equivalent EXEC CICS call: FORMATTIME DAYOFWEEK
Conditions: ERROR
IccClock::daysSince1900
This method returns the number of days that have elapsed since 1 January 1900.
Equivalent EXEC CICS call: FORMATTIME DAYCOUNT
Conditions: ERROR
IccClock::milliSeconds
This method returns the number of milliseconds, which is rounded to the nearest
hundredth of a second, that have elapsed since 00:00 on 1 January 1900.
IccClock::MonthOfYear
MonthOfYear monthOfYear();
the month of the year.
Equivalent EXEC CICS call: FORMATTIME MONTHOFYEAR
Conditions: ERROR
IccClock::setAlarm
const IccAlarmRequestId& setAlarm (const IccTime& time,
const IccRequestId* reqId= 0);
time
A reference to an IccTime object that contains time information. Because
IccTime is an abstract class, time is, in practise, an object of class
IccAbsTime, IccTimeOfDay, or IccTimeInterval.
67
reqId
An optional pointer to an IccRequestId object that is used to identify this
particular alarm request.
This method sets an alarm at the time specified in time. It returns a reference to an
IccAlarmRequestId object that can be used to cancel the alarm; see the
cancelAlarm method. See also the waitOnAlarm method of class IccTask.
Equivalent EXEC CICS call: POST
Conditions: EXPIRED, INVREQ
IccClock::time
const char* time(char timeSeparator= \0);
timeSeparator
The character that delimits the time fields. The default is no separation
character.
This method returns the time as a text string.
Equivalent EXEC CICS call: FORMATTIME TIME
Conditions: ERROR
IccClock::update
void update();
This method updates the clock time and date from CICS. See also the IccClock
constructor.
Equivalent EXEC CICS call: ASKTIME
IccClock::year
This method returns the four-figure year number, such as 1996.

Equivalent EXEC CICS call: FORMATTIME YEAR
Conditions: ERROR
IccClock::DateFormat
typedef enum{
defaultFormat,
DDMMYY,
MMDDYY,
YYDDD,
YYDDMM,
YYMMDD,
DDMMYYYY,
MMDDYYYY,
YYYYDDD,
YYYYDDMM,
YYYYMMDD,
} DateFormat;
IccClock::DayOfWeek
68
typedef enum {
Sunday,
Monday,
Tuesday,
Wednesday,
Thursday,
Friday,
Saturday,
} DayOfWeek;
This enumeration indicates the day of the week.

IccClock::MonthOfYear
typedef enum {
January,
February,
March,
April,
May,
June,
July,
August,
September,
October,
November,
December,
} MonthOfYear;
This enumeration indicates the month of the year.

IccClock::UpdateMode
typedef enum {
manual,
automatic,
} UpdateMode;
manual
The clock initially holds the time at which it was created. It is subsequently
updated only when an update method call is made.
automatic
The clock is updated to the current CICS time and date whenever any time or
date method is called (for example, daysSince1900).
This enumeration indicates whether the clock is automatically updated.
Related Information
IccAbsTime class
IccRequestId class
IccResource class
IccTask class
IccTime class
IccTimeInterval class
IccTimeOfDay class
69
IccCondition structure
Purpose
Contains all the CICS condition codes.
Synopsis
#include <icccndeh.hpp>
structure IccCondition
{
};
Description
Related Information
IccControl
Purpose
Controls application programs.
Synopsis
#include <iccctleh.hpp>
class
{
protected:
IccControl();
public:
void cancelAbendHandler();
IccBuf& commArea();
static IccControl* instance();
static Icc::Bool isCreated();
void resetAbendHandler();
virtual void run()=0;
IccSession* session();
void setAbendHandler(const IccProgramId& programId);
void setAbendHandler(const char* programName);
IccStartRequestQ* startRequestQ();
IccSystem* system();
IccTask* task();
IccTerminal* terminal();
};
Description
The IccControl class controls an application program that uses the supplied
Foundation Classes. This class is a singleton class in the application program; each
program that is running under a CICS task has a single IccControl object.
IccControl has a pure virtual run method, in which application code is written, and
is, therefore, an abstract base class. The application programmer must subclass
IccControl, and implement the run method.
Class Members
IccControl constructor
70
protected:
IccControl();
IccControl::cancelAbendHandler
void cancelAbendHandler();
This method cancels a previously established exit at this logical program level.
Equivalent EXEC CICS call: HANDLE ABEND CANCEL
IccControl::commArea
IccBuf& commArea();
This method returns a reference to an IccBuf object that encapsulates the

COMMAREA, which is the communications area of CICS memory that is used for
passing data between CICS programs and transactions.
Equivalent EXEC CICS call: ADDRESS COMMAREA
Conditions: INVREQ
IccControl::instance
static IccControl* instance();
This method returns a pointer to the single IccControl object. The object is created
if it does not already exist.
IccControl::isCreated
static Icc::Bool isCreated();
This method returns a boolean value that indicates whether the IccControl object
already exists. Possible values are true or false.
IccControl::resetAbendHandler
void resetAbendHandler();
This method reactivates a previously canceled abend handler for this logical
program level. See also cancelAbendHandler in this class.
Equivalent EXEC CICS call: HANDLE ABEND RESET
Conditions: NOTAUTH, PGMIDERR
IccControl::run
virtual void run()=0;
This method should be implemented in a subclass of IccControl by the application

programmer.
IccControl::session
IccSession* session();
This method returns a pointer to the IccSession object that represents the principal
facility for this program. An exception is thrown if this program does not have a
session as its principal facility.
71
IccControl::setAbendHandler (1)
void setAbendHandler(const IccProgramId& programId);
programId
A reference to the IccProgramId object that indicates which program is
affected.
This method sets the abend handler to the named program for this logical program
level.
Equivalent EXEC CICS call: HANDLE ABEND PROGRAM
IccControl::setAbendHandler (2)
void setAbendHandler(const char* programName);
programName
The name of the program that is affected.
This method sets the abend handler to the named program for this logical program
level.
Equivalent EXEC CICS call: HANDLE ABEND PROGRAM
IccControl::startRequestQ
IccStartRequestQ* startRequestQ();
This method returns a pointer to the IccStartRequestQ object. If this object has not
yet been created, this method creates the object before returning a pointer to it.
IccControl::system
IccSystem* system();
This method returns a pointer to the IccSystem object. If this object has not yet
been created, this method creates the object before returning a pointer to it.
IccControl::task
IccTask* task();
This method returns a pointer to the IccTask object. If this object has not yet been
created, this method creates the object before returning a pointer to it.
IccControl::terminal
IccTerminal* terminal();
This method returns a pointer to the IccTerminal object. If this object has not yet
been created, this method creates the object before returning a pointer to it.
Related Information
IccBuf class
IccProgramId class
IccResource class
72
IccSession class
IccStartRequestQ class
IccSystem class
IccTask class
IccTerminal class
IccConvId
Purpose
Identifies an APPC conversation.
Synopsis
class
{
IccConvId(const char* convName);
IccConvId(const IccConvId& convId);
IccConvId& operator=(const char* convName);
IccConvId& operator=(const IccConvId id);
};
Description
IccConvId class identifies an APPC conversation.
Class Members
IccConvId constructor (1)
IccConvId(const char* convName);
convName
The four-character name of the conversation.
IccConvId constructor (2)
IccConvId(const IccConvId& convId);
convId
A reference to an IccConvId object.
This constructor is the copy constructor.
IccConvId::operator= (1)
IccConvId& operator=(const char* convName);
IccConvId::operator= (2)
IccConvId& operator=(const IccConvId id);
Related Information
IccResourceId class
73
IccDataQueue
Purpose
Represents a CICS transient data queue.
Synopsis
#include <iccdateh.hpp>
class
{
IccDataQueue(const IccDataQueueId& id);
IccDataQueue(const char* queueName);
void empty();
const IccBuf& readItem();
void writeItem(const IccBuf& item);
void writeItem(const char* text);
};
Description
IccDataQueue class represents a CICS transient data queue.
Class Members
IccDataQueue constructor (1)
IccDataQueue(const IccDataQueueId& id);
id
A reference to an IccDataQueueId object that contains the name of the CICS

transient data queue.
IccDataQueue constructor (2)

IccDataQueue(const char* queueName);
queueName
The four-byte name of the queue that is to be created. An exception is thrown if
queueName is not valid.
IccDataQueue::clear
This method is synonymous with the empty method. See also Polymorphic
behavior on page 10.
Equivalent EXEC CICS call: DELETEQ TD
IccDataQueue::empty
void empty();
This method empties the queue. That is, it deletes all items that are in the queue.
Conditions: ISCINVREQ, NOTAUTH, QIDERR, SYSIDERR, IOERR (Open Systems
only)
IccDataQueue::get
74
This method is synonymous with the readItem method. See also Polymorphic
IccDataQueue::put
buffer
A reference to an IccBuf object that contains the data that is to be put into the
queue.
This method is synonymous with the writeItem method. See also Polymorphic
IccDataQueue::readItem
const IccBuf& readItem();
This method returns a reference to an IccBuf object that contains one item that has
been read from the data queue.
Equivalent EXEC CICS call: READQ TD
Conditions: IOERR, ISCINVREQ, LENGERR, NOTAUTH, NOTOPEN, QBUSY,
QIDERR, QZERO, SYSIDERR
IccDataQueue::writeItem (1)
void writeItem(const IccBuf& item);
item
A reference to an IccDataQueueId object that contains data that is to be written
to the queue.
This method writes an item of data to the queue.
Equivalent EXEC CICS call: WRITEQ TD
IccDataQueue::writeItem (2)
void writeItem(const char* text);
text
Text that has to be written to the queue.
This method writes an item of data to the queue.
Equivalent EXEC CICS call: WRITEQ TD
Conditions: IOERR, ISCINVREQ, LENGERR, NOSPACE, NOTAUTH, NOTOPEN,
QIDERR, SYSIDERR
Related Information
IccBuf class
IccDataQueueId class
IccResourceId class
75
IccDataQueueId
Purpose
Identifies queue names.
Synopsis
class
{
IccDataQueueId(const char* queueName);
IccDataQueueId(const IccDataQueueId& id);
IccDataQueueId& operator=(const char* queueName);
IccDataQueueId& operator=(const IccDataQueueId& id);
};
Description
IccDataQueueId class identifies a CICS transient data queue name.
Class Members
IccDataQueueId constructor (1)
IccDataQueueId(const char* queueName);
queueName
The four-character name of the queue.
IccDataQueueId constructor (2)
IccDataQueueId(const IccDataQueueId& id);
id
A reference to an IccDataQueueId object.
IccDataQueueId::operator= (1)
IccDataQueueId& operator=(const char* queueName);
queueName
The four-character name of the queue.
IccDataQueueId::operator= (2)
IccDataQueueId& operator=(const IccDataQueueId& id);
id
A reference to an IccDataQueueId object.
This operator assigns a new value.
Related Information
IccDataQueue class
IccResourceId class
IccEvent
Purpose
Contains information about a particular CICS call.
76
Synopsis
#include <iccevteh.hpp>
class
{
IccEvent(const IccResource* object,
const char* methodName);
const char* className() const;
IccBase::ClassType classType() const;
IccCondition::Codes condition(IccResource::ConditionType
type=IccResource::majorCode) const;
const char* conditionText() const;
const char* methodName() const;
const char* summary();
};
Description
IccEvent class contains information about a particular CICS call, which is called a
CICS event.
Class Members
IccEvent constructor
IccEvent(const IccResource* object,
const char* methodName);
object
A pointer to the IccResource object that is responsible for this event.
methodName
The name of the method that caused the event to be created.
IccEvent::className
This method returns the name of the class that is responsible for this event.
IccEvent::classType
This method returns an enumeration, which is described under classType in

IccBase class, that indicates the type of class that is responsible for this event.
IccEvent::condition
IccCondition::Codes condition(IccResource::ConditionType
type=IccResource::majorCode) const;
type
An enumeration that indicates whether a major or minor code is being
requested. Possible values are majorCode or minorCode. The default value is
majorCode.
This method returns an enumerated type that indicates the condition that is returned
from this CICS event. The possible values are described under the Codes type in
the IccCondition structure.
Equivalent EXEC CICS call: RESP & RESP2
IccEvent::conditionText
77
This method returns the text of the CICS condition code, such as NORMAL or
LENGERR.
IccEvent::methodName
This method returns the name of the method that is responsible for this event.
IccEvent::summary
This method returns a summary of the CICS event in the form:

IccEvent: IccDataQueue::readItem condition=23 (QZERO) minor=0
Related Information
IccBase class
IccCondition class
IccResource class
IccException
Purpose
Contains information about CICS Foundation Class exceptions.
Synopsis
#include <iccexceh.hpp>
class
{
IccException(Type exceptionType,
IccBase::ClassType classType,
const char* className,
const char* methodName,
IccMessage* message,
IccBase* object=0,
unsigned short exceptionNum=0);
IccMessage* message() const;
unsigned short number() const;
Type type() const;
const char* typeText() const;
typedef enum {
objectCreationError,
invalidArgument,
invalidMethodCall,
CICSCondition,
platformError,
familyConformanceError,
internalError,
} type;
};
78
Description
IccException class contains information about CICS Foundation Class exceptions.
It is used to create objects that are thrown to application programs. They are
generally used for error conditions, such as invalid method calls, but the application
programmer can also request an exception to be thrown when CICS raises a
particular condition.
Class Members
IccException constructor
IccException(Type exceptionType,
IccBase::ClassType classType,
const char* className,
const char* methodName,
IccMessage* message,
IccBase* object=0,
unsigned short exceptionNum=0);
exceptionType
An enumeration, which is defined in this class, that indicates the type of
exception.
classType
An enumeration, which is defined in this class, that indicates from which type of
class the exception was thrown.
className
The name of the class from which the exception was thrown.
methodName
The name of the method that caused the event to be created.
message
A pointer to the IccMessage object that contains the information about why the
exception was created.
object
A pointer to the object that threw the exception.
exceptionNum
The unique exception number.
Note: When the IccException object is created, it takes ownership of the
IccMessage that is given on the constructor. When the IccException is
deleted, the IccMessage object is deleted automatically by the IccException
destructor. Therefore, do not delete the IccMessage object before deleting
the IccException object.
IccException::className
This method returns the name of the class that is responsible for throwing this
exception.
IccException::classType
This method returns an enumeration, which is described under ClassType in

IccBase class, that indicates the type of class that threw this exception.
79
IccException::message
IccMessage* message() const;
This method returns a pointer to an IccMessage object that contains information on

any message that is associated with this exception.
IccException::methodName
This method returns the name of the method that is responsible for throwing this
exception.
IccException::number
This method returns the unique number exception. This is a useful diagnostic tool
for IBM service. The number uniquely identifies from where in the source code the
exception was thrown.
IccEvent::summary
This method returns a string that contains a summary of the exception. This method
combines the className, methodName, number, Type, and
IccMessage::summary methods into the following form:
IccException: 094 IccTempStore::readNextItem type=CICSCondition
(IccMessage: 008 IccTempStore::readNextItem <CICS returned the QIDERR
condition.>)
IccException::number
This method returns the unique number exception. This is a useful diagnostic tool
for IBM service. The number uniquely identifies from where in the source code the
exception was thrown.
IccException::type
Type type() const;
the type of exception.
IccException::typeText
const char* typeText() const;
This method returns a string representation of the exception type. For example:
objectCreationError
or
invalidArgument
IccException::Type
typedef enum {
objectCreationError,
invalidArgument,
80
invalidMethodCall,
CICSCondition,
platformError,
familyConformanceError,
internalError,
} type;
objectCreationError
An attempt to create an object was invalid. This happens, for example, if an
attempt is made to create a second instance of a singleton class, such as
IccTask.
invalidArgument
A method was called with an invalid argument. This happens, for example, if an
IccBuf object that has too much data is passed to the writeItem method of the
IccTempStore class by the application program. An attempt to create an
IccFileId object with a nine-character file name also generates an exception of
this type.
invalidMethodCall
A method call cannot proceed. A typical reason is that the object cannot honor
the call in its current state. For example, a readRecord call on an IccFile
object is honored only if an IccRecordIndex object, to specify which object is to
be read, has already been associated with the file.
CICSCondition
A CICS condition, which is listed in the IccCondition structure, has occurred in
the object, and the object was configured to throw an exception.
platformError
An operation is invalid because of limitations of this particular platform. For
example, an attempt to create an IccJournal object would fail under CICS for
OS/2 because no CICS journal services are on this server. A platform exception
can occur at three levels:
1. An object is not supported on this platform.
2. An object is supported on this platform, but a particular method is not.
3. A method is supported on this platform, but a particular positional parameter
is not.
See Platform differences on page 44 for more details.
familyConferenceError
Family subset enforcement is on for this program, and an operation that is not
valid on all platforms has been attempted.
internalError
The CICS Foundation Classes have detected an internal error. Call your
support organization.
Related Information
IccBase class
IccCondition class
IccMessage class
IccResource class
81
IccFile
Purpose
Enables the application program to access CICS files.
Synopsis
#include <iccfileh.hpp>
class
{
IccFile(const IccFileId& id,
IccRecordIndex* index);
IccFile (const char* fileName,
IccRecordIndex* index=0);
unsigned long access(Icc::GetOpt opt=Icc::Object);
IccValue::CVDA accessMethod(Icc::GetOpt opt=Icc::Object);
void deleteLockedRecord();
unsigned short deleteRecord();
IccValue::CVDA enableStatus(Icc::GetOpt opt=Icc::object);
Icc::Bool isAddable(Icc::GetOpt opt=Icc:object);
Icc::Bool isBrowsable(Icc::GetOpt opt=Icc:object);
Icc::Bool isDeletable(Icc::GetOpt opt= Icc::object);
Icc::Bool isEmptyOnOpen(Icc::GetOpt opt=Icc::object);
Icc::Bool isReadable(Icc::GetOpt opt=Icc::object);
Icc::Bool isRecoverable(Icc::GetOpt opt=Icc::object);
Icc::Bool isUpdatable(Icc::GetOpt opt=Icc::object);
unsigned long keyLength(Icc::GetOpt opt=Icc::object);
long keyPosition(Icc::GetOpt opt=Icc::object);
IccValue::CDVA openStatus(Icc::GetOpt opt=Icc::object);
const IccBuf& readRecord (ReadMode mode=normal);
IccValue::CVDA recordFormat(Icc::GetOpt opt=Icc::object);
IccRecordIndex* recordIndex() const;
unsigned long recordLength(Icc::GetOpt opt=Icc::object);
void registerRecordIndex(IccRecordIndex* index);
void rewriteRecord(const IccBuf& buffer);
void setAccess(unsigned long access);
void setActionOnLockedRecord(LockAction action);
void setEmptyOnOpen(Icc::Bool trueFalse);
void setStatus(Status status);
IccValue::CVDA type(Icc::GetOpt opt=Icc::object);
void unlockRecord(unsigned long updateToken=0);
void writeRecord(const IccBuf& buffer);
type enum {
readable,
notReadable,
browsable,
notBrowsable,
addable,
notAddable,
updatable,
notUpdatable,
deletable,
notDeletable,
fullAccess,
noAccess,
} Access;
type enum {
suspend,
noSuspend,
} LockAction;
type enum {
normal,
update,
} ReadMode;
type enum {
82
equalToKey,
gteqToKey,
} SearchCriterion;
type enum {
open,
closed,
enabled,
disabled,
} Status;
};
Description
IccFile class enables the application program to access CICS files.
Class Members
IccFile constructor (1)
IccFile(const IccFileId& id,
IccRecordIndex* index);
id
A reference to the IccFileId object that identifies on which file an operation is

being performed.
index
An optional pointer to the IccRecordIndex object that identifies on which record
in the file an operation is being performed.
IccFile constructor (2)
IccFile (const char* fileName,
IccRecordIndex* index=0);
fileName
The eight-character name of a file.
index
An optional pointer to the IccRecordIndex object that identifies on which record
in the file an operation is being performed.
If you want to access files by using an IccFile object, that object must have an
IccRecordIndex object associated with it. If this association is not made when the
object is created, use the registerRecordIndex method.
IccFile::access
unsigned long access(Icc::GetOpt opt=Icc::Object);
opt
An enumeration, which is defined in Icc structure, that indicates whether you
can use a value that was previously retrieved from CICS (object), or whether
the object should retrieve a fresh value from CICS.
This method returns a composite number that indicates the access properties of the
file. See also isReadable, isBrowsable, isAddable, isDeletable, and isUpdatable
methods.
Equivalent EXEC CICS call: INQUIRE FILE
ADD|BROWSE|DELETE|READ|UPDATE
IccFile::accessMethod
IccValue::CVDA accessMethod(Icc::GetOpt opt=Icc::Object);
83
opt
This method returns an enumeration, which is defined in IccValue, that represents
the access method for this file. Possible values are:
v VSAM
v BDAM
v SFS
Equivalent EXEC CICS call: INQUIRE FILE ACCESSMETHOD
Conditions: END, FILENOTFOUND, ILLOGIC, NOTAUTH (Open Systems only)
IccFile::deleteLockedRecord
void deleteLockedRecord();
This method deletes a record that has been previously locked by readRecord
method in update mode. See also readRecord method.
Equivalent EXEC CICS call: DELETE FILE
Conditions: DISABLED, DUPKEY, FILENOTFOUND, ILLOGIC, INVREQ, IOERR,
ISCINVREQ, NOTAUTH, NOTFIND, NOTOPEN, SYSIDERR
IccFile::deleteRecord
unsigned short deleteRecord();
This method deletes one or more records, as specified by the associated

IccRecordIndex object, and returns the number of deleted records.
Equivalent EXEC CICS call: DELETE FILE RIDFILE
ISCINVREQ, NOTAUTH, NOTFIND, NOTOPEN, SYSIDERR
IccFile::enableStatus
IccValue::CVDA enableStatus(Icc::GetOpt opt=Icc::object);
void endInsert();
opt
This method returns an enumeration, which is defined in IccValue, that indicates
whether the file is enabled to be used by programs. Possible values are:
v DISABLED
v DISABLING
v ENABLED
v UNENABLED
Equivalent EXEC CICS call: INQUIRE FILE ENABLESTATUS
84

IccFile::isAddable
Icc::Bool isAddable(Icc::GetOpt opt=Icc:object);
opt
An enumeration, which defined in Icc structure, that indicates whether you can
use a value that was previously retrieved from CICS (object), or whether the
object should retrieve a fresh value from CICS.
This method indicates whether more records can be added to the file.
Equivalent EXEC CICS call: INQUIRE FILE ADD
IccFile::isBrowsable
Icc::Bool isBrowsable(Icc::GetOpt opt=Icc:object);
opt
This method indicates whether the file can be browsed.
Equivalent EXEC CICS call: INQUIRE FILE BROWSE
IccFile::isDeletable
Icc::Bool isDeletable(Icc::GetOpt opt= Icc::object);
opt
This method indicates whether the records in the file can be deleted.
Equivalent EXEC CICS call: INQUIRE FILE DELETE
IccFile::isEmptyOnOpen
Icc::Bool isEmptyOnOpen(Icc::GetOpt opt= Icc::object);
opt
This method permits a Boolean that indicates whether the EMPTYREQ option is
specified. EMPTYREQ causes the object that is associated with this file, to be set
to empty when opened, if it is a VSAM data set that is defined as reusable.
Equivalent EXEC CICS call: INQUIRE FILE EMPTYSTATUS
85

IccFile::isReadable
Icc::Bool isReadable(Icc::GetOpt opt= Icc::object);
opt
This method indicates whether the files can be read.
Equivalent EXEC CICS call: INQUIRE FILE READ
IccFile::isRecoverable
Icc::Bool isRecoverable(Icc::GetOpt opt= Icc::object);
opt
Equivalent EXEC CICS call: INQUIRE FILE RECOVSTATUS
IccFile::isUpdatable
Icc::Bool isUpdatable(Icc::GetOpt opt= Icc::object);
opt
This method indicates whether the file can be updated.
Equivalent EXEC CICS call: INQUIRE FILE UPDATE
IccFile::keyLength
unsigned long keyLength(Icc::GetOpt opt=Icc::object);
opt
This method returns the length of the search key.
IccFile::keyPosition
long keyPosition(Icc::GetOpt opt=Icc::object);
86
opt
This method returns the position of the key field in each record relative to the
beginning of the record. If no key exists, zero (0) is returned.
Equivalent EXEC CICS call: INQUIRE FILE KEYPOSITION
IccFile::openStatus
opt
This method returns a CVDA that indicates the open status of the file. Possible
values are:
v CLOSED: The file is closed.
v CLOSING: The file is in the process of being closed. Closing a file might require
dynamic deallocation of data sets and deletion of shared resources, so the
process might last a very long time.
v CLOSEREQUEST: The file is open and one or more application tasks are using
it. A request has been received to close it.
v OPEN: The file is open.
v OPENING: The file is in the process of being opened.
Equivalent EXEC CICS call: INQUIRE FILE OPENSTATUS
IccFile::readRecord
const IccBuf& readRecord (ReadMode mode=normal);
mode
An enumeration, which is defined in this class, that indicates in which mode the
record is to be read.
This method reads and returns a reference to an IccBuf object that contains the
data from the record.
Equivalent EXEC CICS call: READ FILE
ISCINVREQ, LENGERR, NOTAUTH, NOTFND, NOTOPEN, SYSIDERR
IccFile::recordFormat
opt
87
This method returns a CVDA that indicates the format of the data. Possible values
are:
v FIXED: The records are of fixed length.
v UNDEFINED: (BDAM data sets only) The format of the records on the file is
undefined.
v VARIABLE: The records are of variable length. If the file is associated with a data
table, the record format is always variable in length, even if the source data set
contains fixed-length records.
Equivalent EXEC CICS call: INQUIRE FILE RECORDFORMAT
IccFile::recordIndex
This method returns a pointer to an IccRecordIndex object that indicates which

records are to be accessed when methods such as readRecord, writeRecord, and
deleteRecord are used.
IccFile::recordLength
unsigned long recordLength(Icc::GetOpt opt=Icc::object);
opt
This method returns the length of the current record.
Equivalent EXEC CICS call: INQUIRE FILE RECORDSIZE
IccFile::registerRecordIndex
void registerRecordIndex(IccRecordIndex* index);
index
A pointer to an IccKey, IccRBA, or IccRRN object that will be used by methods
such as readRecord, writeRecord, and so on.
IccFile::recordIndex
This method returns a pointer to an IccRecordIndex object that indicates which

records are to be accessed when methods such as readRecord, writeRecord, and
deleteRecord are used.
IccFile::rewriteRecord
void rewriteRecord(const IccBuf& buffer);
88
buffer
A reference to the IccBuf object that holds the new record data that is to be
written to the file.
This method updates a record with the contents of buffer.
Equivalent EXEC CICS call: REWRITE FILE
Conditions: DISABLED, FILENOTFOUND, ILLOGIC, INVREQ, IOERR,
ISCINVREQ, NOTAUTH, NOTFND, NOTOPEN, SYSIDERR
IccFile::setAccess
void setAccess(unsigned long access);
access
A positive integer value that is created by logical OR-ing (or adding) one or
more of the values of the Access enumeration, which are defined in this class.
This method sets the permitted access to the file. For example:
file.setAccess(IccFile::readable + IccFile::notUpdatable);
Equivalent EXEC CICS call: SET FILE ADD|BROWSE|DELETE| and so on

Conditions: FILENOTFOUND, INVREQ, NOTAUTH (Open Systems only)
IccFile::setActionOnLockedRecord
void setActionOnLockedRecord(LockAction action);
action
An enumeration, which is defined in this class, that indicates what action to
take.
This method sets what action is to be taken when an attempt is made to change a
locked record.
IccFile::setStatus
void setStatus(Status status);
status
An enumeration, which is defined in this class, that indicates the required status
of the file after this method is called.
This method sets the status of the file.
Equivalent EXEC CICS call: SET FILE OPENSTATUS ENABLESTATUS
Conditions: FILENOTFOUND, INVREQ, NOTAUTH( Open Systems only)
IccFile::type
IccValue::CVDA type(Icc::GetOpt opt=Icc::object);
opt
89
This method returns a CVDA that identifies the type of data set that corresponds to
this file. Possible values are:
v ESDS: The data set is an entry-sequenced data set.
v KEYED: The data set is addressed by physical keys.
v
v
v
v
KSDS: The data set is a key-sequenced data set.

NOTKEYED: The data set is not addressed by physical keys.
RRDS: The data set is a relative record data set.
VRRDS: The data set is a variable relative record data set.
Equivalent EXEC CICS call: INQUIRE FILE TYPE

Conditions: END, FILENOTFOUND, ILLOGIC, NOTAUTH( Open Systems only)
IccFile::unlockRecord
void unlockRecord(unsigned long updateToken=0);
This method is used to unlock a record that was previously locked by reading in
update mode. See also readRecord.
Equivalent EXEC CICS call: UNLOCK FILE
Conditions: DISABLED, FILENOTFOUND, ILLOGIC, IOERR, ISCINVREQ,
NOTAUTH, NOTOPEN, SYSIDERR
IccFile::writeRecord
void writeRecord(const IccBuf& buffer);
buffer
A reference to the IccBuf object that holds the data that is to be written into the
record.
This method is used to write either a single record or a sequence of records, if used
with the beginInsert and endInsert methods.
Equivalent EXEC CICS call: WRITE FILE
Conditions: DISABLED, DUPREC, FILENOTFOUND, ILLOGIC, IOERR,
ISCINVREQ, LENGERR, NOSPACE, NOTAUTH, NOTOPEN, SYSIDERR
IccFile::Access
type enum {
readable,
notReadable,
browsable,
notBrowsable,
addable,
notAddable,
updatable,
notUpdatable,
deletable,
notDeletable,
fullAccess,
noAccess,
} Access;
readable
File records can be read by CICS tasks.
90
notReadable
File records cannot be read by CICS tasks.
browsable
File records can be browsed by CICS tasks.
notBrowsable
File records cannot be browsed by CICS tasks.
addable
Records can be added to the file by CICS tasks.
notAddable
Records cannot be added to the file by CICS tasks.
updatable
Records in the file can be updated by CICS tasks.
notUpdatable
Records in the file cannot be updated by CICS tasks.
deletable
Records in the file can be deleted by CICS tasks.
notDeletable
Records in the file cannot be deleted by CICS tasks.
fullAccess
Equivalent to readable AND browsable AND addable AND updatable AND
deletable.
noAccess
Equivalent to notReadable AND notBrowsable AND notAddable AND
notUpdatable AND notDeletable.
IccFile::LockAction
type enum {
suspend,
noSuspend,
} LockAction;
suspend
Not supported by Technology Release.
noSuspend
Not supported by Technology Release.
This enumeration specifies what action is to be taken if a record is locked by VSAM
RLS.
IccFile::ReadMode
type enum {
normal,
update,
} ReadMode;
normal
No update is to be performed. That is, read-only mode is set.
update
The record is to be updated. The record is locked by CICS until:
v It is rewritten by use of the rewriteRecord method or
v It is deleted by use of the deleteLockedRecord method or
91
v It is unlocked by use of the unlockRecord method or

v The task is abended.
This enumeration is the mode in which a file is read.
IccFile::SearchCriterion
type enum {
equalToKey,
gteqToKey,
} SearchCriterion;
equalToKey
The search finds only an exact match.
gteqToKey
The search finds either an exact match or the next record in search sequence.
IccFile::Status
type enum {
open,
closed,
enabled,
disabled,
} Status;
open
The file is open, ready for read/write requests from CICS tasks.
closed
The file is closed, and is, therefore, not currently being used by CICS tasks.
enabled
The file is enabled for access by CICS tasks.
disabled
The file is disabled from access by CICS tasks.
Related Information
IccBase class
IccCondition class
IccMessage class
IccResource class
IccFileId
Purpose
Identifies a file name in the CICS system.
Synopsis
class
{
IccFileId(const char* fileName);
92
IccFileId(const IccFileId& id);

IccFileId& operator=(const char* fileName);
IccFileId& operator=(const IccFileId& id);
};
Description
IccFileId class identifies a file name in the CICS system. On AIX, this is an FD
stanza of the permanent resource database.
Class Members
IccFileId constructor (1)
IccFileId(const char* fileName);
fileName
The name of the file.
IccFileId constructor (2)
IccFileId(const IccFileId& id);
id
A reference to an IccFileId object.
IccFileId::operator= (1)
IccFileId& operator=(const char* fileName);
fileName
The eight-byte name of the file.
IccFileId& operator=(const IccFileId& id);
id
A reference to an IccFileId object.
This method assigns a new value.
Related Information
IccBase class
IccResource class
IccFileIterator
Purpose
Creates IccFileIterator objects to browse through CICS records.
Synopsis
#include <iccfileh.hpp>
class
{
IccFileIterator(IccFile* file,
IccRecordIndex* index,
IccFile::SearchCriterion search= IccFile::gteqToKey);
const IccBuf& readNextRecord(IccFile::ReadMode mode= IccFile::normal);
93
const IccBuf& readPreviousRecord(IccFile::ReadMode mode=IccFile::normal);

void reset(IccRecordIndex* index,
IccFile::SearchCriterion search=IccFile::gteqToKey);
};
Description
IccFileIterator class creates IccFileIterator objects that can be used to browse
through the records of a CICS file, represented by an IccFile object.
Class Members
IccFileIterator constructor
IccFileIterator(IccFile* file,
IccRecordIndex* index,
IccFile::SearchCriterion search= IccFile::gteqToKey);
file
A pointer to the IccFile object that is to be browsed.
index
A pointer to the IccRecordIndex object that is being used to select a record in
the file.
search
An enumeration, which is defined in IccFile, that indicates the criterion that is
being used to find a search match. The default is gteqToKey.
The IccFile and IccRecordIndex object must exist before the IccFileIterator is
created.
Equivalent EXEC CICS call: STARTBR FILE
Conditions: DISABLED, FILENOTFOUND, ILLOGIC, INVREQ, IOERR,
ISCINVREQ, NOTAUTH, NOTFND, NOTOPEN, SYSIDERR
IccFileIterator::readNextRecord
const IccBuf& readNextRecord(IccFile::ReadMode mode= IccFile::normal);
mode
An enumeration, which is defined in IccFile class, that indicates the type of
read request.
This method reads the record that follows the current record.
Equivalent EXEC CICS call: READNEXT FILE
Conditions: DUPKEY, ENDFILE, FILENOTFOUND, ILLOGIC, INVREQ, IOERR,
ISCINVREQ, LENGERR, NOTAUTH, NOTFIND, SYSIDERR
IccFileIterator::readPreviousRecord
const IccBuf& readPreviousRecord(IccFile::ReadMode mode=IccFile::normal);
mode
An enumeration, which is defined in IccFile class, that indicates the type of
read request.
This method reads the record that precedes the current record.
94
Equivalent EXEC CICS call: READPREV FILE

Conditions: DUPKEY, ENDFILE, FILENOTFOUND, ILLOGIC, INVREQ, IOERR,
ISCINVREQ, LENGERR, NOTAUTH, NOTFIND, SYSIDERR
IccFileIterator::reset
void reset(IccRecordIndex* index,
IccFile::SearchCriterion search=IccFile::gteqToKey);
index
A pointer to the IccRecordIndex object that is being used to select a record in
the file.
search
An enumeration, which is defined in IccFile, that indicates the criterion that is
being used to find a search match. The default is gteqToKey.
This method resets the IccFileIterator object to point to the record that is identified
by the IccRecordIndex object and the specified search criterion.
Equivalent EXEC CICS call: RESETBR FILE
Conditions: FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR,
NOTAUTH, NOTFIND, SYSIDERR
Related Information
IccBase class
IccBuf class
IccFile class
IccFileIterator class
IccRecordIndex class
IccResource class
IccGroupId
Purpose
Identifies a CICS group.
Synopsis
class
{
IccGroupId(const char* groupName);
IccGroupId(const IccGroupId& id);
IccGroupId& operator=(const char* groupName);
IccGroupId& operator=(const IccGroupId& id);
};
Description
IccFileId class identifies a CICS group.
95
Class Members
IccGroupId constructor (1)
IccGroupId(const char* groupName);
groupName
The eight-character name of the group.
IccGroupId constructor (2)
IccGroupId(const IccGroupId& id);
id
A reference to an IccGroupId object.

IccGroupId::operator= (1)
IccGroupId& operator=(const char* groupName);
groupName
The eight-character name of the group.
IccGroupId& operator=(const IccGroupId& id);
id
A reference to an IccGroupId object.
Related Information
IccBase class
IccResource class
IccJournalId
Purpose
Identifies a journal number in the CICS system.
Synopsis
class
{
IccJournalId(unsigned short journalNum);
IccJournalId(const IccJournalId& id);
IccJournalId& operator=(unsigned short journalNum);
IccJournalId& operator=(const IccJournalId& id);
};
Description
IccJournalId class identifies a journal number in the CICS system. On AIX, this is a
JD stanza of the permanent resource database.
96
Class Members
IccJournalId constructor (1)
IccJournalId(unsigned short journalNum);
journalNum
The number of the journal, in the range 1 through 99.
IccJournalId constructor (2)
IccJournalId(const IccJournalId& id);
id
A reference to an IccJournalId object.

IccJournalId::number
This method returns the journal number, in the range 1 through 99.
IccJournalId::operator= (1)
IccJournalId& operator=(unsigned short journalNum);
journalNum
The number of the journal, in the range 1 through 99.
IccJournalId::operator= (2)
IccJournalId& operator=(const IccJournalId& id);
id
A reference to an IccJournalId object.
Related Information
IccBase class
IccResource class
IccJournalTypeId
Purpose
Identifies the origin of a journal record.
Synopsis
class
{
IccJournalTypeId(const char* journalTypeName);
IccJournalTypeId(const IccJournalId& id);
void operator=(const IccJournalTypeId& id);
void operator=(const char* journalTypeName);
};
97
Description
IccJournalTypeId class identifies the origin of a journal record. It contains a
two-byte field that is included in the journal record.
Class Members
IccJournalTypeId constructor (1)
IccJournalTypeId(const char* journalTypeName);
journalTypeName
A two-byte identifier that is used in journal records.
IccJournalTypeId constructor (2)
IccJournalTypeId(const IccJournalId& id);
id
A reference to an IccJournalTypeId object.
IccJournalTypeId::operator= (1)
void operator=(const IccJournalTypeId& id);
id
A reference to an IccJournalTypeId object.
IccJournalTypeId::operator= (2)
void operator=(const char* journalTypeName);
journalTypeNum
A two-byte identifier that is used in the journal record.
This method sets the two-byte field that is included in the journal record.
Related Information
IccBase class
IccJournalId class
IccResource class
IccKey
Purpose
Holds a search key.
Synopsis
#include <iccreceh.hpp>
class
{
IccKey(const char* initValue,
Kind kind=complete);
IccKey(unsigned shortcompleteLength,
IccKey(const IccKey& key);
void assign(unsigned short length,
unsigned short completeLength () const;
Kind kind() const;
IccKey& operator=(const IccKey& key);
98
IccKey& operator=(const IccBuf& buffer);

IccKey& operator=(const char* value);
Icc::Bool operator==(const IccKey& key) const;
Icc::Bool operator==(const IccBuf& text) const;
Icc::Bool operator==(const char* text) const;
Icc::Bool operator!=(const IccKey& key) const;
Icc::Bool operator!=(const IccBuf& text) const;
Icc::Bool operator!=(const char* text) const;
void setKind(Kind kind);
const char* value();
type enum {
complete,
generic,
} Kind;
};
Description
IccKey class holds a search key for an indexed (KSDS) file.
Class Members
IccKey constructor (1)
IccKey(const char* initValue,

IccKey(unsigned shortcompleteLength,

IccKey(const IccKey& key);
IccKey::assign
void assign(unsigned short length,
length
The length of the data area.
dataArea
A pointer to the start of the data area that holds the search key.
IccKey::completeLength
unsigned short completeLength () const;
This method returns the length of the key when it is complete.

IccKey::kind
Kind kind() const;
whether the key is generic or complete.
IccKey::operator= (1)
IccKey& operator=(const IccKey& key);
IccKey& operator=(const IccBuf& buffer);
99
IccKey& operator=(const char* value);
This operator assigns a new value to any key.

IccKey::operator== (1)
Icc::Bool operator==(const IccKey& key) const;
Icc::Bool operator==(const IccBuf& text) const;
Icc::Bool operator==(const char* text) const;
This operator tests equality.

IccKey::operator!= (1)
Icc::Bool operator!=(const IccKey& key) const;
Icc::Bool operator!=(const IccBuf& text) const;
Icc::Bool operator!=(const char* text) const;
This operator tests inequality.

IccKey::setKind
void setKind(Kind kind);
kind
An enumeration, which is defined in this class, that indicates whether the key is
generic or complete.
This method changes the type of key from generic to complete, or from complete to
generic.
IccKey::value
const char* value();
This method returns the start of the data area that contains the search key.
IccKey::Kind
type enum {
complete;
generic;
} Kind;
complete
Specifies that the supplied key is not generic.
generic
Specifies that the search key is generic. A search is satisfied when a record is
found with a key whose prefix matches the supplied key.
100
Related Information
IccBase class
IccBuf class
IccLockId
Purpose
Identifies a lock request.
Synopsis
class
{
IccLockId(const char* name);
IccLockId(const IccLockId& id);
IccLockId& operator=(const char* name);
IccLockId& operator=(const IccLockId& id);
};
Description
IccLockId class is used to identify a lock request.
Class Members
IccLockId constructor (1)
IccLockId(const char* name);
name
The eight-character name of the lock request.
IccLockId constructor (2)
IccLockId(const IccLockId& id);
id
A reference to an IccLockId object.

IccLockId::operator= (1)
IccLockId& operator=(const char* name);
name
IccLockId::operator= (2)
IccLockId& operator=(const IccBuf& buffer);
id
101
Related Information
IccBase class
IccResourceId class
IccMessage
Purpose
Holds a message description.
Synopsis
#include <iccmsgeh.hpp>
class
{
IccMessage(const short number,
const char* text,
const char* className=0,
const char* methodName=0);
const char* text() const;
};
Description
IccMessage class holds a message description. It is used primarily by the
IccException class to describe why the IccException object was created.
Class Members
IccMessage constructor
IccMessage(const short number,
const char* text,
const char* className=0,
const char* methodName=0);
number
text
The text that is associated with the message.
className
The optional name of the class that is associated with the message.
methodName
The optional name of the method that is associated with the message.
IccMessage::className
This method returns the name of the class with which the message is associated, if
any.
IccMessage::methodName
102
This method returns the name of the method with which the message is associated,
if any.
IccMessage::number
This method returns the number of the message.

IccMessage::summary
This method returns a summary of the message in the following form:

IccMessage: 008 IccTempStore::readNextItem <CICS returned the QIDERR
condition.>
IccMessage::text
const char* text() const;
This method returns the text of the message.
Related Information
IccBase class
IccException class
IccProgram
Purpose
Represents any program that is outside the program that is executing.
Synopsis
#include <iccprgeh.hpp>
class
{
IccProgram(const IccProgramId& id);
IccProgram(const char*progName);
const void* address() const;
const void* entryPoint() const;
unsigned long length() const;
void link(const IccBuf* commArea=0,
const IccTransId* transId=0,
CommitOpt opt-noCommitOnReturn);
void load(LoadOpt opt=releaseAtTaskEnd);
void unload();
type enum {
noCommitOnReturn,
commitOnReturn,
} CommitOpt;
type enum {
releaseAtTaskEnd,
hold,
} LoadOpt;
};
103
Description
IccProgram class represents any CICS program that is outside the program that is
executing, which the IccControl object represents.
Class Members
IccProgram constructor (1)
IccProgram(const IccProgramId& id);
id
A reference to an IccProgramId object.
IccProgram constructor (2)

IccProgram(const char*progName);
progName
The eight-character name of the program.
IccProgram::address
const void* address() const;
This method returns the address of a program module in memory. This is valid only
after a successful load call.
IccProgram::entryPoint
const void* entryPoint() const;
This method returns the a pointer to the entry point of a loaded program module.
This is valid only after a successful load call.
IccProgram::link
void link(const IccBuf* commArea=0,
const IccTransId* transId=0,
CommitOpt opt-noCommitOnReturn);
commArea
An optional pointer to the IccBuf object that contains the COMMAREA, which is
the buffer that is used to pass information between the calling program and the
program that is being called.
transId
An optional pointer to the IccTransId object that indicates the name of the
mirror transaction under which the program is to run if it is a remote (DPL)
program link.
opt
An enumeration, which is defined in this class, that affects the behavior of the
link when the program is remote (DPL). The default (noCommitOnReturn) is not
to commit resource changes on the remote CICS region until the current task
commits its resources. The alternative (commitOnReturn) means that the
resources of the remote program are committed whether or not this task
subsequently abends or encounters a problem.
Conditions: INVREQ, NOTAUTH, PGMIDERR, SYSIDERR, LENGERR,
ROLLEDBACK, TERMERR
IccProgram::load
void load(LoadOpt opt=releaseAtTaskEnd);
104
opt
An enumeration, which is defined in this class, that indicates whether CICS
should automatically allow the program to be unloaded at task termination
(releaseAtTaskEnd) or not (hold).
IccProgram::unload
void unload();
This method allows a program to be unloaded. It can be reloaded by a call to load.

IccProgram::CommitOpt
type enum {
noCommitOnReturn,
commitOnReturn,
} CommitOpt;
noCommitOnReturn
Changes to resources on the remote CICS region are not committed until the
current task commits its resources. This is the default setting.
commitOnReturn
Changes to resources on the remote CICS region are committed whether or not
the current task subsequently abends or encounters a problem.
IccProgram::LoadOpt
type enum {
releaseAtTaskEnd,
hold,
} LoadOpt;
releaseAtTaskEnd
Indicates that CICS should automatically allow the program to be unloaded at
task termination.
hold
Indicates that CICS should not automatically allow the program to be unloaded
at task termination. In this case, this or another task must explicitly use the
unload method.
Related Information
IccBase class
IccBuf class
IccControl class
IccResource class
IccTransId class
105
IccProgramId
Purpose
Represents program names in the CICS system.
Synopsis
class
{
IccProgramId(const char*progName);
IccProgramId(const IccProgramIdId& id);
IccProgramId& operator=(const char* progName);
IccProgramId& operator=(const IccProgramId& id);
};
Description
IccProgramId class represents program names in the CICS system. On AIX, this is
a PD stanza of the permanent resource database.
Class Members
IccProgramId constructor (1)
IccProgramId(const char*progName);
progName
IccProgramId constructor (2)
IccProgramId(const IccProgramId& id);
id

IccProgramId::operator= (1)
IccProgramId& operator=(const char* progName);
progName
IccProgramId::operator= (2)
IccProgramId& operator=(const IccProgramId& id);
id
Related Information
IccBase class
IccResourceId class
106
IccRBA
Purpose
Holds a relative byte address.
Synopsis
class
{
IccRBA(unsigned long initRBA=0);
IccRBA& operator=(const IccRBA& rba);
IccRBA& operator=(unsigned long num);
Icc::Bool operator==(const IccRBA& rba) const;
Icc::Bool operator==(unsigned long num) const;
Icc!::Bool operator==(const IccRBA& rba) const;
Icc::Bool operator!=(unsigned long num) const;
unsigned long number () const;
};
Description
IccRBA objects hold relative byte addresses that are used for accessing VSAM
ESDS files.
Class Members
IccRBA constructor
IccRBA(unsigned long initRBA=0);
initRBA
An initial value for the relative byte address.
IccRBA::operator= (1)
IccRBA& operator=(const IccRBA& rba);
IccRBA::operator= (2)
IccRBA& operator=(unsigned long num);
num
A valid relative byte address.
This operator assigns a new value for the relative byte address.
IccRBA::operator== (1)
Icc::Bool operator==(const IccRBA& rba) const;
IccRBA::operator== (2)

IccRBA::operator!= (1)
Icc!::Bool operator==(const IccRBA& rba) const;
IccRBA::operator!= (2)
107

IccRBA::number
unsigned long number () const;
This method returns the relative byte address.
Related Information
IccBase class
IccRecordIndex
Purpose
Tells CICS which particular record the program wants to retrieve, delete, or update.
Synopsis
class
{
IccRecordIndex(typetype);
unsigned short length() const;
Type type() const;
type enum {
key,
RBA,
RRN,
} Type;
};
Description
IccRecordIndex is the CICS File Control Record Identifier. It tells CICS which
particular record the program wants to retrieve, delete, or update. IccRecordIndex
is a base class from which IccKey, IccRBA, and IccRRN are derived.
Class Members
IccRecordIndex constructor
IccRecordIndex(typetype);
type
An enumeration, which is defined in this class, that indicates whether the index
type is key, RBA, or RRN.
Note: This is protected because you must not create IccRecordIndex objects; see
subclasses IccKey, IccRBA, and IccRRN.
IccRecordIndex::length
unsigned short length() const;
This method returns the length of the record identifier.

IccRecordIndex::type
108
Type type() const;
This method returns the length of the record identifier.

IccRecordIndex::Type
type enum {
key,
RBA,
RRN,
} Type;
This enumeration indicates the access method.
Related Information
IccBase class
IccKey class
IccRBA class
IccRRN class
IccRequestId
Purpose
Holds the name of a request.
Synopsis
class
{
IccRequestId();
IccRequestId(const char* requestName);
IccRequestId(const IccRequestId& id);
IccRequestId& operator=(const IccRequest& id);
IccRequestId& operator=(const char* requestName);
};
Description
The IccRequestId holds the name of a request. This request identifier can
subsequently be used to cancel a request; see, for example, start and cancel
methods inIccStartRequestQ class.
Class Members
IccRequestId constructor (1)
IccRequestId();
This constructor is an empty IccRequestId object.

IccRequestId(const char* requestName);
109
requestName
The eight-character name of the request.
IccRequestId(const IccRequestId& id);
id
A reference to an IccRequestId.

IccRequestId::operator= (1)
IccRequestId& operator=(const IccRequest& id);
id
A reference to an IccRequestId object whose properties are copied into this

object.
IccRequestId::operator= (2)
IccRequestId& operator=(const char* requestName);
requestName
An eight-character string which is copied into this object.
Related Information
IccBase class
IccResourceId class
IccResource
Purpose
Derives other classes.
Synopsis
#include <iccreseh.hpp>
class
{
IccResource(IccBase::ClassType classType);
ActionOnCondition action OnCondition(IccCondition::Codes condition);
char actionOnConditionAsChar(IccCondition::Codes condition);
const char* actionsOnConditionsText();
unsigned long condition(ConditionType type=majorCode) const;
virtual HandleEventReturnOpt handleEvent(IccEvent& event);
const IccResourceId* id() const;
Icc::Bool isEDFOn() const;
Icc::Bool isRouteOptionOn() const;
const char* name() const;
const IccSysId& routeOption() const;
void setActionOnAnyCondition(ActionOnCondition action);
void setActionOnAnyCondition(ActionOnCondition action,
IccCondition::Codes condition);
void setActionsOnConditions(const char* actions=0);
void setEDF(Icc::Bool onOff);
110
void setRouteOption(const IccSysId& sysId);

void setRouteOption(const char* sysName=0);
type enum {
noAction,
callHandleEvent,
throwException,
abendTask,
} ActionOnCondition;
type enum {
rContinue,
rThrowException,
rAbendTask,
} HandleEventReturnOpt;
type enum {
majorCode,
minorCode,
} ConditionType;
};
Description
The IccResource class is a base class that derives other classes. The methods
that are associated with IccResource are described here, although, in practice,
they are called only on objects of derived classes.
IccResource is the parent class for all CICS resources, such as tasks, files,
programs, and so on. Every class inherits from IccBase, but only those that use
CICS services inherit from IccResource.
Class Members
IccResource constructor
IccResource(IccBase::ClassType classType);
classType
An enumeration that indicates what the subclass type is. For example, for an
IccTempStore object, the class type is cTempStore. The possible values are
listed under ClassType in the description of the IccBase class.
IccResource::actionOnCondition
ActionOnCondition action OnCondition(IccCondition::Codes condition);
condition
The name of the condition as an enumeration. See IccCondition structure for a
list of the possible values.
This method returns an enumeration that indicates what action the class will take in
response to the specified condition that CICS is raising. The possible values are
described in this class.
IccResource::actionOnConditionAsChar
const char* actionsOnConditionsText();
This method returns a string of characters, one character for each possible
condition. Each character indicates the actions that are to be preformed for that
corresponding condition. The characters that are used in the string are described
above in actionOnConditionAsChar. For example, the string: 0X00H0A shows the
actions for the first seven conditions, as follows:
v condition 0 (zero) (NORMAL) : action=0(noAction)
111
v
v
v
v
v
v
condition
condition
condition
condition
condition
condition
1
2
3
4
5
6
(ERROR): action=X (throwException)

(RDATT): action=0 (noAction)
(WRBRK): action=0 (noAction)
(EOF): action=H (callHandleEvent)
(EODS): action=0 (noAction)
(EOC) : action=A (abendTask)
IccResource::clear
This method clears the contents of the object. This method is virtual and is
implemented wherever appropriate in the derived classes. See Polymorphic
behavior on page 10 for a description of polymorphism. The default implementation
in this class throws an exception to indicate that it has not been overridden in a
subclass.
IccResource::condition
unsigned long condition(ConditionType type=majorCode) const;
type
condition that is requested. Possible values are majorCode and minorCode. The
default is majorCode.
This method returns a number that indicates the condition code for the most recent
CICS call that this object made.
IccResource::conditionText
This method returns the symbolic name of the last CICS condition for this object.
IccResource::get
This method gets data from the IccResource object and returns it as an IccBuf
reference. This method is virtual and is implemented wherever appropriate in the
derived classes. See Polymorphic behavior on page 10 for a description of
polymorphism. The default implementation in this class throws an exception to
indicate that it has not been overridden in a subclass.
IccResource::handleEvent
virtual HandleEventReturnOpt handleEvent(IccEvent& event);
event
A reference to an IccEvent object that describes the reason why this method is
being called.
This virtual function can be reimplemented in a subclass (by the application
programmer) to handle CICS events (see IccEvent class for more information).
IccResource::id
const IccResourceId* id() const;
112
This method returns a pointer to the IccResourceId object that is associated with
this IccResource object.
IccResource::isEDFOn
Icc::Bool isEDFOn() const;
This method returns a Boolean value that indicates whether the EDF trace is active.
Possible values are yes or no.
IccResource::isRouteOptionOn
Icc::Bool isRouteOptionOn() const;
This method returns a Boolean value that indicates whether the route option is
active. Possible values are yes or no.
IccResource::name
This method returns a character string that gives the name of the resource that is
being used. For an IccTempStore object, the eight-character name of the
temporary storage queue is returned. For an IccTerminal object, the four-character
terminal name is returned. This is equivalent to calling id()->name.
IccResource::put
buffer
A reference to an IccBuf object that contains data that is to be put into the
object.
This method puts further information into the IccResource object. This method is
virtual and is implemented wherever appropriate in the derived classes. See
Polymorphic behavior on page 10 for a description of polymorphism. The default
implementation in this class throws an exception to indicate that it has not been
overridden in a subclass.
IccResource::routeOption
const IccSysId& routeOption() const;
This method returns a reference to an IccSysId object that represents the system
to which all CICS requests are routed; that is, explicit function shipping.
IccResource::setActionOnAnyCondition
void setActionOnAnyCondition(ActionOnCondition action);
action
The name of the action as an enumeration. The possible values are listed
under the description of this class.
This method specifies the default action that is to be taken by the CICS foundation
classes when a CICS condition occurs.
IccResource::setActionOnCondition
void setActionOnAnyCondition(ActionOnCondition action,
IccCondition::Codes condition);
113
action
The name of the action as an enumeration. The possible values are listed
under the description of this class.
condition
See IccCondition structure.
This method specifies what action is automatically taken by the CICS foundation
classes when a given CICS condition occurs.
IccResource::setActionsOnConditions
void setActionsOnConditions(const char* actions=0);
actions
A string that indicates what action is to be taken for each condition. The default
is not to indicate any actions, in which case each condition is given a default
ActionOneCondition of noAction. The string should have the same format as
the one that is returned by the actionsOnConditionsText method.
IccResource::setEDF
void setEDF(Icc::Bool onOff);
onOff
A Boolean value that selects whether EDF trace is switched on or off.
This method switches EDF on or off for this resource object. See Execution
Diagnostic Facility for more information.
These methods force the object to route CICS requests to the named remote
system. This is called explicit function shipping.
IccResource::setRouteOption (1)
void setRouteOption(const IccSysId& sysId);
sysId
The IccSysId object that represents the remote system to which commands are
routed.
IccResource::setRouteOption (2)
void setRouteOption(const char* sysName=0);
sysName
The four-character name of the system to which commands are routed.
This option is valid only for the following classes:
v IccDataQueue
v IccFile
v IccFileIterator
v IccProgram
v IccStartRequestQ
v IccTempStore
If you use this method on other subclasses, an exception is thrown.
To turn off the route option, specify no parameter, for example:
obj.setRouteOption();
114
IccResource::ActionOnCondition
type enum {
noAction,
callHandleEvent,
throwException,
abendTask,
} ActionOnCondition;
noAction
Carry on as normal; it is the application programs responsibility to test CICS
conditions by using the condition method, after executing a method that calls
CICS services.
callHandleEvent
Call the virtual handleEvent method.
throwException
An IccException object is created and thrown. This is typically used for more
serious conditions or errors.
abendTask
Abend the CICS task.
IccResource::HandleEventReturnOpt
type enum {
rContinue,
rThrowException,
rAbendTask,
} HandleEventReturnOpt;
rContinue
The CICS event proceeded satisfactorily and normal processing is to resume.
rThrowException
The application program could not handle the CICS event and an exception is
to be thrown.
rAbendTask
The application program could not handle the CICS event and the CICS task is
to be abended.
IccResource::ConditionType
type enum {
majorCode,
minorCode,
} ConditionType;
majorCode
The returned value is the CICS RESP value. This is one of the values in
IccCondition::codes.
minorCode
The returned value is the CICS RESP2 value.
Related Information
IccBase class
IccBuf class
IccCondition class
115
IccDataQueue class
IccEvent class
IccFile class
IccFileIterator class
IccProgram class
IccResourceId class
IccSysId class
IccTempStore class
IccResourceId
Purpose
Represents CICS resource names.
Synopsis
class
{
protected:
IccResourceId(IccBase::ClassType type,
const IccResourceId& id);
IccResourceId(IccBase::ClassType type,
const char* resName);
IccResourceId& operator=(const IccResourceId& id);
public:
unsigned short nameLength() const;
};
Description
The IccResourceId is a base class from which all classes whose names end in
Id are derived. Many of these derived classes represent CICS resource names,
such as a file control table (FCT) entry.
Class Members
IccResourceId constructor (1)
protected IccResourceId(IccBase::ClassType type,
const IccResourceId& id);
type
An enumeration, which is defined in IccBase class, that indicates the type of
class.
id
A reference to an IccResourceId object that is used to create this object.
IccResourceId constructor (2)
116
protected IccResourceId(IccBase::ClassType type,

const char* resName);
type
An enumeration, defined in IccBase class, that indicates the type of class.
resName
The name of the resource that is used to create this object.
IccResourceId::operator= (1)
IccResourceId& operator=(const IccResource& id);
id
A reference to an IccResourceId object whose properties are copied into this

object.
IccResourceId::operator= (2)
protected
id
IccResourceId& operator=(const IccResourceId& id);
A reference to an IccResourceId object.
This operator sets an IccResourceId object to be identical to id.

IccResourceId::name
public const char* name() const;
This method returns the name of the resource identifier as a string. Most ...Id
objects have four- or eight-character names.
IccResourceId::nameLength
public unsigned short nameLength() const;
This method returns the length of the name that is returned by the name method.
Related Information
IccBase class
IccRRN
Purpose
Identifies records in VSAM RRDS files.
Synopsis
class
{
IccRRN(unsigned long initRRN=1);
IccRRN& operator=(const IccRRN& rrn);
IccRRN& operator=(unsigned longnum);
Icc::Bool operator==(const IccRRN& rrn) const;
Icc::Bool operator!=(const IccRRN& rrn) const;
unsigned long number() const;
};
117
Description
An IccRRN object holds a relative record number, and identifies records in VSAM
RRDS files.
Class Members
IccRRN constructor
IccRRN(unsigned long initRRN=1);
initRRN
The initial relative record number; that is, an integer greater than 0 (zero). The
default is 1.
IccRRN::operator= (1)
IccRRN& operator=(const IccRRN& rrn);
IccRRN::operator= (2)
IccRRN& operator=(unsigned longnum);
num
A relative record number; that is, an integer greater than 0 (zero).
This operator assigns a new value for the relative record number.
IccRRN::operator== (1)
Icc::Bool operator==(const
IccRRN& rrn) const;
IccRRN::operator== (2)

IccRRN::operator!= (1)
Icc::Bool operator!=(const IccRRN& rrn) const;
IccRRN::operator!= (2)

IccRRN::number
This method returns the relative record number.
Related Information
IccBase class
118
IccSemaphore
Purpose
Enables synchronization of resource updates.
Synopsis
#include <iccsemeh.hpp>
class
{
IccSemaphore(const char* resource,
LockType type=byValue,
LifeTime life-UOW);
IccSemaphore(const IccLockId& id,
LifeTime life=UOW);
Lifetime lifetime() const;
void lock();
Icc::Bool tryLock();
LockType type () const;
void unlock();
type enum {
byValue,
byAddress,
} LockType;
type enum {
UOW,
task,
} LifeTime;
};
Description
The IccSemaphore class enables synchronization of resource updates.
Class Members
IccSemaphore constructor (1)
IccSemaphore(const char* resource,
LockType type=byValue,
LifeTime life-UOW);
resource
A text string, if type is byValue, otherwise an address in storage.
type
An enumeration, which is defined in this class, that indicates whether locking is
by value or by address. The default is by value.
life
An enumeration, which is defined in this class, that indicates how long the
semaphore lasts. The default is to last for the length of the UOW.
IccSemaphore constructor (2)
IccSemaphore(const IccLockId& id,
LifeTime life=UOW);
id
life
An enumeration, which defined in this class, that indicates how long the
semaphore lasts. The default is to last for the length of the unit of work (UOW).
119
IccSemaphore::lifeTime
Lifetime lifetime() const;
whether the lock lasts for the length of the UOW or until the task terminates.
IccSemaphore::lock
void lock();
This method attempts to get a lock. It blocks if another task already owns the lock.
Conditions: ENQBUSY, LENGERR
IccSemaphore::tryLock
Icc::Bool tryLock();
This method attempts to get a lock. It does not block if another task already owns
the lock. It returns a Boolean that indicates whether it succeeded.
Conditions: ENQBUSY, LENGERR
IccSemaphore::type
LockType type () const;
what type of semaphore this is.
IccSemaphore::unlock
void unlock();
This method releases a lock.

Conditions: LENGERR
IccSemaphore::LockType
type enum {
byValue,
byAddress,
} LockType;
byValue
The lock is on the contents (for example, name).
byAddress
The lock is on the memory address.
IccSemaphore::LifeTime
type enum {
UOW,
task,
} LifeTime;
UOW
The semaphore lasts for the length of the current unit of work.
task
The semaphore lasts for the length of the task.
120
Related Information
IccBase class
IccLockId class
IccResource class
IccSession
Purpose
Enables APPC and DTP programming.
Synopsis
#include <iccseseh.hpp>
class
{
protected:
IccSession();
public:
IccSession(const IccPartnerId&);
IccSession(const IccSysId& sysId);
IccSession(const char* sysName);
void allocate(AllocateOpt option=queue);
void connectProcess(SyncLevel level,
const IccTransId& transId,
const IccBuf* PIP=0);
void connectProcess(syncLevel level,
const IccTPNameId& TPName,
const IccBuf& converse(const IccBuf& send);
const IccConvId& convId();
const char* errorCode() const;
void extractProcess();
void flush();
void free();
Icc::Bool isErrorSet() const;
Icc::Bool isNoDataSet() const;
Icc::Bool isSignalSet() const;
void issueAbend();
void issueConfirmation();
void issueError();
void issueSignal();
IccBuf& PIPList();
const IccBuf& process() const;
virtual void put(const IccBuf& data);
const IccBuf& receive();
void send(const IccBuf& send,
SendOpt option=normal);
void send(sendOpt option=normal);
void sendInvite(const IccBuf& send,
void sendInvite(SendOpt option=normal);
void sendLast(const IccBuf& send,
void sendLast(SendOpt option=normal);
IccValue::CVDA state(StateOpt option=lastCommand);
const char* stateText(StateOpt option=lastCommand);
SyncLevel syncLevel() const;
type enum {
queue,
121
noQueue,
} AllocateOpt,
type enum {
normal,
confirmation,
wait,
} SendOpt;
type enum {
lastCommand,
extractState,
} StateOpt;
type enum {
level0,
level1,
} SyncLevel;
};
Description
The IccSession class enables APPC and DTP programming.
Class Members
IccSession constructor
protected IccSession();
This constructor is for back end DTP CICS tasks that have a session as their
principal facility. In this case, the application program uses the session method on
the IccControl object to gain access to their IccSession object.
IccSession constructor (1)
IccSession(const IccPartnerId&);

IccSession(const IccSysId& sysId);
sysId
A reference to an IccSysId object that represents a remote CICS system.
IccSession(const char* sysName);
sysName
The four-character name of the remote CICS system with which this session is
associated.
IccSession::allocate
void allocate(AllocateOpt option=queue);
option
An enumeration, which defined in this class, that indicates what action CICS is
to take if a communication channel is unavailable when this method is called.
This method establishes a session (communication channel) to the remote system.
Equivalent EXEC CICS call: ALLOCATE
Conditions: INVREQ, SYSIDERR
122
IccSession::connectProcess (1)
const IccTransId& transId,
level
An enumeration, which is defined in this class, that indicates what sync level is
to be used for this conversation.
transId
A reference to an IccTransId object that holds the name of the transaction that
is to be started on the remote system.
PIP
An optional pointer to an IccBuf object that contains the PIP data that is to be
sent to the remote system.
Equivalent EXEC CICS call: CONNECT PROCESS CONVID
IccSession::connectProcess (2)
const IccTPNameId& TPName,
level
An enumeration, which is defined in this class, that indicates what sync level is
to be used for this conversation.
TPName
A reference to an IccTPNameId object that contains the 1 through 64 character
TP name.
PIP
An optional pointer top an IccBuf object that contains the PIP data that is nto
be sent to the remote system.
This method starts a partner process on the remote system in preparation for
sending and receiving information.
Equivalent EXEC CICS call: CONNECT PROCESS CONVID
Conditions: INVREQ, LENGERR, NOTALLOC, CBIDERR (Open Systems only),
SYSIDERR (Open Systems only), SYSBUSY (Open Systems only)
IccSession::converse
const IccBuf& converse(const IccBuf& send);
send
A reference to an IccBuf object that contains the data that is to be sent.
This method sends the contents of send and returns a reference to an IccBuf
object that holds the reply from the remote APPC partner.
Equivalent EXEC CICS call: CONVERSE CONVID
Conditions: INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR
IccSession::convId
const IccConvId& convId();
123
This method returns a reference to an IccConvId object that contains the four-byte
conversation identifier.
IccSession::errorCode
const char* errorCode() const;
This method returns the four-byte error code that is received when isErrorSet
remains true. See the relevant DTP Guide for more information.
IccSession::extractProcess
void extractProcess();
This method retrieves information from an APPC conversation attach header and
holds it inside the object. See PIPList, process, and syncLevel methods to
retrieve the information from the object. This method should be used by the back
end task if it wants access to the PIP data, the process name, or the synclevel
under which it is running.
Equivalent EXEC CICS call: EXTRACT PROCESS CONVID
Conditions: INVREQ, NOTAUTH
IccSession::flush
void flush();
This method ensures that accumulated data and control information are transmitted
on an APPC mapped conversation.
Equivalent EXEC CICS call: WAIT CONVID
Conditions: INVREQ, NOTALLOC
IccSession::free
void free();
This method returns the APPC session to CICS so that it can be used by other
tasks.
Equivalent EXEC CICS call: FREE CONVID
IccSession::get
This method is a synonym for receive. See Polymorphic behavior on page 10 for
more information about polymorphism.
IccSession::isErrorSet
Icc::Bool isErrorSet() const;
This method returns a Boolean variable, which is defined in Icc structure, that
indicates whether an error has been set.
IccSession::isNoDataSet
124
Icc::Bool isNoDataSet() const;
indicates if no data was returned on a send; only control information.
IccSession::isSignalSet
Icc::Bool isSignalSet() const;
indicates whether a signal has been received from the remote process.
IccSession::issueAbend
void issueAbend();
This method abnormally ends the conversation. The partner transaction sees the
TERMERR condition.
Equivalent EXEC CICS call: ISSUE ABEND CONVID
Conditions: INVREQ, NOTALLOC, TERMERR
IccSession::issueConfirmation
void issueConfirmation();
This method sends positive response to a partners send request that specified the
confirmation option.
Equivalent EXEC CICS call: ISSUE CONFIRMATION CONVID
IccSession::issueError
void issueError();
This method signals an error to the partner process.

Equivalent EXEC CICS call: ISSUE ERROR CONVID
IccSession::issueSignal
void issueSignal();
This method signals that a mode change is needed.

Equivalent EXEC CICS call: ISSUE SIGNAL CONVID
IccSession::PIPList
IccBuf& PIPList();
This method returns a reference to an IccBuf object that contains the PIP data that
is sent from the front end process. A call to this method should be preceded by a
call to extractProcess on back end DTP processes.
125
IccSession::process
const IccBuf& process() const;
This method returns a reference to an IccBuf object that contains the process data
that is sent from the front end process. A call to this method should be preceded by
a call to extractProcess on back end DTP processes.
IccSession::put
virtual void put(const IccBuf& data);
data
A reference to an IccBuf object that holds the data that is to be sent to the
remote process.
This method is a synonym for send. See Polymorphic behavior on page 10 for
IccSession::receive
const IccBuf& receive();
This method returns a reference to an IccBuf object that contains the data that is
received from the remote system.
Equivalent EXEC CICS call: RECEIVE CONVID
IccSession::send (1)
void send(const IccBuf& send,
send
option
send method. The default is normal.
Equivalent EXEC CICS call: SEND CONVID
IccSession::send (2)
void send(sendOpt option=normal);
option
This method sends data to the remote partner.
Equivalent EXEC CICS call: SEND CONVID
IccSession::sendInvite (1)
void sendInvite(const IccBuf& send,
126
send
option
Equivalent EXEC CICS call: SEND CONVID INVITE
IccSession::sendInvite (2)
void sendInvite(sendOpt option=normal);
option
sendInvite method. The default is normal.
This method sends data to the remote partner and indicates a change of direction;
that is, the next method on this object will be receive.
Equivalent EXEC CICS call: SEND CONVID INVITE
IccSession::sendLast (1)
void sendLast(const IccBuf& send,
send
option
sendLast method. The default is normal.
Equivalent EXEC CICS call: SEND CONVID LAST
IccSession::sendLast (2)
void sendLast(sendOpt option=normal);
option
sendLast method. The default is normal.
This method sends data to the remote partner and indicates that this is a final
transaction. The free method must be invoked next, unless the sync level is 2,
when you must commit resource updates before the free. See commitOUW in
IccTask class for more information.
Equivalent EXEC CICS call: SEND CONVID LAST
IccSession::state
IccValue::CVDA state(StateOpt option=lastCommand);
option
An enumeration, which is defined in this class, that indicates how to report the
state of a conversation.
127
This method returns a CVDA, as defined in IccValue structure, that indicates the
current state of the APPC conversation. Possible values are:
v ALLOCATED
v CONFFREE
v
v
v
v
v
v
v
FREE
PENDFREE
PENDRECEIVE
RECEIVE
ROLLBACK
SEND
SYNCFREE
v SYNCRECEIVE
v SYNCSEND
v NOTAPPLIC
IccValue::NOTAPPLIC is returned if no APPC conversation state exists.
Equivalent EXEC CICS call: EXTRACT ATTRIBUTES
IccSession::stateText
const char* stateText(StateOpt option=lastCommand);
option
An enumeration, which is defined in this class, that indicates how to report the
conversation.
This method returns the symbolic name of the state that state method would return.
For example, if state returns IccValue::ALLOCATED, stateText would return
ALLOCATED.
IccSession::syncLevel
SyncLevel syncLevel() const;
the synchronization level that is being used in this session. A call to this method
should be proceeded by a call to extractProcess on back end DTP processes.
IccSession::AllocateOpt
type enum {
queue,
noQueue,
} AllocateOpt;
queue
If all available sessions are in use, CICS is to queue this request (and block the
method) until it can allocate a session.
noQueue
Control is returned to the application if it cannot allocate a session. CICS raises
the SYSBUSY condition.
This enumeration indicates whether queueing is required on an allocate method.
128
IccSession::SendOpt
type enum {
normal,
confirmation,
wait,
} SendOpt;
normal
The default.
confirmation
Indicates that a program that is using SyncLevel level1 or level2 requires a
response from the remote partner program. The remote partner can respond
positively, by using the issueConfirmation method, or negatively, by using the
issueError method. The sending program does not receive control back from
CICS until the response is received.
wait
Requests that the data is sent and not buffered internally. CICS is free to buffer
requests to improve performance if this option is not specified.
IccSession::StateOpt
type enum {
lastCommand,
extractState,
} StateOpt;
lastCommand
Return the state at the time of the completion of the last operation on the
session.
extractState
Return the explicitly extracted current state.
IccSession::SyncLevel
type enum {
level0,
level1,
} SyncLevel;
level0
Sync level 0 (zero).
level1
Sync level 1.
Related Information
IccBase class
IccBuf class
IccConvId class
IccPartnerId class
IccResource class
IccSysId class
IccTask class
129
IccTPNameId class
IccTransId class
IccValue class
IccStartRequestQ
Purpose
Enables the application programmer to request an asynchronous start of another
CICS transaction.
Synopsis
#include <iccsrqeh.hpp>
class
{
protected:
IccStartRequestQ();
public:
void cancel(const IccRequestId& reqId,
const IccTransId* transId=0);
const IccBuf& data() const;
static IccStartRequestQ* instance();
const char* queueName() const;
void registerData(const IccBuf* buffer);
void reset();
void retrieveData(RetrieveOpt option=noWait);
const IccTransId& returnTermId() const;
const IccTransId& returnTransId() const;
void setData(const IccBuf& buf);
void setQueueName(const char* queueName);
void setReturnTermId(const IccTermId& termId);
void setReturnTermId(const char* termName);
void setReturnTransId(const IccTransId& transId);
void setReturnTransId(const char* transName);
void setStartOpts(ProtectOpt popt=none,
CheckOpt copt=check);
void setTermId(const IccTermId& termId);
void setTermId(const char* termName);
const IccRequestId& start(const IccTransId& transId,
const IccRequestId* reqId=0);
type enum {
noWait,
wait,
} RetrieveOpt;
type enum {
none,
protect,
} ProtectOpt;
type enum {
check,
noCheck,
} CheckOpt;
};
Description
The IccStartRequestQ class is a singleton class that enables the application
programmer to request an asynchronous start of another CICS transaction (see the
start method, which is defined in this class). An asynchronously started transaction
130
uses the IccStartRequestQ class method retrieveData to gain the information that
is passed to it by the transaction that issued the start request.
You can cancel an unexpired start request by using the cancel method.
Class Members
IccStartRequestQ constructor
protected IccStartRequestQ();
IccStartRequestQ::cancel
void cancel(const IccRequestId& reqId,
const IccTransId* transId=0);
reqId
A reference to an IccRequestId object that represents the request that is to be
canceled.
transId
An optional pointer to an IccTransId object that represents the transaction that
is to be canceled.
This method cancels a previously issued start request that has not yet expired.
Equivalent EXEC CICS call: CANCEL
Conditions: INVREQ (Open Systems only), ISCINVREQ, NOTAUTH, NOTFND,
SYSIDERR
IccStartRequestQ::data
const IccBuf& data() const;
This method returns a reference to an IccBuf object that contains data that is
passed on a start request. A call to this method should be preceded by a call to
retrieveData method.
IccStartRequestQ::instance
static IccStartRequestQ* instance();
This method returns a pointer to the single IccStartRequestQ object. If the object
does not exist, it is created. See also startRequestQ method, which is defined in
IccControl class.
IccStartRequestQ::queueName
const char* queueName() const;
This method returns the name of the queue that was passed by the start requester.
A call to this method should be preceded by a call to retrieveData method.
IccStartRequestQ::registerData
void registerData(const IccBuf* buffer);
buffer
A pointer to the IccBuf object that holds data that is to be passed on a start
request.
131
This method registers an IccBuf object to be interrogated for start data on each
subsequent start method invocation. This stores the address of the IccBuf object
within the IccStartRequestQ so that the IccBuf object can be found when using
the start method. This differs from the setData method, which takes a copy of the
data that is held in the IccBuf object during the time that it is invoked.
IccStartRequestQ::reset
void reset();
This method clears any associations that were previously made by set... methods in
this class.
IccStartRequestQ::retrieveData
void retrieveData(RetrieveOpt option=noWait);
option
An enumeration, which is defined in this class, that indicates what happens if no
start data is available.
This method is used by a task that was started, by way of an async start request, to
gain access to the information that is passed by the start requester. The information
is returned by the data, queueName, returnTermId, and returnTransId methods.
Equivalent EXEC CICS call: RETRIEVE
Conditions: ENDDATA, ENVDEFERR, IOERR, LENGERR, NOTFND
Note: The ENVDEFERR condition will be raised if all the possible options
(setData, setQueueName, returnTermId, and setReturnTransId) are not
used before issuing the start method. This condition is therefore not
necessarily an error condition and your program should handle it accordingly.
IccStartRequestQ::returnTermId
const IccTransId& returnTermId() const;
This method returns a reference to an IccTermId object that identifies which

terminal is involved in the session. A call to this method should be preceded by a
call to retrieveData method.
IccStartRequestQ::returnTransId
const IccTransId& returnTransId() const;
This method returns a reference to an IccTransId object that is passed on a start

request. A call to this method should be preceded by a call to retrieveData method.
IccStartRequestQ::setData
void setData(const IccBuf& buf);
This method copies the data in buf into the IccStartRequestQ, which passes it to
the started transaction when the start method is called. See also registerData,
defined in this class, for an alternative way to pass data to started transactions.
IccStartRequestQ::setQueueName
void setQueueName(const char* queueName);
132
queueName
An eight-character queue name.
This method requests that this queue name be passed to the started transaction
when the start method is called.
IccStartRequestQ::setReturnTermId (1)
void setReturnTermId(const IccTermId& termId);
termId
A reference to an IccTermId object that identifies which terminal is involved in
the session.
IccStartRequestQ::setReturnTermId (2)
void setReturnTermId(const char* termName);
termName
A four-character name of the terminal that is involved in the session.
This method requests that this return terminal ID be passed to the started
transaction when the start method is called.
IccStartRequestQ::setReturnTransId (1)
void setReturnTransId(const IccTransId& transId);
transId
A reference to an IccTransId object.
IccStartRequestQ::setReturnTransId (2)
void setReturnTransId(const char* transName);
transName
The four-character name of the return transaction.
IccStartRequestQ::setStartOpts
void setStartOpts(ProtectOpt popt=none,
CheckOpt copt=check);
popt
An enumeration, which is defined in this class, that indicates whether start
requests are to be protected.
copt
An enumeration, which is defined in this class, that indicates whether start
requests are to be checked.
This method sets whether the started transaction is to have protection and whether
it is to be checked.
IccStartRequestQ::setTermId (1)
void setTermId(const IccTermId& termId);
termId
A reference to an IccTermId object that identifies which terminal is involved in
the session.
IccStartRequestQ::setTermId (2)
void setTermId(const char*termName);
133
termName
The four-character name of the terminal that is involved in the session.
This method sets the name of the terminal on which all subsequent starts are to
occur.
IccStartRequestQ::start
const IccRequestId& start(const IccTransId& transId,
transId
A reference to an IccTransId object that represents the transaction that is to be
started.
time
An (optional) pointer to an IccTime object that specifies when the task is to be
started. The default is for the task to be started immediately.
reqId
An (optional) pointer to an IccRequestId object that is used to identify this start
request so that the cancel method can cancel the request.
This method asynchronously starts the named CICS transaction. The returned
reference to an IccRequestId object identifies the start request and can be used
subsequently to cancel the start request.
Equivalent EXEC CICS call: START TRANSID
Conditions: INVREQ, IOERR, ISCINVREQ, LENGERR, NOTAUTH, SYSIDERR,
TERMIDERR, TRANSIDERR
IccStartRequestQ::RetrieveOpt
type enum {
noWait,
wait,
} RetrieveOpt;
IccStartRequestQ::ProtectOpt
type enum {
none,
protect,
} ProtectOpt;
IccStartRequestQ::CheckOpt
type enum {
check,
noCheck,
} CheckOpt;
Related Information
IccBase class
IccBuf class
IccRequestId class
IccTermId class
134
IccTimeId class
IccTransId class
IccSysId
Purpose
Identifies a remote CICS system.
Synopsis
class
{
IccSysId(const char* name);
IccSysId(const IccSysId& id);
IccSysId& operator=(const IccSysId& id);
IccSysId& operator=(const char* name);
};
Description
The IccSysId class is used to identify a remote CICS system.
Class Members
IccSysId constructor (1)
IccSysId(const char* name);
name
The four-character name of the CICS system.
IccSysId constructor (2)
IccSysId(const IccSysId& id);
id
A reference to an IccSysId object.

IccSysId::operator= (1)
IccSysId& operator=(const IccSysId& id);
id
A reference to an existing IccSysId object.
IccSysId::operator= (2)
IccSysId& operator=(const char* name);
name
The four-character name of the CICS system.
This constructor sets the name of the CICS system held in the object.
Related Information
IccBase class
IccResourceId class
135
IccSystem
Purpose
Represents the CICS system.
Synopsis
#include <iccsyseh.hpp>
class
{
protected:
IccSystem();
public:
const char* applName();
void beginBrowse (ResourceType resource);
const char* dateFormat();
void endBrowse(ResourceType resource);
void freeStorage(void* pStorage);
IccFile* getFile(const IccFileId& id);
IccFile* getFile(const char* fileName);
IccFile* getNextFile();
void* getStorage(unsigned long size,
char initByte=-1,
unsigned long storageOpts=0);
static IccSystem* instance();
char operatingSystem();
unsigned short operatingSystemLevel();
unsigned long release();
const char* releaseText();
IccSysId& sysId();
const IccBuf& workArea();
type enum {
autoInstallModel,
connection,
dataQueue,
exitProgram,
externalDataSet,
file,
journal,
modename,
partner,
profile,
program,
requestId,
systemDumpCode,
tempStore,
terminal,
transactionDumpCode,
transaction,
transactionClass,
} ResourceType;
};
Description
The IccSystem class is a singleton class that represents the CICS system. It is
used by an application program to discover information about the CICS system on
which it is running.
136
Class Members
IccSystem constructor
protected IccSystem();
IccSystem::applName
const char* applName();
This method returns the eight-character name of the CICS region.

Equivalent EXEC CICS call: ASSIGN APPLID
Condition: INVREQ
IccSystem::beginBrowse
void beginBrowse (ResourceType resource);
resource
resource that is to be browsed within the CICS system.
This method signals the start of a browse through a set of CICS resources.
Equivalent EXEC CICS call: INQUIRE (FILE, TDQUEUE, and so on) START
IccSystem::dateFormat
const char* dateFormat();
This method returns the default dateFormat for the CICS region.
Equivalent EXEC CICS call: FORMATTIME DATEFORM
Conditions: ERROR (Open Systems only).
IccSystem::endBrowse
void endBrowse(ResourceType resource);
This method signals the end of a browse through a set of CICS resources.
Equivalent EXEC CICS call: INQUIRE (FILE TDQUEUE, and so on) END
IccSystem::freeStorage
This method releases the storage that is obtained by the IccSystem getStorage
method.
Equivalent EXEC CICS call: FREEMAN
137
IccSystem::getFile (1)
IccFile* getFile(const IccFileId& id);
id
A reference to an IccFileId object that identifies a CICS file.
IccSystem::getFile (2)
IccFile* getFile(const char* fileName);
fileName
The name of a CICS file.
This method returns a pointer to the IccFile object that is identified by the
argument.
Equivalent EXEC CICS call: INQUIRE FILE
IccSystem::getNextFile
IccFile* getNextFile();
This method is valid only after a successful beginBrowse(IccSystem::file) call. It

returns the next file object in the browse sequence in the CICS system.
Equivalent EXEC CICS call: INQUIRE FILE NEXT
IccSystem::getStorage
char initByte=-1,
size
The amount of storage that is being requested, in bytes.
initByte
The initial setting of all bytes in the allocated storage.
storageOpts
An enumeration, which is defined in IccTask class, that affects the way that
CICS allocates storage.
This method obtains a block of storage of the requested size and returns a pointer
to it. The storage is not released automatically at the end of the task; it is released
only when a freeStorage operation is performed.
Equivalent EXEC CICS call: GETMAIN SHARED
Conditions: LENGERR, NOSTG
IccSystem::instance
static IccSystem* instance();
This method returns a pointer to the singleton IccSystem object. The object is
created if it does not already exist.
IccSystem::operatingSystem
138
char operatingSystem();
This method returns a one-character value that identifies the operating system
under which CICS is running:
v A: AIX
v N: Windows
v P: OS/2
Equivalent EXEC CICS call: INQUIRE SYSTEM OPSYS
IccSystem::operatingSystemLevel
unsigned short operatingSystemLevel();
This method returns a halfword binary field that gives the release number of the
operating system under which CICS is running. The value that is returned is ten
times the formal release number (the version number is not represented).
Equivalent EXEC CICS call: INQUIRE SYSTEM OPREL
IccSystem::release
unsigned long release();
This method returns the level of the CICS system as an integer that is made from
100 times the version number and 10 times the release level. For example, CICS
for AIX Version 2 Release 1 would return 210, or [(100x2)+(10x1)=210].
Equivalent EXEC CICS call: INQUIRE SYSTEM RELEASE
IccSystem::releaseText
const char* releaseText();
This method returns the same as release, except as a four-character string. For
example, CICS for AIX Version 2 Release 1 would return 0210.
Equivalent EXEC CICS call: INQUIRE SYSTEM RELEASE
IccSystem::sysId
IccSysId& sysId();
This method returns a reference to the IccSysId object that identifies this CICS
system.
Equivalent EXEC CICS call: ASSIGN SYSID
Conditions: INVREQ
IccSystem::workArea
const IccBuf& workArea();
This method returns a reference to the IccBuf object that holds the work area for
the CICS system.
Equivalent EXEC CICS call: ADDRESS CWA
139
Conditions: INVREQ
IccSystem::ResourceType
type enum {
autoInstallModel,
connection,
dataQueue,
exitProgram,
externalDataSet,
file,
journal,
modename,
partner,
profile,
program,
requestId,
systemDumpCode,
tempStore,
terminal,
transactionDumpCode,
transaction,
transactionClass,
} ResourceType;
Related Information
IccBase class
IccBuf class
IccFile class
IccResource class
IccResourceId class
IccSysId class
IccTask
Purpose
Invokes task-related CICS services.
Synopsis
#include <icctskeh.hpp>
class
{
protected:
IccTask();
public:
void abend(const char* abendCode=0,
AbendHandlerOpt opt1=respectAbendHandler,
AbendDumpOpt opt2=createDump);
IccAbendData* abendData();
void commitUOW();
void delay(const IccTime& time,
const char* dump(const char* dumpCode,
const IccBuf* buf=0);
void enterTrace(unsigned short traceNum,
140
const char* resource=0,

IccBuf* data=0,
TraceOpt opt=normal);
FacilityType facilityType();
void getStorage(unsigned long size,
char initByte=-1,
unsigned short storageOpts=0);
static IccTask* instance();
Icc::Bool isCommitSupported();
Icc::Bool isRestarted();
Icc::Bool isStartDataAvailable();
IccSysId& principalSysId(Icc::GetOpt opt=Icc::object);
void rollbackUOW();
void setDumpOpts(unsigned long opts=dDefault);
void setWaitText(const char* name);
StartType startType();
void suspend();
const IccTransId& transId();
const IccDataQueueId& triggerDataQueueId();
const IccUserId& userId(Icc::GetOpt opt=Icc::object);
IccBuf& workArea();
type enum {
respectAbendHandler,
ignoreAbendHandler,
} AbendHandlerOpt;
type enum {
createDump,
} AbendDumpOpt;
type enum {
dDefault,
dComplete,
dTask,
dStorage,
dProgram,
dTerminal,
dTables,
dDCT,
dFCT,
dPCT,
dPPT,
dSIT,
dTCT,
} DumpOpts;
type enum {
none,
terminal,
session,
dataqueue,
} FacilityType;
type enum {
DPL,
dataQueueTrigger,
startRequest,
FEPIRequest,
terminalInput,
CICSInternalTask,
} StartType;
type enum {
purgeable,
nonPurgeable,
} WaitPurgeability;
};
141
Description
The IccTask class is a singleton class that invokes task-related CICS services.
Class Members
IccTask constructor
protected IccTask();
IccTask::abend
void abend(const char* abendCode=0,
AbendHandlerOpt opt1=respectAbendHandler,
AbendDumpOpt opt2=createDump);
abendCode
The four-character abend code.
opt1
An enumeration, which is defined in this class, that indicates whether to respect
or ignore any abend handling program that is specified by setAbendHandler
method in IccControl class.
opt2
An enumeration, which is defined in this class, that indicates whether a dump is
to be created.
This method requests CICS to abend this task.
Equivalent EXEC CICS call: ABEND
IccTask::abendData
IccAbendData* abendData();
This method returns a pointer to an IccAbendData object that contains information

about the program abends, if any, that relate to this task.
IccTask::commitUOW
void commitUOW();
This method commits the resource updates within the UOW for this task. This also
causes a new UOW to start for subsequent resource update activity.
Equivalent EXEC CICS call: SYNCPOINT
Conditions: INVREQ, ROLLEDBACK
IccTask::delay
void delay(const IccTime& time,
time
A reference to an object that contains information about the delay time. The
object can be one of these types:
v IccTimeInterval : Expresses an interval of time, such as 3 hours, 2 minutes,
and 1 second.
v IccTimeOfDay: Expresses a time of day, such as 13 hours, 30 minutes
(1:30PM).
142
reqId
An optional pointer to an IccRequestId object that can be used to cancel an
unexpired delay request.
This method requests that this task be delayed for an interval of time, or until a
specific time.
Equivalent EXEC CICS call: DELAY
Conditions: EXPIRED, INVREQ
IccTask::dump
const char* dump(const char* dumpCode,
const IccBuf* buf=0);
dumpCode
A four-character label that identifies this dump.
buf
A pointer to the IccBuf object that contains additional data that is to be included
in the dump.
This method configures CICS to prepare a system dump for this task. It also returns
the identifier, in characters, of the system dump. See also setDumpOpts for more
information.
Equivalent EXEC CICS call: DUMP TRANSACTION
IccTask::enterTrace
void enterTrace(unsigned short traceNum,
const char* resource=0,
IccBuf* data=0,
TraceOpt opt=normal);
traceNum
The trace identifer for a user trace table entry; a value in the range 0 through
199.
resource
An eight-character name that is to be entered in the resource field of the trace
table entry.
data
A pointer to the IccBuf object that contains data that is to be included in the
trace record.
opt
An enumeration, which is defined in this class, that indicates whether tracing
should be normal or whether only exceptions should be traced.
This method writes a user trace entry in the CICS trace table.
Equivalent EXEC CICS call: ENTER TRACENUM
Conditions: INVREQ, LENGERR
IccTask::facilityType
FacilityType facilityType();
143
what type of principal facility this task has. This is usually a terminal, such as when
the task was started by someones keying a transaction name on a CICS terminal.
It is a session if the task is the back end of a mapped APPC conversation.
Equivalent EXEC CICS call: ASSIGN STARTCODE, TERMCODE, PRINSYSID, FCI
Conditions: INVREQ
IccTask::freeStorage
This method releases the storage that is obtained by the IccTask getStorage
method.
Equivalent EXEC CICS call: FREEMAIN
Conditions: INVREQ
IccTask::getStorage
char initByte=-1,
size
The amount of storage that is being requested, in bytes.
initByte
The initial setting of all bytes in the allocated storage.
storageOpts
An enumeration, which is defined in this class, that affects the way that CICS
allocates storage.
This method obtains a block of storage of the requested size and returns a pointer
to it. The storage is released automatically at the end of the task, or when a
freeStorage operation is performed.
Conditions: LENGERR, NOSTG
IccTask::instance
static IccTask* instance();
This method returns a pointer to the singleton IccTask object. The object is created
if it does not already exist.
IccTask::isCommitSupported
Icc::Bool isCommitSupported();
This method returns a Boolean, which is defined in Icc structure that indicates
whether this task can support the commit method. This method returns true in
most environments; the exception is in a DPL environment (see link in IccProgram
for more information).
Equivalent EXEC CICS call: ASSIGN STARTCODE
Conditions: INVREQ
144
IccTask::isRestarted
Icc::Bool isRestarted();
This method returns a Boolean, which is defined in Icc structure, that indicates
whether this task has been automatically restarted by CICS.
Equivalent EXEC CICS call: ASSIGN RESTART
Conditions: INVREQ
IccTask::isStartDataAvailable
Icc::Bool isStartDataAvailable();
This method returns a Boolean, which is defined in Icc structure, that indicates
whether start data is available for this task. See the retrieveData method in
IccStartRequestQ class if start data is available.
Conditions: INVREQ
IccTask::number
This method returns the number of this task, which is unique within the CICS
system.
IccTask::principalSysId
IccSysId& principalSysId(Icc::GetOpt opt=Icc::object);
This method returns a reference to the IccSysId object that identifies the principal
system identifier for this CICS Task.
Equivalent EXEC CICS call: ASSIGN PRINSYSID
Conditions: INVREQ
IccTask::rollBackUOW
void rollBackUOW();
This method rolls back, or backs out, the resource updates that are associated with
the current UOW within this task.
Equivalent EXEC CICS call: SYNCPOINT ROLLBACK
Conditions: INVREQ, ROLLEDBACK
IccTask::setDumpOpts
void setDumpOpts(unsigned long opts=dDefault);
opts
An integer, which is made by adding or using logical OR values from the
DumpOpts enumeration, that is defined in this class.
145
This method sets the system dump options for this task. This method also affects
the behavior of the dump method that is defined in this class.
IccTask::setWaitText
void setWaitText(const char* name);
name
The eight-character string label that indicates why this task is waiting.
This method sets the text that will appear when someone inquires on this task while
it is suspended as a result of a waitExternal or waitOnAlarm method call.
IccTask::startType
StartType startType();
how this task was started.
Conditions: INVREQ
IccTask::suspend
void suspend();
This method suspends this task, allowing other tasks to be dispatched.

Equivalent EXEC CICS call: SUSPEND
IccTask::transId
const IccTransId& transId();
This method returns the IccTransId object that represents the transaction name of
this CICS task.
IccTask::triggerDataQueueId
const IccDataQueueId& triggerDataQueueId();
This method returns a reference to the IccDataQueueId that represents the trigger
queue, if this task was started as a result of data arriving on an IccDataQueue.
See startType method.
Equivalent EXEC CICS call: ASSIGN QNAME
Conditions: INVREQ
IccTask::userId
const IccUserId& userId(Icc::GetOpt opt=Icc::object);
opt
An enumeration, which is defined in Icc structure, that indicates whether the
information that already exists in the object is to be used or whether it is to be
refreshed from CICS.
This method returns the ID of the user who is associated with this task.
146
Equivalent EXEC CICS call: ASSIGN USERID

Conditions: INVREQ
IccTask::workArea
IccBuf& workArea();
This method returns a reference to the IccBuf object that holds the work area for
this task.
Equivalent EXEC CICS call: ADDRESS TWA
Conditions: INVREQ
IccTask::AbendHandlerOpt
type enum {
respectAbendHandler,
ignoreAbendHandler,
} AbendHandlerOpt;
respectAbendHandler
Allows control to be passed to an abend handling program if one is in effect.
ignoreAbendHandler
Does not allow control to be passed to an abend handling program that might
be in effect.
IccTask::AbendDumpOpt
type enum {
createDump,
} AbendDumpOpt;
createDump
Take a transaction dump when servicing an abend request.
IccTask::DumpOpts
type enum {
dDefault,
dComplete,
dTask,
dStorage,
dProgram,
dTerminal,
dTables,
dDCT,
dFCT,
dPCT,
dPPT,
dSIT,
dTCT,
} DumpOpts;
These values can be added together, or bitwise ORed, to get the desired
combination. For example:
IccTask::dProgram + IccTask::dDCT + IccTask::dSIT
IccTask::FacilityType
147
type enum {
none,
terminal,
session,
dataqueue,
} FacilityType;
none
The task has no principal facility; that is, it is a background task.
terminal
This task has a terminal as its principal facility.
session
This task has a session as its principal facility; that is, it was probably started as
a backend DTP program.
dataqueue
This task has a transient data queue as its principal facility.
IccTask::StartType
type enum {
DPL;
dataQueueTrigger,
startRequest,
FEPIRequest,
terminalInput,
CICSInternalTask,
} StartType;
DPL
Distributed program link request.
dataQueueTrigger
Trigger by data arriving on a data queue.
startRequest
Started as a result of an asynchronous start request. See IccStartRequestQ
class.
FEPIRequest
Front end programming interface.
terminalInput
Started by way of a terminal input.
CICSInternalTask
Started by CICS.
IccTask::WaitPurgeability
type enum {
purgeable,
nonPurgeable,
} WaitPurgeability;
purgeable
Task can be purged by way of a system call.
nonPurgeable
Task cannot be purged by way of a system call.
148
Related Information
IccAbsTime class
IccAbendData class
IccBase class
IccBuf class
IccDataQueueId class
IccFile class
IccRequestId class
IccResource class
IccResourceId class
IccSysId class
IccTask class
IccTime class
IccTimeOfDay class
IccTransId class
IccUserId class
IccTempStore
Purpose
Manages the temporary storage of data.
Synopsis
#include <icctmpeh.hpp>
class
{
public:
IccTempStore(const IccTempStoreId& id,
Location Ioc=auxStorage);
IccTempStore(const char* storeName,
void empty();
unsigned short numberOfItems() const;
const IccBuf& readItem(unsigned short itemNum);
const IccBuf& readNextItem();
149
void rewriteItem(unsigned short itemNum,

const IccBuf& item,
NoSpaceOpt opt=suspend);
unsigned short writeItem(const IccBuf& item,
unsigned short writeItem(const IccBuf& text,
type enum {
auxStorage,
memory,
} Location;
type enum {
suspend,
returnCondition,
} NoSpaceOpt;
};
Description
The IccTempStore objects manage the temporary storage of data. (IccTempStore
data can exist between transaction calls.)
Class Members
IccTempStore constructor (1)
IccTempStore(const IccTempStoreId& id,
id
Reference to an IccTempStoreId object.
loc
An enumeration, which is defined in this class, that indicates where the storage
is to be located when it is first created. The default is to use auxiliary storage
(disks).
IccTempStore constructor (2)
IccTempStore(const char* storeName,
storeName
Specifies the eight-character name of the queue that is to be used. The name
must be unique within the CICS system.
loc
An enumeration, which is defined in this class, that indicates where the storage
is to be located when it is first created. The default is to use auxiliary storage
(disks).
IccTempStore::clear
This method is synonymous with empty. See Polymorphic behavior on page 10

for more information about polymorphism.
IccTempStore::empty
void empty();
This method deletes all the temporary data that is associated with the
IccTempStore object.
150
Equivalent EXEC CICS call: DELETEQ TS

Conditions: INVREQ, ISCINVREQ, NOTAUTH, QIDERR, SYSIDERR, IOERR (Open
Systems only)
IccTempStore::get
This method is synonymous with readNextItem. See Polymorphic behavior on

page 10 for more information about polymorphism.
IccTempStore::numberOfItems
unsigned short numberOfItems() const;
This method returns the number of items that are in temporary storage. This is valid
only after a successful writeItem call.
IccTempStore::put
buffer
A reference to an IccBuf object that contains the data that is to be added to the
end of the temporary storage queue.
This method is synonymous with writeItem. See Polymorphic behavior on page
10 for more information about polymorphism.
IccTempStore::readItem
const IccBuf& readItem(unsigned short itemNum);
itemNum
Specifies the item number of the logical record that is to be retrieved from the
queue.
This method reads the specified item from the temporary storage queue and returns
a reference to the IccBuf object that contains the information.
Equivalent EXEC CICS call: READQ TS ITEM
Conditions: INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, NOTAUTH,
QIDERR, SYSIDERR
IccSystem::readNextItem
const IccBuf& readNextItem();
This method reads the next item from the temporary storage queue and returns a
reference to the IccBuf object that contains the information.
Equivalent EXEC CICS call: READQ TS NEXT
IccSystem::rewriteItem
void rewriteItem(unsigned short itemNum,
const IccBuf& item,
151
itemNum
Specifies the item number of the logical record that is to be modified.
item
The name of the IccBuf object that contains the update data.
opt
An enumeration, which is defined in this class, that indicates whether the
application program is to be suspended if a shortage of space in the queue
prevents the record from being added. suspend is the default value.
This method updates the specified item in the temporary storage queue.
Equivalent EXEC CICS call: WRITEQ TS ITEM REWRITE
Conditions: INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, NOSPACE,
NOTAUTH, QIDERR, SYSIDERR
IccSystem::writeItem (1)
unsigned short writeItem(const IccBuf& item,
item
The name of the IccBuf object that contains the update data.
opt
An enumeration, defined in this class, that indicates whether the application
program is to be suspended if a shortage of space in the queue prevents the
record from being added. suspend is the default value.
IccSystem::writeItem (2)
unsigned short writeItem(const char* text,
text
The text string that is to be added to the end of the temporary storage queue.
opt
An enumeration, which is defined in this class, that indicates whether the
application program is to be suspended if a shortage of space in the queue
prevents the record from being added. suspend is the default value.
This method adds a new record at the end of the temporary storage queue. The
returned value is the item number that was created (if this was done successfully).
Equivalent EXEC CICS call: WRITEQ IS ITEM
Conditions: INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, NOSPACE,
NOTAUTH, QIDERR, SYSIDERR
IccSystem::location
type enum {
auxStorage,
memory,
} Location;
auxStorage
Temporary store data is to reside in auxiliary storage (disks).
152
memory
Temporary storage data is to reside in memory.
IccSystem::NoSpaceOpt
type enum {
suspend,
returnCondition,
} NoSpaceOpt;
suspend
Suspend the application program.
returnCondition
Do not suspend application program, but raise the NOSPACE condition instead.
Related Information
IccBase class
IccBuf class
IccResource class
IccTempStoreId class
IccTempStoreId
Purpose
Identifies a temporary storage name in the CICS system.
Synopsis
class
{
IccTempStoreId(const char* name);
IccTempStoreId(const IccTempStoreId& id);
IccTempStoreId& operator=(const char* name);
IccTempStoreId& operator=(const IccTempStoreId& id);
};
Description
The IccTempStoreId class identifies a temporary storage name in the CICS
system. On AIX, this is a TSD stanza of the permanent resource database.
Class Members
IccTempStoreId constructor (1)
IccTempStoreId(const char* name);
name
The eight-character name of the temporary storage entry.
IccTempStoreId constructor (2)
IccTempStoreId(const IccTempStoreId& id);
id
A reference to an IccTempStoreId object.

153

IccTempStoreId::operator= (1)
IccTempStoreId& operator=(const char* name);
name
The eight-character name of the temporary storage entry.
IccTempStoreId::operator= (2)
IccTempStoreId& operator=(const IccTempStoreId& id);
id
A reference to an IccTempStoreId object.
Related Information
IccBase class
IccResourceId class
IccTermId
Purpose
Identifies a terminal name in the CICS system.
Synopsis
class
{
IccTermId(const char* name);
IccTermId(const IccTermId& id);
IccTermId& operator=(const char* name);
IccTermId& operator=(const IccTermId& id);
};
Description
The IccTermId class is used to identify a terminal name in the CICS system. On
AIX, this is a WD stanza of the permanent resource database.
Class Members
IccTermId constructor (1)
IccTermId(const char* name);
name
The four-character name of the terminal.
IccTermId constructor (2)
IccTermId(const IccTermId& id);
id
A reference to an IccTermId object.

IccTermId::operator= (1)
154
IccTermId& operator=(const char* name);
name
The four-character name of the terminal.
IccTermId::operator= (2)
IccTermId& operator=(const IccTermId& id);
id
A reference to an IccTermId object.
Related Information
IccBase class
IccResourceId class
IccTerminal
Purpose
Represents the terminal that belongs to the CICS task.
Synopsis
#include <icctrmeh.hpp>
class
{
protected:
IccTerminal();
public:
AIDVal AID();
unsigned short cursor();
IccTerminalData* data();
void erase();
void freeKeyboard();
unsigned short height(Icc::getopt opt=Icc::object);
unsigned short inputCursor();
static IccTerminal* instance();
unsigned short line();
const char* netName();
IccTerminal& operator<<(Color color);
IccTerminal& operator<<(Highlight highlight);
IccTerminal& operator<<(const IccBuf& buffer);
IccTerminal& operator<<(char ch);
IccTerminal& operator<<(signed char ch);
IccTerminal& operator<<(unsigned char ch);
IccTerminal& operator<<(const char* text);
IccTerminal& operator<<(const signed char* text);
IccTerminal& operator<<(const unsigned char* text);
IccTerminal& operator<<(short num);
IccTerminal& operator<<(unsigned short num);
IccTerminal& operator<<(long num);
IccTerminal& operator<<(unsigned long num);
IccTerminal& operator<<(int num);
IccTerminal& operator<<(float num);
IccTerminal& operator<<(double num);
IccTerminal& operator<<(long double num);
IccTerminal& operator<<(IccTerminal& (*f)(IccTerminal&));
virtual void put(const IccBuf& buf);
155
const IccBuf& receive(Case caseOpt=upper);

const IccBuf& receive3270Data(Case caseOpt=upper);
void send(const IccBuf& buffer);
void send(const char* format,
...);
void send(unsigned short row,
unsigned short col,
const IccBuf& buffer);
unsigned short col,
const char* format,
...);
void send3270(const IccBuf& buffer);
void send3270(const char* format,
...);
void send3270(unsigned short col,
const IccBuf& buf);
const char* format,
...);
void sendLine(const IccBuf& buffer);
void sendLine(const char* format,
...);
void sendLine(unsigned short col,
const IccBuf& buf);
const char* format,
...);
void setColor(Color color=defaultColor);
void setCursor(unsigned short offset);
void setCursor(unsigned short row,
unsigned short col);
void setHighlight(Highlight highlight=normal);
void setLine(unsigned short lineNum=1);
void setNewLine(unsigned short numLines=1);
void setNextCommArea(const IvvBuf& commArea);
void setNextTransId(const IccTransId& transId,
NextTransIdOpt opt=queue);
AIDVal waitForAID();
void waitForAID(AIDVal aid);
unsigned short width(Icc::getOpt opt=Icc::object);
IccBuf& workArea();
type enum {
ENTER,
CLEAR,
PA1 to PA3,
PF1 to PF24,
} AIDVal;
type enum {
upper,
mixed,
} Case;
type enum {
defaultColor,
blue,
red,
pink,
green,
cyan,
yellow,
neutral,
} Color;
type enum {
defaultHighlight,
blink,
reverse,
underscore,
156
} Highlight;
type enum {
queue,
immediate,
} NextTransIdOpt;
};
Description
The IccTerminal class is a singleton class that represents the terminal that belongs
to the CICS task. It can be created only if the transaction has a 3270 terminal as its
principal facility. Otherwise, an exception is thrown.
Class Members
IccTerminal constructor
protected IccTerminal();
IccTerminal::AID
AIDVal AID();
which AID (action identifier) key was last pressed at this terminal.
IccTerminal::clear
This method is synonymous with erase. See Polymorphic behavior on page 10 for
IccTerminal::cursor
unsigned short cursor();
This method returns the current cursor position as an offset from the top left corner
of the screen.
IccTerminal::data
IccTerminalData* data();
This method returns a pointer to an IccTerminalData object that contains

information about the characteristics of the terminal. The object is created if it does
not already exist.
IccTerminal::erase
void erase();
This method erases all the data that is displayed at the terminal.
Equivalent EXEC CICS call: SEND CONTROL ERASE
Conditions: INVREQ
IccTerminal::freeKeyboard
void freeKeyboard();
This method frees the keyboard so that the terminal can accept input.
157
Equivalent EXEC CICS call: SEND CONTROL FREEKB

Conditions: INVREQ
IccTerminal::get
This method is synonymous with receive. See Polymorphic behavior on page 10

for more information about polymorphism.
IccTerminal::height
unsigned short height(Icc::getopt opt=Icc::object);
This method returns how many lines the screen holds.

Equivalent EXEC CICS call: ASSIGN SCRNHT
Conditions: INVREQ
IccTerminal::inputCursor
unsigned short inputCursor();
This method returns the position of the cursor on the screen.

IccTerminal::instance
static IccTerminal* instance();
This method returns a pointer to the singleton IccTerminal object. The object is
created if it does not already exist.
IccTerminal::line
unsigned short line();
This method returns the current line number of the cursor from the top of the
screen.
IccTerminal::netName
const char* netName();
This method returns the eight-byte string that represents the network logical unit
name of the principal facility.
Equivalent EXEC CICS call: ASSIGN NETNAME
IccTerminal::operator<< (1)
IccTerminal& operator<<(Color color);
This method sets the foreground color for data that is subsequently sent to the
terminal.
IccTerminal& operator<<(Highlighthighlight);
This method sets the highlighting that is used for data that is subsequently sent to
the terminal.
158
IccTerminal& operator<<(const IccBuf& buffer);
This method writes another buffer.

IccTerminal& operator<<(char ch);
This method writes a character.

IccTerminal& operator<<(signed char ch);

IccTerminal& operator<<(unsigned char ch);

IccTerminal& operator<<(const char* text);
This method writes a string.

IccTerminal& operator<<(const signed char* text);

IccTerminal& operator<<(const unsigned char* text);

IccTerminal& operator<<(short* num);
This method writes a short.

IccTerminal& operator<<(unsigned short num);
This method writes an unsigned short.

IccTerminal& operator<<(long num);
This method writes a long.

IccTerminal& operator<<(unsigned long* num);
This method writes an unsigned long.

159
IccTerminal& operator<<(int num);
This method writes an integer.

IccTerminal& operator<<(float num);
This method writes a float.

IccTerminal& operator<<(double num);
This method writes a double.

IccTerminal& operator<<(long double num);
This method writes a long double.

IccTerminal& operator<<(IccTerminal& (*f)(IccTerminal&));
This method enables the following syntax:

Term << "Hello World" << endl;
Term << "Hello again" << flush;
IccTerminal::put
virtual void put(const IccBuf& buf);
This method is synonymous with sendLine. See Polymorphic behavior on page

10 for more information about polymorphism.
IccTerminal::receive
const IccBuf& receive(Case caseOpt=upper);
caseOpt
An enumeration, which is defined in this class, that indicates whether text is to
converted to uppercase or allowed to remain as it is.
This method receives data from the terminal.
Equivalent EXEC CICS call: RECEIVE
IccTerminal::receive3270Data
const IccBuf& receive3270Data(Case caseOpt=upper);
caseOpt
An enumeration, which is defined in this class, that indicates whether text is to
converted to uppercase or allowed to remain as it is.
This method receives the 3270 data buffer from the terminal.
Equivalent EXEC CICS call: RECEIVE BUFFER
160
Conditions: INVREQ, LENGERR, TERMERR, NOTALLOC (Open Systems only)

IccTerminal::send (1)
void send(const IccBuf& buffer);
buffer
A reference to an IccBuf object that holds the data that is to be sent.
void send(const char* format,
...);
format
A format string, as in the printf standard library function.
... The optional arguments that accompany format.
unsigned short col,
const IccBuf& buffer);
row
The row in which the writing of the data is started.
col
The column in which the writing of the data is started.
buffer
unsigned short col,
const char* format,
...);
row
The row in which the writing of the data is started.
col
format
This method writes the specified data to either the current cursor position, or to the
cursor position that is specified by the arguments.
Equivalent EXEC CICS call: SEND
IccTerminal::send3270 (1)
void send3270(const IccBuf& buffer);
buffer
161
void send3270(const char* format,

...)
format
const IccBuf& buf);
col
buf
const char* format,
...);
col
format
This method writes the specified data either to the next line of the terminal, or to the
specified column of the current line.
IccTerminal::sendLine (1)
void sendLine(const IccBuf& buffer);
buffer
void sendLine(const char* format,
...);
format
const IccBuf& buf);
col
buf
162

const char* format,
...);
col
format
This method writes the specified data either to the next line of the terminal, or to the
specified column of the current line.
Equivalent EXEC CICS call: SEND
IccTerminal::setColor
void setColor(Color color=defaultColor);
color
An enumeration, which is defined in this class, that indicates the color of the
text that is written to the screen.
This method changes the color of the text that is subsequently sent to the terminal.
IccTerminal::setCursor (1)
void setCursor(unsigned short offset);
offset
The position of the cursor where the top left corner is zero (0).
IccTerminal::setCursor (2)
void setCursor(unsigned short row,
unsigned short col);
row
The row number of the cursor where the top row is 1.
col
The column number of the cursor where the left column is 1.
This method gives two different ways of setting the position of the cursor on the
screen.
Equivalent EXEC CICS call: SEND CONTROL CURSOR
Conditions: INVREQ
IccTerminal::setHighlight
void setHighlight(Highlight highlight=normal);
highlight
An enumeration, which is defined in this class, that indicates the highlighting of
the text that is written to the screen.
This method changes the highlighting of the data that is subsequently sent to the
terminal.
163
IccTerminal::setLine
void setLine(unsigned short lineNum=1);
lineNum
The line number, counting from the top.
This method moves the cursor to the start of line lineNum, where 1 is the top line of
the terminal. The default is to move the cursor to the start of line 1.
Conditions: INVREQ
IccTerminal::setNewLine
void setNewLine(unsigned short numLines=1);
numLines
The number of blank lines.
This method requests that numLines blank lines be sent to the terminal.
Conditions: INVREQ
IccTerminal::setNextCommArea
void setNextCommArea(const IvvBuf& commArea);
commArea
A reference to the buffer that is to be used as a COMMAREA.
This method specifies the COMMAREA that is to be passed to the next transaction
started on this terminal.
IccTerminal::setNextTransId
void setNextTransId(const IccTransId& transId,
NextTransIdOpt opt=queue);
transId
A reference to the IccTransId object that holds the name of a transaction.
opt
An enumeration, which is defined in this class, that indicates whether transId
should be queued or started immediately (that is, should be the very next
transaction) at this terminal.
This method specifies the next transaction that is to be started on this terminal.
IccTerminal::waitForAID (1)
AIDVal waitForAID();
This method waits for any input and returns an enumeration, which is defined in this
class, that indicates which AID key is expected.
IccTerminal::waitForAID (2)
void waitForAID(AIDVal aid);
164
aid
An enumeration, which is defined in this class, that indicates which AID key was
last pressed.
This method waits for the specified AID key to be pressed before returning control.
This method loops, receiving input from the terminal, until the correct AID key is
pressed by the operator.
Equivalent EXEC CICS call: RECEIVE
IccTerminal::width
unsigned short width(Icc::getOpt opt=Icc::object);
This method returns the width of the screen in characters.

Equivalent EXEC CICS call: ASSIGN SCRNWD
Conditions: INVREQ
IccTerminal::workArea
IccBuf& workArea();
This method returns a reference to the IccBuf object that holds the terminal work
area.
Equivalent EXEC CICS call: ADDRESS TCTUA
IccTerminal::AIDVal
type enum {
ENTER,
CLEAR,
PA1 to PA3,
F1 to PF24,
} AIDVal;
IccTerminal::Case
type enum {
upper,
mixed,
} Case;
IccTerminal::Color
type enum {
defaultColor,
blue,
red,
pink,
green,
cyan,
yellow,
neutral,
} Color;
IccTerminal::Highlight
165
type enum {
defaultHighlight,
blink,
reverse,
underscore,
} Highlight;
IccTerminal::NextTransIdOpt
type enum {
queue,
immediate,
} NextTransIdOpt;
queue
Queue the transaction with any other outstanding starts that are queued on the
terminal.
immediate
Start the transaction immediately, that is, before any other outstanding starts
that are queued on the terminal.
Related Information
IccBase class
IccBuf class
IccResource class
IccTerminalData class
IccTransId class
IccTerminalData
Purpose
Contains information about the terminal characteristics.
Synopsis
#include <icctmdeh.hpp>
class
{
protected:
IccTerminalData();
public:
unsigned short graphicCharCodeSet(Icc::GetOpt opt=Icc::object);
unsigned short graphicCharSetId(Icc::GetOpt opt=Icc::object);
Icc::Bool isBTrans(Icc::GetOpt opt=Icc::object);
Icc::Bool isColor(Icc::GetOpt opt=Icc::object);
Icc::Bool isExtended3270(Icc::GetOpt opt=Icc::object);
Icc::Bool isFieldOutline(Icc::GetOpt opt=Icc::object);
Icc::Bool isHighlight(Icc::GetOpt opt=Icc::object);
Icc::Bool isKatakana(Icc::GetOpt opt=Icc::object);
Icc::Bool isMSRControl(Icc::GetOpt opt=Icc::object);
Icc::Bool isPS(Icc::GetOpt opt=Icc::object);
Icc::Bool isSOSI(Icc::GetOpt opt=Icc::object);
Icc::Bool isValidation(Icc::GetOpt opt=Icc::object);
};
166
Description
The IccTerminalData class is a singleton class that is owned by IccTerminal (see
data in IccTerminal class for more information). IccTerminalData contains
information about the terminal characteristics.
Class Members
IccTerminalData constructor
protected IccTerminalData();
IccTerminalData::graphicCharCodeSet
unsigned short graphicCharCodeSet(Icc::GetOpt opt=Icc::object);
This method returns the binary code page global identifier as a value in the range 1
through 65534, or zero (0) for a non-graphics terminal.
Condition: INVREQ
IccTerminalData::graphicCharSetId
unsigned short graphicCharSetId(Icc::GetOpt opt=Icc::object);
This method returns the graphic character set global identifier as a number in the
range 1 through 65534, or zero (0) for a nongraphics terminal.
Conditions: INVREQ
IccTerminalData::isBTrans
Icc::Bool isBTrans(Icc::GetOpt opt=Icc::object);
This method returns a Boolean that indicates whether the terminal has the
background transparency capability.
Equivalent EXEC CICS call: ASSIGN BTRANS
Conditions: INVREQ
IccTerminalData::isColor
Icc::Bool isColor(Icc::GetOpt opt=Icc::object);
This method returns a Boolean that indicates whether the terminal has the extended
color capability.
Equivalent EXEC CICS call: ASSIGN COLOR
Conditions: INVREQ
IccTerminalData::isExtended3270
Icc::Bool isExtended3270(Icc::GetOpt opt=Icc::object);
This method returns a Boolean that indicates whether the terminal supports the
3270 extended data stream.
Equivalent EXEC CICS call: ASSIGN EXTDS
167
Conditions: INVREQ
IccTerminalData::isFieldOutline
Icc::Bool isFieldOutline(Icc::GetOpt opt=Icc::object);
This method returns a Boolean that indicates whether the terminal supports field
outlining.
Equivalent EXEC CICS call: ASSIGN OUTLINE
Conditions: INVREQ
IccTerminalData::isHighlight
Icc::Bool isHighlight(Icc::GetOpt opt=Icc::object);
This method returns a Boolean that indicates whether the terminal has extended
highlight capabilities.
Equivalent EXEC CICS call: ASSIGN HIGHLIGHT
Conditions: INVREQ
IccTerminalData::isKatakana
Icc::Bool isKatakana(Icc::GetOpt opt=Icc::object);
This method returns a Boolean that indicates whether the terminal supports
Katakana.
Equivalent EXEC CICS call: ASSIGN KATAKANA
Conditions: INVREQ
IccTerminalData::isMSRControl
Icc::Bool isMSRControl(Icc::GetOpt opt=Icc::object);
magnetic slot reader (MSR) control.
Equivalent EXEC CICS call: ASSIGN MSRCONTROL
Conditions: INVREQ
IccTerminalData::isPS
Icc::Bool isPS(Icc::GetOpt opt=Icc::object);
programmed symbols.
Equivalent EXEC CICS call: ASSIGN PS
Conditions: INVREQ
IccTerminalData::isSOSI
Icc::Bool isSOSI(Icc::GetOpt opt=Icc::object);
168
This method returns a Boolean that indicates whether the terminal supports mixed
EBCDIC/DBCS fields.
Equivalent EXEC CICS call: ASSIGN SOSI
Conditions: INVREQ
IccTerminalData::isValidation
Icc::Bool isValidation(Icc::GetOpt opt=Icc::object);
validation.
Equivalent EXEC CICS call: ASSIGN VALIDATION
Conditions: INVREQ
Related Information
IccBase class
IccResource class
IccTime
Purpose
Contains time information.
Synopsis
class
{
protected:
IccTime(unsigned long hours=0,
unsigned long minutes=0,
unsigned long seconds=0);
public:
virtual unsigned long timeInHours();
virtual unsigned long timeInMinutes();
virtual unsigned long timeInSeconds();
Type type() const;
type enum {
absTime,
timeInterval,
timeOfDay,
} Type;
};
Description
The IccTime class contains time information and is the base class from which
IccAbsTime, IccTimeInterval, and IccTimeOfDay classes are derived.
169
Class Members
IccTime constructor
protected IccTime(unsigned long hours=0,
hours
The number of hours.
minutes
The number of minutes.
seconds
The number of seconds.
IccTime::hours
This method returns the hours component of time; that is, the value that is specified
in the constructor.
IccTime::minutes
This method returns the minutes component of time; that is the value that is
specified in the constructor.
IccTime::seconds
This method returns the default dateFormat for the CICS region.
Equivalent EXEC CICS call: FORMATTIME DATEFORM
Conditions: ERROR (Open Systems only).
IccTime::timeInHours
virtual unsigned long timeInHours();
This method returns the time in hours.

IccTime::timeInMinutes
virtual unsigned long timeInMinutes();
This method returns the time in minutes.

IccTime::timeInSeconds
virtual unsigned long timeInSeconds();
This method returns the time in seconds.

IccTime::type
Type type() const;
170
what type of subclass of IccTime this is.
IccSystem::Type
type enum {
absTime,
timeInterval,
timeOfDay,
} Type;
absTime
The object is of IccAbsTime class. It is used to represent a current date and
time as the number of milliseconds that have elapsed since the beginning of the
year 1900.
timeInterval
The object is of IccTimeInterval class. It is used to represent a length of time,
such as 5 minutes.
timeOfDay
The object is of IccTimeofDay class. It is used to represent a particular time of
day, such as midnight.
Related Information
IccAbsTime class
IccBase class
IccResource class
IccTimeOfDay class
IccTimeInterval
Purpose
Holds information about a time interval.
Synopsis
class
{
IccTimeInterval(unsigned long hours=0,
IccTimeInterval(const IccTimeInterval& time);
IccTimeInterval& operator=(const IccTimeInterval& timeInterval);
};
Description
The IccTimeInterval class holds information about a time interval.
Class Members
IccTimeInterval constructor (1)
171
IccTimeInterval(unsigned long hours=0,

hours
The initial hours setting. The default is 0 (zero).
minutes
The initial minutes setting. The default is 0 (zero).
seconds
The initial seconds setting. The default is 0 (zero).
IccTimeInterval constructor (2)
IccTimeInterval(const IccTimeInterval& time);

IccTimeInterval::operator=
IccTimeInterval& operator=(const IccTimeInterval& timeInterval);
This method assigns one IccTimeInterval object to another.
Related Information
IccBase class
IccResource class
IccTime class
IccTimeOfDay
Purpose
Holds information about the time of day.
Synopsis
class
{
IccTimeOfDay(unsigned long hours=0,
IccTimeOfDay(const IccTimeOfDay& time);
IccTimeOfDay& operator=(const IccTimeOfDay& TimeOfDay);
void set(unsigned long hours,
unsigned long minutes,
unsigned long seconds);
};
Description
The IccTimeOfDay class holds information about the time of day.
Class Members
IccTimeOfDay constructor (1)
172
IccTimeOfDay(unsigned long hours=0,

hours
The initial hours setting. The default is 0 (zero).
minutes
The initial minutes setting. The default is 0 (zero).
seconds
The initial seconds setting. The default is 0 (zero).
IccTimeOfDay constructor (2)
IccTimeOfDay(const IccTimeOfDay& time);

IccTimeOfDay::operator=
IccTimeOfDay& operator=(const IccTimeOfDay& TimeOfDay);
This method assigns one IccTimeOfDay object to another.

IccTimeOfDay::set
void set(unsigned long hours,
unsigned long minutes,
unsigned long seconds);
hours
The new hours setting.
minutes
The new minutes setting.
seconds
The new seconds setting.
This method changes the time that is held in the IccTimeOfDay object.
Related Information
IccBase class
IccResource class
IccTime class
IccTPNameId
Purpose
Holds a 1- through 64-byte TP partner name.
Synopsis
class
{
IccTPNameId(const char* name);
173
IccTPNameId(const IccTPNameId& id);

IccTPNameId& operator=(const char* name);
IccTPNameId& operator=(const IccTPNameId& id);
};
Description
The IccTPNameId class holds a 1- through 64-byte TP partner name.
Class Members
IccTPNameId constructor (1)
IccTPNameId(const char* name);
name
The 1- through 64-character TP name.
IccTPNameId constructor (2)
IccTPNameId(const IccTPNameId& id);
id
A reference to an IccTPNameId object.

IccTPNameId::operator= (1)
IccTPNameId& operator=(const char* name);
name
The 1- through 64-character TP name.
IccTPNameId::operator= (2)
IccTPNameId& operator=(const IccTPNameId& id);
id
A reference to an IccTPNameId object.
Related Information
IccBase class
IccResource class
IccTransId
Purpose
Identifies a transaction name in the CICS system.
Synopsis
class
{
IccTransId(const char* name);
IccTransId(const IddTransId& id);
IccTransId& operator=(const char* name);
IccTransId& operator=(const IccTransId& id);
};
174
Description
The IccTransId class identifies a transaction name in the CICS system. On AIX,
this is a TD stanza in the permanent resource database.
Class Members
IccTransId constructor (1)
IccTransId(const char* name);
name
The four-character transaction name.
IccTransId constructor (2)
IccTransId(const IddTransId& id);
id

IccTransId::operator= (1)
IccTransId& operator=(const char* name);
name
The four-character transaction name.
IccTransId::operator= (2)
IccTransId& operator=(const IccTransId& id);
id
Related Information
IccBase class
IccResource class
IccUserId
Purpose
Represents an eight-character user name.
Synopsis
class
{
IccUserId(const char* name);
IccUserId(const IddUserId& id);
IccUserId& operator=(const char* name);
IccUserId& operator=(const IccUserId& id);
};
Description
The IccUserId class represents an eight-character user name.
175
Class Members
IccUserId constructor (1)
IccUserId(const char* name);
name
The eight-character name of the user ID.
IccUserId constructor (2)
IccUserId(const IddUserId& id);
id
A reference to an IccUserId object.

IccUserId::operator= (1)
IccUserId& operator=(const char* name);
name
The eight-character name of the user ID.
IccUserId::operator= (2)
IccUserId& operator=(const IccUserId& id);
id
A reference to an IccUserId object.
Related Information
IccBase class
IccResourceId class
IccValue
Purpose
Synopsis
Description
Class Members
Related Information
IccBase class
IccResourceId class
176
Main Function
Purpose
Synopsis
Description
Class Members
Related Information
IccBase class
IccResourceId class
177
178
Appendix A. CICS Foundation Class abend codes

All CICS Foundation Class abend codes are of the form ACLx.
ACL0
Explanation:
The new operator failed to allocate storage while creating an object.
Problem determination:
This occurs if not enough storage is available to the CICS region to satisfy
the request.
System action:
CICS abnormally terminates the transaction.
User response:
This abend can occur if you are in a loop creating objects and not deleting
them. Alternatively CICS might be short of storage. Try resubmitting the
transaction.
ACL1
Explanation:
The CICS Foundation Classes have thrown an exception that the
application programmer failed to catch.
System action:
User response:
Check whether you have coded your application to catch exceptions.
Interrogate the message object that is contained within the exception object
to establish the cause of the exception that is being thrown. Another
possible cause of this abend is that you are running a Foundation Classes
program on a machine that does not have the C++ runtime installed. Check
whether your machine has the C++ runtime installed.
ACL2
Explanation:
The CICS Foundation Classes invoked the default handleEvent method
(defined in class IccResource) in order to handle a CICS condition because
the application programmer did not implement an own handleEvent method.
System action:
User response:
Implement your own handleEvent method or customize your resource
objects so they do not call the handleEvent method for any of the possible
CICS conditions.
ACL3
Explanation:
The CICS Foundation Classes responded to an application programmers
request to abend a CICS task.
System action:
179
User response:
This abend code has two possible causes:
v A resource object was customized to cause a transaction abend if a
particular CICS condition was raised, and this condition was
subsequently raised by CICS.
v The application programmer requested that the CICS Foundation
Classes abend the transaction and use the appropriate return
enumeration from the handleEvent method (see IccResource class).
ACL4
Explanation:
The CICS Foundation Classes detected an internal error.
System action:
User response:
This abend indicates a CICS Foundation Classes internal problem. Contact
your support organization.
ACL5
Explanation:
The CICS Foundation Classes received an error from a CICS storage
request (GETMAIN) that was made in response to a new operator request.
System action:
User response:
This abend can occur if you are in a loop creating objects and not deleting
them. Alternatively CICS might be short of storage. Try resubmitting the
transaction.
ACL6
Explanation:
The CICS Foundation Classes detected an error while processing a storage
release request.
System action:
User response:
This abend can occur if you try to delete an object that does not exist (that
is, it has already been deleted). It might also indicate a CICS memory
management problem, or a storage corruption problem. If the error persists,
contact your support organization.
ACLT
Explanation:
This (Technology) Release of the CICS Foundation Classes cannot be
started because it has expired.
System action:
180
User response:
This abend is issued when an attempt is made to use the CICS Foundation
Classes after a predefined date. Contact IBM Hursley to get the latest copy
of the CICS Foundation Classes.
ACLZ
Explanation:
The CICS Foundation Classes DLL (Dynamic Link Library) was invoked as
an executable program. (MVS only).
System action:
User response:
This CICS Foundation Classes DLL should not be invoked directly, but from
a C++ application program that was written by use of the class library.
Appendix A. CICS Foundation Class abend codes
181
182
Appendix B. Compiling, executing, and debugging

This chapter describes how to compile, execute, and debug a CICS Foundation
Class program. The following are considered in turn:
v Compiling programs
v Executing programs on page 184
v Debugging programs on page 184
Compiling programs
To compile and link a CICS Foundation Class program, you need access to the
following:
v The source of the program that you are compiling. Your C++ program source
code needs #include statements for the Foundation Class headers and the
Foundation Class main() program stub:
v The IBM C++ compiler for your platform.

v The Foundation Classes header files.
v The Foundation Classes dynamic link library (DLL).
Note that, when using the Foundation Classes, you do not need to translate the
EXEC CICS API. Therefore, do not use the CICSTCL program.
The exact commands that you use to compile your program depend on your server
platform:
CICS for AIX

Foundation Class programs are built for CICS as C++ shared libraries. Compile
myfile.cpp as follows:
xlC_r -I/usr/lpp/cics/include -I/usr/lpp/cics/include/icc
-c -o myfile.o myfile.cpp
Then build it into a shared library as follows:

/usr/lpp/xlC/bin/makeC++SharedLib_r
-o myfile.ibmcpp -p O
-n main
-L/usr/lpp/cics/lib
-lcicsicc myfile.o
CICS for Windows

IBM VisualAge C++
Use these two commands for your programs that use the Foundation Classes.
icc /Ti+ /O- /Oi- /Ge- /Gd+ /Gm+ /Mt
/Idrive:\OPT\CICS\include
myfile.cpp drive:\OPT\CICS\lib\cicsfci.lib
copy myfile.dll drive:\var\cics_regions\region\bin\myfile.ibmcpp
Microsoft Visual C++

Use these three commands for your programs that use the Foundation Classes.
183
cl /Z7 /Od /GX /Gz /MD /c

/Idrive:\OPT\CICS\include myfile.cpp
link /debug /DLL /PDB:none myfile.obj
drive:\OPT\CICS\lib\cicsfcm.lib /out:myfile.dll
copy myfile.dll drive:\var\cics_regions\region\bin\myfile.cpp
Executing programs
To run a compiled and linked (that is, executable) Foundation Classes program, you
must do the following:
1. Make the executable program available to CICS. To do this, ensure that the
program is in a suitable directory or load library. Depending on your server, you
might also need to create a CICS program definition (using CICS resource
definition facilities) before you can execute the program.
2. Logon to a CICS terminal.
3. Run the program.
Note: For AIX users, Foundation Classes program executables should have the
.ibmcpp suffix that identifies the file to CICS as a C++ program. Remove this
suffix when entering the program path name into the CICS Program
Definition (PD).
Note: For CICS users on Windows: To identify them as C++ programs to CICS,
Foundation Class program executables should have the .ibmcpp suffix if they
have been built with IBM VisualAge for C++, or the .cpp suffix if that have
been built with Microsoft Visual C++. Omit this suffix when entering the
program path name into the CICS Program Definition (PD).
Debugging programs
Having successfully compiled, linked, and attempted to execute your Foundation
Classes program, you might need to debug it.
Three options are available to help debug a CICS Foundation Classes program:
1. Use a symbolic debugger.
2. Run the Foundation Class Program with tracing active.
3. Run the Foundation Class Program with the CICS Execution Diagnostic Facility.
Symbolic debuggers
A symbolic debugger allows you to step through the source of your CICS
Foundation Classes program. The following symbolic debuggers are available:
CICS for AIX IBM Distributed Debugger (described in the TXSeries for
Multiplatforms Application Programming Guide)
CICS for Windows
v idebug: IBM VisualAge for C++ or
v msdev: Microsoft VisualC++
v IBM Distributed Debugger (described in the TXSeries for Multiplatforms
Application Programming Guide)
184
To debug a CICS Foundation Classes program with a symbolic debugger, you need
to compile the program with a flag that adds debugging information to your
executable:
CICS for AIX -g
CICS for Windows - IBM VisualAge C++ /Ti
CICS for Windows - Microsoft Visual C++
/Z7 and /debug link option (Microsoft Visual C++)
Note: When debugging under msdev, you need to uncomment the following lines in
iccmain.cpp (supplied in drive:\OPT\CICS\include):
#include <windows.h>
DebugBreak();
When you have finished debugging, these lines must be commented out
again for nondebug use. Failure to remove these lines causes an exception
exc_e_SIGTRAP when the program is run.
For more information see:
CICS for AIX
Using CDCN and the IBM Application Debugging Program in the TXSeries for
Multiplatforms Application Programming Guide
CICS for Windows
CICS application debugging with compilers in the TXSeries for Multiplatforms
Application Programming Guide.
Tracing a Foundation Class Program

The CICS Foundation Classes can be configured to write a trace file for
debugging/service purposes.
Warning - Technology Release This facility is not yet integrated properly with the
CICS auxiliary trace facilities on a particular CICS server platform, but this is the
intention over time.
Activating the trace output: CICS for AIX
Create a file: /var/cics_regions/region_name/dumps/dir1/IccTrOn.
Setting the level of trace output:
Depending on your operating system, you have one or two ways to set the trace
level:
1. CICS for AIX users can put an ascii digit in the IccTrOn file that was created
above in Activating the trace outputActivating the trace output This number is
used to set the initial trace level when the program starts executing.
2. The program might set or change the trace level that is using the method
setTraceLevel.
Appendix B. Compiling, executing, and debugging
185
Where the trace output is written: File: /var/cics_regions/region_name/dumps/

dir1/IccTrOut
Execution Diagnostic Facility

For the EXEC CICS API, a CICS facility called the Execution Diagnostic Facility
(EDF) is available that allows you to step through your CICS program, stopping at
each EXEC CICS call. This does not make much sense from the CICS Foundation
Classes because the display screen shows the procedural EXEC CICS call
interface rather than the CICS Foundation Class type interface. However, this might
be of use to programmers who are familiar with the EXEC CICS interface.
Enabling EDF: To enable EDF, use the preprocessor macro ICC_EDF. You can do
this in your source code before including the file iccmain.cpp as follows:
#define ICC_EDF
//switch EDF on
Alternatively, use the -D flag on your compiler.

For more information about using EDF, see Using CEDF in theTXSeries for
Multiplatforms Administration Guide.
186
Appendix C. Mapping Foundation Class methods to EXEC

CICS calls
The tables in this appendix show how the Foundation Class methods relate to the
EXEC CICS application programming interface (API). Each table lists the methods
of a class and the corresponding EXEC CICS calls.
Table 7. EXEC CICS calls for IccAbendData class methods
IccAbendData method
EXEC CICS call
abendCode
ASSIGN ABCODE
ASRAInterrupt
ASSIGN ASRAINTRPT
ASRAKeyType
ASSIGN ASRAKEY
ASRAPSW
ASSIGN ASRAPSW
ASRARegisters
ASSIGN ASRAREGS
ASRASpaceType
ASSIGN ASRASPC
ASRAStorageType
ASSIGN ASRASTG
isDumpAvailable
ASSIGN ABDUMP
originalAbendCode
ASSIGN ORGABCODE
programName
ASSIGN ABPROGRAM
Table 8. EXEC CICS calls for IccAbsTime class methods

IccAbsTime method
EXEC CICS call
date
FORMATTIME YYDDD/YYMMDD/etc.
dayOfMonth
FORMATTIME DAYOFMONTH
dayOfWeek
FORMATTIME DAYOFWEEK
daysSince1900
FORMATTIME DAYCOUNT
monthOfYear
FORMATTIME MONTHOFYEAR
time
FORMATTIME TIME
year
FORMATTIME YEAR
Table 9. EXEC CICS calls for IccClock class methods

IccClock method
EXEC CICS call
cancelAlarm
CANCEL
date
FORMATTIME YYDDD/YYMMDD/etc.
dayOfMonth
FORMATTIME DAYOFMONTH
dayOfWeek
FORMATTIME DAYOFWEEK
daysSince1900
FORMATTIME DAYCOUNT
monthOfYear
FORMATTIME MONTHOFYEAR
setAlarm
POST
time
FORMATTIME TIME
update
ASKTIME
year
FORMATTIME YEAR
187
Table 10. EXEC CICS calls for IccConsole class methods

IccConsole method
EXEC CICS call
write
WRITE OPERATOR
writeAndGetReply
WRITE OPERATOR
Table 11. EXEC CICS calls for IccControl class methods

IccControl method
EXEC CICS call
callingProgramId
ASSIGN INVOKINGPROG
cancelAbendHandler
HANDLE ABEND CANCEL
commArea
ADDRESS COMMAREA
inientryata
ASSIGN INITPARM & INITPARMLEN
programId
ASSIGN PROGRAM
resetAbendHandler
HANDLE ABEND RESET
setAbendHandler
HANDLE ABEND PROGRAM
Table 12. EXEC CICS calls for IccDataQueue class methods

IccDataQueue method
EXEC CICS call
empty
DELETEQ ENTRY
readItem
READQ ENTRY
writeItem
WRITEQ ENTRY
Table 13. EXEC CICS calls for IccFile class methods
188
IccFile method
EXEC CICS call
access
INQUIRE FILE
ADD|BROWSE|DELETE|READ|UPDATE
accessMethod
INQUIRE FILE ACCESSMETHOD
deleteRecord
DELETE FILE RIDFLD
deleteLockedRecord
DELETE FILE
enableStatus
INQUIRE FILE ENABLESTATUS
isAddable
INQUIRE FILE ADD
isBrowsable
INQUIRE FILE BROWSE
isDeletable
INQUIRE FILE DELETE
isEmptyOnOpen
INQUIRE FILE EMPTYSTATUS
isReadable
INQUIRE FILE READ
isRecoverable
INQUIRE FILE RECOVSTATUS
isUpdatable
INQUIRE FILE UPDATE
keyPosition
INQUIRE FILE KEYPOSITION
openStatus
INQUIRE FILE OPENSTATUS
readRecord
READ FILE
recordFormat
INQUIRE FILE RECORDFORMAT
recordLength
INQUIRE FILE RECORDSIZE
rewriteRecord
REWRITE FILE
setAccess
SET FILE ADD BROWSE DELETE etc.
Table 13. EXEC CICS calls for IccFile class methods (continued)
setEmptyOnOpen
SET FILE EMPTYSTATUS
setStatus
SET FILE OPENSTATUS ENABLESTATUS
type
INQUIRE FILE TYPE
unlockRecord
UNLOCK FILE
writeRecord
WRITE FILE
Table 14. EXEC CICS calls for IccFileIterator class methods

IccFileIterator method
EXEC CICS call
IccFileIterator (constructor)
STARTBR FILE
IccFileIterator (destructor)
ENDBR FILE
readNextRecord
READNEXT FILE
readPreviousRecord
READPREV FILE
reset
RESETBR FILE
Table 15. EXEC CICS calls for IccJournal class methods

IccJournal method
EXEC CICS call
wait
WAIT JOURNALNUM
writeRecord
WRITE JOURNALNUM
Table 16. EXEC CICS calls for IccProgram class methods

IccProgram method
EXEC CICS call
link
LINK PROGRAM
load
LOAD PROGRAM
unload
RELEASE PROGRAM
Table 17. EXEC CICS calls for IccResource class methods

IccResource method
EXEC CICS call
condition
(RESP & RESP2)
setRouteOption
(SYSID)
Table 18. EXEC CICS calls for IccSemaphore class methods

IccSemaphore method
EXEC CICS call
lock
ENQ RESOURCE
tryLock
ENQ RESOURCE NOSUSPEND
unlock
DEQ RESOURCE
Table 19. EXEC CICS calls for IccSession class methods

IccSession method
EXEC CICS call
allocate
ALLOCATE
connectProcess
CONNECT PROCESS CONVID
converse
CONVERSE CONVID
extractProcess
EXTRACT PROCESS CONVID

189
Table 19. EXEC CICS calls for IccSession class methods (continued)
flush
WAIT CONVID
free
FREE CONVID
issueAbend
ISSUE ABEND CONVID
issueConfirmation
ISSUE CONFIRMATION CONVID
issueError
ISSUE ERROR CONVID
issuePrepare
ISSUE PREPARE CONVID
issueSignal
ISSUE SIGNAL CONVID
receive
RECEIVE CONVID
send
SEND CONVID
sendInvite
SEND CONVID INVITE
sendLast
SEND CONVID LAST
state
EXTRACT ATTRIBUTES
Table 20. EXEC CICS calls for IccStartRequestQ class methods

IccStartRequestQ method
EXEC CICS call
cancel
CANCEL
retrieveData
RETRIEVE
start
START TRANSID
Table 21. EXEC CICS calls for IccSystem class methods

IccSystem method
EXEC CICS call
applName
ASSIGN APPLID
beginBrowse
INQUIRE (FILE, ENTRYQUEUE, etc) START
dateFormat
FORMATTIME DATEFORM
endBrowse
INQUIRE (FILE, ENTRYQUEUE, etc) END
freeStorage
FREEMAIN
getFile
INQUIRE FILE
getNextFile
INQUIRE FILE NEXT
getStorage
GETMAIN SHARED
operatingSystem
INQUIRE SYSTEM OPSYS
operatingSystemLevel
INQUIRE SYSTEM OPREL
release
INQUIRE SYSTEM RELEASE
releaseText
INQUIRE SYSTEM RELEASE
sysId
ASSIGN SYSID
workArea
ADDRESS CWA
Table 22. EXEC CICS calls for IccTask class methods
190
IccTask method
EXEC CICS call
abend
ABEND
commitUOW
SYNCPOINT
delay
DELAY
Table 22. EXEC CICS calls for IccTask class methods (continued)
dump
DUMP TRANSACTION
enterTrace
ENTER TRACENUM
facilityType
ASSIGN STARTCODE, TERMCODE, PRINSYSID,

FCI
freeStorage
FREEMAIN
isCommandSecurityOn
ASSIGN CMDSEC
isCommitSupported
ASSIGN STARTCODE
isResourceSecurityOn
ASSIGN RESSEC
isRestarted
ASSIGN RESTART
isStarentryataAvailable
ASSIGN STARTCODE
principalSysId
ASSIGN PRINSYSID
priority
ASSIGN TASKPRIORITY
rollBackUOW
SYNCPOINT ROLLBACK
setPrioity
CHANGE TASK PRIORITY
startType
ASSIGN STARTCODE
suspend
SUSPEND
triggerDataQueueId
ASSIGN QNAME
userId
ASSIGN USERID
waitExternal
WAIT EXTERNAL / WAITCICS
waitOnAlarm
WAIT EVENT
workArea
ADDRESS TWA
Table 23. EXEC CICS calls for IccTempStore class methods

IccTempStore method
EXEC CICS call
empty
DELETEQ TS
readItem
READQ TS ITEM
readNextItem
READQ TS NEXT
rewriteItem
WRITEQ TS ITEM REWRITE
writeItem
WRITEQ TS ITEM
Table 24. EXEC CICS calls for IccTerminal class methods

IccTerminal method
EXEC CICS call
erase
SEND CONTROL ERASE
freeKeyboard
SEND CONTROL FREEKB
height
ASSIGN SCRNHT
netName
ASSIGN NETNAME
receive
RECEIVE
receive3270Data
RECEIVE BUFFER
send
SEND
sendLine
SEND
setCursor
SEND CONTROL CURSOR
191
Table 24. EXEC CICS calls for IccTerminal class methods (continued)
setLine
SEND CONTROL CURSOR
setNewLine
SEND CONTROL CURSOR
signoff
SIGNOFF
signon
SIGNON
waitForAID
RECEIVE
width
ASSIGN SCRNWD
workArea
ADDRESS TCTUA
Table 25. EXEC CICS calls for IccTerminalData class methods

IccTerminalData method
EXEC CICS call
alternateHeight
ASSIGN ALTSCRNHT
alternateWidth
ASSIGN ALTSCRNWD
defaultHeight
ASSIGN DEFSCRNHT
defaultWidth
ASSIGN DEFSCRNWD
graphicCharSetId
ASSIGN GCHARS
graphicCharCodeSet
ASSIGN GCODES
isAPLKeyboard
ASSIGN APLKYBD
isAPLText
ASSIGN APLTEXT
isBTrans
ASSIGN BTRANS
isColor
ASSIGN COLOR
isEWA
ASSIGN ESASUPP
isExtended3270
ASSIGN EXENTRYS
isGoodMorning
ASSIGN GMMI
isHighlight
ASSIGN HILIGHT
isKatakana
ASSIGN KATAKANA
isMSRControl
ASSIGN MSRCONTROL
isFieldOutline
ASSIGN OUTLINE
isPS
ASSIGN PS
isSOSI
ASSIGN SOSI
isTextKeyboard
ASSIGN TEXTKYBD
isTextPrint
ASSIGN TEXTPRINT
isValidation
ASSIGN VALIDATION
Table 26. EXEC CICS calls for IccUser class methods
192
IccUser method
EXEC CICS call
changePassword
CHANGE PASSWORD
verifyPassword
VERIFY PASSWORD
Notices
This information was developed for products and services offered in the U.S.A. IBM
may not offer the products, services, or features discussed in this document in other
countries. Consult your local IBM representative for information on the products and
services currently available in your area. Any reference to an IBM product, program,
or service is not intended to state or imply that only that IBM product, program, or
service may be used. Any functionally equivalent product, program, or service that
does not infringe any IBM intellectual property right may be used instead. However,
it is the users responsibility to evaluate and verify the operation of any non-IBM
product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you any
license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
DOCUMENT AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OR CONDITIONS OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express
or implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the document. IBM may make improvements and/or
changes in the product(s) and/or the program(s) described in this publication at any
time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those
Web sites. The materials at those Web sites are not part of the materials for this
IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of
enabling: (i) the exchange of information between independently created programs
193
and other programs (including this one) and (ii) the mutual use of the information
which has been exchanged, should contact:
IBM Corporation
ATTN: Software Licensing
11 Stanwix Street
Pittsburgh, PA 15222
U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available
for it are provided by IBM under terms of the IBM International Program License
Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those
products, their published announcements or other publicly available sources. IBM
has not tested those products and cannot confirm the accuracy of performance,
compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those
products.
All statements regarding IBMs future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples may include
the names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
If you are viewing this information softcopy, the photographs and color illustrations
may not appear.
Trademarks and service marks

The following terms are trademarks or registered trademarks of the IBM Corporation
in the United States, other countries, or both:
Advanced Peer-to-Peer Networking
AS/400
CICS/400
194
AIX
CICS
CICS/6000
CICS/ESA
CICS/MVS
CICS/VSE
CICSPlex
C-ISAM
Database 2
DB2
DB2 Universal Database
GDDM
IBM Registry
IBM
IMS
Informix
Language Environment
MVS
MVS/ESA
OS/390
OS/2
OS/400
RACF
RETAIN
RISC System/6000
RS/6000
SOM
Systems Application Architecture
System/390
TXSeries
TCS
VisualAge
VSE/ESA
VTAM
WebSphere
z/OS
Domino, Lotus, and LotusScript are trademarks or registered trademarks of Lotus

Development Corporation in the United States, other countries, or both.
ActiveX, Microsoft, Visual Basic, Visual C++, Visual J++, Visual Studio, Windows,
Windows NT, and the Windows 95 logo are trademarks or registered trademarks
of Microsoft Corporation in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Acucorp and ACUCOBOL-GT are registered trademarks of Acucorp, Inc. in the
United States, other countries, or both.
Pentium is a trademark of Intel Corporation in the United States, other countries,
or both.
This software contains RSA encryption code.
Other company, product, and service names may be trademarks or service marks
of others.
Notices
195
196
Index
A
exceptions 8
throwing and catching 39
throwing for CICS conditions 44
types of 41
EXEC CICS calls
equivalent Foundation Classes 187
executing programs 184
abend codes 39
abends
for CICS conditions 44
list of codes 179
retrieving information 47
absolute time 48
asynchronous transactions 26
F
B
base class 51, 53, 56, 65, 70, 73, 74, 76, 78, 82, 92,
93, 95, 96, 97, 98, 101, 102, 103, 106, 107, 108, 109,
110, 116, 117, 119, 121, 130, 135, 136, 140, 149, 153,
154, 155, 166, 169, 171, 172, 173, 174, 175, 176, 177
buffers 8, 13
creating 13
manipulating data areas 13
scope of data 16
using with CICS resources 15
files 19
adding records to 21
browsing 22
deleting records from 22
ESDS 19
KSDS 19
reading records 20
RRDS 19
updating records in 22
I
C
CICS Foundation Classes
base classes 1
derived classes 1
equivalent EXEC CICS calls 187
initializing 5
CICS server 5
CICS table equivalents 3
compiling 183
CICS for AIX issues 183
CICS for Windows issues 183
conditions 42
abends 44
handling automatically 43
handling manually 42
throwing exceptions 44
D
data areas
extensibility 13
ownership 13
date 36
debugging 184
diagnostics
retrieving abend information
47
E
EDF 186
ESDS files 19
cannot delete records from
reading records 20
22
IBM VisualAge C++ 183

IccAbendData class 2, 47
constructor 47
IccAbendData::abendCode 47
IccAbendData::instance 47
IccAbsTime class 2, 36, 48
constructor 48
copy constructor 48
IccAbsTime::date 49
IccAbsTime::dayOfMonth 49
IccAbsTime::dayOfWeek 49
IccAbsTime::daysSince1900 49
IccAbsTime::hours 49
IccAbsTime::milliSeconds 49
IccAbsTime::minutes 50
IccAbsTime::monthOfYear 50
IccAbsTime::operator= 50
IccAbsTime::packedDecimal 50
IccAbsTime::seconds 50
IccAbsTime::time 50
IccAbsTime::timeInHours 50
IccAbsTime::timeInMinutes 50
IccAbsTime::timeInSeconds 50
IccAbsTime::year 51
IccAlarmRequestId class 3, 51
constructor 51, 52
IccAlarmRequestId:: setTimerECA 52
IccAlarmRequestId::isExpired 52
IccAlarmRequestId::operator= 52
IccAlarmRequestId::TimerECA 52
IccBase class 1, 53
constructor 54
IccBase::className 54
197
IccBase::classType 54
IccBase::ClassType 55
IccBase::customClassNum 54
IccBase::NameOpt 56
IccBase::operator delete 55
IccBase::operator new 55
IccBase::setClassName 55
IccBase::setCustomClassNum 55
IccBuf class 1, 13, 56
constructor 58
constructors 13
methods and operators 15
references 16
IccBuf::append (1) 59
IccBuf::append (2) 59
IccBuf::assign (1) 59
IccBuf::assign (2) 59
IccBuf::cut 59
IccBuf::dataArea 60
IccBuf::dataAreaLength 60
IccBuf::dataAreaOwner 60
IccBuf::DataAreaOwner 64
IccBuf::dataAreaType 60
IccBuf::DataAreaType 64
IccBuf::dataLength 60
IccBuf::insert 60
IccBuf::isFMHContained 60
IccBuf::operator const char* 61
IccBuf::operator!= 62
IccBuf::operator<< 62, 63
IccBuf::operator+= 61
IccBuf::operator= 61
IccBuf::operator== 61
IccBuf::overlay 63
IccBuf::replace 63
IccBuf::setDataLength 64
IccBuf::setFMHContained 64
IccClock class 2, 36
constructor 66
IccClock::absTime 66
IccClock::cancelAlarm 66
IccClock::date 66
IccClock::DateFormat 68
IccClock::dayOfMonth 67
IccClock::dayOfWeek 67
IccClock::DayOfWeek 68
IccClock::daysSince1900 67
IccClock::milliSeconds 67
IccClock::MonthOfYear 67, 69
IccClock::setAlarm 67
IccClock::time 68
IccClock::update 68
IccClock::UpdateMode 69
IccClock::year 68
IccConsole class 2
IccControl class 2
constructor 70
IccControl::cancelAbendHandler 71
198
IccControl::commArea 71
IccControl::instance 71
IccControl::isCreated 71
IccControl::resetAbendHandler 71
IccControl::run 71
IccControl::session 71
IccControl::setAbendHandler (1) 71
IccControl::setAbendHandler (2) 72
IccControl::startRequestQ 72
IccControl::system 72
IccControl::task 72
IccControl::terminal 72
IccConvId class 3
constructor 73
IccConvId::operator= 73
IccDataQueue class 2, 30
constructor 74
deleting transient data queues 31
reading transient data 31
writing transient data 31
IccDataQueue::clear 74
IccDataQueue::empty 74
IccDataQueue::get 74
IccDataQueue::put 75
IccDataQueue::readItem 75
IccDataQueue::writeItem 75
IccDataQueueId class 3, 30
constructor 76
IccDataQueueId::operator= 76
IccEvent class 1
constructor 77
IccEvent::classNames 77
IccEvent::classType 77
IccEvent::condition 77
IccEvent::conditionText 77
IccEvent::methodName 78
IccEvent::summary 78, 80
IccException class 1
constructor 79
IccException::classNames 79
IccException::classType 79
IccException::message 79
IccException::methodName 80
IccException::number 80
IccException::type 80
IccException::Type 80
IccException::typeText 80
IccFile class 2
adding records 21
constructor 83
deleting records 22
reading records 20
updating records 22
IccFile::access 83
IccFile::Access 90
IccFile::accessMethod 83
IccFile::deleteLockedRecord 84
IccFile::deleteRecord 84
IccFile::enableStatus 84
IccFile::isAddable 85
IccFile::isBrowsable 85
IccFile::isDeletable 85
IccFile::isEmptyOnOpen 85
IccFile::isReadable 86
IccFile::isRecoverable 86
IccFile::isUpdatable 86
IccFile::keyLength 86
IccFile::keyPosition 86
IccFile::LockAction 91
IccFile::openStatus 87
IccFile::ReadMode 91
IccFile::readRecord 87
IccFile::recordFormat 87
IccFile::recordIndex 88
IccFile::recordLength 88
IccFile::registerRecordIndex 88
IccFile::rewriteRecord 88
IccFile::SearchCriterion 92
IccFile::setAccess 89
IccFile::setActionOnLocked Record 89
IccFile::setStatus 89
IccFile::Status 92
IccFile::type 89
IccFile::unlockRecord 90
IccFile::writeRecord 90
IccFileId
constructor 93
IccFileId class 3
constructor 93
IccFileId::operator= 93, 96
IccFileIterator class 2
browsing records 22
constructor 94
IccFileIterator::readNextRecord 94
IccFileIterator::readPrevious Record 94
IccFileIterator::reset 95
IccGroupId
constructor 96
IccGroupId class 3
constructor 96
IccGroupId::operator= 96
IccJournal class 2
IccJournalId
constructor 97
IccJournalId class 3
constructor 97
IccJournalId::number 97
IccJournalId::operator= 97
IccJournalTypeId
constructor 98
IccJournalTypeId class 3
constructor 98
IccJournalTypeId::operator= 98
IccKey
constructor 99
IccKey class 4
adding records 21
constructor 99
IccKey class (continued)

reading records 20
IccKey::assign 99
IccKey::completeLength 99
IccKey::kind 99
IccKey::Kind 100
IccKey::operator!= 100
IccKey::operator= 99, 100
IccKey::operator== 100
IccKey::setKind 100
IccKey::value 100
IccLockId
constructor 101
IccLockId class 3
constructor 101
IccLockId::operator= 101
iccmain.cpp file 5
IccMessage class 1
constructor 102
IccMessage::className 102
IccMessage::methodName 102
IccMessage::number 103
IccMessage::summary 103
IccMessage::text 103
IccPartnerId class 3
IccProgram class 2, 24
constructor 104
IccProgram::address 104
IccProgram::CommitOpt 105
IccProgram::entryPoint 104
IccProgram::link 104
IccProgram::load 104
IccProgram::LoadOpt 105
IccProgram::unload 105
IccProgramId class 3
constructor 106
IccProgramId::operator= 106
IccRBA class 4
adding records 21
constructor 107
reading records 20
IccRBA::number 108
IccRBA::operator!= 107
IccRBA::operator= 107
IccRBA::operator== 107
IccRecordindex class
derived classes 4
IccRecordIndex class 1
constructor 108
IccRecordIndex::length 108
IccRecordIndex::type 108
IccRecordIndex::Type 109
IccRequestId class 3
constructor 109, 110
IccRequestId::operator= 110
IccResource class 1, 65, 70, 73, 74, 76, 82
constructor 111
derived classes 2
polymorphism 10
Index
199
IccResource class (continued)

using buffers with 15
virtual methods 10
IccResource::actionOnCondition 111
IccResource::ActionOnCondition 115
IccResource::actionOnCondition AsChar 111
IccResource::clear 112
IccResource::condition 112
IccResource::conditionText 112
IccResource::ConditionType 115
IccResource::get 112
IccResource::handleEvent 112
IccResource::HandleEvent ReturnOpt 115
IccResource::id 112
IccResource::isEDFOn 113
IccResource::isRouteOptionOn 113
IccResource::name 113
IccResource::put 113
IccResource::routeOption 113
IccResource::setActionOn Condition 113
IccResource::setActionOnAny Condition 113
IccResource::setActionsOn Conditions 114
IccResource::setEDF 114
IccResource::setRouteOption 114
IccResourceId class
AIX stanza equivalents 3
CICS table equivalents 3
constructor 116
derived classes 3
IccResourceID class 1
IccResourceId::name 117
IccResourceId::nameLength 117
IccResourceId::operator= 117
IccRRN class 4
adding records 21
constructor 118
reading records 20
IccRRN::number 118
IccRRN::operator!= 118
IccRRN::operator= 118
IccRRN::operator== 118
IccSemaphore class 2
constructor 119
IccSemaphore::lifeTime 120
IccSemaphore::LifeTime 120
IccSemaphore::lock 120
IccSemaphore::LockType 120
IccSemaphore::tryLock 120
IccSemaphore::type 120
IccSemaphore::unlock 120
IccSession class 2
constructor 122
IccSession::allocate 122
IccSession::AllocateOpt 128
IccSession::connectProcess 122, 123
IccSession::converse 123
IccSession::convId 123
IccSession::errorCode 124
IccSession::extractProcess 124
200
IccSession::flush 124
IccSession::free 124
IccSession::get 124
IccSession::isErrorSet 124
IccSession::isNoDataSet 124
IccSession::isSignalSet 125
IccSession::issueAbend 125
IccSession::issueConfirmation 125
IccSession::issueError 125
IccSession::issueSignal 125
IccSession::PIPList 125
IccSession::process 125
IccSession::put 126
IccSession::receive 126
IccSession::send 126
IccSession::sendInvite 126, 127
IccSession::sendLast 127
IccSession::SendOpt 128
IccSession::state 127
IccSession::StateOpt 129
IccSession::stateText 128
IccSession::syncLevel 128
IccSession::SyncLevel 129
IccStartRequestQ ::instance 131
IccStartRequestQ class 2
accessing start data 26
canceling unexpired start requests 27
constructor 131
starting transactions 26
IccStartRequestQ::cancel 131
IccStartRequestQ::CheckOpt 134
IccStartRequestQ::data 131
IccStartRequestQ::ProtectOpt 134
IccStartRequestQ::queueName 131
IccStartRequestQ::registerData 131
IccStartRequestQ::reset 132
IccStartRequestQ::retrieveData 132
IccStartRequestQ::RetrieveOpt 134
IccStartRequestQ::returnTermId 132
IccStartRequestQ::returnTransId 132
IccStartRequestQ::setData 132
IccStartRequestQ::setQueue Name 132
IccStartRequestQ::setReturn TermId 133
IccStartRequestQ::setReturn TransId 133
IccStartRequestQ::setStartOpts 133
IccStartRequestQ::setTermId 133
IccStartRequestQ::start 134
IccSysId class 3
constructor 135
IccSysId::operator= 135
IccSystem class 2
constructor 137
IccSystem::applName 137
IccSystem::beginBrowse 137
IccSystem::dateFormat 137
IccSystem::endBrowse 137
IccSystem::freeStorage 137
IccSystem::getFile 137, 138
IccSystem::getNextFile 138
IccSystem::getStorage 138
IccSystem::instance 138
IccSystem::location 152
IccSystem::NoSpaceOpt 153
IccSystem::operatingSystem 138
IccSystem::operatingSystemLevel 139
IccSystem::release 139
IccSystem::releaseText 139
IccSystem::ResourceType 140
IccSystem::rewriteItem 151
IccSystem::sysId 139
IccSystem::Type 171
IccSystem::workArea 139
IccSystem::writeItem 152
IccTask class 2
constructor 142
IccTask::abend 142
IccTask::abendData 142
IccTask::AbendDumpOpt 147
IccTask::AbendHandlerOpt 147
IccTask::commitUOW 142
IccTask::delay 142
IccTask::dump 143
IccTask::DumpOpts 147
IccTask::enterTrace 143
IccTask::facilityType 143
IccTask::FacilityType 147
IccTask::freeStorage 144
IccTask::getStorage 144
IccTask::instance 144
IccTask::isCommitSupported 144
IccTask::isRestarted 144
IccTask::isStartDataAvailable 145
IccTask::number 145
IccTask::principalSysId 145
IccTask::rollBackUOW 145
IccTask::setDumpOpts 145
IccTask::setWaitText 146
IccTask::startType 146
IccTask::StartType 148
IccTask::suspend 146
IccTask::transId 146
IccTask::triggerDataQueueId 146
IccTask::userId 146
IccTask::WaitPurgeability 148
IccTask::workArea 147
IccTempStore class 2, 32
constructor 150
deleting items 32
reading items 32
updating items 32
writing items 32
IccTempStore::clear 150
IccTempStore::empty 150
IccTempStore::get 151
IccTempStore::numberOfItems 151
IccTempStore::put 151
IccTempStore::readItem 151
IccTempStore::readNextItem 151
IccTempStoreId class 3, 32
constructor 153
IccTempStoreId::operator= 154
IccTermId class 3, 34
constructor 154
IccTermId::operator= 154, 155
IccTerminal class 2, 34
characteristics and current state of a terminal
constructor 157
receiving data 34
sending data 34
IccTerminal::AID 157
IccTerminal::AIDVal 165
IccTerminal::Case 165
IccTerminal::clear 157
IccTerminal::Color 165
IccTerminal::cursor 157
IccTerminal::data 157
IccTerminal::erase 157
IccTerminal::freeKeyboard 157
IccTerminal::get 158
IccTerminal::height 158
IccTerminal::Highlight 165
IccTerminal::inputCursor 158
IccTerminal::instance 158
IccTerminal::line 158
IccTerminal::netName 158
IccTerminal::NextTransIdOpt 166
IccTerminal::operator<< 158, 159, 160
IccTerminal::put 160
IccTerminal::receive 160
IccTerminal::receive3270Data 160
IccTerminal::send 161
IccTerminal::send3270 161, 162
IccTerminal::sendLine 162
IccTerminal::setColor 163
IccTerminal::setCursor 163
IccTerminal::setHighlight 163
IccTerminal::setLine 163
IccTerminal::setNewLine 164
IccTerminal::setNextCommArea 164
IccTerminal::setNextTransId 164
IccTerminal::waitForAID 164
IccTerminal::width 165
IccTerminal::workArea 165
IccTerminalData class 2, 34
characteristics and current state of a terminal
constructor 167
IccTerminalData::graphicCharCodeSet 167
IccTerminalData::graphicCharSetId 167
IccTerminalData::isBTrans 167
IccTerminalData::isColor 167
IccTerminalData::isExtended3270 167
IccTerminalData::isFieldOutline 168
IccTerminalData::isHighlight 168
IccTerminalData::isKatakana 168
IccTerminalData::isMSRControl 168
IccTerminalData::isPS 168
IccTerminalData::isSOSI 168
Index
34
34
201
IccTerminalData::isValidation 169
IccTime class 2
constructor 170
IccTime::hours 170
IccTime::minutes 170
IccTime::seconds 170
IccTime::timeInHours 170
IccTime::timeInMinutes 170
IccTime::timeInSeconds 170
IccTime::type 170
IccTimeInterval class 2
IccTimeInterval::operator= 172
IccTimeOfDay class 2
IccTimeOfDay::operator= 173
IccTimeOfDay::set 173
IccTPNameId class 4
constructor 174
IccTPNameId::operator= 174
IccTransId class 4
constructor 175
IccTransId::operator= 175
IccUser class 2
IccUserId class 4
constructor 176
IccUserId::operator= 176
initialization 5
platform differences 44
storage allocation parameters 9
K
key 20
complete 21
KSDS files 19
reading records 20
M
main function 5
memory management 9
message class 102
messages 8
Microsoft Visual C++ 183
P
parameter passing 10
platform differences 44
polymorphism 10
program control 24
programs 24
202
R
record index classes 4
recordindex class 98, 117
Recordindex class 107
records
adding 21
browsing 22
deleting normal and locked 22
normal vs. locked 22
reading 20
updating 22
relative byte address 20
relative record number 20
resource class 92, 93, 95, 96, 97, 119, 121, 130, 136,
140, 149, 155, 166, 169, 171, 172, 173, 174
Resource class 103
resource classes 2
creating objects 6
singleton classes 7
resource identification classes 3
resource objects
calling methods on 7
creating 6
handling conditions 42
resourceid class 101, 109, 135, 153, 154, 175, 176,
177
Resourceid class 106
RRDS files 19
reading records 20
S
singleton classes 7
start data 26
storage operators 9
structure 70
support classes 8
symbolic debuggers 184
T
temporary storage 32
deleting items in 32
reading items from 32
updating items in 32
writing items to 32
terminals 34
finding characteristics and state of
receiving data from 34
sending data to 34
time 36, 48
absolute 8
delays 8
time of day 8
time class 171, 172
tracing 185
transactions 26
accessing start data 26
34
transactions (continued)
canceling unexpired start requests
starting 26
transient data 30
deleting 31
reading 31
writing 31
27
Index
203
204
SC34-6633-02

Spine information:
C++ Foundation Classes Programming Guide

and Reference
Version 6.2
SC34-6633-02

TXSeries For Multiplatforms C++ Foundation Classes Programming Guide and Reference Version 6.2

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

TXSeries For Multiplatforms C++ Foundation Classes Programming Guide and Reference Version 6.2

Caricato da

Copyright:

Formati disponibili

TXSeries for Multiplatforms

C++ Foundation Classes Programming

TXSeries for Multiplatforms

C++ Foundation Classes Programming

Third Edition (January 2008)

Chapter 1. What are the CICS

Chapter 2. Writing an object-oriented CICS server .

Chapter 3. Buffer objects . . . . . . . .

Example of starting transactions . . . . . .

Classes Reference Pages .

Chapter 5. Conditions, errors, and exceptions

Appendix A. CICS Foundation Class abend codes . . . . . . . . . . 179

Appendix C. Mapping Foundation Class methods to EXEC CICS calls

example: main function . . . . . . . . . . . . . . . . . . .

Copyright IBM Corp. 2001, 2008

Conventions that are used in this book . . . . . . . . . . . . . . . . . . . . . . . xi

Copyright IBM Corp. 2001, 2008

About this book

Who should read this book

Conventions used in this book

Indicates values that you must use literally, such as commands,

Indicates text that you must enter at a command prompt. Monospace

Copyright IBM Corp. 2001, 2008

Table 1. Conventions that are used in this book (continued)

Encloses the names of keys on the keyboard.

Where x is the name of a key, indicates a control-character

Represents the UNIX command-shell prompt for a command that

Represents the UNIX command-shell prompt for a command that

Represents the Windows command prompt.

When used to describe a menu, shows a series of menu selections.

When instructed to enter or issue a command, type the command

Encloses optional items in syntax descriptions.

Encloses lists from which you must choose an item in syntax

Separates items in a list of choices enclosed in { } (braces) in syntax

Ellipses in syntax descriptions indicate that you can repeat the

In function descriptions, indicates parameters whose values are used

In function descriptions, indicates parameters whose values are used

In function descriptions, indicates parameters whose values are

Refers collectively to the CICS product for all supported UNIX

Table 1. Conventions that are used in this book (continued)

How to send your comments

About this book

Chapter 1. What are the CICS Foundation Classes?

Base and derived classes

Task abend data

CICS time and date services

Control of executing program

Transient data queue

Browsing (iterating) files

User or system journal

Outside executing program

Locking services (semaphore)

Start request queue; asynchronous

Temporary storage queue

Terminal belonging to current task

Attributes of terminal objects

Base class for time services. Its derived

User security attributes

Resource identification classes

CICS table name

AIX stanza class

Chapter 1. What are the CICS Foundation Classes?

Table 3. Classes derived from IccResourceId (continued)