z/OSVersion 2 Release 4

XL C/C++Programming Guide

IBM

SC14-7315-40

Note

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

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

Last updated: 2019-09-10© Copyright International Business Machines Corporation 1996, 2019.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 V2R4 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..................................................................................................82Other devices.................................................................................................................................. 82Access method selection................................................................................................................83fopen() and freopen() parameters..................................................................................................83

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

DCB (Data Control Block) attributes.................................................................................................... 88Reading from files................................................................................................................................ 90

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

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

Flushing buffers....................................................................................................................................96Updating existing records...............................................................................................................96Reading updated records............................................................................................................... 96Writing 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 64-bit multithreaded 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.......................................................................................................................... 396Compiling 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...............................................................................................................443_EDC_STOR_INCREMENT............................................................................................................444_EDC_STOR_INCREMENT_B....................................................................................................... 444_EDC_STOR_INITIAL................................................................................................................... 444_EDC_STOR_INITIAL_B...............................................................................................................445_EDC_STRPTM_STD..................................................................................................................... 445_EDC_SUSV3................................................................................................................................ 445_EDC_UMASK_DFLT.....................................................................................................................446_EDC_ZERO_RECLEN...................................................................................................................446

Propagating environment variables...................................................................................................446

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

PLO - Perform Locked Operation available in ARCH(5)...............................................................475Decimal instructions.......................................................................................................................... 481Floating-point support instructions...................................................................................................486Decimal floating-point built-in functions.......................................................................................... 487

Macros for use with decimal floating-point built-in functions.................................................... 495

xii

Hexadecimal floating-point instructions...........................................................................................497Binary floating-Point instructions......................................................................................................498Built-in functions for transaction execution......................................................................................501

Chapter 34. Using runtime check library..............................................................................................505

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

Vector literals................................................................................................................................509Initialization of vectors.................................................................................................................512typedef definitions for vector types............................................................................................. 513Pointers.........................................................................................................................................513Unary expressions........................................................................................................................ 513Binary expressions....................................................................................................................... 515Cast expressions...........................................................................................................................535Compound literal expressions..................................................................................................... 535Other extensions for vector types................................................................................................535

Vector built-in functions.................................................................................................................... 536Header file.....................................................................................................................................536Summary of vector built-in functions.......................................................................................... 536Arithmetic..................................................................................................................................... 544Compare........................................................................................................................................563Compare Ranges...........................................................................................................................571Find Any Element..........................................................................................................................581Gather and Scatter........................................................................................................................589Generate Mask..............................................................................................................................596Copy until Zero..............................................................................................................................597Load and Store..............................................................................................................................598Logical........................................................................................................................................... 602Merge............................................................................................................................................ 607Pack and Unpack.......................................................................................................................... 609Replicate....................................................................................................................................... 614Reverse......................................................................................................................................... 617Rotate and Shift............................................................................................................................ 618Rounding and Conversion.............................................................................................................628String Search.................................................................................................................................634Test............................................................................................................................................... 635All Predicates................................................................................................................................637Any Predicates..............................................................................................................................643Defining vector built-in functions from operators................................................................... 649Deprecated vector built-in functions........................................................................................... 649

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

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

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

xiii

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

Part 5. Performance optimization.......................................................................685

Chapter 39. Improving program performance....................................................................................... 687Writing code for performance............................................................................................................687Using C++ constructs in performance-critical code..........................................................................687Using explicit instantiation declarations (C++11 only).....................................................................689ANSI aliasing rules............................................................................................................................. 689Using ANSI aliasing rules...................................................................................................................691Using variables................................................................................................................................... 692Passing function arguments.............................................................................................................. 693Coding expressions............................................................................................................................ 694Coding conversions............................................................................................................................ 695Arithmetical considerations...............................................................................................................695Using loops and control constructs................................................................................................... 695Choosing a data type..........................................................................................................................696Using library extensions.....................................................................................................................697Using #pragmas................................................................................................................................. 698Using rvalue references (C++11).......................................................................................................700Using shared-memory parallelism (SMP)..........................................................................................702

Chapter 40. Using built-in functions to improve performance.............................................................. 705__builtin_expect................................................................................................................................ 706Platform-specific functions............................................................................................................... 706Examples............................................................................................................................................ 707

Chapter 41. I/O Performance considerations.........................................................................................709Accessing MVS data sets................................................................................................................... 709Accessing UNIX file system files....................................................................................................... 710Using memory files.............................................................................................................................711Using the C++ I/O stream libraries.................................................................................................... 711

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

Optimizations performed by the compiler...................................................................................713Aggressive optimizations with OPTIMIZE(3)...............................................................................714The xlc utility optimization option levels..................................................................................... 715

Using the ARCHITECTURE and TUNE options...................................................................................716Inlining................................................................................................................................................717

Selectively marking code to inline............................................................................................... 718Automatically choosing functions to inline..................................................................................718Modifying automatic inlining choices...........................................................................................719Overriding inlining defaults.......................................................................................................... 720Inlining under IPA.........................................................................................................................720

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

Using the HOT option......................................................................................................................... 721Using the IPA option.......................................................................................................................... 721

Types of procedural analysis........................................................................................................721Program-directed feedback......................................................................................................... 722Compiler processing flow.............................................................................................................723

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

xiv

ASSERT(RESTRICT)...................................................................................................................... 728COMPRESS....................................................................................................................................728COMPACT......................................................................................................................................728CVFT (C++ only)............................................................................................................................ 728EXH (C++ only)..............................................................................................................................728EXPORTALL...................................................................................................................................728FLOAT............................................................................................................................................728HGPR.............................................................................................................................................729IGNERRNO....................................................................................................................................729LANGLVL(NOCHECKPLACEMENTNEW)..................................