Sie sind auf Seite 1von 340

OS/390

C/C++ IBM Open Class Library User's Guide

SC09-2363-03

OS/390

C/C++ IBM Open Class Library User's Guide

SC09-2363-03

Note! Before using this information and the product it supports, be sure to read the

Note!

Note! Before using this information and the product it supports, be sure to read the general
Before using this information and the product it supports, be sure to read the general

Before using this information and the product it supports, be sure to read the general information under “Notices” on page xi.

this information and the product it supports, be sure to read the general information under “Notices”

Fourth Edition, September 1998

This edition applies to Version 2 Release 6 of OS/390 C/C++ (5647-A01) and to all subsequent releases and modifications until otherwise indicated in new editions or other updated documentation. Make sure that you use the correct edition for the level of the program listed above. Also, ensure that you apply all necessary PTFs for the program.

Technical changes in the text since the last release of this book are indicated by a vertical line (|) to the left of the change.

Order publications through your IBM representative or the IBM branch office serving your location. Publications are not stocked at the address below. The OS/390 C/C++ publications are available through the OS/390 Library page on the World Wide Web

(http://www.s390.ibm.com/os390/bkserv).

IBM welcomes your comments. You can send your comments electronically to the network ID listed below. Be sure to include your entire network address if you wish a reply.

Internet: torrcf@ca.ibm.com IBMLink: toribm(torrcf) IBM/PROFS: torolab4(torrcf) IBMMAIL: ibmmail(caibmwt9)

You can also send your comments by facsimile (attention: RCF coordinator) or you can use the Reader’s Comment Form that is provided at the back of this publication. Refer to “Communicating Your Comments to IBM” for a description of the methods. This information immediately precedes the Reader’s Comment Form at the back of this publication. You can also address your comments to:

IBM Canada Ltd. Laboratory Information Development

2G/345/1150/TOR

1150 Eglinton Avenue East North York, Ontario, Canada. M3C 1H7

If you send comments, include the title and order number of this book, and the page number or topic related to your comment.

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.

Copyright International Business Machines Corporation 1996, 1998. All rights reserved. Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Contents   Notices . . . . . . . . . . . .

Contents

 

Notices

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

xi

Standards

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

xi

Trademarks

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

xii

About This Book

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

 

xv

IBM OS/390 C/C++ and Related Publications

xv

Hardcopy Books Softcopy Books Softcopy Examples OS/390 C/C++ on the World Wide Web

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

xxii

xxii

xxiii

xxiii

C/C++ News

.

.

.

.

.

.

.

.

xxiv

xxv

About IBM OS/390 C/C++ Changes for Version 2 Release 6

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

 

xxv

The C/C++ Compilers

 

xxvi

The C Language

xxvi

The C++ Language

xxvi

Common Features of the OS/390 C and C++ Compilers

xxvii

OS/390 C Compiler Specific Features

xxviii

Features That Are Specific to the OS/390 C++ Compiler

xxviii

Utilities Class Libraries Class Library Source

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

xxix

xxix

xxx

The Debug Tool

 

xxxi

OS/390 Language Environment

xxxi

The Program Management Binder

xxxii

OS/390 UNIX System Services (OS/390 UNIX)

xxxii

OS/390 C/C++ Applications with OS/390 UNIX C/C++ Functions

xxxiv

Input and Output

xxxv

I/O Interfaces File Types Additional I/O Features

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

xxxv

xxxvi

xxxvii

The System Programming C Facility

 

xxxvii

Interaction with Other IBM Products

xxxvii

Additional Features of OS/390 C/C++

 

xxxix

Suggested Reading

.

.

.

.

.

.

.

.

.

.

xl

1

Chapter 1. Introduction to IBM Open Class Library History of IBM Open Class Library

 

1

Hierarchies of the Class Libraries

1

|

Coding with Class Libraries under OS/390 UNIX System Services

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

 

5

Compiling Programs that Use IBM Open Class Library

5

Binding with IBM Open Class Library

6

Migration Notes Thread Safety and the IBM Open Class Library

.

.

.

.

.

.

.

.

.

6

7

Why Thread Safety?

 

7

Levels of Thread Safety

7

Chapter 2. Using the Complex Mathematics Classes Review of Complex Numbers Header Files and Constants
Chapter 2. Using the Complex Mathematics Classes
Review of Complex Numbers
Header Files and Constants for complex and c_exception
Constructing complex Objects
Complex Mathematics Input and Output
Mathematical Operators for complex
Equality and Inequality Operators Test for Absolute Equality
Assignment Operators Do Not Produce an lvalue
Friend Functions for complex
Mathematical Functions for complex
Trigonometric Functions for complex
Magnitude Functions for complex
Conversion Functions for complex
Using the c_exception Class to Handle Complex Mathematics Errors
Defining a Customized complex_error Function
Errors Handled Outside of the Complex Mathematics Library
An Example of Using the Complex Mathematics Library
11
11
12
12
13
14
15
16
16
16
17
18
18
19
19
20
20
Part 2. The I/O Stream Class Library
23
Chapter 3. Introduction to the I/O Stream Classes
The I/O Stream Classes and stdio.h
Overview of the I/O Stream Classes
Combining Input and Output of Different Types
Input and Output for User-Defined Classes
The I/O Stream Class Hierarchy
The I/O Stream Header Files
Predefined Streams
Anonymous Streams
Stream Buffers
What Does a Stream Buffer Do?
Why Use a Stream Buffer?
How Is a Stream Buffer Implemented?
25
25
25
26
26
26
28
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
28
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
29
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
30
30
30
30
Format State Flags
Thread Safety
32
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
32
Chapter 4. Getting Started with the I/O Stream Library
Receiving Input from Standard Input
Multiple Variables in an Input Statement
String Input
White Space in String Input
Incorrect Input and the Error State of the Input Stream
Using Input Streams Other Than cin
Displaying Output on Standard Output or Standard Error
Multiple Variables in an Output Statement
Using Output Streams Other Than cout, cerr, and clog
Flushing Output Streams with endl and flush
Placing endl or flush in an Output Stream
Parsing Multiple Inputs
Opening a File for Input and Reading from the File
Constructing an fstream or ifstream Object for Input
Reading Input from a File
Opening a File for Output and Writing to the File
35
35
35
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
36
36
38
38
38
39
39
40
41
41
42
43
44
45

Chapter 5. Advanced I/O Stream Topics Associating a File with a Standard Input or Output Stream Using filebuf Functions to Move Through a File Defining an Input Operator for a Class Type Using the cin Stream in a Class Input Operator Displaying Prompts in Input Operator Code Defining an Output Operator for a Class Type Class Output Operators and the Format State Correcting Input Stream Errors Changing the Formatting of Stream Output ios Methods and Manipulators Using setf, unsetf, and flags Changing the Notation of Floating-Point Values Changing the Base of Integral Values Setting the Width and Justification of Output Fields Defining Your Own Format State Flags Using the strstream Classes for String Manipulation

 

47

47

48

50

51

52

52

53

54

56

56

57

59

60

61

61

63

Chapter 6. Manipulators Introduction to Manipulators Simple Manipulators and Parameterized Manipulators Creating Simple Manipulators for Your Own Types Creating Parameterized Manipulators for Your Own Types

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

65

65

 

65

66

67

Part 3. The Collection Class Library

 

71

Chapter 7. Overview of the Collection Class Library Benefits of the Collection Class Library Concrete Classes Provided by the Library Types of Classes in the Collection Class Library Flat Collections Ordering of Collection Elements Access by Key Equality for Keys and Elements Uniqueness of Entries Restricted Access Trees Auxiliary Classes The Overall Implementation Structure Categories of Classes Default Classes Variant Classes Collection Class Hierarchy Typed and Typeless Implementation Classes Class Template Naming Conventions

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

73

73

73

77

.

.

.

.

.

.

.

.

.

.

78

79

 

79

79

81

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

81

82

83

83

 

84

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

85

85

85

 

85

86

Chapter 8. Instantiating and Using the Collection Classes Instantiation and Object Definition Adding, Removing, and Replacing Elements Adding Elements Removing Elements Replacing Elements Cursors

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

89

89

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

90

90

91

93

93

Using Cursors for Locating and Accessing Elements

94

Iterating over Collections

96

Iteration Using Cursors

96

Iteration Using allElementsDo

97

Iteration Using Applicators

98

Copying and Referencing Collections

99

Bounded and Unbounded Collections

100

Chapter 9. Element Functions and Key-Type Functions

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

101

Introduction to Element Functions and Key-Type Functions

101

Using Member Functions

102

Using Separate Functions

103

Using Element Operation Classes

105

Memory Management with Element Operation Classes

109

Functions for Derived Element Classes

109

Using Smart Pointers

111

Overview of Smart Pointers

112

Element Pointers Managed Pointers Automatic Pointers Constructing Smart Pointers

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

113

116

116

118

Chapter 10. Tailoring a Collection Implementation

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

121

Introduction Replacing the Default Implementation

.

.

.

.

.

.

.

.

.

.

121

121

The Based-On Concept

122

Provided Implementation Variants

122

Features of Provided Implementation Variants

123

Sequences Trees Hash Table

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

124

126

129

131

Chapter 11. Polymorphism and the Collections Introduction to Polymorphism

131

Using the Abstract Class Hierarchy

131

Adding and Overloading Member Functions

132

Chapter 12. Support for Notifications

135

Example for IVSequence<IString>

136

Chapter 13. Thread Safety and the Collection Classes

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Chapter 14. Exception Handling

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

139

Guard Objects Usage Restrictions

Introduction to Exception Handling

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

139

139

141

143

143

Exceptions Caused by Violated Preconditions

143

Exceptions Caused by System Failures and Restrictions

144

Precondition and Defined Behavior

144

Levels of Exception Checking

145

List of Exceptions

145

The Hierarchy of Exceptions

147

Chapter 15. Collection Class Library Tutorials Preparing for the Lessons Lesson 1: Defining a Simple Collection of Integers Lesson 2: Adding, Listing, and Removing Elements Lesson 3: Changing the Element Type Lesson 4: Changing the Collection Lesson 5: Changing the Implementation Variant Errors When Compiling or Running the Lessons Other Tutorials Using the Default Classes Advanced Use Source Files for the Tutorials

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

 

149

150

150

153

158

163

171

173

.

.

.

.

.

.

.

173

173

.

.

.

.

.

.

.

174

174

Chapter 16. Solving Problems in the Collection Class Library Cursor Usage Element Functions and Key-Type Functions Key Access Function - How to Return the Key (1) Key Access Function - How to Return the Key (2) Definition of Key-Type Functions Exception Tracing Declaration of Template Arguments and Element Functions (1) Declaration of Template Arguments and Element Functions (2) Declaration of Template Arguments and Element Functions (3) Default Constructor

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

 

177

.

.

.

.

.

.

.

177

178

 

179

180

180

.

.

.

.

.

.

.

181

181

 

181

.

.

.

.

.

.

.

182

182

Chapter 17. Compatibility Information Compatible Items Incompatible Items

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

185

185

186

Part 4. Application Support Class Library

189

Chapter 18. Application Support Class Library Organization of Classes IBase Class IVBase Class String and Buffer Classes Thread Safety MBCS and National Language Support Turning on Internationalization Semantics Setting the Locale

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

 

191

191

.

.

.

.

.

.

.

.

.

.

.

.

.

.

194

194

195

.

.

.

.

.

.

.

195

195

 

196

196

Chapter 19. String Classes Introduction to the String Classes String Buffers Multiple-Byte Character Set Support Indexing of Strings What You Can Do with Strings Creating and Copying Strings Doing String Input and Output Concatenating Strings Finding Words or Substrings within Strings Replacing, Inserting, and Deleting Substrings Determining String Lengths and Word Counts

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

199

199

.

.

.

.

.

.

.

200

200

 

200

200

201

203

.

.

.

.

.

.

.

204

204

 

206

207

Extending Strings Converting between Strings and Numeric Data

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

207

207

Converting between Strings and Different Base Notations

208

Testing the Characteristics of Strings

209

Formatting Strings

.

.

.

.

.

.

.

.

.

.

211

212

Other IString Capabilities IStringTest Class

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

212

215

Chapter 20. Exception and Trace Classes Introduction to the Exception Classes

 

215

Characteristics of the Exception Classes

215

Derivation of the Exception Classes

215

Situations in Which the Exception Classes Are Used

216

Catching Exceptions Thrown by Class Library Functions

217

An Example of the Subscript Operator Throwing an Exception

217

Throwing Your Own Exceptions Using the Exception Classes

218

Macros Used with the Exception Classes

219

Why Use the Macros?

220

Using the ITrace Class

222

Using the Trace Macros to Control Trace Output

222

Capturing Trace Output in a File

223

An Example of Using ITrace

223

Chapter 21. Date and Time Classes

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

225

IDate Class Creating an IDate Object

.

.

.

.

.

.

.

.

.

.

225

225

Changing an IDate Object

226

Information Functions for IDate Objects

226

Testing and Comparing IDate Objects

226

ITime Class Creating an ITime Object

.

.

.

.

.

.

.

.

.

.

227

227

Changing an ITime Object

227

Information Functions for ITime Objects

227

Comparing ITime Objects

228

Writing an ITime Object to an Output Stream

228

ITimeStamp Class Creating an ITimeStamp Object

.

.

.

.

.

.

.

.

.

.

229

229

Changing an ITimeStamp Object

229

Information Functions for ITimeStamp Objects

229

Comparing ITimeStamp Objects

230

Chapter 22. Controlling Threads and Protecting Data

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

Chapter 23. The IBM Open Class Notification Framework

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

231

Accessing the Current Thread

232

Starting a Thread

232

Starting Nonmember Functions

232

Starting a Member Function

232

Protecting Data

.

.

.

.

.

.

.

.

.

.

234

235

Notifiers and Observers

235

Notification Protocol IBM C++ Notification Class Hierarchy

.

.