WIXLIB

IBMIBM iProgrammingAPI overview and concepts7.1

IBMIBM iProgrammingAPI overview and concepts7.1

NoteBefore using this information and the product it supports, read the information in “Notices,” onpage 573.This edition applies to IBM i 7.1 (product number 5770-SS1) and to all subsequent releases and modifications untilotherwise indicated in new editions. This version does not run on all reduced instruction set computer (RISC)models nor does it run on CISC models. Copyright IBM Corporation 1998, 2010.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

ContentsApplication programming interfaces . . 1 APIs overview . . . . . . . . . . . . . . 1What's new for IBM i 7.1 . . . . . . . . . . 3PDF file for APIs . . . . . . . . . . . . . 4API concepts . . . . . . . . . . . . . . 4API terminology . . . . . . . . . . . . 5Generic library names . . . . . . . . . . 5API naming conventions . . . . . . . . . 6Language selection considerations . . . . . . 8Types of APIs. . . . . . . . . . . . . 10APIs for the program-based environment . . 10APIs for the service-program-basedenvironment . . . . . . . . . . . . 10APIs for the ILE Common ExecutionEnvironment . . . . . . . . . . . . 12Differences between program-based APIs andservice-program-based APIs . . . . . . . 12Example in ILE C: Logging software errors(program API without pointers) . . . . 13Example in OPM COBOL: Loggingsoftware errors (program API withoutpointers) . . . . . . . . . . . . 18Example in OPM RPG: Logging softwareerrors (program API without pointers) . . 21Example in ILE RPG: Logging softwareerror (program API without pointers). . . 24Example in ILE C: Reporting softwareerrors (bindable API with pointers) . . . 26Example in ILE COBOL: Reportingsoftware errors (bindable API withpointers) . . . . . . . . . . . . 30Example in ILE RPG: Reporting softwareerrors (bindable API with pointers) . . . 33APIs for the UNIX-type environment . . . . 36Examples: UNIX-type APIs . . . . . . 36API information format . . . . . . . . . 47API description . . . . . . . . . . . 47API format . . . . . . . . . . . . 50API field descriptions . . . . . . . . . 51API error messages . . . . . . . . . . 51Extracting a field from the format . . . . . 51Processing lists that contain data structures . . 52API parameters . . . . . . . . . . . . 52Passing parameters . . . . . . . . . . 53Input and output parameters . . . . . . 53Offset values and lengths . . . . . . . . 54Offset versus displacement considerations forstructures . . . . . . . . . . . . . 54Error code parameter . . . . . . . . . 54Error code parameter format . . . . . 55Examples: Receiving error conditions . . . 57Using the job log to diagnose API errors. . 58Include files and the QSYSINC library . . . . 59Internal object types . . . . . . . . . . 62Data types and APIs . . . . . . . . . . 66Internal identifiers . . . . . . . . . . . 67 Copyright IBM Corp. 1998, 2010User spaces and receiver variables . . . . . . 67User spaces . . . . . . . . . . . . 67General data structure . . . . . . . . 68Common data structure formats . . . . 69Example: User space format . . . . . . 72List sections . . . . . . . . . . . 73Receiver variables . . . . . . . . . . 73Bytes available and bytes returned fields74Keyed interface . . . . . . . . . . 75User space alternative . . . . . . . . 75Continuation handle . . . . . . . . . . 76List APIs overview . . . . . . . . . . . 76General data structure for list APIs . . . . 76User spaces for list APIs . . . . . . . . 79Logic flow of processing a list of entries . . 80Manipulating a user space with pointers . 81Manipulating a user space without pointers 82Examples: Changing a user space . . . . 82Additional information about list APIs anduser spaces . . . . . . . . . . . 86Example in CL: Listing database filemembers . . . . . . . . . . . . 86Example in OPM RPG: List APIs . . . . . 87Example in ILE CL: List APIs . . . . . . 94Example in ILE C: List APIs . . . . . . . 98Example in ILE RPG: List APIs . . . . . 104Example in ILE COBOL: List APIs . . . . 109Domains . . . . . . . . . . . . . . 114Exit programs . . . . . . . . . . . . 114User index considerations . . . . . . . . 115Performance considerations. . . . . . . . 116APIs and system objects . . . . . . . . . 116Open list information format . . . . . . . 116Path name format . . . . . . . . . . . 118Using APIs . . . . . . . . . . . . . . 120Examples: Program-based APIs . . . . . . 120Example in OPM RPG: Retrieving the HOLDparameter (exception message) . . . . . 121Example in ILE COBOL: Retrieving theHOLD parameter (exception message) . . . 126Example in ILE C: Retrieving the HOLDparameter (exception message) . . . . . 127Example in ILE RPG: Retrieving the HOLDparameter (exception message) . . . . . 129Example in OPM RPG: Retrieving the HOLDparameter (error code structure) . . . . . 133Example in ILE COBOL: Retrieving theHOLD parameter (error code structure) . . 139Example in ILE C: Retrieving the HOLDparameter (error code structure) . . . . . 141Example in ILE RPG: Retrieving the HOLDparameter (error code structure) . . . . . 143Example in OPM RPG: Printing the HOLDvalue . . . . . . . . . . . . . . 145Example in ILE COBOL: Printing the HOLDvalue . . . . . . . . . . . . . . 147iii

Example in ILE C: Printing the HOLD valueExample in ILE RPG: Printing the HOLDvalue . . . . . . . . . . . . . .Example in OPM RPG: Accessing a fieldvalue (initial library list) . . . . . . . .Example in ILE COBOL: Accessing a fieldvalue (initial library list) . . . . . . . .Example in ILE C: Accessing a field value(initial library list) . . . . . . . . . .Example in ILE RPG: Accessing a field value(initial library list) . . . . . . . . . .Example in OPM RPG: Using keys with theList Spooled Files (QUSLSPL) API . . . .Example in ILE COBOL: Using keys with theList Spooled Files (QUSLSPL) API . . . .Example in ILE C: Using keys with the ListSpooled Files (QUSLSPL) API . . . . . .Example in ILE RPG: Using keys with theList Spooled Files (QUSLSPL) API . . . .Examples: Service-program-based APIs . . . .Example in ILE C: Registering exit pointsand adding exit programs . . . . . . .Example in OPM COBOL: Registering exitpoints and adding exit programs . . . . .Example in ILE COBOL: Registering exitpoints and adding exit programs . . . . .Example in OPM RPG: Registering exitpoints and adding exit programs . . . . .Example in ILE RPG: Registering exit pointsand adding exit programs . . . . . . .Example in ILE C: Removing exit programsand deregistering exit points . . . . . .Example in OPM COBOL: Removing exitprograms and deregistering exit points . . .Example in ILE COBOL: Removing exitprograms and deregistering exit points . . .Example in OPM RPG: Removing exitprograms and deregistering exit points . . .Example in ILE RPG: Removing exitprograms and deregistering exit points . . .Example in ILE C: Retrieving exit point andexit program information . . . . . . .Example in OPM COBOL: Retrieving exitpoint and exit program information . . . .Example in ILE COBOL: Retrieving exit pointand exit program information . . . . . .Example in OPM RPG: Retrieving exit pointand exit program information . . . . . .Example in ILE RPG: Retrieving exit pointand exit program information . . . . . .Performing tasks using APIs . . . . . . .Examples: Packaging your own softwareproducts . . . . . . . . . . . . .Creating the example product . . . . .Example in CL: Creating objects forpackaging a product . . . . . . . .Example in OPM RPG: Packaging aproduct . . . . . . . . . . . .Example in ILE C: Packaging a productExample in ILE COBOL: Packaging aproduct . . . . . . . . . . . .ivIBM i: Programming API overview and 0247253Example in ILE RPG: Packaging a productExamples: Retrieving a file description to auser space . . . . . . . . . . . .Example in ILE C: Retrieving a filedescription to a user space . . . . . .Example in ILE COBOL: Retrieving a filedescription to a user space . . . . . .Example in ILE RPG: Retrieving a filedescription to a user space . . . . . .Examples: Using data queues or user queuesConsiderations for using data queues anduser queues . . . . . . . . . . .Example in ILE C: Using data queues . .Example in ILE COBOL: Using dataqueues . . . . . . . . . . . .Example in OPM RPG: Using data queuesExample in ILE RPG: Using data queuesExample in ILE C: Using user queues . .Examples: APIs and exit programs . . . . . .Example: Changing an active job . . . . . .Example: Changing a job schedule entry . . .Example: Creating a batch machine . . . . .Example: Creating and manipulating a userindex . . . . . . . . . . . . . . .Example: Creating your own telephonedirectory . . . . . . . . . . . . . .Example: Defining queries . . . . . . . .Example: Deleting old spooled files . . . . .Example: Diagnostic reporting. . . . . . .Example: Generating and sending an alert. . .Example: Listing directories . . . . . . .Example: Listing subdirectories . . . . . .Example: Saving to multiple devices. . . . .Example: Saving and restoring system-levelenvironment variables . . . . . . . . .Examples: Scanning string patterns . . . . .Example: Using a COBOL/400 program to callAPIs . . . . . . . . . . . . . . .Examples: Using the Control Device(QTACTLDV) API . . . . . . . . . . .Examples: Processing data queue entries . . .Example: Using environment variables . . . .Examples: Using ILE Common ExecutionEnvironment APIs . . . . . . . . . . .Example: Using generic terminal APIs . . . .Example: Using profile handles . . . . . .Example: Using registration facility APIs . . .Example: Using semaphore set and sharedmemory functions . . . . . . . . . . .Example: Using SNA/Management ServicesTransport APIs . . . . . . . . . . . .Example: Using source debugger APIs . . . .Example: Using process-related APIs . . . .Example: Using the user-definedcommunications programs for file transfer. . .Example: Working with stream files . . . . .Example: Creating a program temporary fix exitprogram . . . . . . . . . . . . . .Example: Creating an exit program forOperational Assistant backup . . . . . . .Machine interface programming . . . . . . 402404408414426450459491494496497

Machine interface instructions . . . . . . .Example: Writing an MI program. . . . . .Compiling an MI program . . . . . . . .Creating an MI version of the CLCRTPGprogram . . . . . . . . . . . . . .Enhanced version of the MICRTPG programWriting the MICRTPG2 program (by sectionsof code) . . . . . . . . . . . . .Beginning the instruction stream . . . . .Using static storage to your advantage . . .MI code example: MICRTPG2 completeprogram . . . . . . . . . . . . .Updated CL06 program . . . . . . . .Creating the MICRTPG2 program . . . . .Example: Common MI programming techniquesProgram storage . . . . . . . . . . .497498500507513514516517518520521525529Common API programming errors . . . . .Using the error code parameter . . . . .Defining data structures . . . . . . . .Defining receiver variables . . . . . . .Defining list-entry format lengths . . . .Using null pointers with program-based APIsDefining byte alignment . . . . . . . .Using offsets in a user space . . . . . .Coding for new functions . . . . . . .529530532535539543. 546. 550. 558Appendix. Notices . . . . . . . . . 573Programming interface information .Trademarks . . . . . . . . .Terms and conditions. . . . . . 574. 575. 575Contentsv

viIBM i: Programming API overview and concepts