IBM i: ILE C/C++ Programmer's Guide

IBM i 7.2

Programming IBM Rational Development Studio for i ILE C/C++ Programmer's Guide

IBM

SC09-2712-07

Note Before using this information and the product it supports, read the information in "Notices" on page 441.

This edition applies to version 7, release 2, modification 0 of IBM Rational Development Studio for i (product number 5770-WDS) and to all subsequent releases and modifications until otherwise indicated in new editions. This version does not run on all reduced instruction set computer (RISC) models nor does it run on CISC models. This document may contain references to Licensed Internal Code. Licensed Internal Code is Machine Code and is licensed to you under the terms of the IBM License Agreement for Machine Code. ? Copyright International Business Machines Corporation 1993, 2013. US Government Users Restricted Rights ? Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

ILE C/C++ Programmer's Guide.............................................................................. 1

PDF file for ILE C/C++ Programmer's Guide............................................................................................... 3

About ILE C/C++ Programmer's Guide........................................................................................................5 Install Licensed Program Information................................................................................................... 5 Notes About Examples........................................................................................................................... 5 Control Language Commands and the Procedures in This Guide......................................................... 5

Introduction................................................................................................................................................. 7 Introduction to the ILE C/C++ Compiler................................................................................................ 7 Multi-Language Program Creation....................................................................................................7 Programming Languages Supported by the IBM i Operating System........................................7 ILE Program Creation.................................................................................................................. 7 Binding Directories...................................................................................................................... 8 Service Programs.........................................................................................................................8 Program and Resource Management............................................................................................... 8 Program Flow...............................................................................................................................8 Program and Procedure Calls................................................................................................ 9 Resource Allocation.....................................................................................................................9 Bindable APIs.............................................................................................................................. 9 Runtime Exceptions.....................................................................................................................9 Program Debugging...........................................................................................................................9

Creating and Compiling Programs.............................................................................................................11 Creating a Program...............................................................................................................................11 The Program Development Process............................................................................................... 11 Preparing a Program..................................................................................................................11 Compiling a Program................................................................................................................. 11 Binding Modules........................................................................................................................12 Running or Calling Objects........................................................................................................ 12 Debugging a Program................................................................................................................ 12 Entering Source Statements...........................................................................................................13 Example Of Creating a Source File............................................................................................13 Instructions............................................................................................................................... 13 Source Code Sample................................................................................................................. 13 Creating a Program in One Step..................................................................................................... 14 Creating a Program in Two Steps................................................................................................... 15 Identifying Program and User Entry Procedures......................................................................16 Understanding the Internal Structure of a Program Object.....................................................16 Using Static Procedure Calls..................................................................................................... 16 Working with Binding Directories..............................................................................................17 Creating a Binding Directory..................................................................................................... 17 Using the Binder to Create a Program ..................................................................................... 17 Preparing to Create a Program..................................................................................................17 Specifying Parameters for the CRTPGM Command................................................................. 18 How Import Requests Are Resolved.........................................................................................19 Using a Binder Listing................................................................................................................19 Updating a Module or a Program Object ..................................................................................20 Updating a Program...................................................................................................................21 Activating Groups...................................................................................................................... 21

iii

Messaging Support......................................................................................................................... 21 Service Programs..................................................................................................................................22

Differences Between Programs and Service Programs................................................................. 22 Public Interface...............................................................................................................................22 Considerations When Creating a Service Program........................................................................ 23 Using the Binder to Create a Service Program...............................................................................23

Specifying Parameters for the CRTSRVPGM Command...........................................................23 Updating or Changing a Service Program................................................................................. 24 Using Control Language (CL) Commands with Service Programs............................................24 Creating, Compiling, and Binding a Service Program.................................................................... 24 Creating the Source Files.......................................................................................................... 24

User Header File.................................................................................................................. 25 Source Code Files................................................................................................................ 25 Compiling and Binding the Service Program............................................................................ 26 Binding the Service Program to a Program...............................................................................27 Working with Exports from Service Programs..................................................................................... 28 Determining Exports from Service Programs.................................................................................28 Displaying Exported Defined Symbols with the Display Module Command........................... 28 Creating a Binder Language Source File.........................................................................................29 Creating Binder Language Using SEU....................................................................................... 29 Creating Binder Language Using the RTVBNDSRC Command................................................. 30 Updating a Service Program Export List.........................................................................................30 Using the Demangling Functions....................................................................................................31 Handling Unresolved Import Requests During Program Creation................................................ 31 Creating an Export Service Program Using Binder Language........................................................ 32 Creating a Program with Circular References................................................................................ 32 Creating the Source Files.......................................................................................................... 33 Compiling the Source Files into Modules................................................................................. 34 Generating the Binder Language to Create the Service Program............................................ 34 Binding the Modules into the Program..................................................................................... 35 Handling Unresolved Import Requests Using the *UNRSLVREF Parameter........................... 35 Handling Unresolved Import Requests by Changing Program Creation Order....................... 36 Binding a Program to a Non-Existent Service Program................................................................. 37 Instructions............................................................................................................................... 37 Code Samples............................................................................................................................38 Running the Program.................................................................................................................38 Updating a Service Program Export List.........................................................................................38 Program Description..................................................................................................................38 Creating the Source Files.......................................................................................................... 39 Compiling and Binding Programs and Service Programs......................................................... 40 Running the Program.................................................................................................................41 Running a Program............................................................................................................................... 41 The ILE C/C++ Runtime Model....................................................................................................... 42 Activations and Activation Groups................................................................................................. 42 Runtime Library Functions and Activation Groups........................................................................ 43 Calling Programs............................................................................................................................. 44 Using the Call (CALL) Command............................................................................................... 44 Passing Parameters to the Called Program.........................................................................44 Call (CALL) Command Parameter Conversions...................................................................46 Using the Process Commands (QCAPCMD) API................................................................. 46 Using the Transfer Control (TFRCTL) Command...................................................................... 46 Example: Creating and Running a Program that Uses the TFRCTL Command.................. 47 Code Samples...................................................................................................................... 47 Creating a CL Command to Run a Program.............................................................................. 48 Program Description............................................................................................................ 48 Instructions..........................................................................................................................48 Code Samples...................................................................................................................... 49 Normal and Abnormal End-of-Program......................................................................................... 50

iv

Managing Activation Groups...........................................................................................................50 Specifying an Activation Group................................................................................................. 50 Running a Program in a Named Activation Group...............................................................50 Running a Program in Activation Group *NEW....................................................................51 Non-Standard Behavior with Named Activation Groups.................................................... 52 Running a Program in Activation Group (*CALLER)............................................................ 52 Presence of a Program on the Call Stack..................................................................................53 Deleting an Activation Group.................................................................................................... 53 Reclaiming System Resources.................................................................................................. 53 Using the Reclaim Resources (RCLRSC) Command............................................................54

Managing Runtime Storage.............................................................................................................54 Managing the Default Heap.......................................................................................................54 Using Bindable APIs to Manage the Default Heap..............................................................55 Dynamically Allocating Storage at Runtime........................................................................55 Overriding Replacement Functions..................................................................................... 55 Overloading the new or delete Operator.............................................................................56

Improving Runtime Performance........................................................................................................ 56 Choosing Data Types to Improve Performance............................................................................. 57 Avoiding Use of the Volatile Qualifier........................................................................................57 Replacing Bit Fields with Other Data Types............................................................................. 57 Minimizing the Use of Static and Global Variables................................................................... 57 Using the Register Storage Class.............................................................................................. 57 Creating Classes to Improve Performance.................................................................................... 58 Enabling Performance Measurement.............................................................................................58 Using a Compiler Option to Enable Performance Measurement............................................. 58 Minimizing Exception Handling...................................................................................................... 58 Turning on Return Codes during Record I/O.............................................................................58 Turning Off C2M Messages during Record Input and Output.................................................. 59 Using a Direct Monitor Handler.................................................................................................59 Minimizing Percolation of Exceptions....................................................................................... 59 Example of Exception Percolation for a Sample ILE C Source Code..................................59 Reducing the Number of Function Calls and Arguments...............................................................61 Inlining Function Calls...............................................................................................................61 Using Static Class Member Functions or Global Variables.......................................................61 Passing Arguments in Registers................................................................................................61 Using Prototypes to Minimize Function Call Processing.......................................................... 62 Choosing Input and Output Functions to Improve Performance.................................................. 62 Using Record Input and Output Functions............................................................................... 62 ISO C Record I/O........................................................................................................................ 62 ILE C Record I/O.........................................................................................................................63 Using Input and Output Feedback Information....................................................................... 63 Blocking Records.......................................................................................................................63 Manipulating the System Buffer............................................................................................... 63 Opening Files Once for Both Input and Output........................................................................ 64 Minimizing the Use of Shared Files........................................................................................... 64 Minimizing the Number of File Opens and Closes....................................................................65 Defining Tape Files to Improve Performance........................................................................... 65 Improving Performance when Using Stream Input and Output Functions............................. 65 Using C++ Input and Output Stream Classes...........................................................................65 Using Physical Files Instead of Source Physical Files..............................................................65 Specifying Library Names......................................................................................................... 66 Using Pointers to Improve Performance........................................................................................ 66 Avoiding Use of Open Pointers..................................................................................................66 Avoiding Pointer Comparisons.................................................................................................. 66 Reducing Indirect Access through Pointers............................................................................. 68 Using Shallow Copy instead of Deep Copy.....................................................................................69 Minimizing Space Requirements.................................................................................................... 69 Choosing Appropriate Data Types............................................................................................ 69

v

Minimizing Dynamic Memory Allocation Calls..........................................................................69 Arranging Variables to Reduce Padding................................................................................... 70 Removing Observability............................................................................................................ 71 Compressing Objects................................................................................................................ 72 Optimizing Use of Activation Groups..............................................................................................72 Calling Functions in Other Activation Groups...........................................................................72 Reducing Program Startup Time...............................................................................................72 Minimizing Use of Virtual Functions............................................................................................... 72 Choosing Compiler Options to Optimize for Speed or Size............................................................73 Setting Runtime Limits................................................................................................................... 74 Example: Creating an ILE C Application.............................................................................................. 74 Process Flow................................................................................................................................... 75 ILE Activation Group....................................................................................................................... 76 Resource Requirements................................................................................................................. 76 Task Summary.................................................................................................................................76 Instructions to Create the Sample Application..............................................................................78 Source Code Samples..................................................................................................................... 81 Source Code for an Audit Log File............................................................................................. 81 Source Code Pass Terminal Session Input to an ILE Program.................................................81 Source Code to Define a CL Command to Collect Session Data.............................................. 81 Source Code for a User Entry Procedure (UEP)........................................................................ 82 Source Code to Calculate Tax and Format Cost for Output......................................................83 Source Code to Write an Audit Trail.......................................................................................... 84 Source Code to Export Tax Rate Data....................................................................................... 86 Binder Language to Export Tax Rate Data................................................................................ 86 Binder Language to Export the write-audit-trail Procedure.....................................................86

Debugging Programs..................................................................................................................................89 The ILE Source Debugger.....................................................................................................................89 Debug Data Options........................................................................................................................ 89 Debug Language Syntax................................................................................................................. 89 Limitations of the Debug Language Syntax.................................................................................... 90 Debug Commands...........................................................................................................................90 Examples of Using Debug Expressions in ILE C Programs............................................................ 92 Examples of Program Definitions and Corresponding Debug Expressions............................. 92 Evaluating Pointers to Find and Correct Errors...................................................................93 Evaluating Simple Expression to Find and Correct Errors.................................................. 94 Evaluating Bit Fields to Find and Correct Errors................................................................. 95 Evaluating Structures and Unions to Find and Correct Errors............................................ 95 Evaluating Enumerations to Find and Correct Errors......................................................... 96 Examples of Displaying System and Space Pointers in the ILE Source Debugger.................. 97 Preparing a Program for Debugging.....................................................................................................98 Setting Up a Test Library.................................................................................................................99 Creating a Listing View for Debugging............................................................................................99 Working with Source Debug Sessions..................................................................................................99 Starting a Source Debug Session................................................................................................. 100 Adding and Removing Programs from a Debug Session............................................................. 102 Setting or Changing Debug Options During a Session................................................................. 103 Example: Adding an OPM Program to an ILE Debug Session................................................ 103 Example: Setting Debug Options during a Debug Session.....................................................103 Viewing the Program Source........................................................................................................ 104 Displaying Other Modules in Your Program............................................................................104 Example: Changing the Module Displayed in a Session................................................... 104 Displaying a Different View Of a Module................................................................................ 105 Using Breakpoints to Aid Debugging................................................................................................. 105 Types Of Breakpoints................................................................................................................... 106 Job and Thread Breakpoints...................................................................................................106 Conditional and Unconditional Breakpoints...........................................................................106

vi

Setting Breakpoints...................................................................................................................... 106 Setting Unconditional Breakpoints from the Display Module Source Display...................... 106 Setting Unconditional Breakpoints from the Command Line................................................ 107 Setting Conditional Breakpoints for a Macro..........................................................................107 Setting Conditional Breakpoints for a Statement...................................................................108

Setting Conditional Thread Breakpoints...................................................................................... 108 Setting a Conditional Thread Breakpoint from the Work with Module Breakpoints Display 108 Setting a Conditional Thread Breakpoint from the Command Line....................................... 109

Testing Breakpoints...................................................................................................................... 109 Removing All Breakpoints............................................................................................................ 109 Using Watches to Aid Debugging....................................................................................................... 109 Characteristics and Limitations Of Watches................................................................................ 109 Setting and Removing Watch Conditions..................................................................................... 110

Setting watch conditions.........................................................................................................110 Using the WATCH Debug Command....................................................................................... 111 Removing Watch Conditions................................................................................................... 112 Automatic Removal Of Watch Conditions.............................................................................. 112 Example Of Setting a Watch Condition........................................................................................ 112 Displaying Active Watches........................................................................................................... 113 Stepping Through Programs.............................................................................................................. 114 Stepping Over Programs...............................................................................................................114 Using F10 to Step Over Programs...........................................................................................114 Using the STEP OVER Debug Command.................................................................................114 Stepping into Programs................................................................................................................ 114 Using F22 to Step into Programs............................................................................................ 114 Using the STEP INTO Debug Command................................................................................. 114 Stepping into Called Programs............................................................................................... 115 Example of Stepping into a Program Using F22.....................................................................115 Stepping into an OPM Program...............................................................................................116 Stepping Over Procedures............................................................................................................116 Stepping into Procedures............................................................................................................. 117 Debugging Variables.......................................................................................................................... 118 Displaying the Value Of a Variable............................................................................................... 118 Using F11 to Display Variables............................................................................................... 119 Changing the Value of a Variable..................................................................................................120 Changing the Value of a Scalar Variable.......................................................................................120 Equating a Name with a Variable, Expression, or Debug Command........................................... 121 Displaying a Structure............................................................................................................. 122 Displaying Variables As Hexadecimal Values.........................................................................122 Displaying Null-Ended Character Arrays................................................................................ 123 Displaying Character Arrays....................................................................................................124 Sample EVAL Commands for Pointers, Variables, and Bit Fields.......................................... 125 EVAL Commands for System and Space Pointers.................................................................. 127

Displaying a Class Template and a Function Template.................................................... 128 Source for Sample EVAL Commands............................................................................................129 Source for Sample EVAL Commands for Displaying System and Space Pointers.......................130 Source for Sample EVAL Commands for Displaying C++ Constructs..........................................131 Changing Module Optimization and Observability............................................................................ 133 Changing Optimization Levels...................................................................................................... 134 Removing Module Observability...................................................................................................135

Performing I/O Operations...................................................................................................................... 137 Using ILE C/C++ Stream and Record I/O Functions with IBM i files................................................ 137 ILE C Record I/O Functions.......................................................................................................... 137 Stream Buffering..................................................................................................................... 137 Dynamic Stream File Creation................................................................................................ 138 Open Modes for Dynamically Created Stream Files...............................................................138 Standard I/O Text Stream Files ()............................................................................138

vii

Overriding Standard Output to the Terminal.................................................................... 139 Allowing a Program to Re-Read an Input File with QINLINE Specified........................... 139 IBM i Files..................................................................................................................................... 139 IBM i File Types....................................................................................................................... 139 Stream Files and ILE C I/O Operations...................................................................................140 Avoiding Positioning Problems in the File.........................................................................140 Using the fopen() Function................................................................................................ 140 Using the open() member Function.................................................................................. 140 IBM i File Naming Conventions...............................................................................................140 File Control Structure of Text Streams and Binary Streams........................................................142 I/O Processes for Text Stream Files.............................................................................................143 Opening Text Stream Files...................................................................................................... 143 Writing Text Stream Files........................................................................................................ 144 Reading Text Stream Files...................................................................................................... 145 Updating Text Stream Files.....................................................................................................146 I/O Process for Binary Stream Files............................................................................................. 146 Opening Binary Stream Files (character at a time)................................................................ 146 Writing Binary Stream Files (character at a time).................................................................. 148 Reading Binary Stream Files (character at a time).................................................................148 Updating Binary Stream Files (character at a time)............................................................... 149 Opening Binary Stream Files (record at a time)..................................................................... 151 Writing Binary Stream Files (record at a time)....................................................................... 152 Reading Binary Stream Files (record at a time)......................................................................153 Open Feedback Area.................................................................................................................... 154 I/O Feedback Area........................................................................................................................154 Using Session Manager.................................................................................................................155 Obtaining the Session Handle.................................................................................................155 Using Session Manager APIs.................................................................................................. 155 Example: Using an ILE Bindable API to Display a DSM Session............................................155 Instructions........................................................................................................................155 Code Samples.................................................................................................................... 156 Using ILE C/C++ Stream Functions with the IBM i Integrated File System..................................... 157 The Integrated File System (IFS)................................................................................................. 158 root(/) File System...................................................................................................................159 User Access....................................................................................................................... 159 Path Names........................................................................................................................159 Open Systems (QOpenSys) File System................................................................................. 159 User Access....................................................................................................................... 160 Path Names........................................................................................................................160 Library (QSYS.LIB) File System...............................................................................................160 File Handling Restrictions................................................................................................. 160 Path Names........................................................................................................................160 Document Library Services (QDLS) File System.....................................................................161 User Access....................................................................................................................... 161 Path Names........................................................................................................................161 LAN Server/400 (QLANSrv) File System.................................................................................161 User Access....................................................................................................................... 161 Path Names........................................................................................................................161 Optical Support (QOPT) File System...................................................................................... 162 Path Names........................................................................................................................162 File Server (QFileSvr.400) File System................................................................................... 162 Path Names........................................................................................................................162 Enabling Integrated File System Stream I/O............................................................................... 163 Using Stream I/O with Large Files.......................................................................................... 163 Stream Files.................................................................................................................................. 164 Stream Files Versus Database Files.............................................................................................164 Text Streams................................................................................................................................. 165 Binary Streams............................................................................................................................. 166

viii

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download