z/OS 

XL C/C++
Programming Guide

SC09-4765-13
 Note
Before using this information and the product it supports, read the information under Notices on page 1019.

This edition applies to z/OS XL C/C++ compiler in version 1, release 13, modification 0 of z/OS (5694-A01) and to all
subsequent releases and modifications until otherwise indicated in new editions.
This edition replaces SC09-4765-12.
Copyright IBM Corporation 1996, 2012.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

About this document . . . . . . . . . . . . . . . . . . . . . xxv

How to read syntax diagrams . . . . . . . . . . . . . . . . . . . xxv
Related z/OS XL C/C++ information . . . . . . . . . . . . . . . . xxvii
Where to find more information . . . . . . . . . . . . . . . . . . xxvii

How to send your comments to IBM . . . . . . . . . . . . . . . xxix

If you have a technical problem . . . . . . . . . . . . . . . . . . xxix

Summary of changes . . . . . . . . . . . . . . . . . . . . . xxxi

Changes made in z/OS Version 1 Release 13 . . . . . . . . . . . . . xxxi
Changes made in z/OS Version 1 Release 12 . . . . . . . . . . . . . xxxi
Changes made in z/OS Version 1 Release 11 . . . . . . . . . . . . . xxxii

Part 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. About IBM z/OS XL C/C++ . . . . . . . . . . . . . . . . 3

Part 2. Input and Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2. Introduction to C and C++ input and output . . . . . . . . . 7

Types of C and C++ input and output . . . . . . . . . . . . . . . . . 7

Chapter 3. Understanding models of C I/O . . . . . . . . . . . . . . 9

The record model for C I/O . . . . . . . . . . . . . . . . . . . . . 9
The byte stream model for C I/O . . . . . . . . . . . . . . . . . . 18

Chapter 4. Using the Standard C++ Library I/O Stream Classes . . . . . 21

Advantages to using the C++ I/O stream classes . . . . . . . . . . . . 21
Predefined streams for C++ . . . . . . . . . . . . . . . . . . . . 21
How C++ I/O streams relate to C I/O streams . . . . . . . . . . . . . 22
Mixing the Standard C++ I/O stream classes, USL I/O stream class library, and
C I/O library functions . . . . . . . . . . . . . . . . . . . . . 22
Specifying file attributes . . . . . . . . . . . . . . . . . . . . . 22

Chapter 5. Opening files . . . . . . . . . . . . . . . . . . . . . 25

Prototypes of functions . . . . . . . . . . . . . . . . . . . . . . 25
Categories of I/O . . . . . . . . . . . . . . . . . . . . . . . . 27
Specifying what kind of file to use . . . . . . . . . . . . . . . . . . 28
Avoiding Undesirable Results when Using I/O . . . . . . . . . . . . . 35
How z/OS XL C/C++ determines what kind of file to open . . . . . . . . . 35
MAP 0010: Under TSO, MVS batch, IMS POSIX(ON) . . . . . . . . . 36
MAP 0020: Under TSO, MVS batch, IMS POSIX(OFF) . . . . . . . . . 40
MAP 0030: Under CICS . . . . . . . . . . . . . . . . . . . . . 43

Chapter 6. Buffering of C streams . . . . . . . . . . . . . . . . . 45

Chapter 7. Using ASA text files . . . . . . . . . . . . . . . . . . 47

Example of writing to an ASA file . . . . . . . . . . . . . . . . . . 47

Copyright IBM Corp. 1996, 2012 iii

 ASA file control . . . . . . . . . . . . . . . . . . . . . . . . . 48

Chapter 8. z/OS XL C Support for the double-byte character set . . . . . 51

Opening files . . . . . . . . . . . . . . . . . . . . . . . . . 52
Reading streams and files . . . . . . . . . . . . . . . . . . . . . 52
Writing streams and files . . . . . . . . . . . . . . . . . . . . . 54
Flushing buffers . . . . . . . . . . . . . . . . . . . . . . . . 56
Setting positions within files . . . . . . . . . . . . . . . . . . . . 57
Closing files . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Manipulating wide character array functions . . . . . . . . . . . . . . 59

Chapter 9. Using C and C++ standard streams and redirection . . . . . . 61

Default open modes . . . . . . . . . . . . . . . . . . . . . . . 62
Interleaving the standard streams with sync_with_stdio() . . . . . . . . . 63
Interleaving the standard streams without sync_with_stdio() . . . . . . . . 64
Redirecting standard streams . . . . . . . . . . . . . . . . . . . 66
Redirecting streams from the command line . . . . . . . . . . . . . . 66
Assigning the standard streams. . . . . . . . . . . . . . . . . . . 68
Using the freopen() library function . . . . . . . . . . . . . . . . . 68
Redirecting streams with the MSGFILE option . . . . . . . . . . . . . 68
Redirecting streams under z/OS . . . . . . . . . . . . . . . . . . 70
Passing C and C++ standard streams across a system() call . . . . . . . . 73
Using global standard streams . . . . . . . . . . . . . . . . . . . 76

Chapter 10. Performing OS I/O operations . . . . . . . . . . . . . . 81

Opening files . . . . . . . . . . . . . . . . . . . . . . . . . 81
Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
DCB (Data Control Block) attributes . . . . . . . . . . . . . . . . . 101
Reading from files . . . . . . . . . . . . . . . . . . . . . . . 103
Writing to files . . . . . . . . . . . . . . . . . . . . . . . . . 105
Flushing buffers . . . . . . . . . . . . . . . . . . . . . . . . 109
Repositioning within files . . . . . . . . . . . . . . . . . . . . . 112
Closing files . . . . . . . . . . . . . . . . . . . . . . . . . 117
Renaming and removing files . . . . . . . . . . . . . . . . . . . 119
fldata() behavior . . . . . . . . . . . . . . . . . . . . . . . . 119

Chapter 11. Performing z/OS UNIX file system I/O operations . . . . . . 123
Creating files . . . . . . . . . . . . . . . . . . . . . . . . . 123
Opening files . . . . . . . . . . . . . . . . . . . . . . . . . 124
Reading from z/OS UNIX file system files . . . . . . . . . . . . . . 128
Opening and reading from z/OS UNIX file system directory files . . . . . . 129
Writing to z/OS UNIX file system files . . . . . . . . . . . . . . . . 129
Flushing records . . . . . . . . . . . . . . . . . . . . . . . . 130
Setting positions within files . . . . . . . . . . . . . . . . . . . . 130
Closing files . . . . . . . . . . . . . . . . . . . . . . . . . 131
Deleting files . . . . . . . . . . . . . . . . . . . . . . . . . 131
Pipe I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Low-level z/OS UNIX I/O . . . . . . . . . . . . . . . . . . . . . 137
Example of z/OS UNIX file system I/O functions . . . . . . . . . . . . 137
fldata() behavior . . . . . . . . . . . . . . . . . . . . . . . . 142
File tagging and conversion . . . . . . . . . . . . . . . . . . . . 144
Access control lists (ACLs) . . . . . . . . . . . . . . . . . . . . 144

Chapter 12. Performing VSAM I/O operations . . . . . . . . . . . . 147

VSAM types (data set organization) . . . . . . . . . . . . . . . . . 147
Choosing VSAM data set types . . . . . . . . . . . . . . . . . . 148

iv z/OS V1R13.0 XL C/C++ Programming Guide

Opening VSAM data sets . . . . . . . . . . . . . . . . . . . . 152
Record I/O in VSAM . . . . . . . . . . . . . . . . . . . . . . 157
VSAM record level sharing and transactional VSAM . . . . . . . . . . . 165
VSAM extended addressability . . . . . . . . . . . . . . . . . . 167
Text and binary I/O in VSAM . . . . . . . . . . . . . . . . . . . 167
Closing VSAM data sets . . . . . . . . . . . . . . . . . . . . . 172
VSAM return codes . . . . . . . . . . . . . . . . . . . . . . . 173
VSAM examples . . . . . . . . . . . . . . . . . . . . . . . . 173
fldata() behavior . . . . . . . . . . . . . . . . . . . . . . . . 185

Chapter 13. Performing terminal I/O operations . . . . . . . . . . . 189

Opening files . . . . . . . . . . . . . . . . . . . . . . . . . 189
Reading from files . . . . . . . . . . . . . . . . . . . . . . . 191
Writing to files . . . . . . . . . . . . . . . . . . . . . . . . . 193
Flushing records . . . . . . . . . . . . . . . . . . . . . . . . 195
Repositioning within files . . . . . . . . . . . . . . . . . . . . . 196
Closing files . . . . . . . . . . . . . . . . . . . . . . . . . 196
fldata() behavior . . . . . . . . . . . . . . . . . . . . . . . . 196

Chapter 14. Performing memory file and hiperspace I/O operations . . . 199
Using hiperspace operations . . . . . . . . . . . . . . . . . . . 199
Opening files . . . . . . . . . . . . . . . . . . . . . . . . . 200
Reading from files . . . . . . . . . . . . . . . . . . . . . . . 206
Writing to files . . . . . . . . . . . . . . . . . . . . . . . . . 207
Flushing records . . . . . . . . . . . . . . . . . . . . . . . . 208
Repositioning within files . . . . . . . . . . . . . . . . . . . . . 208
Closing files . . . . . . . . . . . . . . . . . . . . . . . . . 209
Removing memory files . . . . . . . . . . . . . . . . . . . . . 209
fldata() behavior . . . . . . . . . . . . . . . . . . . . . . . . 209
Example program . . . . . . . . . . . . . . . . . . . . . . . 210

Chapter 15. Performing CICS Transaction Server I/O operations . . . . . 213

Chapter 16. Language Environment Message file operations . . . . . . 215

Opening files . . . . . . . . . . . . . . . . . . . . . . . . . 215
Reading from files . . . . . . . . . . . . . . . . . . . . . . . 215
Writing to files . . . . . . . . . . . . . . . . . . . . . . . . . 215
Flushing buffers . . . . . . . . . . . . . . . . . . . . . . . . 216
Repositioning within files . . . . . . . . . . . . . . . . . . . . . 216
Closing files . . . . . . . . . . . . . . . . . . . . . . . . . 216

Chapter 17. CELQPIPI MSGRTN file operations . . . . . . . . . . . 217

Opening files . . . . . . . . . . . . . . . . . . . . . . . . . 217
Reading from files . . . . . . . . . . . . . . . . . . . . . . . 217
Writing to files . . . . . . . . . . . . . . . . . . . . . . . . . 217
Flushing buffers . . . . . . . . . . . . . . . . . . . . . . . . 217
Repositioning within files . . . . . . . . . . . . . . . . . . . . . 217
Closing files . . . . . . . . . . . . . . . . . . . . . . . . . 218
fldata() behavior . . . . . . . . . . . . . . . . . . . . . . . . 218
fldata() example . . . . . . . . . . . . . . . . . . . . . . . . 219

Chapter 18. Debugging I/O programs . . . . . . . . . . . . . . . 221

Using the __amrc structure . . . . . . . . . . . . . . . . . . . . 221
Using the __amrc2 structure . . . . . . . . . . . . . . . . . . . 225
Using __last_op codes . . . . . . . . . . . . . . . . . . . . . 225
Using the SIGIOERR signal. . . . . . . . . . . . . . . . . . . . 229

Contents v
 File I/O trace . . . . . . . . . . . . . . . . . . . . . . . . . 232
Locating the file I/O trace . . . . . . . . . . . . . . . . . . . . 233

Part 3. Interlanguage Calls with z/OS XL C/C++ . . . . . . . . . . . . . . . . 235

Chapter 19. Using Linkage Specifications in C or C++. . . . . . . . . 237

Syntax for Linkage in C or C++ . . . . . . . . . . . . . . . . . . 237
Kinds of Linkage used by C or C++ Interlanguage Programs . . . . . . . 238
Using Linkage Specifications in C++ . . . . . . . . . . . . . . . . 240

Chapter 20. Combining C or C++ and Assembler . . . . . . . . . . . 243

Establishing the z/OS XL C/C++ environment . . . . . . . . . . . . . 243
Specifying linkage for C or C++ to Assembler . . . . . . . . . . . . . 244
Parameter lists for OS linkage . . . . . . . . . . . . . . . . . . . 244
XPLINK Assembler . . . . . . . . . . . . . . . . . . . . . . . 245
Using standard macros . . . . . . . . . . . . . . . . . . . . . 247
Calling C code from Assembler C example . . . . . . . . . . . . . 253
Calling run-time library routines from Assembler C++ example . . . . . . 254
Register content at entry to a non-XPLINK ASM routine using OS linkage 256
Register content at exit from a non-XPLINK ASM routine to z/OS XL C/C++ 256
Retaining the C environment using preinitialization . . . . . . . . . . . 257

Part 4. Coding: Advanced Topics . . . . . . . . . . . . . . . . . . . . . . 277

Chapter 21. Building and using Dynamic Link Libraries (DLLs) . . . . . 279
Support for DLLs. . . . . . . . . . . . . . . . . . . . . . . . 279
DLL concepts and terms . . . . . . . . . . . . . . . . . . . . . 280
Loading a DLL . . . . . . . . . . . . . . . . . . . . . . . . 281
Managing the use of DLLs when running DLL applications . . . . . . . . 286
Creating a DLL or a DLL application . . . . . . . . . . . . . . . . 288
Building a simple DLL . . . . . . . . . . . . . . . . . . . . . . 288
Building a simple DLL application . . . . . . . . . . . . . . . . . 292
Creating and using DLLs . . . . . . . . . . . . . . . . . . . . . 293
DLL restrictions . . . . . . . . . . . . . . . . . . . . . . . . 294

Chapter 22. Building complex DLLs . . . . . . . . . . . . . . . . 299

Rules for compiling source code with XPLINK . . . . . . . . . . . . . 300
Compatibility issues between DLL and non-DLL code . . . . . . . . . . 303
DLL function pointer call in non-DLL code . . . . . . . . . . . . . . 306
Using DLLs that call each other . . . . . . . . . . . . . . . . . . 317

Chapter 23. z/OS 64-bit environment . . . . . . . . . . . . . . . 325

Differences between the ILP32 and LP64 environments . . . . . . . . . 325
Advantages and disadvantages of the LP64 environment . . . . . . . . . 326
Migrating applications from ILP32 to LP64 . . . . . . . . . . . . . . 327
Using compiler diagnostics to ensure portability of code . . . . . . . . . 329
ILP32-to-LP64 portability issues . . . . . . . . . . . . . . . . . . 331
Programming for portability between ILP32 and LP64 . . . . . . . . . . 348

Chapter 24. Using threads in z/OS UNIX applications . . . . . . . . . 353

Models and requirements . . . . . . . . . . . . . . . . . . . . 353
Behaviors and restrictions in z/OS UNIX applications . . . . . . . . . . 365

Chapter 25. Reentrancy in z/OS XL C/C++ . . . . . . . . . . . . . 369

Natural or constructed reentrancy . . . . . . . . . . . . . . . . . 370

vi z/OS V1R13.0 XL C/C++ Programming Guide

Controlling external static in C programs . . . . . . . . . . . . . . . 370
Controlling where string literals exist in C++ code. . . . . . . . . . . . 373
Using writable static in Assembler code . . . . . . . . . . . . . . . 373

Chapter 26. Using decimal data types in C . . . . . . . . . . . . . 377

Decimal data type declarations . . . . . . . . . . . . . . . . . . 377
Defining decimal-type constants . . . . . . . . . . . . . . . . . . 379
Using operators on decimal data types . . . . . . . . . . . . . . . 379
Converting decimal types . . . . . . . . . . . . . . . . . . . . 385
Calling functions with decimal data types . . . . . . . . . . . . . . . 389
Using library functions . . . . . . . . . . . . . . . . . . . . . . 389
Formatting input and output operations with decimal data types . . . . . . 389
Validating decimal values . . . . . . . . . . . . . . . . . . . . 389
Fixing sign variables . . . . . . . . . . . . . . . . . . . . . . 390
Returning decimal absolute values . . . . . . . . . . . . . . . . . 390
Programming examples . . . . . . . . . . . . . . . . . . . . . 390
Decimal exception handling . . . . . . . . . . . . . . . . . . . . 393

Chapter 27. IEEE Floating-Point . . . . . . . . . . . . . . . . . 397

Floating-point numbers . . . . . . . . . . . . . . . . . . . . . 397
C/C++ compiler support . . . . . . . . . . . . . . . . . . . . . 398
Using IEEE floating-point. . . . . . . . . . . . . . . . . . . . . 398

Chapter 28. Handling error conditions, exceptions, and signals . . . . . 403

Handling C software exceptions under C++ . . . . . . . . . . . . . . 403
Handling hardware exceptions under C++ . . . . . . . . . . . . . . 404
Tracebacks under C++ . . . . . . . . . . . . . . . . . . . . . 404
AMODE 64 exception handlers . . . . . . . . . . . . . . . . . . 408
Signal handlers . . . . . . . . . . . . . . . . . . . . . . . . 409

Chapter 29. Network communications under UNIX System Services . . . 425

Understanding z/OS UNIX sockets and internetworking . . . . . . . . . 425
Basics of network communication . . . . . . . . . . . . . . . . . 426
What is a socket? . . . . . . . . . . . . . . . . . . . . . . . 427
The conversation . . . . . . . . . . . . . . . . . . . . . . . 432
A typical UDP socket session . . . . . . . . . . . . . . . . . . . 436
Locating the server's port . . . . . . . . . . . . . . . . . . . . 437
Network application example . . . . . . . . . . . . . . . . . . . 437
Using common INET . . . . . . . . . . . . . . . . . . . . . . 443
Compiling and binding . . . . . . . . . . . . . . . . . . . . . . 444
Using TCP/IP APIs . . . . . . . . . . . . . . . . . . . . . . . 445
Using z/OS UNIX sockets . . . . . . . . . . . . . . . . . . . . 447
Understanding the X/Open Transport Interface (XTI). . . . . . . . . . . 450

Chapter 30. Interprocess communication using z/OS UNIX . . . . . . . 453

Message queues. . . . . . . . . . . . . . . . . . . . . . . . 453
Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . 454
Shared memory . . . . . . . . . . . . . . . . . . . . . . . . 454
Memory mapping . . . . . . . . . . . . . . . . . . . . . . . 454
TSO commands from a shell . . . . . . . . . . . . . . . . . . . 455

Chapter 31. Using templates in C++ programs . . . . . . . . . . . . 457

Using the TEMPINC compiler option . . . . . . . . . . . . . . . . 457
Using the TEMPLATEDEPTH compiler option . . . . . . . . . . . . . 462
Using the TEMPLATEREGISTRY compiler option. . . . . . . . . . . . 462
Using explicit instantiation declarations (C++0x only) . . . . . . . . . . 463

Contents vii
 Chapter 32. Using environment variables . . . . . . . . . . . . . . 467
Working with environment variables . . . . . . . . . . . . . . . . . 475
Environment variables specific to the z/OS XL C/C++ library. . . . . . . . 477
Propagating environment variables . . . . . . . . . . . . . . . . . 501

Chapter 33. Using hardware built-in functions . . . . . . . . . . . . 503

General instructions . . . . . . . . . . . . . . . . . . . . . . 503
Decimal instructions . . . . . . . . . . . . . . . . . . . . . . 526
Floating-point support instructions . . . . . . . . . . . . . . . . . 528
Decimal floating-point built-in functions. . . . . . . . . . . . . . . . 529
Hexadecimal floating-point instructions. . . . . . . . . . . . . . . . 538
Binary floating-Point instructions . . . . . . . . . . . . . . . . . . 539
Built-in functions for transaction execution . . . . . . . . . . . . . . 541

Chapter 34. ANSI C/C++ 98 applications and C99. . . . . . . . . . . 545

Obtaining C99 behavior with XL C . . . . . . . . . . . . . . . . . 545
Using C99 functions in XL C++ applications . . . . . . . . . . . . . . 545

Chapter 35. Writing applications for Single UNIX Specification, Version 3 549
Announcing your intentions . . . . . . . . . . . . . . . . . . . . 549
Testing the environment . . . . . . . . . . . . . . . . . . . . . 550
What is different in SUSv3 . . . . . . . . . . . . . . . . . . . . 551
Symbols withdrawn in SUSv3 . . . . . . . . . . . . . . . . . . . 552
Candidates for removal in a future version . . . . . . . . . . . . . . 552
Implementation compliance . . . . . . . . . . . . . . . . . . . . 552

Chapter 36. Saved compile-time options information . . . . . . . . . 555

Saved options information layout . . . . . . . . . . . . . . . . . . 555

Part 5. Performance optimization . . . . . . . . . . . . . . . . . . . . . . 563

Chapter 37. Improving program performance . . . . . . . . . . . . 565

Writing code for performance . . . . . . . . . . . . . . . . . . . 565
Using C++ constructs in performance-critical code . . . . . . . . . . . 565
Using explicit instantiation declarations (C++0x only) . . . . . . . . . . 567
ANSI aliasing rules . . . . . . . . . . . . . . . . . . . . . . . 567
Using ANSI aliasing rules . . . . . . . . . . . . . . . . . . . . 569
Using variables . . . . . . . . . . . . . . . . . . . . . . . . 571
Passing function arguments. . . . . . . . . . . . . . . . . . . . 572
Coding expressions. . . . . . . . . . . . . . . . . . . . . . . 573
Coding conversions. . . . . . . . . . . . . . . . . . . . . . . 574
Arithmetical considerations . . . . . . . . . . . . . . . . . . . . 574
Using loops and control constructs . . . . . . . . . . . . . . . . . 575
Choosing a data type . . . . . . . . . . . . . . . . . . . . . . 575
Using built-in library functions and macros . . . . . . . . . . . . . . 577
Using library extensions . . . . . . . . . . . . . . . . . . . . . 579
Using #pragmas . . . . . . . . . . . . . . . . . . . . . . . . 581

Chapter 38. Using built-in functions to improve performance . . . . . . 583

Platform-specific functions . . . . . . . . . . . . . . . . . . . . 584

Chapter 39. I/O Performance considerations . . . . . . . . . . . . 585

Accessing MVS data sets . . . . . . . . . . . . . . . . . . . . 585
Accessing UNIX file system files . . . . . . . . . . . . . . . . . . 586
Using memory files . . . . . . . . . . . . . . . . . . . . . . . 587
Using the C++ I/O stream libraries . . . . . . . . . . . . . . . . . 587

viii z/OS V1R13.0 XL C/C++ Programming Guide

 Chapter 40. Improving performance with compiler options . . . . . . . 589
Using the OPTIMIZE option . . . . . . . . . . . . . . . . . . . . 589
Optimizations performed by the compiler . . . . . . . . . . . . . . . 589
Additional options that affect performance . . . . . . . . . . . . . . 591
Inlining . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
Using the XPLINK option. . . . . . . . . . . . . . . . . . . . . 597
Using the IPA option . . . . . . . . . . . . . . . . . . . . . . 598

Chapter 41. Optimizing the system and Language Environment . . . . . 607

Improving the performance of the Language Environment. . . . . . . . . 607
Tuning the system for efficient execution . . . . . . . . . . . . . . . 609

Chapter 42. Balancing compilation time and application performance 611

General tips . . . . . . . . . . . . . . . . . . . . . . . . . 611
Programmer tips . . . . . . . . . . . . . . . . . . . . . . . . 612
System programmer tips . . . . . . . . . . . . . . . . . . . . . 613

Chapter 43. Stepping through optimized code using the dbx debugger
utility . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
Steps for setting up a stopping point for dbx in optimized code . . . . . . . 615
Steps for using dbx to step through optimized code . . . . . . . . . . . 615

Part 6. z/OS XL C/C++ Environments. . . . . . . . . . . . . . . . . . . . . 617

Chapter 44. Using the system programming C facilities . . . . . . . . 619

Using functions in the system programming C environment . . . . . . . . 620
System programming C facility considerations and restrictions . . . . . . . 621
Creating freestanding applications . . . . . . . . . . . . . . . . . 622
Creating system exit routines . . . . . . . . . . . . . . . . . . . 628
Creating and using persistent C environments . . . . . . . . . . . . . 632
Developing services in the service routine environment . . . . . . . . . 637
Tailoring the system programming C environment. . . . . . . . . . . . 653
Including a run-time message file. . . . . . . . . . . . . . . . . . 657
Additional library routines . . . . . . . . . . . . . . . . . . . . 658
Summary of application types . . . . . . . . . . . . . . . . . . . 658

Chapter 45. Library functions for system programming C . . . . . . . 661

__xhotc() Set Up a Persistent C Environment (No Library) . . . . . . . 661
__xhotl() Set Up a Persistent C Environment (With Library) . . . . . . . 662
__xhott() Terminate a Persistent C Environment . . . . . . . . . . . 662
__xhotu() . . . . . . . . . . . . . . . . . . . . . . . . . . 663
__xregs() Get Registers on Entry . . . . . . . . . . . . . . . . 663
__xsacc() Accept Request for Service . . . . . . . . . . . . . . . 664
__xsrvc() Return Control from Service . . . . . . . . . . . . . . . 665
__xusr() - __xusr2() Get Address of User Word . . . . . . . . . . . 665
__24malc() Allocate Storage below 16MB Line . . . . . . . . . . . 665
__4kmalc() Allocate Page-Aligned Storage . . . . . . . . . . . . . 666

Chapter 46. Using run-time user exits . . . . . . . . . . . . . . . 667

Using run-time user exits in z/OS Language Environment. . . . . . . . . 667

Chapter 47. Using the z/OS XL C MultiTasking Facility . . . . . . . . 685

Organizing a program with MTF . . . . . . . . . . . . . . . . . . 685
Designing and coding applications for MTF . . . . . . . . . . . . . . 693
Compiling and linking programs that use MTF . . . . . . . . . . . . . 702
Running programs that use MTF . . . . . . . . . . . . . . . . . . 704

Contents ix
Part 7. Programming with Other Products . . . . . . . . . . . . . . . . . . 709

Chapter 48. Using the CICS Transaction Server (CICS TS) . . . . . . . 711
Developing XL C/C++ programs for the CICS environment . . . . . . . . 711
Preparing CICS for use with z/OS Language Environment . . . . . . . . 711
Designing and coding for CICS . . . . . . . . . . . . . . . . . . 712
Translating and compiling for reentrancy . . . . . . . . . . . . . . . 725
Prelinking and linking all object modules . . . . . . . . . . . . . . . 732
Defining and running the CICS program . . . . . . . . . . . . . . . 733

Chapter 49. Using Cross System Product (CSP) . . . . . . . . . . . 735

Common data types . . . . . . . . . . . . . . . . . . . . . . 735
Passing control . . . . . . . . . . . . . . . . . . . . . . . . 735
Running CSP under MVS . . . . . . . . . . . . . . . . . . . . 736
Running under CICS control . . . . . . . . . . . . . . . . . . . 743

Chapter 50. Using Data Window Services (DWS) . . . . . . . . . . . 751

Chapter 51. Using DB2 Universal Database . . . . . . . . . . . . . 753

Preparing an XL C/C++ application to request DB2 services . . . . . . . . 753
Using DB2 services and stored procedures with XPLINK . . . . . . . . . 754
Examples of how to use XL C/C++ programs to request DB2 services . . . . 755

Chapter 52. Using Graphical Data Display Manager (GDDM) . . . . . . 761

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 761

Chapter 53. Using the Information Management System (IMS) . . . . . 767

Handling errors . . . . . . . . . . . . . . . . . . . . . . . . 768
Other considerations . . . . . . . . . . . . . . . . . . . . . . 768

Chapter 54. Using the Query Management Facility (QMF) . . . . . . . 775

Example programs . . . . . . . . . . . . . . . . . . . . . . . 775

Part 8. Internationalization: Locales and Character Sets . . . . . . . . . . . 781

Chapter 55. Introduction to locale. . . . . . . . . . . . . . . . . 783

Internationalization in programming languages . . . . . . . . . . . . . 783
Elements of internationalization . . . . . . . . . . . . . . . . . . 783
z/OS XL C/C++ Support for internationalization . . . . . . . . . . . . 784
Locales and localization . . . . . . . . . . . . . . . . . . . . . 784

Chapter 56. Building a locale . . . . . . . . . . . . . . . . . . 787

Limitations of enhanced ASCII . . . . . . . . . . . . . . . . . . . 787
Using the charmap file . . . . . . . . . . . . . . . . . . . . . 788
Locale source files . . . . . . . . . . . . . . . . . . . . . . . 796
Method files . . . . . . . . . . . . . . . . . . . . . . . . . 822
Using the localedef utility. . . . . . . . . . . . . . . . . . . . . 827

Chapter 57. Customizing a locale . . . . . . . . . . . . . . . . . 839

Using the customized locale . . . . . . . . . . . . . . . . . . . 841
Referring explicitly to a customized locale . . . . . . . . . . . . . . 842
Referring implicitly to a customized locale . . . . . . . . . . . . . . 844

Chapter 58. Customizing a time zone . . . . . . . . . . . . . . . 847

Using the TZ or _TZ environment variable to specify time zone . . . . . . 847

x z/OS V1R13.0 XL C/C++ Programming Guide

Relationship between TZ or _TZ and LC_TOD . . . . . . . . . . . . . 848

Chapter 59. Definition of S370 C, SAA C, and POSIX C locales . . . . . 849

Differences between SAA C and POSIX C locales . . . . . . . . . . . 858

Chapter 60. Code set conversion utilities . . . . . . . . . . . . . . 861

The genxlt utility . . . . . . . . . . . . . . . . . . . . . . . . 861
The iconv utility . . . . . . . . . . . . . . . . . . . . . . . . 861
Code conversion functions . . . . . . . . . . . . . . . . . . . . 862
Code set converters supplied . . . . . . . . . . . . . . . . . . . 864
Universal coded character set converters . . . . . . . . . . . . . . . 874

Chapter 61. Coded character set considerations with locale functions 885
Variant character detail . . . . . . . . . . . . . . . . . . . . . 885
Alternate code points . . . . . . . . . . . . . . . . . . . . . . 887
Coding without locale support by using a hybrid coded character set . . . . 887
Coded character set independence in developing applications . . . . . . . 889
Writing source code in coded character set IBM-1047 . . . . . . . . . . 900
Exporting source code to other sites . . . . . . . . . . . . . . . . 900
Converting existing work . . . . . . . . . . . . . . . . . . . . . 901
Considerations with other products and tools . . . . . . . . . . . . . 902

Chapter 62. Bidirectional language support . . . . . . . . . . . . . 903

Bidirectional languages . . . . . . . . . . . . . . . . . . . . . 903

Appendix A. POSIX character set . . . . . . . . . . . . . . . . . 915

Appendix B. Mapping variant characters for z/OS XL C/C++ . . . . . . 919

Specifying the appropriate code page for the compiler . . . . . . . . . . 919
Testing the display of variant characters . . . . . . . . . . . . . . . 919
Inserting and viewing square brackets during an ISPF edit session . . . . . 922

Appendix C. z/OS XL C/C++ code point mappings . . . . . . . . . . 925

Appendix D. Locales supplied with z/OS XL C/C++ . . . . . . . . . . 927

Compiled locales. . . . . . . . . . . . . . . . . . . . . . . . 927
Locale source files . . . . . . . . . . . . . . . . . . . . . . . 947

Appendix E. Charmap files supplied with z/OS XL C/C++ . . . . . . . 953

Appendix F. Examples of charmap and locale definition source . . . . . 957

Charmap file . . . . . . . . . . . . . . . . . . . . . . . . . 957
Locale definition source file . . . . . . . . . . . . . . . . . . . . 967
Locale method source file . . . . . . . . . . . . . . . . . . . . 974

Appendix G. Converting hybrid code to a specific character set . . . . . 977

Sample program . . . . . . . . . . . . . . . . . . . . . . . . 977

Appendix H. Additional Examples. . . . . . . . . . . . . . . . . 987

Memory Management . . . . . . . . . . . . . . . . . . . . . . 987
Calling MVS WTO routines from C . . . . . . . . . . . . . . . . . 996
Listing Partitioned Data Set Members . . . . . . . . . . . . . . . . 998

Appendix I. Application considerations for z/OS UNIX XL C/C++ . . . . 1005

Relationship to DB2 universal database . . . . . . . . . . . . . . . 1005
Application programming environments not supported. . . . . . . . . . 1005

Contents xi
 Support for the Curses library . . . . . . . . . . . . . . . . . . 1005

Appendix J. External variables . . . . . . . . . . . . . . . . . 1007

errno. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
daylight. . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
getdate_err . . . . . . . . . . . . . . . . . . . . . . . . . 1008
h_errno. . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
__loc1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
loc1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
loc2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
locs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
optarg . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
opterr . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
optind . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
optopt . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
signgam . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
stdin . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
stderr . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
stdout . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
t_errno . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010
timezone . . . . . . . . . . . . . . . . . . . . . . . . . . 1010
tzname . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010

Appendix K. Packaging considerations . . . . . . . . . . . . . . 1011

Compiler options . . . . . . . . . . . . . . . . . . . . . . . 1011
Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
Prelinking . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012

Appendix L. Accessibility . . . . . . . . . . . . . . . . . . . 1015

Using assistive technologies . . . . . . . . . . . . . . . . . . . 1015
Keyboard navigation of the user interface . . . . . . . . . . . . . . 1015
z/OS information . . . . . . . . . . . . . . . . . . . . . . . 1015

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . 1019
Policy for unsupported hardware . . . . . . . . . . . . . . . . . 1021
Permission Notice . . . . . . . . . . . . . . . . . . . . . . . 1021
Programming Interface Information . . . . . . . . . . . . . . . . 1021
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . 1022
Standards . . . . . . . . . . . . . . . . . . . . . . . . . . 1022

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . 1025
z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
z/OS XL C/C++ . . . . . . . . . . . . . . . . . . . . . . . . 1025
z/OS Metal C Runtime Library . . . . . . . . . . . . . . . . . . 1025
z/OS Run-Time Library Extensions. . . . . . . . . . . . . . . . . 1025
Debug Tool . . . . . . . . . . . . . . . . . . . . . . . . . 1025
z/OS Language Environment . . . . . . . . . . . . . . . . . . . 1026
Assembler. . . . . . . . . . . . . . . . . . . . . . . . . . 1026
COBOL. . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
PL/I . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
VS FORTRAN . . . . . . . . . . . . . . . . . . . . . . . . 1026
CICS Transaction Server for z/OS . . . . . . . . . . . . . . . . . 1026
DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
IMS/ESA . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
MVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026

xii z/OS V1R13.0 XL C/C++ Programming Guide

QMF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
DFSMS. . . . . . . . . . . . . . . . . . . . . . . . . . . 1027

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029

Contents xiii
xiv z/OS V1R13.0 XL C/C++ Programming Guide
Figures
1. Blocking fixed-length records . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2. Variable-length records on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . 15
3. Memory file example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4. ASA Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5. ungetwc() Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
6. Interleaving I/O with sync_with_stdio() . . . . . . . . . . . . . . . . . . . . . . . 63
7. Interleaving I/O without sync_with_stdio() . . . . . . . . . . . . . . . . . . . . . . 65
8. MVS example of redirecting three standard streams by ddnames . . . . . . . . . . . . . 71
9. Example of using stdout and stderr to share the same file. . . . . . . . . . . . . . . . 72
10. Example of passing text streams . . . . . . . . . . . . . . . . . . . . . . . . . 74
11. Example of passing record I/O streams . . . . . . . . . . . . . . . . . . . . . . 76
12. Example of command line redirection . . . . . . . . . . . . . . . . . . . . . . . 79
13. Generation data group example for C . . . . . . . . . . . . . . . . . . . . . . . 86
14. Generation data group example for C++ . . . . . . . . . . . . . . . . . . . . . . 87
15. How the operating system completes the DCB . . . . . . . . . . . . . . . . . . . 102
16. Example of reading updated records . . . . . . . . . . . . . . . . . . . . . . . 110
17. Example of signal handler . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
18. fldata() Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
19. Unnamed pipes example . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
20. Named pipes example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
21. Example of z/OS UNIX stream input and output functions . . . . . . . . . . . . . . . 137
22. Example of HFS stream input and output functions . . . . . . . . . . . . . . . . . . 141
23. fldata() structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
24. Types and advantages of VSAM data sets . . . . . . . . . . . . . . . . . . . . . 149
25. VSAM example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
26. KSDS example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
27. KSDS example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
28. RRDS example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
29. fldata() structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
30. fldata() structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
31. Removing members of a PDS . . . . . . . . . . . . . . . . . . . . . . . . . 204
32. Renaming members of a PDS . . . . . . . . . . . . . . . . . . . . . . . . . 205
33. fldata() structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
34. Memory file example, part 1 . . . . . . . . . . . . . . . . . . . . . . . . . . 211
35. Memory file example, part 2 . . . . . . . . . . . . . . . . . . . . . . . . . . 212
36. fldata() structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
37. fldata() example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
38. CELQPIPI MSGRTN example . . . . . . . . . . . . . . . . . . . . . . . . . 219
39. __amrc structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
40. Example of printing the __amrc structure . . . . . . . . . . . . . . . . . . . . . 224
41. __amrc2 structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
42. Example of using SIGIOERR . . . . . . . . . . . . . . . . . . . . . . . . . . 230
43. Sample File I/O Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
44. Example of parameter lists For OS linkages . . . . . . . . . . . . . . . . . . . . 245
45. EDCXPRLG macro with an ALIAS statement . . . . . . . . . . . . . . . . . . . . 250
46. Call to an XPLINK routine with no parameters . . . . . . . . . . . . . . . . . . . 251
47. Call to an XPLINK routine with 5 parameters . . . . . . . . . . . . . . . . . . . . 252
48. Establishing the C run-time environment . . . . . . . . . . . . . . . . . . . . . . 253
49. Calling an intermediate C function from Assembler OS linkage . . . . . . . . . . . . . 254
50. Intermediate C routine calling a run-time library function . . . . . . . . . . . . . . . . 254
51. Establishing the XL C/C++ run-time environment. . . . . . . . . . . . . . . . . . . 255
52. Calling an intermediate XL C/C++ function from Assembler using OS linkage . . . . . . . . 255
53. Intermediate XL C/C++ routine calling a run-time library function . . . . . . . . . . . . . 256
Copyright IBM Corp. 1996, 2012 xv
 54. Interface for preinitializable programs . . . . . . . . . . . . . . . . . . . . . . . 258
55. Preinitializing a C program (CCNGCA6) . . . . . . . . . . . . . . . . . . . . . . 262
56. Using the preinitializable program (CCNGCA7) . . . . . . . . . . . . . . . . . . . 264
57. Using the preinitializable program (CCNGCA8) . . . . . . . . . . . . . . . . . . . 265
58. JCL for running a preinitializable C program . . . . . . . . . . . . . . . . . . . . 267
59. Explicit use of a DLL in an application using the dllload() family of functions . . . . . . . . 283
60. Explicit use of a DLL in an application using the dlopen() family of functions . . . . . . . . 285
61. Using #pragma export to create a DLL executable module named BASICIO . . . . . . . . 289
62. Using #pragma export to create the triangle DLL executable module . . . . . . . . . . . 290
63. Using _Export to create the triangle DLL executable module . . . . . . . . . . . . . . 290
64. Summary of DLL and DLL application preparation and usage . . . . . . . . . . . . . . 294
65. Referencing functions and external variables in DLL code . . . . . . . . . . . . . . . 304
66. Pointer Assignment in DLL code. . . . . . . . . . . . . . . . . . . . . . . . . 305
67. Pointer assignment in non-DLL code . . . . . . . . . . . . . . . . . . . . . . . 306
68. File 1. Application A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
69. File 2. Application A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
70. File 3. Application B . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
71. File 4. DLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
72. DLL function pointer call in non-DLL code . . . . . . . . . . . . . . . . . . . . . 309
73. DLL function pointer call in non-DLL code . . . . . . . . . . . . . . . . . . . . . 310
74. C non-DLL code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
75. C DLL code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
76. C++ DLL code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
77. C++ DLL code calling an Assembler function . . . . . . . . . . . . . . . . . . . . 312
78. Comparison of function pointers in non-DLL code . . . . . . . . . . . . . . . . . . 313
79. C DLL code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
80. C non-DLL code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
81. File 1 C DLL code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
82. File 2 C DLL code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
83. File 3 C non-DLL code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
84. Comparison of two DLL function pointers in non-DLL code . . . . . . . . . . . . . . . 315
85. Undefined comparison in DLL code (C or C++) . . . . . . . . . . . . . . . . . . . 316
86. Comparison of function pointers in DLL code (C or C++) . . . . . . . . . . . . . . . . 316
87. Valid comparisons in DLL code (C or C++) . . . . . . . . . . . . . . . . . . . . . 317
88. Application CCNGA2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
89. Application CCNGA2D1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
90. Application CCNGA2D2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
91. Application CCNGA2D3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
92. CCNGA2M1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
93. CCNGA2M2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
94. Comparison of struct li, alignments under ILP32 and LP64 . . . . . . . . . . . . . . . 335
95. Comparison of struct lii alignments under ILP32 and LP64 . . . . . . . . . . . . . . . 336
96. Comparison of struct ili alignments under ILP32 and LP64 . . . . . . . . . . . . . . . 337
97. Example of potential alignment problems when a struct is shared or exchanged among 32-bit
and 64-bit processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
98. Example of user-defined data padding for a structure that is shared or exchanged among 32-bit
and 64-bit processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
99. Referring to thread-specific data . . . . . . . . . . . . . . . . . . . . . . . . . 360
100. Controlling external static . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
101. Making strings constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
102. Example of controllong the memory area . . . . . . . . . . . . . . . . . . . . . 372
103. How to Make String Literals Modifiable . . . . . . . . . . . . . . . . . . . . . . 373
104. Referencing objects in the writable static area, Part 1 . . . . . . . . . . . . . . . . . 374
105. Referencing objects in the writable static area, Part 2 . . . . . . . . . . . . . . . . . 375
106. Arithmetic operators example . . . . . . . . . . . . . . . . . . . . . . . . . . 380
107. Relational operators example . . . . . . . . . . . . . . . . . . . . . . . . . . 381

xvi z/OS V1R13.0 XL C/C++ Programming Guide

108. Getting the total number of bytes occupied by the decimal data type . . . . . . . . . . . 383
109. Getting the total number of digits in the decimal data type . . . . . . . . . . . . . . . 384
110. Getting the number of decimal digits in the decimal data type . . . . . . . . . . . . . . 384
111. Fractional part cannot be represented. . . . . . . . . . . . . . . . . . . . . . . 386
112. Integral part cannot be represented . . . . . . . . . . . . . . . . . . . . . . . 386
113. Conversion to integer type . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
114. Conversion from integral type. . . . . . . . . . . . . . . . . . . . . . . . . . 387
115. Conversion to floating-point type. . . . . . . . . . . . . . . . . . . . . . . . . 388
116. Conversion from floating-point type. . . . . . . . . . . . . . . . . . . . . . . . 388
117. Decimal type Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . 391
118. Output produced by CCNGDC3 . . . . . . . . . . . . . . . . . . . . . . . . . 392
119. Decimal type example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . 393
120. Output produced by CCNGDC4 . . . . . . . . . . . . . . . . . . . . . . . . . 393
121. Example illustrating C++ exception handling/traceback . . . . . . . . . . . . . . . . 405
122. Example illustrating C++ exception handling/traceback . . . . . . . . . . . . . . . . 407
123. Example illustrating signal handling . . . . . . . . . . . . . . . . . . . . . . . 424
124. An electrical analogy showing the socket concept . . . . . . . . . . . . . . . . . . 427
125. A typical stream socket session . . . . . . . . . . . . . . . . . . . . . . . . . 436
126. A typical datagram socket session . . . . . . . . . . . . . . . . . . . . . . . . 437
127. An application using socket() . . . . . . . . . . . . . . . . . . . . . . . . . . 438
128. An application using bind() . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
129. A bind() function using gethostbyname() . . . . . . . . . . . . . . . . . . . . . . 439
130. An application using listen() . . . . . . . . . . . . . . . . . . . . . . . . . . 439
131. An application using connect() . . . . . . . . . . . . . . . . . . . . . . . . . 440
132. An application using accept() . . . . . . . . . . . . . . . . . . . . . . . . . . 440
133. An application using send() and recv() . . . . . . . . . . . . . . . . . . . . . . 441
134. An application using sendto() and recvfrom() . . . . . . . . . . . . . . . . . . . . 441
135. An application using select() . . . . . . . . . . . . . . . . . . . . . . . . . . 442
136. An Application Using ioctl(). . . . . . . . . . . . . . . . . . . . . . . . . . . 443
137. An application using close() . . . . . . . . . . . . . . . . . . . . . . . . . . 443
138. A conceptual overview of the compile, bind, and run steps . . . . . . . . . . . . . . . 445
139. stackadd.cpp file (ccntmp3.cpp) . . . . . . . . . . . . . . . . . . . . . . . . . 459
140. stackops.cpp file (ccntmp4.cpp) . . . . . . . . . . . . . . . . . . . . . . . . . 459
141. stack.h file (ccntmp2.h) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
142. stack.c file (ccntmp1.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
143. stackops.h File (ccntmp5.h) . . . . . . . . . . . . . . . . . . . . . . . . . . 460
144. JCL to compile source Files and TEMPINC destination . . . . . . . . . . . . . . . . 461
145. z/OS UNIX Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
146. Simple and typical use of explicit instantiation declarations . . . . . . . . . . . . . . . 464
147. Erroneous use of explicit instantiation declarations . . . . . . . . . . . . . . . . . . 465
148. _CEE_RUNOPTS behaviour . . . . . . . . . . . . . . . . . . . . . . . . . . 485
149. Environment variables example-Part 1 . . . . . . . . . . . . . . . . . . . . . . 501
150. Environment variables example-Part 2 . . . . . . . . . . . . . . . . . . . . . . 502
151. Interface provided to setup the parameter list . . . . . . . . . . . . . . . . . . . . 522
152. z/Architecture FPC register-rounding mode definitions . . . . . . . . . . . . . . . . . 536
153. Biased exponent type definitions . . . . . . . . . . . . . . . . . . . . . . . . 537
154. Test Data Class masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
155. Test Data Group masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
156. Example of code that requires the global namespace syntax . . . . . . . . . . . . . . 547
157. Definition of saved options information layout . . . . . . . . . . . . . . . . . . . . 556
158. Numeric conversions example . . . . . . . . . . . . . . . . . . . . . . . . . 574
159. Example of using OPTIMIZE(2) . . . . . . . . . . . . . . . . . . . . . . . . . 591
160. Flow of regular compiler processing . . . . . . . . . . . . . . . . . . . . . . . 601
161. IPA compile step processing . . . . . . . . . . . . . . . . . . . . . . . . . . 602
162. IPA link step processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
163. Specifying alternative initialization at link edit . . . . . . . . . . . . . . . . . . . . 623

Figures xvii
164. Sample Freestanding z/OS Routine . . . . . . . . . . . . . . . . . . . . . . . 625
165. Link edit control statements used to build a freestanding z/OS routine . . . . . . . . . . . 626
166. Compile and link using EDCCL . . . . . . . . . . . . . . . . . . . . . . . . . 626
167. Sample reentrant freestanding z/OS routine . . . . . . . . . . . . . . . . . . . . 626
168. Building and running a reentrant freestanding z/OS routine . . . . . . . . . . . . . . . 627
169. System exit example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
170. Example of function used in a persistent C environment . . . . . . . . . . . . . . . . 634
171. Using a persistent C environment . . . . . . . . . . . . . . . . . . . . . . . . 635
172. Example of user routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639
173. Example of application service routine . . . . . . . . . . . . . . . . . . . . . . 640
174. Example of server initialization stub . . . . . . . . . . . . . . . . . . . . . . . 644
175. Example of server message stub-LIFO . . . . . . . . . . . . . . . . . . . . . . 646
176. Example of server message stub-FIFO . . . . . . . . . . . . . . . . . . . . . . 647
177. Example of server message stub-GET . . . . . . . . . . . . . . . . . . . . . . 649
178. Example of server message stub-TERM . . . . . . . . . . . . . . . . . . . . . . 650
179. Example of routine to generate abend . . . . . . . . . . . . . . . . . . . . . . 654
180. Example of routine to get storage . . . . . . . . . . . . . . . . . . . . . . . . 655
181. Example of routine to free storage . . . . . . . . . . . . . . . . . . . . . . . . 656
182. Location of user exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
183. Interface for Assembler user exits . . . . . . . . . . . . . . . . . . . . . . . . 673
184. CEEAUE_FLAGS format . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
185. Exit_list and hook_exit control blocks . . . . . . . . . . . . . . . . . . . . . . . 683
186. Computational independence . . . . . . . . . . . . . . . . . . . . . . . . . . 686
187. Example of a C program running without MTF . . . . . . . . . . . . . . . . . . . 687
188. Processor usage with one parallel function . . . . . . . . . . . . . . . . . . . . . 689
189. Sample program using one parallel function . . . . . . . . . . . . . . . . . . . . 690
190. Processor usage with two parallel function . . . . . . . . . . . . . . . . . . . . . 690
191. Sample program using two parallel functions . . . . . . . . . . . . . . . . . . . . 691
192. Processor use with multiple instances of the same parallel function . . . . . . . . . . . . 692
193. Sample program using multiple instances of the same parallel function . . . . . . . . . . 693
194. Basic MTF layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
195. Identifying Computationally-Independent Code . . . . . . . . . . . . . . . . . . . 698
196. Sample code as a parallel function . . . . . . . . . . . . . . . . . . . . . . . . 698
197. Scheduling instances of a parallel function . . . . . . . . . . . . . . . . . . . . . 699
198. Main task program to call dot product function . . . . . . . . . . . . . . . . . . . 699
199. Sample code to be changed to use MTF . . . . . . . . . . . . . . . . . . . . . 700
200. Sample code (main routine) . . . . . . . . . . . . . . . . . . . . . . . . . . 701
201. Sample code (routine to create parallel functions) . . . . . . . . . . . . . . . . . . 702
202. Sample JCL to compile and link main task program . . . . . . . . . . . . . . . . . 703
203. Sample JCL to compile and link parallel functions . . . . . . . . . . . . . . . . . . 703
204. Source code for EDCMTFS . . . . . . . . . . . . . . . . . . . . . . . . . . 704
205. Example run-time JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
206. Example illustrating how to use EXEC CICS commands . . . . . . . . . . . . . . . . 714
207. Format of data written to a CICS data queue . . . . . . . . . . . . . . . . . . . . 717
208. Example illustrating error handling under CICS . . . . . . . . . . . . . . . . . . . 723
209. Example illustrating how to use EXEC CICS commands . . . . . . . . . . . . . . . . 727
210. Child C program after translation . . . . . . . . . . . . . . . . . . . . . . . . 728
211. JCL to translate and compile a C program . . . . . . . . . . . . . . . . . . . . . 731
212. JCL to translate and compile a C++ program . . . . . . . . . . . . . . . . . . . . 731
213. Prelinking and linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
214. JCL to install z/OS XL C/C++ application programs . . . . . . . . . . . . . . . . . . 734
215. C/370 CALLing CSP under TSO. . . . . . . . . . . . . . . . . . . . . . . . . 736
216. z/OS XL Ctransferring control to CSP under TSO using the XFER/DXFR statement . . . . . . 738
217. CSP CALLing z/OS XL C under TSO . . . . . . . . . . . . . . . . . . . . . . . 740
218. CSP transferring control to z/OS XL C under TSO using the XFER statement . . . . . . . . 741
219. CSP CALLing z/OS XL C under CICS . . . . . . . . . . . . . . . . . . . . . . 744

xviii z/OS V1R13.0 XL C/C++ Programming Guide

220. CSP transferring control to z/OS XL C under CICS using the XFER statement. . . . . .
. 745 .
221. CSP Transferring Control to z/OS XL C under CICS Using the DXFR Statement . . . . .
. 747 .
222. Example using DWS and C++ . . . . . . . . . . . . . . . . . . . . . . .
. 751 .
223. z/OS XL C/C++ Using Data Window Services . . . . . . . . . . . . . . . . . .
. 752 .
224. Using DB2 with C . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 756 .
225. Using DB2 with C++ . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 758 .
226. Example using GDDM and C . . . . . . . . . . . . . . . . . . . . . . . .
. 762 .
227. Example using GDDM and C++ . . . . . . . . . . . . . . . . . . . . . . .
. 764 .
228. C++ Program using IMS. . . . . . . . . . . . . . . . . . . . . . . . . .
. 769 .
229. C Program using IMS . . . . . . . . . . . . . . . . . . . . . . . . . .
. 771 .
230. Header file for IMS example . . . . . . . . . . . . . . . . . . . . . . . .
. 773 .
231. QMF interface example . . . . . . . . . . . . . . . . . . . . . . . . . .
. 775 .
232. C++ Calling a C program that accesses QMF . . . . . . . . . . . . . . . . . .
. 778 .
233. C program that accesses QMF . . . . . . . . . . . . . . . . . . . . . . .
. 779 .
234. Conceptual model of the locale build process . . . . . . . . . . . . . . . . . .
. 787 .
235. Example locale source containing header, body, and trailer . . . . . . . . . . . . .
. 798 .
236. Example LC_CTYPE definition . . . . . . . . . . . . . . . . . . . . . . .
. 802 .
237. Example LC_COLLATE definition . . . . . . . . . . . . . . . . . . . . . .
. 808 .
238. Example LC_MONETARY definition . . . . . . . . . . . . . . . . . . . . .
. 814 .
239. Example LC_NUMERIC definition . . . . . . . . . . . . . . . . . . . . . .
. 815 .
240. Example LC_MESSAGES definition . . . . . . . . . . . . . . . . . . . . .
. 818 .
241. Example LC_TOD definition . . . . . . . . . . . . . . . . . . . . . . . .
. 820 .
242. Example definition of LC_SYNTAX . . . . . . . . . . . . . . . . . . . . . .
. 822 .
243. Expected grammar for method files . . . . . . . . . . . . . . . . . . . . .
. 824 .
244. Referring explicitly to a customized locale . . . . . . . . . . . . . . . . . . .
. 843 .
245. Referring implicitly to a customized locale . . . . . . . . . . . . . . . . . . .
. 844 .
246. Using environment variables to select a locale . . . . . . . . . . . . . . . . .
. 845 .
247. Additional locale categories for POSIX C . . . . . . . . . . . . . . . . . . .
. 850 .
248. Determining which locale is in effect . . . . . . . . . . . . . . . . . . . . .
. 859 .
249. Supplied code set converters . . . . . . . . . . . . . . . . . . . . . . . .
. 864 .
250. Example of hybrid coded character set . . . . . . . . . . . . . . . . . . . .
. 888 .
251. Compile-edit, related to locale function . . . . . . . . . . . . . . . . . . . .
. 890 .
252. Example of __CODESET__ macro . . . . . . . . . . . . . . . . . . . . . .
. 893 .
253. Values of macros __FILETAG__, __LOCALE__, and __CODESET__ . . . . . . . . . .
. 894 .
254. Using the CONVLIT compiler option . . . . . . . . . . . . . . . . . . . . .
. 895 .
255. Example of output when locale option is used. . . . . . . . . . . . . . . . . .
. 898 .
256. Using the pragma convert directive. . . . . . . . . . . . . . . . . . . . . .
. 900 .
257. Example of using a layout string modifier . . . . . . . . . . . . . . . . . . .
. 909 .
258. Example of using the m_setvalues_layout() function . . . . . . . . . . . . . . .
. 909 .
259. Example of bidirectional layout API's . . . . . . . . . . . . . . . . . . . . .
. 913 .
260. Variant characters . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 920 .
261. CCNGMV1: Displaying hexadecimal values . . . . . . . . . . . . . . . . . .
. 921 .
262. Sample ISPF macro for displaying square brackets. . . . . . . . . . . . . . . .
. 923 .
263. Coded character set for Latin 1/Open systems . . . . . . . . . . . . . . . . .
. 925 .
264. Coded character set for APL . . . . . . . . . . . . . . . . . . . . . . . .
. 926 .
265. Charmap file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 957 .
266. Example locale definition source file . . . . . . . . . . . . . . . . . . . . .
. 968 .
267. Example locale method source file . . . . . . . . . . . . . . . . . . . . . .
. 975 .
268. Converting hybrid C syntax from code page IBM-1047 . . . . . . . . . . . . . .
. 977 .
269. Debuggable malloc()/calloc()/realloc()/free() example . . . . . . . . . . . . . . .
. 987 .
270. Main routine - debuggable malloc()/calloc()/realloc()/free() example . . . . . . . . . .
. 988 .
271. Performing a Write To Operator . . . . . . . . . . . . . . . . . . . . . . .
. 997 .
272. Performing a Write To Operator . . . . . . . . . . . . . . . . . . . . . . .
. 998 .
273. Example of Listing All Members of a PDS . . . . . . . . . . . . . . . . . . .
. 999 .
274. ccngip2.h Header file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003

Figures xix
xx z/OS V1R13.0 XL C/C++ Programming Guide
Tables
1. Syntax examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
2. C control to ASA characters . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3. Summary of prototype functions . . . . . . . . . . . . . . . . . . . . . . . . . 25
4. Kinds of I/O supported by z/OS XL C/C++ . . . . . . . . . . . . . . . . . . . . . 27
5. I/O categories and environments that support them . . . . . . . . . . . . . . . . . . 28
6. fopen() defaults for LRECL and BLKSIZE when creating OS files . . . . . . . . . . . . . 33
7. C control to ASA characters translation table . . . . . . . . . . . . . . . . . . . . 47
8. Manipulating wide character arrays . . . . . . . . . . . . . . . . . . . . . . . . 59
9. Standard C and C++ streams . . . . . . . . . . . . . . . . . . . . . . . . . . 61
10. z/OS XL C/C++ Redirection symbols . . . . . . . . . . . . . . . . . . . . . . . 67
11. Output destinations under z/OS XL C/C++ . . . . . . . . . . . . . . . . . . . . . 68
12. z/OS XL C/C++ Interleaved output . . . . . . . . . . . . . . . . . . . . . . . . 69
13. Association of standard streams with ddnames . . . . . . . . . . . . . . . . . . . . 71
14. Standard stream behavior differences . . . . . . . . . . . . . . . . . . . . . . . 77
15. PDSE and PDS differences . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
16. Rules for possible concatenations . . . . . . . . . . . . . . . . . . . . . . . . 90
17. Other devices supported for input and output . . . . . . . . . . . . . . . . . . . . 94
18. Parameters for the fopen() and freopen() functions for z/OS OS I/O . . . . . . . . . . . . 95
19. fopen() defaults for LRECL and BLKSIZE when creating OS files . . . . . . . . . . . . 102
20. C control to ASA characters . . . . . . . . . . . . . . . . . . . . . . . . . . 107
21. Parameters for the fopen() and freopen() functions for z/OS UNIX file system I/O . . . . . . 127
22. Summary of VSAM data set characteristics and allowable I/O operations. . . . . . . . . . 151
23. Keywords for the fopen() and freopen() functions for VSAM data sets . . . . . . . . . . . 155
24. Summary of VSAM record I/O operations . . . . . . . . . . . . . . . . . . . . . 164
25. AMODE31 application XADDR support . . . . . . . . . . . . . . . . . . . . . . 167
26. Summary of fseek() and ftell() parameters in text and binary . . . . . . . . . . . . . . 170
27. Summary of VSAM text I/O operations . . . . . . . . . . . . . . . . . . . . . . 171
28. Summary of VSAM binary I/O operations . . . . . . . . . . . . . . . . . . . . . 171
29. Keywords for the fopen() and freopen() functions for terminal I/O. . . . . . . . . . . . . 190
30. Keywords for the fopen() and freopen() functions for memory file I/O . . . . . . . . . . . 201
31. __last_op codes and diagnosis information . . . . . . . . . . . . . . . . . . . . . 225
32. Linkage used by C or C++ Interlanguage Programs . . . . . . . . . . . . . . . . . 238
33. Comparison of non-XPLINK and XPLINK register conventions. . . . . . . . . . . . . . 246
34. Load service routine parameters. . . . . . . . . . . . . . . . . . . . . . . . . 271
35. Delete service routine parameters . . . . . . . . . . . . . . . . . . . . . . . . 272
36. Get-storage service routine parameters . . . . . . . . . . . . . . . . . . . . . . 272
37. Free-storage service routine parameters . . . . . . . . . . . . . . . . . . . . . . 273
38. Exception router service routine parameters . . . . . . . . . . . . . . . . . . . . 273
39. Attention router service routine parameters . . . . . . . . . . . . . . . . . . . . . 275
40. Attention handler parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 275
41. Message router service routine parameters. . . . . . . . . . . . . . . . . . . . . 276
42. Summary of DLL concepts and terms . . . . . . . . . . . . . . . . . . . . . . . 280
43. Example programs to demonstrate compiling options . . . . . . . . . . . . . . . . . 302
44. Examples of how to compile two source modules and list result . . . . . . . . . . . . . 302
45. Referencing functions and external variables . . . . . . . . . . . . . . . . . . . . 303
46. Comparison of ILP32 and LP64 addressing capabilities . . . . . . . . . . . . . . . . 325
47. Comparison of ILP32 and LP64 data models . . . . . . . . . . . . . . . . . . . . 325
48. ILP32 and LP64 type size comparisons for signed and unsigned data types . . . . . . . . 326
49. Example of diagnostic messages generated from code that is not ready to be migrated from
ILP32 to LP64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
50. Comparison of ILP32 and LP64 processing and run-time options. . . . . . . . . . . . . 332
51. Comparison of data structure member lengths produced from the same code . . . . . . . . 334
52. Example of possible change of result after conversion from signed number to unsigned long 338
Copyright IBM Corp. 1996, 2012 xxi
 53. Example of possible change of result after conversion from unsigned int variable to signed long 338
54. Example of possible change of result after conversion from signed long long variable to signed
long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
55. Example of possible change of result after conversion from unsigned long long variable to
unsigned long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
56. Example of possible change of result after conversion from signed long long variable to signed
long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
57. Example of possible change of result after conversion from unsigned long long variable to signed
long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
58. Examples of pointer declarations that can be made under LP64 . . . . . . . . . . . . . 341
59. Example of source code that explicitly converts an integer to a pointer . . . . . . . . . . 343
60. Example of truncation problem with a pointer cast conversion . . . . . . . . . . . . . . 343
61. Type of an integer constant . . . . . . . . . . . . . . . . . . . . . . . . . . 344
62. An attempt to share pointers between 32-bit and 64-bit processes . . . . . . . . . . . . 345
63. Example of unexpected behavior resulting from use of unsuffixed numbers . . . . . . . . . 346
64. Example of using LONG_MAX macros in a printf subroutine . . . . . . . . . . . . . . 347
65. Example of source code that successfully shares pointers between ILP32 and LP64 programs 349
66. Functions used in creating multi-threaded applications . . . . . . . . . . . . . . . . 353
67. Functions to change default attributes. . . . . . . . . . . . . . . . . . . . . . . 353
68. Functions used to control individual threads in a multi-threaded environment . . . . . . . . 354
69. Functions that allow for synchronization between threads . . . . . . . . . . . . . . . 355
70. Functions used with thread-specific data. . . . . . . . . . . . . . . . . . . . . . 359
71. Cancellation point summary . . . . . . . . . . . . . . . . . . . . . . . . . . 363
72. Functions used to control cancellability . . . . . . . . . . . . . . . . . . . . . . 363
73. Functions used for cleanup purposes . . . . . . . . . . . . . . . . . . . . . . . 364
74. Declarations of fixed-point decimal constants . . . . . . . . . . . . . . . . . . . . 378
75. Examples of Fixed-Point decimal constants and their attributes . . . . . . . . . . . . . 378
76. Intermediate results (without overflow in n or p) . . . . . . . . . . . . . . . . . . . 382
77. Intermediate results (in the general form) . . . . . . . . . . . . . . . . . . . . . 382
78. Operators used with decimal data types . . . . . . . . . . . . . . . . . . . . . . 384
79. C/C++ functions that support floating-point . . . . . . . . . . . . . . . . . . . . . 399
80. Special purpose C/C++ functions that support floating-point. . . . . . . . . . . . . . . 401
81. Functions that establish a signal handler . . . . . . . . . . . . . . . . . . . . . 412
82. Other signal-related functions . . . . . . . . . . . . . . . . . . . . . . . . . . 412
83. Hardware exceptions - Default run-time messages and system actions . . . . . . . . . . 417
84. Software exceptions - Default run-time messages and system actions with POSIX(OFF) 417
85. Default signal processing with POSIX(ON) . . . . . . . . . . . . . . . . . . . . . 419
86. Original versions of fdlibm functions . . . . . . . . . . . . . . . . . . . . . . . 494
87. Standard general-instruction prototypes . . . . . . . . . . . . . . . . . . . . . . 503
88. Built-in general-instruction prototypes . . . . . . . . . . . . . . . . . . . . . . . 505
89. PLO helper macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
90. Compare and load prototypes . . . . . . . . . . . . . . . . . . . . . . . . . 523
91. Compare and swap prototypes . . . . . . . . . . . . . . . . . . . . . . . . . 524
92. Double compare and swap prototypes . . . . . . . . . . . . . . . . . . . . . . 524
93. Compare and swap and store prototypes . . . . . . . . . . . . . . . . . . . . . 525
94. Compare swap and double store prototypes . . . . . . . . . . . . . . . . . . . . 525
95. Compare and swap and triple store prototypes . . . . . . . . . . . . . . . . . . . 526
96. Decimal instruction prototypes . . . . . . . . . . . . . . . . . . . . . . . . . 527
97. Floating-point instruction prototypes . . . . . . . . . . . . . . . . . . . . . . . 528
98. Decimal floating-point instruction prototypes for IEEE operations . . . . . . . . . . . . . 529
99. Decimal floating-point instruction prototypes for IEEE . . . is operations . . . . . . . . . . 531
100. Decimal floating-point instruction prototypes for IBM Instructions . . . . . . . . . . . . . 532
101. Hexadecimal floating-point instruction prototypes . . . . . . . . . . . . . . . . . . 538
102. Binary floating-point instruction prototypes . . . . . . . . . . . . . . . . . . . . . 539
103. Built-in functions for transactional memory . . . . . . . . . . . . . . . . . . . . . 542
104. SUSv3 options and option groups . . . . . . . . . . . . . . . . . . . . . . . . 550

xxii z/OS V1R13.0 XL C/C++ Programming Guide

105. Symbols not supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
106. Examples of acceptable alias types . . . . . . . . . . . . . . . . . . . . . . . 568
107. Comparison of code generated with the ANSIALIAS and NOANSIALIAS options . . . . . . . 569
108. Example of using temporaries to remove aliasing effects. . . . . . . . . . . . . . . . 571
109. Referencing data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
110. Pragmas that affect performance . . . . . . . . . . . . . . . . . . . . . . . . 581
111. C-library built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
112. Platform-specific built-in functions . . . . . . . . . . . . . . . . . . . . . . . . 584
113. Examples of optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
114. Parts used for freestanding applications . . . . . . . . . . . . . . . . . . . . . . 628
115. Parts used by exit routines . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
116. Parts used by persistent environments . . . . . . . . . . . . . . . . . . . . . . 637
117. Parts used by or with application server routines. . . . . . . . . . . . . . . . . . . 653
118. Abend and reason codes specific to system programming environments . . . . . . . . . . 657
119. Summary of types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
120. User exits supported under z/OS Language Environment . . . . . . . . . . . . . . . 668
121. Sample Assembler user exits for z/OS Language Environment . . . . . . . . . . . . . 670
122. Interaction of Assembler user exits . . . . . . . . . . . . . . . . . . . . . . . . 681
123. Common data types between z/OS XL C and CSP . . . . . . . . . . . . . . . . . . 735
124. PCB generated for C program under TSO and IMS. . . . . . . . . . . . . . . . . . 769
125. PCB generated for C or C++ program under TSO and IMS . . . . . . . . . . . . . . . 769
126. Characters in portable character set and corresponding symbolic names . . . . . . . . . . 788
127. Locale object prefix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
128. Supported language-territory names and LT codes for EBCDIC locales . . . . . . . . . . 830
129. Supported language-territory names and LT codes for ASCII locales . . . . . . . . . . . 832
130. Supported codeset names and CC codes . . . . . . . . . . . . . . . . . . . . . 835
131. C macros used as synonyms for special locale names . . . . . . . . . . . . . . . . 838
132. Referencing data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
133. Coded character set conversion tables . . . . . . . . . . . . . . . . . . . . . . 865
134. UCS-2 converter names. . . . . . . . . . . . . . . . . . . . . . . . . . . . 876
135. Mappings of 13 PPCS variant characters . . . . . . . . . . . . . . . . . . . . . 886
136. Mappings of Hex encoding of 13 PPCS variant characters . . . . . . . . . . . . . . . 886
137. Layout attribute and values . . . . . . . . . . . . . . . . . . . . . . . . . . 905
138. Referencing data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927
139. Compiled EBCDIC locales supplied with z/OS XL C/C++. . . . . . . . . . . . . . . . 928
140. Compiled ASCII locales supplied with z/OS XL C/C++. . . . . . . . . . . . . . . . . 937
141. ASCII locale object names and method files in the z/OS UNIX file system . . . . . . . . . 943
142. Locale source files supplied with z/OS XL C/C++ . . . . . . . . . . . . . . . . . . 947
143. Coded character set names and corresponding primary country/territory . . . . . . . . . . 953

Tables xxiii
xxiv z/OS V1R13.0 XL C/C++ Programming Guide
About this document
This document provides information about implementing programs that are written
in C and C++. It contains advanced guidelines and information for developing C and
C++ programs to run under z/OS.

Note: As of z/OS V1R7, the z/OS C/C++ compiler has been rebranded to z/OS XL
C/C++.

This document contains terminology, maintenance, and editorial changes. Technical

changes or additions to the text and illustrations are indicated by a vertical line (|) to
the left of the change.

You may notice changes in the style and structure of some of the contents in this
document; for example, headings that use uppercase for the first letter of initial
words only, and procedures that have a different look and format. The changes are
ongoing improvements to the consistency and retrievability of information in our
documents.

How to read syntax diagrams

This section describes how to read syntax diagrams. It defines syntax diagram
symbols, items that may be contained within the diagrams (keywords, variables,
delimiters, operators, fragment references, operands) and provides syntax examples
that contain these items.

Syntax diagrams pictorially display the order and parts (options and arguments) that
comprise a command statement. They are read from left to right and from top to
bottom, following the main path of the horizontal line.

For users accessing the Information Center using a screen reader, syntax diagrams
are provided in dotted decimal format.

Symbols
The following symbols may be displayed in syntax diagrams:
Symbol Definition
 Indicates the beginning of the syntax diagram.
 Indicates that the syntax diagram is continued to the next line.
 Indicates that the syntax is continued from the previous line.
 Indicates the end of the syntax diagram.

Syntax items
Syntax diagrams contain many different items. Syntax items include:
v Keywords - a command name or any other literal information.
v Variables - variables are italicized, appear in lowercase, and represent the name
of values you can supply.
v Delimiters - delimiters indicate the start or end of keywords, variables, or
operators. For example, a left parenthesis is a delimiter.
v Operators - operators include add (+), subtract (-), multiply (*), divide (/), equal
(=), and other mathematical operations that may need to be performed.

Copyright IBM Corp. 1996, 2012 xxv

 v Fragment references - a part of a syntax diagram, separated from the diagram to
show greater detail.
v Separators - a separator separates keywords, variables or operators. For
example, a comma (,) is a separator.

Note: If a syntax diagram shows a character that is not alphanumeric (for example,
parentheses, periods, commas, equal signs, a blank space), enter the character as
part of the syntax.

Keywords, variables, and operators may be displayed as required, optional, or

default. Fragments, separators, and delimiters may be displayed as required or
optional.
Item type Definition
Required Required items are displayed on the main path of the horizontal
line.
Optional Optional items are displayed below the main path of the horizontal
line.
Default Default items are displayed above the main path of the horizontal
line.

Syntax examples
The following table provides syntax examples.
Table 1. Syntax examples
Item Syntax example
Required item.
 KEYWORD required_item 
Required items appear on the main path of the
horizontal line. You must specify these items.
Required choice.
 KEYWORD required_choice1 
A required choice (two or more items) appears
in a vertical stack on the main path of the
required_choice2
horizontal line. You must choose one of the
items in the stack.
Optional item.
 KEYWORD 
Optional items appear below the main path of
the horizontal line.
optional_item

Optional choice.
 KEYWORD 
An optional choice (two or more items) appears
in a vertical stack below the main path of the
optional_choice1
horizontal line. You may choose one of the optional_choice2
items in the stack.
Default.
default_choice1
Default items appear above the main path of
the horizontal line. The remaining items
 KEYWORD 
(required or optional) appear on (required) or optional_choice2
below (optional) the main path of the horizontal optional_choice3
line. The following example displays a default
with optional items.
Variable.
 KEYWORD variable 
Variables appear in lowercase italics. They
represent names or values.

xxvi z/OS V1R13.0 XL C/C++ Programming Guide

Table 1. Syntax examples (continued)
Item Syntax example
Repeatable item.

An arrow returning to the left above the main

path of the horizontal line indicates an item that
can be repeated.  KEYWORD  repeatable_item 

A character within the arrow means you must ,

separate repeated items with that character.
 KEYWORD  repeatable_item 
An arrow returning to the left above a group of
repeatable items indicates that one of the items
can be selected,or a single item can be
repeated.
Fragment.
 KEYWORD fragment 
The fragment symbol indicates that a labelled
group is described below the main syntax
fragment:
diagram. Syntax is occasionally broken into
fragments if the inclusion of the fragment would
overly complicate the main syntax diagram. ,required_choice1
,default_choice
,required_choice2
,optional_choice

Related z/OS XL C/C++ information

The following list shows where to find related z/OS XL C/C++ information:
v Softcopy examples and related documents information in z/OS XL C/C++ User's
Guide
v z/OS XL C/C++ home page at: www.ibm.com/software/awdtools/czos/
v z/OS XL C/C++ documents in PDF and HTML formats at: www.ibm.com/software/
awdtools/czos/library/

Where to find more information

For an overview of the information associated with z/OS, see z/OS Information
Roadmap.

Information updates on the web

For the latest information updates that have been provided in PTF cover letters and
documentation APARs for z/OS, see the online document at: http://
publibz.boulder.ibm.com/cgi-bin/bookmgr_OS390/Shelves/ZDOCAPAR

This document is updated weekly and lists documentation changes before they are
incorporated into z/OS publications.

The z/OS Basic Skills Information Center

The z/OS Basic Skills Information Center is a Web-based information resource
intended to help users learn the basic concepts of z/OS, the operating system that
runs most of the IBM mainframe computers in use today. The Information Center is
designed to introduce a new generation of Information Technology professionals to
basic concepts and help them prepare for a career as a z/OS professional, such as
a z/OS system programmer.

About this document xxvii

 Specifically, the z/OS Basic Skills Information Center is intended to achieve the
following objectives:
v Provide basic education and information about z/OS without charge
v Shorten the time it takes for people to become productive on the mainframe
v Make it easier for new people to learn z/OS.

To access the z/OS Basic Skills Information Center, open your Web browser to the
following Web site, which is available to all users (no login required):
http://publib.boulder.ibm.com/infocenter/zos/basics/index.jsp

xxviii z/OS V1R13.0 XL C/C++ Programming Guide

How to send your comments to IBM
We appreciate your input on this publication. Feel free to comment on the clarity,
accuracy, and completeness of the information or give us any other feedback that
you might have.

Use one of the following methods to send us your comments:

1. Send an email to [email protected]
2. Visit the Contact z/OS web page at http://www.ibm.com/systems/z/os/zos/
webqs.html
3. Mail the comments to the following address:
IBM Corporation
Attention: MHVRCFS Reader Comments
Department H6MA, Building 707
2455 South Road
Poughkeepsie, NY 12601-5400
U.S.A.
4. Fax the comments to us as follows:
From the United States and Canada: 1+845+432-9405
From all other countries: Your international access code +1+845+432-9405

Include the following information:

v Your name and address
v Your email address
v Your telephone or fax number
v The publication title and order number:
z/OS V1R13.0 XL C/C++ Programming Guide
SC09-4765-13
v The topic and page number related to your comment
v The text of your comment.
When you send comments to IBM, you grant IBM a nonexclusive right to use or
distribute your comments in any way it believes appropriate without incurring any
obligation to you.

IBM or any other organizations will only use the personal information that you
supply to contact you about the issues that you submit.

If you have a technical problem

Do not use the feedback methods listed above. Instead, do one of the following:
v Contact your IBM service representative
v Call IBM technical support
v Visit the IBM support portal at http://www.ibm.com/systems/z/support/

Copyright IBM Corp. 1996, 2012 xxix

xxx z/OS V1R13.0 XL C/C++ Programming Guide
Summary of changes
This document contains terminology, maintenance, and editorial changes, including
changes to improve consistency and retrievability. Technical changes or additions to
the text and illustrations are indicated by a vertical line to the left of the change.

Changes made in z/OS Version 1 Release 13

The book contains information that was previously presented in z/OS XL C/C++
Programming Guide, SC09-4765-11, which supports z/OS Version 1 Release 12.

New information:
v A new environment variable has been added to provide enhanced I/O abend
recovery support; see _EDC_IO_ABEND on page 494 for more information.
v The abend= parameter has been added to the fopen() and freopen() functions;
this parameter controls if the run-time library should attempt to recover from an
abend that is issued during an I/O operation. In addition, the rlse and norlse
keywords have been added to the space= parameter. See Table 18 on page 95
for more information.
v Support for 10 new text locales has been added; see Table 140 on page 937 for
details.
v Support for new standard and built-in general instruction prototypes has been
added; for more information, see Table 88 on page 505.
v New built-in functions have been added to mark the beginning and end of
transactions, and to diagnose the reasons for failure. For detailed information,
see Built-in functions for transaction execution on page 541.

Changed information:
v Information about the preservation of the contents of high registers has been
added to Get-storage service routine on page 272 and Free-storage service
routine on page 273.
v Information about large file support has been clarified in Chapter 10, Performing
OS I/O operations, on page 81.
v Figure 157 on page 556 (saved options information layout) has been updated.
v Reference information about using UCS-2 codeset conversion has been updated
in Codeset conversion using UCS-2 on page 880.

Deleted information:
v Information about using fseek() and ftell() in binary files been removed.
v Information about default signal processing with POSIX(ON) for the SIGDCE
event has been removed.

Changes made in z/OS Version 1 Release 12

The book contains information that was previously presented in z/OS XL C/C++
Programming Guide, SC09-4765-10, which supports z/OS Version 1 Release 11.

New information:
v Information has been added for the z/OS XL C/C++ support for accessing an
extended addressable VSAM KSDS data set through an alternate index. For the
details, see Chapter 12, Performing VSAM I/O operations, on page 147.

Copyright IBM Corp. 1996, 2012 xxxi

 v Information has been added for the z/OS XL C/C++ support for large format
sequential DASD data sets (>64K tracks per volume). For the details, see
Chapter 10, Performing OS I/O operations, on page 81.
v The feature test macro _TR1_C99 has been added to control exposure to the
C++ TR1 C99 name space. For the details, see Feature test macros that control
C99 interfaces in XL C++ applications on page 545.
v z/OS XL C/C++ supports opening DDNAMEs that have been dynamically
allocated with the XTIOT, UCB nocapture, and DSAB-above-the-line options
specified in the SVC99 parameters.
v The following environment variables have been added; for the details, see
Chapter 32, Using environment variables, on page 467.
_CEE_ENVFILE_COMMENT
_CEE_ENVFILE_CONTINUATION
_CEE_REALLOC_CONTROL.
_EDC_FLUSH_STDOUT_PIPE
_EDC_FLUSH_STDOUT_SOCKET
_EDC_PTHREAD_YIELD_MAX
__POSIX_TMPNAM
v The default Slovakian locales have been changed to point to the @euro version
of the locale instead of the @preeuro version.

Changed information:
v Updated getdate_err on page 1008 in Appendix J, External variables, on page
1007.
v An restriction has been added to the _BPXK_AUTOCVT and _BPXK_CCSIDS
environment variables in Chapter 32, Using environment variables, on page
467.
v Updated Chapter 58, Customizing a time zone, on page 847.
v The "Readers' Comments - We'd Like to Hear from You" section at the back of
this publication has been replaced with a new section How to send your
comments to IBM on page xxix. The hardcopy mail-in form has been replaced
with a page that provides information appropriate for submitting readers
comments to IBM.

Changes made in z/OS Version 1 Release 11

The book contains information previously presented in z/OS XL C/C++
Programming Guide, SC09-4765-09, which supports z/OS Version 1 Release 10.

New information:
v Information has been added for the support of z/OS XL C/C++ compiler direction.
Using built-in library functions and macros on page 577 has been updated to
indicate replacing wcsxxx() functions with their corresponding wmemxxx()
functions, whenever possible.
The C-library built-in functions described in Table 111 on page 583 have been
updated with new information.
Using functions in the system programming C environment on page 620 has
been updated to indicate that 4 new functions are available as built-in.
v A new compiled ASCII locale has been added to Table 140 on page 937.
v File I/O trace on page 232 and Locating the file I/O trace on page 233 has
been added to Chapter 18, Debugging I/O programs, on page 221.

xxxii z/OS V1R13.0 XL C/C++ Programming Guide

v Two new environment variables _EDC_IO_TRACE on page 495 and
_EDC_CONTEXT_GUARD on page 488 have been added.
v Chapter 17, CELQPIPI MSGRTN file operations, on page 217 has been added.
v Language Environment provides I/O support within the C/C++ run-time library for
extended format sequential data sets that are in the extended addressing space
on extended address volumes (EAVs).
v Using explicit instantiation declarations (C++0x only) on page 463 has been
added to indicate that the extern templates feature introduced in C++0x is
available as C++ template.

Changed information:
v Updates have been made to fldata() behavior on page 119.
v IEEE binary and decimal floating-point can be supported in a CICS environment.
See Using IEEE floating-point on page 398.
v Table 79 on page 399 has been updated with more C/C++ functions that support
floating point.
v A note in Chapter 10, Performing OS I/O operations, on page 81 has been
updated to indicate z/OS XL C/C++ does not support non-VSAM keyed data sets.
v Updates have been made to Identifying hardware and software signals on page
415 and Default handling of signals on page 418.
v Updates have been made to Overview of the layout functions on page 904 and
Using the layout functions on page 909.

Summary of changes xxxiii

xxxiv z/OS V1R13.0 XL C/C++ Programming Guide
Part 1. Introduction
This part discusses introductory concepts on the z/OS XL C/C++ feature.
Specifically, it discusses the following:
v Chapter 1, About IBM z/OS XL C/C++, on page 3

Copyright IBM Corp. 1996, 2012 1

2 z/OS V1R13.0 XL C/C++ Programming Guide
Chapter 1. About IBM z/OS XL C/C++
For an introduction to z/OS XL C/C++ and for information about changes to z/OS
XL C/C++ for the current release, see About IBM z/OS XL C/C++ in z/OS XL C/C++
User's Guide.

Copyright IBM Corp. 1996, 2012 3

4 z/OS V1R13.0 XL C/C++ Programming Guide
Part 2. Input and Output
This part describes the models of input and output available with IBM z/OS XL
C/C++.

The C run-time functions are available if the corresponding C header files are used.
C I/O can be used by C++ when the C run-time library functions are used.

The following references provide a description and examples of I/O streams:

v Chapter 2, Introduction to C and C++ input and output, on page 7
v Chapter 3, Understanding models of C I/O, on page 9
v Chapter 4, Using the Standard C++ Library I/O Stream Classes, on page 21
v Chapter 5, Opening files, on page 25
v Chapter 6, Buffering of C streams, on page 45
v Chapter 7, Using ASA text files, on page 47
v Chapter 8, z/OS XL C Support for the double-byte character set, on page 51
v Chapter 9, Using C and C++ standard streams and redirection, on page 61
v Chapter 10, Performing OS I/O operations, on page 81
v Chapter 11, Performing z/OS UNIX file system I/O operations, on page 123
v Chapter 12, Performing VSAM I/O operations, on page 147
v Chapter 13, Performing terminal I/O operations, on page 189
v Chapter 14, Performing memory file and hiperspace I/O operations, on page
199
v Chapter 15, Performing CICS Transaction Server I/O operations, on page 213
v Chapter 16, Language Environment Message file operations, on page 215
v Chapter 17, CELQPIPI MSGRTN file operations, on page 217
v Chapter 18, Debugging I/O programs, on page 221

Copyright IBM Corp. 1996, 2012 5

6 z/OS V1R13.0 XL C/C++ Programming Guide
Chapter 2. Introduction to C and C++ input and output
This chapter provides you with a general introduction to C and C++ input and
output (I/O). Three types of C and C++ input and output are discussed in this
chapter:
v text streams
v binary streams
v record I/O

Types of C and C++ input and output

A stream is a flow of data elements that are transmitted or intended for transmission
in a defined format. A record is a set of data elements treated as a unit, and a file
(or data set) is a named set of records that is stored or processed as a unit.

The z/OS XL C/C++ compiler supports three types of input and output: text streams,
binary streams, and record I/O. Text and binary streams are both ANSI standards;
record I/O is an extension for z/OS XL C. Record I/O is not supported by either the
USL I/O Stream Class Library or the Standard C++ I/O stream classes.

Note: If you have written data in one of these three types and try to read it as
another type (for example, reading a binary file in text mode), you may not get the
behavior that you expect.

Text streams
Text streams contain printable characters and, depending on the type of file, control
characters. Text streams are organized into lines. Each line ends with a control
character, usually a new-line. The last record in a text file may or may not end with
a control character, depending on what kind of file you are using. Text files
recognize the following control characters:
\a Alarm.
\b Backspace.
\f Form feed.
\n New-line.
\r Carriage return.
\t Horizontal tab character.
\v Vertical tab character.
\x0E DBCS shift-out character. Indicates the beginning of a DBCS string, if
MB_CUR_MAX>1 in the definition of the locale that is in effect. For more
information about __MBCURMAX, see Chapter 8, z/OS XL C Support for the
double-byte character set, on page 51.
\x0F DBCS shift-in character. Indicates the end of a DBCS string, if
MB_CUR_MAX>1 in the definition of the locale that is in effect. For more
information about __MBCURMAX, see Chapter 8, z/OS XL C Support for the
double-byte character set, on page 51.

Control characters behave differently in terminal files (see Chapter 13, Performing
terminal I/O operations, on page 189) and ASA files (see Chapter 7, Using ASA
text files, on page 47).

Copyright IBM Corp. 1996, 2012 7

Binary streams
Binary streams contain a sequence of bytes. For binary streams, the library does
not translate any characters on input or output. It treats them as a continuous
stream of bytes, and ignores any record boundaries. When data is written out to a
record-oriented file, it fills one record before it starts filling the next. Streams in the
z/OS UNIX file system follow the binary model, regardless of whether they are
opened for text, binary, or record I/O. You can simulate record I/O by using new-line
characters as record boundaries.

Record I/O
Record I/O is an extension to the ISO standard. For files opened in record format,
z/OS XL C/C++ reads and writes one record at a time. If you try to write more data
to a record than the record can hold, the data is truncated. For record I/O, z/OS XL
C/C++ allows only the use of fread() and fwrite() to read and write to files. Any
other functions (such as fprintf(), fscanf(), getc(), and putc()) will fail. For
record-oriented files, records do not change size when you update them. If the new
record has fewer characters than the original record, the new data fills the first n
characters, where n is the number of characters of the new data. The record will
remain the same size, and the old characters (those after n) are left unchanged. A
subsequent update begins at the next boundary. For example, if you have the string
"abcdefgh":

a b c d e f g h

and you overwrite it with the string "1234", the record will look like this:

1 2 3 4 e f g h

z/OS XL C/C++ record I/O is binary. That is, it does not interpret any of the data in
a record file and therefore does not recognize control characters. The only
exception is for file categories that do not support records, such as the UNIX file
system (also known as POSIX I/O). For these files, z/OS XL C/C++ uses new-line
characters as record boundaries.

8 z/OS V1R13.0 XL C/C++ Programming Guide

Chapter 3. Understanding models of C I/O
This chapter describes z/OS XL C/C++ support for the major models of C I/O:
v The record model
v The byte stream model

The next chapter (Chapter 4, Using the Standard C++ Library I/O Stream Classes,
on page 21) describes a third major model, the object-oriented model.

The record model for C I/O

Almost all the kinds of I/O that z/OS XL C/C++ supports use this model. The only
ones that do not are z/OS UNIX file system, memory file, and Hiperspace I/O.

The record model consists of the following:

v A record, which is the unit of data transmitted to and from a program.
v A block, which is the unit of data transmitted to and from a device. Each block
may contain one or more records.

In the record model of I/O, records and blocks have the following attributes:
RECFM Specifies the format of the data or how the data is organized on the
physical device.
LRECL Specifies the length of logical records (as opposed to physical
ones). Variable length records include a count field that is normally
not available to the programmer.
BLKSIZE Specifies the length of physical records (blocks on the physical
device).

Record formats
Use the RECFM attribute to specify the record format. The records in a file using the
record model have one of the following formats:
v Fixed-length (F)
v Variable-length (V)
v Undefined-length (U)

Note: z/OS XL C/C++ does not support Format-D files.

These formats support the following additional options for RECFM. The record formats
and the options associated with them are discussed in the following sections.
A Specifies that the file contains ASA control characters.
B Specifies that a file is blocked. A blocked file can have more than one
record in each block.
M Specifies that the file contains machine control characters.
S Specifies that a file is either in standard format (if it is fixed) or spanned (if it
is variable). In a standard file, every block must be full before another one
starts. In a spanned file, a record can be longer than a block. If it is, the
record is divided into segments and stored in consecutive blocks.

Copyright IBM Corp. 1996, 2012 9

 Not all the I/O categories (listed in Table 4 on page 27) support all of these
attributes. Depending on what category you are using, z/OS XL C/C++ ignores or
simulates attributes that do not apply. For more information on the record formats
and the options supported for each I/O category, see Chapter 5, Opening files, on
page 25.

Fixed-format records
These are the formats you can specify for RECFM if you want to use a fixed-format
file:
F Fixed-length, unblocked
FA Fixed-length, ASA print-control characters
FB Fixed-length, blocked
FM Fixed-length, machine print-control codes
FS Fixed-length, unblocked, standard
FBA Fixed-length, blocked, ASA print-control characters
FBM Fixed-length, blocked, machine print-control codes
FBS Fixed-length, blocked, standard
FSA Fixed-length, unblocked, standard, ASA print-control characters
FSM Fixed-length, unblocked, standard, machine print-control codes
FBSM Fixed-length, blocked, standard, machine print-control codes
FBSA Fixed-length, blocked, standard, ASA print-control characters.

In general, all references to files with record format FB also refer to FBM and FBA.
The specific behavior of ASA files (such as FBA) is explained in Chapter 7, Using
ASA text files, on page 47.

Attention: z/OS XL C/C++ distinguishes between FB and FBS formats, because an

FBS file contains no embedded short blocks (the last block may be short). FBS files
give you much better performance. The use of standard (S) blocks optimizes the
sequential processing of a file on a direct-access device. With a standard format
file, the file pointer can be directly repositioned by calculating the exact position in
that file of a given record rather than reading through the entire file.

If the records are FB, some blocks may contain fewer records than others, as shown
in Figure 1 on page 11.

10 z/OS V1R13.0 XL C/C++ Programming Guide

F-Format FB-Format FBS-Format

Block Block

Record Record Record Record Record Record Record

Record Record Record Record Record Record

Record Record Record Record Record Record Record

Record Record Record Record Record Record

... ... ...

Record Record Record Record Record Record

Figure 1. Blocking fixed-length records

Mapping C types to fixed format: This section describes the following formats:
v Binary
v Text (non-ASA)
v Text (ASA)
v Record
Binary On binary input and output, data flows over record boundaries.
Because all fixed-format records must be full, z/OS XL C/C++
completes any incomplete output record by padding it with nulls
(\0) when you close the file. Incomplete blocks are not padded.
On input, nulls are visible and are treated as data.
For example, if record length is set to 10 and you are writing 25
characters of data, z/OS XL C/C++ will write two full records, each
containing 10 characters, and then an incomplete record containing
5 characters. If you then close the file, z/OS XL C/C++ will
complete the last record with 5 nulls. If you open the file for
reading, z/OS XL C/C++ will read the records in order. z/OS XL
C/C++ will not strip off the nulls at the end of the last record.
Text (non-ASA)
When writing in a text stream, you indicate the end of the data for a
record by writing a new-line (\n) or carriage return (\r) to the
stream. In a fixed-format file, the new-line or carriage return will not
appear in the external file, and the record will be padded with
blanks from the position of the new-line or carriage return to
LRECL. (A carriage return is considered the same as a new-line
because the \r is not written to the file.)
For example, if you have set LRECL to 10, and you write the string
"ABC\n" to a fixed-format text file, z/OS XL C/C++ will write this to
the physical file:

Chapter 3. Understanding models of C I/O 11

 A B C

A record containing only a new-line is written to the file as LRECL

blanks.
When reading in a text stream, the I/O functions place a new-line
character ('\n') in the buffer to indicate the end of data for the
record. In a fixed-format file, the new-line character is placed at the
start of the blank padding at the end of the data.
For example, if your file position points to the start of the following
record in a fixed-format file opened as a text stream

A B C

file pointer

and you call fgets() to read the line of text, fgets() places the
string "ABC\n" in your input buffer.

Attention: Any blanks written immediately before a new-line or

carriage return will be considered blank padding when the record is
read back from the file. You cannot change the padding character.
When you are updating a fixed-format file opened as a text stream,
you can update the amount of data in a record. The maximum
length of the updated data is LRECL bytes plus the new-line
character; the minimum length is zero data bytes plus the new-line
character. Writing new data into an existing record replaces the old
data. If the new data is longer or shorter than the old data, the
number of blank padding characters in the record in the external file
is changed. When you extend a record, thereby writing over the old
new-line, there will be a new-line character implied after the new
characters. For instance, if you were to overwrite the record
mentioned in the previous example with the string "123456", the
records in the physical file would then look like this:

1 2 3 4 5 6

file pointer

The blanks at the end of the record imply a new-line at position 7.

You can see this new-line by calling fflush() and then performing
a read. The implied new-line is the first character returned from this
read.
A fixed record can hold only LRECL characters. If you try to write
more than that, z/OS XL C/C++ truncates the data unless you are
using a standard stream or a terminal file. In this case, the output is

12 z/OS V1R13.0 XL C/C++ Programming Guide

 split across multiple records. If truncation occurs, z/OS XL C/C++
raises SIGIOERR and sets both errno and the error flag.
Text (ASA) For ASA files, the first character of each record is reserved for the
ASA control character that represents a new-line, a carriage return,
or a form feed. This control character represents what should
happen before the record is written.
Table 2. C control to ASA characters
C Control Character ASA Character Description
\n skip one line
\n\n 0 skip two lines
\n\n\n - skip three lines
\f 1 new page
\r + overstrike

A control character that ends a logical record is represented at the

beginning of the following record in the external file. Since the ASA
control character is in the first byte of each record, a record can
hold only LRECL - 1 bytes of data. As with non-ASA text files
described above, z/OS XL C/C++ adds blank padding to complete
any record shorter than LRECL - 1 when it writes the record to the
file. On input, z/OS XL C/C++ removes all trailing blanks. For
example, if LRECL is 10, and you enter the string:
\nABC\nDEF

the record in the physical file will look like this:

A B C D E F ...

On input, this string is read as follows:

\nABC\nDEF

You can lengthen and shorten records the same way as you can for
non-ASA files. For more information about ASA, refer to Chapter 7,
Using ASA text files, on page 47.
Record As with fixed-format text files, a record can hold LRECL characters.
Every call to fwrite() is considered to be writing a full record. If
you write fewer than LRECL characters, z/OS XL C/C++ completes
the record with enough nulls to make it LRECL characters long. If
you try to write more than that, z/OS XL C/C++ truncates the data.

Variable-format records
In a file with variable-length records, each record may be a different length. The
variable length formats permit both variable-length records and variable-length
blocks. The first 4 bytes of each block are reserved for the Block Descriptor Word
(BDW); the first 4 bytes of each record are reserved for the Record Descriptor Word
(RDW), or, if you are using spanned files, the Segment Descriptor Word (SDW).
Illustrations of variable-length records are shown in Figure 2 on page 15.

Chapter 3. Understanding models of C I/O 13

 Once you have set the LRECL for a variable-format file, you can write up to LRECL
minus 4 characters in each record. z/OS XL C/C++ does not let you see RDWs,
BDWs, or SDWs when you open a file as variable-format. To see the RDWs or
SDWs and BDWs, open the variable file as undefined-format, as described in
Undefined-format records on page 16.

The value of LRECL must be greater than 4 to accommodate the RDW or SDW.
The value of BLKSIZE must be greater than or equal to the value of LRECL plus 4.
You should not use a BLKSIZE greater than LRECL plus 4 for an unblocked data
set. Doing so results in buffers that are larger than they need to be. The largest
amount of data that any one record can hold is LRECL bytes minus 4.

For striped data sets, a block is padded out to its full BLKSIZE. This makes
specifying an unnecessarily large BLKSIZE very inefficient.

Record format (RECFM): You can specify the following formats for variable-length
records:
V Variable-length, unblocked
VA Variable-length, ASA print control characters, unblocked
VB Variable-length, blocked
VM Variable-length, machine print-control codes, unblocked
VS Variable-length, unblocked, spanned
VBA Variable-length, blocked, ASA print control characters
VBM Variable-length, blocked, machine print-control codes
VBS Variable-length, blocked, spanned
VSA Variable-length, spanned, ASA print control characters
VSM Variable-length, spanned, machine print-control codes
VBSA Variable-length, blocked, spanned, ASA print control characters
VBSM Variable-length, blocked, spanned, machine print-control codes

Note: In general, all references in this guide to files with record format VB also refer
to VBM and VBA. The specific behavior of ASA files (such as VBA) is explained in
Chapter 7, Using ASA text files, on page 47.

V-format signifies unblocked variable-length records. Each record is treated as a

block containing only one record.

VB-format signifies blocked variable-length records. Each block contains as many

complete records as it can accommodate.

Spanned records: A spanned record is opened using both V and S in the format
specifier. A spanned record is a variable-length record in which the length of the
record can exceed the size of a block. If it does, the record is divided into segments
and accommodated in two or more consecutive blocks. The use of spanned records
allows you to select a block size, independent of record length, that will combine
optimum use of auxiliary storage with the maximum efficiency of transmission.

VS-format specifies that each block contains only one record or segment of a
record. The first 4 bytes of a block describe the block control information. The

14 z/OS V1R13.0 XL C/C++ Programming Guide

second 4 bytes contain record or segment control information, including an
indication of whether the record is complete or is a first, intermediate, or last
segment.

VBS-format differs from VS-format in that each block in VBS-format contains as many
complete records or segments as it can accommodate, while each block in
VS-format contains at most one record per block.

V-format:

C1 C2 Record 1 C1 C2 Record 2 C1 C2

VB-format:
Block

C1 C2 Record 1 C2 Record 2 C1 C2 Record 3

VS-format:
Spanned Record

Record 1 Record 2 Record 2

C1 C2 (entire) C1 C2 (first segment) C1 C2 (next segment)

VBS-format:
Spanned Record

Record 1 Record 2 Record 2

C1 C2 (entire) C2 (first segment) C1 C2 (last segment) C2 Record 3

C1: Block control information

C2: Record or segment control information

Figure 2. Variable-length records on z/OS

Mapping C types to variable format:

Binary On input and output, data flows over record boundaries. Any record
will hold up to LRECL minus 4 characters of data. If you try to write
more than that, your data will go to the next record, after the RDW
or SDW. You will not be able to see the descriptor words when you
read the file.

Note: If you need to see the BDWs, RDWs, or SDWs, you can
open and read a V-format file as a U-format file. See
Undefined-format records on page 16 for more information.
z/OS XL C/C++ never creates empty binary records for files opened
in V-format. See Writing to binary files on page 106 for more
information. An empty binary record is one that contains only an
RDW, which is 4 bytes long. On input, empty records are ignored.
Text (non-ASA)
Record boundaries are used in the physical file to represent the

Chapter 3. Understanding models of C I/O 15

 position of the new-line character. You can indicate the end of a
record by including a new-line or carriage return character in your
data. In variable-format files, z/OS XL C/C++ treats the carriage
return character as if it were a new-line. z/OS XL C/C++ does not
write either of these characters to the physical file; instead, it
creates a record boundary. When you read the file back, boundaries
are read as new-lines.
If a record only contains a new-line character, the default behavior
of z/OS XL C/C++ is to write a record containing a single blank to
the file. Therefore, the string \n is treated the same way as the
string \n; both are read back as \n. All other blanks in your
output are read back as is. Any empty (zero-length) record is
ignored on input. However, if the environment variable
_EDC_ZERO_RECLEN was set to Y at the time the file was opened, a
single new-line is written to the file as an empty record, and a
single blank represents \n. On input, an empty record is treated
as a single new-line and is not ignored.
After a record has been written to a file, you cannot change its
length. If you try to shorten a logical record by writing a new,
smaller amount of data into it, the C I/O library will add blank
characters until the record is full. Writing more data to a record than
it can hold causes your data to be truncated unless you are writing
to a standard stream or a terminal file. In this case, your output is
split across multiple records. If truncation occurs, z/OS XL C/C++
raises SIGIOERR and sets both errno and the error flag.

Note: If you did not explicitly set the _EDC_ZERO_RECLEN

environment variable when you opened the file, you can update a
record that contains a single blank to contain a non-blank character,
thereby lengthening the logical record from \n to x\n), where x
is the non-blank character.
Text (ASA) z/OS XL C/C++ treats variable-format ASA text files similarly to the
way it treats fixed-format ones. Empty records are always ignored
in ASA variable-format files; for a record to be recognized, it must
contain at least one character as the ASA control character. For
more information about ASA, refer to Chapter 7, Using ASA text
files, on page 47.
Record Each call to fwrite() creates a record that must be shorter than or
equal to the size established by LRECL. If you try to write more
than LRECL bytes on one call to fwrite(), z/OS XL C/C++ will
truncate your data. z/OS XL C/C++ never creates empty records
using record I/O. On input, empty records are ignored unless you
have set the _EDC_ZERO_RECLEN environment variable to Y. In this
case, empty records are treated as records with length 0.
If your application sets _EDC_ZERO_RECLEN to Y, bear in mind that
fread() returns back 0 bytes read, but does not set errno, and that
both feof() and ferror() return 0 as well.

Undefined-format records
Everything in an undefined-format file is treated as data, including control
characters and record boundaries. Blocks in undefined-format records are
variable-length; each block is considered a record.

16 z/OS V1R13.0 XL C/C++ Programming Guide

It is impossible to have an empty record. Whatever you specify for LRECL has no
effect on your data, but the value of LRECL must be less than or equal to the value
you specify for BLKSIZE. Regardless of what you specify, z/OS XL C/C++ sets
LRECL to zero when it creates an undefined-format file.

Reading a file in U-format enables you to read an entire block at once.

Record format (RECFM): You can specify the following formats for
undefined-length records:
U Undefined-length
UA Undefined-length, ASA print control characters
UM Undefined-length, machine print-control codes

U, UA, and UM formats permit the processing of records that do not conform to F- and
V-formats. The operating system treats each block as a record; your program must
perform any additional blocking or deblocking.

You can read any file in U-format. This is useful if, for example, you want to see the
BDWs and RDWs of a file that you have written in V-format.

Mapping C types to undefined format:

Binary When you are writing to an undefined-format file, binary data fills a
block and then begins a new block.
Text (non-ASA)
Record boundaries (that is, block boundaries) are used in the
physical file to represent the position of the new-line character. You
can indicate the end of a record by including a new-line or carriage
return character in your data. In undefined-format files, z/OS XL
C/C++ treats the carriage return character as if it were a new-line.
z/OS XL C/C++ does not write either of these characters to the
physical file; instead, it creates a record boundary. When you read
the file back, these boundaries are read as new-lines.
If a record contains only a new-line character, z/OS XL C/C++
writes a record containing a single blank to the file regardless of the
setting of the _EDC_ZERO_RECLEN environment variable. Therefore,
the string \n (a single blank followed by a new-line character) is
treated the same way as \n; both are written out as a single
blank. On input, both are read as \n. All other blank characters
are written and read as you intended.
After a record has been written to a file, you cannot change its
length. If you try to shorten a logical record by writing a new,
smaller amount of data into it, the C I/O library adds blank
characters until the record is full. Writing more data to a record than
it can hold will cause your data to be truncated unless you are
writing to a standard stream or a terminal file. In these cases, your
output is split across multiple records. If truncation occurs, z/OS XL
C/C++ raises SIGIOERR and sets both errno and the error flag.

Note: You can update a record that contains a single blank to

contain a non-blank character, thereby lengthening the logical
record from \n to x\n), where x is the non-blank character.
Text (ASA) For a record to be recognized, it must contain at least one

Chapter 3. Understanding models of C I/O 17

 character as the ASA control character. For more information about
ASA, refer to Chapter 7, Using ASA text files, on page 47.
Record Each call to fwrite() creates a record that must be shorter than or
equal to the size established by BLKSIZE. If you try to write more
than BLKSIZE bytes on one call to fwrite(), z/OS XL C/C++
truncates your data.

The byte stream model for C I/O

The byte stream model differs from the record I/O model. In the byte stream model,
a file is just a stream of bytes, with no record boundaries. New-line characters
written to the stream appear in the external file.

If the file is opened in binary mode, any new-line characters previously written to
the file are visible on input. z/OS XL C/C++ memory file I/O and Hiperspace
memory file I/O are based on the byte stream model (see Chapter 14, Performing
memory file and hiperspace I/O operations, on page 199 for more information).

UNIX file system I/O, defined by POSIX, is also based on the byte stream model.
See Chapter 11, Performing z/OS UNIX file system I/O operations, on page 123
for information about I/O with UNIX file system.

Mapping the C types of I/O to the byte stream model

Binary In the byte stream model, files opened in binary mode do not
contain any record boundaries. Data is written as is to the file.
Text The byte stream model does not support ASA. New-lines, carriage
returns, and other control characters are written as-is to the file.
Record If record I/O is supported by the kind of file you are using, z/OS XL
C/C++ simulates it by treating new-line characters as record
boundaries. New-lines are not treated as part of the record. A
record written out with a new-line inside it is not read back as it was
written, because z/OS XL C/C++ treats the new-line as a record
boundary instead of data.
Files in z/OS UNIX file system support record I/O, but memory files
do not.
As with all other record I/O, you can use only fread() and fwrite()
to read from and write to files. Each call to fwrite() inserts a
new-line in the byte stream; each call to fread() strips it off. For
example, if you use one fwrite() statement to write the string ABC
and the next to write DEF, the byte stream will look like this:

A B C \n D E F \n ...

There are no limitations on lengthening and shortening records. If

you then rewind the file and write new data into it, z/OS XL C/C++
will replace the old data. For example, if you used the rewind()
function on the stream in the previous example and then called
fwrite() to place the string 12345 into it, the stream would look like
this:

18 z/OS V1R13.0 XL C/C++ Programming Guide

 1 2 3 4 5 \n F \n ...

If you are using files with this model, do not use new-line
characters in your output. If you do, they will create extra record
boundaries. If you are unsure about the data being written or are
writing numeric data, use binary instead of text to avoid writing a
byte that has the hex value of a new-line.

Chapter 3. Understanding models of C I/O 19

20 z/OS V1R13.0 XL C/C++ Programming Guide
Chapter 4. Using the Standard C++ Library I/O Stream Classes
The object-oriented model for input and output (I/O) is a set of classes and header
files that are provided by the Standard C++ Library. These classes implement and
manage the stream buffers and the data held in the buffers. Stream buffers hold
data sent to the program (input) and from the program (output), enabling the
program to manipulate and format the data.

There are two base classes, ios and streambuf, from which all other I/O stream
classes are derived. The ios class and its derivative classes are used to implement
formatting of I/O and maintain error state information of stream buffers implemented
with the streambuf class.

There are two shipped versions of the I/O stream classes:

v The UNIX Systems Laboratories C++ Language System Release (USL) I/O
Stream Class Library
The UNIX Systems Laboratories C++ Language System Release (USL) I/O
Stream Class Library is declared in the iostream.h header file. This version does
not support ASCII and large files.
v The Standard C++ I/O stream classes
The Standard C++ I/O stream classes are declared in the iostream header file.
This version supports ASCII and large files. For more detailed information on the
I/O stream classes provided by the Standard C++ Library, see _LARGE_FILES in
z/OS XL C/C++ Language Reference.

The I/O stream classes use OBJECTMODEL(COMPAT). They cannot be used with
other classes that use OBJECTMODEL(IBM), within the same inheritance
hierarchy. For more information, see OBJECTMODEL in z/OS XL C/C++ User's
Guide.

Advantages to using the C++ I/O stream classes

Although input and output are implemented with streams for both C and C++, the
C++ I/O stream classes provide the same facilities for input and output as C
stdio.h. The I/O stream classes in the Standard C++ Library have the following
advantages:
v The input (>>) operator and output (<<) operator are typesafe. These operators
are easier to use than scanf() and printf().
v You can overload the input and output operators to define input and output for
your own types and classes. This makes input and output across types, including
your own, uniform.

Predefined streams for C++

z/OS XL C++ provides the following predefined streams:
cin The standard input stream
cout The standard output stream
cerr The standard error stream, unit-buffered such that characters sent
to this stream are flushed on each output operation
clog The buffered error stream

Copyright IBM Corp. 1996, 2012 21

 All predefined streams are tied to cout. When you use cin, cerr, or clog, cout gets
flushed sending the contents of cout to the ultimate consumer.

z/OS C standard streams create all I/O to I/O streams:

v Input to cin comes from stdin (unless cin is redirected)
v cout output goes to stdout (unless cout is redirected)
v cerr output goes to stderr (unit-buffered) (unless cerr is redirected)
v clog output goes to stderr (unless clog is redirected)

When redirecting or intercepting a C standard stream, the corresponding C++

standard stream becomes redirected. This applies unless you redirect an I/O
stream. See Chapter 9, Using C and C++ standard streams and redirection, on
page 61 for more information.

How C++ I/O streams relate to C I/O streams

Typically, USL I/O Stream Class Library file I/O is implemented in terms of z/OS XL
C file I/O, and is buffered from it.

Note: The only exception is that cerr is unit-buffered (that is, ios::unitbuf is set).

A filebuf object is associated with each ifstream, ofstream, and fstream object.
When the filebuf is flushed, it writes to the underlying C stream, which has its own
buffer. The filebuf object follows every fwrite() to the underlying C stream with
an fflush().

Mixing the Standard C++ I/O stream classes, USL I/O stream class
library, and C I/O library functions
It is not recommended to mix the usage of the Standard C++ I/O stream classes,
USL I/O Stream Class Library, and C I/O library functions.

The USL I/O stream class library uses a separate buffer, which means that you
would need to flush the buffer after each call to cout either by setting ios::unitbuf
or by calling sync_with_stdio().

You should avoid switching between the formatted extraction functions of the C++
I/O stream classes and C stdio library functions whenever possible. You should
also avoid switching between versions of these classes.

For more information on mixing the I/O stream classes refer to Interleaving the
standard streams with sync_with_stdio() on page 63 and Interleaving the standard
streams without sync_with_stdio() on page 64.

Specifying file attributes

The fstream, ifstream, and ofstream classes specialize stream input and output
for files.

For z/OS XL C++, overloaded fstream, ifstream, and ofstream constructors, and
open() member functions, with an additional parameter, are provided so you can
specify z/OS XL C fopen() mode values. You can use this additional parameter to
specify any z/OS XL C fopen() mode value except type=record. If you choose to

22 z/OS V1R13.0 XL C/C++ Programming Guide

use a constructor without this additional parameter, you will get the default z/OS XL
C fopen() file characteristics. Table 6 on page 33 describes the default fopen()
characteristics.

Chapter 4. Using the Standard C++ Library I/O Stream Classes 23

24 z/OS V1R13.0 XL C/C++ Programming Guide
Chapter 5. Opening files
This chapter describes how to open I/O files. You can open files using the Standard
C fopen() and freopen() library functions. Alternatively, if you want to use the C++
I/O stream classes, you can use the constructors for the ifstream, ofstream or
fstream classes, or the open() member functions of the filebuf, ifstream,
ofstream or fstream classes.

To open a file stream with a previously opened z/OS UNIX file descriptor, use the
fdopen() function.

To open files with UNIX file system low-level I/O, use the open() function. For more
information about opening files in UNIX file system, see Chapter 11, Performing
z/OS UNIX file system I/O operations, on page 123.

Prototypes of functions
Table 3 summarizes the prototypes of various functions. For more detailed
information about the C I/O stream functions, see z/OS XL C/C++ Run-Time Library
Reference. For more detailed information about the C++ I/O stream classes, see
Standard C++ Library Reference, which discusses the Standard C++ I/O stream
classes.
Table 3. Summary of prototype functions
Type of function Prototype
C Library Functions FILE *fopen(const char *filename, const char *mode);

FILE *freopen(const char *filename, const char *mode, FILE *stream);

FILE *fdopen(int filedes, char *mode);

USL I/O stream library // ifstream constructor
functions ifstream(const char* fname, int mode=ios::in,
int prot=filebuf::openprot);

// ifstream constructor; z/OS C++ extension

ifstream(const char* fname, const char* fattr,
int mode=ios::in, int prot=filebuf::openprot);

// ifstream::open()
void open(const char* fname, int mode=ios::in,
int prot=filebuf::openprot);

// z/OS C++ extension

void open(const char* fname, const char* fattr,
int mode=ios::in, int prot=filebuf::openprot);

// ofstream constructor
ofstream(const char* fname, int mode=ios::out,
int prot=filebuf::openprot);

Copyright IBM Corp. 1996, 2012 25

Table 3. Summary of prototype functions (continued)
Type of function Prototype
USL I/O stream library // ofstream constructor; z/OS C++ extension
functions (continued) ofstream(const char* fname, const char* fattr,
int mode=ios::out, int prot=filebuf::openprot);

// ofstream::open()
void open(const char* fname, int mode=ios::out,
int prot=filebuf::openprot);

// z/OS C++ extension

void open(const char* fname, const char* fattr,
int mode=ios::out, int prot=filebuf::openprot);
// fstream constructor
fstream(const char* fname, int mode,
int prot=filebuf::openprot);

// fstream constructor; z/OS C++ extension

fstream(const char* fname, const char* fattr,
int mode, int prot=filebuf::openprot);

// fstream::open()
void open(const char* fname, int mode,
int prot=filebuf::openprot);

// z/OS C++ extension

void open(const char* fname, const char* fattr,
int mode, int prot=filebuf::openprot);

// filebuf::open()
filebuf* open(const char* fname, int mode,
int prot=filebuf::openprot);

// z/OS C++ extension

filebuf* open(const char* fname, const char* fattr,
int mode, int prot=filebuf::openprot);
Standard C++ I/O stream // z/OS C++ Standard Library ifstream constructor
functions ifstream(const char *, ios_base::openmode, const char * _A)

// z/OS C++ Standard Library ifstream::open

void ifstream::open(const char *, ios_base::openmode, const char * _A)
void ifstream::open(const char *, ios_base::open_mode, const char * _A)

// z/OS C++ Standard Library ofstream constructor

ofstream(const char *, ios_base::openmode, const char * _A)

// z/OS C++ Standard Library ofstream::open

void ofstream::open(const char *, ios_base::openmode, const char * _A)
void ofstream::open(const char *, ios_base::open_mode, const char * _A)

// z/OS C++ Standard Library fstream constructor

fstream(const char *, ios_base::openmode, const char * _A)

// z/OS C++ Standard Library fstream::open

void fstream::open(const char *, ios_base::openmode, const char * _A)
void fstream::open(const char *, ios_base::open_mode, const char * _A)

// C++ Standard Library filebuf::open

filebuf::open(const char *, ios_base::openmode, const char * _A)
filebuf::open(const char *, ios_base::open_mode, const char * _A)

26 z/OS V1R13.0 XL C/C++ Programming Guide

Categories of I/O
Table 4 lists the categories of I/O that z/OS XL C/C++ supports and points to the
section where each category is described.

Note: CICS Data Queues and z/OS Language Environment Message File do not
apply in AMODE 64 applications. Hiperspace Memory Files are opened as (regular)
Memory Files since the size of a (regular) Memory File can exceed 2GB in AMODE
64 applications.
Table 4. Kinds of I/O supported by z/OS XL C/C++
Type of I/O Suggested Uses and Supported Devices Model Page
OS I/O Used for dealing with the following kinds of files: Record 81
v Generation data group
v MVS sequential DASD files
v Regular and extended partitioned data sets
v Tapes
v Printers
v Punch data sets
v Card reader data sets
v MVS inline JCL data sets
v MVS spool data sets
v Striped data sets
v Optical readers
UNIX file system I/O Used under z/OS UNIX System Services (z/OS UNIX) to support Byte stream 123
data sets in the UNIX file system, and access the byte-oriented
UNIX file system files according to POSIX .1 and XPG 4.2
interfaces. This increases the portability of applications written on
UNIX-based systems to z/OS XL C/C++ systems.
VSAM I/O Used for working with VSAM data sets. Supports direct access to Record 147
records by key, relative record number, or relative byte address.
Supports entry-sequenced, relative record, and key-sequenced
data sets.
Terminal I/O Used to perform interactive input and output operations with a Record 189
terminal.
Memory Files Used for applications requiring temporary I/O files without the Byte stream 199
overhead of system data sets. Fast and efficient.
Hiperspace Memory Used to deal with memory files as large as 2 gigabytes. Byte stream 199
Files
CICS Data Queues Used under the Customer Information Control System (CICS). Record 213
CICS data queues are automatically selected under CICS for the
standard streams stdout and stderr for C, or cout and cerr for
C++. The CICS I/O commands are supported through the
Command Level interface. The standard stream stdin under C (or
cin under C++) is treated as an empty file under CICS.
z/OS Language Used when you are running with z/OS Language Environment. The Record 215
Environment Message message file is automatically selected for stderr under z/OS
File Language Environment. For C++, automatic selection is of cerr.

Table 5 on page 28 lists the environments that z/OS XL C/C++ supports, and which
categories of I/O work in which environment.

Chapter 5. Opening files 27

 Table 5. I/O categories and environments that support them
MVS IMS TSO
Type of I/O batch online TSO batch CICS
OS I/O Yes Yes Yes Yes No
UNIX file system I/O Yes Yes Yes Yes No
VSAM I/O Yes Yes Yes Yes No
Terminal I/O No No Yes No No
Memory Files Yes Yes Yes Yes Yes
Hiperspace Memory Files Yes Yes Yes Yes No
CICS Data Queues No No No No Yes
z/OS Language Environment Yes Yes Yes Yes No
Message File
Note: MVS batch includes IMS batch. TSO is interactive. TSO batch indicates an
environment set up by a batch call to IKJEFT01. Programs run in such an environment
behave more like a TSO interactive program than an MVS batch program.

Specifying what kind of file to use

This section discusses:
v the kinds of files you can use
v how to specify RECFM, LRECL, and BLKSIZE
v how to specify DDnames

OS files
z/OS XL C/C++ treats a file as an OS file, provided that it is not a CICS data
queue, or a UNIX file system, VSAM, memory, terminal, or Hiperspace file.

UNIX file system files

When you are running under MVS, TSO (batch and interactive), or IMS, z/OS XL
C/C++ recognizes a UNIX file system I/O file as such if the name specified on the
fopen() or freopen() call conforms to certain rules. These rules are described in
How z/OS XL C/C++ determines what kind of file to open on page 35.

VSAM data sets

z/OS XL C/C++ recognizes a VSAM data set if the file exists and has been defined
as a VSAM cluster before the call to fopen().

Terminal files
When you are running with the run-time option POSIX(OFF) under interactive TSO,
z/OS XL C/C++ associates streams to the terminal. You can also call fopen() to
open the terminal directly if you are running under TSO (interactive or batch), and
either the file name you specify begins with an asterisk (*), or the ddname has been
allocated with a DSN of *.

When running with POSIX(ON), z/OS XL C/C++ associates streams to the terminal
under TSO and a shell if the file name you have specified fits one of the following
criteria:
v Under TSO (interactive and batch), the name must begin with the sequence
//*, or the ddname must have been allocated with a DSN of *.

28 z/OS V1R13.0 XL C/C++ Programming Guide

 v Under a shell, the name specified on fopen() or freopen() must be the
character string returned by ttyname().

Interactive IMS and CICS behave differently from what is described here. For more
information about terminal files with interactive IMS and CICS see Chapter 9, Using
C and C++ standard streams and redirection, on page 61.

If you are running with POSIX(ON) outside a shell, you must use the regular z/OS XL
C/C++ I/O functions for terminal I/O. If you are running with POSIX(ON) from a shell,
you can use the regular z/OS XL C/C++ I/O functions or the POSIX low-level
functions (such as read()) for terminal I/O.

Memory files and hiperspace memory files

You can use regular memory files on all the systems that z/OS XL C/C++ supports.
To create one, specify type=memory on the fopen() or freopen() call that creates
the file. A memory file, once created, exists until either of the following happens:
v You explicitly remove it with remove() or clrmemf()
v The root program is terminated

While a memory file exists, you can just use another fopen() or freopen() that
specifies the memory file's name. As sample program CCNGOF1 shows in Figure 3,
you do not have to specify type=memory.

/* this example shows how fopen() may be used with memory files */

#include <stdio.h>
char text[3], *result;
FILE * fp;

int main(void)
{
fp = fopen("a.b", "w, type=memory"); /* Opens a memory file */
fprintf(fp, "%d\n",10); /* Writes to the file */
fclose(fp); /* Closes the file */
fp = fopen("a.b", "r"); /* Reopens the same */
/* file (already */
/* a memory file) */
if ((result=fgets(text,3,fp)) !=NULL) /* Retrieves results */
printf("value retrieved is %s\n",result);
fclose(fp); /* Closes the file */

return(0);
}

Figure 3. Memory file example

A valid memory file name will match current file restrictions on a real file. Thus, a
memory file name that is classified as UNIX file system can have more characters
than can one classified as an MVS file name.

If you are not running under CICS, you can open a Hiperspace memory file as
follows:
fp = fopen("a.b", "w, type=memory(hiperspace)");

If you specify hiperspace and you are running in a CICS environment, z/OS XL
C/C++ opens a regular memory file. If you are running with the run-time options

Chapter 5. Opening files 29

 POSIX(ON) and TRAP(OFF), specifying hiperspace has no effect; z/OS XL C/C++ will
open a regular memory file. You must specify TRAP(ON) to be able to create
Hiperspace files.

Restriction: Hiperspace is not supported in AMODE 64 applications. If you specify

hiperspace in AMODE 64 applications, z/OS XL C/C++ opens a regular memory
file.

CICS data queues

A CICS transient data queue is a pathway to a single predefined destination. The
destination can be a ddname, another transient data queue, a VSAM file, a
terminal, or another CICS environment. The CICS system administrator defines the
queues that are active during execution of CICS. All users who direct data to a
given queue will be placing data in the same location, in order of occurrence.

You cannot use fopen() or freopen() to specify this kind of I/O. It is the category
selected automatically when you call any ANSI functions that reference stdout and
stderr under CICS. If you reference either of these in a C or C++ program under
CICS, z/OS XL C/C++ attempts to open the CESO (stdout) or CESE (stderr)
queue. If you want to write to any other queue, you should use the CICS-provided
interface.

z/OS Language Environment Message file

The z/OS Language Environment message file is managed by z/OS Language
Environment and may not be directly opened or closed with fopen(), freopen() or
fclose() within a C or C++ application. In z/OS Language Environment, output
from stderr is directed to the z/OS Language Environment message file by default.
You can use freopen() and fclose() to manage stderr, or you can redirect it to
another destination. There are application writer interfaces (AWIs) that enable you
to access the z/OS Language Environment message file directly. These are
documented in z/OS Language Environment Programming Guide.

See Chapter 16, Language Environment Message file operations, on page 215 for
more information on z/OS Language Environment message files.

How to specify RECFM, LRECL, and BLKSIZE

For OS files and terminal files, the values of RECFM, LRECL, and BLKSIZE are
significant. When you open a file, z/OS XL C/C++ searches for the RECFM,
LRECL, and BLKSIZE values in the following places:
1. The fopen() or freopen() statement that opens the file
2. The DD statement (described in DDnames on page 34)
3. The values set in the existing file
4. The default values for fopen() or freopen().

When you call fopen() and specify a write mode (w, wb, w+, wb+, w+b) for an
existing file, z/OS XL C/C++ uses the default values for fopen() if:
v the data set is opened by the data set name or
v the data set is opened by ddname and the DD statement does not have any
attributes filled in.

These defaults are listed in Table 6 on page 33. To force z/OS XL C/C++ to use
existing attributes when you are opening a file, specify recfm=* (or recfm=+) on the
fopen() or freopen() call.

30 z/OS V1R13.0 XL C/C++ Programming Guide

recfm=* (or recfm=+) is valid only for existing DASD data sets. It is ignored in all
other cases.

recfm=+ is identical to recfm=* with the following exceptions:

v If there is no record format for the existing DASD data set, the defaults are
assigned as if the data set did not exist.
v When append mode is used, the fopen() fails.
Notes:
1. When specifying a ddname on fopen() or freopen() you should be aware of
the following when opening the ddname using one of the write modes:
2. If the ddname is allocated to an already existing file and that ddname has not
yet been opened, then the DD statement will not contain the recfm, lrecl, or
blksize. That information is not filled in until the ddname is opened for the first
time. If the first open uses one of the write modes (w,wb, w+, wb+, w+b) and
recfm=* (or recfm=+) is not specified, then the existing file attributes are not
considered. Therefore, since the DD statement has not yet been filled in, the
fopen() defaults are used.
3. If the ddname is allocated at the same time the file is created, then the DD
statement will contain the same recfm, lrecl, and blksize specified for the
file. If the first open uses one of the write modes (w, wb, w+, wb+, w+b) and
recfm=* (or recfm=+) is not specified, then z/OS XL C/C++ picks up the existing
file attributes from the DD statement since they were placed there at the time of
allocation.
You can specify the record format in
v The RECFM parameter of the JCL DD statement under MVS
v The RECFM parameter of the ALLOCATE statement under TSO
v The __recfm field of the __dyn_t structure passed to the dynalloc() library
function under MVS
v The RECFM parameter on the call to the fopen() or freopen() library function
v The __S99TXTPP text unit field on an SVC99 parameter list passed to the svc99()
library function under MVS
v The ISPF data set utility under MVS

Certain categories of I/O may ignore or simulate some attributes such as BLKSIZE
or RECFM that are not physically supported on the device. Table 4 on page 27 lists
all the categories of I/O that z/OS XL C/C++ supports and directs you to where you
can find more information about them.

You can specify the logical record length in

v The LRECL parameter of the JCL DD statement under MVS
v The LRECL parameter of the ALLOCATE statement under TSO
v The __lrecl field of the __dyn_t structure passed to the dynalloc() library
function under MVS
v The LRECL parameter on the call to the fopen() or freopen() library function
v The __S99TXTPP text unit field on an SVC99 parameter list passed to the svc99()
library function under MVS
v The ISPF data set utility

If you are creating a file and you do not select a record size, z/OS XL C/C++ uses a
default. See fopen() defaults on page 32 for details on how defaults are
calculated.

Chapter 5. Opening files 31

 You can specify the block size in
v The BLKSIZE parameter of the JCL DD statement
v The BLKSIZE parameter of the ALLOCATE statement under TSO
v The __blksize field of the __dyn_t structure passed to the dynalloc() library
function under MVS
v The BLKSIZE parameter on a call to the fopen() or freopen() library function
v The __S99TXTPP text unit field on an SVC99 parameter list passed to the svc99()
library function under MVS
v The ISPF data set utility

If you are creating a file and do not select a block size, z/OS XL C/C++ uses a
default. The defaults are listed in Table 6 on page 33.

fopen() defaults
You cannot specify a file attribute more than once on a call to fopen() or freopen().
If you do, the function call fails. If the file attributes specified on the call to fopen()
differ from the actual file attributes, fopen() usually fails. However, fopen() does
not fail if:
v The file is opened for w, w+, wb, or wb+, and the file is neither an existing PDS or
PDSE nor an existing file opened by a ddname that specifies DISP=MOD. In such
instances, fopen() attributes override the actual file attributes. However, if
recfm=* (or recfm=+) is specified on the fopen(), any attributes that are not
specified either on the fopen() or for the ddname will be retrieved from the
existing file. If the final combination of attributes is invalid, the fopen() will fail.
v The file is opened for reading (r or rb) with recfm=U. Any other specified
attributes should be compatible with those of the existing data set.

In calls to fopen(), the LRECL, BLKSIZE, and RECFM parameters are optional. (If
you are opening a file for read or append, any attributes that you specify must
match the existing attributes.)

If you do not specify file attributes for fopen() (or for an I/O stream object), you get
the following defaults.

RECFM defaults
If recfm is not specified in a fopen() call for an output binary file, recfm defaults to:
v recfm=VB for spool (printer) files
v recfm=FB otherwise

If recfm is not specified in a fopen() call for an output text file, recfm defaults to:
v recfm=F if _EDC_ANSI_OPEN_DEFAULT is set to Y and no LRECL or BLKSIZE
specified. In this case, LRECL and BLKSIZE are both defaulted to 254.
v recfm=VBA for spool (printer) files.
v recfm=U for terminal files.
v recfm=VB for MVS files.
v recfm=VB for all other OS files.

If recfm is not specified for a record I/O file, you will get the default of recfm=VB.

LRECL and BLKSIZE defaults

Table 6 on page 33 shows the defaults for LRECL and BLKSIZE when z/OS XL
C/C++ is creating a file, not appending or updating it. The table assumes that z/OS

32 z/OS V1R13.0 XL C/C++ Programming Guide

 XL C/C++ has already processed any information from the fopen() statement or
ddname. The defaults provide a basis for fopen() to select values for unspecified
attributes when you create a file.
Table 6. fopen() defaults for LRECL and BLKSIZE when creating OS files
lrecl blksize RECFM LRECL BLKSIZE
specified? specified?
no no All F 80 80
All FB 80 maximum integral multiple of 80 less
than or equal to max
All V, VB, minimum of 1028 or max4 max
VS, or VBS
All U 0 max
yes no All F lrecl lrecl
All FB lrecl maximum integral multiple of lrecl less
than or equal to max
All V lrecl lrecl+4
All U 0 lrecl
no yes All F or FB blksize blksize
All V, VB, minimum of 1028 or blksize4 blksize
VS, or VBS
All U 0 blksize
Note: All includes the standard (S) specifier for fixed formats, the ASA (A) specifier, and the machine control
character (M) specifier.

In Table 6, the value max represents the maximum block size for the device. These
are the current default maximum block sizes for several devices that z/OS XL
C/C++ supports:
Device Block Size
DASD 6144
3203 Printer 132
3211 Printer 132
4245 Printer 132
2540 Reader 80
2540 Punch 80
2501 Reader 80
3890 Document Processor 80
TAPE 32760

For more information about specific default block sizes, as returned by the DEVTYPE
macro, refer to z/OS DFSMS Using Data Sets.

For DASD files that do not have recfm=U, if you specify blksize=0 on the call to
fopen() or freopen() and you have DFP Release 3.1 or higher, the system
determines the optimal block size for your file. If you do not have the correct level
of DFP or you specify blksize=0 for a ddname instead of specifying it on the
fopen() or freopen() call, z/OS XL C/C++ behaves as if you had not specified the
blksize parameter at all.

For information about block sizes for different categories of I/O, see the chapters
listed in Table 4 on page 27.

Chapter 5. Opening files 33

 You do not have to specify the LRECL and BLKSIZE attributes; however, it is
possible to have conflicting attributes when you do specify them. The restrictions
are:
v For a V file, the LRECL must be greater than 4 bytes and must be at least 4
bytes smaller than the BLKSIZE.
v For an F file, the LRECL must be equal to the BLKSIZE, and must be at least 1.
v For an FB file, the BLKSIZE must be an integer multiple of the LRECL.
v For a U file, the LRECL must be less than or equal to the BLKSIZE and must be
greater than or equal to 0. The BLKSIZE must be at least 1.
v In spanned files, the LRECL and the BLKSIZE attributes must be greater than 4.
v If you specify LRECL=X, the BLKSIZE attribute must be less than or equal to the
maximum block size allowed on the device.

To determine the maximum LRECL and BLKSIZE values for the various file types
and devices available on your operating system, refer to the chapters listed in
Table 4 on page 27.

DDnames
DD names are specified by prefixing the DD name with DD:. All the following
forms of the prefix are supported:
v DD:
v dd:
v dD:
v Dd:

The DD statement enables you to write C source programs that are independent of
the files and input/output devices they will use. You can modify the parameters of a
file (such as LRECL, BLKSIZE, and RECFM) or process different files without
recompiling your program.
v How to create a DDname under MVS batch
To create a ddname under MVS batch, you must write a JCL DD statement. For
the C file PARTS.INSTOCK, you would write a JCL DD statement similar to the
following:
//STOCK DD DSN=PARTS.INSTOCK, . . .
UNIX file system files can be allocated with a DD card, as shown in the following
example:
//STOCK DD PATH=/u/parts.instock,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=(SIRWXU,SIRWXO,SIRWXG)
When defining DD, do not use DD ... FREE=CLOSE for unallocating DD
statements. The C library may close files to perform some file operations such as
freopen(), and the DD statement will be unallocated.
For more information on writing DD statements, refer to the JCL manuals listed in
z/OS Information Roadmap.
v How to create a DDname under TSO
To create a ddname under TSO, you must write an ALLOCATE command. For the
declaration shown above for the C file STOCK, you should write a TSO ALLOCATE
statement similar to the following:
ALLOCATE FILE(STOCK) DATASET(PARTS.INSTOCK)
You can also allocate UNIX file system files with TSO ALLOCATE commands. For
example:

34 z/OS V1R13.0 XL C/C++ Programming Guide

 ALLOC FI(stock) PATH(/used/parts.stock) PATHOPTS(OWRONLY,OCREAT)
PATHMODE(sirwxu,sirwxo,sirwxg)
See z/OS Information Roadmap for more information on TSO ALLOCATE.
v How to create a DDname in source code
You can also use the z/OS XL C/C++ library functions svc99() and dynalloc() to
allocate ddnames. See z/OS XL C/C++ Run-Time Library Reference for more
information about these functions.

You do not always need to describe the characteristics of the data in files both
within the program and outside it. There are, in fact, advantages to describing the
characteristics of your data in only one place.

Opening a file by ddname may require the merging of information internal and
external to the program. If any conflict is detected that will prevent the opening of a
file, fopen() returns a NULL pointer to indicate that the file cannot be opened. See
z/OS XL C/C++ Run-Time Library Reference for more information on fopen().

If DISP=MOD is specified on a DD statement and if the file is opened in w or wb mode,

the DISP=MOD causes the file to be opened in append mode rather than in write
mode.

Note: You can open a ddname only with fopen() or freopen(). open() does not
interpret ddnames as such.

Avoiding Undesirable Results when Using I/O

File serialization is not provided for different tasks attempting to access the same
file. When a C/C++ application is run on one task, and the same application or
another C/C++ application is run on a different task, any attempts for both
applications to access the same file is the responsibility of the application.

How z/OS XL C/C++ determines what kind of file to open

This section describes the criteria that z/OS XL C/C++ uses to determine what kind
of file it is opening. z/OS XL C/C++ goes through the categories listed in Table 4 on
page 27 in the order that follows. If a category applies to a file, z/OS XL C/C++
stops searching.

Note: Files cannot be opened under CICS when you have specified the POSIX(ON)
run-time option.

MAP 0010: Under TSO, MVS batch, IMS POSIX(ON) on page 36 shows how
z/OS XL C/C++ determines what type of file to open under TSO, MVS batch, and
interactive IMS with POSIX(ON). For information on the types of files shown in the
chart, see the appropriate chapter in the I/O section.

Chapter 5. Opening files 35

MAP 0010: Under TSO, MVS batch, IMS POSIX(ON)

001

Is type=memory specified?
Yes No

002

Does the name begin with // but NOT ///?

Yes No

003
Continue at Step 017 on page 37.

004
Continue at Step 008.

005

Is hiperspace specified?
Yes No

006
z/OS XL C/C++ opens a regular memory file.

007
z/OS XL C/C++ opens a memory file in Hiperspace.

008

Is the next character an asterisk?

Yes No

009

Is name of form DDname?

Yes No

010

Does the name specified match that of an existing memory file?

Yes No

011
z/OS XL C/C++ opens an OS file.

012
z/OS XL C/C++ opens the existing memory file.

36 z/OS V1R13.0 XL C/C++ Programming Guide

 MAP 0010 (continued)

013
Continue to Step 032 on page 38.

014

Are you running under TSO interactive?

Yes No

015
z/OS XL C/C++ removes the asterisk from the name unless the asterisk is
the only character, and proceeds to Step 028 on page 38.

016
z/OS XL C/C++ opens a terminal file.

017

Is the name of the form *DD:ddname or DD:ddname?

Yes No

018

Does the name specified match that of an existing memory file?

Yes No

019
z/OS XL C/C++ opens a UNIX file system file.

020
z/OS XL C/C++ opens the existing memory file.

021

Does ddname exist?

Yes No

022

Does a memory file exist?

Yes No

023
z/OS XL C/C++ opens a UNIX file system file called either *DD:ddname
or DD:ddname.

024
z/OS XL C/C++ opens the existing memory file.

Chapter 5. Opening files 37

MAP 0010 (continued)

025

Is a path specified in ddname?

Yes No

026
z/OS XL C/C++ opens an OS file.

027
z/OS XL C/C++ opens a UNIX file system file.

028

Is the name of the form *DD:ddname or DD:ddname?

Yes No

029

Does the name specified match that of an existing memory file?

Yes No

030
z/OS XL C/C++ opens an OS file.

031
z/OS XL C/C++ opens the existing memory file.

032

Does ddname exist?

Yes No

033

Does a memory file exist?

Yes No

034
***ERROR***

035
z/OS XL C/C++ opens the existing memory file.

036

Is a path specified in ddname?

Yes No

037
z/OS XL C/C++ opens an OS file.

38 z/OS V1R13.0 XL C/C++ Programming Guide

 MAP 0010 (continued)

038
z/OS XL C/C++ opens a UNIX file system file.

MAP 0020: Under TSO, MVS batch, IMS POSIX(OFF) on page 40 shows how
z/OS XL C/C++ determines what type of file to open under TSO, MVS batch, and
interactive IMS with POSIX(OFF). For information on the types of files shown in the
chart, see the appropriate chapter in the I/O section.

Chapter 5. Opening files 39

MAP 0020: Under TSO, MVS batch, IMS POSIX(OFF)

001

Is type=memory specified?
Yes No

002

Does the name begin with // but NOT ///?

Yes No

003
Continue at Step 017 on page 41.

004
Continue at Step 008.

005

Is hiperspace specified?
Yes No

006
z/OS XL C/C++ opens a regular memory file.

007
z/OS XL C/C++ opens a memory file in Hiperspace.

008

Is the next character an asterisk?

Yes No

009

Is name of form DDname?

Yes No

010

Does the name specified match that of an existing memory file?

Yes No

011
z/OS XL C/C++ opens an OS file.

012
z/OS XL C/C++ opens the existing memory file.

40 z/OS V1R13.0 XL C/C++ Programming Guide

 MAP 0020 (continued)

013
Continue at Step 021.

014

Are you running under TSO interactive?

Yes No

015
z/OS XL C/C++ removes the asterisk from the name unless the asterisk is
the only character, and proceeds to Step 017.

016
z/OS XL C/C++ opens a terminal file.

017

Is the name of the form *DD:ddname or DD:ddname?

Yes No

018

Does the name specified match that of an existing memory file?

Yes No

019
z/OS XL C/C++ opens an OS file.

020
z/OS XL C/C++ opens the existing memory file.

021

Does ddname exist?

Yes No

022

Does a memory file exist?

Yes No

023
***ERROR***

024
z/OS XL C/C++ opens the existing memory file.

Chapter 5. Opening files 41

MAP 0020 (continued)

025

Is a path specified in ddname?

Yes No

026
z/OS XL C/C++ opens an OS file.

027
z/OS XL C/C++ opens a UNIX file system file.

MAP 0030: Under CICS on page 43 shows how z/OS XL C/C++ determines what
type of file to open under CICS. For information on the types of files shown in the
chart, see the appropriate chapter in the I/O section.

42 z/OS V1R13.0 XL C/C++ Programming Guide

MAP 0030: Under CICS

001

Is type=memory specified?
Yes No

002

Does the name specified match that of an existing memory file?

Yes No

003
The fopen() call fails.

004
z/OS XL C/C++ opens that memory file.

005

Is hiperspace specified?
Yes No

006
z/OS XL C/C++ opens the specified memory file.

007
The fopen() call ignores the hiperspace specification and opens the memory file.

Chapter 5. Opening files 43

MAP 0030 (continued)

44 z/OS V1R13.0 XL C/C++ Programming Guide

Chapter 6. Buffering of C streams
This chapter describes buffering modes used by z/OS XL C/C++ library functions
available to control buffering and methods of flushing buffers.

z/OS XL C/C++ uses buffers to map C I/O to system-level I/O. When z/OS XL
C/C++ performs I/O operations, it uses one of the following buffering modes:
v Line buffering - characters are transmitted to the system as a block when a
new-line character is encountered. Line buffering is meaningful only for text
streams and UNIX file system files.
v Full buffering - characters are transmitted to the system as a block when a buffer
is filled.
v No buffering - characters are transmitted to the system as they are written. Only
regular memory files and UNIX file system files support the no buffering mode.
The buffer mode affects the way the buffer is flushed. You can use the setvbuf()
and setbuf() library functions to control buffering, but you cannot change the
buffering mode after an I/O operation has used the buffer, as all read, write, and
reposition operations do. In some circumstances, repositioning alters the contents of
the buffer. It is strongly recommended that you only use setbuf() and setvbuf()
before any I/O, to conform with ANSI, and to avoid any dependency on the current
implementation. If you use setvbuf(), z/OS XL C/C++ may or may not accept your
buffer for its internal use. For a hiperspace memory file, if the size of the buffer
specified to setvbuf() is 8K or more, it will affect the number of hiperspace blocks
read or written on each call to the operating system; the size is rounded down to
the nearest multiple of 4K.

Full buffering is the default except in the following cases:

v If you are using an interactive terminal, z/OS XL C/C++ uses line buffering.
v If you are running under CICS, z/OS XL C/C++ also uses line buffering.
v stderr is line-buffered by default.
v If you are using a memory file, z/OS XL C/C++ does not use any buffering.
For terminals, because I/O is always unblocked, line buffering is equivalent to full
buffering.

For record I/O files, buffering is meaningful only for blocked files or for record I/O
files in z/OS UNIX file system using full buffering. For unblocked files, the buffer is
full after every write and is therefore written immediately, leaving nothing to flush.
For blocked files or fully-buffered UNIX file system files, however, the buffer can
contain one or more records that have not been flushed and that require a flush
operation for them to go to the system.

You can flush buffers to the system in several different ways.

v If you are using full buffering, z/OS XL C/C++ automatically flushes a buffer when
it is filled.
v If you are using line buffering for a text file or a UNIX file system file, z/OS XL
C/C++ flushes a buffer when you complete it with a control character. Except for
UNIX file system files, specifying line buffering for a record I/O or binary file has
no effect; z/OS XL C/C++ treats the file as if you had specified full buffering.
v z/OS XL C/C++ flushes buffers to the system when you close a file or end a
program.

Copyright IBM Corp. 1996, 2012 45

 v z/OS XL C/C++ flushes buffers to the system when you call the fflush() library
function, with the following restrictions:
A file opened in text mode does not flush data if a record has not been
completed with a new-line.
A file opened in fixed format does not flush incomplete records to the file.
An FBS file does not flush out a short block unless it is a DISK file opened
without the NOSEEK parameter.
v All streams are flushed across non-POSIX system() calls. Streams are not
flushed across POSIX system() calls. For a POSIX system call, we recommend
that you do a fflush() before the system() call.
If you are reading a record that another user is writing to at the same time, you can
see the new data if you call fflush() to refresh the contents of the input buffer.

Note: This is not supported for VSAM files.

You may not see output if a program that is using input and output fails, and the
error handling routines cannot close all the open files.

46 z/OS V1R13.0 XL C/C++ Programming Guide

Chapter 7. Using ASA text files
This chapter describes the American Standards Association (ASA) text files, the
control characters used in ASA files, how z/OS XL C/C++ translates the control
characters, and how z/OS XL C/C++ treats ASA files during input and output. The
first column of each record in an ASA file contains a control character (' ', '0', '', '1',
or '+') when it appears in the external medium.

z/OS XL C/C++ translates control characters in ASA files opened for text processing
(r, w, a, r+, w+, a+ functions). On input, z/OS XL C/C++ translates ASA
characters to sequences of control characters, as shown in Table 7. On output,
z/OS XL C/C++ performs the reverse translation. The following sequences of control
characters are translated, and the resultant ASA character becomes the first
character of the following record.
Table 7. C control to ASA characters translation table
C Control Character ASA Character Description
Sequence
\n '' skip one line
\n\n '0' skip two lines
\n\n\n '-' skip three lines
\f '1' new page
\r '+' overstrike

If you are writing to the first record or byte of the file and the output data does not
start with a translatable sequence of C control characters, the ' ' ASA control
character is written to the file before the specified data.

z/OS XL C/C++ does not translate or verify control characters when you open an
ASA file for binary or record I/O.

Example of writing to an ASA file

Sample program CCNGAS1, shown in Figure 4, demonstrates how a program can
write to an ASA file.

/* this example shows how to write to an ASA file */

#include <stdio.h>
#define MAX_LEN 80

int main(void) {
FILE *fp;
int i;
char s[MAX_LEN+1];

Figure 4. ASA Example (Part 1 of 2)

Copyright IBM Corp. 1996, 2012 47

 fp = fopen("asa.file", "w, recfm=fba");
if (fp != NULL) {
fputs("\n\nabcdef\f\r345\n\n", fp);
fputs("\n\n9034\n", fp);
fclose(fp);

return(0);
}

fp = fopen("asa.file", "r");
for (i = 0; i < 5; i++) {
fscanf(fp, "%s", s[0]);
printf("string = %s\n",s);
}
}

Figure 4. ASA Example (Part 2 of 2)

The program writes five records to the file asa.file, as follows. Note that the last
record is 9034. The last single '\n' does not create a record with a single control
character (' '). If this same file is opened for read, and the getc() function is called
to read the file 1 byte at a time, the same characters as those that were written out
by fputs() in the first program are read.
0abcdef
1
+345
-
9034

ASA file control

ASA files are treated as follows:
v If the first record written does not begin with a control character, then a single
new-line is written and then followed by data; that is, the ASA character defaults
to a space when none is specified.
v In ASA files, control characters are treated the same way that they are treated in
other text files, with the following exceptions (see Table 7 on page 47 for more
information):
'\f' form feed
Defines a record boundary and determines the ASA character of the
following record
'\n' new-line
Does either of these:
Define a record boundary and determines the ASA character of the
following record.
Modify the preceding ASA character if the current position is directly
after an ASA character of ' ' or '0'.
'\r' carriage return
Defines a record boundary and determines the ASA character of the
following record.
v Records are terminated by writing a new-line ('\n'), carriage return ('\r'), or
form feed ('\f') character.
v An ASA character can be updated to any other ASA character.

48 z/OS V1R13.0 XL C/C++ Programming Guide

 Updates made to any of the C control characters that make up an ASA character
cause the ASA character to change.
If the file is positioned directly after a ' ' or '0' ASA character, writing a '\n'
character changes the ASA character to a '0' or '-' respectively. However, if the
ASA character is a '-', '1' or '+', the '\n' truncates the record (that is, it adds blank
padding to the end of the record), and causes the following record's ASA
character to be written as a ' '. Writing a '\f' or '\r' terminates the record and
start a new one, but writing a normal data character simply overwrites the first
data character of the record.
v You cannot overwrite the ASA character with a normal data character. The
position at the start of a record (at the ASA character) is the logical end of the
previous record. If you write normal data there, you are writing to the end of the
previous record. z/OS XL C/C++ truncates data for the following files, except
when they are standard streams:
Variable-format files
Undefined-format files
Fixed-format files in which the previous record is full of data
When truncation occurs, z/OS XL C/C++ raises SIGIOERR and sets both errno
and the error flag.
v Even when you update an ASA control character, seeking to a previously
recorded position still succeeds. If the recorded position was at a control
character that no longer exists (because of an update), the reposition is to the
next character. Often, this is the first data character of the record.
For example, if you have the following string, you have saved the position of the
third new-line:

\n\n\nHELLO WORLD

x = ftell()

If you then update the ASA character to a form feed ('\f'), the logical ASA
position x no longer exists:
\fHELLO WORLD
If you call fseek() with the logical position x, it repositions to the next valid
character, which is the letter 'H':

\fHELLO WORLD

fseek() to pos x

v If you try to shorten a record when you are updating it, z/OS XL C/C++ adds
enough blank padding to fill the record.
v The ASA character can represent up to three new-lines, which can increase the
logical record length by 1 or 2 bytes.
v Extending a fixed logical record on update implies that the logical end of the line
follows the last written non-blank character.

Chapter 7. Using ASA text files 49

 v If an undefined text record is updated, the length of the physical records does not
change. If the replacement record is:
Longer - data characters beyond the record boundary are truncated. At the
point of truncation, the User error flag is set and SIGIOERR is raised (if the
signal is not set up to be ignored). Truncation continues until you do one of
these:
1. Write a new-line character, carriage return, or form feed to complete the
current record
2. Close the file explicitly or implicitly at termination
3. Reposition to another position in the file.
Shorter - the blank character is used to overwrite the rest of the record.
v If you close an ASA file that has a new-line as its last character, z/OS XL C/C++
does not write the new-line to the physical file. The next time you read from the
file or update it, z/OS XL C/C++ returns the new-line to the end of the file. An
exception to this rule happens when you write only a new-line to a new file. In
this case, z/OS XL C/C++ does not truncate the new-line; it writes a single blank
to the file. On input, however, you will read two new-lines.
v Using ASA format to read a file that contains zero-length records results in
undefined behavior.
v You may have trouble updating a file if two ASA characters are next to each
other in the file. For example, if there is a single-byte record (containing only an
ASA character) immediately followed by the ASA character of the next record,
you are positioned at or within the first ASA character. If you then write a
sequence of '\n' characters intended to update both ASA characters, the '\n's
will be absorbed by the first ASA character before overflowing to the next record.
This absorption may affect the crossing of record boundaries and cause
truncation or corruption of data.
At least one normal intervening data character (for example, a space) is required
between '\n' and '\n' to differentiate record boundaries.

Note: Be careful when you update an ASA file with data containing more than
one consecutive new-line: the result of the update depends on how the original
ASA records were structured.
v If you are writing data to a non-blocked file without intervening flush or reposition
requests, each record is written to the system on completion (that is, when a
'\n', '\r' or '\f' character is written or when the file is closed).
If you are writing data to a blocked file without intervening flush or reposition
requests, and the file is opened in full buffering mode, the block is written to the
system on completion of the record that fills the block. If the blocked file is line
buffered, each record is written to the system on completion.
If you are writing data to a spanned file without intervening flush or reposition
requests, and the record spans multiple blocks, each block is written to the
system once it is full and the user writes an additional byte of data.
v If a flush occurs while an ASA character indicating more than one new-line is
being updated, the remaining new-lines will be discarded and a read will continue
at the first data character. For example, if '\n\n\n' is updated to be '\n\n' and
a flush occurs, then a '0' will be written out in the ASA character position.

50 z/OS V1R13.0 XL C/C++ Programming Guide

Chapter 8. z/OS XL C Support for the double-byte character
set
The number of characters in some languages such as Japanese or Korean is larger
than 256, the number of distinct values that can be encoded in a single byte. The
characters in such languages are represented in computers by a sequence of
bytes, and are called multibyte characters. This chapter explains how the z/OS XL
C compiler supports multibyte characters.

Note: The z/OS XL C++ compiler does not have native support for multibyte
characters. The support described here is what z/OS XL C provides; for C++, you
can take advantage of this support by using interlanguage calls to C code. Please
refer to Chapter 19, Using Linkage Specifications in C or C++, on page 237 for
more information.

The z/OS XL C compiler supports the IBM EBCDIC encoding of multibyte

characters, in which each natural language character is uniquely represented by
one to four bytes. The number of bytes that encode a single character depends on
the global shift state information. If a stream is in initial shift state, one multibyte
character is represented by a byte or sequence of bytes that has the following
characteristics:
v It starts with the byte containing the shift-out (0x0e) character.
v The shift-out character is followed by 2 bytes that encode the value of the
character.
v These bytes may be followed by a byte containing the shift-in (0x0f) character.

If the sequence of bytes ends with the shift-in character, the state remains initial,
making this sequence represent a 4-byte multibyte character. Multibyte characters
of various lengths can be normalized by the set of z/OS XL C library functions and
encoded in units of one length. Such normalized characters are called wide
characters; in z/OS XL C they are represented by two bytes. Conversions between
multibyte format and wide character format can be performed by string conversion
functions such as wcstombs(), mbstowcs(), wcsrtombs(), and mbsrtowcs(), as well
by the family of the wide character I/O functions. MB_CUR_MAX is defined in the
stdlib.h header file. Depending on its value, either of the following happens:
v When MB_CUR_MAX is 1, all bytes are considered single-byte characters; shift-out
and shift-in characters are treated as data as well.
v When MB_CUR_MAX is 4:
On input, the wide character I/O functions read the multibyte character from
the streams, and convert them to the wide characters.
On output, they convert wide characters to multibyte characters and write
them to the output streams.

Both binary and text streams have orientation. Streams opened with type=record
do not. There are three possible orientations of a stream:
Non-oriented
A stream that has been associated with an open file before any I/O
operation is performed. The first I/O operation on a non-oriented stream will
set the orientation of the stream. The fwide() function may be used to set
the orientation of a stream before any I/O operation is performed. You can
use the setbuf() and setvbuf() functions only when I/O has not yet been
performed on a stream. When you use these functions, the orientation of

Copyright IBM Corp. 1996, 2012 51

 the stream is not affected. When you perform one of the wide character
input/output operations on a non-oriented stream, the stream becomes
wide-oriented. When you perform one of the byte input/output operations on
a non-oriented stream, the stream becomes byte-oriented.
Wide-oriented
A stream on which any wide character input/output functions are
guaranteed to operate correctly. Conceptually, wide-oriented streams are
sequences of wide characters. The external file associated with a
wide-oriented stream is a sequence of multibyte characters. Using byte I/O
functions on a wide-oriented stream results in undefined behavior. A stream
opened for record I/O cannot be wide-oriented.
Byte-oriented
A stream on which any byte input/output functions are guaranteed to
operate properly. Using wide character I/O functions on a byte input/output
stream results in undefined behavior. Byte-oriented streams have minimal
support for multibyte characters.

Calls to the clearerr(), feof(), ferror(), fflush(), fgetpos(), or ftell()

functions do not change the orientation. Other functions that do not change the
orientation are ftello(), fsetpos(), fseek(), fseeko(), rewind(), fldata(), and
fileno(). Also, the perror() function does not affect the orientation of the stderr
stream.

Once you have established a stream's orientation, the only way to change it is to
make a successful call to the freopen() function, which removes a stream's
orientation.

The wchar.h header file declares the WEOF macro and the functions that support
wide character input and output. The macro expands to a constant expression of
type wint_t. Certain functions return WEOF type when the end-of-file is reached on
the stream.

Note: The behavior of the wide character I/O functions is affected by the LC_CTYPE
category of the current locale, and the setting of MB_CUR_MAX. Wide-character input
and output should be performed under the same LC_CTYPE setting. If you change
the setting between when you read from a file and when you write to it, or vice
versa, you may get undefined behavior. If you change it back to the original setting,
however, you will get the behavior that is documented. See the introduction of this
chapter for a discussion of the effects of MB_CUR_MAX.

Opening files
You can use the fopen() or freopen() library functions to open I/O files that contain
multibyte characters. You do not need to specify any special parameters on these
functions for wide character I/O.

Reading streams and files

Wide character input functions read multibyte characters from the stream and
convert them to wide characters. The conversion process is performed in the same
way that the mbrtowc() function performs conversions. The following z/OS XL C
library functions support wide character input:
v fgetwc()
v fgetwc_unlocked()

52 z/OS V1R13.0 XL C/C++ Programming Guide

v fgetws()
v fgetws_unlocked()
v fwscanf()
v fwscanf_unlocked()
v getwc()
v getwc_unlocked()
v getwchar()
v getwchar_unlocked()
v vfwscanf()
v vfwscanf_unlocked()
v vwscanf()
v vwscanf_unlocked()
v wscanf()
v wscanf_unlocked()

In addition, the following byte-oriented functions support handling multibyte

characters by providing conversion specifiers to handle the wchar_t data type:
v fscanf()
v fscanf_unlocked()
v scanf()
v scanf_unlocked()
v vfscanf()
v vfscanf_unlocked()
v vscanf()
v vscanf_unlocked()

All other byte-oriented input functions treat input as single-byte.

For a detailed description of unformatted and formatted I/O functions, see z/OS XL
C/C++ Run-Time Library Reference.

The wide-character input/output functions maintain global shift state for multibyte
character streams they read or write. For each multibyte character they read,
wide-character input functions change global shift state as the mbrtowc() function
would do. Similarly, for each multibyte character they write, wide-character output
functions change global shift state as the wcrtomb() function would do.

When you are using wide-oriented input functions, multibyte characters are
converted to wide characters according to the current shift state. Invalid double-byte
character sequences cause conversion errors on input. As z/OS XL C uses
wide-oriented functions to read a stream, it updates the shift state when it
encounters shift-out and shift-in characters. Wide-oriented functions always read
complete multibyte characters. Byte-oriented functions do not check for complete
multibyte characters, nor do they maintain information about the shift state.
Therefore, they should not be used to read multibyte streams.

For binary streams, no validation is performed to ensure that records start or end in
initial shift state. For text streams, however, all records must start and end in initial
shift state.

Chapter 8. z/OS XL C Support for the double-byte character set 53

Writing streams and files
Wide character output functions convert wide characters to multibyte characters and
write the result to the stream. The conversion process is performed in the same
way that the wcrtomb() function performs conversions.

The following z/OS XL C functions support wide character output:

v fputwc()
v fputwc_unlocked()
v fputws()
v fputws_unlocked()
v fwprintf()
v fwprintf_unlocked()
v putwc()
v putwc_unlocked()
v putwchar()
v putwchar_unlocked()
v vfwprintf()
v vfwprintf_unlocked()
v vwprintf()
v vwprintf_unlocked()
v wprintf()
v wprintf_unlocked()

In addition, the following byte-oriented functions support handling multibyte

characters by providing conversion specifiers to handle the wchar_t data type:
v fprintf()
v fprintf_unlocked()
v printf()
v printf_unlocked()
v vfprintf()
v vfprintf_unlocked()
v vprintf()
v vprintf_unlocked()

All other output functions do not support the wchar_t data type. However, all of the
output functions support multibyte character output for text streams if MB_CUR_MAX is
4.

For a detailed description of unformatted and formatted I/O functions, see z/OS XL
C/C++ Run-Time Library Reference.

Writing text streams

When you are using wide-oriented output functions, wide characters are converted
to multibyte characters. For text streams, all records must start and end in initial
shift state. The wide-character functions add shift-out and shift-in characters as they
are needed. When the file is closed, a shift-out character may be added to
complete the file in initial shift state.

54 z/OS V1R13.0 XL C/C++ Programming Guide

When you are using byte-oriented functions to write out multibyte data, z/OS XL C
starts each record in initial shift state and makes sure you complete each record in
initial shift state before moving to the next record. When a string starts with a
shift-out, all data written is treated as multibyte, not single-byte. This means that
you cannot write a single-byte control character (such as a new-line) until you
complete the multibyte string with a shift-in character.

Attempting to write a second shift-out character before a shift-in is not allowed.

z/OS XL C truncates the second shift-out and raises SIGIOERR if SIGIOERR is not set
to SIG_IGN.

When you write a shift-in character to an incomplete multibyte character, z/OS XL C

completes the multibyte character with a padding character (0xfe) before it writes
the shift-in. The padding character is not counted as an output character in the total
returned by the output function; you will never get a return code indicating that you
wrote more characters than you provided. If z/OS XL C adds a padding character,
however, it does raise SIGIOERR, if SIGIOERR is not set to SIG_IGN.

Control characters written before the shift-in are treated as multibyte data and are
not interpreted or validated.

When you close the file, z/OS XL C ensures that the file ends in initial shift state.
This may require adding a shift-in and possibly a padding character to complete the
last multibyte character, if it is not already complete. If padding is needed in this
case, z/OS XL C does not raise SIGIOERR.

Multibyte characters are never split across record boundaries. In addition, all
records end and start in initial shift state. When a shift-out is written to the file,
either directly or indirectly by wide-oriented functions, z/OS XL C calculates the
maximum number of complete multibyte characters that can be contained in the
record with the accompanying shift-in. If multibyte output (including any required
shift-out and shift-in characters) does not fit within the current record, the behavior
depends on what type of file it is (a memory file has no record boundaries and so
never has this particular problem). For a standard stream or terminal file, data is
wrapped from one record to the next. Shift characters may be added to ensure that
the first record ends in initial shift state and that the second record starts in the
required shift state.

For files that are not standard streams, terminal files, or memory files, any attempt
to write data that does not fit into the current record results in data truncation. In
such a case, the output function returns an error code, raises SIGIOERR, and sets
errno and the error flag. Truncation continues until initial state is reached and a
new-line is written to the file. An entire multibyte stream may be truncated, including
the shift-out and shift-in, if there are not at least two bytes in the record. For a
wide-oriented stream, truncation stops when a wchar_t new-line character is written
out.

Updating a wide-oriented file or a file containing multibyte characters is strongly

discouraged, because your update may overwrite part of a multibyte string or
character, thereby invalidating subsequent data. For example, you could
inadvertently add data that overwrites a shift-out. The data after the shift-out is
meaningless when it is treated in initial shift state. Appending new data to the end
of the file is safe.

Chapter 8. z/OS XL C Support for the double-byte character set 55

Writing binary streams
When you are using wide-oriented output functions, wide characters are converted
to multibyte characters. No validation is performed to ensure that records start or
end in initial shift state. When the file is closed, any appends are completed with a
shift-in character, if it is needed to end the stream in initial shift state. If you are
updating a record when the stream is closed, the stream is flushed. See Flushing
buffers for more information.

Byte-oriented output functions do not interpret binary data. If you use them for
writing multibyte data, ensure that your data is correct and ends in initial shift state.

Updating a wide-oriented file or a file containing multibyte characters is strongly

discouraged, because your update may overwrite part of a multibyte string or
character, thereby invalidating subsequent data. For example, you could
inadvertently add data that overwrites a shift-out. The data after the shift-out is
meaningless when it is treated in initial shift state. Appending new data to the end
of the file is safe for a wide-oriented file.

If you update a record after you call fgetpos(), the shift state may change. Using
the fpos_t value with the fsetpos() function may cause the shift state to be set
incorrectly.

Flushing buffers
You can use the library function fflush() to flush streams to the system. For more
information about fflush(), see the z/OS XL C/C++ Run-Time Library Reference.

The action taken by the fflush() library function depends on the buffering mode
associated with the stream and the type of stream. If you call one z/OS XL C
program from another z/OS XL C program by using the ANSI system() function, all
open streams are flushed before control is passed to the callee. A call to the POSIX
system() function does not flush any streams to the system. For a POSIX system
call, we recommend that you do a fflush() before the system call.

Flushing text streams

When you call fflush() after updating a text stream, fflush() calculates your
current shift state. If you are not in initial shift state, z/OS XL C looks forward in the
record to see whether a shift-in character occurs before the end of the record or
any shift-out. If not, z/OS XL C adds a shift-in to the data if it will not overwrite a
shift-out character. The shift-in is placed such that there are complete multibyte
characters between it and the shift-out that took the data out of initial state. z/OS
XL C may accomplish this by skipping over the next byte in order to leave an even
number of bytes between the shift-out and the added shift-in.

Updating a wide-oriented or byte-oriented multibyte stream is strongly discouraged.

In a byte-oriented stream, you may have written only half of a multibyte character
when you call fflush(). In such a case, z/OS XL C adds a padding byte before the
shift-out. For both wide-oriented and byte-oriented streams, the addition of any shift
or padding character does not move the current file position.

Calling fflush() has no effect on the current record when you are writing new data
to a wide-oriented or byte-oriented multibyte stream, because the record is
incomplete.

56 z/OS V1R13.0 XL C/C++ Programming Guide

Flushing binary streams
In a wide-oriented stream, calling fflush() causes z/OS XL C to add a shift-in
character if the stream does not already end in initial shift state. In a byte-oriented
stream, calling fflush() causes no special behavior beyond what a call to fflush()
usually does.

ungetwc() considerations
ungetwc() pushes wide characters back onto the input stream for binary and text
files. You can use it to push one wide character onto the ungetwc() buffer. Never
use ungetc() on a wide-oriented file. After you call ungetwc(), calling fflush()
backs up the file position by one wide character and clears the pushed-back wide
character from the stream. Backing up by one wide character skips over shift
characters and backs up to the start of the previous character (whether single-byte
or double-byte). For text files, z/OS XL C counts the new-lines added to the records
as single-byte characters when it calculates the file position. For example, if you
have the following stream,

A B SO X'FE' X'7F' SI C

fp

you can run the code fragment shown in Figure 5.

fgetwc(fp); /* Returns X'00C1' (the hexadecimal */

/* wchar representation of A) */
fgetwc(fp); /* Returns X'00C2' (the hexadecimal */
/* wchar representation of B) */
fgetwc(fp); /* Returns X'7FFE' (the hexadecimal */
/* wchar representation of the DBCS */
/* character) between the SO and SI */
/* characters; leaves file position at C */
ungetwc(Z,fp); /* Logically inserts Z before SI character */
fflush(fp); /* Backs up one wchar, leaving position at */
/* beginning of X'7FFE' DBCS char */
/* and DBCS state in double-byte mode; */
/* clears Z from the logical stream */

Figure 5. ungetwc() Example

You can set the _EDC_COMPAT environment variable before you open the file, so that
fflush() ignores any character pushed back with ungetwc() or ungetc(), and leaves
the file position where it was when ungetwc() or ungetc() was first issued. Any
characters pushed back are still cleared. For more information about _EDC_COMPAT,
see Chapter 32, Using environment variables, on page 467.

Setting positions within files

The following conditions apply to text streams and binary streams.

Repositioning within text streams

When you use the fseek() or fsetpos() function to reposition within files, z/OS XL
C recalculates the shift state.

Chapter 8. z/OS XL C Support for the double-byte character set 57

 If you update a record after a successful call to the fseek() function or the
fsetpos() function, a partial multibyte character can be overwritten. Calling a wide
character function for data after the written character can result in undefined
behavior.

Use the fseek() or fsetpos() functions to reposition only to the start of a multibyte
character. If you reposition to the middle of a multibyte character, undefined
behavior can occur.

Repositioning within binary streams

When you are working with a wide-oriented file, keep in mind the state of the file
position that you are repositioning to. If you call ftell(), you can seek with
SEEK_SET and the state will be reset correctly. You cannot use such an ftell()
value across a program boundary unless the stream has been marked
wide-oriented. A seek specifying a relative offset (SEEK_CUR or SEEK_END) will
change the state to initial state. Using relative offsets is strongly discouraged,
because you may be seeking to a point that is not in initial state, or you may end
up in the middle of a multibyte character, causing wide-oriented functions to give
you undefined behavior. These functions expect you to be at the beginning or end
of a multibyte character in the correct state. Using your own offset with SEEK_SET
also does the same. For a wide-oriented file, the number of valid bytes or records
that ftell() supports is cut in half.

When you use the fsetpos() function to reposition within a file, the shift state is set
to the state saved by the function. Use this function to reposition to a wide
character that is not in the initial state.

ungetwc() considerations
For text files, the library functions fgetpos() and ftell() take into account the
character you have pushed back onto the input stream with ungetwc(), and move
the file position back by one wide character. The starting position for an fseek() call
with a whence value of SEEK_CUR also takes into account this pushed-back wide
character. Backing up one wide character means backing up either a single-byte
character or a multibyte character, depending on the type of the preceding
character. The implicit new-lines at the end of each record are counted as wide
characters.

For binary files, the library functions fgetpos() and ftell() also take into account
the character you have pushed back onto the input stream with ungetwc(), and
adjust the file position accordingly. However, the ungetwc() must push back the
same type of character just read by fgetwc(), so that ftell() and fgetpos() can
save the state correctly. An fseek() with an offset of SEEK_CUR also accounts for
the pushed-back character. Again, the ungetwc() must unget the same type of
character for this to work properly. If the ungetwc() pushes back a character in the
opposite state, you will get undefined behavior.

You can make only one call to ungetwc(). If the current logical file position is
already at or before the first wchar in the file, a call to ftell() or fgetpos() after
ungetwc() fails.

When you are using fseek() with a whence value of SEEK_CUR, the starting point
for the reposition also accounts for the presence of ungetwc() characters and
compensates as ftell() and fgetpos() do. Specifying a relative offset other than 0
is not supported and results in undefined behavior.

58 z/OS V1R13.0 XL C/C++ Programming Guide

 You can set the _EDC_COMPAT environment variable to specify that ungetwc() should
not affect fgetpos() or fseek(). (It will still affect ftell().) If the environment
variable is set, fgetpos() and fseek() ignore any pushed-back wide character. See
Chapter 32, Using environment variables, on page 467 for more information about
_EDC_COMPAT.

If a repositioning operation fails, z/OS XL C attempts to restore the original file

position by treating the operation as a call to fflush(). It does not account for the
presence of ungetwc() characters, which are lost.

Closing files
z/OS XL C expects files to end in initial shift state. For binary byte-oriented files,
you must ensure that the ending state of the file is initial state. Failure to do so
results in undefined behavior if you reaccess the file again. For wide-oriented
streams and byte-oriented text streams, z/OS XL C tracks new data that you add. If
necessary, z/OS XL C adds a padding byte to complete any incomplete multibyte
character and a shift-in to end the file in initial state.

Manipulating wide character array functions

To manipulate wide character arrays in your program, you can use the functions
shown in Table 8. For more information about these functions, refer to z/OS XL
C/C++ Run-Time Library Reference.
Table 8. Manipulating wide character arrays
Function Purpose
wmemcmp() Compare wide character
wmemchr() Locate wide character
wmemcpy() Copy wide character
wmemmove() Move wide character
wmemset() Set wide character
wcrtomb() Convert a wide character to a multibyte character
wcscat() Append to wide-character string
wcschr() Search for wide-character substring
wcscmp() Compare wide-character strings

Chapter 8. z/OS XL C Support for the double-byte character set 59

60 z/OS V1R13.0 XL C/C++ Programming Guide
Chapter 9. Using C and C++ standard streams and redirection
The standard streams are declared in the C header file stdio.h or in the C++
header files iostream.h or iostream. Table 9 shows the C standard streams and the
functions that use them, as well as the C++ standard streams and the operators
typically used to perform I/O with them.

By default, the standard streams are opened implicitly the first time they are
referenced. You do not have to declare them or call their open() member functions
to open them. For example, with no preceding declaration or open() call, the
following statement writes the decimal number n to the cout stream.
cout << n << endl;

For more detailed information about C++ I/O streaming, see the following:
v z/OS XL C/C++ Run-Time Library Reference discusses the C I/O stream
functions
v Standard C++ Library Reference discusses the Standard C++ I/O stream classes
Table 9. Standard C and C++ streams
Stream Purpose Functions that use it
name
C standard streams and their related functions
stdin The input device from which your C program usually getchar()
retrieves its data. getchar_unlocked()
gets()
gets_unlocked()
scanf()
scanf_unlocked()
vscanf()
vscanf_unlocked()
wscanf()
wscanf_unlocked()
vwscanf()
vwscanf_unlocked()
stdout The output device to which your C program normally printf()
directs its output. printf_unlocked()
puts()
puts_unlocked()
putchar()
putchar_unlocked()
vprintf()
vprintf_unlocked()
wprintf()
wprintf_unlocked()
vwprintf()
vwprintf_unlocked()
stderr The output device to which your C program directs perror()
its diagnostic messages. z/OS XL C/C++ uses perror_unlocked()
stderr to collect error messages about exceptions
that occur.
C++ standard streams and the operators typically used with them
Stream Purpose Common usage
name

Copyright IBM Corp. 1996, 2012 61

 Table 9. Standard C and C++ streams (continued)
cin The object from which your C++ program usually >>, the input
retrieves its data. In z/OS XL C++, input from cin (extraction) operator
comes from stdin by default.
cout The object to which your C++ program normally <<, the output
directs its output. In z/OS XL C++, output to cout (insertion) operator
goes to stdout by default.
cerr The object to which your C++ program normally <<, the output
directs its diagnostic messages. In z/OS XL C++, (insertion) operator
output to cerr goes to stderr by default. cerr is
unbuffered, so each character is flushed as you write
it.
clog Another object intended for error messages. In z/OS <<, the output
XL C++, output to clog goes to stderr by default. (insertion) operator
Unlike cerr, clog is buffered.

On I/O operations requiring a file pointer, you can use stdin, stdout, or stderr in
the same manner as you would any other file pointer.

If you are running with POSIX(ON), standard streams are opened during initialization
of the process, before the application receives control. With POSIX(OFF), the default
behavior is for the C standard streams to open automatically on first reference. You
do not have to call fopen() to open them. For example, if the following statement is
specified without a preceding fopen() statement, it writes the decimal number n to
the stdout stream.
printf("%d\n",n);

By default, stdin interprets the character sequence /* as indicating that the end of
the file has been reached. See Chapter 13, Performing terminal I/O operations, on
page 189 for more information.

Default open modes

The default open modes for the C standard streams are:
stdin r
stdout w
stderr w

Where the streams go depends on what kind of environment you are running under.
These are the defaults:
v Under interactive TSO, all three standard streams go to the terminal.
v Under MVS batch, TSO batch, and IMS (batch and interactive):
stdin goes to dd:sysin. If dd:sysin does not exist, all read operations from
stdin will fail.
stdout goes first to dd:sysprint. If dd:sysprint does not exist, stdout looks
for dd:systerm and then dd:syserr. If neither of these files exists, z/OS XL
C/C++ opens a sysout=* data set and sends the stdout stream to it.
stderr will go to the z/OS Language Environment message file. In AMODE 64
applications, stderr goes to dd:sysout.

Note: When a standard stream is allocated to a large format sequential data set,
the stream will be opened without repositioning (noseek). In this situation, the
open is initially attempted with repositioning (seek), fails with an ABEND 213-14

62 z/OS V1R13.0 XL C/C++ Programming Guide

 or 213-16, and the stream is then opened without repositioning. For more
information on large format sequential data sets, see Large format sequential
data sets on page 94.
v Under CICS, stdout and stderr are assigned to transient data queues, allocated
during CICS initialization. The CICS standard streams can be redirected only to
or from memory files. You can do this by using freopen().
v Under z/OS UNIX, if you are running in one of the z/OS UNIX shells, the shell
controls redirection. See z/OS UNIX System Services User's Guide and z/OS
UNIX System Services Command Reference for information.

You can also redirect the standard streams to other files. See Redirecting standard
streams and sections following.

Interleaving the standard streams with sync_with_stdio()

The sync_with_stdio() function allows you to interleave C standard streams with
standard streams from either the Standard C++ Library or the USL I/O Stream
Class Library. A call to sync_with_stdio() does the following:
v cin, cout, cerr, and clog are initialized with stdiobuf objects associated with
stdin, stdout, and stderr.
v The flags unitbuf and stdio are set for cout, cerr, and clog.

This ensures that subsequent standard streams may be mixed on a per-character

basis. However, a run-time performance penalty is incurred to ensure this
synchronization. Figure 6 shows an example program and the output that it
produces.

//
// Example of interleaving USL I/O with sync_with_stdio()
//
// tsyncws.cxx
#include <stdio.h>
#include <fstream.h>

int main() {
ios::sync_with_stdio();
cout << "object: to show that sync_with_stdio() allows interleaving\n "
" standard input and output on a per character basis\n" << endl;

printf( "line 1 ");

cout << "rest of line 1\n";
cout << "line 2 ";
printf( "rest of line 2\n\n");

char string1[80] = "";

char string2[80] = "";
char string3[80] = "";
char* rc = NULL;

cout << "type the following 2 lines:\n"

"hello world, here I am\n"
"again\n" << endl;

Figure 6. Interleaving I/O with sync_with_stdio() (Part 1 of 2)

Chapter 9. Using C and C++ standard streams and redirection 63

 cin.get(string1[0]);
string1[1] = getchar();
cin.get(string1[2]);

cout << "\nstring1[0] is \" << string1[0] << "\\n"

<< "string1[1] is \" << string1[1] << "\\n"
<< "string1[2] is \" << string1[2] << "\\n" << endl;

cin >> &string1[3];

rc = gets(string2); // note: reads to end of line, so
cin >> string3; // this line waits for more input

cout << "\nstring1 is \"" << string1 << "\"\n"

<< "string2 is \"" << string2 << "\"\n"
<< "string3 is \"" << string3 << "\"\n" << flush;
}

// sample output (with user input shown underlined):

//
// object: to show that sync_with_stdio() allows interleaving
// standard input and output on a per character basis
//
// line 1 rest of line 1
// line 2 rest of line 2
//
// type the following 2 lines:
// hello world, here I am
// again
//
// hello world, here I am
//
// string1[0] is h
// string1[1] is e
// string1[2] is l
//
// again
//
// string1 is "hello"
// string2 is "world, here I am"
// string3 is "again"

Figure 6. Interleaving I/O with sync_with_stdio() (Part 2 of 2)

Interleaving the standard streams without sync_with_stdio()

Output can be interleaved without sync_with_stdio(), since the C++ standard
streams are based on z/OS XL C I/O. That is, cout can be interleaved with stdout,
and clog can be interleaved with stderr. This is done by explicitly flushing cout or
clog before calling the z/OS XL C output function. Results of attempting to
interleave these streams without explicitly flushing, are undefined. Output to cerr
doesn't have to be explicitly flushed, since cerr is unit-buffered.

Input to cin may be interleaved with input to stdin, without sync_with_stdio(), on

a line-by-line basis. Results of attempting to interleave on a per-character basis are
undefined. Figure 7 on page 65 shows an example program and the output it
produces.

64 z/OS V1R13.0 XL C/C++ Programming Guide

// Example of interleaving I/O without sync_with_stdio()
//
// tsyncwos.cxx
#include <stdio.h>
#include <fstream.h>

int main() {
cout << "object: to illustrate interleaving input and output\n "
" without sync_with_stdio()\n" << endl;

printf( "interleaving output ");

cout << "works with an (end of line 1) \n" << flush;
cout << "explicit flush of cout " << flush;
printf( "(end of line 2)\n\n");

char string1[80] = "";

char string2[80] = "";
char string3[80] = "";
char* rc = NULL;

cout << "type the following 3 lines:\n"

"interleaving input\n"
"on a per-line basis\n"
"is supported\n" << endl;

cin.getline(string1, 80);
rc = gets(string2);
cin.getline(string3, 80);

cout << "\nstring1 is \"" << string1 << "\"\n"

<< "string2 is \"" << string2 << "\"\n"
<< "string3 is \"" << string3 << "\"\n" << endl;
// The endl manipulator inserts a newline
// character and calls flush().

char char1 = \0;

char char2 = \0;
char char3 = \0;

cout << "type the following 2 lines:\n"

"results of interleaving input on a per-\n"
"character basis are not defined\n" << endl;

cin >> char1;

char2 = (char) getchar();
cin >> char3;

cout << "\nchar1 is \" << char1 << "\\n"

<< "char2 is \" << char2 << "\\n"
<< "char3 is \" << char3 << "\\n" << flush;
}

Figure 7. Interleaving I/O without sync_with_stdio() (Part 1 of 2)

Chapter 9. Using C and C++ standard streams and redirection 65

 // sample output (with user input shown underlined):
//
// object: to illustrate interleaving input and output
// without sync_with_stdio()
//
// interleaving output works with an (end of line 1)
// explicit flush of cout (end of line 2)
//
// type the following 3 lines:
// interleaving input
// on a per-line basis
// is supported
//
// interleaving-input
// on a per-line basis
// is supported
//
// string1 is "interleaving input"
// string2 is "on a per-line basis"
// string3 is "is supported"
//
// type the following 2 lines:
// results of interleaving input on a per-
// character basis are not defined
//
// results of interleaving input on a per-
// character basis are not defined
//
// char1 is r
// char2 is c
// char3 is e

Figure 7. Interleaving I/O without sync_with_stdio() (Part 2 of 2)

Redirecting standard streams

This section describes redirection of standard streams:
v From the command line
v By assignment
v With freopen()
v With the MSGFILE run-time option

Note that, C++ standard streams are implemented in terms of C standard streams.
Therefore, cin, cout, cerr, and clog are implicitly redirected when the
corresponding C standard streams are redirected. These streams can be redirected
by assignment, as described in Assigning the standard streams on page 68. If
freopen() is applied to a C standard stream, creating a binary stream or one with
"type=record", then behavior of the related stream is undefined.

Redirecting streams from the command line

To redirect a standard stream to a file from the command line, invoke your program
by entering the following:
1. Program name
2. Any parameters your program requires (these may be specified before and after
the redirection)

66 z/OS V1R13.0 XL C/C++ Programming Guide

 3. A redirection symbol followed by the name of the file that is to be used in place
of the standard stream

Note: If you specify a redirection in a system() call, after system() returns, the
streams are redirected back to those at the time of the system() call.

Using the redirection symbols

The following table lists the redirection symbols supported by z/OS XL C/C++ (when
not running under one of the z/OS UNIX shells) for redirection of C standard
streams from the command line or from a system() call. 0, 1, and 2 represent
stdin, stdout, and stderr, respectively.
Table 10. z/OS XL C/C++ Redirection symbols
Symbol Description
<fn associates the file specified as fn with stdin; reopens fn in mode r.
0<fn associates the file specified as fn with stdin; reopens fn in mode r.
>fn associates the file specified as fn with stdout; reopens fn in mode w.
1>fn associates the file specified as fn with stdout; reopens fn in mode w.
>>fn associates the file specified as fn with stdout; reopens fn in mode a.
2>fn associates the file specified as fn with stderr; reopens fn in mode w.
2>>fn associates the file specified as fn with stderr; reopens fn in mode a.
2>&1 associate stderr with stdout; same file and mode.
1>&2 associate stdout with stderr; same file and mode.

Notes:
1. If you use the NOREDIR option on a #pragma runopts directive, or the
NOREDIR compile-time option, you cannot redirect standard streams on the
command line using the preceding list of symbols.
2. If you want to pass one of the redirection symbols as an argument, you can
enclose it in double quotation marks. For example, the following passes the
string "here are the args including a <" to prog and redirects stdout to
redir1 output a.
prog "here are args including a <" >"redir1 output a"
3. TSO (batch and online) and MVS batch support command line arguments. CICS
and IMS do not.
4. When two options specifying redirection conflict with each other, or when you
redirect a standard stream more than once, the redirection fails. If you do the
latter, you will get an abend. For example, if you specify
2>&1
and then
1>&2
z/OS XL C/C++ uses the first redirection and ignores any subsequent ones. If
you specify
>a.out
and then
1>&2
the redirection fails and the program abends.
5. A failed attempt to redirect a standard stream causes your program to fail in
initialization.

Chapter 9. Using C and C++ standard streams and redirection 67

 6. The C standard streams can be redirected to large format sequential data sets.
If this occurs, the stream will be reopened without repositioning (noseek). In this
situation, the reopen is initially attempted with repositioning (seek), fails with an
ABEND 213-14 or 213-16, and the stream is then reopened without
repositioning.

Assigning the standard streams

This method of redirecting streams is known as direct assignment. You can redirect
a C standard stream by assigning a valid file pointer to it, as follows:
FILE *stream;
stream = fopen("new.file", "w+");
stdout = stream;

You must ensure that the streams are appropriate; for example, do not assign a
stream opened for w to stdin. Doing so would cause a function such as getchar()
called for the stream to fail, because getchar() expects a stream to be opened for
read access.

Similarly, you can redirect a standard stream under C++ by assignment:

ofstream myfile("myfile.data");
cout = myfile;

Again, you must ensure that the assigned stream is appropriate; for example, do
not assign an fstream opened for ios::out only to cin. This will cause a
subsequent read operation to fail.

Using the freopen() library function

You can use the freopen() C library function to redirect C standard streams in all
environments.

Redirecting streams with the MSGFILE option

Restriction: This section does not apply to AMODE 64.

You can redirect stderr by specifying a ddname on the MSGFILE run-time option and
not redirecting stderr elsewhere (such as on the command line). The default
ddname for the z/OS Language Environment MSGFILE is SYSOUT. See z/OS
Language Environment Programming Guide for more information on MSGFILE.

MSGFILE considerations
z/OS XL C/C++ makes a distinction between types of error output according to
whether the output is directed to the MSGFILE, to stderr, or to stdout:
Table 11. Output destinations under z/OS XL C/C++
Destination of Type of Message Produced by Default Destination
Output
MSGFILE output z/OS Language z/OS Language MSGFILE ddname
Environment Environment
messages (CEExxxx) conditions
z/OS XL C/C++ z/OS XL C/C++ MSGFILE ddname
language messages unhandled conditions
(EDCxxxx)

68 z/OS V1R13.0 XL C/C++ Programming Guide

Table 11. Output destinations under z/OS XL C/C++ (continued)
Destination of Type of Message Produced by Default Destination
Output
stderr messages perror() messages Issued by a call, for MSGFILE ddname
(EDCxxxx) example, to: perror() (see note 1)
User output sent Issued by a call to MSGFILE ddname
explicitly to stderr fprintf()
stdout messages User output sent Issued by a call, for stdout (see note 2)
explicitly to stdout example, to: printf()

Notes:
1. When you are using one of the z/OS UNIX shells, stderr will go to file descriptor 2,
which is typically the terminal. See Chapter 16, Language Environment Message file
operations, on page 215 for more information about z/OS Language Environment
message files.
2. When you are using one of the z/OS UNIX shells, stdout will go to file descriptor 1,
which is typically the terminal.

All stderr output is by default sent to the MSGFILE destination, while stdout output
is sent to its own destination. When stderr is redirected to stdout, both share the
stdout destination. When stdout is redirected to stderr, both share the stderr
destination.

If you specified one of the DDs used in the stdout open search order as the DD for
the MSGFILE option, then that DD will be ignored in the stdout open search.

Table 12 describes the destination of output to stderr and stdout after redirection
has occurred. Whenever stdout and stderr share a common destination, the
output is interleaved. The default case is the one where stdout and stderr have
not been redirected.
Table 12. z/OS XL C/C++ Interleaved output
stderr not stderr redirected to stderr redirected to
redirected destination other stdout
than stdout
stdout not stdout to itself stderr stdout to itself stderr Both to stdout
redirected to MSGFILE to its other destination
stdout redirected to stdout to its other stdout to its other Both to the new
destination other destination stderr to destination stderr to stdout destination
than stderr MSGFILE its other destination
stdout redirected to Both to MSGFILE Both to the new stdout to stderr
stderr stderr destination stderr to stdout

z/OS XL C/C++ routes error output as follows:

v MSGFILE output
z/OS Language Environment messages (messages prefixed with CEE)
Language messages (messages prefixed with EDC)
v stderr output
perror messages (messages prefixed with EDC and issued by a call to
perror())
Output explicitly sent to stderr (for example, by a call to fprintf())

Chapter 9. Using C and C++ standard streams and redirection 69

 By default, z/OS XL C/C++ sends all stderr output to the MSGFILE destination
and stdout output to its own destination. You can change this by using z/OS XL
C/C++ redirection, which enables you to redirect stdout and stderr to a ddname,
file name, or each other. Unless you have redirected stderr, it always uses the
MSGFILE destination. When you redirect stderr to stdout, stderr and stdout
share the stdout destination. When you redirect stdout to stderr, they share the
stderr destination.

Redirecting streams under z/OS

This section describes how to redirect C standard streams under MVS batch and
under TSO.

Restrictions: The following restrictions apply to AMODE 64 applications:

v IMS and CICS environments are not supported in AMODE 64 applications
v The Language Environment Message File (MSGFILE) is not supported in
AMODE 64 applications
v The stderr stream goes to the ddname SYSOUT in AMODE 64 applications

Under MVS batch

You can redirect standard streams in the following ways:
v From the freopen() library function call
v On the PARM parameter of the EXEC used to invoke your C or C++ program
v Using DD statements

Because the topic of JCL statements goes beyond the scope of this book, only
simple examples will be shown here.

Using the PARM parameter of the EXEC statement

The following example shows an excerpt taken from a job stream. It demonstrates
both the redirection of stdout using the PARM parameter of the EXEC statement, and
the way to redirect to a fully qualified data set. You can use the redirection symbols
described in Table 10 on page 67.

Suppose you have a program called BATCHPGM, with 1 required parameter DEBUG.
The output from BATCHPGM is to be directed to a sequential data set called
MAINT.LOG.LISTING. You can use the following JCL statements:

//JOBname JOB...
. //STEP01 EXEC PGM=BATCHPGM,PARM=DEBUG >MAINT.LOG.LISTING
.
.

The following JCL redirects output to an unqualified data set using the same
program name, parameter and output data set as the example above:

//STEP01 EXEC PGM=BATCHPGM,PARM=DEBUG >LOG.LISTING

If your user ID was TSOU812, stdout would be sent to TSOU812.LOG.LISTING.

70 z/OS V1R13.0 XL C/C++ Programming Guide

Using DD statements
When you use DD statements to redirect standard streams, the standard streams
will be associated with ddnames as follows:
v stdin will be associated with the SYSIN ddname. If SYSIN is not defined, no
characters can be read in from stdin.
v stdout will be associated with the SYSPRINT ddname. If SYSPRINT is not defined,
the C library will try to associate stdout with SYSTERM, and if SYSTERM is also not
defined, the C library will try to associate stdout with SYSERR. If any of the above
DD statements are used as the MSGFILE DD, then that DD statement will not be
considered for use as the stdout DD.
Restriction: The reference to the MSGFILE does not apply to AMODE 64
applications.
v stderr will be associated with the MSGFILE, which defaults to SYSOUT. See z/OS
Language Environment Programming Guide for more information on MSGFILE.
Restriction: The reference to the MSGFILE does not apply to AMODE 64
applications.
v If you are running with the run-time option POSIX(ON), you can redirect standard
streams with ddnames only for MVS data sets, not for UNIX file system files.
v If the ddname for stdout is not allocated to a device or data set, it is dynamically
allocated to the terminal in an interactive environment or to SYSOUT=* in an MVS
batch environment.

Table 13 summarizes the association of streams with ddnames:

Table 13. Association of standard streams with ddnames
Standard stream ddname Alternate ddname
stdin SYSIN none
stdout SYSPRINT SYSTERM, SYSERR
stderr DD associated with MSGFILE. For AMODE 64 None
applications stderr is SYSOUT, and there is no
alternate ddname.

Figure 8 shows excerpt from an MVS example job stream that demonstrates the
redirection of the three standard streams by using ddnames. In the example, your
program name is MONITOR and the input to MONITOR is to be retrieved from a
sequential data set called SAFETY.CHEM.LIST. The output of MONITOR is to be
directed to a partitioned data set member called YEAREND.ACTION(CHEM), and any
errors generated by MONITOR are to be written to a sequential data set called
YEAREND.MONITOR.ERRLIST. To redirect the standard streams using DD statements,
you could use the JCL statements shown in Figure 8.

//JOBname JOB...
. //STEP01 EXEC PGM=MONITOR,PARM=MSGFILE(SYSERR)/
.
.
//SYSIN DD DSN=SAFETY.CHEM.LIST,DISP=OLD
//SYSERR DD DSN=YEAREND.MONITOR.ERRLIST,DISP=MOD
. //SYSPRINT DD DSN=YEAREND.ACTION(CHEM),DISP=OLD
.
.

Figure 8. MVS example of redirecting three standard streams by ddnames

Chapter 9. Using C and C++ standard streams and redirection 71

 Figure 9 shows how to get stdout and stderr to share the same file where: the
program name is HOCKEY and the input to HOCKEY is to be retrieved from a sequential
data set called HOCKEY.PLAYER.LIST. The output of HOCKEY is to be directed to a
sequential data set called HOCKEY.OUTPUT and any errors generated by HOCKEY are
also to be written to the sequential data set HOCKEY.OUTPUT. You could use the
JCL statements shown in Figure 9.

//JOBname JOB...
//STEP01 EXEC PGM=HOCKEY,PARM=/ 2>&1
//SYSIN DD DSN=HOCKEY.PLAYER.LIST,DISP=SHR
//SYSPRINT DD DSN=HOCKEY.OUTPUT,DISP=(OLD),DCB=...

Figure 9. Example of using stdout and stderr to share the same file

stderr shares stdout because of the 2>&1 redirection statement.

If you want to redirect to a UNIX file system file, you can modify the above
examples to use the PATH and PATHOPT options described in DDnames on page 34.

Under TSO
You can redirect standard streams in the following ways:
v From the freopen() library function call
v From the command line
v Using the parameter list in a CALL command

From the command line

The following example illustrates the redirection of stdin under TSO. The program
in this example is called BUILD and it has 2 required parameters, PLAN and
JOHNSTON. The input to BUILD is to be retrieved from a partitioned data set
member called CONDO(SPRING). To redirect stdin in this example under TSO you
can use the following command:
BUILD PLAN JOHNSTON <CONDO(SPRING)
Notes:
1. If the data set name is not enclosed in quotation marks, your user prefix will be
appended to the data set name specified.
2. If you specify a redirection in a system() call, after system() returns, the
streams are redirected back to those at the time of the system() call.

Using the parameter list in a CALL command

You can also redirect the output to a file with a ddname in TSO by specifying the
output file in the parameter list like the following:
CALL PREFIX.PROGRAM >DD:OUTFILE

The ddname can be created by an ALLOCATE command.

Under IMS
Under IMS online and batch, you can redirect the C standard streams in any of the
following ways:
v with direct assignment
v with the freopen() function
v with ddnames

72 z/OS V1R13.0 XL C/C++ Programming Guide

 For details on ddnames, see Using DD statements on page 71.

Under CICS
There are several ways to redirect C standard streams under CICS:
v You can assign a memory file to the stream (for example, stdout=myfile).
v You can use freopen() to open a standard stream as a memory file.
v You can use CICS facilities to direct where the stream output goes.

If you assign a file pointer to a stream or use freopen() on it, you will not be able
to use C functions to direct the information outside or elsewhere in the CICS
environment. Once access to a CICS transient data queue has been removed,
either by a call to freopen() or fclose(), or by the assignment of another file
pointer to the stream, z/OS XL C/C++ does not provide a way to regain access.
Once C functions have lost access to the transient data queues, you must use the
CICS-provided facilities to regain it.

CICS provides a facility that enables you to direct where a given transient data
queue, the default standard stream implementation, will go, but you must configure
this facility before a CICS cold start.

Passing C and C++ standard streams across a system() call

Restriction: ANSI system() is not supported in AMODE 64, but references to POSIX
system() apply to all applications.

A system() call occurs when one z/OS XL C/C++ program calls another z/OS XL
C/C++ program by using the ANSI system() function, which z/OS XL C/C++ uses if
you are not running with POSIX(ON). Standard streams are inherited across calls to
the ANSI system() function. With a POSIX system() function, file descriptors 0, 1,
and 2 will be mapped to standard streams stdin, stdout and stderr in the child
process. The behavior of these streams is similar to binary streams called with the
ANSI system() function.

Inheritance includes any redirection of the stream as well as the open mode of the
stream. For example, if program A reopens stdout as "A.B" for "wb" and then calls
program B, program B inherits the definition of stdout. If program B reopens stdout
as "C.D" for "ab" and then uses system() to call program C, program C inherits
stdout opened to "C.D" for append. Once control returns to the calling program, the
definitions of the standard streams from the time of the system() call are restored.
For example, when program B finally returns control to program A, stdout is
restored to "A.B" opened for "wb".

The file position and the amount of data that is visible in the called and calling
programs depend on whether the standard streams are opened for binary, text, or
record I/O.

The behavior of the C standard streams across a system() call indicates the
behavior of all standard streams since they are implemented in terms of the C
standard streams.

Passing binary streams

If the standard stream being passed across a system() call is opened in binary
mode, any reads or writes issued in the called program occur at the next byte in the
file. On return, the position of the file is wherever the called program is positioned.

Chapter 9. Using C and C++ standard streams and redirection 73

 This includes any possible repositions made by the called program if the file is
enabled for positioning. Because output to binary files is done byte by byte, all
bytes are written to stdout and stderr in the order they are written. This is shown
in the following example:
printf("123");
printf("456");
system("CHILD"); ------> int main(void) { putc(7,stdout);}
printf("89");

The output from this example is: 123456789

Memory files are always opened in binary mode, even if you specify text. Any
standard streams redirected to memory files and passed across system() calls will
be treated as binary files. UNIX file system files are also treated as binary files,
because they do not contain any real record boundaries. Memory files are not
passed across calls to the POSIX system() function.

If freopen() is applied to a C standard stream, thereby creating a binary stream,

then the results of I/O to the associated standard stream across a system() call are
undefined.

Passing text streams

If the C standard stream being passed across a system() call is opened in text
mode (the default), the file position in the called program is placed at the next
record boundary, if it is not already at the start of a record. Any data in the current
record that is unread is skipped. Figure 10 show an example.

INPUT FILE ROOT C PROGRAM CHILD PROGRAM

---------- int main() { int main() {
abcdefghijklm char c[4]; char d[2];
nopqrstuvwxyz c[0] = getchar(); d[0] = getchar();
0123456789ABC c[1] = getchar(); d[1] = getchar();
DEFGHIJKLMNOP system("CHILD"); printf("%.2s\n",
c[2] = getchar(); d);
c[3] = getchar(); }
printf("%.4s\n",c);
}

OUTPUT
------
no ---> from the child
ab01 ---> from root

Figure 10. Example of passing text streams

When you write to a spanned file, the file position moves to the beginning of the
next record, if that record exists. If not, the position moves to the end of the
incomplete record.

For non-spanned standard streams opened for output, if the caller has created a
text record missing an ending control character, the last record is hidden from the
called program. The called program can append new data if the stream is open in
append mode. Any appends made by the called program will be after the last
record that was complete at the time of the system() call.

When the called program terminates, it completes any new unfinished text record
with a new-line; the addition of the new-line does not move the file position. Once

74 z/OS V1R13.0 XL C/C++ Programming Guide

any incomplete record is completed, the file position moves to the next record
boundary, if it is not already on a record boundary or at EOF.

When control returns to the original caller, any incomplete record hidden at the time
of the system() call is restored to the end of the file. If the called program is at EOF
when it is terminated and the caller was within an incomplete record at the time of
the system() call, the position upon return is restored to the original record offset at
the time of the system() call. This position is usually the end of the incomplete
record. Generally, if the caller is writing to a standard stream and does not complete
the last record before it calls system(), writes continue to add to the last record
when control returns to the caller. For example:

printf("test");
printf("abc");
system("hello"); ------> int main(void) { printf("hello world\n");}
printf("def\n");

The output from this example is as follows:

test
hello world
abcdef

If stdout had been opened for "w+" in this example, and a reposition had been
made to the character b before the system() call, upon return, the incomplete
record "abc" would have been restored and the position would have been at the
b. The subsequent write of def would have performed an update to give test
hello world adef.

C++ standard streams considerations

The following sections are considerations for C++ standard streams.

Output with sync_with_stdio(): When a standard output stream is open in text

mode (the default), and sync_with_stdio() has been called, the output across a
system() call behaves the same as a C standard stream:
v If the parent program writes a newline character, the line will be flushed before
the child program is invoked;
v Otherwise, the output from the parent will be held in a buffer until the child
returns.

Output without sync_with_stdio(): When a standard output stream is open in

text mode, and sync_with_stdio() has not been called, the behavior is as follows:
v If the parent program writes a newline character, and explicitly flushes it, the line
will be written out before the child program is invoked;
v Otherwise, the behavior is undefined.

Input with sync_with_stdio(): When cin is open in text mode (the default), and
sync_with_stdio() has been called, the input across a system() call behaves the
same as stdin:
v The child program begins reading at the next record boundary, that is, unread
data in the current record in the parent is hidden.
v When the child program returns, the parent program begins reading at the next
record boundary, that is, unread data in the current record in the child is lost.

Input without sync_with_stdio(): When cin is open in text mode, and

sync_with_stdio() has not been called, the behavior is as follows:

Chapter 9. Using C and C++ standard streams and redirection 75

 v The parent program must either not read from cin before calling the child, or
must read to the end of a complete record.
v The child program begins reading at the next record boundary, that is, unread
data in the current record in the parent is hidden.
v When the child program returns, the parent program begins reading at the next
record boundary, that is, unread data in the current record in the child is lost.
v If the parent program read only part of a record before calling the child, the
behavior upon returning from the child is undefined.

Passing record I/O streams

For record I/O, all reads and writes made by the called program occur at the next
record boundary. Since complete records are always read and written, there is no
change in the file position across a system() call boundary.

In the example shown in Figure 11, stdout is a variable-length record I/O file.

fwrite("test",1,4,stdout);
fwrite("abc",1,3,stdout);
system("hello"); ------> int main(void) {
fwrite("def",1,3,stdout); fwrite("hello world",1,11,stdout)
}

Figure 11. Example of passing record I/O streams

The output from this code fragment is as follows:

test
abc
hello world
def

If freopen() is applied to a C standard stream, creating a stream with

"type=record", then behavior of the associated I/O stream is undefined across a
system() call.

Using global standard streams

Restriction: This section does not apply to AMODE 64.

In the default inheritance model, the behavior of C standard streams is such that a
child main() function cannot affect the standard streams of the parent. The child
can use the parent's definition or redirect a standard stream to a new location, but
when control returns to the parent, the standard stream reverts back to the
definition of the parent. In the global model, the C standard streams, stdin, stdout,
and stderr, can be redirected to a different location while running in a child main()
function and have that redirection stay in effect when control returns to the parent.
You can use the _EDC_GLOBAL_STREAMS environment variable to set standard
stream behavior to the global model. For more information, see
_EDC_GLOBAL_STREAMS on page 492.

Table 14 on page 77 highlights the standard stream behavior differences between

the default inheritance model and the global model.

76 z/OS V1R13.0 XL C/C++ Programming Guide

Table 14. Standard stream behavior differences
Behavior Default Inheritance Model Global Model
POSIX(OFF) Standard streams are opened automatically on (Same)
first reference.
POSIX(ON) Standard streams are opened during initialization Not supported.
of the process, before the application receives
control.
default open modes As described in Default open modes on page (Same)
62.
default locations As described in this chapter. (Same)
command line Changes the location for the main being called Changes the location for the entire C
redirection and subsequent child programs. environment.
direct assignment Affects the current main and subsequent child Affects the current main only. This
programs. definition is not passed on to a subsequent
child program. The child gets the current
global definition, if there is one defined.
freopen() Changes location for the main from which it is Changes location for the entire C
called and affects any subsequent child environment.
programs.
MSGFILE() run-time Redirects stderr for the main being invoked and (Same)
option affects any subsequent child programs. When
control returns to a parent program, stderr
reverts back to the definition of the parent. If
stderr is also redirected on the command line,
that redirection takes precedence.
fclose() Closes the standard stream in current main only. Closes the standard stream for the entire
C environment. The standard stream
cannot be global anymore. Only direct
assignment can be used to use the
standard stream, and that would only be
for the main in which it is assigned.
file position and visible As currently described in this chapter. File position and visible data across mains
data are as if there were only one main. No
special processing occurs during the ANSI
system() call. The standard streams are
left untouched. When either entering or
returning from a child program, reading or
writing to the standard streams begin
where previously left off,
C++ I/O Stream cin defaults to stdin (Same)
cout defaults to stdout
cerr defaults to stderr (unbuffered)
clog defaults to stderr (buffered)

Notes:
1. The following environments do not allow global standard stream behavior as an
option:
v POSIX(ON)
v CICS
v SPC
v AMODE 64
2. You must identify the behavior of the standard streams to the C run-time library
before initialization of the first C main in the environment. The default behavior

Chapter 9. Using C and C++ standard streams and redirection 77

 uses the inheritance model. Once you set the standard stream behavior, it
cannot be changed. Attempts to change the behavior after the first C main has
been initialized are ignored.
3. The value of the environment variable, when queried, does not necessarily
reflect the standard stream behavior being used. This is because the value of
the environment variable can be changed after the standard stream behavior
has been set.
4. The behaviors described in Table 14 on page 77 only apply to the standard
streams that use the global behavior.

Command line redirection

In the C standard stream global model, command line redirection of the standard
streams is supported, but has much different behavior than the C standard stream
inheritance model.

The most important difference is that when redirection is done at system() call time,
the redirection takes effect for the entire C environment. When the child program
terminates, the standard stream definitions do not revert back to what they were
before the system() call.

Redirection of any of the standard streams, except when stderr is redirected to

stdout or vice versa, causes the standard stream to be flushed. This is because an
freopen() is done under the covers, which first closes the stream before reopening
it. Since the standard stream is global, the close causes the flush.

Redirecting stderr to stdout, or stdout to stderr, does not flush the redirected
stream. Any data in the buffer remains there until the stream is redirected again, to
something other than stdout or stderr. Only then is the buffer flushed.

Consider the following example programs, PARENT.C and CHILD.C, shown in

Figure 12 on page 79.

78 z/OS V1R13.0 XL C/C++ Programming Guide

 PARENT.C

#include <stdio.h>
#include <stdlib.h>
main() {
int rc;
printf("line 1\n");
printf("line 2");
fprintf(stderr,"line 3\n");
fprintf(stderr,"line 4");
rc=system("PGM=CHILD,PARM=/ >stdout.file 2>&1;")
printf("line 5\n");
fprintf(stderr,"line 6\n");
}

CHILD.C

#include <stdio.h>
main() {
printf("line 7\n");
fprintf(stderr,"line 8\n");
stderr = freopen("stderr.file","w",stderr);
printf("line 9\n");
fprintf(stderr,"line 10\n");
}

Figure 12. Example of command line redirection

When run from TSO terminal using the command parent

ENVAR(_EDC_GLOBAL_STREAMS=7)/, the output will be as follows:
(terminal) stdout.file stderr.file
line 1 line 7 line 10
line 3 line 8 line 6
line 2 line 9
line 4 line 5

Attention: If the stdout or stderr stream has data in its buffer and it is redirected
to stderr or stdout, then the data is lost if stdout or stderr is not redirected again.

Note: If either stdout or stderr is using global behavior, but not both, then any
redirection of stdout or stderr to stderr or stdout is ignored.

Direct assignment
You can directly assign the C standard streams in any main program. This
assignment does not have any effect on the global standard stream. No flush is
done and the new definition is not passed on to a child program nor back to a
parent program. Once you directly assign a standard stream, there is no way to
re-associate it with the global standard stream.

freopen()
When you use freopen() to redirect a standard stream, the stream is closed,
causing a flush, and then redirected. The new definition affects all C mains currently
using the global stream.

MSGFILE() run-time option

The MSGFILE() run-time option redirects the stderr stream similar to command line
redirection. However, this redirection is controlled by the Common Execution Library

Chapter 9. Using C and C++ standard streams and redirection 79

 and does not apply to all C mains in the environment. When control returns to a
parent program, stderr reverts back to the definition of the parent.

fclose()
When a global standard stream is closed, only direct assignment can be used to
begin using the standard stream again. That use would only be for the main
performing the direct assignment. There is no way to get back global behavior for
the standard stream that was closed.

File position and visible data

The file position and amount of visible data in the called and calling program is as if
there is only one program. There is no data hidden from a called program. A child
program continues where the parent program left off. This is true for all types of I/O:
binary, text, and record.

C++ I/O stream library

Since cin, cout, cerr and clog are initially based on stdin, stdout and stderr, they
continue to be in the global model. For example, if stdout is redirected using
freopen() in a child program, then both stdout and cout retain that redirection
when control returns to the parent.

80 z/OS V1R13.0 XL C/C++ Programming Guide

Chapter 10. Performing OS I/O operations
This topic describes using OS I/O, which includes support for the following:
v Regular sequential DASD (including striped data sets)
v Partitioned DASD (PDS and PDSE)
v Tapes
v SYSOUT
v Printers
v In-stream JCL
Notes:
1. z/OS XL C/C++ does not support BDAM, ISAM, or non-VSAM keyed data sets.
Attempting to open a non-VSAM keyed data set for read or append fails;
attempting to open an existing non-VSAM keyed data set for write results in
unpredictable results.
2. z/OS XL C/C++ provides complete read and write support for large format
sequential data sets when seek is requested (not specifying the noseek
keyword) and when noseek is requested and honored.
3. z/OS XL C/C++ provides support for extended format sequential data sets in the
extended addressing space on extended address volumes (EAVs).
4. z/OS XL C/C++ supports opening DDNAMEs that have been dynamically
allocated with the XTIOT, UCB nocapture, and DSAB-above-the-line options
specified in the SVC99 parameters (S99TIOEX, S99ACUCB, S99DSABA flags).

OS I/O supports text, binary, and record I/O, in three record formats: fixed (F),
variable (V), and undefined (U). For information about using wide-character I/O with
z/OS XL C/C++, see Chapter 8, z/OS XL C Support for the double-byte character
set, on page 51.

This topic describes C I/O stream functions as they can be used within C++
programs. If you want to use the C++ I/O stream classes instead, see Chapter 4,
Using the Standard C++ Library I/O Stream Classes, on page 21 for general
information. For more detailed information, see Standard C++ Library Reference,
which discusses the Standard C++ I/O stream classes

Opening files
To open an OS file, you can use the Standard C functions fopen() or freopen().
These are described in general terms in z/OS XL C/C++ Run-Time Library
Reference. Details about them specific to all z/OS XL C/C++ I/O are discussed in
the "Opening Files" section. This section describes considerations for using fopen()
and freopen() with OS files.

Using fopen() or freopen()

When you open a file using fopen() or freopen(), you must specify the filename (a
data set name) or a ddname. Restriction: It is not possible to open a file for writing
if there is already an open file with the same data set name on a different volume

Copyright IBM Corp. 1996, 2012 81

 Using a data set name
Files are opened with a call to fopen() or freopen() in the format
fopen("filename", "mode"). The following diagram shows the syntax for the
filename argument on your fopen() or freopen() call:

  qualifier 
// ' ( member ) '
+ number

0
& qualifier
&&

Note: The single quotation marks in the filename syntax diagram must be matched;
if you use one, you must use the other.

A sample construct is shown below:

qualifier1.qualifier2(member)

// Specifying these slashes indicates that the filename refers to a non-POSIX

file or data set.
qualifier
Each qualifier is a 1- to 8-character name. These characters may be
alphanumeric, national ($, #, @), or the hyphen. The first character should
be either alphabetic or national. Do not use hyphens in names for
RACF-protected data sets.
You can join qualifiers with periods. The maximum length of a data set
name is as follows:
v Generally, 44 characters, including periods.
v For a generation data group, 35 characters, including periods.
These numbers do not include a member name or GDG number and
accompanying parentheses.
Specifying one or two ampersands before a single qualifier opens a
temporary data set. Multiple qualifiers are not valid after ampersands,
because the system generates additional qualifiers. Opening two temporary
data sets with the same name creates two distinct files. If you open a
second temporary data set using the same name as the first, you get a
distinct data set. For example, the following statements open two temporary
data sets:

fp = fopen("//&&myfile","wb+");
fp2 = fopen("//&&myfile","wb+");

82 z/OS V1R13.0 XL C/C++ Programming Guide

 You cannot fully qualify a temporary data set name. The file is created at
open time and is empty. When you close a temporary data set, the system
removes it.
(member)
If you specify a member, the data set you are opening must be a PDS or a
PDSE. For more information about PDSs and PDSEs, see Regular and
extended partitioned data sets on page 88. For members, the member
name (including trailing blanks) can be up to 8 characters long. A member
name cannot begin with leading blanks. The characters in a member name
may be alphanumeric, national ($, #, @), the hyphen, or the character
X'C0'. The first character should be either alphabetic or national.
+number
number
0 You specify a Generation Data Group (GDG) by using a plus (+) or minus
() to precede the version number, or by using a 0. For more information
about GDGs, see Generation data group I/O on page 85.

The Resource Access Control Facility (RACF) expects the data set name to have
a high-level qualifier that is defined to RACF. RACF uses the entire data set name
when it protects a tape data set.

When you enclose a name in single quotation marks, the name is fully qualified.
The file opened is the one specified by the name inside the quotation marks. If the
name is not fully qualified, z/OS XL C/C++ does one of the following:
v If your system does not use RACF, z/OS XL C/C++ does not add a high-level
qualifier to the name you specified.
v If you are running under TSO (batch or interactive), z/OS XL C/C++ appends the
TSO user prefix to the front of the name. For example, the statement
fopen("a.b","w"); opens a data set tsoid.A.B, where tsoid is the user prefix. If
the name is fully qualified, z/OS XL C/C++ does not append a user prefix. You
can set the user prefix by using the TSO PROFILE command with the PREFIX
parameter.
v If you are running under z/OS batch or IMS (batch or online), z/OS XL C/C++
appends the RACF user ID to the front of the name.

If you want your code to be portable between the VM/CMS and z/OS systems and
between memory files and disk files, use a name of the format name1.name2, where
name1 and name2 are up to 8 characters and are delimited by a period, or use a
ddname. You can also add a member name.

For example, the following piece of code can run under Language Environment for
VM and z/OS Language Environment:
FILE *stream;
stream = fopen("parts.instock", "r");

Using a DDname
The DD statement enables you to write C or C++ source programs that are
independent of the files and input/output devices they use. You can modify the
parameters of a file or process different files without recompiling your program.

Use ddnames if you want to use non-DASD devices.

Chapter 10. Performing OS I/O operations 83

 If you specify DISP=MOD on a DD statement and w or wb mode on the fopen() call,
z/OS XL C/C++ treats the file as if you had opened it in append mode instead of
write mode.

To open a file by ddname under z/OS batch, you must define the ddname first. You
can do this in any of the following ways:
v In batch (z/OS, TSO, or IMS), you can write a JCL DD statement. For the
declaration shown above for the C or C++ file PARTS.INSTOCK, you write a JCL
DD statement similar to the following:
//STOCK DD DSN=USERID.PARTS.INSTOCK,DISP=SHR
When defining DD, do not use DD ... FREE=CLOSE for unallocating DD
statements. The C library may close files to perform some file operations such as
freopen(), and the DD statement will be unallocated.
If you use SPACE=RLSE on a DD statement, z/OS XL C/C++ releases space only if
all of the following are true:
The file is open in w, wb, a, or ab mode
It is not simultaneously open for read
No positioning functions (fseek(), ftell(), rewind(), fgetpos(), fsetpos())
have been performed.
For more information on writing DD statements, refer to the job control language
(JCL) manuals listed in z/OS Information Roadmap.
v Under TSO (interactive and batch), you can issue an ALLOCATE command. The
DD definition shown above for the C file STOCK has an equivalent TSO ALLOCATE
command, as follows:
ALLOCATE FILE(STOCK) DATASET(PARTS.INSTOCK) SHR
See z/OS Information Roadmap for manuals containing information on TSO
ALLOCATE.
v In the z/OS environment, you can use the svc99() or dynalloc() library functions
to define ddnames. For information about these functions, refer to z/OS XL
C/C++ Run-Time Library Reference.

DCB parameter: The DCB (data control block) parameter of the DD statement
allows you to describe the characteristics of the data in a file and the way it will be
processed at run time. The other parameters of the DD statement deal chiefly with
the identity, location, and disposition of the file. The DCB parameter specifies
information required for the processing of the records themselves. The
subparameters of the DCB parameter are described in z/OS MVS JCL User's Guide.

The DCB parameter contains subparameters that describe:

v The organization of the file and how it will be accessed. Parameters supplied on
fopen() override those specified in DCB.
v Device-dependent information such as the recording technique for magnetic tape
or the line spacing for a printer (for example: CODE, DEN, FUNC, MODE, OPTCD=J,
PRTSP, STACK, SPACE, UNIT and TRTCH subparameters).
v The data set format (for example: BLKSIZE, LRECL, and RECFM
subparameters).

You cannot use the DCB parameter to override information already established for
the file in your C or C++ program (by the file attributes declared and the other
attributes that are implied by them). DCB subparameters that attempt to change
information already supplied by fopen() or freopen() are ignored. An example of
the DCB parameter is:
DCB=(RECFM=FB,BLKSIZE=400,LRECL=40)

84 z/OS V1R13.0 XL C/C++ Programming Guide

 It specifies that fixed-length records, 40 bytes in length, are to be grouped in a
block 400 bytes long. You can copy attributes from another data set by either
setting the DCB parameter to DCB=(dsname) or using the SVC 99 services provided
by the svc99() and dynalloc() library functions.

Generation data group I/O

A Generation Data Group (GDG) is a group of related cataloged data sets. Each
data set within a generation data group is called a generation data set. Generation
data sets have sequentially ordered absolute and relative names that represent
their age. The absolute generation name is the representation used by the catalog
management routines in the catalog. The relative name is a signed integer used to
refer to the latest (0), the next to the latest (-1), and so forth, generation. The
relative number can also be used to catalog a new generation (+1). For more
information on GDGs, see z/OS DFSMS Using Data Sets.

If you want to open a generation data set by data set name with fopen() or
freopen(), you will require a model. This model specifies parameters for the group,
including the maximum number of generations (the generation index). You can
define such a model by using the Access Method Services DEFINE command. For
more information on the DEFINE command, see z/OS DFSMS Access Method
Services for Catalogs. Note also that fopen() does not support a DCB= parameter. If
you want to change the parameters, alter the JCL that describes the model and
open it in w mode.

z/OS uses an absolute generation and version number to catalog each generation.
The generation and version numbers are in the form GxxxxVyy, where xxxx is an
unsigned 4-digit decimal generation number (0001 through 9999) and yy is an
unsigned 2-digit decimal version number (00 through 99). For example:
v A.B.C.G0001V00 is generation data set 1, version 0, in generation data group
A.B.C.
v A.B.C.G0009V01 is generation data set 9, version 1, in generation data group
A.B.C.

The number of generations kept depends on the size of the generation index.

When you open a GDG by relative number, z/OS XL C/C++ returns the relative
generation in the __dsname field of the structure returned by the fldata() function.
You cannot use the rename() library function to rename GDGs by relative
generation number; rename GDG data sets by using their absolute names.

The example shown in Figure 13 on page 86 is valid only for C. The sample
program (CCNGOS1) defines a GDG. The fopen() fails because it tries to change
the RECFM of the data set.

Chapter 10. Performing OS I/O operations 85

 //*---------------------------------------------------------------------
//* This example demonstrates GDG I/O
//*---------------------------------------------------------------------
//* Create GDG model MYGDG.MODEL and GDG name MYGDG
//*---------------------------------------------------------------------
//MODEL EXEC PGM=IDCAMS
//DD1 DD DSN=userid.MYGDG.MODEL,DISP=(NEW,CATLG),
// UNIT=SYSDA,SPACE=(TRK,(0)),
// DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB)
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE GDG -
(NAME(userid.MYGDG) -
EMPTY -
SCRATCH -
LIMIT(255))
/*
//*---------------------------------------------------------------------
//* Create GDG data set MYGDG(+1)
//*---------------------------------------------------------------------
//DATASET EXEC PGM=IEFBR14
//DD1 DD DSN=userid.MYGDG(+1),DISP=(NEW,CATLG),
// SPACE=(CYL,(1,1)),UNIT=SYSDA,
// DCB=userid.MYGDG.MODEL
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
//*---------------------------------------------------------------------
//* Compile, link, and run an inlined C program.
//* This program attempts to open the GDG data set MYGDG(+1) but
//* should fail as it is opening the data set with a RECFM that is
//* different from that of the GDG model (F versus FB).
//*---------------------------------------------------------------------
//C EXEC EDCCLG,
// CPARM=NOSEQ,NOMARGINS
//COMPILE.SYSIN DD DATA,DLM=/>
#include <stdio.h>
#include <errno.h>
int main(void)
{
FILE *fp;

fp = fopen("MYGDG(+1)", "a,recfm=F");

if (fp == NULL)
{
printf("Error...Unable to open file\n");
printf("errno ... %d\n",errno);
perror("perror ... ");
}

printf("Finished\n");
}
/>

Figure 13. Generation data group example for C

The example shown in Figure 14 on page 87 (CCNGOS2) is valid only C++.

86 z/OS V1R13.0 XL C/C++ Programming Guide

//*---------------------------------------------------------------------
//* This example demonstrates GDG I/O
//*---------------------------------------------------------------------
//* Create GDG model MYGDG.MODEL and GDG name MYGDG
//*---------------------------------------------------------------------
//MODEL EXEC PGM=IDCAMS
//DD1 DD DSN=userid.MYGDG.MODEL,DISP=(NEW,CATLG),
// UNIT=SYSDA,SPACE=(TRK,(0)),
// DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB)
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE GDG -
(NAME(userid.MYGDG) -
EMPTY -
SCRATCH -
LIMIT(255))
/*
//*---------------------------------------------------------------------
//* Create GDG data set MYGDG(+1)
//*---------------------------------------------------------------------
//DATASET EXEC PGM=IEFBR14
//DD1 DD DSN=userid.MYGDG(+1),DISP=(NEW,CATLG),
// SPACE=(CYL,(1,1)),UNIT=SYSDA,
// DCB=userid.MYGDG.MODEL
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
//*---------------------------------------------------------------------
//* Compile, bind, and run an inlined C++ program.
//* This program attempts to open the GDG data set MYGDG(+1) but
//* should fail as it is opening the data set with a RECFM that is
//* different from that of the GDG model (F versus FB).
//*---------------------------------------------------------------------
//*
//DOCLG1 EXEC CBCCBG,
// CPARM=NOSEQ,NOMARGINS
//COMPILE.SYSIN DD DATA,DLM=<>
#include <stdio.h>
#include <errno.h>
int main(void)
{
FILE *fp;

fp = fopen("MYGDG(+1)", "a,recfm=F");

if (fp == NULL)
{
printf("Error...Unable to open file\n");
printf("errno ... %d\n",errno);
perror("perror ... ");
}

printf("Finished\n");
}

Figure 14. Generation data group example for C++

A relative number used in the JCL refers to the same generation throughout a job.
The (+1) used in the example above exists for the life of the entire job and not just
the step, so that fopen()'s reference to (+1) did not create another new data set
but accessed the same data set as in previous steps.

Note: You cannot use fopen() to create another generation data set because
fopen() does not fully support the DCB parameter.

Chapter 10. Performing OS I/O operations 87

Regular and extended partitioned data sets
Partitioned data sets (PDS) and partitioned data sets extended (PDSE) are DASD
data sets divided into sections known as members. Each member can be accessed
individually by its unique 1- to 8-character name. As Table 15 shows, PDSEs are
similar to PDSs, but contain a number of enhancements.
Table 15. PDSE and PDS differences
PDSE Characteristics PDS Characteristics
Data set has a 123-extent limit Data set has a 16-extent limit
Directory is open-ended and indexed by Fixed-size directory is searched sequentially
member name; faster to search directory
PDSEs are device-independent: records are Block sizes are device-dependent
reblockable
Uses dynamic space allocation and Must use IEBCOPY COMPRESS to reclaim
reclamation space
Supports creation of more than one member Supports creation of only one member at a
at a time* time
Note: *z/OS XL C/C++ allows you to open two separate members of a PDSE for writing at
the same time. However, you cannot open a single member for writing more than once.

You specify a member by enclosing its name in parentheses and placing it after the
data set name. For example, the following JCL refers to member A of the data set
MY.DATA:
//MYDD DD DSN=userid.MY.DATA(A),DISP=SHR

You can specify members on calls to fopen() and freopen(). You can specify
members when you are opening a data set by its data set name or by a ddname.
When you use a ddname and a member name, the definition of the ddname must
not also specify a member. For example, using the DD statement above, the
following will fail:
fp = fopen("dd:MYDD(B)","r");

You cannot open a PDS or PDSE member using the modes a, ab, a+, a+b, w+, w+b,
or wb+. If you want to perform the equivalent of the w+ or wb+ mode, you must first
open the file as w or wb, write to it, and then close it. Then you can perform updates
by reopening the file in r+ or rb+ mode. You can use the C library functions ftell()
or fgetpos() to obtain file positions for later updates to the member. Normally,
opening a file in r+ or rb+ mode enables you to extend a file by writing to the end;
however, with these modes you cannot extend a member. To do so, you must copy
the contents of the old member plus any extensions to a new member. You can
remove the old member by using the remove() function and then rename the new
member to the old name by using rename().

All members have identical attributes for RECFM, LRECL, and BLKSIZE. For PDSs,
you cannot add a member with different attributes or specify a RECFM of FBS, FBSA,
or FBSM. z/OS XL C/C++ verifies any attributes you specify.

For PDSEs, z/OS XL C/C++ checks to make sure that any attributes you specify
are compatible with those of the existing data set. Compatible attributes are those
that specify the same record format (F, V, or U) and the same LRECL. Compatibility
of attributes enables you to choose whether to specify blocked or unblocked format,
because PDSEs reblock all the records. For example, you can create a PDSE as FB
LRECL=40 BLKSIZE=80, and later open it for read as FB LRECL=40 BLKSIZE=1600 or F

88 z/OS V1R13.0 XL C/C++ Programming Guide

 LRECL=40 BLKSIZE=40. The LRECL cannot change, and the BLKSIZE must be
compatible with the RECFM and LRECL. Also, you cannot change the basic format
of the PDSE from F to V or vice versa. If the PDS or PDSE already exists, you do
not need to specify any attributes, because z/OS XL C/C++ uses the previously
existing ones as its defaults.

At the start of each partitioned data set is its directory, a series of records that
contain the member names and starting locations for each member within the data
set. You can access the directory by specifying the PDS or PDSE name without
specifying a member. You can open the directory only for read; update and write
modes are not allowed. The only RECFM that you can specify for reading the
directory is RECFM=U. However, you do not need to specify the RECFM, because
z/OS XL C/C++ uses U as the default.

z/OS DFSMS Using Data Sets contains more detailed explanations about how to
use PDSs and PDSEs.

Partitioned and sequential concatenated data sets

There are two forms of concatenated data sets: partitioned and sequential. You can
open concatenated data sets only by ddname, and only for read or update.
Specifying any of the write, or append modes fails. As with PDS members, you
cannot extend a concatenated data set.

Partitioned concatenation consists of specifying multiple PDSs or PDSEs under

one ddname. When you access the concatenation, it acts as one large PDS or
PDSE, from which you can access any member. If two or more partitioned data sets
in the concatenation contain a member with the same name, using the
concatenation ddname to specify that member refers to the first member with that
name found in the entire concatenation. You cannot use the ddname to access
subsequent members. For example, if you have a PDS named PDS1, with members
A, B, and C, and a second PDS named PDS2, with members C, D, and E, and you
concatenate the two data sets as follows:
//MYDD DD userid.PDS1,DISP=SHR
// DD userid.PDS2,DISP=SHR

and perform the following:

fp = fopen("DD:MYDD(C)","r");
fp2 = fopen("DD:MYDD(D)","r");

the first call to fopen() finds member C from PDS1, even though there is also a
member C in PDS2. The second call finds member D from PDS2, because PDS2 is the
first PDS in the concatenation that contains this member. The member C in PDS2 is
inaccessible.

When you are concatenating partitioned data sets, be aware of the DCB attributes
for them. The concatenation is treated as a single data set with the following
attributes:
v RECFM= the RECFM of the first data set in the concatenation
v LRECL= the LRECL of the first data set in the concatenation
v BLKSIZE= the largest BLKSIZE of any data set in the concatenation

Table 16 on page 90 describes the rules for compatible concatenations.

Chapter 10. Performing OS I/O operations 89

 Table 16. Rules for possible concatenations
RECFM of first RECFM of subsequent data sets LRECL of subsequent data sets
data set
RECFM=F RECFM=F Same as that of first one
RECFM=FB RECFM=F or RECFM=FB Same as that of first one
RECFM=V RECFM=V Less than or equal to that of first
one
RECFM=VS RECFM=V or RECFM=VS Less than or equal to that of first
one
RECFM=VB RECFM=V or RECFM=VB Less than or equal to that of first
one
RECFM=VBS RECFM=V, RECFM=VB, Less than or equal to that of first
RECFM=VS, or RECFM=VBS one
RECFM=U RECFM=U or RECFM=F (see note)
Note: You can use a data set in V-format, but when you read it, you will see all of the BDWs
and RDWs or SDWs with the data.

If the first data set is in ASA format, all subsequent data sets must be ASA as well.
The preceding rules apply to ASA files if you add an A to the RECFMs specified.

If you do not follow these rules, undefined behavior occurs. For example, trying to
read a fixed-format member as RECFM=V could cause an exception or abend.

Repositioning is supported as it is for regular PDSs and PDSEs. If you try to read
the directory, you will be able to read only the first one.

Sequential concatenation consists of treating multiple sequential data sets or

partitioned data set members as one long sequential data set.

//MYDD DD userid.PDS1(A),DISP=SHR
// DD userid.PDS2(E),DISP=SHR
// DD userid.DATA,DISP=SHR

creates a concatenation that contains two members and a regular sequential data
set. You can read or update all of these in order. In partitioned concatenations, you
can read only one member at a time.

z/OS XL C/C++ does not support concatenating data sets that do not have
compatible DCB attributes. The rules for compatibility are the same as those for
partitioned concatenations.

If all the data sets in the concatenation support repositioning, you can reposition
within a concatenation by using the functions fseek(), ftell(), fgetpos(),
fsetpos(), and rewind(). If the first one does not, all of the repositioning functions
except rewind() fail for the entire concatenation. If the first data set supports
repositioning but a subsequent one does not, you must specify the noseek
parameter on the fopen() or freopen() call. If you do not, fopen() or freopen()
opens the file successfully; however, an error occurs when the read position gets to
the data set that does not support repositioning.

Note: Concatenated and multivolume data sets only tolerate single buffering mode.

90 z/OS V1R13.0 XL C/C++ Programming Guide

In-stream data sets
An in-stream data set is a data set contained within a set of JCL statements.
In-stream data sets (also called inline data sets) begin with a DD * or DD DATA
statement. These DD statements can have any valid ddname, including SYSIN. If
you omit a DD statement before the input data, the system provides a DD *
statement with the ddname of SYSIN. This example shows you how to indicate an
in-stream data set:

//MYDD DD *
record 1
record 2
record 3
/*

The // at the beginning of the data set starts in column 1. The statement
fopen("DD:MYDD","rb"); opens a data set with lrecl=80, blksize=80, and
recfm=FB. In this example, the delimiter indicating the end of the data set is /*. In
some cases, your data may contain this string. For example, if you are using C
source code that contains comments, z/OS XL C/C++ treats the beginning of the
first comment as the end of the in-stream data set. To avoid this occurrence, you
can change the delimiter by specifying DLM=nn, where nn is a two-character
delimiter, on the DD statement that identifies the file. For example:

//MYDD DD *,DLM=
#include <stdio.h>
/* Hello, world program */
int main() {printf("Hello, world\n"); }
@@

For more information about in-stream data sets, see z/OS MVS JCL User's Guide.

To open an in-stream data set, call the fopen() or freopen() library function and
specify the ddname of the data set. You can open an in-stream data set only for
reading. Specifying any of the update, write, or append modes fails. Once you have
opened an in-stream data set, you cannot acquire or change the file position except
by rewinding. This means that calls to the fseek(), ftell(), fgetpos(), and
fsetpos() for in-stream data sets fail. Calling rewind() causes z/OS XL C/C++ to
reopen the file, leaving the file position at the beginning.

You can concatenate regular sequential data sets and in-stream data sets. If you do
so, note the following:
v If the first data set is in-stream, you cannot acquire or change the file position for
the entire concatenation.
v If the first data set is not in-stream and supports repositioning, you must specify
the noseek parameter on the fopen() or freopen() call that opens the
concatenation. If you do not, fopen() or freopen() opens the file successfully;
however, an error occurs when the read position gets to the in-stream.
v The in-stream data set is treated as FB 80 and the concatenation rules for
sequential concatenation apply.

Chapter 10. Performing OS I/O operations 91

SYSOUT data sets
You can specify a SYSOUT data set by using the SYSOUT parameter on a DD
statement. z/OS XL C/C++ supports opening SYSOUT data sets in two ways:
1. Specifying a ddname that has the SYSOUT parameter. For information about
defining ddnames, see Using a DDname on page 83.
2. Specifying a data set name of * on a call to fopen() or freopen() while you are
running under z/OS batch or IMS online or batch.

On a DD statement, you specify SYSOUT=x, where x is the output class. If the class
matches the JOB statement MSGCLASS, the output appears with the job log. You can
specify a SYSOUT data set and get the job MSGCLASS by specifying SYSOUT=*. If you
want to create a job stream within your program, you can specify INTRDR on the DD
statement. This sends your SYSOUT data set to the internal reader to be read as
an input job stream. For example,
//MYDD DD SYSOUT=(A,INTRDR)

For more details about the SYSOUT parameter, refer to z/OS MVS JCL User's
Guide.

You can specify DCB attributes for a SYSOUT data set on a DD statement or a call
to fopen() or freopen(). If you do not, z/OS XL C/C++ uses the following defaults:
Binary or Record I/O RECFM=VB LRECL=137 BLKSIZE=882
Text I/O RECFM=VBA LRECL=137 BLKSIZE=882

Tapes
z/OS XL C/C++ supports standard label (SL) tapes. If you are creating tape files,
you can only open them by ddname. z/OS XL C/C++ provides support for opening
tapes in read, write, or append mode, but not update. When you open a tape for
read or append, any data set control block (DCB) characteristics you specify must
match those of the existing data set exactly. The repositioning functions are
available only when you have opened a tape for read. For tapes opened for write or
append, calling rewind() has no effect; calls to any of the other repositioning
functions fail. To open a tape file for write, you must open it by ddname.

Opening FBS-format tape files with append-only mode is not supported.

When you open a tape file for output, the data set name you specify in the JCL
must match the data set name specified in the tape label, even if the existing tape
file is empty. If this is not the case, you must either change the JCL to specify the
correct data set name or write to another tape file, or reinitialize the tape to remove
the tape label and the data. You can use IEBGENER with the following JCL to create
an empty tape file before passing it to the subsequent steps:

//ALLOC EXEC PGM=IEBGENER

//SYSUT1 DD *
/*
//SYSUT2 DD DSN=name-of-OUTPUT-tape-file,UNIT=xxxx,LABEL=(x,SL),
// DISP=(NEW,PASS),(DCB=LRECL=xx,BLKSIZE=xx,RECFM=xx),
// VOL=SER=xxx
//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*

Note: For tapes, the value for UNIT= can be TAPE or CART.

92 z/OS V1R13.0 XL C/C++ Programming Guide

 Because the C library does not create tape files, you can append only to a tape file
that already exists. Attempting to append to a file that does not already exist on a
tape will cause an error. You can create an empty data set on a tape by using the
utility IEBGENER.

Multivolume data sets

z/OS XL C/C++ supports data sets that span more than one volume of DASD or
tape. You can open multivolume DASD data sets for read (r,rb), write (w,wb),
update (r+,rb+,w+,wb+), or append (a,a+,ab,ab+) by dsname and ddname.
Multivolume data sets can be extended in read/update mode (r+,rb+).

The repositioning functions are available when you have opened a multivolume data
set for r,r+,rb,rb+,w+,wb+,a+,ab+. Repositioning multivolume data sets opened for
w,wb,a,ab is not allowed because it would be meaningless. For multivolume data
sets opened for write, calling rewind() has no effect; calls to any of the other
repositioning functions fail.

Here is an example of a multivolume data set declaration:

//MYDD DD DSNAME=TEST.TWO,DISP=(NEW,CATLG),
// VOLUME=(,,,3,SER=(333001,333002,333003)),
// SPACE=(TRK,(9,10)),UNIT=(3390,P)

This creates a data set that may span up to three volumes. For more information
about the VOLUME parameter on DD statements, refer to z/OS MVS JCL User's
Guide.
Notes:
1. Simultaneous readers (files that can support sharing by a writer and one or
more readers) are not supported for multivolume data sets.
2. Concatenated and multivolume data sets only tolerate single buffering mode.

Striped data sets

z/OS XL C/C++ supports extended format sequential data sets. Extended format
data sets must be SMS-managed. Optionally, extended format data sets can be
striped. Striping spreads a data set over a specified number of volumes such that
I/O parallelism can be exploited. Unlike a multivolume data set in which physical
record n follows record n-1, a striped data set has physical records n and n-1 on
separate volumes. This enables asynchronous I/O to perform parallel operations,
making requests for multiple reads and writes faster.

Striped data sets also facilitate repositioning once the relative block number is
known. z/OS XL C/C++ exploits this capability when it uses fseek() to reposition.
This can result in substantial savings for applications that use ftell() and fseek()
with data sets that have RECFMs of V, U, and FB (not FBS). data sets. When a data
set is striped, an fseek() can seek directly to the specified block just as an
fsetpos() or rewind() can. For a normal data set with the aforementioned
RECFMs, z/OS XL C/C++ has to read forward or rewind the data set to get to the
desired position. Depending on how large the data set is, this can be quite
inefficient compared to a direct reposition. Note that for such data sets, striping
pads blocks to their maximum size. Therefore, you may be wasting space if you
have short records.

Chapter 10. Performing OS I/O operations 93

Large format sequential data sets
A large format sequential data set is a modification to traditional sequential data
sets that allows for more than 65535 tracks of data per volume. Large format
sequential data sets can be single or multivolume, and can reside on SMS
managed or non-SMS managed direct access storage devices.

A large format sequential data set is specified using the DSNTYPE=LARGE keyword on
a JCL DD statement or using the dynamic allocation equivalent. z/OS XL C/C++
does not support the allocation of a large format sequential data set using fopen()
or freopen().

z/OS XL C/C++ provides complete read and write support for:

v Large format sequential data sets when seek is requested (not specifying the
noseek keyword).
v Large format sequential data sets when noseek is requested and honored. See
Access method selection on page 95 for more information on when noseek is
requested but not honored.

Note: Restrictions associated with traditional sequential single and multivolume

data sets, or concatenations of such data sets, continue to apply when the data set
is large format.

Other devices
z/OS XL C/C++ supports several other devices for input and output. You can open
these devices only by ddname. Table 17 lists a number of these devices and
describes which record formats are valid for them. None of the devices listed can
be opened for update except the DUMMY data set.
Table 17. Other devices supported for input and output
Device Valid open modes Repositioning? fldata()__device
Printer w, wb, a, ab No __PRINTER
Card reader r, rb rewind() only __OTHER
Card punch w, wb, a, ab No __OTHER
Optical reader r, rb rewind() only __OTHER
DUMMY data set r, rb, r+, rb+, r+b, w, rewind() only __DUMMY
wb, w+, wb+ w+b, a,
ab, a+, ab+, a+b
SUBSYS= r, rb No __OTHER
Note: For all devices above that support open modes a or ab, the modes are treated as if
you had specified w or wb.

z/OS XL C/C++ queries each device to find out its maximum BLKSIZE.

The DUMMY data set is not truly a device, although z/OS XL C/C++ treats it as one.
To use the DUMMY data set, specify DD DUMMY in your JCL. On input, the DUMMY data
set always returns EOF; on output, it is always successful. This is the way to specify
a DUMMY data set:
//MYDD DD DUMMY

For more information on DUMMY data sets, see z/OS MVS JCL User's Guide.

94 z/OS V1R13.0 XL C/C++ Programming Guide

 z/OS XL C/C++ provides minimal support for subsystem (SUBSYS=) managed data
sets. Support is limited to opening for read using the dd:ddname(member) syntax
with the fopen() filename. The ddname in the JCL stream must specify the SUBSYS=
parameter. In this case, fopen() will open the DCB as DSORG=PS, required for
subsystem managed data sets, but will perform the BLDL/FIND sequence to allow
the subsystem to manage processing of the desired member.

Access method selection

The fopen() and freopen() keyword noseek requests QSAM (queued sequential
access method) be used to process the data set. This request also indicates that
the repositioning functions will not be used by the application. This access method
generally provides the best performance. Omitting the keyword noseek selects
BSAM (basic sequential access method) with NOTE and POINT macros requested,
allowing repositioning functions to be used (where applicable) on the stream.

The following scenarios exist where QSAM (noseek) is requested, but the z/OS XL
C/C++ Run-Time Library switches to BSAM with NOTE and POINT macros requested
(seek):
v The data set is opened for update (r+, rb+, w+, wb+, a+, ab+)
v The data set is already opened for write (or update) in the same C process
v The data set is RECFM=FBS opened for append (a, ab, a+, ab+)
v The data set is LRECL=X
v The data set is the directory of a partitioned data set (PDS or PDSE)
v The data set is a member of a partitioned data set where the member was not
specified at allocation, but rather specified at fopen() or freopen()

Note: Repositioning is not allowed when noseek is requested, even if there was a
switch to seek.

fopen() and freopen() parameters

Table 18 lists the parameters that are available on the fopen() and freopen()
functions, tells you which ones are allowed and applicable for OS I/O, and lists the
option values that are valid for the applicable ones. Detailed descriptions of these
options follow the table.
Table 18. Parameters for the fopen() and freopen() functions for z/OS OS I/O
Parameter Allowed? Applicable? Notes
recfm= Yes Yes Any of the 27 record formats available under
z/OS XL C/C++, plus * and A are valid.
lrecl= Yes Yes 0, any positive integer up to 32760, or X is
valid. See the parameter list below.
blksize= Yes Yes 0 or any positive integer up to 32760 is valid.
space= Yes Yes Valid only if you are opening a new data set by
its data set name. See the parameter list
below.
type= Yes Yes May be omitted. If you do specify it,
type=record is the only valid value.
acc= Yes No Not used for OS I/O.
password= Yes No Not used for OS I/O.
asis Yes No Used to specify mixed-case filenames. Not
recommended.

Chapter 10. Performing OS I/O operations 95

 Table 18. Parameters for the fopen() and freopen() functions for z/OS OS I/O (continued)
Parameter Allowed? Applicable? Notes
byteseek Yes Yes Used for binary files to specify that the seeking
functions should use relative byte offsets
instead of encoded offsets.
noseek Yes Yes Used to disable seeking functions for improved
performance.
OS Yes No Ignored.
abend= Yes Yes See note below.

recfm=
z/OS XL C/C++ allows you to specify any of the 27 possible RECFM types
(listed in Fixed-format records on page 10, Variable-format records on page
13, and Undefined-format records on page 16), as well as the z/OS XL C/C++
RECFMs * and A.
When you are opening an existing file for read or append (or for write, if you
have specified DISP=MOD), any RECFM that you specify must match that of the
existing file, except that you may specify recfm=U to open any file for read, and
you may specify recfm=FBS for a file created as recfm=FB. Specifying recfm=FBS
indicates to z/OS XL C/C++ that there are no short blocks within the file. If there
are, undefined behavior results.
For variable-format OS files, the RDW, SDW, and BDW contain the length of
the record, segment, and block as well as their own lengths. If you open a file
for read with recfm=U, z/OS XL C/C++ treats each physical block as an
undefined-format record. For files created with recfm=V, z/OS XL C/C++ does
not strip off block descriptor words (BDWs) or record descriptor words (RDWs),
and for blocked files, it does not deblock records. Using recfm=U is helpful for
viewing variable-format files or seeing how records are blocked in the file.
When you are opening an existing PDS or PDSE for write and you specify a
RECFM, it must be compatible with the RECFM of the existing data set. FS and
FBS formats are invalid for PDS members. For PDSs, you must use exactly the
same RECFM. For PDSEs, you may choose to change the blocked attribute (B),
because PDSEs perform their own blocking. If you want to read a PDS or
PDSE directory and you specify a RECFM, it must be recfm=U.
Specifying recfm=A indicates that the file contains ASA control characters. If you
are opening an existing file and you specify that ASA characters exist
(>recfm=A) when they do not, the call to fopen() or freopen() fails. If you create
a file by opening it for write or append, the A attribute is added to the default
RECFM. For more information about ASA, see Chapter 7, Using ASA text files,
on page 47.
Specifying recfm=* causes z/OS XL C/C++ to fill in any attributes that you do
not specify, taking the attributes from the existing data set. This is useful if you
want to create a new version of a data set with the same attributes as the
previous version. If you open a data set for write and the data set does not
exist, z/OS XL C/C++ uses the default attributes specified in fopen() defaults
on page 32. This parameter has no effect when you are opening for read or
append, and when you use it for non-DASD files.
recfm=+ is identical to recfm=* with the following exceptions:
v If there is no record format for the existing DASD data set, the defaults are
assigned as if the data set did not exist.
v When append mode is used, the fopen() fails.
96 z/OS V1R13.0 XL C/C++ Programming Guide
lrecl= and blksize=
The LRECL that you specify on the fopen() call defines the maximum record
length that the C library allows. Records longer than the maximum record length
are not written to the file. The first 4 bytes of each block and the first 4 bytes of
each record of variable-format files are used for control information. For more
information, see Variable-format records on page 13.
The maximum LRECL supported for fixed, undefined, or variable-blocked-
spanned format sequential disk files is 32760. For other variable-length format
disk files the maximum LRECL is 32756. Sequential disk files for any format
have a maximum BLKSIZE of 32760. The record length can be any size when
opening a spanned file and specifying lrecl=X. You can now specify lrecl=X on
the fopen() or freopen() call for spanned files. If you are updating an existing
file, the file must have been originally opened with lrecl=X for the open to
succeed. lrecl=X is useful only for text and record I/O.
When you are opening an existing file for read or append (or for write, if you
have specified DISP=MOD), any LRECL or BLKSIZE that you specify must match
that of the existing file, except when you open an F or FB format file on a disk
device without specifying the noseek parameter. In this case, you can specify
the S attribute to indicate to z/OS XL C/C++ that the file has no imbedded short
blocks. Files without short blocks improve z/OS XL C/C++'s performance.
BLKSIZE=0 will be ignored for an existing data set opened for read or append.
When you are opening an existing PDS or PDSE for write and you specify an
LRECL or BLKSIZE, it must be compatible with the LRECL or BLKSIZE of the
existing data set. For PDSs, you must use exactly the same values. For
PDSEs, the LRECL must be the same, but the BLKSIZE may be different if you
have changed the blocking attribute as described under the RECFM parameter
above. You can change the blocking attribute, because PDSEs perform their
own blocking. The BLKSIZE you choose should be compatible with the RECFM
and LRECL. When you open the directory of a PDS or PDSE, do not specify
LRECL or BLKSIZE; z/OS XL C/C++ uses the defaults. See Table 19 on page
102 for more information.
space=(units,(primary,secondary,directory) [rlse | norlse])
This keyword enables you to specify the space parameters for the allocation of
a z/OS data set. It applies only to z/OS data sets that you open by filename
and do not already exist. If you open a data set by ddname, this parameter has
no effect. You cannot specify any whitespace inside the value for the space
keyword. You must specify at least one value with this parameter. Any
parameter that you specify will be validated for syntax. If that validation fails,
then the fopen() or freopen() will fail even if the parameter would have been
ignored.
The supported values for units are as follows:
v Any positive integer indicating BLKSIZE
v CYL (mixed case)
v TRK (mixed case)
The primary quantity, the secondary quantity, and the directory quantity all must
be positive integers. The primary quantity is always required.
If you specify values only for units and primary, you do not have to specify the
inside set of parentheses. You can use a comma to indicate a quantity is to
take the default value. For example:

Chapter 10. Performing OS I/O operations 97

 space=(cyl,(100,,10)) - default secondary value
space=(trk,(100,,)) - default secondary and directory value
space=(500,(100,)) - default secondary, no directory

The last parameter, rlse or norlse , controls the disposition of the unused space.
If you open a new file for write and specify the space keyword, by default, any
unused space will be released when the file is closed. You can preserve the
allocated space by specifying norlse. For example:

space=(cyl,(100,,10),norlse) - does not release unused space

space=(trk,(100,,),rlse) - releases unused space
pace=(500,(100,)) - releases unused space

You can specify only the values indicated on this parameter. If you specify any
other values, fopen() or freopen() fails. Any values not specified are omitted
on the allocation. These values are filled by the system during SVC 99
processing.
type=
You can omit this parameter. If you specify it, the only valid value for OS I/O is
type=record, which opens a file for record I/O.
acc=
This parameter is not valid for OS I/O. If you specify it, z/OS XL C/C++ ignores
it.
password=
This parameter is not valid for OS I/O. If you specify it, z/OS XL C/C++ ignores
it.
asis
If you use this parameter, z/OS XL C/C++ does not convert your filenames to
upper case. The use of the asis parameter is strongly discouraged, because
most of the I/O services used by z/OS XL C/C++ require uppercase filenames.
byteseek
When you specify this parameter and open a file in binary mode, all
repositioning functions (such as fseek() and ftell()) use relative byte offsets
from the beginning of the file instead of encoded offsets. In previous releases of
z/OS XL C/C++, byteseeking was performed only for fixed format binary files. To
have the byteseek parameter set as the default for all your calls to fopen() or
freopen(), you can set the environment variable _EDC_BYTE_SEEK to Y. See
Chapter 32, Using environment variables, on page 467 for more information.
noseek
Specifying this parameter on the fopen() call disables the repositioning
functions ftell(), fseek(), fgetpos(), and fsetpos() for as long as the file is
open. When you have specified NOSEEK and have opened a disk file for read
only, the only repositioning function allowed on the file is rewind(), if the device
supports rewinding. Otherwise, a call to rewind() sets errno and raises
SIGIOERR, if SIGIOERR is not set to SIG_IGN. Calls to ftell(), fseek(),
fsetpos(), or fgetpos() return EOF, set errno, and set the stream error flag on.
The use of the noseek parameter may improve performance when you are
reading and writing data sets.

98 z/OS V1R13.0 XL C/C++ Programming Guide

 Note: If you specify the NOSEEK parameter when you open a file for writing, you
must specify NOSEEK on any subsequent fopen() call that simultaneously opens
the file for reading; otherwise, you will get undefined behavior.
OS
If you specify this parameter, z/OS XL C/C++ ignores it.
abend= abend | recover
This parameter is ignored for SPC applications. The z/OS XL C/C++ run-time
library uses the DCB ABEND exit to intercept abend conditions that occur
during OS I/O operations. When an abend condition occurs, DFSMS issues a
write-to-programmer message and gives control to the DCB ABEND exit. Within
the information provided to the exit, a flag indicates if the abend condition can
be ignored. It is not predictable when an abend condition can be ignored, and
sometimes the same abend condition (completion code and reason code) can
be ignored while at other times it cannot.
When the abend condition can be ignored, the run-time library instructs DFSMS
to do so. This allows the run-time library to return gracefully back to the user
code with a failing return value, errno set to 92 (meaning an I/O abend was
trapped), and diagnostic information in the __amrc structure. DFSMS will have
stopped processing the DCB. Only the fldata(), fclose(), and freopen() functions
are permitted on the stream after an abend condition is trapped.
When the abend condition cannot be ignored, DFSMS issues the abend and
Language Environment condition handling semantics take effect. If condition
handling is active, the abend is converted to a Language Environment condition
or SIGABND signal. In the absence of a condition handler or signal handler, the
default behavior is to terminate the enclave. An application can write its own
condition handler or SIGABND handler and try to recover from the error. As is
the case when an abend condition can be ignored, DFSMS will have stopped
processing the DCB and only the fldata(), fclose(), and freopen() functions are
permitted on the stream.
abend instructs the run-time library to ignore abend conditions that can
be ignored. No attempt is made to recover from abend
conditions that cannot be ignored.
recover instructs the run-time library to attempt to recover from an
abend issued during certain low-level I/O operations (WRITE /
CHECK sequence and CLOSE). If recovery is possible, control
will be returned to the user code with a failing return value,
errno set to 92, and diagnostic information in the __amrc
structure.
The abend keyword specifies the behavior only for the stream being opened. It
overrides the setting of the _EDC_IO_ABEND environment variable. See
Chapter 32, Using environment variables, on page 467 for more information.
Also, see Chapter 18, Debugging I/O programs, on page 221 for more
information on the __amrc structure and handling errors during I/O operations.

Buffering
z/OS XL C/C++ uses buffers to map C I/O to system-level I/O. When z/OS XL
C/C++ performs I/O operations, it uses one of the following buffering modes:
v Line buffering characters are transmitted to the system when a new-line
character is encountered. Line buffering is meaningless for binary and record I/O
files.
v Full buffering characters are transmitted to the system when a buffer is filled.

Chapter 10. Performing OS I/O operations 99

 C/C++ provides a third buffering mode, unbuffered I/O, which is not supported for
OS files.

You can use the setvbuf() and setbuf() library functions to set the buffering mode
before you perform any I/O operation to the file. setvbuf() fails if you specify
unbuffered I/O. It also fails if you try to specify line buffering for an FBS data set
opened in text mode, where the device does not support repositioning. This failure
happens because z/OS XL C/C++ cannot deliver records at line boundaries without
violating FBS format. Do not try to change the buffering mode after you have
performed any I/O operation to the file.

For all files except stderr, full buffering is the default, but you can use setvbuf() to
specify line buffering. For binary files, record I/O files, and unblocked text files, a
block is written out as soon as it is full, regardless of whether you have specified
line buffering or full buffering. Line buffering is different from full buffering only for
blocked text files.

Multiple buffering
Multiple buffering (or asynchronous I/O) is supported for z/OS data sets. Multiple
buffering is not supported for a data set opened for read at the same time that
another file pointer has it opened for write or append. When you open files for
multiple buffering, blocks are read into buffers before they are needed, eliminating
the delay caused by waiting for I/O to complete. Multiple buffering may make I/O
less efficient if you are seeking within or writing to a file, because seeking or writing
may discard blocks that were read into buffers but never used.

To specify multiple buffering, code either the NCP=xx or BUFNO=yy subparameter of

the DCB parameter on the JCL DD statement (or allocation), where xx is an integer
number between 02 and 99, and yy is an integer number normally between 02 and
255. Whether z/OS XL C/C++ uses NCP or BUFNO depends on whether you are using
BSAM or QSAM, respectively. NCP is supported under BSAM; BUFNO is supported
under QSAM. BSAM and QSAM are documented in z/OS DFSMS Using Data Sets.
If you specify noseek, z/OS XL C/C++ uses QSAM if possible. If z/OS XL C/C++ is
using BSAM and you specify a value for BUFNO, z/OS XL C/C++ maps this value to
NCP. If z/OS XL C/C++ is using QSAM and you specify a value for NCP, z/OS XL
C/C++ maps this value to BUFNO.

If you specify both NCP and BUFNO, z/OS XL C/C++ takes the greater of the two
values, up to the maximum for the applicable value. For example, if you specify a
BUFNO of 120 and you are using BSAM, which uses NCP instead, z/OS XL C/C++ will
use NCP=99.

If you do not specify either, z/OS XL C/C++ defaults to single buffering, except in
the following cases, where z/OS XL C/C++ uses the system's default BUFNO and
performs multiple buffering for both reading and writing:
v If you open a device that does not support repositioning, and specify read-only or
write-only mode (r, rb, w, wb, a, ab).
v If you specify the NOSEEK parameter on the call to fopen() or freopen(), and
specify read-only or write-only mode. When you specify NOSEEK, you get multiple
buffering for both reads and writes.

Here is an example of how to specify BUFNO:

//DD5 DD DSNAME=TORONTO.BLUEJAYS,DISP=SHR,DCB=(BUFNO=5)

100 z/OS V1R13.0 XL C/C++ Programming Guide

 You may need to update code from previous releases that relies on z/OS XL C/C++
ignoring NCP or BUFNO parameters.

Note: Multiple buffering is ignored for concatenated and multivolume data sets.

DCB (Data Control Block) attributes

For OS files, the C run-time library creates a skeleton data control block (DCB) for
the file when you open it. File attributes are determined from the following sources
in this order:
1. The fopen() or freopen() function call
2. Attributes for a ddname specified previously (if you are opening by ddname)
3. Existing file attributes (if you specify recfm=* or you are opening an existing file
for read or append)
4. Defaults from fopen() or freopen() for creating a new file.

If you do not specify RECFM when you are creating a new file, z/OS XL C/C++
uses the following defaults:
v If recfm is not specified in a fopen() call for an output binary file, recfm defaults
to:
recfm=VB for spool (printer) files,
recfm=FB otherwise.
v If recfm is not specified in a fopen() call for an output text file, recfm defaults to:
recfm=F if _EDC_ANSI_OPEN_DEFAULT is set to Y and no LRECL or BLKSIZE
specified. In this case, LRECL and BLKSIZE are both defaulted to 254.
recfm=VBA for spool (printer) files.
recfm=U for terminal files
recfm=V if the LRECL or BLKSIZE is specified
recfm=VB for all other OS files.

If recfm is not specified for a record I/O file, you will get the default of recfm=VB.
Table 19 on page 102 shows the defaults for LRECL and BLKSIZE when the z/OS
XL C/C++ compiler creates an OS file. Information from the C or C++ program
overrides that from the DD statement and the tape label. Information from the DD
statement overrides that from the data set label.

Chapter 10. Performing OS I/O operations 101

 C OR C++
PROGRAM file *f;

f = fopen("dd:master","r, DATA CONTROL BOX

blksize=400, recfm=FB")
Record format FB

Block size 400

Record length 100

DD STATEMENT //MASTER DD UNIT=3480,
VOLUME=SER=1791 Device type 3480
DSNAME=LIST,
Recording density 1600
DCB=(...,
RECFM=FB,
BLKSIZE=400,
LRECL=100)

TAPE LABEL
Record format=FB
Record length=100
Block size=400
Recording density=1600

Figure 15. How the operating system completes the DCB

Table 19. fopen() defaults for LRECL and BLKSIZE when creating OS files
lrecl specified? blksize specified? RECFM LRECL BLKSIZE
no no All F 80 80
All FB 80 maximum integral
multiple of 80 less
than or equal to max
All V, VB, VS, or VBS minimum of 1028 or max
max4
All U 0 max
yes no All F lrecl lrecl
All FB lrecl maximum integral
multiple of lrecl less
than or equal to max
All V lrecl lrecl+4
All U 0 lrecl
no yes All F or FB blksize blksize
All V, VB, VS, or VBS minimum of 1028 or blksize
blksize4
All U 0 blksize
Note: All includes the standard (S) specifier for fixed formats, the ASA (A) specifier, and the machine control character
(M) specifier.

In Table 19, the value max represents the maximum reasonable block size for the
device. These are the current default maximum block sizes for several devices that
z/OS XL C/C++ supports:
Device Default maximum block size

102 z/OS V1R13.0 XL C/C++ Programming Guide

 DASD 6144
3203 Printer 132
3211 Printer 132
4245 Printer 132
2540 Reader 80
2540 Punch 80
2501 Reader 80
3890 Document Processor 80
TAPE 32760

For more information about specific default block sizes as returned by the DEVTYPE
macro, refer to z/OS DFSMS Using Data Sets.

You can perform multiple buffering under z/OS. See Multiple buffering on page
100 for details.

Reading from files

You can use the following library functions to read from a file:
v fread()
v fread_unlocked()
v fgetc()
v fgetc_unlocked()
v fgets()
v fgets_unlocked()
v fscanf()
v fscanf_unlocked()
v getc()
v getc_unlocked()
v gets()
v gets_unlocked()
v getchar()
v getchar_unlocked()
v scanf()
v scanf_unlocked()
v vfscanf()
v vfscanf_unlocked()
v vscanf()
v vscanf_unlocked()

fread() is the only interface allowed for reading record I/O files. A read operation
directly after a write operation without an intervening call to fflush(), fsetpos(),
fseek(), or rewind() fails. z/OS XL C/C++ treats the following as read operations:
v Calls to read functions that request 0 bytes
v Read requests that fail because of a system error
v Calls to the ungetc() function

Chapter 10. Performing OS I/O operations 103

 z/OS XL C/C++ does not consider a read to be at EOF until you try to read past the
last byte visible in the file. For example, in a file containing three bytes, the feof()
function returns FALSE after three calls to fgetc(). Calling fgetc() one more time
causes feof() to return TRUE.

You can set up a SIGIOERR handler to catch read or write system errors. See the
debugging section in this book for more details.

Reading from binary files

z/OS XL C/C++ reads binary records in the order that they were written to the file.
Any null padding is visible and treated as data. Record boundaries are
meaningless.

Reading from text files

For non-ASA variable text files, the default for z/OS XL C/C++ is to ignore any
empty physical records in the file. If a physical record contains a single blank, z/OS
XL C/C++ reads in a logical record containing only a new-line. However, if the
environment variable _EDC_ZERO_RECLEN was set to Y, z/OS XL C/C++ reads an
empty physical record as a logical record containing a new-line, and a physical
record containing a single blank as a logical record containing a blank and a
new-line. z/OS XL C/C++ differentiates between empty records and records
containing single blanks, and does not ignore either of them. For more information
about how z/OS XL C/C++ treats empty records in variable format, see Mapping C
types to variable format on page 15.

For ASA variable text files, if a file was created without a control character as its
first byte, the first byte defaults to the ' ' character. When the file is read back, the
first character is read as a new-line.

On input, ASA characters are translated to the corresponding sequence of control

characters. For more information about using ASA files, refer to Chapter 7, Using
ASA text files, on page 47.

For undefined format text files, reading a file causes a new-line character to be
inserted at the end of each record. On input, a record containing a single blank
character is considered an empty record and is translated to a new-line character.
Trailing blanks are preserved for each record.

For files opened in fixed text format, rightmost blanks are stripped off a record at
input, and a new-line character is placed in the logical record. This means that a
record consisting of a single new-line character is represented by a fixed-length
record made entirely of blanks.

Reading from record I/O files

For files opened in record format, fread() is the only interface that supports
reading. Each time you call fread() for a record I/O file, fread() reads one record.
If you call fread() with a request for less than a complete record, the requested
bytes are copied to your buffer, and the file position is set to the start of the next
record. If the request is for more bytes than are in the record, one record is read
and the position is set to the start of the next record. z/OS XL C/C++ does not strip
any blank characters or interpret any data.

fread() returns the number of items read successfully, so if you pass a size
argument equal to 1 and a count argument equal to the maximum expected length

104 z/OS V1R13.0 XL C/C++ Programming Guide

 of the record, fread() returns the length, in bytes, of the record read. If you pass a
size argument equal to the maximum expected length of the record, and a count
argument equal to 1, fread() returns either 0 or 1, indicating whether a record of
length size read. If a record is read successfully but is less than size bytes long,
fread() returns 0.

A failed read operation may lead to undefined behavior until you reposition
successfully.

Writing to files
You can use the following library functions to write to a file:
v fwrite()
v fwrite_unlocked()
v printf()
v printf_unlocked()
v fprintf()
v fprintf_unlocked()
v vprintf()
v vprintf_unlocked()
v vfprintf()
v vfprintf_unlocked()
v puts()
v puts_unlocked()
v fputc()
v fputc_unlocked()
v fputs()
v fputs_unlocked()
v putc()
v putc_unlocked()
v putchar()
v putchar_unlocked()

fwrite() is the only interface allowed for writing to record I/O files. See z/OS XL
C/C++ Run-Time Library Reference for more information on these library functions.

A write operation directly after a read operation without an intervening call to

fflush(), fsetpos(), fseek(), or rewind() fails unless the read operation has
reached EOF. The file pointer does not reach EOF until after you have tried to read
past the last byte of the file.

z/OS XL C/C++ counts a call to a write function writing 0 bytes or a write request
that fails because of a system error as a write operation.

If you are updating a file and a system failure occurs, z/OS XL C/C++ tries to set
the file position to the end of the last record updated successfully. For a
fully-buffered file, this is at the end of the last record in a block. For a line-buffered
file, this may be any record in the current block. If you are writing new data at the
time of a system failure, z/OS XL C/C++ puts the file position at the end of the last

Chapter 10. Performing OS I/O operations 105

 block of the file. In files opened for blocked output, you may lose data written by
other writes to that block before the system failure. The contents of a file after a
system write failure are indeterminate.

If one user opens a file for writing, and another later opens the same file for
reading, the user who is reading the file can check for records that may have been
written past the end of the file by the other user. If the file is a spanned variable text
file, the reader can read part of a spanned record and reach the end of the file
before reading in the last segment of the spanned record.

Writing to binary files

Data flows over record boundaries in binary files. Writes or updates past the end of
a record go to the next record. When you are writing to files and not making any
intervening calls to fflush(), blocks are written to the system as they are filled. If a
fixed record is incomplete when you close the file, z/OS XL C/C++ completes it with
nulls. You cannot change the length of existing records in a file by updating them.

If you are using variable binary files, note the following:

v On input and on update, records that have no length are ignored; you will not be
notified. On output, zero-length records are not written. However, in spanned
files, if the first segment of a record has been written to the system, and the user
flushes or closes the file, a zero-length last segment may be written to the file.
v If you are writing new data in a data set that has variable-length records
(RECFM=V, VB, VBM, etc.), z/OS XL C/C++ may split a record between two blocks
to fill the first block out to the maximum block size. This means that when you
read them, the record boundaries will not necessarily be the same.
v If your file is spanned, records are written up to length LRECL, spanning multiple
blocks if necessary. You can create a spanned file by specifying a RECFM
containing V and S on the fopen() call.

Writing to text files

z/OS XL C/C++ treats the control characters as follows when you are writing to a
non-ASA text file:
\a Alarm. Placed directly into the file; z/OS XL C/C++ does not interpret it.
\b Backspace. Placed directly into the file; z/OS XL C/C++ does not interpret
it.
\f Form feed. Placed directly into the file; z/OS XL C/C++ does not interpret it.
\n New-line. Defines a record boundary; z/OS XL C/C++ does not place it in
the file.
\r Carriage return. Defines a record boundary; z/OS XL C/C++ does not place
it in the file. Treated like a new-line character.
\t Horizontal tab character. Placed directly into the file; z/OS XL C/C++ does
not interpret it.
\v Vertical tab character. Placed directly into the file; z/OS XL C/C++ does not
interpret it.
\x0E DBCS shift-out character. Indicates the beginning of a DBCS string, if
MB_CUR_MAX > 1. Placed into the file.
\x0F DBCS shift-in character. Indicates the end of a DBCS string, if MB_CUR_MAX

106 z/OS V1R13.0 XL C/C++ Programming Guide

 > 1. Placed into the file. See Chapter 8, z/OS XL C Support for the
double-byte character set, on page 51 for more information about
MB_CUR_MAX.

The way z/OS XL C/C++ treats text files depends on whether they are in fixed,
variable, or undefined format, and whether they use ASA.

As with ASA files in other environments, the first character of each record is
reserved for the ASA control character that represents a new-line, a carriage return,
or a form feed. See Chapter 7, Using ASA text files, on page 47 for more
information.
Table 20. C control to ASA characters
C Control Character Sequence ASA Character Description
\n ' ' skip one line
\n\n '0' skip two lines
\n\n\n '-' skip three lines
\f '1' new page
\r '+' overstrike

Writing to fixed-format text files

Records in fixed-format files are all the same length. You complete each record with
a new-line or carriage return character. For fixed text files, the new-line character is
not written to the file. Blank padding is inserted to the LRECL of each record of the
block, and the block, when full, is written. For a more complete description of the
way fixed-format files are handled, see Fixed-format records on page 10.

A logical record can be shortened to be an empty record (containing just a new-line)

or extended to a record containing LRECL bytes of data plus a new-line. Because
the physical record represents the new-line position by using padding blanks, the
new-line position can be changed on an update as long as it is within the physical
record.

Note: Using ftell() or fgetpos() values for positions that do not exist after you
have shortened records results in undefined behavior.

When you are updating a file, writing new data into an existing record replaces the
old data and, if the new data is longer or shorter than the old data, changes the
size of the logical record by changing the number of blank characters in the
physical record. When you extend a record, thereby writing over the old new-line, a
new-line character is implied after the last character of the update. Calling fflush()
flushes the data out to the file and inserts blank padding between the last data
character and the end of the record. Once you have called fflush(), you can call
any of the read functions, which begin reading at the new-line. Once the new-line is
read, reading continues at the beginning of the next record.

Writing to variable-format text files

In a file with variable-length records, each record may be a different length. The
variable length formats permit both variable-length records and variable-length
blocks. The first 4 bytes of each block are reserved for the Block Descriptor Word
(BDW); the first 4 bytes of each record are reserved for the Record Descriptor Word
(RDW).

Chapter 10. Performing OS I/O operations 107

 For ASA and non-ASA, the \n (new-line) character implies a record boundary. On
output, the new-line is not written to the physical file; instead, it is assumed to follow
the data of the record.

If you have not set _EDC_ZERO_RECLEN, z/OS XL C/C++ writes out a record
containing a single blank character to represent a single new-line. On input, a
record containing a single blank character is considered an empty record and is
translated to a new-line character. Note that a single blank followed by a new-line is
written out as a single blank, and is treated as just a new-line on input. When
_EDC_ZERO_RECLEN is set, writing a record containing only a new-line results in a
zero-length variable record.

For more information about environment variables, refer to Chapter 32, Using
environment variables, on page 467. For more information about how z/OS XL
C/C++ treats empty records in variable format, see Mapping C types to variable
format on page 15.

Attempting to shorten a record on update by specifying less data before the

new-line causes the record to be padded with blanks to the original record size. For
spanned records, updating a record to a shorter length results in the same blank
padding to the original record length, over multiple blocks, if applicable.

Attempts to lengthen a record on update generally result in truncation. The

exception to this rule is extending an empty record to a 1-byte record when the
environment variable _EDC_ZERO_RECLEN is not set. Because the physical
representation for an empty record is a record containing one blank character, it is
possible to extend the logical record to a single non-blank character followed by a
new-line character. For standard streams, truncation in text files does not occur;
data is wrapped automatically to the next record as if you had added a new-line.

When you are writing data to a non-blocked file without intervening flush or
reposition requests, each record is written to the system when a new-line or
carriage return character is written or when the file is closed.

When you are writing data to a blocked file without intervening flush or reposition
requests, if the file is opened in full buffering mode, the block is written to the
system on completion of the record that fills the block. If the blocked file is line
buffered, each record is written to the system when it is completed. If you are using
full buffering for a VB format file, a write may not fill a block completely. The data
does not go to the system unless a block is full; you can complete the block with
another write. If the subsequent write contains more data than is needed to fill the
block, it flushes the current block to the system and starts writing your data to a
new block.

When you are writing data to a spanned file without intervening flush or reposition
requests, if the record spans multiple blocks, each block is written to the system
once it is full and the user writes an additional byte of data.

For ASA variable text files, if a file was created without a control character as its
first byte or record (after the RDW and BDW), the first byte defaults to the ' '
character. When the file is read back, the first character is read as a new-line.

Writing to undefined-format text files

In an undefined-format file, there is only one record per block. Each record may be
a different length, up to a maximum length of BLKSIZE. Each record is completed
with a new-line or carriage return character. The new-line character is not written to

108 z/OS V1R13.0 XL C/C++ Programming Guide

 the physical file; it is assumed to follow the data of the record. However, if a record
contains only a new-line character, z/OS XL C/C++ writes a record containing a
single blank to the file to represent an empty record. On input, the blank is read in
as a new-line.

Once a record has been written, you cannot change its length. If you try to shorten
a logical record by updating it with a shorter record, z/OS XL C/C++ completes the
record with blank padding. If you try to lengthen a record by updating it with more
data than it can hold, z/OS XL C/C++ truncates the new data. The only instance in
which this does not happen is when you extend an empty record so that it contains
a single byte. Any data beyond the single byte is truncated.

Truncation versus splitting

If you try to write more data to a record than z/OS XL C/C++ allows, and the file
you are writing to is not one of the standard streams (the defaults, or those
redirected by freopen() or command-level redirection), output is cut off at the
record boundary and the remaining bytes are discarded. z/OS XL C/C++ does not
count the discarded characters as characters that have been written out
successfully.

In all truncation cases, the SIGIOERR signal is raised if the action for SIGIOERR is not
SIG_IGN. The user error flag is set so that ferror() will return TRUE. For more
information about SIGIOERR, ferror(), and other I/O-related debugging tools, see
Chapter 18, Debugging I/O programs, on page 221. z/OS XL C/C++ continues to
discard new output until you complete the current record by writing a new-line or
carriage return character, close the file, or change the file position.

If you are writing to one of the standard streams, attempting to write more data than
a record can hold results in the data being split across multiple records.

Writing to record I/O files

fwrite() is the only interface allowed for writing to a file opened for record I/O.
Only one record is written at a time. If you attempt to write more new data than a
full record can hold or you try to update a record with more data than it currently
has, z/OS XL C/C++ truncates your output at the record boundary. When z/OS XL
C/C++ performs a truncation, it sets errno and raises SIGIOERR, if SIGIOERR is not
set to SIG_IGN.

When you update a record, you can update less than the full record. The remaining
data that you do not update is left untouched in the file.

When you are writing new records to a fixed-record I/O file, if you try to write a
short record, z/OS XL C/C++ pads the record with nulls out to LRECL.

At the completion of an fwrite(), the file position is at the start of the next record.
For new data, the block is flushed out to the system as soon as it is full.

Flushing buffers
You can use the library function fflush() to flush streams to the system. For more
information about fflush(), see z/OS XL C/C++ Run-Time Library Reference.

The action taken by the fflush() library function depends on the buffering mode
associated with the stream and the type of streams. If you call one z/OS XL C/C++
program from another z/OS XL C/C++ program by using the ANSI system()

Chapter 10. Performing OS I/O operations 109

 function, all open streams are flushed before control is passed to the callee, and
again before control is returned to the caller. If you are running with POSIX(ON), a
call to the POSIX system() function does not flush any streams to the system.

Updating existing records

Calling fflush() while you are updating flushes the updates out to the system. If
you call fflush() when you are in the middle of updating a record, z/OS XL C/C++
writes the partially updated record out to the system. A subsequent write continues
to update the current record.

Reading updated records

If you have a file open for read at the same time that the file is open for write in the
same application, you will be able to see the new data if you call fflush() to
refresh the contents of the input buffer, as shown in Figure 16.

/* this example demonstrates how updated records are read */

#include <stdio.h>
int main(void)
{
FILE * fp, * fp2;
int rc, rc2, rc3, rc4;
fp = fopen("a.b","w+");

fprintf(fp,"first record");

fp2 = fopen("a.b","r"); /* Simultaneous Reader */

/* following gets EOF since fp has not completed first line

* of output so nothing will be flushed to file yet */
rc = fgetc(fp2);
printf("return code is %i\n", rc);

fputc(\n, fp); /* this will complete first line */

fflush(fp); /* ensures data is flushed to file */

rc2 = fgetc(fp2); /* this gets f from first record */

printf("value is now %c\n", rc2);

rewind(fp);

fprintf(fp, "some updates\n");

rc3 = fgetc(fp2); /* gets i ..doesnt know about update */
printf("value is now %c\n", rc3);

fflush(fp); /* ensure update makes it to file */

fflush(fp2); /* this updates readers buffer */

rc4 = fgetc(fp2); /* gets m, 3rd char of updated record */

printf("value is now %c\n", rc4);

return(0);
}

Figure 16. Example of reading updated records

110 z/OS V1R13.0 XL C/C++ Programming Guide

Writing new records
Writing new records is handled differently for:
v Binary streams
v Text streams
v Record I/O

Binary streams
z/OS XL C/C++ treats line buffering and full buffering the same way for binary files.

If the file has a variable length or undefined record format, fflush() writes the
current record out. This may result in short records. In blocked files, this means that
the block is written to disk, and subsequent writes are to a new block. For fixed
files, no incomplete records are flushed.

For single-volume disk files in FBS format, fflush() flushes complete records in an
incomplete block out to the file. For all other types of FBS files, fflush() does not
flush an incomplete block out to the file.

For files in FB format, fflush() always flushes out all complete records in the
current block. For sequential DASD files, new completed records are added to the
end of the flushed block if it is short. For non-DASD or non-sequential files, any
new record will start a new block.

Text streams
v Line-Buffered Streams
fflush() has no effect on line-buffered text files, because z/OS XL C/C++ writes
all records to the system as they are completed. All incomplete new records
remain in the buffer.
v Fully Buffered Streams
Calling fflush() flushes all completed records in the buffer, that is, all records
ending with a new-line or carriage return (or form feed character, if you are using
ASA), to the system. z/OS XL C/C++ holds any incomplete record in the buffer
until you complete the record or close the file.

For ASA text files, if a flush occurs while an ASA character that indicates more than
one new-line is being updated, the remaining new-lines will be discarded and a
read will continue at the first data character. For example, if \n\n\n is updated to
be \n\n and a flush occurs, then a 0 will be written out in the ASA character
position.

Record I/O
z/OS XL C/C++ treats line buffering and full buffering the same way for record I/O.
For files in FB format, calling fflush() writes all records in the buffer to the system.
For single-volume disk files in FBS format, fflush() will flush complete records in an
incomplete block out to the file. For all other types of FBS files, fflush() will not
flush an incomplete block out to the file. For all other formats, calling fflush() has
no effect, because fwrite() has already written the records to disk.

ungetc() considerations
ungetc() pushes characters back onto the input stream for binary and text files.
ungetc() handles only single-byte characters. You can use it to push back as many
as four characters onto the ungetc() buffer. For every character pushed back with
ungetc(), fflush() backs up the file position by one character and clears all the
pushed-back characters from the stream. Backing up the file position may end up

Chapter 10. Performing OS I/O operations 111

 going across a record boundary. Remember that for text files, z/OS XL C/C++
counts the new-lines added to the records as single-byte characters when it
calculates the file position.

A B C D

file pointer

For example, given the stream you can run the following code fragment:
fgetc(fp); /* Returns A and puts the file position at */
/* the beginning of the character B */
ungetc(Z,fp); /* Logically inserts Z ahead of B */
fflush(fp); /* Moves the file position back by one to A, */
/* removes Z from the logical stream */

If you want fflush() to ignore ungetc() characters, you can set the _EDC_COMPAT
environment variable. See Chapter 32, Using environment variables, on page 467
for more information.

Repositioning within files

You can use the following library functions to help you position within a file:
v fseek()
v fseek_unlocked()
v fseeko()
v fseeko_unlocked()
v ftell()
v ftell_unlocked()
v ftello()
v ftello_unlocked()
v fgetpos()
v fgetpos_unlocked()
v fsetpos()
v fsetpos_unlocked()
v rewind()
v rewind_unlocked()

With large file support enabled for AMODE 31 C/C++ applications, you can use the
following library functions for 64-bit offsets:
v fseeko()
v fseeko_unlocked()
v ftello()
v ftello_unlocked()
For AMODE 64 C/C++ applications, large files are automatically supported in the
LP64 programming model. All of the above functions (both lists) can be used with
64-bit offsets.

See z/OS XL C/C++ Run-Time Library Reference for more information on these
library functions.

112 z/OS V1R13.0 XL C/C++ Programming Guide

 Opening a file with fopen() and specifying the NOSEEK parameter disables all of
these library functions except rewind(). A call to rewind() causes the file to be
reopened, unless the file is a non-disk file opened for write-only. In this case,
rewind() sets errno and raises SIGIOERR (if SIGIOERR is not set to SIG_IGN, which is
its default).

Calling any of these functions flushes all complete and updated records out to the
system. If a repositioning operation fails, z/OS XL C/C++ attempts to restore the
original file position and treats the operation as a call to fflush(), except that it
does not account for the presence of ungetc() or ungetwc() characters, which are
lost. After a successful repositioning operation, feof() always returns 0, even if the
position is just after the last byte of data in the file.

The fsetpos() and fgetpos() library functions are generally more efficient than ftell()
and fseek(). The fgetpos() function can encode the current position into a structure
that provides enough room to hold the system position as well as position data
specific to C or C++. The ftell() function must encode the position into a single
word of storage, which it returns. This compaction forces fseek() to calculate
certain position information specific to C or C++ at the time of repositioning. For
variable-format binary files, you can choose to have ftell() return relative byte
offsets. In previous releases, ftell() returned only encoded offsets, which
contained the relative block number. Since you cannot calculate the block number
from a relative byte offset in a variable-format file, fseek() may have to read
through the file to get to the new position. fsetpos() has system position
information available within the the fpos_t structure and can generally reposition
directly to the desired location.

You can use the ftell() and fseek() functions to set the current position within all
types of files except for the following:
v Files on nonseekable devices (for example, printers)
v Partitioned data sets opened in w or wb mode.

Although repositioning within files opened for write mode is not available, you can
use fgetpos() and ftell() to save the current position, and this position can later
be used to reposition within the same file if opened in one of the modes where
reposition is allowed.

For AMODE 31 C/C++ applications, the repositioning functions can be used with
large format sequential data sets under the following conditions:
v The data set contains 256 TB - 256 bytes or less.
v The data set uses 2 GB blocks or less.

ungetc() considerations
For binary and text files, the library functions fgetpos() and ftell() take into
account the number of characters you have pushed back onto the input stream with
ungetc(), and adjust the file position accordingly. ungetc() backs up the file position
by a single byte each time you call it. For text files, z/OS XL C/C++ counts the
new-lines added to the records as single-byte characters when it calculates the file
position.

If you make so many calls to ungetc() that the logical file position is before the
beginning of the file, the next call to ftell() or fgetpos() fails.

Chapter 10. Performing OS I/O operations 113

 When you are using fseek() with a whence value of SEEK_CUR, the starting point
for the reposition also accounts for the presence of ungetc() characters and
compensates as ftell() and fgetpos() do.

If you want fgetpos() and fseek() to ignore ungetc() characters, you can set the
_EDC_COMPAT environment variable. See Chapter 32, Using environment variables,
on page 467 for details. ftell() is not affected by the setting of _EDC_COMPAT.

How long fgetpos() and ftell() values last

As long as you do not re-create a file or shorten logical records, you can rely on the
values returned by ftell() and fgetpos(), even across program boundaries and
calls to fclose(). (Calling fopen() or freopen() with any of the w modes re-creates
a file.) Using ftell() and fgetpos() values that point to information deleted or
re-created results in undefined behavior. For more information about shortening
records, see Writing to variable-format text files on page 107.

Using fseek() and ftell() in binary files

With binary files, ftell() returns two types of positions:
v Relative byte offsets
v Encoded offsets

Relative byte offsets

You get byte offsets by default when you are seeking or positioning in fixed-format
binary files. You can also use byte offsets on a variable or undefined format file
opened in binary mode with the BYTESEEK parameter specified on the fopen() or
freopen() function call. You can specify BYTESEEK to be the default for fopen()
calls by setting the environment variable _EDC_BYTE_SEEK to Y. See Chapter 32,
Using environment variables, on page 467 for information on how to set
environment variables.

You do not need to acquire an offset from ftell() to seek to a relative position; you
may specify a relative offset to fseek() with a whence value of SEEK_SET.
However, you cannot specify a negative offset to fseek() when you have specified
SEEK_SET, because a negative offset would indicate a position before the
beginning of the file. Also, you cannot specify a negative offset with whence values
of SEEK_CUR or SEEK_END such that the resulting file position would be before
the beginning of the file. If you specify such an offset, fseek() fails.

If your file is not opened read-only, you can specify a position that is beyond the
current EOF. In such cases, a new end-of-file position is created; null characters are
automatically added between the old EOF and the new EOF.

fseek() support of byte offsets in variable-format files generally requires reading all
records from the whence value to the new position. The impact on performance is
greatest if you open an existing file for append in BYTESEEK mode and then call
ftell(). In this case, ftell() has to read from the beginning of the file to the
current position to calculate the required byte offset. Support for byteseeking is
intended to ease portability from other platforms. If you need better performance,
consider using ftell()-encoded offsets, see Encoded offsets on page 115.

For AMODE 31 C/C++ applications repositioning within a large format sequential

data set that need fseek() and ftell() to access positions beyond 2 GB - 1 byte
must use the large file version of fseeko() and ftello().

114 z/OS V1R13.0 XL C/C++ Programming Guide

 Encoded offsets
If you do not specify the BYTESEEK parameter and you set the _EDC_BYTE_SEEK
variable to N, any variable- or undefined-format binary file gets encoded offsets from
ftell(). This keeps this release of z/OS XL C/C++ compatible with code generated
by old releases of C/370.

Encoded offsets are values representing the block number and the relative byte
within that block, all within one long int. Because z/OS XL C/C++ does not
document its encoding scheme, you cannot rely on any encoded offset not returned
by ftell(), except 0, which is the beginning of the file. This includes encoded
offsets that you adjust yourself (for example, with addition or subtraction). When
you call fseek() with the whence value SEEK_SET, you must use either 0 or an
encoded offset returned from ftell(). For whence values of SEEK_CUR and
SEEK_END, however, you specify relative byte offsets. If you want to seek to a
certain relative byte offset, you can use SEEK_SET with an offset of 0 to rewind the
file to the beginning, and then you can use SEEK_CUR to specify the desired
relative byte offset.

In earlier releases, ftell() could determine position only for files with no more than
131,071 blocks. In the new design, this number increases depending on the block
size. From a maximum block size of 32,760, every time this number decreases by
half, the number of blocks that can be represented doubles. Using the large file
version of ftello() for a large format sequential data set increases the maximum
number of blocks that can be represented to 2 GB in AMODE 31 C/C++
applications.

If your file is not opened read-only, you can use SEEK_CUR or SEEK_END to
specify a position that is beyond the current EOF. In such cases, a new end-of-file
position is created; null characters are automatically added between the old EOF and
the new EOF. This does not apply to PDS members, as they cannot be extended.
For SEEK_SET, because you are restricted to using offsets returned by ftell(),
any offset that indicates a position outside the current file is invalid and causes
fseek() to fail.

Using fseek() and ftell() in text files (ASA and Non-ASA)

In text files, ftell() produces only encoded offsets. It returns a long int, in which
the block number and the byte offset within the block are encoded. You cannot rely
on any encoded offset not returned by ftell() except 0. This includes encoded
offsets that you adjust yourself (for example, with addition or subtraction).

When you call fseek() with the whence value SEEK_SET, you must use an encoded
offset returned from ftell(). For whence values of SEEK_CUR and SEEK_END,
however, you specify relative byte offsets. If you want to seek to a certain relative
byte offset, you can use SEEK_SET with an offset of 0 to rewind the file to the
beginning, and then you can use SEEK_CUR to specify the desired relative byte
offset. z/OS XL C/C++ counts new-line characters and skips to the next record each
time it reads one.

Unlike binary files you cannot specify offsets for SEEK_CUR and SEEK_END that
set the file position past the end of the file. Any offset that indicates a position
outside the current file is invalid and causes fseek() to fail.

In earlier releases, ftell() could determine position only for files with no more than
131071 blocks. In the new design, this number increases depending on the block
size. From a maximum block size of 32760, every time this number decreases by

Chapter 10. Performing OS I/O operations 115

 half, the number of blocks that can be represented doubles. Using the large file
version of ftello() for a large format sequential data set increases the maximum
number of blocks that can be represented to 2 GB in AMODE 31 C/C++
applications.

Repositioning flushes all updates before changing position. An invalid call to

fseek() is now always treated as a flush. It flushes all updated records or all
complete new records in the block, and leaves the file position unchanged. If the
flush fails, any characters in the ungetc() buffer are lost. If a block contains an
incomplete new record, the block is saved and will be completed by another write or
by closing the file.

Using fseek() and ftell() in record files

For files opened with type=record, ftell() returns relative record numbers. The
behavior of fseek() and ftell() is similar to that when you use relative byte offsets
for binary files, except that the unit is a record rather than a byte. For example,
fseek(fp,-2,SEEK_CUR);

seeks backward two records from the current position.

fseek(fp,6,SEEK_SET);

seeks to relative record 6. You do not need to get an offset from ftell().

You cannot seek past the end or before the beginning of a file.

The first record of a file is relative record 0.

For AMODE 31 C/C++ applications repositioning within a large format sequential

data set that need fseek() and ftell() to access positions beyond 2 GB - 1 record
must use the large file version of fseeko() and ftello().

Porting old C code that uses fseek() or ftell()

The encoding scheme used by ftell() in non-BYTESEEK mode in the z/OS XL
C/C++ RTL is different from that used in the XL C/C++ run-time library prior to
C/370 Release 2.2 and Language Environment prior to release 1.3.
v If your code obtains ftell() values and passes them to fseek(), the change to
the encoding scheme should not affect your application. On the other hand, your
application may not work if you have saved encoded ftell() values in a file and
your application reads in these encoded values to pass to fseek(). For
non-record I/O files, you can set the environment variable _EDC_COMPAT with the
ftell() encoding set to tell z/OS XL C/C++ that you have old ftell() values.
Files opened for record I/O do not support old ftell() values saved across the
program boundary.
v In previous versions, the fseek() support for the ftell() encoding scheme
inadvertently supported seeking from SEEK_SET with a byte offset up to 32K.
This is no longer be supported. Users of this support must change to BYTESEEK
mode. You can do this without changing your source code; just use the
_EDC_BYTE_SEEK environment variable.

116 z/OS V1R13.0 XL C/C++ Programming Guide

Closing files
Use the fclose() library function to close a file. z/OS XL C/C++ automatically
closes files on normal program termination and attempts to do so under abnormal
program termination or abend. See z/OS XL C/C++ Run-Time Library Reference for
more information on this library function.

For files opened in fixed binary mode, incomplete records will be padded with null
characters when you close the file.

For files opened in variable binary mode, incomplete records are flushed to the
system. In a spanned file, closing a file can cause a zero-length segment to be
written. This segment will still be part of the non-zero-length record. For files
opened in undefined binary mode, any incomplete output is flushed on close.

Closing files opened in text mode causes any incomplete new record to be
completed with a new-line character. All records not yet flushed to the file are
written out when the file is closed.

For files opened for record I/O, closing causes all records not yet flushed to the file
to be written out.

Note: If an application has locked a (FILE *) object (with flockfile() or

ftrylockfile()), it is responsible for relinquishing the locked (FILE *) object (with
funlockfile()) before calling fclose(). Failure to relinquish a locked (FILE *)
object may cause deadlock or looping.

When fclose() is used to close a stream associated with a z/OS data set, some
failures may be unrecoverable, and will result in an ABEND. These ABENDs may
include I/O ABENDs of the form x14 and x37. Control will not be returned to the
caller of fclose() to report the error. To process these types of errors, applications
need to use z/OS Language Environment condition handling to receive control (see
z/OS Language Environment Programming Guide), or register a signal handler for
SIGABND (see Chapter 28, Handling error conditions, exceptions, and signals, on
page 403).

If an application fails during fclose() with a x37 abend, and the application would
like to recover and perform any functions not related to file I/O, the following
technique can be used. Refer to Figure 17 on page 118 for an example.
1. Register a signal handler for SIGABND and SIGIOERR.
2. fopen() the file. The NOSEEK option cannot be specified.
3. Manipulate the file as needed by the application.
4. When the application is done with the file, fflush() the file, before any fclose() is
issued. This will ensure, if an x37 is going to occur during fflush() or fclose()
processing, that the x37 occurs in the fflush(), before the fclose() occurs.
5. An x37 abend occurs during fflush().
6. The signal handler will receive control.
7. Once inside the signal handler, any functions not related to file I/O may be
performed.

Chapter 10. Performing OS I/O operations 117

 /* example of signal handler */

#include <stdio.h>
#include <stdlib.h>
#include <dynit.h>
#include <signal.h>
#include <setjmp.h>

void sighandler();
jmp_buf env;
FILE *f;

int main()
{
int rc;
int s=80;
int w;
char buff 80 ="data";
__dyn_t ip;

redo:
dyninit(&ip);
ip.__dsname="MY.DATASET";
ip.__status=__DISP_OLD;
ip.__ddname="NAMEDD";
ip.__conddisp=__DISP_CATLG;
rc=dynalloc(&ip);

f=fopen("DD:NAMEDD","wb");
if (f==0)
{ perror("open error");
return 12;
}

signal(SIGABND,sighandler);
signal(SIGIOERR,sighandler);

while (1)
{
if (setjmp(env))
{
dyninit(&ip);
ip.__ddname="NAMEDD";
ip.__conddisp=__DISP_CATLG;
rc= dynfree(&ip);
goto retry;
}
w=fwrite(buff,1,s,f);
}

fflush(f);
fclose(f);

retry:
goto redo;
}

void sighandler() {
fclose(f);
longjmp(env,1);
}

Figure 17. Example of signal handler

118 z/OS V1R13.0 XL C/C++ Programming Guide

 Note: When an abend condition occurs, a write-to-programmer message about the
abend is issued and your DCB abend exit is given control, provided there is an
active DCB abend exit routine address in the exit list contained in the DCB being
processed. If STOW called the end-of-volume routines to get secondary space to
write an end-of-file mark for a PDS, or if the DCB being processed is for an indexed
sequential data set, the DCB abend exit routine is not given control if an abend
condition occurs. If the situation described above is encountered, the Language
Environment DCB abend exit will not receive control, and therefore the signal
handler routine in an application will not receive control for the x37 abend.

Renaming and removing files

You can remove or rename a z/OS data set that has an uppercase filename by
using the remove() or rename() library functions, respectively. rename() and
remove() both accept data set names. rename() does not accept ddnames, but
remove() does. You can use remove() or rename() on individual members or entire
PDSs or PDSEs. If you use rename() for a member, you can change only the name
of the member, not the name of the entire data set. To rename both the member
and the data set, make two calls to rename(), one for the member and one for the
whole PDS or PDSE.

fldata() behavior
The format of the fldata() function is as follows:
The fldata() function is used to retrieve information about an open stream. The

int fldata(FILE *file, char *filename,

fldata_t *info);

name of the file is returned in filename and other information is returned in the
fldata_t structure, shown in Figure 18 on page 120. Values specific to this category
of I/O are shown in the comment beside the structure element. Additional notes
follow the figure. For more information on the fldata() function, refer to z/OS XL
C/C++ Run-Time Library Reference.

Chapter 10. Performing OS I/O operations 119

 struct __fileData {
unsigned int __recfmF : 1,/* */
__recfmV : 1,/* */
__recfmU : 1,/* */
__recfmS : 1,/* */
__recfmBlk : 1,/* */
__recfmASA : 1,/* */
__recfmM : 1,/* */
__dsorgPO : 1,/* */
__dsorgPDSmem : 1,/* */
__dsorgPDSdir : 1,/* */
__dsorgPS : 1,/* */
__dsorgConcat : 1,/* */
__dsorgMem : 1,/* N/A -- always off */
__dsorgHiper : 1,/* N/A -- always off */
__dsorgTemp: 1,/* */
__dsorgVSAM: 1,/* N/A -- always off */
__dsorgHFS : 1,/* N/A -- always off */
__openmode : 2,/* one of: */
/* __TEXT */
/* __BINARY */
/* __RECORD */
__modeflag : 4, /* combination of: */
/* __READ */
/* __WRITE */
/* __APPEND */
/* __UPDATE */
__dsorgPDSE: 1, /* N/A -- always off */
__vsamRLS : 3, /* N/A */
#if __EDC_TARGET >= 0x41080000 */
__vsamEA : 1, */
__recfmB : 1, */
__reserve2: 3; */
#else */
__reserve3: 5; */
#endif */
__device_t __device; /* one of: */
/* __DISK */
/* __TAPE */
/* __PRINTER */
/* __DUMMY */
/* __OTHER */
unsigned long __blksize, /* */
__maxreclen; /* */
union { /* */
struct { /* */
unsigned short __vsam_type; /* N/A */
unsigned long __vsam_keylen; /* N/A */
unsigned long __vsam_RKP; /* N/A */
} __vsam; /* */
struct { /* */
unsigned short __disk_vsam_type; /* */
unsigned char __disk_access_method; /* */
unsigned char __disk_noseek_to_seek; /* */
long __disk_reserve[2]; /* */
} __disk; /* */
} __device_specific; /* */
char * __dsname; /* */
unsigned int __reserve4; /* */
};
typedef struct __fileData fldata_t;

Figure 18. fldata() Structure

120 z/OS V1R13.0 XL C/C++ Programming Guide

Notes:
1. If you have opened the file by its data set name, filename is fully qualified,
including quotation marks. If you have opened the file by ddname, filename is
dd:ddname, without any quotation marks. The ddname is uppercase. If you
specified a member on the fopen() or freopen() function call, the member is
returned as part of filename.
2. Any of the __recfm bits may be set on for OS files.
3. The __dsorgPO bit will be set on only if you are reading a directory or member
of a partitioned data set, either regular or extended, regardless of whether the
member is specified on a DD statement or on the fopen() or freopen()
function call. The __dsorgPS bit will be set on for all other OS files.
4. The __dsorgPDSE bit will be set when processing an extended partitioned data
set (PDSE).
5. The __dsorgConcat bit will be set on for a concatenation of sequential data
sets, but not for a concatenation of partitioned data sets.
6. The __dsorgTemp bit will be set on only if the file was created using the
tmpfile() function.
7. The __blksize value may include BDW and RDWs.
8. The __maxreclen value may include the ASA character.
9. The __recfm bits and the __blksize and __maxreclen values correspond to the
attributes of the open stream. They do not necessarily reflect the attributes of
the existing data set.
10. The __dsname field is filled in for __DISK files with the data set name. The
member name is added if the file is a member of a partitioned data set, either
regular or extended. The __dsname value is uppercase unless the asis option
was specified on the fopen() or freopen() function call. The __dsname field is
set to NULL for all other OS files.

Chapter 10. Performing OS I/O operations 121

122 z/OS V1R13.0 XL C/C++ Programming Guide
Chapter 11. Performing z/OS UNIX file system I/O operations
You can create the following file types in the z/OS UNIX file system:
v Regular
v Link
v Directory
v Character special
v FIFO

The Single UNIX Specification defines another type of file called STREAMS. Even
though the system interfaces are provided, it is impossible to have a valid STREAMS
file descriptor. These interfaces will always return a return code of -1 with errno set
to indicate an error such as, EBADF, EINVAL, or ENOTTY.

z/OS UNIX file system streams follow the binary model, regardless of whether they
are opened for text, binary, or record I/O. You can simulate record I/O by using
new-line characters as record boundaries.

For information on the z/OS UNIX file system and access to files within it from other
than the C or C++ language, see z/OS UNIX System Services User's Guide. For an
introduction to and description of the behavior of a POSIX-defined file system, see
Zlotnick, Fred, The POSIX.1 Standard: A Programmer's Guide,,Redwood City, CA:
The Benjamin/Cummings Publishing Company, Inc., 1991.

This topic describes C I/O stream functions as they can be used within C++
programs. If you want to use the C++ I/O stream classes instead, see Chapter 4,
Using the Standard C++ Library I/O Stream Classes, on page 21. For more
detailed information, see Standard C++ Library Reference. For information about
using wide-character I/O with z/OS XL C/C++, see Chapter 8, z/OS XL C Support
for the double-byte character set, on page 51.

Creating files
You can use library functions to create the following types of z/OS UNIX file system
files.
v Regular Files
v Link and Symbolic Link Files
v Directory Files
v Character Special Files
v FIFO Files

Regular files
Use any of the following C functions to create regular files in the z/OS UNIX file
system:
v creat()
v fopen()
v freopen()
v open()

For a description of these and other I/O functions, see z/OS XL C/C++ Run-Time
Library Reference.
Copyright IBM Corp. 1996, 2012 123
Link and symbolic link files
Use either of the following C functions to create z/OS UNIX file system link or
symbolic link files:
v link()
v symlink()

Directory files
Use the mkdir() C function to create a z/OS UNIX file system directory file.

Character special files

Use the mknod() C function to create a character special file in the z/OS UNIX file
system; you must have superuser authority to create a character special file.

Other functions used for character special files are:

v ptsname()
v grantpt()
v unlockpt()
v tcgetsid()
v ttyname()
v isatty()

FIFO files
Use the mkfifo() C function to create a FIFO file (named pipe) in the z/OS UNIX
file system.

To create an unnamed pipe, use the pipe() C function.

Opening files
This section discusses the use of the fopen() or freopen() library functions to open
z/OS UNIX file system I/O files. You can also access z/OS UNIX file system files
using low-level I/O open() function. See Low-level z/OS UNIX I/O on page 137 for
information about low-level I/O, and z/OS XL C/C++ Run-Time Library Reference
for information about any of the functions listed above.

The name of a z/OS UNIX file system file can include characters chosen from the
complete set of character values, except for null characters. If you want a portable
filename, then choose characters from the POSIX .1 portable filename character
set.

The complete pathname can begin with a slash and be followed by zero, one, or
more filenames, each separated by a slash. If a directory is included within the
pathname, it may have one or more trailing slashes. Multiple slashes following one
another are interpreted as one slash.

If your program is running under POSIX(ON), all valid POSIX names are passed with
the asis fopen() parameter to the POSIX open() function.

You can access either z/OS UNIX file system files or MVS data sets from programs.
Programs accessing files or data sets can be executed with either the POSIX(OFF)
or POSIX(ON) run-time options. There are basic file naming rules that apply for z/OS

124 z/OS V1R13.0 XL C/C++ Programming Guide

 UNIX file system files and MVS data sets. However, there are also special z/OS XL
C/C++ naming considerations that depend on how you execute your program.

The POSIX run-time option determines the type of z/OS XL C/C++ services and I/O
available to your program. (See z/OS XL C/C++ User's Guide for a discussion of
the z/OS UNIX programming environment and overview of binding z/OS UNIX XL
C/C++ applications.)

Both the basic and special z/OS XL C/C++ file naming rules for z/OS UNIX file
system files are described in the sections that follow. Examples are provided. All
examples must be run with the POSIX(ON) option. For information about MVS data
sets, see Chapter 10, Performing OS I/O operations, on page 81.

Using fopen() or freopen()

When you open a file with fopen() or freopen(), you must specify the data set
name, file name, or ddname.

File naming considerations

Files are opened with a call to fopen() or freopen() in the format
fopen("filename", "mode").

z/OS UNIX file system files: The following is the format for the pathname
argument on the fopen() or freopen() function:

 pathname 
" /
.
dd: ddname
// DD: ( member ) "

The POSIX.1 standard defines pathname as the information that identifies a file. For
the z/OS UNIX implementation of the POSIX.1 standard, a pathname can be up to
1024 charactersincluding the null-terminating character. Optionally, it can begin
with a slash character (/) followed by directory names separated by slash
characters and a filename. For the pathname, each directory name or the filename
can be up to 255 characters long.

Note: Regardless of whether your program is run under z/OS UNIX or as a

traditional MVS application, if the pathname that you attempt to open using fopen()
or freopen() contains a slash character but does not begin with exactly two
slashes, a z/OS UNIX file system file is opened. For example, if you code:
fopen("tradnsell/parts.order", "w+")

the file tradnsell/parts.order from the working directory is opened.

If you begin the pathname value with ./, the specified file in the working directory is
opened:
fopen("./parts.order", "w+")

Likewise, if you begin the pathname value with /, the specified file in the root
directory is opened:
fopen("/parts.order", "w+")

Chapter 11. Performing z/OS UNIX file system I/O operations 125
 If you specify more than two consecutive slash characters anywhere in a pathname,
all but the first slash character is ignored, as in the following examples:
"//a.b" MVS data set prefix.a.b
"///a.b" z/OS UNIX file system file /a.b
"////a.b" z/OS UNIX file system file /a.b
"a////b.c" z/OS UNIX file system file a/b.c
"/a.b" z/OS UNIX file system file /a.b
"/a///b.c" z/OS UNIX file system file /a/b.c

If you specify /dd:pathname or ./dd:pathname, a file named dd:pathname is opened

in the file system root directory or your working directory, respectively. For example,
if you code the following statement, the file dd:parder is opened in the root
directory.
fopen("/dd:parder", "w+")

For z/OS UNIX file system files, leading and trailing white spaces are significant.

Opening a file by name

Which type of file (z/OS UNIX file system or MVS data set) you open may depend
on whether the z/OS XL C/C++ application program is running under POSIX(ON).

For an application program that is to be run under POSIX(ON), you can include in
your program statements similar to the following to open the file parts.instock for
reading in the working directory:
FILE *stream;

stream = fopen("parts.instock", "r");

To open the MVS data set user-prefix.PARTS.INSTOCK for reading, include statements
similar to the following in your program:
FILE *stream;

stream = fopen("//parts.instock", "r");

For an application program that is to be run as a traditional z/OS XL C/C++

application program, with POSIX(OFF), to open the MVS data set
user-prefix.PARTS.INSTOCK for reading, include statements similar to the following in
your program:
FILE *stream;

stream = fopen("parts.instock", "r");

To open the file parts.instock in the working directory for reading, include
statements similar to the following in your program:
FILE *stream;

stream = fopen("./parts.instock", "r");

Opening a file by DDname

The DD statement enables you to write z/OS XL C/C++ source programs that are
independent of the files and I/O devices they will use. You can modify the
parameters of a file or process different files without recompiling your program.

126 z/OS V1R13.0 XL C/C++ Programming Guide

When dd:ddname is specified to fopen() or freopen(), the z/OS XL C/C++ library
looks to find and resolve the data definition information for the filename to open. If
the data definition information points to an MVS data set, MVS data set naming
rules are followed. If a z/OS UNIX file system file is indicated using the PATH
parameter on the data definition statement, a ddname is resolved to the associated
pathname.

Note: Use of the z/OS XL C/C++ fork() library function from an application
program under z/OS UNIX does not replicate the data definition information of the
parent process in the child process. Use of any of the exec() library functions
deallocates the data definition information for the application process.

For the declaration just shown for the file parts.instock, you should write a JCL
DD statement similar to the following:
//PSTOCK DD PATH=/u/parts.instock,...

For more information on writing DD statements, you should refer to the job control
language (JCL) manual z/OS MVS JCL Reference.

To open the file by DD name under TSO/E, you must write an ALLOCATE command.
For the declaration of a file parts.instock, you should write a TSO/E ALLOCATE
command similar to the following:
ALLOCATE DDNAME(PSTOCK) PATH(/u/parts.instock)...

See z/OS TSO/E Command Reference for more information on TSO ALLOCATE.

fopen() and freopen() parameters

The following table lists the parameters that are available on the fopen() and
freopen() functions, tells you which ones are useful for z/OS UNIX file system I/O,
and lists the values that are valid for the applicable ones.
Table 21. Parameters for the fopen() and freopen() functions for z/OS UNIX file system I/O
Parameter Allowed? Applicable? Notes
recfm= Yes No z/OS UNIX file system I/O uses a
continuous stream of data as its file format.
lrecl= Yes No z/OS UNIX file system I/O uses a
continuous stream of data as its file format.
blksize= Yes No z/OS UNIX file system I/O uses a
continuous stream of data as its file format.
space= Yes No Not used for z/OS UNIX file system I/O.
type= Yes Yes May be omitted. If you do specify it,
type=record is the only valid value.
acc= Yes No Not used for z/OS UNIX file system I/O.
password= Yes No Not used for z/OS UNIX file system I/O.
asis Yes No Not used for z/OS UNIX file system I/O.
byteseek Yes No Not used for z/OS UNIX file system I/O.
noseek Yes No Not used for z/OS UNIX file system I/O.
OS Yes No Not used for z/OS UNIX file system I/O.
abend= Yes No Not used for z/OS UNIX file system I/O.

recfm=
Ignored for z/OS UNIX file system I/O.

Chapter 11. Performing z/OS UNIX file system I/O operations 127
 lrecl= and blksize=
Ignored for z/OS UNIX file system I/O, except that lrecl affects the value
returned in the __maxreclen field of fldata() as described below.
acc= Ignored for z/OS UNIX file system I/O.
password
Ignored for z/OS UNIX file system I/O.
space=
Ignored for z/OS UNIX file system I/O.
type= The only valid value for this parameter under the z/OS UNIX file system is
type=record. If you specify this, your file follows the z/OS UNIX file system
record I/O rules:
1. One record is defined to be the data up to the next new-line character.
2. When an fread() is done the data will be copied into the user buffer as
if an fgets(buf, size_item*num_items, stream) were issued. Data is
read into the user buffer up to the number of bytes specified on the
fread(), or until a new-line character or EOF is found. The new-line
character is not included.
3. When an fwrite() is done the data will be written from the user buffer
with a new-line character added by the RTL code. Data is written up to
the number of bytes specified on the fwrite(); the new-line is added by
the RTL and is not included in the return value from fwrite().
4. If you have specified an lrecl and type=record, fldata() of this stream
will return the lrecl you specified, in the __maxreclen field of the
__fileData return structure of stdio.h. If you specified type=record but
no lrecl, the __maxreclen field will contain 1024.
If type=record is not in effect, a call to fldata() of this stream will return
0 in the __maxreclen field of the __fileData return structure of stdio.h.
asis Ignored for z/OS UNIX file system I/O.
byteseek
Ignored for z/OS UNIX file system I/O.
noseek
Ignored for z/OS UNIX file system I/O.
OS Ignored for z/OS UNIX file system I/O.
abend=
Ignored for z/OS UNIX file system I/O.

Reading from z/OS UNIX file system files

You can use the following library functions to read in information from z/OS UNIX
file system files:
v fread()
v fread_unlocked()
v fgets()
v fgets_unlocked()
v gets()
v gets_unlocked()
v fgetc()
v fgetc_unlocked()
v getc()
v getc_unlocked()

128 z/OS V1R13.0 XL C/C++ Programming Guide

 v getchar()
v getchar_unlocked()
v scanf()
v scanf_unlocked()
v fscanf()
v fscanf_unlocked()
v read()
v pread()
v vscanf()
v vscanf_unlocked()
v vfscanf()
v vfscanf_unlocked()

fread() is the only interface allowed for reading record I/O files. See z/OS XL
C/C++ Run-Time Library Reference for more information on all of the above library
functions.

For z/OS UNIX low-level I/O, you can use the read() and readv() function. See
Low-level z/OS UNIX I/O on page 137.

Opening and reading from z/OS UNIX file system directory files
To open a z/OS UNIX file system directory, you can use the opendir() function.

You can use the following library functions to read from, and position within, z/OS
UNIX file system directories:
v readdir()
v seekdir()
v telldir()

To close a directory, use the closedir() function.

Writing to z/OS UNIX file system files

You can use the following library functions to write to z/OS UNIX file system files:
v fwrite()
v fwrite_unlocked()
v printf()
v printf_unlocked()
v fprintf()
v fprintf_unlocked()
v vprintf()
v vprintf_unlocked()
v vfprintf()
v vfprintf_unlocked()
v puts()
v puts_unlocked()
v fputs()
v fputs_unlocked()
v fputc()
v fputc_unlocked()
v putc()
v putc_unlocked()
v putchar()
v putchar_unlocked()
v write()

Chapter 11. Performing z/OS UNIX file system I/O operations 129
 v pwrite()

fwrite() is the only interface allowed for writing to record I/O files. See z/OS XL
C/C++ Run-Time Library Reference for more information on all of the above library
functions. For z/OS UNIX low-level I/O, you can use the write() and writev()
function.

Flushing records
You can use the library function fflush() to flush streams to the system. For more
information about fflush(), see z/OS XL C/C++ Run-Time Library Reference.

The action taken by the fflush() library function depends on the buffering mode
associated with the stream and the type of streams. If you call one z/OS XL C/C++
program from another z/OS XL C/C++ program by using the ANSI system()
function, all open streams are flushed before control is passed to the callee, and
again before control is returned to the caller. A call to the POSIX system() function
does not flush any streams.

For z/OS UNIX file system files, the fflush() function copies the data from the
run-time buffer to the file system. The fsync() function copies the data from the file
system buffer to the storage device.

Setting positions within files

You can use the following library functions to help you reposition within a regular
file:
v fseek()
v fseek_unlocked()
v fseeko()
v fseeko_unlocked()
v ftell()
v ftell_unlocked()
v ftello()
v ftello_unlocked()
v fgetpos()
v fgetpos_unlocked()
v fsetpos()
v fsetpos_unlocked()
v lseek()
v rewind()
v rewind_unlocked()

With large file support enabled for AMODE 31 C/C++ applications, you can use the
following library functions for 64-bit offsets:
v fseeko()
v fseeko_unlocked()
v ftello()
v ftello_unlocked()
v lseek()
For AMODE 64 C/C++ applications, large files are automatically supported in the
LP64 programming model. All of the above functions (both lists) can be used with
64-bit offsets.

130 z/OS V1R13.0 XL C/C++ Programming Guide

 See z/OS XL C/C++ Run-Time Library Reference for more information on these
library functions.

Closing files
You can use fclose(), freopen(), or close() to close a file. z/OS XL C/C++
automatically closes files on normal program termination, and attempts to do so
under abnormal program termination or abend. See z/OS XL C/C++ Run-Time
Library Reference for more information on these library functions. For z/OS UNIX
low-level I/O, you can use the close() function. When you use any exec() or
fork() function, files defined as marked to be closed are closed before control is
returned.

Deleting files
Use the unlink() or remove() z/OS XL C/C++ function to delete the following types
of z/OS UNIX file system files:
v Regular
v Character special
v FIFO
v Link files

Use the rmdir() z/OS XL C/C++ function to delete a z/OS UNIX file system
directory file. See z/OS XL C/C++ Run-Time Library Reference for more information
about these functions.

Pipe I/O
POSIX.1 pipes represent an I/O channel that processes can use to communicate
with other processes. Pipes are conceptually like z/OS UNIX file system files. One
process can write data into a pipe, and another process can read data from the
pipe.

z/OS UNIX XL C/C++ supports two types of POSIX.1-defined pipes: unnamed pipes
and named pipes (FIFO files).

An unnamed pipe is accessible only by the process that created the pipe and its
child processes. An unnamed pipe does not have to be opened before it can be
used. It is a temporary file that lasts only until the last file descriptor that references
it is closed. You can create an unnamed pipe by calling the pipe() function.

A named pipe can be used by independent processes and must be explicitly

opened and closed. Named pipes are also referred to as first-in, first-out (FIFO)
files, or FIFOs. You can create a named pipe by calling the mkfifo() function. If you
want to stream I/O after a pipe() function, call the fdopen() function to build a
stream on one of the file descriptors returned by pipe(). If you want to stream I/O
on a FIFO file, open the file with fdopen() together with one of fopen(), freopen(),
or open(). When the stream is built, you can then use Standard C I/O functions,
such as fgets() or printf(), to carry out input and output.

Using unnamed pipes

If your z/OS UNIX XL C/C++ application program forks processes that need to
communicate among themselves for work to be done, you can take advantage of
POSIX.1-defined unnamed pipes. If your application program's processes need to

Chapter 11. Performing z/OS UNIX file system I/O operations 131
 communicate with other processes that it did not fork, you should use the
POSIX.1-defined named pipe (FIFO special file) support. See Using named pipes
on page 133 for more information.

When you code the pipe() function to create a pipe, you pass a pointer to a
two-element integer array where pipe() puts the file descriptors it creates. One
descriptor is for the input end of the pipe, and the other is for the output end of the
pipe. You can code your application so that one process writes data to the input
end of the pipe and another process reads from the output end on a first-in-first-out
basis. You can also build a stream on the pipe by using fdopen(), and use buffered
I/O functions. The result is that you can communicate data between a parent
process and any of its child processes.

The opened pipe is assigned the two lowest-numbered file descriptors available.

z/OS UNIX provides no security checks for unnamed pipes, because such a pipe is
accessible only by the parent process that creates the pipe and any of the parent
process's descendent processes. When the parent process ends, an unnamed pipe
created by the process can still be used, if needed, by any existing descendant
process that has an open file descriptor for the pipe.

Consider the sample program (CCNGHF1) in Figure 19 on page 133. In this

example, where you open a pipe, do a write operation, and later do a read
operation from the pipe. For more information on the pipe() function and the file I/O
functions, see z/OS XL C/C++ Run-Time Library Reference.

132 z/OS V1R13.0 XL C/C++ Programming Guide

 /* this example shows how unnamed pipes may be used */

#include <unistd.h>
#include <stdio.h>
#include <errno.h>

int main() {
int ret_val;
int pfd[2];
char buff[32];
char string1[]="String for pipe I/O";

ret_val = pipe(pfd); /* Create pipe */

if (ret_val != 0) { /* Test for success */
printf("Unable to create a pipe; errno=%d\n",errno);

exit(1); /* Print error message and exit */

}
if (fork() == 0) {
/* child program */
close(pfd[0]); /* close the read end */
ret_val = write(pfd[1],string1,strlen(string1)); /*Write to pipe*/
if (ret_val != strlen(string1)) {
printf("Write did not return expected value\n");
exit(2); /* Print error message and exit */
}
}
else {
/* parent program */
close(pfd[1]); /* close the write end of pipe */
ret_val = read(pfd[0],buff,strlen(string1)); /* Read from pipe */
if (ret_val != strlen(string1)) {
printf("Read did not return expected value\n");
exit(3); /* Print error message and exit */
}
printf("parent read %s from the child program\n",buff);
}
exit(0);
}

Figure 19. Unnamed pipes example

Using named pipes

If the z/OS UNIX XL C/C++ application program you are developing requires its
active processes to communicate with other processes that are active but may not
be from the same program, code your application program to create a named pipe
(FIFO file). Named pipes allow transfer of data between processes in a FIFO
manner and synchronization of process execution. Use of a named pipe allows
processes to communicate even though they do not know what processes are on
the other end of the pipe. Named pipes differ from standard unnamed pipes,
created using the pipe() function, in that they involve the creation of a real file that
is available for I/O operations to properly authorized processes.

Within the application program, you create a named pipe by coding a mkfifo() or
mknod() function. You give the FIFO a name and an access mode when you create
it. If the access mode allows all users read and write access to the named pipe,
any process that knows its name can use it to send or receive data.

Chapter 11. Performing z/OS UNIX file system I/O operations 133
 Processes can use the open() function to access named pipes and then use the
regular I/O functions for files, such as read(), write(), and close(), when
manipulating named pipes. Buffered I/O functions can also be used to access and
manipulate named pipes. For more information on the mkfifo() and mknod()
functions and the file I/O functions, see z/OS XL C/C++ Run-Time Library
Reference.

Restriction: If fopen() is used to open named pipes in a multi-threaded

environment, a deadlock will occur. This deadlock is caused by a named pipe
waiting for the other end of the pipe to be opened, while still holding the fopen()
multi-thread mutex. To prevent this deadlock, use open() to open the named pipe,
instead of fopen().

z/OS UNIX does security checks on named pipes.

The following steps outline how to use a named pipe from z/OS UNIX XL C/C++
application programs:
1. Create a named pipe using the mkfifo() function. Only one of the processes
that use the named pipe needs to do this.
2. Access the named pipe using the appropriate I/O method.
3. Communicate through the pipe with another process using file I/O functions:
a. Write data to the named pipe.
b. Read data from the named pipe.
4. Close the named pipe.
5. If the process created the named pipe and the named pipe is no longer needed,
remove that named pipe using the unlink() function.

A process running the following simple example program creates a new named pipe
with the file pathname pointed to by the path value coded in the mkfifo() function.
The access mode of the new named pipe is initialized from the mode value coded in
the mkfifo() function. The file permission bits of the mode argument are modified
by the process file creation mask.

As an example, a process running the program code (CCNGHF2) in Figure 20 on

page 135 creates a child process and then creates a named pipe called fifo.test.
The child process then writes a data string to the pipe file. The parent process
reads from the pipe file and verifies that the data string it reads is the expected one.

Note: The two processes are related and have agreed to communicate through the
named pipe. They need not be related, however. Other authorized users can run
the same program and participate in (or interfere with) the process communication.

134 z/OS V1R13.0 XL C/C++ Programming Guide

/* this example shows how named pipes may be used */
#define _OPEN_SYS
#include <stdio.h>
#include <unistd.h>
#include <errno.h>
#include <fcntl.h>
#include <sys/wait.h>
/* *
* Sample use of mkfifo() *
* */

main()

{ /* start of program */

int flags, ret_value, c_status;

pid_t pid;
size_t n_elements;
char char_ptr[32];
char str[] = "string for fifo ";
char fifoname[] = "temp.fifo";
FILE *rd_stream,*wr_stream;

if ((mkfifo(fifoname,S_IRWXU)) != 0) {
printf("Unable to create a fifo; errno=%d\n",errno);
exit(1); /* Print error message and return */
}

if ((pid = fork()) < 0) {

perror("fork failed");
exit(2);
}

if (pid == (pid_t)0) { /* CHILD process */

/* issue fopen for write end of the fifo */
wr_stream = fopen(fifoname,"w");
if (wr_stream == (FILE *) NULL) {
printf("In child process\n");
printf("fopen returned a NULL, expected valid stream\n");
exit(100);
}

/* perform a write */
n_elements = fwrite(str,1,strlen(str),wr_stream);
if (n_elements != (size_t) strlen(str)) {
printf("Fwrite returned %d, expected %d\n",
(int)n_elements,strlen(str));
exit(101);
}
exit(0); /* return success to parent */
}

else { /* PARENT process */

/* issue fopen for read */

rd_stream = fopen(fifoname,"r");
if (rd_stream == (FILE *) NULL) {
printf("In parent process\n");
printf("fopen returned a NULL, expected valid pointer\n");
exit(2);
}

Figure 20. Named pipes example (Part 1 of 2)

Chapter 11. Performing z/OS UNIX file system I/O operations 135
 /* get current flag settings of file */
if ((flags = fcntl(fileno(rd_stream),F_GETFL)) == -1) {
printf("fcntl returned -1 for %s\n",fifoname);
exit(3);
}

/* clear O_NONBLOCK and reset file flags */

flags &= (O_NONBLOCK);
if ((fcntl(fileno(rd_stream),F_SETFL,flags)) == -1) {
printf("\nfcntl returned -1 for %s",fifoname);
exit(4);
}

/* try to read the string */

ret_value = fread(char_ptr,sizeof(char),strlen(str),rd_stream);
if (ret_value != strlen(str)) {
printf("\nFread did not read %d elements as expected ",
strlen(str));
printf("\nret_value is %d ",ret_value);
exit(6);
}

if (strncmp(char_ptr,str,strlen(str))) {
printf("\ncontents of char_ptr are %s ",
char_ptr);
printf("\ncontents of str are %s ",
str);
printf("\nThese should be equal");
exit(7);
}

ret_value = fclose(rd_stream);
if (ret_value != 0) {
printf("\nFclose failed for %s",fifoname);
printf("\nerrno is %d",errno);
exit(8);
}
ret_value = remove(fifoname);
if (ret_value != 0) {
printf("\nremove failed for %s",fifoname);
printf("\nerrno is %d",errno);
exit(9);
}

pid = wait(c_status);
if ((WIFEXITED(c_status) !=0) &&; (WEXITSTATUS(c_status) !=0)) {
printf("\nchild exited with code %d",WEXITSTATUS(c_status));
exit(10);
}
} /* end of else clause */
printf("About to issue exit(0), \
processing completed successfully\n");
exit(0);
}

Figure 20. Named pipes example (Part 2 of 2)

Character special file I/O

A named pipe (FIFO file) is a type of character special file. Therefore, it obeys the
I/O rules for character special files rather than the rules for regular files:
v It cannot be opened in read/write mode. A process must open a named pipe in
either write-only or read-only mode.

136 z/OS V1R13.0 XL C/C++ Programming Guide

 v It must be opened in read mode by a process before it can be opened in write
mode by another process. Otherwise, the file is blocked from use for I/O by
processes. Blocked processes can cause an application program to hang.
A single process intending to access a named pipe can use an open() function
with O_NONBLOCK to open the read end of the named pipe. It can then open the
named pipe in write mode.

Note: The fopen() function cannot be used to accomplish this.

Low-level z/OS UNIX I/O

Low-level z/OS UNIX I/O is the POSIX.1-defined I/O method. All input and output is
processed using the defined read(), readv(), write(), and writev() functions.

For application programmers used to a UNIX environment, z/OS UNIX behaves in

familiar and predictable ways. Standard UNIX programming practices for shared
resources, along with designing applications to respect locks put on files by multiple
threads running in a process, will ensure that data is handled predictably.

For a discussion of POSIX.1-defined low-level I/O and some of the practical

considerations to take into account when designing an application, see The
POSIX.1 Standard: A Programmer's Guide, by Fred Zlotnick (Redwood City, CA:
The Benjamin/Cummings Publishing Company, Inc., 1991).

Example of z/OS UNIX file system I/O functions

This section contains examples that demonstrate different uses of z/OS UNIX I/O
file system functions

Figure 21 is example code (CCNGHF3) that demonstrates the use of z/OS UNIX
stream input/output by writing streams to a file, reading the input lines, and
replacing a line.

/* this example uses HFS stream I/O */

#define _OPEN_SYS
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <unistd.h>
#include <fcntl.h>
#include <sys/types.h>
#undef _OPEN_SYS
FILE *stream;

char string1[] = "A line of text."; /* NOTE: There are actually 16 */

char string2[] = "Find this line."; /* characters in each line of */
char string3[] = "Another stream."; /* text. The 16th is a null */
char string4[16]; /* terminator on each string. */
long position, strpos; /* Since the null character */
int i, result, fd; /* is not being written to */
int rc; /* the file, 15 is used as */
/* the data stream length. */
ssize_t x;
char buffer[16];

Figure 21. Example of z/OS UNIX stream input and output functions (Part 1 of 3)

Chapter 11. Performing z/OS UNIX file system I/O operations 137
 int main(void)
{

/* Write continuous streams to file */

if ((stream = fopen("./myfile.data","wb"))==NULL) {
perror("Error opening file");
exit(0);
}

for(i=0; i<12;i++) {
int len1 = strlen(string1);
rc = fwrite(string1, 1, len1, stream);
if (rc != len1) {
perror("fwrite failed");
printf("i = %d\n", i);
exit(99);
}
}
rc = fwrite(string2,1,sizeof(string2)-1,stream);

if (rc != sizeof(string2)-1) {
perror("fwrite failed");
exit(99);
}

for(i=0;i<12;i++) {
rc = fwrite(string1,1,sizeof(string1)-1,stream);

if (rc != sizeof(string1)-1) {
perror("fwrite failed");
printf("i = %d\n", i);
exit(99);
}
}
fclose(stream);
/* Read data stream and search for location of string2. */
/* EOF is not set until an attempt is made to read past the */
/* end-of-file, thus the fread is at the end of the while loop */

stream = fopen("./myfile.data", "rb");

if ((position = ftell(stream)) == -1L)

perror("Error saving file position.");
rc = fread(string4, 1, sizeof(string2)-1, stream);

Figure 21. Example of z/OS UNIX stream input and output functions (Part 2 of 3)

138 z/OS V1R13.0 XL C/C++ Programming Guide

 while(!feof(stream)) {
if (rc != sizeof(string2)-1) {
perror("fread failed");
exit(99);
}

if (strstr(string4,string2) != NULL) /* If string2 is found */

strpos = position ; /* then save position. */

if ((position=ftell(stream)) == -1L)
perror("Error saving file position.");
rc = fread(string4, 1, sizeof(string2)-1, stream);
}

fclose(stream);
/* Replace line containing string2 with string3 */

fd = open("test.data",O_RDWR);

if (fd < 0){

perror("open failed\n");
}

x = write(fd,"a record",8);

if (x < 8){
perror("write failed\n");
}

rc = lseek(fd,0,SEEK_SET);
x = read(fd,buffer,8);

if (x < 8){
perror("read failed\n");
}
printf("data read is %.8s\n",buffer);

close(fd);
}

Figure 21. Example of z/OS UNIX stream input and output functions (Part 3 of 3)

To use 64-bit offset and file sizes, you must make the following changes in your
code:
1. Change any variables used for offsets in fseek() or ftell() that are int
or long to the off_t data type.
2. Define the _LARGE_FILES 1 feature test macro.
3. Replace fseek()/ftell() with fseeko()/ftello(). See z/OS XL C/C++
Run-Time Library Reference for descriptions of these functions.
4. Compile with the LANGLVL(LONGLONG) compiler option.
Notes:
1. These changes are compatible with your older files.
2. Large Files support (64bit offset and file sizes) is automatic in the LP64
programming model that is used in 64bit. The long data type is widened to
64bits. This enables fseek() and ftell() to work with the larger offsets with
no code change. The fseeko() and ftello() functions also work with 64bit
offsets since off_t is typedef'd as a long int.

Chapter 11. Performing z/OS UNIX file system I/O operations 139
 The example program (CCNGHF4) in Figure 22 on page 141 provides the same
function as CCNGHF3, but it uses 64-bit offsets. The changed lines are marked in a
bold font.

140 z/OS V1R13.0 XL C/C++ Programming Guide

/* this example uses HFS stream I/O and 64-bit offsets*/

#define _OPEN_SYS
#define _LARGE_FILES 1
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <unistd.h>
#include <fcntl.h>
#include <sys/types.h>
#undef _OPEN_SYS
FILE *stream;

char string1[] = "A line of text."; /* NOTE: There are actually 16 */

char string2[] = "Find this line."; /* characters in each line of */
char string3[] = "Another stream."; /* text. The 16th is a null */
char string4[16]; /* terminator on each string. */
off_t position,strpos; /* Since the null character */
int i, result, fd; /* is not being written to */
int rc; /* the file, 15 is used as */
/* the data stream length. */
ssize_t x;
char buffer[16];

int main(void)
{

/* Write continuous streams to file */

if ((stream = fopen("./myfile.data","wb"))==NULL) {
perror("Error opening file");
exit(0);
}

for(i=0; i<12;i++) {
int len1 = strlen(string1);
rc = fwrite(string1, 1, len1, stream);
if (rc != len1) {
perror("fwrite failed");
printf("i = %d\n", i);
exit(99);
}
}
rc = fwrite(string2,1,sizeof(string2)-1,stream);

if (rc != sizeof(string2)-1) {
perror("fwrite failed");
exit(99);
}

for(i=0;i<12;i++) {
rc = fwrite(string1,1,sizeof(string1)-1,stream);

if (rc != sizeof(string1)-1) {
perror("fwrite failed");
printf("i = %d\n", i);
exit(99);
}
}

Figure 22. Example of HFS stream input and output functions (Part 1 of 2)

Chapter 11. Performing z/OS UNIX file system I/O operations 141
 fclose(stream);
/* Read data stream and search for location of string2. */
/* EOF is not set until an attempt is made to read past the */
/* end-of-file, thus the fread is at the end of the while loop */

stream = fopen("./myfile.data", "rb");

if ((position=ftello(stream)) == -1LL)
perror("Error saving file position.");

rc = fread(string4, 1, sizeof(string2)-1, stream);

while(!feof(stream)) {
if (rc != sizeof(string2)-1) {
perror("fread failed");
exit(99);
}

if (strstr(string4,string2) != NULL) /* If string2 is found */

strpos = position ; /* then save position. */

if ((position=ftello(stream)) == -1LL)
perror("Error saving file position.");

rc = fread(string4, 1, sizeof(string2)-1, stream);

}

fclose(stream);
/* Replace line containing string2 with string3 */

fd = open("test.data",O_RDWR);

if (fd < 0){

perror("open failed\n");
}

x = write(fd,"a record",8);

if (x < 8){
perror("write failed\n");
}
strpos = lseek(fd,0LL,SEEK_SET); /* Note off_t is 64bits with _LARGE_FILES */
/* set and the off_t variable */
/* needs a 64bit constant of 0LL */
x = read(fd,buffer,8);

if (x < 8){
perror("read failed\n");
}
printf("data read is %.8s\n",buffer);

close(fd);
}

Figure 22. Example of HFS stream input and output functions (Part 2 of 2)

fldata() behavior
The format of the fldata() function is as follows:

142 z/OS V1R13.0 XL C/C++ Programming Guide

 int fldata(FILE *file, char *filename,
fldata_t
*info);

The fldata() function is used to retrieve information about an open stream. The
name of the file is returned in filename and other information is returned in the
fldata_t structure, shown in Figure 23. Values specific to this category of I/O are
shown in the comment beside the structure element. Additional notes pertaining to
this category of I/O follow the figure. For more information on the fldata() function,
refer to z/OS XL C/C++ Run-Time Library Reference.

struct __fileData {
unsigned int __recfmF : 1, /* always off */
__recfmV : 1, /* always off */
__recfmU : 1, /* always on */
__recfmS : 1, /* always off */
__recfmBlk : 1, /* always off */
__recfmASA : 1, /* always off */
__recfmM : 1, /* always off */
__dsorgPO : 1, /* N/A -- always off */
__dsorgPDSmem : 1, /* N/A -- always off */
__dsorgPDSdir : 1, /* N/A -- always off */
__dsorgPS : 1, /* N/A -- always off */
__dsorgConcat : 1, /* N/A -- always off */
__dsorgMem : 1, /* N/A -- always off */
__dsorgHiper : 1, /* N/A -- always off */
__dsorgTemp: 1, /* N/A -- always off */
__dsorgVSAM: 1, /* N/A -- always off */
__dsorgHFS : 1, /* always on */
__openmode : 2, /* one of: */
/* __BINARY */
/* __RECORD */
__modeflag : 4, /* combination of: */
/* __READ */
/* __WRITE */
/* __APPEND */
/* __UPDATE */
__dsorgPDSE: 1, /* N/A -- always off */
__reserve2 : 8; /* */
__device_t __device; /* __HFS */
unsigned long __blksize, /* 0 */
__maxreclen; /* */
unsigned short __vsamtype; /* N/A */
unsigned long __vsamkeylen; /* N/A */
unsigned long __vsamRKP; /* N/A */
char * __dsname; /* */
unsigned int __reserve4; /* */
};
typedef struct __fileData fldata_t;

Figure 23. fldata() structure

Notes:
1. The filename is the same as specified on the fopen() or freopen() function call.
2. The __maxreclen value is 0 for regular I/O (binary). For record I/O the value is
lrecl or the default of 1024 when lrecl is not specified.
3. The __dsname value is the real POSIX pathname.

Chapter 11. Performing z/OS UNIX file system I/O operations 143
File tagging and conversion
In general, the file system knows the contents of a file only as a set of bytes.
Applications which create and process bytes in a file know whether these bytes
represent binary data, text (character) data, or a mixture of both. File tags are file
metadata fields which describe the contents of a file. Enhanced ASCII includes the
following file tag fields:
txtflag A flag indicating if a file consists solely of character data encoded
by a single coded character set ID (CCSID).
file ccsid A 16 bit field specifying the CCSID of characters in the file.

Applications can explicitly tag files using new open() or fcntl() options, or
applications can allow the logical file system (LFS) to tag new files on first write,
fopen(). A new environment variable, _BPXK_CCSID, is used to assign a program
CCSID to an application, which LFS will use to tag new files on first write. LFS also
uses the program CCSID derived from _BPXK_CCSID to set up auto-conversion of
pure text datastreams. LFS attempts to set up auto-conversion when:
v Auto-conversion is enabled for an application by the _BPXK_AUTOCVT environment
variable
v The file txtflag flag is set indicating a pure text file
v The file and program CCSIDs do not match.

Automatic file conversion and file tagging include the following facilities:
v _OPEN_SYS_FILE_EXT feature test macro. For more information, see z/OS XL
C/C++ Run-Time Library Reference .
v _BPXK_AUTOCVT and _BPXK_CCSIDS environment variables. For more information,
see Chapter 32, Using environment variables, on page 467.
v z/OS Language Environment FILETAG run-time option. For more information, see
z/OS Language Environment Programming Reference.
v __chattr() and __fchattr() functions; F_SETTAG and F_CONTROL_CVT
arguments for the fcntl() function; options for the fopen(), popen(), stat(),
fstat(), and lstat() functions. For more information, see z/OS XL C/C++
Run-Time Library Reference.

Access control lists (ACLs)

Access control lists (ACLs) enable you to control access to files and directories by
individual user (UID) and group (GID). ACLs are used in conjunction with
permission bits. You can create, modify, and delete ACLs using the following
functions:
v acl_create_entry()
v acl_delete_entry()
v acl_delete_fd()
v acl_delete_file()
v acl_first_entry()
v acl_free()
v acl_from_text()
v acl_get_entry()
v acl_get_fd()
v acl_get_file()

144 z/OS V1R13.0 XL C/C++ Programming Guide

v acl_init()
v acl_set_fd()
v acl_set_file()
v acl_sort(
v acl_to_text()
v acl_update_entry()
v acl_valid()
For descriptions of these functions see z/OS XL C/C++ Run-Time Library
Reference. For more information on using ACLs to protect file system resources
see z/OS UNIX System Services Planning and z/OS Security Server RACF Security
Administrator's Guide.

Chapter 11. Performing z/OS UNIX file system I/O operations 145
146 z/OS V1R13.0 XL C/C++ Programming Guide
Chapter 12. Performing VSAM I/O operations
This chapter outlines the use of Virtual Storage Access Method (VSAM) data sets in
z/OS XL C/C++. Three I/O processing modes for VSAM data sets are available in
z/OS XL C/C++:
v Record
v Text Stream
v Binary Stream

Because VSAM is a record-based access method, record mode is the logical

processing mode and is specified by coding the type=record keyword parameter on
the fopen() function call. z/OS XL C/C++ also provides limited support for VSAM
text streams and binary streams. Because of the record-based nature of VSAM, this
chapter is organized differently from the other chapters in this section. The focus of
this chapter is on record I/O, and only those aspects of text and binary I/O that are
specific to VSAM are also discussed.

For more information about the facilities of VSAM, see the list of DFSMS on page
1027 publications.

See Chapter 8, z/OS XL C Support for the double-byte character set, on page 51
for information about using wide-character I/O with z/OS XL C/C++.
Notes:
1. This chapter describes C I/O as it can be used within C++ programs.
2. The C++ I/O stream libraries cannot be used for VSAM I/O because these do
not support the record processing mode (where type=record is specified).
3. Starting in z/OS V1R10, the C/C++ run-time library provides support for VSAM
data sets in the extended addressing space on extended address volumes
(EAVs).

VSAM types (data set organization)

There are three types of VSAM data sets supported by z/OS XL C/C++, all of which
are held on direct-access storage devices.
v Key-Sequenced Data Set (KSDS) is used when a record is accessed through a
key field within the record (for example, an employee directory file where the
employee number can be used to access the record). KSDS also supports
sequential access. Each record in a KSDS must have a unique key value.
v Entry-Sequenced Data Set (ESDS) is used for data that is primarily accessed in
the order it was created (or the reverse order). It supports direct access by
Relative Byte Address (RBA), and sequential access.
v Relative Record Data Set (RRDS) is used for data in which each item has a
particular number, and the relevant record is accessed by that number (for
example, a telephone system with a record associated with each number). It
supports direct access by Relative Record Number (RRN), and sequential
access.

In addition to the primary VSAM access described above, for KSDS and ESDS,
there is also direct access by one or more additional key fields within each record.
These additional keys can be unique or non-unique; they are called an alternate
index (AIX).

Copyright IBM Corp. 1996, 2012 147

 Notes:
1. VSAM Linear Data Sets are not supported in z/OS XL C/C++ I/O.
2. z/OS XL C/C++ supports extended addressable KSDS, ESDS, and RRDS data
sets. Extended addressable KSDS data sets can be accessed through an
alternate index, but extended addressable ESDS data sets cannot.

Access method services

Access Method Services are generally known by the name IDCAMS on MVS. For
more information, see z/OS DFSMS Access Method Services for Catalogs.

Before a VSAM data set is used for the first time, its structure is defined to the
system by the Access Method Services DEFINE CLUSTER command. This command
defines the type of VSAM data set, its structure, and the space it requires.

Before a VSAM alternate index is used for the first time, its structure is defined to
the system by the Access Method Services DEFINE ALTERNATEINDEX command. To
enable access to the base cluster records through the alternate index, use the
DEFINE PATH command. Finally, to build the alternate index, use the BLDINDEX
command.

When you have built the alternate index, you call fopen() and specify the PATH in
order to access the base cluster through the alternate index. Do not use fopen() to
access the alternate index itself.

Note: You cannot use the BLDINDEX command on an empty base cluster.

Choosing VSAM data set types

When you plan your program, you must first decide the type of data set to use.
Figure 24 on page 149 shows you the possibilities available with the types of VSAM
data sets.

148 z/OS V1R13.0 XL C/C++ Programming Guide

The diagrams show how the information contained in the family tree below could be held in VSAM data sets of different types.
ANDREW M SMITH &
VALERIE SUZIE ANN MORGAN (1967)

FRED (1969) ANDY (1970) SUZAN (1972) JANE (1975)

Key-Sequenced Data Set

Alternate Indexes
By Birthdate (unique)
Data component
Prime 69
ANDY 70 M
Index 70
empty space
ANDY 72
FRED 69 M
FRED 75
empty space
JANE By sex (non-unique)
JANE 75 F
SUZAN
empty space
F
SUZAN 72 F
M

Entry-Sequenced Data Set

Relative byte addresses Alternate Indexes

can be accessed and Alphabetically by name
used as keys Data component (unique)

FRED 69 M
ANDY
ANDY 70 M FRED
SUZAN 72 F JANE
JANE 75 F SUZAN
By sex (non-unique)

F
M

Relative Record Data Set

Relative record numbers Data component No Alternate Indexes

can be accessed and Slot 1 FRED 69 M
used as keys
2 ANDY 70 M
3 empty space for 71
4 SUZAN 72 F
5 empty space for 73

6 empty space for 74

7 JANE 75 F
Each slot corresponds to a year 8 empty space for 76

Figure 24. Types and advantages of VSAM data sets

When choosing the VSAM data set type, you should base your choice on the most
common sequence in which you require data. You should follow a procedure similar
to the one suggested below to help ensure a combination of data sets and indexes
that provide the function you require.

Chapter 12. Performing VSAM I/O operations 149

 1. Determine the type of data and its primary access.
v sequentially favors ESDS
v by key favors KSDS
v by number favors RRDS
2. Determine whether you require access through an alternate index path. These
are only supported on KSDS and ESDS. If you do, determine whether the
alternate index is to have unique or nonunique keys. You should keep in mind
that making an assumption that all future records will have unique keys may not
be practical, and an attempt to insert a record with a nonunique key in an index
that has been created for unique keys causes an error.
3. When you have determined the data sets and paths that you require, ensure
that the operations you have in mind are supported.

Keys, RBAs and RRNs

All VSAM data sets have keys associated with their records. For KSDS, KSDS AIX,
and ESDS AIX, the key is a defined field within the logical record. For ESDS, the
key is the relative byte address (RBA) of the record. For RRDS, the key is a relative
record number (RRN).

Keys for indexed VSAM data sets

For KSDS, KSDS AIX, and ESDS AIX, keys are part of the logical records recorded
on the data set. For KSDS, the length and location of the keys are defined by the
DEFINE CLUSTER command of Access Method Services. For KSDS AIX and ESDS
AIX, the keys are defined by the DEFINE ALTERNATEINDEX command.

Relative byte addresses

Relative byte addresses (RBAs) enable you to access ESDS files directly. The
RBAs are either 4 or 8 byte fields, depending on the usage, and their values are
computed by VSAM. The 4 byte RBA can only be used when accessing within the
first 4GB of a VSAM data set. The 8 byte RBA can be used to access beyond 4GB
in an extended addressable VSAM data set.
Notes:
1. KSDS can also use RBAs. However, because the RBA of a KSDS record can
change if an insert, delete or update operation is performed elsewhere in the
file, it is not recommended.
2. You can call flocate() with RBA values in an RRDS cluster, but flocate() with
RBA values does not work across control intervals. Therefore, using RBAs with
RRDS clusters is not recommended. The RRDS access method does not
support RBAs. z/OS XL C/C++ supports the use of RBAs in an RRDS cluster by
translating the RBA value to an RRN. It does this by dividing the RBA value by
the LRECL.
3. Alternate indexes do not allow positioning by RBA.

The RBA value is stored in the C structure __amrc, which is defined in the C
<stdio.h> header file. The __amrc->__RBA field is defined as an unsigned int, and
therefore will contain only a 4-byte RBA value. The __amrc->__XRBA field is 8 bytes
(unsigned long long in AMODE 31 applications, and unsigned long in AMODE 64
applications), and therefore can hold the RBA for all locations within an extended
addressable VSAM data set.

You can access the field __amrc->__RBA, as shown in< xref refid="gvs1">. This
example code (CCNGVS1) can be converted to use __amrc->__XRBA with just a few
modifications. For more information about the __amrc structure, refer to Chapter 18,

150 z/OS V1R13.0 XL C/C++ Programming Guide

 Debugging I/O programs, on page 221.

/* this example shows how to access the __amrc->__RBA field */

/* it assumes that an ESDS has already been defined, and has been */
/* assigned the ddname ESDSCLUS */

#include <stdio.h>
#include <stdlib.h>

main() {
FILE *ESDSfile;
unsigned int myRBA;
char recbuff[100]="This is record one.";
int w_retcd;
int l_retcd;
int r_retcd;

printf("calling fopen(\"dd:esdsclus\",\"rb+,type=record\");\n");
ESDSfile = fopen("dd:esdsclus", "rb+,type=record");
printf("fopen() returned 0X%.8x\n",ESDSfile);
if (ESDSfile==NULL) exit;

w_retcd = fwrite(recbuff, 1, sizeof(recbuff), ESDSfile);

printf("fwrite() returned %d\n",w_retcd);
if (w_retcd != sizeof(recbuff)) exit;
myRBA = __amrc->__RBA;

l_retcd = flocate(ESDSfile, &myRBA, sizeof(myRBA), __RBA_EQ);

printf("flocate() returned %d\n",l_retcd);
if (l_retcd !=0) exit;

r_retcd = fread(recbuff, 1, sizeof(recbuff), ESDSfile);

printf("fread() returned %d\n",r_retcd);
if (l_retcd !=0) exit;

return(0);
}

Figure 25. VSAM example

Relative record numbers

Records in an RRDS are identified by a relative record number that starts at 1 and
is incremented by 1 for each succeeding record position. Only RRDS files support
accessing a record by its relative record number.

Summary of VSAM I/O operations

Table 22 summarizes VSAM data set characteristics and the allowable I/O
operations on them.
Table 22. Summary of VSAM data set characteristics and allowable I/O operations
Characteristic or I/O KSDS ESDS RRDS
Operation
Record Length Variable. Length can be Variable. Length cannot be Fixed.
changed by update. changed by update.
Alternate index Allows access using unique Allows access using unique Not supported by VSAM.
Note: z/OS XL C/C++ does or non-unique keys. or non-unique keys.
not support extended
addressable ESDS alternate
indexes.

Chapter 12. Performing VSAM I/O operations 151

Table 22. Summary of VSAM data set characteristics and allowable I/O operations (continued)
Characteristic or I/O KSDS ESDS RRDS
Operation
Record Read (Sequential) The order is determined by By entry sequence. Reads By relative record number.
the VSAM key proceed in key sequence for
the key of reference.
Record Write (Direct) Position determined by the Record written at the end of By relative record number.
value in the field designated the file.
as the key.
Positioning for Record Read By key or by RBA value. By RBA value. Alternate By relative record number.
Positioning by RBA value is index allows use by key.
not recommended because
changes to the file change
the RBA.
Delete (Record) If not already in correct Not supported by VSAM. If not already in correct
position, reposition the file position, position the file
pointer; read the record pointer; read the record
using fread(); delete the using fread(); delete the
record using fdelrec(). record using fdelrec().
fread() must immediately fread() must immediately
precede fdelrec(). precede fdelrec().
Update (Record) If not already in correct If not already in correct If not already in correct
position, reposition the file position, reposition the file position, reposition the file
pointer; read the record pointer; read the record pointer; read the record
using fread(); update the using fread(); update the using fread(); update the
record using fupdate(). record using fupdate(). record using fupdate().
fread() must immediately fread() must immediately fread() must immediately
precede fupdate(). precede fupdate(). precede fupdate().
Empty the file Define the file as reusable Define the file as reusable Define the file as reusable
using the DEFINE using the DEFINE using the DEFINE
CLUSTER command, and CLUSTER command, and CLUSTER command, and
then open the data set in then open the data set in then open the data set in
write ("wb,type=record" or write ("wb,type=record" or write ("wb,type=record" or
"wb+,type=record") mode. "wb+,type=record") mode. "wb+,type=record") mode.
Not supported for alternate Not supported for alternate
indexes. indexes.
Stream Read Supported by z/OS XL Supported by z/OS XL Supported by z/OS XL
C/C++. C/C++. C/C++.
Stream Write/Update Not supported by z/OS XL Supported by z/OS XL Supported by z/OS XL
C/C++. C/C++. C/C++.
Stream Repositioning Supported by z/OS XL Supported by z/OS XL Supported by z/OS XL
C/C++. C/C++. C/C++.

Opening VSAM data sets

To open a VSAM data set, use the Standard C library functions fopen() and
freopen() just as you would for opening non-VSAM data sets. The fopen() and
freopen() functions are described in z/OS XL C/C++ Run-Time Library Reference.

This section describes considerations for using fopen() and freopen() with VSAM
files. Remember that a VSAM file must exist and be defined as a VSAM cluster
before you call fopen().

152 z/OS V1R13.0 XL C/C++ Programming Guide

Using fopen() or freopen()
This section covers using file names for MVS data sets, specifying fopen() and
freopen() keywords, and buffering.

File names for MVS data sets: Using a data set name
The following diagram shows the syntax for the filename argument on your fopen()
or freopen() call:

  qualifier 
// ' '

The following is a sample construct:

qualifier1.qualifier2

' Single quotation marks indicate that you are passing a fully-qualified data set
name, that is, one which includes the high-level qualifier. If you pass a data set
name without single quotation marks, the z/OS XL C/C++ compiler prefixes the
high-level qualifier (usually the user ID) to the name. See Chapter 10,
Performing OS I/O operations, on page 81 for information on fully qualified
data set names.
// Specifying these slashes indicates that the file names refer to MVS data sets.
qualifier
Each qualifier is a 1- to 8-character name. These characters may be
alphanumeric, national ($, #, @), the hyphen, or the character \xC0. The first
character should be either alphabetic or national. Do not use hyphens in names
for RACF-protected data sets.
You can join qualifiers with periods. The maximum length of a data set name is
generally 44 characters, including periods.

To open a data set by its name, you can code something like the following in your
C or C++ program:
infile=fopen("VSAM.CLUSTER1", "ab+, type=record");

File names for MVS data sets: Using a DDname

To access a cluster or path by ddname, you can write the required DD statement
and call fopen() as shown in the following example.

If your data set is VSAM.CLUSTER1, your C or C++ program refers to this data set by
the ddname CFILE, and you want exclusive control of the data set for update, you
can write the DD statement:
//CFILE DD DSNAME=VSAM.CLUSTER1,DISP=OLD

and code the following in your C or C++ source program:

#include <stdio.h>

FILE *infile;

Chapter 12. Performing VSAM I/O operations 153

 main()
{
. infile=fopen("DD:CFILE", "ab+, type=record");
.
.
}

To share your data set, use DISP=SHR on the DD statement. DISP=SHR is the default
for fopen() calls that use a data set name and specify any of the r,rb, rb+, and
r+b open modes.

Note: z/OS XL C/C++ does not check the value of shareoptions at fopen() time,
and does not provide support for read-integrity and write-integrity, as required to
share files under shareoptions 3 and 4.

For more information on shareoptions, see the information on DEFINE CLUSTER in

the books listed in DFSMS on page 1027.

Specifying fopen() and freopen() keywords

The mode argument is a character string specifying the type of access requested
for the file. The mode argument contains one positional parameter (access mode)
followed by keyword parameters. A description of these parameters, along with an
explanation of how they apply to VSAM data sets is given the following sections.

Specifying access mode: The access mode is specified by the positional

parameter of the fopen() function call. The possible record I/O and binary modes
you can specify are:
rb Open for reading. If the file is empty, fopen() fails.
wb Open for writing. If the cluster is defined as reusable, the existing contents
of the cluster are destroyed. If the cluster is defined as not reusable
(clusters with paths are, by definition, not reusable), fopen() fails. However,
if the cluster has been defined but not loaded, this mode can be used to do
the initial load of both reusable and non reusable clusters.

Note: If a "key out of sequence" condition is encountered, the data set will
automatically be reopened with a mode string "ab+" and will no longer be in
create mode.
ab Open for writing.
rb+ or r+b
Open for reading, writing, and/or updating.
wb+ or w+b
Open for reading, writing, and/or updating. If the cluster is defined as
reusable, the existing contents of the cluster are destroyed. If the cluster is
defined as not reusable (clusters with paths are, by definition, not reusable),
the fopen() fails. However, if the cluster has been defined but not loaded,
this mode can be used to do the initial load of both reusable and non
reusable clusters.
ab+ or a+b
Open for reading, writing, and/or updating.

For text files, you can specify the following modes: r, w, a, r+, w+, and a+.

Note: For KSDS, KSDS AIX and ESDS AIX in text and binary I/O, the only valid
modes are r and rb, respectively.

154 z/OS V1R13.0 XL C/C++ Programming Guide

fopen() and freopen() keywords
The following table lists the keywords that are available on the fopen() and
freopen() functions, tells you which ones are useful for VSAM I/O, and lists the
values that are valid for the applicable ones.
Table 23. Keywords for the fopen() and freopen() functions for VSAM data sets
Keyword Allowed? Applicable? Notes
recfm= Yes No Ignored.
lrecl= Yes No Ignored.
blksize= Yes No Ignored.
space= Yes No Ignored.
type= Yes Yes May be omitted. If you do specify it,
type=record is the only valid value.
acc= Yes Yes Specifies the access direction for VSAM data
sets. Valid values are BWD and FWD.
password= Yes Yes Specifies the password for a VSAM data set.
asis Yes No Enables the use of mixed-case file names. Not
supported for VSAM.
byteseek Yes Yes Used for binary stream files to specify that the
seeking functions should use relative byte
offsets instead of encoded offsets. This is the
default setting.
noseek Yes No Ignored.
OS Yes No Ignored.
rls= Yes Yes Indicates the VSAM RLS/TVS access mode in
which a VSAM file is to be opened.

Keyword descriptions
recfm=
Any values passed into fopen() are ignored.
lrecl= and blksize=
These keywords are set to the maximum record size of the cluster as
initialized in the cluster definition. Any values passed into fopen() are
ignored.
space=
This keyword is not supported under VSAM.
type=
If you use the type= keyword, the only valid value for VSAM data sets is
type=record. This opens a file for record I/O.
acc= For VSAM files opened with the keyword type=record, you can specify the
direction by using the acc=access_type keyword on the fopen() function
call. For text and binary files, the access direction is always forward.
Attempts to open a VSAM data set with acc=BWD for either binary or text
stream I/O will fail. The access_type can be one of the following:
FWD The acc=FWD keyword specifies that the file be processed in a
forward direction. When the file is opened, it will be positioned at
the beginning of the first physical record, and any subsequent read
operations sets the file position indicator to the beginning of the
next record. The default value for the access keyword is acc=FWD.

Chapter 12. Performing VSAM I/O operations 155

 BWD The acc=BWD keyword specifies that the file be processed in a
backward direction. When the file is opened, it is positioned at the
beginning of the last physical record and any subsequent read
operation sets the file position indicator to the beginning of the
preceding record.
You can change the direction of sequential processing (from forward to
backward or from backward to forward) by using the flocate() library
function. For more information about flocate(), see Repositioning within
record I/O files on page 161.

Note: When opening paths, records with duplicate alternate index keys are
processed in order of arrival time (oldest to newest) regardless of the
current processing direction.
password=
VSAM facilities provide password protection for your data sets. You access
a data set that has password protection by specifying the password on the
password keyword parameter of the fopen() function call; the password
resides in the VSAM catalog entry for the named file. There can be more
than one password in the VSAM catalog entry; data sets can have different
passwords for different levels of authorization such as reading, writing,
updating, inserting, or deleting. For a complete description of password
protection on VSAM files, see the list of publications given on DFSMS on
page 1027.
The password keyword has the following form, where x is a 1- to
8-character password, and n is the exact number of characters in the
password. The password can contain special characters such as blanks
and commas.
password=nx
If a required password is not supplied, or if an incorrect password is given,
fopen() fails.
asis This keyword is not supported for VSAM.
byteseek
When you specify this keyword and open a file in binary stream mode,
fseek() and ftell() use relative byte offsets from the beginning of the file.
This is the default setting.
noseek
This keyword is ignored for VSAM data sets.
OS This keyword is ignored for VSAM data sets.
rls= Indicates the VSAM RLS/TVS access mode in which a VSAM file is to be
opened. This keyword is ignored for non-VSAM files. The following values
are valid:
v nri No Read Integrity
v cr Consistent Read
v cre Consistent Read Explicit

Note: When the RLS keyword is specified, DISP is changed to default to

SHR when dynamic allocation of the data set is performed. In the rare case
when a batch job must use RLS without sharing the data set with other
tasks, DISP should be OLD. To set DISP to OLD, the application must
specify DISP=OLD in the DD statement and start the application using JCL.
You cannot specify DISP in the fopen() mode argument.
156 z/OS V1R13.0 XL C/C++ Programming Guide
Buffering
Full buffering is the default. You can specify line buffering, but z/OS XL C/C++
treats line buffering as full buffering for VSAM data sets. Unbuffered I/O is not
supported under VSAM; if you specify it, your setvbuf() call fails.

To find out how to optimize VSAM performance by controlling the number of VSAM
buffers used for your data set, refer to z/OS DFSMS Access Method Services for
Catalogs.

Record I/O in VSAM

This section describes how to use record I/O in VSAM. The following topics are
covered:
v RRDS Record Structure
v RRDS Record Structure
v Reading Record I/O Files
v Writing to Record I/O Files
v Updating Record I/O Files
v Deleting Records
v Repositioning within Record I/O Files
v Flushing Buffers
v Summary of VSAM Record I/O Operations
v Reading from Text and Binary I/O Files
v Writing to and Updating Text and Binary I/O Files
v Deleting Records in Text and Binary I/O Files
v Repositioning within Text and Binary I/O Files
v Flushing Buffers
v Summary of VSAM Text I/O Operations
v Summary of VSAM Binary I/O Operations

RRDS record structure

For RRDS files opened in record mode, z/OS XL C/C++ defines the following key
structure in the C header file <stdio.h>:

typedef struct {
#ifndef _LP64
unsigned int __fill, /* version: either 0 or 1 */
__recnum; /* the key, starting at 1 */
#else
unsigned long __fill, /* version: either 0 or 1 */
__recnum; /* the key, starting at 1 */
#endif /* not _LP64 */
} __rrds_key_type;

In your source program, you can define an RRDS record structure as either:

Chapter 12. Performing VSAM I/O operations 157

 struct {
__rrds_key_type rrds_key; /* __fill value always 0 */
char data[MY_REC_SIZE];
} rrds_rec_0;

or:

struct {
__rrds_key_type rrds_key; /* __fill value always 1 */
char *data;
} rrds_rec_1;

The z/OS XL C/C++ library recognizes which type of record structures you have
used by the value of rrds_key.__fill. Zero indicates that the data is contiguous
with rrds_key and 1 indicates that a pointer to the data follows rrds_key.

Reading record I/O files

To read from a VSAM data set opened with type=record, use the Standard C
fread() library function. If you set the size argument to 1 and the count argument
to the maximum record size, fread() returns the number of bytes read successfully.
For more information on fread(), see z/OS XL C/C++ Run-Time Library Reference.

fread() reads one record from the system from the current file position. Thus, if
you want to read a certain record, you can call flocate() to position the file pointer
to point to it; the subsequent call to fread() reads in that record.

If you use an fread() call to request more bytes than the record about to be read
contains, fread() reads the entire record and returns the number of bytes read. If
you use fread() to request fewer bytes than the record about to read contains,
fread() reads the number of bytes that you specified and returns your request.

z/OS XL C/C++ VSAM Record I/O does not allow a read operation to immediately
follow a write operation without an intervening reposition. z/OS XL C/C++ treats the
following as read operations:
v Calls to read functions that request 0 bytes
v Read requests that fail because of a system error
v Calls to the ungetc() function

Calling fread() several times in succession, with no other operations on this file in
between, reads several records in sequence (sequential processing), which can be
forward or backward, depending on the access direction, as described in the
following.
v KSDS, KSDS AIX and ESDS AIX
The records are retrieved according to the sequence of the key of reference, or
in reverse key sequence.

Note: Records with duplicate alternate index keys are processed in order of
arrival time (oldest to newest) regardless of the current processing direction
v ESDS
The records are retrieved according to the sequence they were written to the file
(entry sequence), or in reverse entry sequence.

158 z/OS V1R13.0 XL C/C++ Programming Guide

 v RRDS
The records are retrieved according to relative record number sequence or
reverse relative record number sequence.
When records are being read, RRNs without an associated record are ignored.
For example, if a file has relative records of 1, 2, and 5, the nonexistent records
3 and 4 are ignored.
By default, in record mode, fread() must be called with a pointer to an RRDS
record structure. The field __rrds_key_type.__fill must be set to either 0 or 1
indicating the type of the structure, and the count argument must include the
length of the __rrds_key_type. fread() returns the RRN number in the __recnum
field, and includes the length of the __rrds_key_type in the return value. You can
override these operations by setting the _EDC_RRDS_HIDE_KEY environment
variable to Y. Once this variable is set, fread() is called with a data buffer and
not an RRDS data structure. The return value of fread() is now only the length
of the data read. In this case, fread() cannot return the RRN. For information on
setting environment variables, see Chapter 32, Using environment variables, on
page 467.

Writing to record I/O files

To write new records to a VSAM data set opened with type=record, use the
Standard C fwrite() library function. If you set size to 1 and count to the desired
record size, fwrite() returns the number of bytes written successfully. For more
information on fwrite() and the type=record parameter, see z/OS XL C/C++
Run-Time Library Reference.

In general, C I/O does not allow a write operation to follow a read operation without
an intervening reposition or fflush(). z/OS XL C/C++ counts a call to a write
function writing 0 bytes or a write request that fails because of a system error as a
write operation. However, z/OS XL C/C++ VSAM record I/O allows a write to directly
follow a read. This feature has been provided for compatibility with earlier releases.

The process of writing to a data set for the first time is known as initial loading.
Using the fwrite() function, you can write to a new VSAM file in initial load mode
just as you would to a file not in initial load mode. Writing to a KSDS PATH or an
ESDS PATH in initial load mode is not supported.

If your fwrite() call does not try to write more bytes than the maximum record
size, fwrite() writes a record of the length you asked for and returns your request.
If your fwrite() call asks for more than the maximum record size, fwrite() writes
the maximum record size, sets errno, and returns the maximum record size. In
either case, the next call to fwrite() writes to the following record.

Note: If an fwrite() fails, you must reposition the file before you try to read or
write again.
v KSDS, KSDS AIX
Records are written to the cluster according to the value stored in the field
designated as the prime key.
You can load a KSDS in any key order but it is most efficient to perform the
fwrite() operations in key sequence.
v ESDS, ESDS AIX
Records are written to the end of the file.
v RRDS

Chapter 12. Performing VSAM I/O operations 159

 Records are written according to the value stored in the relative record number
field.
fwrite() is called with the RRDS record structure.
By default, in record mode, fwrite() and fupdate() must be called with a pointer
to an RRDS record structure. The __rrds_key_type fields __fill and __recnum
must be set. __fill is set to 0 or 1 to indicate the type of the structure. The
__recnum field specifies the RRN to write, and is required for fwrite() but not
fupdate(). The count argument must include the length of the __rrds_key_type.
fwrite() and fupdate() include the length of the __rrds_key_type in the return
value.

Updating record I/O files

The fupdate() function, a z/OS XL C/C++ extension to the SAA C library, is used to
update records in a VSAM file. For more information on this function, see z/OS XL
C/C++ Run-Time Library Reference.
v KSDS, ESDS, and RRDS
To update a record in a VSAM file, you must perform the following operations:
1. Open the VSAM file in update mode (rb+/r+b, wb+/w+b, or ab+/a+b specified
as the required positional parameter of the fopen() function call and
type=record).
2. If the file is not already positioned at the record you want to update,
reposition to that record.
3. Read in the record using fread().
Once the record you want to update has been read in, you must ensure that
no reading, writing, or repositioning operations are performed before
fupdate().
4. Make the necessary changes to the copy of the record in your buffer area.
5. Update the record from your local buffer area using the fupdate() function.
If an fupdate() fails, you must reposition using flocate() before trying to
read or write.
Notes:
1. If a file is opened in update mode, a read operation can result in the locking
of control intervals, depending on shareoptions specification of the VSAM
file. If after reading a record, you decide not to update it, you may need to
unlock a control interval by performing a file positioning operation to the same
record, such as an flocate() using the same key.
2. If fupdate() wrote out a record the file position is the start of the next record.
If the fupdate() call did not write out a record, the file position remains the
same.
v KSDS and KSDS PATH
You can change the length of the record being updated. If your request does not
exceed the maximum record size of the file, fupdate() writes a record of the
length requested and returns the request. If your request exceeds the maximum
record size of the file, fupdate() writes a record that is the maximum record size,
sets errno, and returns the maximum record size.
You cannot change the prime key field of the record, and in KSDS AIX, you
cannot change the key of reference of the record.
v ESDS
You cannot change the length of the record being updated. If the size of the
record being updated is less than the current record size, fupdate() updates the

160 z/OS V1R13.0 XL C/C++ Programming Guide

 amount you specify and does not alter the data remaining in the record. If your
request exceeds the length of the record that was read, fupdate() writes a
record that is the length of the record that was read, sets errno, and returns the
length of the record that was read.
v ESDS PATH
You cannot change the length of the record being updated or the key of
reference of the record. If the size of the record being updated is less than the
current record size, fupdate() updates the amount you specify and does not
alter the data remaining in the record. If your request exceeds the length of the
record that was read, fupdate() writes a record that is the length of the record
that was read, sets errno, and returns the length of the record that was read.
v RRDS
RRDS files have fixed record length. If you update the record with less than the
record size, only those characters specified are updated, and the remaining data
is not altered. If your request exceeds the record size of the file, fupdate() writes
a record that is the record size, sets errno, and returns the length of the record
that was read.

Deleting records
To delete records, use the library function fdelrec(), a z/OS XL C/C++ extension to
the SAA C library. For more information on this function, see z/OS XL C/C++
Run-Time Library Reference.
v KSDS, KSDS PATH, and RRDS
To delete records, you must perform the following operations:
1. Open the VSAM file in update mode (rb+/r+b, ab+/a+b, or wb+/w+b specified
as the required positional parameter of the fopen() function call and
type=record).
2. If the file is not already positioned at the record you want to delete, reposition
to that record.
3. Read the record using the fread() function.
Once the record you want to delete has been read in, you must ensure that
no reading, writing, or repositioning operations are performed before
fdelrec().
4. Delete the record using the fdelrec() function.

Note: If the data set was opened with an access mode of rb+ or r+b, a read
operation can result in the locking of control intervals, depending on
shareoptions specification of the VSAM file. If after reading a record, you decide
not to delete it, you may need to unlock a control interval by performing a
file-positioning operation to the same record, such as an flocate() using the
same key.
v ESDS and ESDS PATH
VSAM does not support deletion of records in ESDS files.

Repositioning within record I/O files

You can use the following functions to locate a record within a VSAM data set:
v flocate()
v ftell(), ftello() and fseek(), fseeko()
v fgetpos() and fsetpos()
v rewind()

Chapter 12. Performing VSAM I/O operations 161

 For complete details on these library functions, see z/OS XL C/C++ Run-Time
Library Reference.

flocate()
The flocate() C library function can be used to locate a specific record within a
VSAM data set given the key, relative byte address, or the relative record number.
The flocate() function also sets the access direction.

VSAM extended addressability support includes an 8 byte RBA for use with
positioning functions such as flocate(). flocate() supports RBA lengths of 4 and
8 bytes. Existing applications that use flocate() with a 4 byte RBA will continue
unaffected, but must use a key length of 8 to locate an RBA beyond 4GB.

The following flocate() parameters set the access direction to forward:

v __KEY_FIRST (the key and key_len parameters are ignored)
v __KEY_EQ
v __KEY_GE
v __RBA_EQ

The following flocate() parameters all set the access direction to backward and are
only valid for record I/O:
v __KEY_LAST (the key and key_len parameters are ignored)
v __KEY_EQ_BWD
v __RBA_EQ_BWD

Note: The __RBA_EQ and __RBA_EQ_BWD parameters are not valid for paths and are
not recommended for KSDS and RRDS data sets.

You can use the rewind() library function instead of calling flocate() with
__KEY_FIRST.
v KSDS, KSDS AIX, and ESDS AIX
The key parameter of flocate() for the options __KEY_EQ, __KEY_GE, and
__KEY_EQ_BWD is a pointer to the key of reference of the data set. The key_len
parameter is the key length as defined for the data set for a full key search, or
less than the defined key length for a generic key search (a partial key match).
For KSDSs, __RBA_EQ and __RBA_EQ_BWD are supported, but are not
recommended.
For __KEY_EQ_BWD the key_len parameter must be equal to the key length as
defined for the data set for a full key search.
Alternate indexes do not allow positioning by RBA.
v ESDS
The key parameter of flocate() is a pointer to the specified RBA value. The
key_len parameter is either 4 or 8 depending on the size of the RBA.
v RRDS
For __KEY_EQ, __KEY_GE, and __KEY_EQ_BWD, the key parameter of flocate() is a
pointer to an unsigned long integer containing the specified relative record
number. The key_len parameter is sizeof(unsigned long). For __RBA_EQ and
__RBA_EQ_BWD, the key parameter of flocate() is a pointer to the specified RBA.
However, seeking to RBA values is not recommended, because it is not
supported across control intervals. The key_len parameter is either 4 or 8
depending on the size of the RBA.

162 z/OS V1R13.0 XL C/C++ Programming Guide

fgetpos() and fsetpos()
fgetpos() is used to store the current file position and access direction. fsetpos()
is used to relocate to a file position stored by fgetpos() and restore the saved
access direction.
v KSDS
fgetpos() stores the RBA value. This RBA value may be invalidated by
subsequent insertions, deletions, or updates.
v KSDS AIX and ESDS AIX
fgetpos() and fsetpos() are not supported for PATHs.
v ESDS and RRDS
There are no special considerations.

ftell() and fseek()

ftell() is used to store the current file position. fseek() is used to relocate to one
of the following:
v A file position stored by ftell()
v A calculated record number (SEEK_SET)
v A position relative to the current position (SEEK_CUR)
v A position relative to the end of the file (SEEK_END).

ftell() and fseek() offsets in record mode I/O are relative record offsets. For
example, the following call moves the file position to the start of the previous
record:
fseek(fp, -1L, SEEK_CUR);

You cannot use fseek() to reposition to a file position before the beginning of the
file or to a position beyond the end of the file.

Note: In general, the performance of this method is inferior to flocate().

The access direction is unchanged by the repositioning.

v KSDS and RRDS
There are no special considerations.
v KSDS AIX and ESDS AIX
ftell() and fseek() are not supported.
v ESDS
ftell() is not supported.
v RRDS
fseek() seeks to a relative position in the file, and not to an RRN value. For
example, in a file consisting of RRNs 1, 3, 5 and 7, fseek(fp, 3L, SEEK_SET);
followed by an fread() would read in RRN 7, which is at offset 3 in the file.

rewind()
The rewind() function repositions the file position to the beginning of the file, and
clears the error setting for the file. rewind() does not reset the file access direction.
For example, a call to flocate() with __KEY_LAST sets the file pointer to the end of
the file and sets the access direction to backwards. A subsequent call to rewind()
sets the file pointer to the beginning of the file, but the access direction remains
backwards.

Chapter 12. Performing VSAM I/O operations 163

Flushing buffers
You can use the C library function fflush() to flush buffers. However, fflush()
writes nothing to the system, because all records have already been written there
by fwrite(). fflush() after a read operation does not refresh the contents of the
buffer. For more information on fflush(), see z/OS XL C/C++ Run-Time Library
Reference.

Summary of VSAM record I/O operations

Table 24. Summary of VSAM record I/O operations
KSDS ESDS RRDS PATH
fopen(), freopen() rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+
(empty cluster or reuse (empty cluster or reuse (empty cluster or reuse
specified for wb & wb+) specified for wb & wb+) specified for wb & wb+)
fwrite(), rb+, ab, ab+, wb, wb+ rb+, ab, ab+, wb, wb+ rb+, ab, ab+, wb, wb+ rb+, ab, ab+
fwrite_unlocked()
fread(), rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb, rb+, ab+
fread_unlocked()
ftell(), rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
ftell_unlocked() (see note 1)
ftello(), rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
ftello_unlocked() (see note 1)
fseek(), rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
fseek_unlocked() (see note 1)
fseeko(), rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
fseeko_unlocked() (see note 1)
fgetpos(), rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
fgetpos_unlocked() (see note 2)
fsetpos(), rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
fsetpos_unlocked() (see note 2)
flocate(), rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb, rb+, ab+
flocate_unlocked()
rewind(), rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+
rewind_unlocked()
fflush(), rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+
fflush_unlocked()
fdelrec(), rb+, ab+, wb+ rb+, ab+, wb+ rb+, ab+ (not ESDS)
fdelrec_unlocked()
fupdate(), rb+, ab+, wb+ rb+, ab+, wb+ rb+, ab+, wb+ rb+, ab+
fupdate_unlocked()
ferror(), rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+
ferror_unlocked()
feof(), feof_unlocked() rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+
clearerr(), rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+
clearerr_unlocked()
fclose() rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+
fldata(), rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+
fldata_unlocked()

Notes:
1. The saved position is based on the relative position of the record within the data set. Subsequent insertions or deletions may
invalidate the saved position.
2. The saved position is based on the RBA of the record. Subsequent insertions, deletions or updates may invalidate the saved
position.

164 z/OS V1R13.0 XL C/C++ Programming Guide

VSAM record level sharing and transactional VSAM
VSAM Record Level Sharing (RLS) and Transactional VSAM (VSAM RLS/TVS)
provide for the sharing of VSAM data at the record level, using the locking and
caching functions of the coupling facility hardware. For more information on Record
Level Sharing, see z/OS DFSMS Introduction.

The C/C++ run-time library provides the following support for VSAM RLS/TVS:
v Specification of RLS/TVS-related keywords in the mode string of fopen() and
freopen().
v Specification of RLS/TVS-related text unit key values in the __dyn_t structure,
which is used as input to the dynalloc() function.
v Provides the application with VSAM return and reason codes for VSAM I/O
errors.
v Performs implicit positioning for files opened for RLS/TVS access.

VSAM RLS/TVS has three read integrity file access modes. These modes tell
VSAM the level of locking to perform when records are accessed within a file that
has not been opened in update mode. The access modes are:
nri No Read Integrity indicates that requests performed by the application are
not to be serialized with updates or erases of the records by other calling
programs. VSAM accesses the records without obtaining a lock on the
record.
cr Consistent Read indicates that requests performed by the application are to
be serialized with updates or erases of the records by other calling
programs. VSAM obtains a share lock when accessing the record. This lock
is released once the record has been returned to the caller.
cre Consistent Read Explicit indicates that requests performed by the
application are to be serialized with updates or erases of the records by
other requestors.VSAM obtains a share lock when accessing the record.
This lock is held until the application commits its changes. This ensures that
records read by the application are not changed by other requestors until
the application commits or aborts its changes. Consistent Read Explicit is
for use only by commit protocol applications.

VSAM RLS locks records to support record integrity. An application may wait for an
exclusive record lock if another user has the record locked. The application is also
subject to new locking errors such as deadlock or timeout errors.

If the file has been opened in update mode, and RLS=CR or RLS=CRE is specified,
VSAM also serializes access to the records within the file. However, the type of
serialization differs from non-update mode in the following ways:
v A reposition within the file causes VSAM to obtain a share lock for the record.
v A read of a record causes VSAM to obtain an exclusive lock for the record. The
lock is held until the record is updated in the file, or another record is read. If
RLS=CRE is specified (for commit protocol applications), the lock is held until the
application commits or aborts its changes.
Notes:
1. When a file is opened, it is implicitly positioned to the first record to be
accessed.

Chapter 12. Performing VSAM I/O operations 165

 2. You can also specify the RLS/TVS keyword on the JCL DD statement. When
specified on both the JCL DD statement and in the mode string on fopen() or
freopen(), the read integrity options specified in the mode string override those
specified on the JCL DD statement.
3. VSAM RLS/TVS access is supported for the 3 types of VSAM files that the
C/C++ run-time library supports: Key-Sequenced (KSDS), Entry-Sequenced
(ESDS), and Relative Record (RRDS) data sets.
4. VSAM RLS/TVS functions require the use of a Coupling Facility. For more
information on using the Coupling Facility, see z/OS DFSMS Introduction, and
z/OS Parallel Sysplex Overview.
5. In an environment where one thread opens and another thread issues record
management requests, VSAM RLS/TVS requires that record management
requests be issued from a thread whose Task Control Block (TCB) is
subordinate to the TCB of the thread which opened the file.
6. VSAM RLS/TVS does not support the following:
v Key range data sets
v Direct open of an AIX cluster as a KSDS
v Access to individual components of a cluster
v OS Checkpoint and Restart

Error reporting
Errors are reported through the __amrc structure and the SIGIOERR signal. The
following are additional considerations for error reporting in a VSAM RLS
application:
v VSAM RLS/TVS uses the SMSVSAM server address space. When a file open
fails because the server is not available, the C run-time library places the error
return code and error value in the __amrc structure, and returns a null file
descriptor. Record management requests return specific error return/reason
codes, if the SMSVSAM server is not available. The server address space is
automatically restarted. To recover from this type of error, an application should
first close the file to clean up the file status, and then open the file prior to
attempting record management requests. The close for the file returns a return
code of 4, and an error code of 170(X'AA'). This is the expected result. It is not
an error.
v Opening a recoverable file for output is not supported. If you attempt to do so,
the open will fail with error return code 255 in the __amrc structure.
v Some of the VSAM errors, that are reported in the __amrc structure, are
situations from which an application can recover. These are problems that can
occur unpredictably in a sharing environment. Usually, the application can
recover by simply accessing another record. Examples of such errors are the
following:
RC 8, 21(X'15'): Request cancelled as part of deadlock resolution.
RC 8, 22(X'16'): Request cancelled as part of timeout resolution.
RC 8, 24(X'18'): Request cancelled because transaction backout is pending
on the requested record.
RC 8, 29(X'14'): Intra-luwid contention between threads under a given TCB.
The application can intercept errors by registering a condition handler for the
SIGIOERR condition. Within the condition handler, the application can examine
the information in the __amrc structure and determine how to recover from each
specific situation.

166 z/OS V1R13.0 XL C/C++ Programming Guide

 Refer to z/OS DFSMS Macro Instructions for Data Sets for a complete list of
return and reason codes.

VSAM extended addressability

DFSMS supports VSAM data sets greater than 4GB in size through extended
addressability (XADDR) support. XADDR support is an extension to DFSMS
extended-format data set support. VSAM XADDR supports key sequenced data
sets (KSDS), entry sequenced data sets (ESDS), and relative-record data set
(RRDS).

Restriction: z/OS XL C/C++ does not support XADDR for ESDS alternate indexes.

VSAM XADDR support includes an 8 byte relative byte address for use with
positioning functions such as flocate(). flocate() supports key lengths of 4 and 8
bytes. Existing applications that use flocate() to locate with a 4 byte relative byte
address will continue unaffected, but must use a key length of 8 to locate a record
within XADDR addresses.

The RBA field in the __amrc structure is set to -1 when applications access beyond
the addresses that can be represented by the 4 byte value, effectively appearing to
be EOF to any 4 byte RBA positioning (flocate()) calls. The __XRBA field will always
be updated with the address, and must be used in these cases.

For AMODE 31 applications repositioning within a VSAM data set, users of ftell()
and fseek() that need to access XADDR addresses, must use the large file version
of ftello() and fseeko() .

XADDR support for AMODE 31 applications is listed in the following table:

Table 25. AMODE31 application XADDR support
Function XADDR support
fgetpos(), fgetpos_unlocked() Yes
fsetpos(), fsetpos_unlocked() Yes
ftell(), ftell_unlocked() No
fseek(), fseek_unlocked() No
ftello() or ftello_unlocked() non-large files version No
fseeko() or fseeko_unlocked() non-large files No
version
ftello() or ftello_unlocked() large files version Yes
fseeko() or fseeko_unlocked() large files version Yes
flocate() or flocate_unlocked() Yes
fldata() or fldata_unlocked() Yes

Note: AMODE 64 applications also have the above restrictions on XADDR support.

Text and binary I/O in VSAM

Because VSAM is primarily record-based, this section only discusses those aspects
of text and binary I/O that are specific to VSAM. For general information on text and
binary I/O, refer to the respective sections in Chapter 10, Performing OS I/O
operations, on page 81.

Chapter 12. Performing VSAM I/O operations 167

Reading from text and binary I/O files
v RRDS
All the read functions support reading from text and binary RRDS files. fread() is
called with a character buffer instead of an RRDS record structure.

Writing to and updating text and binary I/O files

v KSDS, KSDS AIX, and ESDS AIX
z/OS XL C/C++ VSAM support for streams does not provide for writing and
updating these types of data sets opened for text or binary stream I/O.
v ESDS
Writes are supported for ESDSs opened as binary or text streams. Updating data
in an ESDS stream cannot change the length of the record in the external file.
Therefore, in a binary stream:
updates for less than the existing record length leave existing data beyond the
updated length unchanged;
updates for longer than the existing record length flow over the record
boundary and update the start of the next record.
In text streams:
updates that specify records shorter than the original record pad the updated
record to the existing record length with blanks;
updates for longer than the existing record length result in truncation, unless
the original record contained only a new-line character, in which case it may
be updated to contain one byte of data plus a new-line character.
v RRDS
fwrite() is called with a character buffer instead of an RRDS record structure.
Records are treated as contiguous. Once the current record is filled, the next
record in the file is written to. For example, if the file consisted of only record 1,
record 5, and record 28, a write would complete record 1 and then go directly to
record 5.
Writing past the last record in the file is allowed, up to the maximum size of the
RRDS data set. For example, if the last record in the file is record 28, the next
record to be written is record 29.
Insertion of records is not supported. For example, in a file of records 1, 5, and
28, you cannot insert record 3 into the file.

Deleting records in text and binary I/O files

fdelrec() is not supported for text and binary I/O in VSAM.

Repositioning within text and binary I/O files

You can use the following functions to locate a record within a VSAM data set:
v flocate()
v ftell(), ftello(), fseek(), and fseeko()
v fgetpos() and fsetpos()
v rewind()

For complete details on these library functions, see z/OS XL C/C++ Run-Time
Library Reference.

168 z/OS V1R13.0 XL C/C++ Programming Guide

flocate()
The flocate() C library function can be used to reposition to the beginning of a
specific record within a VSAM data set given the key, relative byte address, or the
relative record number. For more information on this function, see z/OS XL C/C++
Run-Time Library Reference.

VSAM extended addressability support includes an 8 byte RBA for use with
positioning functions such as flocate(). flocate() supports RBA lengths of 4 and
8 bytes. Existing applications that use flocate() with a 4 byte RBA will continue
unaffected, but must use a key length of 8 to locate an RBA beyond 4GB.

The following flocate() parameters set the direction access to forward:

v __KEY_FIRST (the key and key_len parameters are ignored)
v __KEY_EQ
v __KEY_GE
v __RBA_EQ

The following flocate() parameters all set the access direction to backward and are
not valid for text and binary I/O, because backwards access is not supported:
v __KEY_LAST (the key and key_len parameters are ignored)
v __KEY_EQ_BWD
v __RBA_EQ_BWD

You can use the rewind() library function instead of calling flocate() with
__KEY_FIRST.
v KSDS, KSDS AIX, and ESDS AIX
The key parameter of flocate() for the options __KEY_EQ and __KEY_GE is a
pointer to the key of reference of the data set. The key_len parameter is the key
length as defined for the data set for a full key search, or less than the defined
key length for a generic key search (a partial key match).
Alternate indexes do not allow positioning by RBA.

Note: The __RBA_EQ parameter is not valid for paths and is not recommended.
v ESDS
The key parameter of flocate() is a pointer to the specified RBA value. The
key_len parameter is either 4 or 8 depending on the size of the RBA.
v RRDS
For __KEY_EQ and __KEY_GE, the key parameter of flocate() is a pointer to an
unsigned long integer containing the specified relative record number. The
key_len parameter is sizeof(unsigned long). For __RBA_EQ, the key parameter of
flocate() is a pointer to the specified RBA. However, seeking to RBA values is
not recommended, because it is not supported across control intervals. The
key_len parameter is either 4 or 8 depending on the size of the RBA.

fgetpos() and fsetpos()

fgetpos() saves the access direction, an RBA value, and the file position, and
fsetpos() restores the saved access direction. fgetpos() accounts for the
presence of characters in the ungetc() buffer unless you have set the _EDC_COMPAT
variable. See Chapter 32, Using environment variables, on page 467 for
information about _EDC_COMPAT. If ungetc() characters back the file position up to
before the start of the file, calls to fgetpos() fail.
v KSDS

Chapter 12. Performing VSAM I/O operations 169

 fgetpos() stores the RBA value. This RBA value may be invalidated by
subsequent insertions, deletions or updates.
v KSDS PATH and ESDS PATH
fgetpos() and fsetpos() are not supported for PATHs.
v ESDS and RRDS
There are no special considerations.

ftell() and fseek()

Using fseek() to seek beyond the current end of file in a writable ESDS or RRDS
binary file results in the file being extended with nulls to the new position. An
incomplete last record is completed with nulls, records of length lrecl are added as
required, and the current record is filled with the remaining number of nulls and left
in the current buffer. This is supported for relative byte offset from SEEK_SET,
SEEK_CUR and SEEK_END.

For AMODE 31 applications repositioning within a VSAM data set, users of ftell()
and fseek() that need to access positions beyond 4GB, must use the large file
version of ftello() and fseeko() .

Table 26 provides a summary of the fseek() and ftell() parameters in binary and
text.
Table 26. Summary of fseek() and ftell() parameters in text and binary
Type Mode ftell() return fseek() SEEK_CUR SEEK_END
values SEEK_SET
KSDS Binary relative byte offset relative byte offset relative byte offset relative byte offset
Text not supported zero only relative byte offset relative byte offset
ESDS Binary relative byte offset relative byte offset relative byte offset relative byte offset
Text not supported zero only relative byte offset relative byte offset
RRDS Binary encoded byte encoded byte relative byte offset relative byte offset
offset offset
Text encoded byte encoded byte relative byte offset relative byte offset
offset offset
PATH Binary not supported not supported not supported not supported
Text not supported not supported not supported not supported

Flushing buffers
You can use the C library function fflush() to flush data.

For text files, calling fflush() to flush an update to a record causes the new data
to be written to the file.

If you call fflush() while you are updating, the updates are flushed out to VSAM.

For more information on fflush(), see z/OS XL C/C++ Run-Time Library

Reference.

170 z/OS V1R13.0 XL C/C++ Programming Guide

Summary of VSAM text I/O operations
Table 27 summarizes the VSAM text I/O operations.
Table 27. Summary of VSAM text I/O operations
KSDS ESDS RRDS PATH
fopen(), freopen() r r, r+, a, a+, w, w+ (empty r, r+, a, a+, w, w+ (empty r
cluster or reuse specified cluster or reuse specified for
for w & w+) w & w+)
fwrite(), fwrite_unlocked() r+, a, a+, w, w+ r+, a, a+, w, w+
fprintf(), fprintf_unlocked() r+, a, a+, w, w+ r+, a, a+, w, w+
fputs(), fputs_unlocked() r+, a, a+, w, w+ r+, a, a+, w, w+
fputc(), fputc_unlocked() r+, a, a+, w, w+ r+, a, a+, w, w+
putc(), putc_unlocked() r+, a, a+, w, w+ r+, a, a+, w, w+
vfprintf(), vfprintf_unlocked() r+, a, a+, w, w+ r+, a, a+, w, w+
vprintf(), vprintf_unlocked() r+, a, a+, w, w+ r+, a, a+, w, w+
fread(), fread_unlocked() r r, r+, a+, w+ r, r+, a+, w+ r
fscanf(), fscanf_unlocked() r r, r+, a+, w+ r, r+, a+, w+ r
vfscanf(), vfscanf_unlocked() r r, r+, a+, w+ r, r+, a+, w+ r
fgets(), fgets_unlocked() r r, r+, a+, w+ r, r+, a+, w+ r
fgetc(), fgetc_unlocked() r r, r+, a+, w+ r, r+, a+, w+ r
getc(), getc_unlocked() r r, r+, a+, w+ r, r+, a+, w+ r
ungetc(), ungetc_unlocked() r r, r+, a+, w+ r, r+, a+, w+ r
ftell(), ftell_unlocked() r, r+, a, a+, w, w+
ftello(), ftello_unlocked() r, r+, a, a+, w, w+
fseek(), fseek_unlocked() r r, r+, a, a+, w, w+ r, r+, a, a+, w, w+
fseeko(), fseeko_unlocked() r r, r+, a, a+, w, w+ r, r+, a, a+, w, w+
fgetpos(), fgetpos_unlocked() r r, r+, a, a+, w, w+ r, r+, a, a+, w, w+
fsetpos(), fsetpos_unlocked() r r, r+, a, a+, w, w+ r, r+, a, a+, w, w+
flocate(), flocate_unlocked() r r, r+, a+, w+ r, r+, a+, w+ r
rewind(), rewind_unlocked() r r, r+, a, a+, w, w+ r, r+, a, a+, w, w+ r
fflush(), fflush_unlocked() r r, r+, a, a+, w, w+ r, r+, a, a+, w, w+ r
ferror(), ferror_unlocked() r r, r+, a, a+, w, w+ r, r+, a, a+, w, w+ r
fdelrec(), fdelrec_unlocked()
fupdate(), fupdate_unlocked()
feof(), feof_unlocked() r r, r+, a, a+, w, w+ r, r+, a, a+, w, w+ r
clearerr(), clearerr_unlocked() r r, r+, a, a+, w, w+ r, r+, a, a+, w, w+ r
fclose() r r, r+, a, a+, w, w+ r, r+, a, a+, w, w+ r
fldata(), fldata_unlocked() r r, r+, a, a+, w, w+ r, r+, a, a+, w, w+ r

Summary of VSAM binary I/O operations

Table 28 summarizes the VSAM binary I/O operations.
Table 28. Summary of VSAM binary I/O operations
KSDS ESDS RRDS PATH
fopen(), freopen() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb
(empty cluster or reuse (empty cluster or reuse
specified for wb & wb+) specified for wb & wb+)
fwrite(), fwrite_unlocked() rb+, ab, ab+, wb, wb+ rb+, ab, ab+, wb, wb+
fprintf(), fprintf_unlocked() rb+, ab, ab+, wb, wb+ rb+, ab, ab+, wb, wb+

Chapter 12. Performing VSAM I/O operations 171

Table 28. Summary of VSAM binary I/O operations (continued)
KSDS ESDS RRDS PATH
fputs(), fputs_unlocked() rb+, ab, ab+, wb, wb+ rb+, ab, ab+, wb, wb+
fputc(), fputc_unlocked() rb+, ab, ab+, wb, wb+ rb+, ab, ab+, wb, wb+
putc(), putc_unlocked() rb+, ab, ab+, wb, wb+ rb+, ab, ab+, wb, wb+
vfprintf(), vfprintf_unlocked() rb+, ab, ab+, wb, wb+ rb+, ab, ab+, wb, wb+
vprintf(), vprintf_unlocked() rb+, ab, ab+, wb, wb+ rb+, ab, ab+, wb, wb+
fread(), fread_unlocked() rb rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb
fscanf(), fscanf_unlocked() rb rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb
vfscanf(), vfscanf_unlocked() rb rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb
fgets(), fgets_unlocked() rb rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb
fgetc(), fgetc_unlocked() rb rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb
getc() rb rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb
getc_unlocked() rb rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb
ungetc(), ungetc_unlocked() rb rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb
ftell(), ftell_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
ftello(), ftello_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
fseek(), fseek_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
fseeko(), fseeko_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
fgetpos(), fgetpos_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
fsetpos(), fsetpos_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+
flocate(), flocate_unlocked() rb rb, rb+, ab+, wb+ rb, rb+, ab+, wb+ rb
rewind(), rewind_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb
fflush(), fflush_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb
ferror(), ferror_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb
fdelrec(), fdelrec_unlocked()
fupdate(), fupdate_unlocked()
feof(), feof_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb
clearerr(), clearerr_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb
fclose() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb
fldata(), fldata_unlocked() rb rb, rb+, ab, ab+, wb, wb+ rb, rb+, ab, ab+, wb, wb+ rb

Closing VSAM data sets

To close a VSAM data set, use the Standard C fclose() library function as you
would for closing non-VSAM files. See z/OS XL C/C++ Run-Time Library Reference
for more details on the fclose() library function.

For ESDS binary files, if fclose() is called and there is a new record in the buffer
that is less than the maximum record size, this record is written to the file at its
current size. A new RRDS binary record that is incomplete when the file is closed is
filled with null characters to the record size.

A new ESDS or RRDS text record that is incomplete when the file is closed is
completed with a new-line.

172 z/OS V1R13.0 XL C/C++ Programming Guide

VSAM return codes
When failing return codes are received from z/OS XL C/C++ VSAM I/O functions,
you can access the __amrc structure to help you diagnose errors. The __amrc_type
structure is defined in the header file stdio.h (when the compiler option
LANGLVL(LIBEXT) is used).

Note: The __amrc struct is global and can be reset by another I/O operation (such
as printf()).

The following fields of the structure are important to VSAM users:

__amrc.__code.__feedback.__rc
Stores the VSAM R15.
__amrc.__code.__feedback.__fdbk
Stores the VSAM error code or reason code.
__amrc.__RBA
Stores the RBA after some operations. The __amrc.__RBA field is defined as
an unsigned int, and therefore will only contain a 4-byte RBA value. This
field will be set to -1 when the RBA is beyond 4GB in an extended
addressable VSAM data set. In this case, the __XRBA field should be used.
__amrc.__XRBA
The 8 byte relative byte address returned by VSAM after an ESDS or
KSDS record is written out. For an RRDS, it is the calculated value from the
record number. It may be used in subsequent calls to flocate().
__amrc.__last_op
Stores a code for the last operation. The codes are defined in the header
file stdio.h.
__amrc.__rplfdbwd
Stores the feedback code from the IFGRPL control block.

For definitions of these return codes and feedback codes, refer to the publications
listed in DFSMS on page 1027.

You can set up a SIGIOERR handler to catch read or write system errors. See
Chapter 18, Debugging I/O programs, on page 221 for more information.

VSAM examples
This section provides several examples of using I/O under VSAM.

KSDS example
The example in Figure 26 on page 174 shows a sample program (CCNGVS2) with
two functions from an employee record entry system with a mainline driver to
process selected options (display, display next, update, delete, create). The update
routine is an example of KSDS clusters, and the display routine is an example of
both KSDS clusters and alternate indexes.

For these examples, the clusters and alternate indexes should be defined as
follows:
v The KSDS cluster has a record size of 150 with a key length of 4 with offset 0.
v The unique KSDS AIX has a key length of 20 with an offset of 10.
v The non-unique KSDS AIX has a key length of 40 with an offset of 30.
Chapter 12. Performing VSAM I/O operations 173
 The update routine is passed the following:
v data_ptr, which points to the information that is to be updated
v orig_data_ptr, which points to the information that was originally displayed using
the display option
v A file pointer to the KSDS cluster

The display routine is passed the following:

v data_ptr, which points to the information that was entered on the screen for the
search query
v orig_data_ptr, which is returned with the information for the record to be
displayed if it exists
v File pointers for the primary cluster, unique alternate index and non-unique
alternate index

By definition, the primary key is unique and therefore the employee number was
chosen for this key. The user_id is also a unique key; therefore, it was chosen as
the unique alternate index key. The name field may not be unique; therefore, it was
chosen as the non-unique alternate index key.

/* this example demonstrates the use of a KSDS file */

/* part 1 of 2-other file is CCNGVS3 */

#include <stdio.h>
#include <string.h>

/* global definitions */

struct data_struct {
char emp_number[4];
char user_id[8];
char name[20];
char pers_info[37];
};

#define REC_SIZE 69
#define CLUS_KEY_SIZE 4
#define AIX_UNIQUE_KEY_SIZE 8
#define AIX_NONUNIQUE_KEY_SIZE 20

static void print_amrc() {

__amrc_type currErr = *__amrc; /* copy contents of __amrc */
/* structure so that values */
/* dont get jumbled by printf */
printf("R15 value = %d\n", currErr.__code.__feedback.__rc);
printf("Reason code = %d\n", currErr.__code.__feedback.__fdbk);
printf("RBA = %d\n", currErr.__RBA);
printf("Last op = %d\n", currErr.__last_op);
return;
}

Figure 26. KSDS example (Part 1 of 5)

174 z/OS V1R13.0 XL C/C++ Programming Guide

/* update_emp_rec() function definition */

int update_emp_rec (struct data_struct *data_ptr,

struct data_struct *orig_data_ptr,
FILE *fp)
{
int rc;
char buffer[REC_SIZE+1];

/* Check to see if update will change primary key (emp_number) */

if (memcmp(data_ptr->emp_number,orig_data_ptr->emp_number,4) != 0) {
/* Check to see if changed primary key exists */
rc = flocate(fp,&(data_ptr->emp_number),CLUS_KEY_SIZE,__KEY_EQ);
if (rc == 0) {
print_amrc();
printf("Error: new employee number already exists\n");
return 10;
}

clearerr(fp);

/* Write out new record */

rc = fwrite(data_ptr,1,REC_SIZE,fp);
if (rc != REC_SIZE || ferror(fp)) {
print_amrc();
printf("Error: write with new employee number failed\n");
return 20;
}

/* Locate to old employee record so it can be deleted */

rc = flocate(fp,&(orig_data_ptr->emp_number),CLUS_KEY_SIZE,
__KEY_EQ);
if (rc != 0) {
print_amrc();
printf("Error: flocate to original employee number failed\n");
return 30;
}

rc = fread(buffer,1,REC_SIZE,fp);
if (rc != REC_SIZE || ferror(fp)) {
print_amrc();
printf("Error: reading old employee record failed\n");
return 40;
}

rc = fdelrec(fp);
if (rc != 0) {
print_amrc();
printf("Error: deleting old employee record failed\n");
return 50;
}
} /* end of checking for change in primary key */
else { /* Locate to current employee record */
rc = flocate(fp,&(data_ptr->emp_number),CLUS_KEY_SIZE,__KEY_EQ);
if (rc == 0) {
/* record exists, so update it */
rc = fread(buffer,1,REC_SIZE,fp);
if (rc != REC_SIZE || ferror(fp)) {
print_amrc();
printf("Error: reading old employee record failed\n");
return 60;
}

Figure 26. KSDS example (Part 2 of 5)

Chapter 12. Performing VSAM I/O operations 175

176 z/OS V1R13.0 XL C/C++ Programming Guide
 rc = fupdate(data_ptr,REC_SIZE,fp);
if (rc == 0) {
print_amrc();
printf("Error: updating new employee record failed\n");
return 70;
}
}
else { /* record doesnt exist so write out new record */
clearerr(fp);
printf("Warning: record previously displayed no longer\n");
printf(" : exists, new record being created\n");
rc = fwrite(data_ptr,1,REC_SIZE,fp);
if (rc != REC_SIZE || ferror(fp)) {
print_amrc();
printf("Error: write with new employee number failed\n");
return 80;
}
}
}
return 0;
}

/* display_emp_rec() function definition */

int display_emp_rec (struct data_struct *data_ptr,

struct data_struct *orig_data_ptr,
FILE *clus_fp, FILE *aix_unique_fp,
FILE *aix_non_unique_fp)
{
int rc = 0;
char buffer[REC_SIZE+1];

/* Primary Key Search */

if (memcmp(data_ptr->emp_number, "\0\0\0\0", 4) != 0) {
rc = flocate(clus_fp,&(data_ptr->emp_number),CLUS_KEY_SIZE,
__KEY_EQ);
if (rc != 0) {
printf("Error: flocate with primary key failed\n");
return 10;
}

/* Read record for display */

rc = fread(orig_data_ptr,1,REC_SIZE,clus_fp);
if (rc != REC_SIZE || ferror(clus_fp)) {
printf("Error: reading employee record failed\n");
return 15;
}
}

/* Unique Alternate Index Search */

else if (data_ptr->user_id[0] != \0) {
rc = flocate(aix_unique_fp,data_ptr->user_id,AIX_UNIQUE_KEY_SIZE,
__KEY_EQ);
if (rc != 0) {
printf("Error: flocate with user id failed\n");
return 20;
}

/* Read record for display */

rc = fread(orig_data_ptr,1,REC_SIZE,aix_unique_fp);
if (rc != REC_SIZE || ferror(aix_unique_fp)) {
printf("Error: reading employee record failed\n");
return 25;
}
}

Figure 26. KSDS example (Part 3 of 5) Chapter 12. Performing VSAM I/O operations 177
178 z/OS V1R13.0 XL C/C++ Programming Guide
 /* Non-unique Alternate Index Search */
else if (data_ptr->name[0] != \0) {
rc = flocate(aix_non_unique_fp,data_ptr->name,
AIX_NONUNIQUE_KEY_SIZE,__KEY_GE);
if (rc != 0) {
printf("Error: flocate with name failed\n");
return 30;
}

/* Read record for display */

rc = fread(orig_data_ptr,1,REC_SIZE,aix_non_unique_fp);
if (rc != REC_SIZE || ferror(aix_non_unique_fp)) {
printf("Error: reading employee record failed\n");
return 35;
}
}
else {
printf("Error: invalid search argument; valid search arguments\n"
" : are either employee number, user id, or name\n");
return 40;
}
/* display record data */
printf("Employee Number: %.4s\n", orig_data_ptr->emp_number);
printf("Employee Userid: %.8s\n", orig_data_ptr->user_id);
printf("Employee Name: %.20s\n", orig_data_ptr->name);
printf("Employee Info: %.37s\n", orig_data_ptr->pers_info);
return 0;
}
/* main() function definition */

int main() {
FILE* clus_fp;
FILE* aix_ufp;
FILE* aix_nufp;
int i;
struct data_struct buf1, buf2;

char data[3][REC_SIZE+1] = {
" 1LARRY LARRY HI, IM LARRY, ",
" 2DARRYL1 DARRYL AND THIS IS MY BROTHER DARRYL, ",
" 3DARRYL2 DARRYL "
};

/* open file three ways */

clus_fp = fopen("dd:cluster", "rb+,type=record");
if (clus_fp == NULL) {
print_amrc();
printf("Error: fopen(\"dd:cluster\"...) failed\n");
return 5;
}

/* assume base cluster was loaded with at least one dummy record */
/* so aix could be defined */
aix_ufp = fopen("dd:aixuniq", "rb,type=record");
if (aix_ufp == NULL) {
print_amrc();
printf("Error: fopen(\"dd:aixuniq\"...) failed\n");
return 10;
}

/* assume base cluster was loaded with at least one dummy record */
/* so aix could be defined */
aix_nufp = fopen("dd:aixnuniq", "rb,type=record");

Figure 26. KSDS example (Part 4 of 5)

Chapter 12. Performing VSAM I/O operations 179

 if (aix_nufp == NULL) {
print_amrc();
printf("Error: fopen(\"dd:aixnuniq\"...) failed\n");
return 15;
}

/* load sample records */

for (i = 0; i < 3; ++i) {
if (fwrite(data[i],1,REC_SIZE,clus_fp) != REC_SIZE) {
print_amrc();
printf("Error: fwrite(data[%d]...) failed\n", i);
return 66+i;
}
}

/* display sample record by primary key */

memcpy(buf1.emp_number, " 1", 4);
if (display_emp_rec(&buf1, &buf2, clus_fp, aix_ufp, aix_nufp) != 0)
return 69;

/* display sample record by nonunique aix key */

memset(buf1.emp_number, \0, 4);
buf1.user_id[0] = \0;
memcpy(buf1.name, "DARRYL ", 20);
if (display_emp_rec(&buf1, &buf2, clus_fp, aix_ufp, aix_nufp) != 0)
return 70;

/* display sample record by unique aix key */

memcpy(buf1.user_id, "DARRYL2 ", 8);
if (display_emp_rec(&buf1, &buf2, clus_fp, aix_ufp, aix_nufp) != 0)
return 71;

/* update record just read with new personal info */

memcpy(&buf1, &buf2, REC_SIZE);
memcpy(buf1.pers_info, "AND THIS IS MY OTHER BROTHER DARRYL. ", 37);
if (update_emp_rec(&buf1, &buf2, clus_fp) != 0) return 72;

/* display sample record by unique aix key */

if (display_emp_rec(&buf1, &buf2, clus_fp, aix_ufp, aix_nufp) != 0)
return 73;

return 0;
}

Figure 26. KSDS example (Part 5 of 5)

The JCL in the sample code (CCNGVS3) in Figure 27 can be used to test the
example code in Figure 26 on page 174.

//* this example illustrates the use of a KSDS file

//* part 2 of 2-other file is CCNGVS2
//*------------------------------------------------------------------
//* Delete cluster, and AIX and PATH
//*------------------------------------------------------------------
//DELETEC EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *

Figure 27. KSDS example (Part 1 of 3)

180 z/OS V1R13.0 XL C/C++ Programming Guide

 DELETE -
userid.KSDS.CLUSTER -
CLUSTER -
PURGE -
ERASE
//*------------------------------------------------------------------
//* Define KSDS
//*------------------------------------------------------------------
//DEFINE EXEC PGM=IDCAMS
//VOLUME DD UNIT=SYSDA,DISP=SHR,VOL=SER=(XXXXXX)
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE CLUSTER -
(NAME(userid.KSDS.CLUSTER) -
FILE(VOLUME) -
VOL(XXXXXX) -
TRK(4 4) -
RECSZ(69 100) -
INDEXED -
NOREUSE -
KEYS(4 0) -
OWNER(userid) ) -
DATA -
(NAME(userid.KSDS.DA)) -
INDEX -
(NAME(userid.KSDS.IX))
/*
//*------------------------------------------------------------------
//* Repro data into KSDS
//*------------------------------------------------------------------
//REPRO EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
REPRO INDATASET(userid.DUMMY.DATA) -
OUTDATASET(userid.KSDS.CLUSTER)
/*
//*------------------------------------------------------------------
//* Define unique AIX, define and build PATH
//*------------------------------------------------------------------
//DEFAIX EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE AIX -
(NAME(userid.KSDS.UAIX) -
RECORDS(25) -
KEYS(8,4) -
VOL(XXXXXX) -
UNIQUEKEY -
RELATE(userid.KSDS.CLUSTER)) -
DATA -
(NAME(userid.KSDS.UAIXDA)) -
INDEX -
(NAME(userid.KSDS.UAIXIX))
DEFINE PATH -
(NAME(userid.KSDS.UPATH) -
PATHENTRY(userid.KSDS.UAIX))
BLDINDEX -
INDATASET(userid.KSDS.CLUSTER) -
OUTDATASET(userid.KSDS.UAIX)
/*

Figure 27. KSDS example (Part 2 of 3)

Chapter 12. Performing VSAM I/O operations 181

 //*------------------------------------------------------------------
//* Define nonunique AIX, define and build PATH
//*------------------------------------------------------------------
//DEFAIX EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE AIX -
(NAME(userid.KSDS.NUAIX) -
RECORDS(25) -
KEYS(20, 12) -
VOL(XXXXXX) -
NONUNIQUEKEY -
RELATE(userid.KSDS.CLUSTER)) -
DATA -
(NAME(userid.KSDS.NUAIXDA)) -
INDEX -
(NAME(userid.KSDS.NUAIXIX))
DEFINE PATH -
(NAME(userid.KSDS.NUPATH) -
PATHENTRY(userid.KSDS.NUAIX))
BLDINDEX -
INDATASET(userid.KSDS.CLUSTER) -
OUTDATASET(userid.KSDS.NUAIX)
/*
//*------------------------------------------------------------------
//* Run the testcase
//*------------------------------------------------------------------
//GO EXEC PGM=CCNGVS2,REGION=5M
//STEPLIB DD DSN=userid.TEST.LOAD,DISP=SHR
// DD DSN=CEE.SCEERUN,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSTERM DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//PLIDUMP DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//CLUSTER DD DSN=userid.KSDS.CLUSTER,DISP=SHR
//AIXUNIQ DD DSN=userid.KSDS.UPATH,DISP=SHR
//AIXNUNIQ DD DSN=userid.KSDS.NUPATH,DISP=SHR
//*------------------------------------------------------------------
//* Print out the cluster
//*------------------------------------------------------------------
//PRINTF EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
PRINT -
INDATASET(userid.KSDS.CLUSTER) CHAR
/*

Figure 27. KSDS example (Part 3 of 3)

RRDS example
The sample program (CCNGVS4) in Figure 28 on page 184 illustrates the use of an
RRDS file. It performs the following operations:
1. Opens an RRDS file in record mode (the cluster must be defined)
2. Writes three records (RRN 2, RRN 10, and RRN 32)
3. Sets the file position to the first record
4. Reads the first record in the file
5. Deletes it

182 z/OS V1R13.0 XL C/C++ Programming Guide

 6. Locates the last record in the file and sets the access direction to backwards
7. Reads the record
8. Updates the record
9. Sets the _EDC_RRDS_HIDE_KEY environment variable
10. Reads the next record in sequence (RRN 10) into a character string

Chapter 12. Performing VSAM I/O operations 183

 /* this example illustrates the use of an RRDS file */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <env.h>

struct rrds_struct {
__
rrds_key_type rrds_key;
char *rrds_buf;
};

typedef struct rrds_struct RRDS_STRUCT;

main() {

FILE *fileptr;
RRDS_STRUCT RRDSstruct;
RRDS_STRUCT *rrds_rec = &RRDSstruct;
char buffer1[80] =
"THIS IS THE FIRST RECORD IN THE FILE. I"
"T WILL BE WRITTEN AT RRN POSITION 2. ";
char buffer2[80] =
"THIS IS THE SECOND RECORD IN THE FILE. I"
"T WILL BE WRITTEN AT RRN POSITION 10. ";
char buffer3[80] =
"THIS IS THE THIRD RECORD IN THE FILE. I"
"T WILL BE WRITTEN AT RRN POSITION 32. ";
char outputbuf[80];
unsigned long flocate_key = 0;

/*------------------------------------------------------------------*/
/*| select RRDS record structure 2 by setting __fill to 1 */
/*| */
/*| 1. open an RRDS file record mode (the cluster must be defined) */
/*| 2. write three records (RRN 2, RRN 10, RRN 32) */
/*------------------------------------------------------------------*/
rrds_rec->rrds_key.__fill = 1;

fileptr = fopen("DD:RRDSFILE", "wb+,type=record");

if (fileptr == NULL) {
perror("fopen");
exit(99);
}
rrds_rec->rrds_key.__recnum = 2;
rrds_rec->rrds_buf = buffer1;
fwrite(rrds_rec,1,88, fileptr);

rrds_rec->rrds_key.__recnum = 10;
rrds_rec->rrds_buf = buffer2;
fwrite(rrds_rec,1,88, fileptr);

rrds_rec->rrds_key.__recnum = 32;
rrds_rec->rrds_buf = buffer3;
fwrite(rrds_rec,1,88, fileptr);

Figure 28. RRDS example (Part 1 of 2)

184 z/OS V1R13.0 XL C/C++ Programming Guide

 /*------------------------------------------------------------------*/
/*| 3. set file position to the first record */
/*| 4. read the first record in the file */
/*| 5. delete it */
/*------------------------------------------------------------------*/
flocate(fileptr, &flocate_key,; sizeof(unsigned long), __KEY_FIRST);

memset(outputbuf,0x00,80);
rrds_rec->rrds_buf = outputbuf;

fread(rrds_rec,1, 88, fileptr);

printf("The first record in the file (this will be deleted):\n");
printf("RRN %d: %s\n\n",rrds_rec->rrds_key.__recnum,outputbuf);

fdelrec(fileptr);

/*------------------------------------------------------------------*/
/*| 6. locate last record in file and set access direction backwards*/
/*| 7. read the record */
/*| 8. update the record */
/*------------------------------------------------------------------*/
flocate(fileptr, &flocate_key,; sizeof(unsigned long), __KEY_LAST);

memset(outputbuf,0x00,80);
rrds_rec->rrds_buf = outputbuf;

fread(rrds_rec,1, 88, fileptr);

printf("The last record in the file (this one will be updated):\n");
printf("RRN %d: %s\n\n",rrds_rec->rrds_key.__recnum,outputbuf);

memset(outputbuf,0x00,80);
memcpy(outputbuf,"THIS IS THE UPDATED STRING... ",30);
fupdate(rrds_rec,88,fileptr);

/*------------------------------------------------------------------*/
/*| 9. set _EDC_RRDS_HIDE_KEY environment variable */
/*|10. read the next record in sequence (ie. RRN 10) into a */
/*| + character string */
/*------------------------------------------------------------------*/

setenv("_EDC_RRDS_HIDE_KEY","Y",1);
memset(outputbuf,0x00,80);
fread(outputbuf, 1, 80, fileptr);
printf("The middle record in the file (read into char string):\n");
printf("%80s\n\n",outputbuf);

fclose(fileptr);
}

Figure 28. RRDS example (Part 2 of 2)

fldata() behavior
The format of the fldata() function is as follows:

int fldata(FILE *file, char *filename, fldata_t *info);

The fldata() function is used to retrieve information about an open stream. The
name of the file is returned in filename and other information is returned in the

Chapter 12. Performing VSAM I/O operations 185

 fldata_t structure, shown in Figure 29 on page 187. Values specific to this category
of I/O are shown in the comment beside the structure element. Other notes about
this category of I/O follow the figure. For more information on the fldata() function,
see z/OS XL C/C++ Run-Time Library Reference.

186 z/OS V1R13.0 XL C/C++ Programming Guide

struct __fileData {
unsigned int __recfmF : 1, /* */
__recfmV : 1, /* */
__recfmU : 1, /* */
__recfmS : 1, /* always off */
__recfmBlk : 1, /* always off */
__recfmASA : 1, /* always off */
__recfmM : 1, /* always off */
__dsorgPO : 1, /* N/A -- always off */
__dsorgPDSmem : 1, /* N/A -- always off */
__dsorgPDSdir : 1, /* N/A -- always off */
__dsorgPS : 1, /* N/A -- always off */
__dsorgConcat : 1, /* N/A -- always off */
__dsorgMem : 1, /* N/A -- always off */
__dsorgHiper : 1, /* N/A -- always off */
__dsorgTemp: 1, /* N/A -- always off */
__dsorgVSAM: 1, /* always on */

#if __TARGET_LIB__ >= __EDC_LE /* */

__dsorgHFS : 1, /* */
#else
__reserve1 : 1, /* */
#endif
__openmode : 2, /* one of: */
/* __TEXT */
/* __BINARY */
/* __RECORD */
__modeflag : 4, /* combination of: */
/* __READ */
/* __WRITE */
/* __APPEND */
/* __UPDATE */
__dsorgPDSE: 1, /* N/A -- always off */
__vsamRLS : 3, /* One of: */
/* __NORLS */
/* __RLS */
#if __EDC_TARGET >= 0x41080000 /* */
__vsamEA : 1, /* */
__reserve2 : 4; /* */
#else
__reserve3 : 5; /* */
#endif

__device_t __device; /* */
unsigned long __blksize, /* */
__maxreclen; /* */
union { /* */
struct { /* */
unsigned short __vsam_type; /* */
unsigned long __vsam_keylen; /* */
unsigned long __vsam_RKP; /* */
} __vsam; /* */
#if __EDC_TARGET >= 0x41080000 /* */
struct { /* */
unsigned char __disk_access_method; /* */
unsigned char __disk_noseek_to_seek; /* */
long __disk_reserve[2]; /* */
} __disk;
#endif
} __device_specific;

char * __dsname; /* */
unsigned int __reserve4; /* */
};
typedef struct __fileData fldata_t;

Figure 29. fldata() structure Chapter 12. Performing VSAM I/O operations 187
 Notes:
1. If you have opened the file by its data set name, the filename is fully qualified,
including quotation marks. If you have opened the file by ddname, filename is
dd:ddname, without any quotation marks. The ddname is uppercase.
2. The __dsname field is filled in with the data set name. The __dsname value is
uppercase unless the asis option was specified on the fopen() or freopen()
function call.

188 z/OS V1R13.0 XL C/C++ Programming Guide

Chapter 13. Performing terminal I/O operations
This chapter describes how to use input and output interactively with a terminal
(using TSO or z/OS UNIX). Terminal I/O supports text, binary, and record I/O, in
undefined, variable and fixed-length formats, except that ASA format is not valid for
any text terminal files.

Note: You cannot use the z/OS XL C/C++ I/O functions for terminal I/O under
either IMS or CICS. Terminal I/O under CICS is supported through the CICS
command level interface.

This chapter describes C I/O stream functions as they can be used within C++
programs. If you want to use the C++ I/O stream classes instead, see Chapter 4,
Using the Standard C++ Library I/O Stream Classes, on page 21 for general
information. For more detailed information, see Standard C++ Library Reference,
which discusses the Standard C++ I/O stream classes.

Opening files
You can use the library functions fopen() or freopen() to open a file.

Using fopen() and freopen()

This section covers:
v Opening a file by data set name
v Opening a file by DD name
v fopen() and freopen() keywords
v Opening a terminal file under a shell

Opening a file by data set name

Files are opened with a call to fopen() or freopen() in the format
fopen("filename", "mode"). The first character of the filename must be an asterisk
(*).

z/OS UNIX Considerations: If you have specified POSIX(ON),

fopen("*file.data","r"); does not open a terminal file. Instead, it opens a file
called *file.data in the UNIX file system. To open a terminal file under POSIX, you
must specify two slashes before the asterisk, as follows:
fopen("//*file.data","r"):

Terminal files cannot be opened in update mode.

Terminal files opened in append mode are treated as if they were opened in write
mode.

Opening a file by DDname

The data set name that is associated with the DD statement must be an asterisk(*).
For example:
TSO ALLOC f(ddname) DA(*)
fopen("dd:ddname", "mode");

fopen() and freopen() keywords

The following table lists the keywords that are available on the fopen() and
freopen() functions, tells you which ones are useful for terminal I/O, and lists the
values that are valid for the applicable ones.

Copyright IBM Corp. 1996, 2012 189

 Table 29. Keywords for the fopen() and freopen() functions for terminal I/O
Parameter Allowed? Applicable? Notes
recfm= Yes Yes F, V, U and additional keywords A, B, S, M are
the valid values. A, B, S, and M are ignored.
lrecl= Yes Yes See below.
blksize= Yes Yes See below.
space= Yes No Has no effect for terminal I/O.
type= Yes Yes May be omitted. If you do specify it, type=record
is the only valid value.
acc= No No Not used for terminal I/O.
password= No No Not used for terminal I/O.
asis Yes No Has no effect for terminal I/O.
byteseek Yes No Has no effect for terminal I/O.
noseek Yes No Has no effect for terminal I/O.
OS Yes No Not used for terminal I/O.

recfm=
z/OS XL C/C++ allows you to specify any of the 27 possible RECFM types
(listed in Fixed-format records on page 10, Variable-format records on
page 13, and Undefined-format records on page 16). The default is
recfm=U. Any specification of ASA for the record format is ignored.
lrecl= and blksize=
The lrecl and blksize parameters allow you to set the record size and
block size, respectively. The maximum limits on lrecl values are as follows:
32771 For input z/OS variable terminals (data length of 32767)
32767 For input z/OS fixed and undefined terminals
32770 For output z/OS variable terminals (data length of 32766)
32766 For output z/OS fixed and undefined terminals
In fixed and undefined terminal files, blksize is always the size of lrecl. In
variable terminal files, blksize is always the size of lrecl plus 4 bytes. It is
not necessary to specify values for lrecl and blksize. If neither is
specified, the default values are used. The default lrecl sizes (not
including the extra 4 bytes in the lrecl of variable length types) are as
follows:
v Screen width for output terminals
v 1000 for input z/OS text terminals
v 254 for all other input terminals
space=
This parameter is accepted as an option for terminal I/O, but it is ignored. It
does not generate an error.
type=
type=record specifies that the file is to be opened for sequential record I/O.
The file must be opened as a binary file.
acc= This parameter is not valid for terminal I/O. If you specify it, your fopen()
call fails.

190 z/OS V1R13.0 XL C/C++ Programming Guide

 password=
This parameter is not valid for terminal I/O. If you specify it, your fopen()
call fails.
asis This parameter is accepted as an option for terminal I/O, but it is ignored. It
does not generate an error.
byteseek
This parameter is accepted as an option for terminal I/O, but it is ignored. It
does not generate an error.
noseek
This parameter is accepted as an option for terminal I/O, but it is ignored. It
does not generate an error.
OS This parameter is not valid for terminal I/O. If you specify it, your fopen()
call fails.

When you perform input and output in an interactive mode with the terminal, all
standard streams and all files with * as the first character of their names are
associated with the terminal. Output goes to the screen; input comes from the
keyboard.

An input EOF can be generated by a /* if you open a stream in text mode. If you
open the stream in binary or record mode, you can generate an EOF by entering a
null string.

ASA characters are not interpreted in terminal I/O.

Opening a terminal file under a shell

Files are opened with a call to fopen() in the format fopen("/dev/tty", "mode").

Buffering
z/OS XL C/C++ uses buffers to map byte-level I/O (data stored in records and
blocks) to system-level C I/O.

In terminal I/O, line buffering is always in effect.

The setvbuf() and setbuf() functions can be used to control buffering before any
read or write operation to the file. If you want to reset the buffering mode, you must
call setvbuf() or setbuf() before any other operation occurs on a file, because you
cannot change the buffering mode after an I/O operation to the file.

Reading from files

You can use the following library functions to read in information from terminal files;
see z/OS XL C/C++ Run-Time Library Reference for more information on these
library functions.
v fread()
v fread_unlocked()
v fgets()
v fgets_unlocked()
v gets()
v gets_unlocked()
v fgetc()
v fgetc_unlocked()
v getc()

Chapter 13. Performing terminal I/O operations 191

 v getc_unlocked()
v getchar()
v getchar_unlocked()
v scanf()
v scanf_unlocked()
v fscanf()
v fscanf_unlocked()
v vscanf()
v vscanf_unlocked()
v vfscanf()
v vfscanf_unlocked()

You can set up a SIGIOERR handler to catch read or write system errors. See
Chapter 18, Debugging I/O programs, on page 221 for more information.

A call to the rewind() function clears unread input data in the terminal buffer so that
on the next read request, the system waits for more user input.

With z/OS Language Environment, an empty record is considered EOF in binary

mode or record mode. This remains in effect until a rewind() or clearerr() is
issued. When the rewind() is issued, the buffer is cleared and reading can
continue.

Under TSO, the virtual line size of the terminal is used to determine the line length.

When reading from the terminal and the RECFM has been set to be F (for example,
by an ALLOCATE under TSO) in binary or record mode, the input is padded with
blanks to the record length.

On input, all terminal files opened for output flush their output, no matter what type
of file they are and whether a record is complete or not. This includes fixed terminal
files that would normally withhold output until a record is completed, as well as text
records that normally wait until a new-line or carriage return. In all cases, the data
is placed into one line with a blank added to separate output from different terminal
files. Fixed terminal files do not pad the output with blanks when flushing this way.

Note: This flush is not the same as a call to fflush(), because fixed terminal files
do not have incomplete records and text terminal files do not output until the
new-line or carriage return. This flush occurs only when actual input is required
from the terminal. When data is still in the buffer, that data is read without flushing
output terminal files.

Reading from binary files

This discussion includes reading from fixed binary files and from variable or
undefined binary files.

Reading from fixed binary files

v Any input that is smaller than the record length is padded with blanks to the
record length. The default record length is 254 bytes.
v The carriage return or new-line is not included as part of the data.
v An input line longer than the record length is returned to the calling program on
subsequent system reads.
For example, suppose a program requests 30 bytes of user input from an input
fixed binary terminal with record length 25. The full 30 bytes of user input returns
to satisfy the request, so that you do not need to enter a second line of input.

192 z/OS V1R13.0 XL C/C++ Programming Guide

 v An empty input line indicates EOF.

Reading from variable or undefined binary files

These files behave like fixed-length binary files, except that no padding is
performed if the input is smaller than the record length.

Reading from text files

This discussion includes reading from fixed text files and from variable or undefined
text files.

Reading from fixed text files

v The carriage return indicates the end of the record.
v A new-line character is added as part of the data to indicate the end of an input
line.
v If the input is larger than the record length, it is truncated to the record length.
The truncation causes SIGIOERR to be raised, if the default action for SIGIOERR is
not SIG_IGN.
v When an input line is smaller than the record length, it is not padded with blanks.
v The character sequence /* indicates that the end of the file has been reached.

Reading from variable or undefined text files

These files behave like fixed-length text files.

Reading from record I/O files

This discussion includes reading from fixed record I/O files and from variable or
undefined record I/O files.

Reading from fixed record I/O files

v Records smaller than the record length are padded with blanks up to the record
length. The default record length is 254 bytes.
v Input record terminal records have an implicit logical record boundary at the
record length if the input size exceeds the record length.
If you enter input data larger than the record length, each subsequent block of
record-length bytes from the user input satisfies successive read requests.
v The carriage return or new-line is not included as part of the data.
v An empty line indicates an EOF.

Reading from variable or undefined record I/O files

These files behave like fixed-length record files, except that no padding is
performed.

Writing to files
You can use the following library functions to write to a terminal file; see z/OS XL
C/C++ Run-Time Library Reference for more information on these library functions.
v fwrite()
v fwrite_unlocked()
v printf()
v printf_unlocked()
v fprintf()
v fprintf_unlocked()
v vprintf()
v vprintf_unlocked()

Chapter 13. Performing terminal I/O operations 193

 v vfprintf()
v vfprintf_unlocked()
v puts()
v puts_unlocked()
v fputs()
v fputs_unlocked()
v fputc()
v fputc_unlocked()
v putc()
v putc_unlocked()
v putchar()
v purchar_unlocked()

If no record length is specified for the output terminal file, it defaults to the virtual
line size of the terminal.

On output, records are written one line at a time up to the record length. For all
output terminal files, records are not truncated. If you are printing a long string, it
wraps around to another line.

Writing to binary files

This discussion includes writing to fixed binary files and to variable or undefined
binary files.

Writing to fixed binary files

v Output data is sent to the terminal when the last character of a record is written.
v When closing an output terminal, any unwritten data is padded to the record
length with blanks before it is flushed.

Writing to variable or undefined binary files

These files behave the same as fixed-length binary files, except that no padding
occurs for output that is smaller than the record length.

Writing to text files

The following control characters are supported:
\a Alarm. Causes the terminal to generate an audible beep.
\b Backspace. Backs up the output position by one byte. If you are at the start
of the record, you cannot back up to previous record, and backspace is
ignored.
\f Form feed. Sends any unwritten data to the terminal and clears the screen
if the environment variable _EDC_CLEAR_SCREEN is set. If the variable is not
set, the \f character is written to the screen.
\n New-line. Sends the preceding unwritten character to the terminal. If no
preceding data exists, it sends a single blank character.
\t Horizontal tab. Pads the output record with blanks up to the next tab stop
(set at eight characters).
\v Vertical tab. Placed in the output as is.
\r Carriage return. Treated as a new-line, sends preceding unwritten data to
the terminal.

194 z/OS V1R13.0 XL C/C++ Programming Guide

 Writing to fixed text files
v Lines that are longer than the record length are not truncated. They are split
across multiple lines, each LRECL bytes long. Subsequent writes begin on a new
line.
v Output data is sent to the terminal when one character more than the record
length is written, or when a \r, \n, or \f character is written. In the case of \f,
output is displayed only if the _EDC_CLEAR_SCREEN environment variable is set.
v No padding occurs on output when a record is smaller than the record length.

Writing to variable or undefined text files

These terminal files behave like fixed-length terminal files.

Writing to record I/O files

This discussion includes writing to fixed record I/O files and to variable or undefined
record I/O files.

Writing to fixed record I/O files

v Any output record that is smaller than the record length is padded to the record
length with blanks, and trailing blanks are displayed.
v If a record is longer than the record length, all data is written to the terminal,
wrapping at the record length.
v Output data is sent to the terminal with every record write.

Writing to variable or undefined record I/O files

These files behave like fixed-length record files except that no padding occurs when
the output record is smaller than the record length.

Flushing records
The action taken by the fflush() library function depends on the file mode. The
fflush() function only flushes buffers in binary files with Variable or Undefined
record format.

If you call one z/OS XL C/C++ program from another z/OS XL C/C++ program by
using the ANSI system() function, all open streams are flushed before control is
passed to the callee, and again before control is returned to the caller. If you are
running with POSIX(ON), a call to the POSIX system() function does not flush any
streams to the system.

Text streams
v Writing a new record:
Because a new-line character has not been encountered to indicate the
end-of-line, fflush() takes no action. The record is written as a new record
when one of the following takes place:
A new-line character is written.
The file is closed.
v Reading a record:
fflush() clears a previous ungetc() character.

Binary streams
v Writing a new record:

Chapter 13. Performing terminal I/O operations 195

 If the file is variable or undefined length in record format, fflush() causes the
current record to be written out, which in turn causes a new record to be created
for subsequent writes. If the file is of fixed record length, no action is taken.
v Reading a record:
fflush() clears a previous ungetc() character.

Record I/O
v Writing a new record: fflush() takes no action.
v Reading a record: fflush() takes no action.

Repositioning within files

In terminal I/O, rewind() is the only positioning library function available. Using the
library functions fseek(), fgetpos(), fsetpos(), and ftell() generates an error.
See z/OS XL C/C++ Run-Time Library Reference for more information on these
library functions.

When an input terminal reaches an EOF, the rewind() function:

1. Clears the EOF condition.
2. Enables the terminal to read again.

You can also use rewind() when reading from the terminal to flush out your record
buffer for that stream.

Closing files
Use the fclose() library function to close a file. z/OS XL C/C++ automatically
closes files on normal program termination and attempts to do so under abnormal
program termination or abend. When closing a fixed binary terminal, z/OS XL
C/C++ pads the last record with blanks if it is incomplete.

See z/OS XL C/C++ Run-Time Library Reference for more information on this
library function.

fldata() behavior
The format of the fldata() function is as follows:
The fldata() function is used to retrieve information about an op