z/OS

XL C/C++Programming GuideVersion 2 Release 3

SC14-7315-30

IBM

NoteBefore using this information and the product it supports, read the information in “Notices” on page 1207.

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

Last updated: August 7, 2018

© Copyright IBM Corporation 1996, 2017.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . xv

Tables . . . . . . . . . . . . . . . xix

About this document . . . . . . . . xxvRelated z/OS XL C/C++ information . . . . xxxiiiWhere to find more information . . . . . . xxxiii

z/OS Basic Skills in IBM Knowledge Center xxxiiiHow to send your comments to IBM . . . . . xxxiii

If you have a technical problem . . . . . xxxiv

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

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 CI/O. . . . . . . . . . . . . . . . . 11The record model for C I/O . . . . . . . . . 11

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

Mapping the C types of I/O to the byte streammodel . . . . . . . . . . . . . . . 21

Chapter 4. Using the Standard C++Library I/O Stream Classes . . . . . . 23Advantages to using the C++ I/O stream classes . . 23Predefined streams for C++ . . . . . . . . . 23How C++ I/O streams relate to C I/O streams . . 24Mixing the Standard C++ I/O stream classes, USLI/O stream class library, and C I/O library functions 24Specifying file attributes . . . . . . . . . . 24

Chapter 5. Opening files . . . . . . . 27Prototypes of functions . . . . . . . . . . 27Categories of I/O . . . . . . . . . . . . 29Specifying what kind of file to use. . . . . . . 30

OS files . . . . . . . . . . . . . . . 30UNIX file system files . . . . . . . . . . 30VSAM data sets . . . . . . . . . . . . 30Terminal files . . . . . . . . . . . . . 30

Memory files and hiperspace memory files . . . 31CICS data queues . . . . . . . . . . . 32z/OS Language Environment Message file . . . 32How to specify RECFM, LRECL, and BLKSIZE 32fopen() defaults . . . . . . . . . . . . 34DDnames . . . . . . . . . . . . . . 36

Avoiding Undesirable Results when Using I/O . . 37How z/OS XL C/C++ determines what kind of fileto open . . . . . . . . . . . . . . . . 37

Under TSO, MVS batch, IMS — POSIX(ON) . . 38Under TSO, MVS batch, IMS — POSIX(OFF) . . 41Under CICS . . . . . . . . . . . . . 43

Chapter 6. Buffering of C streams . . . 45

Chapter 7. Using ASA text files . . . . 47Example of writing to an ASA file . . . . . . . 47ASA file control . . . . . . . . . . . . . 48

Chapter 8. z/OS XL C Support for thedouble-byte character set . . . . . . 53Opening files . . . . . . . . . . . . . . 54Reading streams and files . . . . . . . . . 54Writing streams and files . . . . . . . . . . 56

Writing text streams . . . . . . . . . . 56Writing binary streams . . . . . . . . . 58

Flushing buffers . . . . . . . . . . . . . 58Flushing text streams . . . . . . . . . . 58Flushing binary streams . . . . . . . . . 59ungetwc() considerations . . . . . . . . . 59

Setting positions within files. . . . . . . . . 59Repositioning within text streams . . . . . . 59Repositioning within binary streams . . . . . 60ungetwc() considerations . . . . . . . . . 60

Closing files . . . . . . . . . . . . . . 61Manipulating wide character array functions . . . 61

Chapter 9. Using C and C++ standardstreams and redirection . . . . . . . 63Default open modes . . . . . . . . . . . 64Interleaving the standard streams withsync_with_stdio() . . . . . . . . . . . . 65Interleaving the standard streams withoutsync_with_stdio() . . . . . . . . . . . . 66Redirecting standard streams . . . . . . . . 68Redirecting streams from the command line . . . 68

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

MSGFILE considerations . . . . . . . . . 70Redirecting streams under z/OS . . . . . . . 72

Under MVS batch . . . . . . . . . . . 72Under TSO . . . . . . . . . . . . . 74

© Copyright IBM Corp. 1996, 2017 iii

||

Under IMS . . . . . . . . . . . . . 74Under CICS . . . . . . . . . . . . . 75

Passing C and C++ standard streams across asystem() call . . . . . . . . . . . . . . 75

Passing binary streams . . . . . . . . . 75Passing text streams . . . . . . . . . . 76Passing record I/O streams . . . . . . . . 78Passing blocked I/O streams . . . . . . . 78

Using global standard streams . . . . . . . . 78Command line redirection . . . . . . . . 80Direct assignment . . . . . . . . . . . 81freopen() . . . . . . . . . . . . . . 81MSGFILE() runtime option . . . . . . . . 81fclose() . . . . . . . . . . . . . . . 82File position and visible data . . . . . . . 82C++ I/O stream library . . . . . . . . . 82

Chapter 10. Performing OS I/Ooperations . . . . . . . . . . . . . 83Opening files . . . . . . . . . . . . . . 83

Using fopen() or freopen() . . . . . . . . 83Generation data group I/O . . . . . . . . 87Regular and extended partitioned data sets . . . 89Partitioned and sequential concatenated data sets 91In-stream data sets . . . . . . . . . . . 93SYSOUT data sets . . . . . . . . . . . 93Tapes . . . . . . . . . . . . . . . 94Multivolume data sets . . . . . . . . . . 95Striped data sets . . . . . . . . . . . . 95Large format sequential data sets . . . . . . 96Other devices. . . . . . . . . . . . . 96Access method selection . . . . . . . . . 97fopen() and freopen() parameters . . . . . . 97

Buffering . . . . . . . . . . . . . . . 101Multiple buffering . . . . . . . . . . . 102

DCB (Data Control Block) attributes . . . . . . 103Reading from files . . . . . . . . . . . . 105

Reading from binary files . . . . . . . . 106Reading from text files . . . . . . . . . 106Reading from record I/O files . . . . . . . 106Reading from blocked I/O files . . . . . . 107

Writing to files . . . . . . . . . . . . . 107Writing to binary files . . . . . . . . . 108Writing to text files . . . . . . . . . . 109Writing to record I/O files . . . . . . . . 112Writing to blocked I/O files . . . . . . . 112

Flushing buffers . . . . . . . . . . . . 112Updating existing records . . . . . . . . 113Reading updated records . . . . . . . . 113Writing new records . . . . . . . . . . 113ungetc() considerations . . . . . . . . . 114

Repositioning within files . . . . . . . . . 115ungetc() considerations . . . . . . . . . 116How long fgetpos() and ftell() values last . . . 117Using fseek() and ftell() in binary files . . . . 117Using fseek() and ftell() in text files (ASA andNon-ASA) . . . . . . . . . . . . . 118Using fseek() and ftell() in record files . . . . 119Using fseek() and ftell() in blocked files . . . 119Porting old C code that uses fseek() or ftell() 120

Closing files . . . . . . . . . . . . . . 120

Renaming and removing files . . . . . . . . 123fldata() behavior . . . . . . . . . . . . 123

Chapter 11. Performing z/OS UNIX filesystem I/O operations. . . . . . . . 127Creating files . . . . . . . . . . . . . 127

Regular files . . . . . . . . . . . . . 127Link and symbolic link files . . . . . . . 128Directory files . . . . . . . . . . . . 128Character special files . . . . . . . . . 128FIFO files. . . . . . . . . . . . . . 128

Opening files . . . . . . . . . . . . . 128Using fopen() or freopen() . . . . . . . . 129

Reading from z/OS UNIX file system files . . . 133Opening and reading from z/OS UNIX file systemdirectory files . . . . . . . . . . . . . 133Writing to z/OS UNIX file system files . . . . . 134Flushing records . . . . . . . . . . . . 134Setting positions within files . . . . . . . . 134Closing files . . . . . . . . . . . . . . 135Deleting files . . . . . . . . . . . . . 135Pipe I/O . . . . . . . . . . . . . . . 136

Using unnamed pipes . . . . . . . . . 136Using named pipes . . . . . . . . . . 137Character special file I/O . . . . . . . . 140

Low-level z/OS UNIX I/O . . . . . . . . . 141Example of z/OS UNIX file system I/O functions 141fldata() behavior . . . . . . . . . . . . 147File tagging and conversion . . . . . . . . 149Access control lists (ACLs) . . . . . . . . . 149

Chapter 12. Performing VSAM I/Ooperations. . . . . . . . . . . . . 151VSAM types (data set organization) . . . . . . 151

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

Keys, RBAs and RRNs . . . . . . . . . 154Summary of VSAM I/O operations . . . . . 155

Opening VSAM data sets . . . . . . . . . 156Using fopen() or freopen() . . . . . . . . 156Buffering . . . . . . . . . . . . . . 161

Record I/O in VSAM. . . . . . . . . . . 161RRDS record structure . . . . . . . . . 161Reading record I/O files. . . . . . . . . 162Writing to record I/O files . . . . . . . . 163Updating record I/O files . . . . . . . . 164Deleting records . . . . . . . . . . . 165Repositioning within record I/O files . . . . 165Flushing buffers . . . . . . . . . . . 167Summary of VSAM record I/O operations . . 168

VSAM record level sharing and transactionalVSAM. . . . . . . . . . . . . . . . 169

Error reporting . . . . . . . . . . . . 170VSAM extended addressability . . . . . . . 171Text and binary I/O in VSAM. . . . . . . . 171

Reading from text and binary I/O files . . . . 172Writing to and updating text and binary I/Ofiles . . . . . . . . . . . . . . . 172Deleting records in text and binary I/O files . . 172Repositioning within text and binary I/O files 172

iv z/OS XL C/C++ Programming Guide

Flushing buffers . . . . . . . . . . . 174Summary of VSAM text I/O operations . . . 175Summary of VSAM binary I/O operations . . 175

Closing VSAM data sets . . . . . . . . . . 176VSAM return codes . . . . . . . . . . . 177VSAM examples . . . . . . . . . . . . 177

KSDS example . . . . . . . . . . . . 177RRDS example . . . . . . . . . . . . 186

fldata() behavior . . . . . . . . . . . . 188

Chapter 13. Performing terminal I/Ooperations. . . . . . . . . . . . . 191Opening files . . . . . . . . . . . . . 191

Using fopen() and freopen() . . . . . . . 191Buffering . . . . . . . . . . . . . . 193

Reading from files . . . . . . . . . . . . 193Reading from binary files . . . . . . . . 195Reading from text files . . . . . . . . . 195Reading from record I/O files . . . . . . . 195

Writing to files . . . . . . . . . . . . . 196Writing to binary files . . . . . . . . . 196Writing to text files . . . . . . . . . . 197Writing to record I/O files . . . . . . . . 197

Flushing records . . . . . . . . . . . . 197Text streams . . . . . . . . . . . . . 198Binary streams . . . . . . . . . . . . 198Record I/O . . . . . . . . . . . . . 198

Repositioning within files . . . . . . . . . 198Closing files . . . . . . . . . . . . . . 198fldata() behavior . . . . . . . . . . . . 199

Chapter 14. Performing memory fileand hiperspace I/O operations . . . . 201Using hiperspace operations . . . . . . . . 201Opening files . . . . . . . . . . . . . 202

Using fopen() or freopen() . . . . . . . . 202Simulating partitioned data sets . . . . . . 206Buffering . . . . . . . . . . . . . . 208

Reading from files . . . . . . . . . . . . 209Writing to files . . . . . . . . . . . . . 210Flushing records . . . . . . . . . . . . 210

ungetc() considerations . . . . . . . . . 211Repositioning within files . . . . . . . . . 211Closing files . . . . . . . . . . . . . . 212

Performance tips . . . . . . . . . . . 212Removing memory files . . . . . . . . . . 212fldata() behavior . . . . . . . . . . . . 212Example program . . . . . . . . . . . . 213

Chapter 15. Performing CICSTransaction Server I/O operations . . 215

Chapter 16. Language EnvironmentMessage file operations . . . . . . . 217Opening files . . . . . . . . . . . . . 217Reading from files . . . . . . . . . . . . 217Writing to files . . . . . . . . . . . . . 218Flushing buffers . . . . . . . . . . . . 218Repositioning within files . . . . . . . . . 218

Closing files . . . . . . . . . . . . . . 218

Chapter 17. CELQPIPI MSGRTN fileoperations. . . . . . . . . . . . . 219Opening files . . . . . . . . . . . . . 219Reading from files . . . . . . . . . . . . 219Writing to files . . . . . . . . . . . . . 219Flushing buffers . . . . . . . . . . . . 219Repositioning within files . . . . . . . . . 219Closing files . . . . . . . . . . . . . . 220fldata() behavior . . . . . . . . . . . . 220fldata() example . . . . . . . . . . . . 221

Chapter 18. Debugging I/O programs 223Using the __amrc structure . . . . . . . . . 223Using the __amrc2 structure . . . . . . . . 227Using __last_op codes . . . . . . . . . . 227Using the SIGIOERR signal. . . . . . . . . 231File I/O trace . . . . . . . . . . . . . 234Locating the file I/O trace . . . . . . . . . 234

Part 3. Interlanguage Calls withz/OS XL C/C++ . . . . . . . . . . 237

Chapter 19. Using LinkageSpecifications in C or C++ . . . . . . 239Syntax for Linkage in C or C++ . . . . . . . 239

Syntax for Linkage in C . . . . . . . . . 239Syntax for Linkage in C++ . . . . . . . . 240

Kinds of Linkage used by C or C++ InterlanguagePrograms . . . . . . . . . . . . . . . 240Using Linkage Specifications in C++. . . . . . 242

Chapter 20. Combining C or C++ andAssembler programs . . . . . . . . 245Establishing the z/OS XL C/C++ environment . . 245Specifying linkage for C or C++ to Assembler . . 246Parameter lists for OS linkage . . . . . . . . 246XPLINK Assembler . . . . . . . . . . . 247Using standard macros . . . . . . . . . . 249

Non-XPLINK assembler prolog . . . . . . 249Non-XPLINK assembler epilog . . . . . . 250XPLINK Assembler prolog . . . . . . . . 251XPLINK Call . . . . . . . . . . . . 252XPLINK Assembler epilog . . . . . . . . 254Accessing automatic memory in thenon-XPLINK stack. . . . . . . . . . . 254

Calling C code from Assembler — C example . . 255Calling runtime library routines from Assembler —C++ example . . . . . . . . . . . . . 256Register content at entry to a non-XPLINK ASMroutine using OS linkage . . . . . . . . . 258Register content at exit from a non-XPLINK ASMroutine to z/OS XL C/C++. . . . . . . . . 258Retaining the C environment using preinitialization 258

Setting up the interface for preinitializableprograms . . . . . . . . . . . . . . 259Preinitializing a C program. . . . . . . . 263

Contents v

Multiple preinitialization compatibility interfaceC environments . . . . . . . . . . . 270Using the service vector and associated routines 272

Part 4. Coding: Advanced Topics 279

Chapter 21. Building and usingDynamic Link Libraries (DLLs) . . . . 281Support for DLLs . . . . . . . . . . . . 282DLL concepts and terms. . . . . . . . . . 282Loading a DLL . . . . . . . . . . . . . 283

Loading a DLL implicitly . . . . . . . . 283Loading a DLL explicitly . . . . . . . . 284

Managing the use of DLLs when running DLLapplications . . . . . . . . . . . . . . 288

Loading DLLs . . . . . . . . . . . . 288Sharing DLLs . . . . . . . . . . . . 290Freeing DLLs . . . . . . . . . . . . 290

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

Example of building a simple C DLL . . . . 291Example of building a simple C++ DLL . . . 291Compiling your code . . . . . . . . . . 292Binding your code. . . . . . . . . . . 293

Building a simple DLL application . . . . . . 294Steps for using an implicitly loaded DLL inyour simple DLL application . . . . . . . 294

Creating and using DLLs . . . . . . . . . 295DLL restrictions . . . . . . . . . . . . 296

Improving performance . . . . . . . . . 298

Chapter 22. Building complex DLLs 301Rules for compiling source code with XPLINK . . 302

XPLINK applications . . . . . . . . . . 302Non-XPLINK applications . . . . . . . . 303

Compatibility issues between DLL and non-DLLcode . . . . . . . . . . . . . . . . 305

Pointer assignment . . . . . . . . . . 306Function pointers . . . . . . . . . . . 306

DLL function pointer call in non-DLL code . . . 308C example . . . . . . . . . . . . . 309Non-DLL function pointer call in DLL(CBA)code . . . . . . . . . . . . . . . 311Non-DLL function pointer call in DLL code . . 313Function pointer comparison in non-DLL code 314Function pointer comparison in DLL code . . . 317

Using DLLs that call each other . . . . . . . 319

Chapter 23. z/OS 64-bit environment 325Differences between the ILP32 and LP64environments . . . . . . . . . . . . . 325

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

Advantages and disadvantages of the LP64environment. . . . . . . . . . . . . . 326

LP64 application performance and program size 326LP64 restrictions . . . . . . . . . . . 327

Migrating applications from ILP32 to LP64 . . . 327When to migrate applications to LP64 . . . . 327

Checklist for ILP32-to-LP64 pre-migrationactivities . . . . . . . . . . . . . . 328Checklist for ILP32-to-LP64 post-migrationactivities . . . . . . . . . . . . . . 328

Using compiler diagnostics to ensure portability ofcode . . . . . . . . . . . . . . . . 329

Using the INFO option to ensure that numbersare suffixed . . . . . . . . . . . . . 329Using the WARN64 option to identify potentialportability problems . . . . . . . . . . 330

ILP32-to-LP64 portability issues . . . . . . . 331IPA(LINK) option and exploitation of 64-bitvirtual memory. . . . . . . . . . . . 332Availability of suboptions . . . . . . . . 332Potential changes in structure size andalignment . . . . . . . . . . . . . 332Data type assignment differences under ILP32and LP64 . . . . . . . . . . . . . . 337Pointer declarations when 32-bit and 64-bitapplications share header files . . . . . . . 341Potential pointer corruption . . . . . . . 342Potential loss of data in constant expressions 343Data alignment problems when structures areshared. . . . . . . . . . . . . . . 344Portability issues with unsuffixed numbers . . 346Using a LONG_MAX macro in a printfsubroutine . . . . . . . . . . . . . 347

Programming for portability between ILP32 andLP64 . . . . . . . . . . . . . . . . 348

Using header files to provide type definitions 348Using suffixes and explicit types to preventunexpected behavior . . . . . . . . . . 348Defining pad members to avoid data alignmentproblems . . . . . . . . . . . . . . 349Using prototypes to avoid debugging problems 350Using a conditional compiler directive forpreprocessor macro selection . . . . . . . 351Using converters under ILP32 or LP64 . . . . 351Using locales under ILP32 or LP64 . . . . . 351

Chapter 24. Using threads in z/OSUNIX applications . . . . . . . . . 353Models and requirements . . . . . . . . . 353

Functions. . . . . . . . . . . . . . 353Creating a thread . . . . . . . . . . . 353Synchronization primitives . . . . . . . . 355Thread-specific data . . . . . . . . . . 358Signals . . . . . . . . . . . . . . 360Generating a signal . . . . . . . . . . 361Thread cancellation . . . . . . . . . . 362Cleanup for threads . . . . . . . . . . 364Thread stack attributes . . . . . . . . . 364

Behaviors and restrictions in z/OS UNIXapplications . . . . . . . . . . . . . . 365

Using threads with MVS files . . . . . . . 365Multithreaded I/O . . . . . . . . . . 366Thread-scoped functions. . . . . . . . . 366Unsafe thread functions . . . . . . . . . 367Fetched functions and writable statics . . . . 367MTF and z/OS UNIX threading . . . . . . 367Thread queuing function . . . . . . . . 367

vi z/OS XL C/C++ Programming Guide

Thread scheduling. . . . . . . . . . . 367iconv() family of functions . . . . . . . . 368Threads and recoverable resources . . . . . 368

Chapter 25. Reentrancy in z/OS XLC/C++. . . . . . . . . . . . . . . 369Natural or constructed reentrancy . . . . . . 370

Limitations of constructed reentrancy for Cprograms . . . . . . . . . . . . . . 370

Controlling external static in C programs . . . . 370Controlling writable strings . . . . . . . 371Controlling the memory area in C++ . . . . 372

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

Chapter 26. Using decimal data typesin C . . . . . . . . . . . . . . . 377Decimal data type declarations . . . . . . . 377

Declaring fixed-point decimal constants . . . 378Declaring decimal variables . . . . . . . 378

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

Arithmetic operators . . . . . . . . . . 380Assignment operators . . . . . . . . . 383Unary operators . . . . . . . . . . . 383Summary of operators used with decimal types 384

Converting decimal types . . . . . . . . . 385Converting decimal types to decimal types . . 385Converting decimal types to and from integertypes . . . . . . . . . . . . . . . 386Converting decimal data types to and fromfloating-point data types . . . . . . . . 388

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

Using variable arguments with decimal datatypes . . . . . . . . . . . . . . . 389

Formatting input and output operations withdecimal data types . . . . . . . . . . . 389Validating decimal values . . . . . . . . . 389Fixing sign variables . . . . . . . . . . . 390Returning decimal absolute values . . . . . . 390Programming examples . . . . . . . . . . 391Decimal exception handling . . . . . . . . 393

printf() and scanf() and format validation . . . 394Additional considerations . . . . . . . . 394Error messages . . . . . . . . . . . . 394Decimal exceptions and Assemblerinterlanguage calls . . . . . . . . . . 395

Chapter 27. IEEE Floating-Point . . . 397Floating-point numbers . . . . . . . . . . 397C/C++ compiler support . . . . . . . . . 398Using IEEE floating-point . . . . . . . . . 399

Chapter 28. Handling error conditions,exceptions, and signals . . . . . . . 403Handling C software exceptions under C++ . . . 404Handling hardware exceptions under C++ . . . 404Tracebacks under C++ . . . . . . . . . . 404

AMODE 64 exception handlers . . . . . . . 407Scope and nesting of exception handlers . . . 407Handling exceptions . . . . . . . . . . 408

Signal handlers . . . . . . . . . . . . . 408Handling signals with POSIX(OFF) usingsignal() and raise() . . . . . . . . . . 409Handling signals using Language Environmentcallable services . . . . . . . . . . . 409Handling signals using z/OS UNIX withPOSIX(ON) . . . . . . . . . . . . . 410Asynchronous signal delivery under z/OSUNIX . . . . . . . . . . . . . . . 412C signal handling features under z/OS XLC/C++ . . . . . . . . . . . . . . 413

Chapter 29. Network communicationsunder UNIX System Services. . . . . 425Understanding z/OS UNIX sockets andinternetworking . . . . . . . . . . . . 425Basics of network communication . . . . . . 426

Transport protocols for sockets . . . . . . 426What is a socket? . . . . . . . . . . . . 427

z/OS UNIX Socket families. . . . . . . . 428z/OS UNIX Socket types . . . . . . . . 428Guidelines for using socket types. . . . . . 429Addressing within sockets . . . . . . . . 429

The conversation . . . . . . . . . . . . 432The server perspective . . . . . . . . . 433The client perspective . . . . . . . . . 434A typical TCP socket session . . . . . . . 435

A typical UDP socket session . . . . . . . . 436Locating the server's port . . . . . . . . . 437Network application example . . . . . . . . 437Using common INET . . . . . . . . . . . 443Compiling and binding . . . . . . . . . . 444Using TCP/IP APIs . . . . . . . . . . . 445

Restrictions for using z/OS TCP/IP API withz/OS UNIX . . . . . . . . . . . . . 446

Using z/OS UNIX sockets . . . . . . . . . 447Compiling under MVS batch for Berkeleysockets . . . . . . . . . . . . . . 448Compiling under MVS batch for X/Opensockets . . . . . . . . . . . . . . 449

Understanding the X/Open Transport Interface(XTI) . . . . . . . . . . . . . . . . 450

Transport endpoints . . . . . . . . . . 451Transport providers for X/Open TransportInterface . . . . . . . . . . . . . . 451General restrictions for z/OS UNIX . . . . . 451

Chapter 30. Interprocesscommunication using z/OS UNIX . . . 453Message queues . . . . . . . . . . . . 453Semaphores . . . . . . . . . . . . . . 454Shared memory . . . . . . . . . . . . 454Memory mapping . . . . . . . . . . . . 454TSO commands from a shell . . . . . . . . 455

Contents vii

||

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

TEMPINC example . . . . . . . . . . 458Regenerating the template instantiation file . . 461TEMPINC considerations for shared libraries 461

Using the TEMPLATEDEPTH compiler option . . 461Using the TEMPLATEREGISTRY compiler option 461

Recompiling related compilation units . . . . 462Switching from TEMPINC toTEMPLATEREGISTRY . . . . . . . . . 462

Using explicit instantiation declarations (C++11only) . . . . . . . . . . . . . . . . 462

Examples of explicit instantiation declarations 464

Chapter 32. Using environmentvariables . . . . . . . . . . . . . 467Working with environment variables . . . . . 475

Naming conventions . . . . . . . . . . 476Environment variables specific to the z/OS XLC/C++ library . . . . . . . . . . . . . 477

_CEE_CONDWAIT_PAUSE. . . . . . . . 478_CEE_DLLLOAD_XPCOMPAT . . . . . . 479_CEE_DMPTARG . . . . . . . . . . . 479_CEE_ENVFILE . . . . . . . . . . . 480_CEE_ENVFILE_COMMENT . . . . . . . 481_CEE_ENVFILE_CONTINUATION . . . . . 481_CEE_ENVFILE_S . . . . . . . . . . . 482_CEE_HEAP_MANAGER . . . . . . . . 483_CEE_REALLOC_CONTROL . . . . . . . 483_CEE_RUNOPTS . . . . . . . . . . . 484_EDC_ADD_ERRNO2 . . . . . . . . . 487_EDC_ANSI_OPEN_DEFAULT . . . . . . 487_EDC_AUTOCVT_BINARY . . . . . . . 487_EDC_BYTE_SEEK . . . . . . . . . . 488_EDC_CLEAR_SCREEN . . . . . . . . . 488_EDC_COMPAT . . . . . . . . . . . 488_EDC_CONTEXT_GUARD . . . . . . . . 489_EDC_C99_NAN . . . . . . . . . . . 490_EDC_DLL_DIAG . . . . . . . . . . . 490_EDC_EOVERFLOW . . . . . . . . . . 491_EDC_ERRNO_DIAG . . . . . . . . . 491_EDC_FLUSH_STDOUT_PIPE. . . . . . . 492_EDC_FLUSH_STDOUT_SOCKET . . . . . 493_EDC_GLOBAL_STREAMS. . . . . . . . 493_EDC_IEEEV1_COMPATIBILITY_ENV . . . . 494_EDC_IO_ABEND. . . . . . . . . . . 495_EDC_IO_TRACE . . . . . . . . . . . 496_EDC_OPEN_CONCAT . . . . . . . . . 497_EDC_POPEN . . . . . . . . . . . . 498_EDC_PTHREAD_YIELD . . . . . . . . 498_EDC_PTHREAD_YIELD_MAX . . . . . . 498_EDC_PUTENV_COPY . . . . . . . . . 499_EDC_RRDS_HIDE_KEY . . . . . . . . 500_EDC_STOR_INCREMENT. . . . . . . . 500_EDC_STOR_INCREMENT_B . . . . . . . 500_EDC_STOR_INITIAL . . . . . . . . . 501_EDC_STOR_INITIAL_B . . . . . . . . 501_EDC_STRPTM_STD . . . . . . . . . . 502_EDC_SUSV3 . . . . . . . . . . . . 502

_EDC_UMASK_DFLT . . . . . . . . . 502_EDC_ZERO_RECLEN . . . . . . . . . 503

Propagating environment variables . . . . . . 503

Chapter 33. Using hardware built-infunctions . . . . . . . . . . . . . 505General instructions . . . . . . . . . . . 505

PLO - Perform Locked Operation available inARCH(5) . . . . . . . . . . . . . . 523

Decimal instructions . . . . . . . . . . . 528Floating-point support instructions . . . . . . 533Decimal floating-point built-in functions . . . . 534

Macros for use with decimal floating-pointbuilt-in functions . . . . . . . . . . . 542

Hexadecimal floating-point instructions . . . . 544Binary floating-Point instructions . . . . . . . 545Built-in functions for transaction execution . . . 547

Chapter 34. Using runtime checklibrary . . . . . . . . . . . . . . 551

Chapter 35. Using vectorprogramming support. . . . . . . . 553Options . . . . . . . . . . . . . . . 553Macro . . . . . . . . . . . . . . . . 553Vector data types . . . . . . . . . . . . 554Language extensions . . . . . . . . . . . 555

Vector literals . . . . . . . . . . . . 555Initialization of vectors . . . . . . . . . 558typedef definitions for vector types . . . . . 559Pointers . . . . . . . . . . . . . . 559Unary expressions . . . . . . . . . . . 559Binary expressions. . . . . . . . . . . 561Cast expressions . . . . . . . . . . . 581Compound literal expressions . . . . . . . 581Other extensions for vector types . . . . . . 581

Vector built-in functions . . . . . . . . . . 581Header file . . . . . . . . . . . . . 582Summary of vector built-in functions . . . . 582Arithmetic . . . . . . . . . . . . . 589Compare . . . . . . . . . . . . . . 608Compare Ranges . . . . . . . . . . . 616Find Any Element . . . . . . . . . . . 628Gather and Scatter. . . . . . . . . . . 636Generate Mask . . . . . . . . . . . . 642Copy until Zero . . . . . . . . . . . 644Load and Store . . . . . . . . . . . . 645Logical . . . . . . . . . . . . . . 649Merge . . . . . . . . . . . . . . . 654Pack and Unpack . . . . . . . . . . . 655Replicate . . . . . . . . . . . . . . 660Rotate and Shift . . . . . . . . . . . 663Rounding and Conversion . . . . . . . . 670Test. . . . . . . . . . . . . . . . 675All Predicates . . . . . . . . . . . . 676Any Predicates . . . . . . . . . . . . 682Defining vector built-in functions fromoperators . . . . . . . . . . . . . . 688Deprecated vector built-in functions . . . . . 688

viii z/OS XL C/C++ Programming Guide

||

||

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

Feature test macros that control C99 interfaces inXL C++ applications . . . . . . . . . . 711Using C99 functions in C++ applications whenambiguous definitions exist. . . . . . . . 712

Chapter 37. Writing applications forSingle UNIX Specification, Version 3 . 715Announcing your intentions . . . . . . . . 715Testing the environment . . . . . . . . . . 716What is different in SUSv3 . . . . . . . . . 717Symbols withdrawn in SUSv3 . . . . . . . . 718Candidates for removal in a future version . . . 718Implementation compliance . . . . . . . . 718

Chapter 38. Saved compile-timeoptions information. . . . . . . . . 721Saved options information layout . . . . . . 722

Part 5. Performance optimization 727

Chapter 39. Improving programperformance . . . . . . . . . . . . 729Writing code for performance . . . . . . . . 729Using C++ constructs in performance-critical code 729Using explicit instantiation declarations (C++11only) . . . . . . . . . . . . . . . . 731ANSI aliasing rules . . . . . . . . . . . 731Using ANSI aliasing rules . . . . . . . . . 734Using variables . . . . . . . . . . . . . 735Passing function arguments . . . . . . . . 736Coding expressions . . . . . . . . . . . 737Coding conversions . . . . . . . . . . . 738Arithmetical considerations. . . . . . . . . 738Using loops and control constructs . . . . . . 738Choosing a data type . . . . . . . . . . . 739Using library extensions . . . . . . . . . . 740Using #pragmas . . . . . . . . . . . . 742Using rvalue references (C++11) . . . . . . . 743Using shared-memory parallelism (SMP) . . . . 746

Chapter 40. Using built-in functions toimprove performance . . . . . . . . 747__builtin_expect . . . . . . . . . . . . 748Platform-specific functions . . . . . . . . . 748Examples . . . . . . . . . . . . . . . 749

Chapter 41. I/O Performanceconsiderations . . . . . . . . . . . 751Accessing MVS data sets . . . . . . . . . 751Accessing UNIX file system files . . . . . . . 753Using memory files . . . . . . . . . . . 753Using the C++ I/O stream libraries . . . . . . 753

Chapter 42. Improving performancewith compiler options . . . . . . . . 755Using the OPTIMIZE option . . . . . . . . 755

Optimizations performed by the compiler . . . 755Aggressive optimizations with OPTIMIZE(3) 756The xlc utility optimization option levels . . . 757

Using the ARCHITECTURE and TUNE options 758Inlining . . . . . . . . . . . . . . . 759

Selectively marking code to inline . . . . . 760Automatically choosing functions to inline . . 760Modifying automatic inlining choices . . . . 761Overriding inlining defaults . . . . . . . 762Inlining under IPA . . . . . . . . . . 762

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

Using the HOT option . . . . . . . . . . 763Using the IPA option . . . . . . . . . . . 764

Types of procedural analysis . . . . . . . 764Program-directed feedback . . . . . . . . 766Compiler processing flow . . . . . . . . 766

Additional options that affect performance . . . 771ANSIALIAS . . . . . . . . . . . . . 771AGGRCOPY. . . . . . . . . . . . . 771ASSERT(RESTRICT) . . . . . . . . . . 771COMPRESS . . . . . . . . . . . . . 771COMPACT . . . . . . . . . . . . . 771CVFT (C++ only) . . . . . . . . . . . 772EXH (C++ only) . . . . . . . . . . . 772EXPORTALL . . . . . . . . . . . . 772FLOAT . . . . . . . . . . . . . . 772HGPR . . . . . . . . . . . . . . . 772IGNERRNO . . . . . . . . . . . . . 772LANGLVL(NOCHECKPLACEMENTNEW) . . 772LIBANSI . . . . . . . . . . . . . . 773NOCHECKNEW . . . . . . . . . . . 773OBJECTMODEL (C++ only) . . . . . . . 773PREFETCH . . . . . . . . . . . . . 773RESTRICT . . . . . . . . . . . . . 773ROCONST . . . . . . . . . . . . . 773ROSTRING . . . . . . . . . . . . . 774RTTI . . . . . . . . . . . . . . . 774SPILL . . . . . . . . . . . . . . . 774STRICT . . . . . . . . . . . . . . 774STRICT_INDUCTION . . . . . . . . . 774THREADED. . . . . . . . . . . . . 774UNROLL . . . . . . . . . . . . . . 774VECTOR . . . . . . . . . . . . . . 774

Chapter 43. Using high performancelibraries . . . . . . . . . . . . . . 777Using the Mathematical Acceleration Subsystem(MASS) libraries . . . . . . . . . . . . 777

Using the MASS scalar library. . . . . . . 777Using the MASS vector library . . . . . . 780Using the MASS SIMD library. . . . . . . 784Compiling and linking a program with MASS 785

Using the Automatically Tuned Linear AlgebraSoftware (ATLAS) libraries . . . . . . . . . 789

Description and functionality provided . . . . 790

Contents ix

||

||||

||

||

||

||

||

||

Supplied ATLAS libraries and theircorresponding header files . . . . . . . . 790Required compiler options . . . . . . . . 792Examples - Compiling, linking, and running asimple matrix multiplication ATLAS program . 792Examples - Compiling, linking, and running acomplex ATLAS sample . . . . . . . . . 799Related external information . . . . . . . 801

Chapter 44. Parallelizing yourprograms . . . . . . . . . . . . . 803Using OpenMP directives . . . . . . . . . 803Shared and private variables in a parallelenvironment. . . . . . . . . . . . . . 804OpenMP runtime functions for parallel processing 806

Chapter 45. Optimizing the systemand Language Environment . . . . . 815Improving the performance of the LanguageEnvironment . . . . . . . . . . . . . 815

Storing libraries and modules in systemmemory . . . . . . . . . . . . . . 815Optimizing memory and storage . . . . . . 815Optimizing runtime options . . . . . . . 816

Tuning the system for efficient execution . . . . 817Link pack areas . . . . . . . . . . . 817Library lookasides . . . . . . . . . . . 817Virtual lookasides . . . . . . . . . . . 817

Chapter 46. Balancing compilationtime and application performance . . 819General tips . . . . . . . . . . . . . . 819Programmer tips . . . . . . . . . . . . 820System programmer tips . . . . . . . . . 821

Chapter 47. Stepping throughoptimized code using the dbxdebugger utility . . . . . . . . . . 823Steps for setting up a stopping point for dbx inoptimized code . . . . . . . . . . . . . 823Steps for setting up a stopping point for dbx inoptimized code . . . . . . . . . . . . . 823

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

Chapter 48. Using the systemprogramming C facilities . . . . . . 827Using functions in the system programming Cenvironment. . . . . . . . . . . . . . 828System programming C facility considerations andrestrictions . . . . . . . . . . . . . . 829Creating freestanding applications . . . . . . 830

Creating modules without CEESTART . . . . 831Including an alternative initialization routineunder z/OS . . . . . . . . . . . . . 831Initializing a freestanding application withoutLanguage Environment. . . . . . . . . . 831

Initializing a freestanding application using Cfunctions . . . . . . . . . . . . . . 832Setting up a C environment with preallocatedstack and heap . . . . . . . . . . . . 832Determining ISA requirements. . . . . . . 833Building freestanding applications to run underz/OS . . . . . . . . . . . . . . . 833Parts used for freestanding applications . . . 836

Creating system exit routines . . . . . . . . 836Building system exit routines under z/OS . . . 837An example of a system exit . . . . . . . 837

Creating and using persistent C environments . . 840Building applications that use persistent Cenvironments . . . . . . . . . . . . 841An example of persistent C environments . . . 841

Developing services in the service routineenvironment. . . . . . . . . . . . . . 845

Using application service routine control flow 846Understanding the stub perspective . . . . . 851Establishing a server environment . . . . . 859Initiating a server request . . . . . . . . 860Accepting a request for service . . . . . . 860Returning control from service . . . . . . 860Constructing user-server stub routines . . . . 860Building user-server environments . . . . . 860

Tailoring the system programming C environment 861Generating abends . . . . . . . . . . 861Getting storage . . . . . . . . . . . . 862Getting page-aligned storage . . . . . . . 863Freeing storage . . . . . . . . . . . . 864Loading a module . . . . . . . . . . . 864Deleting a module. . . . . . . . . . . 864

Including a runtime message file . . . . . . . 865Additional library routines . . . . . . . . . 866Summary of application types . . . . . . . . 866

Chapter 49. Library functions forsystem programming C . . . . . . . 869__xhotc() — Set Up a Persistent C Environment(No Library). . . . . . . . . . . . . . 869__xhotl() — Set Up a Persistent C Environment(With Library) . . . . . . . . . . . . . 870__xhott() — Terminate a Persistent C Environment 870__xhotu() . . . . . . . . . . . . . . . 871__xregs() — Get Registers on Entry . . . . . . 871__xsacc() — Accept Request for Service. . . . . 872__xsrvc() — Return Control from Service . . . . 872__xusr() - __xusr2() — Get Address of User Word 873__24malc() — Allocate Storage below 16MB Line 873__4kmalc() — Allocate Page-Aligned Storage . . . 873

Chapter 50. Using runtime user exits 875Using runtime user exits in z/OS LanguageEnvironment . . . . . . . . . . . . . 875

Understanding the basics . . . . . . . . 875PL/I and C/370 compatibility . . . . . . . 875User exits supported under z/OS LanguageEnvironment . . . . . . . . . . . . 876Order of processing of user exits . . . . . . 876

x z/OS XL C/C++ Programming Guide

Using installation-wide or application-specificuser exits . . . . . . . . . . . . . . 877Using the Assembler user exit . . . . . . . 878Using sample Assembler user exits . . . . . 878Assembler user exit interface . . . . . . . 880Parameter values in the Assembler user exit . . 884PL/I and C/370 compatibility . . . . . . . 889High level language user exit interface . . . . 890

Chapter 51. Using the z/OS XL CMultiTasking Facility . . . . . . . . 893Organizing a program with MTF . . . . . . . 893

Ensuring computational independence . . . . 894Running a C program without MTF . . . . . 895Running a C program with MTF . . . . . . 896Running a C program with one parallel function 896Running a C program with two differentparallel functions . . . . . . . . . . . 898z/OS XL C with multiple instances of the sameparallel function . . . . . . . . . . . 899

Designing and coding applications for MTF . . . 901Step 1: Identifying computationally-independentcode . . . . . . . . . . . . . . . 901Step 2: Creating parallel functions . . . . . 901Step 3: Inserting calls to parallel functions . . . 905Changing an application to use MTF . . . . 905

Compiling and linking programs that use MTF . . 910Creating the main task program load module 910Creating the parallel functions load module . . 911Specifying the linkage-editor option . . . . . 912Modifying runtime options . . . . . . . . 912

Running programs that use MTF . . . . . . . 912STEPLIB DD statement . . . . . . . . . 912DD statements for standard streams . . . . . 912Example of JCL. . . . . . . . . . . . 913Debugging programs that use MTF . . . . . 913Avoiding undesirable results when using MTF 913

Part 7. Programming with OtherProducts . . . . . . . . . . . . . 915

Chapter 52. Using the CICSTransaction Server (CICS TS) . . . . 917Developing XL C/C++ programs for the CICSenvironment. . . . . . . . . . . . . . 917Preparing CICS for use with z/OS LanguageEnvironment . . . . . . . . . . . . . 917Designing and coding for CICS . . . . . . . 918

Using the CICS command-level interface . . . 918Using input and output . . . . . . . . . 922Using z/OS XL C/C++ library support. . . . 924Storage management . . . . . . . . . . 926Using ILC support . . . . . . . . . . 927Exception handling . . . . . . . . . . 927Example of error handling in CICS . . . . . 928ABEND codes and error messages under z/OSXL C/C++ . . . . . . . . . . . . . 932Coding hints and tips . . . . . . . . . 932

Translating and compiling for reentrancy . . . . 932

Options for translating CICS statements . . . 932Compiling XL C/C++ programs that werepreprocessed by the standalone CICS translator . 937

Linking all object modules . . . . . . . . . 938Defining and running the CICS program . . . . 939

Program processing . . . . . . . . . . 939Link considerations for C programs . . . . . 939CSD considerations . . . . . . . . . . 940Sample JCL to install z/OS XL C/C++application programs . . . . . . . . . . 940

Chapter 53. Using Cross SystemProduct (CSP) . . . . . . . . . . . 941Common data types . . . . . . . . . . . 941Passing control . . . . . . . . . . . . . 941Running CSP under MVS . . . . . . . . . 942

Calling CSP applications from z/OS XL C . . . 942Calling z/OS XL C from CSP . . . . . . . 945

Running under CICS control . . . . . . . . 949Example programs . . . . . . . . . . 949

Chapter 54. Using Data WindowServices (DWS) . . . . . . . . . . 955

Chapter 55. Using DB2 UniversalDatabase . . . . . . . . . . . . . 957Preparing an XL C/C++ application to request DB2services . . . . . . . . . . . . . . . 957

Using the XL C/C++ DB2 coprocessor . . . . 957Using the DB2 C/C++ precompiler . . . . . 958

Using DB2 services and stored procedures withXPLINK . . . . . . . . . . . . . . . 958Examples of how to use XL C/C++ programs torequest DB2 services . . . . . . . . . . . 959

Chapter 56. Using Graphical DataDisplay Manager (GDDM) . . . . . . 965Examples . . . . . . . . . . . . . . . 966

Chapter 57. Using the InformationManagement System (IMS) . . . . . 971Handling errors . . . . . . . . . . . . 972Other considerations . . . . . . . . . . . 972

Examples . . . . . . . . . . . . . . 973

Chapter 58. Using the QueryManagement Facility (QMF) . . . . . 979Example programs . . . . . . . . . . . 980

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

Chapter 59. Introduction to locale . . 989Internationalization in programming languages . . 989Elements of internationalization . . . . . . . 989z/OS XL C/C++ Support for internationalization 990Locales and localization . . . . . . . . . . 990

Contents xi

|

Locale-sensitive interfaces . . . . . . . . 990

Chapter 60. Building a locale. . . . . 993Limitations of enhanced ASCII . . . . . . . 993Using the charmap file . . . . . . . . . . 994

The CHARMAP section . . . . . . . . . 999The CHARSETID section . . . . . . . . 1000

Locale source files . . . . . . . . . . . 1001LC_CTYPE category. . . . . . . . . . 1005LC_COLLATE category . . . . . . . . 1007LC_MONETARY category . . . . . . . . 1014LC_NUMERIC category . . . . . . . . 1018LC_TIME category . . . . . . . . . . 1019LC_MESSAGES category . . . . . . . . 1021LC_TOD category . . . . . . . . . . 1022LC_SYNTAX category . . . . . . . . . 1024

Method files . . . . . . . . . . . . . 1026Using the localedef utility . . . . . . . . . 1031

Locale naming conventions . . . . . . . 1032

Chapter 61. Customizing a locale 1043Using the customized locale . . . . . . . . 1045Referring explicitly to a customized locale . . . 1046Referring implicitly to a customized locale . . . 1047

Customizing your installation . . . . . . 1049

Chapter 62. Customizing a time zone 1051Using the TZ or _TZ environment variable tospecify time zone. . . . . . . . . . . . 1051Relationship between TZ or _TZ and LC_TOD 1052

Chapter 63. Definition of S370 C,SAA C, and POSIX C locales . . . . 1053Differences between SAA C and POSIX C locales 1059

Chapter 64. Code set conversionutilities . . . . . . . . . . . . . 1061The genxlt utility . . . . . . . . . . . . 1061The iconv utility . . . . . . . . . . . . 1061Code conversion functions . . . . . . . . 1062

_ICONV_MODE environmental variable . . . 1063_ICONV_TECHNIQUE environmental variable 1063

Code set converters supplied . . . . . . . . 1064Universal coded character set converters . . . . 1073

Codeset conversion using UCS-2 . . . . . 1080UCMAP source format . . . . . . . . . 1081

Chapter 65. Coded character setconsiderations with locale functions . 1085Variant character detail . . . . . . . . . . 1085Alternate code points . . . . . . . . . . 1087Coding without locale support by using a hybridcoded character set . . . . . . . . . . . 1087

Writing code using a hybrid coded characterset. . . . . . . . . . . . . . . . 1089Converting hybrid code . . . . . . . . 1089

Coded character set independence in developingapplications . . . . . . . . . . . . . 1089

Coded character set in source code and headerfiles . . . . . . . . . . . . . . . 1091Converting coded character sets at compiletime . . . . . . . . . . . . . . . 1094

Writing source code in coded character setIBM-1047 . . . . . . . . . . . . . . 1100Exporting source code to other sites . . . . . 1100Converting existing work . . . . . . . . . 1101Considerations with other products and tools 1102

Chapter 66. Bidirectional languagesupport . . . . . . . . . . . . . 1103Bidirectional languages . . . . . . . . . . 1103

Overview of the layout functions . . . . . 1104Using the layout functions. . . . . . . . 1108

Part 9. Appendixes. . . . . . . . 1115

Appendix A. POSIX character set 1117

Appendix B. Mapping variantcharacters for z/OS XL C/C++ . . . . 1121Specifying the appropriate code page for thecompiler. . . . . . . . . . . . . . . 1121Testing the display of variant characters . . . . 1121Inserting and viewing square brackets during anISPF edit session . . . . . . . . . . . . 1124

Appendix C. z/OS XL C/C++ codepoint mappings . . . . . . . . . . 1127

Appendix D. Locales supplied withz/OS XL C/C++ . . . . . . . . . . 1129Compiled locales . . . . . . . . . . . . 1129Locale source files . . . . . . . . . . . 1149

Appendix E. Charmap files suppliedwith z/OS XL C/C++ . . . . . . . . 1155

Appendix F. Examples of charmapand locale definition source . . . . 1159Charmap file . . . . . . . . . . . . . 1159Locale definition source file . . . . . . . . 1164Locale method source file . . . . . . . . . 1169

Appendix G. Converting hybrid codeto a specific character set . . . . . 1171Sample program . . . . . . . . . . . . 1171

Appendix H. Additional Examples 1179Memory Management . . . . . . . . . . 1179Calling MVS WTO routines from C. . . . . . 1186Listing Partitioned Data Set Members . . . . . 1188

xii z/OS XL C/C++ Programming Guide

Appendix I. Applicationconsiderations for z/OS UNIX XLC/C++ . . . . . . . . . . . . . . 1193Relationship to DB2 universal database . . . . 1193Application programming environments notsupported . . . . . . . . . . . . . . 1193Support for the Curses library . . . . . . . 1193

Appendix J. External variables . . . 1195errno . . . . . . . . . . . . . . . . 1195daylight . . . . . . . . . . . . . . . 1196getdate_err . . . . . . . . . . . . . . 1196h_errno . . . . . . . . . . . . . . . 1196__loc1 . . . . . . . . . . . . . . . 1196loc1 . . . . . . . . . . . . . . . . 1196loc2 . . . . . . . . . . . . . . . . 1197locs . . . . . . . . . . . . . . . . 1197optarg . . . . . . . . . . . . . . . 1197opterr . . . . . . . . . . . . . . . 1197optind . . . . . . . . . . . . . . . 1197optopt . . . . . . . . . . . . . . . 1197signgam . . . . . . . . . . . . . . . 1197stdin . . . . . . . . . . . . . . . . 1197stderr. . . . . . . . . . . . . . . . 1197stdout . . . . . . . . . . . . . . . 1198t_errno . . . . . . . . . . . . . . . 1198timezone . . . . . . . . . . . . . . 1198tzname . . . . . . . . . . . . . . . 1198

Appendix K. Packagingconsiderations . . . . . . . . . . 1199Compiler options . . . . . . . . . . . . 1199Libraries. . . . . . . . . . . . . . . 1199Prelinking . . . . . . . . . . . . . . 1200Linking . . . . . . . . . . . . . . . 1200

Appendix L. Accessibility. . . . . . 1203Accessibility features . . . . . . . . . . 1203Consult assistive technologies . . . . . . . 1203Keyboard navigation of the user interface . . . 1203Dotted decimal syntax diagrams . . . . . . 1203

Notices . . . . . . . . . . . . . 1207Terms and conditions for product documentation 1209IBM Online Privacy Statement . . . . . . . 1210Policy for unsupported hardware . . . . . . 1210Minimum supported hardware . . . . . . . 1210Permission Notice . . . . . . . . . . . 1211Programming interface information. . . . . . 1211Trademarks. . . . . . . . . . . . . . 1211Standards . . . . . . . . . . . . . . 1212

Bibliography . . . . . . . . . . . 1213

Index . . . . . . . . . . . . . . 1215

Contents xiii

xiv z/OS XL C/C++ Programming Guide

Figures

1. Blocking fixed-length records . . . . . . 132. Variable-length records on z/OS . . . . . 173. Memory file example . . . . . . . . . 314. ASA Example . . . . . . . . . . . . 485. ungetwc() Example . . . . . . . . . . 596. Interleaving I/O with sync_with_stdio() 657. Interleaving I/O without sync_with_stdio() 678. MVS example of redirecting three standard

streams by ddnames . . . . . . . . . 739. Example of using stdout and stderr to share

the same file . . . . . . . . . . . . 7410. Example of passing text streams . . . . . 7611. Example of passing record I/O streams 7812. Example of command line redirection . . . . 8113. Generation data group example for C . . . . 8814. Generation data group example for C++ 8915. How the operating system completes the

DCB . . . . . . . . . . . . . . 10416. Example of reading updated records . . . . 11317. Example of signal handler . . . . . . . 12218. fldata() Structure . . . . . . . . . . 12419. Unnamed pipes example. . . . . . . . 13720. Named pipes example . . . . . . . . 13921. Example of z/OS UNIX stream input and

output functions . . . . . . . . . . 14222. Example of HFS stream input and output

functions . . . . . . . . . . . . . 14623. fldata() structure . . . . . . . . . . 14824. Types and advantages of VSAM data sets 15325. VSAM example . . . . . . . . . . . 15526. KSDS example . . . . . . . . . . . 17927. KSDS example . . . . . . . . . . . 18428. RRDS example . . . . . . . . . . . 18729. fldata() structure . . . . . . . . . . 18930. fldata() structure . . . . . . . . . . 19931. Removing members of a PDS . . . . . . 20732. Renaming members of a PDS . . . . . . 20833. fldata() structure . . . . . . . . . . 21334. Memory file example, part 1 . . . . . . 21435. Memory file example, part 2 . . . . . . 21436. fldata() structure . . . . . . . . . . 22037. fldata() example . . . . . . . . . . 22138. CELQPIPI MSGRTN example . . . . . . 22139. __amrc structure . . . . . . . . . . 22340. Example of printing the __amrc structure 22641. __amrc2 structure . . . . . . . . . . 22742. Example of using SIGIOERR . . . . . . 23243. Sample File I/O Trace. . . . . . . . . 23444. Example of parameter lists For OS linkages 24745. EDCXPRLG macro with an ALIAS statement 25246. Call to an XPLINK routine with no

parameters . . . . . . . . . . . . 25347. Call to an XPLINK routine with 5 parameters 25448. Establishing the C runtime environment 25549. Calling an intermediate C function from

Assembler OS linkage. . . . . . . . . 256

50. Intermediate C routine calling a runtimelibrary function . . . . . . . . . . . 256

51. Establishing the XL C/C++ runtimeenvironment . . . . . . . . . . . . 257

52. Calling an intermediate XL C/C++ functionfrom Assembler using OS linkage . . . . . 257

53. Intermediate XL C/C++ routine calling aruntime library function . . . . . . . . 257

54. Interface for preinitializable programs 26055. Preinitializing a C program (CCNGCA6) 26456. Using the preinitializable program

(CCNGCA7) . . . . . . . . . . . . 26657. Using the preinitializable program

(CCNGCA8) . . . . . . . . . . . . 26758. JCL for running a preinitializable C program 26959. Explicit use of a DLL in an application using

the dllload() family of functions . . . . . 28560. Explicit use of a DLL in an application using

the dlopen() family of functions . . . . . 28761. Using #pragma export to create a DLL

executable module named BASICIO . . . . 29162. Using #pragma export to create the triangle

DLL executable module . . . . . . . . 29263. Using _Export to create the triangle DLL

executable module . . . . . . . . . . 29264. Summary of DLL and DLL application

preparation and usage . . . . . . . . 29665. Referencing functions and external variables

in DLL code . . . . . . . . . . . . 30666. Pointer Assignment in DLL code . . . . . 30767. Pointer assignment in non-DLL code 30868. File 1. Application A . . . . . . . . . 30969. File 2. Application A . . . . . . . . . 30970. File 3. Application B . . . . . . . . . 31071. File 4. DLL . . . . . . . . . . . . 31072. DLL function pointer call in non-DLL code 31173. DLL function pointer call in non-DLL code 31274. C non-DLL code . . . . . . . . . . 31375. C DLL code . . . . . . . . . . . . 31476. C++ DLL code . . . . . . . . . . . 31477. C++ DLL code calling an Assembler function 31478. Comparison of function pointers in non-DLL

code . . . . . . . . . . . . . . 31579. C DLL code . . . . . . . . . . . . 31580. C non-DLL code . . . . . . . . . . 31581. File 1 C DLL code . . . . . . . . . . 31682. File 2 C DLL code . . . . . . . . . . 31683. File 3 C non-DLL code . . . . . . . . 31684. Comparison of two DLL function pointers in

non-DLL code . . . . . . . . . . . 31685. Undefined comparison in DLL code (C or

C++) . . . . . . . . . . . . . . 31886. Comparison of function pointers in DLL code

(C or C++) . . . . . . . . . . . . 31887. Valid comparisons in DLL code (C or C++) 31988. Application CCNGA2. . . . . . . . . 320

© Copyright IBM Corp. 1996, 2017 xv

89. Application CCNGA2D1 . . . . . . . . 32090. Application CCNGA2D2 . . . . . . . . 32191. Application CCNGA2D3 . . . . . . . . 32192. CCNGA2M1 . . . . . . . . . . . . 32293. CCNGA2M2 . . . . . . . . . . . . 32394. Comparison of struct li, alignments under

ILP32 and LP64 . . . . . . . . . . . 33595. Comparison of struct lii alignments under

ILP32 and LP64 . . . . . . . . . . . 33696. Comparison of struct ili alignments under

ILP32 and LP64 . . . . . . . . . . . 33797. Example of potential alignment problems

when a struct is shared or exchanged among32-bit and 64-bit processes . . . . . . . 346

98. Example of user-defined data padding for astructure that is shared or exchanged among32-bit and 64-bit processes . . . . . . . 350

99. Referring to thread-specific data . . . . . 360100. Controlling external static . . . . . . . 371101. Making strings constant . . . . . . . . 372102. Example of controllong the memory area 372103. How to Make String Literals Modifiable 373104. Referencing objects in the writable static area,

Part 1 . . . . . . . . . . . . . . 374105. Referencing objects in the writable static area,

Part 2 . . . . . . . . . . . . . . 375106. Arithmetic operators example . . . . . . 380107. Relational operators example . . . . . . 381108. Getting the total number of bytes occupied by

the decimal data type . . . . . . . . . 383109. Getting the total number of digits in the

decimal data type . . . . . . . . . . 384110. Getting the number of decimal digits in the

decimal data type . . . . . . . . . . 384111. Fractional part cannot be represented 386112. Integral part cannot be represented . . . . 386113. Conversion to integer type . . . . . . . 387114. Conversion from integral type . . . . . . 387115. Conversion to floating-point type . . . . . 388116. Conversion from floating-point type . . . . 388117. Decimal type — Example 1 . . . . . . . 391118. Output produced by CCNGDC3 . . . . . 392119. Decimal type — example 2 . . . . . . . 393120. Output produced by CCNGDC4 . . . . . 393121. Example illustrating C++ exception

handling/traceback . . . . . . . . . 405122. Example illustrating C++ exception

handling/traceback . . . . . . . . . 406123. Example illustrating signal handling . . . . 424124. An electrical analogy showing the socket

concept . . . . . . . . . . . . . 427125. A typical stream socket session . . . . . 436126. A typical datagram socket session. . . . . 437127. An application using socket() . . . . . . 438128. An application using bind() . . . . . . . 438129. A bind() function using gethostbyname() 439130. An application using listen() . . . . . . 439131. An application using connect() . . . . . . 440132. An application using accept() . . . . . . 440133. An application using send() and recv() 441134. An application using sendto() and recvfrom() 441

135. An application using select() . . . . . . 442136. An Application Using ioctl() . . . . . . 443137. An application using close(). . . . . . . 443138. A conceptual overview of the compile, bind,

and run steps . . . . . . . . . . . 445139. stackadd.cpp file (ccntmp3.cpp) . . . . . 459140. stackops.cpp file (ccntmp4.cpp) . . . . . 459141. stack.h file (ccntmp2.h) . . . . . . . . 459142. stack.c file (ccntmp1.c) . . . . . . . . 460143. stackops.h File (ccntmp5.h) . . . . . . . 460144. JCL to compile source Files and TEMPINC

destination . . . . . . . . . . . . 460145. z/OS UNIX Syntax . . . . . . . . . 461146. Simple and typical use of explicit

instantiation declarations. . . . . . . . 464147. Erroneous use of explicit instantiation

declarations . . . . . . . . . . . . 465148. _CEE_RUNOPTS behaviour. . . . . . . 486149. Environment variables example-Part 1 503150. Environment variables example-Part 2 504151. z/Architecture FPC register-rounding mode

definitions . . . . . . . . . . . . 542152. Biased exponent type definitions . . . . . 543153. Test Data Class masks . . . . . . . . 543154. Test Data Group masks . . . . . . . . 544155. Multiply and add even of integer elements

(32-bit) . . . . . . . . . . . . . . 595156. Multiply and add high of integer elements

(32-bit) . . . . . . . . . . . . . . 596157. Multiply and add low of integer elements

(32-bit) . . . . . . . . . . . . . . 598158. Multiply and add odd of integer elements

(32-bit) . . . . . . . . . . . . . . 599159. Multiply and sum with optional

multiplication by 2. . . . . . . . . . 601160. Even multiply of 4 integer elements (16-bit) 602161. Odd multiply of 4 integer elements (16-bit) 603162. Sum across doubleword of unsigned integer

elements (32-bit) . . . . . . . . . . 607163. Sum across word of unsigned short elements

(16-bit) . . . . . . . . . . . . . . 608164. Merge 2 high-order elements (32-bit) 654165. Merge 2 low-order elements (32-bit) . . . . 655166. Pack 8 integer elements (32-bit) to 8 integer

elements (16-bit) . . . . . . . . . . 656167. Pack 8 integer elements (32-bit) to 8 integer

elements (16-bit) . . . . . . . . . . 657168. Unpack high-order integer elements (16-bit)

to integer elements (32-bit) . . . . . . . 659169. Unpack low-order integer elements (16-bit) to

integer elements (32-bit) . . . . . . . . 660170. Bit-wise conditional select of vector contents

(128-bit) . . . . . . . . . . . . . 665171. Example of code that requires the global

namespace syntax . . . . . . . . . . 713172. Numeric conversions example . . . . . . 738173. Example of using OPTIMIZE(2) . . . . . 757174. Flow of regular compiler processing . . . . 767175. IPA compile step processing . . . . . . 768176. IPA link step processing . . . . . . . . 769

xvi z/OS XL C/C++ Programming Guide

|||

177. Specifying alternative initialization at linkedit . . . . . . . . . . . . . . . 831

178. Sample Freestanding z/OS Routine . . . . 834179. Link edit control statements used to build a

freestanding z/OS routine . . . . . . . 834180. Compile and link using EDCCL . . . . . 834181. Sample reentrant freestanding z/OS routine 835182. Building and running a reentrant freestanding

z/OS routine. . . . . . . . . . . . 835183. System exit example . . . . . . . . . 838184. Example of function used in a persistent C

environment . . . . . . . . . . . . 842185. Using a persistent C environment . . . . . 843186. Example of user routine . . . . . . . . 847187. Example of application service routine 848188. Example of server initialization stub . . . . 852189. Example of server message stub-LIFO 854190. Example of server message stub-FIFO 855191. Example of server message stub-GET 857192. Example of server message stub-TERM 858193. Example of routine to generate abend 862194. Example of routine to get storage . . . . . 863195. Example of routine to free storage . . . . 864196. Location of user exits . . . . . . . . . 876197. Interface for Assembler user exits . . . . . 881198. CEEAUE_FLAGS format . . . . . . . . 882199. Exit_list and hook_exit control blocks 891200. Computational independence . . . . . . 894201. Example of a C program running without

MTF . . . . . . . . . . . . . . 895202. Example of a C program running without

MTF (Part 2) . . . . . . . . . . . . 896203. Processor usage with one parallel function 897204. Sample program using one parallel function 898205. Processor usage with two parallel function 898206. Sample program using two parallel functions 899207. Processor use with multiple instances of the

same parallel function . . . . . . . . 900208. Sample program using multiple instances of

the same parallel function . . . . . . . 901209. Basic MTF layout . . . . . . . . . . 903210. Identifying Computationally-Independent

Code . . . . . . . . . . . . . . 906211. Sample code as a parallel function . . . . 906212. Scheduling instances of a parallel function 907213. Main task program to call dot product

function . . . . . . . . . . . . . 907214. Sample code to be changed to use MTF 908215. Sample code (main routine) . . . . . . . 909216. Sample code (routine to create parallel

functions) . . . . . . . . . . . . . 910217. Sample JCL to compile and link main task

program . . . . . . . . . . . . . 911218. Sample JCL to compile and link parallel

functions . . . . . . . . . . . . . 911219. Source code for EDCMTFS . . . . . . . 912220. Example runtime JCL . . . . . . . . . 913221. Example illustrating how to use EXEC CICS

commands . . . . . . . . . . . . 920222. Format of data written to a CICS data queue 923

223. Example illustrating error handling underCICS . . . . . . . . . . . . . . 929

224. Example illustrating how to use EXEC CICScommands . . . . . . . . . . . . 934

225. Child C program after translation . . . . . 935226. JCL to translate and compile a C program 938227. JCL to translate and compile a C++ program 938228. JCL to install z/OS XL C/C++ application

programs . . . . . . . . . . . . . 940229. C/370 CALLing CSP under TSO . . . . . 942230. z/OS XL C transferring control to CSP under

TSO using the XFER/DXFR statement . . . 944231. CSP CALLing z/OS XL C under TSO 946232. CSP transferring control to z/OS XL C under

TSO using the XFER statement. . . . . . 947233. CSP CALLing z/OS XL C under CICS 949234. CSP transferring control to z/OS XL C under

CICS using the XFER statement . . . . . 950235. CSP Transferring Control to z/OS XL C under

CICS Using the DXFR Statement . . . . . 952236. Example using DWS and C++ . . . . . . 955237. z/OS XL C/C++ Using Data Window

Services . . . . . . . . . . . . . 956238. Using DB2 with C . . . . . . . . . . 960239. Using DB2 with C/C++ . . . . . . . . 962240. Example using GDDM and C . . . . . . 966241. Example using GDDM and C++ . . . . . 968242. C++ Program using IMS . . . . . . . . 973243. C Program using IMS . . . . . . . . . 975244. Header file for IMS example . . . . . . 976245. QMF interface example . . . . . . . . 980246. C++ Calling a C program that accesses QMF 982247. C program that accesses QMF . . . . . . 983248. Conceptual model of the locale build process 993249. Example locale source containing header,

body, and trailer . . . . . . . . . . 1003250. Example LC_CTYPE definition . . . . . 1007251. Example LC_COLLATE definition . . . . 1012252. Example LC_MONETARY definition 1018253. Example LC_NUMERIC definition 1019254. Example LC_MESSAGES definition 1022255. Example LC_TOD definition . . . . . . 1024256. Example definition of LC_SYNTAX 1026257. Expected grammar for method files 1028258. Referring explicitly to a customized locale 1046259. Referring implicitly to a customized locale 1047260. Using environment variables to select a

locale . . . . . . . . . . . . . . 1048261. Additional locale categories for POSIX C 1054262. Determining which locale is in effect 1060263. Supplied code set converters . . . . . . 1064264. Example of hybrid coded character set 1088265. Compile-edit, related to locale function 1090266. Example of __CODESET__ macro . . . . 1093267. Values of macros __FILETAG__,

__LOCALE__, and __CODESET__ . . . . 1094268. Using the CONVLIT compiler option 1095269. Example of output when locale option is

used . . . . . . . . . . . . . . 1098270. Using the pragma convert directive 1100271. Example of using a layout string modifier 1109

Figures xvii

|||

272. Example of using the m_setvalues_layout()function . . . . . . . . . . . . . 1109

273. Example of bidirectional layout API's 1113274. Variant characters . . . . . . . . . . 1122275. CCNGMV1: Displaying hexadecimal values 1123276. Sample ISPF macro for displaying square

brackets . . . . . . . . . . . . . 1125277. Coded character set for Latin 1/Open

systems . . . . . . . . . . . . . 1127278. Coded character set for APL . . . . . . 1128279. Charmap file . . . . . . . . . . . 1159280. Example locale definition source file 1165

281. Example locale method source file . . . . 1170282. Converting hybrid C syntax from code page

IBM-1047 . . . . . . . . . . . . 1171283. Debuggable malloc()/calloc()/realloc()/free()

example . . . . . . . . . . . . . 1179284. Main routine - debuggable

malloc()/calloc()/realloc()/free() example . . 1180285. Performing a Write To Operator . . . . . 1187286. Performing a Write To Operator . . . . . 1188287. Example of Listing All Members of a PDS 1189288. ccngip2.h Header file . . . . . . . . 1192

xviii z/OS XL C/C++ Programming Guide

Tables

1. Syntax examples . . . . . . . . . . xxvi2. z/OS XL C/C++ and related documents xxviii3. Documents by task . . . . . . . . . xxx4. C control to ASA characters . . . . . . . 155. Summary of prototype functions . . . . . 276. Kinds of I/O supported by z/OS XL C/C++ 297. I/O categories and environments that support

them . . . . . . . . . . . . . . . 308. fopen() defaults for LRECL and BLKSIZE

when creating OS files . . . . . . . . . 359. C control to ASA characters translation table 47

10. Manipulating wide character arrays . . . . 6111. C standard streams . . . . . . . . . . 6312. C++ standard streams . . . . . . . . . 6413. z/OS XL C/C++ Redirection symbols . . . . 6914. Output destinations under z/OS XL C/C++ 7015. z/OS XL C/C++ Interleaved output . . . . 7116. Association of standard streams with ddnames 7317. Standard stream behavior differences . . . . 7918. PDSE and PDS differences . . . . . . . 9019. Rules for possible concatenations . . . . . 9120. Other devices supported for input and output 9621. Parameters for the fopen() and freopen()

functions for z/OS OS I/O . . . . . . . 9722. fopen() defaults for LRECL and BLKSIZE

when creating OS files . . . . . . . . 10423. C control to ASA characters . . . . . . . 10924. Parameters for the fopen() and freopen()

functions for z/OS UNIX file system I/O . . 13125. Summary of VSAM data set characteristics

and allowable I/O operations . . . . . . 15526. Keywords for the fopen() and freopen()

functions for VSAM data sets . . . . . . 15927. Summary of VSAM record I/O operations 16828. AMODE31 application XADDR support 17129. Summary of fseek() and ftell() parameters in

text and binary . . . . . . . . . . . 17430. Summary of VSAM text I/O operations 17531. Summary of VSAM binary I/O operations 17532. Keywords for the fopen() and freopen()

functions for terminal I/O . . . . . . . 19233. Keywords for the fopen() and freopen()

functions for memory file I/O . . . . . . 20334. __last_op codes and diagnosis information 22735. Linkage used by C or C++ Interlanguage

Programs . . . . . . . . . . . . . 24036. Comparison of non-XPLINK and XPLINK

register conventions . . . . . . . . . 24837. Load service routine parameters . . . . . 27338. Delete service routine parameters . . . . . 27439. Get-storage service routine parameters 27440. Free-storage service routine parameters 27541. Exception router service routine parameters 27542. Attention router service routine parameters 27743. Attention handler parameters . . . . . . 27744. Message router service routine parameters 278

45. Summary of DLL concepts and terms 28246. Example programs to demonstrate compiling

options . . . . . . . . . . . . . 30447. Examples of how to compile two source

modules and list result . . . . . . . . 30448. Referencing functions and external variables 30549. Comparison of ILP32 and LP64 addressing

capabilities . . . . . . . . . . . . 32550. Comparison of ILP32 and LP64 data models 32551. ILP32 and LP64 type size comparisons for

signed and unsigned data types . . . . . 32652. Example of diagnostic messages generated

from code that is not ready to be migratedfrom ILP32 to LP64 . . . . . . . . . 329

53. Comparison of ILP32 and LP64 processingand runtime options . . . . . . . . . 332

54. Comparison of data structure member lengthsproduced from the same code . . . . . . 333

55. Example of possible change of result afterconversion from signed number to unsignedlong . . . . . . . . . . . . . . 338

56. Example of possible change of result afterconversion from unsigned int variable tosigned long . . . . . . . . . . . . 338

57. Example of possible change of result afterconversion from signed long long variable tounsigned long . . . . . . . . . . . 339

58. Example of possible change of result afterconversion from unsigned long long variableto unsigned long . . . . . . . . . . 339

59. Example of possible change of result afterconversion from signed long long variable tosigned long . . . . . . . . . . . . 340

60. Example of possible change of result afterconversion from unsigned long long variableto signed long . . . . . . . . . . . 341

61. Example of source code that explicitlyconverts an integer to a pointer . . . . . 342

62. Example of truncation problem with a pointercast conversion . . . . . . . . . . . 343

63. Type of an integer constant . . . . . . . 34464. An attempt to share pointers between 32-bit

and 64-bit processes . . . . . . . . . 34465. Example of unexpected behavior resulting

from use of unsuffixed numbers . . . . . 34666. Example of using LONG_MAX macros in a

printf subroutine . . . . . . . . . . 34767. Example of source code that successfully

shares pointers between ILP32 and LP64programs . . . . . . . . . . . . . 349

68. Functions used in creating multi-threadedapplications . . . . . . . . . . . . 353

69. Functions to change default attributes 35370. Functions used to control individual threads

in a multi-threaded environment . . . . . 354

© Copyright IBM Corp. 1996, 2017 xix

|

71. Functions that allow for synchronizationbetween threads . . . . . . . . . . 355

72. Functions used with thread-specific data 35973. Cancellation point summary . . . . . . 36374. Functions used to control cancellability 36375. Functions used for cleanup purposes 36476. Declarations of fixed-point decimal constants 37877. Examples of Fixed-Point decimal constants

and their attributes . . . . . . . . . 37878. Intermediate results (without overflow in n or

p) . . . . . . . . . . . . . . . 38279. Intermediate results (in the general form) 38280. Operators used with decimal data types 38481. C/C++ functions that support floating-point 39982. Special purpose C/C++ functions that

support floating-point. . . . . . . . . 40283. Functions that establish a signal handler 41184. Other signal-related functions . . . . . . 41185. Hardware exceptions - Default runtime

messages and system actions . . . . . . 41786. Software exceptions - Default runtime

messages and system actions withPOSIX(OFF) . . . . . . . . . . . . 417

87. Default signal processing with POSIX(ON) 41988. Original versions of fdlibm functions 49589. Standard general-instruction prototypes 50590. Built-in general-instruction prototypes 50791. PLO helper macros . . . . . . . . . 52592. Compare and load prototypes . . . . . . 52693. Compare and swap prototypes. . . . . . 52694. Double compare and swap prototypes 52795. Compare and swap and store prototypes 52796. Compare swap and double store prototypes 52897. Compare and swap and triple store

prototypes . . . . . . . . . . . . 52898. Decimal instruction prototypes. . . . . . 52999. Floating-point instruction prototypes 533

100. Decimal floating-point instruction prototypesfor IEEE operations . . . . . . . . . 534

101. Decimal floating-point instruction prototypesfor IEEE . . . is operations . . . . . . . 536

102. Decimal floating-point instruction prototypesfor IBM Instructions . . . . . . . . . 537

103. Instruction prototypes for conversionsbetween decimal floating-point and zonedtypes . . . . . . . . . . . . . . 541

104. Hexadecimal floating-point instructionprototypes . . . . . . . . . . . . 544

105. Binary floating-point instruction prototypes 545106. Built-in functions for transactional memory 548107. Vector data types . . . . . . . . . . 555108. Vector literals . . . . . . . . . . . 556109. Unary operators . . . . . . . . . . 560110. Increment value for vec_step by data type 561111. Binary operators . . . . . . . . . . 562112. Relational operators . . . . . . . . . 562113. Accepted vector data types for multiplication

operator * . . . . . . . . . . . . . 563114. Accepted vector data types for division

operator / . . . . . . . . . . . . 563

115. Accepted vector data types for remainderoperator % . . . . . . . . . . . . 564

116. Accepted vector data types for additionoperator + . . . . . . . . . . . . 564

117. Accepted vector data types for subtractionoperator - . . . . . . . . . . . . . 565

118. Accepted vector data types for bitwise leftshift operator > . . . . . . . . . . 566

120. Accepted vector data types for relational lessthan operator < . . . . . . . . . . . 567

121. Accepted vector data types for relationalgreater than operator > . . . . . . . . 567

122. Accepted vector data types for relational lessthan or equal to operator = . . . . 568

124. Accepted vector data types for equalityoperator == . . . . . . . . . . . . 569

125. Accepted vector data types for inequalityoperator != . . . . . . . . . . . . 569

126. Accepted vector data types for bitwise ANDoperator & . . . . . . . . . . . . 570

127. Accepted vector data types for bitwiseexclusive OR operator ^ . . . . . . . . 571

128. Accepted vector data types for bitwiseinclusive OR operator | . . . . . . . . 571

129. Deprecated vector data types for additionoperator + . . . . . . . . . . . . 573

130. Deprecated vector data types for subtractionoperator - . . . . . . . . . . . . . 573

131. Deprecated vector data types for relationalgreater than operator > . . . . . . . . 574

132. Deprecated vector data types for relationalless than operator < . . . . . . . . . 575

133. Deprecated vector data types for relationalgreater than or equal to operator >= . . . . 575

134. Deprecated vector data types for relationalless than or equal to operator

147. Vector built-in functions for loading andstoring vectors . . . . . . . . . . . 586

148. Vector built-in functions for logical calculation 586149. Vector built-in functions for merging vectors 586150. Vector built-in functions for pack and unpack 587151. Vector built-in functions for replicating vector

elements . . . . . . . . . . . . . 587152. Vector built-in functions for rotate and shift 587153. Vector built-in functions for rounding and

conversion . . . . . . . . . . . . 588154. Vector built-in functions for testing . . . . 588155. Vector built-in functions for searching and

comparing all elements . . . . . . . . 588156. Vector built-in functions for searching and

comparing any elements . . . . . . . . 589157. Vector Absolute Value. . . . . . . . . 590158. Vector Add unsigned 128-bits . . . . . . 590159. Vector Add Carryout . . . . . . . . . 590160. Vector Add Compute Carryout unsigned

128-bits . . . . . . . . . . . . . 591161. Vector Add With Carry unsigned 128-bits 591162. Vector Add With Carry Compute Carry

unsigned 128-bits . . . . . . . . . . 591163. Vector Average . . . . . . . . . . . 592164. Vector Checksum . . . . . . . . . . 592165. Vector Galois Field Multiply Sum . . . . . 592166. Vector Galois Field Multiply Sum 128-bits 593167. Vector Galois Field Multiply Sum and

Accumulate . . . . . . . . . . . . 593168. Vector Galois Field Multiply Sum and

Accumulate 128-bits . . . . . . . . . 593169. Vector Multiply Add . . . . . . . . . 594170. Vector Maximum . . . . . . . . . . 594171. Vector Multiply and Add Even. . . . . . 595172. Vector Multiply and Add High. . . . . . 596173. Vector Minimum . . . . . . . . . . 597174. Vector Multiply and Add Low . . . . . . 598175. Vector Multiply and Add Odd . . . . . . 599176. Vector Multiply Subtract . . . . . . . . 600177. Vector Multiply Sum Logical . . . . . . 601178. Vector Multiply Even . . . . . . . . . 602179. Vector Multiply High . . . . . . . . . 602180. Vector Multiply Odd . . . . . . . . . 603181. Vector Negative Absolute . . . . . . . 603182. Vector Negative Multiply Add . . . . . . 604183. Vector Negative Multiply Subtract . . . . 604184. Vector Square Root. . . . . . . . . . 604185. Vector Subtract unsigned 128-bits . . . . . 605186. Vector Subtract Carryout . . . . . . . . 605187. Vector Subtract Carryout unsigned 128-bits 606188. Vector Subtract with Carryout . . . . . . 606189. Vector Subtract with Carryout, Carryout 606190. Vector Sum Across Quadword . . . . . . 607191. Vector Sum Across Doubleword . . . . . 607192. Vector Sum Across Word. . . . . . . . 608193. Vector Compare Equal . . . . . . . . 609194. Vector Compare Equal Index . . . . . . 609195. Vector Compare Equal Index with Condition

Code . . . . . . . . . . . . . . 610196. Vector Compare Equal or Zero Index 610

197. Vector Compare Equal or Zero Index withCondition Code . . . . . . . . . . . 611

198. Vector Compare Greater Than or Equal 611199. Vector Compare Greater Than . . . . . . 612200. Vector Compare Less Than or Equal . . . . 613201. Vector Compare Less Than . . . . . . . 613202. Vector Compare Not Equal Index . . . . . 614203. Vector Compare Not Equal Index with

Condition Code . . . . . . . . . . . 615204. Vector Compare Not Equal or Zero Index 615205. Vector Compare Not Equal or Zero Index

with Condition Code . . . . . . . . . 616206. Vector Compare Not in Ranges . . . . . 617207. Vector Compare Not in Ranges with

Condition Code . . . . . . . . . . . 618208. Vector Compare Not in Ranges Index 619209. Vector Compare Not in Ranges Index with

Condition Code . . . . . . . . . . . 620210. Vector Compare Not in Ranges or Zero Index 621211. Vector Compare Not in Ranges or Zero Index

with Condition Code . . . . . . . . . 622212. Vector Compare Ranges . . . . . . . . 622213. Vector Compare Ranges with Condition Code 624214. Vector Compare Ranges Index . . . . . . 624215. Vector Compare Ranges Index with Condition

Code . . . . . . . . . . . . . . 626216. Vector Compare Ranges or Zero Index 626217. Vector Compare Ranges or Zero Index with

Condition Code . . . . . . . . . . . 628218. Vector Find Any Element Equal . . . . . 628219. Vector Find Any Element Equal with

Condition Code . . . . . . . . . . . 629220. Vector Find Any Element Equal Index 629221. Vector Find Any Element Equal Index with

Condition Code . . . . . . . . . . . 630222. Vector Find Any Element Equal or Zero Index 631223. Vector Find Any Element Equal or Zero Index

with Condition Code . . . . . . . . . 632224. Vector Find Any Element Not Equal . . . . 632225. Vector Find Any Element Not Equal with

Condition Code . . . . . . . . . . . 633226. Vector Find Any Element Not Equal Index 633227. Vector Find Any Element Not Equal Index

with Condition Code . . . . . . . . . 634228. Vector Find Any Element Not Equal or Zero

Index . . . . . . . . . . . . . . 635229. Vector Find Any Element Not Equal or Zero

Index with Condition Code . . . . . . . 636230. Vector Bit Permute . . . . . . . . . . 636231. Vector Extract . . . . . . . . . . . 637232. Vector Gather Element . . . . . . . . 637233. Vector Insert . . . . . . . . . . . . 638234. Vector Insert and Zero . . . . . . . . 638235. Vector Permute . . . . . . . . . . . 639236. Vector Promote . . . . . . . . . . . 640237. Vector Scatter Element . . . . . . . . 640238. Vector Select . . . . . . . . . . . . 641239. Vector Generate Byte Mask . . . . . . . 642240. Vector Generate Mask (Byte) . . . . . . 643241. Vector Generate Mask (Halfword). . . . . 643242. Vector Generate Mask (Word) . . . . . . 643

Tables xxi

||

||||

||

243. Vector Generate Mask (Doubleword) 644244. Vector Copy Until Zero . . . . . . . . 644245. Vector Copy Until Zero . . . . . . . . 645246. Vector Load to Block Boundary . . . . . 645247. Vector Load with Length. . . . . . . . 646248. Vector Load Rightmost with Length . . . . 646249. Vector Load Pair . . . . . . . . . . 646250. Vector Store with Length. . . . . . . . 647251. Vector Store Rightmost with Length . . . . 647252. Vector Load . . . . . . . . . . . . 648253. Vector Store . . . . . . . . . . . . 648254. Vector AND With Complement . . . . . 649255. Vector Count Leading Zeros . . . . . . 649256. Vector Count Trailing Zeros . . . . . . . 650257. Vector Not Exclusive Or . . . . . . . . 651258. Vector NAND . . . . . . . . . . . 651259. Vector NOR . . . . . . . . . . . . 652260. Vector OR with Complement . . . . . . 653261. Vector Population Count . . . . . . . . 653262. Vector Merge High. . . . . . . . . . 654263. Vector Merge Low . . . . . . . . . . 655264. Vector Pack . . . . . . . . . . . . 656265. Vector Pack Saturate . . . . . . . . . 657266. Vector Pack Saturate Condition Code 657267. Vector Pack Saturated Unsigned . . . . . 658268. Vector Pack Saturated Unsigned Condition

Code . . . . . . . . . . . . . . 658269. Vector Unpack High Element . . . . . . 659270. Vector Unpack Low Element . . . . . . 660271. Vector Splat . . . . . . . . . . . . 660272. Vector Splat Signed Byte . . . . . . . . 661273. Vector Splat Signed Halfword . . . . . . 661274. Vector Splat Signed Word . . . . . . . 661275. Vector Splat Signed Doubleword . . . . . 661276. Vector Splat Unsigned Byte . . . . . . . 662277. Vector Splat Unsigned Halfword . . . . . 662278. Vector Splat Unsigned Word . . . . . . 662279. Vector Splat Doubleword . . . . . . . 662280. Vector Splats . . . . . . . . . . . . 662281. Vector Element Rotate Left . . . . . . . 663282. Vector Element Rotate and Insert Under Mask 664283. Vector Element Rotate Left Immediate 664284. Vector Shift Left by Byte . . . . . . . . 664285. Vector Shift Left Double by Byte . . . . . 666286. Vector Shift Left Double by Word . . . . . 666287. Vector Shift Left. . . . . . . . . . . 667288. Vector Shift Right Arithmetic by Byte 667289. Vector Shift Right Arithmetic . . . . . . 668290. Vector Shift Right by Byte . . . . . . . 669291. Vector Shift Right . . . . . . . . . . 670292. Vector Ceiling . . . . . . . . . . . 670293. Vector Convert from Logical . . . . . . 671294. Vector Load Lengthened . . . . . . . . 671295. Extend Sign to Doubleword. . . . . . . 671296. Vector Load Rounded . . . . . . . . . 671297. Vector Floor . . . . . . . . . . . . 672298. Vector Round to Integer . . . . . . . . 672299. Vector Round to Nearest . . . . . . . . 673300. Vector Round to Current . . . . . . . . 673301. Vector Round toward Negative Infinity 673302. Vector Round toward Positive Infinity 674

303. Vector Round toward Zero . . . . . . . 674304. Vector Convert double to signed long long 674305. Vector Truncate . . . . . . . . . . . 674306. Vector Convert double to unsigned long long 675307. Vector Floating-Point Test Data Class 675308. Vector Test under Mask . . . . . . . . 676309. All Elements Equal . . . . . . . . . 677310. All Elements Greater Than or Equal . . . . 677311. All Elements Greater Than . . . . . . . 678312. All Elements Less Than or Equal . . . . . 679313. All Elements Less Than . . . . . . . . 679314. All Elements Not a Number . . . . . . 680315. All Elements Not Equal . . . . . . . . 680316. All Elements Not Greater Than or Equal 681317. All Elements Not Greater Than . . . . . 681318. All Elements Not Less Than or Equal 681319. All Elements Not Less Than . . . . . . 681320. All Elements Numeric . . . . . . . . 682321. Any Element Equal . . . . . . . . . 682322. Any Element Greater Than or Equal . . . . 683323. Any Element Greater Than . . . . . . . 684324. Any Element Less Than or Equal . . . . . 684325. Any Element Less Than . . . . . . . . 685326. Any Element Not Equal . . . . . . . . 685327. Any Element Not a Number . . . . . . 686328. Any Element Not Greater Than or Equal 686329. Any Element Not Greater Than . . . . . 686330. Any Element Not Less Than or Equal 687331. Any Element Not Less Than . . . . . . 687332. Any Element Numeric . . . . . . . . 687333. Deprecated prototypes of vec_all_eq 689334. Deprecated prototypes of vec_all_ge 690335. Deprecated prototypes of vec_all_gt 691336. Deprecated prototypes of vec_all_le 692337. Deprecated prototypes of vec_all_lt 693338. Deprecated prototypes of vec_all_ne 694339. Deprecated prototypes of vec_andc . . . . 694340. Deprecated prototypes of vec_any_eq 695341. Deprecated prototypes of vec_any_ge 696342. Deprecated prototypes of vec_any_gt 697343. Deprecated prototypes of vec_any_le 698344. Deprecated prototypes of vec_any_lt 699345. Deprecated prototypes o