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

��

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

Who should read this book . . . . . . . . . . . . . . . . . . . . . xi

Document organization . . . . . . . . . . . . . . . . . . . . . . xi

Related information . . . . . . . . . . . . . . . . . . . . . . . xi

Conventions used in this book . . . . . . . . . . . . . . . . . . . xi

How to send your comments . . . . . . . . . . . . . . . . . . . . xiii

Chapter 1. What are the CICS Foundation Classes? . . . . . . . . . . 1

Base and derived classes . . . . . . . . . . . . . . . . . . . . . 1

Resource classes . . . . . . . . . . . . . . . . . . . . . . . . 2

Resource identification classes . . . . . . . . . . . . . . . . . . . 3

Record index classes . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 2. Writing an object-oriented CICS server . . . . . . . . . . . 5

Including the main function . . . . . . . . . . . . . . . . . . . . . 5

Using CICS resources . . . . . . . . . . . . . . . . . . . . . . . 6

Creating a resource object . . . . . . . . . . . . . . . . . . . . 6

Singleton classes . . . . . . . . . . . . . . . . . . . . . . . 7

Calling methods on a resource object . . . . . . . . . . . . . . . . 7

Support Classes . . . . . . . . . . . . . . . . . . . . . . . . . 8

Memory management . . . . . . . . . . . . . . . . . . . . . . . 9

Parameter passing conventions . . . . . . . . . . . . . . . . . . . 10

Polymorphic behavior . . . . . . . . . . . . . . . . . . . . . . 10

Polymorphism in the IccResource class . . . . . . . . . . . . . . . 10

Example of polymorphic behavior . . . . . . . . . . . . . . . . . 11

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

Data area manipulation . . . . . . . . . . . . . . . . . . . . . . 13

Data area ownership . . . . . . . . . . . . . . . . . . . . . . 13

Data area extensibility . . . . . . . . . . . . . . . . . . . . . 13

IccBuf constructors . . . . . . . . . . . . . . . . . . . . . . . 13

IccBuf methods and operators . . . . . . . . . . . . . . . . . . . 15

Using buffer objects with IccResource classes . . . . . . . . . . . . . 15

Scope of data in IccBuf references returned from read methods . . . . . . . 16

Chapter 4. Using CICS Services . . . . . . . . . . . . . . . . . . 19

APPC and DTP . . . . . . . . . . . . . . . . . . . . . . . . . 19

File control . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Reading records . . . . . . . . . . . . . . . . . . . . . . . 20

Writing new records . . . . . . . . . . . . . . . . . . . . . . 21

Updating existing records . . . . . . . . . . . . . . . . . . . . 22

Deleting records . . . . . . . . . . . . . . . . . . . . . . . 22

Browsing records . . . . . . . . . . . . . . . . . . . . . . . 22

Example of file control . . . . . . . . . . . . . . . . . . . . . 23

Program control . . . . . . . . . . . . . . . . . . . . . . . . 24

Starting transactions asynchronously . . . . . . . . . . . . . . . . . 26

Starting transactions . . . . . . . . . . . . . . . . . . . . . . 26

Accessing start data . . . . . . . . . . . . . . . . . . . . . . 26

Canceling unexpired start requests . . . . . . . . . . . . . . . . 27

© Copyright IBM Corp. 2001, 2008 iii

Example of starting transactions . . . . . . . . . . . . . . . . . 27

Transient data . . . . . . . . . . . . . . . . . . . . . . . . . 30

Reading transient data . . . . . . . . . . . . . . . . . . . . . 31

Writing transient data . . . . . . . . . . . . . . . . . . . . . 31

Deleting transient data queues . . . . . . . . . . . . . . . . . . 31

Example of managing transient data . . . . . . . . . . . . . . . . 31

Temporary storage . . . . . . . . . . . . . . . . . . . . . . . 32

Reading items from temporary storage queues . . . . . . . . . . . . 32

Writing items to temporary storage queues . . . . . . . . . . . . . 32

Updating items . . . . . . . . . . . . . . . . . . . . . . . . 32

Deleting items . . . . . . . . . . . . . . . . . . . . . . . . 32

Example of using temporary storage . . . . . . . . . . . . . . . . 33

Terminal control . . . . . . . . . . . . . . . . . . . . . . . . 34

Sending data to a terminal . . . . . . . . . . . . . . . . . . . 34

Receiving data from a terminal . . . . . . . . . . . . . . . . . . 34

Finding the characteristics and current state of a terminal . . . . . . . . 34

Example of terminal control . . . . . . . . . . . . . . . . . . . 35

Time and date services . . . . . . . . . . . . . . . . . . . . . . 36

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

Foundation Class Abend codes . . . . . . . . . . . . . . . . . . . 39

C++ Exceptions and the Foundation Classes . . . . . . . . . . . . . . 39

CICS conditions . . . . . . . . . . . . . . . . . . . . . . . . 42

Manual condition handling (noAction) . . . . . . . . . . . . . . . . 42

Automatic condition handling (callHandleEvent) . . . . . . . . . . . . 43

Exception handling (throwException) . . . . . . . . . . . . . . . . 44

Severe error handling (abendTask) . . . . . . . . . . . . . . . . 44

Platform differences . . . . . . . . . . . . . . . . . . . . . . . 44

Object level . . . . . . . . . . . . . . . . . . . . . . . . . 45

Method level . . . . . . . . . . . . . . . . . . . . . . . . . 45

Parameter level . . . . . . . . . . . . . . . . . . . . . . . . 45

Chapter 6. CICS Foundation Classes Reference Pages . . . . . . . . . 47

IccAbendData . . . . . . . . . . . . . . . . . . . . . . . . . 47

IccAbsTime . . . . . . . . . . . . . . . . . . . . . . . . . . 48

IccAlarmRequestId . . . . . . . . . . . . . . . . . . . . . . . 51

IccBase . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

IccBuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

IccClock . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

IccCondition structure . . . . . . . . . . . . . . . . . . . . . . 70

IccControl . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

IccConvId . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

IccDataQueue . . . . . . . . . . . . . . . . . . . . . . . . . 74

IccDataQueueId . . . . . . . . . . . . . . . . . . . . . . . . 76

IccEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

IccException . . . . . . . . . . . . . . . . . . . . . . . . . . 78

IccFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

IccFileId . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

IccFileIterator . . . . . . . . . . . . . . . . . . . . . . . . . 93

IccGroupId . . . . . . . . . . . . . . . . . . . . . . . . . . 95

IccJournalId . . . . . . . . . . . . . . . . . . . . . . . . . . 96

IccJournalTypeId . . . . . . . . . . . . . . . . . . . . . . . . 97

IccKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

IccLockId . . . . . . . . . . . . . . . . . . . . . . . . . . 101

IccMessage . . . . . . . . . . . . . . . . . . . . . . . . . 102

IccProgram . . . . . . . . . . . . . . . . . . . . . . . . . . 103

iv TXSeries for Multiplatforms: C++ Foundation Classes Programming Guide and Reference

IccProgramId . . . . . . . . . . . . . . . . . . . . . . . . . 106

IccRBA . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

IccRecordIndex . . . . . . . . . . . . . . . . . . . . . . . . 108

IccRequestId . . . . . . . . . . . . . . . . . . . . . . . . . 109

IccResource . . . . . . . . . . . . . . . . . . . . . . . . . 110

IccResourceId . . . . . . . . . . . . . . . . . . . . . . . . . 116

IccRRN . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

IccSemaphore . . . . . . . . . . . . . . . . . . . . . . . . . 119

IccSession . . . . . . . . . . . . . . . . . . . . . . . . . . 121

IccStartRequestQ . . . . . . . . . . . . . . . . . . . . . . . 130

IccSysId . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

IccSystem . . . . . . . . . . . . . . . . . . . . . . . . . . 136

IccTask . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

IccTempStore . . . . . . . . . . . . . . . . . . . . . . . . . 149

IccTempStoreId . . . . . . . . . . . . . . . . . . . . . . . . 153

IccTermId . . . . . . . . . . . . . . . . . . . . . . . . . . 154

IccTerminal . . . . . . . . . . . . . . . . . . . . . . . . . . 155

IccTerminalData . . . . . . . . . . . . . . . . . . . . . . . . 166

IccTime . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

IccTimeInterval . . . . . . . . . . . . . . . . . . . . . . . . 171

IccTimeOfDay . . . . . . . . . . . . . . . . . . . . . . . . . 172

IccTPNameId . . . . . . . . . . . . . . . . . . . . . . . . . 173

IccTransId . . . . . . . . . . . . . . . . . . . . . . . . . . 174

IccUserId . . . . . . . . . . . . . . . . . . . . . . . . . . 175

IccValue . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Main Function . . . . . . . . . . . . . . . . . . . . . . . . . 177

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

Appendix B. Compiling, executing, and debugging . . . . . . . . . . 183

Compiling programs . . . . . . . . . . . . . . . . . . . . . . 183

CICS for AIX . . . . . . . . . . . . . . . . . . . . . . . . 183

CICS for Windows . . . . . . . . . . . . . . . . . . . . . . 183

Executing programs . . . . . . . . . . . . . . . . . . . . . 184

Debugging programs . . . . . . . . . . . . . . . . . . . . . 184

Appendix C. Mapping Foundation Class methods to EXEC CICS calls 187

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Trademarks and service marks . . . . . . . . . . . . . . . . . . 194

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Contents v

vi TXSeries for Multiplatforms: C++ Foundation Classes Programming Guide and Reference

Figures

1. Code example: main function . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2. Code example: Memory management . . . . . . . . . . . . . . . . . . . . . . . 9

3. Code example: Signature of IccStartRequestQ::start method . . . . . . . . . . . . . . . 10

4. Code example: Passing parameters . . . . . . . . . . . . . . . . . . . . . . . . 10

5. Code example: Defining virtual clear, get, and put methods in the IccResource class . . . . . . 10

6. Code example: Polymorphic behavior . . . . . . . . . . . . . . . . . . . . . . . 12

7. Code example: Using an external data area . . . . . . . . . . . . . . . . . . . . . 14

8. Code example: Using the copy constructor . . . . . . . . . . . . . . . . . . . . . 14

9. Code example: Using a buffer with a temporary storage queue . . . . . . . . . . . . . . 15

10. Code example: Using a buffer with a transient data queue . . . . . . . . . . . . . . . 16

11. Code example: Copying returned data to a local buffer object . . . . . . . . . . . . . . 16

12. Code example: Maintaining a reference to a buffer object . . . . . . . . . . . . . . . . 16

13. Code example: File control . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

14. Code example: Program control (ICCPRG1) . . . . . . . . . . . . . . . . . . . . . 25



17. Code example: Starting transactions (ISR1) . . . . . . . . . . . . . . . . . . . . . 28

18. Code example: Starting transactions (ISR2) . . . . . . . . . . . . . . . . . . . . . 29

19. Code example: Managing transient data . . . . . . . . . . . . . . . . . . . . . . 31

20. Code example: Managing temporary storage queues . . . . . . . . . . . . . . . . . 33

21. Code example: Controlling CICS terminals . . . . . . . . . . . . . . . . . . . . . 35

22. Code example: Using CICS time and date services . . . . . . . . . . . . . . . . . . 37

23. Code example: Throwing and catching exceptions . . . . . . . . . . . . . . . . . . 40

24. Code example: Output from exception handling example . . . . . . . . . . . . . . . . 41

25. Code example: Throwing an invalidArgument exception . . . . . . . . . . . . . . . . 41

26. Code example: Manual condition handling . . . . . . . . . . . . . . . . . . . . . 43

27. Code example: Automatic condition handling . . . . . . . . . . . . . . . . . . . . 43

28. Code example: Condition exception handling . . . . . . . . . . . . . . . . . . . . 44

29. Code example: Severe error handling . . . . . . . . . . . . . . . . . . . . . . . 44

30. Code example: Method level enforcement . . . . . . . . . . . . . . . . . . . . . 45

31. Code example: Parameter level enforcement . . . . . . . . . . . . . . . . . . . . 46

© Copyright IBM Corp. 2001, 2008 vii

viii TXSeries for Multiplatforms: C++ Foundation Classes Programming Guide and Reference

Tables

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

2. Classes derived from IccResource . . . . . . . . . . . . . . . . . . . . . . . . . 2

3. Classes derived from IccResourceId . . . . . . . . . . . . . . . . . . . . . . . . 3

4. Classes derived from IccRecordIndex . . . . . . . . . . . . . . . . . . . . . . . . 4

5. Implementation of get, clear, and put methods in IccResource subclasses . . . . . . . . . . 10

6. Example of starting transactions . . . . . . . . . . . . . . . . . . . . . . . . . 27

7. EXEC CICS calls for IccAbendData class methods . . . . . . . . . . . . . . . . . . 187

8. EXEC CICS calls for IccAbsTime class methods . . . . . . . . . . . . . . . . . . . 187

9. EXEC CICS calls for IccClock class methods . . . . . . . . . . . . . . . . . . . . 187

10. EXEC CICS calls for IccConsole class methods . . . . . . . . . . . . . . . . . . . 188

11. EXEC CICS calls for IccControl class methods . . . . . . . . . . . . . . . . . . . 188

12. EXEC CICS calls for IccDataQueue class methods . . . . . . . . . . . . . . . . . . 188

13. EXEC CICS calls for IccFile class methods . . . . . . . . . . . . . . . . . . . . . 188

14. EXEC CICS calls for IccFileIterator class methods . . . . . . . . . . . . . . . . . . 189

15. EXEC CICS calls for IccJournal class methods . . . . . . . . . . . . . . . . . . . 189

16. EXEC CICS calls for IccProgram class methods . . . . . . . . . . . . . . . . . . . 189

17. EXEC CICS calls for IccResource class methods . . . . . . . . . . . . . . . . . . 189

18. EXEC CICS calls for IccSemaphore class methods . . . . . . . . . . . . . . . . . . 189

19. EXEC CICS calls for IccSession class methods . . . . . . . . . . . . . . . . . . . 189

20. EXEC CICS calls for IccStartRequestQ class methods . . . . . . . . . . . . . . . . 190

21. EXEC CICS calls for IccSystem class methods . . . . . . . . . . . . . . . . . . . 190

22. EXEC CICS calls for IccTask class methods . . . . . . . . . . . . . . . . . . . . 190

23. EXEC CICS calls for IccTempStore class methods . . . . . . . . . . . . . . . . . . 191

24. EXEC CICS calls for IccTerminal class methods . . . . . . . . . . . . . . . . . . . 191

25. EXEC CICS calls for IccTerminalData class methods . . . . . . . . . . . . . . . . . 192

26. EXEC CICS calls for IccUser class methods . . . . . . . . . . . . . . . . . . . . 192

© Copyright IBM Corp. 2001, 2008 ix

x TXSeries for Multiplatforms: C++ Foundation Classes Programming Guide and Reference

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.

© Copyright IBM Corp. 2001, 2008 xi

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

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.

xii TXSeries for Multiplatforms: C++ Foundation Classes Programming Guide and Reference

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

[email protected]. 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 TXSeries for Multiplatforms: C++ Foundation Classes Programming Guide and Reference

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.

© Copyright IBM Corp. 2001, 2008 1

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

2 TXSeries for Multiplatforms: C++ Foundation Classes Programming Guide and Reference

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 region’s 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? 3

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 user’s control object by using a try-catch

construct.

The functional part of the main code is shown in Figure 1 on page 6.


(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 user’s 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 application’s 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:

void main(void) (1)

{

Icc::initializeEnvironment(ICC_CLASS_MEMORY_MGMT, (2)

ICC_FAMILY_SUBSET,

ICC_EDF_BOOL);

try (3)

{

ICC_USER_CONTROL control; (4)

control.run(); (5)

}

catch(IccException& exc) (6)

{

Icc::catchException(exc); (7)

}

catch(...) (8)

{

Icc::unknownException(); (9)

}

Icc::returnToCICS(); (10)

}

Figure 1. Code example: main function


IccFileId id("XYZ123");

IccFile file(id);

This allows the C++ compiler to protect you against doing something wrong such

as:

IccDataQueueId id("WXYZ");

IccFile 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 id1("File1");

IccFileId id2("File2");

IccFile file1(id1);

IccFile 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 task’s 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″).

Chapter 2. Writing an object-oriented CICS server 7

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

application’s 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.

Alternatively, use the -D option of your compiler.

#define ICC_CLASS_MEMORY_MGMT Icc::cmmNonCICS

#include "iccmain.cpp"

Figure 2. Code example: Memory management


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.

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.

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.

// 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 clear method get method put method

const IccRequestId& start( const IccTransId& transId,

const IccTime* time=0,

const IccRequestId* reqId=0 );

Figure 3. Code example: Signature of IccStartRequestQ::start method

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

Figure 5. Code example: Defining virtual clear, get, and put methods in the IccResource class


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.


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

method’s 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.

#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


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.


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.

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 object’s 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.

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.

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

IccBuf buffer("Hello World");

buffer << " out there";

IccBuf buffer2(buffer);

Figure 8. Code example: Using the copy constructor


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.

The IccTempStore object that is created is the application’s 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 program’s 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.

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

Chapter 3. Buffer objects 15

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 application’s own

IccBuf 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 application’s own storage.

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

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

IccBuf buf(50);

IccTempStore store("TEMPSTOR");

buf = store.readNextItem();

Figure 11. Code example: Copying returned data to a local buffer object

IccTempStore store("TEMPSTOR");

const IccBuf& buf = store.readNextItem();

Figure 12. Code example: Maintaining a reference to a buffer object


v The task ends normally or abnormally.

Chapter 3. Buffer objects 17

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 “Starting transactions asynchronously” on page 26

v “Transient data” on page 30

v “Temporary storage” on page 32

v “Terminal control” on page 34

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


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

file’s 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 keyLength

v keyPosition

v recordIndex

v 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


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 recordLength

v recordIndex

v keyLength

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

v recordFormat

v recordLength

v recordIndex


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

Chapter 4. Using CICS Services 21


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.


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


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


Most of the terminal I/O in these samples has been omitted from the code that

follows.

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.

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.




{

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)

IccBuf& commArea = IccControl::commArea();

commArea = "DATA RETURNED BY ICCPRG2";

return;



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.

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

IccBuf& commArea = IccControl::commArea();

commArea = "DATA RETURNED BY ICCPRG3";

return;



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.


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 program’s terminal.

buffer

An IccBuf object that holds start data.

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


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

Here, as in iccsrq1.cpp, it creates several objects:

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)


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

caller’s 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 program’s terminal. The

setRouteOption method indicates that the transaction starts on the caller’s 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.


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


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.

// Header files



// Buffer for the example

const char* queueItems[] =

{




};

// Example code


{

short itemNum =1;


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


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.


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.

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

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


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


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.

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.

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


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.

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


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.


Chapter 5. Conditions, errors, and exceptions

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 compiler’s 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″):


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:



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( 1 );




}

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


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.

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




{

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

Chapter 5. Conditions, errors, and exceptions 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.


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.

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

IccTempStore temp("TEMP1234");

temp.setActionOnCondition(IccResource::noAction,

IccCondition::QIDERR);IccTempStore temp("TEMP1234");

IccBuf buf(40);

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


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


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.

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.

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:


temp.setActionOnCondition(IccResource::throwException,


...

try

{

buf = temp.readNextItem();

·

}

catch (IccException& exception)

{

//Exception handling code

·

}

Figure 28. Code example: Condition exception handling


temp.setActionOnCondition(IccResource::abendTask,


Figure 29. Code example: Severe error handling


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 object’s 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.

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.


{

if (strcmp(programId.name(), "PROG1234") == 0)

//do something

}

Figure 30. Code example: Method 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.

task()->abend(); (1)

task()->abend("WXYZ"); (2)

task()->abend("WXYZ", IccTask::respectAbendHandler); (3)

task()->abend("WXYZ", IccTask::ignoreAbendHandler); (4)

task()->abend("WXYZ", IccTask::ignoreAbendHandler, (5)

IccTask::suppressDump);

Figure 31. Code example: Parameter level enforcement


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.


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


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


Chapter 6. CICS Foundation Classes Reference Pages 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.


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.



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;


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,


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();


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,


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.


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 {


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.


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,



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.


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




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.



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,




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.


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,


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.


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.


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


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


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


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.


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


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


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



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


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.


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



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;

};


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.


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,


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


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 {


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


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



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



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


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





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


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





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 KSDS: The data set is a key-sequenced data set.

v NOTKEYED: The data set is not addressed by physical keys.

v RRDS: The data set is a relative record data set.

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


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


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


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


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.


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.


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.


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

};


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


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



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.


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




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



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;

};


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


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


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



IccProgramId::operator= (1)

IccProgramId& operator=(const char* progName);

progName


IccProgramId::operator= (2)

IccProgramId& operator=(const IccProgramId& id);



Related Information

IccBase class

IccResourceId class


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)




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


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


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


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)


v condition 1 (ERROR): action=X (throwException)

v condition 2 (RDATT): action=0 (noAction)

v condition 3 (WRBRK): action=0 (noAction)

v condition 4 (EOF): action=H (callHandleEvent)

v condition 5 (EODS): action=0 (noAction)

v condition 6 (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;


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


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();


IccResource::ActionOnCondition

type enum {

noAction,

callHandleEvent,

throwException,

abendTask,

} ActionOnCondition;

noAction

Carry on as normal; it is the application program’s 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


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)


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 IccResourceId& operator=(const IccResourceId& id);

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;

};


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



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


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


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.


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,


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


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();


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


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 partner’s 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.


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,



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.


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 FREE

v PENDFREE

v PENDRECEIVE

v RECEIVE

v ROLLBACK

v SEND

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


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


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


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.


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


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


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


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


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.


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



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


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


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,


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;

};


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


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();



what type of principal facility this task has. This is usually a terminal, such as when

the task was started by someone’s 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


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.


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.


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 ″OR″ed, to get the desired

combination. For example:

IccTask::dProgram + IccTask::dDCT + IccTask::dSIT

IccTask::FacilityType


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.


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();


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.


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,



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


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.



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)


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


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,


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


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.



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.



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


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




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





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.


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


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


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

};


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


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


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.


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;



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)


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)


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


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

};


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 A reference to an IccTransId object.


IccTransId::operator= (1)

IccTransId& operator=(const char* name);

name

The four-character transaction name.

IccTransId::operator= (2)

IccTransId& operator=(const IccTransId& id);

id A reference to an IccTransId object.


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.


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


Main Function

Purpose

Synopsis

Description

Class Members

Related Information

IccBase class

IccResourceId class


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 programmer’s

request to abend a CICS task.

System action:



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:



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

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.


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)


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 output”″Activating 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.


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


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

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


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

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


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

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 user’s 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


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 IBM’s 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® AIX

AS/400® CICS

CICS/400® CICS/6000®

CICS/ESA® CICS/MVS®

CICS/VSE® CICSPlex®

C-ISAM™ Database 2™

DB2® DB2 Universal Database™


GDDM® IBM

IBM Registry™ 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

Index

Aabend codes 39

abendsfor CICS conditions 44

list of codes 179

retrieving information 47

absolute time 48

asynchronous transactions 26

Bbase 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

CCICS 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

Ddata areas

extensibility 13

ownership 13

date 36

debugging 184

diagnosticsretrieving abend information 47

EEDF 186

ESDS files 19

adding records to 21

cannot delete records from 22

reading records 20

exceptions 8

throwing and catching 39

throwing for CICS conditions 44

types of 41

EXEC CICS callsequivalent Foundation Classes 187

executing programs 184

Ffiles 19


browsing 22

deleting records from 22

ESDS 19

KSDS 19

reading records 20

RRDS 19

updating records in 22

IIBM 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


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

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

IccFileIdconstructor 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

IccGroupIdconstructor 96

IccGroupId class 3

constructor 96

IccGroupId::operator= 96

IccJournal class 2


IccJournalIdconstructor 97

IccJournalId class 3

constructor 97

IccJournalId::number 97

IccJournalId::operator= 97

IccJournalTypeIdconstructor 98

IccJournalTypeId class 3

constructor 98

IccJournalTypeId::operator= 98

IccKeyconstructor 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

IccLockIdconstructor 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 classderived 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 classAIX 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

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 34

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 34

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

Kkey 20

complete 21

KSDS files 19



reading records 20

Mmain function 5

memory management 9

message class 102

messages 8

Microsoft Visual C++ 183

Pparameter passing 10

platform differences 44

polymorphism 10

program control 24

programs 24

Rrecord index classes 4

recordindex class 98, 117

Recordindex class 107

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

Ssingleton classes 7

start data 26

storage operators 9

structure 70

support classes 8

symbolic debuggers 184

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

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


transactions (continued)canceling unexpired start requests 27

starting 26

transient data 30

deleting 31

reading 31

writing 31

Index 203

��

SC34-6633-02

Spine information:

��

�

TX

Serie

s fo

r M

ultip

latfo

rms

C+

+ Fo

unda

tion

Cla

sses

Pr

ogra

mm

ing

Gui

de

and

Ref

eren

ce

Vers

ion

6.2

SC34

-663

3-02

txseries for multiplatforms c++ foundation classes programming guide and reference version 6.2

Documents

iccresource classes

scope of data

support classes

derived classes

singleton classes

record index classes

example of terminal

writing items