ILE C/C++ Programmer's Guide
Part 1. Introduction
Chapter 1. Introduction to the ILE C/C++ Compiler
Multi-Language Program Creation
Programming Languages Supported by the OS/400 Operating System
ILE Program Creation
Binding Directories
Service Programs
Program and Resource Management
Program Flow
Resource Allocation
Bindable APIs
Run-Time Exceptions
Program Debugging
Part 2. Creating and Compiling Programs
Chapter 2. Creating a Program
The Program Development Process
Preparing a Program
Compiling a Program
Binding Modules
Running or Calling Objects
Debugging a Program
Entering Source Statements
Example Of Creating a Source File
Instructions
Source Code Sample
Creating a Program in One Step
Creating a Program in Two Steps
Identifying Program and User Entry Procedures
Understanding the Internal Structure of a Program Object
Using Static Procedure Calls
Working with Binding Directories
Creating a Binding Directory
Using the Binder to Create a Program
Preparing to Create a Program
Specifying Parameters for the CRTPGM Command
How Import Requests Are Resolved
Using a Binder Listing
Updating a Module or a Program Object
Updating a Program
Activating Groups
Messaging Support
Chapter 3. Service Programs
Differences Between Programs and Service Programs
Public Interface
Considerations When Creating a Service Program
Using the Binder to Create a Service Program
Specifying Parameters for the CRTSRVPGM Command
Updating or Changing a Service Program
Using Control Language (CL) Commands with Service Programs
Creating, Compiling, and Binding a Service Program
Creating the Source Files
Compiling and Binding the Service Program
Binding the Service Program to a Program
Chapter 4. Working with Exports from Service Programs
Determining Exports from Service Programs
Displaying Exported Defined Symbols with the Display Module Command
Creating a Binder Language Source File
Creating Binder Language Using SEU
Creating Binder Language Using the RTVBNDSRC Command
Updating a Service Program Export List
Using the Demangling Functions
Handling Unresolved Import Requests During Program Creation
Creating an Export Service Program Using Binder Language
Creating a Program with Circular References
Creating the Source Files
Compiling the Source Files into Modules
Generating the Binder Language to Create the Service Program
Binding the Modules into the Program
Handling Unresolved Import Requests Using the *UNRSLVREF Parameter
Handling Unresolved Import Requests by Changing Program Creation Order
Binding a Program to a Non-Existent Service Program
Instructions
Code Samples
Running the Program
Updating a Service Program Export List
Program Description
Creating the Source Files
Compiling and Binding Programs and Service Programs
Running the Program
Chapter 5. Running a Program
The ILE C/C++ Run-Time Model
Activations and Activation Groups
Run-Time Library Functions and Activation Groups
Calling Programs
Using the Call (CALL) Command
Using the Transfer Control (TFRCTL) Command
Creating a CL Command to Run a Program
Normal and Abnormal End-of-Program
Managing Activation Groups
Specifying an Activation Group
Presence of a Program on the Call Stack
Deleting an Activation Group
Reclaiming System Resources
Managing Run-Time Storage
Managing the Default Heap
Chapter 6. Improving Run-Time Performance
Choosing Data Types to Improve Performance
Avoiding Use of the Volatile Qualifier
Replacing Bit Fields with Other Data Types
Minimizing the Use of Static and Global Variables
Using the Register Storage Class
Creating Classes to Improve Performance
Enabling Performance Measurement
Using a Compiler Option to Enable Performance Measurement
Minimizing Exception Handling
Turning on Return Codes during Record I/O
Turning Off C2M Messages during Record Input and Output
Using a Direct Monitor Handler
Minimizing Percolation of Exceptions
Reducing the Number of Function Calls and Arguments
Inlining Function Calls
Using Static Class Member Functions or Global Variables
Passing Arguments in Registers
Using Prototypes to Minimize Function Call Processing
Choosing Input and Output Functions to Improve Performance
Using Record Input and Output Functions
ISO C Record I/O
ILE C Record I/O
Using Input and Output Feedback Information
Blocking Records
Manipulating the System Buffer
Opening Files Once for Both Input and Output
Minimizing the Use of Shared Files
Minimizing the Number of File Opens and Closes
Defining Tape Files to Improve Performance
Improving Performance when Using Stream Input and Output Functions
Using C++ Input and Output Stream Classes
Using Physical Files Instead of Source Physical Files
Specifying Library Names
Using Pointers to Improve Performance
Avoiding Use of Open Pointers
Avoiding Pointer Comparisons
Reducing Indirect Access through Pointers
Using Shallow Copy instead of Deep Copy
Minimizing Space Requirements
Choosing Appropriate Data Types
Minimizing Dynamic Memory Allocation Calls
Arranging Variables to Reduce Padding
Removing Observability
Compressing Objects
Optimizing Use of Activation Groups
Calling Functions in Other Activation Groups
Reducing Program Startup Time
Minimizing Use of Virtual Functions
Choosing Compiler Options to Optimize for Speed or Size
Setting Run-Time Limits
Chapter 7. Example: Creating an ILE C Application
Process Flow
ILE Activation Group
Resource Requirements
Task Summary
Instructions to Create the Sample Application
Source Code Samples
Source Code for an Audit Log File
Source Code Pass Terminal Session Input to an ILE Program
Source Code to Define a CL Command to Collect Session Data
Source Code for a User Entry Procedure (UEP)
Source Code to Calculate Tax and Format Cost for Output
Source Code to Write an Audit Trail
Source Code to Export Tax Rate Data
Binder Language to Export Tax Rate Data
Binder Language to Export the write-audit-trail Procedure
Part 3. Debugging Programs
Chapter 8. The ILE Source Debugger
Debug Data Options
Debug Language Syntax
Limitations of the Debug Language Syntax
Debug Commands
Examples of Using Debug Expressions in ILE C Programs
Examples of Program Definitions and Corresponding Debug Expressions
Examples of Displaying System and Space Pointers in the ILE Source Debugger
Chapter 9. Preparing a Program for Debugging
Setting Up a Test Library
Creating a Listing View for Debugging
Chapter 10. Working with Source Debug Sessions
Starting a Source Debug Session
Adding and Removing Programs from a Debug Session
Setting or Changing Debug Options During a Session
Example: Adding an OPM Program to an ILE Debug Session
Example: Setting Debug Options during a Debug Session
Viewing the Program Source
Displaying Other Modules in Your Program
Displaying a Different View Of a Module
Chapter 11. Using Breakpoints to Aid Debugging
Types Of Breakpoints
Job and Thread Breakpoints
Conditional and Unconditional Breakpoints
Setting Breakpoints
Setting Unconditional Breakpoints from the Display Module Source Display
Setting Unconditional Breakpoints from the Command Line
Setting Conditional Breakpoints for a Macro
Setting Conditional Breakpoints for a Statement
Setting Conditional Thread Breakpoints
Setting a Conditional Thread Breakpoint from the Work with Module Breakpoints Display
Setting a Conditional Thread Breakpoint from the Command Line
Testing Breakpoints
Removing All Breakpoints
Chapter 12. Using Watches to Aid Debugging
Characteristics and Limitations Of Watches
Setting and Removing Watch Conditions
Setting watch conditions
Using the WATCH Debug Command
Removing Watch Conditions
Automatic Removal Of Watch Conditions
Example Of Setting a Watch Condition
Displaying Active Watches
Chapter 13. Stepping Through Programs
Stepping Over Programs
Using F10 to Step Over Programs
Using the STEP OVER Debug Command
Stepping into Programs
Using F22 to Step into Programs
Using the STEP INTO Debug Command
Stepping into Called Programs
Example of Stepping into a Program Using F22
Stepping into an OPM Program
Stepping Over Procedures
Stepping into Procedures
Chapter 14. Debugging Variables
Displaying the Value Of a Variable
Using F11 to Display Variables
Changing the Value of a Variable
Changing the Value of a Scalar Variable
Equating a Name with a Variable, Expression, or Debug Command
Displaying a Structure
Displaying Variables As Hexadecimal Values
Displaying Null-Ended Character Arrays
Displaying Character Arrays
Sample EVAL Commands for Pointers, Variables, and Bit Fields
EVAL Commands for System and Space Pointers
Source for Sample EVAL Commands
Source for Sample EVAL Commands for Displaying System and Space Pointers
Source for Sample EVAL Commands for Displaying C++ Constructs
Chapter 15. Changing Module Optimization and Observability
Changing Optimization Levels
Removing Module Observability
Part 4. Performing I/O Operations
Chapter 16. Using ILE C/C++ Stream and Record I/O Functions with iSeries Data Management files
ILE C Record I/O Functions
Stream Buffering
Dynamic Stream File Creation
Open Modes for Dynamically Created Stream Files
Standard I/O Text Stream Files (<stdio.h>)
iSeries Data Management Files
iSeries Data Management File Types
Data Management Stream Files and ILE C I/O Operations
iSeries Data Management File Naming Conventions
File Control Structure of Text Streams and Binary Streams
I/O Processes for Text Stream Files
Opening Text Stream Files
Writing Text Stream Files
Reading Text Stream Files
Updating Text Stream Files
I/O Process for Binary Stream Files
Opening Binary Stream Files (character at a time)
Writing Binary Stream Files (character at a time)
Reading Binary Stream Files (character at a time)
Updating Binary Stream Files (character at a time)
Opening Binary Stream Files (record at a time)
Writing Binary Stream Files (record at a time)
Reading Binary Stream Files (record at a time)
Open Feedback Area
I/O Feedback Area
Using Session Manager
Obtaining the Session Handle
Using Session Manager APIs
Example: Using an ILE Bindable API to Display a DSM Session
Chapter 17. Using ILE C/C++ Stream Functions with the iSeries Integrated File System
The Integrated File System (IFS)
root(/) File System
Open Systems (QOpenSys) File System
Library (QSYS.LIB) File System
Document Library Services (QDLS) File System
LAN Server/400 (QLANSrv) File System
Optical Support (QOPT) File System
File Server (QFileSvr.400) File System
Enabling Integrated File System Stream I/O
Using Stream I/O with Large Files
Stream Files
Stream Files Versus Database Files
Text Streams
Binary Streams
Opening Text Stream and Binary Stream Files
Storing Data as a Text Stream or as a Binary Stream
Using the Integrated File System (IFS)
Copying Source Files into the IFS
Editing Stream Files
The SRCSTMF Parameter
Header File Search
Preprocessor Output
Listing Output
Code Pages and CCSIDs
Pitfalls to Avoid
Examples of Using Integrated File System Source
Using Stream I/O
Part 5. Working with iSeries File Systems and Devices
Chapter 18. Using Externally Described Files in a Program
Creating Externally Described Database Files
Creating Type Definitions
Creating Header Descriptions
Specifying the Record Format Name
Specifying Record Field Names
Including Database Files in the Type Definition
Defining the Structure Type (KEY Field)
Using Long Names for Files
Level Checking to Verify Descriptions
Using the GENCSRC Utility for Level Checking
Using the #pragma mapinc Directive for Level Checking
Avoiding Field Alignment Problems in C/C++ Structures
Including External Field Definitions in a Program
The INPUT Option
The OUTPUT Option
The BOTH Option
Defining and Using Indicators
Creation of Indicators in the File Buffer
Creating a Separate Indicator Area
Including Physical and Logical Database Files in a Program
Including Device Files in a Program
Including Externally Described Multiple Record Formats in a Logical File
Using Externally Described Packed Decimal Data in a Program
Chapter 19. Using Database Files and Distributed Data Management Files in a Program
Database Files and Distributed Data Management Files
Physical Files and Logical Files
Describing Records in Database Files
Data Files and Source Files
Access Paths
Arranging Key Fields
Duplicate Key Values
Deleted Records
Locking
Sharing
Null-Capable Fields
Opening Database and DDM Files as Record Files
Record Functions for Database and DDM Files
I/O Considerations for DDM Files
Opening Database and DDM Files as Binary Stream Files
I/O Considerations for Binary Stream Database and DDM Files
Binary Stream Functions for Database and DDM Files
Processing a Database Record File in Arrival Sequence
Instructions
Source Code Sample
Processing a Database Record File in Keyed Sequence
Processing a Database Record File Using Record Input and Output Functions
Synchronizing Database File Changes in a Single Job
Blocking Records
Chapter 20. Using Device Files in a Program
Using OS/400 Feedback Areas for all Device Files
Using Indicators to Transfer Information
Types of Indicators
Separate Indicator Areas
Major and Minor Return Codes
Example: Returning Indicators to a Separate Indicator Area
Example: Returning Indicators to the File Buffer
Establishing the Default Program Device
Changing the Default Program Device
Obtaining Feedback Information
Using Display Files and Subfiles
Display Files and Subfiles
Using Subfiles to Minimize I/O Operations
Opening Display Files and Subfiles as Binary Stream Files
Opening Display Files as Record Files
Using Intersystem Communication Function Files
I/O Considerations for Intersystem Communication Function Files
Opening ICF Files as Binary Stream Files
I/O Considerations for Binary Stream ICF Files
Binary Stream Functions for ICF Files
Opening ICF Files as Record Files
I/O Considerations for Record ICF Files
Record Functions for ICF Files
Using Printer Files
I/O Considerations for Printer Files
Opening Printer Files as Binary Stream Files
Opening Printer Files as Record Files
Record Functions for Printer Files
Writing to a Tape File
I/O Considerations for Tape Files
Opening Tape Files as Binary Stream Files
Binary Stream Functions for Tape Files
Opening Tape Files as Record Files
Record Functions for Tape Files
Writing to a Diskette File
I/O Considerations for Diskette Files
Opening Diskette Files as Binary Stream Files
Binary Stream Functions for Diskette Files
Opening Diskette Files as Record Files
Record Functions for Diskette Files
Using Save Files
I/O Considerations for Save Files
Opening Save Files as Binary Stream Files
I/O Considerations for Binary Stream Save Files
Binary Stream Functions for Save Files
Opening Save Files as Record Files
I/O Considerations for Record Save Files
Record Functions for Save Files
Part 6. Working with iSeries Features
Chapter 21. Handling Exceptions in a Program
ILE Language-Specific Error Handling
Exception Messages
How the System Processes Exceptions
How the Call Message Queue Handles ILE Procedures and Functions
How Control Boundaries Affect Exception Handling in ILE
Unmonitored Exceptions and Unhandled Exceptions
Nested Exceptions
Detecting Stream File and Record File Errors
Checking the Return Value of a Function
Checking the Errno Value
Checking the Major/Minor Return Code
Checking the System Exceptions for Record Files
Checking the Global Variable _EXCP_MSGID
Using ILE Exception Handlers
Types of Exception Handlers
Using ILE Direct Monitor Handlers
Using ILE Condition Handlers
Using the C/C++ Signal Handler
When to Use the Signal Handler
Raising Signals
Signal Handling Function Prototypes
How the ILE C/C++ Run-Time Environment Handles Signals
Resetting the Signal Action
Stacking Signal Handlers
Example: Setting Up a Signal Handler
Using Both C/C++ Signal and ILE Exception Handlers
Order of Priority
Example of Using a Direct Monitor Handler and Signal Handler Together
Handling Nested Exceptions
Using Cancel Handlers
Example: Using a Variety of Ways to Detect Errors and Handle Exceptions
Instructions
Source Code Samples
Chapter 22. Using OS/400 pointers in a Program
OS/400 pointer Types
Using Open Pointers
Using Pointers Other than Open Pointers
Declaring Pointer Variables
Declaring OS/400 pointer Variables in C and C++
Declaring a Function Pointer to a Bound Procedure in ILE C
Declaring a Function Pointer with OS-Linkage in ILE C and ILE C++
Casting Pointers
Example: Passing OS/400 pointers as Arguments on a Dynamic Program Call to Another ILE C Program
Instructions
Source Code Samples
Chapter 23. Using ILE C/C++ Call Conventions
Program and Procedure Calls
Using Dynamic Program Calls
How the ILE Call Stack Is Used to Control Program Flow
Renaming Programs and Procedures
Calling Programs that Have Library Qualification
Calling C++ Programs and Procedures from ILE C
Specifying the Linkage Convention
Example: An ILE C Program that Uses C++ Objects
Accessing C++ Classes from ILE C
Mapping a C++ Class to a C Structure
Example: An ILE C Program that Uses C++ Objects
Chapter 24. Porting Programs from Another Platform to ILE
Limitations to Porting Code to ILE C or C++
File Inclusions
Platform-Specific Extensions
Members of a Union
Members of a Structure
Decimal Constants
Decimal Constants and Case Statements
Library QSYS.LIB under IFS
Teraspace Considerations
Modifying Calls of ILE C++ Objects
Differences in Header Files
Differences in Linkage Specification
Differences in Function Definitions
Using BCD Macros to Port Coded Decimal Objects to ILE C++
Examples
Mapping Class Template Instantiations to ILE C Syntax
Handling Extra Precision for Multiplication and Division
Determining the Number of Digits in an Object
Determining the Number of Digits in an Internal Packed Decimal Data Object
Formatting the Value of a Formatted C Input or Output Function
Porting Conditional Operators to ILE C or C++
Porting ILE C Packed Decimal Data Types to the _DecimalT Class Template
Differences in Using Packed Structures
Differences in Error Checking
Header Files that Work with Both C and C++
Using Dual Function Prototypes
Permitting ILE C Programs to Access C++ Linkage Functions
Including QSYSINC Header Files
Handling the Stricter C++ Type Checking
Resolving Integer Data Type Size Issues
Resolving Incompatible Pointer Types
Disabling Name Mangling to Avoid Undefined Name Errors
Resolving Type Mismatches with the C++ Function Prototype
Example of Function Prototype Mismatch
Handling the Function Prototype Mismatch
Declaring unsigned char Pointers as unsigned char Variables
Initializing Character Arrays
Specifying Access to String Literals
Avoiding Uncaught Exceptions by Scoping to a Single Activation Group
Chapter 25. Working with Multi-Language Applications
Inter-Language Procedure Calls
ILE Conventions for Calling Any Program (*PGM)
Mixing Recursive and Non-Recursive Calls
Passing Arguments from an ILE Program to a Non-EPM Program
Passing Arguments from an ILE Program to an EPM Program
Using a Linkage Specification in a C++ Dynamic Program Call
Calling Any ILE Program from ILE C/C++
Passing Parameters from ILE C++ to a Different High-Level Language
Type Casting to Override a Function without Overriding Linkage
Passing Arguments from a CL Program to an ILE C++ Program
How CL Constants Are Passed to an ILE C++ Program
How CL Variables Are Passed to an ILE C++ Program
CL Example: a Multi-Language ILE Application
Example: a User-Defined CL Program that Calls an ILE C++ Program
Example: CL Program that Passes Parameters to an ILE C++ Program
Accessing ILE C Procedures from Any ILE Program
Static Procedure Calls
Procedure Pointer Calls
Called Procedures and Operational Descriptors
Operational Descriptors and the #pragma descriptor Directive
OPM CL Example: Calling OPM, COBOL, and RPG Programs from an ILE C Program
ILE CL Example: Calling OPM, COBOL, and RPG Programs from an ILE C Program
ILE-OPM CL Example: Calling OPM, COBOL, and RPG Programs from an ILE C++ Program
Using a Linkage Specification to Call an ILE Procedure
Using a Linkage Specification in a C++ Dynamic Program Call
Valid String Literals
Linkage Specification
Chapter 26. Using Packed Decimal Data in a C Program
Converting from Packed Decimal Data Types
Converting from a Packed Decimal Type to a Packed Decimal Type
Converting from a Packed Decimal Type to an Integer Type
Converting from a Packed Decimal Type to a Floating Point Type
Overflow Behavior
Passing Packed Decimal Data to a Function
Passing a Pointer to a Packed Decimal Variable to a Function
Calling Another Program that Contains Packed Decimal Data
Using Library Functions with a Packed Decimal Data Type
Understanding Packed Decimal Data Type Errors
Packed Decimal Warnings and Error Conditions
Suppressing a Run-Time Overflow Exception
Chapter 27. Using Packed Decimal Data in a C++ Program
The OS/400 Binary Coded Decimal (BCD) Header File
Using the _DecimalT Class Template
Declaring _DecimalT Class Template Objects
Using the __D Macro to Simplify Code
_DecimalT Class Template Input and Output
Using Operators with the _DecimalT Class Template
C++ Packed Decimal Data Conversions
Converting Values from One _DecimalT Class Template to Another
Converting Values from a _DecimalT Class Template to an Integer Data Type
Converting Values from a _DecimalT Class Template to a Floating Point Data Type
Determining the Size of a _DecimalT Class Template
Determining the Number of Digits in a _DecimalT Class Template
Determining the Precision of a _DecimalT Class Template
How Overflows Are Handled
Using C++ Exception Handling with the _DecimalT Template
_DecimalT Class Template Run-Time Exceptions
Defining a C++ _DecimalT Class Template Exception Handler
Using Debug Macros for _DecimalT Class Templates
Passing a _DecimalT Class Template Object to a Function
Passing a Pointer to a _DecimalT Class Template Object
Calling Another Program Containing a _DecimalT Class Template
Validating _DecimalT Class Template Constants to a File
Chapter 28. Using Templates in C++ Programs
Managing Template Instantiations
Template Instantiation Management Options
How the ILE C++ Compiler Handles Template Instantiations
Generation of Static Member Definitions
Internal Linkage
External Linkage
Example of a Class Template Instantiation
Declarations and Definitions
Linkage
Using the Default Template Instantiation Management Option
Manually Structuring Code for Single Instantiations
Explicit Instantiations
Using the ILE Template Registry Option
How the ILE Template Registry Option Works
Specifying Values for the TMPLREG Parameter
Using the ILE TEMPINC Option
How the ILE TEMPINC Option Works
Structuring a Program for TEMPINC-Managed Instantiations
Chapter 29. Using Teraspace in ILE C and C++ Programs
Supported Teraspace Environments
C/C++ Pointer Support
C/C++ Pointer Conversions
Bindable APIs for Using Teraspace
The 16-Byte Run-Time Binding Libraries
The 8-Byte Run-Time Binding (RTBND) Library Extensions
Using RTBND to Optimize Performance of a C++ Program
Requirements
Error Conditions
Limitations
Characteristics of Each Teraspace Storage Model
Binary Compatibility Considerations When Porting Code in a Teraspace Environment
Specifying the Teraspace Environment
Determining the Size of a Specific Pointer
Maintaining Consistent Argument Declarations
Source Code Samples
Example: Effect of Forward Declarations on the Data Model
Example: Redefining the new or delete Operator
Example: How a Template Adopts a Data Model
Examples: Overloading Functions
Chapter 30. Casting with Run-Time Type Information
The RTTI Language Extension
Using C++ Language-Defined RTTI
The dynamic_cast Operator
The typeid Operator
Using RTTI in Constructors and Destructors
ILE C++ Extensions to RTTI
The extended_type_info Classes
Part 7. Using International Locales and Coded Character Sets
Chapter 31. Internationalizing a Program
Coded Character Set Identifiers
Source File Conversions to CCSID
Creating a Source Physical File with a Coded Character Set Identifier
Changing the Coded Character Set Identifier (CCSID)
Converting String Literals in a Source File
Using Unicode Support for Wide-Character Literals
Representation of Wide-Character Literals
Enabling Unicode Character Set Support
Effect of Unicode on #pragma convert() Operations
GB18030 Code Page Support
Targeting a CCSID
How the ILE C/C++ Compiler Converts a Source File to a Target CCSID
Literals, Comments, and Identifiers
Limitations
Chapter 32. International Locale Support
Elements of a Language Environment
Locales
ILE C/C++ Support for Locales
ILE C/C++ Support for *CLD and *LOCALE Object Types
C Locale Migration Table
POSIX Locale Definition and *LOCALE Support
LOCALETYPE Compiler Option
Creating Locales
Creating Modules Using LOCALETYPE(*LOCALE)
Categories Used in a Locale
Setting an Active Locale for an Application
Using Environment Variables to Set the Active Locale
SAA and POSIX *Locale Definitions
Locale-Sensitive Run-Time Functions
Part 8. Appendixes
Appendix A. The GENCSRC Utility and the #pragma mapinc Directive
Appendix B. Interlanguage Data-Type Compatibilities
Bibliography
[ Top of Page | Previous Page | Next Page | Table of Contents ]
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.