IBM Version 4

I\ Varying length

I 17 1ðð QUSBNG

I\

I\ List Objects API Include

I\

I/COPY QSYSINC/QRPGSRC,QUSLOBJ

I\

I\ Qualified User Space Data Structure

I\

IUSERSP DS

I I 'APIUG1 ' 1 1ð USRSPC

I I 'QGPL ' 11 2ð SPCLIB

i\ Qualified Object Name Data Structure

IOBJECT DS

I I '\ALL ' 1 1ð OBJNAM

I I 'QGPL ' 11 2ð OBJLIB

I\

I\ Miscellaneous Data Structure

I\

I DS

I\ Set up parameters for the Create User Space API

I I 'TESTUSRSPC' 1 1ð EXTATR

I I X'ðð' 11 11 INTVAL

I 12 12 RSVD1

I I 256 B 13 16ðINTSIZ

I I '\USE ' 17 26 PUBAUT

I I 'TEXT DESCRIPTION - 27 76 TEXT

I 'FOR USER SPACE -

I 'CALLED APIUG1 '

I I '\YES ' 77 87 REPLAC

I\ Set up parameters for the List Objects API

I I 'OBJLð1ðð' 88 95 FORMAT

I I '\ALL ' 96 1ð5 OBJTYP

I 1ð6 1ð8 RSVD2

I\ Set up parameters for the Retrieve User Space API

I I 1 B 1ð9 112ðSTRPOS

I I 192 B 113 116ðLENDTA

I B 117 12ððCOUNT

C\

C\ Create a user space called APIUG1 in library QGPL.

C\

C Z-ADD1ðð QUSBNB

C CALL 'QUSCRTUS'

C PARM USERSP

C PARM EXTATR

C PARM INTSIZ

C PARM INTVAL

C PARM PUBAUT

C PARM TEXT

C PARM REPLAC

C PARM QUSBN

C\ See if any errors were returned in the error code parameter.

C EXSR ERRCOD

C\

C\ Get a list of all objects in the QGPL library.

C\

C CALL 'QUSLOBJ'

C PARM USERSP

Chapter 9. Common API Programming Errors 9-29

Contents

Main System API Programming Page Page First Edition (August 1997) Contents iv vi Page Page Figures Page Notices Programming Interface Information xii Trademarks About System API Programming (SC41-5800) AS/400 Information Directory AS/400 Information Directory Publications Reference System API Ref- erence Page Chapter 1. Application Programming InterfaceOverview API Compatibility 1-2 Using APIsBenefits System APIs or CL CommandsWhen to Use Each Actions and System Functions of APIs 1-4 Ultimedia System Facilities Programming REXX/400 Reference REXX/400 Programmers Guide Chapter 2. Getting Started with APIs functions System API Reference Locating the API to Use 2-2 ations Selecting the High-Level Language To Use Figure 2-2. Language Selection Considerations Data Types 2-4 API Environments APIs for the Original Program Model Environment APIs for the Integrated Language Environment APIs for the ILE Common Execution Environment (CEE) ILE Concepts 2-6 APIs for the UNIX Environment System API Reference API Parameters Parameter Passing Parameter Classification 2-8 Error Code Parameter Receiving Error Conditions as ExceptionsExample Receiving the Error Code without the Exception DataExample Receiving the Error Code with the Exception DataExample 2-10 Using the Job Log to Diagnose API Errors Receiving Error Messages from the Job LogExample To receive error messages from the job log using a CL program, specify the fol- lowing: 2-12 message key handle internal spooled file identifier User Spaces User Spaces User Space FormatExample 2-14 Logic Flow of Processing a List of Entries The User Space API chapter of the When you process a list containing multiple entries, the logic flow looks as follows: , SC41-5801 The User Space Format for List APIs topic in Chapter 2 of the , SC41-5801 Manipulating a User Space with Pointers 2-16 Synchronizing between Two or More Jobs Using Offset Values with Pointers Updating Usage Data Manipulating a User Space without Pointers Position Values Lengths Using Offset Values with the Change and Retrieve User Space APIs Changing a User SpaceExample Page Page Manipulating a User Space without Pointers Changing a User Space with an ILE RPG ProgramExample 2-20 Changing a User Space with an OPM RPG ProgramExample Additional Information about List APIs and a User Space 2-22 Listing Database File Members with a CL ProgramExample Field Receiver Variables Bytes Available and Bytes Returned Fields Keyed Interface 2-24 User Space Alternative Related Information Continuation Handle Using a Continuation Handle 2-26 user Domain Concepts System Guide to Enabling C2 Security Security Reference Exit Programs Exit Points APIs and the QSYSINC Library User Index Considerations APIs and the QUSRTOOL Library 2-30 User Index Considerations APIs and Internal System Objects Performance Considerations Page Chapter 3. Common Information across APIsBasic (OPM) Example Original Program Model (OPM) APIScenario Finding the API Name to Use Description of an API 3-2 RPG Call StatementParameter Example: x Parameters Required Parameter Group Length of Receiver Variable: Dec Receiver Variable: Format Name: 3-4 Error Code: Qualified Job Description Name: Format Field Descriptions Error Messages Extracting a Field from the Format Retrieving the Hold Parameter (Exception Message)OPM RPG Example 3-6 Handling Error ConditionsOPM RPG Example 3-8 3-10 Retrieving the Hold Parameter (Error Code Structure)OPM RPG Example Format of an Error Code Structure 3-12 Handling Error ConditionsOPM RPG Example 3-14 3-16 Accessing the HOLD AttributeOPM RPG Example 3-18 Accessing a Field Value (Initial Library List)OPM RPG Example Offset 3-20 3-22 Using Keys with List Spooled Files APIExample 3-24 3-26 3-28 Processing Lists That Contain Data Structures Retrieve Job Description Information APIExample Authorities and Locks 3-30 Required Parameter Group JOBD0100 Format Field Descriptions 3-32 *SYSVAL *MSG *DSCMSG 0 3-34 4 3 QCMDI 3-36 *BASE *NONE Page Page Chapter 4. Common Information across APIsAdvanced (ILE) Example Integrated Language Environment (ILE) APIsIntroduction Registration Facility Using ILE APIsConcepts 4-2 Generic Header Files Variable-Length StructureExample Keyed InterfaceExample Exit Program Attributes Parameter Exit Program Attribute Keys 4-4 Error Handling Error DeterminationExample: Error Handling through the Error Code Parameter Message DataExample: Error Handling Signaled by API Receiver VariablesExamples Repeating Entry Type with Fixed-Length FieldsExample Repeating Entry Type with Variable-Length FieldsExample 4-8 Offsets TypeExample: Registration Facility Using ILE APIsExamples Register Exit Point and Add Exit ProgramILE C Example 4-10 4-12 Retrieve Exit Point and Exit Program InformationILE C Example 4-14 4-16 4-18 Remove Exit Program and Deregister Exit PointILE C Example 4-20 Page Page Chapter 5. List APIs Characteristics of a List API General Data Structure User Area Offset to Header Section 5-2 Offset to List Data Section Other Fields of Generic Header P I C Processing a List 5-4 List Object APIOPM RPG Example 5-6 5-8 5-10 List Objects That Adopt Owner Authority APIExample 5-12 Authorities and Locks Required Parameter Group User Space Variables 5-14 Input Parameter Section Header Section OBJP0100 Format Field Descriptions 5-16 Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences errnos Omitted Parameters: Optional Parameters: Contrasting OPM and ILE APIs API Name Pointers 6-2 Logging Software Error (OPM API without Pointers)ILE C Example 6-4 6-6 Reporting Software Error (ILE API with Pointers)ILE C Example 6-8 6-10 Page Page Chapter 7. Machine Interface Programming Machine Interface InstructionsIntroduction Writing an MI ProgramExample 7-2 Setting the Entry Point Setting the Declare Statements Starting the Instruction Stream Machine Interface Func- tional Reference System API MI01 ProgramComplete Code Example Compiling a Program Machine Interface Func- tional Reference Using CLCRTPG to Create an MI Program Creating the MI Example Program 7-6 Testing MI01 Debugging the MI Program Setting Breakpoints in the MI Program 7-8 Handling Exceptions in the MI Program Machine Interface Functional 7-10 Creating an MI Version of CLCRTPG 7-12 Source for the CL03 Program Source for the CL04 Program Source for the CL05 Program 7-14 Source for the MICRTPG Program Understanding the MICRTPG Program (by Sections of Code) 7-16 AS/400 Licensed Internal Code Diagnostic Aids Volume 2 AS/400 Licensed Internal Code Diagnostic Aids Volume 1 Declaring the Structure Declaring Pointers Defining an External Call Calling the CL05 Program 7-18 Enhanced Version of the MICRTPG Program Understanding the MICRTPG2 Program (by Sections of Code) 7-20 Beginning the Instruction Stream 7-22 Using Static Storage to Your Advantage MICRTPG2 Complete ProgramMI Code Example 7-24 Updated CL06 Program 7-26 Creating the MICRTPG2 Program Handling Exceptions in the MICRTPG2 Program MICRTPG2 Complete Program (Enhanced)MI Code Example 7-28 7-30 MI Common Programming TechniquesExamples 7-32 7-34 AS/400 Program Storage 7-36 Program Invocation and Automatic Storage: Program Activation and Static Storage: Chapter 8. Use of OS/400 APIs Backup and Recovery APIs Client Support APIs Simple Network Management Protocol (SNMP) Support Communications APIs 8-2 OptiConnect APIs Configuration APIs Debugger APIs Dynamic Screen Manager APIs 8-4 Edit Function APIs File APIs Hardware Resource APIs 8-6 Hierarchical File System (HFS) APIs High-Level Language APIs Application Development Manager APIs Integrated Language Environment (ILE) CEE APIs Naming Conventions of the ILE CEE APIs Journal and Commit APIs 8-8 Journal APIs Commitment Control APIs Message Handling APIs National Language Support APIs network National Language Support APIs National Language Data Conversion APIs Character Data Representation Architecture (CDRA) APIs SNA/Management Services Transport (SNA/MS Transport) APIs Alert APIs Node List API Registered Filter APIs Object APIs Data Queue APIs 8-12 Comparisons with Using Database Files as Queues: Similarities to Message Queues: User Queue APIs User Index APIs User Space APIs 8-14 Object APIs Office APIs AnyMail/400 Mail Server Framework APIs SNADS File Server APIs 8-16 Office Exit Programs Operational Assistant APIs Performance Collector APIs Print APIs Print APIs Problem Management APIs Filtering Working with a Problem Problem Log Entry APIs Program and CL Command APIs Registration Facility APIs Security APIs 8-20 System Manager Use Network Security APIs Software Product APIs UNIX-Type APIs Environment Variable APIs are 8-22 Integrated File System APIs Integrated File System Introduction Interprocess Communication APIs msqid Signal APIs handle using signal default action 8-24 Simple Network Management Protocol (SNMP) APIs SNMP Manager APIs: SNMP Subagent APIs: Sockets APIs 8-26 Sockets Programming Process-Related APIs User Interface APIs UIM Advantages DDS Advantages 8-28 Virtual Terminal APIs Work Management APIs Work Station Support APIs Miscellaneous APIs Miscellaneous APIs Process Open List APIs 8-30 Chapter 9. Common API Programming Errors Using the Error Code Parameter 9-2 Using the Error Code ParameterExample of Incorrect Coding Using the Error Code ParameterExample of Correct Coding 9-4 Defining Data Structures Defining a Data StructureExample of Incorrect Coding 9-6 Defining A Data StructureExample of Correct Coding 9-8 Page Defining Receiver Variables 9-10 Defining Receiver VariablesExample of Incorrect Coding Defining Receiver VariablesExample of Correct Coding 9-12 Defining List Entry Format Lengths 9-14 Defining List Entry Format LengthsExample of Incorrect Coding Defining List Entry Format LengthsExample of Correct Coding 9-16 Using Null Pointers with OPM APIs 9-18 Using Null Pointers with OPM APIsExample of Incorrect Coding Using Null Pointers with OPM APIsExample of Correct Coding 9-20 Defining Byte Alignment 9-22 Defining Byte AlignmentExample of Incorrect Coding 9-24 Defining Byte AlignmentExample of Correct Coding 9-26 Using Offsets in a User Space Using Offsets in a User SpaceExample of Incorrect Coding 9-28 9-30 Using Offsets in a User SpaceExample of Correct Coding 9-32 9-34 Coding for New Function 9-36 Coding for New FunctionExample of Incorrect Coding 9-38 9-40 9-42 Coding for New FunctionExample of Correct Coding 9-44 9-46 9-48 9-50 Appendix A. Performing Tasks Using APIsExamples Packaging Your Own Software Products CL Program for Creating Objects and Library for Packaging a Product A-2 Program for Packaging a ProductOPM RPG Example A-4 A-6 A-8 A-10 Retrieving a File Description to a User SpaceILE C Example A-12 A-14 Using Data Queues versus User Queues Data QueueILE C Example A-16 User QueueILE C Example A-18 A-20 Page Page Appendix B. Original Examples in Additional Languages Original Program Model (OPM) APIsExamples B-2 Retrieving the Hold Parameter (Exception Message)ILE C Example Retrieving the Hold Parameter (Exception Message)ILE COBOL Example B-4 Retrieving the Hold Parameter (Exception Message)ILE RPG Example B-6 Handling Error ConditionsILE RPG Example B-8 Retrieving the Hold Parameter (Error Code Structure)ILE C Example B-10 Retrieving the Hold Parameter (Error Code Structure)ILE COBOL Example B-12 Retrieving the Hold Parameter (Error Code Structure)ILE RPG Example B-14 Accessing the HOLD AttributeILE C Example B-16 Accessing the HOLD AttributeILE COBOL Example B-18 B-20 Accessing the HOLD AttributeILE RPG Example Accessing a Field Value (Initial Library List)ILE C Example B-22 B-24 Accessing a Field Value (Initial Library List)ILE COBOL Example B-26 B-28 Accessing a Field Value (Initial Library List)ILE RPG Example B-30 B-32 Using Keys with List Spooled Files APIILE C Example B-34 B-36 Using Keys with List Spooled Files APIILE COBOL Example B-38 B-40 Using Keys with List Spooled Files APIILE RPG Example B-42 B-44 B-46 Integrated Language Environment (ILE) APIsExamples Register Exit Point and Add Exit ProgramOPM COBOL Example B-48 Register Exit Point and Add Exit ProgramILE COBOL Example B-50 B-52 Register Exit Point and Add Exit ProgramOPM RPG Example B-54 B-56 Register Exit Point and Add Exit ProgramILE RPG Example B-58 B-60 Retrieve Exit Point and Exit Program InformationOPM COBOL Example B-62 B-64 Retrieve Exit Point and Exit Program InformationILE COBOL Example B-66 B-68 B-70 Retrieve Exit Point and Exit Program InformationOPM RPG Example B-72 B-74 Retrieve Exit Point and Exit Program InformationILE RPG Example B-76 B-78 B-80 B-82 B-84 Remove Exit Program and Deregister Exit PointOPM COBOL Example B-86 Remove Exit Program and Deregister Exit PointILE COBOL Example B-88 Remove Exit Program and Deregister Exit PointOPM RPG Example B-90 Remove Exit Program and Deregister Exit PointILE RPG Example B-92 List Object APIExamples B-94 List Object APIILE C Example B-96 B-98 B-100 List Object APIILE COBOL Example B-102 B-104 List Object APIILE RPG Example B-106 B-108 B-110 OPM API without PointersExamples B-112 Logging Software Error (OPM API without Pointers)OPM COBOL Example CBLERR1 Program ERRHDL1 Program B-114 Logging Software Error (OPM API without Pointers)OPM RPG Example B-116 B-118 Logging Software Error (OPM API without Pointers)ILE RPG Example B-120 ILE API with PointersExamples B-122 Reporting Software Error (ILE API with Pointers)ILE COBOL Example CBLERR2 Program ERRHDL2 Program B-124 Reporting Software Error (ILE API with Pointers)ILE RPG Example B-126 B-128 Program for Packaging a ProductExamples Program for Packaging a ProductILE C Example B-130 B-132 B-134 Program for Packaging a ProductILE COBOL Example B-136 B-138 B-140 B-142 Program for Packaging a ProductILE RPG Example B-144 B-146 B-148 B-150 Retrieving a File Description to a User SpaceExamples B-152 Retrieving a File Description to a User SpaceILE COBOL Example B-154 Retrieving a File Description to a User SpaceILE RPG Example B-156 B-158 B-160 B-162 B-164 Data QueueExamples Data QueueILE COBOL Example B-166 B-168 Data QueueOPM RPG Example B-170 Data QueueILE RPG Example B-172 B-174 UNIX-Type APIsExamples Using the Integrated File SystemILE C Example B-176 Using the Integrated File SystemILE COBOL Example B-178 B-180 B-182 Using the Integrated File SystemILE RPG Example B-184 B-186 Page Page PrintManager API Reference Machine Interface Functional Reference GDDM Programming Guide DB2 for AS/400 Query Management Programming Programming Language Books Page Page Index Special Characters Numerics A Index X-2 Index X-4 B Index C X-6 D Index X-8 E Index X-10 Index (continued) X-12 See (continued) F G H Index I X-14 J K L Index M X-16 N Index O X-18 P Index X-20 Index Q X-22 Index R X-24 Index S X-26 T Index U X-28 V W Z Page Reader CommentsWe'd Like to Hear from You! BUSINESS REPLY MAIL