z/OSVersion 2 Release 3

XL C/C++Programming Guide

IBM

SC14-7315-30

Note

Before using this information and the product it supports, read the information in “Notices” on page1129.

This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modifications untilotherwise indicated in new editions.

Last updated: 2019-06-26© Copyright International Business Machines Corporation 1996, 2017.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

Figures............................................................................................................. xxiii

Tables.............................................................................................................. xxxv

About this document............................................................................................liiiRelated z/OS XL C/C++ information.......................................................................................................... lxiiWhere to find more information................................................................................................................ lxii

z/OS Basic Skills in IBM Knowledge Center........................................................................................ lxiiHow to send your comments to IBM........................................................................................................lxiii

If you have a technical problem......................................................................................................... lxiii

What's new for z/OS V2R3 XL C/C++....................................................................lxv

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............................................................................. 7Types of C and C++ input and output.....................................................................................................7

Text streams......................................................................................................................................7Binary streams.................................................................................................................................. 8Record I/O......................................................................................................................................... 8Blocked I/O....................................................................................................................................... 8

Chapter 3. Understanding models of C I/O...............................................................................................11The record model for C I/O.................................................................................................................. 11

Record formats............................................................................................................................... 11The byte stream model for C I/O......................................................................................................... 19

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

Chapter 4. Using the Standard C++ Library I/O Stream Classes.............................................................. 21Advantages to using the C++ I/O stream classes................................................................................21Predefined streams for C++................................................................................................................. 21How C++ I/O streams relate to C I/O streams.................................................................................... 22Mixing the Standard C++ I/O stream classes, USL I/O stream class library, and C I/O library

functions..........................................................................................................................................22Specifying file attributes...................................................................................................................... 22

Chapter 5. Opening files............................................................................................................................ 23Prototypes of functions........................................................................................................................ 23Categories of I/O.................................................................................................................................. 25Specifying what kind of file to use....................................................................................................... 26

OS files............................................................................................................................................ 26UNIX file system files......................................................................................................................26VSAM data sets............................................................................................................................... 26Terminal files...................................................................................................................................26Memory files and hiperspace memory files................................................................................... 27

iii

CICS data queues........................................................................................................................... 27z/OS Language Environment Message file..................................................................................... 28How to specify RECFM, LRECL, and BLKSIZE................................................................................ 28fopen() defaults...............................................................................................................................29DDnames.........................................................................................................................................31

Avoiding Undesirable Results when Using I/O.................................................................................... 32How z/OS XL C/C++ determines what kind of file to open..................................................................33

Under TSO, MVS batch, IMS — POSIX(ON).................................................................................... 33Under TSO, MVS batch, IMS — POSIX(OFF)...................................................................................36Under CICS......................................................................................................................................37

Chapter 6. Buffering of C streams............................................................................................................. 39

Chapter 7. Using ASA text files..................................................................................................................41Example of writing to an ASA file.........................................................................................................41ASA file control..................................................................................................................................... 42

Chapter 8. z/OS XL C Support for the double-byte character set.............................................................45Opening files.........................................................................................................................................46Reading streams and files....................................................................................................................46Writing streams and files......................................................................................................................47

Writing text streams........................................................................................................................48Writing binary streams....................................................................................................................49

Flushing buffers....................................................................................................................................49Flushing text streams..................................................................................................................... 49Flushing binary streams................................................................................................................. 50ungetwc() considerations............................................................................................................... 50

Setting positions within files................................................................................................................ 50Repositioning within text streams..................................................................................................50Repositioning within binary streams..............................................................................................51ungetwc() considerations............................................................................................................... 51

Closing files.......................................................................................................................................... 51Manipulating wide character array functions...................................................................................... 52

Chapter 9. Using C and C++ standard streams and redirection............................................................... 53Default open modes............................................................................................................................. 54Interleaving the standard streams with sync_with_stdio()................................................................ 55Interleaving the standard streams without sync_with_stdio()........................................................... 56Redirecting standard streams..............................................................................................................58Redirecting streams from the command line...................................................................................... 58

Using the redirection symbols........................................................................................................59Assigning the standard streams.......................................................................................................... 60Using the freopen() library function.....................................................................................................60Redirecting streams with the MSGFILE option....................................................................................60

MSGFILE considerations................................................................................................................ 60Redirecting streams under z/OS.......................................................................................................... 61

Under MVS batch............................................................................................................................ 62Under TSO....................................................................................................................................... 63Under IMS....................................................................................................................................... 64Under CICS......................................................................................................................................64

Passing C and C++ standard streams across a system() call..............................................................64Passing binary streams...................................................................................................................65Passing text streams.......................................................................................................................65Passing record I/O streams............................................................................................................ 67Passing blocked I/O streams..........................................................................................................67

Using global standard streams............................................................................................................ 67Command line redirection.............................................................................................................. 69Direct assignment........................................................................................................................... 70

iv

freopen()..........................................................................................................................................70MSGFILE() runtime option.............................................................................................................. 70fclose()............................................................................................................................................ 70File position and visible data.......................................................................................................... 70C++ I/O stream library.................................................................................................................... 70

Chapter 10. Performing OS I/O operations...............................................................................................71Opening files.........................................................................................................................................71

Using fopen() or freopen().............................................................................................................. 71Generation data group I/O..............................................................................................................74Regular and extended partitioned data sets..................................................................................76Partitioned and sequential concatenated data sets...................................................................... 78In-stream data sets........................................................................................................................ 79SYSOUT data sets........................................................................................................................... 80Tapes............................................................................................................................................... 80Multivolume data sets.................................................................................................................... 81Striped data sets.............................................................................................................................81Large format sequential data sets..................................................................................................81Other devices.................................................................................................................................. 82Access method selection................................................................................................................82fopen() and freopen() parameters..................................................................................................83

Buffering............................................................................................................................................... 86Multiple buffering............................................................................................................................87

DCB (Data Control Block) attributes.................................................................................................... 87Reading from files.................................................................................................................................89

Reading from binary files................................................................................................................90Reading from text files....................................................................................................................90Reading from record I/O files......................................................................................................... 91Reading from blocked I/O files.......................................................................................................91

Writing to files.......................................................................................................................................91Writing to binary files......................................................................................................................92Writing to text files..........................................................................................................................92Writing to record I/O files............................................................................................................... 95Writing to blocked I/O files.............................................................................................................95

Flushing buffers....................................................................................................................................96Updating existing records...............................................................................................................96Reading updated records............................................................................................................... 97Writing new records........................................................................................................................97ungetc() considerations.................................................................................................................. 98

Repositioning within files..................................................................................................................... 98ungetc() considerations................................................................................................................100How long fgetpos() and ftell() values last.................................................................................... 100Using fseek() and ftell() in binary files......................................................................................... 100Using fseek() and ftell() in text files (ASA and Non-ASA)............................................................ 101Using fseek() and ftell() in record files......................................................................................... 102Using fseek() and ftell() in blocked files.......................................................................................102Porting old C code that uses fseek() or ftell().............................................................................. 102

Closing files........................................................................................................................................ 103Renaming and removing files.............................................................................................................105fldata() behavior................................................................................................................................. 105

Chapter 11. Performing z/OS UNIX file system I/O operations............................................................. 109Creating files.......................................................................................................................................109

Regular files.................................................................................................................................. 109Link and symbolic link files...........................................................................................................110Directory files................................................................................................................................110Character special files.................................................................................................................. 110FIFO files.......................................................................................................................................110

v

Opening files.......................................................................................................................................110Using fopen() or freopen()............................................................................................................ 111

Reading from z/OS UNIX file system files......................................................................................... 114Opening and reading from z/OS UNIX file system directory files.....................................................115Writing to z/OS UNIX file system files............................................................................................... 115Flushing records.................................................................................................................................116Setting positions within files..............................................................................................................116Closing files........................................................................................................................................ 117Deleting files.......................................................................................................................................117Pipe I/O...............................................................................................................................................117

Using unnamed pipes................................................................................................................... 117Using named pipes....................................................................................................................... 118Character special file I/O..............................................................................................................121

Low-level z/OS UNIX I/O....................................................................................................................122Example of z/OS UNIX file system I/O functions.............................................................................. 122fldata() behavior................................................................................................................................. 126File tagging and conversion............................................................................................................... 127Access control lists (ACLs).................................................................................................................128

Chapter 12. Performing VSAM I/O operations........................................................................................129VSAM types (data set organization)...................................................................................................129

Access method services...............................................................................................................130Choosing VSAM data set types.......................................................................................................... 130

Keys, RBAs and RRNs................................................................................................................... 132Summary of VSAM I/O operations............................................................................................... 133

Opening VSAM data sets....................................................................................................................134Using fopen() or freopen()............................................................................................................ 134Buffering....................................................................................................................................... 138

Record I/O in VSAM............................................................................................................................138RRDS record structure..................................................................................................................139Reading record I/O files................................................................................................................139Writing to record I/O files............................................................................................................. 140Updating record I/O files.............................................................................................................. 141Deleting records............................................................................................................................142Repositioning within record I/O files........................................................................................... 142Flushing buffers............................................................................................................................ 144Summary of VSAM record I/O operations....................................................................................144

VSAM record level sharing and transactional VSAM......................................................................... 145Error reporting.............................................................................................................................. 146

VSAM extended addressability.......................................................................................................... 147Text and binary I/O in VSAM.............................................................................................................. 148

Reading from text and binary I/O files......................................................................................... 148Writing to and updating text and binary I/O files.........................................................................148Deleting records in text and binary I/O files................................................................................ 149Repositioning within text and binary I/O files..............................................................................149Flushing buffers............................................................................................................................ 150Summary of VSAM text I/O operations........................................................................................ 151Summary of VSAM binary I/O operations.................................................................................... 151

Closing VSAM data sets......................................................................................................................152VSAM return codes.............................................................................................................................153VSAM examples..................................................................................................................................153

KSDS example...............................................................................................................................153RRDS example.............................................................................................................................. 161

fldata() behavior................................................................................................................................. 163

Chapter 13. Performing terminal I/O operations....................................................................................165Opening files.......................................................................................................................................165

Using fopen() and freopen()......................................................................................................... 165

vi

Buffering....................................................................................................................................... 167Reading from files.............................................................................................................................. 167

Reading from binary files..............................................................................................................168Reading from text files..................................................................................................................169Reading from record I/O files....................................................................................................... 169

Writing to files.................................................................................................................................... 169Writing to binary files....................................................................................................................170Writing to text files........................................................................................................................170Writing to record I/O files............................................................................................................. 171

Flushing records.................................................................................................................................171Text streams................................................................................................................................. 171Binary streams..............................................................................................................................171Record I/O.....................................................................................................................................172

Repositioning within files...................................................................................................................172Closing files........................................................................................................................................ 172fldata() behavior................................................................................................................................. 172

Chapter 14. Performing memory file and hiperspace I/O operations....................................................175Using hiperspace operations............................................................................................................. 175Opening files.......................................................................................................................................175

Using fopen() or freopen()............................................................................................................ 176Simulating partitioned data sets.................................................................................................. 179Buffering....................................................................................................................................... 181

Reading from files.............................................................................................................................. 181Writing to files.................................................................................................................................... 182Flushing records.................................................................................................................................183

ungetc() considerations................................................................................................................183Repositioning within files...................................................................................................................183Closing files........................................................................................................................................ 184

Performance tips.......................................................................................................................... 184Removing memory files..................................................................................................................... 184fldata() behavior................................................................................................................................. 184Example program............................................................................................................................... 185

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

Chapter 16. Language Environment Message file operations................................................................189Opening files.......................................................................................................................................189Reading from files.............................................................................................................................. 189Writing to files.................................................................................................................................... 189Flushing buffers..................................................................................................................................190Repositioning within files...................................................................................................................190Closing files........................................................................................................................................ 190

Chapter 17. CELQPIPI MSGRTN file operations..................................................................................... 191Opening files.......................................................................................................................................191Reading from files.............................................................................................................................. 191Writing to files.................................................................................................................................... 191Flushing buffers..................................................................................................................................191Repositioning within files...................................................................................................................191Closing files........................................................................................................................................ 191fldata() behavior................................................................................................................................. 192fldata() example................................................................................................................................. 192

Chapter 18. Debugging I/O programs.....................................................................................................195Using the __amrc structure............................................................................................................... 195Using the __amrc2 structure............................................................................................................. 198Using __last_op codes....................................................................................................................... 199

vii

Using the SIGIOERR signal................................................................................................................ 202File I/O trace.......................................................................................................................................204Locating the file I/O trace.................................................................................................................. 205

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

Chapter 19. Using Linkage Specifications in C or C++............................................................................209Syntax for Linkage in C or C++........................................................................................................... 209

Syntax for Linkage in C................................................................................................................. 209Syntax for Linkage in C++............................................................................................................. 209

Kinds of Linkage used by C or C++ Interlanguage Programs............................................................210Using Linkage Specifications in C++.................................................................................................. 212

Chapter 20. Combining C or C++ and Assembler programs...................................................................215Establishing the z/OS XL C/C++ environment................................................................................... 215Specifying linkage for C or C++ to Assembler................................................................................... 215Parameter lists for OS linkage........................................................................................................... 216XPLINK Assembler.............................................................................................................................217Using standard macros...................................................................................................................... 218

Non-XPLINK assembler prolog.................................................................................................... 219Non-XPLINK assembler epilog.....................................................................................................220XPLINK Assembler prolog............................................................................................................ 220XPLINK Call...................................................................................................................................221XPLINK Assembler epilog............................................................................................................ 223Accessing automatic memory in the non-XPLINK stack.............................................................223

Calling C code from Assembler — C example....................................................................................224Calling runtime library routines from Assembler — C++ example....................................................225Register content at entry to a non-XPLINK ASM routine using OS linkage...................................... 226Register content at exit from a non-XPLINK ASM routine to z/OS XL C/C++................................... 227Retaining the C environment using preinitialization......................................................................... 227

Setting up the interface for preinitializable programs.................................................................228Preinitializing a C program............................................................................................................231Multiple preinitialization compatibility interface C environments.............................................. 237Using the service vector and associated routines....................................................................... 239

Part 4. Coding: Advanced Topics........................................................................ 245

Chapter 21. Building and using Dynamic Link Libraries (DLLs)..............................................................247Support for DLLs.................................................................................................................................247DLL concepts and terms.....................................................................................................................248Loading a DLL..................................................................................................................................... 248

Loading a DLL implicitly................................................................................................................ 249Loading a DLL explicitly................................................................................................................ 249

Managing the use of DLLs when running DLL applications............................................................... 254Loading DLLs.................................................................................................................................254Sharing DLLs................................................................................................................................. 255Freeing DLLs................................................................................................................................. 256

Creating a DLL or a DLL application................................................................................................... 256Building a simple DLL.........................................................................................................................256

Example of building a simple C DLL............................................................................................. 256Example of building a simple C++ DLL.........................................................................................257Compiling your code..................................................................................................................... 258Binding your code......................................................................................................................... 258

Building a simple DLL application......................................................................................................259Steps for using an implicitly loaded DLL in your simple DLL application....................................259

Creating and using DLLs.....................................................................................................................261DLL restrictions.................................................................................................................................. 262

viii

Improving performance ...............................................................................................................264

Chapter 22. Building complex DLLs........................................................................................................ 267Rules for compiling source code with XPLINK.................................................................................. 268

XPLINK applications.....................................................................................................................268Non-XPLINK applications.............................................................................................................268

Compatibility issues between DLL and non-DLL code...................................................................... 270Pointer assignment.......................................................................................................................271Function pointers..........................................................................................................................272

DLL function pointer call in non-DLL code.........................................................................................273C example .................................................................................................................................... 274Non-DLL function pointer call in DLL(CBA) code......................................................................... 276Non-DLL function pointer call in DLL code...................................................................................278Function pointer comparison in non-DLL code............................................................................279Function pointer comparison in DLL code................................................................................... 281

Using DLLs that call each other......................................................................................................... 283

Chapter 23. z/OS 64-bit environment.....................................................................................................289Differences between the ILP32 and LP64 environments................................................................. 289

ILP32 and LP64 addressing capabilities......................................................................................289ILP32 and LP64 data models and data type sizes...................................................................... 289

Advantages and disadvantages of the LP64 environment................................................................290LP64 application performance and program size........................................................................290LP64 restrictions...........................................................................................................................291

Migrating applications from ILP32 to LP64.......................................................................................291When to migrate applications to LP64.........................................................................................291Checklist for ILP32-to-LP64 pre-migration activities................................................................. 291Checklist for ILP32-to-LP64 post-migration activities................................................................292

Using compiler diagnostics to ensure portability of code.................................................................292Using the INFO option to ensure that numbers are suffixed.......................................................293Using the WARN64 option to identify potential portability problems........................................ 294

ILP32-to-LP64 portability issues...................................................................................................... 294IPA(LINK) option and exploitation of 64-bit virtual memory...................................................... 295Availability of suboptions............................................................................................................. 295Potential changes in structure size and alignment......................................................................295Data type assignment differences under ILP32 and LP64..........................................................300Pointer declarations when 32-bit and 64-bit applications share header files........................... 304Potential pointer corruption......................................................................................................... 304Potential loss of data in constant expressions............................................................................ 306Data alignment problems when structures are shared............................................................... 307Portability issues with unsuffixed numbers.................................................................................308Using a LONG_MAX macro in a printf subroutine........................................................................ 309

Programming for portability between ILP32 and LP64.................................................................... 310Using header files to provide type definitions............................................................................. 310Using suffixes and explicit types to prevent unexpected behavior.............................................311Defining pad members to avoid data alignment problems......................................................... 311Using prototypes to avoid debugging problems.......................................................................... 312Using a conditional compiler directive for preprocessor macro selection..................................312Using converters under ILP32 or LP64........................................................................................ 313Using locales under ILP32 or LP64..............................................................................................313

Chapter 24. Using threads in z/OS UNIX applications........................................................................... 315Models and requirements.................................................................................................................. 315

Functions...................................................................................................................................... 315Creating a thread.......................................................................................................................... 315Synchronization primitives........................................................................................................... 316Thread-specific data.....................................................................................................................320Signals...........................................................................................................................................321

ix

Generating a signal....................................................................................................................... 322Thread cancellation...................................................................................................................... 322Cleanup for threads...................................................................................................................... 324Thread stack attributes................................................................................................................ 325

Behaviors and restrictions in z/OS UNIX applications...................................................................... 325Using threads with MVS files........................................................................................................ 325Multithreaded I/O......................................................................................................................... 326Thread-scoped functions............................................................................................................. 326Unsafe thread functions............................................................................................................... 327Fetched functions and writable statics........................................................................................327MTF and z/OS UNIX threading..................................................................................................... 327Thread queuing function.............................................................................................................. 327Thread scheduling........................................................................................................................ 327iconv() family of functions............................................................................................................ 328Threads and recoverable resources.............................................................................................328MEMLIMIT for 64bit multi-threaded applications.......................................................................328

Chapter 25. Reentrancy in z/OS XL C/C++..............................................................................................329Natural or constructed reentrancy.................................................................................................... 330

Limitations of constructed reentrancy for C programs................................................................330Controlling external static in C programs.......................................................................................... 330

Controlling writable strings.......................................................................................................... 331Controlling the memory area in C++............................................................................................ 332

Controlling where string literals exist in C++ code............................................................................332Using writable static in Assembler code........................................................................................... 333

Chapter 26. Using decimal data types in C............................................................................................. 335Decimal data type declarations......................................................................................................... 335

Declaring fixed-point decimal constants..................................................................................... 335Declaring decimal variables......................................................................................................... 336

Defining decimal-type constants.......................................................................................................337Using operators on decimal data types.............................................................................................337

Arithmetic operators.................................................................................................................... 338Assignment operators.................................................................................................................. 340Unary operators............................................................................................................................ 340Summary of operators used with decimal types......................................................................... 342

Converting decimal types.................................................................................................................. 342Converting decimal types to decimal types.................................................................................342Converting decimal types to and from integer types...................................................................344Converting decimal data types to and from floating-point data types....................................... 345

Calling functions with decimal data types.........................................................................................346Using library functions....................................................................................................................... 346

Using variable arguments with decimal data types.....................................................................346Formatting input and output operations with decimal data types................................................... 346Validating decimal values.................................................................................................................. 347Fixing sign variables........................................................................................................................... 347Returning decimal absolute values................................................................................................... 347Programming examples..................................................................................................................... 348Decimal exception handling...............................................................................................................351

printf() and scanf() and format validation.................................................................................... 352Additional considerations.............................................................................................................352Error messages............................................................................................................................. 352Decimal exceptions and Assembler interlanguage calls.............................................................353

Chapter 27. IEEE Floating-Point ............................................................................................................ 355Floating-point numbers..................................................................................................................... 355C/C++ compiler support.....................................................................................................................356Using IEEE floating-point...................................................................................................................356

x

Chapter 28. Handling error conditions, exceptions, and signals............................................................361Handling C software exceptions under C++...................................................................................... 361Handling hardware exceptions under C++........................................................................................ 362Tracebacks under C++....................................................................................................................... 362AMODE 64 exception handlers.......................................................................................................... 364

Scope and nesting of exception handlers.................................................................................... 365Handling exceptions..................................................................................................................... 365

Signal handlers...................................................................................................................................366Handling signals with POSIX(OFF) using signal() and raise()......................................................366Handling signals using Language Environment callable services............................................... 366Handling signals using z/OS UNIX with POSIX(ON).................................................................... 367Asynchronous signal delivery under z/OS UNIX..........................................................................369C signal handling features under z/OS XL C/C++.........................................................................370

Chapter 29. Network communications under UNIX System Services................................................... 381Understanding z/OS UNIX sockets and internetworking..................................................................381Basics of network communication.................................................................................................... 381

Transport protocols for sockets................................................................................................... 382What is a socket?................................................................................................................................382

z/OS UNIX Socket families........................................................................................................... 384z/OS UNIX Socket types............................................................................................................... 384Guidelines for using socket types................................................................................................ 384Addressing within sockets............................................................................................................385

The conversation................................................................................................................................387The server perspective................................................................................................................. 387The client perspective.................................................................................................................. 389A typical TCP socket session........................................................................................................389

A typical UDP socket session.............................................................................................................390Locating the server's port.................................................................................................................. 391Network application example............................................................................................................391Using common INET.......................................................................................................................... 397Compiling and binding....................................................................................................................... 397Using TCP/IP APIs..............................................................................................................................398

Restrictions for using z/OS TCP/IP API with z/OS UNIX..............................................................399Using z/OS UNIX sockets................................................................................................................... 400

Compiling under MVS batch for Berkeley sockets.......................................................................401Compiling under MVS batch for X/Open sockets.........................................................................402

Understanding the X/Open Transport Interface (XTI)...................................................................... 403Transport endpoints..................................................................................................................... 403Transport providers for X/Open Transport Interface...................................................................403General restrictions for z/OS UNIX.............................................................................................. 403

Chapter 30. Interprocess communication using z/OS UNIX..................................................................405Message queues.................................................................................................................................405Semaphores....................................................................................................................................... 405Shared memory..................................................................................................................................406Memory mapping............................................................................................................................... 406TSO commands from a shell.............................................................................................................. 406

Chapter 31. Using templates in C++ programs.......................................................................................407Using the TEMPINC compiler option................................................................................................. 407

TEMPINC example........................................................................................................................408Regenerating the template instantiation file............................................................................... 411TEMPINC considerations for shared libraries..............................................................................411

Using the TEMPLATEDEPTH compiler option....................................................................................411Using the TEMPLATEREGISTRY compiler option.............................................................................. 411

Recompiling related compilation units........................................................................................ 411

xi

Switching from TEMPINC to TEMPLATEREGISTRY..................................................................... 412Using explicit instantiation declarations (C++11 only)..................................................................... 412

Examples of explicit instantiation declarations...........................................................................413

Chapter 32. Using environment variables...............................................................................................415Working with environment variables................................................................................................. 421

Naming conventions..................................................................................................................... 422Environment variables specific to the z/OS XL C/C++ library........................................................... 423

_CEE_CONDWAIT_PAUSE............................................................................................................ 424_CEE_DLLLOAD_XPCOMPAT........................................................................................................ 424_CEE_DMPTARG........................................................................................................................... 425_CEE_ENVFILE..............................................................................................................................426_CEE_ENVFILE_COMMENT.......................................................................................................... 426_CEE_ENVFILE_CONTINUATION................................................................................................. 427_CEE_ENVFILE_S..........................................................................................................................427_CEE_HEAP_MANAGER................................................................................................................ 428_CEE_REALLOC_CONTROL...........................................................................................................428_CEE_RUNOPTS............................................................................................................................430_EDC_ADD_ERRNO2.................................................................................................................... 431_EDC_ANSI_OPEN_DEFAULT.......................................................................................................432_EDC_AUTOCVT_BINARY............................................................................................................ 432_EDC_BYTE_SEEK........................................................................................................................ 433_EDC_CLEAR_SCREEN................................................................................................................. 433_EDC_COMPAT..............................................................................................................................433_EDC_CONTEXT_GUARD.............................................................................................................. 434_EDC_C99_NAN............................................................................................................................434_EDC_DLL_DIAG.......................................................................................................................... 434_EDC_EOVERFLOW.......................................................................................................................435_EDC_ERRNO_DIAG..................................................................................................................... 436_EDC_FLUSH_STDOUT_PIPE....................................................................................................... 436_EDC_FLUSH_STDOUT_SOCKET..................................................................................................437_EDC_GLOBAL_STREAMS............................................................................................................ 437_EDC_IEEEV1_COMPATIBILITY_ENV..........................................................................................438_EDC_IO_ABEND..........................................................................................................................439_EDC_IO_TRACE...........................................................................................................................440_EDC_OPEN_CONCAT...................................................................................................................441_EDC_POPEN................................................................................................................................442_EDC_PTHREAD_YIELD................................................................................................................442_EDC_PTHREAD_YIELD_MAX...................................................................................................... 442_EDC_PUTENV_COPY................................................................................................................... 443_EDC_RRDS_HIDE_KEY............................................................................................................... 444_EDC_SIG_DFLT........................................................................................................................... 444_EDC_STOR_INCREMENT............................................................................................................444_EDC_STOR_INCREMENT_B........................................................................................................444_EDC_STOR_INITIAL................................................................................................................... 445_EDC_STOR_INITIAL_B...............................................................................................................445_EDC_STRPTM_STD..................................................................................................................... 445_EDC_SUSV3.................................................................................................................................445_EDC_UMASK_DFLT..................................................................................................................... 446_EDC_ZERO_RECLEN................................................................................................................... 446

Propagating environment variables...................................................................................................447

Chapter 33. Using hardware built-in functions.......................................................................................449General instructions...........................................................................................................................449

PLO - Perform Locked Operation available in ARCH(5)............................................................... 473Decimal instructions.......................................................................................................................... 479Floating-point support instructions...................................................................................................484Decimal floating-point built-in functions...........................................................................................485

xii

Macros for use with decimal floating-point built-in functions.................................................... 493Hexadecimal floating-point instructions........................................................................................... 495Binary floating-Point instructions......................................................................................................497Built-in functions for transaction execution......................................................................................499

Chapter 34. Using runtime check library..............................................................................................503

Chapter 35. Using vector programming support.................................................................................... 505Options............................................................................................................................................... 505Macro..................................................................................................................................................505Vector data types............................................................................................................................... 505Language extensions..........................................................................................................................507

Vector literals................................................................................................................................507Initialization of vectors.................................................................................................................510typedef definitions for vector types............................................................................................. 511Pointers......................................................................................................................................... 511Unary expressions........................................................................................................................ 511Binary expressions....................................................................................................................... 513Cast expressions...........................................................................................................................533Compound literal expressions......................................................................................................533Other extensions for vector types................................................................................................533

Vector built-in functions.....................................................................................................................533Header file.....................................................................................................................................534Summary of vector built-in functions...........................................................................................534Arithmetic..................................................................................................................................... 542Compare........................................................................................................................................560Compare Ranges...........................................................................................................................568Find Any Element..........................................................................................................................578Gather and Scatter........................................................................................................................586Generate Mask..............................................................................................................................593Copy until Zero..............................................................................................................................594Load and Store..............................................................................................................................595Logical........................................................................................................................................... 599Merge............................................................................................................................................ 604Pack and Unpack.......................................................................................................................... 606Replicate....................................................................................................................................... 611Rotate and Shift............................................................................................................................ 614Rounding and Conversion.............................................................................................................621Test................................................................................................................................................626All Predicates................................................................................................................................628Any Predicates.............................................................................................................................. 634Defining vector built-in functions from operators................................................................... 641Deprecated vector built-in functions........................................................................................... 641

Chapter 36. ANSI C/C++ 98 applications and C99.................................................................................665Obtaining C99 behavior with XL C..................................................................................................... 665Using C99 functions in XL C++ applications......................................................................................665

Feature test macros that control C99 interfaces in XL C++ applications................................... 665Using C99 functions in C++ applications when ambiguous definitions exist............................. 666

Chapter 37. Writing applications for Single UNIX Specification, Version 3........................................... 667Announcing your intentions............................................................................................................... 667Testing the environment ................................................................................................................... 668What is different in SUSv3................................................................................................................. 669Symbols withdrawn in SUSv3............................................................................................................ 669Candidates for removal in a future version....................................................................................... 669Implementation compliance............................................................................................................. 670

xiii

Chapter 38. Saved compile-time options information........................................................................... 671Saved options information layout......................................................................................................671

Part 5. Performance optimization.......................................................................677

Chapter 39. Improving program performance........................................................................................679Writing code for performance............................................................................................................ 679Using C++ constructs in performance-critical code..........................................................................679Using explicit instantiation declarations (C++11 only)..................................................................... 681ANSI aliasing rules............................................................................................................................. 681Using ANSI aliasing rules...................................................................................................................683Using variables................................................................................................................................... 684Passing function arguments...............................................................................................................685Coding expressions............................................................................................................................ 686Coding conversions............................................................................................................................ 686Arithmetical considerations...............................................................................................................687Using loops and control constructs................................................................................................... 687Choosing a data type..........................................................................................................................688Using library extensions.....................................................................................................................689Using #pragmas................................................................................................................................. 690Using rvalue references (C++11).......................................................................................................691Using shared-memory parallelism (SMP)..........................................................................................694

Chapter 40. Using built-in functions to improve performance...............................................................695__builtin_expect.................................................................................................................................696Platform-specific functions................................................................................................................696Examples............................................................................................................................................ 697

Chapter 41. I/O Performance considerations.........................................................................................699Accessing MVS data sets................................................................................................................... 699Accessing UNIX file system files....................................................................................................... 700Using memory files.............................................................................................................................701Using the C++ I/O stream libraries.................................................................................................... 701

Chapter 42. Improving performance with compiler options..................................................................703Using the OPTIMIZE option............................................................................................................... 703

Optimizations performed by the compiler................................................................................... 703Aggressive optimizations with OPTIMIZE(3)...............................................................................704The xlc utility optimization option levels..................................................................................... 705

Using the ARCHITECTURE and TUNE options...................................................................................706Inlining................................................................................................................................................707

Selectively marking code to inline............................................................................................... 708Automatically choosing functions to inline..................................................................................708Modifying automatic inlining choices...........................................................................................709Overriding inlining defaults.......................................................................................................... 710Inlining under IPA.........................................................................................................................710

Using the XPLINK option....................................................................................................................710When you should not use XPLINK................................................................................................710

Using the HOT option......................................................................................................................... 711Using the IPA option.......................................................................................................................... 711

Types of procedural analysis........................................................................................................711Program-directed feedback......................................................................................................... 712Compiler processing flow............................................................................................................. 713

Additional options that affect performance...................................................................................... 718ANSIALIAS....................................................................................................................................718AGGRCOPY....................................................................................................................................718

xiv

ASSERT(RESTRICT)...................................................................................................................... 718COMPRESS....................................................................................................................................718COMPACT...................................................................................................................................... 718CVFT (C++ only)............................................................................................................................ 718EXH (C++ only)..............................................................................................................................718EXPORTALL................................................................................................................................... 718FLOAT............................................................................................................................................ 718HGPR.............................................................................................................................................719IGNERRNO....................................................................................................................................719LANGLVL(NOCHECKPLACEMENTNEW)....................................................................................... 719LIBANSI......................