IBM Universal Remote Version 4 User Manual
AS/400 Advanced Series  
IBM  
System API Programming  
Version 4  
SC41-5800-00  
Download from Www.Somanuals.com. All Manuals Search And Download.  
AS/400 Advanced Series  
IBM  
System API Programming  
Version 4  
SC41-5800-00  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Take Note!  
Before using this information and the product it supports, be sure to read the general information under “Notices” on page xi.  
First Edition (August 1997)  
This edition applies to the licensed program IBM Operating System/400 (Program 5769-SS1), Version 4 Release 1 Modification 0,  
and to all subsequent releases and modifications until otherwise indicated in new editions.  
Make sure that you are using the proper edition for the level of the product.  
Order publications through your IBM representative or the IBM branch serving your locality. If you live in the United States, Puerto  
Rico, or Guam, you can order publications through the IBM Software Manufacturing Solutions at 800+879-2755. Publications are not  
stocked at the address given below.  
IBM welcomes your comments. A form for readers’ comments may be provided at the back of this publication. You can also mail  
your comments to the following address:  
IBM Corporation  
Attention Department 542  
IDCLERK  
3605 Highway 52 N  
Rochester, MN 55901-7829 USA  
or you can fax your comments to:  
United States and Canada: 800+937-3430  
Other countries: (+1)+507+253-5192  
If you have access to Internet, you can send your comments electronically to [email protected]; IBMMAIL, to  
IBMMAIL(USIB56RZ).  
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes  
appropriate without incurring any obligation to you.  
Copyright International Business Machines Corporation 1997. All rights reserved.  
Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to  
restrictions set forth in GSA ADP Schedule Contract with IBM Corp.  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Contents  
Notices  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi  
. . . . . . . . . . . . . . . . . . . . . . . . . xii  
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii  
Programming Interface Information  
About System API Programming (SC41-5800)  
. . . . . . . . . . . . . . . . . xiii  
Who Should Use This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii  
. . . . . . . . . . . . . . . . . . . . . . . . xiii  
Prerequisite and Related Information  
Information Available on the World Wide Web . . . . . . . . . . . . . . . . . . . xiii  
Chapter 1. Application Programming Interface—Overview  
. . . . . . . . . 1-1  
API Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2  
Using APIs—Benefits  
System APIs or CL Commands—When to Use Each . . . . . . . . . . . . . . . 1-3  
Actions and System Functions of APIs  
Related Information  
. . . . . . . . . . . . . . . . . . . . . . . 1-3  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4  
Chapter 2. Getting Started with APIs . . . . . . . . . . . . . . . . . . . . . . . 2-1  
Locating the API to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1  
Selecting the High-Level Language To Use  
. . . . . . . . . . . . . . . . . . . . 2-3  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4  
API Environments  
APIs for the Original Program Model Environment . . . . . . . . . . . . . . . 2-4  
APIs for the Integrated Language Environment . . . . . . . . . . . . . . . . . 2-5  
APIs for the ILE Common Execution Environment (CEE) . . . . . . . . . . . 2-5  
APIs for the UNIX Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6  
API Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6  
Parameter Passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7  
Parameter Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8  
Error Code Parameter  
Using the Job Log to Diagnose API Errors  
Internal Identifiers  
User Spaces  
User Space Format—Example  
Logic Flow of Processing a List of Entries . . . . . . . . . . . . . . . . . . . 2-15  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8  
. . . . . . . . . . . . . . . . . . 2-10  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13  
. . . . . . . . . . . . . . . . . . . . . . . . . 2-14  
Manipulating a User Space with Pointers  
Manipulating a User Space without Pointers  
. . . . . . . . . . . . . . . . . . . 2-16  
. . . . . . . . . . . . . . . . . 2-17  
Additional Information about List APIs and a User Space . . . . . . . . . . 2-22  
Listing Database File Members with a CL Program—Example . . . . . . . 2-22  
Receiver Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23  
Bytes Available and Bytes Returned Fields . . . . . . . . . . . . . . . . . . 2-23  
Keyed Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24  
User Space Alternative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25  
Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25  
Continuation Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25  
Using a Continuation Handle  
. . . . . . . . . . . . . . . . . . . . . . . . . . 2-25  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26  
Domain Concepts  
Exit Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27  
Exit Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27  
APIs and the QSYSINC Library  
. . . . . . . . . . . . . . . . . . . . . . . . . . 2-28  
APIs and the QUSRTOOL Library . . . . . . . . . . . . . . . . . . . . . . . . . 2-30  
User Index Considerations  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30  
Copyright IBM Corp. 1997  
iii  
Download from Www.Somanuals.com. All Manuals Search And Download.  
APIs and Internal System Objects . . . . . . . . . . . . . . . . . . . . . . . . . 2-31  
Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31  
Chapter 3. Common Information across APIs—Basic (OPM) Example . . 3-1  
Original Program Model (OPM) API–Scenario . . . . . . . . . . . . . . . . . . . 3-1  
Finding the API Name to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1  
Description of an API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2  
Format  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5  
Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5  
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5  
Extracting a Field from the Format . . . . . . . . . . . . . . . . . . . . . . . . 3-5  
Retrieving the Hold Parameter (Exception Message)—OPM RPG Example  
Retrieving the Hold Parameter (Error Code Structure)—OPM RPG  
3-6  
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11  
Accessing the HOLD Attribute—OPM RPG Example . . . . . . . . . . . . . . 3-17  
Accessing a Field Value (Initial Library List)—OPM RPG Example  
Using Keys with List Spooled Files API—Example  
Processing Lists That Contain Data Structures . . . . . . . . . . . . . . . . . . 3-29  
Retrieve Job Description Information API—Example . . . . . . . . . . . . . . 3-29  
Authorities and Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30  
. . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30  
. . . . 3-19  
. . . . . . . . . . . . . . . 3-24  
Required Parameter Group  
JOBD0100 Format  
Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32  
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-36  
Chapter 4. Common Information across APIs—Advanced (ILE) Example  
4-1  
Integrated Language Environment (ILE) APIs—Introduction . . . . . . . . . . . 4-1  
Registration Facility Using ILE APIs—Concepts . . . . . . . . . . . . . . . . . . 4-2  
Generic Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2  
Keyed Interface—Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3  
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5  
Receiver Variables—Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7  
Registration Facility Using ILE APIs—Examples . . . . . . . . . . . . . . . . . . 4-9  
Register Exit Point and Add Exit Program—ILE C Example . . . . . . . . . . 4-9  
Retrieve Exit Point and Exit Program Information—ILE C Example  
. . . . 4-13  
Remove Exit Program and Deregister Exit Point—ILE C Example . . . . . 4-19  
Chapter 5. List APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1  
Characteristics of a List API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1  
General Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1  
Processing a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4  
List Object API—OPM RPG Example . . . . . . . . . . . . . . . . . . . . . . . . 5-4  
List Objects That Adopt Owner Authority API—Example . . . . . . . . . . . . 5-12  
Authorities and Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12  
Required Parameter Group  
. . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12  
User Space Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14  
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16  
Chapter 6. Original Program Model (OPM) and Integrated Language  
Environment (ILE) Differences . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1  
Contrasting OPM and ILE APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1  
API Name  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1  
Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1  
Error Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1  
iv System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2  
. . . . . . . . . . . . . . . . . . 7-1  
Chapter 7. Machine Interface Programming  
Machine Interface Instructions—Introduction . . . . . . . . . . . . . . . . . . . . 7-1  
Writing an MI Program—Example . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2  
Setting the Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2  
Setting the Declare Statements . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2  
Starting the Instruction Stream  
Compiling a Program  
Using CLCRTPG to Create an MI Program . . . . . . . . . . . . . . . . . . . 7-5  
Creating the MI Example Program  
Debugging the MI Program  
. . . . . . . . . . . . . . . . . . . . . . . . . . 7-3  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4  
. . . . . . . . . . . . . . . . . . . . . . . . 7-6  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7  
Setting Breakpoints in the MI Program . . . . . . . . . . . . . . . . . . . . . . 7-7  
Handling Exceptions in the MI Program . . . . . . . . . . . . . . . . . . . . . 7-9  
Creating an MI Version of CLCRTPG . . . . . . . . . . . . . . . . . . . . . . . 7-11  
Source for the CL03 Program . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13  
Source for the CL04 Program . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13  
Source for the CL05 Program . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14  
Source for the MICRTPG Program . . . . . . . . . . . . . . . . . . . . . . . 7-15  
Understanding the MICRTPG Program (by Sections of Code) . . . . . . . 7-16  
Enhanced Version of the MICRTPG Program  
. . . . . . . . . . . . . . . . . . 7-18  
. . . . . . 7-18  
Understanding the MICRTPG2 Program (by Sections of Code)  
Beginning the Instruction Stream . . . . . . . . . . . . . . . . . . . . . . . . 7-22  
MICRTPG2 Complete Program—MI Code Example . . . . . . . . . . . . . 7-23  
Creating the MICRTPG2 Program . . . . . . . . . . . . . . . . . . . . . . . . . 7-27  
Handling Exceptions in the MICRTPG2 Program . . . . . . . . . . . . . . . 7-27  
MI Common Programming Techniques—Examples . . . . . . . . . . . . . . . 7-32  
AS/400 Program Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-36  
Chapter 8. Use of OS/400 APIs  
. . . . . . . . . . . . . . . . . . . . . . . . . . 8-1  
Backup and Recovery APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1  
Client Support APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1  
Communications APIs  
Configuration APIs  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3  
Debugger APIs  
Dynamic Screen Manager APIs . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4  
Edit Function APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5  
File APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3  
Hardware Resource APIs  
Hierarchical File System (HFS) APIs . . . . . . . . . . . . . . . . . . . . . . . 8-6  
High-Level Language APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6  
Integrated Language Environment (ILE) CEE APIs . . . . . . . . . . . . . . . 8-7  
Journal and Commit APIs  
Message Handling APIs  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8  
National Language Support APIs . . . . . . . . . . . . . . . . . . . . . . . . . 8-9  
Network Management APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9  
Object APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11  
Office APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15  
Operational Assistant APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17  
Performance Collector APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17  
Print APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17  
Problem Management APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18  
Program and CL Command APIs . . . . . . . . . . . . . . . . . . . . . . . . 8-19  
Registration Facility APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19  
Contents  
v
Download from Www.Somanuals.com. All Manuals Search And Download.  
Security APIs  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20  
Software Product APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20  
UNIX-Type APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21  
User Interface APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27  
Virtual Terminal APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28  
Work Management APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28  
Work Station Support APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28  
Miscellaneous APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29  
Chapter 9. Common API Programming Errors . . . . . . . . . . . . . . . . . 9-1  
Using the Error Code Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2  
Using the Error Code Parameter—Example of Incorrect Coding . . . . . . . 9-2  
Using the Error Code Parameter—Example of Correct Coding . . . . . . . . 9-3  
Defining Data Structures  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5  
Defining a Data Structure—Example of Incorrect Coding . . . . . . . . . . . 9-5  
Defining A Data Structure—Example of Correct Coding . . . . . . . . . . . . 9-7  
Defining Receiver Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10  
Defining Receiver Variables—Example of Incorrect Coding . . . . . . . . . 9-10  
Defining Receiver Variables—Example of Correct Coding . . . . . . . . . . 9-12  
Defining List Entry Format Lengths  
Defining List Entry Format Lengths—Example of Incorrect Coding . . . . . 9-14  
Defining List Entry Format Lengths—Example of Correct Coding . . . . . 9-16  
Using Null Pointers with OPM APIs . . . . . . . . . . . . . . . . . . . . . . . . 9-18  
Using Null Pointers with OPM APIs—Example of Incorrect Coding . . . . 9-18  
. . . . . . . . . . . . . . . . . . . . . . . . 9-14  
Using Null Pointers with OPM APIs—Example of Correct Coding . . . . . 9-19  
Defining Byte Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22  
Defining Byte Alignment—Example of Incorrect Coding . . . . . . . . . . . 9-22  
Defining Byte Alignment—Example of Correct Coding . . . . . . . . . . . . 9-25  
Using Offsets in a User Space . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-27  
Using Offsets in a User Space—Example of Incorrect Coding . . . . . . . 9-27  
Using Offsets in a User Space—Example of Correct Coding . . . . . . . . 9-31  
Coding for New Function  
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-36  
Coding for New Function—Example of Incorrect Coding  
Coding for New Function—Example of Correct Coding  
. . . . . . . . . . 9-36  
. . . . . . . . . . . 9-43  
Appendix A. Performing Tasks Using APIs—Examples . . . . . . . . . . A-1  
Packaging Your Own Software Products A-1  
. . . . . . . . . . . . . . . . . . . . .  
Retrieving a File Description to a User Space—ILE C Example . . . . . . . . A-11  
Using Data Queues versus User Queues . . . . . . . . . . . . . . . . . . . . . A-15  
Data Queue—ILE C Example . . . . . . . . . . . . . . . . . . . . . . . . . . A-16  
User Queue—ILE C Example . . . . . . . . . . . . . . . . . . . . . . . . . . A-17  
Appendix B. Original Examples in Additional Languages . . . . . . . . . B-1  
Original Program Model (OPM) APIs—Examples  
. . . . . . . . . . . . . . . .  
B-2  
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 Conditions—ILE RPG Example . . . . . . . . . . . . . . . . B-8  
Retrieving the Hold Parameter (Error Code Structure)—ILE C Example  
Retrieving the Hold Parameter (Error Code Structure)—ILE COBOL  
. B-10  
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12  
Retrieving the Hold Parameter (Error Code Structure)—ILE RPG Example B-14  
Accessing the HOLD Attribute—ILE C Example  
. . . . . . . . . . . . . . . B-16  
Accessing the HOLD Attribute—ILE COBOL Example . . . . . . . . . . . . B-18  
vi System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Accessing the HOLD Attribute—ILE RPG Example  
Accessing a Field Value (Initial Library List)—ILE C Example  
. . . . . . . . . . . . . B-21  
. . . . . . . B-22  
Accessing a Field Value (Initial Library List)—ILE COBOL Example . . . . B-25  
Accessing a Field Value (Initial Library List)—ILE RPG Example . . . . . . B-29  
Using Keys with List Spooled Files API—ILE C Example . . . . . . . . . . B-33  
Using Keys with List Spooled Files API—ILE COBOL Example  
Using Keys with List Spooled Files API—ILE RPG Example . . . . . . . . B-42  
Integrated Language Environment (ILE) APIs—Examples  
. . . . . . B-38  
. . . . . . . . . . . B-47  
Register Exit Point and Add Exit Program—OPM COBOL Example . . . . B-47  
Register Exit Point and Add Exit Program—ILE COBOL Example . . . . . B-50  
Register Exit Point and Add Exit Program—OPM RPG Example . . . . . . B-54  
Register Exit Point and Add Exit Program—ILE RPG Example . . . . . . . B-58  
Retrieve Exit Point and Exit Program Information—OPM COBOL Example B-61  
Retrieve Exit Point and Exit Program Information—ILE COBOL Example . B-66  
Retrieve Exit Point and Exit Program Information—OPM RPG Example  
Retrieve Exit Point and Exit Program Information—ILE RPG Example  
. B-71  
. . B-75  
Remove Exit Program and Deregister Exit Point—OPM COBOL Example  
B-85  
Remove Exit Program and Deregister Exit Point—ILE COBOL Example . B-87  
Remove Exit Program and Deregister Exit Point—OPM RPG Example . . B-90  
Remove Exit Program and Deregister Exit Point—ILE RPG Example . . . B-92  
List Object API—Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-94  
List Object API—ILE C Example  
. . . . . . . . . . . . . . . . . . . . . . . . B-94  
List Object API—ILE COBOL Example . . . . . . . . . . . . . . . . . . . . B-101  
List Object API—ILE RPG Example  
OPM API without Pointers—Examples  
. . . . . . . . . . . . . . . . . . . . . B-106  
. . . . . . . . . . . . . . . . . . . . . B-112  
Logging Software Error (OPM API without Pointers)—OPM COBOL  
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-112  
Logging Software Error (OPM API without Pointers)—OPM RPG Example B-116  
Logging Software Error (OPM API without Pointers)—ILE RPG Example B-119  
ILE API with Pointers—Examples  
. . . . . . . . . . . . . . . . . . . . . . . . B-122  
Reporting Software Error (ILE API with Pointers)—ILE COBOL Example  
B-122  
Reporting Software Error (ILE API with Pointers)—ILE RPG Example . . B-126  
Program for Packaging a Product—Examples . . . . . . . . . . . . . . . . . B-129  
Program for Packaging a Product—ILE C Example  
Program for Packaging a Product—ILE COBOL Example . . . . . . . . . B-136  
Program for Packaging a Product—ILE RPG Example  
. . . . . . . . . . . . B-129  
. . . . . . . . . . B-144  
Retrieving a File Description to a User Space—Examples . . . . . . . . . . B-152  
Retrieving a File Description to a User Space—ILE COBOL Example . . B-152  
Retrieving a File Description to a User Space—ILE RPG Example  
. . . B-155  
Data Queue—Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-165  
. . . . . . . . . . . . . . . . . . . . . B-165  
Data Queue—ILE COBOL Example  
Data Queue—OPM RPG Example . . . . . . . . . . . . . . . . . . . . . . B-169  
Data Queue—ILE RPG Example . . . . . . . . . . . . . . . . . . . . . . . B-172  
UNIX-Type APIs—Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . B-175  
Using the Integrated File System—ILE C Example . . . . . . . . . . . . . B-175  
Using the Integrated File System—ILE COBOL Example . . . . . . . . . B-178  
Using the Integrated File System—ILE RPG Example . . . . . . . . . . . B-183  
Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . H-1  
General-Purpose Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . H-1  
OS/400 API Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . H-1  
Programming Language Books . . . . . . . . . . . . . . . . . . . . . . . . . . . H-2  
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
X-1  
Contents vii  
Download from Www.Somanuals.com. All Manuals Search And Download.  
viii System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Figures  
1-1. How APIs Fit into the AS/400 Business Computing System Structure 1-2  
2-1. OPM and ILE API Verbs and Abbreviations . . . . . . . . . . . . . . . 2-2  
2-2. Language Selection Considerations — Data Types . . . . . . . . . . . 2-3  
2-3. Language Selection Considerations — Call Conventions  
. . . . . . . 2-4  
. . . . . . . . . . . . . . . . . . . . . 2-7  
2-4. Methods for Passing Parameters  
2-5. Include Files Shipped with the QSYSINC Library . . . . . . . . . . . 2-28  
5-1. General Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2  
7-1. Program Flow for Creating the MICRTPG Program . . . . . . . . . . 7-12  
8-1. Simplified Sequence of Events for a Sockets Program Example . . 8-26  
9-1. Common Programming Errors . . . . . . . . . . . . . . . . . . . . . . . 9-1  
A-1. ABC Software Packaging . . . . . . . . . . . . . . . . . . . . . . . . . A-1  
A-2. Steps for Creating a Software Product . . . . . . . . . . . . . . . . . A-2  
B-1. Original Program Model (OPM) API Examples from Chapter 3 . . . B-1  
B-2. Integrated Language Environment (ILE) API Examples from Chapter  
4
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  
B-1  
B-1  
B-1  
B-2  
B-2  
B-3. List API Examples from Chapter 5  
B-4. Pointer API Examples from Chapter 6  
B-5. Performing Tasks Using API Examples from Appendix A  
B-6. UNIX-Type API Examples  
. . . . . . . . . . . . . . . . . . .  
. . . . . . . . . . . . . . . . .  
. . . . . .  
. . . . . . . . . . . . . . . . . . . . . . . .  
Copyright IBM Corp. 1997  
ix  
Download from Www.Somanuals.com. All Manuals Search And Download.  
x
System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Notices  
References in this publication to IBM products, programs, or services do not imply that IBM intends to  
make these available in all countries in which IBM operates. Any reference to an IBM product, program,  
or service is not intended to state or imply that only that IBM product, program, or service may be used.  
Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent  
product, program, or service may be used instead of the IBM product, program, or service. The evaluation  
and verification of operation in conjunction with other products, except those expressly designated by IBM,  
are the responsibility of the user.  
IBM may have patents or pending patent applications covering subject matter in this document. The fur-  
nishing of this document does not give you any license to these patents. You can send license inquiries,  
in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY  
10594, U.S.A.  
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the  
exchange of information between independently created programs and other programs (including this one)  
and (ii) the mutual use of the information which has been exchanged, should contact the software interop-  
erability coordinator. Such information may be available, subject to appropriate terms and conditions,  
including in some cases, payment of a fee.  
Address your questions to:  
IBM Corporation  
Software Interoperability Coordinator  
3605 Highway 52 N  
Rochester, MN 55901-7829 USA  
This publication could contain technical inaccuracies or typographical errors.  
This publication may refer to products that are announced but not currently available in your country. This  
publication may also refer to products that have not been announced in your country. IBM makes no  
commitment to make available any unannounced products referred to herein. The final decision to  
announce any product is based on IBM's business and technical judgment.  
This publication contains examples of data and reports used in daily business operations. To illustrate  
them as completely as possible, the examples include the names of individuals, companies, brands, and  
products. All of these names are fictitious and any similarity to the names and addresses used by an  
actual business enterprise is entirely coincidental.  
This publication contains small programs that are furnished by IBM as simple examples to provide an  
illustration. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot  
guarantee or imply reliability, serviceability, or function of these programs. All programs contained herein  
are provided to you "AS IS". THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR  
A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED.  
Copyright IBM Corp. 1997  
xi  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Programming Interface Information  
This publication is intended to help experienced programmers create application programs. This publica-  
tion documents General-Use Programming Interface and Associated Guidance Information provided by the  
Operating System/400 (OS/400) licensed program.  
General-Use programming interfaces allow the customer to write programs that obtain the services of the  
OS/400 program. If you have a requirement for additional interfaces to the OS/400 program, contact IBM  
at 1-507-253-1055 (FAX 507-253-1571).  
Trademarks  
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:  
Advanced Function Printing  
Advanced Peer-to-Peer Networking  
AFP  
Operating System/2  
Operating System/400  
Operational Assistant  
OS/400  
Application System/400  
APPN  
AS/400  
PrintManager  
RPG IV  
C/400  
RPG/400  
COBOL/400  
SAA  
DB2  
SOM  
FORTRAN/400  
GDDM  
SOMobjects  
System/38  
IBM  
System/370  
Systems Application Architecture  
Ultimedia  
Integrated Language Environment  
NetView  
OfficeVision  
400  
Microsoft, Windows, and the Windows 95 logo are trademarks or registered trademarks of Microsoft Cor-  
poration.  
PC Direct is a trademark of Ziff Communications Company and is used by IBM Corporation under license.  
UNIX is a registered trademark in the United States and other countries licensed exclusively through  
X/Open Company Limited.  
C-bus is a trademark of Corollary, Inc.  
Java and HotJava are trademarks of Sun Microsystems, Inc.  
Other company, product, and service names, which may be denoted by a double asterisk (**), may be  
trademarks or service marks of others.  
xii System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
About System API Programming (SC41-5800)  
This book provides introductory, conceptual, and  
Prerequisite and Related  
Information  
guidance information about how to use OS/400  
application programming interfaces (APIs) with  
your application programs. It includes examples  
and discusses the following:  
For information about other AS/400 publications  
(except Advanced 36), see either of the following:  
Ÿ Benefits of using APIs  
Ÿ The Publications Reference book, SC41-5003,  
in the AS/400 Softcopy Library.  
Ÿ When to use APIs versus CL commands  
Ÿ How to locate an API in the System API Ref-  
erence book, SC41-5801  
Ÿ Which high-level language (HLL) to use for  
APIs  
Ÿ The AS/400 Information Directory, a unique,  
multimedia interface to a searchable database  
that contains descriptions of titles available  
from IBM or from selected other publishers.  
The AS/400 Information Directory is shipped  
with the OS/400 operating system at no  
charge.  
Ÿ Various API environments  
Ÿ Common information across object program  
model (OPM) APIs and Integrated Language  
Environment (ILE) APIs  
Ÿ Characteristics and use of list APIs  
Ÿ Differences between OPM and ILE APIs  
Ÿ Machine interface (MI) programming  
Ÿ Why you might want to make use of various  
OS/400 APIs  
Information Available on the  
World Wide Web  
Ÿ Tips for common API programming errors  
More AS/400 information is available on the World  
Wide Web. You can access this information from  
the AS/400 home page, which is at the following  
uniform resource locator (URL) address:  
This book provides introductory and guidance  
information only; it does not contain API reference  
information. For reference information, see the  
System API Reference book.  
http://www.as4ðð.ibm.com  
Select the Information Desk, and you will be able  
to access a variety of AS/400 information topics  
from that page.  
For a list of related publications, see the  
“Bibliography” on page H-1.  
Who Should Use This Book  
This book is intended for experienced application  
programmers who are developing system-level  
and other OS/400 applications.  
Copyright IBM Corp. 1997  
xiii  
Download from Www.Somanuals.com. All Manuals Search And Download.  
xiv System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
API Compatibility  
Chapter 1. Application Programming Interface—Overview  
Application programming interfaces (APIs) that are used on AS/400 business com-  
puting systems provide paths into system functions. APIs are intended for experi-  
enced application programmers who develop system-level applications and other  
AS/400 applications.  
In the broadest sense, AS/400 application programming interfaces (APIs) are  
any formal interfaces that are intended to be used in the building of applications.  
These interfaces can include such functions as:  
Ÿ Control language (CL) commands  
Ÿ High-level language (HLL) instructions  
Ÿ Machine Interface (MI) instructions  
Ÿ Exit programs  
Ÿ Callable Operating System/400 (OS/400) APIs, such as those discussed in the  
System API Reference, SC41-5801, and documentation for various licensed  
programs.  
The APIs discussed in this book are those callable and bindable OS/400 APIs and  
OS/400 exit programs that are documented in the System API Reference.  
Figure 1-1 on page 1-2 shows how APIs fit into the system structure.  
API Compatibility  
Original program model (OPM) APIs and Integrated Language Environment (ILE)  
APIs must be compatible from one release to the next. To ensure this compat-  
ibility, at least one of the following is true:  
Ÿ Any additional parameters for existing OPM APIs are placed after the current  
parameters and are optional parameters. For example, the Move Program  
Message (QMHMOVPM) API has a group of required parameters and two  
groups of optional parameters.  
Note: ILE APIs cannot have additional parameters added to existing APIs.  
Ÿ Any additional data structures are provided as a new format.  
Ÿ Any new information for a data structure is added at the end of that format or  
replaces a field currently defined as reserved.  
It is IBM's intention that the APIs will continue to work as they originally worked and  
any existing applications that use the APIs will continue to work without changes.  
However, significant architectural changes may necessitate incompatible changes.  
Some API definitions (for example, the UNIX** type of API definitions) are estab-  
lished by industry standards organizations where the degree of compatibility is  
determined by the organizations.  
Copyright IBM Corp. 1997  
1-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
CL  
Program  
Application  
Licensed Programs  
Commands  
User  
Exit  
Application  
High-Level  
Languages  
HLL  
Program  
Application  
Calls  
Exits  
OS/400  
ILE C for AS/400  
or  
MI Application  
MI  
Machine  
Interface  
Licensed Internal Code  
CL commands  
Callable programs  
Exit programs  
Machine Interface Instructions  
(accessible through ILE C for AS/400 or MI programming languages)  
RV3W217-1  
Figure 1-1. How APIs Fit into the AS/400 Business Computing System Structure  
Using APIs—Benefits  
Although some CL commands and some OS/400 APIs perform the same basic  
functions, APIs often can provide additional performance improvements and access  
to functions. Benefits for using APIs include the following:  
Ÿ APIs are slightly faster than the following:  
– Using the equivalent command or calling a CL program to call the  
command.  
– Coding a call to a command by using the Process Commands (QCAPCMD)  
API because the API is saved the overhead of processing a command.  
When you call an API, you do not have to go through the command ana-  
lyzer.  
– Using the system function in the ILE C language that processes com-  
mands.  
1-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Ÿ Your application is more straightforward if you are coding in a programming lan-  
guage other than CL, which is not a fully defined language (it does not have  
the full capabilities of a high-level language). For example, you may have to  
code separate CL programs to perform specific functions.  
Ÿ You can access system information and functions that are not available through  
CL commands.  
Ÿ Data is often easier to work with when returned to you by an API.  
Ÿ At times, you may need access to system functions at a lower level than what  
was initially provided on the AS/400 system. APIs and a set of documented  
machine interface (MI) instructions are available to allow the experienced pro-  
grammer access to these system functions.  
System APIs or CL Commands—When to Use Each  
Before system APIs were offered on the AS/400, you had to either code separate  
CL programs to perform the needed functions using the appropriate CL commands  
or code a call to the Execute Command (QCMDEXC) API in your program. Both  
methods made coding an application on the AS/400 more cumbersome (less  
straightforward and not as fast as possible).  
CL commands will always be needed; they are ideal for the interactive user and for  
CL applications that are performing basic tasks. They provide a complete set of  
functions on the AS/400 system.  
APIs are not provided as a replacement for CL commands, although in many cases  
there may be both an API and a CL command that perform the same function. If a  
CL command and an API provide the same function, at times the API provides  
more flexibility and information. The CL command is intended to be entered either  
interactively or in a CL program, and the API is designed as a programming inter-  
face.  
Some APIs have no equivalent CL command. These APIs have been provided in  
areas where customers and business partners have indicated that they need high-  
level language (HLL) access.  
Actions and System Functions of APIs  
An API can be categorized by the type of action it performs and by the system  
function that it relates to.  
Following are some of the types of APIs that perform actions; several examples of  
these APIs are discussed in more detail in later chapters of this book.  
Ÿ List APIs, which return lists of information about something on the system.  
Refer to “List Object API—Examples” on page B-94 for an example of a list  
API in both ILE COBOL and ILE RPG.  
Ÿ Retrieve APIs, which return information to the application program.  
Ÿ Create, change, and delete APIs, which work with objects of a specified type  
on the system.  
Ÿ Other APIs, which perform a variety of actions on the system.  
While many APIs are used alone, some can be used together to perform a task or  
function. The following is a list of a few functions:  
Chapter 1. Application Programming Interface—Overview 1-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Ÿ Defining, creating, distributing, and maintaining your own software products.  
See “Packaging Your Own Software Products” on page A-1 for an example of  
packaging a product similar to the way IBM packages products.  
Ÿ Controlling systems and networks, which can include configuration, spooled  
files, network management, problem management, and so forth.  
Ÿ Handling objects, which includes creating, changing, copying, deleting, moving,  
and renaming objects on the system.  
APIs can also be categorized by the operating environment. For more information,  
refer to “API Environments” on page 2-4.  
Related Information  
Besides the OS/400 APIs that are documented in the System API Reference, other  
OS/400 APIs are documented in the following books:  
Ÿ Common Programming APIs Toolkit/400 Reference, SC41-4802  
Ÿ CPI Communications Reference, SC26-4399  
Ÿ DB2 for AS/400 Query Management Programming, SC41-5703  
Ÿ GDDM Programming Guide, SC41-0536  
Ÿ Machine Interface Functional Reference, SC41-5810  
Ÿ PrintManager API Reference, S544-3699  
Ÿ REXX/400 Programmer’s Guide, SC41-5728, and REXX/400 Reference,  
SC41-5729  
Ÿ Ultimedia System Facilities Programming, SC41-4652  
Many products on the AS/400 system also provide APIs. Refer to the product doc-  
umentation for more information.  
Ÿ Client Access  
Ÿ OfficeVision for AS/400  
Ÿ OSI File Services, OSI Message Services, and OSI Communications Sub-  
system  
Ÿ System Manager for AS/400 and Managed System Services for OS/400  
Ÿ TCP/IP Connectivity Utilities for AS/400  
1-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Chapter 2. Getting Started with APIs  
You may find the information in this chapter helpful as you start to work with APIs;  
for example, locating the API that you want to use. It also tells you about informa-  
tion that you will need when using the APIs. Other topics covered are:  
Ÿ Language selection considerations  
Ÿ API environments  
Ÿ API parameters  
Ÿ Internal identifiers  
Ÿ User spaces and receiver variables  
Ÿ Continuation handles  
Ÿ System and user domain concepts  
Ÿ Exit programs  
Ÿ QSYSINC library  
Ÿ QUSRTOOL library  
Ÿ User index considerations (recovering data)  
Ÿ APIs and internal system objects  
Ÿ Performance considerations  
Locating the API to Use  
If you are using the System API Reference, you can use the following methods to  
find an API:  
Ÿ You can use the table of contents where the APIs are grouped by function.  
Within each chapter, the APIs are listed in alphabetical order.  
Ÿ You can use the index where the APIs are listed in alphabetical order under the  
application programming interface (API) topic.  
Ÿ You can also use the index where the APIs are listed under terms such as the  
following:  
– Job API  
– List API  
– Spooled file API  
– Socket network functions (in this case, the term functions means the same  
as APIs)  
Except for APIs that are defined by formal standards organizations (for example,  
UNIX type or Systems Application Architecture (SAA)), OS/400 APIs start with the  
letter Q and are followed by two to three letters that make up an internal compo-  
nent identifier. The last part of the API name identifies the action or function of the  
API. Generally, the information after the component ID is an abbreviation of the  
verb that describes the function of the API. Figure 2-1 on page 2-2 contains all of  
the verbs that are either part of an API name or are implied verbs associated with  
an API name.  
Copyright IBM Corp. 1997  
2-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Figure 2-1. OPM and ILE API Verbs and Abbrevi-  
ations  
Figure 2-1. OPM and ILE API Verbs and Abbrevi-  
ations  
Verb  
Abbreviation  
access  
Verb  
Abbreviation  
access  
Add  
Put  
PUT, Put  
ADD, Add  
C, CHG, Chg, ch  
C, CHK, CHECK  
CLR, Clr  
CLO, close  
Cmp  
PutGet  
Query  
PutGet  
Change  
Check  
Clear  
Q, QRY, Qry  
Read  
RD, Read, read  
Receive  
Register  
Release  
Remove  
Rename  
Report  
Resend  
Reserve  
Restore  
reset  
R, RCV, RECV  
Close  
RG, REG, R, Register  
Complete  
Control  
Convert  
Copy  
RLS  
CTL  
RMV, Rmv, Remove, rm  
CVT, CVRT, Convert  
CPY, Cpy  
CRT, Crt, create  
CST  
RNM, rename  
Report  
Create  
Customize  
Delete  
Deregister  
Disable  
Display  
Dump  
RSN  
Reserve  
DLT, Dlt  
DRG, Deregister  
D
Restore  
rewind  
Resize  
Retrieve  
Roll  
Rsz  
DSP, Dsp  
DMP, Dump  
dup  
R, RTV, Rtv, Retrieve  
Roll  
duplicate  
Edit  
Save  
SAV, Sav, Save  
EDT  
Scan for  
Send  
SCAN  
Enable  
End  
E
S, SND, SEND, Send  
END, End  
EXC, EXEC  
FTR  
Set  
SET, Set  
Execute (run)  
Filter  
Shift  
Shf  
Start  
Start, STR, Str  
Force  
FRC  
Submit  
Switch  
Test  
Submit  
Generate  
Get (fetch)  
Initialize  
Insert  
GEN  
Set  
G, GET, Get, get  
Inz  
T
Toggle  
Transform  
Translate  
truncate  
Unregister  
Update  
Validate  
Work with  
Write  
Tgl  
Ins  
T
link  
link  
TR, TRN, XLATE  
List  
L, LST, List  
LUL  
truncate  
Lock/unlock  
make  
U
mk  
UPD  
Map  
Map  
V
Maximize  
Move  
Mxz  
WK, WRK, Wrk  
WRT, Wrt, write, W  
MOV, Mov  
OPN, open  
Pad  
Open  
Note: Refer to “APIs for the ILE Common Exe-  
cution Environment (CEE)” on page 2-5 for infor-  
mation about ILE CEE API names.  
Pad  
Print  
PRT, Prt  
2-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Selecting the High-Level Language To Use  
You can use APIs with all the languages available on AS/400 business computing  
systems, except for the ILE APIs. ILE APIs that are implemented as service pro-  
grams (*SRVPGM) can be accessed only by ILE languages. In some cases, a  
program (*PGM) interface is provided so that non-ILE languages can access the  
function.  
Some APIs also require that particular data types and particular parameter passing  
conventions be used. Figure 2-2 shows the languages available on the AS/400  
system and the data types that they provide.  
Figure 2-2. Language Selection Considerations — Data Types  
Excep-  
tion  
Han-  
dling  
Float-  
ing  
Point  
Poin-  
ters  
Binary  
2
Binary  
4
Char-  
acter  
Zoned  
Decimal  
Packed  
Decimal  
Struc-  
tures  
Single  
Array  
1
Language  
2
2
BASIC (PRPQ  
5799-FPK)  
X
X
X
X
X
X
X
X
9
ILE C  
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
10  
X
VisualAge C++ for  
OS/400  
3
3
4
4
CL  
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
5
3
3
4
4
ILE CL  
COBOL  
ILE COBOL  
MI  
X
X
X
X
X
6
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
6
X
X
X
X
X
7
7
Pascal (PRPQ  
5799-FRJ)  
X
X
PL/I (PRPQ  
5799-FPJ)  
X
X
X
X
X
X
X
X
X
X
4
4
REXX  
RPG  
X
X
X
X
X
X
8
X
X
X
X
X
X
X
X
X
X
X
X
X
8
ILE RPG  
X
X
Notes:  
1
You cannot develop Cross System Product (CSP) programs on an AS/400 system. However, you can develop CSP pro-  
grams on a System/370 system and run them on your AS/400 system.  
2
3
Refer to the CNVRT$ intrinsic function.  
There is no direct support, but the %BIN function exists on the Change Variable (CHGVAR) CL command to convert to and  
from binary.  
4
5
6
There is no direct support, but you can use the substring capability to simulate structures and arrays.  
There is no direct support, but pointers passed to a CL program are preserved.  
COBOL and ILE COBOL programs cannot monitor for specific messages, but these programs can define an error handler to  
run when a program ends because of an error.  
7
8
There is no direct support, but you can use extended program model (EPM) conversion routines to convert to and from  
zoned and packed decimal.  
RPG programs cannot monitor for specific messages, but these programs turn on an error indicator when a called program  
ends with an error. These programs can define an error handler to run when a program ends because of an error.  
Packed decimal is implemented in ILE C with the decimal() data type.  
Packed decimal is implemented in VisualAge C++ for OS/400 with the Binary Coded Decimal (BCD) class. The BCD class is  
the C++ implementation of the C-language's decimal(). The BCD object can be used in API calls because it is binary com-  
patible with the decimal() data type.  
9
10  
Chapter 2. Getting Started with APIs 2-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Figure 2-3 on page 2-4 shows the languages available on the AS/400 system and  
the parameter support that they provide. For more information, see the reference  
manual for the specific programming language that you plan to use.  
Figure 2-3. Language Selection Considerations — Call Conventions  
Function  
Return  
Values  
Pass  
by  
Value  
Pass by  
Reference  
1
2
Language  
BASIC  
X
X
X
X
X
X
X
X
X
X
X
X
X
ILE C  
X
X
X
X
VisualAge C++ for OS/400  
CL  
ILE CL  
COBOL  
ILE COBOL  
MI  
3
X
X
X
Pascal  
PL/I  
REXX  
RPG  
ILE RPG  
X
X
Notes:  
1
You cannot develop Cross System Product (CSP) programs on an AS/400 system. However,  
you can develop CSP programs on a System/370 and run them on your AS/400 system.  
Return values are used by the UNIX-type APIs and the Dynamic Screen Manager (DSM) APIs.  
COBOL provides a by-content phrase, but it does not have the same semantics as ILE C pass-  
by-value.  
2
3
API Environments  
OS/400 APIs exist in several operating environments on an AS/400 system. These  
environments are:  
Ÿ Original program model (OPM)  
Ÿ Integrated Language Environment (ILE)  
Ÿ ILE Common Execution Environment (CEE)  
Ÿ UNIX-type  
APIs for the Original Program Model Environment  
OPM APIs, the initial APIs on AS/400, use the following naming conventions:  
Ÿ Start with the letter Q.  
Ÿ Are followed by a 2- or 3-letter internal component identifier.  
Ÿ Are limited to 8 characters.  
Ÿ Must be uppercase.  
2-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Related Information  
Ÿ System API Reference, SC41-5801  
Ÿ CL Reference, SC41-5722  
Ÿ Chapter 3, “Common Information across APIs—Basic (OPM) Example” on  
page 3-1  
APIs for the Integrated Language Environment  
The Integrated Language Environment (ILE) model is a set of tools and associated  
system support designed to enhance program development on an AS/400 system.  
Bindable ILE APIs are independent from the high-level languages. This can be  
useful when mixed languages are involved.  
The ILE APIs provide functions such as:  
Ÿ Dynamic screen management (DSM)  
Ÿ National language support  
Ÿ Mail server framework  
Ÿ Problem management  
Ÿ Programming and control language (CL)  
Ÿ Registration facility  
Ÿ Source debugger  
ILE APIs use the following naming conventions:  
Ÿ Start with the letter Q.  
Ÿ Are followed by a 2- or 3-character internal component identifier.  
Ÿ Can be up to 30 characters.  
Ÿ Are case sensitive.  
ILE service programs (*SRVPGM) use the following naming conventions:  
Ÿ Start with the letter Q.  
Ÿ Are followed by a 2- or 3-character internal component identifier.  
Ÿ Are limited to 8 characters.  
Ÿ Are uppercase.  
Related Information  
Ÿ Chapter 4, “Common Information across APIs—Advanced (ILE) Example” on  
page 4-1  
Ÿ ILE Concepts, SC41-5606, for conceptual information about ILE  
Ÿ Appropriate language guide or reference for information about the ILE lan-  
guages  
Ÿ System API Reference, SC41-5801  
APIs for the ILE Common Execution Environment (CEE)  
The ILE APIs with names beginning with CEE are based on the SAA language  
environment specifications. These APIs are intended to be consistent across the  
IBM SAA systems. CEE APIs with names beginning with CEE4 or CEES4 are spe-  
cific to AS/400 business computing systems.  
The ILE CEE APIs provide functions such as:  
Ÿ Activation group and control flow management  
Ÿ Condition management  
Ÿ Date and time manipulation  
Chapter 2. Getting Started with APIs 2-5  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Ÿ Math functions  
Ÿ Message services  
Ÿ Program or procedure call management and operational descriptor access  
Ÿ Storage management  
Related Information  
Ÿ “Integrated Language Environment (ILE) CEE APIs” on page 8-7  
Ÿ ILE Concepts, SC41-5606, for conceptual information about ILE  
Ÿ SAA CPI Language Environment Reference, for information about the SAA  
Language Environment  
Ÿ ILE CEE APIs in the System API Reference, SC41-5801  
APIs for the UNIX Environment  
The interfaces provided by sockets, the integrated file system, and the Common  
Programming APIs (CPA) Toolkit/400 are part of a continuing emphasis on sup-  
porting an open environment on the AS/400 system. The socket functions and inte-  
grated file system should ease the amount of effort required to move UNIX**  
applications to the AS/400 system.  
The integrated file system is a function of OS/400 that supports stream input/output  
and storage management similar to personal computer and UNIX operating  
systems. It also provides an integrating structure over all information stored in  
AS/400.  
The naming conventions for the UNIX-type APIs are determined by industry stand-  
ards organizations.  
Related Information  
Ÿ “UNIX-Type APIs” on page 8-21  
Ÿ Common Programming APIs Toolkit/400 Reference, SC41-4802  
Ÿ Integrated File System Introduction, SC41-5711  
Ÿ Sockets Programming, SC41-5422  
Ÿ UNIX-type APIs in the System API Reference, SC41-5801  
API Parameters  
After you have found the API that you want to use, you need to code a call to an  
API and pass to the API the required set of parameters appropriate for that API.  
Parameters can be:  
Ÿ Required, which means that you must enter all of the parameters in the speci-  
fied order.  
Ÿ Optional, which means that you must enter all or none of the parameters within  
the optional group. When you enter an optional group, you must also include  
all preceding optional groups.  
Ÿ Omissible, which means that the group of parameters may have parameters  
that can be omitted. When these parameters are omitted, you must pass a null  
pointer.  
For OPM and ILE APIs, the values for all parameters that identify objects on the  
system must be in *NAME (basic name) format, left-justified, uppercase, and with  
valid special characters. (The *NAME format is a character string that must begin  
with an alphabetic character (A through Z, $, #, or @) followed by up to 9 charac-  
2-6 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ters (A through Z, 0 through 9, $, #, @, ), or _). The system uses an object name  
as is, and it does not change or check the object name before locating the object.  
This improves the performance of the API. An incorrect name usually results in an  
Object not found error.  
Parameter Passing  
With the exception of the UNIX-type APIs, the standard protocol is to pass a space  
pointer that points to the information that is being passed. (This is also referred to  
as pass-by-reference.) This is the convention automatically used by CL, RPG, and  
COBOL compilers. If you are using a language that supports pointers, you must  
ensure that these conventions are followed. Refer to the appropriate language doc-  
umentation for instructions. Refer to “Selecting the High-Level Language To Use”  
on page 2-3 for a table that discusses the high-level languages.  
In an OPM or ILE call, a parameter is an expression that represents a value that  
the calling application passes to the API specified in the call. HLL languages use  
the following methods for passing parameters:  
by value, directly  
The value of the data object is placed directly into the  
parameter list.  
by value, indirectly  
The value of the data object is copied to a temporary  
location. The address of the copy (a pointer) is placed  
into the parameter list. By value, indirectly is not done  
explicitly by the application programmer. It is done by  
the operating system at run time.  
by reference  
A pointer to the data object is placed into the parameter  
list. Changes made by the called API to the parameter  
are reflected in the calling application.  
Figure 2-4 illustrates these parameter passing styles. Not all HLL languages  
support all styles.  
By value, directly  
a copy of argument  
By value, indirectly  
pointer  
a copy of argument  
By reference  
the actual argument  
pointer  
RV2W1027-1  
Figure 2-4. Methods for Passing Parameters  
HLL semantics usually determine when data is passed by value and when it is  
passed by reference. For example, ILE C passes and accepts parameters by  
value, directly, while for OPM and ILE COBOL and OPM and ILE RPG parameters  
are usually passed by reference. You must ensure that the calling program or pro-  
Chapter 2. Getting Started with APIs 2-7  
Download from Www.Somanuals.com. All Manuals Search And Download.  
cedure passes parameters in the manner expected by the called API. The OPM or  
ILE HLL programmer's guides contain more information on passing parameters to  
different languages.  
The ILE languages support the following parameter-passing styles:  
Ÿ ILE C passes and accepts parameters by value (directly and indirectly) and by  
reference.  
Ÿ ILE COBOL and COBOL support the passing of parameters by value (indi-  
rectly) and by reference.  
Ÿ ILE RPG and RPG support the passing of parameters by reference.  
Ÿ ILE CL and CL support the passing of parameters by reference.  
Parameter Classification  
Parameters can be classified into the following general categories:  
Ÿ Input parameters: These parameters must be set to a value before calling the  
API because they pass needed information to the API to enable it to perform its  
function. For example, if the API is to perform a function on an object, one of  
the parameters would be the name and library of that object. Input parameters  
are not changed by the API.  
Ÿ Output parameters: These parameters do not need to be set before calling the  
API because the API returns information to the application in these parameters.  
When a return to the application is successful and no errors have occurred, the  
application then accesses the information returned in output parameters.  
Ÿ Input/Output parameters: These are parameters that are identified as struc-  
tures that contain fields. The fields within the structure can be either input,  
output, or both. For example, the bytes provided field in the error code param-  
eter is an input field. The rest of the fields that make up this parameter are  
output fields. The rules for input parameters and output parameters apply to  
the individual fields in the structure.  
Error Code Parameter  
The error code parameter is a variable-length structure that is a parameter for most  
APIs. (UNIX-type APIs and ILE CEE APIs do not use the error code structure.)  
The error code parameter controls how errors are returned to the application. The  
parameter must be initialized before the program calls the API. Depending on how  
the error code structure is set, this parameter either returns information associated  
with an error condition or causes errors to be returned as exception messages.  
For some APIs, the error code parameter is optional. If you do not code the  
optional error code parameter, the API returns diagnostic and escape messages. If  
you code the optional error code parameter, the API can either signal exceptions or  
return the exception information in the error code parameter.  
The structure for the error code parameter is discussed in the topic “Format of an  
Error Code Structure” on page 3-12. It contains information about the error code  
fields. Although the information is about an RPG example, the information is true  
for other APIs.  
Note: The error code structure is provided in the QSYSINC library and is called  
QUSEC. Refer to Figure 2-5 on page 2-28 for a list of include files that are  
shipped in the QSYSINC library.  
2-8 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Receiving Error Conditions as Exceptions—Example  
This example shows an application that receives error conditions as exceptions. It  
allocates an error code parameter that is a minimum of 4 bytes long to hold the  
bytes provided field. The only field used is the bytes-provided INPUT field, which  
the application sets to zero to request exceptions. The error code parameter con-  
tains the following:  
Field  
INPUT  
OUTPUT  
Bytes provided  
0
0
Receiving the Error Code without the Exception Data—Example  
This application example attempts to create an alert for message ID USR1234 in  
message file USRMSG in library QGPL. It receives the error condition in the error  
code parameter but does not receive any exception data. To do this, it allocates an  
error code parameter that is a minimum of 16 bytes long—for the bytes provided,  
bytes available, exception ID, and reserved fields. It sets the bytes-provided field of  
the error code parameter to 16.  
When the application calls the Generate Alert (QALGENA) API, the alert table  
USRMSG is not found, and QALGENA returns exception CPF7B03. The error  
code parameter contains the data shown in the following table. In this example, 16  
bytes are provided for data, but 36 are available. Twenty more bytes of data could  
be returned if the bytes-provided field were set to reflect a larger error code param-  
eter (see “Receiving the Error Code with the Exception Data—Example”).  
Field  
INPUT  
16  
OUTPUT  
Bytes provided  
Bytes available  
Exception ID  
Reserved  
16  
Ignored  
Ignored  
Ignored  
36  
CPF7B03  
0
Receiving the Error Code with the Exception Data—Example  
This application example attempts to create an alert for message ID USR1234 in  
message file USRMSG in library QGPL. It receives the error condition in the error  
code parameter and receives exception data as well. To do this, it allocates an  
error code parameter that is 116 bytes long—16 bytes for the bytes provided, bytes  
available, exception ID, and reserved fields, and 100 bytes for the exception data  
for the exception. (In some cases, the exception data might be a variable-length  
directory or file name, so this might not be large enough to hold all of the data;  
whatever fits is returned in the error code parameter.) Finally, it sets the bytes-  
provided field to 116.  
When the application calls the Generate Alert (QALGENA) API, the alert table  
USRMSG is not found, and QALGENA returns exception CPF7B03. The error  
code parameter contains the following:  
Field  
INPUT  
116  
OUTPUT  
116  
Bytes provided  
Bytes available  
Ignored  
36  
Chapter 2. Getting Started with APIs 2-9  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Field  
INPUT  
Ignored  
Ignored  
Ignored  
OUTPUT  
CPF7B03  
0
Exception ID  
Reserved  
Exception data  
USRMSG  
QGPL  
Using the Job Log to Diagnose API Errors  
Sometimes an API may issue one or more messages that state that the API failed,  
and the messages may direct you to see the previously listed messages in the job  
log. If your application program needs to determine the cause of the error  
message, you can use the Receive Message (RCVMSG) command or the Receive  
Message APIs to receive the messages that explain the reason for the error. In  
some cases, you can write an application program to use the diagnostic message  
to identify and correct the parameter values that caused the error.  
Receiving Error Messages from the Job Log—Example  
To receive error messages from the job log using a CL program, specify the fol-  
lowing:  
/ᑍ  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
PROGRAM: CLRCVMSG  
LANGUAGE: CL  
DESCRIPTION: THIS PROGRAM DEMONSTRATES HOW TO RECEIVE  
DIAGNOSTIC MESSAGES FROM THE JOB LOG  
APIs USED: QUSCRTUS  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
CLRCVMSG:  
PGM  
DCL  
DCL  
DCL  
VAR(&MSGDATA) TYPE(ᑍCHAR) LEN(8ð)  
VAR(&MSGID) TYPE(ᑍCHAR) LEN(7)  
VAR(&MSGLEN) TYPE(ᑍDEC) LEN(5 ð)  
MONMSG  
CALL  
MSGID(CPF3Cð1) EXEC(GOTO CMDLBL(GETDIAGS))  
PGM(QUSCRTUS) PARM('!BADNAME !BADLIB  
'!BADEXATTR' -1 '@' 'ᑍBADAUTH ' 'Text +  
Description')  
' +  
/ᑍ IF WE MAKE IT HERE, THE SPACE WAS CREATED OK  
GOTO CMDLBL(ALLDONE)  
ᑍ/  
/ᑍ IF THIS PART OF THE PROGRAM RECEIVES CONTROL, A CPF3Cð1  
/ᑍ WAS RECEIVED INDICATING THAT THE SPACE WAS NOT CREATED.  
ᑍ/  
ᑍ/  
/ᑍ THERE WILL BE ONE OR MORE DIAGNOSTICS THAT WE WILL RECEIVE ᑍ/  
/ᑍ TO DETERMINE WHAT WENT WRONG. FOR THIS EXAMPLE WE WILL  
/ᑍ JUST USE SNDPGMMSG TO SEND THE ID'S OF THE MESSAGES  
/ᑍ RECEIVED.  
ᑍ/  
ᑍ/  
ᑍ/  
GETDIAGS:  
RCVMSG  
PGMQ(ᑍSAME) MSGQ(ᑍPGMQ) MSGTYPE(ᑍDIAG) +  
WAIT(3) RMV(ᑍNO) MSGDTA(&MSGDATA) +  
MSGDTALEN(&MSGLEN) MSGID(&MSGID)  
COND(&MSGID = '  
CMDLBL(ALLDONE))  
CMD(DO)  
IF  
') THEN(GOTO +  
ELSE  
SNDPGMMSG MSG(&MSGID)  
GOTO  
ENDDO  
CMDLBL(GETDIAGS)  
2-10 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ALLDONE:  
ENDPGM  
As an alternative to using the job log, the following RPG program uses the error  
code structure to receive error messages:  
Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Hᑍ  
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
Hᑍ MODULE: ERRCODE  
Hᑍ  
Hᑍ LANGUAGE: RPG  
Hᑍ  
Hᑍ FUNCTION: THIS APPLICATION DEMONSTRATES THE USE OF THE  
Hᑍ  
Hᑍ  
ERROR CODE PARAMETER.  
Hᑍ APIs USED: QHFRTVAT, QHFCRTDR  
Hᑍ  
Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Hᑍ  
ᑍ
ᑍ
Hᑍ THIS PROGRAM DOES SOME SIMPLE VERIFICATION ON AN HFS  
Hᑍ DIRECTORY. THE QHFRTVAT API IS USED TO VERIFY THE EXISTENCE ᑍ  
Hᑍ OF THE SPECIFIED DIRECTORY. IF THE DIRECTORY DOES NOT EXIST, ᑍ  
Hᑍ AN ATTEMPT IS MADE TO CREATE THE DIRECTORY.  
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
Hᑍ  
Hᑍ THERE ARE THREE PARAMETERS TO THIS PROGRAM  
Hᑍ  
Hᑍ  
Hᑍ  
Hᑍ  
Hᑍ  
Hᑍ  
1
2
3
INPUT  
INPUT  
PATHNM - NAME OF DIRECTORY  
PATHLN - LENGTH OF PATHNM PARAMETER  
OUTPUT SUCCES - INDICATES SUCCESS OR FAILURE  
'ð' SUCCESS  
'1' FAILURE  
Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ISUCCES  
DS  
DS  
DS  
I
B
B
1
1
4ðRETCOD  
4ðPATHLN  
IPLENG  
I
IBINS  
I
I
B
B
1
5
4ðRETDTA  
8ðATTRLN  
IERROR  
DS  
I
I
I
I
I
C
C
C
C
Cᑍ  
B
B
1
5
4ðBYTPRV  
8ðBYTAVA  
9 15 ERRID  
16 16 ERR###  
17 272 INSDTA  
ᑍENTRY  
PLIST  
PARM  
PARM  
PARM  
PATHNM 8ð  
PLENG  
SUCCES  
Cᑍ INITIALIZE BYTES PROVIDED AND THE ATTRIBUTE LENGTH VARIABLE  
Cᑍ  
C
C
Cᑍ  
Z-ADD272  
Z-ADDð  
BYTPRV  
ATTRLN  
Cᑍ RETRIEVE DIRECTORY ENTRY ATTRIBUTES  
Cᑍ  
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL 'QHFRTVAT'  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PATHNM  
PATHLN  
ATTR  
ATTRLN  
ATTR  
ATTRLN  
RETDTA  
ERROR  
1
Cᑍ CHECK FOR DIRECTORY NOT FOUND OR FILE NOT FOUND ERRORS.  
Cᑍ IF WE RECEIVE ONE OF THESE THIS IS THE INDICATION THAT  
Cᑍ WE CAN TRY TO CREATE THE DIRECTORY.  
Cᑍ  
C
BYTAVA  
IFEQ ᑍZERO  
Chapter 2. Getting Started with APIs 2-11  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
C
C
C
Z-ADDð  
ELSE  
'CPF1Fð2' IFEQ ERRID  
'CPF1F22' OREQ ERRID  
RETCOD  
Cᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ THERE IS NO NEED TO REINITIALIZE THE ERROR CODE PARAMETER.  
Cᑍ ONLY BYTES PROVIDED IS INPUT TO THE API; IT WILL RESET THE  
Cᑍ ERROR CODE PARAMETER FOR US. AFTER THE CALL TO QHFCRTDR,  
Cᑍ BYTES AVAILABLE WILL EITHER BE ð IF SUCCESSFUL OR NONZERO  
Cᑍ IF THE CREATE FAILS. WE DO NOT HAVE TO WORRY ABOUT THE  
Cᑍ PREVIOUS ERROR CODE BEING LEFT IN THE ERROR CODE PARAMETER.  
Cᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
CALL 'QHFCRTDR'  
PARM  
PARM 2ð  
PARM  
PARM ð  
PARM  
IFEQ ᑍZERO  
Z-ADDð  
ELSE  
C
PATHNM  
PATHLN  
ATTR  
ATTRLN  
ERROR  
C
C
1
C
C
C
BYTAVA  
C
RETCOD  
RETCOD  
C
C
Z-ADD1  
END  
C
Cᑍ  
C
ELSE  
Z-ADD1  
END  
C
RETCOD  
C
C
Cᑍ  
END  
Cᑍ PROGRAM END  
Cᑍ  
C
SETON  
LR  
Related Information  
Ÿ “Retrieving the Hold Parameter (Exception Message)—OPM RPG Example” on  
page 3-6  
Ÿ “Error Handling” on page 4-5  
Ÿ The “API Error Reporting” topic in Chapter 2 of the System API Reference,  
SC41-5801  
Internal Identifiers  
You know of jobs, spooled files, and so forth, by their names. The system uses an  
ID that is associated with the name. The ID is assigned based on usage. Several  
of the APIs either require or allow you to use an internal ID. When you use an  
internal ID, it is generally faster because the system does not have to convert the  
external name to the internal ID.  
A variety of terminology is used to identify internal IDs. For example:  
Ÿ Work Management uses an internal job identifier.  
Ÿ Spooling uses an internal spooled file identifier.  
Ÿ Security uses the term handle to mean the user profile that is currently running  
the job.  
Ÿ Message handling uses the term message key (also appears on CL com-  
mands) to identify a message in a message queue.  
The internal values are often accessed in one API and then used in another. For  
example, if you want a list of jobs, you would use the List Jobs (QUSLJOB) API,  
which provides the internal job ID for each job in the list. You could then use the  
2-12 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
User Spaces  
internal job ID to access a spooled file for a job with the Retrieve Spooled File  
Attributes (QUSRSPLA) API.  
User Spaces  
APIs that return information to a caller generally return the information in a user  
space (used by list APIs) or a receiver variable (used by retrieve APIs).1  
The list APIs require a user space for returning information. A user space is an  
object type that is created by the Create User Space (QUSCRTUS) API. Gener-  
ally, a user space is used when information about more than one object is being  
requested.  
Following are some of the advantages of using user spaces:  
Ÿ User spaces can be automatically extendable.  
Ÿ User spaces can be shared across jobs.  
Ÿ User spaces can exist across IPLs.  
Most lists returned by APIs are made up of a series of entries where each entry is  
a data structure. Special fields are placed in the user space at consistent locations  
that describe:  
Ÿ Where the list begins.  
Ÿ The number of entries. The topic “Logic Flow of Processing a List of Entries”  
on page 2-15 shows the logic for processing a list of entries.  
Ÿ The length of each entry.  
User spaces are used for such functions as returning either a list of members in a  
file or objects in a library. When you use one of the list APIs, the parameter list  
requires that you name the user space that will be used.  
User spaces can be processed in two ways:  
Ÿ If your language supports pointers, you can access or change the information  
directly. Figure 2-2 on page 2-3 describes each supported language and  
whether it supports pointers. Generally, pointer access is faster than API  
access.  
Ÿ For languages that do not support pointers, you can use APIs to access or  
change the data in a user space. For example, the data in a user space can  
be accessed by the Retrieve User Space (QUSRTVUS) API. The API identifies  
a receiver variable that receives a number of bytes of information from the user  
space.  
You can pass the user space as a parameter to a program. You do need to use a  
language that has pointer support to be able to pass the address of the first byte of  
the user space as a parameter to the processing program. “Retrieving a File  
Description to a User Space—Examples” on page B-152 shows an example of  
pointer support.  
1
A user space is an object consisting of a collection of bytes that can be used for storing any user-defined information. A receiver  
variable is a program variable that is used as an output field to contain information that is returned from an API.  
Chapter 2. Getting Started with APIs 2-13  
Download from Www.Somanuals.com. All Manuals Search And Download.  
User Spaces  
User Space Format—Example  
Following is an example of the format of a user space. This example does not  
contain all of the fields in the fixed portion of a user space.  
User Space  
Fixed locations  
┌────────────────────────┐  
in the user space  
──────────────────  
│
│
│
│
│
│
│
│
│
│
│
│
│
XXXX ─────┼───5 Offset to data section  
│
XXXX ─────┼───5 Number of list entries  
│
XXXX ─────┼───5 Size of each entry  
│
│
│
2nd entry ───│─────────────────┐  
│
│
│
6
│ Variable locations in the  
│ user space  
│ ─────────────────────────  
1st entry ───│──┐  
│
6
│AAAAABBBBCCCDDDEEAAAABB │────5 List of entries  
│BBBCCCDDDEEAAAABBBBBCCD │  
│DDDEEAAAABBBBCCCDDDEE.. │  
└────────────────────────┘  
2-14 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
User Spaces  
Logic Flow of Processing a List of Entries  
When you process a list containing multiple entries, the logic flow looks as follows:  
┌────────────────────────┐  
│
│
│
│
│
Initialize the next │  
entry with 'Where │  
the list begins' │  
└────────────┬───────────┘  
│
6
┌────────────────────────┐  
│
│
│
Have all of the  
entries been  
processed?  
│ YES  
├───────┐  
┌───────5│  
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
└────────────┬───────────┘  
│
│NO  
6
List is  
complete  
┌────────────────────────┐  
│
│
│ Access the entry. Use │  
│ the next entry value │  
│ as an index.  
└───────────┬────────────┘  
│
│
6
┌────────────────────────┐  
│
│
│
│
Process  
the  
entry  
│
│
│
│
└────────────┬───────────┘  
│
6
┌────────────────────────┐  
│
│
│
│
Add the length of │  
each entry  
│
│
│ to the next entry  
└────────────┬───────────┘  
│
6
┌────────────────────────┐  
│ Add 1 to a count of │  
│
│
│
how many have  
been processed  
│
│
│
└────────────┬───────────┘  
│
│
└─────────────────────┘  
It is important from an upward compatibility viewpoint to use the offset, length of  
each entry, and the number of entries rather than hard coding the values in your  
program.  
Related Information  
Ÿ The User Space API chapter of the System API Reference, SC41-5801  
Ÿ The “User Space Format for List APIs” topic in Chapter 2 of the System API  
Reference, SC41-5801  
Chapter 2. Getting Started with APIs 2-15  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Manipulating a User Space with Pointers  
Manipulating a User Space with Pointers  
Some languages, such as ILE C', VisualAge C++ for OS/400, ILE COBOL, ILE  
RPG, COBOL, Pascal, and PL/I, support pointers. Pointers allow you to manipulate  
information more rapidly from the user space. To use pointers with the OS/400  
APIs, you should understand how to:  
Ÿ Synchronize between two or more jobs  
Ÿ Use offset values with pointers  
Ÿ Update usage data  
Synchronizing between Two or More Jobs  
If you are using the Change User Space (QUSCHGUS) or Retrieve User Space  
(QUSRTVUS) API to manipulate user spaces, you do not need to synchronize  
update and retrieve operations when multiple jobs access the user space. The  
APIs already do that for you. However, if you are using space pointers to retrieve  
the information directly from the user space, you should synchronize your applica-  
tion programs to avoid data errors. This ensures that no two users update the  
space at the same time, which can cause unpredictable results.  
Locks are typically used to synchronize two jobs on the system, and you can lock  
user spaces. To synchronize multiple jobs, you can use one of the following:  
Ÿ Compare and swap (CMPSWP MI instructions)  
Ÿ Space location locks (LOCKSL and UNLOCKSL MI instructions)  
Ÿ Object locks (LOCK and UNLOCK MI instructions)  
Ÿ Allocate Object (ALCOBJ) and Deallocate Object (DLCOBJ) commands  
The preceding list is ordered by relative performance where CMPSWP is the  
fastest. If you do not synchronize two or more jobs, multiple concurrent updates to  
the user space or read operations can occur while information is being updated.  
As a result, the data may not be accurate.  
Using Offset Values with Pointers  
When using a pointer to manipulate the user space, you must:  
1. Get a space pointer to the first byte (offset value of zero) of the user space.  
2. Retrieve the offset value of the information you want to use from the user  
space.  
3. Add that offset value to the space pointer value.  
4. Use the space pointer value to directly refer to the information in the user  
space.  
See “Changing a User Space with an ILE RPG Program—Example” on page 2-20  
for an example of this procedure.  
Updating Usage Data  
If you are using the Change User Space (QUSCHGUS) or Retrieve User Space  
(QUSRTVUS) API to manipulate user spaces, you do not need to update usage  
data information. If you directly retrieve data using pointers, your application pro-  
grams should update the usage data information. To do this, use the QUSCHGUS  
API to update the date last changed and use the QUSRTVUS API to update the  
date last retrieved. You do not need to do this for each retrieve or change opera-  
tion to the user space, but you should do this once within each application program  
to maintain accurate usage data information.  
2-16 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Manipulating a User Space without Pointers  
Manipulating a User Space without Pointers  
When programming in a language that does not support pointers, you can use the  
Change User Space (QUSCHGUS) and Retrieve User Space (QUSRTVUS) APIs  
to manipulate data. However, you must first understand how to use positions and  
lengths with these APIs.  
Position Values  
Some APIs return offset values into a user space. To use other APIs, such as the  
Retrieve User Space (QUSRTVUS) API, you must use position values to locate  
bytes.  
Position values and offset values are different ways to express the same thing. An  
offset value is the relative distance of a byte from the first byte of the user space,  
which has an offset value of 0. A position value is the offset value plus 1.  
For examples of HLL programs that use positions, see “List Object API—OPM RPG  
Example” on page 5-4.  
Lengths  
List APIs return the length of the information in the different sections of the user  
space, as well as the length of the list entries in the user space. You should code  
your application using the lengths returned instead of specifying the current length  
returned by the API or the size of a data structure in the data structure files. The  
amount of information returned for any format may increase in future releases, but  
the information will be placed at the end of the existing information. In order for  
your application to function properly, it should retrieve the length of the information  
returned and add that length to a pointer or to a starting position.  
Using Offset Values with the Change and Retrieve User Space  
APIs  
When you use the Change User Space (QUSCHGUS) or Retrieve User Space  
(QUSRTVUS) API, your application program should first retrieve the offset value for  
the information you want. You must then add one to the offset value to get the  
starting position for the information.  
Changing a User Space—Example  
Before and after illustrations show how the QUSCHGUS API changes a user  
space. The following is a user space before you change it with one of the change  
examples.  
Chapter 2. Getting Started with APIs 2-17  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Manipulating a User Space without Pointers  
Area that will change  
after using the  
Change User Space  
(QUSCHGUS) API  
RV3F089-0  
2-18 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Manipulating a User Space without Pointers  
The following is a user space after you change it with one of the change examples.  
Area changed  
after using the  
Change User Space  
(QUSCHGUS)  
RV3F088-0  
Chapter 2. Getting Started with APIs 2-19  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Manipulating a User Space without Pointers  
Changing a User Space with an ILE RPG Program—Example  
To change the user area of a user space as shown in the previous example with a  
call from an ILE RPG program, specify the following:  
Hᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Hᑍ  
Hᑍ PROGRAM: CHANGUSPTR  
Hᑍ  
Hᑍ LANGUAGE: ILE RPG for OS/4ðð  
Hᑍ  
Hᑍ DESCRIPTION: CHANGE THE CONTENTS OF INFORMATION IN THE USER  
Hᑍ  
Hᑍ  
AREA IN THE USER SPACE USING A POINTER  
Hᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
DUSRSPCNAM  
DNEWVALUE  
DUSRSPCPTR  
DUSERAREA  
D CHARFIELD  
Dᑍ  
S
2ð  
64  
INZ('TEMPSPACE QTEMP  
')  
S
INZ('Big String padded with blanks')  
S
DS  
ᑍ
BASED(USRSPCPTR)  
1
64  
Dᑍ Following QUSEC structure copied from QSYSINC library  
Dᑍ  
DQUSEC  
Dᑍ  
D QUSBPRV  
Dᑍ  
D QUSBAVL  
Dᑍ  
D QUSEI  
Dᑍ  
DS  
Qus EC  
1
5
4B ð  
8B ð  
Bytes Provided  
Bytes Available  
Exception Id  
Reserved  
9
15  
16  
D QUSERVED  
Dᑍ  
Dᑍ End of QSYSINC copy  
16  
Dᑍ  
Cᑍ  
Cᑍ Initialize Error code structure to return error ids  
Cᑍ  
C
Cᑍ  
Z-ADD  
16  
QUSBPRV  
Cᑍ Set USRSPCPTR to the address of the User Space  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
'QUSPTRUS'  
C
USRSPCNAM  
USRSPCPTR  
QUSEC  
C
C
Cᑍ  
Cᑍ Check for successful setting of pointer  
Cᑍ  
C
Cᑍ  
QUSBAVL  
IFGT  
ð
Cᑍ If an error, then display the error message id  
Cᑍ  
C
DSPLY  
ELSE  
QUSEI  
C
Cᑍ  
Cᑍ Otherwise, update the User Space via the based structure  
Cᑍ  
C
MOVEL  
END  
NEWVALUE  
USERAREA  
C
Cᑍ  
Cᑍ And return to our caller  
Cᑍ  
C
C
SETON  
LR  
RETURN  
2-20 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Manipulating a User Space without Pointers  
Changing a User Space with an OPM RPG Program—Example  
To change the user area of a user space with a call from an OPM RPG program,  
specify the following:  
Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Hᑍ  
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
Hᑍ PROGRAM: CHANGUS  
Hᑍ  
Hᑍ LANGUAGE: RPG  
Hᑍ  
Hᑍ DESCRIPTION: THIS PROGRAM WILL CHANGE THE CONTENTS OF  
Hᑍ  
Hᑍ  
Hᑍ  
INFORMATION IN THE USER AREA IN THE USER SPACE ᑍ  
(FIRST 64 BYTES).  
ᑍ
ᑍ
ᑍ
ᑍ
Hᑍ APIs USED: QUSCHGUS  
Hᑍ  
Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Hᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
E
ARY  
CHG  
1
1
1 2ð  
1 64  
E
IUSRSPC  
DS  
DS  
I
1 1ð USNAME  
11 2ð USLIB  
I
I
I
B
B
1
5
4ðLENDTA  
8ðSTRPOS  
I
Cᑍ  
ᑍ
Cᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
Cᑍ  
Cᑍ  
ᑍ
ᑍ
ᑍ
OPERABLE CODE STARTS HERE  
Cᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
ᑍ
Cᑍ MOVE THE USER SPACE AND LIBRARY NAME FROM ARY ARRAY INTO THE ᑍ  
Cᑍ USRSPC DATA STRUCTURE. ALSO, MOVE THE NEW USER DATA FROM  
ᑍ
ᑍ
ᑍ
Cᑍ CHG ARRAY INTO NEWVAL.  
Cᑍ  
C
C
MOVELARY,1  
MOVELCHG,1  
USRSPC  
NEWVAL 64  
Cᑍ  
C
ᑍ
LEN OF USERAREA  
STARTING POS  
FORCE PARM  
ᑍ
Z-ADD64  
Z-ADD1  
LENDTA  
STRPOS  
C
C
MOVE '1'  
FORCE  
1
Cᑍ  
Cᑍ CALL THE QUSCHGUS API WHICH WILL CHANGE THE USER AREA IN THE ᑍ  
Cᑍ USER SPACE.  
ᑍ
ᑍ
Cᑍ  
C
CALL 'QUSCHGUS'  
C
PARM  
PARM  
PARM  
PARM  
PARM  
USRSPC  
STRPOS  
LENDTA  
NEWVAL  
FORCE  
C
C
C
C
Cᑍ  
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
Cᑍ IF MORE OF THE USER SPACE NEEDS TO BE CHANGED, THIS PROGRAM  
Cᑍ COULD BE UPDATED TO LOOP UNTIL THE END OF THE ARRAY WAS  
Cᑍ REACHED.  
Cᑍ  
C
C
SETON  
RETRN  
LR  
ᑍᑍ ARY  
TEMPSPACE QGPL  
ᑍᑍ CHG  
Big String padded with blanks  
Chapter 2. Getting Started with APIs 2-21  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Additional Information about List APIs and a User Space  
Before you can use a list API to create a list, the *USRSPC object must exist.  
If the user space is too small to contain the list and you have *CHANGE authority  
to the user space, the list API extends the user space to the nearest page  
boundary. If the user space is too small and you do not have *CHANGE authority,  
an authority error results. An extended user space is not truncated when you run  
the API again.  
When you are creating a list into a user space and the user space cannot hold all  
of the available information (the list is greater than 16MB in length), the API places  
as much information as possible in the user space and sends a message (typically  
CPF3CAA) to the user of the API. The returned list contains only the number of  
entries that can fit inside the user space (not the total number of entries available).  
Listing Database File Members with a CL Program—Example  
To generate a list of members that start with M and are in file QCLSRC in library  
QGPL, specify the following:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ PROGRAM: LSTMBR2  
/ᑍ  
/ᑍ LANGUAGE: CL  
/ᑍ  
/ᑍ DESCRIPTION: THIS PROGRAM WILL GENERATE A LIST OF MEMBERS, ᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
THAT START WITH M, AND PLACE THE LIST INTO A  
USER SPACE NAMED EXAMPLE IN LIBRARY QGPL.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ APIs USED: QUSCRTUS, QUSLMBR  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
PGM  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
CREATE A ᑍUSRSPC OBJECT TO PUT THE LIST INFORMATION INTO. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
CALL QUSCRTUS  
+
('EXAMPLE  
'EXAMPLE  
X'ððððð12C'  
' '  
QGPL  
'
' /ᑍ USER SPACE NAME AND LIB  
/ᑍ EXTENDED ATTRIBUTE  
/ᑍ SIZE OF USER SPACE  
/ᑍ INITIALIZATION VALUE  
/ᑍ AUTHORITY  
ᑍ/ +  
ᑍ/ +  
ᑍ/ +  
ᑍ/ +  
ᑍ/ +  
'ᑍCHANGE  
'
'USER SPACE FOR QUSLMBR EXAMPLE  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
')  
/ᑍ  
/ᑍ  
/ᑍ  
LIST THE MEMBERS BEGINNING WITH "M" OF A FILE CALLED  
QCLSRC FROM LIBRARY QGPL USING THE OUTPUT FORMAT MBRLð2ðð. ᑍ/  
OVERRIDE PROCESSING SHOULD OCCUR. ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
CALL QUSLMBR  
+
('EXAMPLE  
'MBRLð2ðð'  
'QCLSRC  
'Mᑍ  
QGPL  
' /ᑍ USER SPACE NAME AND LIB  
/ᑍ FORMAT NAME  
ᑍ/ +  
ᑍ/ +  
QGPL  
'
' /ᑍ DATABASE FILE AND LIBRARY ᑍ/ +  
/ᑍ MEMBER NAME  
/ᑍ OVERRIDE PROCESSING  
ᑍ/ +  
ᑍ/  
'1')  
ENDPGM  
2-22 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Receiver Variables  
Some APIs use receiver variables to place returned information. For example,  
instead of using a user space to return the information, the information is placed in  
a receiver variable. A retrieve API requires only addressability to storage of fixed  
size (typically a field or structure defined in your program), whereas a list API  
requires a user space because the amount of information returned by a list API  
may be large and not of a predictable size.  
Retrieve APIs that return information to a receiver variable use the storage provided  
for the receiver variable parameter. The returned information is in a specific format.  
The format name is usually a parameter on the call to the API, and the format indi-  
cates to the API the information that you want returned. On the return from the call  
to the API, the caller parses through the receiver variable and extracts the informa-  
tion that is needed. The caller knows how the information is returned by the docu-  
mented format of the information. An API may have one or many formats that give  
you the flexibility to choose the information that you need. Chapter 3, “Common  
Information across APIs—Basic (OPM) Example” on page 3-1 contains several  
examples of using receiver variables.  
Some formats have variable-length fields, some only fixed-length fields, and yet  
others have repeating entries. To move through the information, some formats use  
offsets, some use lengths, and some use displacements. When the field is defined  
as an offset, the offset is always the number of bytes from the beginning of the  
receiver variable. When a length or displacement is used to move through the  
receiver variable entries, the length is always added to the current position within  
the receiver variable. For examples of repeating entry types and the various ways  
to move through receiver variable entries, see “Receiver Variables—Examples” on  
page 4-7.  
Offsets and displacements are not the same. An offset is relative to the beginning  
of a receiver variable or the beginning of a user space, whereas a displacement is  
relative to the current position of the pointer plus the value within the displacement  
field. If a format uses a displacement, you will see the word displacement in the  
Field column of the API description.  
Bytes Available and Bytes Returned Fields  
Most formats used by retrieve APIs have a bytes available field and a bytes  
returned field. The bytes available field contains the length in bytes of all the data  
available to be returned to the user. The bytes returned field contains the length in  
bytes of all the data that is actually returned to the user.  
All available data is returned if enough space is provided in the receiver variable. If  
the size of the receiver variable is at least large enough to contain all of the data,  
the bytes returned field equals the bytes available field. If the receiver variable is  
not large enough to contain all of the data, the bytes available field contains the  
number of bytes that can be returned.  
Your code could check the values for both the bytes available and bytes returned  
fields. If the bytes available field is greater than the bytes returned field, the API  
had more information to return than what would fit in the receiver variable. This  
could occur, over time, because the APIs that you use may be enhanced with new  
releases. The API may also have more information to return if the receiver variable  
is being used to return a variable-length field (or array) and a very large value was  
Chapter 2. Getting Started with APIs 2-23  
Download from Www.Somanuals.com. All Manuals Search And Download.  
returned on this API call. If both values are the same, the API returned all the  
information.  
Depending on the capabilities of your high-level language, some API users take  
advantage of the following technique to avoid guessing the appropriate size for the  
receiver variable:  
1. Call the API with a receiver variable length of 8 bytes (that is, just enough for  
the bytes available and the bytes returned fields).  
2. Dynamically allocate an amount of storage equivalent to the bytes available.  
3. Set the length of receiver variable parameter to the amount of storage allo-  
cated.  
4. Pass the address of the storage allocated in step 2 by using pass by value  
(directly).  
This technique provides for highly flexible use of APIs that can return variable  
amounts of data.  
Keyed Interface  
Some APIs have a keyed interface for selecting what information you want  
returned. A keyed interface allows the user of the API to provide information to  
the API through the use of keys. Keys are API-specific values that inform the API  
that a certain function should be performed. Keys also are used to pass informa-  
tion to an API or to retrieve information from an API.  
Through the use of keys, you can be more selective; you can choose one item or a  
number of items rather than all of them. For example, using the List Job  
(QUSLJOB) API, you can receive selected information about a job based on the  
keys that you specify. If you want job information about the output queue priority,  
you only need to specify the output queue priority key.  
The keys are typically supplied to an API and are passed to the API using a  
variable-length record (there are some exceptions). A variable-length record is a  
collection of information that specifies the key being used and the data that is asso-  
ciated with the key. If a given structure contains binary values, it must be 4-byte  
aligned. “Defining Byte Alignment” on page 9-22 shows examples of correctly and  
incorrectly defining byte alignment.  
Some APIs that use variable-length records in addition to the List Job API are the  
Change Object Description (QLICOBJD) API and the Register Exit Point  
(QUSRGPT, QusRegisterExitPoint) API. You can use the appropriate include file in  
member QUS in the system include (QSYSINC) library when you have variable-  
length records as either input or output.  
A keyed interface provides an easy-to-use means for later enhancing an API  
without affecting the user who chooses not to use the enhancements. For exam-  
ples that use a keyed interface, see “Using Keys with List Spooled Files  
API—Example” on page 3-24 (OPM RPG) and “Keyed Interface—Example” on  
page 4-3 (ILE C).  
2-24 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
User Space Alternative  
Although a receiver variable is usually used for returning information from a retrieve  
API, sometimes a user space should be used instead. If the number of bytes of  
information being returned is not known or is large, a user space is preferred. You  
can create a user space so that it can automatically extend up to 16MB of storage  
to accommodate the information being retrieved.  
The disadvantage of using a receiver variable when it may be too small for the  
amount of data being returned is that the API must be called again to receive the  
remaining data.  
For an example of using a user space to return information from a retrieve API, see  
“Retrieving a File Description to a User Space—ILE C Example” on page A-11.  
Related Information  
Ÿ For a discussion of variable-length structures using ILE C, see “Variable-Length  
Structure—Example” on page 4-3.  
Ÿ For an example using the Register Exit Point (QusRegisterExitPoint) API, see  
“Register Exit Point and Add Exit Program—ILE C Example” on page 4-9.  
Ÿ For an example using the Change Object Description (QLICOBJD) API in RPG,  
see “Program for Packaging a Product—OPM RPG Example” on page A-3.  
The change object information parameter is defined as the COBJI field, and  
this field is later used by the QLICOBJD API.  
Ÿ For a discussion of include files, see “APIs and the QSYSINC Library” on  
page 2-28.  
Continuation Handle  
Some APIs that return information offer a continuation handle. A continuation  
handle is a value that is passed between a high-level language program and an  
API. It is used to mark the last value put in either the receiver variable or the user  
space. When a call to an API is made and the API has more information to return  
than what could fit in the receiver variable or user space provided by the caller, the  
API returns a continuation handle. If a continuation handle is returned to the caller  
because there is more information to return, the caller can then call the API again  
and pass the continuation handle that was returned. The API continues to return  
information from the point that it left off on the call that generated the continuation  
handle.  
When you use the continuation handle parameter, that is the only parameter that  
can change. All other parameters must appear as they did on the call to the API  
that generated the continuation handle to obtain predictable results.  
Using a Continuation Handle  
To make use of a continuation handle, do the following:  
1. Blank out the continuation handle to let the API know that this is a first attempt  
at the retrieve operation.  
2. Call the API to retrieve the information.  
3. Make use of the information returned.  
Chapter 2. Getting Started with APIs 2-25  
Download from Www.Somanuals.com. All Manuals Search And Download.  
4. If the continuation handle field in the receiver variable is not set to blanks, do  
the following steps until the continuation handle equals blanks:  
a. Copy the continuation handle from the receiver variable to the continuation  
handle parameter.  
b. Call the API again by using the continuation handle that is returned. Keep  
all other parameters the same as the original API call.  
For a program example that uses a continuation handle, see “Retrieve Exit Point  
and Exit Program Information—ILE C Example” on page 4-13.  
Domain Concepts  
All objects are assigned a domain attribute when they are created. A domain is a  
characteristic of an object that controls how programs can access the object. Once  
set, the domain remains in effect for the life of the object. The two possible attri-  
butes are system and user.  
Most object types on the system are created in system domain. When you run  
your system at security level 40 or 50, system domain objects can be accessed  
only by using the commands and callable APIs provided.  
These object types can be either system or user domain. The list includes the  
symbolic object type.  
Ÿ User space (*USRSPC)  
Ÿ User index (*USRIDX)  
Ÿ User queue (*USRQ)  
Objects of the type *USRSPC, *USRIDX, and *USRQ in the user domain can be  
manipulated directly by MI instructions without using the system-provided APIs and  
commands.  
Note: Objects of the type *PGM, *SRVPGM, and *SQLPKG also can be in the  
user domain. Their contents cannot be manipulated directly by MI  
instructions.  
Prior to Version 2 Release 3 Modification 0, all user objects were created into the  
user domain. Starting in Version 2 Release 3 Modification 0, user objects can exist  
in either the user domain or the system domain. The allow user domain  
(QALWUSRDMN) system value determines which libraries can contain user-domain  
user objects. The default QALWUSRDMN system value is set to *ALL, but can be  
changed by system administrators on individual machines to be one library or a list  
of libraries. If your application requires direct pointer access to user-domain user  
objects in a library that is not specified in the QALWUSRDMN value, your system  
administrator can add the library to the system value.  
The ability to create user domain objects on a system with a security level 40 or 50  
is controlled by the allow user domain (QALWUSRDMN) system value. See the  
table in the description of the Create User Queue (QUSCRTUQ) API in the System  
API Reference for more information.  
2-26 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Note: On a system configured for C22 system security, QALWUSRDMN is set to  
QTEMP (only the QTEMP library can contain user-domain user objects).  
For more information about C2 security, refer to the Guide to Enabling C2  
Security book, SC41-0103.  
Related Information  
Ÿ “Using Data Queues versus User Queues” on page A-15  
Ÿ Create User Index (QUSCRTUI), Create User Queue (QUSCRTUQ), and  
Create User Space (QUSCRTUS) APIs in the Object part of the System API  
Reference, SC41-5801  
Ÿ Chapter 2 of the Security – Reference, SC41-5302  
Exit Programs  
Exit programs are called and given control by an application program or system  
program. They can be used to customize particular functions to your needs. An  
exit program is a program to which control is passed from a calling program.  
Exit programs are usually user-written programs; however, a few are system-  
supplied (such as a few of the Operational Assistant exit programs).  
To transfer control to an exit program, you do an external call as you would to any  
other program.  
There are no general requirements for using exit programs. For any specific  
requirements, see the documentation for the specific exit program.  
Exit Points  
An exit point signifies the point in a system function or program where control is  
turned over to one or more exit programs to perform a function.  
Prior to Version 3 Release 1, the exit program might have been represented as  
network attributes, system values, CL command parameters, or attributes of system  
objects. Also, in previous releases, all exit point providers had to supply their own  
means of registering and deregistering exit programs.  
The registration facility provides a central point to store and retrieve information  
about OS/400 and non-OS/400 exit points and their associated exit programs. This  
information is stored in the registration facility repository and can be retrieved to  
determine which exit points and exit programs already exist.  
You can use the registration facility APIs to register and deregister exit points, to  
add and remove exit programs, and to retrieve information about exit points and  
exit programs. You can also perform some of these functions by using the Work  
with Registration Information (WRKREGINF) command.  
2
C2 is a level of security defined in the Trusted Computer System Evaluation Criteria (TCSEC) published by the United States  
Government.  
Chapter 2. Getting Started with APIs 2-27  
Download from Www.Somanuals.com. All Manuals Search And Download.  
The exit point provider is responsible for defining the exit point information,  
defining the format in which the exit program receives data, and calling the exit  
program.  
Related Information  
Ÿ For more information about the registration facility, see the Registration Facility  
part in the System API Reference, SC41-5801.  
Ÿ For an example of adding an exit program to an exit point, see the topic “Reg-  
ister Exit Point and Add Exit Program—ILE C Example” on page 4-9.  
Ÿ For an example of calling an exit program to retrieve information in the registra-  
tion facility repository, see the topic “Retrieve Exit Point and Exit Program  
Information—ILE C Example” on page 4-13.  
APIs and the QSYSINC Library  
The QSYSINC (system include) library provides source include files shipped with  
the AS/400 system for OS/400 APIs. This optionally installable library is fully sup-  
ported, which means that you can write APARs if you find a problem.  
You can install this library by using the GO LICPGM functions of OS/400. Select  
the Install Licensed Programs option on the Work with Licensed Programs display  
and the OS/400 - Openness Includes option on the Install Licensed Programs  
display.  
The terms include file and header file are interchangeable and pertain to the con-  
tents of the QSYSINC library. These files are intended to be compatible with future  
releases.  
The naming conventions for the include files are the same as either the OPM API  
name or the ILE service program name. If the API has a callable and a bindable  
interface, an include file exists with both names.  
The following table shows the API include files that are shipped with the QSYSINC  
library:  
Figure 2-5 (Page 1 of 2). Include Files Shipped with the QSYSINC Library  
Operating  
Language  
File Name  
Member Name (Header File)  
Environment  
OPM APIs  
ILE C1  
RPG  
H
OPM API program name  
QRPGSRC  
OPM API program name or OPM  
API program name with the letter  
E replacing the letter Q for  
members containing array defi-  
nitions  
ILE RPG  
COBOL  
QRPGLESRC  
QLBLSRC  
OPM API program name  
OPM API name  
ILE COBOL  
QCBLLESRC  
OPM API program name  
2-28 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Figure 2-5 (Page 2 of 2). Include Files Shipped with the QSYSINC Library  
Operating  
Language  
File Name  
Member Name (Header File)  
Environment  
ILE APIs  
ILE C  
H
Service program name or API  
program name2  
ILE RPG  
ILE COBOL  
QRPGLESRC  
QCBLLESRC  
Service program name or API  
program name2  
Service program name or API  
program name2  
UNIX type  
ILE C  
ILE C  
ILE C  
ILE C  
ILE C  
ARPA  
H
Industry defined  
Industry defined  
Industry defined  
Industry defined  
Industry defined  
NET  
NETINET  
SYS  
Notes:  
1
CEE ILE APIs are included in this part of the table.  
2
The API can be either bindable when you use the service program name or callable  
when you use the API program name.  
For development of client-based applications, the integrated-file-system symbolic  
links to QSYSINC openness includes are provided in the /QIBM/include path.  
Include files for exit programs are shipped only if the exit program has a structure.  
The member names for these exit programs start with the letter E. Except for RPG  
array definitions for APIs that also start with E, any member names in the  
QSYSINC library that start with the letter E are include files for exit programs.  
Refer to the System API Reference for the actual member names for the exit pro-  
grams.  
All source physical files are shipped with read capabilities only; changes cannot be  
made to the QSYSINC library. All are built with a CCSID of 00037. When you  
compile a program in a specific CCSID, any QSYSINC include file is converted to  
the program CCSID.  
If you are coding in ILE C, the header files in the QSYSINC library are considered  
system include files. You should use the < and > symbols on the #include state-  
ment; this affects how the library list is used to search for header files.  
If you are coding in RPG or COBOL and need to define storage for variable length  
fields, you should copy the appropriate QSYSINC system include to a user source  
library. You can then customize the include file to your specific needs and use the  
customized member when you compile your application.  
If you are developing applications on a release n system that will run on a  
release n-1 system, you may want to copy each release's include files to user  
source libraries. This will minimize the impact of include file changes as APIs are  
enhanced over time with additional fields.  
Chapter 2. Getting Started with APIs 2-29  
Download from Www.Somanuals.com. All Manuals Search And Download.  
User Index Considerations  
Related Information  
Ÿ Chapter 2 in the System API Reference, SC41-5801  
APIs and the QUSRTOOL Library  
QUSRTOOL, an optionally installable library, has several tools that use APIs and  
include files (header files) for APIs. You can use the code as a model for your  
programming. As of Version 3 Release 6, source include files will be removed from  
this library. APARs against the offerings in QUSRTOOL are not allowed. There is  
no support for enhancements or fixes to the contents of the library other than a  
complete reshipment that occurs with each release. If you intend to use the tools,  
you should copy the members that you plan to use to your own source libraries.  
User Index Considerations  
The performance of a user index is much better than that of a database file.  
However, before using a user index, you must know the functional differences  
between a user index and a database file.  
The contents of a database file are not affected by an abnormal system end. On  
the other hand, the contents of a user index may become totally unusable if the  
system ends abnormally. Therefore, you should not use a user index if the infor-  
mation you want to store needs to remain without errors after an abnormal system  
end.  
If your system abnormally ends when you are removing or inserting a user index  
entry, unpredictable results may occur. If you are inserting or removing a user  
index entry and you do not force the index entry to the disk unit using one of the  
following:  
Ÿ A user index created with the immediate update parameter set to 1 (affects  
performance)  
Ÿ A modify index (MODIDX) MI instruction with the immediate update bit set to 1  
Ÿ The set access state (SETACST) MI instruction  
and the system abnormally ends, your index is probably damaged.  
To determine if your last system power down was normal or abnormal, you can  
check the system value QABNORMSW.  
You will not get an error message if your index is damaged. The definition of your  
index is usable; it is probably the data in your index that is bad.  
You can log changes to a database file in a journal, and you can use the journal to  
apply or remove those changes later. You can also use the journal to audit who is  
using the database file. However, the system does not support the journaling of  
indexes. As a result, user applications should log entries in a journal to keep track  
of changes to the index, but you cannot update the index using apply and remove  
journal entry functions. For more information on journaling, see the Journal and  
Commit APIs in the System API Reference book, SC41-5801.  
Indexes support the storage of data that does not need to remain after an abnormal  
system end. If an abnormal system end does occur, you must use a backup copy  
of the index that was previously saved or create a new copy of the index.  
2-30 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Performance Considerations  
APIs and Internal System Objects  
APIs retrieve information from internal system objects. Some of the information  
contains special values. For example, the list object API returns the object type as  
a special value (*PGM, *LIB, and so on). However, special values may be added  
in future releases. Even numeric values may have new special values. When you  
code to APIs, you should assume that the format of the information returned will not  
change from release to release, but the content of the information might change.  
Performance Considerations  
The retrieve APIs allow you to control the performance cost for information you  
retrieve. The format specified for any API influences the performance cost of the  
API. In general, when more information is returned, the performance is slower.  
Some list APIs, such as list jobs, list spooled files, and list objects, generate the list  
with minimal cost. This is why these formats do not retrieve very much information.  
Some of the APIs, such as list record formats and list fields, have only one format,  
because there is no additional performance cost to supply the complete information.  
The retrieve APIs, such as retrieve member description and retrieve spooled file  
attributes, have formats that are generally ordered from fastest performance to  
slowest performance. That is, the lower numbered formats run faster but retrieve  
less information, and the higher numbered formats run slower but retrieve more  
information. One exception is the Retrieve Job Information (QUSRJOBI) API where  
the order of the formats does not have anything to do with performance character-  
istics. For more information about the performance characteristics for the  
QUSRJOBI API formats, see the Retrieve Job Information (QUSRJOBI) API in the  
Work Management part of the System API Reference book.  
Chapter 2. Getting Started with APIs 2-31  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Performance Considerations  
2-32 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Chapter 3. Common Information across APIs—Basic (OPM)  
Example  
Through the use of several examples, this chapter provides information about how  
to use original program model (OPM) APIs in your programs. The primary example  
programs in this chapter are also shown in additional languages in “Original  
Program Model (OPM) APIs—Examples” on page B-2.  
In the examples, the following are focus items:  
Ÿ Description of an API by section  
Ÿ Fixed-length formats  
Ÿ Variable-length fields as output  
Ÿ Optional parameters  
The Retrieve Job Description Information (QWDRJOBD) API is used as the founda-  
tion for the examples in this chapter. The QWDRJOBD API has been included in  
“Retrieve Job Description Information API—Example” on page 3-29 for your use, if  
you would like to refer to it as you read this chapter.  
For details on the OS/400 APIs, refer to the System API Reference, SC41-5801.  
Original Program Model (OPM) API–Scenario  
In this chapter, accessing information from a job description is used to demonstrate  
how to code APIs. While this may not be what your application requires, you can  
use the same approach to access information when you use most of the APIs.  
Assume that you are interested in accessing the value of the hold parameter on the  
Retrieve Job Description (RTVJOBD) command. The hold parameter determines  
whether the job is held on the job queue. Two values are supported:  
*NO  
The job is not held.  
*YES  
The job is held on the job queue.  
Finding the API Name to Use  
A first step in finding the correct API is to identify the part of the OS/400 program  
that is most closely related to the function in which you are interested.  
If you want to access information from a job description, for example, you have to  
know that a job description object is considered part of the work management func-  
tion. Next, you would turn to that chapter of the System API Reference.  
Within each chapter of the System API Reference, the APIs are listed in alphabet-  
ical order by the spelled-out form of the API name. The API names contain verbs  
that are similar to the OS/400 licensed program: change, create, remove, and  
retrieve. Other verbs, such as list and set, you may not be familiar with. For more  
information on verbs, see Figure 2-1 on page 2-2. If you want to access informa-  
tion from a job description, the verb retrieve is a good place to start.  
Retrieve functions are available for several work management objects, such as data  
areas, job descriptions, and job queues. Retrieve functions are also available for  
Copyright IBM Corp. 1997  
3-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
nonobject information that represents data known to the system, such as job infor-  
mation or system status.  
Description of an API  
Most APIs have similar topic headings. The following lists the API topic headings,  
each with an overview and details on how to use the information.  
Parameters  
The Parameters box describes how to call the API. The first column in the Param-  
eters box lists the required order of the parameters. The second column lists each  
parameter used on the call.  
The third column lists whether the parameter is defined for input, output, or input  
and output. Input parameters and fields are not changed by the API. They have  
the same value on the return from the API call as they do before the API call. In  
contrast, output parameters are changed. Any information that an API caller places  
in an output parameter or output field before the call to the API could be lost on the  
return from the call to the API.  
In the fourth column of the Parameters box is the type of data defined for the  
parameter. CHAR(*) represents a data type that is not known, such as character,  
binary, and so on, or a length that is not known. Binary(x) represents x bytes of a  
binary value. CHAR(x) represents x bytes of character data. When calling the  
QWDRJOBD API, for example, there is an 8-byte character format name, a 4-byte  
binary value named length of receiver variable, and a variable-length receiver vari-  
able. The receiver variable is a structure made up of several character and binary  
fields. For more information on format names, see “Format Name” on page 3-4.  
RPG Call Statement—Parameter Example: In this example program, you must  
pass 5 parameters to use the API. For example, your RPG CALL statement might  
look like the following:  
C
C
C
C
C
C
CALL 'QWDRJOBD'  
PARM  
PARM  
PARM  
PARM  
PARM  
QWDBH  
RCVLEN  
FORMAT  
LFNAM  
QUSBN  
Receiver Var.  
Length QWDBH  
Format Name  
Qual. Job Desc  
Error Code  
Note: There is no parameter for the HOLD information. The first parameter,  
receiver variable (QWDBH), is where the information is passed back from  
the job description API. You will receive a data structure that contains infor-  
mation, and you will need to find the specific location within the data struc-  
ture for where the HOLD information is stored.  
Authorities and Locks  
The Authorities and Locks topic lists all the authorities that you need to use the  
API. This topic also lists the locks that the API uses. To use an API, you must  
have the correct authority to the following:  
Ÿ The API itself  
Ÿ All the objects that the API uses  
Ÿ Any locks that the API places on any objects  
3-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Locks are based on the objects that the API uses. The type of locking that occurs,  
such as whether the object can be used by more than one user at the same time,  
is based on what actions the API performs on the object.  
For the QWDRJOBD API, you must have *USE authority to both the job description  
object and the library to access the object. This is the same type of authority that  
is required for most situations where you want to display or retrieve information in  
an object. For example, it is the same authority that you would need to use the  
Display Job Description (DSPJOBD) command. Because no specific information is  
described for locks, you can assume that nothing unusual is required.  
Required Parameter Group  
The Required Parameter Group topic of an API lists all the parameters required for  
that API. You must use all of the parameters in the order that they are listed.  
None of the parameters may be left out.  
The details of each parameter that must be used on the call to the QWDRJOBD  
API are described in “Required Parameter Group” on page 3-30.  
Receiver Variable: A receiver variable is the name of the variable (QWDBH in the  
example RPG program in “Parameters” on page 3-2) where the information will be  
placed. You need to declare the length of the receiver variable based on what you  
want from the format. The include file QWDRJOBD contains the definition for the  
receiver variable structure depending on the value used for the format name. For  
more information on the format, see the table in “JOBD0100 Format” on page 3-30.  
You can see from the Dec (decimal offset) column of the JOBD0100 format table  
(.1/ on page 3-31) that at least 390 bytes plus additional bytes (of unknown length)  
for the initial library list and the request data are returned. “Accessing a Field  
Value (Initial Library List)—OPM RPG Example” on page 3-19 describes how to  
determine the lengths of these fields. For now, you should focus on the fixed  
portion (390 bytes) of the format.  
You have a choice of receiving the maximum or enough bytes to contain the infor-  
mation in which you are interested. Because the value of the hold on job queue  
field starts at decimal 76, you could specify that the receiver variable is 100 bytes  
(or any number greater than or equal to 86 bytes). It is not necessary to be precise  
when you specify the length of the receiver variable. Whatever you specify is the  
amount of data that is returned. You can truncate a value in the middle of a field in  
the format, specify more length than the format has, and so on.  
For example, assume that you decided to receive the fixed information, a length of  
390 (.2/ on page 3-7). If you are going to call the API once, no measurable perfor-  
mance gain occurs if you specify anything less than the maximum. When defining  
the length of your receiver variable, you would usually use the length of the infor-  
mation that you want to receive. The length of receiver variable parameter must be  
set to a value equal to or less than the length that you defined the receiver variable  
parameter to be.  
Length of Receiver Variable: You normally enter the length that you have speci-  
fied for the receiver variable. Remember that in this example, you decided to  
declare the receiver variable to be 390 bytes in length. The length of receiver vari-  
able parameter will have a value of 390 assigned to it (.3/ on page 3-7). You  
could have specified a different value, but the value must be the same or less than  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
the size of the variable in your program. In the example program in “RPG Call  
Statement—Parameter Example” on page 3-2, RCVLEN is the length of receiver  
variable parameter.  
The length field, according to the required parameter group, must be described as  
BINARY(4). This means that a field of 4 bytes is passed where the value is speci-  
fied in binary. You need to know how your high-level language allows you to define  
a 4-byte field and place a binary value in it. The API does not care if the field is  
declared as a binary type. For example, some languages, like control language  
(CL), do not have a binary type. What is important is that the field is 4 bytes in  
length and that it contains the receiver length in binary.  
If you write programs in CL, you need the %BIN function to convert a decimal value  
or variable to a character field that is declared as 4 bytes. If you write programs in  
RPG, you can declare a data structure that contains a 4-byte field of zero decimals  
and is defined as B for binary (.4/ on page 3-7). Because the field is a binary  
type, RPG would make a binary value.  
Format Name: A format name is a name that identifies what type of information  
you want returned in the receiver variable. Because this API has a single format  
name, JOBD0100, you would use the format name given (.5/ on page 3-7) in the  
Retrieve Job Description Information API. The format name variable in the  
example program is called FORMAT. You can place the format name in a variable  
or pass it as a literal.  
Qualified Job Description Name: This name must be passed as a 20-character  
name with the job description name in the first 10 characters and the library qual-  
ifier beginning in the 11th character. If you want JOBD1 in LIBX, you would  
specify:  
1
11  
.
2ð  
.
.
.
.
.
JOBD1  
LIBX  
The special values of *CURLIB or *LIBL can be used as the library qualifier.  
Note: APIs generally do not convert parameter values to uppercase. When using  
object names (like job description and library), you must provide the name  
in uppercase.  
Error Code: This parameter allows you to select how errors are to be handled.  
The include file QUSEC contains the definition for the error code structure that is  
used for the error code parameter.  
You can choose to receive exceptions (escape messages) or to receive an error-  
code data structure that allows you to determine if an exception occurred.  
Depending on your high-level language, you may not have a choice for which  
method you use. You may have to use the error-code data structure because  
some languages do not provide for escape messages.  
In the example in “Retrieving the Hold Parameter (Exception Message)—OPM RPG  
Example” on page 3-6, the RPG program requests that exceptions be sent if any  
errors occur. To provide for this type of exception handling, a 4-byte binary field  
3-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
with a value of zero (.6/ on page 3-7) must be passed. This indicates to the API  
that you want exception messages sent.  
Optional Parameter Group  
Some of the APIs have optional parameters; the optional parameters form a group.  
You must either include or exclude the entire group. You cannot use one of these  
parameters by itself. You must include all preceding parameters.  
The API can be called two ways: either with the optional parameters or without the  
optional parameters.  
The Retrieve Job Description Information API has no optional parameter groups.  
The List Job (QUSLJOB) API is an example of an API with an optional parameter  
group.  
Format  
The Format topic describes a format name, which for the Retrieve Job Description  
(QWDRJOBD) API is JOBD0100. Listed within the format are the individual fields  
that contain the attributes of the job description. The offset in the Dec (decimal  
offset) column for the hold on job queue field (hold parameter on the Retrieve Job  
Description command) begins at decimal offset 76. For more information on this  
format, see “JOBD0100 Format” on page 3-30.  
The fields in the format do not occur in any particular sequence. You have to scan  
the format to determine what you want.  
This API has only a single format; other APIs may have multiple formats where  
each format has different levels of information. With multiple formats, a format  
name parameter allows you to specify which format you want to retrieve.  
Field Descriptions  
The Field Descriptions topic describes the fields found in the format. The contents  
of the format are presented in alphabetical sequence and not in the sequence of  
the fields defined in the format. In the Retrieve Job Description Information API  
example, you can find the description of the hold on job queue field. The field does  
not use the parameter name found on the Create Job Description (CRTJOBD)  
command.  
Error Messages  
The Error Messages topic lists error messages that can occur when you use the  
API. These are message IDs that normally exist in the QCPFMSG file. You may  
want to program for these messages regardless of the high-level language that you  
are using. If you need more detail about the messages, use the Display Message  
Description (DSPMSGD) command.  
Extracting a Field from the Format  
The format describes where the field that you want is located within the receiver  
variable. An offset is shown in both decimal and hexadecimal. Depending on  
which language you use, either offset may be helpful. For CL and RPG, you would  
normally use the decimal offset. With any offset, it is important to remember  
whether your language works with an offset from a base of 0 or a base of 1. The  
format tables in the System API Reference are prepared for languages that work  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-5  
Download from Www.Somanuals.com. All Manuals Search And Download.  
from a base of 0, but not all languages can use this base. CL and RPG, for  
example, work from a base of 1, so you need to add 1 to the decimal value of each  
offset. The hold on job queue field begins at decimal offset 76, for example. To  
access the information in CL or RPG, you need to address byte 77 within the  
receiver variable.  
Using the format, you can tell that the field after the hold on job queue field, output  
queue name, begins in offset 86. This means that the hold on job queue informa-  
tion is in the following location from a CL or RPG perspective:  
77  
.
86  
.
.
.
XXXXXXXXXX  
The only possible values for the hold on job queue field are *YES and *NO. They  
are left-justified in the field and the remaining positions are blank.  
Most of the formats provide additional bytes for each field to allow for expansion,  
such as a new value for the hold on job queue field that would be more than 4  
bytes.  
Many of the needed structures are provided by the system-include library,  
QSYSINC. However, any fields of a structure that are variable in length are not  
defined by QSYSINC. These variable-length fields must be defined by the user, as  
shown by .7/ on page 3-20. For more information on the QSYSINC library, see  
“APIs and the QSYSINC Library” on page 2-28.  
Retrieving the Hold Parameter (Exception Message)—OPM RPG  
Example  
In the following program example, all the pieces have been put together with an  
RPG program that accesses the hold on job queue information from a job  
description. A message is sent for the value found. To make the RPG program  
more general purpose, two parameters for the job description (JOBD) name and  
library (JOBDL) name are passed to it .8/ (refer to page 3-7). The program  
example, which is named JOBDAPI (this program name is also used in other exam-  
ples in this chapter), does not handle errors. Any errors that are received are  
returned as exception messages.  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍProgram Name: JOBDAPI  
Iᑍ  
IᑍLanguage: OPM RPG  
Iᑍ  
IᑍDescriptive Name: Job Description  
Iᑍ  
IᑍDescription: This example expects errors to be sent as escape  
Iᑍ  
Iᑍ  
messages.  
IᑍHeader Files Included: QUSEC - Error Code Parameter  
Iᑍ  
Iᑍ  
QWDRJOBD - Retrieve Job Description API  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
Iᑍ Error Code Parameter Include for the APIs  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSEC  
3-6 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ  
Iᑍ Retrieve Job Description API Include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QWDRJOBD.2/  
Iᑍ  
Iᑍ Command String Data Structure  
Iᑍ  
ICMDSTR  
DS  
I I  
I
I
I I  
Iᑍ  
'SNDMSG MSG(''HOLD -  
'value is '  
1 26 CMD1  
27 36 HOLD  
37 51 CMD2  
''') TOUSR(QPGMR)'  
Iᑍ Miscellaneous Data Structure  
Iᑍ  
I
DS  
Iᑍ  
I I  
I I  
Iᑍ  
Cᑍ  
.3/  
39ð  
.4/  
B
1
4ðRCVLEN  
'JOBDð1ðð'  
5 12 FORMAT  
.5/  
Cᑍ Beginning of Mainline  
Cᑍ  
Cᑍ Two parameters are being passed into this program.  
Cᑍ  
C
ᑍENTRY  
PLIST .8/  
PARM  
PARM  
C
JOBD  
1ð  
C
Cᑍ  
JOBDL 1ð  
Cᑍ Move the two parameters passed into LFNAM.  
Cᑍ  
C
JOBD  
CAT JOBDL  
LFNAM 2ð .9/  
Cᑍ Error code bytes provided is set to ð  
Cᑍ  
C
Z-ADDð  
QUSBNB .6/  
Cᑍ  
Cᑍ Instead of specifying 'QWCRJOBD', I could have used the  
Cᑍ constant QWDBGB that was defined in the QWDRJOBD include.  
Cᑍ  
C
CALL 'QWDRJOBD'  
C
PARM  
PARM  
PARM  
PARM  
PARM  
QWDBH  
RCVLEN  
FORMAT  
LFNAM  
QUSBN  
Receiver Var.  
Length RCVVAR  
Format Name  
Qual. Job Desc  
Error Code  
C
C
C
C
Cᑍ  
C
Cᑍ  
MOVELQWDBHN  
HOLD  
Cᑍ Let's tell everyone what the hold value was for this jobd.  
Cᑍ  
C
Z-ADD51  
CALL 'QCMDEXC'  
PARM  
LENSTR 155  
C
C
C
Cᑍ  
C
C
Cᑍ  
CMDSTR  
LENSTR  
PARM  
SETON  
RETRN  
LR  
Cᑍ End of MAINLINE  
Cᑍ  
The program declares the variables to be used. The QWDBH variable is length  
390 as shown by .3/ on page 3-7.  
In the example, the program places a value of JOBD0100 in the format variable. A  
literal could have been used instead for those languages that support a literal on a  
call .5/. (For program examples in other languages, see “Original Program Model  
(OPM) APIs—Examples” on page B-2.) The program generates the qualified name  
of the job description (JOBD) by concatenating the simple name and the library  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-7  
Download from Www.Somanuals.com. All Manuals Search And Download.  
qualifier .9/. A 20-character variable must be used, and the simple name must  
begin in byte 1 with the library qualifier in byte 11. Because CAT is used, a simple  
concatenation of two 10-byte variables occurs so that the names are in the correct  
place for the LFNAM parameter.  
The QWDRJOBD API is called with the correct parameter list. The API uses the  
parameter list and accesses the job description specified. The API extracts the  
values from the internal object form and places them in a data structure that  
matches the JOBD0100 format. The API then returns with the data structure  
placed in variable QWDBH, which is located in member QWDRJOBD in the  
QSYSINC library.  
The output is similar to the following:  
à
ð
Display Messages  
System:  
GENSYS9ð  
ᑍDSPMSG  
Queue . . . . . :  
Library . . . :  
Severity . . . :  
QPGMR  
QUSRSYS  
Program . . . . :  
Library . . . :  
Delivery . . . :  
ðð  
ᑍHOLD  
Type reply (if required), press Enter.  
From . . . :  
HOLD value is ᑍNO  
SMITH  
ð7/23/94  
1ð:25:14  
The API does not need to be called each time that you want a separate field  
because all fields are returned that would fit within the size indicated by the length  
of receiver variable (RCVLEN) parameter. You can run the program against the  
QBATCH job description in library QGPL by using the following call statement:  
CALL JOBDAPI PARM(QBATCH QGPL)  
If QGPL is on the library list, you can run the program against the QBATCH job  
description by using the following call statement:  
CALL JOBDAPI PARM(QBATCH ᑍLIBL)  
You can run the program on one of your own job descriptions or on a test job  
description where you have specified HOLD(*YES).  
Handling Error Conditions—OPM RPG Example  
For this example, assume that the XYZ job description does not exist:  
CALL JOBDAPI PARM(XYZ ᑍLIBL)  
You probably will receive the inquiry message CPA0701 that states an unmonitored  
exception (CPF9801) has occurred and offers several possible replies. At this point,  
you would enter C for Cancel and press the Enter key.  
If you displayed the low-level messages, you would see the following: CPF9801  
(Object not found), followed by the inquiry message (CPA0701), followed by your  
reply.  
When you specify the error code parameter as zero, you are specifying that  
exceptions be sent as escape messages. You can code the RPG program so that  
any errors on the call set the indicator 01 to on (.1ð/ on page 3-10). This causes a  
different path to be taken in the code.  
3-8 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
For RPG, the CALL operation specifies the error indicator. Based on whether the  
error indicator is on or off, a set of instructions can be processed. The API must  
receive an error code parameter that consists of a binary 4 field with a value of  
binary zeros (.11/ on page 3-10). The message ID can be accessed from the  
program-status data structure. You would define this as follows:  
Iᑍ Program status DS (.12/ on page 3-9)  
IPGMSTS  
I
SDS  
4ð 46 MSGIDD  
If you are going to do something about an error condition, you must test for an  
error condition in RPG:  
Ÿ If you use the error-code data structure, test the bytes available field (.13/ on  
page 3-14).  
Ÿ If you let exceptions occur, test the error indicator on the CALL operation (.1ð/  
on page 3-10).  
Because you must test for some condition (one of the error messages in “Error  
Messages” on page 3-36), no great difference exists in how you handle error con-  
ditions in RPG. The error-code data structure is a little more straightforward (the  
program-status data structure is not used). The only disadvantage of the error-  
code data structure is that the escape message that occurred was removed from  
the job log.  
The following program shows how to code for an error condition, test for that condi-  
tion, and send a message to the QPGMR message queue if the condition occurs:  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍProgram Name: JOBDAPI  
Iᑍ  
IᑍLanguage: OPM RPG  
Iᑍ  
IᑍDescriptive Name: Get Job Description  
Iᑍ  
IᑍDescription: This program handles any errors that are  
Iᑍ  
Iᑍ  
returned  
IᑍHeader Files Included: QUSEC - Error Code Parameter  
Iᑍ  
Iᑍ  
QWDRJOBD - Retrieve Job Description API  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
Iᑍ Error Code Parameter Include for the APIs  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSEC  
Iᑍ  
Iᑍ Retrieve Job Description API Include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QWDRJOBD  
Iᑍ Program status DS  
IPGMSTS  
SDS .12/  
I
4ð 46 MSGIDD  
1 26 CMD1  
Iᑍ  
Iᑍ Command String Data Structure  
Iᑍ  
ICMDSTR  
I I  
I
DS  
'SNDMSG MSG(''HOLD -  
'value is '  
I
I I  
Iᑍ  
27 36 HOLD  
37 51 CMD2  
''') TOUSR(QPGMR)'  
IMSG3  
DS  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-9  
Download from Www.Somanuals.com. All Manuals Search And Download.  
I I  
I
I I  
Iᑍ  
'SNDMSG MSG(''No such-  
' ᑍJOBD exists'') '  
'TOUSR(QPGMR)'  
1 35 MSG3A  
36 47 MSG3B  
Iᑍ Miscellaneous Data Structure  
Iᑍ  
I
DS  
I I  
I I  
Cᑍ  
39ð  
'JOBDð1ðð'  
B
1
4ðRCVLEN  
5 12 FORMAT  
Cᑍ Beginning of Mainline  
Cᑍ  
Cᑍ Two parameters are being passed into this program.  
Cᑍ  
C
ᑍENTRY  
PLIST  
PARM  
PARM  
C
JOBD  
1ð  
C
Cᑍ  
JOBDL 1ð  
Cᑍ Move the two parameters passed into LFNAM.  
Cᑍ  
C
JOBD  
CAT JOBDL  
LFNAM 2ð  
Cᑍ Error code bytes provided is set to ð  
Cᑍ  
C
Z-ADDð  
QUSBNB .11/  
Cᑍ  
Cᑍ Instead of specifying 'QWCRJOBD', I could have used the  
Cᑍ constant QWDBGB that was defined in the QWDRJOBD include.  
Cᑍ  
C
CALL 'QWDRJOBD'  
PARM  
ð1 .1ð/  
Receiver Var.  
C
QWDBH  
RCVLEN  
FORMAT  
LFNAM  
QUSBN  
C
PARM  
Length RCVVAR  
Format Name  
Qual. Job Desc  
Error Code  
Error Subroutine  
C
PARM  
C
PARM  
C
PARM  
C
ð1  
EXSR ERROR  
Cᑍ  
C Nð1  
Cᑍ  
MOVELQWDBHN  
HOLD  
Cᑍ Let's tell everyone what the hold value was for this job.  
Cᑍ  
C Nð1  
Z-ADD51  
CALL 'QCMDEXC'  
PARM  
LENSTR 155  
C Nð1  
C
C
Cᑍ  
C
C
Cᑍ  
CMDSTR  
LENSTR  
PARM  
SETON  
RETRN  
LR  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ Subroutine to handle errors received on the CALL  
Cᑍ  
C
ERROR  
MSGIDD  
BEGSR  
IFEQ 'CPF98ð1'  
C
Cᑍ  
Cᑍ Process errors returned from the API.  
Cᑍ  
C
C
C
C
C
C
Z-ADD47  
CALL 'QCMDEXC'  
PARM  
LENSTR 155  
MSG3  
LENSTR  
PARM  
END  
ENDSR  
If the CPF9801 exception occurs, your program sends a message to the QPGMR  
message queue as shown in the following display:  
3-10 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
à
ð
Display Messages  
System:  
GENSYS9ð  
ᑍDSPMSG  
Queue . . . . . :  
Library . . . :  
Severity . . . :  
QPGMR  
QUSRSYS  
Program . . . . :  
Library . . . :  
Delivery . . . :  
ðð  
ᑍHOLD  
Type reply (if required), press Enter.  
From . . . :  
No such ᑍJOBD exists  
SMITH  
ð7/25/94  
11:1ð:12  
If another exception occurs (for example, a library name that is not valid), you do  
not receive an indication that an error occurred because of the way the error sub-  
routine is currently coded.  
In addition, you can use the Message Handling APIs to receive the messages sent  
to your program message queue.  
The call to the API fails if you specify a valid job description but use a library qual-  
ifier such as *ALLUSR. The value *ALLUSR is not supported by the description of  
the required parameter group.  
Retrieving the Hold Parameter (Error Code Structure)—OPM RPG  
Example  
In the program example in “Retrieving the Hold Parameter (Exception  
Message)—OPM RPG Example,” QUSBNB (.6/ on page 3-7) was set to a value of  
binary zero to tell the API to send exceptions (escape messages) for any error con-  
ditions. The example in this topic uses an error-code data structure as an alterna-  
tive to receiving exceptions.  
Some languages do not support the use of exceptions, so you may prefer to code  
for errors using error code structures.  
In your programs, you can use error code structures in the following ways:  
Ÿ Define an 8-byte error code structure that provides feedback on whether an  
error occurred. If an error does occur, you are not able to determine the spe-  
cifics of the problem.  
Ÿ Define a 16-byte error code structure that allows you to determine if an error  
exists and to access the exception message ID. The exception message IDs  
are the same as shown in “Error Messages” on page 3-36.  
Ÿ Define a larger than 16-byte error code structure that provides the same infor-  
mation as described in the previous two error code structures as well as some  
or all of the exception data. The exception data is the message data that is  
sent with the exception message. Because the vast majority of exception mes-  
sages do not have more than 512 bytes of message data, a 600-byte error  
code structure would be adequate for almost all cases.  
Note: Lengths of 1 through 7 bytes are not valid for the error code structure.  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-11  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Format of an Error Code Structure  
The format of the error code structure (QUSBN) is:  
Offset  
Dec  
0
Hex  
0
Use  
Type  
Field  
INPUT  
BINARY(4) Bytes provided  
4
4
OUTPUT BINARY(4) Bytes available  
8
8
OUTPUT CHAR(7)  
OUTPUT CHAR(1)  
OUTPUT CHAR(*)  
Exception ID  
Reserved  
15  
16  
F
10  
Exception data  
The error code structure can be found in the QSYSINC library in the member  
QUSEC (see .14/ on page 3-12). Which of the files you use depends on the lan-  
guage. For more information on the QSYSINC library, see “APIs and the  
QSYSINC Library” on page 2-28.  
The bytes provided field describes the size of the error code structure that you  
declared in your program and how you want errors returned. (This was set to 0 as  
shown by .6/ on page 3-7 in the JOBDAPI example on page 3-6.)  
The bytes available field describes how many bytes the API could have passed  
back. If this field is zero, no exception occurred. The correct method for testing if  
an error occurred when using a nonzero-bytes-provided value is to check this field  
for a value greater than zero (.13/ on page 3-14).  
The exception ID is the normal 7-character message ID, such as CPF9801, that  
occurs for an object-not-found condition. Do not test this field to determine if an  
error exists. The field is properly set by the system only if the number of bytes  
available is greater than 0. Similarly, the exception data (message data) informa-  
tion is not set properly unless an error exists; for example, any information left from  
a prior call is not changed.  
The following program is the same as the previous program except that a 16-byte  
error code structure is used:  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍProgram Name: JOBDAPI  
Iᑍ  
IᑍLanguage: OPM RPG  
Iᑍ  
IᑍDescriptive Name: Get Job Description  
Iᑍ  
IᑍDescription: This sample program shows exceptions being  
Iᑍ  
Iᑍ  
returned in the error code parameter.  
IᑍHeader Files Included: QUSEC - Error Code Parameter  
Iᑍ  
Iᑍ  
QWDRJOBD - Retrieve Job Description API  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
Iᑍ Error Code Parameter Include for the APIs  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSEC .14/  
Iᑍ  
Iᑍ Retrieve Job Description API Include  
3-12 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QWDRJOBD  
Iᑍ  
Iᑍ Command String Data Structure  
Iᑍ  
ICMDSTR  
DS  
I I  
I
I
I I  
Iᑍ  
IMSG2  
I I  
I
I
I
I I  
Iᑍ  
'SNDMSG MSG(''HOLD -  
'value is '  
1 26 CMD1  
27 36 HOLD  
37 51 CMD2  
''') TOUSR(QPGMR)'  
DS  
'SNDMSG MSG(''Progr-  
'am failed with mes-  
'sage ID '  
1 43 MSG2A  
44 5ð MSGIDD  
51 65 MSG2B  
''') TOUSR(QPGMR)'  
Iᑍ Miscellaneous Data Structure  
Iᑍ  
I
DS  
I I  
I I  
Cᑍ  
39ð  
'JOBDð1ðð'  
B
1
4ðRCVLEN  
5 12 FORMAT  
Cᑍ Beginning of Mainline  
Cᑍ  
Cᑍ Two parameters are being passed into this program.  
Cᑍ  
C
ᑍENTRY  
PLIST  
PARM  
PARM  
C
JOBD  
1ð  
C
Cᑍ  
JOBDL 1ð  
Cᑍ Move the two parameters passed into the LFNAM.  
Cᑍ  
C
Cᑍ  
JOBD  
CAT JOBDL  
LFNAM 2ð  
Cᑍ Error code parameter is set to 16  
Cᑍ  
C
Z-ADD16  
QUSBNB .15/  
Cᑍ  
Cᑍ Instead of specifying 'QWCRJOBD', I could have used the  
Cᑍ constant QWDBGB that was defined in the QWDRJOBD include.  
Cᑍ  
C
C
C
C
C
C
CALL 'QWDRJOBD'  
PARM  
PARM  
PARM  
PARM  
PARM  
QWDBH  
RCVLEN  
FORMAT  
LFNAM  
QUSBN  
Receiver Var.  
Length RCVVAR  
Format Name  
Qual. Job Desc  
Error Code  
Cᑍ See if any errors were returned in the error code parameter.  
C
EXSR ERRCOD  
Cᑍ  
Cᑍ  
Cᑍ  
C Nð1  
Cᑍ  
MOVELQWDBHN  
HOLD  
Cᑍ Let's tell everyone what the hold value was for this job.  
Cᑍ  
C Nð1  
Z-ADD51  
CALL 'QCMDEXC'  
PARM  
LENSTR 155  
C Nð1  
C
C
Cᑍ  
C
C
Cᑍ  
CMDSTR  
LENSTR  
PARM  
SETON  
RETRN  
LR  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ  
Cᑍ Subroutine to handle errors returned in the error code  
Cᑍ parameter.  
Cᑍ  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-13  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
ERRCOD  
QUSBNC  
BEGSR  
IFGT ð .13/  
C
Cᑍ  
Cᑍ Process errors returned from the API.  
Cᑍ  
C
C
C
C
C
C
C
C
SETON  
ð1  
Z-ADD65  
MOVELQUSBND  
CALL 'QCMDEXC'  
PARM  
LENSTR 155  
MSGIDD  
MSG2  
LENSTR  
PARM  
END  
ENDSR  
The QUSBN error-code data structure is defined in the include file QUSEC (.14/ on  
page 3-12), and the program initializes the bytes provided field (QUSBNB) with a  
value of 16 (.15/ on page 3-13). This sets the first field of the error code structure  
to tell the API not to send an exception but to use the first 16 bytes of the QUSBN  
parameter to return the error information. After the CALL to the API, the program  
accesses the bytes available (QUSBNC) (.13/ on page 3-14). This contains the  
number of bytes of information about the error condition. The program is coded so  
that it tests if the number exceeds zero. This is the correct method of determining  
whether an error has occurred.  
If an error occurred, you may want to handle the error in many different methods.  
The program shown extracts the specific error message ID that occurred and sends  
the 7-character value as a message. The QUSBN parameter is used for both input  
and output (see “Format of an Error Code Structure” on page 3-12). The first 4  
bytes are input to the API to tell it how to handle exceptions. The remaining bytes  
are output from the API about any exception conditions.  
To see the value of the HOLD attribute, use the following call statement to run the  
program against the QBATCH job description in library QGPL:  
CALL JOBDAPI (QBATCH QGPL)  
You should see that the value of the HOLD attribute is *NO:  
à
ð
Display Messages  
System:  
GENSYS9ð  
ᑍDSPMSG  
Queue . . . . . :  
Library . . . :  
Severity . . . :  
QPGMR  
QUSRSYS  
Program . . . . :  
Library . . . :  
Delivery . . . :  
ðð  
ᑍHOLD  
Type reply (if required), press Enter.  
From . . . :  
HOLD value is ᑍNO  
SMITH  
ð7/23/94  
1ð:25:14  
Handling Error Conditions—OPM RPG Example  
For this error condition, you should assume that the XYZ job description does not  
exist. Use the following call statement to run the error condition:  
CALL JOBDAPI (XYZ ᑍLIBL)  
You should see that the CPF9801 message (Object not found) was issued:  
3-14 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
à
ð
Display Messages  
System:  
GENSYS9ð  
ᑍDSPMSG  
Queue . . . . . :  
Library . . . :  
Severity . . . :  
QPGMR  
QUSRSYS  
Program . . . . :  
Library . . . :  
Delivery . . . :  
ðð  
ᑍHOLD  
Type reply (if required), press Enter.  
From . . . :  
Program failed with message ID CPF98ð1  
SMITH  
ð7/23/94  
1ð:56:13  
Then run another error condition. For this error condition, you should assume that  
the XYZ library does not exist. Use the following call statement:  
CALL JOBDAPI (QPGMR XYZ)  
The output is similar to the following:  
à
ð
Display Messages  
System:  
GENSYS9ð  
ᑍDSPMSG  
Queue . . . . . :  
Library . . . :  
Severity . . . :  
QPGMR  
QUSRSYS  
Program . . . . :  
Library . . . :  
Delivery . . . :  
ðð  
ᑍHOLD  
Type reply (if required), press Enter.  
From . . . :  
Program failed with message ID CPF981ð  
SMITH  
ð7/23/94  
1ð:56:13  
You should see that the CPF9810 message (Library not found) was issued. An  
advantage of the error return variable is that it can contain other information such  
as message data. The following are the changes needed to return a 200-byte error  
code structure:  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍProgram Name: JOBDAPI  
Iᑍ  
IᑍLanguage: OPM RPG  
Iᑍ  
IᑍDescriptive Name: Get Job Description  
Iᑍ  
IᑍDescription: This sample program shows the incorrect  
Iᑍ  
Iᑍ  
way of using the offset in a user space in RPG.  
IᑍHeader Files Included: QUSEC - Error Code Parameter  
Iᑍ  
Iᑍ  
Iᑍ  
(Copied into Program)  
QWDRJOBD - Retrieve Job Description API  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ Error Code Parameter Include for the APIs  
Iᑍ  
Iᑍ The following QUSEC include is copied into this program  
Iᑍ so that the variable-length field can be defined as  
Iᑍ fixed length.  
Iᑍ  
Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍHeader File Name: H/QUSEC  
Iᑍ  
IᑍDescriptive Name: Error Code Parameter.  
Iᑍ  
Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994  
IᑍAll rights reserved.  
IᑍUS Government Users Restricted Rights -  
IᑍUse, duplication or disclosure restricted  
Iᑍby GSA ADP Schedule Contract with IBM Corp.  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-15  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ  
IᑍLicensed Materials-Property of IBM  
Iᑍ  
Iᑍ  
IᑍDescription: Include header file for the error code parameter.  
Iᑍ  
IᑍHeader Files Included: None.  
Iᑍ  
IᑍMacros List: None.  
Iᑍ  
IᑍStructure List: Qus_EC_t  
Iᑍ  
IᑍFunction Prototype List: None.  
Iᑍ  
IᑍChange Activity:  
Iᑍ  
IᑍCFD List:  
Iᑍ  
IᑍFLAG REASON  
LEVEL DATE  
PGMR  
CHANGE DESCRIPTION  
Iᑍ---- ------------ ----- ------ --------- ----------------------  
Iᑍ$Að= D2862ððð  
Iᑍ  
3D1ð 9312ð1 DPOHLSON: New Include  
IᑍEnd CFD List.  
Iᑍ  
IᑍAdditional notes about the Change Activity  
IᑍEnd Change Activity.  
Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IᑍRecord structure for Error Code Parameter  
Iᑍᑍᑍᑍ  
ᑍᑍᑍ  
IᑍNOTE: The following type definition defines only the fixed  
Iᑍ  
Iᑍ  
portion of the format. Varying-length field exception  
data is not defined here.  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IQUSBN  
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
Iᑍ  
Iᑍ  
Iᑍ  
I
DS  
Qus EC  
B
B
1
5
4ðQUSBNB  
Bytes Provided  
8ðQUSBNC  
Bytes Available  
9 15 QUSBND  
Exception Id  
16 16 QUSBNF  
Reserved  
17 17 QUSBNG  
Varying length  
17 2ðð QUSBNG .16/  
.
.
.
C
Z-ADD2ðð  
QUSBNB  
Cᑍ  
C
CALL 'QWDRJOBD'  
C
PARM  
PARM  
PARM  
PARM  
PARM  
QWDBH  
RCVLEN  
FORMAT  
LFNAM  
QUSBN  
Receiver Var.  
Length RCVVAR  
Format Name  
Qual. Job Desc  
Error Code  
C
C
C
C
The value placed in the QUSBNG variable .16/ is the message data associated  
with the message ID that is identified as the exception. The message data follows  
the same format as if you had entered a Receive Message (RCVMSG) command  
and requested the message data (MSGDTA) parameter. You can use the Display  
Message Description (DSPMSGD) command to determine the layout of the  
message data for a particular message ID. When you handle exceptions, the only  
information provided is the exception ID and the message data associated with the  
3-16 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
exception. You cannot receive a diagnostic message (if one were sent in addition  
to the escape message) in the error-code data structure. You can use the message  
handling APIs to receive messages from your program message queue and to  
access the other messages that may be issued from the API. Appendix A of the  
System API Reference book contains an example of a diagnostic report program  
that uses the message handling APIs.  
When you instruct the API to return all errors in the error-code data structure, the  
escape message does not appear in the job log. The escape message not  
appearing in the job log is one of the major differences between letting the API  
return errors in an error-code data structure and letting the API send escape mes-  
sages. For the error-code data structure, the escape messages have been  
removed from the job log by the API. If a diagnostic message is sent first, the  
diagnostic message exists in the job log and can be received.  
Accessing the HOLD Attribute—OPM RPG Example  
The following is the RPG code used to access the HOLD attribute. This is the  
same type of program as the RPG program examples in “Retrieving the Hold  
Parameter (Exception Message)—OPM RPG Example” on page 3-6 and  
“Retrieving the Hold Parameter (Error Code Structure)—OPM RPG Example” on  
page 3-11. The program, named JOBDAPI, prints the value of HOLD if it is found  
(.17/ on page 3-19). If an error occurs, the program prints a line that contains the  
error message ID to a spooled file called QPRINT (.18/ on page 3-19).  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FᑍProgram Name: JOBDAPI  
Fᑍ  
FᑍLanguage: OPM RPG  
Fᑍ  
FᑍDescriptive Name: Get Job Description  
Fᑍ  
FᑍDescription: The following program prints out the name of  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
the job description or prints an error if the  
API could not find the job description name  
specified.  
FᑍHeader Files Included: QUSEC - Error Code Parameter  
Fᑍ  
Fᑍ  
QWDRJOBD - Retrieve Job Description API  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ JOBDAPIR - Print value of HOLD parameter using API  
Fᑍ  
Fᑍ  
Uses error-code data structure  
FQPRINT O  
Iᑍ  
F
132  
OF  
PRINTER  
Iᑍ Error Code Parameter Include for the APIs  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSEC  
Iᑍ  
Iᑍ Retrieve Job Description API Include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QWDRJOBD  
Iᑍ  
Iᑍ  
Iᑍ Dummy data structure used to declare binary field .19/  
Iᑍ  
I
DS  
I I  
I I  
39ð  
'JOBDð1ðð'  
B
1
5
4ðRCVLEN  
12FORMAT  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-17  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
Cᑍ Beginning of Mainline  
Cᑍ  
Cᑍ Two parameters are being passed into this program.  
Cᑍ  
C
ᑍENTRY  
PLIST  
PARM  
PARM  
Parm list  
Job descrp  
Jobd library  
C
JOBD  
1ð  
C
JOBDL 1ð  
Cᑍ  
Cᑍ Move the two parameters passed into LFNAM.  
Cᑍ  
C
JOBD  
CAT JOBDL  
LFNAM 2ð  
Qlfd name  
Cᑍ  
Cᑍ Error code parameter is set to 16.  
Cᑍ  
C
Z-ADD16  
QUSBNB  
Bytes provid  
Cᑍ  
Cᑍ Instead of specifying 'QWCRJOBD', I could have used the  
Cᑍ constant QWDBGB that was defined in the QWDRJOBD include.  
Cᑍ Call the API  
Cᑍ  
C
C
C
C
C
C
CALL 'QWDRJOBD'  
Parm list  
PARM  
PARM  
PARM  
PARM  
PARM  
QWDBH  
RCVLEN  
FORMAT  
LFNAM  
QUSBN  
Receiver Var.  
Length RCVVAR  
Format Name  
Qual. Job Desc  
Error Code  
Cᑍ If no bytes available, API was successful; print HOLD value  
C
C
C
QUSBNC  
IFEQ ð  
EXCPTGOOD  
ENDIF  
Cᑍ If some bytes available, API failed; print error message ID  
C
C
C
QUSBNC  
IFGT ð  
EXCPTBAD  
ENDIF  
Cᑍ End of program  
C
C
Cᑍ  
SETON  
RETRN  
LR  
Cᑍ End of MAINLINE  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Oᑍ  
OQPRINT E 1ð6  
GOOD  
O
'HOLD value - '  
O
QWDBHN  
BAD  
OQPRINT E 1ð6  
O
O
'Failed. Error ID - '  
QUSBND  
The following data structures are used:  
Error-code data structure  
This defines the two binary fields used and the message ID that is returned for  
error conditions.  
Retrieve job description data structure  
This defines format JOBD0100, a 390-byte data structure with the hold field in  
positions 77-86.  
Dummy data structure  
This contains a field used for the length of the receiver variable. The field is  
defined as binary and is in the first 4 bytes. The dummy data structure (.19/  
on page 3-17) also contains the format field.  
This data structure is used because RPG only allows binary variables to be  
defined in the context of a data structure.  
The program retrieves the parameter list that is passed and initializes the fields to  
be passed to the API. The API is called and places information into the receiver-  
3-18 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
variable data structure if information is found. The API places the information in the  
error-code data structure if an error occurred and if enough space was provided to  
receive the information.  
The program prints one of two different lines depending on whether any errors were  
found:  
HOLD value - ᑍNO .17/  
Failed. Error ID - CPF98ð1 .18/  
Accessing a Field Value (Initial Library List)—OPM RPG Example  
In this topic, the JOBDAPI program accesses a variable-length array. The variable-  
length array is the initial library list for the job description.  
The discussion of the initial library list field in the job description format, “JOBD0100  
Format” on page 3-30, indicates that the initial library list field is 11 bytes per entry,  
where each entry is a library name followed by a blank. Because the maximum  
number of libraries allowed on an initial library list is 25, this field is up to and  
including 275 bytes in length. Depending on how many libraries are named for the  
initial library list, the actual amount of space used varies (by multiples of 11).  
The format does not have an entry in the Offset columns for initial library list. It may  
begin in offset 390, but you should not rely on this. For example, if a new field is  
added to the job description format, it will probably be placed at offset 390, and the  
initial library list information will be shifted.  
To access the initial library list field, use the following two fields found in the format:  
Ÿ Offset to the initial library list field (.19/ on page 3-22 and on page 3-31).  
Ÿ Number of libraries in the initial library list field (.2ð/ on page 3-22 and on page  
3-31).  
If you use these field values in the format instead of hard coding an offset and a  
number of libraries, your program can work on any future release of an AS/400  
business computing system, even if more job description attributes are defined in  
the format. This is an important upward compatibility approach that you will want to  
use whenever you code for a list of entries.  
The following RPG code sends a message for each library found in the initial library  
list field. Exceptions are handled by the RPG program. Although a library name  
cannot exceed 10 bytes, each entry is 11 bytes long.  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍProgram Name: JOBDAPI  
Iᑍ  
IᑍLanguage: OPM RPG  
Iᑍ  
IᑍDescriptive Name: Get Job Description  
Iᑍ  
IᑍDescription: This sample program shows the correct  
Iᑍ  
Iᑍ  
way of using the offset in a user space in RPG.  
IᑍHeader Files Included: QUSEC - Error Code Parameter  
Iᑍ  
Iᑍ  
Iᑍ  
Iᑍ  
(Copied into Program)  
QWDRJOBD - Retrieve Job Description API  
(Copied into Program)  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-19  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
Iᑍ Error Code Parameter Include for the APIs  
Iᑍ  
Iᑍ The following QUSEC include is copied into this program  
Iᑍ so that the variable-length field can be defined as  
Iᑍ fixed length.  
Iᑍ  
Iᑍ  
Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍHeader File Name: H/QUSEC  
Iᑍ  
IᑍDescriptive Name: Error Code Parameter.  
Iᑍ  
Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994  
IᑍAll rights reserved.  
IᑍUS Government Users Restricted Rights -  
IᑍUse, duplication or disclosure restricted  
Iᑍby GSA ADP Schedule Contract with IBM Corp.  
Iᑍ  
IᑍLicensed Materials-Property of IBM  
Iᑍ  
Iᑍ  
IᑍDescription: Include header file for the error code parameter.  
Iᑍ  
IᑍHeader Files Included: None.  
Iᑍ  
IᑍMacros List: None.  
Iᑍ  
IᑍStructure List: Qus_EC_t  
Iᑍ  
IᑍFunction Prototype List: None.  
Iᑍ  
IᑍChange Activity:  
Iᑍ  
IᑍCFD List:  
Iᑍ  
IᑍFLAG REASON  
LEVEL DATE  
PGMR  
CHANGE DESCRIPTION  
Iᑍ---- ------------ ----- ------ --------- ----------------------  
Iᑍ$Að= D2862ððð  
Iᑍ  
3D1ð 9312ð1 DPOHLSON: New Include  
IᑍEnd CFD List.  
Iᑍ  
IᑍAdditional notes about the Change Activity  
IᑍEnd Change Activity.  
Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IᑍRecord structure for Error Code Parameter  
Iᑍᑍᑍᑍ  
ᑍᑍᑍ  
IᑍNOTE: The following type definition defines only the fixed  
Iᑍ  
Iᑍ  
portion of the format. Varying-length field exception  
data is not defined here.  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IQUSBN  
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
DS  
Qus EC  
B
B
1
5
4ðQUSBNB  
Bytes Provided  
8ðQUSBNC  
Bytes Available  
9 15 QUSBND  
Exception Id  
16 16 QUSBNF  
Reserved  
Iᑍ  
I
Iᑍ  
Iᑍ  
I
Varying length, had to define len  
17 1ðð QUSBNG .7/  
Iᑍ  
Iᑍ Retrieve Job Description API Include  
Iᑍ  
Iᑍ The following QWDRJOBD include is copied into this program  
Iᑍ so that the variable-length field can be defined as fixed  
Iᑍ length.  
3-20 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ  
Iᑍ  
Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍHeader File Name: H/QWDRJOBD  
Iᑍ  
IᑍDescriptive Name: Retrieve Job Description Information API  
Iᑍ  
Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994  
IᑍAll rights reserved.  
IᑍUS Government Users Restricted Rights -  
IᑍUse, duplication or disclosure restricted  
Iᑍby GSA ADP Schedule Contract with IBM Corp.  
Iᑍ  
IᑍLicensed Materials-Property of IBM  
Iᑍ  
Iᑍ  
IᑍDescription: The Retrieve Job Description Information API  
Iᑍ  
Iᑍ  
Iᑍ  
Iᑍ  
retrieves information from a job description  
object and places it into a single variable in the  
calling program.  
IᑍHeader Files Included: None.  
Iᑍ  
IᑍMacros List: None.  
Iᑍ  
IᑍStructure List: Qwd_JOBDð1ðð_t  
Iᑍ  
IᑍFunction Prototype List: QWDRJOBD  
Iᑍ  
IᑍChange Activity:  
Iᑍ  
IᑍCFD List:  
Iᑍ  
IᑍFLAG REASON  
LEVEL DATE  
PGMR  
CHANGE DESCRIPTION  
Iᑍ---- ------------ ----- ------ --------- ----------------------  
Iᑍ$Að= D2862ððð  
Iᑍ  
3D1ð 94ð424 ROCH:  
New Include  
IᑍEnd CFD List.  
Iᑍ  
IᑍAdditional notes about the Change Activity  
IᑍEnd Change Activity.  
Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IᑍPrototype for QWDRJOBD API  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
I
'QWDRJOBD'  
C
QWDBGB  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IᑍType Definition for the JOBDð1ðð format.  
Iᑍᑍᑍᑍ  
ᑍᑍᑍ  
IᑍNOTE: The following type definition defines only the fixed  
Iᑍ  
Iᑍ  
portion of the format. Any varying-length fields have  
to be defined by the user.  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IQWDBH  
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
DS  
1ððð  
Qwd JOBDð1ðð  
4ðQWDBHB  
Bytes Returned  
8ðQWDBHC  
Bytes Available  
9 18 QWDBHD  
Job Description Name  
19 28 QWDBHF  
Job Description Lib Name  
29 38 QWDBHG  
User Name  
39 46 QWDBHH  
Job Date  
47 54 QWDBHJ  
Job Switches  
55 64 QWDBHK  
Job Queue Name  
B
B
1
5
Iᑍ  
I
Iᑍ  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-21  
Download from Www.Somanuals.com. All Manuals Search And Download.  
I
65 74 QWDBHL  
Job Queue Lib Name  
75 76 QWDBHM  
Job Queue Priority  
77 86 QWDBHN  
Hold Job Queue  
87 96 QWDBHP  
Output Queue Name  
97 1ð6 QWDBHQ  
Output Queue Lib Name  
1ð7 1ð8 QWDBHR  
Output Queue Priority  
1ð9 118 QWDBHS  
Printer Device Name  
119 148 QWDBHT  
Print Text  
B 149 152ðQWDBHV  
Syntax Check Severity  
B 153 156ðQWDBHW  
End Severity  
B 157 16ððQWDBHX  
Message Log Severity  
161 161 QWDBHY  
Message Log Level  
162 171 QWDBHZ  
Message Log Text  
172 181 QWDBHð  
Log CL Programs  
182 191 QWDBH1  
Inquiry Message Reply  
192 2ð4 QWDBH2  
Device Recovery Action  
2ð5 214 QWDBH3  
Time Slice End Pool  
215 229 QWDBH4  
Accounting Code  
23ð 3ð9 QWDBH5  
Routing Data  
31ð 359 QWDBH6  
Text Description  
36ð 36ð QWDBH7  
Reserved  
B 361 364ðQWDBH8 .19/  
Offset Initial Lib List  
B 365 368ðQWDBH9 .2ð/  
Number Libs In Lib list  
B 369 372ðQWDBJB  
Offset Request Data  
B 373 376ðQWDBJC  
Length Request Data  
B 377 38ððQWDBJH  
Job Message Queue Max Size  
381 39ð QWDBJJ  
Job Message Queue Full Actio  
391 391 QWDBJD  
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
Iᑍ  
Iᑍ  
Iᑍ  
Varying length  
392 4ð2 QWDBJF  
Iᑍ  
Iᑍ  
Iᑍ  
Varying length  
Iᑍ  
4ð3 4ð3 QWDBJG  
Iᑍ  
Iᑍ  
Iᑍ Command String Data Structure  
Iᑍ  
ICMDSTR  
DS  
I I  
I
I
I I  
Iᑍ  
'SNDMSG MSG(''LIBRARY-  
' - '  
1 22 CMD1  
23 32 LIB  
33 47 CMD2  
''') TOUSR(QPGMR)'  
Iᑍ Miscellaneous Data Structure  
3-22 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ  
I
DS  
I I  
I I  
I I  
Cᑍ  
1ððð  
B
B
1
5
4ðRCVLEN  
8ðX  
ð
'JOBDð1ðð'  
9 16 FORMAT  
Cᑍ Beginning of Mainline  
Cᑍ  
Cᑍ Two parameters are being passed into this program.  
Cᑍ  
C
ᑍENTRY  
PLIST  
PARM  
PARM  
C
JOBD  
1ð  
C
Cᑍ  
JOBDL 1ð  
Cᑍ Move the two parameters passed into LFNAM.  
Cᑍ  
C
Cᑍ  
JOBD  
CAT JOBDL  
LFNAM 2ð  
Cᑍ Error code Parameter is set to 1ðð  
Cᑍ  
C
Z-ADD1ðð  
QUSBNB  
Cᑍ  
Cᑍ Instead of specifying 'QWCRJOBD', I could have used the  
Cᑍ constant QWDBGB that was defined in the QWDRJOBD include.  
Cᑍ  
C
C
C
C
C
C
CALL 'QWDRJOBD'  
PARM  
PARM  
PARM  
PARM  
PARM  
QWDBH  
RCVLEN  
FORMAT  
LFNAM  
QUSBN  
Receiver Var.  
Length RCVVAR  
Format Name  
Qual. Job Desc  
Error Code  
Cᑍ See if any errors were returned in the error code parameter.  
C
Cᑍ  
C Nð1  
Cᑍ  
EXSR ERRCOD  
Z-ADD47  
LENSTR 155  
C Nð1  
C Nð1  
C
QWDBH8  
ADD 1  
X
1
DO  
QWDBH9  
1ð  
SUBSTQWDBH:X  
LIB  
Cᑍ  
Cᑍ Let's tell everyone what the library value is.  
Cᑍ  
C
CALL 'QCMDEXC'  
PARM  
C
CMDSTR  
LENSTR  
X
C
PARM  
C
ADD 11  
IFGE RCVLEN  
LEAVE  
ENDIF  
ENDDO  
C
X
C
C
C
Cᑍ  
C
SETON  
RETRN  
LR  
C
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ  
Cᑍ Subroutine to handle errors returned in the error code  
Cᑍ parameter.  
Cᑍ  
C
ERRCOD  
QUSBNC  
BEGSR  
IFGT ð  
SETON  
C
C
ð1  
Error on API Call  
Cᑍ  
Cᑍ Process errors returned from the API.  
Cᑍ  
C
C
END  
ENDSR  
Note: It is important to access the count and to compare for the exact number of  
libraries to be processed. If you do not check for the exact number of  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-23  
Download from Www.Somanuals.com. All Manuals Search And Download.  
libraries, you may begin to access information in the format for the next set  
of information (in this example, it may be the request data value).  
The output for this program example is as follows:  
à
ð
Display Messages  
System: GENSYS9ð  
Queue . . . . . : QPGMR  
Program . . . . : ᑍDSPMSG  
Library . . . :  
Library . . . :  
QUSRSYS  
Severity . . . : ðð  
Type reply (if required), press Enter.  
LIBRARY - SMITH  
From . . . : SMITH  
LIBRARY - QTEMP  
From . . . : SMITH  
LIBRARY - QGPL  
Delivery . . . : ᑍHOLD  
ð7/23/94 12:29:38  
ð7/23/94 12:29:38  
From . . . : SMITH  
LIBRARY - QBLDCPF  
From . . . : SMITH  
LIBRARY - UTIL  
From . . . : SMITH  
LIBRARY - OPENTEST  
ð7/23/94 12:29:38  
ð7/23/94 12:29:38  
ð7/23/94 12:29:38  
The handling of the initial library list field is typical of what you will find in many  
APIs.  
Using Keys with List Spooled Files API—Example  
This topic introduces a new program named LSTSPL. Program LSTSPL uses the  
List Spooled Files (QUSLSPL) API to determine the spooled file name, date  
created, and number of pages for all spooled files created by the current user of  
the LSTSPL program. Unlike the earlier JOBDAPI program examples, where  
format JOBD0100 of the Retrieve Job Description (QWDRJOBD) API returned  
dozens of fields while we were only interested in the HOLD field, the QUSLSPL API  
provides a keyed interface that allows LSTSPL to request that only the relevant  
fields (spooled file name, date created, and number of pages) be returned. In addi-  
tion to providing a keyed interface, QUSLSPL also differs from QWDRJOBD in that  
the QUSLSPL API retrieves a list of all spooled files into a User Space (*USRSPC)  
while QWDRJOBD retrieves information about one specific job description into a  
program variable.  
In the following program example, all the pieces have been put together with an  
OPM RPG program that accesses specific information related to spooled files. A  
report listing this information is created. The program example does not handle  
API-related errors. Any errors that are received are returned as exception mes-  
sages.1/.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program Name:  
LSTSPL  
Fᑍ  
Fᑍ Program Language:  
OPM RPG  
Fᑍ  
Fᑍ Descriptive Name:  
List Spooled Files for Current User  
Fᑍ  
Fᑍ Description:  
Fᑍ  
This example shows the steps necessary  
to process keyed output from an API.  
3-24 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Fᑍ  
Fᑍ Header Files Included: QUSEC  
- Error Code Parameter  
Fᑍ  
QUSGEN  
- User Space Generic Header  
Fᑍ  
QUSLSPL - List Spooled Files  
Fᑍ  
Fᑍ APIs Used:  
QUSLSPL - List Spooled Files  
QUSCRTUS - Create User Space  
QUSRTVUS - Retrieve User Space  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
FQSYSPRT O  
Iᑍ  
F
132  
OF  
PRINTER  
Iᑍ Copy User Space Generic Header  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSGEN  
.11/  
Iᑍ  
Iᑍ Copy API Error Code parameter  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSEC  
Iᑍ  
Iᑍ Copy List Spooled Files API include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSLSPL  
Iᑍ  
Iᑍ Data structure to hold space name  
Iᑍ  
ISPCNAM  
I I  
DS  
'SPCNAME  
'QTEMP  
'
'
1 1ð SPC  
11 2ð LIB  
I I  
Iᑍ  
Iᑍ Data structure to hold requested key values  
Iᑍ  
IKEYARA  
I I  
DS  
.5/ .7/  
2ð1  
216  
211  
B
B
B
1
5
4ðKEY1  
8ðKEY2  
I I  
I I  
Iᑍ  
9 12ðKEY3  
.8/  
Iᑍ Receiver variable for QUSRTVUS  
Iᑍ  
IRECVR  
Iᑍ  
DS  
1ððð  
Iᑍ Other assorted variables  
Iᑍ  
I
DS  
I
B
B
B
1
5
4ðSIZ  
I
8ðSTART  
I
9 12ðLENDTA  
I
B 13 16ðKEY#  
B 17 2ððPAGES#  
17 2ð PAGESA  
21 21 INTVAL  
I
I
I I  
Cᑍ  
X'ðð'  
Cᑍ Initialize Error Code structure to accept exceptions  
Cᑍ  
C
Cᑍ  
Z-ADDð  
QUSBNB .1/  
Cᑍ Create the User Space to hold the QUSLSPL API results  
Cᑍ  
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL 'QUSCRTUS'  
PARM  
.2/  
SPCNAM  
PARM 'quslspl' EXTATR 1ð  
PARM 2ððð  
PARM  
PARM 'ᑍALL'  
PARM  
PARM 'ᑍYES'  
PARM  
SIZ  
INTVAL  
PUBAUT 1ð  
TXTDSC 5ð  
REPLAC 1ð  
QUSBN  
Cᑍ Call QUSLSPL to get all spooled files for ᑍCURRENT user  
Cᑍ  
C
C
CALL 'QUSLSPL'  
PARM  
.3/  
SPCNAM  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-25  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
C
C
C
C
C
C
C
C
Cᑍ  
PARM 'SPLFð2ðð'FORMAT 8 .4/  
PARM 'ᑍCURRENT'USRNAM 1ð  
PARM 'ᑍALL'  
PARM 'ᑍALL'  
PARM 'ᑍALL'  
PARM  
OUTQ  
2ð  
FRMTYP 1ð  
USRDTA 1ð  
QUSBN  
PARM  
JOBNAM 26  
KEYARA  
KEY#  
PARM  
PARM 3  
.5/  
.6/  
Cᑍ Retrieve information concerning the User Space and its contents  
Cᑍ  
C
CALL 'QUSRTVUS'  
PARM  
.9/  
SPCNAM  
START  
LENDTA  
QUSBP  
QUSBN  
C
C
PARM 1  
Start Rtv at 1  
for length =192  
C
PARM 192  
PARM  
PARM  
C
.1ð/  
C
Cᑍ  
Cᑍ Check User Space status for good information  
Cᑍ  
C
QUSBPD  
QUSBPJ  
QUSBPJ  
IFEQ 'ð1ðð'  
IFEQ 'C'  
OREQ 'P'  
.12/  
.14/  
Header Fmt  
Complete  
C
C
or Partial  
Cᑍ  
Cᑍ Check to see if any entries were put into User Space  
Cᑍ  
C
Cᑍ  
QUSBPS  
IFGT ð  
.16/  
Cᑍ Keep count of how many list entries we have processed  
Cᑍ  
C
Cᑍ  
Z-ADDð  
COUNT  
9ð .17/  
Cᑍ Adjust Offset value to Position value  
Cᑍ  
C
QUSBPQ  
ADD 1  
START  
.18/  
Cᑍ  
Cᑍ Retrieve the lesser of allocated storage or available data  
Cᑍ  
C
QUSBPT  
IFLT 1ððð  
Z-ADDQUSBPT  
ELSE  
Z-ADD1ððð  
ENDIF  
.19/  
LENDTA  
C
C
C
LENDTA  
C
Cᑍ  
Cᑍ Process all entries returned  
Cᑍ  
C
COUNT  
DOWLTQUSBPS  
.2ð/  
Cᑍ  
Cᑍ Retrieve spooled file information  
Cᑍ  
C
CALL 'QUSRTVUS'  
.21/  
SPCNAM  
START  
LENDTA  
RECVR  
QUSBN  
C
PARM  
PARM  
PARM  
PARM  
PARM  
C
C
C
C
Cᑍ  
Cᑍ Loop through returned fields  
Cᑍ  
C
4
SUBSTRECVR  
Z-ADD5  
QUSFV  
X
.22/  
.24/  
C
4ð  
C
DO  
QUSFVB  
.23/  
Cᑍ  
Cᑍ Get header information  
Cᑍ  
C
Cᑍ  
16  
SUBSTRECVR:X  
QUSKR  
Cᑍ Set Y to location of actual data associated with key  
Cᑍ  
C
Cᑍ  
X
ADD 16  
Y
4ð  
3-26 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ Process the data based on key type  
Cᑍ  
C
QUSKRC  
QUSKRC  
QUSKRC  
CASEQ2ð1  
CASEQ211  
CASEQ216  
CAS  
FILNAM  
PAGES  
AGE  
.25/  
C
C
C
C
ERROR  
END  
Cᑍ  
Cᑍ Adjust X to address next keyed record returned  
Cᑍ  
C
ADD QUSKRB  
ENDDO  
X
C
Cᑍ  
Cᑍ Output information on spooled file  
Cᑍ  
C
EXCPTPRTLIN  
.26/  
.27/  
Cᑍ  
Cᑍ Adjust START to address next entry  
Cᑍ  
C
ADD 1  
ADD QUSBPT  
ENDDO  
ENDIF  
ELSE  
EXCPTLSTERR  
ENDIF  
ELSE  
EXCPTHDRERR  
ENDIF  
MOVE '1'  
RETRN  
COUNT  
START  
C
C
C
C
.15/  
C
C
C
.13/  
C
C
C
ᑍINLR  
.28/  
C
Cᑍ  
Cᑍ Various subroutines  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
FILNAM  
BEGSR  
Cᑍ Extract spooled file name for report  
Cᑍ  
C
C
C
MOVE ᑍBLANKS  
SUBSTRECVR:Y  
ENDSR  
PRTFIL 1ð  
PRTFIL  
QUSKRG  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
PAGES  
BEGSR  
Cᑍ Extract number of pages for report  
Cᑍ  
C
C
QUSKRG  
SUBSTRECVR:Y  
ENDSR  
PAGESA  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
AGE  
BEGSR  
Cᑍ Extract age of spooled file for report  
Cᑍ  
C
C
C
MOVE ᑍBLANKS  
SUBSTRECVR:Y  
ENDSR  
OPNDAT 7  
OPNDAT  
QUSKRG  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
ERROR  
BEGSR  
Cᑍ If unknown key value, then display the value and end  
Cᑍ  
C
DSPLY  
QUSKRC  
ᑍINLR  
C
MOVE '1'  
RETRN  
C
C
Oᑍ  
ENDSR  
OQSYSPRT E  
PRTLIN  
O
PRTFIL  
PAGES#  
OPNDAT  
LSTERR  
1ð  
25  
4ð  
O
O
OQSYSPRT E  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-27  
Download from Www.Somanuals.com. All Manuals Search And Download.  
O
22 'List data not valid  
'
OQSYSPRT E  
O
HDRERR  
22 'Unknown Generic Header'  
List APIs do not automatically create the user space (*USRSPC) to receive the list.  
You must first create one using the Create User Space (QUSCRTUS) API.2/.  
Similar to CL create commands, the QUSCRTUS API has several parameters that  
identify the name of the object, the public authority, the object description text, and  
so forth.  
After creating the user space, you can call the QUSLSPL API to return spooled file  
information into the user space.3/. The QUSLSPL API supports two formats:  
SPLF0100, which returns a fixed set of information about each selected spooled  
file, and SPLF0200, which returns only user-selected fields. LSTSPL uses  
SPLF0200.4/ and passes to the QUSLSPL API a list of keys to identify the  
selected fields.5/ and the number of keys.6/. Because OPM RPG does not  
support an array (list) of binary values, LSTSPL defines the key array (KEYARA) as  
a data structure comprised of contiguous binary(4) fields.7/. The fields are initial-  
ized to 201, 216, and 211, which correspond to the keys named spooled file name,  
date file was opened, and total pages, respectively.8/. Note that while the user  
space was created with an initial size of 2000 bytes.2/, most List APIs implicitly  
extend the user space (up to a maximum of 16MB) in order to return all available  
list entries. The reverse, truncation when the user space is too large, is not per-  
formed by list APIs.  
Having generated the list, you can now process the user space data.  
List APIs (like QUSLSPL) generally provide a generic list header at the beginning of  
the user space, which provides information such as the API that created the list, the  
number of entries (spooled files for this example) in the list, the size of each entry,  
and so on. See the “User Space Format for List APIs” topic in the book System  
API Reference for further information. To access the generic list header, use the  
Retrieve User Space (QUSRTVUS) API.9/. Program LSTSPL retrieves the generic  
list header into the data structure QUSBP.1ð/, which is defined in the QUSGEN  
QSYSINC /COPY (include) file.11/. Note that languages, such as ILE RPG,  
COBOL, and C, which support pointers, can avoid this call to QUSRTVUS (and the  
resulting movement of data) by using the Retrieve Pointer to User Space  
(QUSPTRUS) API. See “List Object API—Examples” on page B-94 for examples.  
Program LSTSPL now checks that the format of the generic list header is the one  
expected.12/, and if not, prints an error line.13/. Having verified the header  
format, LSTSPL now checks the information status of the list.14/ (and if it is not  
accurate, prints an error line.15/) and that at least one list entry is available.16/.  
Having determined that accurate list entries are available, LSTSPL does the fol-  
lowing:  
Ÿ Initializes the COUNT variable to keep track of how many entries have been  
processed.17/  
Ÿ Adds one to the base 0 offset (to the first entry in the list) as the QUSRTVUS  
API assumes base 1 positional values.18/  
Ÿ Determines how much data is associated with each entry.19/ (which is the  
lesser of either the amount of storage you allocated to receive a list entry, or  
the size of a list entry)  
3-28 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Ÿ Falls into a DO loop to process all of the available list entries.2ð/  
Within this loop, LSTSPL retrieves each list entry.21/, extracts the number of fields  
returned.22/, and enters an inner DO loop to process all of the available list entry  
fields.23/.  
Within this inner loop, the program extracts the field information.24/ and processes  
the field data based on the key field.25/.  
When all fields for a given list entry have been processed, LSTSPL generates a  
print line.26/ and proceeds to the next list entry.27/.  
When all the list entries have been processed, LSTSPL ends.28/.  
Processing Lists That Contain Data Structures  
Some APIs support a list where each entry in the list is itself a data structure. A  
good example is the Retrieve System Status (QWCRSSTS) API. It supports mul-  
tiple formats for different types of information. The SSTS0300 format contains a list  
where each entry in the list has the information about a particular storage pool. In  
addition to the two critical fields (the offset to where the list begins field and the  
number of entries in the list field), the format also supports a field that describes the  
length of each entry. In the initial library list, each entry was 11-bytes long. But in  
a storage pool, a field (length of pool information entry) describes the length and  
should be used instead of a fixed-length increment. This allows for growth, such as  
more information being available in another release for each list entry.  
For example, if another field is added to describe some additional information about  
a storage pool, it is probably added after the paging option field. The length of pool  
information entry allows your code to be upwardly compatible while it retains the  
locations (relative to the start of a list entry) of the current fields.  
Retrieve Job Description Information API—Example  
The following API has been included as reference information. This API is used in  
many examples throughout this chapter and should not be used to code your pro-  
grams. Refer to the System API Reference, SC41-5801, for the most recent  
version of this API.  
Parameters  
Required Parameter Group:  
1
2
3
4
5
Receiver variable  
Length of receiver variable  
Format name  
Qualified job description name  
Error code  
Output  
Input  
Input  
Input  
I/O  
Char(*)  
Binary(4)  
Char(8)  
Char(20)  
Char(*)  
The Retrieve Job Description Information (QWDRJOBD) API retrieves information  
from a job description object and places it into a single variable in the calling  
program. The amount of information returned depends on the size of the variable.  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-29  
Download from Www.Somanuals.com. All Manuals Search And Download.  
The information returned is the same information returned by the Display Job  
Description (DSPJOBD) command.  
Authorities and Locks  
Job Description Object Authority *USE  
Library Authority  
*USE  
Required Parameter Group  
Receiver variable  
OUTPUT; CHAR(*)  
The variable that is to receive the information requested. You can specify the  
size of this area to be smaller than the format requested if you specify the  
length of receiver variable parameter correctly. As a result, the API returns  
only the data that the area can hold.  
Length of receiver variable  
INPUT; BINARY(4)  
The length of the receiver variable. If this value is larger than the actual size of  
the receiver variable, the result may not be predictable. The minimum length is  
8 bytes.  
Format name  
INPUT; CHAR(8)  
The format of the job description information to be returned. You can use this  
format:  
JOBD0100  
Basic job description information. For details, see “JOBD0100  
Format.”  
Qualified job description name  
INPUT; CHAR(20)  
The name of the job description whose contents are to be retrieved. The first  
10 characters contain the name of the job description, and the second 10 char-  
acters contain the name of the library where the job description is located. You  
can use these special values for the library name:  
*CURLIB  
*LIBL  
The job's current library  
The library list  
Error code  
I/O; CHAR(*)  
The structure in which to return error information. For the format of the struc-  
ture, see "Error Code Parameter" in Chapter 2 of the System API Reference.  
JOBD0100 Format  
The following table describes the information that is returned in the receiver vari-  
able for the JOBD0100 format. For detailed descriptions of the fields, see “Field  
Descriptions” on page 3-32.  
Offset  
Dec  
0
Hex  
0
Type  
Field  
BINARY(4)  
BINARY(4)  
Bytes returned  
Bytes available  
4
4
3-30 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Offset  
Dec  
Hex  
8
Type  
Field  
8
CHAR(10)  
CHAR(10)  
CHAR(10)  
CHAR(8)  
Job description name  
Job description library name  
User name  
18  
12  
28  
1C  
26  
38  
Job date  
46  
2E  
36  
CHAR(8)  
Job switches  
54  
CHAR(10)  
CHAR(10)  
CHAR(2)  
Job queue name  
64  
40  
Job queue library name  
Job queue priority  
74  
4A  
4C  
56  
76  
CHAR(10)  
CHAR(10)  
CHAR(10)  
CHAR(2)  
Hold on job queue  
Output queue name  
Output queue library name  
Output queue priority  
Printer device name  
Print text  
86  
96  
60  
106  
108  
118  
148  
152  
156  
160  
161  
171  
181  
191  
204  
214  
229  
309  
359  
360  
364  
368  
372  
376  
380  
6A  
6C  
76  
CHAR(10)  
CHAR(30)  
BINARY(4)  
BINARY(4)  
BINARY(4)  
CHAR(1)  
94  
Syntax check severity  
End severity  
98  
9C  
A0  
A1  
AB  
B5  
BF  
CC  
D6  
E5  
135  
167  
168  
16C  
170  
174  
178  
17C  
186  
Message logging severity  
Message logging level  
Message logging text  
Logging of CL programs  
Inquiry message reply  
Device recovery action  
Time-slice end pool  
Accounting code  
CHAR(10)  
CHAR(10)  
CHAR(10)  
CHAR(13)  
CHAR(10)  
CHAR(15)  
CHAR(80)  
CHAR(50)  
CHAR(1)  
Routing data  
Text description  
Reserved  
BINARY(4)  
BINARY(4)  
BINARY(4)  
BINARY(4)  
BINARY(4)  
CHAR(10)  
CHAR(*)  
Offset to initial library list .19/  
Number of libraries in initial library list .2ð/  
Offset to request data  
Length of request data  
Job message queue maximum size  
Job message queue full action  
Reserved  
390  
.1/  
*
*
*
*
ARRAY (*) of  
CHAR(11)  
Initial library list  
Request data  
CHAR(*)  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-31  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Field Descriptions  
Accounting code. An identifier assigned to jobs that use this job description.  
This code is used to collect system resource use information. If the special value  
*USRPRF is specified, the accounting code used for jobs using this job description  
is obtained from the job's user profile.  
Bytes available. The length of all data available to return. All available data is  
returned if enough space is provided.  
Bytes returned. The length of all data actually returned. If the data is truncated  
because the receiver variable was not sufficiently large to hold all of the data avail-  
able, this value will be less than the bytes available.  
Device recovery action. The action to take when an I/O error occurs for the inter-  
active job's requesting program device. The possible values are:  
*SYSVAL  
The value in the system value QDEVRCYACN at the time the job is started is  
used as the device recovery action for this job description.  
*MSG  
Signals the I/O error message to the application and lets the application  
program perform error recovery.  
*DSCMSG  
Disconnects the job when an I/O error occurs. When the job reconnects, the  
system sends a message to the application program, indicating the job has  
reconnected and that the workstation device has recovered.  
*DSCENDRQS  
Disconnects the job when an I/O error occurs. When the job reconnects, the  
system sends the End Request (ENDRQS) command to return control to the  
previous request level.  
*ENDJOB  
Ends the job when an I/O error occurs. A message is sent to the job's log  
and to the history log (QHST). This message indicates that the job ended  
because of a device error.  
*ENDJOBNOLIST  
Ends the job when an I/O error occurs. There is no job log produced for the  
job. The system sends a message to the history log (QHST). This message  
indicates that the job ended because of a device error.  
End severity. The message severity level of escape messages that can cause a  
batch job to end. The batch job ends when a request in the batch input stream  
sends an escape message, whose severity is equal to or greater than this value, to  
the request processing program. The possible values are from 0 through 99.  
Hold on job queue. Whether jobs using this job description are put on the job  
queue in the hold condition. The possible values are *YES and *NO.  
Initial library list. The initial library list that is used for jobs that use this job  
description. Only the libraries in the user portion of the library list are included.  
Note: The data is an array of 11-byte entries, each entry consisting of a 10-byte  
library name left-justified with a blank pad at the end. The 11-byte entries  
can be easily used in CL commands. The number of libraries in the initial  
library list tells how many entries are contained in the array.  
3-32 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Inquiry message reply. How inquiry messages are answered for jobs that use  
this job description.  
*RQD  
*DFT  
The job requires an answer for any inquiry messages that occur while  
the job is running.  
The system uses the default message reply to answer any inquiry mes-  
sages issued while the job is running. The default reply is either  
defined in the message description or is the default system reply.  
*SYSRPYL The system reply list is checked to see if there is an entry for an  
inquiry message issued while the job is running. If a match occurs, the  
system uses the reply value for that entry. If no entry exists for that  
message, the system uses an inquiry message.  
Job date. The date that will be assigned to jobs using this job description when  
they are started. The possible values are:  
*SYSVAL  
The value in the QDATE system value is used at the time the job is started.  
job-date  
The date to be used at the time the job is started. This date is in the format  
specified for the DATFMT job attribute.  
Job description library name. The name of the library in which the job  
description resides.  
Job description name. The name of the job description about which information  
is being returned.  
Job message queue maximum size. The maximum size (in megabytes) of the  
job message queue. The possible values are:  
0
The maximum size set by system value QJOBMSGMX at the time the  
job is started.  
2–64  
The maximum size of the job message queue in megabytes.  
Job message queue full action. The action taken when the job message queue  
becomes full. The possible values are:  
*SYSVAL The value is specified by the system value QJOBMSGQFL.  
*NOWRAP  
When the message queue becomes full, do not wrap. This action will  
cause the job to end.  
*WRAP  
When the message queue becomes full, wrap to the beginning and start  
filling again.  
*PRTWRAP  
When the message queue becomes full, wrap the job queue and print  
the messages that are being overlaid.  
Job queue library name. The library of the job queue into which batch jobs using  
this job description are placed.  
Job queue name. The name of the job queue into which batch jobs using this job  
description are placed.  
Job queue priority. The scheduling priority of each job that uses this job  
description. The highest priority is 1 and the lowest priority is 9.  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-33  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Job switches. The initial settings for a group of eight job switches used by jobs  
that use this job description. These switches can be set or tested in a program and  
used to control a program's flow. The possible values are '0' (off) and '1' (on).  
Length of request data. The length of all available request data, in bytes. If the  
receiver variable was not sufficiently large to hold all of the request data available,  
the amount of request data actually returned may be less than this value.  
Logging of CL programs. Whether or not messages are logged for CL programs  
that are run. The possible values are *YES and *NO.  
Message logging level. The type of information logged. Possible types are:  
0
1
No messages are logged.  
All messages sent to the job's external message queue with a severity greater  
than or equal to the message logging severity are logged.  
The following information is logged:  
2
Ÿ Level 1 information.  
Ÿ Requests or commands from CL programs for which the system issues  
messages with a severity code greater than or equal to the logging  
severity.  
Ÿ All messages associated with those requests or commands that have a  
severity code greater than or equal to the logging severity.  
The following information is logged:  
3
4
Ÿ Level 1 information.  
Ÿ All requests or commands from CL programs.  
Ÿ All messages associated with those requests or commands that have a  
severity greater than or equal to the logging severity.  
The following information is logged:  
Ÿ All requests or commands from CL programs.  
Ÿ All messages with a severity code greater than or equal to the logging  
severity.  
Message logging severity. The minimum severity level that causes error mes-  
sages to be logged in the job log. The possible values are from 0 through 99.  
Message logging text. The level of message text that is written in the job log or  
displayed to the user when an error message is created according to the logging  
level and logging severity. The possible values are:  
*MSG  
Only the message is written to the job log.  
*SECLVL  
Both the message and the message help for the error message are written to  
the job log.  
*NOLIST  
If the job ends normally, there is no job log. If the job ends abnormally (the  
job end code is 20 or higher), there is a job log. The messages appearing in  
the job's log contain both the message and the message help.  
Number of libraries in initial library list. The number of libraries in the user  
portion of the initial library list. Up to 25 libraries can be specified.  
Offset to initial library list. The offset from the beginning of the structure to the  
start of the initial library list.  
3-34 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Offset to request data. The offset from the beginning of the structure to the start  
of the request data.  
Output queue library name. The name of the library in which the output queue  
resides.  
Output queue name. The name of the default output queue that is used for  
spooled output produced by jobs that use this job description.  
*USRPRF The output queue name for jobs using this job description is obtained  
from the user profile of the job at the time the job is started.  
*DEV  
The output queue with the same name as the printer device for this job  
description is used.  
*WRKSTN The output queue name is obtained from the device description from  
which this job is started.  
output-queue-name  
The name of the output queue for this job description.  
Output queue priority. The output priority for spooled files that are produced by  
jobs using this job description. The highest priority is 1, and the lowest priority is 9.  
Print text. The line of text (if any) that is printed at the bottom of each page of  
printed output for jobs using this job description. If the special value *SYSVAL is  
specified, the value in the system value QPRTTXT is used for jobs using this job  
description.  
Printer device name. The name of the printer device or the source for the name  
of the printer device that is used for all spooled files created by jobs that use this  
job description.  
*USRPRF  
The printer device name is obtained from the user profile of the job at the  
time the job is started.  
*SYSVAL  
The value in the system value QPRTDEV at the time the job is started is used  
as the printer device name.  
*WRKSTN  
The printer device name is obtained from the work station where the job was  
started.  
printer-device-name  
The name of the printer device that is used with this job description.  
Request data. The request data that is placed as the last entry in the job's  
message queue for jobs that use this job description. The possible values are:  
*NONE  
No request data is placed in the job's message queue.  
*RTGDTA  
The data specified in the routing data parameter is placed as the last entry in  
the job's message queue.  
request-data  
The request data to use for jobs that use this job description.  
Reserved. An ignored field.  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-35  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Routing data. The routing data that is used with this job description to start jobs.  
The possible values are:  
QCMDI  
The default routing data QCMDI is used by the IBM-supplied interactive sub-  
system to route the job to the IBM-supplied control language processor  
QCMD in the QSYS library.  
*RQSDTA  
Up to the first 80 characters of the request data specified in the request data  
field are used as the routing data for the job.  
routing-data  
The routing data to use for jobs that use this job description.  
Syntax check severity. Whether requests placed on the job's message queue  
are checked for syntax as CL commands, and the message severity that causes a  
syntax error to end processing of a job. The possible values are:  
-1  
The request data is not checked for syntax as CL commands. This is  
equivalent to *NOCHK.  
0–99  
Specifies the lowest message severity that causes a running job to end.  
The request data is checked for syntax as CL commands, and, if a syntax  
error occurs that is greater than or equal to the error message severity  
specified here, the running of the job that contains the erroneous  
command is suppressed.  
Text description. The user text, if any, used to briefly describe the job  
description.  
Time-slice end pool. Whether interactive jobs using this job description should be  
moved to another main storage pool when they reach time-slice end. The possible  
values are:  
*SYSVAL The system value is used.  
*NONE  
*BASE  
The job is not moved when it reaches time-slice end.  
The job is moved to the base pool when it reaches time-slice end.  
User name. The name of the user profile associated with this job description. If  
*RQD is specified, a user name is required to use the job description.  
Error Messages  
CPF1618 E Job description &1 in library &2 damaged.  
CPF24B4 E Severe error while addressing parameter list.  
CPF3CF1 E Error code parameter not valid.  
CPF3CF2 E Error(s) occurred during running of &1 API.  
CPF3C21 E Format name &1 is not valid.  
CPF3C24 E Length of the receiver variable is not valid.  
CPF9801 E Object &2 in library &3 not found.  
CPF9802 E Not authorized to object &2 in &3.  
CPF9803 E Cannot allocate object &2 in library &3.  
CPF9804 E Object &2 in library &3 damaged.  
CPF9807 E One or more libraries in library list deleted.  
CPF9808 E Cannot allocate one or more libraries on library list.  
CPF9810 E Library &1 not found.  
CPF9820 E Not authorized to use library &1.  
CPF9830 E Cannot assign library &1.  
3-36 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.  
Chapter 3. Common Information across APIs—Basic (OPM) Example 3-37  
Download from Www.Somanuals.com. All Manuals Search And Download.  
3-38 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Chapter 4. Common Information across APIs—Advanced  
(ILE) Example  
Through the use of several examples, this chapter provides information about how  
to use more advanced or more complex API concepts in your programs. The  
example programs in this chapter use ILE APIs. These examples are also shown  
in additional languages in “Integrated Language Environment (ILE)  
APIs—Examples” on page B-47.  
In the examples, the following are focus items:  
Ÿ Header files  
Ÿ Keyed interfaces  
Ÿ Error handling  
Ÿ Receiver variables  
For more information about the APIs used in this chapter, refer to the System API  
Reference, SC41-5801.  
Integrated Language Environment (ILE) APIs—Introduction  
OS/400 Integrated Language Environment (ILE) APIs are contained within service  
programs that the calling program binds to. In addition, some OS/400 ILE APIs  
provide a program interface for the original program model (OPM) languages. You  
can usually distinguish between the *SRVPGM interface and the *PGM interface by  
the name of the API. For example, the registration facility APIs provide both a  
program and a service program entry point (procedure) interface. For the Register  
Exit Point API, the service program entry point interface is named  
QusRegisterExitPoint and the program interface is named QUSRGPT. A bindable  
procedure name can be up to 30 characters and mixed uppercase and lowercase.  
A program interface name can be up to 8 characters and is all uppercase.  
A binding directory is used for OS/400 ILE APIs that are contained in service pro-  
grams. A binding directory is a list of names of modules and service programs  
that provides a reference by name and type. Service programs that contain  
OS/400 ILE APIs are in the QUSAPIBD binding directory. This binding directory is  
implicitly used by ILE compilers to resolve the OS/400 ILE API references; there-  
fore, it is not necessary to explicitly name the service program or the API binding  
directory when creating programs that use OS/400 ILE APIs. If you provide your  
own APIs with the same name, make sure that you also provide your own binding  
directory or service program.  
All OS/400 APIs (ILE and non-ILE) have a header file supplied by OS/400. These  
header files reside in the optionally installable library QSYSINC. The header files  
provide the prototypes for the API as well as define any structures that are used by  
the API. The QSYSINC library is used by the ILE C compiler to search for header  
files; therefore, it is not necessary to specify a library qualifier for any header files  
that reside in the QSYSINC library. When coding in ILE C, remember to enclose  
the header file name in less-than (<) and greater-than (>) symbols because this  
affects how the library list is processed in locating the header file.  
Copyright IBM Corp. 1997  
4-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
The example APIs in this chapter represent two general functions of APIs—change  
and retrieve. It is typical for an API that is not retrieving information not to return  
any output to the caller other than the error code parameter. If an error did not  
occur when using APIs, the requested function completed successfully.  
The presentation of the ILE APIs in the System API Reference is similar to the  
OPM APIs. For a general discussion of the API topics, see “Description of an API”  
on page 3-2.  
Registration Facility Using ILE APIs—Concepts  
The following examples illustrate the use of OS/400 ILE APIs. The examples use  
the registration facility APIs. The registration facility APIs provide a means for  
storing and retrieving information about exit points and exit programs. An exit  
point is a specific point in a system function or program where control may be  
passed to one or more exit programs. An exit program is a program to which  
control is passed from an exit point. The examples show how to manipulate exit  
points and exit programs, how to retrieve information about exit points and exit pro-  
grams that are stored with the registration facility, and how to call an exit program.  
Several of the registration facility APIs manipulate the information that the registra-  
tion facility repository contains. One API is provided for retrieving information from  
the repository.  
The example programs are provided at the end of this chapter in their entirety (see  
“Registration Facility Using ILE APIs—Examples” on page 4-9). The example  
makes use of a continuation handle. Following are portions of the code to help  
illustrate concepts pertaining to the use of OS/400 ILE APIs. The following con-  
cepts include:  
Ÿ Various types of header files  
Ÿ The use of keyed interfaces  
Ÿ Error handling and the error code parameter  
Ÿ The use of receiver variables for returned information  
Generic Header Files  
This topic shows how to use a generic header file from the QSYSINC (system  
include) library in a program. For information about the QSYSINC header files, see  
“APIs and the QSYSINC Library” on page 2-28.  
In addition to the traditional C-library header files (such as stdio and string), the API  
header file qusrgfa1.h is included in the following example. The qusrgfa1.h header  
file defines the functions exported from service program QUSRGFA1. This service  
program contains the APIs provided for manipulating the information in the reposi-  
tory. A second service program named QUSRGFA2 contains the ILE API for  
retrieving information from the registration facility repository. The header file  
qusec.h contains the definition for the error code structure that is used for the error  
code parameter. The following list shows the standard C header files (the first four  
includes) and a few AS/400-defined header files for APIs. This list does not show  
all the header files used in the example programs starting on page 4-9.  
4-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
#include <stdio.h>  
#include <signal.h>  
#include <string.h>  
#include <stdlib.h>  
#include <qusrgfa1.h>  
#include <qusec.h>  
Variable-Length Structure—Example  
Many of the structures needed are provided by the QSYSINC (system include)  
library. However, any fields of a structure that are variable in length are not defined  
by QSYSINC and must be defined by the user. For example, in the qusec.h  
header file, the structure Qus_EC_t is defined as:  
typedef struct Qus_EC {  
int Bytes_Provided;  
int Bytes_Available;  
char Exception_Id[7];  
char Reserved;  
/ᑍchar Exception_Data[]; .1/ᑍ/ /ᑍ Varying length field ᑍ/  
} Qus_EC_t;  
Because the Exception_Data field .1/ is a varying-length field, it is shown as a  
comment. The following is a new error code structure, which defines the  
exception_data field .2/. It was created by using the structure that was defined in  
the qusec.h header file.  
typedef struct {  
Qus_EC_t ec_fields;  
char  
exception_data[1ðð].2/;  
} error_code_struct;  
Within QSYSINC include files, all varying-length fields and arrays are in the form of  
comments so that you can control how much storage to allocate based on your  
specific requirements.  
Keyed Interface—Example  
This example shows how to set key values for a keyed interface.  
Exit Program Attributes Parameter  
The interface for the Add Exit Program API is a keyed interface. One of the param-  
eters for the Add Exit Program API is the exit program attributes parameter. The  
exit program attributes are provided to the API by means of a variable-length  
record. Typically, APIs that use a variable-length record interface use either a 3- or  
4-field record. The Add Exit Program API makes use of a 4-field variable-length  
record .4/. The exit program attributes parameter for the API is defined as follows:  
.3/  
Type  
Field  
BINARY(4)  
Number of variable-length records  
.4/  
Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Type  
Field  
BINARY(4)  
BINARY(4)  
BINARY(4)  
CHAR(*)  
Length of variable-length record  
Exit program attribute key  
Length of data  
Data  
The number of variable-length records field .3/ is the first 4 bytes, and this field  
tells the API how many variable-length records have been specified. The fields  
defined in .4/ are repeated (contiguously) immediately following the number of  
variable-length records for each record that is sent to the API. The API gets to  
each variable-length record by using the length of variable-length record field to get  
to the next record, up to and including the number of records specified.  
The variable-length record structures are defined in the qus.h header file (this  
C-language header file is included by the qusrgfa1.h header file). The 4-field  
variable-length record is defined as:  
typedef _Packed struct Qus_Vlen_Rec_4 {  
int Length_Vlen_Record;  
int Control_Key;  
int Length_Data;  
/ᑍchar Data[];ᑍ/  
/ᑍ Varying length field ᑍ/  
} Qus_Vlen_Rec_4_t;  
Because the data field is a varying-length field, it needs to be defined in a new  
structure.  
Exit Program Attribute Keys  
The Add Exit Program API has several exit program attributes that can be set. The  
following table shows the valid exit program attribute keys for the key field area of  
the variable-length record.  
Key  
Type  
Field  
1
CHAR(27)  
Qualified message file name and message identifier for exit  
program description  
2
3
4
CHAR(50)  
BINARY(4)  
CHAR(1)  
Exit program text description  
Exit program data CCSID  
Replace  
This example specifies only two attribute keys (replace_rec and CCSID_rec fields)  
and lets the remaining attribute keys be set by the API to the default value. When  
working with variable-length structures, each variable-length record must start on a  
4-byte boundary alignment. (The 4-byte boundary alignment requirement is only  
true for the registration facility APIs, not all keyed APIs.) The following new struc-  
ture becomes the exit program attributes parameter on the call to the Add Exit  
Program API:  
typedef struct {  
int  
num_rec;  
Qus_Vlen_Rec_4_t replace_rec;  
char  
char  
replace;  
Reserved[3];  
4-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Qus_Vlen_Rec_4_t CCSID_rec;  
int  
CCSID;  
} addep_attributes;  
The num_rec field is set to the value of 2 because the example specifies two  
variable-length records. The replace_rec field contains the length of the variable-  
length record (value of 16), the key (value of 4), and the length of the data (value of  
1). The replace field contains the data for the replace key. The Reserved field  
reserves 3 bytes to force the next record to start on a 4-byte boundary alignment.  
The 3 bytes that are reserved are counted as part of the length for the replace  
variable-length record. The next record then follows the first record.  
Error Handling  
Error handling with ILE APIs can be accomplished in two ways: use the error code  
parameter or have exceptions signaled by the API to your application program.  
Error Handling through the Error Code Parameter  
The error code parameter enables a user to have exceptions returned to the  
program through the use of the parameter instead of having the exceptions sig-  
naled. Some exceptions may be signaled to the caller regardless of the size of the  
error code parameter. These exceptions are usually from errors that occur with the  
error code parameter itself (that is, message CPF3CF1) or with one of the other  
parameters (that is, message CPF9872). In the latter case, message CPF9872 is  
always signaled and never returned through the error code parameter because the  
API is unable to verify the error code parameter before the exception occurs.  
The caller of the API must initialize the error code parameter so that the bytes pro-  
vided field is set to the size, in bytes, of the error code parameter. For example,  
the error_code_struct structure on page 4-3 sets the size at 116 bytes. To initialize  
the error code parameter, do the following:  
1. Allocate storage for the error code parameter:  
error_code_struct error_code;  
2. Initialize the bytes provided field to the number of bytes that were allocated for  
the parameter:  
error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);  
If the bytes provided field is set to a value equal to or greater than 8, the caller  
wants all exceptions returned through the error code parameter. The API fills in all  
of the message information up to the size of the error code parameter.  
Error Determination—Example: On the return from the call to the API, verify  
whether or not an error occurred. If an error occurred, the bytes available field is  
set to something other than zero. If the bytes available field is not zero, you can  
use the message ID and the message data to determine what the program should  
do next. To receive the message ID and data, you must provide enough storage  
on the error code parameter for the information.  
In the following example, the bytes available field is checked to determine if an  
error occurred. In this case, if an error occurred, a message is printed, which  
states the message ID and that the call to the API failed.  
Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-5  
Download from Www.Somanuals.com. All Manuals Search And Download.  
if (error_code.ec_fields.Bytes_Available != ð)  
{
printf("ATTEMPT TO REGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
Message Data—Example: If your program needs to handle different exceptions in  
different ways, you may need to make use of both the message data and the  
message ID. The message data is returned in the same format as when you  
display the message description on an AS/400. For example, if message  
CPF3C1E is received, some of the message data is printed. You can see  
message data that is associated with the message by using the Display Message  
Description (DSPMSGD) command. The message data for message CPF3C1E is  
defined as:  
BIN(4)  
Parameter number  
CHAR(256)  
ILE entry point name  
To receive all of the message data for this exception, the exception data field of the  
error code structure would need to be at least 260 bytes in size. The following  
example uses only the number of bytes shown for the parameter number of the  
exception in the message data; therefore, the exception data field only needs to be  
4 bytes.  
int parm_number;  
char ᑍtemp_ptr;  
if (error_code.ec_fields.Bytes_Available != ð)  
{
if (memcmp(error_code.ec_fields.Exception_Id,"CPF3C1E",7)==ð)  
{
printf("\nFAILED WITH CPF3C1E:");  
temp_ptr=&(error_code.exception_data);  
parm_number=ᑍ((int ᑍ)temp_ptr);  
printf("\n Parameter number omitted: %d",parm_number);  
}
else  
{
printf("ATTEMPT TO REGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
}
Error Handling Signaled by API  
The second means of exception handling is by having all exceptions signaled by  
the API to the calling program. To have all exceptions signaled by the API, set the  
bytes provided field of the error code structure to zero. Refer to the documentation  
of your specific programming language for information on exception handling.  
4-6 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Receiver Variables—Examples  
As discussed in “Receiver Variables” on page 2-23, receiver variables are generally  
used by retrieve APIs to return information to a caller. This topic provides coding  
examples of repeating entry types and of the use of offsets to go from one entry to  
the next in the receiver variable.  
Repeating Entry Type with Fixed-Length Fields—Example  
In the following example, the EXTI0100 format is defined in the qusreg.h header  
file, which is included by the qusrgfa2.h header file in the QSYSINC library.  
This format is of the repeating entry type with all fixed-length fields. The repeating  
portion of the format (Qus_EXTI0100_Entry_t) is repeated after the fixed portion.  
The fixed portion of the format (Qus_EXTI0100_t) is returned only once. To go  
from one entry to the next, you add the offset exit point entry field to the starting  
position of the receiver variable to get to the first entry. Add the length exit point  
entry field to the current position in the receiver variable to move to the subsequent  
entries.  
typedef _Packed struct Qus_EXTIð1ðð_Entry {  
char Exit_Point_Name[2ð];  
char Format_Name[8];  
int Max_Exit_Programs;  
int Number_Exit_Programs;  
char Allow_Deregistration;  
char Allow_Change_Control;  
char Registered_Exit_Point;  
char Prep_Name_Add_Pgm[1ð];  
char Prep_Lib_Add_Pgm[1ð];  
char Prep_Format_Add[8];  
char Prep_Name_Rmv_Pgm[1ð];  
char Prep_Lib_Rmv_Pgm[1ð];  
char Prep_Format_Rmv[8];  
char Prep_Name_Rtv_Info[1ð];  
char Prep_Lib_Rtv_Info[1ð];  
char Prep_Format_Rtv[8];  
char Desc_Indicator;  
char Desc_Msg_File[1ð];  
char Desc_Msg_Library[1ð];  
char Desc_Msg_Id[7];  
char Text_Description[5ð];  
/ᑍchar Reserved[];ᑍ/  
} Qus_EXTIð1ðð_Entry_t;  
typedef _Packed struct Qus_EXTIð1ðð {  
int Bytes_Returned;  
int Bytes_Available;  
char Continue_Handle[16];  
int Offset_Exit_Point_Entry;  
int Number_Points_Returned;  
int Length_Exit_Point_Entry;  
/ᑍchar Reserved[];ᑍ/  
/ᑍQus_EXTIð1ðð_Entry_t Array[];ᑍ/  
} Qus_EXTIð1ðð_t;  
Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-7  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Repeating Entry Type with Variable-Length Fields—Example  
In this example, the EXTI0200 format is defined in the qusreg.h header file, which  
is included by the qusrgfa2.h header file in the QSYSINC library.  
This format is of the repeating entry type with some variable-length fields. The  
repeating portion of the format (Qus_EXTI0200_Entry_t) is repeated for each entry  
returned, and the fixed portion of the format (Qus_EXTI0200_t) is returned only  
once. To go from one entry to the next, you add the offset program entry field to  
the starting position of the receiver variable to get to the first entry. Then add the  
offset next entry field to the starting position of the receiver variable to get to each  
subsequent entry. To get to the Prog_Data field, add the offset exit data field to  
the starting position of the receiver variable and use the length exit data field to  
determine the number of bytes of information in the Prog_Data field.  
typedef _Packed struct Qus_EXTIð2ðð_Entry {  
int Offset_Next_Entry;  
char Exit_Point_Name[2ð];  
char Format_Name[8];  
char Registered_Exit_Pt;  
char Complete_Entry;  
char Reserved[2];  
int Program_Number;  
char Program_Name[1ð];  
char Program_Library[1ð];  
int Data_Ccsid;  
int Offset_Exit_Data;  
int Length_Exit_Data;  
/ᑍchar Reserved[];ᑍ/  
/ᑍQus_Program_Data_t Prog_Data;ᑍ/  
} Qus_EXTIð2ðð_Entry_t;  
typedef _Packed struct Qus_EXTIð2ðð {  
int Bytes_Returned;  
int Bytes_Available;  
char Continue_Handle[16];  
int Offset_Program_Entry;  
int Number_Programs_Returned;  
int Length_Program_Entry;  
/ᑍchar Reserved[];ᑍ/  
/ᑍQus_EXTIð2ðð_Entry_t Array[];ᑍ/  
} Qus_EXTIð2ðð_t;  
Offsets Type—Example: The following portion of code illustrates the use of the  
offsets to go from one entry to the next in the receiver variable:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Save the number of exit programs returned, and set the pointer ᑍ/  
/ᑍ to point to the first exit program entry.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
rcv_ptr=rcv_var;  
num_exit_pgms=((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)→Number_Programs_Returned;  
rcv_ptr += ((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)→Offset_Program_Entry;  
rsl_ok=1;  
for (i=ð; i<num_exit_pgms; i++)  
{
memcpy(exit_pgm_name,  
((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Program_Name,1ð);  
4-8 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
memcpy(exit_pgm_lib,  
((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Program_Library,1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Resolve to the exit program. If an error occurs on the  
/ᑍ resolve operation to the library, the rsl_ok indicator is  
/ᑍ set to failed in the RSL_PGM_HDLR exception handler.  
/ᑍ The RSLVSP MI instruction signals all errors to this  
/ᑍ program; therefore, enable the exception handler to  
/ᑍ capture any errors that may occur.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#pragma exception_handler (RSLVSP_PGM_HDLR,rsl_ok,ð,_C2_MH_ESCAPE)  
exit_pgm_ptr=((Pgm_OS ᑍ)rslvsp(_Program,  
exit_pgm_name,  
exit_pgm_lib,  
_AUTH_POINTER));  
#pragma disable_handler  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If the resolve is successful, call the exit program.  
/ᑍ If not, move on to the next exit program.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (rsl_ok)  
{
exit_pgm_ptr(info_for_exit_pgm);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the receiver variable to point to the next exit program ᑍ/  
/ᑍ that is returned.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
rsl_ok=1;  
rcv_ptr=rcv_var +  
((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Offset_Next_Entry;  
}
Registration Facility Using ILE APIs—Examples  
Following are the entire program listings for the ILE C programs discussed in the  
preceding topics. The programs perform the following tasks:  
Ÿ Register an exit point and add an exit program  
Ÿ Retrieve exit point and exit program information  
Ÿ Remove an exit program and deregister an exit point  
These example programs are also shown in additional languages in “Integrated  
Language Environment (ILE) APIs—Examples” on page B-47.  
Register Exit Point and Add Exit Program—ILE C Example  
The following program registers an exit point with the registration facility and adds  
an exit program to the exit point.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ PROGRAM:  
Register an Exit Point  
Add an Exit Program  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ  
/ᑍ LANGUAGE:  
ILE C  
Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-9  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ DESCRIPTION: This program registers an exit point with the  
/ᑍ  
registration facility. After the successful  
/ᑍ  
completion of the registration of the exit point, ᑍ/  
an exit program is added to the exit point.  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ APIs USED:  
QusRegisterExitPoint - Register Exit Point  
/ᑍ  
/ᑍ  
QusAddExitProgram  
- Add Exit Program  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ NOTE: This example uses APIs that are shipped with ᑍEXCLUDE ᑍ/  
authority. The user needs ᑍUSE authority to the service ᑍ/  
program QUSRGFA1 to use these APIs. ᑍ/  
/ᑍ  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Includes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <signal.h>  
#include <string.h>  
#include <stdlib.h>  
#include <qusrgfa1.h>  
#include <qusec.h>  
#include <qliept.h>  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Structures  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
/ᑍ Error code  
ᑍ/  
Qus_EC_t ec_fields;  
char  
exception_data[1ðð];  
} error_code_struct;  
typedef struct {  
/ᑍ Exit point control keys  
ᑍ/  
int  
num_rec;  
Qus_Vlen_Rec_4_t max_pgms_rec;  
int  
max_pgms;  
Qus_Vlen_Rec_4_t descrip_rec;  
char  
} rgpt_controls;  
text_desc[5ð];  
typedef struct {  
int  
/ᑍ Exit program attribute keysᑍ/  
num_rec;  
Qus_Vlen_Rec_4_t replace_rec;  
char  
char  
replace;  
Reserved[3];  
Qus_Vlen_Rec_4_t CCSID_rec;  
int  
CCSID;  
} addep_attributes;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
main  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
4-10 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
int main()  
{
int ccsid,  
pgm_num,  
num_of_attrs,  
epgm_num,  
len_epgm_data,  
add_epgm_num,  
ᑍccsid_ptr,  
ᑍpgm_num_ptr;  
error_code_struct error_code;  
rgpt_controls control_keys;  
addep_attributes attrib_keys;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Register the exit point with the registration facility. If the ᑍ/  
/ᑍ registration of the exit point is successful, add an exit  
/ᑍ program to the exit point.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize the error code parameter. To signal exceptions to ᑍ/  
/ᑍ this program by the API, you need to set the bytes provided  
/ᑍ field of the error code to zero. Because this program has  
ᑍ/  
ᑍ/  
/ᑍ exceptions sent back through the error code parameter, it sets ᑍ/  
/ᑍ the bytes provided field to the number of bytes that it gives ᑍ/  
/ᑍ the API for the parameter.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the exit point controls. Each control field is passed to ᑍ/  
/ᑍ the API using a variable length record. Each record must  
/ᑍ start on a 4-byte boundary.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the total number of controls that are being specified on ᑍ/  
/ᑍ the call. This program lets the API take the default for the ᑍ/  
/ᑍ controls that are not specified.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
control_keys.num_rec=2;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the values for the two controls that are specified:  
/ᑍ Maximum number of exit programs = 1ð  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Exit point text description  
= "EXIT POINT EXAMPLE"  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
control_keys.max_pgms_rec.Length_Vlen_Record=16;  
control_keys.max_pgms_rec.Control_Key=3;  
control_keys.max_pgms_rec.Length_Data=4;  
control_keys.max_pgms=1ð;  
control_keys.descrip_rec.Length_Vlen_Record=62;  
control_keys.descrip_rec.Control_Key=8;  
control_keys.descrip_rec.Length_Data=5ð;  
memcpy(control_keys.text_desc,  
"EXIT POINT EXAMPLE  
",5ð);  
Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-11  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the API to register the exit point.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QusRegisterExitPoint("EXAMPLE_EXIT_POINT ",  
"EXMPð1ðð",  
&control_keys,  
&error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If an exception occurs, the API returns the exception in the ᑍ/  
/ᑍ error code parameter. The bytes available field is set to  
ᑍ/  
/ᑍ zero if no exception occurs and nonzero if an exception does ᑍ/  
/ᑍ occur.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (error_code.ec_fields.Bytes_Available != ð)  
{
printf("ATTEMPT TO REGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If the call to register an exit point is successful, add  
/ᑍ an exit program to the exit point.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the total number of exit program attributes that are being ᑍ/  
/ᑍ specified on the call. This program lets the API take the  
/ᑍ default for the attributes that are not specified. Each  
/ᑍ attribute record must be 4-byte aligned.  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
attrib_keys.num_rec=2;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the values for the two attributes that are being  
/ᑍ specified:  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ  
Replace exit program  
= 1  
Exit program data CCSID = 37  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
attrib_keys.replace_rec.Length_Vlen_Record=16;  
attrib_keys.replace_rec.Control_Key=4;  
attrib_keys.replace_rec.Length_Data=1;  
attrib_keys.replace='1';  
attrib_keys.CCSID_rec.Length_Vlen_Record=16;  
attrib_keys.CCSID_rec.Control_Key=3;  
attrib_keys.CCSID_rec.Length_Data=4;  
attrib_keys.CCSID=37;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the API to add the exit program.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QusAddExitProgram("EXAMPLE_EXIT_POINT ",  
"EXMPð1ðð",  
1,  
4-12 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
"EXAMPLEPGMEXAMPLELIB",  
"EXAMPLE EXIT PROGRAM DATA",  
25,  
&attrib_keys,  
&error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If an exception occurs, the API returns the exception in the ᑍ/  
/ᑍ error code parameter. The bytes available field is set to  
ᑍ/  
/ᑍ zero if no exception occurs and nonzero if an exception does ᑍ/  
/ᑍ occur.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (error_code.ec_fields.Bytes_Available != ð)  
{
printf("ATTEMPT TO ADD AN EXIT PROGRAM FAILED WITH EXCEPTION: %.7s",  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
} /ᑍ End program ᑍ/  
Retrieve Exit Point and Exit Program Information—ILE C Example  
The following program retrieves information about exit points and exit programs. It  
then resolves to each exit program and calls the exit program.  
The Retrieve Exit Information API returns a continuation handle when it has more  
information to return than what fits in the receiver variable. For more information  
about continuation handles, see “Continuation Handle” on page 2-25.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ PROGRAM:  
Retrieve Exit Point and Exit Program Information ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ LANGUAGE:  
/ᑍ  
ILE C  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ DESCRIPTION: This program retrieves exit point and exit  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
program information. After retrieving the  
exit point information, the program resolves to ᑍ/  
each associated exit program and calls each exit ᑍ/  
program.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ APIs USED: QusRetrieveExitInformation - Retrieve Exit  
/ᑍ  
/ᑍ  
Information  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Includes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <signal.h>  
#include <string.h>  
#include <stdlib.h>  
#include <except.h>  
#include <qusrgfa2.h>  
#include <qusec.h>  
#include <qmhchgem.h>  
Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-13  
Download from Www.Somanuals.com. All Manuals Search And Download.  
#include <miptrnam.h>  
#include <qliept.h>  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Prototypes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef void Pgm_OS(void ᑍarg,...);  
#pragma linkage(Pgm_OS,OS)  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Structures  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
/ᑍ Error code  
ᑍ/  
Qus_EC_t ec_fields;  
char  
exception_data[1ðð];  
} error_code_struct;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ FUNCTION NAME: RSLVSP_PGM_HDLR  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ FUNCTION :  
This function handles all exceptions that  
/ᑍ  
may occur while resolving to the exit  
program.  
/ᑍ  
/ᑍ  
/ᑍ INPUT:  
Interrupt handler information  
NONE  
/ᑍ  
/ᑍ OUTPUT:  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void RSLVSP_PGM_HDLR(_INTRPT_Hndlr_Parms_T ᑍerrmsg)  
{
error_code_struct Error_Code;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the rsl_ok indicator to not valid.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
int ᑍrsl_ok = (int ᑍ)(errmsg→Com_Area);  
ᑍrsl_ok = ð;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Let message handler know that the program handled the message ᑍ/  
/ᑍ and to remove it from the job log.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
Error_Code.ec_fields.Bytes_Provided=ð;  
QMHCHGEM(&(errmsg→Target),  
ð,  
(char ᑍ)&errmsg→Msg_Ref_Key,  
"ᑍREMOVE ",  
"",  
ð,  
&Error_Code);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ FUNCTION NAME: Call_Exit_Program  
/ᑍ  
ᑍ/  
ᑍ/  
4-14 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ FUNCTION :  
This function calls the exit programs that  
ᑍ/  
/ᑍ  
were retrieved from the registration facility ᑍ/  
/ᑍ  
/ᑍ  
repository.  
Information retrieved  
NONE  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ INPUT:  
/ᑍ  
/ᑍ OUTPUT:  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void Call_Exit_Program(char ᑍrcv_var)  
{
int num_exit_pgms,  
i;  
char exit_pgm_name[1ð],  
exit_pgm_lib[1ð],  
info_for_exit_pgm[1ð],  
ᑍrcv_ptr;  
volatile int rsl_ok;  
Pgm_OS ᑍexit_pgm_ptr;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Save the number of exit programs returned and set the pointer ᑍ/  
/ᑍ to point to the first exit program entry.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
rcv_ptr=rcv_var;  
num_exit_pgms=((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)→Number_Programs_Returned;  
rcv_ptr += ((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)→Offset_Program_Entry;  
rsl_ok=1;  
for (i=ð; i<num_exit_pgms; i++)  
{
memcpy(exit_pgm_name,  
((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Program_Name,1ð);  
memcpy(exit_pgm_lib,  
((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Program_Library,1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Resolve to the exit program. If an error occurs on the  
/ᑍ resolve operation to the library, the rsl_ok indicator is  
/ᑍ set to failed in the RSL_PGM_HDLR exception handler.  
/ᑍ The rslvsp MI instruction signals all errors to this  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ program; therefore, enable the exception handler to capture ᑍ/  
/ᑍ any errors that may occur. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#pragma exception_handler (RSLVSP_PGM_HDLR,rsl_ok,ð,_C2_MH_ESCAPE)  
exit_pgm_ptr=((Pgm_OS ᑍ)rslvsp(_Program,  
exit_pgm_name,  
exit_pgm_lib,  
_AUTH_POINTER));  
#pragma disable_handler  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If the resolve operation is successful, call the exit  
/ᑍ program. If not, move on to the next exit program.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (rsl_ok)  
{
Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-15  
Download from Www.Somanuals.com. All Manuals Search And Download.  
exit_pgm_ptr(info_for_exit_pgm);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the receiver variable to point to the next exit program ᑍ/  
/ᑍ that is returned.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
rsl_ok=1;  
rcv_ptr=rcv_var +  
((Qus_EXTIð2ðð_Entry_t ᑍ)rcv_ptr)→Offset_Next_Entry;  
}
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
main  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void main()  
{
int sel_criteria=ð,  
len_rcv_variable=35ðð,  
exit_pgm_num=-1;  
char continuation_hdl[16],  
rcv_variable[35ðð],  
ᑍrcv_ptr;  
error_code_struct error_code;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Retrieve the exit point information first. If the current  
/ᑍ number of exit programs is not zero, retrieve the exit  
/ᑍ programs. It is not necessary to call for the exit point  
/ᑍ information to determine if the exit point has any exit  
/ᑍ programs. It is done here for illustration purposes only.  
/ᑍ You can make one call to the API for the exit program  
/ᑍ information and check the number of exit program entries  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ returned field to see if there are any exit programs to call. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize the error code to inform the API that all  
ᑍ/  
/ᑍ exceptions should be returned through the error code parameter.ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Blank out the continuation handle to let the API know that thisᑍ/  
/ᑍ is a first attempt at the retrieve operation.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(continuation_hdl,' ',16);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the API to retrieve the exit point information.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QusRetrieveExitInformation(continuation_hdl,  
&rcv_variable,  
len_rcv_variable,  
"EXTIð1ðð",  
4-16 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
"EXAMPLE_EXIT_POINT ",  
"EXMPð1ðð",  
exit_pgm_num,  
&sel_criteria,  
&error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If an exception occurs, the API returns the exception in the ᑍ/  
/ᑍ error code parameter. The bytes available field is set to  
ᑍ/  
/ᑍ zero if no exception occurs and nonzero if an exception does ᑍ/  
/ᑍ occur.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (error_code.ec_fields.Bytes_Available != ð)  
{
printf("ATTEMPT TO RETRIEVE INFORMATION FAILED WITH EXCEPTION: %.7s",  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If the call to retrieve exit point information is successful, ᑍ/  
/ᑍ check to see if there are any exit programs to call.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
rcv_ptr=rcv_variable;  
rcv_ptr += ((Qus_EXTIð1ðð_t ᑍ)rcv_ptr)->Offset_Exit_Point_Entry;  
if (((Qus_EXTIð1ðð_Entry_t ᑍ)rcv_ptr)->Number_Exit_Programs != ð)  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Blank out the continuation handle to let the API know that  
/ᑍ this is a first attempt at the retrieve operation.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(continuation_hdl,' ',16);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the API to retrieve the exit program information.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QusRetrieveExitInformation(continuation_hdl,  
&rcv_variable,  
len_rcv_variable,  
"EXTIð2ðð",  
"EXAMPLE_EXIT_POINT ",  
"EXMPð1ðð",  
exit_pgm_num,  
&sel_criteria,  
&error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Verify that the call to the API is successful.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (error_code.ec_fields.Bytes_Available != ð)  
{
printf("ATTEMPT TO RETRIEVE EXIT PROGRAMS FAILED WITH EXCEPTION:\  
%.7s", error_code.ec_fields.Exception_Id);  
exit(1);  
}
Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-17  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If the call is successful, call the exit programs. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
Call_Exit_Program(rcv_variable);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If the continuation handle field in the receiver variable is ᑍ/  
/ᑍ not set to blanks, the API has more information to return  
/ᑍ than what could fit in the receiver variable.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
rcv_ptr=rcv_variable;  
while (memcmp(((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)->Continue_Handle,  
"
",16)!=ð)  
{
memcpy(continuation_hdl,  
((Qus_EXTIð2ðð_t ᑍ)rcv_ptr)→Continue_Handle,16);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the API to retrieve the exit program information.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QusRetrieveExitInformation(continuation_hdl,  
&rcv_variable,  
len_rcv_variable,  
"EXTIð2ðð",  
"EXAMPLE_EXIT_POINT ",  
"EXMPð1ðð",  
exit_pgm_num,  
&sel_criteria,  
&error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Verify that the call to the API is successful.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (error_code.ec_fields.Bytes_Available != ð)  
{
printf("RETRIEVE EXIT PROGRAMS FAILED WITH EXCEPTION: %.7s",  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If the call is successful, call the exit programs.  
ᑍ/  
/ᑍ The receiver variable offers enough room for a minimum of ᑍ/  
/ᑍ one exit program entry because the receiver variable was  
/ᑍ declared as 35ðð bytes. Therefore, this example only  
ᑍ/  
ᑍ/  
/ᑍ checks the number of exit programs returned field. If the ᑍ/  
/ᑍ receiver variable were not large enough to hold at least  
/ᑍ one entry, the bytes available field would need to be  
/ᑍ checked as well as the number of exit programs returned  
/ᑍ field. If the number of exit programs returned field is  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ set to zero and the bytes available field is greater than ᑍ/  
/ᑍ the bytes returned field, the API had at least one exit  
/ᑍ program entry to return but was unable to because the  
/ᑍ receiver variable was too small.  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
Call_Exit_Program(rcv_variable);  
} /ᑍ While continuation handle not set to blanks ᑍ/  
} /ᑍ Number of exit programs not equal to zero ᑍ/  
4-18 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
} /ᑍ End program ᑍ/  
Remove Exit Program and Deregister Exit Point—ILE C Example  
The following program removes an exit program from an exit point and deregisters  
the exit point from the registration facility.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ PROGRAM:  
Remove an Exit Program  
Deregister an Exit Point  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ  
/ᑍ LANGUAGE:  
/ᑍ  
ILE C  
/ᑍ DESCRIPTION: This program removes an exit program and  
/ᑍ  
deregisters an exit point from the registration ᑍ/  
facility.  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ APIs USED:  
QusRemoveExitProgram - Remove Exit Program  
QusDeregisterExitPoint - Deregister Exit Point  
/ᑍ  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ NOTE: This example uses APIs that are shipped with ᑍEXCLUDE ᑍ/  
authority. The user needs ᑍUSE authority to the service ᑍ/  
program QUSRGFA1 to use these APIs. ᑍ/  
/ᑍ  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Includes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <signal.h>  
#include <string.h>  
#include <stdlib.h>  
#include <qusrgfa1.h>  
#include <qusec.h>  
#include <qliept.h>  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Structures  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
/ᑍ Error code  
ᑍ/  
Qus_EC_t ec_fields;  
char  
exception_data[1ðð];  
} error_code_struct;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
main  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
int main()  
{
int pgm_num=1;  
error_code_struct error_code;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-19  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ Remove an exit program from the exit point and then deregister ᑍ/  
/ᑍ the exit point. It is not necessary to remove exit programs ᑍ/  
/ᑍ from an exit point before deregistering the exit point. It is ᑍ/  
/ᑍ done here only for illustration purposes.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize the error code parameter. To have exceptions  
/ᑍ signaled to this program by the API, set the bytes provided  
ᑍ/  
ᑍ/  
/ᑍ field of the code to zero. This program has exceptions sent ᑍ/  
/ᑍ through the error code parameter; therefore, the bytes ᑍ/  
/ᑍ provided field is set to the number of bytes that this program ᑍ/  
/ᑍ gives the API for the parameter. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the API to remove the exit program.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QusRemoveExitProgram("EXAMPLE_EXIT_POINT ",  
"EXMPð1ðð",  
pgm_num,  
&error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If an exception occurs, the API returns the exception in the ᑍ/  
/ᑍ error code parameter. The bytes available field is set to  
ᑍ/  
/ᑍ zero if no exception occurs and nonzero if an exception does ᑍ/  
/ᑍ occur.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (error_code.ec_fields.Bytes_Available != ð)  
{
printf("ATTEMPT TO REMOVE EXIT PROGRAM FAILED WITH EXCEPTION: %.7s",  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If the call to remove the exit program is successful,  
/ᑍ deregister the exit point.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the API to add the exit program.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QusDeregisterExitPoint("EXAMPLE_EXIT_POINT ",  
"EXMPð1ðð",  
&error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If an exception occurs, the API returns the exception in the ᑍ/  
/ᑍ error code parameter. The bytes available field is set to  
/ᑍ zero if no exception occurs and nonzero if an exception does ᑍ/  
/ᑍ occur. ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (error_code.ec_fields.Bytes_Available != ð)  
{
printf("ATTEMPT TO DEREGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",  
4-20 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
} /ᑍ End program ᑍ/  
Chapter 4. Common Information across APIs—Advanced (ILE) Example 4-21  
Download from Www.Somanuals.com. All Manuals Search And Download.  
4-22 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Chapter 5. List APIs  
This chapter contains an overview of list APIs, which are those APIs that return a  
list unique to a given API. The chapter discusses the characteristics of a list API  
and provides information that you should be aware of when you use list APIs.  
The List Objects That Adopt Owner Authority (QSYLOBJP) API is referred to  
throughout this chapter. The QSYLOBJP API is included in “List Objects That  
Adopt Owner Authority API—Example” on page 5-12 if you need to refer to it as  
you read this chapter.  
Characteristics of a List API  
As discussed in “User Spaces” on page 2-13, list APIs return information to a user  
space. List APIs generally have a user space parameter that uses a general (or  
common) data structure. You must use the general data structure to get at the  
information placed in the user space by the list API.  
General Data Structure  
This topic describes some of the more important fields that comprise the general  
data structure. Figure 5-1 on page 5-2 shows the common fields that list APIs  
use. All list APIs have an input parameter section, a header section, and a list data  
section.  
User Area  
The first field in the general data structure is called the user area. This is a 64-byte  
field that is not used or changed by the system. Whatever information you place in  
this field remains there. For example, you may specify the date last used, include  
comments about the list, and so forth.  
Size of Generic Header  
The size of the generic header does not include the size of the user area. All  
sections have a size, which may differ for each API.  
Some fields may be added to the generic header from release to release. Because  
fields may be added, you may want to check the size of this field. If your applica-  
tion works across multiple releases, it is recommended that you check the size of  
this field to determine which fields are applicable.  
Offset to Input Parameter Section  
The offset to input parameter section is an offset to the start of the input parameter  
section. The input parameter section may contain a copy of the input parameters  
that you pass to the list API. The QSYLOBJP API's input parameter section is  
shown on page 5-14.  
The input parameter section contains a copy of the continuation handle value that  
you passed as the continuation handle parameter to the API. “Other Fields of  
Generic Header” on page 5-3 discusses continuation handles further.  
Copyright IBM Corp. 1997  
5-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Header  
┌────────────────────────────────────┐  
┌─────────────────────────┐  
+ðð│  
│
│
│
│
│
│
│
│
│
│ 64─Byte User Area  
│
├────────────────────────────────────┤  
┌───5│ Input Parameter Section │  
+4ð│ Size of Generic Header  
│
│
│
│
│
│
│
│
'
'
│
'
'
├────────────────────────────────────┤  
│
│
│
│
│
│ Generic Header  
├─────────────────────────┤  
│
│
│
│
+6C│ Offset to Input Parameter Section ─┼────┘  
│
│
│
│
│
│
+7ð│ Input Parameter Section Size  
│
+74│ Offset to Header Section───────────┼────────5│  
├─────────────────────────┤  
│
│
│
│
│
│
│
│
│
'
'
│
Header Section  
│
│
│
│
│
│
│
│
│
│
'
'
│
+78│ Header Section Size  
│
+7C│ Offset to List Data Section────────┼────┐  
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
│
+8ð│ List Data Section Size  
│
+84│ Number of List Entries  
│
+88│ Size of Each Entry  
├─────────────────────────┤  
│
│
│
+8C│ CCSID of data in the user space  
│
+9ð│ Country ID  
│
│
│
│
│
List Data Section  
+93│ Language ID  
│─────────────────────────┤  
│
└───5│ Entry 1  
│─────────────────────────┤  
│ Entry 2  
│
+95│ Subsetted list indicator  
│
│
+Cð│ API entry point name  
│─────────────────────────┤  
│ Entry 3  
│
│
│
│
'
'
│
│
'
'
│
└────────────────────────────────────┘  
│─────────────────────────┤  
│ Last Entry  
│─────────────────────────┤  
│
│
│
Figure 5-1. General Data Structure  
Offset to Header Section  
The header section includes an offset to where the header section starts and the  
size of the header section. This section is needed in the event any input parame-  
ters have a special value. The fields in the header section tell what the special  
value resolved to. For example, the special value *CURRENT for the user name  
parameter would resolve to the user profile name for the job that called the API.  
This section is also sometimes used for API-specific control information that is not  
related to a particular list entry.  
The QSYLOBJP API's header section is shown on page 5-14.  
Offset to List Data Section  
The offset to the list data section is the offset to the start of the format. The spe-  
cific format that the API uses is determined by the name you specify for the format  
name parameter. The specific format that you use determines what information is  
returned in the user space.  
The number of list entries field tells how many entries have been returned to you.  
The size of each entry field within the list data section tells how large each entry is.  
In the list data section, each entry is of the same length for a given list. If the size  
5-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
of each entry field is ð, the entries have different lengths and the format tells the  
length of each entry.  
The list data sections for the QSYLOBJP API are shown in the “OBJP0100 Format”  
on page 5-14 and the “OBJP0200 Format” on page 5-14. This API has two pos-  
sible formats.  
For more information about formats and how to extract a field from a format, see  
“Format” on page 3-5 and “Extracting a Field from the Format” on page 3-5.  
Other Fields of Generic Header  
The field called structure’s release and level is part of the generic header. This  
field tells the layout of the generic header. For an original program model (OPM)  
layout, this value should be 0100. For an Integrated Language Environment (ILE)  
model layout, the value should be 0300.  
The information status field tells you whether the information in the user space is  
complete and accurate, or partial. You need to check the value of this field before  
you do anything with the information in the user space (see .1/ on page 5-9). Pos-  
sible values for this field follow:  
C
I
P
Complete and accurate.  
Incomplete. The information you received is not accurate or complete.  
Partial but accurate. The information you received is accurate, but the API  
had more information to return than the user space could hold.  
If the value is P, the API has more information to return than what could fit in the  
user space. If you received the value P, you need to process the current informa-  
tion in the user space before you get the remaining information. The API returns a  
continuation handle usually in the form of a parameter. You can use this continua-  
tion handle value to have the remaining information placed in the user space. You  
specify the continuation handle value that the API returned as the value of the con-  
tinuation handle input parameter on your next call to the API.  
The QSYLOBJP API provides a continuation handle in the header section (see .2/  
on page 5-14) to return the remaining information to the user space. The user then  
passes this value back to the API as an input parameter (see .3/ on page 5-14) so  
that the API can locate the remaining information and place it in the user space.  
If the API does not have a continuation handle and the information status field  
value is P, you must further qualify what you want in the list. In other words, you  
must be more specific on the parameter values that you pass to the API. For  
example, the QUSLOBJ API asked to get a list of objects; however, all of the  
objects on the system would not fit in the user space. To further qualify or limit the  
number of objects returned, the user might specify all libraries that start with a spe-  
cific letter.  
For more information about continuation handles and how to use them, see “Con-  
tinuation Handle” on page 2-25.  
Chapter 5. List APIs 5-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Processing a List  
This is the preferred method for processing lists. To correctly process through a  
list, do the following:  
1. Use the offset to list data section field (see .5/ on page 5-9)  
2. Look at the number of list entries field in the list (see .6/ on page 5-10)  
3. Add the size of each entry field to get to the start of the next entry (see .7/ on  
page 5-9)  
IBM may add fields to the bottom of formats in future releases. If this occurs and  
your code uses the size of each entry for a previous release, your list would not  
process at the start of each entry.  
The example program defines the size of each entry at .4/ on page 5-9. For  
another example that shows the correct and incorrect way, see “Defining List Entry  
Format Lengths” on page 9-14.  
List Object API—OPM RPG Example  
The example program prints a report that shows all objects that adopt owner  
authority.  
Fᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FᑍProgram Name: List objects which adopt owner authority  
Fᑍ  
FᑍLanguage:  
Fᑍ  
OPM RPG  
FᑍDescription: This program prints a report showing all objects  
Fᑍ  
that adopt owner authority. The two parameters  
passed to the program are the profile to be  
checked and the type of objects to be listed.  
The parameter values are the same as those  
accepted by the QSYLOBJP API.  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
FᑍAPIs Used:  
QSYLOBJP - List Objects that Adopt Owner Authority  
QUSCRTUS - Create User Space  
QUSROBJD - Retrieve Object Description  
QUSRTVUS - Retrieve From User Space  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
/
/
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQSYSPRT O F  
132  
OF  
PRINTER  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
I/COPY QSYSINC/QRPGSRC,QSYLOBJP  
I/COPY QSYSINC/QRPGSRC,QUSROBJD  
I/COPY QSYSINC/QRPGSRC,QUSGEN  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ Error Code Structure  
Iᑍ  
Iᑍ This shows how the user can define the variable length portion  
5-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ of error code for the exception data.  
Iᑍ  
Iᑍ/COPY QSYSINC/QRPGSRC,QUSEC  
Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍHeader File Name: QRPGSRC/QUSEC  
Iᑍ  
IᑍDescriptive Name: Error Code Parameter.  
Iᑍ  
Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994  
IᑍAll rights reserved.  
IᑍUS Government Users Restricted Rights -  
IᑍUse, duplication or disclosure restricted  
Iᑍby GSA ADP Schedule Contract with IBM Corp.  
Iᑍ  
IᑍLicensed Materials-Property of IBM  
Iᑍ  
Iᑍ  
IᑍDescription: Include header file for the error code parameter.  
Iᑍ  
IᑍHeader Files Included: None.  
Iᑍ  
IᑍMacros List: None.  
Iᑍ  
IᑍStructure List: Qus_EC_t  
Iᑍ  
Iᑍ  
Qus_ERRCð2ðð_t  
IᑍFunction Prototype List: None.  
Iᑍ  
IᑍChange Activity:  
Iᑍ  
IᑍCFD List:  
Iᑍ  
IᑍFLAG REASON  
LEVEL DATE PGMR  
CHANGE DESCRIPTION  
Iᑍ---- ------------ ----- ------ --------- ----------------------  
Iᑍ$Að= D2862ððð  
Iᑍ$B1= D91794ðð  
Iᑍ  
Iᑍ  
3D1ð 9312ð1 DPOHLSON: New Include  
3D6ð 94ð9ð4 GEORGE : Add Qus_ERRCð2ðð_t  
structure.  
IᑍEnd CFD List.  
Iᑍ  
IᑍAdditional notes about the Change Activity  
IᑍEnd Change Activity.  
Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IᑍRecord structure for Error Code Parameter  
Iᑍᑍᑍᑍ  
ᑍᑍᑍ  
IᑍNOTE: The following type definition only defines the fixed  
Iᑍ portion of the format. Varying length field Exception  
Iᑍ Data will not be defined here.  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IQUSBN  
Iᑍ  
I
DS  
Qus EC  
B 1 4ðQUSBNB  
Iᑍ  
I
Iᑍ  
I
Bytes Provided  
B 5 8ðQUSBNC  
Bytes Available  
9 15 QUSBND  
Chapter 5. List APIs 5-5  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ  
I
Exception Id  
16 16 QUSBNF  
Reserved  
Iᑍ  
Iᑍ Following statement was uncommented and 17 was changed to 1ðð  
I
17 1ðð QUSBNG  
Iᑍ  
Iᑍ  
IQUSKY  
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Varying length  
DS  
Qus ERRCð2ðð  
B 1 4ðQUSKYB  
Key  
B 5 8ðQUSKYC  
Bytes Provided  
B 9 12ðQUSKYD  
Bytes Available  
13 19 QUSKYF  
Exception Id  
2ð 2ð QUSKYG  
Reserved  
B 21 24ðQUSKYH  
CCSID  
B 25 28ðQUSKYJ  
Offset Exc Data  
B 29 32ðQUSKYK  
Length Exc Data  
33 33 QUSKYL  
Reserved2  
Iᑍ  
Iᑍ  
Iᑍ  
Iᑍ  
Iᑍ  
Iᑍ  
Iᑍ  
34 34 QUSKYM  
Iᑍ Global Variables  
Iᑍ  
I
DS  
I
1 1ð APINAM  
11 3ð CONHDL  
31 4ð EXTATR  
41 41 LSTSTS  
42 49 MBRLST  
68 75 RJOBDF  
76 85 SPCAUT  
86 95 SPCDMN  
96 96 SPCINT  
' 97 116 SPCNAM  
117 126 SPCREP  
127 176 SPCTXT  
177 186 SPCTYP  
B 197 2ðððRCVLEN  
B 2ð1 2ð4ðSIZENT  
B 2ð5 2ð8ðSPCSIZ  
B 2ð9 212ðI  
I
I I  
I
'QSYSLOBJP '  
I I  
I I  
I I  
I I  
I I  
I I  
I I  
I
'OBJPð2ðð'  
'OBJDð1ðð'  
'ᑍALL  
'
'
'ᑍUSER  
X'ðð'  
'ADOPTS  
'ᑍYES  
QTEMP  
'
I I  
I I  
I
'ᑍUSRSPC '  
8
I I  
I
1
I
B 213 216ðNUMENT  
B 217 22ððOFFSET  
B 221 224ðSTRPOS  
2ððð  
I
I
IRCVVAR  
Cᑍ  
DS  
Cᑍ Beginning of Mainline  
Cᑍ  
5-6 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ Two parameters are being passed into this program.  
Cᑍ  
C
ᑍENTRY  
PLIST  
PARM  
PARM  
C
USRPRF 1ð  
OBJTYP 1ð  
C
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
EXSR INIT  
EXSR PROCES  
EXSR DONE  
C
C
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Function:  
Cᑍ  
getlst  
Cᑍ Description: This function calls QSYLOBJP to build a list.  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
C
GETLST  
BEGSR  
MOVEL'OBJPð2ðð'MBRLST  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Call QSYLOBJP API to generate a list. The continuation handle  
Cᑍ is set by the caller of this function.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
C
C
CALL 'QSYLOBJP'  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
SPCNAM  
MBRLST  
USRPRF  
OBJTYP  
CONHDL  
QUSBN  
User space/lib  
Member list  
User profile  
Object type sc  
Continuation ha (.3/  
Error Code  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Check for errors on QSYLOBJP.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
QUSBNC  
IFGT ð  
MOVEL'QSYLOBJP'APINAM  
EXSR APIERR  
ENDIF  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Function:  
Cᑍ  
INIT  
Cᑍ Description: This function does all the necessary  
Cᑍ  
Cᑍ  
initialization for this program and the  
rest is done in the I specs.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
INIT BEGSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Z-ADD1ðð QUSBNB  
C
C
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Call QUSROBJD to see if the user space was previously created  
Cᑍ in QTEMP. If it was, simply reuse it.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
CALL 'QUSROBJD'  
PARM  
RCVVAR  
Receiver Var  
Chapter 5. List APIs 5-7  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
PARM  
PARM  
PARM  
PARM  
PARM  
RCVLEN  
RJOBDF  
SPCNAM  
SPCTYP  
QUSBN  
Rec Var Length  
Format  
Qual User Space  
User object typ  
Error Code  
C
C
C
C
Cᑍ  
C
QUSBNC  
IFGT ð  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ If a CPF98ð1 error was received, then the user space was not  
Cᑍ found.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
QUSBND  
IFEQ 'CPF98ð1'  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Create a user space for the list generated by QSYLOBJP.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
C
C
C
C
C
CALL 'QUSCRTUS'  
PARM  
SPCNAM  
EXTATR  
SPCSIZ  
SPCINT  
SPCAUT  
SPCTXT  
SPCREP  
QUSBN  
Qual User Space  
Extended Attrib  
Size user space  
Space Initializ  
Public Authorit  
User space text  
Replace existin  
Error Code  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
SPCDMN  
Domain of us  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Check for errors on QUSCRTUS.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
QUSBNC  
IFGT ð  
MOVEL'QUSCRTUS'APINAM  
EXSR APIERR  
ENDIF  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ An error occurred accessing the user space.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
ELSE  
MOVEL'QUSROBJD'APINAM  
EXSR APIERR  
ENDIF  
CPF98ð1 ELSE  
BYTAVL > ð  
ENDIF  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Set QSYLOBJP (via GETLST) to start a new list.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
MOVE ᑍBLANKS CONHDL  
EXSR GETLST  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Let's retrieve the generic header information from the user  
Cᑍ space since OPM RPG does not have pointer support.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
C
C
C
Z-ADD1  
Z-ADD192  
CALL 'QUSRTVUS'  
PARM  
STRPOS  
RCVLEN  
Format 1ðð  
SPCNAM  
STRPOS  
RCVLEN  
QUSBP  
Qual User Space  
Start Position  
Length of Data  
Receiver Var.  
Error Code  
PARM  
PARM  
PARM  
PARM  
QUSBN  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
5-8 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ Check for errors on QUSRTVUS.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
C
QUSBNC  
IFGT ð  
MOVEL'QUSRTVUS'APINAM  
EXSR APIERR  
ENDIF  
1
ADD QUSBPQ  
ENDSR  
STRPOS  
Offset to List .5/  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Function:  
Cᑍ  
proc2  
Cᑍ Description: This function processes each entry returned by  
Cᑍ  
Cᑍ  
QSYLOBJP.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
C
C
PROC2  
BEGSR  
CALL 'QUSRTVUS'  
PARM  
PARM  
PARM  
PARM  
PARM  
SPCNAM  
STRPOS  
SIZENT  
QSYB6  
Qual User Space  
Start Position  
Length of Data  
Receiver Var.  
Error Code  
QUSBN  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Check for errors on QUSRTVUS.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
QUSBNC  
IFGT ð  
MOVEL'QUSRTVUS'APINAM  
EXSR APIERR  
ENDIF  
EXCPTPRTENT  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ After each entry, increment to the next entry.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
STRPOS  
ADD SIZENT  
ENDSR  
STRPOS  
.7/  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Function:  
Cᑍ  
proc1  
Cᑍ Description: This function processes each entry returned by  
Cᑍ  
Cᑍ  
QSYLOBJP.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROC1 BEGSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ If valid information was returned. .1/  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
Z-ADDQUSBPS  
IFEQ 'P'  
OREQ 'C'  
IFGT ð  
NUMENT  
QUSBPJ  
QUSBPJ  
NUMENT  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Get the size of each entry to use later. .4/  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Z-ADDQUSBPT SIZENT  
C
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Increment to the first list entry.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
1
ADD QUSBPQ  
OFFSET  
Chapter 5. List APIs 5-9  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Process all of the entries.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
1
DO NUMENT  
EXSR PROC2  
ENDDO  
I
.6/  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ If all entries in this user space have been processed, check  
Cᑍ if more entries exist than can fit in one user space.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
QUSBPJ  
IFEQ 'P'  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Address the input parameter header.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
C
C
C
1
ADD QUSBPL  
Z-ADD68  
CALL 'QUSRTVUS'  
PARM  
STRPOS  
RCVLEN  
Format 1ðð  
SPCNAM  
STRPOS  
RCVLEN  
QUSBP  
Qual User Space  
Start Position  
Length of Data  
Receiver Var.  
Error Code  
PARM  
PARM  
PARM  
PARM  
QUSBN  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Check for errors on QUSRTVUS.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
QUSBNC  
IFGT ð  
MOVEL'QUSRTVUS'APINAM  
EXSR APIERR  
ENDIF  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ If the continuation handle in the input parameter header  
Cᑍ is blank, then set the list status to complete.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
QSYCRJ  
IFEQ ᑍBLANKS  
MOVE 'C'  
ELSE  
LSTSTS  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Else, call QSYLOBJP reusing the user space to get more  
Cᑍ list entries.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
C
C
C
C
C
MOVELQSYCRJ  
EXSR GETLST  
Z-ADD1  
CONHDL  
.2/  
STRPOS  
RCVLEN  
Z-ADD192  
CALL 'QUSRTVUS'  
PARM  
Format 1ðð  
SPCNAM  
STRPOS  
RCVLEN  
QUSBP  
Qual User Space  
Start Position  
Length of Data  
Receiver Var.  
Error Code  
PARM  
PARM  
PARM  
PARM  
QUSBN  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Check for errors on QUSRTVUS.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
QUSBNC  
IFGT ð  
MOVEL'QUSRTVUS'APINAM  
EXSR APIERR  
ENDIF  
MOVE QUSBPJ  
LSTSTS  
5-10 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
C
C
ENDIF  
ENDIF  
ELSE  
HDL = BLANKS  
INFOSTS = ð  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
CᑍIf there exists an unexpected status, log an error (not shown)  
Cᑍand exit.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
EXSR DONE  
ENDIF  
ENDIF  
ENDSR  
done();  
#ENT > ð  
USRSPC=P/C  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Function:  
Cᑍ  
proces  
Cᑍ Description: Processes entries until they are complete.  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
C
C
PROCES  
BEGSR  
MOVELQUSBPJ  
DOUEQ'C'  
OREQ 'I'  
EXSR PROC1  
ENDDO  
LSTSTS  
LSTSTS  
LSTSTS  
proces1();  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Function:  
Cᑍ  
Cᑍ Description: Exits the program.  
done  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
DONE  
BEGSR  
EXCPTENDLST  
SETON  
LR  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ Function:  
Cᑍ  
apierr  
Cᑍ Description: This function prints the API name, and exception  
Cᑍ identifier of an error that occurred.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
APIERR  
APINAM  
QUSBND  
BEGSR  
DSPLY  
DSPLY  
EXSR DONE  
ENDSR  
Oᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Oᑍ Function:  
Oᑍ  
PRTENT  
Oᑍ Description: This function prints the information returned in  
Oᑍ user space.  
Oᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
OQSYSPRT E 1ð6  
PRTENT  
QSYB6C  
QSYB6D  
QSYB6F  
O
O
O
O
O
O
'Object: '  
'Library: '  
'Type: '  
Chapter 5. List APIs 5-11  
Download from Www.Somanuals.com. All Manuals Search And Download.  
O
O
'Text: '  
QSYB6J  
Oᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Oᑍ Function:  
Oᑍ  
ENDLST  
Oᑍ Description: This function prints the end of listing print  
Oᑍ line and returns to the caller.  
Oᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
OQSYSPRT E 1ð6  
O
ENDLST  
'ᑍᑍᑍ End of List'  
List Objects That Adopt Owner Authority API—Example  
Parameters  
Required Parameter Group:  
1
2
3
4
5
6
Qualified user space name  
Format name  
User  
Object type  
Continuation handle  
Error code  
Input  
Input  
Input  
Input  
Input  
I/O  
Char(20)  
Char(8)  
Char(10)  
Char(10)  
Char(20)  
Char(*)  
The List Objects That Adopt Owner Authority (QSYLOBJP) API puts a list of  
objects that adopt an object owner's authority into a user space.  
This API provides information similar to that provided by the Display Program Adopt  
(DSPPGMADP) command.  
Authorities and Locks  
User Space Authority  
*CHANGE  
Authority to Library Containing User Space  
*USE  
User Profile Authority  
*OBJMGT  
Required Parameter Group  
Qualified user space name  
INPUT; CHAR(20)  
The name of the existing user space to which the list of objects that adopt a  
user's authority is returned. The first 10 characters specify the user space  
name, and the second 10 characters specify the library. You can use these  
special values for the library name:  
*CURLIB The current library is used to locate the user space. If there is no  
current library, QGPL (general purpose library) is used.  
*LIBL  
The library list is used to locate the user space.  
5-12 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Format name  
INPUT; CHAR(8)  
The name of the format that returns information on the objects that adopt a  
user's authority.  
You can specify these formats:  
OBJP0100  
Each entry contains the object name, library, type, and object  
in use indicator. For a detailed description of this format, see  
“OBJP0100 Format” on page 5-14.  
OBJP0200  
Each entry contains the same information as format  
OBJP0100 plus the object attribute and descriptive text. For a  
detailed description of this format, see “OBJP0200 Format” on  
page 5-14.  
User name  
INPUT; CHAR(10)  
The user name for which the list of objects that adopt the user's authority is  
returned. You can specify the following special value:  
*CURRENT  
The list of objects that adopt the authority of the user currently  
running is returned. If *CURRENT is used, the name of the  
current user is returned in the list header section of the user  
space.  
Object type  
INPUT; CHAR(10)  
The type of object for which the list of objects that adopt the user's authority is  
returned. You can specify only the following special values:  
*ALL  
*PGM  
*SQLPKG  
*SRVPGM  
Return entries for all object types that adopt authority.  
Return entries for programs that adopt authority.  
Return entries for SQL packages that adopt authority.  
Return entries for service programs that adopt authority.  
Continuation handle  
INPUT; CHAR(20)  
The handle used to continue from a previous call to this API that resulted in  
partially complete information. You can determine if a previous call resulted in  
partially complete information by checking the Information Status variable in the  
generic user space header following the API call.  
If the API is not attempting to continue from a previous call, this parameter  
must be set to blanks. Otherwise, a valid continuation value must be supplied.  
The value may be obtained from the list header section of the user space used  
in the previous call. When continuing, the first entry in the returned list is the  
entry that immediately follows the last entry returned in the previous call.  
Error code  
I/O; CHAR(*)  
The structure in which to return error information. For the format of the struc-  
ture, see "Error Code Parameter" in Chapter 2 of the System API Reference.  
Chapter 5. List APIs 5-13  
Download from Www.Somanuals.com. All Manuals Search And Download.  
User Space Variables  
The following tables describe the order and format of the data returned in the user  
space. For detailed descriptions of the fields in the tables, see “Field Descriptions”  
on page 5-15.  
Input Parameter Section  
Offset  
Dec  
0
Hex  
0
Type  
Field  
CHAR(10)  
CHAR(10)  
CHAR(8)  
CHAR(10)  
CHAR(10)  
CHAR(20)  
User space name specified  
User space library name specified  
Format name  
10  
20  
28  
38  
48  
0A  
14  
1C  
26  
30  
User name specified  
Object type  
Continuation handle .3/  
Header Section  
Offset  
Dec  
0
Hex  
0
Type  
Field  
CHAR(10)  
CHAR(20)  
User name  
10  
0A  
Continuation handle .2/  
OBJP0100 Format  
Offset  
Dec  
0
Hex  
0
Type  
Field  
CHAR(10)  
CHAR(10)  
CHAR(10)  
CHAR(1)  
Object name  
Library name  
Object type  
Object in use  
10  
20  
30  
0A  
14  
1E  
OBJP0200 Format  
Offset  
Dec  
0
Hex  
0
Type  
Field  
CHAR(10)  
CHAR(10)  
CHAR(10)  
CHAR(1)  
CHAR(10)  
CHAR(50)  
Object name  
Library name  
Object type  
Object in use  
Attribute  
10  
20  
30  
31  
41  
0A  
14  
1E  
1F  
29  
Text description  
5-14 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Field Descriptions  
Attribute. The object attribute.  
Continuation handle (header section). A continuation point for the API. This  
value is set based on the contents of the Information Status variable in the generic  
header for the user space. The following situations can occur:  
Ÿ Information status–C. The information returned in the user space is valid and  
complete. No continuation is necessary and the continuation handle is set to  
blanks.  
Ÿ Information status–P. The information returned in the user space is valid but  
incomplete. The user may call the API again, starting where the last call left  
off. The continuation handle contains a value which may be supplied as an  
input parameter in later calls.  
Ÿ Information status–I. The information returned in the user space is not valid  
and incomplete. The content of the continuation handle is unpredictable.  
Continuation handle (input section). Used to continue from a previous call to  
this API which resulted in partially complete information.  
Format name. The name of the format used to return information on the objects  
that adopt authority.  
Library name. The name of the library containing the user space or object.  
Object name. The name of the object that adopts the user's authority.  
Object in use. Whether the object is in use when the API tries to access it. If the  
object is in use, the API is not able to determine if the object adopts the user's  
authority. If the object is in use, this field is Y. If not, this field is N.  
Object type.  
Ÿ Input Section: The type of object for which the list of objects adopting the user's  
authority is returned.  
Ÿ List Section: The type of object which adopts the user's authority.  
Text description. The text description of the object.  
User name. The name of the owner of the object.  
User name specified. The name of the user for which the list of objects that  
adopt the user's authority is returned.  
User space library name specified. The name of the library that contains the  
user space.  
User space name specified. The name of the user space to which the list of  
objects that adopt the users authority is returned.  
Chapter 5. List APIs 5-15  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Error Messages  
CPF22FD E Continuation handle not valid for API &1.  
CPF2204 E User profile &1 not found.  
CPF2213 E Not able to allocate user profile &1.  
CPF2217 E Not authorized to user profile &1.  
CPF3CF1 E Error code parameter not valid.  
CPF3C21 E Format name &1 is not valid.  
CPF3C31 E Object type &1 is not valid.  
CPF811A E User space &4 in &9 damaged.  
CPF9801 E Object &2 in library &3 not found.  
CPF9802 E Not authorized to object &2 in &3.  
CPF9803 E Cannot allocate object &2 in library &3.  
CPF9807 E One or more libraries in library list deleted.  
CPF9808 E Cannot allocate one or more libraries on library list.  
CPF9810 E Library &1 not found.  
CPF9820 E Not authorized to use library &1.  
CPF9830 E Cannot assign library &1.  
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.  
5-16 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Chapter 6. Original Program Model (OPM) and Integrated  
Language Environment (ILE) Differences  
This chapter contains an overview of how Original Program Model (OPM) APIs and  
Integrated Language Environment (ILE) APIs differ from each other. The ILE APIs  
include the UNIX-type APIs and the ILE CEE APIs among others.  
You must have the ILE language compiler on your system to develop applications  
that use any ILE APIs.  
Contrasting OPM and ILE APIs  
API Name  
The maximum number of characters that an OPM API name can contain is 8,  
whereas the maximum number in an ILE API name is 30. ILE API names are  
case-sensitive.  
Parameters  
There are several types of parameters: required, optional, and omitted. The  
AS/400 OPM and ILE APIs show the parameters in a Parameter box, whereas the  
AS/400 UNIX-type APIs show them in a Syntax box. The ILE APIs include the  
service program name at the bottom of the box.  
Optional Parameters: Some of the OPM APIs have optional parameters. The  
optional parameters form a group, and you must either include or exclude the entire  
group.  
OPM APIs do not have omitted parameters.  
Omitted Parameters: The ILE APIs may have parameters that can be omitted.  
When these parameters are omitted, you must pass a null pointer.  
ILE APIs do not have optional parameters.  
The required and optional parameters are discussed in more detail in “Required  
Parameter Group” on page 3-3 and “Optional Parameter Group” on page 3-5.  
Error Conditions  
The error code parameter is common to most of the OPM APIs, and it is used to  
return error codes and exception data to the application. The errors that are  
returned for a given API are in the form of an error message and include the  
7-character message identifier.  
Some APIs use means other than the error code parameter for reporting error con-  
ditions, as follows:  
Ÿ The ILE CEE APIs use feedback codes and conditions.  
Ÿ The UNIX-type APIs use errnos and return values.  
Ÿ The national language data conversion APIs use errnos and return values.  
Copyright IBM Corp. 1997  
6-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Ÿ The Dynamic Screen Manager (DSM) supports returned values in addition to  
the error code parameter.  
The errnos are provided as include files in the QSYSINC library.  
Pointers  
Due to the greater availability of pointer support in ILE languages, there is a much  
greater use of pointers in ILE APIs. The use of pointers can provide a performance  
advantage.  
Following are examples of an OPM API and an ILE API that do similar functions  
(log or report software errors). The ILE API example makes use of pointers,  
whereas the OPM API does not. Both programs log software errors by using first-  
failure data capture (FFDC).  
Logging Software Error (OPM API without Pointers)—ILE C  
Example  
This program calls the Log Software Error (QPDLOGER) API to perform FFDC.  
The program does not make use of pointers. The OPM program physically moves  
the data that is pointed to (shown at .1/ on page 6-6), which slows down perfor-  
mance.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍProgram Name: FFDCPGM1  
/ᑍ  
/ᑍProgram Language: ILE C  
/ᑍ  
/ᑍDescription: This program illustrates how to use APIs to log  
/ᑍ  
/ᑍ  
/ᑍ  
software errors using FFDC.  
/ᑍHeader Files Included: except  
/ᑍ  
stdio  
/ᑍ  
string  
qmhchgem  
qpdloger  
qusec  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍAPIs Used:  
/ᑍ  
QPDLOGER  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
System Includes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <except.h>  
#include <stdio.h>  
#include <string.h>  
/ᑍ from QCLE/H  
/ᑍ from QCLE/H  
/ᑍ from QCLE/H  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Miscellaneous Includes ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <qmhchgem.h>  
#include <qpdloger.h>  
#include <qusec.h>  
/ᑍ from QSYSINC/H  
/ᑍ from QSYSINC/H  
/ᑍ from QSYSINC/H  
ᑍ/  
ᑍ/  
ᑍ/  
6-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Structures  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
void ᑍparm1;  
void ᑍparm2;  
char ᑍpgm_name;  
int  
pgm_name_size;  
} ffdc_info_t;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Prototypes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void UNEXPECTED_HDLR(_INTRPT_Hndlr_Parms_T ᑍ);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ FUNCTION NAME: main  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ FUNCTION:  
Generates exception and then passes control  
/ᑍ  
to exception handler.  
Two character strings.  
NONE  
/ᑍ  
/ᑍ INPUT:  
/ᑍ  
/ᑍ OUTPUT:  
/ᑍ  
/ᑍ EXCEPTIONS:  
CPFxxxx - All unexpected CPF exceptions  
MCHxxxx - All unexpected MCH exceptions  
/ᑍ  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void main(int argc, char ᑍargv[])  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ NOTE: argv will contain the parameters passed in to this  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ  
function. In this case, two parameters are passed  
in.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ The argv parameter contains the parameters that were passed as ᑍ/  
/ᑍ character arrays. argv[ð] contains the program name, and the ᑍ/  
/ᑍ parameter(s) starts with argv[1].  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
char ᑍnulptr;  
/ᑍ Pointer used to generate error ᑍ/  
/ᑍ Program name ᑍ/  
char pgm_name[3ð];  
volatile ffdc_info_t ffdc_info; /ᑍ FFDC info for unexpected error ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up FFDC information for unexpected error.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ffdc_info.parm1 = argv[1];  
ffdc_info.parm2 = argv[2];  
ffdc_info.pgm_name = pgm_name;  
memcpy(pgm_name, argv[ð], strlen(argv[ð]));  
ffdc_info.pgm_name_size = strlen(argv[ð]);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Enable the exception handler, and pass ffdc_info into the  
/ᑍ exception handler via the communications area so that data  
ᑍ/  
ᑍ/  
Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences 6-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ can be used for FFDC.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#pragma exception_handler (UNEXPECTED_HDLR, ffdc_info, ð, _C2_MH_ESCAPE)  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the pointer to null, then try to increment. This will  
/ᑍ generate an MCH36ð1 error that will be trapped by the  
/ᑍ unexpected handler.  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
nulptr = NULL;  
nulptr++;  
#pragma disable_handler  
} /ᑍ main ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ FUNCTION NAME: UNEXPECTED_HDLR  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍ FUNCTION:  
Handle unexpected exception. This exception  
ᑍ/  
/ᑍ  
handler is used to log the software error via ᑍ/  
/ᑍ  
FFDC.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ INPUT:  
Interrupt handler information  
NONE  
/ᑍ  
/ᑍ OUTPUT:  
/ᑍ  
/ᑍ EXCEPTIONS:  
CPFxxxx - All unexpected CPF exceptions  
MCHxxxx - All unexpected MCH exceptions  
/ᑍ  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void UNEXPECTED_HDLR(_INTRPT_Hndlr_Parms_T ᑍerrmsg)  
{
typedef struct {  
char obj_name[3ð];  
char obj_lib[3ð];  
char obj_type[1ð];  
} obj_info_t;  
typedef struct {  
int  
int  
data_offset;  
data_length;  
} data_info_t;  
char  
int  
pgm_suspected[1ð],  
msg_id[12],  
msg_key[4],  
print_job_log,  
data[2ᑍ(sizeof(char ᑍ))],  
ᑍdata_item,  
ile_mod_name[11];  
point_of_failure,  
num_items,  
num_objs;  
data_info_t  
obj_info_t  
data_info[2];  
obj_info[1];  
6-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ffdc_info_t ᑍffdc_info;  
Qus_EC_t ErrorCode;  
ErrorCode.Bytes_Provided = ð;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Getting pointer in local storage to the Communications Area.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ffdc_info = (ffdc_info_t ᑍ)(errmsg->Com_Area);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Need to notify message handler that we will handle the error. ᑍ/  
/ᑍ Leave the message in the job log, just mark it handled.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QMHCHGEM(&(errmsg->Target),  
ð,  
/ᑍ Invocation pointer  
/ᑍ Call stack counter  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
(char ᑍ)&errmsg->Msg_Ref_Key,/ᑍ Message key  
"ᑍHANDLE ",  
/ᑍ Modification option  
/ᑍ Reply text  
/ᑍ Reply text length  
/ᑍ Error code  
"",  
ð,  
&ErrorCode);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up the suspected program. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(pgm_suspected, "ᑍPRV ", 1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up the detection identifier. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(msg_id, ' ', 12);  
memcpy(msg_id, errmsg->Msg_Id, 7);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up the message key.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(msg_key, (char ᑍ)&errmsg->Msg_Ref_Key, 4);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up point of failure. Since this example program is small ᑍ/  
/ᑍ and we know where the error occurred, we will just put a dummy ᑍ/  
/ᑍ value in. However, this can be very useful information in  
/ᑍ larger programs.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
point_of_failure = 1ðð;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up to print the job log.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
print_job_log = 'Y';  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up data items.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
data_item = data;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Put in first parameter.  
ᑍ/  
Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences 6-5  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(data_item, (char ᑍ)ffdc_info->parm1, sizeof(char ᑍ)); .1/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Add in the second parameter.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
data_item += sizeof(char ᑍ);  
memcpy(data_item, (char ᑍ)ffdc_info->parm2, sizeof(char ᑍ));  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Reset the data item pointer.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
data_item -= sizeof(char ᑍ);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up data item offset/length information.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
data_info[ð].data_offset = ð;  
data_info[ð].data_length = sizeof(char ᑍ);  
data_info[1].data_offset = sizeof(char ᑍ);  
data_info[1].data_length = sizeof(char ᑍ);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up the number of data items. In this case we only have one.ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
num_items = 2;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up the object name array. In this case, we have no objects ᑍ/  
/ᑍ to dump, but we will put dummy values in to illustrate.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(obj_info[ð].obj_name, "OBJUSRSPC  
memcpy(obj_info[ð].obj_lib, "QTEMP  
memcpy(obj_info[ð].obj_type, "ᑍUSRSPC ", 1ð);  
", 3ð);  
", 3ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the number of objects in name array. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
num_objs = ð;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up the ILE module name.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(ile_mod_name, ffdc_info->pgm_name, ffdc_info->pgm_name_size);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call QPDLOGER to perform FFDC.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ErrorCode.Bytes_Provided = sizeof(ErrorCode);  
QPDLOGER(pgm_suspected,  
msg_id,  
msg_key,  
point_of_failure,  
&print_job_log,  
data_item,  
data_info,  
num_items,  
obj_info,  
6-6 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
num_objs,  
&ErrorCode,  
ile_mod_name);  
} /ᑍ UNEXPECTED_HDLR ᑍ/  
Reporting Software Error (ILE API with Pointers)—ILE C Example  
This program calls the Report Software Error (QpdReportSoftwareError) API to  
perform FFDC, and uses pointers. The ILE program sets a pointer (shown at .2/  
on page 6-10) to point to the same location as in the OPM program (shown at .1/  
on page 6-6).  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍProgram Name: FFDCPGM2  
/ᑍ  
/ᑍProgram Language: ILE C  
/ᑍ  
/ᑍDescription: This program illustrates how to use APIs to log  
/ᑍ  
/ᑍ  
/ᑍ  
software errors using FFDC.  
/ᑍHeader Files Included: except  
/ᑍ  
stdio  
/ᑍ  
string  
qmhchgem  
qpdsrvpg  
qusec  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍAPIs Used:  
/ᑍ  
QpdReportSoftwareError  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
System Includes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <except.h>  
#include <stdio.h>  
#include <string.h>  
/ᑍ from QCLE/H  
/ᑍ from QCLE/H  
/ᑍ from QCLE/H  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Miscellaneous Includes ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <qmhchgem.h>  
#include <qpdsrvpg.h>  
#include <qusec.h>  
/ᑍ from QSYSINC/H  
/ᑍ from QSYSINC/H  
/ᑍ from QSYSINC/H  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Definitions used for developing key information for FFDC. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#define CHARACTER 'C'  
#define MAX_KEYS 3  
#define MESSAGE "MSG"  
#define MESSAGE_LEN 7  
#define MSG_SYMPTOM_LEN 3  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Structures  
ᑍ/  
Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences 6-7  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
void ᑍparm1;  
void ᑍparm2;  
char ᑍpgm_name;  
int  
pgm_name_size;  
} ffdc_info_t;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Prototypes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void UNEXPECTED_HDLR(_INTRPT_Hndlr_Parms_T ᑍ);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ FUNCTION NAME: main  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ FUNCTION:  
Generates exception and then passes control  
/ᑍ  
to exception handler.  
Two character strings.  
NONE  
/ᑍ  
/ᑍ INPUT:  
/ᑍ  
/ᑍ OUTPUT:  
/ᑍ  
/ᑍ EXCEPTIONS:  
CPFxxxx - All unexpected CPF exceptions  
MCHxxxx - All unexpected MCH exceptions  
/ᑍ  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void main(int argc, char ᑍargv[])  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ NOTE: argv will contain the parameters passed in to this  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ  
function. In this case, two parameters are passed  
in.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ The argv parameter contains the parameters that were passed as ᑍ/  
/ᑍ character arrays. argv[ð] contains the program name, and the ᑍ/  
/ᑍ parameter(s) starts with argv[1].  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
char ᑍnulptr;  
/ᑍ Pointer used to generate error ᑍ/  
/ᑍ Program name ᑍ/  
char pgm_name[3ð];  
volatile ffdc_info_t ffdc_info; /ᑍ FFDC info for unexpected error ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set up FFDC information for unexpected error.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ffdc_info.parm1 = argv[1];  
ffdc_info.parm2 = argv[2];  
ffdc_info.pgm_name = pgm_name;  
memcpy(pgm_name, argv[ð], strlen(argv[ð]));  
ffdc_info.pgm_name_size = strlen(argv[ð]);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Enable the exception handler, and pass ffdc_info into the  
/ᑍ exception handler via the communications area so that data  
/ᑍ can be used for FFDC.  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
6-8 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
#pragma exception_handler (UNEXPECTED_HDLR, ffdc_info, ð, _C2_MH_ESCAPE)  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the pointer to null, then try to increment. This will  
/ᑍ generate an MCH36ð1 error that will be trapped by the  
/ᑍ unexpected handler.  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
nulptr = NULL;  
nulptr++;  
#pragma disable_handler  
} /ᑍ main ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ FUNCTION NAME: UNEXPECTED_HDLR  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍ FUNCTION:  
Handle unexpected exception. This exception  
ᑍ/  
/ᑍ  
handler is used to log the software error via ᑍ/  
/ᑍ  
FFDC.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ INPUT:  
Interrupt handler information  
NONE  
/ᑍ  
/ᑍ OUTPUT:  
/ᑍ  
/ᑍ EXCEPTIONS:  
CPFxxxx - All unexpected CPF exceptions  
MCHxxxx - All unexpected MCH exceptions  
/ᑍ  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void UNEXPECTED_HDLR(_INTRPT_Hndlr_Parms_T ᑍerrmsg)  
{
int  
i = ð,  
MsgLen = ð,  
number_of_keys = ð;  
pgm_name[3ð],  
char  
context_name[3ð],  
lib_name[5],  
symptom_msg_data[MESSAGE_LEN],  
symptom_msg_keyword[MSG_SYMPTOM_LEN];  
ᑍffdc_info;  
ffdc_info_t  
Qpd_Data_t  
data_key,  
data_key2;  
ffdc_keys[MAX_KEYS];  
Qpd_Suspected_Module_t module_key;  
Qpd_Key_Pointer_t  
Qpd_Symptom_t  
Qus_EC_t  
symptom_msg_key;  
ErrorCode;  
ErrorCode.Bytes_Provided = ð;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Getting pointer in local storage to the Communications Area.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ffdc_info = (ffdc_info_t ᑍ)(errmsg->Com_Area);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Need to notify message handler that we will handle the error. ᑍ/  
Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences 6-9  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ Leave the message in the job log, just mark it handled.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QMHCHGEM(&(errmsg->Target),  
ð,  
/ᑍ Invocation pointer  
/ᑍ Call stack counter  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
(char ᑍ)&errmsg->Msg_Ref_Key,/ᑍ Message key  
"ᑍHANDLE ",  
/ᑍ Modification option  
/ᑍ Reply text  
/ᑍ Reply text length  
/ᑍ Error code  
"",  
ð,  
&ErrorCode);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize module suspected key for FFDC. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ffdc_keys[number_of_keys++].Suspected_Module = &module_key;  
module_key.Key = Qpd_Suspected_Module;  
module_key.Module_Name_Length = ffdc_info->pgm_name_size;  
module_key.Library_Name_Length = 7;  
module_key.Module_Name = pgm_name;  
memcpy(pgm_name, ffdc_info->pgm_name, ffdc_info->pgm_name_size);  
module_key.Library_Name = lib_name;  
memcpy(lib_name, "TESTLIB", 7);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize symptom keys for FFDC.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ffdc_keys[number_of_keys++].Symptom = &symptom_msg_key;  
symptom_msg_key.Key = Qpd_Symptom;  
symptom_msg_key.Keyword_Length = MSG_SYMPTOM_LEN;  
symptom_msg_key.Data_Length = MESSAGE_LEN;  
symptom_msg_key.Data_Type = CHARACTER;  
memcpy(symptom_msg_keyword, MESSAGE, MSG_SYMPTOM_LEN);  
symptom_msg_key.Keyword = symptom_msg_keyword;  
memcpy(symptom_msg_data, errmsg->Msg_Id, MESSAGE_LEN);  
symptom_msg_key.Data = symptom_msg_data;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Parameter 1 information  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ffdc_keys[number_of_keys++].Data = &data_key;  
data_key.Key = Qpd_Data;  
data_key.Data_Length = sizeof(char ᑍ);  
data_key.Data_Id = 1;  
data_key.Data = ffdc_info->parm1;  
.2/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Parameter 2 information ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ffdc_keys[number_of_keys++].Data = &data_key2;  
data_key2.Key = Qpd_Data;  
data_key2.Data_Length = sizeof(char ᑍ);  
data_key2.Data_Id = 1;  
data_key2.Data = ffdc_info->parm2;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call QpdReportSoftwareError to perform FFDC.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ErrorCode.Bytes_Provided = sizeof(ErrorCode);  
QpdReportSoftwareError(ffdc_keys,  
6-10 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
&number_of_keys,  
&ErrorCode);  
} /ᑍ UNEXPECTED_HDLR ᑍ/  
Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences 6-11  
Download from Www.Somanuals.com. All Manuals Search And Download.  
6-12 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Chapter 7. Machine Interface Programming  
This chapter is for programmers interested in creating machine interface (MI) pro-  
grams. While some MI instructions are discussed within the context of how to  
develop MI programs, this chapter makes no attempt to review the full range of MI  
instructions. The goal of this chapter is to provide a sufficient base of knowledge  
so that you can begin to use the MI language. After reading this chapter, you  
should be able to develop, create, run, and debug an AS/400 MI program. When  
reading this chapter, you will need access to the System API Reference,  
SC41-5801, and the Machine Interface Functional Reference, SC41-5810, because  
these two books are referred to extensively.  
Machine Interface Instructions—Introduction  
Programs and procedures are the two basic units of execution on the AS/400. Pro-  
grams come in two flavors: the original program model (OPM) and the Integrated  
Language Environment (ILE). MI programs can be created only for the OPM envi-  
ronment. If you require ILE support in the development of your applications, use  
ILE C and its built-in MI support.  
In the OPM environment, a program is comprised of two basic components: the  
object definition table (ODT) and an instruction stream. In the case of MI pro-  
grams, the program is created using the Create Program (QPRCRTPG) API. This  
API is documented in the System API Reference.  
The ODT is the means for defining all objects1 that are referred to by the MI  
instruction stream. An ODT definition of an object does not actually allocate  
storage for the object. It does, however, define when and how much storage is to  
be allocated and also the attributes of the storage (for example, the data type of the  
object). The ODT is built from the declare (DCL) statements found in the source  
used to create a program. Because DCL statements are actually instructions to the  
QPRCRTPG API and not MI instructions, they are defined in the QPRCRTPG API.  
The types of objects that can be declared are:  
Scalar  
Pointer  
Machine space pointer  
Operand list  
Instruction definition list  
Exception description  
Space  
Constant  
The instruction stream defines the set of operations to be performed by the  
program. The instruction stream is built from the MI instructions found in the  
source used to create a program. The various MI instructions that you can use are  
defined in the Machine Interface Functional Reference.  
1
The term objects in this chapter refers to program data elements and not OS/400 object types such as a *FILE, *PGM, *USRPRF,  
and so on.  
Copyright IBM Corp. 1997  
7-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Within the source used to create a program, there is a type of statement called a  
directive. Directive statements are defined in the System API Reference in the  
section discussing the QPRCRTPG API and are used to do the following:  
Ÿ Control the formatting of the output listing, such as the title, page ejection, and  
so on.  
Ÿ Define entry points within the program for external and internal calls.  
Ÿ Define breakpoints within the program to associate a breakpoint name to a par-  
ticular MI instruction.  
Ÿ Specify the end of the program source.  
The program end (PEND) directive must be the last statement in the source, and it  
functions as a return external (RTX) MI instruction if logically processed as part of  
the instruction stream.  
Noncomment source statements (declares, instructions, and directives) are always  
ended by a semicolon (;). Comments always begin with a slash and asterisk (/ᑍ)  
and end with an asterisk and slash (ᑍ/).  
Writing an MI Program—Example  
This topic shows how to write a simple MI program that receives two packed-  
decimal parameters and returns the larger value through a third parameter. This  
program demonstrates how to do the following:  
Ÿ Define an external entry point  
Ÿ Define and access parameters  
Ÿ Use conditional branching  
Ÿ Assign a value to a scalar object  
Ÿ End the program  
Note: When reviewing this source code, unless noted otherwise, you can find all  
directive and DCL statements in the System API Reference; all other state-  
ments are in the Machine Interface Functional Reference. While this  
chapter attempts to discuss the intent of a statement, refer to the applicable  
reference book for specific details.  
Setting the Entry Point  
First the program, MI01 in this example, needs an ENTRY directive statement to  
designate its external entry point. The following directive declares an unnamed (the  
*) external (the EXT) entry point, which is called with a parameter list corresponding  
to PARM_LIST (defined later in the source code):  
ENTRY ᑍ (PARM_LIST) EXT;  
Setting the Declare Statements  
OS/400 programs typically pass parameters by reference as part of the high-level  
language (HLL) calling convention. Because OS/400 programs pass by reference  
(that is, address and not value), the program also needs to define three space  
pointers (how storage is referenced) to represent the three parameters being  
passed. This is accomplished by the following directives:  
DCL  
DCL  
DCL  
SPCPTR  
SPCPTR  
SPCPTR  
ARG1@  
PARM;  
PARM;  
PARM;  
ARG2@  
RESULT@  
7-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
To associate these three space pointers with the parameters being passed to the  
program, the following operand list (OL) is declared:  
DCL  
OL  
PARM_LIST  
(ARG1@,  
ARG2@,  
RESULT@)  
PARM  
/ᑍ Name of OL is PARM_LIST ᑍ/  
/ᑍ The first parameter  
/ᑍ The second parameter  
/ᑍ The third parameter  
ᑍ/  
ᑍ/  
ᑍ/  
EXT; /ᑍ External parameter list ᑍ/  
The names ARG1@, ARG2@, RESULT@, and PARM_LIST are chosen by you  
and are not mandated by the AS/400 system. You can choose any valid name for  
any object data element. For a definition of what constitutes a valid name, see  
“Name” in the “Program Syntax” topic of the Create Program (QPRCRTPG) API in  
the System API Reference.  
Now that the program has established addressability (the space pointers) to the  
three parameters, the program needs to declare how to map (or view) the storage  
addressed. The following declarations define the storage addressed (the BAS  
argument) by the three space pointer parameters as being packed-decimal (PKD)  
scalar data objects (DD) with 15 digits, 5 digits being to the right of the decimal  
point:  
DCL  
DCL  
DCL  
DD  
DD  
DD  
ARG1  
PKD(15,5)  
PKD(15,5)  
PKD(15,5)  
BAS(ARG1@);  
BAS(ARG2@);  
BAS(RESULT@);  
ARG2  
RESULT  
The names ARG1, ARG2, and RESULT are chosen arbitrarily, but, for ease of  
reading, are similar to the basing space pointers ARG1@, ARG2@, and  
RESULT@. The declarations of packed 15,5 are used for consistency with CL.  
The declared type and size could be of any other valid type and size. The true  
requirement is that the calling program and the MI program agree on the type and  
size.  
Starting the Instruction Stream  
With all the needed declarations now done, the instruction stream definition, where  
the program will compare the numeric values (CMPNV instruction) of parameters  
one and two, is started:  
CMPNV(B)  
ARG1,ARG2 / LO(ITS2);  
The program then branches (the (B) extender to CMPNV) to label ITS2 if ARG1 is  
less than ARG2 (the /LO branch target).  
Note: MI instructions such as CMPNV are defined in the Machine Interface Func-  
tional Reference. Pervasive instruction extenders such as branch (B) and  
target keywords (LO, HI, EQ, and so on) are defined in the System API  
Reference under “Instruction Statement,” which is a subheading in the  
“Program Syntax” topic of the Create Program (QPRCRTPG) API.  
If ARG1 is not low (LO) when compared to ARG2, the next MI instruction in the  
source stream is run. When the next MI instruction is run, it copies the numeric  
value (CPYNV instruction) of ARG1 to RESULT and, following that, branches to  
label RETURN:  
CPYNV  
B
RESULT,ARG1;  
RETURN;  
If ARG2 was greater than ARG1, the CPYNV instruction at label ITS2 is run, setting  
RESULT to the value of ARG2:  
Chapter 7. Machine Interface Programming 7-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ITS2: CPYNV  
The program has now finished processing and ends:  
RETURN: RTX ᑍ;  
RESULT,ARG2;  
PEND;  
The previous return external (RTX) instruction is not needed because it is implied  
by the PEND directive. The RTX instruction is included to add clarity to the  
program flow.  
MI01 Program—Complete Code Example  
Put all together, the program looks like this:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: MIð1  
Programming Language: MI  
Description: Return the larger of two packed arguments.  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ENTRY ᑍ (PARM_LIST) EXT;  
DCL  
DCL  
DCL  
DCL  
SPCPTR  
SPCPTR  
SPCPTR  
OL  
ARG1@  
ARG2@  
PARM;  
PARM;  
PARM;  
RESULT@  
PARM_LIST  
(ARG1@,  
ARG2@,  
RESULT@)  
PARM  
ARG1  
ARG2  
RESULT  
EXT;  
DCL  
DCL  
DCL  
DD  
PKD(15,5)  
PKD(15,5)  
PKD(15,5)  
BAS(ARG1@);  
BAS(ARG2@);  
BAS(RESULT@);  
DD  
DD  
CMPNV(B)  
CPYNV  
B
ARG1,ARG2 / LO(ITS2);  
RESULT,ARG1;  
RETURN;  
ITS2: CPYNV  
RETURN: RTX  
PEND;  
RESULT,ARG2;  
ᑍ;  
Compiling a Program  
If you enter the source into a source physical file, you can now compile the source  
and create an MI program. To create the program, use the Create Program  
(QPRCRTPG) API documented in the System API Reference.  
Note: The QPRCRTPG API assumes that the source statements presented to it  
are in code page 37. See the introduction to the Machine Interface Func-  
tional Reference for the specific code points required to build MI programs.  
7-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Using CLCRTPG to Create an MI Program  
Assume that the source is in a member named MI01 in the source file MISRC,  
which is created with a default record length (RCDLEN) of 92. The following  
CLCRTPG CL program can be used to create an MI program called MI01. (An MI  
program to call the Create Program (QPRCRTPG) API is developed in “Creating an  
MI Version of CLCRTPG” on page 7-11.)  
Note: All non-MI source examples are provided in CL, because CL is the one lan-  
guage (other than REXX) that is standard on all AS/400 systems. Other  
high-level languages (HLLs) could be used in place of the CL programs  
(and in many cases would have been easier).  
The following program reads a source file member into a program variable  
(&MIPGMSRC) and then does a CALL to the QPRCRTPG API. This program has  
many limitations (the major limitation is a program variable-size limit of 2000 bytes  
for the source), but provides for a reasonably simple MI program creation scenario:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: CLCRTPG  
Programming Language: CL  
Description: Create an MI program using the QPRCRTPG API.  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
PGM  
DCLF  
DCL  
DCL  
DCL  
DCL  
DCL  
PARM(&SRCMBR)  
FILE(MISRC)  
VAR(&SRCMBR) TYPE(ᑍCHAR) LEN(1ð)  
VAR(&MIPGMSRC) TYPE(ᑍCHAR) LEN(2ððð)  
VAR(&MIPGMSRCSZ) TYPE(ᑍCHAR) LEN(4)  
VAR(&OFFSET) TYPE(ᑍDEC) LEN(5 ð) VALUE(1)  
VAR(&PGMNAM) TYPE(ᑍCHAR) LEN(2ð) +  
VALUE('  
ᑍCURLIB ')  
DCL  
VAR(&PGMTXT) TYPE(ᑍCHAR) LEN(5ð) +  
VALUE('Compare two packed arguments and +  
return larger')  
DCL  
VAR(&PGMSRCF) TYPE(ᑍCHAR) LEN(2ð) +  
VALUE('ᑍNONE')  
DCL  
DCL  
DCL  
VAR(&PGMSRCM) TYPE(ᑍCHAR) LEN(1ð) VALUE(' ')  
VAR(&PGMSRCCHG) TYPE(ᑍCHAR) LEN(13) VALUE(' ')  
VAR(&PRTFNAM) TYPE(ᑍCHAR) LEN(2ð) +  
VALUE('QSYSPRT ᑍLIBL  
')  
DCL  
DCL  
DCL  
DCL  
RCVF  
VAR(&PRTSTRPAG) TYPE(ᑍCHAR) LEN(4) +  
VALUE(X'ððððððð1')  
VAR(&PGMPUBAUT) TYPE(ᑍCHAR) LEN(1ð) +  
VALUE('ᑍALL  
')  
VAR(&PGMOPTS) TYPE(ᑍCHAR) LEN(22) +  
VALUE('ᑍLIST ᑍREPLACE ')  
VAR(&NUMOPTS) TYPE(ᑍCHAR) LEN(4) +  
VALUE(X'ððððððð2')  
LOOP:  
Chapter 7. Machine Interface Programming 7-5  
Download from Www.Somanuals.com. All Manuals Search And Download.  
MONMSG  
CHGVAR  
CHGVAR  
GOTO  
CHGVAR  
CHGVAR  
CALL  
MSGID(CPFð864) EXEC(GOTO CMDLBL(CRTPGM))  
VAR(%SST(&MIPGMSRC &OFFSET 8ð)) VALUE(&SRCDTA)  
VAR(&OFFSET) VALUE(&OFFSET + 8ð)  
CMDLBL(LOOP)  
VAR(%SST(&PGMNAM 1 1ð)) VALUE(&SRCMBR)  
VAR(%BIN(&MIPGMSRCSZ)) VALUE(&OFFSET)  
PGM(QSYS/QPRCRTPG) PARM(&MIPGMSRC +  
&MIPGMSRCSZ &PGMNAM &PGMTXT &PGMSRCF +  
&PGMSRCM &PGMSRCCHG &PRTFNAM &PRTSTRPAG +  
&PGMPUBAUT &PGMOPTS &NUMOPTS)  
CRTPGM:  
ENDPGM  
Creating the MI Example Program  
After creating the CL program (assumed to be called CLCRTPG), the following  
statements create the previous MI program MI01:  
DLTOVR MISRC  
OVRDBF MISRC MBR(MIð1)  
CALL CLCRTPG MIð1  
Note: If the creation of MI01 fails, you should closely compare your source to that  
shown in this chapter. In general, consider the QPRCRTPG error mes-  
sages that refer to “probable compiler error” as referring to your input  
source and not that the QPRCRTPG API itself is in error. (QPRCRTPG  
assumes its input is probably from a high-level language (HLL) compiler.)  
If the error message is CPF6399 (Identifier not declared), you can get an  
object definition table (ODT) listing by adding *XREF to the option template  
parameter (variable &PGMOPTS in the CLCRTPG program) when calling  
the QPRCRTPG API. Add *XREF to the existing *LIST and *REPLACE  
options, and change the number of option template entries parameter (vari-  
able &NUMOPTS) to 3.  
Testing MI01  
In this topic, assume that MI01 was successfully created. Test the MI01 program  
with the following CL01 CL program:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: CLð1  
Programming Language: CL  
Description: Test the MI program MIð1.  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
PGM  
DCL  
DCL  
DCL  
DCL  
DCL  
PARM(&ARG1 &ARG2)  
VAR(&ARG1) TYPE(ᑍDEC) LEN(15 5)  
VAR(&ARG2) TYPE(ᑍDEC) LEN(15 5)  
VAR(&RESULT) TYPE(ᑍDEC) LEN(15 5)  
VAR(&MSG) TYPE(ᑍCHAR) LEN(2ð)  
VAR(&USR) TYPE(ᑍCHAR) LEN(1ð)  
7-6 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
RTVJOBA  
CALL  
CHGVAR  
SNDMSG  
ENDPGM  
USER(&USR)  
PGM(MIð1) PARM(&ARG1 &ARG2 &RESULT)  
VAR(&MSG) VALUE(&RESULT)  
MSG(&MSG) TOUSR(&USR)  
The following statement calls the CL01 program:  
CALL CLð1 (-5 6)  
This test should cause a message to be sent to your user message queue with the  
following value:  
ððððððððððððð6.ððððð  
Debugging the MI Program  
The MI program (MI01) that you created is a standard *PGM object on the AS/400  
system. As you would expect, you can call MI01 from other high-level languages.  
You can delete MI01 with the Delete Program (DLTPGM) command, save and  
restore MI01 using the standard save (SAV) and restore (RST) commands, and so  
on.  
You can also debug it using the standard debugger on the AS/400 system. To  
debug it, you need to look at the listing produced by the QPRCRTPG API to deter-  
mine the MI instruction number. Then use that number with the Add Breakpoint  
(ADDBKP) CL command. For example, when creating MI01 in the previous exer-  
cise, the following listing was generated by QPRCRTPG:  
5763SS1 V3R1Mð 94ð9ð9  
Generated Output  
ð8/ð8/94 ð9:46:36 Page  
1
SEQ.1/INST Offset  
ðððð1  
Generated Code  
ᑍ... ... 1 ... ... 2 ... ... 3 ... ... 4 ... ... 5 ... ... 6 ... ... 7 ... ... 8  
ENTRY ᑍ (PARM_LIST) EXT  
;
;
;
;
;
;
;
;
;
ðððð2  
DCL SPCPTR ARG1@ PARM  
ðððð3  
DCL SPCPTR ARG2@ PARM  
ðððð4  
DCL SPCPTR RESULT@ PARM  
ðððð5  
DCL OL PARM_LIST (ARG1@, ARG2@, RESULT@) PARM EXT  
DCL DD ARG1 PKD(15,5) BAS(ARG1@)  
DCL DD ARG2 PKD(15,5) BAS(ARG2@)  
DCL DD RESULT PKD(15,5) BAS(RESULT@)  
CMPNV(B) ARG1,ARG2 / LO(ITS2)  
ðððð6  
ðððð7  
ðððð8  
ðððð9 ððð1 ððððð4 3C46 2ððð ððð6 ððð7  
ððð9  
ððð1ð ððð2 ðððððE 1ð42 ððð8 ððð6  
ððð11 ððð3 ðððð14 1ð11 ðððA  
ððð12 ððð4 ðððð18 3ð42 ððð8 ððð7  
ððð13 ððð5 ðððð1E 22A1 ðððð .2/  
ððð14 ððð6 ðððð22 ð26ð  
CPYNV RESULT,ARG1  
B RETURN  
CPYNV RESULT,ARG2  
;
;
ITS2:  
;
RETURN: RTX ᑍ  
PEND  
;
;
5763SS1 V3R1Mð 94ð9ð9  
Generated Output  
Semantics and ODT Syntax Diagnostics  
Generated Output  
ð8/ð8/94 ð9:46:36 Page  
2
3
MSGID  
ODT  
ODT Name  
5763SS1 V3R1Mð 94ð9ð9  
MSGID MI Instruction Stream Semantic Diagnostics  
ð8/ð8/94 ð9:46:36 Page  
Setting Breakpoints in the MI Program  
To view the value of RESULT at label RETURN, you first determine that RETURN  
corresponds to MI instruction (.1/) 0005 (.2/) and enter the following CL com-  
mands:  
STRDBG PGM(MIð1)  
ADDBKP STMT('/ððð5') PGMVAR((RESULT ()))  
CALL CLð1 (-5  
6)  
The following display is shown:  
Chapter 7. Machine Interface Programming 7-7  
Download from Www.Somanuals.com. All Manuals Search And Download.  
à
ð
Display Breakpoint  
Statement/Instruction . . . . . . . . . : /ððð5  
Program . . . . . . . . . . . . . . . . : MIð1  
Recursion level . . . . . . . . . . . . : 1  
Start position . . . . . . . . . . . . : 1  
Format . . . . . . . . . . . . . . . . : ᑍCHAR  
Length . . . . . . . . . . . . . . . . : ᑍDCL  
Variable . . . . . . . . . . . . . . . : RESULT  
Type . . . . . . . . . . . . . . . . :  
Length . . . . . . . . . . . . . . . :  
6.ððððð'  
PACKED  
15 5  
'
Breakpoints also can be set with a directive statement. Given that the MI01  
program is able to be debugged and a break directive was not used, the purpose  
for which you use the directive may not be obvious. As mentioned in “Creating the  
MI Example Program” on page 7-6, many expected users of the QPRCRTPG API  
are compilers of HLLs. The break (BRK) directive allows users of the QPRCRTPG  
API to associate an HLL statement identifier with a generated MI instruction. For  
example, assume that MI01 was developed to be an implementation of a fictional  
HLL language statement such as:  
RESULT = MAX(ARG1, ARG2)  
This assigns the MAX (defined as the largest argument) of ARG1 or ARG2 to  
RESULT. Also assume that an HLL programmer had written a program called  
HLLEXAMPLE with the following statements:  
ðððð1 RESULT = MAX(ARG1, ARG2)  
ðððð2 EXIT  
By using break (BRK) directives, the QPRCRTPG user or compiler could associate  
the HLL statements with the generated MI instructions in the following way:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: MIð1  
Programming Language: MI  
Description: Demonstrate how to associate HLL statement  
identifiers with MI instructions using BRK  
directives.  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ENTRY ᑍ (PARM_LIST) EXT;  
DCL  
DCL  
DCL  
DCL  
SPCPTR  
SPCPTR  
SPCPTR  
OL  
ARG1@  
ARG2@  
PARM;  
PARM;  
PARM;  
RESULT@  
PARM_LIST  
(ARG1@,  
ARG2@,  
RESULT@)  
PARM  
EXT;  
PKD(15,5)  
PKD(15,5)  
DCL  
DCL  
DD  
DD  
ARG1  
ARG2  
BAS(ARG1@);  
BAS(ARG2@);  
7-8 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DCL  
BRK "ðððð1";  
CMPNV(B)  
CPYNV  
B
ITS2: CPYNV  
BRK "ðððð2";  
RETURN: RTX  
PEND;  
DD  
RESULT  
PKD(15,5)  
BAS(RESULT@);  
ARG1,ARG2 / LO(ITS2);  
RESULT,ARG1;  
RETURN;  
RESULT,ARG2;  
ᑍ;  
This allows the HLL programmer to use the following to debug the HLL program by  
using the statement identifiers of the HLL:  
STRDBG PGM(HLLEXAMPLE)  
ADDBKP STMT(ðððð2) PGMVAR((RESULT ()))  
The following display shows that the HLL statement 00002 has been equated with  
MI instruction 0005 due to the use of BRK directives:  
à
ð
Display Breakpoint  
Statement/Instruction . . . . . . . . . : ðððð2 /ððð5  
Program . . . . . . . . . . . . . . . . : HLLEXAMPLE  
Recursion level . . . . . . . . . . . . : 1  
Start position . . . . . . . . . . . . : 1  
Format . . . . . . . . . . . . . . . . : ᑍCHAR  
Length . . . . . . . . . . . . . . . . : ᑍDCL  
Variable . . . . . . . . . . . . . . . : RESULT  
Type . . . . . . . . . . . . . . . . :  
Length . . . . . . . . . . . . . . . :  
6.ððððð'  
PACKED  
15 5  
'
Handling Exceptions in the MI Program  
As coded, the MI01 program works fine when it is passed packed decimal parame-  
ters. But when the MI01 program is passed other data types, such as in CALL  
CL01 (abc 6), exceptions occur. To handle these exceptions, additional state-  
ments could be added to MI01 so that:  
Ÿ A 1-character return code parameter returns a status where ð indicates no  
error and 1 indicates an error occurred.  
Ÿ An exception description is defined to handle MCH1202 decimal data errors.  
Add the following statements to MI01:  
1. Declare a fourth space parameter to receive the return code parameter:  
DCL  
SPCPTR  
RC@  
PARM;  
2. Update the operand list directive for PARM_LIST:  
DCL  
OL  
PARM_LIST  
(ARG1@,  
ARG2@,  
RESULT@,  
RC@)  
/ᑍ the new parameter ᑍ/  
PARM  
EXT;  
3. Declare the storage addressed by RC@ as a 1-byte character data element:  
DCL DD RC CHAR(1) BAS(RC@);  
Chapter 7. Machine Interface Programming 7-9  
Download from Www.Somanuals.com. All Manuals Search And Download.  
4. Declare an exception handler for MCH1202. With this exception description, all  
occurrences of MCH1202 will cause an immediate (IMD) branch to label  
M1202.  
DCL  
EXCM  
DATAERROR EXCID(H'ðCð2') BP (M12ð2) IMD;  
Note: The EXCID is the hexadecimal representation of the message identifier  
string 1202 where 12 = X'0C' and 02 = X'02'. While most MCH  
errors follow this relationship of message ID string to hexadecimal  
EXCID, you should always refer to the Machine Interface Functional  
Reference to determine what specific exception IDs may be signaled by  
a given MI statement.  
5. Because label M1202 is being used to indicate an error, set the return code to  
1 by using copy bytes left-justified and then end:  
M12ð2: CPYBLA  
RC,'1';  
ᑍ;  
RTX  
PEND;  
A more complete example of how to handle exceptions is provided in “Handling  
Exceptions in the MICRTPG2 Program” on page 7-27.  
6. Because the non-M1202 path indicates that no error was detected, update the  
normal return path:  
RETURN: CPYBLA  
RC,'ð';  
7. Because M1202 was appended to the end of the MI01 source, remove the ori-  
ginal MI01 PEND directive.  
The following is an updated view of the MI01 program:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: MIð1  
Programming Language: MI  
Description: Enhanced version of MI program MIð1 that  
demonstrates enabling an exception monitor.  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ENTRY ᑍ (PARM_LIST) EXT;  
DCL  
DCL  
DCL  
DCL  
DCL  
SPCPTR  
SPCPTR  
SPCPTR  
SPCPTR  
OL  
ARG1@  
ARG2@  
RESULT@  
RC@  
PARM;  
PARM;  
PARM;  
PARM;  
PARM_LIST  
(ARG1@,  
ARG2@,  
RESULT@,  
RC@)  
PARM  
EXT;  
DCL  
DCL  
DCL  
DD  
DD  
DD  
ARG1  
PKD(15,5)  
PKD(15,5)  
PKD(15,5)  
BAS(ARG1@);  
BAS(ARG2@);  
BAS(RESULT@);  
ARG2  
RESULT  
7-10 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DCL  
DCL  
DD  
RC  
CHAR(1)  
BAS(RC@);  
EXCM  
CMPNV(B)  
CPYNV  
B
DATAERROR EXCID(H'ðCð2') BP (M12ð2) IMD;  
ARG1,ARG2 / LO(ITS2);  
RESULT,ARG1;  
RETURN;  
RESULT,ARG2;  
RC,'ð';  
ᑍ;  
ITS2: CPYNV  
RETURN: CPYBLA  
RTX  
M12ð2: CPYBLA  
RTX  
RC,'1';  
ᑍ;  
PEND;  
The following example updates CL01 to support the new return code parameter:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: CLð1  
Programming Language: CL  
Description: Enhanced version of CL program CLð1 that  
demonstrates the use of enhanced MIð1.  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
PGM  
PARM(&ARG1 &ARG2)  
DCL  
VAR(&ARG1) TYPE(ᑍDEC) LEN(15 5)  
VAR(&ARG2) TYPE(ᑍDEC) LEN(15 5)  
VAR(&RESULT) TYPE(ᑍDEC) LEN(15 5)  
VAR(&RC) TYPE(ᑍCHAR) LEN(1)  
VAR(&MSG) TYPE(ᑍCHAR) LEN(2ð)  
VAR(&USR) TYPE(ᑍCHAR) LEN(1ð)  
USER(&USR)  
DCL  
DCL  
DCL  
DCL  
DCL  
RTVJOBA  
CALL  
IF  
PGM(MIð1) PARM(&ARG1 &ARG2 &RESULT &RC)  
COND(&RC = 'ð') +  
THEN(CHGVAR  
VAR(&MSG) VALUE(&RESULT))  
ELSE +  
CHGVAR  
SNDMSG  
ENDPGM  
VAR(&MSG) VALUE('ERROR FOUND')  
MSG(&MSG) TOUSR(&USR)  
After recompiling the MI01 program and the CL01 program, CALL CL01 (abc 6)  
now results in the following message (not the previous MCH1202):  
ERROR FOUND  
Creating an MI Version of CLCRTPG  
The topics previous to this discuss how to create MI01 to be a reasonably complete  
program. This topic discusses how to create an MI version of the CLCRTPG  
program that can be used to create MI programs. This program is called  
MICRTPG.  
Chapter 7. Machine Interface Programming 7-11  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Because the CLCRTPG program is used to create the initial version of MICRTPG  
and CLCRTPG can support only as many as 2000 bytes of source in the  
&MIPGMSRC variable, MICRTPG is initially defined with a minimal set of function.  
Significant additions to the MICRTPG program can be made after it is used as a  
building block in the creation of MI programs.  
In the initial design (see the program flow on page 7-13), there are four programs.  
The first program is a CL program (CL03) that does the following:  
Ÿ Creates a user space (*USRSPC) object of 64KB size to hold the MI source.  
Ÿ Overrides the MISRC file to the appropriate source physical file and  
member.1/.  
Ÿ Calls a second CL program (CL04), which loads the selected MISRC member  
into the user space (*USRSPC).2/.  
Ÿ Calls an MI program (MICRTPG).3/. The MICRTPG program calls CL  
program CL05.4/ and passes addressability to the *USRSPC, where CL05  
then calls the QPRCRTPG API.5/.  
The MICRTPG program demonstrates how to do the following:  
Ÿ Define a structure  
Ÿ Initialize declared storage  
Ÿ Use two different approaches to resolve a system pointer to an external object  
Ÿ Assign a space pointer to address a user space  
Ÿ Call a program and pass three parameters  
The overall program flow appears as follows:  
CL Pgm CL03  
MISRC  
CL Pgm  
CL04  
USRSPC  
MI Pgm MICRTPG  
CL Pgm  
CL05  
API  
QPRCRTPG  
RV3W216-2  
Figure 7-1. Program Flow for Creating the MICRTPG Program  
7-12 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Source for the CL03 Program  
The source for CL03 follows:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: CLð3  
Programming Language: CL  
Description: Main driver program for initial version of  
MI program MICRTPG. This program creates a  
ᑍUSRSPC, calls CLð4 to load MI source from  
a ᑍSRC physical file into the ᑍUSRSPC, and  
then calls MICRTPG to create MI programs.  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
PGM  
DCL  
DCL  
DCL  
PARM(&FILE &MBR)  
VAR(&FILE) TYPE(ᑍCHAR) LEN(1ð)  
VAR(&MBR) TYPE(ᑍCHAR) LEN(1ð)  
VAR(&SPCNAM) TYPE(ᑍCHAR) LEN(2ð) +  
VALUE('  
ᑍCURLIB ')  
DCL  
DCL  
VAR(&SPCEXTATR) TYPE(ᑍCHAR) LEN(1ð) VALUE(' ')  
VAR(&SPCSIZ) TYPE(ᑍCHAR) LEN(4) +  
VALUE(X'ððð1ðððð')  
DCL  
DCL  
VAR(&SPCINTVAL) TYPE(ᑍCHAR) LEN(1) VALUE(X'ðð')  
VAR(&SPCSPCAUT) TYPE(ᑍCHAR) LEN(1ð) +  
VALUE('ᑍALL')  
DCL  
DCL  
VAR(&SPCTXTDSC) TYPE(ᑍCHAR) LEN(5ð) VALUE(' ')  
VAR(&SPCRPLOPT) TYPE(ᑍCHAR) LEN(1ð) +  
VALUE('ᑍYES')  
VAR(&ERRCOD) TYPE(ᑍCHAR) LEN(4) +  
VALUE(X'ðððððððð')  
DCL  
DCL  
DCL  
VAR(&SPCDMN) TYPE(ᑍCHAR) LEN(1ð) VALUE('ᑍUSER')  
VAR(&BINOFFSET) TYPE(ᑍCHAR) LEN(4) +  
VALUE(X'ððððððð1')  
CHGVAR  
CALL  
VAR(%SST(&SPCNAM 1 1ð)) VALUE(&MBR)  
PGM(QUSCRTUS) PARM(&SPCNAM &SPCEXTATR +  
&SPCSIZ &SPCINTVAL &SPCSPCAUT &SPCTXTDSC +  
&SPCRPLOPT &ERRCOD &SPCDMN)  
OVRDBF  
CALL  
FILE(MISRC) TOFILE(&FILE) MBR(&MBR)  
PGM(CLð4) PARM(&MBR &BINOFFSET)  
PGM(MICRTPG) PARM(&MBR &BINOFFSET)  
CALL  
ENDPGM  
Source for the CL04 Program  
The source for CL04 follows:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: CLð4  
Programming Language: CL  
Chapter 7. Machine Interface Programming 7-13  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Description: Load a source physical file member into the  
ᑍUSRSPC named &MBR.  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
PGM  
DCLF  
DCL  
DCL  
DCL  
DCL  
PARM(&MBR &BINOFFSET)  
FILE(MISRC)  
VAR(&MBR) TYPE(ᑍCHAR) LEN(1ð)  
VAR(&BINOFFSET) TYPE(ᑍCHAR) LEN(4)  
VAR(&OFFSET) TYPE(ᑍDEC) LEN(8 ð) VALUE(1)  
VAR(&LENGTH) TYPE(ᑍCHAR) LEN(4) +  
VALUE(X'ðððððð5ð')  
DCL  
VAR(&SPCNAM) TYPE(ᑍCHAR) LEN(2ð) +  
VALUE('  
ᑍLIBL  
')  
CHGVAR  
RCVF  
VAR(%SST(&SPCNAM 1 1ð)) VALUE(&MBR)  
LOOP:  
DONE:  
MONMSG  
CALL  
MSGID(CPFð864) EXEC(GOTO CMDLBL(DONE))  
PGM(QUSCHGUS) PARM(&SPCNAM &BINOFFSET +  
&LENGTH &SRCDTA 'ð')  
CHGVAR  
CHGVAR  
GOTO  
VAR(&OFFSET) VALUE(&OFFSET + 8ð)  
VAR(%BIN(&BINOFFSET)) VALUE(&OFFSET)  
CMDLBL(LOOP)  
ENDPGM  
Source for the CL05 Program  
The source for CL05 follows:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: CLð5  
Programming Language: CL  
Description: Create an MI program using the QPRCRTPG API.  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
PGM  
DCL  
DCL  
DCL  
DCL  
PARM(&SRCMBR &MIPGMSRC &MIPGMSRCSZ)  
VAR(&SRCMBR) TYPE(ᑍCHAR) LEN(1ð)  
VAR(&MIPGMSRC) TYPE(ᑍCHAR) LEN(1)  
VAR(&MIPGMSRCSZ) TYPE(ᑍCHAR) LEN(4)  
VAR(&PGMNAM) TYPE(ᑍCHAR) LEN(2ð) +  
VALUE('  
ᑍCURLIB ')  
DCL  
DCL  
VAR(&PGMTXT) TYPE(ᑍCHAR) LEN(5ð) +  
VALUE(' ')  
VAR(&PGMSRCF) TYPE(ᑍCHAR) LEN(2ð) +  
VALUE('ᑍNONE')  
DCL  
DCL  
VAR(&PGMSRCM) TYPE(ᑍCHAR) LEN(1ð) VALUE(' ')  
VAR(&PGMSRCCHG) TYPE(ᑍCHAR) LEN(13) VALUE(' ')  
7-14 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DCL  
DCL  
DCL  
DCL  
DCL  
VAR(&PRTFNAM) TYPE(ᑍCHAR) LEN(2ð) +  
VALUE('QSYSPRT ᑍLIBL ')  
VAR(&PRTSTRPAG) TYPE(ᑍCHAR) LEN(4) +  
VALUE(X'ððððððð1')  
VAR(&PGMPUBAUT) TYPE(ᑍCHAR) LEN(1ð) +  
VALUE('ᑍALL  
')  
VAR(&PGMOPTS) TYPE(ᑍCHAR) LEN(22) +  
VALUE('ᑍLIST ᑍREPLACE ')  
VAR(&NUMOPTS) TYPE(ᑍCHAR) LEN(4) +  
VALUE(X'ððððððð2')  
CHGVAR  
CALL  
VAR(%SST(&PGMNAM 1 1ð)) VALUE(&SRCMBR)  
PGM(QSYS/QPRCRTPG) PARM(&MIPGMSRC +  
&MIPGMSRCSZ &PGMNAM &PGMTXT &PGMSRCF +  
&PGMSRCM &PGMSRCCHG &PRTFNAM &PRTSTRPAG +  
&PGMPUBAUT &PGMOPTS &NUMOPTS)  
ENDPGM  
Source for the MICRTPG Program  
The source for MICRTPG follows:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: MICRTPG  
Programming Language: MI  
Description: Initial version of MI program to create  
additional MI programs using the QPRCRTPG API. ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ENTRY ᑍ (PARM_LIST) EXT;  
DCL SPCPTR MBR@ PARM;  
DCL SPCPTR BINOFFSET@ PARM;  
DCL OL PARM_LIST (MBR@, BINOFFSET@) PARM EXT;  
DCL DD MBR CHAR(1ð) BAS(MBR@);  
DCL DD BINOFFSET BIN(4) BAS(BINOFFSET@);  
DCL DD RSLVOBJ CHAR(34);  
DCL DD RSLVTYPE CHAR(1) DEF(RSLVOBJ) POS(1) INIT(X'19');  
DCL DD RSLVSUBTYPE CHAR(1) DEF(RSLVOBJ) POS(2) INIT(X'34');  
DCL DD RSLVNAME CHAR(3ð) DEF(RSLVOBJ) POS(3);  
DCL DD RSLVAUTH CHAR(2) DEF(RSLVOBJ) POS(33) INIT(X'ðððð');  
DCL SYSPTR USRSPCOBJ;  
DCL SPCPTR USRSPC;  
DCL SYSPTR CLð5 INIT("CLð5", TYPE(PGM));  
DCL OL CLð5OL (MBR@, USRSPC, BINOFFSET@) ARG;  
CPYBLAP RSLVNAME, MBR, ' ';  
RSLVSP USRSPCOBJ, RSLVOBJ, ᑍ, ᑍ;  
SETSPPFP USRSPC, USRSPCOBJ;  
CALLX CLð5, CLð5OL, ᑍ;  
RTX ᑍ;  
PEND;  
Chapter 7. Machine Interface Programming 7-15  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Understanding the MICRTPG Program (by Sections of Code)  
You will recognize some of these statements from the MI01 example, but others  
are new.  
The following statements, which you have seen, for example, in “MI01  
Program—Complete Code Example,” define the entry point to this program and the  
parameters being passed on the call:  
ENTRY ᑍ (PARM_LIST) EXT;  
DCL SPCPTR MBR@ PARM;  
DCL SPCPTR BINOFFSET@ PARM;  
DCL OL PARM_LIST (MBR@, BINOFFSET@) PARM EXT;  
DCL DD MBR CHAR(1ð) BAS(MBR@);  
DCL DD BINOFFSET BIN(4) BAS(BINOFFSET@);  
Declaring the Structure  
The following, however, are new statements:  
DCL DD RSLVOBJ CHAR(34);  
DCL DD RSLVTYPE CHAR(1) DEF(RSLVOBJ) POS(1) INIT(X'19');  
DCL DD RSLVSUBTYPE CHAR(1) DEF(RSLVOBJ) POS(2) INIT(X'34');  
DCL DD RSLVNAME CHAR(3ð) DEF(RSLVOBJ) POS(3);  
DCL DD RSLVAUTH CHAR(2) DEF(RSLVOBJ) POS(33) INIT(X'ðððð');  
These statements declare a structure named RSLVOBJ that comprises four subele-  
ments defined within it. The subelements specify their position relative to the start  
of the structure RSLVOBJ. In the cases of the RSLVTYPE, RSLVSUBTYPE, and  
RSLVAUTH data elements, they initialize the associated storage.  
The RSLVOBJ structure is used later in the program as an input to the resolve  
system pointer (RSLVSP) MI instruction. The RSLVSP instruction resolves (estab-  
lishes addressability) to a user space (*USRSPC) (the X'1934' object type and  
subtype) named RSLVNAME (assigned from the source member name (MBR) data  
element). This user space is the one created in “Source for the CL03 Program” on  
page 7-13. If you are interested in the details of this structure, see the Machine  
Interface Functional Reference under RSLVSP. For other valid object types and  
subtypes, see AS/400 Licensed Internal Code Diagnostic Aids – Volume 1,  
LY44-5900, and AS/400 Licensed Internal Code Diagnostic Aids – Volume 2,  
LY44-5901.  
Note: In the declare (DCL) statement of RSLVOBJ, the leading blanks used to  
indent the subelements (for example, RSLVTYPE and RSLVSUBTYPE) are  
strictly to enhance the readability of the source. They are not a requirement  
of the QPRCRTPG API. In general, you can use strings of blanks of any  
length in the source of a program. Blanks, one or more, are simply used as  
delimiters in identifying tokens. The major exception is the INIT argument  
of a DCL statement where the number of blanks is important. For example,  
the previous declare statement could have been written as follows and other  
than readability, nothing would have been lost:  
DCL DD RSLVOBJ CHAR(34); DCL DD RSLVTYPE CHAR(1)  
DEF(RSLVOBJ) POS(1) INIT(X'19');  
DEF(RSLVOBJ)  
DCL DD RSLVSUBTYPE CHAR(1)  
POS(2)  
INIT(X'34'); DCL DD RSLVNAME CHAR(3ð) DEF(RSLVOBJ) POS(3); DCL  
DD RSLVAUTH CHAR(2) DEF(RSLVOBJ) POS(33) INIT(X'ðððð');  
7-16 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Declaring Pointers  
The next statements declare a system pointer named USRSPCOBJ and a space  
pointer named USRSPC. USRSPCOBJ contains the address of the *USRSPC  
object after the execution of the RSLVSP instruction later in the instruction stream.  
USRSPC addresses the first byte of the *USRSPC:  
DCL SYSPTR USRSPCOBJ;  
DCL SPCPTR USRSPC;  
Defining an External Call  
Because this program also uses the call external (CALLX) instruction to call the CL  
program CL05, define a system pointer for CL05:  
DCL SYSPTR CLð5 INIT("CLð5", TYPE(PGM));  
The preceding statement causes the QPRCRTPG API to initialize the system  
pointer CL05 to the name of the PGM CL05. The CL05 pointer is not set to the  
address of the CL05 object—this happens the first time the CL05 pointer is referred  
to in the instruction stream. If you review the System API Reference for this  
declare statement, notice that the context (CTX) argument uses the default. Using  
the context default (better known as library to most programmers) is equivalent to  
specifying *LIBL. *LIBL is referred to as the process name resolution list in the  
Machine Interface Functional Reference.  
Because this program calls the CL05 program (CALLX CL05) with parameters, it  
now defines an operand list CL05OL, which specifies the arguments to be passed  
on the CALLX:  
DCL OL CLð5OL (MBR@, USRSPC, BINOFFSET@) ARG;  
When you get to the instruction stream of MICRTPG, copy the passed parameter  
MBR to the data structure element RSLVNAME. As RSLVNAME is defined as  
CHAR(30) and MBR is CHAR(10), the program uses the copy bytes left-justified  
with pad (CPYBLAP) instruction to set the rightmost 20 bytes of RSLVNAME to the  
value of the third argument (in this case, blanks):  
CPYBLAP RSLVNAME, MBR, ' ';  
Having established the *USRSPC name, use the RSLVSP instruction to get  
addressability to the object itself:  
RSLVSP USRSPCOBJ, RSLVOBJ, ᑍ, ᑍ;  
Note: Similar to how the *USRSPC name was resolved, RSLVSP could be used  
with a type of X'02' and a subtype of X'01' to resolve a system pointer to  
the CL05 *PGM object. The two different approaches were used to demon-  
strate the different styles (RSLVSP is clearly more flexible) and also to stay  
within the 2000-byte limit of the program source size imposed by the  
CLCRTPG program.  
Then set the USRSPC space pointer to the first byte of the *USRSPC:  
SETSPPFP USRSPC, USRSPCOBJ;  
Chapter 7. Machine Interface Programming 7-17  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Calling the CL05 Program  
Now the program will call the CL05 program (CALLX CL05) and pass the address  
of the *USRSPC as a parameter (along with the member name, program name,  
and the size of the source stream). When you call CL05 with the operand list  
CL05OL, CL05 passes the actual space pointer USRSPC. CL05 does not pass a  
space pointer that refers to the space pointer USRSPC (as opposed to how MBR@  
and BINOFFSET@ are passed to refer to MBR and BINOFFSET, respectively).  
This has the effect of having the CL05 program treat the *USRSPC storage as the  
parameter:  
CALLX CLð5, CLð5OL, ᑍ;  
Finally, as the program comes to an end, this is the return external instruction and  
pend directive for the initial version of MICRTPG:  
RTX ᑍ;  
PEND;  
Creating the MICRTPG Program  
To create MICRTPG, use the following CL commands:  
DLTOVR MISRC  
OVRDBF MISRC MBR(MICRTPG)  
CALL CLCRTPG MICRTPG  
Assuming a successful creation, the CLCRTPG program is not used again because  
of the MI base with which to work (for example, MICRTPG is used as a boot-strap  
for further compiler enhancement).  
Enhanced Version of the MICRTPG Program  
Now that the MICRTPG program provides addressability (through the *USRSPC as  
a parameter to the CL05 program) for as many as 64KB of input source, a new  
version of MICRTPG (named MICRTPG2) will incorporate the functions of the CL03  
program and the CL05 program. A modified form of CL04 (renamed to CL06) is  
used in these examples to read the MISRC source physical file because MI instruc-  
tion support for database access is beyond the scope of this chapter.  
The MICRTPG2 program demonstrates how to do the following:  
Ÿ Receive a variable number of parameters  
Ÿ Use static and automatic storage  
Ÿ Create a space object  
Ÿ Perform arithmetic operations  
Understanding the MICRTPG2 Program (by Sections of Code)  
Writing the program code for MICRTPG2:  
1. Define the entry point and associated parameters:  
ENTRY ᑍ (PARM_LIST) EXT;  
DCL SPCPTR FIL@ PARM;  
DCL SPCPTR MBR@ PARM;  
DCL OL PARM_LIST (MBR@, FIL@) PARM EXT MIN(1);  
DCL DD FIL CHAR(1ð) BAS(FIL@);  
DCL DD MBR CHAR(1ð) BAS(MBR@);  
DCL DD NUM_PARMS BIN(4);  
7-18 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
2. Have MICRTPG2 create an automatically extendable space (it can automat-  
ically increase to as many as 16MB in size) using the Create Space (CRTS)  
instruction. Because the CRTS instruction requires a definition template, you  
need to define it (see the Machine Interface Functional Reference for details).  
The following template creates a space (type and subtype equal to X'19EF')  
that is defined through the OBJCRTOPT data element.1/. The space is  
defined as temporary (the next initial program load (IPL) will free up the storage  
occupied by the space), extendable up to as many as 16MB, and within a  
context (a library).  
DCL DD CRTSTMPLT CHAR(16ð) BDRY(16);  
DCL DD TMPLTSPEC CHAR(8) DEF(CRTSTMPLT) POS(1);  
DCL DD TMPLTSIZE BIN(4) DEF(TMPLTSPEC) POS(1) INIT(16ð);  
DCL DD TMPLTBA BIN(4) DEF(TMPLTSPEC) POS(5) INIT(ð);  
DCL DD OBJID CHAR(32) DEF(CRTSTMPLT) POS(9);  
DCL DD SPCTYPE CHAR(1) DEF(OBJID) POS(1) INIT(X'19');  
DCL DD SPCSUBTYPE CHAR(1) DEF(OBJID) POS(2) INIT(X'EF');  
DCL DD SPCNAME CHAR(3ð) DEF(OBJID) POS(3) INIT(" ");  
DCL DD OBJCRTOPT CHAR(4) DEF(CRTSTMPLT) POS(41) INIT(X'6ðð2ðððð');.1/  
DCL DD OBJRCVOPTS CHAR(4) DEF(CRTSTMPLT) POS(45);  
DCL DD ᑍ CHAR(2) DEF(OBJRCVOPTS) POS(1) INIT(X'ðððð');  
DCL DD ASP CHAR(2) DEF(OBJRCVOPTS) POS(3) INIT(X'ðððð');  
DCL DD SPCSIZ BIN(4) DEF(CRTSTMPLT) POS(49) INIT(1);  
DCL DD INTSPCVAL CHAR(1) DEF(CRTSTMPLT) POS(53) INIT(X'ðð');  
DCL DD PERFCLASS CHAR(4) DEF(CRTSTMPLT) POS(54) INIT(X'ðððððððð');  
DCL DD ᑍ CHAR(1) DEF(CRTSTMPLT) POS(58) INIT(X'ðð');  
DCL DD PUBAUT CHAR(2) DEF(CRTSTMPLT) POS(59) INIT(X'ðððð');  
DCL DD TMPLTEXTN BIN(4) DEF(CRTSTMPLT) POS(61) INIT(96);  
DCL SYSPTR CONTEXT DEF(CRTSTMPLT) POS(65);  
DCL SYSPTR ACCESSGRP DEF(CRTSTMPLT) POS(81);  
DCL SYSPTR USRPRF DEF(CRTSTMPLT) POS(97);  
DCL DD MAXSPCSIZ BIN(4) DEF(CRTSTMPLT) POS(113) INIT(ð);  
DCL DD DOMAIN CHAR(2) DEF(CRTSTMPLT) POS(117) INIT(X'ððð1');  
DCL DD ᑍ CHAR(42) DEF(CRTSTMPLT) POS(119) INIT((42)X'ðð');  
3. Establish addressability to the CRTS template:  
DCL SPCPTR CRTSTMPLT@ INIT(CRTSTMPLT);  
4. Because the space is defined to be in a context, supply the address of the  
context in the previous CRTS template. This program uses the QTEMP context  
that is identified by the following:  
DCL SYSPTR QTEMP@ BASPCO POS(65);  
Use the copy bytes with pointers instruction (CPYBWP) to set the template  
context data element.  
CPYBWP CONTEXT, QTEMP@;  
5. In the instruction stream, create the space:  
CRTS USRSPC@, CRTSTMPLT@;  
This returns a system pointer to the created space in the system pointer:  
DCL SYSPTR USRSPC@;  
6. Declare a space pointer for addressability to the space through a space pointer  
(as opposed to the system pointer returned by the CRTS instruction):  
DCL SPCPTR USRSPC;  
Chapter 7. Machine Interface Programming 7-19  
Download from Www.Somanuals.com. All Manuals Search And Download.  
7. To keep track of how many bytes of source are loaded into the *USRSPC,  
define BINOFFSET. BINOFFSET is also being defined very specifically as an  
integer (BIN(4)) because it will be used later in the program with the set space  
pointer offset (SETSPPO) MI instruction. This requires an integer argument to  
refer to the space:  
DCL DD BINOFFSET BIN(4) AUTO INIT(ð);  
8. Because the size of the source is also a parameter to the QPRCRTPG API,  
define a space pointer to refer to BINOFFSET:  
DCL SPCPTR BINOFFSET@ AUTO INIT(BINOFFSET);  
The two previous declare statements have also introduced a new attribute to  
the DCL statement. Previously, all of the DCLs used the default of static  
(STAT) storage. BINOFFSET and BINOFFSET@, on the other hand, are being  
allocated from automatic (AUTO) storage. Many hours of debug time can be  
saved if you clearly understand how the AS/400 manages these two types of  
storage. For more information on the types of storage, see “AS/400 Program  
Storage” on page 7-36.  
So that the program does not retain the size of the source loaded from pre-  
vious invocations of the program, you can declare BINOFFSET as being auto-  
matic. Because BINOFFSET@ needs to be set to the address of BINOFFSET  
(so that BINOFFSET can be passed as a parameter to CL06), you will also  
declare it as automatic. An alternative to using automatic storage would have  
been to explicitly set a static storage BINOFFSET to 0 by using CPYNV, but  
this does not allow for a discussion of the storage management differences.  
9. Use the CL06 program to load the space after it is created. Because CL06 is  
limited to only 2000 bytes of addressability per parameter per call (CALLX), the  
MICRTPG2 program uses the Override with Database File (OVRDBF) CL  
command to cause the CL06 program to read and load twenty 80-byte source  
records per call. The source records are read starting at 1 on the first call, 21  
on the second, 41 on the third, and so on. To run CL commands from the  
MICRTPG2 program, the program uses the Execute Command (QCMDEXC)  
API:  
DCL SYSPTR QCMDEXC INIT("QCMDEXC", CTX("QSYS"), TYPE(PGM));  
10. Format the appropriate character strings for the Override with Database File  
(OVRDBF) CL command:  
Note: In the following declare (DCL) statement for CLOVRCMD, the 3 strings  
of '1234567890' are used strictly so that you can see that 10 bytes are  
being used. The strings themselves are overridden by the subsequent  
subelement DCLs for FILNAM, MBRNAM, and RECNUM, and could be  
replaced by 10 blanks:  
DCL DD CLOVRCMD CHAR(65);  
DCL DD OVRSTR CHAR(39) DEF(CLOVRCMD) POS(1)  
INIT("OVRDBF MISRC 123456789ð MBR(123456789ð)");  
DCL DD OVRSTR2 CHAR(26) DEF(CLOVRCMD) POS(4ð)  
INIT(" POSITION(ᑍRRN 123456789ð)");  
DCL DD FILNAM CHAR(1ð) DEF(CLOVRCMD) POS(14);  
DCL DD MBRNAM CHAR(1ð) DEF(CLOVRCMD) POS(29);  
DCL DD RECNUM ZND(1ð,ð) DEF(CLOVRCMD) POS(55);  
11. Format the appropriate character strings for the Delete Override (DLTOVR) CL  
command. Because the OVRDBF commands are issued repetitively to  
progress through the source, the previous overrides need to be deleted:  
7-20 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DCL DD CLDLTCMD CHAR(12) INIT("DLTOVR MISRC");  
12. Establish space pointers to the CL command parameters, and, because the  
QCMDEXC API is being used, define the CL command string lengths as  
parameters:  
DCL SPCPTR CLOVRCMD@ INIT(CLOVRCMD);  
DCL SPCPTR CLDLTCMD@ INIT(CLDLTCMD);  
DCL DD CLOVRLNG PKD(15,5) INIT(P'65'); /ᑍ Length of OVRDBF CL cmd ᑍ/  
DCL SPCPTR CLOVRLNG@ INIT(CLOVRLNG);  
DCL DD CLDLTLNG PKD(15,5) INIT(P'12'); /ᑍ Length of DLTOVR CL cmd ᑍ/  
DCL SPCPTR CLDLTLNG@ INIT(CLDLTLNG);  
13. Define the operand list (OL) definitions for calling the QCMDEXC API under the  
two different conditions:  
DCL OL QCMDOVROL (CLOVRCMD@, CLOVRLNG@) ARG;  
DCL OL QCMDDLTOL (CLDLTCMD@, CLDLTLNG@) ARG;  
14. Because CALLX CL06 is called to load the space, declare its system pointer,  
parameters, and OL:  
DCL SYSPTR CLð6 INIT("CLð6", TYPE(PGM));  
DCL DD OFFSET PKD(15,5);  
DCL SPCPTR OFFSET@ INIT(OFFSET);  
DCL OL CLð6OL (USRSPC, OFFSET@) ARG;  
15. Declare the system pointer, parameters, and OL for the QPRCRTPG API:  
DCL DD PGM CHAR(2ð);  
DCL DD PGMNAM CHAR(1ð) DEF(PGM) POS(1);  
DCL DD PGMLIBNAM CHAR(1ð) DEF(PGM) POS(11) INIT("ᑍCURLIB ");  
DCL SPCPTR PGM@ INIT(PGM);  
DCL DD PGMTXT CHAR(5ð) INIT(" ");  
DCL SPCPTR PGMTXT@ INIT(PGMTXT);  
DCL DD PGMSRCF CHAR(2ð) INIT("ᑍNONE");  
DCL SPCPTR PGMSRCF@ INIT(PGMSRCF);  
DCL DD PGMSRCM CHAR(1ð) INIT(" ");  
DCL SPCPTR PGMSRCM@ INIT(PGMSRCM);  
DCL DD PGMSRCCHG CHAR(13) INIT(" ");  
DCL SPCPTR PGMSRCCHG@ INIT(PGMSRCCHG);  
DCL DD PRTFNAM CHAR(2ð) INIT("QSYSPRT ᑍLIBL  
DCL SPCPTR PRTFNAM@ INIT(PRTFNAM);  
DCL DD PRTSTRPAG BIN(4) INIT(1);  
");  
DCL SPCPTR PRTSTRPAG@ INIT(PRTSTRPAG);  
DCL DD PGMPUBAUT CHAR(1ð) INIT("ᑍALL  
DCL SPCPTR PGMPUBAUT@ INIT(PGMPUBAUT);  
");  
DCL DD PGMOPTS(16) CHAR(11) INIT((1)"ᑍLIST", ᑍ(2)(1)"ᑍREPLACE");  
DCL SPCPTR PGMOPTS@ INIT(PGMOPTS);  
DCL DD NUMOPTS BIN(4) INIT(2);  
DCL SPCPTR NUMOPTS@ INIT(NUMOPTS);  
DCL OL QPRCRTPGOL (USRSPC, BINOFFSET@, PGM@, PGMTXT@, PGMSRCF@,  
PGMSRCM@, PGMSRCCHG@, PRTFNAM@, PRTSTRPAG@,  
PGMPUBAUT@, PGMOPTS@, NUMOPTS@) ARG;  
DCL SYSPTR QPRCRTPG INIT("QPRCRTPG", CTX("QSYS"), TYPE(PGM));  
Chapter 7. Machine Interface Programming 7-21  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Beginning the Instruction Stream  
Begin the instruction stream definition by doing the following:  
1. Use the store parameter list length (STPLLEN) instruction to determine the  
number of parameters that were passed to the program:  
STPLLEN NUM_PARMS;  
2. If the number of parameters is 1, assign FILNAM to the value MISRC (the  
default that this program supports for the source physical file) and branch to  
label PARM1 to set the source member name:  
CMPNV(B) NUM_PARMS, 2 / EQ(PARM2);  
CPYBLAP FILNAM, 'MISRC', ' ';  
B PARM1;  
3. If the number of parameters is 2, assign FILNAM to the value of the second  
parameter:  
PARM2: CPYBLA FILNAM, FIL;  
4. Assign the source member name:  
PARM1: CPYBLA MBRNAM, MBR;  
5. Assign the proper context for the space:  
CPYBWP CONTEXT, QTEMP@;  
6. After establishing the context of the space, now create the space:  
CRTS USRSPC@, CRTSTMPLT@;  
7. Assign the space pointer USRSPC to address the first byte of the space:  
SETSPPFP USRSPC, USRSPC@;  
8. Set the OVRDBF CL command to start with POSITION(1):  
CPYNV RECNUM, 1;  
Using Static Storage to Your Advantage  
In “Beginning the Instruction Stream,” the instructions in steps 5, 6, and 7 can be  
done once and the space reused on subsequent invocations of the program. As a  
performance enhancement, add a check to see if this program has been previously  
invoked. To do the check, add a control field, and conditionally branch around the  
CRTS-oriented instructions if this call is not the initial call:  
STPLLEN NUM_PARMS;  
CMPNV(B) NUM_PARMS, 2 / EQ(PARM2);  
CPYBLAP FILNAM, 'MISRC', ' ';  
B PARM1;  
PARM2: CPYBLA FILNAM, FIL;  
PARM1: CPYBLA MBRNAM,MBR;  
CMPBLA(B) READY, '1' / EQ(SKIP);  
CPYBWP CONTEXT, QTEMP@;  
CRTS USRSPC@, CRTSTMPLT@;  
SETSPPFP USRSPC,USRSPC@;  
CPYBLA READY, '1';  
SKIP: CPYNV RECNUM, 1;  
Resuming the program flow of the MICRTPG2 program from “Beginning the Instruc-  
tion Stream” on page 7-22, you should have the program perform the following:  
7-22 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
1. Fall into a loop (the MORE label) until all source records are loaded as the  
source physical file member position is overridden:  
MORE: CALLX QCMDEXC, QCMDOVROL, ᑍ;  
2. Instruct the CL06 program to load source records from the start of the input  
buffer, which is actually the BINOFFSET into the space created earlier:  
CPYNV OFFSET,1;  
CALLX CLð6, CLð6OL, ᑍ;  
3. Back out (subtract) the base-1 nature of CL using the short (the (S) extender)  
form of the subtract numeric (SUBN) instruction:  
SUBN(S) OFFSET, 1;  
4. Add the number of MI source bytes processed by CL06 to the offset into the  
space (for the next call):  
ADDN(S) BINOFFSET, OFFSET;  
SETSPPO USRSPC, BINOFFSET;  
5. Update the Override with Database File (OVRDBF) position parameter for the  
next call to CL06:  
ADDN(S) RECNUM, 2ð;  
6. Delete the previous OVRDBF:  
CALLX QCMDEXC, QCMDDLTOL, ᑍ;  
7. Check to see if all records were processed, and if not, branch to label MORE to  
load more source records:  
CMPNV(B) OFFSET, 16ðð /EQ(MORE);  
Otherwise, assume that all source was loaded and prepare for calling the  
QPRCRTPG API by setting the program name:  
CPYBLA PGMNAM, MBR;  
8. Reset the space pointer from the source of the input program to the start of the  
space. This resetting of the static storage USRSPC is also assumed in the  
branch to label SKIP earlier in the program:  
SETSPPO USRSPC,ð;  
9. Call the QPRCRTPG API to create the MI program:  
CALLX QPRCRTPG, QPRCRTPGOL, ᑍ;  
10. Indicate that the program is done:  
RTX ᑍ;  
PEND;  
MICRTPG2 Complete Program—MI Code Example  
In its consolidated state, this is the new MICRTPG2 program:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: MICRTPG2  
Programming Language: MI  
Description: Initial version of MI program MICRTPG2,  
Chapter 7. Machine Interface Programming 7-23  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
which calls QPRCRTPG API.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Entry point and associated parameters  
ᑍ/  
ENTRY ᑍ (ᑍENTRY) EXT;  
DCL SPCPTR FIL@ PARM;  
DCL SPCPTR MBR@ PARM;  
DCL OL ᑍENTRY (MBR@, FIL@) PARM EXT MIN(1);  
DCL DD FIL CHAR(1ð) BAS(FIL@);  
DCL DD MBR CHAR(1ð) BAS(MBR@);  
DCL DD NUM_PARMS BIN( 4);  
/ᑍ Control field for first time initialization ᑍ/  
DCL DD READY CHAR( 1) INIT("ð");  
/ᑍ Binary offset into the space  
ᑍ/  
ᑍ/  
ᑍ/  
DCL DD BINOFFSET BIN(4) AUTO INIT(ð);  
DCL SPCPTR BINOFFSET@ AUTO INIT(BINOFFSET);  
/ᑍ Pointers for accessing the space  
DCL SPCPTR USRSPC;  
DCL SYSPTR USRSPC@;  
/ᑍ QCMDEXC and associated CL commands  
DCL SYSPTR QCMDEXC INIT("QCMDEXC", CTX("QSYS"), TYPE(PGM));  
DCL DD CLOVRCMD CHAR(65);  
DCL DD OVRSTR CHAR(39) DEF(CLOVRCMD) POS(1)  
INIT("OVRDBF MISRC 123456789ð MBR(123456789ð)");  
DCL DD OVRSTR2 CHAR(26) DEF(CLOVRCMD) POS(4ð)  
INIT(" POSITION(ᑍRRN 123456789ð)");  
DCL DD FILNAM CHAR(1ð) DEF(CLOVRCMD) POS(14);  
DCL DD MBRNAM CHAR(1ð) DEF(CLOVRCMD) POS(29);  
DCL DD RECNUM ZND(1ð,ð) DEF(CLOVRCMD) POS(55);  
DCL SPCPTR CLOVRCMD@ INIT(CLOVRCMD);  
DCL DD CLOVRLNG PKD(15,5) INIT(P'65');  
DCL SPCPTR CLOVRLNG@ INIT(CLOVRLNG);  
DCL OL QCMDOVROL (CLOVRCMD@, CLOVRLNG@) ARG;  
DCL DD CLDLTCMD CHAR(12) INIT("DLTOVR MISRC");  
DCL SPCPTR CLDLTCMD@ INIT(CLDLTCMD);  
DCL DD CLDLTLNG PKD(15,5) INIT(P'12');  
DCL SPCPTR CLDLTLNG@ INIT(CLDLTLNG);  
DCL OL QCMDDLTOL (CLDLTCMD@, CLDLTLNG@) ARG;  
/ᑍ CLð6 and associated parameters  
ᑍ/  
DCL SYSPTR CLð6 INIT("CLð6", TYPE(PGM));  
DCL DD OFFSET PKD(15,5);  
DCL SPCPTR OFFSET@ INIT(OFFSET);  
DCL OL CLð6OL (USRSPC, OFFSET@) ARG;  
7-24 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ Access QTEMP address  
ᑍ/  
DCL SYSPTR QTEMP@ BASPCO  
POS(65);  
/ᑍ Template for CRTS MI instruction  
ᑍ/  
DCL DD CRTSTMPLT CHAR(16ð) BDRY(16);  
DCL DD TMPLTSPEC CHAR(8) DEF(CRTSTMPLT) POS(1);  
DCL DD TMPLTSIZE BIN(4) DEF(TMPLTSPEC) POS(1) INIT(16ð);  
DCL DD TMPLTBA BIN(4) DEF(TMPLTSPEC) POS(5) INIT(ð);  
DCL DD OBJID CHAR(32) DEF(CRTSTMPLT) POS(9);  
DCL DD SPCTYPE CHAR(1) DEF(OBJID) POS(1) INIT(X'19');  
DCL DD SPCSUBTYPE CHAR(1) DEF(OBJID) POS(2) INIT(X'EF');  
DCL DD SPCNAME CHAR(3ð) DEF(OBJID) POS(3) INIT("MICRTPG2");  
DCL DD OBJCRTOPT CHAR(4) DEF(CRTSTMPLT) POS(41) INIT(X'6ðð2ðððð');  
DCL DD OBJRCVOPTS CHAR(4) DEF(CRTSTMPLT) POS(45);  
DCL DD ᑍ CHAR(2) DEF(OBJRCVOPTS) POS(1) INIT(X'ðððð');  
DCL DD ASP CHAR(2) DEF(OBJRCVOPTS) POS(3) INIT(X'ðððð');  
DCL DD SPCSIZ BIN(4) DEF(CRTSTMPLT) POS(49) INIT(1);  
DCL DD INTSPCVAL CHAR(1) DEF(CRTSTMPLT) POS(53) INIT(X'ðð');  
DCL DD PERFCLASS CHAR(4) DEF(CRTSTMPLT) POS(54) INIT(X'ðððððððð');  
DCL DD ᑍ CHAR(1) DEF(CRTSTMPLT) POS(58) INIT(X'ðð');  
DCL DD PUBAUT CHAR(2) DEF(CRTSTMPLT) POS(59) INIT(X'ðððð');  
DCL DD TMPLTEXTN BIN(4) DEF(CRTSTMPLT) POS(61) INIT(96);  
DCL SYSPTR CONTEXT DEF(CRTSTMPLT) POS(65);  
DCL SYSPTR ACCESSGRP DEF(CRTSTMPLT) POS(81);  
DCL SYSPTR USRPRF DEF(CRTSTMPLT) POS(97);  
DCL DD MAXSPCSIZ BIN(4) DEF(CRTSTMPLT) POS(113) INIT(ð);  
DCL DD DOMAIN CHAR(2) DEF(CRTSTMPLT) POS(117) INIT(X'ððð1');  
DCL DD ᑍ CHAR(42) DEF(CRTSTMPLT) POS(119) INIT((42)X'ðð');  
DCL SPCPTR CRTSTMPLT@ INIT(CRTSTMPLT);  
/ᑍ QPRCRTPG and associated parameters  
ᑍ/  
DCL DD PGM CHAR(2ð);  
DCL DD PGMNAM CHAR(1ð) DEF(PGM) POS(1);  
DCL DD PGMLIBNAM CHAR(1ð) DEF(PGM) POS(11) INIT("ᑍCURLIB ");  
DCL SPCPTR PGM@ INIT(PGM);  
DCL DD PGMTXT CHAR(5ð) INIT(" ");  
DCL SPCPTR PGMTXT@ INIT(PGMTXT);  
DCL DD PGMSRCF CHAR(2ð) INIT("ᑍNONE");  
DCL SPCPTR PGMSRCF@ INIT(PGMSRCF);  
DCL DD PGMSRCM CHAR(1ð) INIT(" ");  
DCL SPCPTR PGMSRCM@ INIT(PGMSRCM);  
DCL DD PGMSRCCHG CHAR(13) INIT(" ");  
DCL SPCPTR PGMSRCCHG@ INIT(PGMSRCCHG);  
DCL DD PRTFNAM CHAR(2ð) INIT("QSYSPRT ᑍLIBL  
DCL SPCPTR PRTFNAM@ INIT(PRTFNAM);  
DCL DD PRTSTRPAG BIN(4) INIT(1);  
");  
DCL SPCPTR PRTSTRPAG@ INIT(PRTSTRPAG);  
DCL DD PGMPUBAUT CHAR(1ð) INIT("ᑍALL  
DCL SPCPTR PGMPUBAUT@ INIT(PGMPUBAUT);  
");  
DCL DD PGMOPTS(16) CHAR(11) INIT((1)"ᑍLIST", ᑍ(2)(1)"ᑍREPLACE",  
ᑍ(3)(1)"ᑍXREF");  
DCL SPCPTR PGMOPTS@ INIT(PGMOPTS);  
DCL DD NUMOPTS BIN(4) INIT(3);  
Chapter 7. Machine Interface Programming 7-25  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DCL SPCPTR NUMOPTS@ INIT(NUMOPTS);  
DCL OL QPRCRTPGOL (USRSPC, BINOFFSET@, PGM@, PGMTXT@, PGMSRCF@,  
PGMSRCM@, PGMSRCCHG@, PRTFNAM@, PRTSTRPAG@,  
PGMPUBAUT@, PGMOPTS@, NUMOPTS@) ARG;  
DCL SYSPTR QPRCRTPG INIT("QPRCRTPG", CTX("QSYS"), TYPE(PGM));  
/ᑍ Start of instruction stream  
ᑍ/  
STPLLEN NUM_PARMS;  
CMPNV(B) NUM_PARMS, 2 / EQ(PARM2);  
CPYBLAP FILNAM, 'MISRC', ' ';  
B PARM1;  
PARM2: CPYBLA FILNAM, FIL;  
PARM1: CPYBLA MBRNAM,MBR;  
CMPBLA(B) READY, '1' / EQ(SKIP);  
CPYBWP CONTEXT, QTEMP@;  
CRTS USRSPC@, CRTSTMPLT@;  
SETSPPFP USRSPC,USRSPC@;  
CPYBLA READY, '1';  
SKIP: CPYNV RECNUM, 1;  
MORE: CALLX QCMDEXC, QCMDOVROL, ᑍ;  
CPYNV OFFSET,1;  
CALLX CLð6, CLð6OL, ᑍ;  
SUBN(S) OFFSET, 1;  
ADDN(S) BINOFFSET, OFFSET;  
SETSPPO USRSPC, BINOFFSET;  
ADDN(S) RECNUM, 2ð;  
CALLX QCMDEXC, QCMDDLTOL, ᑍ;  
CMPNV(B) OFFSET, 16ðð /EQ(MORE);  
CPYBLA PGMNAM, MBR;  
SETSPPO USRSPC, ð;  
CALLX QPRCRTPG, QPRCRTPGOL, ᑍ;  
RTX ᑍ;  
PEND;  
Updated CL06 Program  
Following is the updated CL06 program:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: CLð6  
Programming Language: CL  
Description: Load a source physical file member into the  
ᑍUSRSPC addressed by &BUFFER.  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
PGM  
DCLF  
DCL  
DCL  
RCVF  
PARM(&BUFFER &OFFSET)  
FILE(MISRC)  
VAR(&BUFFER) TYPE(ᑍCHAR) LEN(16ðð)  
VAR(&OFFSET) TYPE(ᑍDEC) LEN(15 5)  
LOOP:  
7-26 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
MONMSG  
CHGVAR  
CHGVAR  
IF  
MSGID(CPFð864 CPF4137) EXEC(GOTO CMDLBL(DONE))  
VAR(%SST(&BUFFER &OFFSET 8ð)) VALUE(&SRCDTA)  
VAR(&OFFSET) VALUE(&OFFSET + 8ð)  
COND(&OFFSET ᑍGT 16ðð) THEN(GOTO CMDLBL(DONE))  
CMDLBL(LOOP)  
GOTO  
DONE:  
ENDPGM  
Creating the MICRTPG2 Program  
To create the MICRTPG2 program, use:  
DLTOVR MISRC  
CALL CLð3 (MISRC MICRTPG2)  
After the successful creation of MICRTPG2, you can create any new MI programs  
by entering the following, where SourceFileName is an optional parameter:  
CALL MICRTPG2 (MemberName SourceFileName)  
Handling Exceptions in the MICRTPG2 Program  
Some exceptions that are not being handled by the MICRTPG2 program may  
occur. For example, if you used MICRTPG2 to compile MICRTPG2 two times in  
succession, the exception MCH1401 occurs. This occurs because the most recent  
activation of the MICRTPG2 program has its own static storage and is not aware of  
the earlier instances of MICRTPG2 creating the space named MICRTPG2 in  
QTEMP.  
To correct this problem do the following:  
1. Define an exception description that passes control to an internal exception  
handler:  
DCL EXCM DUPERROR EXCID(H'ðEð1') INT(M14ð1) IMD;  
2. Define the internal entry point:  
ENTRY M14ð1 INT;  
3. Define related data elements for the M1401 exception:  
/ᑍ Exception description template for RETEXCPD ᑍ/  
DCL DD EXCPDBUF CHAR(2ðð) BDRY(16);  
DCL DD BYTPRV BIN(4) DEF(EXCPDBUF) POS(1) INIT(2ðð);  
DCL DD BYTAVL BIN(4) DEF(EXCPDBUF) POS(5);  
DCL DD EXCPID CHAR(2) DEF(EXCPDBUF) POS(9);  
DCL DD CMPLEN BIN(2) DEF(EXCPDBUF) POS(11);  
DCL DD CMPDTA CHAR(32) DEF(EXCPDBUF) POS(13);  
DCL DD MSGKEY CHAR(4) DEF(EXCPDBUF) POS(45);  
DCL DD EXCDTA CHAR(5ð) DEF(EXCPDBUF) POS(49);  
DCL SYSPTR EXC_OBJ@ DEF(EXCDTA) POS(1);  
DCL DD EXC_OBJ CHAR(32) DEF(EXCDTA) POS(17);  
DCL PTR INV_PTR DEF(EXCPDBUF) POS(97);  
DCL DD ᑍ CHAR(87) DEF(EXCPDBUF) POS(113);  
DCL SPCPTR EXCPDBUF@ INIT(EXCPDBUF);  
/ᑍ Template for RTNEXCP  
ᑍ/  
DCL DD RTNTMPLT CHAR(19) BDRY(16);  
Chapter 7. Machine Interface Programming 7-27  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DCL PTR INV_PTR2 DEF(RTNTMPLT) POS(1);  
DCL DD ᑍ CHAR(1) DEF(RTNTMPLT) POS(17) INIT(X'ðð');  
DCL DD ACTION CHAR(2) DEF(RTNTMPLT) POS(18);  
DCL SPCPTR RTNTMPLT@ INIT(RTNTMPLT);  
4. Retrieve the exception data associated with the MCH1401 exception:  
RETEXCPD EXCPDBUF@, X'ð1';  
5. Compare the exception data object identifier to the space identifier you create.  
If they are the same, branch to label SAME:  
CMPBLA(B) EXC_OBJ, OBJID / EQ(SAME);  
a. If the exception data object identifier and the space identifier are not the  
same, the program is truly in an unexpected error condition and the excep-  
tion description needs to be disabled:  
MODEXCPD DUPERROR, X'2ððð', X'ð1';  
Retry the failing instruction. As the exception description is disabled, the  
exception is sent to the caller of the program:  
CPYBLA ACTION, X'ðððð';  
B E14ð1;  
b. If the exception data object identifier and the space identifier are the same,  
the static storage must have been effectively reset. The program reassigns  
USRSPC@ by using the returned system pointer in the exception data and  
continues with the next instruction following the failed CRTS:  
SAME: CPYBWP USRSPC@, EXC_OBJ@;  
CPYBLA ACTION, X'ð1ðð';  
E14ð1: CPYBWP INV_PTR2, INV_PTR;  
RTNEXCP RTNTMPLT@;  
PEND;  
MICRTPG2 Complete Program (Enhanced)—MI Code Example  
In its consolidated state, this is the new MICRTPG2 program:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: MICRTPG2  
Programming Language: MI  
Description: Enhanced version of MI program MICRTPG2,  
which provides for exception handling.  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Entry point and associated parameters  
ᑍ/  
ENTRY ᑍ (ᑍENTRY) EXT;  
DCL SPCPTR FIL@ PARM;  
DCL SPCPTR MBR@ PARM;  
DCL OL ᑍENTRY (MBR@, FIL@) PARM EXT MIN(1);  
DCL DD FIL CHAR(1ð) BAS(FIL@);  
7-28 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DCL DD MBR CHAR(1ð) BAS(MBR@);  
DCL DD NUM_PARMS BIN( 4);  
/ᑍ Control field for first time initialization ᑍ/  
DCL DD READY CHAR( 1) INIT("ð");  
/ᑍ Binary offset into the space  
ᑍ/  
ᑍ/  
ᑍ/  
DCL DD BINOFFSET BIN(4) AUTO INIT(ð);  
DCL SPCPTR BINOFFSET@ AUTO INIT(BINOFFSET);  
/ᑍ Pointers for accessing the space  
DCL SPCPTR USRSPC;  
DCL SYSPTR USRSPC@;  
/ᑍ QCMDEXC and associated CL commands  
DCL SYSPTR QCMDEXC INIT("QCMDEXC", CTX("QSYS"), TYPE(PGM));  
DCL DD CLOVRCMD CHAR(65);  
DCL DD OVRSTR CHAR(39) DEF(CLOVRCMD) POS(1)  
INIT("OVRDBF MISRC 123456789ð MBR(123456789ð)");  
DCL DD OVRSTR2 CHAR(26) DEF(CLOVRCMD) POS(4ð)  
INIT(" POSITION(ᑍRRN 123456789ð)");  
DCL DD FILNAM CHAR(1ð) DEF(CLOVRCMD) POS(14);  
DCL DD MBRNAM CHAR(1ð) DEF(CLOVRCMD) POS(29);  
DCL DD RECNUM ZND(1ð,ð) DEF(CLOVRCMD) POS(55);  
DCL SPCPTR CLOVRCMD@ INIT(CLOVRCMD);  
DCL DD CLOVRLNG PKD(15,5) INIT(P'65');  
DCL SPCPTR CLOVRLNG@ INIT(CLOVRLNG);  
DCL OL QCMDOVROL (CLOVRCMD@, CLOVRLNG@) ARG;  
DCL DD CLDLTCMD CHAR(12) INIT("DLTOVR MISRC");  
DCL SPCPTR CLDLTCMD@ INIT(CLDLTCMD);  
DCL DD CLDLTLNG PKD(15,5) INIT(P'12');  
DCL SPCPTR CLDLTLNG@ INIT(CLDLTLNG);  
DCL OL QCMDDLTOL (CLDLTCMD@, CLDLTLNG@) ARG;  
/ᑍ CLð6 and associated parameters  
ᑍ/  
DCL SYSPTR CLð6 INIT("CLð6", TYPE(PGM));  
DCL DD OFFSET PKD(15,5);  
DCL SPCPTR OFFSET@ INIT(OFFSET);  
DCL OL CLð6OL (USRSPC, OFFSET@) ARG;  
/ᑍ Access QTEMP address  
ᑍ/  
DCL SYSPTR QTEMP@ BASPCO  
POS(65);  
/ᑍ Template for CRTS MI instruction  
ᑍ/  
DCL DD CRTSTMPLT CHAR(16ð) BDRY(16);  
DCL DD TMPLTSPEC CHAR(8) DEF(CRTSTMPLT) POS(1);  
DCL DD TMPLTSIZE BIN(4) DEF(TMPLTSPEC) POS(1) INIT(16ð);  
DCL DD TMPLTBA BIN(4) DEF(TMPLTSPEC) POS(5) INIT(ð);  
DCL DD OBJID CHAR(32) DEF(CRTSTMPLT) POS(9);  
DCL DD SPCTYPE CHAR(1) DEF(OBJID) POS(1) INIT(X'19');  
DCL DD SPCSUBTYPE CHAR(1) DEF(OBJID) POS(2) INIT(X'EF');  
Chapter 7. Machine Interface Programming 7-29  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DCL DD SPCNAME CHAR(3ð) DEF(OBJID) POS(3) INIT("MICRTPG2");  
DCL DD OBJCRTOPT CHAR(4) DEF(CRTSTMPLT) POS(41) INIT(X'6ðð2ðððð');  
DCL DD OBJRCVOPTS CHAR(4) DEF(CRTSTMPLT) POS(45);  
DCL DD ᑍ CHAR(2) DEF(OBJRCVOPTS) POS(1) INIT(X'ðððð');  
DCL DD ASP CHAR(2) DEF(OBJRCVOPTS) POS(3) INIT(X'ðððð');  
DCL DD SPCSIZ BIN(4) DEF(CRTSTMPLT) POS(49) INIT(1);  
DCL DD INTSPCVAL CHAR(1) DEF(CRTSTMPLT) POS(53) INIT(X'ðð');  
DCL DD PERFCLASS CHAR(4) DEF(CRTSTMPLT) POS(54) INIT(X'ðððððððð');  
DCL DD ᑍ CHAR(1) DEF(CRTSTMPLT) POS(58) INIT(X'ðð');  
DCL DD PUBAUT CHAR(2) DEF(CRTSTMPLT) POS(59) INIT(X'ðððð');  
DCL DD TMPLTEXTN BIN(4) DEF(CRTSTMPLT) POS(61) INIT(96);  
DCL SYSPTR CONTEXT DEF(CRTSTMPLT) POS(65);  
DCL SYSPTR ACCESSGRP DEF(CRTSTMPLT) POS(81);  
DCL SYSPTR USRPRF DEF(CRTSTMPLT) POS(97);  
DCL DD MAXSPCSIZ BIN(4) DEF(CRTSTMPLT) POS(113) INIT(ð);  
DCL DD DOMAIN CHAR(2) DEF(CRTSTMPLT) POS(117) INIT(X'ððð1');  
DCL DD ᑍ CHAR(42) DEF(CRTSTMPLT) POS(119) INIT((42)X'ðð');  
DCL SPCPTR CRTSTMPLT@ INIT(CRTSTMPLT);  
/ᑍ QPRCRTPG and associated parameters  
ᑍ/  
DCL DD PGM CHAR(2ð);  
DCL DD PGMNAM CHAR(1ð) DEF(PGM) POS(1);  
DCL DD PGMLIBNAM CHAR(1ð) DEF(PGM) POS(11) INIT("ᑍCURLIB ");  
DCL SPCPTR PGM@ INIT(PGM);  
DCL DD PGMTXT CHAR(5ð) INIT(" ");  
DCL SPCPTR PGMTXT@ INIT(PGMTXT);  
DCL DD PGMSRCF CHAR(2ð) INIT("ᑍNONE");  
DCL SPCPTR PGMSRCF@ INIT(PGMSRCF);  
DCL DD PGMSRCM CHAR(1ð) INIT(" ");  
DCL SPCPTR PGMSRCM@ INIT(PGMSRCM);  
DCL DD PGMSRCCHG CHAR(13) INIT(" ");  
DCL SPCPTR PGMSRCCHG@ INIT(PGMSRCCHG);  
DCL DD PRTFNAM CHAR(2ð) INIT("QSYSPRT ᑍLIBL  
DCL SPCPTR PRTFNAM@ INIT(PRTFNAM);  
DCL DD PRTSTRPAG BIN(4) INIT(1);  
");  
DCL SPCPTR PRTSTRPAG@ INIT(PRTSTRPAG);  
DCL DD PGMPUBAUT CHAR(1ð) INIT("ᑍALL  
DCL SPCPTR PGMPUBAUT@ INIT(PGMPUBAUT);  
");  
DCL DD PGMOPTS(16) CHAR(11) INIT((1)"ᑍLIST", ᑍ(2)(1)"ᑍREPLACE",  
ᑍ(3)(1)"ᑍXREF");  
DCL SPCPTR PGMOPTS@ INIT(PGMOPTS);  
DCL DD NUMOPTS BIN(4) INIT(3);  
DCL SPCPTR NUMOPTS@ INIT(NUMOPTS);  
DCL OL QPRCRTPGOL (USRSPC, BINOFFSET@, PGM@, PGMTXT@, PGMSRCF@,  
PGMSRCM@, PGMSRCCHG@, PRTFNAM@, PRTSTRPAG@,  
PGMPUBAUT@, PGMOPTS@, NUMOPTS@) ARG;  
DCL SYSPTR QPRCRTPG INIT("QPRCRTPG", CTX("QSYS"), TYPE(PGM));  
/ᑍ Exception Description Monitor for MCH14ð1  
DCL EXCM DUPERROR EXCID(H'ðEð1') INT(M14ð1) IMD;  
/ᑍ Start of instruction stream  
ᑍ/  
ᑍ/  
STPLLEN NUM_PARMS;  
CMPNV(B) NUM_PARMS, 2 / EQ(PARM2);  
CPYBLAP FILNAM, 'MISRC', ' ';  
7-30 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
B PARM1;  
PARM2: CPYBLA FILNAM, FIL;  
PARM1: CPYBLA MBRNAM,MBR;  
CMPBLA(B) READY, '1' / EQ(SKIP);  
CPYBWP CONTEXT, QTEMP@;  
CRTS USRSPC@, CRTSTMPLT@;  
SETSPPFP USRSPC,USRSPC@;  
CPYBLA READY, '1';  
SKIP: CPYNV RECNUM, 1;  
MORE: CALLX QCMDEXC, QCMDOVROL, ᑍ;  
CPYNV OFFSET,1;  
CALLX CLð6, CLð6OL, ᑍ;  
SUBN(S) OFFSET, 1;  
ADDN(S) BINOFFSET, OFFSET;  
SETSPPO USRSPC, BINOFFSET;  
ADDN(S) RECNUM, 2ð;  
CALLX QCMDEXC, QCMDDLTOL, ᑍ;  
CMPNV(B) OFFSET, 16ðð /EQ(MORE);  
CPYBLA PGMNAM, MBR;  
SETSPPO USRSPC, ð;  
CALLX QPRCRTPG, QPRCRTPGOL, ᑍ;  
RTX ᑍ;  
/ᑍ Entry point for internal exception handler  
ENTRY M14ð1 INT;  
ᑍ/  
/ᑍ Exception description template for RETEXCPD ᑍ/  
DCL DD EXCPDBUF CHAR(2ðð) BDRY(16);  
DCL DD BYTPRV BIN(4) DEF(EXCPDBUF) POS(1) INIT(2ðð);  
DCL DD BYTAVL BIN(4) DEF(EXCPDBUF) POS(5);  
DCL DD EXCPID CHAR(2) DEF(EXCPDBUF) POS(9);  
DCL DD CMPLEN BIN(2) DEF(EXCPDBUF) POS(11);  
DCL DD CMPDTA CHAR(32) DEF(EXCPDBUF) POS(13);  
DCL DD MSGKEY CHAR(4) DEF(EXCPDBUF) POS(45);  
DCL DD EXCDTA CHAR(5ð) DEF(EXCPDBUF) POS(49);  
DCL SYSPTR EXC_OBJ@ DEF(EXCDTA) POS(1);  
DCL DD EXC_OBJ CHAR(32) DEF(EXCDTA) POS(17);  
DCL PTR INV_PTR DEF(EXCPDBUF) POS(97);  
DCL DD ᑍ CHAR(87) DCF(EXCPDBUF) POS(113);  
DCL SPCPTR EXCPDBUF@ INIT(EXCPDBUF);  
/ᑍ Template for RTNEXCP  
ᑍ/  
DCL DD RTNTMPLT CHAR(19) BDRY(16);  
DCL PTR INV_PTR2 DEF(RTNTMPLT) POS(1);  
DCL DD ᑍ CHAR(1) DEF(RTNTMPLT) POS(17) INIT(X'ðð');  
DCL DD ACTION CHAR(2) DEF(RTNTMPLT) POS(18);  
DCL SPCPTR RTNTMPLT@ INIT(RTNTMPLT);  
/ᑍ Start of internal handler  
ᑍ/  
RETEXCPD EXCPDBUF@, X'ð1';  
CMPBLA(B) EXC_OBJ, OBJID / EQ(SAME);  
MODEXCPD DUPERROR, X'2ððð', X'ð1';  
CPYBLA ACTION, X'ðððð';  
Chapter 7. Machine Interface Programming 7-31  
Download from Www.Somanuals.com. All Manuals Search And Download.  
B E14ð1;  
SAME: CPYBWP USRSPC@, EXC_OBJ@;  
CPYBLA ACTION, X'ð1ðð';  
E14ð1: CPYBWP INV_PTR2, INV_PTR;  
RTNEXCP RTNTMPLT@;  
PEND;  
MI Common Programming Techniques—Examples  
With the completion of the MICRTPG2 program, the following example MI program  
demonstrates some additional programming techniques:  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Program Name: MISC1  
Programming Language: MI  
Description: This program materializes the objects found  
within the QTEMP library (context). For each ᑍ/  
object found, a message is sent to the  
interactive user message queue showing the  
name of the object and the object's type and  
subtype.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
Several new MI instructions are used by this  
program:  
1. Materialize Context (MATCTX)  
2. Modify Automatic Storage (MODASA)  
3. Divide (DIV)  
4. Convert Hex to Character (CVTHC)  
5. Override Program Attributes (OVRPGATR)  
Header Files Included: None  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Entry point  
ᑍ/  
ENTRY ᑍ EXT;  
/ᑍ Declare layout of Process Communications Object (PCO)  
/ᑍ The PCO is a control area that is unique to each job on the  
ᑍ/  
ᑍ/  
/ᑍ system. Within the PCO, there are two data elements that can ᑍ/  
/ᑍ be used. The first is a space pointer to the system entry  
/ᑍ point table (SEPT), the second is the address of the QTEMP  
ᑍ/  
ᑍ/  
/ᑍ library. The use of any other data element in the PCO is NOT ᑍ/  
/ᑍ supported.  
ᑍ/  
DCL DD PCO CHAR(8ð) BASPCO;  
DCL SPCPTR SEPT@  
DCL SYSPTR QTEMP@  
DEF(PCO)  
DEF(PCO)  
POS( 1);  
POS(65);  
7-32 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ The SEPT is an array of system pointers that address IBM  
ᑍ/  
/ᑍ programs in QSYS. Within this array of pointers, some of the ᑍ/  
/ᑍ offsets represent fixed (upward compatible) assignments. All ᑍ/  
/ᑍ OS/4ðð APIs, for instance, are fixed at certain offsets within ᑍ/  
/ᑍ the SEPT and you can call these APIs directly via the SEPT.  
/ᑍ Calling APIs in this way avoids having to resolve to the API  
/ᑍ (that is, performance is improved) and prevents someone from  
/ᑍ placing their version of the API earlier in the library list  
/ᑍ than the IBM-supplied API (that is, avoids counterfeits).  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ All APIs, and their offsets, can be found in the source member ᑍ/  
/ᑍ QLIEPTI of file H in the optionally installed QSYSINC library. ᑍ/  
/ᑍ You should only use the SEPT for those programs identified in ᑍ/  
/ᑍ member QLIEPTI. The use of any other SEPT offsets is NOT  
/ᑍ supported.  
ᑍ/  
ᑍ/  
/ᑍ Because the offset values in member QLIEPTI are oriented to the ᑍ/  
/ᑍ C language, they are assuming a base of ð. Because MI arrays ᑍ/  
/ᑍ use a default base of 1, we will declare the SEPT array with  
/ᑍ an explicit base of ð. Because the array can grow over time  
/ᑍ (and we don't necessarily want to have to change the upper  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ bound every release), we'll just define the array as having 2 ᑍ/  
/ᑍ elements and use the OVRPGATR instruction later in the program ᑍ/  
/ᑍ to instruct the translator to ignore the array bounds when  
/ᑍ referring to the array. For example, later we will use  
ᑍ/  
ᑍ/  
/ᑍ SEPT(4267) to call the Send Nonprogram Message (QMHSNDM) API. ᑍ/  
DCL SYSPTR SEPT(ð:1) BAS(SEPT@); /ᑍ use Base ð to match QLIEPTI ᑍ/  
/ᑍ Declare template for Materialize Context (MATCTX)  
DCL DD MATCTXOPTS CHAR(44);  
ᑍ/  
ᑍ/  
DCL DD MATCTXCTL  
CHAR( 2) DEF(MATCTXOPTS) POS( 1) INIT(X'ð5ðð');  
DCL DD MATCTXSELCTL CHAR(42) DEF(MATCTXOPTS) POS( 3);  
/ᑍ Declare Small Receiver for initial MATCTX  
DCL DD S_RECEIVER CHAR(8) BDRY(16);  
DCL DD S_BYTPRV  
DCL DD S_BYTAVL  
BIN( 4) DEF(S_RECEIVER) POS( 1) INIT(8);  
BIN( 4) DEF(S_RECEIVER) POS( 5);  
DCL SPCPTR S_RECEIVER@ INIT(S_RECEIVER);  
/ᑍ Declare Large Receiver Layout for second MATCTX  
ᑍ/  
DCL DD L_RECEIVER  
DCL DD L_BYTPRV  
DCL DD L_BYTAVL  
DCL DD L_CONTEXT  
CHAR(129) BAS(L_RECEIVER@);  
BIN( 4) DEF(L_RECEIVER) POS( 1);  
BIN( 4) DEF(L_RECEIVER) POS( 5);  
CHAR(32) DEF(L_RECEIVER) POS( 9);  
DCL DD L_OBJ_TYPE CHAR( 1) DEF(L_CONTEXT) POS( 1);  
DCL DD L_OBJ_STYPE CHAR( 1) DEF(L_CONTEXT) POS( 2);  
DCL DD L_OBJ_NAME CHAR(3ð) DEF(L_CONTEXT) POS( 3);  
DCL DD L_CTX_OPTS CHAR( 4) DEF(L_RECEIVER) POS(41);  
DCL DD L_RCV_OPTS CHAR( 4) DEF(L_RECEIVER) POS(45);  
DCL DD L_SPC_SIZ  
BIN( 4) DEF(L_RECEIVER) POS(49);  
DCL DD L_SPC_IVAL CHAR( 1) DEF(L_RECEIVER) POS(53);  
DCL DD L_PERF_CLS CHAR( 4) DEF(L_RECEIVER) POS(54);  
DCL DD ᑍ  
DCL DD ᑍ  
CHAR( 7) DEF(L_RECEIVER) POS(58);  
CHAR(16) DEF(L_RECEIVER) POS(65);  
DCL SYSPTR L_ACC_GROUP;  
Chapter 7. Machine Interface Programming 7-33  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DCL DD L_EXT_ATTR CHAR( 1) DEF(L_RECEIVER) POS(81);  
DCL DD ᑍ CHAR( 7) DEF(L_RECEIVER) POS(82);  
DCL DD L_TIMESTAMP CHAR( 8) DEF(L_RECEIVER) POS(89);  
DCL DD L_ENTRY CHAR(32) DEF(L_RECEIVER) POS(97);  
/ᑍ Individual object entry layout  
ᑍ/  
DCL DD OBJ_ENTRY  
CHAR(32) BAS(OBJ_ENTRY@);  
DCL DD OBJ_INFO_X CHAR( 2) DEF(OBJ_ENTRY) POS( 1);  
DCL DD OBJ_TYPE_X CHAR( 1) DEF(OBJ_INFO_X) POS( 1);  
DCL DD OBJ_STYPE_X CHAR( 1) DEF(OBJ_INFO_X) POS( 2);  
DCL DD OBJ_NAME  
CHAR(3ð) DEF(OBJ_ENTRY) POS( 3);  
/ᑍ Define basing pointers:  
ᑍ/  
ᑍ/  
DCL SPCPTR L_RECEIVER@;  
DCL SPCPTR OBJ_ENTRY@;  
/ᑍ Define various working variables  
DCL DD SIZE  
BIN( 4);  
BIN( 4)  
/ᑍ number of objects materialized ᑍ/  
DCL DD NUM_DONE  
/ᑍ number of objects processed  
ᑍ/  
AUTO INIT(ð);  
/ᑍ Define needed parameters for QMHSNDM API  
ᑍ/  
DCL DD MSG_ID  
DCL SPCPTR MSG_ID@ INIT(MSG_ID);  
DCL DD MSG_FILE CHAR(2ð) INIT("  
DCL SPCPTR MSG_FILE@ INIT(MSG_FILE);  
CHAR (7) INIT("  
");  
");  
DCL DD MSG_TEXT  
DCL DD ᑍ  
CHAR(57);  
CHAR( 8) DEF(MSG_TEXT) POS( 1)  
INIT("OBJECT: ");  
DCL DD OBJ_NAME_T CHAR(3ð) DEF(MSG_TEXT) POS( 9);  
DCL DD ᑍ  
CHAR(15) DEF(MSG_TEXT) POS(39)  
INIT(" TYPE/SUBTYPE: ");  
DCL DD OBJ_INFO_C CHAR( 4) DEF(MSG_TEXT) POS(54);  
DCL DD OBJ_TYPE_C CHAR( 2) DEF(OBJ_INFO_C) POS( 1);  
DCL DD OBJ_STYPE_C CHAR( 2) DEF(OBJ_INFO_C) POS( 3);  
DCL SPCPTR MSG_TEXT@ INIT(MSG_TEXT);  
DCL DD MSG_SIZE  
BIN( 4) INIT(57);  
DCL SPCPTR MSG_SIZE@ INIT(MSG_SIZE);  
DCL DD MSG_TYPE  
CHAR(1ð) INIT("ᑍINFO  
");  
DCL SPCPTR MSG_TYPE@ INIT(MSG_TYPE);  
DCL DD MSG_QS  
CHAR(2ð) INIT("ᑍREQUESTER  
");  
");  
DCL SPCPTR MSG_QS@ INIT(MSG_QS);  
DCL DD MSG_QSN  
BIN( 4) INIT(1);  
DCL SPCPTR MSG_QSN@ INIT(MSG_QSN);  
DCL DD REPLY_Q CHAR(2ð) INIT("  
DCL SPCPTR REPLY_Q@ INIT(REPLY_Q);  
DCL DD MSG_KEY CHAR( 4);  
DCL SPCPTR MSG_KEY@ INIT(MSG_KEY);  
DCL DD ERR_COD BIN( 4) INIT(ð);  
DCL SPCPTR ERR_COD@ INIT(ERR_COD);  
DCL OL QMHSNDMOL (MSG_ID@, MSG_FILE@, MSG_TEXT@, MSG_SIZE@,  
MSG_TYPE@, MSG_QS@, MSG_QSN@, REPLY_Q@,  
MSG_KEY@, ERR_COD@) ARG;  
/ᑍ Start the instruction stream  
ᑍ/  
7-34 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ Materialize the amount of storage needed to store object info ᑍ/  
MATCTX S_RECEIVER@, QTEMP@, MATCTXOPTS;  
/ᑍ If no objects are in the library, then exit  
CMPNV(B) S_BYTAVL, 96 / EQ(DONE);  
ᑍ/  
/ᑍ Allocate the necessary storage (we could also have used CRTS  
to allocate the storage and a SPCPTR to the space for the  
large receiver variable)  
ᑍ/  
MODASA  
/ᑍ Set the bytes provided field to indicate the allocated storage ᑍ/  
CPYNV L_BYTPRV, S_BYTAVL;  
/ᑍ Materialize the objects within the library  
L_RECEIVER@, S_BYTAVL;  
ᑍ/  
MATCTX  
L_RECEIVER@, QTEMP@, MATCTXOPTS;  
/ᑍ Calculate how many objects were returned:  
ᑍ/  
ᑍ/  
/ᑍ 1. Find the lower of bytes provided and bytes available  
/ᑍ  
/ᑍ  
(L_BYTPRV and L_BYTAVL) as the number of objects could have ᑍ/  
changed since the first materialize  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ 2. Subtract the size of the fixed MATCTX header (96)  
/ᑍ 3. Divide the remainder by the size of each entry returned  
CMPNV(B) L_BYTPRV, L_BYTAVL / HI(ITS_AVL);  
CPYNV  
B
SIZE, L_BYTPRV;  
CONTINUE;  
ITS_AVL:  
CPYNV  
SIZE, L_BYTAVL;  
CONTINUE: SUBN(SB) SIZE, 96 / ZER(DONE);  
DIV  
SIZE, SIZE, 32;  
/ᑍ Address the first object returned  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
SETSPP  
OBJ_ENTRY@, L_ENTRY;  
/ᑍ Loop through all materialized entries  
MORE:  
/ᑍ Convert the hex object type and subtype to character form  
CVTHC  
/ᑍ Copy the object name to the message variable  
CPYBLA OBJ_NAME_T, OBJ_NAME;  
OBJ_INFO_C, OBJ_INFO_X;  
/ᑍ Unconstrain the array bounds (at compile time)  
OVRPGATR 1,3;  
/ᑍ Send a message to caller's msg queue containing the object info ᑍ/  
Chapter 7. Machine Interface Programming 7-35  
Download from Www.Somanuals.com. All Manuals Search And Download.  
CALLX  
SEPT(4267), QMHSNDMOL, ᑍ;  
/ᑍ resume normal array constraint  
OVRPGATR 1,4;  
ᑍ/  
ᑍ/  
/ᑍ and move on to the next entry  
ADDN(S)  
ADDSPP  
NUM_DONE, 1;  
OBJ_ENTRY@, OBJ_ENTRY@, 32;  
CMPNV(B) NUM_DONE, SIZE / LO(MORE);  
/ᑍ When all entries are processed, end the program.  
/ᑍ  
/ᑍ Note that this program may not actually display all objects  
/ᑍ in QTEMP. If L_BYTAVL is greater than L_BYTPRV, additional  
/ᑍ objects were inserted into QTEMP between the time of the  
/ᑍ "small" MATCTX and the "large" MATCTX. The processing of these ᑍ/  
/ᑍ additional objects is not addressed in this program and is  
/ᑍ the responsibility of the user of this program.  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
DONE:  
RTX  
PEND;  
ᑍ;  
AS/400 Program Storage  
On AS/400 systems, two steps are needed to run a program: program activation  
and program invocation. Program activation is the process of allocating and ini-  
tializing static storage for the program. Program invocation is the process of allo-  
cating and initializing automatic storage.  
Program Activation and Static Storage: Program activation can be done explic-  
itly through the Activate Program (ACTPG) instruction or implicitly by using a call  
external (CALLX) instruction when the called program has not been previously acti-  
vated. Program activation typically occurs only once within a job or process.  
Program activation is not reset by an RTX instruction within the called program (the  
program is still considered to be in an activated state). This means that all static  
storage on subsequent calls (CALLXs) to the program are found in a last-used  
state, not in a reinitialized state. If a programmer wants to reinitialize the static  
storage associated with a program activation, this can be accomplished through the  
deactivate program (DEACTPG) instruction so that the next call (CALLX or ACTPG)  
causes a new activation of the program.  
Program Invocation and Automatic Storage: Program invocation, on the other  
hand, occurs every time a program is called with a CALLX instruction. Automatic  
storage is reinitialized if a discrete INIT value was specified on the declare (DCL)  
statement. (If the INIT was allowed to be the default, then whether or not initializa-  
tion occurs for the field is determined by an option of the QPRCRTPG API when  
the program was created.) If you have not already done so, review all of the option  
template values available on the QPRCRTPG API before developing your MI appli-  
cations.  
7-36 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Chapter 8. Use of OS/400 APIs  
This chapter discusses the various groups of OS/400 APIs and how they may be of  
use to you. Some APIs are discussed as a group, similar to the parts in the  
System API Reference, while others are discussed individually.  
The API discussions in this chapter are presented in the same order as in the  
System API Reference.  
Backup and Recovery APIs  
Use of the backup and recovery APIs is described as follows:  
Ÿ Operational-Assistant Backup APIs  
The APIs for Operational Assistant backup have been provided to give the  
users an interface into the Operational-Assistant backup setup functions without  
having to go through the normal displays. One possible use of these APIs  
would be to change the way the backup runs from one week to the next. For  
example, the user could write a CL program that could run on those weeks in  
which holidays occur to change the backup options to skip the backup for a  
certain day. This CL program could be submitted to run the week of a holiday  
to change the backup options to skip the backup on the holiday, and it could be  
submitted to run again after that week to set the options back to normal. The  
APIs could also be used to retrieve backup history about certain libraries,  
folders, and so forth, in order to better tailor the backups to get the most effi-  
cient backups.  
Ÿ Retrieve Device Capabilities (QTARDCAP) API  
This API is useful for a tape management system. The API returns information  
about what capabilities your tape devices support.  
Ÿ Save Object List (QSRSAVO) API  
This API is useful to get a level of granularity from your save operations that  
you cannot get by using the Save Object (SAVOBJ) command. The API allows  
you to associate specific object names with specific object types instead of  
saving the cross-product of all object names and object types entered on the  
command.  
Ÿ List Save File (QSRLSAVF) API  
This API lists the contents of a save file into a user space. This is primarily for  
those who develop backup and recovery applications.  
Client Support APIs  
The client support APIs include the client software management and configuration  
APIs and exit programs.  
The client software management and configuration section provides APIs to add,  
remove, refresh, and update client information on the AS/400 database with the  
information stored at the client. The client software management database formats  
are affected by these APIs. For information about these formats, see the chapter  
about client inventory management in the Simple Network Management Protocol  
(SNMP) Support book, SC41-5412. The exit programs notify you when these API  
functions have been completed.  
Copyright IBM Corp. 1997  
8-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
With the exception of the Get Client Handle API, which is available only through the  
Integrated Language Environment (ILE), the client software management and con-  
figuration APIs are available as both the original program model (OPM) and ILE  
APIs.  
Ÿ Add Client (QZCAADDC, QzcaAddClient) API  
To manage a client one must keep track of all clients on the network. This API  
provides a convenient way of keeping track of clients. By calling this API, a  
client is added to the database. If a client is SNMP-enabled and is set up in  
such a way so as to send traps to the managing AS/400, the client is automat-  
ically added to the AS/400 database. This API provides a way to add clients  
that may not be SNMP-enabled.  
Ÿ Remove Client (QZCARMVC, QzcaRemoveClient) API  
This API provides a way to remove a client from the database for a client that  
is no longer required to be managed.  
Ÿ Refresh Client (QZCAREFC, QzcaRefreshClientInfo) API  
If a client is SNMP-enabled, this API makes an attempt to get hardware and  
software information from this client. Hardware information is retrieved from the  
host resource management information base (MIB), and software information is  
retrieved from both the Desktop Management Interface (DMI) and the host  
resource MIB.  
This information is also retrieved automatically when traps are received on the  
managing AS/400 from its clients. Therefore, this API provides a way to force  
a “refresh” of client information to keep information current.  
Ÿ Update Client Information (QZCAUPDC, QzcaUpdateClientInfo) API  
This API provides a way to update a few fields that are not updated with the  
Refresh Client API.  
Ÿ Get Client Handle (QzcaGetClientHandle) API  
This API returns a handle, which is unique for every client known to AS/400.  
As mentioned earlier, the interface to this API is only provided through a  
service program.  
Communications APIs  
The user-defined communications APIs were created to provide users with the  
ability to develop their own high-level communications protocol with as little system  
interference as possible. While the system manages the lower-level protocol, the  
user develops the upper layers of a protocol in any high-level programming lan-  
guage supported by the AS/400. Several lower-level protocols are supported  
including X.25, Ethernet Version 2, IEEE Ethernet, token ring, and fiber distributed  
data interface (FDDI) (the selection of which is chosen by the user).  
The APIs provide the ability to enable a link (that is, line, controller, and device),  
disable a link, establish inbound routing information by setting service access points  
(that is, filters), transmit and receive data, set timers, and query line descriptions.  
The user-defined communications APIs are used primarily by users who have com-  
munications needs not normally associated with the other existing communications  
protocols, namely TCP/IP, SNA, or OSI. Applications that have been developed  
8-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
using these APIs range from dedicated point-to-point file transfer to local-area-  
network client/server applications.  
OptiConnect APIs  
The OptiConnect APIs are used to move user data between two or more AS/400  
systems that are connected by the OptiConnect fiber-optic bus. The OptiConnect  
APIs require that the OptiConnect hardware and software products have been  
installed on all of the systems that will be used for communications. A maximum of  
32KB (where KB equals 1024 bytes) of data may be transferred in a single send or  
receive function.  
Note: To use these APIs, you need the OptiConnect for OS/400 feature.  
The OptiConnect APIs provide the following functions:  
Ÿ Open and close an OptiConnect path  
Ÿ Open and close an OptiConnect stream  
Ÿ Send and receive a control message on an OptiConnect stream  
Ÿ Send and receive a request or a message over an OptiConnect path  
Ÿ Wait for a message on an OptiConnect stream  
Configuration APIs  
The configuration APIs can be used for the following functions:  
Ÿ Change Configuration Description (QDCCCFGD) API  
This API allows a user to modify the values of parameters on existing AS/400  
configuration descriptions. The primary purpose of this API is to allow support  
of new parameters or values as required, with their addition to the appropriate  
CL configuration command deferred to a later time. A primary user of this level  
of information would be user applications using new configuration capabilities  
not yet available through CL commands.  
Ÿ List Configuration Descriptions (QDCLCFGD) API  
This API returns a list of configuration descriptions, based on a user-specified  
set of criteria.  
Ÿ Retrieve Configuration Status (QDCRCFGS) API  
This API returns the current operational status of a specific configuration  
description on an AS/400.  
Several APIs also provide feedback of information for any controller description,  
device description, and line description on an AS/400. The primary user of these  
APIs would be user applications performing system or network management func-  
tions on an AS/400. Separate formats are provided for each type of controller,  
device, and line.  
Debugger APIs  
The debugger APIs can be used for program debugging on the AS/400 system.  
The APIs are divided into separate sets of APIs, as follows:  
Ÿ Integrated Language Environment (ILE) APIs  
– Source debugger APIs  
– Create view APIs  
– Dump Module Variable API  
Chapter 8. Use of OS/400 APIs 8-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Ÿ Original program model (OPM) APIs  
– Retrieve Program Variable API  
You can use these sets of source debugger APIs independently of each other or  
together as needed. The source debugger APIs can be used to write debuggers  
for the AS/400 system. The users of these APIs include:  
Ÿ The source debugger that is shipped with the OS/400 licensed program. A  
source debugger is a tool for debugging Integrated Language Environment  
(ILE) programs by displaying a representation of their source code.  
Ÿ Any other debugger that IBM or a business partner writes.  
Debugger functions are designed to help you write and maintain your applications.  
You can run your programs in a special testing environment while closely observing  
and controlling the processing of these programs in the testing environment. You  
can write a debugger application that interacts with the debugger APIs, or you can  
use the debugger provided with the AS/400 system.  
All debugger APIs must be called within the job in which the Start Debug  
(STRDBG) command is issued. The same program can be used at the same time  
in another job without being affected by the debugger functions set up.  
To enable source-level debugging of ILE programs, view information must be  
stored with the compiled program. The ILE compilers use the create view APIs to  
create view information. This information is then available to source-level debugger  
applications through the source debugger APIs.  
Dynamic Screen Manager APIs  
The Dynamic Screen Manager (DSM) APIs are a set of screen I/O interfaces that  
provide a dynamic way to create and manage screens for the Integrated Language  
Environment (ILE) high-level languages. Because the DSM interfaces are bindable,  
they are accessible to ILE programs only.  
The DSM APIs provide an alternative to the existing way of defining screen appear-  
ance outside a program by coding in data description specifications (DDS) or user  
interface manager (UIM), for example. Instead, programmers can use a series of  
calls to DSM within their programs to dynamically specify and control screen  
appearance for their applications. Unlike static definition methods, the DSM inter-  
faces provide the flexibility needed for those applications requiring more dynamic  
screen control. The DSM support provided varies from low-level interfaces for  
direct screen manipulation to windowing support.  
The DSM APIs fall into the following functional groups:  
Ÿ Low-level services  
The low-level services APIs provide a direct interface to the 5250 data stream  
commands. These APIs are used to query and manipulate the state of the  
screen; to create, query, and manipulate input and command buffers used to  
interact with the screen; and to define fields and write data to the screen.  
Ÿ Window services  
The window services APIs are used to create, delete, move, and resize  
windows, and to manage multiple windows during a session.  
8-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Ÿ Session services  
The session services APIs provide a general scrolling interface that can be  
used to create, query, and manipulate sessions, and to perform input and  
output operations to sessions.  
Edit Function APIs  
The edit function APIs are used to create and use edit masks. An edit mask is a  
byte string that tells the edit machine instruction or the Edit (QECEDT) API how to  
format a numeric value into a readable character string.  
An edit mask can format a numeric value so that languages that cannot directly use  
machine instructions can now take advantage of this function. The edit mask was  
previously defined by the Edit Code (EDTCDE) and Edit Word (EDTWRD)  
keywords in DDS.  
An edit code is a standard description of how a number should be formatted.  
There are many standard edit codes defined by the system. Users can define  
several edit codes the way they want with the use of the Create Edit Description  
(CRTEDTD) command.  
An edit word is a user-defined description of how a number should be formatted.  
An edit word is usually used when one of the standard edit codes or user-defined  
edit codes is not sufficient for a particular situation.  
The Convert Edit Code (QECCVTEC) API converts an edit code specification into  
an edit mask, and the Convert Edit Word (QECCVTEW) API converts an edit word  
specification into an edit mask. The resulting edit mask along with the value to be  
formatted are then passed to the Edit (QECEDT) API, which transforms the  
numeric from its internal format to a character form for displaying.  
File APIs  
File APIs provide complete and specific information about a file on a local or  
remote system. The file APIs include list, query, retrieve, and Structured Query  
Language (SQL) APIs. The list APIs generate lists of the following:  
Ÿ Database file members  
Ÿ How files and members are related to a specified database file  
Ÿ Fields within a specified file record format name  
Ÿ Record formats contained within a specified file  
The Query (QQQQRY) API is useful for querying requests whereby you want a  
direct interface to OS/400 Query. The advantage of using the Query API is that  
you are not limited by the function of any particular product interface. Also, you  
can provide your own user interface and not be impeded by the extra code path  
associated with an extra layer such as SQL. It is currently used only by more  
expert programmers.  
The Retrieve Display File (QDFRTVFD) API can be used to get complete and spe-  
cific information about a display file. All the information that was in the data  
description specifications (DDS) is returned in the output of the QDFRTVFD API.  
By using the API, you can get specific field information for the display file.  
Chapter 8. Use of OS/400 APIs 8-5  
Download from Www.Somanuals.com. All Manuals Search And Download.  
The Retrieve File Override Information (QDMRTVFO) API retrieves the name of the  
file that will be referenced after file overrides have been applied to the file specified.  
A user program can retrieve the actual name of the file that will be used when the  
specified file is referenced.  
SQL-related APIs process SQL extended dynamic statements in an SQL package  
object and call the DB2 SQL for OS/400 parser to check the syntax of an SQL  
statement.  
Hardware Resource APIs  
The hardware resource APIs allow you to work with hardware resources. A hard-  
ware resource is an addressable piece of hardware on the system. A hardware  
resource is known to the system by its resource name. A resource entry is the  
reference to the hardware resource in the hardware resource information, which  
can be thought of as a list of the hardware resources on the system.  
The hardware resource APIs offer a more convenient means of accessing hardware  
resource information than its output file alternative. The output file may contain a  
great amount of information that is not needed by your application. The APIs,  
however, are a means of getting specific bits of information. For example, assume  
an application handles licensing of AS/400 information, and the application needs to  
know the type number of the system processor card. This type number represents  
the feature code of the system. To get this information previously, the application  
created an output file through a CL program, read each record of the file until it  
found the system processor card record, and then read the type field of this record.  
With the APIs, the type field can be returned directly.  
Hierarchical File System (HFS) APIs  
The HFS APIs provide applications with a single, consistent interface to the file  
systems registered with the hierarchical file system on your AS/400 system. The  
APIs automatically support the document library services (QDLS) file system and  
the optical file system (QOPT), and they can support user-written file systems also.  
The HFS APIs allow you to work with nonrelational data stored in objects, such as  
directories and files in existing file systems. Using these APIs, you can perform  
such tasks as creating and deleting directories and files, reading from and writing to  
files, and changing the directory entry attributes of files and directories.  
High-Level Language APIs  
The high-level language part consists of the Application Development Manager  
APIs and the COBOL APIs.  
Application Development Manager APIs  
The Application Development Manager APIs allow a control language (CL)  
command such as the Build Part (BLDPART) command to determine, for example,  
the includes and external references that were used by certain processors (com-  
pilers or preprocessors) when processing a source member.  
In terms of Application Development Manager, a part can be either a source  
member or an object, such as a file.  
If you have an application that can use the information provided by the APIs, you  
can call these APIs from any high-level programming language. The Application  
8-6 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Development Manager feature does not need to be installed on your system for you  
to use these APIs.  
The Application Development Manager APIs are:  
Ÿ Get Space Status  
Ÿ Read Build Information  
Ÿ Set Space Status  
Ÿ Write Build Information  
The Get and Set Status APIs are used to query and initialize the build information  
space that is to contain the Application Development Manager information. The  
Write and Read Build Information APIs are used to write or read records of build  
information to and from the space.  
COBOL APIs  
These APIs let you control run units and error handling.  
Integrated Language Environment (ILE) CEE APIs  
The Integrated Language Environment (ILE) architecture on the OS/400 operating  
system provides a set of bindable APIs known as ILE CEE APIs. In some cases  
they provide additional function beyond that provided by a specific high-level lan-  
guage. For example, not all high-level languages (HLL) offer intrinsic means to  
manipulate dynamic storage. In these cases, you can supplement an HLL function  
by using appropriate ILE CEE APIs. If your HLL provides the same function as a  
particular ILE CEE API, use the HLL-specific one.  
The ILE CEE APIs are useful for mixed-language applications because they are  
HLL independent. For example, if you use only condition management ILE CEE  
APIs with a mixed-language application, you will have uniform condition handling  
semantics for that application. This uniformity can make condition management  
easier than when using multiple HLL-specific condition handling models.  
The ILE CEE APIs provide a wide-range of functions including:  
Activation group and control flow management  
Storage management  
Condition management  
Message services  
Source debugger  
Date and time manipulation  
Math functions  
Call management  
Operational descriptor access  
Naming Conventions of the ILE CEE APIs  
Most ILE CEE APIs are available to any HLL that ILE supports. Naming con-  
ventions of the ILE CEE APIs are as follows:  
Ÿ Bindable API names starting with CEE are intended to be consistent across the  
IBM SAA systems.  
Ÿ Bindable API names starting with CEE4 are specific to AS/400.  
Chapter 8. Use of OS/400 APIs 8-7  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Journal and Commit APIs  
This section includes the journal and commitment control APIs.  
Journal APIs  
The journal APIs allow you to:  
Ÿ Obtain information about some of the journal’s attributes or the journal  
receiver’s attributes  
Ÿ Obtain journal information based on the journal identifier  
Ÿ Send an entry to specified journal  
Commitment Control APIs  
The commitment control APIs allow you to:  
Ÿ Add and remove your own resources to be used during AS/400 system commit  
or rollback processing  
Ÿ Retrieve information about the commitment control environment  
Ÿ Change commitment control options  
Ÿ Put a commitment definition into rollback-required state  
Message Handling APIs  
On the AS/400, communications between programs, between jobs, between users,  
and between users and programs occurs through messages. The message han-  
dling APIs allow your application to work with these messages. The APIs consist of  
the following groups of functions:  
Ÿ Send different types of messages to users and programs  
This would be done to communicate the status of an action that is about to  
occur or one that has been completed. You can also ask a question and wait  
for a response to it.  
Ÿ Receive a message from a message queue  
This would be done to determine what action occurred, for example, to deter-  
mine whether a function completed successfully (your program can continue) or  
failed.  
Ÿ Handle errors that occur  
This is done to allow your application to tolerate errors that occur. For  
example, you can move and resend messages to another program for appro-  
priate action. Or perhaps you expected the error, and you can just remove the  
message and continue.  
Ÿ Return message or message queue information  
This is done to find attributes (for example, current delivery mode or severity) of  
a message queue or to return one or more messages on a message queue.  
Ÿ Return message description or message file information  
This is done to find attributes of a message file or to return the actual  
description of a message in a message file.  
Detailed information about these concepts and functions can be found in the CL  
Programming book, SC41-5721.  
8-8 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
National Language Support APIs  
These APIs provide the capability to retrieve cultural values, to convert sort  
sequence to different CCSIDs, to convert and truncate character strings, and to  
work with data that uses CCSIDs.  
National Language Support APIs  
This set of APIs gives you the capability to work with language IDs, sort sequence  
tables, and single- or double-byte character string data. The sort API allows a sort  
using a national language sorting sequence.  
This set also includes an API that converts all characters to either uppercase or  
lowercase.  
National Language Data Conversion APIs  
This set of APIs provides the capability to convert character data from one CCSID  
to another.  
Character Data Representation Architecture (CDRA) APIs  
These APIs are part of the Character Data Representation Architecture that allows  
access to the system CCSID support.  
Network Management APIs  
Network management APIs give you the capability to manage one or more nodes  
from another node. The network management section consists of the following  
groups of APIs:  
Ÿ Advanced Peer-to-Peer Networking (APPN) topology  
Ÿ SNA/Management Services Transport  
Ÿ Alert  
Ÿ Node list  
Ÿ Registered filter  
Ÿ Change request management  
Advanced Peer-to-Peer Networking (APPN) Topology Information  
APIs  
APPN topology information APIs allow an application to obtain information about  
the current APPN topology, and to register and deregister for information about  
ongoing updates to the topology. The specific types of topology updates that an  
application may register to receiver follow:  
Ÿ Network network node (*NN) updates  
Ÿ Network virtual node (*VN) updates  
Ÿ Local end node (*EN) updates  
Ÿ Local virtual node (*VN) updates  
APPN network topology identifies the following in an APPN subnetwork. (An APPN  
subnetwork consists of nodes having a common network ID and the links con-  
necting those nodes.)  
Ÿ All network nodes and virtual nodes in the subnetwork  
Ÿ Transmission groups interconnecting network nodes and virtual nodes in the  
subnetwork  
Ÿ Transmission groups from network nodes in the subnetwork to network nodes  
in adjacent subnetworks  
Chapter 8. Use of OS/400 APIs 8-9  
Download from Www.Somanuals.com. All Manuals Search And Download.  
The APPN local topology for an APPN node consists of the following:  
Ÿ The local node  
Ÿ Adjacent nodes (network nodes, end nodes, or virtual nodes to which the local  
node has a direct connection)  
Ÿ Transmission groups from the local node to adjacent nodes  
Both end nodes and network nodes can report local topology updates; however,  
network topology updates can be reported only on a network node system.  
SNA/Management Services Transport (SNA/MS Transport) APIs  
Systems Network Architecture Management Services Transport (SNA/MS Trans-  
port) functions are used to support the sending and receiving of management ser-  
vices data between systems in an SNA network. The network can include AS/400  
systems, Operating System/2 and NetView licensed programs, and other platforms  
that support the SNA/MS architecture.  
The SNA/MS functions provided on the AS/400 system include:  
Ÿ The transport of network management data in APPN networks  
Ÿ The maintenance of node relationships for network management  
The APIs allow a network management application running on one system to send  
data to and receive data from a network management application running on  
another system in an APPN network. The APIs are a callable interface that allow  
the application to be notified about asynchronous events, such as incoming data,  
by way of a notification placed on a data queue.  
Some examples of IBM applications that use SNA/MS Transport APIs are:  
Ÿ Alerts  
Ÿ Problem reporting  
Ÿ Remote problem analysis  
Ÿ Program temporary fix (PTF) ordering  
In large networks, the number of sessions needed to support the various network  
management applications could become burdensome without session concen-  
tration. SNA/MS Transport APIs reduce the number of SNA LU 6.2 sessions that  
would normally be used to transmit data. This support multiplexes or transmits all  
of the network management data from all the applications in a network node  
domain (network node and attached end nodes) on a single session to applications  
in another domain.  
This means that data transmitted from an end node is always sent to its network  
node server first. Then, the SNA/MS Transport support on the network node server  
routes the data to its proper destination.  
Alert APIs  
The alert APIs let your application create alerts, notify the OS/400 alert manager of  
alerts that need to be handled, and allow you to retrieve alerts and alert data. The  
generate and send APIs differ from ordinary AS/400 alert processing in that they let  
your application create an alert at any time without sending an alertable message  
to an alertable message queue. (An alertable message queue is a message queue  
that has been created or changed with the allow alerts (ALWALR) parameter speci-  
8-10 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
fied as yes.) The retrieve API allows your application, in conjunction with alert fil-  
tering, to perform user-defined actions based on the contents of the alert.  
Node List API  
A node list is either or both of the following:  
Ÿ A list of SNA nodes (network ID and control point name)  
Ÿ Internet protocol nodes (internet address or host name)  
You can use node lists for grouping systems by any criteria that you may need for  
your own applications. For example, the entries you put in a node list could be for  
systems at a certain hardware level. The List Node List Entries (QFVLSTNL) API  
is used to get the entries from the node list for use in your applications.  
Registered Filter APIs  
A filter is a function you can use to assign events into groups and to specify  
actions to take for each group. The registered filter APIs allow a product to register  
a filter with the operating system. The product can receive notification of events  
recorded in a data queue by using the Send to Data Queue (SNDDTAQ) action of  
the Work with Filter Action Entry (WRKFTRACNE) command.  
A user filter is the filter defined by the network attributes for alert filtering and by the  
system value for problem log filtering. A user filter and a registered filter differ in  
their function and their notification record. There can only be one user filter active  
at one time for each type of filter, but there can be multiple registered filters active  
at one time. All actions are active for a user filter, but only the SNDDTAQ action is  
active for a registered filter.  
A product can use registered filter APIs for the following purposes:  
Ÿ To register multiple filters at the same time for each event type (alert or  
problem log)  
Ÿ To deregister a filter when notifications from that filter are no longer necessary  
Ÿ To retrieve all the filters that are registered  
The event notification record for a registered filter differs from notification records  
for other types of filters. The registered notification contains a common header for  
all events, as well as specific information based on the type of event. The common  
header includes the name of the notification, a function type, a format, the filter  
name and library, the group name, and a timestamp. The specific information for  
the problem log includes the problem ID, the last event logged, and the timestamp  
for the last event.  
Change Request Management APIs  
This group of APIs can be used to add, remove, and list activities and to retrieve  
change request descriptions.  
Object APIs  
The object APIs consist of the following groups.  
Chapter 8. Use of OS/400 APIs 8-11  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Data Queue APIs  
Data queues are a type of system object that you can create, to which one high-  
level language (HLL) program can send data, and from which another HLL program  
can receive data. The receiving program can be waiting for the data, or can  
receive the data later.  
The advantages of using data queues are:  
Ÿ Using data queues frees a job from performing some work. If the job is an  
interactive job, the data queue APIs can provide better response time and  
decrease the size of the interactive program and its process activation group  
(PAG). This, in turn, can help overall system performance. For example, if  
several work station users enter a transaction that involves updating and  
adding to several files, the system can perform better if the interactive jobs  
submit the request for the transaction to a single batch processing job.  
Ÿ Data queues are a fast means of asynchronous communication between two  
jobs. Using a data queue to send and receive data requires less system  
resource than using database files, message queues, or data areas to send  
and receive data.  
Ÿ You can send to, receive from, and retrieve a description of a data queue in  
any HLL program. This is done by calling the Send to a Data Queue  
(QSNDDTAQ), Receive from Data Queue (QRCVDTAQ), Retrieve Data Queue  
Message (QMHRDQM), Clear Data Queue (QCLRDTAQ), and Retrieve Data  
Queue Description (QMHQRDQD) APIs.  
Ÿ When receiving data from a data queue, you can set a time-out such that the  
job waits until an entry arrives on the data queue. This is different from using  
the EOFDLY parameter on the Override Database File (OVRDBF) command,  
which causes the job to be activated whenever the delay time ends.  
Ÿ More than one job can receive data from the same data queue. This is an  
advantage in certain applications where the number of entries to be processed  
is greater than one job can handle within the desired performance restraints.  
For example, if several printers are available to print orders, several interactive  
jobs could send requests to a single data queue. A separate job for each  
printer could receive data from the data queue in first-in-first-out (FIFO), last-in-  
first-out (LIFO), or keyed-queue order.  
Ÿ Data queues have the ability to attach a sender ID to each message being  
placed on the queue. The sender ID, an attribute of the data queue that is  
established when the queue is created, contains the qualified job name and  
current user profile.  
Comparisons with Using Database Files as Queues: The following describes  
the differences between using data queues and database files:  
Ÿ Data queues have been improved to communicate between active programs,  
not to store large volumes of data or large numbers of entries. For these pur-  
poses, use database files as queues.  
Ÿ Data queues should not be used for long-term storage or indefinite retention of  
data. For this purpose, you should use database files.  
Ÿ When using data queues, you should include abnormal end procedures in your  
programs to recover any entries not yet completely processed before the  
system is ended.  
8-12 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Ÿ It is good practice to periodically (such as once a day) delete and re-create a  
data queue at a safe point. Performance can be affected if too many entries  
exist without being removed. Re-creating the data queue periodically will return  
the data queue to its optimal size.  
Similarities to Message Queues: Data queues are similar to message queues, in  
that programs can send data to a queue and that data can be received later by  
another program. However, more than one program can have a receive operation  
pending on a data queue at the same time, while only one program can have a  
receive operation pending on a message queue at the same time. (Only one  
program receives an entry from a data queue, even if more than one program is  
waiting.) Entries on a data queue are handled in either first-in first-out,  
last-in-first-out, or keyed-queue order. When an entry is received, it is removed  
from the queue.  
User Queue APIs  
The user queue APIs let you create and delete user queues. User queues are  
permanent objects with an object type of *USRQ. They provide a way for one or  
more processes to communicate asynchronously.  
You can use user queues to:  
Ÿ Communicate between two processes asynchronously  
Ÿ Store data in arrival sequence for later use  
Ÿ Contain keyed messages  
Ÿ Create a batch machine  
Ÿ Permit better performance than the data queue interface  
You can save and restore user queues. However, you can only save or restore its  
definition. You cannot save or restore the messages in it. You cannot restore a  
user queue if a user queue with the same name already exists in the library. You  
must provide programs to use this object type to enqueue and dequeue messages.  
User Index APIs  
The user index APIs allow you to:  
Ÿ Create and delete user indexes  
Ÿ Add, retrieve, and remove user index entries  
Ÿ Retrieve the attributes of a user index  
A user index is an object that allows search functions for data in the index and  
automatically sorts data based on the value of the data. User indexes are perma-  
nent objects in the user domain or in the system domain. They have an object type  
of *USRIDX and a maximum size of 4 gigabytes (4 294 967 296 bytes). They  
help streamline table searching, cross-referencing, and ordering of data. In  
general, if your table is longer than 1000 entries, an index performs faster than a  
user-sorted table.  
You can use user indexes to:  
Ÿ Provide search functions  
Ÿ Do faster insert operations than in a database file  
Ÿ Do faster retrieve operations than in a database file  
Ÿ Create an index by name, such as a telephone directory  
Ÿ Use order entry programs  
Ÿ Look up abbreviations in an index  
Chapter 8. Use of OS/400 APIs 8-13  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Ÿ Sort data automatically based on the hexadecimal value of a key  
For more information about user index considerations, refer to “User Index  
Considerations” on page 2-30. User index entries cannot contain a pointer. You  
can save and restore all the data in an index. You can also save and restore user  
indexes to another system.  
User Space APIs  
You can use these APIs to:  
Ÿ Create and delete user spaces  
Ÿ Change and retrieve the contents of user spaces  
Ÿ Change and retrieve information about user spaces  
User spaces are objects that consist of a collection of bytes used for storing user-  
defined information. They are permanent objects that are located in either the  
system domain or the user domain. They have an object type of *USRSPC and a  
maximum size of 16MB. You can save and restore user spaces to other systems.  
However, if the user spaces contain pointers, you cannot restore the pointers even  
if you want to restore them to the same system.  
You can use the user space APIs to:  
Ÿ Create user spaces to be used by list APIs to generate lists of data.  
Ÿ Store pointers.  
Ÿ Store large amounts of data. You can create a user space as large as 16MB.  
You cannot create a data area larger than 2000 bytes.  
Ÿ Save information in user space objects, and save and restore the object with  
the information in it using CL commands.  
Ÿ Pass data from job to job or from system to system.  
Object APIs  
Use of the object APIs is described as follows:  
Ÿ Change Library List (QLICHGLL) API  
This API provides the only way to change the product libraries in the library list.  
The only other way to change the product libraries is using the Create  
Command (CRTCMD) or the Create Menu (CRTMNU) command. You can  
also use this API to change the current library and the libraries in the user part  
of the library list similar to the Change Library List (CHGLIBL) command.  
Ÿ Change Object Description (QLICOBJD) API  
Unlike the Change Object Description (CHGOBJD) command, this can be used  
on all external object types. This API supports changing more parts of the  
object descriptive information than are supported using the CHGOBJD  
command.  
Ÿ Convert Type (QLICVTTP) API  
This API is the only supported way to convert a symbolic type to hexadecimal  
format and vice versa.  
Ÿ List Objects (QUSLOBJ) API  
This API returns information similar to the Display Object Description  
(DSPOBJD) command. An advantage over the DSPOBJD command is that  
you can perform authority checking on the objects and libraries. You can get a  
8-14 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
list of objects with only a certain status, which you cannot do with the  
DSPOBJD command.  
Ÿ Rename Object (QLIRNMO) API  
This API combines the functions of the Rename Object (RNMOBJ) and the  
Move Object (MOVOBJ) commands. The API allows you to rename and move  
in one step, and replace the existing target.  
Ÿ Retrieve Library Description (QLIRLIBD) API  
This API returns the number of objects in a library and the library size. Cur-  
rently, the only other function that does this is the Display Library (DSPLIB)  
command with OUTPUT(*PRINT). Without this API, the user would have to  
generate a list of objects, using the Display Object Description (DSPOBJD)  
command, to an output file (or use the QUSLOBJ API), and then count the  
number of objects and total the size of the objects (and include the size of the  
*LIB object itself).  
Ÿ Retrieve Object Description (QUSROBJD) API  
This API returns the same information as the Retrieve Object Description  
(RTVOBJD) command.  
Office APIs  
Descriptions of the office APIs follow:  
Ÿ Display Directory Panels (QOKDSPDP) API  
This API can be called to change the system distribution directory interactively  
without using the OfficeVision administration interface.  
Ÿ Display Directory X.400 Panels (QOKDSPX4) API  
This API adds an X.400 O/R name if one does not exist for a user. Also, the  
ability to display the O/R name is given. This API is for interactive use only  
and is useful if you want to add an X.400 O/R name to the directory interac-  
tively or to display an X.400 O/R name interactively.  
Ÿ Search System Directory (QOKSCHD) API  
This API gives the ability to search any fields in the system distribution directory  
and return specified fields for each user that matches the search criteria. It  
also is used to query the actual fields that exist in the system distribution direc-  
tory. It is most useful when the system distribution directory is used as a  
repository for information about users, and can be used in a program to query  
this information.  
Other office APIs check spelling, and work with the document handling and docu-  
ment conversion exit programs, which are discussed under “Office Exit Programs”  
on page 8-16.  
AnyMail/400 Mail Server Framework APIs  
These APIs are used by those who are writing support for specific electronic mail  
(E-mail) server functions on the AS/400. An E-mail framework (the mail server  
framework or MSF), part of AnyMail/400, was added at Version 3 Release 1.  
One API allows programs to create E-mail-related messages (MSF messages) that  
are then processed as part of this framework. The framework has a series of exit  
points that allow someone to plug in their own programs that are called when the  
Chapter 8. Use of OS/400 APIs 8-15  
Download from Www.Somanuals.com. All Manuals Search And Download.  
MSF framework processes its messages. These exit programs perform E-mail-  
related functions and are passed information about the MSF message. These exit  
programs can use two other APIs to retrieve or change part of the MSF message.  
The remaining APIs are used to configure information to the MSF framework that it  
uses to tag and identify the parts of an MSF message. There are APIs to add,  
remove, and list these MSF-data-type definitions as part of MSF's configuration.  
SNADS File Server APIs  
You would use these APIs if you were dealing with AnyMail/400 mail server frame-  
work (MSF) messages that contained SNADS attachments. You would use the file  
server object read API if the MSF message was originated by OfficeVision or object  
distribution. You would use the create and write APIs if the MSF message was  
destined for an OfficeVision user or an object distribution user, or if you want to  
temporarily store attachments.  
Office Exit Programs  
Descriptions of the office exit programs follow:  
Ÿ Directory Search exit program  
This exit program is provided for those who want the ability to search other files  
that contain user information. For example, when in OfficeVision and a user is  
on the Search System Directory display, if this exit program is provided, the  
F10 key is provided to call this exit program and as a result return the user ID  
and address.  
Ÿ Directory Supplier exit program  
This exit program is provided for system distribution directory shadowing. It  
provides the ability to prevent add, change, and delete operations of select data  
from being supplied to a collector system. The advantages this provides is  
additional security to allow other systems on the network to see only the data  
you want them to see. It also gives you a way to provide partial replication  
through shadowing.  
Ÿ Directory Verification exit program  
This exit program is provided to verify data that is being added, changed, and  
deleted in the system distribution directory. It is called for when data is directly  
being changed on the system and also when data is being changed through  
shadowing. This gives you the ability to verify that data is valid for specific  
fields (like telephone number format). It also gives you the added security of  
ensuring that the systems changing your data are authorized to do so. You  
could also use this exit program to provide partial replication for data that has  
already been sent from the other systems.  
Ÿ Document Conversion exit program  
This exit program allows other document conversion programs to be called  
when a request is made for the OfficeVision program to process a document  
that is an unsupported type.  
Ÿ Document Handling exit program  
This exit program allows other editors and applications to be called from the  
OfficeVision word processing and print functions.  
Ÿ User Application Administration exit program  
8-16 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
This exit program passes control to the application enabler where a registered  
alternate administration program will be called.  
Operational Assistant APIs  
Most functions on the AS/400 Operational Assistant menu can be accessed individ-  
ually by calling APIs found in the QSYS library. The Operational Assistant APIs  
allow you to incorporate Operational Assistant functions into your application  
menus.  
For information about the Operational-Assistant backup APIs, see “Backup and  
Recovery APIs” on page 8-1.  
You can also tailor some of the Operational Assistant functions to your needs by  
using Operational Assistant exit programs.  
Performance Collector APIs  
The performance collector APIs allow applications to be developed that provide  
real-time performance monitoring capabilities. As with all APIs, this can be done  
without the overhead of databases or spooled files, and through a hardened inter-  
face. This is in contrast to the performance monitor, which collects much more  
information and retrieves its data much less frequently to database files. That is, in  
real-time, you have more control over collecting just the type of data you are inter-  
ested in.  
Print APIs  
The print APIs consist of the following:  
Ÿ Print APIs  
Ÿ Spooled file APIs  
Ÿ Exit programs  
Print APIs  
Print APIs can obtain information about or perform printing activities on the AS/400  
system. Print APIs can:  
Ÿ Retrieve output queue information such as status and number of entries on the  
queue.  
Ÿ Retrieve information about specific printer writers.  
Ÿ Transform data streams from one type to another.  
The following discussion pertains to specific print APIs.  
The AFP to ASCII Transform (QWPZTAFP) API converts an Advanced Function  
Printing data stream (AFPDS) into an ASCII printer data stream. The ASCII printer  
data streams supported are the printer control language Hewlett Packard**  
LaserJet**, Personal Printer Data Stream level 3 and 4 (IBM 4019, 4029), and  
PostScript** data stream. The API can be useful to anyone who wants to print AFP  
documents to lower-cost ASCII printers.  
The Host Print Transform (QWPZHPTR) API converts an AFP data stream or an  
SNA-character-string (SCS) data stream to an ASCII data stream. The Host Print  
Transform API can be used as an alternative to printer emulation in the following  
situations to transform AFPDS and SCS data streams to ASCII data streams:  
Chapter 8. Use of OS/400 APIs 8-17  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Ÿ Twinaxial ASCII printing  
Ÿ LAN ASCII printing  
Ÿ TCP/IP printing through the Send TCP/IP Spooled File command (known as  
LPR or line printer requester in UNIX TCP/IP)  
The API provides a programming interface to the same transform.  
The QWPZHPTR API goes along with another function, the Print Driver exit  
program. This exit program allows you to create your own print driver program.  
For example, the system provides a print driver to communicate to LAN-attached  
printers through the LexLink protocol. This print driver uses the host print transform  
to convert the SNA-character-string spooled files or AFP spooled files to ASCII  
before sending them to the printer.  
With the QWPZHPTR API, you can write your own print driver (maybe to communi-  
cate over a protocol other than LexLink), but still use the system-provided transform  
(host print transform).  
Spooled File APIs  
Spooled file APIs obtain specific information about spooled files. For example,  
spooled file APIs can:  
Ÿ Return a list of spooled files based on given selection criteria, such as a user  
or an output queue.  
Ÿ Provide functions to access a specific spooled file from which the API can  
return the attributes and data of a spooled file or create a duplicate of a specific  
spooled file.  
Spooled file APIs are useful in writing applications to clean up, save, and restore  
spooled files.  
Problem Management APIs  
The problem management APIs offer you the ability to write problem management  
solutions, improve serviceability, and manage your own applications. Problem  
management APIs deal directly with how the AS/400 handles problems today.  
Today, the problem log provides most of the operations necessary for problem  
management in a network environment. These APIs have several capabilities:  
Filtering  
A filter categorizes problem log entries into groups and performs operations on  
them accordingly.  
The problem log applies the currently active filter to a problem log entry whenever a  
problem entry is created, changed, or deleted using system-provided interfaces.  
The operations supported allow you to send application notification to a user data  
queue and assign the problem to a user. Your application can receive these notifi-  
cations from the data queue using existing APIs.  
8-18 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Working with a Problem  
Problem analysis is the process of finding the cause of a problem and identifying  
why the system is not working. Often this process identifies equipment or data  
communications functions as the source of the problem. The Work with Problem  
(QPDWRKPB) API allows you to perform problem analysis on local machine-  
detected problems in the problem log. The Work with Problem (QPDWRKPB) API  
prepares the problem in the problem log for reporting; it does not report the  
problem automatically.  
Problem Log Entry APIs  
The following set of problem management APIs are for designing problem log appli-  
cations.  
Ÿ Add Problem Log Entry (QsxAddProblemLogEntry)  
Ÿ Change Problem Log Entry (QsxChangeProblemLogEntry)  
Ÿ Create Problem Log Entry (QsxCreateProblemLogEntry)  
Ÿ Delete Problem Log Entry (QsxDeleteProblemLogEntry)  
Ÿ End Problem Log Services (QsxEndProblemLogServices)  
Ÿ Retrieve Problem Log Entry (QsxRetrieveProblemLogEntry)  
Ÿ Start Problem Log Services (QsxStartProblemLogServices)  
Error Reporting APIs  
The following set of problem management APIs log software problems.  
Ÿ Log Software Error (QPDLOGER) reports a software problem and collects data  
needed for its resolution.  
Ÿ Report Software Error (QpdReportSoftwareError) logs problems in the problem  
log and sends it to a service provider.  
Program and CL Command APIs  
You can use these APIs to do the following:  
Ÿ Create programs  
Ÿ List program or service program information  
Ÿ Retrieve program or service program information  
Ÿ Activate service programs  
Ÿ Manipulate entries in the associated space of a program  
Ÿ Handle compiler preprocessor-related tasks  
Ÿ Resolve a pointer to an export  
Ÿ Scan a string of characters for a pattern  
Ÿ Execute a CL command or run a command from within an HLL or CL program  
You can use the Create Program (QPRCRTPG) API to write your own assembler  
or compiler. When the assembler or compiler has created the machine interface  
template, this API is used to create the program from it.  
Registration Facility APIs  
The registration facility is a service that provides storage and retrieval operations  
for OS/400 and non-OS/400 exit points and exit programs. An exit point is a spe-  
cific point in a system function or program where control may be passed to one or  
more specified exit programs. An exit program is a program to which control is  
passed from an exit point. This registration facility repository allows multiple  
programs to associate with a given system function or application function.  
Chapter 8. Use of OS/400 APIs 8-19  
Download from Www.Somanuals.com. All Manuals Search And Download.  
The registration facility APIs provide the capability to:  
Ÿ Register and deregister exit points with the registration facility  
Ÿ Add and remove exit programs to and from the repository  
Ÿ Retrieve exit point and exit program information from the repository  
Ÿ Designate the order in which exit programs should be called  
An exit point can call one program, a fixed number of programs, or all programs  
associated with an exit point. The exit program number associated with each exit  
program should be used to determine the sequence in which the exit programs are  
run.  
An exit point can be registered multiple times with the same exit point name;  
however, the combination of the exit point name and the exit point format name  
must be unique. Each exit program will be associated with a specific exit point and  
exit point format. The exit point format name can be used to indicate that a change  
occurred to the interface of the exit point. For example, this unique name (exit  
point and format) could be the result of a parameter change, version change, exit  
program data definition, and so forth. This unique name will facilitate having dif-  
ferent exit programs run from different versions of a product for the same exit point  
name.  
Security APIs  
The OS/400 security APIs allow you to:  
Ÿ Perform many of the security functions through a program interface. You can  
use APIs instead of CL commands.  
Ÿ Combine many individual jobs into a single server or overhead job without com-  
promising system security.  
Network Security APIs  
The OS/400 network security APIs provide a means that automatically logs you on  
to a server when you request a NetWare** function (for example, file or print). You  
can create authentication entries for each NetWare Directory Services** (NDS**)  
tree or NetWare 3.x server to which you are authorized. The entry identifies the  
tree or server, your name on that server, and (optionally) your password. When  
you request a NetWare function, the system attempts to start a connection to the  
server by using this data.  
Note: To use these APIs, you need the Enhanced NetWare Integration for OS/400  
feature.  
Software Product APIs  
The software products APIs were created to provide the user with the ability to  
package and manage their product in a manner similar to the way IBM licensed  
programs are managed. OS/400 commands along with these APIs allow you to  
work with and create program temporary fixes (PTFs), to package and distribute  
products, and to manage software licenses.  
For more details on managing a product, see the System Manager Use book,  
SC41-5321. The System Manager for AS/400 licensed program can be used to  
facilitate managing your products.  
8-20 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
The CD-ROM premastering APIs could be used if you currently produce distributed  
systems license option (DSLO) distribution tapes at a central site. If you would now  
like to distribute on CD-ROM rather than tape, you would use the CD-ROM pre-  
mastering APIs.  
You would use the Handle CD-ROM Premastering State (QlpHandleCdState or  
QLPCDRST) API to place your job into a CD-ROM premastering state. While in  
this state, any save operations performed will have information about the tape file  
sizes stored away for future use in generating the QDSETMAP file. In the case of  
a SAVSYS or option 40 (Create Distribution Tape) on the Work with Licensed Pro-  
grams menu, special files are saved to tape so that the CD-ROM volumes  
produced can be used for installation.  
When the save operations have been performed, you would then use the Generate  
CD-ROM Premastering Information (QlpGenerateCdPremasteringInfo or  
QLPCDINF) API. This API is used to analyze the tape file size information stored  
away during the previous API and produce a byte-stream file that contains informa-  
tion about which CD-ROM volumes these files will reside on. Information is also  
returned into a user space that is useful in producing a mastering control file that  
may be necessary when having the CD-ROMs mastered.  
UNIX-Type APIs  
The UNIX-type APIs are intended for experienced UNIX programmers who want to  
do either of the following:  
Ÿ Create new application programs that run on the AS/400  
Ÿ Create an AS/400 version of existing application programs that run on other  
UNIX-based systems  
The UNIX-type APIs consist of the following groups.  
Environment Variable APIs  
Environment variables are character strings of the form name=value that are  
stored in an environment space outside of the program. The strings are stored in a  
temporary space associated with the job.  
Environment variables can be set using the putenv() or Qp0zPutEnv() function.  
They can be retrieved using the getenv() or Qp0zGetEnv() function. The putenv()  
and getenv() functions are designed to meet the X/Open** single UNIX specifica-  
tion (formerly Spec 1170). The Qp0zPutEnv() and Qp0zGetEnv() functions are  
AS/400 extensions to the industry-standard APIs. They provide the additional  
capability to store or retrieve a coded character set identifier (CCSID) associated  
with the string.  
After environment variables are set, they exist for the duration of the job. There is  
no way to remove an environment variable. However, the value can be set to  
NULL by using a subsequent call to putenv() or Qp0zPutEnv() and specifying a  
value of NULL.  
The OS/400 support for environment variables does differ from the usual behavior  
of environment variables on UNIX systems:  
Ÿ There is no default set of environment variables provided when a job starts.  
On the AS/400, the environ array, which points to the environment variable  
Chapter 8. Use of OS/400 APIs 8-21  
Download from Www.Somanuals.com. All Manuals Search And Download.  
strings, is NULL (not initialized) until environment variables are associated with  
the job.  
Ÿ On a UNIX system, the exec() function creates a new process and extends the  
environment variables of the original process to the new process. Although the  
AS/400 has no exec() function, environment variables are extended to a new  
job created using the Submit Job (SBMJOB) command, provided the first job  
has environment variables.  
To help alleviate these differences, OS/400 provides several nonstandard interfaces  
that can be used to establish a default set of environment variables.  
Ÿ The Add Environment Variable (ADDENVVAR) CL command can be used to  
set an environment variable for a job. Further, a CL program can be written  
using the ADDENVVAR command that sets several environment variables for a  
job. Alternatively, the putenv() or Qp0zPutEnv() function can be used in a  
similar manner in a C program.  
Ÿ Other environment variable CL commands, Change Environment Variable  
(CHGENVVAR) and Work with Environment Variables (WRKENVVAR), or C  
functions can be used to change or retrieve environment variables for a job.  
Integrated File System APIs  
The integrated file system is a part of OS/400 that supports stream input/output and  
storage management similar to personal computer and UNIX operating systems.  
The stream file support is designed for efficient use in client/server applications.  
Stream files are particularly well suited for storing strings of data such as the text of  
documents, images, audio, and video.  
The integrated file system provides a hierarchical directory structure that supports  
UNIX-based open system standards, such as POSIX** and XPG. This file and  
directory structure provides the users of PC operating systems with a familiar envi-  
ronment. The integrated file system takes better advantage of the graphical user  
interface.  
In addition to providing a common interface for users and application to access  
stream files, the integrated file system also provides access to database files, docu-  
ments and other objects stored on the AS/400.  
The integrated file system APIs can perform operations on directories, files, and  
related objects in the file systems accessed through the integrated file system inter-  
face. For more information about the integrated file system, see the Integrated File  
System Introduction book, SC41-5711.  
Interprocess Communication APIs  
Interprocess communication (IPC) on the AS/400 is made up of three services:  
message queues, semaphores, and shared memory. The basic purpose of these  
services is to provide OS/400 processes with a way to communicate with each  
other through a set of standardized APIs. These C-language functions are based  
on the definitions in the X/Open single UNIX specification (formerly Spec 1170).  
Message queues provide a form of message passing in which any process (given  
that it has the necessary permissions) can read a message from or write a  
message to any message queue on the system. There are no requirements that a  
process be waiting to receive a message from a queue before another process  
8-22 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
sends one, or that a message exist on the queue before a process requests to  
receive one.  
A semaphore is a synchronization mechanism similar to a mutex or a machine  
interface (MI) lock. It can be used to control access to shared resources, or used  
to notify other processes of the availability of resources.  
Processes can communicate directly with one another by sharing parts of their  
memory space and then reading and writing the data stored in the shared  
memory. Synchronization of shared memory is the responsibility of the application  
program. Semaphores can be used to synchronize shared memory use across  
processes. Mutexes or condition variables can be used to synchronize shared  
memory use across threads.  
Although each IPC service provides a specific type of interprocess communication,  
the three services share many similarities. Each service defines a mechanism  
through which its communications take place. For message queues, that mech-  
anism is a message queue; for semaphores, it is a semaphore set; and for shared  
memory, it is a shared memory segment. These mechanisms are identified by a  
unique positive integer, called, respectively, a message queue identifier (msqid), a  
semaphore identifier (semid), and a shared memory identifier (shmid).  
Associated with each identifier is a data structure that contains state information for  
the IPC mechanism, as well as ownership and permissions information. This struc-  
ture is similar to a file permissions structure, and is initialized by the process that  
creates the IPC mechanism. It is then checked by all subsequent IPC operations  
to determine if the requesting process has the required permissions to perform the  
operation.  
To get an identifier, a process must either create a new IPC mechanism or access  
an existing mechanism. This is done through the msgget(), semget(), and  
shmget() functions. Each get operation takes as input a key parameter and  
returns an identifier. Each get operation also takes a flag parameter. This flag  
parameter contains the IPC permissions for the mechanism as well as bits that  
determine whether or not a new mechanism is created.  
When a message queue, semaphore set, or shared memory segment is created,  
the process that creates it determines how it can be accessed. Subsequent IPC  
operations do a permission test for the calling process before allowing the process  
to perform the requested operation.  
Signal APIs  
An X/Open** specification defines a signal1 as “a mechanism by which a process  
may be notified of, or affected by, an event occurring in the system.” The term  
signal is also used to refer to the event itself.  
A signal is said to be generated when the event that causes the signal first occurs.  
Examples of such events include the following:  
Ÿ System-detected errors  
Ÿ Timer expiration  
1
X/Open CAE Specification System Interface Definitions Issue 4, Number 2, Glossary, page 27. X/Open Company Ltd., United  
Kingdom, 1994.  
Chapter 8. Use of OS/400 APIs 8-23  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Ÿ Terminal (work station) activity  
Ÿ Calling an API such as the X/Open kill() function, the American National  
Standard C raise() function, or the ILE CEESGL (signal a condition) function.  
The signal action vector is a list of signal-handling actions for each defined signal.  
The signal action vector is maintained separately for each process and is inherited  
from the parent process. The signal action vector specifies the signal-handling  
actions for both synchronously and asynchronously generated signals.  
A signal is said to be delivered to a process when the specified signal-handling  
action for the signal is taken.  
The following describes some of the support provided by OS/400 signal manage-  
ment. The set of defined signals is determined by the system. The system speci-  
fies the attributes for each defined signal. These attributes consist of a signal  
number, the initial signal action, and the signal default action. The system also  
specifies an initial signal blocking mask. The set of defined signals, the signal attri-  
butes, and signal blocking mask are referred to as signal controls.  
A signal can be generated or delivered only to a process that has expressed an  
interest in signals. An error condition results under the following conditions:  
Ÿ An attempt is made to generate a signal when the system signal controls have  
not been initialized.  
Ÿ An attempt is made to generate a signal for a process that has not been  
enabled for signals.  
A process can express an interest in signals by calling the Qp0sEnableSignals()  
API. In addition, calling particular signal APIs implicitly enables the process for  
signals.  
If the process has not been enabled for signals, the process signal controls are set  
from signal controls established by the system during IPL (the system signal con-  
trols). An error condition results if an attempt is made to enable signals for the  
process before the system signal controls have been initialized.  
Once the process signal controls have been initialized, the user is permitted to  
change the signal controls for the process.  
The attributes for each defined signal are stored in an object called a signal  
monitor. The system supports a maximum of 63 signal monitors for each process.  
The process signal action vector is a list of signal monitors, one for each defined  
signal. The signal monitor contains, but is not limited to, the following information:  
Ÿ Signal action  
Ÿ Signal default action  
Ÿ Signal options  
The signal action defines the action to be taken by the system when a process  
receives an unblocked signal. The user can change the signal action for a process  
signal monitor.  
The signal default action field defines the action to be taken by the system when  
the signal action is set to handle using signal default action. The signal default  
action for a signal monitor is set in the system signal controls and cannot be  
changed for a process signal monitor.  
8-24 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
The signal options specify an additional set of attributes for the signal monitor.  
The primary use of these options is to specify an additional set of actions to be  
taken by the system when a signal-catching function is called.  
A signal is generated by sending a request to a signal monitor.  
The process to receive the signal is identified by a process ID. The process ID is  
used to indicate whether the signal should be sent to an individual process or to a  
group of processes (known as a process group). The process ID is used to locate  
an entry in the system-managed process table. A process table entry contains the  
following information relating to the process:  
Ÿ Parent process ID  
Ÿ Process group ID  
Ÿ Status information  
The parent process is the logical creator of the process. A process group repre-  
sents a collection of processes that are bound together for some common purpose.  
The process sending a signal must have the appropriate authority to the receiving  
process.  
The OS/400 support for signals does differ from the usual behavior of signals on  
UNIX systems.  
For additional information about signal concepts, OS/400 management support, and  
how signals differ on OS/400 from UNIX systems, see the “Signal Concepts” topic  
in the book System API Reference.  
Simple Network Management Protocol (SNMP) APIs  
The Simple Network Management Protocol (SNMP) APIs comprise the SNMP sub-  
agent APIs and the SNMP manager APIs.  
SNMP Subagent APIs: The SNMP subagent APIs can be used to dynamically  
extend the management information base (MIB) that the system SNMP agent is  
aware of. The MIB is extended without any change to the SNMP agent itself while  
the AS/400 is running. Dynamically added MIB subtrees (as supported and defined  
by a program known as a subagent) provide this capability. You may now extend  
the remote and automated system management capabilities of the AS/400 within  
the SNMP framework. So, for example, you could define an SNMP MIB group for  
your RPG and SQL application.  
The Distributed Protocol Interface (DPI) is an extension to SNMP agents. DPI  
permits users to dynamically add, delete, or replace management variables in the  
local MIB without requiring recompilation of the SNMP agent.  
SNMP Manager APIs: SNMP managing applications typically use APIs to estab-  
lish communication with local or remote SNMP agents, and then call other APIs to  
retrieve or modify MIB objects managed by those agents. The OS/400 SNMP  
manager APIs accomplish both of these tasks within the same API. Three  
manager APIs are provided to perform the SNMP GET, GETNEXT, and SET oper-  
ations. In general, all three APIs are blocked, that is, once the application calls  
these APIs, the API constructs a proper SNMP message, delivers it to the proper  
SNMP agent, waits, decodes the response from the agent, and delivers the infor-  
mation to the application. No processing occurs in the application until the API  
Chapter 8. Use of OS/400 APIs 8-25  
Download from Www.Somanuals.com. All Manuals Search And Download.  
delivers this information or times out. The communications mechanism between  
the manager APIs and agents uses the User Datagram Protocol (UDP). Therefore,  
both systems need to support UDP.  
Sockets APIs  
Sockets provides an API for applications that require program-to-program commu-  
nications. This interface is based on and compatible with Berkeley Software Distri-  
butions 4.3. Using sockets, server and client processes can be on the same  
system or on different systems.  
The types of sockets follow:  
Ÿ Stream sockets, which are connection oriented  
Ÿ Datagrams, which are connectionless  
Ÿ Raw sockets, which provide direct access to low-layer protocols  
Ÿ Sequenced-packet sockets, which are connection oriented  
Figure 8-1 shows a typical application flow when the sockets APIs are used.  
SERVER  
CLIENT  
┌──────────────────┐  
┌──────────────────┐  
│
socket()  
│
│
socket()  
│
└────────┬─────────┘  
└────────┬─────────┘  
6
6
┌──────────────────┐  
┌──────────────────┐  
│
bind()  
│
│
bind()  
│
└────────┬─────────┘  
└────────┬─────────┘  
6
│
┌──────────────────┐  
│
│
listen()  
│
│
└────────┬─────────┘  
│
│
6
│
┌──────────────────┐  
│
│
connect()  
│
│
└────────┬─────────┘  
6
│
┌──────────────────┐  
│
│
accept()  
│
│
└────────┬─────────┘  
│
6
6
┌──────────────────┐  
┌──────────────────┐  
│
│
send  
receive  
├───────────5│  
│ %──────────┤  
receive  
send  
│
│
└────────┬─────────┘  
└────────┬─────────┘  
6
6
┌──────────────────┐  
┌──────────────────┐  
│
close()  
│
│
close()  
│
└──────────────────┘  
└──────────────────┘  
Figure 8-1. Simplified Sequence of Events for a Sockets Program Example  
For more information about sockets, see the Sockets Programming book,  
SC41-5422.  
8-26 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Process-Related APIs  
The process-related APIs perform process-related or other general operations.  
Using these APIs, a process can get the process ID of itself, its parent process, or  
the process group. A process can also check the status for itself, its child pro-  
cesses, or the process group.  
For information on APIs to create processes (for example, spawn() and spawnp()),  
see the System API Reference book.  
User Interface APIs  
The user interface manager (UIM) APIs are a set of programs that allow the user  
the ability to use panel groups and create applications that function in the same  
way. This means using the same standards for function key descriptions, and so  
forth, as the system panels.  
The UIM APIs are used in combination with variables, lists, and panel definitions in  
a panel group object.  
When you design an application program that manipulates the user interface, you  
can use all UIM panel groups, data description specifications (DDS) display files  
with UIM help, or DDS display files with help in folders. The following shows the  
advantages of using UIM versus DDS.  
UIM Advantages  
The advantages of using UIM over DDS follow:  
Ÿ Uses the same standards as the AS/400  
There is no need to redefine standards because the applications would work  
the same way as the system panels. UIM formats the panel for you based on  
what you want displayed.  
Ÿ Processes more efficiently from a list panel  
– UIM has the ability to process commands from a list panel. There is no  
need to call a program to issue the command.  
– UIM has the ability to prompt in the same manner as the AS/400.  
– You can specify a program for UIM to call after the option is selected.  
– Confirmation panels are built into the system.  
– UIM provides more efficient list entry access and update processing.  
Ÿ Works better with languages that efficiently process structures  
Each type of UIM exit program requires a different set of parameters, thus  
making it difficult to have one program that processes all the exit program func-  
tions.  
Ÿ Provides for more modular programming techniques  
One program can process all incomplete list exit program calls, one can open  
all applications, and so forth.  
Ÿ Has the ability to condition menu options  
Ÿ Formats and handles scrolling of large areas with no user program intervention  
Examples are data, list, information, menu, and function key areas.  
Chapter 8. Use of OS/400 APIs 8-27  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DDS Advantages  
The advantages of using DDS over UIM follow:  
Ÿ Provides more flexibility in screen design  
The user defines in what row and column a field should appear.  
Ÿ Provides initial formatting with Screen Design Aid (SDA)  
Ÿ Has the ability to use UIM help or help in folders  
Ÿ Has the ability to take advantage of graphical operations windows  
Ÿ Does subfile processing  
Ÿ Uses edit code (EDTCDE), edit word (EDTWRD), and user-defined editing  
Ÿ Is faster for smaller applications  
DDS requires less initial setup (that is, the display file may be opened automat-  
ically by an HLL program).  
Ÿ Can also imbed HyperText Markup Language (HTML) tags into the data stream  
that is sent out  
Virtual Terminal APIs  
The virtual terminal APIs allow your AS/400 application programs to interact with  
AS/400 application programs that are performing work station input and output  
(I/O).  
A virtual terminal is a device that does not have hardware associated with it. It  
forms a connection between your application and AS/400 applications, representing  
a physical work station (possibly on a remote system). The OS/400 licensed  
program manages the virtual terminal, which directs work station I/O performed by  
an AS/400 application to the virtual terminal. The virtual terminal APIs allow  
another AS/400 application, called a server program, to work with the data associ-  
ated with the virtual terminal.  
In a distributed systems environment, the requesting program is called a client; the  
answering program is called a server. The client and server programs may reside  
on the same AS/400 system or may be distributed between two different systems.  
The server program generally runs on behalf of (or in conjunction with) the client  
program. Together, the server program and the client program allow a work station  
to be supported as if the work station were connected locally.  
Work Management APIs  
This group of APIs helps you to better manage the work on your system. The APIs  
let you keep track of the jobs and the things associated with those jobs. Also,  
some of the APIs allow you to adjust the performance characteristics.  
Work Station Support APIs  
The work station support APIs allow you to control the type-ahead characteristics of  
a work station and to retrieve information about the last output operation to the  
requester device for the specified interactive job.  
Type-ahead, also called keyboard buffering, lets the user type data faster than it  
can be sent to the system. Attention key buffering determines how to process  
the action of pressing an Attention key. If attention key buffering is on, the Atten-  
8-28 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
tion key is treated as any other key. If attention key buffering is not on, pressing  
the Attention key results in sending the information to the system even when other  
work station input is inhibited.  
Miscellaneous APIs  
The miscellaneous part of the System API Reference includes the following miscel-  
laneous APIs plus the process open list APIs.  
Miscellaneous APIs  
The miscellaneous APIs include the following:  
Ÿ Convert Date and Time Format (QWCCVTDT) API  
This API allows you to convert date and time formats from one format to  
another format.  
Ÿ Remove All Bookmarks from a Course (QEARMVBM) API  
This API allows you to remove the bookmarks from a Tutorial System Support  
course.  
Ÿ Retrieve Data (QPARTVDA) API  
This API retrieves up to 1KB of user data, which was passed to this system  
with the Start Pass-through (QPASTRPT) API.  
Ÿ Start Pass-Through (QPASTRPT) API  
This API starts a 5250 pass-through session and optionally passes up to 1KB  
of user data from the source system to the target system. This data can be  
accessed on the target system with the Retrieve Data (QPARTVDA) API.  
Process Open List APIs  
These AS/400 list APIs can improve perceived performance when they create lists.  
The APIs create and make available to the caller a partial listing of the total set of  
files, messages, or objects. This list is immediately available to be acted upon,  
while the remainder of the list is being created. The user does not have to wait for  
the entire list to be created. Following is a description of the APIs and how they  
work together.  
The process open list APIs are used to access the data returned by the following  
AS/400 APIs:  
Ÿ Open List of Job Log Messages (QGYOLJBL)  
Ÿ Open List of Messages (QGYOLMSG)  
Ÿ Open List of Objects (QGYOLOBJ)  
Ÿ Open List of Objects to be Backed Up (QEZOLBKL)  
Ÿ Open List of Printers (QGYRPRTL)  
Ÿ Open List of Spooled Files (QGYOLSPL)  
The APIs in the previous list are located in their respective sections in the System  
API Reference book; that is, backup and recovery APIs, message handling APIs,  
object APIs, and print APIs.  
Each of these APIs builds a list of the appropriate type and returns the number of  
records requested by the caller of the API. Also returned from the list building  
program is a request handle associated with that particular list. This request  
handle can be used on subsequent calls to the Get List Entry (QGYGTLE) API to  
Chapter 8. Use of OS/400 APIs 8-29  
Download from Www.Somanuals.com. All Manuals Search And Download.  
get more records from the list. The request handle is valid until the Close List  
(QGYCLST) API is used to close the list.  
The request handle is also used as input to the following APIs when you need to  
find a specific entry in the list:  
Ÿ Find Entry Number in List (QGYFNDE) API, which returns the number of the  
entry in a list of information for a given key value. This API can be used with  
lists that have been created by either the QGYOLOBJ or QGYOLSPL API.  
Ÿ Find Entry Number in Message List (QGYFNDME) API, which returns the  
number of the entry in the list of message information for a given key value.  
This API can be used with lists that have been created by either the  
QGYOLMSG or QGYOLJBL API.  
Ÿ Find Field Numbers in List (QGYFNDF) API, which returns the number of the  
entry in a list of information and the value of that entry whenever the value of  
that field changes.  
8-30 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Chapter 9. Common API Programming Errors  
This chapter contains information identified as common programming errors  
encountered when using APIs within application programs. The chapter design  
provides two program examples for each common error. The first program  
example is incorrectly coded and is followed by the correctly coded example. If you  
encounter errors or problems while working with APIs, these examples may provide  
ideas or solutions.  
Note: Do not assume that an API will do things other than what the System API  
Reference mentions. If the manual does not say specifically that it is  
allowed, it probably is not.  
Figure 9-1 identifies common API programming errors and refers you to examples  
that show you how to avoid the errors.  
Figure 9-1. Common Programming Errors  
Task  
Location of Example  
Using the error code param-  
eter  
Page 9-2  
Defining data structures  
Page 9-5  
Page 9-10  
Page 9-14  
Defining receiver variables  
Defining list entry format  
lengths  
Using null pointers with OPM  
APIs  
Page 9-18  
Defining byte alignment  
Using offsets in user space  
Coding for new function  
Page 9-22  
Page 9-27  
Page 9-36  
Copyright IBM Corp. 1997  
9-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Using the Error Code Parameter  
The error code parameter provides a way for you to determine if the API encoun-  
tered any errors.  
The examples in this topic present a program used for creating a user space.  
Using the Error Code Parameter—Example of Incorrect Coding  
The common error shown in the following example is the use of the error code  
structure to indicate to the API not to send exception messages for errors found.  
Additionally, the example does not examine the error code structure to determine if  
the API call was successful or not. To demonstrate the improper use of the error  
code structure, an incorrect value is used on the replace parameter of the  
QUSCRTUS API. The replace parameter is a required parameter. The coded  
error (*XXXXXXX) is shown at location .2/ in the incorrect and correct coding  
(pages 9-3 and 9-4, respectively).  
Both the incorrect and correct coding (.1/ on page 9-3 and .1/ on page 9-3) show  
the program monitoring for any error from the call to the API. However, the  
program does not examine the bytes available field after calling the QUSCRTUS  
API.  
Because of the error on the replace parameter, the requested user space is not  
created. The calling program, however, is not aware of this (shown at .3/ on page  
9-3).  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name: PGM1  
ᑍ
ᑍProgram Language: RPG  
ᑍ
ᑍDescription: This sample program illustrates the incorrect  
ᑍ
ᑍ
way of using the error code parameter.  
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍAPIs Used: QUSCRTUS - Create User Space  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC  
I/COPY QSYSINC/QRPGSRC,QUSEC  
ᑍᑍ  
ISPCNAM  
I I  
I I  
DS  
'SPCNAME '  
'PAM  
1 1ð SPC  
11 2ð LIB  
'
ᑍᑍ OTHER ASSORTED VARIABLES  
DS  
I
I I  
I
2ððð  
B 1 4ðSIZ  
B 5 8ðSTART  
9 9 INTVAL  
I I  
ᑍ
X'ðð'  
ᑍ Initialize the bytes provided field (QUSBNDB) of the error code  
ᑍ structure. Languages such as RPG and CL tend to initialize the bytes  
ᑍ provided field to blanks, which when passed to an API is viewed as a  
ᑍ very large (and incorrect) binary value. If you receive CPF3CF1 when  
9-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ calling an API, the bytes provided field should be the first field  
ᑍ you examine as part of problem determination.  
C
Z-ADD16  
QUSBNB  
.1/  
ᑍ
ᑍ CREATE THE SPACE TO HOLD THE DATA  
C
C
C
C
C
C
C
C
C
CALL 'QUSCRTUS'  
PARM  
SPCNAM  
PARM 'EXT_ATTR'EXTATR 1ð  
PARM  
SIZ  
INTVAL  
PARM  
PARM 'ᑍALL  
'PUBAUT 1ð  
PARM 'NO TEXT 'TXTDSC 5ð  
PARM 'ᑍXXXXXXX'REPLAC 1ð  
PARM  
.2/  
QUSBN  
ᑍᑍ Program does not check the error code parameter .3/  
ᑍᑍ  
C
SETON  
LR  
Using the Error Code Parameter—Example of Correct Coding  
You can add code to help you discover what errors may be in a program. In the  
following example program, code has been added to monitor error information  
passed back in the error code parameter (QUSBN). This code is shown at .4/ on  
page 9-4. The code at .4/ has been added to check the error code parameter for  
any messages and to display the exception identifier to the user if any errors are  
found. The incorrectly coded program does no checking for the error code param-  
eter (shown at .3/ on page 9-3).  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name: PGM2  
ᑍ
ᑍProgram Language: RPG  
ᑍ
ᑍDescription: This sample program illustrates the correct  
ᑍ
ᑍ
way of using the error code parameter.  
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍAPIs Used: QUSCRTUS - Create User Space  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC  
I/COPY QSYSINC/QRPGSRC,QUSEC  
ᑍᑍ  
ISPCNAM  
I I  
I I  
DS  
'SPCNAME '  
'QTEMP  
1 1ð SPC  
11 2ð LIB  
'
ᑍᑍ OTHER ASSORTED VARIABLES  
DS  
I
I I  
I
I I  
ᑍ
2ððð  
B 1 4ðSIZ  
B 5 8ðSTART  
9 9 INTVAL  
X'ðð'  
C
Z-ADD16  
QUSBNB .1/  
ᑍ
Chapter 9. Common API Programming Errors 9-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ CREATE THE SPACE TO HOLD THE DATA  
C
C
C
C
C
C
C
C
C
CALL 'QUSCRTUS'  
PARM  
PARM 'EXT_ATTR'EXTATR 1ð  
PARM  
PARM  
PARM 'ᑍALL  
PARM 'NO TEXT 'TXTDSC 5ð  
PARM 'ᑍXXXXXXX'REPLAC 1ð  
PARM  
SPCNAM  
SIZ  
INTVAL  
'PUBAUT 1ð  
.2/  
QUSBN  
ᑍᑍ  
ᑍ DISPLAY EXCEPTION IDENTIFIER TO THE USER  
C
C
C
QUSBNC  
IFGT ᑍZEROS  
EXSR DSPERR  
END  
.4/  
ᑍ
ᑍ
C
SETON  
LR  
C
C
C
DSPERR BEGSR  
DSPLY  
ENDSR  
QUSBND  
9-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Defining Data Structures  
When a data structure is defined for use with an API, the structure must be built to  
receive what the API returns.  
The use of IBM-supplied data structures eliminates having to create your own data  
structures. For information on IBM-supplied data structures that are contained in  
library QSYSINC, see “APIs and the QSYSINC Library” on page 2-28.  
Defining a Data Structure—Example of Incorrect Coding  
When the program that defines a data structure is run, it does the following:  
Ÿ Creates a user space  
Ÿ Retrieves a list of active jobs  
Ÿ Displays the first part of a job name  
Ÿ Deletes the user space that held the data  
In this example, the data structure to be used with the QUSLJOB API has been  
defined incorrectly. The incorrectly defined variables are JNAME and USRNAM.  
The JNAME length is defined as 1 through 12 and the USRNAM length as 13  
through 20. This is shown at .5/ on page 9-5. The data displayed (JNAME vari-  
able) will be incorrect. The correct coding is shown at .6/ on page 9-7.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name: PGM1  
ᑍ
ᑍProgram Language: RPG  
ᑍ
ᑍDescription: This sample program illustrates the incorrect  
ᑍ
ᑍ
way of defining data structures.  
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
QUSGEN - User Space Format for Generic Header  
ᑍ
ᑍAPIs Used: QUSCRTUS - Create User Space  
ᑍ
ᑍ
ᑍ
QUSLJOB - List Job  
QUSRTVUS - Retrieve User Space  
QUSDLTUS - Delete User Space  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL  
ᑍ THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.  
ᑍ THE FIRST JOB NAME/USER WILL BE DISPLAYED TO THE USER.  
ᑍ
ᑍ BRING IN THE USER SPACE GENERIC HEADER  
I/COPY QSYSINC/QRPGSRC,QUSGEN  
ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC  
I/COPY QSYSINC/QRPGSRC,QUSEC  
ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB  
IJOBNAM  
I I  
DS  
'ᑍALL  
'
'
1 1ð JOB  
11 2ð USER  
21 26 JOBNUM  
I I  
'ᑍALL  
I I  
'ᑍALL '  
ᑍᑍ JOBLð1ðð FORMAT RETURNED FROM QUSLJOB API  
ᑍᑍ INCORRECTLY CODE THE JNAME/USRNAM LENGTHS  
IRECVR  
I
DS  
1 12 JNAME  
.5/  
Chapter 9. Common API Programming Errors 9-5  
Download from Www.Somanuals.com. All Manuals Search And Download.  
I
I
I
I
I
I
I
13 2ð USRNAM .5/  
21 26 JOBNBR  
27 42 JOBID  
43 52 JSTAT  
53 53 JTYPE  
54 54 JSUBT  
55 56 RESRV  
ᑍᑍ  
ISPCNAM  
I I  
I I  
ᑍᑍ OTHER ASSORTED VARIABLES  
I
I I  
I I  
I I  
I I  
ᑍ
DS  
'SPCNAME '  
'QTEMP  
1 1ð SPC  
11 2ð LIB  
'
DS  
2ððð  
B 1 4ðSIZ  
B 5 8ðSTART  
B 9 12ðLENDTA  
13 13INTVAL  
X'ðð'  
ᑍ SET UP TO ACCEPT EXCEPTIONS  
C
Z-ADDᑍZEROS  
QUSBNB  
ᑍ
ᑍ CREATE THE SPACE TO HOLD THE DATA  
C
C
C
C
C
C
C
C
C
CALL 'QUSCRTUS'  
PARM  
SPCNAM  
PARM 'EXT_ATTR'EXTATR 1ð  
PARM  
PARM  
SIZ  
INTVAL  
PARM 'ᑍALL  
'PUBAUT 1ð  
PARM 'TEXT DSC'TXTDSC 5ð  
PARM 'ᑍYES  
PARM  
'REPLAC 1ð  
QUSBN  
ᑍ
ᑍ CALL THE API TO LIST THE ACTIVE JOBS  
CALL 'QUSLJOB'  
C
C
C
C
C
C
PARM  
SPCNAM  
PARM 'JOBLð1ðð'FORMAT 8  
PARM  
JOBNAM  
PARM 'ᑍACTIVE 'STAT 1ð  
PARM QUSBN  
ᑍ
ᑍ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE  
C
C
C
C
C
C
C
C
Z-ADD1  
Z-ADD14ð  
CALL 'QUSRTVUS'  
PARM  
START  
LENDTA  
SPCNAM  
START  
LENDTA  
QUSBP  
QUSBN  
PARM  
PARM  
PARM  
PARM  
ᑍ
ᑍ RETRIEVE THE FIRST LIST ENTRY  
QUSBPQ ADD 1  
C
C
C
C
C
C
START  
Z-ADD56  
LENDTA  
CALL 'QUSRTVUS'  
PARM  
PARM  
PARM  
SPCNAM  
START  
LENDTA  
9-6 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
C
PARM  
PARM  
RECVR  
QUSBN  
ᑍ
ᑍ DISPLAY THE JOB NAME  
C
DSPLY  
JNAME >>> When displayed,JNAME  
will look something like  
ᑍ
ᑍ
'QCPF  
QS'  
ᑍ DELETE THE SPACE THAT HELD THE DATA  
CALL 'QUSDLTUS'  
C
C
C
PARM  
PARM  
SPCNAM  
QUSBN  
ᑍᑍ  
C
SETON  
LR  
Defining A Data Structure—Example of Correct Coding  
The following program uses a data structure that is supplied from the QSYSINC  
library. When you use this data structure, you can prevent errors in data structure  
creation from happening. If the data structures change from release to release,  
updates to programs do not have to be done. The application program would have  
to be updated only if a new field was added to the data structure and you wanted  
to use the field. The copying of the QSYSINC data structure is shown at .6/ on  
page 9-7.  
ᑍ
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name: PGM2  
ᑍ
ᑍProgram Language: RPG  
ᑍ
ᑍDescription: This sample program illustrates the correct  
ᑍ
ᑍ
way of defining data structures.  
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍ
ᑍ
QUSGEN - User Space Format for Generic Header  
QUSLJOB - List Job API  
ᑍAPIs Used: QUSCRTUS - Create User Space  
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
QUSLJOB - List Job  
QUSRTVUS - Retrieve User Space  
QUSDLTUS - Delete User Space  
ᑍ THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL  
ᑍ THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.  
ᑍ THE FIRST JOB NAME/USER WILL BE DISPLAYED TO THE USER.  
ᑍ
I/COPY QSYSINC/QRPGSRC,QUSGEN  
I/COPY QSYSINC/QRPGSRC,QUSEC  
I/COPY QSYSINC/QRPGSRC,QUSLJOB  
.6/  
ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB  
IJOBNAM  
I I  
DS  
'ᑍALL  
'ᑍALL  
'ᑍALL'  
'
'
1 1ð JOB  
I I  
11 2ð USER  
21 26 JOBNUM  
I I  
ᑍᑍ JOBLð1ðð FORMAT RETURNED FROM QUSLJOB API  
Chapter 9. Common API Programming Errors 9-7  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍᑍ  
ᑍᑍ  
ISPCNAM  
I I  
DS  
'SPCNAME '  
'QTEMP  
1 1ð SPC  
11 2ð LIB  
I I  
'
ᑍᑍ OTHER ASSORTED VARIABLES  
DS  
I
I I  
I I  
I I  
I I  
ᑍ
2ððð  
B 1 4ðSIZ  
B 5 8ðSTART  
B 9 12ðLENDTA  
13 13 INTVAL  
X'ðð'  
ᑍ SET UP TO ACCEPT EXCEPTIONS  
C
Z-ADDᑍZEROS  
QUSBNB  
ᑍ
ᑍ CREATE THE SPACE TO HOLD THE DATA  
C
C
C
C
C
C
C
C
C
CALL 'QUSCRTUS'  
PARM  
SPCNAM  
PARM 'EXT_ATTR'EXTATR 1ð  
PARM  
PARM  
SIZ  
INTVAL  
PARM 'ᑍALL  
'PUBAUT 1ð  
PARM 'TEXT DSC'TXTDSC 5ð  
PARM 'ᑍYES  
PARM  
'REPLAC 1ð  
QUSBN  
ᑍ
ᑍ CALL THE API TO LIST THE ACTIVE JOBS  
CALL 'QUSLJOB'  
C
C
C
C
C
C
PARM  
SPCNAM  
PARM 'JOBLð1ðð'FORMAT 8  
PARM  
JOBNAM  
PARM 'ᑍACTIVE 'STAT 1ð  
PARM QUSBN  
ᑍ
ᑍ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE  
C
C
C
C
C
C
C
C
Z-ADD1  
Z-ADD14ð  
CALL 'QUSRTVUS'  
PARM  
START  
LENDTA  
SPCNAM  
START  
LENDTA  
QUSBP  
QUSBN  
PARM  
PARM  
PARM  
PARM  
ᑍ
ᑍ RETRIEVE THE FIRST LIST ENTRY  
C
C
C
C
C
C
C
C
QUSBPQ  
ADD 1  
Z-ADD56  
CALL 'QUSRTVUS'  
PARM  
START  
LENDTA  
SPCNAM  
START  
LENDTA  
QUSDD  
QUSBN  
PARM  
PARM  
PARM  
PARM  
ᑍ
ᑍ DISPLAY THE JOB NAME  
DSPLY  
ᑍ
ᑍ
C
QUSDDB >>> Correct job name  
will now show as  
'QCPF  
'
9-8 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ DELETE THE SPACE THAT HELD THE DATA  
CALL 'QUSDLTUS'  
C
C
C
PARM  
PARM  
SPCNAM  
QUSBN  
ᑍᑍ  
C
SETON  
LR  
Chapter 9. Common API Programming Errors 9-9  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Defining Receiver Variables  
When defining receiver variables, the most common error is to create them too  
small for the amount of data that they are to receive. Both example programs are  
coded in RPG and, when run, lists all active jobs on the system.  
Defining Receiver Variables—Example of Incorrect Coding  
The following example program will fail because the receiver variable has been  
defined as 50 bytes (shown at .7/ on page 9-11), but 60 bytes are being requested  
to be passed back from the API (shown at .8/ in the incorrect and correct pro-  
grams on pages 9-11 and 9-13, respectively). The correct coding is shown at .9/  
on page 9-13.  
When this happens, other variables are overwritten with unintended data. This  
causes the other variables to be incorrect. For example, the first 10 characters of  
QUSBN may be written over with these extra characters. On the call to the next  
API, the error code parameter may appear to contain meaningless characters that  
would cause the next call to an API to fail.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name: PGM1  
ᑍ
ᑍProgram Language: RPG  
ᑍ
ᑍDescription: This sample program illustrates the incorrect  
ᑍ
ᑍ
way of defining receiver variables.  
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍ
ᑍ
QUSLJOB - List Job API  
QUSGEN - User Space Format for Generic Header  
ᑍAPIs Used: QUSCRTUS - Create User Space  
ᑍ
ᑍ
ᑍ
QUSLJOB - List Job  
QUSRTVUS - Retrieve User Space  
QUSDLTUS - Delete User Space  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL  
ᑍ THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.  
ᑍ BRING IN THE GENERIC USER SPACE HEADER FROM QSYSINC  
I/COPY QSYSINC/QRPGSRC,QUSGEN  
ᑍ
ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC  
I/COPY QSYSINC/QRPGSRC,QUSEC  
ᑍ
ᑍᑍ JOBLð1ðð FORMAT RETURNED FROM QUSLJOB API  
I/COPY QSYSINC/QRPGSRC,QUSLJOB  
ᑍ
ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB  
IJOBNAM  
I I  
I I  
I I  
ISPCNAM  
I I  
I I  
DS  
'ᑍALL  
'ᑍALL  
'ᑍALL'  
'
'
1 1ð JOB  
11 2ð USER  
21 26 JOBNUM  
DS  
'SPCNAME '  
'QTEMP  
1 1ð SPC  
'
11 2ð LIB  
9-10 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍᑍ OTHER ASSORTED VARIABLES  
DS  
I I  
I
I
2ððð  
B 1 4ðSIZ  
B 5 8ðSTART  
B 9 12ðLENDTA  
13 13 INTVAL  
I
I I  
ᑍ
X'ðð'  
ᑍ SET UP TO ACCEPT EXCEPTIONS  
C
Z-ADDᑍZEROS  
QUSBNB  
ᑍ
ᑍ CREATE THE SPACE TO HOLD THE DATA  
C
C
C
C
C
C
C
C
C
CALL 'QUSCRTUS'  
PARM  
SPCNAM  
PARM 'EXT_ATTR'EXTATR 1ð  
PARM  
PARM  
SIZ  
INTVAL  
PARM 'ᑍALL  
'PUBAUT 1ð  
PARM 'TEXT DSC'TXTDSC 5ð  
PARM 'ᑍYES  
PARM  
'REPLAC 1ð  
QUSBN  
ᑍ
ᑍ CALL THE API TO LIST THE ACTIVE JOBS  
CALL 'QUSLJOB'  
C
C
C
C
C
C
PARM  
SPCNAM  
PARM 'JOBLð1ðð'FORMAT 8  
PARM  
JOBNAM  
PARM 'ᑍACTIVE 'STAT 1ð  
PARM QUSBN  
ᑍ
ᑍ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE  
C
C
C
C
C
C
C
C
Z-ADD1  
Z-ADD14ð  
CALL 'QUSRTVUS'  
PARM  
START  
LENDTA  
SPCNAM  
START  
LENDTA  
QUSBP  
QUSBN  
PARM  
PARM  
PARM  
PARM  
ᑍ
ᑍ RETRIEVE THE LIST ENTRIES  
C
C
QUSBPQ  
ADD 1  
START  
LENDTA  
X
ᑍ
ᑍ
Z-ADD6ð  
.8/  
C
C
C
C
C
C
C
C
Z-ADD1  
DOWLEQUSBPS  
CALL 'QUSRTVUS'  
PARM  
9ð  
X
SPCNAM  
START  
LENDTA  
RECVR 5ð .7/  
QUSBN  
PARM  
PARM  
PARM  
PARM  
ᑍ
ᑍ
C
DSPLY  
QUSBN  
C
C
C
ADD QUSBPT  
ADD 1  
END  
START  
X
Chapter 9. Common API Programming Errors 9-11  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ DELETE THE SPACE THAT HELD THE DATA  
CALL 'QUSDLTUS'  
C
C
C
PARM  
PARM  
SPCNAM  
QUSBN  
ᑍ
C
SETON  
LR  
Defining Receiver Variables—Example of Correct Coding  
The following example program defines a larger receiver variable: 60 bytes. This  
is shown at position .9/ on page 9-13. This increase in the receiver variable allows  
up to 60 bytes of data to be received.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name: PGM2  
ᑍ
ᑍProgram Language: RPG  
ᑍ
ᑍDescription: This sample program illustrates the correct  
ᑍ
ᑍ
way of defining receiver variables.  
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍ
ᑍ
QUSLJOB - List Job API  
QUSGEN - User Space Format for Generic Header  
ᑍAPIs Used: QUSCRTUS - Create User Space  
ᑍ
ᑍ
ᑍ
QUSLJOB - List Job  
QUSRTVUS - Retrieve User Space  
QUSDLTUS - Delete User Space  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC  
I/COPY QSYSINC/QRPGSRC,QUSEC  
ᑍ BRING IN THE GENERIC USER SPACE HEADER FROM QSYSINC  
I/COPY QSYSINC/QRPGSRC,QUSGEN  
ᑍ
ᑍᑍ JOBLð1ðð FORMAT RETURNED FROM QUSLJOB API  
I/COPY QSYSINC/QRPGSRC,QUSLJOB  
ᑍ
ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB  
IJOBNAM  
I I  
DS  
'ᑍALL  
'ᑍALL  
'ᑍALL'  
'
'
1 1ð JOB  
11 2ð USER  
21 26 JOBNUM  
I I  
I I  
ISPCNAM  
I I  
DS  
'SPCNAME '  
'QTEMP  
1 1ð SPC  
11 2ð LIB  
I I  
'
ᑍᑍ OTHER ASSORTED VARIABLES  
DS  
I I  
I
I
2ððð  
B 1 4ðSIZ  
B 5 8ðSTART  
B 9 12ðLENDTA  
13 13 INTVAL  
I
I I  
ᑍ
X'ðð'  
ᑍ SET UP TO ACCEPT EXCEPTIONS  
C
Z-ADDᑍZEROS  
QUSBNB  
ᑍ
9-12 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ CREATE THE SPACE TO HOLD THE DATA  
C
C
C
C
C
C
C
C
C
CALL 'QUSCRTUS'  
PARM  
PARM 'EXT_ATTR'EXTATR 1ð  
PARM  
SPCNAM  
SIZ  
INTVAL  
PARM  
PARM 'ᑍALL  
'PUBAUT 1ð  
PARM 'TEXT DSC'TXTDSC 5ð  
PARM 'ᑍYES  
PARM  
'REPLAC 1ð  
QUSBN  
ᑍ
ᑍ CALL THE API TO LIST THE ACTIVE JOBS  
CALL 'QUSLJOB'  
C
C
C
C
C
C
PARM  
SPCNAM  
PARM 'JOBLð1ðð'FORMAT 8  
PARM  
JOBNAM  
PARM 'ᑍACTIVE 'STAT 1ð  
PARM QUSBN  
ᑍ
ᑍ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE  
C
C
C
C
C
C
C
C
Z-ADD1  
Z-ADD14ð  
CALL 'QUSRTVUS'  
PARM  
START  
LENDTA  
SPCNAM  
START  
LENDTA  
QUSBP  
QUSBN  
PARM  
PARM  
PARM  
PARM  
ᑍ
ᑍ RETRIEVE LIST ENTRIES  
C
QUSBPQ  
ADD 1  
START  
LENDTA  
X
ᑍ
C
ᑍ
C
C
C
C
C
C
C
C
Z-ADD6ð  
.8/  
Z-ADD1  
DOWLEQUSBPS  
CALL 'QUSRTVUS'  
PARM  
9ð  
X
SPCNAM  
START  
LENDTA  
RECVR 6ð .9/  
QUSBN  
PARM  
PARM  
PARM  
PARM  
ᑍ
C
C
C
C
MOVELRECVR  
ADD QUSBPT  
ADD 1  
QUSDD  
START  
X
END  
ᑍ DELETE THE SPACE THAT HELD THE DATA  
CALL 'QUSDLTUS'  
C
C
C
PARM  
PARM  
SPCNAM  
QUSBN  
ᑍ
ᑍ
C
SETON  
LR  
Chapter 9. Common API Programming Errors 9-13  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Defining List Entry Format Lengths  
The example programs in this topic show how to code flexibility into your program  
as it works its way through the formats used by an API.  
Defining List Entry Format Lengths—Example of Incorrect Coding  
A common error, or trap, when working with list entry format lengths is to hard code  
the format length into your program. The format length is used by the program to  
advance to the next list entry in the user space. From release to release, the  
length of the format may change. Therefore, when the format length changes, your  
program can be susceptible to being pointed to an incorrect position in the user  
space and nonsense data placed in the receiver variable.  
The program has the length of the list entry format hard coded. This is shown at  
.1ð/ on page 9-16. If your program runs on a Version 2 Release 2 system, that  
value would work. However, with Version 2 Release 3, the format size increased  
from 52 to 56 bytes. The correct coding is shown at .11/ on page 9-17.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name: PGM1  
ᑍ
ᑍProgram Language: RPG  
ᑍ
ᑍDescription: This sample program illustrates the incorrect  
ᑍ
ᑍ
way of using list entry length formats.  
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍ
ᑍ
QUSLJOB - List Job API  
QUSGEN - User Space Format for Generic Header  
ᑍAPIs Used: QUSCRTUS - Create User Space  
ᑍ
ᑍ
ᑍ
QUSLJOB - List Job  
QUSRTVUS - Retrieve User Space  
QUSDLTUS - Delete User Space  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL  
ᑍ THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.  
ᑍ THE FIRST JOB NAME/USER WILL BE DISPLAYED TO THE USER.  
I/COPY QSYSINC/QRPGSRC,QUSGEN  
I/COPY QSYSINC/QRPGSRC,QUSLJOB  
ᑍ
ᑍ BRING IN THE ERROR STRUCTURE FROM QSYSINC  
I/COPY QSYSINC/QRPGSRC,QUSEC  
ᑍ
ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB  
IJOBNAM  
I I  
I I  
I I  
DS  
'ᑍALL  
'ᑍALL  
'ᑍALL'  
'
'
1 1ð JOB  
11 2ð USER  
21 26 JOBNUM  
ᑍ FORMAT JOBLð1ðð FOR QUSLJOB API  
ᑍ
ᑍᑍ DATA STRUCTURE CONTAINING SPACE NAME/LIB  
ISPCNAM  
DS  
9-14 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
I I  
I I  
'SPCNAME '  
'QTEMP  
1 1ð SPC  
11 2ð LIB  
'
ᑍᑍ OTHER ASSORTED VARIABLES  
DS  
I I  
I
I
2ððð  
B 1 4ðSIZ  
B 5 8ðSTART  
B 9 12ðLENDTA  
13 13 INTVAL  
I
I I  
ᑍ
X'ðð'  
ᑍ SET UP TO ACCEPT EXCEPTIONS  
C
Z-ADDᑍZEROS  
QUSBNB  
ᑍ
ᑍ CREATE THE SPACE TO HOLD THE DATA  
C
C
C
C
C
C
C
C
C
CALL 'QUSCRTUS'  
PARM  
SPCNAM  
PARM 'EXT_ATTR'EXTATR 1ð  
PARM  
PARM  
SIZ  
INTVAL  
PARM 'ᑍALL  
'PUBAUT 1ð  
PARM 'TEXT DSC'TXTDSC 5ð  
PARM 'ᑍYES  
PARM  
'REPLAC 1ð  
QUSBN  
ᑍ
ᑍ CALL THE API TO LIST THE ACTIVE JOBS  
CALL 'QUSLJOB'  
C
C
C
C
C
C
PARM  
SPCNAM  
PARM 'JOBLð1ðð'FORMAT 8  
PARM  
JOBNAM  
PARM 'ᑍACTIVE 'STAT 1ð  
PARM QUSBN  
ᑍ
ᑍ RETRIEVE INFORMATION ABOUT THE USER SPACE AND ITS CONTENTS  
C
C
C
C
C
C
C
C
Z-ADD1  
Z-ADD14ð  
CALL 'QUSRTVUS'  
PARM  
START  
LENDTA  
SPCNAM  
START  
LENDTA  
QUSBP  
QUSBN  
PARM  
PARM  
PARM  
PARM  
ᑍ
ᑍ RETRIEVE LIST ENTRIES  
C
C
C
C
C
C
C
C
C
C
QUSBPQ  
ADD 1  
START  
LENDTA  
X
Z-ADD52  
Z-ADD1  
DOWLEQUSBPS  
CALL 'QUSRTVUS'  
PARM  
9ð  
X
SPCNAM  
START  
LENDTA  
QUSDD  
QUSBN  
PARM  
PARM  
PARM  
PARM  
ᑍ
ᑍ RETRIEVE THE NEXT LIST ENTRY (SPECIFYING LAST RELEASE'S  
ᑍ FORMAT LENGTH AS THE AMOUNT TO BUMP THE POINTER - THIS  
ᑍ WILL RESULT IN "GARBAGE" IN THE RECEIVER VARIABLE BECAUSE THE  
ᑍ FORMAT IS NOW 56 BYTES LONG)  
ᑍ
Chapter 9. Common API Programming Errors 9-15  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ DISPLAY THE INFORMATION RETURNED  
C
C
C
C
C
MOVELQUSDD  
RECVR 52  
RECVR  
START  
X
DSPLY  
ADD 52  
.1ð/  
ADD 1  
END  
ᑍ
ᑍ DELETE THE SPACE THAT HELD THE DATA  
CALL 'QUSDLTUS'  
C
C
C
PARM  
PARM  
SPCNAM  
QUSBN  
ᑍ
C
SETON  
LR  
Defining List Entry Format Lengths—Example of Correct Coding  
The following program correctly uses the list entry length that is defined in the  
space header for the QUSRTVUS API to advance from one entry to the next. This  
is shown at .11/ on page 9-17. If you use this value in your program, you will  
always have the correct list entry length regardless of the version or release level of  
the API.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name: PGM2  
ᑍ
ᑍProgram Language: RPG  
ᑍ
ᑍDescription: This sample program illustrates the correct  
ᑍ
ᑍ
way of using list entry length formats.  
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍ
ᑍ
QUSLJOB - List Job API  
QUSGEN - User Space Format for Generic Header  
ᑍAPIs Used: QUSCRTUS - Create User Space  
ᑍ
ᑍ
ᑍ
QUSLJOB - List Job  
QUSRTVUS - Retrieve User Space  
QUSDLTUS - Delete User Space  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL  
ᑍ THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.  
ᑍ
I/COPY QSYSINC/QRPGSRC,QUSGEN  
I/COPY QSYSINC/QRPGSRC,QUSLJOB  
I/COPY QSYSINC/QRPGSRC,QUSEC  
ᑍ
ᑍᑍ JOB NAME STRUCTURE FOR CALLING QUSLJOB  
IJOBNAM  
I I  
DS  
'ᑍALL  
'ᑍALL  
'ᑍALL'  
'
'
1 1ð JOB  
11 2ð USER  
21 26 JOBNUM  
I I  
I I  
ᑍ
ᑍᑍ DATA STRUCTURE TO HOLD SPACE NAME  
ISPCNAM  
I I  
I I  
DS  
'SPCNAME  
'QTEMP  
'
'
1 1ð SPC  
11 2ð LIB  
ᑍᑍ OTHER ASSORTED VARIABLES  
DS  
I I  
I
I
2ððð  
B
B
B
1
5
4ðSIZ  
8ðSTART  
I
9 12ðLENDTA  
13 13 INTVAL  
I I  
ᑍ
X'ðð'  
9-16 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ SET UP TO ACCEPT EXCEPTIONS  
C
Z-ADDᑍZEROS  
QUSBNB  
SPCNAM  
ᑍ
ᑍ CREATE THE SPACE TO HOLD THE DATA  
C
C
C
C
C
C
C
C
C
CALL 'QUSCRTUS'  
PARM  
PARM 'EXT_ATTR'EXTATR 1ð  
PARM  
PARM  
PARM 'ᑍALL  
PARM 'TEXT DSC'TXTDSC 5ð  
SIZ  
INTVAL  
'PUBAUT 1ð  
PARM 'ᑍYES  
PARM  
'REPLAC 1ð  
QUSBN  
ᑍ
ᑍ CALL THE API TO LIST THE ACTIVE JOBS  
CALL 'QUSLJOB'  
C
C
C
C
C
C
PARM  
SPCNAM  
PARM 'JOBLð1ðð'FORMAT 8  
PARM  
PARM 'ᑍACTIVE 'STAT  
PARM QUSBN  
JOBNAM  
1ð  
ᑍ
ᑍ RETRIEVE INFORMATION ABOUT THE USER SPACE AND ITS CONTENTS  
C
C
C
C
C
C
C
C
ᑍ
Z-ADD1  
Z-ADD14ð  
CALL 'QUSRTVUS'  
PARM  
START  
LENDTA  
SPCNAM  
START  
LENDTA  
QUSBP  
QUSBN  
PARM  
PARM  
PARM  
PARM  
ᑍ RETRIEVE THE FIRST LIST ENTRY BASED ON THE LIST ENTRY OFFSET  
ᑍ FOUND IN THE SPACE HEADER  
C
C
C
C
C
C
C
C
C
C
QUSBPQ  
ADD 1  
Z-ADD52  
Z-ADD1  
DOWLEQUSBPS  
CALL 'QUSRTVUS'  
PARM  
START  
LENDTA  
X
9ð  
X
SPCNAM  
START  
LENDTA  
QUSDD  
QUSBN  
PARM  
PARM  
PARM  
PARM  
ᑍ
ᑍ RETRIEVE THE NEXT LIST ENTRY (SPECIFYING LIST ENTRY LENGTH  
ᑍ RETRIEVED FROM THE SPACE HEADER)  
C
ADD QUSBPT  
START  
.11/  
ᑍ
ᑍ DISPLAY THE INFORMATION RETURNED  
C
C
C
C
MOVELQUSDD  
RECVR 52  
RECVR  
X
DSPLY  
ADD 1  
END  
ᑍ
ᑍ DELETE THE SPACE THAT HELD THE DATA  
CALL 'QUSDLTUS'  
C
C
C
PARM  
PARM  
SPCNAM  
QUSBN  
ᑍᑍ  
C
SETON  
LR  
Chapter 9. Common API Programming Errors 9-17  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Using Null Pointers with OPM APIs  
Many programmers, especially those with a C programming background, view  
ignored parameters and NULL parameters as being the same. This expectation  
can lead to unexpected results when OPM-based APIs are used.  
Note: Using NULL with ignored parameters is primarily a consideration with  
OPM-based APIs. ILE-based APIs allow you to pass NULL parameters to  
indicate omitted parameter values.  
Even though the value assigned to a parameter is not used, the parameter itself  
must be addressable. When you use NULL for a parameter value, the system con-  
ceptually passes an address that can be equated with 0, where 0 indicates that the  
parameter cannot be addressed. This lack of addressability often results in a func-  
tion check (MCH3601). Additionally, other error messages may also occur.  
Using Null Pointers with OPM APIs—Example of Incorrect Coding  
The following program has two parameter values coded as NULL. They are the  
ignored parameters of the member and record format used in the List Database  
Relations (QDBLDBR) API, which is shown at .12/ on page 9-19. The correct  
coding is shown at .13/ on page 9-21.  
When the program is called, a machine function check of MCH3601 is reported  
because the address of the required parameters member and record format are  
specified as NULL.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍProgram Name: PGM1  
/ᑍ  
/ᑍProgram Language: ILE C  
/ᑍ  
/ᑍDescription: This sample program illustrates the incorrect ᑍ/  
/ᑍ  
/ᑍ  
use of ignored and null parameters.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍHeader Files Included: <stdio.h>  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
<qusec.h>  
<qusgen.h>  
<qdbldbr.h>  
<quscrtus.h>  
<qusptrus.h>  
<qliept.h>  
/ᑍAPIs Used: QUSCRTUS - Create User Space  
/ᑍ  
/ᑍ  
QDBLDBR - List Database Relations  
QUSPTRUS - Retrieve Pointer to User Space  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <qusec.h>  
#include <qusgen.h>  
#include <qdbldbr.h>  
#include <quscrtus.h>  
#include <qusptrus.h>  
#include <qliept.h>  
main()  
{
9-18 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ initialize program data elements  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
char initial_value = ðxðð;  
char text_description[5ð] =  
"test of QDBLDBR API  
";  
char qualified_usrspc_name[2ð] = "GETLDBR QTEMP  
Qus_EC_t error_code;  
";  
Qus_Generic_Header_ð1ðð_t ᑍheader_ptr;  
error_code.Bytes_Provided = ð;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Create the user space to hold API results ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSCRTUS(qualified_usrspc_name, "SPACE  
", 1,  
&initial_value, "ᑍALL  
"ᑍYES  
", text_description,  
");  
", &error_code, "ᑍUSER  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Get list of file dependencies in current library  
/ᑍ  
/ᑍ Note that in this API call NULL pointers are being  
/ᑍ used for the "ignored" parameters Member and  
/ᑍ Record_Format. This convention is not valid as the  
/ᑍ parameters must address a valid storage address.  
/ᑍ The value  
/ᑍ assigned to a storage location is not important, the  
/ᑍ passing of a valid storage location is.  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ The next statement will cause a MCH36ð1  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QDBLDBR(qualified_usrspc_name, "DBRLð1ðð", "ᑍALL  
ᑍCURLIB ",  
NULL, NULL, &error_code); .12/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Get pointer to user space which contains dependencies ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSPTRUS(qualified_usrspc_name, &header_ptr, &error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ and display number of entries generated  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
printf("The number of entries returned is %d\n",  
header_ptr->Number_List_Entries);  
}
Using Null Pointers with OPM APIs—Example of Correct Coding  
The following program specifies that blanks be used as the values for both the  
member and record format parameters. This coding is shown at .13/ on page 9-21  
in the example program. By using blanks, the storage or address location of those  
parameters is identified and passed when needed.  
Chapter 9. Common API Programming Errors 9-19  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍProgram Name: PGM2  
/ᑍ  
/ᑍProgram Language: ILE C  
/ᑍ  
/ᑍDescription: This sample program illustrates the correct  
/ᑍ  
/ᑍ  
use of ignored and null parameters.  
/ᑍHeader Files Included: <stdio.h>  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
<qusec.h>  
<qusgen.h>  
<qdbldbr.h>  
<quscrtus.h>  
<qusptrus.h>  
<qliept.h>  
/ᑍAPIs Used: QUSCRTUS - Create User Space  
/ᑍ  
/ᑍ  
QDBLDBR - List Database Relations  
QUSPTRUS - Retrieve Pointer to User Space  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <qusec.h>  
#include <qusgen.h>  
#include <qdbldbr.h>  
#include <quscrtus.h>  
#include <qusptrus.h>  
#include <qliept.h>  
main()  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ initialize program data elements  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
char initial_value = ðxðð;  
char text_description[5ð] =  
"test of QDBLDBR API  
";  
char qualified_usrspc_name[2ð] = "GETLDBR QTEMP  
Qus_EC_t error_code;  
";  
Qus_Generic_Header_ð1ðð_t ᑍheader_ptr;  
error_code.Bytes_Provided = ð;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Create the user space to hold API results ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSCRTUS(qualified_usrspc_name, "SPACE  
", 1,  
&initial_value, "ᑍALL  
"ᑍYES  
", text_description,  
");  
", &error_code, "ᑍUSER  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Get list of file dependencies in current library  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍ Note that in this API call, blank characters are being ᑍ/  
/ᑍ used for the "ignored" parameters Member and  
/ᑍ Record_Format. While the value is ignored, a valid  
/ᑍ parameter storage location must still be passed  
ᑍ/  
ᑍ/  
ᑍ/  
9-20 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QDBLDBR(qualified_usrspc_name, "DBRLð1ðð", "ᑍALL  
" ", " ", &error_code); .13/  
ᑍCURLIB ",  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Get pointer to user space which contains dependencies ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSPTRUS(qualified_usrspc_name, &header_ptr, &error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ and display number of entries generated  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
printf("The number of entries returned is %d\n",  
header_ptr->Number_List_Entries);  
}
Chapter 9. Common API Programming Errors 9-21  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Defining Byte Alignment  
Correct byte alignment ensures that data used with an API is correct. Byte align-  
ment is also essential when APIs are used to retrieve and then print or display  
data. When byte alignment is off, it causes the API to read the data at some point  
other than at the beginning of a record.  
Defining Byte Alignment—Example of Incorrect Coding  
This program illustrates byte alignment while defining a structure. This is shown at  
.14/ on page 9-23. Four-byte alignment is required when using this program.  
Variable-length records must begin on a 4-byte boundary. As shown at .14/, the  
variable-length record CCSID_rec is not beginning on a 4-byte boundary. When  
the API accesses the CCSID_rec record, 4-byte alignment is forced by padding the  
first 3 bytes of the CCSID_rec between the replace field and the start of the  
CCSID_rec record. .15/ on page 9-24 shows that the variable-length record is  
not 4-byte aligned (the value is 13, which is not divisible by 4). The correct coding  
is shown at .17/ on page 9-26.  
Note: Not all APIs require a 4-byte boundary. ILE APIs, such as  
QusAddExitProgram, do.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ ᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍProgram Name: PGM1  
/ᑍ  
/ᑍProgram Language: ILE C  
/ᑍ  
/ᑍDescription:  
This program illustrates improper byte  
alignment when using variable length  
records.  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍHeader Files Included: <stdio.h>  
/ᑍ  
<signal.h>  
<string.h>  
<stdlib.h>  
<qusrgfa1.h>  
<qusec.h>  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
<qliept.h>  
/ᑍ  
/ᑍ APIs Used:  
/ᑍ  
QusAddExitProgram  
- Add an exit program  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Includes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <signal.h>  
#include <string.h>  
#include <stdlib.h>  
#include <qusrgfa1.h>  
#include <qusec.h>  
#include <qliept.h>  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Structures  
ᑍ/  
9-22 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
/ᑍ Error code  
ᑍ/  
Qus_EC_t ec_fields;  
char  
exception_data[1ðð];  
} error_code_struct;  
typedef struct {  
/ᑍ Exit program attribute keysᑍ/  
int  
num_rec;  
Qus_Vlen_Rec_4_t replace_rec;  
char  
replace;  
Qus_Vlen_Rec_4_t CCSID_rec;  
int CCSID;  
.14/  
Qus_Vlen_Rec_4_t desc_rec;  
char  
desc[5ð];  
} addep_attributes;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
main  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
int main()  
{
error_code_struct error_code;  
addep_attributes attrib_keys;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize the error code parameter.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the total number of exit program attributes that we are  
ᑍ/  
/ᑍ specifying on the call. We will let the API take the default ᑍ/  
/ᑍ for the attributes that we are not specifying. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
attrib_keys.num_rec=3;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the values for the three attributes that we will be  
/ᑍ specifying:  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
Replace exit program  
= 1  
(CHAR(1) field)  
(BIN(4) field)  
Exit program data CCSID = 37  
Exit program description='THIS IS A TEST EXIT PROGRAM' ᑍ/  
(CHAR(5ð) field)  
ᑍ/  
ᑍ/  
/ᑍ The structure for the exit program attributes defined above is ᑍ/  
/ᑍ as follows:  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
typedef struct {  
int  
Qus_Vlen_Rec_4_t replace_rec;  
char replace;  
Qus_Vlen_Rec_4_t CCSID_rec;  
int CCSID;  
num_rec;  
Qus_Vlen_Rec_4_t desc_rec;  
char  
desc[5ð];  
} addep_attributes;  
Chapter 9. Common API Programming Errors 9-23  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ and the Qus_Vlen_Rec_4_t structure is defined in  
/ᑍ qus.h (included by qusrgfa1) as:  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
typedef _Packed struct Qus_Vlen_Rec_4 {  
int Length_Vlen_Record;  
int Control_Key;  
int Length_Data;  
ᑍᑍchar Data[];-> this field is supplied by  
the user  
} Qus_Vlen_Rec_4_t;  
/ᑍ This structure is mapped in bytes as follows:  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
{
BIN(4) - num_rec  
BIN(4) - length variable length record for replace key ᑍ/  
BIN(4) - replace key  
BIN(4) - length replace data  
CHAR(1) - replace data  
ᑍ/  
ᑍ/  
ᑍ/  
BIN(4) - length variable length record for CCSID key ᑍ/  
BIN(4) - CCSID key  
BIN(4) - length CCSID data  
BIN(4) - CCSID data  
ᑍ/  
ᑍ/  
ᑍ/  
BIN(4) - length variable length record for description ᑍ/  
key  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
BIN(4) - description key  
BIN(4) - length description key  
CHAR(5ð) - description data  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
attrib_keys.replace_rec.Length_Vlen_Record=13;  
attrib_keys.replace_rec.Control_Key=4;  
attrib_keys.replace_rec.Length_Data=1;  
attrib_keys.replace='1';  
.15/  
attrib_keys.CCSID_rec.Length_Vlen_Record=16;  
attrib_keys.CCSID_rec.Control_Key=3;  
attrib_keys.CCSID_rec.Length_Data=4;  
attrib_keys.CCSID=37;  
attrib_keys.desc_rec.Length_Vlen_Record=39;  
attrib_keys.desc_rec.Control_Key=2;  
attrib_keys.desc_rec.Length_Data=27;  
memcpy(&attrib_keys.desc,  
"THIS IS A TEST EXIT PROGRAM",27);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the API to add the exit program.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QusAddExitProgram("EXAMPLE_EXIT_POINT ",  
"EXMPð1ðð",  
1,  
"EXAMPLEPGMEXAMPLELIB",  
"EXAMPLE EXIT PROGRAM DATA",  
25,  
&attrib_keys,  
&error_code);  
9-24 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
if (error_code.ec_fields.Bytes_Available != ð)  
{
printf("ATTEMPT TO ADD AN EXIT PROGRAM FAILED WITH EXCEPTION:%.7s",  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
} /ᑍ end program ᑍ/  
Defining Byte Alignment—Example of Correct Coding  
The following example program shows a CHAR(3) bytes reserved field being added  
to the structure to maintain 4-byte alignment (shown at .16/ on page 9-25). This  
corresponds to .14/ on page 9-23 in the incorrect coding example. The 3 reserved  
bytes are included in the length of the replace variable-length record. .17/ on  
page 9-26 shows the variable-length record is now 4-byte aligned (record length of  
16 is divisible by 4). This corresponds to .15/ on page 9-24 in the incorrect coding  
example.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍProgram Name: PGM2  
/ᑍ  
/ᑍProgram Language: ILE C  
/ᑍ  
/ᑍDescription:  
This program illustrates proper byte  
alignment when using variable length  
records.  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍHeader Files Included: <stdio.h>  
/ᑍ  
<signal.h>  
<string.h>  
<stdlib.h>  
<qusrgfa1.h>  
<qusec.h>  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
<qliept.h>  
/ᑍ  
/ᑍ APIs Used:  
QusAddExitProgram  
- Add an exit program  
/ᑍ  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Includes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <signal.h>  
#include <string.h>  
#include <stdlib.h>  
#include <qusrgfa1.h>  
#include <qusec.h>  
#include <qliept.h>  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Structures  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
/ᑍ Error code  
ᑍ/  
Qus_EC_t ec_fields;  
char  
exception_data[1ðð];  
} error_code_struct;  
typedef struct {  
/ᑍ Exit program attribute keysᑍ/  
int  
num_rec;  
Qus_Vlen_Rec_4_t replace_rec;  
char  
char  
replace;  
Reserved[3];  
.16/  
Chapter 9. Common API Programming Errors 9-25  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Qus_Vlen_Rec_4_t CCSID_rec;  
int CCSID;  
Qus_Vlen_Rec_4_t desc_rec;  
char  
desc[1ðð];  
} addep_attributes;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
main  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
int main()  
{
error_code_struct error_code;  
addep_attributes attrib_keys;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize the error code parameter.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the total number of exit program attributes that we are  
ᑍ/  
/ᑍ specifying on the call. We will let the API take the default ᑍ/  
/ᑍ for the attributes that we are not specifying. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
attrib_keys.num_rec=3;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the values for the three attributes that we will be  
/ᑍ specifying:  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
Replace exit program  
= 1  
(CHAR(1) field)  
(BIN(4) field)  
Exit program description='THIS IS A TEST EXIT PROGRAM'  
(CHAR(5ð) field)  
Exit program data CCSID = 37  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
attrib_keys.replace_rec.Length_Vlen_Record=16;  
attrib_keys.replace_rec.Control_Key=4;  
attrib_keys.replace_rec.Length_Data=1;  
attrib_keys.replace='1';  
.17/  
attrib_keys.CCSID_rec.Length_Vlen_Record=16;  
attrib_keys.CCSID_rec.Control_Key=3;  
attrib_keys.CCSID_rec.Length_Data=4;  
attrib_keys.CCSID=37;  
attrib_keys.desc_rec.Length_Vlen_Record=39;  
attrib_keys.desc_rec.Control_Key=2;  
attrib_keys.desc_rec.Length_Data=27;  
memcpy(&attrib_keys.desc,"THIS IS A TEST EXIT PROGRAM",27);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the API to add the exit program.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QusAddExitProgram("EXAMPLE_EXIT_POINT ",  
"EXMPð1ðð",  
1,  
"EXAMPLEPGMEXAMPLELIB",  
"EXAMPLE EXIT PROGRAM DATA",  
25,  
&attrib_keys,  
&error_code);  
if (error_code.ec_fields.Bytes_Available != ð)  
{
printf("ATTEMPT TO ADD AN EXIT PROGRAM FAILED WITH EXCEPTION: %.7s",  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
} /ᑍ end program ᑍ/  
9-26 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Using Offsets in a User Space  
An offset indicates where in a structure that specific information should start. When  
offsets are correctly used, programs can extract specific pieces of data from a  
structure and perform actions on that data.  
Incorrectly working with offsets can produce errors by API users when coding in a  
base 1 language such as RPG and COBOL. One way to determine the base of a  
language is how a programmer specifies the first element of an array. In a base 0  
language, the first element is number 0. In base 1 languages, the first element is  
number 1.  
The example programs in the following topics are coded using RPG. RPG is a  
base 1 language while the APIs produce information using a base of 0. To com-  
pensate for APIs producing information at base 0, the API user must add 1 to all  
decimal and hexadecimal offsets to formats that are contained in the System API  
Reference book.  
Using Offsets in a User Space—Example of Incorrect Coding  
The point for beginning to read a user space is shown at .18/ on page 9-30. The  
data is read and placed into a user space. However, the data in the user space is  
incorrect because the starting position to start was off by 1. This program started  
to retrieve the data one character (or position) too soon. The correct coding is  
shown at .19/ on page 9-34.  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍProgram Name: APIUG1  
Iᑍ  
IᑍProgramming Language: RPG  
Iᑍ  
IᑍDescription: This sample program illustrates the incorrect  
Iᑍ  
Iᑍ  
way of using the offset in a user space.  
IᑍHeader Files Included: QUSGEN - Generic Header of a User Space  
Iᑍ  
Iᑍ  
Iᑍ  
Iᑍ  
QUSEC - Error Code Parameter  
(Copied into Program)  
QUSLOBJ - List Objects API  
IᑍAPIs Used: QUSCRTUS - Create User Space  
Iᑍ  
Iᑍ  
Iᑍ  
QUSLOBJ - List Objects  
QUSRTVUS - Retrieve User Space  
QUSDLTUS - Delete User Space  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
Iᑍ Generic Header of a User Space Include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSGEN  
Iᑍ  
Iᑍ Error Code Parameter Include for the APIs  
Iᑍ  
Iᑍ The following QUSEC include is copied into this program  
Iᑍ so that the variable length field can be defined as a  
Iᑍ fixed length.  
Chapter 9. Common API Programming Errors 9-27  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ  
Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍHeader File Name: H/QUSEC  
Iᑍ  
IᑍDescriptive Name: Error Code Parameter.  
Iᑍ  
Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994  
IᑍAll rights reserved.  
IᑍUS Government Users Restricted Rights -  
IᑍUse, duplication or disclosure restricted  
Iᑍby GSA ADP Schedule Contract with IBM Corp.  
Iᑍ  
IᑍLicensed Materials-Property of IBM  
Iᑍ  
Iᑍ  
IᑍDescription: Include header file for the error code parameter.  
Iᑍ  
IᑍHeader Files Included: None.  
Iᑍ  
IᑍMacros List: None.  
Iᑍ  
IᑍStructure List: Qus_EC_t  
Iᑍ  
IᑍFunction Prototype List: None.  
Iᑍ  
IᑍChange Activity:  
Iᑍ  
IᑍCFD List:  
Iᑍ  
IᑍFLAG REASON  
LEVEL DATE PGMR  
CHANGE DESCRIPTION  
Iᑍ---- ------------ ----- ------ --------- ----------------------  
Iᑍ$Að= D2862ððð  
Iᑍ  
3D1ð 9312ð1 DPOHLSON: New Include  
IᑍEnd CFD List.  
Iᑍ  
IᑍAdditional notes about the Change Activity  
IᑍEnd Change Activity.  
Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IᑍRecord structure for Error Code Parameter  
Iᑍᑍᑍᑍ  
ᑍᑍᑍ  
IᑍNOTE: The following type definition only defines the corrected  
Iᑍ portion of the format. Varying length field Exception  
Iᑍ Data will not be defined here.  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IQUSBN  
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
DS  
Qus EC  
B 1 4ðQUSBNB  
Bytes Provided  
B 5 8ðQUSBNC  
Bytes Available  
9 15 QUSBND  
Exception Id  
16 16 QUSBNF  
Reserved  
17 17 QUSBNG  
Iᑍ  
Iᑍ  
Iᑍ  
9-28 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ  
Varying length  
17 1ðð QUSBNG  
I
Iᑍ  
Iᑍ List Objects API Include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSLOBJ  
Iᑍ  
Iᑍ Qualified User Space Data Structure  
Iᑍ  
IUSERSP  
I I  
DS  
'APIUG1  
'QGPL  
'
'
1 1ð USRSPC  
11 2ð SPCLIB  
I I  
iᑍ Qualified Object Name Data Structure  
IOBJECT  
I I  
I I  
Iᑍ  
DS  
'ᑍALL  
'QGPL  
'
'
1 1ð OBJNAM  
11 2ð OBJLIB  
Iᑍ Miscellaneous Data Structure  
Iᑍ  
I
DS  
Iᑍ Set up parameters for the Create User Space API  
I I  
I I  
I
I I  
I I  
I I  
I
'TESTUSRSPC'  
X'ðð'  
1 1ð EXTATR  
11 11 INTVAL  
12 12 RSVD1  
256  
'ᑍUSE  
B 13 16ðINTSIZ  
17 26 PUBAUT  
27 76 TEXT  
'
'TEXT DESCRIPTION -  
'FOR USER SPACE -  
'CALLED APIUG1 '  
I
I I  
'ᑍYES  
'
77 87 REPLAC  
Iᑍ Set up parameters for the List Objects API  
I I  
I I  
I
'OBJLð1ðð'  
'ᑍALL  
88 95 FORMAT  
96 1ð5 OBJTYP  
1ð6 1ð8 RSVD2  
'
Iᑍ Set up parameters for the Retrieve User Space API  
I I  
I I  
I
1
192  
B 1ð9 112ðSTRPOS  
B 113 116ðLENDTA  
B 117 12ððCOUNT  
Cᑍ  
Cᑍ Create a user space called APIUG1 in library QGPL.  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
Z-ADD1ðð  
CALL 'QUSCRTUS'  
PARM  
QUSBNB  
USERSP  
EXTATR  
INTSIZ  
INTVAL  
PUBAUT  
TEXT  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
REPLAC  
QUSBN  
PARM  
Cᑍ See if any errors were returned in the error code parameter.  
C
Cᑍ  
EXSR ERRCOD  
Cᑍ Get a list of all objects in the QGPL library.  
Cᑍ  
C
C
CALL 'QUSLOBJ'  
PARM  
USERSP  
Chapter 9. Common API Programming Errors 9-29  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
C
C
C
PARM  
PARM  
PARM  
PARM  
FORMAT  
OBJECT  
OBJTYP  
QUSBN  
Cᑍ See if any errors were returned in the error code parameter.  
C
Cᑍ  
EXSR ERRCOD  
Cᑍ Look at the generic header.  
Cᑍ The generic header contains information  
Cᑍ about the list data section that is needed when processing  
Cᑍ the entries.  
Cᑍ  
C
C
C
C
C
C
CALL 'QUSRTVUS'  
PARM  
PARM  
PARM  
PARM  
PARM  
USERSP  
STRPOS  
LENDTA  
QUSBP  
QUSBN  
Cᑍ See if any errors were returned in the error code parameter.  
C
Cᑍ  
EXSR ERRCOD  
Cᑍ Check the information status field, QUSBPJ, to see if  
Cᑍ the API was able to return all the information.  
Cᑍ Possible values are:  
Cᑍ C -- Complete and accurate  
Cᑍ P -- Partial but accurate  
Cᑍ I -- Incomplete  
Cᑍ  
C
QUSBPJ  
QUSBPJ  
IFEQ 'C'  
OREQ 'P'  
C
Cᑍ  
Cᑍ Check to see if any entries were put into the user space.  
Cᑍ  
C
C
C
C
QUSBPS  
IFGT ð  
Z-ADD1  
COUNT  
STRPOS .18/  
LENDTA  
Z-ADDQUSBPQ  
Z-ADD3ð  
Cᑍ Walk through all the entries in the user space.  
C
C
C
C
C
C
C
COUNT  
DOWLEQUSBPS  
CALL 'QUSRTVUS'  
PARM  
USERSP  
STRPOS  
LENDTA  
QUSDM  
PARM  
PARM  
PARM  
PARM  
QUSBN  
Cᑍ See if any errors were returned in the error code parameter.  
C
EXSR ERRCOD  
Cᑍ  
Cᑍ  
Cᑍ Process the objects.  
Cᑍ  
C
ADD 1  
COUNT  
STRPOS  
C
ADD QUSBPT  
ENDDO  
ENDIF  
C
C
Cᑍ  
Cᑍ Information in the user space is not accurate  
Cᑍ  
9-30 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
Cᑍ  
ENDIF  
Cᑍ Delete the user space called APIUG1 in library QGPL.  
Cᑍ  
C
C
C
CALL 'QUSDLTUS'  
PARM  
PARM  
USERSP  
QUSBN  
Cᑍ See if any errors were returned in the error code parameter.  
C
Cᑍ  
C
C
Cᑍ  
EXSR ERRCOD  
SETON  
RETRN  
LR  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ Subroutine to handle errors returned in the error code  
Cᑍ parameter.  
Cᑍ  
C
ERRCOD  
QUSBNC  
BEGSR  
IFGT ð  
C
Cᑍ  
Cᑍ Process errors returned from the API.  
Cᑍ  
C
C
END  
ENDSR  
Using Offsets in a User Space—Example of Correct Coding  
The following example program has code in it that compensates for the API offset  
convention of that starts at 0. The code adds 1 to the starting position (STRPOS)  
offset. This is shown at .19/ on page 9-34.  
Iᑍ  
IᑍProgram Name: APIUG2  
Iᑍ  
IᑍProgramming Language: RPG  
Iᑍ  
IᑍDescription: This sample program illustrates the correct  
Iᑍ  
Iᑍ  
way of using offsets in user space.  
IᑍHeader Files Included: QUSGEN - Generic Header of a User Space  
Iᑍ  
Iᑍ  
Iᑍ  
Iᑍ  
QUSEC - Error Code Parameter  
(Copied into Program)  
QUSLOBJ - List Objects API  
IᑍAPIs Used: QUSCRTUS - Create User Space  
Iᑍ  
Iᑍ  
Iᑍ  
QUSLOBJ - List Objects  
QUSRTVUS - Retrieve User Space  
QUSDLTUS - Delete User Space  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
Iᑍ Generic Header of a User Space Include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSGEN  
Iᑍ  
Iᑍ Error Code Parameter Include for the APIs  
Iᑍ  
Chapter 9. Common API Programming Errors 9-31  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ The following QUSEC include is copied into this program  
Iᑍ so that the variable length field can be defined as a  
Iᑍ fixed length.  
Iᑍ  
Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍHeader File Name: H/QUSEC  
Iᑍ  
IᑍDescriptive Name: Error Code Parameter.  
Iᑍ  
Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994  
IᑍAll rights reserved.  
IᑍUS Government Users Restricted Rights -  
IᑍUse, duplication or disclosure restricted  
Iᑍby GSA ADP Schedule Contract with IBM Corp.  
Iᑍ  
IᑍLicensed Materials-Property of IBM  
Iᑍ  
Iᑍ  
IᑍDescription: Include header file for the error code parameter.  
Iᑍ  
IᑍHeader Files Included: None.  
Iᑍ  
IᑍMacros List: None.  
Iᑍ  
IᑍStructure List: Qus_EC_t  
Iᑍ  
IᑍFunction Prototype List: None.  
Iᑍ  
IᑍChange Activity:  
Iᑍ  
IᑍCFD List:  
Iᑍ  
IᑍFLAG REASON  
LEVEL DATE PGMR  
CHANGE DESCRIPTION  
Iᑍ---- ------------ ----- ------ --------- ----------------------  
Iᑍ$Að= D2862ððð  
Iᑍ  
3D1ð 9312ð1 DPOHLSON: New Include  
IᑍEnd CFD List.  
Iᑍ  
IᑍAdditional notes about the Change Activity  
IᑍEnd Change Activity.  
Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IᑍRecord structure for Error Code Parameter  
Iᑍᑍᑍᑍ  
ᑍᑍᑍ  
IᑍNOTE: The following type definition only defines the corrected  
Iᑍ portion of the format. Varying length field Exception  
Iᑍ Data will not be defined here.  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IQUSBN  
Iᑍ  
I
DS  
Qus EC  
B 1 4ðQUSBNB  
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Bytes Provided  
B 5 8ðQUSBNC  
Bytes Available  
9 15 QUSBND  
Exception Id  
16 16 QUSBNF  
9-32 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ  
Reserved  
17 17 QUSBNG  
Iᑍ  
Iᑍ  
Iᑍ  
Varying length  
17 1ðð QUSBNG  
I
Iᑍ  
Iᑍ List Objects API Include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSLOBJ  
Iᑍ  
Iᑍ Qualified User Space Data Structure  
Iᑍ  
IUSERSP  
I I  
DS  
'APIUG1  
'QGPL  
'
'
1 1ð USRSPC  
11 2ð SPCLIB  
I I  
iᑍ Qualified Object Name Data Structure  
IOBJECT  
I I  
I I  
Iᑍ  
DS  
'ᑍALL  
'QGPL  
'
'
1 1ð OBJNAM  
11 2ð OBJLIB  
Iᑍ Miscellaneous Data Structure  
Iᑍ  
I
DS  
Iᑍ Set up parameters for the Create User Space API  
I I  
I I  
I
I I  
I I  
I I  
I
'TESTUSRSPC'  
X'ðð'  
1 1ð EXTATR  
11 11 INTVAL  
12 12 RSVD1  
256  
'ᑍUSE  
B 13 16ðINTSIZ  
17 26 PUBAUT  
27 76 TEXT  
'
'TEXT DESCRIPTION -  
'FOR USER SPACE -  
'CALLED APIUG2 '  
I
I I  
'ᑍYES  
'
77 87 REPLAC  
Iᑍ Set up parameters for the List Objects API  
I I  
I I  
I
'OBJLð1ðð'  
'ᑍALL  
88 95 FORMAT  
96 1ð5 OBJTYP  
1ð6 1ð8 RSVD2  
'
Iᑍ Set up parameters for the Retrieve User Space API  
I I  
I I  
I
1
192  
B 1ð9 112ðSTRPOS  
B 113 116ðLENDTA  
B 117 12ððCOUNT  
Cᑍ  
Cᑍ Create a user space called APIUG1 in library QGPL.  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
Z-ADD1ðð  
CALL 'QUSCRTUS'  
PARM  
QUSBNB  
USERSP  
EXTATR  
INTSIZ  
INTVAL  
PUBAUT  
TEXT  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
REPLAC  
QUSBN  
PARM  
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.  
Chapter 9. Common API Programming Errors 9-33  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
C
CALL 'QUSLOBJ'  
C
PARM  
PARM  
PARM  
PARM  
PARM  
USERSP  
FORMAT  
OBJECT  
OBJTYP  
QUSBN  
C
C
C
C
Cᑍ See if any errors were returned in the error code parameter.  
C
Cᑍ  
EXSR ERRCOD  
Cᑍ Look at the generic header. This contains information  
Cᑍ about the list data section that is needed when processing  
Cᑍ the entries.  
Cᑍ  
C
C
C
C
C
C
CALL 'QUSRTVUS'  
PARM  
PARM  
PARM  
PARM  
PARM  
USERSP  
STRPOS  
LENDTA  
QUSBP  
QUSBN  
Cᑍ See if any errors were returned in the error code parameter.  
C
EXSR ERRCOD  
Cᑍ  
Cᑍ  
Cᑍ Check the information status field, QUSBPJ, to see if the  
Cᑍ API was able to return all the information. Possible values  
Cᑍ are: C -- Complete and accurate  
Cᑍ  
Cᑍ  
Cᑍ  
C
P -- Partial but accurate  
I -- Incomplete.  
QUSBPJ  
QUSBPJ  
IFEQ 'C'  
OREQ 'P'  
C
Cᑍ  
Cᑍ Check to see if any entries were put into the user space.  
Cᑍ  
C
C
QUSBPS  
IFGT ð  
Z-ADD1  
COUNT  
Cᑍ Because RPG is Base 1, the offset must be increased by one.  
Cᑍ  
C
C
QUSBPQ  
ADD 1  
Z-ADD3ð  
STRPOS  
LENDTA  
.19/  
Cᑍ Walk through all the entries in the user space.  
C
C
C
C
C
C
C
COUNT  
DOWLEQUSBPS  
CALL 'QUSRTVUS'  
PARM  
USERSP  
STRPOS  
LENDTA  
QUSDM  
PARM  
PARM  
PARM  
PARM  
QUSBN  
Cᑍ See if any errors were returned in the error code parameter.  
C
EXSR ERRCOD  
Cᑍ  
Cᑍ  
Cᑍ Process the objects.  
Cᑍ  
C
C
C
ADD 1  
COUNT  
STRPOS  
ADD QUSBPT  
ENDDO  
9-34 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
Cᑍ  
ENDIF  
Cᑍ Information in the user space is not accurate.  
Cᑍ  
C
ENDIF  
Cᑍ  
Cᑍ  
Cᑍ Delete the user space called APIUG1 in library QGPL.  
Cᑍ  
C
C
C
CALL 'QUSDLTUS'  
PARM  
PARM  
USERSP  
QUSBN  
Cᑍ See if any errors were returned in the error code parameter.  
C
Cᑍ  
C
C
Cᑍ  
EXSR ERRCOD  
SETON  
RETRN  
LR  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ Subroutine to handle errors returned in the error code  
Cᑍ parameter.  
Cᑍ  
C
ERRCOD  
QUSBNC  
BEGSR  
IFGT ð  
C
Cᑍ  
Cᑍ Process errors returned from the API.  
Cᑍ  
C
C
END  
ENDSR  
Chapter 9. Common API Programming Errors 9-35  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Coding for New Function  
New function from IBM can cause programs to fail if the programs do not allow for  
the handling of a new function.  
The example programs in the following topics create a list of all objects that adopt  
authority and then process the objects based on their object type. The new func-  
tion added is the addition of another object type, *SRVPGM, that can adopt owner  
authority.  
A general theme of this example is never to assume that the values returned by an  
API are static. OS/400 is continually evolving. While the example is based on the  
addition of a new object type, this philosophy should be applied to any output of an  
API. For example, if an API today can return *YES or *NO, you should discretely  
check for these values because *MAYBE might be valid in the future. Similarly, if  
your application assumes a particular integer output has a positive nonzero value  
(an offset for instance), you should check for a positive nonzero value because  
future releases could return a negative value to indicate new function.  
Coding for New Function—Example of Incorrect Coding  
In this example program, a check is made to determine the object type. This is  
shown at .2ð/ on page 9-40. The example program considers only object types of  
*SQLPKG or *PGMs. This is because they are the only object types that could  
adopt owner authority before Version 2 Release 3. Since that time, a new object  
type of *SRVPGM has been introduced. *SRVPGM can adopt owner authority.  
Hence, this example program processes *SRVPGM objects as if they were *PGM  
objects. The correct coding is shown at .23/ on page 9-47.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
DᑍProgram Name: PGM1  
Dᑍ  
DᑍProgram Language: ILE RPG  
Dᑍ  
DᑍDescription: This example program demonstrates how a program can  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
be "broken" by new functions introduced on the AS/4ðð.  
DᑍHeader Files Included: QUSGEN - Generic Header of a User Space  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
(Copied Into Program)  
Error Code Parameter  
(Copied Into Program)  
QUSEC -  
QSYLOBJP - List Objects API  
(Copied Into Program)  
DᑍAPIs Used: QUSCRTUS - Create User Space  
Dᑍ  
Dᑍ  
Dᑍ  
QSYLOBJP - List Objects That Adopt Owner Authority  
QUSROBJD - Retrieve Object Description  
QUSPTRUS - Retrieve Pointer to User Space  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ This program demonstrates how a program can be "broken" by  
Cᑍ new functions introduced on the AS/4ðð.  
Dᑍ  
9-36 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
DSPC_NAME  
DSPC_SIZE  
DSPC_INIT  
DLSTPTR  
S
S
S
S
S
S
S
S
2ð  
INZ('ADOPTS  
INZ(X'ðð')  
QTEMP  
')  
9B ð INZ(1)  
1
ᑍ
ᑍ
DSPCPTR  
DARR  
DRCVVAR  
DRCVVARSIZ  
1
8
BASED(LSTPTR) DIM(32767)  
9B ð INZ(%SIZE(RCVVAR))  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ The following QUSGEN include is copied into this program so  
Dᑍ that it can be declared as BASED on SPCPTR (shown at .21/  
Dᑍ in the incorrect and correct programs on pages  
Dᑍ 9-37 and 9-45, respectively)  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
DᑍHeader File Name: H/QUSGEN  
Dᑍ  
DᑍDescriptive Name: Format structures for User Space for ILE/C  
Dᑍ  
Dᑍ5763-SS1 (C) Copyright IBM Corp. 1994, 1994  
DᑍAll rights reserved.  
DᑍUS Government Users Restricted Rights -  
DᑍUse, duplication or disclosure restricted  
Dᑍby GSA ADP Schedule Contract with IBM Corp.  
Dᑍ  
DᑍDescription: Contains the Generic Record format headers  
Dᑍ  
Dᑍ  
for the user space.  
DᑍHeader Files Included: none.  
Dᑍ  
DᑍMacros List: none.  
Dᑍ  
DᑍStructure List: Qus_Generic_Header_ð1ðð  
Dᑍ  
Dᑍ  
Qus_Generic_Header_ð3ðð  
DᑍFunction Prototype List: none.  
Dᑍ  
DᑍChange Activity:  
Dᑍ  
DᑍCFD List:  
Dᑍ  
DᑍFLAG REASON  
LEVEL DATE PGMR  
CHANGE DESCRIPTION  
Dᑍ---- ------------ ----- ------ --------- ----------------------  
Dᑍ$Að= D2862ððð  
DᑍEnd CFD List.  
Dᑍ  
DᑍAdditional notes about the Change Activity  
DᑍEnd Change Activity.  
3D1ð 94ð213 LUPA:  
New Include  
Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍType Definition for the User Space Generic Header.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSHð1ðð  
DS  
BASED(SPCPTR)  
.21/  
Chapter 9. Common API Programming Errors 9-37  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
D QUSUA  
Dᑍ  
D QUSSGH  
Dᑍ  
D QUSSRL  
Dᑍ  
D QUSFN  
Dᑍ  
D QUSAU  
Dᑍ  
D QUSDTC  
Dᑍ  
D QUSIS  
Dᑍ  
D QUSSUS  
Dᑍ  
D QUSOIP  
Dᑍ  
D QUSSIP  
Dᑍ  
D QUSOHS  
Dᑍ  
D QUSSHS  
Dᑍ  
D QUSOLD  
Dᑍ  
D QUSSLD  
Dᑍ  
D QUSNBRLE  
Dᑍ  
Qus Generic Header ð1ðð  
User Area  
1
65  
64  
68B ð  
72  
Size Generic Header  
Structure Release Level  
Format Name  
69  
73  
8ð  
81  
9ð  
API Used  
91  
1ð3  
Date Time Created  
Information Status  
Size User Space  
Offset Input Parameter  
Size Input Parameter  
Offset Header Section  
Size Header Section  
Offset List Data  
Size List Data  
1ð4  
1ð5  
1ð9  
113  
117  
121  
125  
129  
133  
137  
141  
145  
147  
15ð  
151  
1ð4  
1ð8B ð  
112B ð  
116B ð  
12ðB ð  
124B ð  
128B ð  
132B ð  
136B ð  
14ðB ð  
144B ð  
146  
Number List Entries  
Size Each Entry  
CCSID List Ent  
D QUSSEE  
Dᑍ  
D QUSSIDLE  
Dᑍ  
D QUSCID  
Dᑍ  
D QUSLID  
Dᑍ  
D QUSSLI  
Dᑍ  
D QUSERVEDðð  
Dᑍ  
Country ID  
149  
Language ID  
15ð  
Partial List Indicator  
192  
Reserved  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ The following QSYLOBJP include is copied into this program so  
Dᑍ that it can be declared as BASED on LSTPTR (shown at .22/  
Dᑍ in the incorrect and correct coding on  
Dᑍ pages 9-39 and 9-46, respectively)  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
DᑍHeader File Name: H/QSYLOBJP  
Dᑍ  
DᑍDescriptive Name: List Objects That Adopt Owner Authority.  
Dᑍ  
Dᑍ  
9-38 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DᑍDescription: Include header file for the QSYLOBJP API.  
Dᑍ  
DᑍHeader Files Included: H/QSYLOBJP  
Dᑍ  
Dᑍ  
H/QSY  
DᑍMacros List: None.  
Dᑍ  
DᑍStructure List: OBJPð1ðð  
Dᑍ  
Dᑍ  
Dᑍ  
OBJPð2ðð  
Qsy_OBJP_Header  
DᑍFunction Prototype List: QSYLOBJP  
Dᑍ  
DᑍChange Activity:  
Dᑍ  
DᑍCFD List:  
Dᑍ  
DᑍFLAG REASON  
LEVEL DATE PGMR  
CHANGE DESCRIPTION  
Dᑍ---- ------------ ----- ------ --------- ----------------------  
Dᑍ$Að= D2862ððð  
Dᑍ  
3D1ð 931222 XZYð432: New Include  
DᑍEnd CFD List.  
Dᑍ  
DᑍAdditional notes about the Change Activity  
DᑍEnd Change Activity.  
Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍPrototype for calling Security API QSYLOBJP  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
D QSYLOBJP  
C
'QSYLOBJP'  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍHeader structure for QSYLOBJP  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQSYOBJPH  
Dᑍ  
D QSYUNðð  
Dᑍ  
D QSYCVðð  
Dᑍ  
DS  
BASED(LSTPTR)  
.22/  
Qsy OBJP Header  
1
1ð  
User name  
3ð  
Continuation Value  
11  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍRecord structure for OBJPð1ðð format  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQSYð1ððLð2  
DS  
BASED(LSTPTR) .22/  
Qsy OBJPð1ðð List  
Dᑍ  
D QSYNAMEð5  
1
1ð  
2ð  
D QSYBRARYð5  
11  
Dᑍ  
Qualified object name  
D QSYOBJT12  
21  
31  
3ð  
Dᑍ  
Object type  
31  
Object in use  
D QSYOBJIU  
Dᑍ  
Cᑍ  
Cᑍ Start of mainline  
Cᑍ  
C
EXSR  
EXSR  
EXSR  
INIT  
PROCES  
DONE  
C
C
Cᑍ  
Chapter 9. Common API Programming Errors 9-39  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ Start of subroutines  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
PROCES  
BEGSR  
Cᑍ  
Cᑍ This subroutine processes each entry returned by QSYLOBJP  
Cᑍ  
Cᑍ  
Cᑍ Do until the list is complete  
Cᑍ  
C
MOVE  
QUSIS  
'C'  
LST_STATUS  
1
C
Cᑍ  
LST_STATUS  
DOUEQ  
Cᑍ If valid information was returned  
Cᑍ  
C
QUSIS  
QUSIS  
IFEQ  
OREQ  
'C'  
'P'  
C
Cᑍ  
Cᑍ and list entries were found  
Cᑍ  
C
QUSNBRLE  
IFGT  
ð
Cᑍ  
Cᑍ set LSTPTR to the first byte of the user space  
Cᑍ  
C
Cᑍ  
EVAL  
LSTPTR = SPCPTR  
Cᑍ increment LSTPTR to the first list entry  
Cᑍ  
C
Cᑍ  
EVAL  
LSTPTR = %ADDR(ARR(QUSOLD + 1))  
Cᑍ and process all of the entries  
Cᑍ  
C
DO  
IFEQ  
QUSNBRLE  
'ᑍSQLPKG'  
C
QSYOBJT12  
Cᑍ  
Cᑍ Process ᑍSQLPKG type  
Cᑍ  
C
ELSE  
.2ð/  
Cᑍ  
|
|
|
|
|
|
Cᑍ This 'ELSE' logic is the potential bug in this program. In  
Cᑍ releases prior to V2R3 only ᑍSQLPKGs and ᑍPGMs could adopt  
Cᑍ owner authority, and this program is assuming that if the  
Cᑍ object type is not ᑍSQLPKG then it must be a ᑍPGM. In V2R3  
Cᑍ a new type of object (the ᑍSRVPGM) was introduced. As this  
Cᑍ program is written, all ᑍSRVPGMs that adopt the owner profile |  
Cᑍ will be processed as if they were ᑍPGMs -- this erroneous  
|
|
|
|
↓
Cᑍ processing could definitely cause problems.  
Cᑍ  
C
QSYNAMEð5  
DSPLY  
END  
C
Cᑍ  
Cᑍ after each entry, increment LSTPTR to the next entry  
Cᑍ  
C
EVAL  
END  
LSTPTR = %ADDR(ARR(QUSSEE + 1))  
C
C
END  
Cᑍ  
Cᑍ When all entries in this user space have been processed, check  
9-40 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ if more entries exist than can fit in one user space  
Cᑍ  
C
Cᑍ  
QUSIS  
IFEQ  
'P'  
Cᑍ by resetting LSTPTR to the start of the user space  
Cᑍ  
C
Cᑍ  
EVAL  
LSTPTR = SPCPTR  
Cᑍ and then incrementing LSTPTR to the input parameter header  
Cᑍ  
C
EVAL  
LSTPTR = %ADDR(ARR(QUSOIP + 1))  
Cᑍ  
Cᑍ If the continuation handle in the input parameter header is  
Cᑍ blank, then set the list status to Complete  
Cᑍ  
C
QSYCVðð  
IFEQ  
MOVE  
ELSE  
ᑍBLANKS  
'C'  
C
LST_STATUS  
C
Cᑍ  
Cᑍ Else, call QSYLOBJP reusing the User Space to get more  
Cᑍ List entries  
Cᑍ  
C
MOVE  
EXSR  
MOVE  
END  
QSYCVðð  
GETLST  
QUSIS  
CONTIN_HDL  
LST_STATUS  
C
C
C
C
END  
C
ELSE  
Cᑍ  
Cᑍ And if an unexpected status, log an error (not shown) and exit  
Cᑍ  
C
C
C
C
EXSR  
END  
DONE  
END  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
GETLST  
BEGSR  
Cᑍ Call QSYLOBJP to generate a list  
Cᑍ The continuation handle is set by the caller of this subroutine.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
QSYLOBJP  
C
SPC_NAME  
MBR_LIST  
USR_PRF  
OBJ_TYPE  
CONTIN_HDL  
QUSEC  
C
'OBJPð1ðð'  
'ᑍCURRENT'  
'ᑍALL'  
8
1ð  
1ð  
2ð  
C
C
C
C
Cᑍ  
Cᑍ Check for errors on QSYLOBJP  
Cᑍ  
C
C
C
C
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
'QSYLOBJP'  
APIERR  
APINAM  
1ð  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
INIT  
BEGSR  
Chapter 9. Common API Programming Errors 9-41  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
Cᑍ One-time initialization code for this program  
Cᑍ  
Cᑍ Set error code structure to not use exceptions  
Cᑍ  
C
EVAL  
QUSBPRV = %SIZE(QUSEC)  
Cᑍ  
Cᑍ Check to see if the user space was previously created in  
Cᑍ QTEMP. If it was, simply reuse it.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'QUSROBJD'  
C
RCVVAR  
C
RCVVARSIZ  
ROBJD_FMT  
SPC_NAME  
OBJ_TYPE  
QUSEC  
C
'OBJDð1ðð'  
'ᑍUSRSPC'  
8
C
C
1ð  
C
Cᑍ  
Cᑍ Check for errors on QUSROBJD  
Cᑍ  
C
Cᑍ  
QUSBAVL  
IFGT  
ð
Cᑍ If CPF98ð1, then user space was not found  
Cᑍ  
C
Cᑍ  
QUSEI  
IFEQ  
'CPF98ð1'  
Cᑍ So create a user space for the list generated by QSYLOBJP  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'QUSCRTUS'  
SPC_NAME  
'QSYLOBJP ' EXT_ATTR  
SPC_SIZE  
1ð  
SPC_INIT  
SPC_AUT  
'ᑍALL'  
ᑍBLANKS  
'ᑍYES'  
1ð  
5ð  
1ð  
SPC_TEXT  
SPC_REPLAC  
QUSEC  
'ᑍUSER'  
SPC_DOMAIN  
1ð  
Cᑍ Check for errors on QUSCRTUS  
Cᑍ  
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
C
'QUSCRTUS'  
APIERR  
APINAM  
1ð  
C
C
Cᑍ  
Cᑍ Else, an error occurred accessing the user space  
Cᑍ  
C
ELSE  
MOVEL  
EXSR  
END  
C
'QUSROBJD'  
APIERR  
APINAM  
1ð  
C
C
C
END  
Cᑍ  
Cᑍ Set QSYLOBJP (using GETLST) to start a new list  
Cᑍ  
C
C
MOVE  
EXSR  
ᑍBLANKS  
GETLST  
CONTIN_HDL  
9-42 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
Cᑍ Get a resolved pointer to the user space for performance  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
'QUSPTRUS'  
C
SPC_NAME  
SPCPTR  
QUSEC  
C
C
Cᑍ  
Cᑍ Check for errors on QUSPTRUS  
Cᑍ  
C
C
C
C
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
'QUSPTRUS'  
APIERR  
APINAM  
1ð  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
APIERR  
BEGSR  
Cᑍ Log any error encountered, and exit the program  
Cᑍ  
C
C
C
APINAM  
DSPLY  
EXSR  
QUSEI  
DONE  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
DONE  
BEGSR  
Cᑍ Exit the program  
Cᑍ  
C
EVAL  
RETURN  
ENDSR  
ᑍINLR = '1'  
C
C
Coding for New Function—Example of Correct Coding  
In the following example program, code has been written that checks for object  
types *SRVPGM, *PGM, and *SQLPKG. If an object type is encountered that is  
unknown (it does not match *SRVPGM, *PGM, or *SQLPKG), an error is logged  
and an exit from the program takes place.  
The coding to handle the integration of new function (in this case the new object  
type that can adopt owner authority) is shown at .23/ on page 9-47.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
CᑍProgram Name: PGM2  
Cᑍ  
CᑍProgram Language: ILE RPG  
Cᑍ  
CᑍDescription: This example program demonstrates how a program can  
Cᑍ  
Cᑍ  
Cᑍ  
Cᑍ  
be coded to accept new functions introduced on the AS/4ðð.  
CᑍHeader Files Included: QUSGEN - Generic Header of a User Space  
Dᑍ  
Cᑍ  
Dᑍ  
Cᑍ  
(Copied Into Program)  
Error Code Parameter  
(Copied Into Program)  
QUSEC -  
QSYLOBJP - List Objects API  
Chapter 9. Common API Programming Errors 9-43  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
Cᑍ  
(Copied Into Program)  
CᑍAPIs Used: QUSCRTUS - Create User Space  
Cᑍ  
Cᑍ  
Cᑍ  
QSYLOBJP - List Objects That Adopt Owner Authority  
QUSROBJD - Retrieve Object Description  
QUSPTRUS - Retrieve Pointer to User Space  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
H
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
DSPC_NAME  
DSPC_SIZE  
DSPC_INIT  
DLSTPTR  
S
S
S
S
S
S
S
S
2ð  
INZ('ADOPTS  
INZ(X'ðð')  
QTEMP  
')  
9B ð INZ(1)  
1
ᑍ
ᑍ
DSPCPTR  
DARR  
DRCVVAR  
DRCVVARSIZ  
1
8
BASED(LSTPTR) DIM(32767)  
9B ð INZ(%SIZE(RCVVAR))  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ The following QUSGEN include is copied into this program so  
Dᑍ that it can be declared as BASED on SPCPTR (shown at .21/  
Dᑍ in the incorrect and correct programs on pages  
Dᑍ 9-37 and 9-45, respectively)  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
DᑍHeader File Name: H/QUSGEN  
Dᑍ  
DᑍDescriptive Name: Format structures for User Space for ILE/C  
Dᑍ  
Dᑍ  
Dᑍ5763-SS1 (C) Copyright IBM Corp. 1994, 1994  
DᑍAll rights reserved.  
DᑍUS Government Users Restricted Rights -  
DᑍUse, duplication or disclosure restricted  
Dᑍby GSA ADP Schedule Contract with IBM Corp.  
Dᑍ  
DᑍDescription: Contains the Generic Record format headers  
Dᑍ  
Dᑍ  
for the user space.  
DᑍHeader Files Included: none.  
Dᑍ  
DᑍMacros List: none.  
Dᑍ  
DᑍStructure List: Qus_Generic_Header_ð1ðð  
Dᑍ  
Dᑍ  
Qus_Generic_Header_ð3ðð  
DᑍFunction Prototype List: none.  
Dᑍ  
DᑍChange Activity:  
Dᑍ  
DᑍCFD List:  
Dᑍ  
9-44 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DᑍFLAG REASON  
LEVEL DATE PGMR  
CHANGE DESCRIPTION  
Dᑍ---- ------------ ----- ------ --------- ----------------------  
Dᑍ$Að= D2862ððð  
DᑍEnd CFD List.  
Dᑍ  
DᑍAdditional notes about the Change Activity  
DᑍEnd Change Activity.  
3D1ð 94ð213 LUPA:  
New Include  
Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍType Definition for the User Space Generic Header.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSHð1ðð  
Dᑍ  
D QUSUA  
Dᑍ  
D QUSSGH  
Dᑍ  
D QUSSRL  
Dᑍ  
D QUSFN  
Dᑍ  
D QUSAU  
Dᑍ  
D QUSDTC  
Dᑍ  
D QUSIS  
Dᑍ  
D QUSSUS  
Dᑍ  
D QUSOIP  
Dᑍ  
D QUSSIP  
Dᑍ  
D QUSOHS  
Dᑍ  
D QUSSHS  
Dᑍ  
D QUSOLD  
Dᑍ  
D QUSSLD  
Dᑍ  
D QUSNBRLE  
Dᑍ  
DS  
BASED(SPCPTR)  
.21/  
Qus Generic Header ð1ðð  
1
65  
64  
User Area  
68B ð  
72  
Size Generic Header  
Structure Release Level  
Format Name  
69  
73  
8ð  
81  
9ð  
API Used  
91  
1ð3  
Date Time Created  
Information Status  
Size User Space  
Offset Input Parameter  
Size Input Parameter  
Offset Header Section  
Size Header Section  
Offset List Data  
Size List Data  
1ð4  
1ð5  
1ð9  
113  
117  
121  
125  
129  
133  
137  
141  
145  
147  
15ð  
151  
1ð4  
1ð8B ð  
112B ð  
116B ð  
12ðB ð  
124B ð  
128B ð  
132B ð  
136B ð  
14ðB ð  
144B ð  
146  
Number List Entries  
Size Each Entry  
CCSID List Ent  
D QUSSEE  
Dᑍ  
D QUSSIDLE  
Dᑍ  
D QUSCID  
Dᑍ  
D QUSLID  
Dᑍ  
D QUSSLI  
Dᑍ  
D QUSERVEDðð  
Dᑍ  
Country ID  
149  
Language ID  
15ð  
Partial List Indicator  
192  
Reserved  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ The following QSYLOBJP include is copied into this program so  
Chapter 9. Common API Programming Errors 9-45  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ that it can be declared as BASED on LSTPTR (shown at .22/  
Dᑍ in the incorrect and correct coding on  
Dᑍ pages 9-39 and 9-46,  
Dᑍ respectively)  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
DᑍHeader File Name: H/QSYLOBJP  
Dᑍ  
DᑍDescriptive Name: List Objects That Adopt Owner Authority.  
Dᑍ  
Dᑍ  
DᑍDescription: Include header file for the QSYLOBJP API.  
Dᑍ  
DᑍHeader Files Included: H/QSYLOBJP  
Dᑍ  
Dᑍ  
H/QSY  
DᑍMacros List: None.  
Dᑍ  
DᑍStructure List: OBJPð1ðð  
Dᑍ  
Dᑍ  
Dᑍ  
OBJPð2ðð  
Qsy_OBJP_Header  
DᑍFunction Prototype List: QSYLOBJP  
Dᑍ  
DᑍChange Activity:  
Dᑍ  
DᑍCFD List:  
Dᑍ  
DᑍFLAG REASON  
LEVEL DATE PGMR  
CHANGE DESCRIPTION  
Dᑍ---- ------------ ----- ------ --------- ----------------------  
Dᑍ$Að= D2862ððð  
Dᑍ  
3D1ð 931222 XZYð432: New Include  
DᑍEnd CFD List.  
Dᑍ  
DᑍAdditional notes about the Change Activity  
DᑍEnd Change Activity.  
Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍPrototype for calling Security API QSYLOBJP  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
D QSYLOBJP  
C
'QSYLOBJP'  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍHeader structure for QSYLOBJP  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQSYOBJPH  
Dᑍ  
D QSYUNðð  
Dᑍ  
D QSYCVðð  
Dᑍ  
DS  
BASED(LSTPTR)  
.22/  
Qsy OBJP Header  
1
1ð  
User name  
3ð  
Continuation Value  
11  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍRecord structure for OBJPð1ðð format  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQSYð1ððLð2  
Dᑍ  
D QSYNAMEð5  
DS  
BASED(LSTPTR)  
.22/  
Qsy OBJPð1ðð List  
1
1ð  
9-46 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
D QSYBRARYð5  
11  
21  
31  
2ð  
Dᑍ  
Qualified object name  
D QSYOBJT12  
3ð  
Dᑍ  
Object type  
31  
D QSYOBJIU  
Dᑍ  
Cᑍ  
Object in use  
Cᑍ Start of mainline  
Cᑍ  
C
EXSR  
EXSR  
EXSR  
INIT  
PROCES  
DONE  
C
C
Cᑍ  
Cᑍ Start of subroutines  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
PROCES  
BEGSR  
Cᑍ This subroutine processes each entry returned by QSYLOBJP  
Cᑍ  
Cᑍ  
Cᑍ Do until the list is complete  
Cᑍ  
C
MOVE  
QUSIS  
LST_STATUS  
1
Cᑍ  
C
Cᑍ  
LST_STATUS  
DOUEQ  
'C'  
Cᑍ If valid information was returned  
Cᑍ  
C
QUSIS  
QUSIS  
IFEQ  
OREQ  
'C'  
'P'  
C
Cᑍ  
Cᑍ and list entries were found  
Cᑍ  
C
QUSNBRLE  
IFGT  
ð
Cᑍ  
Cᑍ set LSTPTR to the first byte of the user space  
Cᑍ  
C
Cᑍ  
EVAL  
LSTPTR = SPCPTR  
Cᑍ increment LSTPTR to the first list entry  
Cᑍ  
C
Cᑍ  
EVAL  
LSTPTR = %ADDR(ARR(QUSOLD + 1))  
Cᑍ and process all of the entries  
Cᑍ  
C
DO  
IFEQ  
QUSNBRLE  
'ᑍSQLPKG'  
C
QSYOBJT12  
Cᑍ  
Cᑍ Process ᑍSQLPKG type  
Cᑍ  
.23/  
|
|
|
|
|
|
|
|
C
ELSE  
C
Cᑍ  
QSYOBJT12  
IFEQ  
'ᑍPGM'  
Cᑍ Process ᑍPGM type  
Cᑍ  
C
C
QSYNAMEð5  
DSPLY  
ELSE  
Chapter 9. Common API Programming Errors 9-47  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
QSYOBJT12  
IFEQ  
'ᑍSRVPGM'  
|
|
|
|
|
↓
Cᑍ  
Cᑍ Process ᑍSRVPGM type  
Cᑍ  
C
Cᑍ  
Cᑍ  
ELSE  
Cᑍ Unknown type, log an error and exit from program (maybe..)  
Cᑍ  
C
EXSR  
END  
END  
END  
DONE  
C
C
C
Cᑍ  
Cᑍ after each entry, increment LSTPTR to the next entry  
Cᑍ  
C
EVAL  
END  
LSTPTR = %ADDR(ARR(QUSSEE + 1))  
C
C
END  
Cᑍ  
Cᑍ When all entries in this user space have been processed, check  
Cᑍ if more entries exist than can fit in one user space  
Cᑍ  
C
Cᑍ  
QUSIS  
IFEQ  
'P'  
Cᑍ by resetting LSTPTR to the start of the user space  
Cᑍ  
C
Cᑍ  
EVAL  
LSTPTR = SPCPTR  
Cᑍ and then incrementing LSTPTR to the input parameter header  
Cᑍ  
C
EVAL  
LSTPTR = %ADDR(ARR(QUSOIP + 1))  
Cᑍ  
Cᑍ If the continuation handle in the input parameter header is  
Cᑍ blank, then set the list status to complete.  
Cᑍ  
C
QSYCVðð  
IFEQ  
MOVE  
ELSE  
ᑍBLANKS  
'C'  
C
LST_STATUS  
C
Cᑍ  
Cᑍ Else, call QSYLOBJP reusing the user space to get more  
Cᑍ list entries  
Cᑍ  
C
MOVE  
EXSR  
MOVE  
END  
QSYCVðð  
GETLST  
QUSIS  
CONTIN_HDL  
LST_STATUS  
C
C
C
C
END  
C
ELSE  
Cᑍ  
Cᑍ And if an unexpected status, log an error (not shown) and exit  
Cᑍ  
C
C
C
C
EXSR  
END  
DONE  
END  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
GETLST  
BEGSR  
9-48 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
Cᑍ Call QSYLOBJP to generate a list  
Cᑍ The continuation handle is set by the caller of this subroutine.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
QSYLOBJP  
C
SPC_NAME  
MBR_LIST  
USR_PRF  
OBJ_TYPE  
CONTIN_HDL  
QUSEC  
C
'OBJPð1ðð'  
'ᑍCURRENT'  
'ᑍALL'  
8
1ð  
1ð  
2ð  
C
C
C
C
Cᑍ  
Cᑍ Check for errors on QSYLOBJP  
Cᑍ  
C
C
C
C
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
'QSYLOBJP'  
APIERR  
APINAM  
1ð  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
INIT  
BEGSR  
Cᑍ  
Cᑍ One time initialization code for this program  
Cᑍ  
Cᑍ Set error code structure to not use exceptions  
Cᑍ  
C
EVAL  
QUSBPRV = %SIZE(QUSEC)  
Cᑍ  
Cᑍ Check to see if the user space was previously created in  
Cᑍ QTEMP. If it was, simply reuse it.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'QUSROBJD'  
C
RCVVAR  
C
RCVVARSIZ  
ROBJD_FMT  
SPC_NAME  
OBJ_TYPE  
QUSEC  
C
'OBJDð1ðð'  
'ᑍUSRSPC'  
8
C
C
1ð  
C
Cᑍ  
Cᑍ Check for errors on QUSROBJD  
Cᑍ  
C
Cᑍ  
QUSBAVL  
IFGT  
ð
Cᑍ If CPF98ð1, then user space was not found  
Cᑍ  
C
Cᑍ  
QUSEI  
IFEQ  
'CPF98ð1'  
Cᑍ So create a user space for the list generated by QSYLOBJP  
Cᑍ  
C
C
C
C
C
C
C
C
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'QUSCRTUS'  
SPC_NAME  
'QSYLOBJP ' EXT_ATTR  
SPC_SIZE  
1ð  
SPC_INIT  
'ᑍALL'  
ᑍBLANKS  
'ᑍYES'  
SPC_AUT  
SPC_TEXT  
SPC_REPLAC  
QUSEC  
1ð  
5ð  
1ð  
Chapter 9. Common API Programming Errors 9-49  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
PARM  
'ᑍUSER'  
SPC_DOMAIN  
APINAM  
1ð  
1ð  
Cᑍ  
Cᑍ Check for errors on QUSCRTUS  
Cᑍ  
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
C
'QUSCRTUS'  
APIERR  
C
C
Cᑍ  
Cᑍ Else, an error occurred accessing the user space  
Cᑍ  
C
ELSE  
MOVEL  
EXSR  
END  
C
'QUSROBJD'  
APIERR  
APINAM  
1ð  
C
C
C
END  
Cᑍ  
Cᑍ Set QSYLOBJP (using GETLST) to start a new list  
Cᑍ  
C
MOVE  
EXSR  
ᑍBLANKS  
GETLST  
CONTIN_HDL  
C
Cᑍ  
Cᑍ Get a resolved pointer to the user space for performance  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
'QUSPTRUS'  
C
SPC_NAME  
SPCPTR  
QUSEC  
C
C
Cᑍ  
Cᑍ Check for errors on QUSPTRUS  
Cᑍ  
C
C
C
C
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
'QUSPTRUS'  
APIERR  
APINAM  
1ð  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
APIERR  
BEGSR  
Cᑍ Log any error encountered, and exit the program  
Cᑍ  
C
C
C
APINAM  
DSPLY  
EXSR  
QUSEI  
DONE  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
DONE  
BEGSR  
Cᑍ Exit the program  
Cᑍ  
C
EVAL  
RETURN  
ENDSR  
ᑍINLR = '1'  
C
C
9-50 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Appendix A. Performing Tasks Using APIs—Examples  
This appendix contains the following examples of using multiple APIs to perform  
tasks:  
Ÿ Packaging your own software products  
Ÿ Retrieving a file description to a user space  
Ÿ Using data queues versus user queues  
Packaging Your Own Software Products  
You can define, create, distribute, and maintain your own product using APIs. The  
following demonstrates how you can use the APIs to package a product similar to  
the way IBM packages products.  
The example product being packaged in this example is called ABC Product. The  
product is made up of one library, ABC, with no options off of this product. ABC  
Product consists of the following objects:  
Figure A-1. ABC Software Packaging  
Number  
Object Name  
Object Type  
Text Description  
1
2
3
4
5
6
7
8
ABCPGMMRM1  
ABCPGMMRM2  
ABCPGMMRI1  
ABCPGMMRI2  
ABCPGM  
QCLSRC  
ABCDSPF  
ABCPF  
*PGM  
*PGM  
*PGM  
*PGM  
MRM1 preprocessing program  
MRM postprocessing program  
MRI2 preprocessing program  
MRI postprocessing program  
CPP3 for ABC command  
Source physical file  
Display file  
*PGM  
*FILE(SRCPF)  
*FILE(DSPF)  
*FILE(PF)  
*MSGF  
Physical file  
Message file  
9
ABCMSG  
10  
11  
12  
13  
14  
15  
Note:  
ABC  
ABCPNLGRP  
ABC0050  
ABC0029  
ABC0050  
*CMD  
Command for ABC Product  
Panels for ABC  
Product definition  
Product load for MRI  
Product load for MRM  
ABC Product  
*PNLGRP  
*PRDDFN  
*PRDLOD  
*PRDLOD  
*LIB  
ABC  
1. Machine readable material  
2. Machine readable information  
3. Command processing program  
To package a product, first you create all of the objects (numbers 1 through 11 and  
number 15 in Figure A-1) that will comprise your product. (“CL Program for Cre-  
ating Objects and Library for Packaging a Product” on page A-2 shows the code  
that creates the objects.) After your objects are created, you do the steps listed in  
“Program for Packaging a Product—OPM RPG Example” on page A-3.  
Copyright IBM Corp. 1997  
A-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
The following figure is an overview of the steps required to create a product. An  
explanation is given of the numbers in Figure A-2. The same numbers also appear  
in the code.  
Product  
Definition  
Product  
Build  
Product  
Objects  
Application  
Product  
Load  
Packaged  
Product  
RV3W218-1  
Figure A-2. Steps for Creating a Software Product  
.1/ Create a product definition with information about the licensed program, such  
as ID, version, and release.  
.2/ Create a product load, which further defines each option of a licensed  
program, such as the libraries, folders, and exit programs that comprise the  
product.  
.3/ Identify all objects associated with the product by changing the product ID,  
release level, product option, and load ID in the object description by using  
the Change Object Description API.  
.4/ Package the product. Verify and store a list of all objects marked for this  
product in the product load object.  
.5/ Use the Save Licensed Program (SAVLICPGM) command to save the product  
to tape.  
CL Program for Creating Objects and Library for Packaging a  
Product  
The following CL program creates objects 1 through 11 and 15 in Figure A-1 on  
page A-1.  
PGM  
/ᑍ Delete library and start from scratch ᑍ/  
DLTLIB ABC  
/ᑍ MRM Objects ᑍ/  
CRTLIB ABC  
CRTCLPGM ABC/ABCPGMMRM1 ABCDEV/QCLSRC +  
TEXT('MRM Preprocessing Program')  
CRTCLPGM ABC/ABCPGMMRM2 ABCDEV/QCLSRC +  
TEXT('MRM Postprocessing Program')  
CRTCLPGM ABC/ABCPGM  
ABCDEV/QCLSRC +  
TEXT('CPP for ABC command')  
/ᑍ MRI Objects ᑍ/  
CRTCLPGM ABC/ABCPGMMRI1 ABCDEV/QCLSRC +  
TEXT('MRI Preprocessing Program')  
CRTCLPGM ABC/ABCPGMMRI2 ABCDEV/QCLSRC +  
TEXT('MRI Postprocessing Program')  
CRTSRCPF ABC/QCLSRC TEXT('Source Physical File for ABC Product')  
A-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
CRTDSPF ABC/ABCDSPF ABCDEV/QDDSSRC +  
TEXT('Display File for ABC Product')  
CRTPF ABC/ABCPF ABCDEV/QDDSSRC +  
TEXT('Physical File for ABC Product')  
CRTMSGF ABC/ABCMSG TEXT('Message File')  
ADDMSGD ABCððð1 ABC/ABCMSG MSG('ABC Product')  
CRTCMD ABC/ABC ABC/ABCPGM ABCDEV/QCMDSRC +  
TEXT('Command for ABC Product')  
CRTPNLGRP ABC/ABCPNLGRP ABCDEV/QPNLSRC +  
TEXT('Panel for ABC Command')  
/ᑍ The next program creates the product definitions, product loads, ᑍ/  
/ᑍ and gives all the objects associated with the product the correctᑍ/  
/ᑍ product information. It packages the product, which enables  
/ᑍ you to use the SAVLICPGM, RSTLICPGM, and DLTLICPGM commands.  
ᑍ/  
ᑍ/  
CRTRPGPGM ABCDEV/SFTWPRDEX ABCDEV/QRPGSRC  
/ᑍ .1/ .2/ .3/ .4/  
ᑍ/  
CALL ABCDEV/SFTWPRDEX  
ENDPGM  
Program for Packaging a Product—OPM RPG Example  
The following program creates objects 12 through 14 in Figure A-1 on page A-1.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FᑍProgram Name: SFTWPRDEX  
Fᑍ  
FᑍLanguage: OPM RPG  
Fᑍ  
FᑍDescriptive Name: Software Product Example  
Fᑍ  
FᑍDescription: This example contains the steps necessary to  
Fᑍ  
Fᑍ  
package your product like IBM products.  
FᑍHeader Files Included: QUSEC - Error Code Parameter  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
(Copied into Program)  
QSZCRTPD - Create Product Definition API  
QSZCRTPL - Create Product Load API  
QSZPKGPO - Package Product Option API  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
FQPRINT O F  
132  
OF  
PRINTER  
Eᑍ COMPILE TIME ARRAY  
E
OBJ ðð1 15 41  
Iᑍ  
Iᑍ Error Code Parameter Include for the APIs  
Iᑍ  
Iᑍ The following QUSEC include has been copied into this program  
Iᑍ so that the variable length field can be defined as a fixed  
Iᑍ length.  
Iᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
IᑍHeader File Name: H/QUSEC  
Iᑍ  
IᑍDescriptive Name: Error Code Parameter.  
Appendix A. Performing Tasks Using APIs—Examples A-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ  
Iᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994  
IᑍAll rights reserved.  
IᑍUS Government Users Restricted Rights -  
IᑍUse, duplication or disclosure restricted  
Iᑍby GSA ADP Schedule Contract with IBM Corp.  
Iᑍ  
IᑍLicensed Materials-Property of IBM  
Iᑍ  
Iᑍ  
IᑍDescription: Include header file for the error code parameter.  
Iᑍ  
IᑍHeader Files Included: None.  
Iᑍ  
IᑍMacros List: None.  
Iᑍ  
IᑍStructure List: Qus_EC_t  
Iᑍ  
IᑍFunction Prototype List: None.  
Iᑍ  
IᑍChange Activity:  
Iᑍ  
IᑍCFD List:  
Iᑍ  
IᑍFLAG REASON  
LEVEL DATE PGMR  
CHANGE DESCRIPTION  
Iᑍ---- ------------ ----- ------ --------- ----------------------  
Iᑍ$Að= D2862ððð  
Iᑍ  
3D1ð 9312ð1 DPOHLSON: New Include  
IᑍEnd CFD List.  
Iᑍ  
IᑍAdditional notes about the Change Activity  
IᑍEnd Change Activity.  
Iᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IᑍRecord structure for error code parameter  
Iᑍᑍᑍᑍ  
ᑍᑍᑍ  
IᑍNOTE: The following type definition only defines the fixed  
Iᑍ portion of the format. Varying length field exception  
Iᑍ data will not be defined here.  
Iᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
IQUSBN  
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
Iᑍ  
I
DS  
Qus EC  
B 1 4ðQUSBNB  
Bytes Provided  
B 5 8ðQUSBNC  
Bytes Available  
9 15 QUSBND  
Exception Id  
16 16 QUSBNF  
Iᑍ  
Iᑍ  
Iᑍ  
Iᑍ  
I
Reserved  
17 17 QUSBNG  
Varying length  
17 1ðð QUSBNG  
Iᑍ  
Iᑍ Create Product Definition API Include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QSZCRTPD  
A-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Iᑍ  
Iᑍ Create Product Load API Include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QSZCRTPL  
Iᑍ  
Iᑍ Package Product Option API Include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QSZPKGPO  
Iᑍ  
Iᑍ  
I
DS  
I I  
I I  
I I  
I I  
I I  
I I  
I I  
I I  
I I  
I I  
I I  
Iᑍ  
1
B 1 4ðNUMPOP  
B 5 8ðNUMLAN  
' 9 28 PDFN  
1
'ABCðð5ð ABC  
'ABC Product'  
'5ð72535ð1ð  
'ᑍNODYNNAM '  
29 78 TEXTD  
79 92 PHONE  
93 1ð2 ALWDYN  
1ð3 112 PUBAUT  
113 122 POSTM  
123 132 PREM  
133 142 POSTI  
143 152 PREI  
'
'ᑍUSE  
'
'ABCPGMMRM2'  
'ABCPGMMRM1'  
'ABCPGMMRI2'  
'ABCPGMMRI1'  
Iᑍ Change Object Information Parameter  
ICOBJI  
I I  
I I  
I I  
I
DS  
49  
3
13  
4
B 1 4ðNUMKEY  
B 5 8ðKEY13  
B 9 12ðLEN13  
13 16 PID13  
I I  
I I  
I
I I  
I I  
I
12  
4
B 17 2ððKEY12  
B 21 24ðLEN12  
25 28 LID12  
B 29 32ðKEY5  
B 33 36ðLEN5  
37 49 LP5  
5
13  
Iᑍ  
Iᑍ Object Data Structure - Breakdown of fields in Array OBJ  
IOBJDS  
DS  
I
1 1ð NAME  
11 2ð TYP  
21 24 PID  
25 28 LID  
29 41 LP  
I
I
I
I
I
DS  
I
B 1 4ðRCVLEN  
B 5 8ðNUMBK  
B 9 12ðNUMBL  
B 13 16ðNUMBM  
I I  
I I  
I I  
Cᑍ  
ð
1
ð
Cᑍ Beginning of Mainline  
Cᑍ  
Cᑍ Create Product Definition Object - ABCðð5ð  
Cᑍ  
C
Cᑍ  
EXSR PRDDFN  
.1/  
Cᑍ Create Product Load Objects - ABCðð5ð (MRM) and ABCðð29 (MRI)  
Cᑍ  
C
EXSR PRDLOD  
.2/  
Appendix A. Performing Tasks Using APIs—Examples A-5  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
Cᑍ Change Object Description for all objects associated with  
Cᑍ the ABC Product.  
Cᑍ  
C
EXSR COBJD  
.3/  
Cᑍ  
Cᑍ Package the ABC Product so that all the SAVLICPGM, RSTLIBPGM,  
Cᑍ and DLTLICPGM commands work with the product.  
Cᑍ  
C
Cᑍ  
EXSR PKGPO  
.4/  
Cᑍ Complete; product is ready to ship.  
Cᑍ  
C
SETON  
RETRN  
LR  
C
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
Cᑍ Subroutine: PRDDFN  
Cᑍ  
Cᑍ Descriptive Name: Create product definitions.  
Cᑍ  
Cᑍ Description: This subroutine creates the product definition  
Cᑍ  
Cᑍ  
ABCðð5ð for the ABC Product.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
PRDDFN  
BEGSR  
Cᑍ Setup for Product Definition  
Cᑍ Fill Product Definition Information Parameter  
C
C
C
C
C
C
C
C
C
C
Z-ADD1ðð  
QUSBNB  
MOVEL'ðABCABC' QSZBCB  
MOVEL'V3R1Mð' QSZBCC  
MOVEL'ABCMSG' QSZBCD  
MOVEL'ᑍCURRENT'QSZBCF  
MOVEL'ᑍCURRENT'QSZBCG  
MOVEL'9412ð1' QSZBCH  
Product ID  
Release Level  
Message File  
First Copyright  
Current Copyright  
Release Date  
MOVEL'ᑍNO'  
QSZBCJ  
Allow multiple rel.  
Registration ID Value  
Registration ID Value  
MOVEL'ᑍPHONE' QSZBCK  
MOVELPHONE  
QSZBCL  
Cᑍ Fill Product Load Parameter  
C
C
C
C
C
MOVEL'ðððð'  
MOVEL'ABCððð1' QSZBDC  
MOVELALWDYN  
MOVEL'5ðð1'  
MOVELᑍBLANKS QSZBDG  
QSZBDB  
Product Option Number  
Message ID  
Allow Dynamic Naming  
Code Load ID  
Reserved  
QSZBDD  
QSZBDF  
Cᑍ Fill Language Load List Parameter  
C
MOVEL'2924  
MOVEL'ðððð'  
MOVELᑍBLANKS QSZBFD  
'QSZBFB  
QSZBFC  
Language Load ID  
Product Option Number  
Reserved  
C
C
Cᑍ  
Cᑍ Create the Product Definition for the ABC Product  
Cᑍ  
A-6 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
C
C
C
C
C
C
C
C
C
C
MOVEL'QSZCRTPD'API  
CALL 'QSZCRTPD'  
1ð  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PDFN  
Qual. Prod. Defn.  
Prod. Defn. Info.  
Prod. Option List  
# Prod. Options  
Lang. Load List  
# Lang. Load List  
Text Description  
Public Authority  
Error Code  
QSZBC  
QSZBD  
NUMPOP  
QSZBF  
NUMLAN  
TEXTD  
PUBAUT  
QUSBN  
Cᑍ Check for errors returned in the error code parameter.  
C
C
EXSR ERRCOD  
ENDSR  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
Cᑍ Subroutine: PRDLOD  
Cᑍ  
Cᑍ Descriptive Name: Create product loads.  
Cᑍ  
Cᑍ Description: This subroutine creates the product loads,  
Cᑍ  
Cᑍ  
ABCðð5ð and ABCðð29, for the ABC Product.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
PRDLOD  
BEGSR  
Cᑍ Setup for Product Load for MRM Objects  
Cᑍ Fill Product Load Information Parameter  
C
C
C
C
C
C
C
C
C
Cᑍ  
MOVEL'ðABCABC' QSZBHB  
MOVEL'V3R1Mð' QSZBHC  
Product ID  
Release Level  
MOVEL'ðððð'  
QSZBHD  
Product Option  
Product Load Type  
Load ID  
Registration ID Type  
Registration ID Value  
Min. Target Release  
Reserved  
MOVEL'ᑍCODE' QSZBHF  
MOVEL'ᑍCODEDFT'QSZBHG  
MOVEL'ᑍPRDDFN' QSZBHH  
MOVELᑍBLANKS QSZBHJ  
MOVEL'ᑍCURRENT'QSZBCK  
MOVELᑍBLANKS QSZBCL  
Cᑍ Fill Principal Library Information Parameter  
C
MOVEL'ABC'  
MOVEL'ABC'  
MOVELPOSTM  
QSZBJB  
QSZBJC  
QSZBJD  
Prin. Dev. Lib. Name  
Prin. Prim. Lib. Name  
Post-Exit Prog. Name  
C
C
Cᑍ  
Cᑍ Fill Preoperation Exit Programs Parameter  
C
C
MOVELPREM  
MOVEL'ABC'  
QSZBLB  
QSZBLC  
Pre-Exit Prog. Name  
Dev. Lib. Name  
Cᑍ  
Cᑍ Fill Additional Library List Parameter  
Cᑍ  
Cᑍ  
None  
Cᑍ Fill Folder List Parameter  
Cᑍ  
Cᑍ  
None  
Cᑍ Create the product load for the ABC Product - MRM Objects  
Appendix A. Performing Tasks Using APIs—Examples A-7  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
MOVEL'QSZCRTPL'API  
CALL 'QSZCRTPL'  
PARM 'ABCðð5ð' PRDIDN 1ð  
Prod. ID Name  
PARM  
QSZBH  
Prod. Defn. Info.  
Sec. Lang. Lib  
Principal Lib Info  
Add. Library List  
# Add. Lib. List  
Pre-Exit Programs  
# Pre-Exit Programs  
Folder List  
PARM ᑍBLANKS SECLIB 1ð  
PARM  
PARM  
PARM ð  
PARM  
PARM 1  
PARM  
PARM ð  
PARM  
PARM 'ᑍUSE'  
PARM  
QSZBJ  
QSZBK  
NUMBK  
QSZBL  
NUMBL  
QSZBM  
NUMBM  
TEXTD  
PUBAUT  
QUSBN  
# Folder List  
Text Description  
Public Authority  
Error Code  
Cᑍ Check for errors returned in the error code parameter.  
C
Cᑍ  
EXSR ERRCOD  
Cᑍ Setup for Product Load for MRI Objects  
Cᑍ Fill Product Load Information Parameter  
C
MOVEL'ᑍLNG ' QSZBHF  
MOVEL'2924 'QSZBHG  
Product Load Type  
Load ID  
C
Cᑍ  
Cᑍ Fill Principal Library Information Parameter  
C
Cᑍ  
MOVELPOSTI  
QSZBJD  
Post-Exit Prog. Name  
Pre-Exit Prog. Name  
Cᑍ Fill Preoperation Exit Programs Parameter  
C
Cᑍ  
MOVELPREI  
QSZBLB  
Cᑍ Fill Additional Library List Parameter  
Cᑍ  
Cᑍ  
None  
Cᑍ Fill Folder List Parameter  
Cᑍ  
Cᑍ  
None  
Cᑍ Create the product load for the ABC Product - MRI Objects  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
MOVEL'QSZCRTPL'API  
CALL 'QSZCRTPL'  
PARM 'ABCðð29' PRDIDN 1ð  
Prod. ID Name  
PARM  
QSZBH  
Prod. Defn. Info.  
Sec. Lang. Lib  
Principal Lib Info  
Add. Library List  
# Add. Lib. List  
Pre-Exit Programs  
# Pre-Exit Programs  
Folder List  
PARM 'ABC2924 'SECLIB  
PARM  
PARM  
PARM ð  
PARM  
PARM 1  
PARM  
PARM ð  
PARM  
PARM 'ᑍUSE'  
PARM  
QSZBJ  
QSZBK  
NUMBK  
QSZBL  
NUMBL  
QSZBM  
NUMBM  
TEXTD  
PUBAUT  
QUSBN  
# Folder List  
Text Description  
Public Authority  
Error Code  
Cᑍ Check for errors returned in the error code parameter.  
C
C
EXSR ERRCOD  
ENDSR  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
A-8 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
Cᑍ Subroutine: COBJD  
Cᑍ  
Cᑍ Descriptive Name: Change object descriptions for the  
Cᑍ ABC Product.  
Cᑍ  
Cᑍ Description: This subroutine changes the object  
Cᑍ  
Cᑍ  
Cᑍ  
Cᑍ  
descriptions for all objects that make up the  
ABC Product. Currently, 15 objects exist. They  
are listed at the end of this program.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
COBJD  
BEGSR  
Cᑍ Need to associate all objects with the ABC Product  
C
C
C
C
C
C
C
C
C
C
C
C
C
C
1
DO 15  
I
3ð  
MOVE OBJ,I  
CAT 'ABC'  
MOVELLP  
OBJDS  
NAME  
QOBJNM 2ð  
LP5  
PID13  
LID12  
TYPE 1ð  
MOVELPID  
MOVELLID  
MOVELTYP  
MOVEL'QLICOBJD'API  
CALL 'QLICOBJD'  
PARM  
PARM  
PARM  
PARM  
PARM  
RTNLIB 1ð  
QOBJNM  
TYPE  
COBJI  
QUSBN  
Returned Lib. Name  
Qual. Object Name  
Object Type  
Chg'd Object Info.  
Error Code  
Cᑍ Check for any errors returned in the error code parameter.  
C
EXSR ERRCOD  
ENDDO  
ENDSR  
C
C
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
Cᑍ Subroutine: PKGPO  
Cᑍ  
Cᑍ Descriptive Name: Package software ABC Product.  
Cᑍ  
Cᑍ Description: This subroutine packages the ABC Product.  
Cᑍ  
Cᑍ  
Cᑍ  
It makes sure that all objects exist that are  
associated with the product.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
PKGPO  
BEGSR  
Cᑍ Setup for packing the ABC Product.  
Cᑍ Fill Product Option Information Parameter  
C
C
C
MOVEL'ðððð'  
QSZBRB  
Product Option  
Product ID  
Release Level  
MOVEL'ðABCABC' QSZBRC  
MOVEL'V3R1Mð' QSZBRD  
Appendix A. Performing Tasks Using APIs—Examples A-9  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
MOVEL'ᑍALL  
'QSZBRF  
Load ID  
Reserved  
C
MOVELᑍBLANKS QSZBRG  
Cᑍ  
Cᑍ Package the ABC Product.  
Cᑍ  
Cᑍ  
C
C
C
C
C
C
MOVEL'QSZPKGPO'API  
CALL 'QSZPKGPO'  
PARM  
QSZBR  
Prod. Option Info.  
Repackage  
Allow Object Change  
Error Code  
PARM 'ᑍYES'  
REPKG 4  
PARM 'ᑍNO ' ALWCHG 5  
PARM  
QUSBN  
Cᑍ Check for any errors returned in the error code parameter.  
C
EXSR ERRCOD  
ENDSR  
C
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
Cᑍ Subroutine: ERRCOD  
Cᑍ  
Cᑍ Descriptive Name: Process API errors.  
Cᑍ  
Cᑍ Description: This subroutine prints a line to a spooled  
Cᑍ  
Cᑍ  
Cᑍ  
file if any errors are returned in the error code  
parameter.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
ERRCOD  
QUSBNC  
BEGSR  
IFNE ð  
C
Cᑍ  
Cᑍ Process errors returned from the API.  
Cᑍ  
C
EXCPTBADNWS  
END  
C
C
ENDSR  
OQPRINT E 1ð6  
BADNWS  
O
O
O
O
'Failed in API '  
'with error '  
API  
QUSBND  
Oᑍ The information below is for array OBJ.  
Oᑍ111 represents the object name.  
Oᑍ2222222222 represents the object type.  
Oᑍ3333 represents the product option ID.  
Oᑍ4444 represents the product option load ID.  
Oᑍ5555555555555 represents the licensed program.  
Oᑍ1112222222222333344445555555555555  
ᑍᑍ  
ABCPGMMRM1ᑍPGM  
ABCPGMMRM2ᑍPGM  
ABCPGMMRI1ᑍPGM  
ABCPGMMRI2ᑍPGM  
ðððð5ðð1ðABCABCV3R1Mð  
ðððð5ðð1ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ðððð5ðð1ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ABCPGM  
QCLSRC  
ᑍPGM  
ᑍFILE  
ABCDSPF ᑍFILE  
A-10 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ABCPF  
ABCMSG  
ABC  
ᑍFILE  
ᑍMSGF  
ᑍCMD  
ðððð2924ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ABCPNLGRP ᑍPNLGRP ðððð2924ðABCABCV3R1Mð  
ABCðð5ð ᑍPRDDFN ðððð5ðð1ðABCABCV3R1Mð  
ABCðð5ð ᑍPRDLOD ðððð5ðð1ðABCABCV3R1Mð  
ABCðð29 ᑍPRDLOD ðððð2924ðABCABCV3R1Mð  
ABC  
ᑍLIB  
ðððð5ðð1ðABCABCV3R1Mð  
Before you can build PTFs for the product, you need to save the product and install  
the product by using the Save Licensed Program (SAVLICPGM) and Restore  
Licensed Program (RSTLICPGM) commands.  
Once the product is built, you can do the following:  
Ÿ Build PTFs for the product by using the following APIs:  
– Create Program Temporary Fix (QPZCRTFX)  
– Retrieve Program Temporary Fix Information (QPZRTVFX)  
– Program Temporary Fix Exit Program  
Ÿ Use save, restore, or delete license program (SAVLICPGM, RSTLICPGM,  
DLTLICPGM) commands on it.  
Ÿ Retrieve information about the product by using the Retrieve Product Informa-  
tion (QSZRTVPR) API.  
Ÿ Check the product to verify the existence of libraries, folders, and objects that  
are part of the specified product (Check Product Option (CHKPRDOPT)  
command).  
Note: For examples of the software product example program in additional lan-  
guages, see “Program for Packaging a Product—Examples” on  
page B-129.  
Retrieving a File Description to a User Space—ILE C Example  
The following programming example shows an application that uses a user space  
as a receiver variable by retrieving a file description to a user space. This  
approach is possible only if you use an HLL that is able to work with pointers. The  
application accepts the following parameters:  
Ÿ User space name and library  
Ÿ File name and library  
Ÿ Record format  
The following shows the sequence of steps to retrieve a file description to a user  
space:  
1. The application creates a user space to store the data in, changes the user  
space to be automatically extendable, and retrieves a pointer to the user space.  
2. The application calls the Retrieve File Description API to retrieve the file defi-  
nition template and uses the user space as the receiver variable.  
This example uses an automatically extended user space as the receiver variable  
on a retrieve API. A user space can return a varying amount of information  
depending on the file description being retrieved. The user space is automatically  
extended up to 16MB to accommodate the information being retrieved.  
Appendix A. Performing Tasks Using APIs—Examples A-11  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Program Name:  
RTVFD  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ Program Language:  
ILE C  
/ᑍ  
/ᑍ Description:  
Retrieve a file definition template to a ᑍ/  
user space.  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Header Files Included: <stdlib.h>  
/ᑍ  
<signal.h>  
<string.h>  
<stdio.h>  
<quscrtus.h>  
<quscusat.h>  
<qusptrus.h>  
<qdbrtvfd.h>  
<qusec.h>  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
<qus.h>  
<qliept.h>  
/ᑍ  
/ᑍ  
/ᑍ APIs Used:  
QUSCRTUS - Create User Space  
/ᑍ  
/ᑍ  
/ᑍ  
QUSCUSAT - Change User Space Attributes ᑍ/  
QUSPTRUS - Retrieve Pointer to User Space ᑍ/  
QDBRTVFD - Retrieve File Description  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdlib.h>  
#include <signal.h>  
#include <string.h>  
#include <stdio.h>  
#include <quscrtus.h>  
#include <quscusat.h>  
#include <qusptrus.h>  
#include <qdbrtvfd.h>  
#include <qusec.h>  
#include <qus.h>  
#include <qliept.h>  
/ᑍ Note that this must be the last ᑍ/  
/ᑍ include specified.  
ᑍ/  
int error_flag = ð;  
/ᑍ Set by error handler  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function:  
error_handler  
ᑍ/  
ᑍ/  
/ᑍ Description: Handle exceptions.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void error_handler(int errparm)  
{
_INTRPT_Hndlr_Parms_T ExcDta = {ð};  
_GetExcData(&ExcDta);  
error_flag = 1;  
signal(SIGALL,error_handler);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Start of main procedure  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
A-12 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
main(int argc, char ᑍᑍargv)  
{
typedef struct attrib_struct {  
int attrib_count;  
Qus_Vlen_Rec_3_t keyinfo;  
char key_value;  
} attrib_struct;  
Qus_EC_t error_code;  
attrib_struct attrib_info;  
char user_space[21];  
char descr[5ð];  
char initial_value = ðxðð;  
char return_lib[1ð];  
char ret_file_lib[2ð];  
char file_and_lib[21];  
char record_fmt[11];  
char ᑍspace_ptr;  
/ᑍ Error code parameter  
/ᑍ Attribute to change  
/ᑍ User space and library  
/ᑍ Text description  
/ᑍ Initial value for user spaceᑍ/  
/ᑍ Return library ᑍ/  
/ᑍ Returned file and library ᑍ/  
/ᑍ File and library  
/ᑍ Record format name  
/ᑍ Pointer to user space objectᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Start of executable code. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (argc != 4) {  
printf("This program requires 3 parameters:\n");  
printf(" 1) User space name and library\n");  
printf(" 2) File name and library\n");  
printf(" 3) Record format name\n");  
printf("Please retry with those parameters.\n");  
exit(1);  
}
memcpy(user_space, ᑍ++argv, 2ð);  
memcpy(file_and_lib, ᑍ++argv, 2ð);  
memcpy(record_fmt, ᑍ++argv, 1ð);  
memset(desc,' ',5ð);  
memcpy(descr,"RTVFD User Space",16);  
signal(SIGALL,error_handler);  
error_code.Bytes_Provided=ð;  
/ᑍ Enable the error handler  
ᑍ/  
/ᑍ Have APIs return exceptions ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Create the user space. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSCRTUS(user_space,  
/ᑍ User space  
/ᑍ Extended attribute  
/ᑍ Initial size  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
"
",  
1ð24,  
&initial_value,  
"ᑍCHANGE ",  
descr,  
/ᑍ Initial value  
/ᑍ Public authority  
/ᑍ Text description  
/ᑍ Replace if it exists  
/ᑍ Error code  
"ᑍYES  
",  
&error_code,  
"ᑍUSER  
");  
/ᑍ Domain = USER  
if (error_flag) {  
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
Appendix A. Performing Tasks Using APIs—Examples A-13  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ Initialize the attributes to change structure.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
attrib_info.attrib_count = 1;  
attrib_info.keyinfo.Key = 3;  
/ᑍ Number of attributes  
/ᑍ Key of attribute to change ᑍ/  
attrib_info.keyinfo.Length_Vlen_Record = 1;  
/ᑍ Length of data  
/ᑍ Autoextend space  
ᑍ/  
ᑍ/  
attrib_info.key_value='1';  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Change the user space to be automatically extendable. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSCUSAT(return_lib,  
user_space,  
/ᑍ Return library  
ᑍ/  
/ᑍ User space name and library ᑍ/  
&attrib_info,  
&error_code);  
/ᑍ Attributes to change  
/ᑍ Error code  
ᑍ/  
ᑍ/  
if (error_flag) {  
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Retrieve a pointer to the user space object. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSPTRUS(user_space,&space_ptr);  
if (error_flag) {  
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Retrieve the file description information to the user space. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QDBRTVFD(space_ptr,  
167767ð4,  
/ᑍ Receiver variable  
/ᑍ Return up to 16MB minus 512 ᑍ/  
/ᑍ bytes of data ᑍ/  
/ᑍ Returned file and library ᑍ/  
ᑍ/  
ret_file_lib,  
"FILDð1ðð",  
file_and_lib,  
record_fmt,  
"ð",  
"ᑍLCL  
"ᑍINT  
&error_code);  
/ᑍ File definition template  
/ᑍ File and library name  
/ᑍ Record format name  
/ᑍ No override processing  
/ᑍ Local system  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
",  
",  
/ᑍ Internal formats .1/  
/ᑍ Error code  
if (error_flag) {  
exit(1);  
}
}
The example program uses the value *INT (.1/). A description and examples of  
the internal (*INT) and external (*EXT) formats are provided in the “Retrieve Data-  
base File Description (QDBRTVFD) API” in the System API Reference book.  
A-14 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Using Data Queues versus User Queues  
Data queues and user queues both provide a means for one or more processes to  
communicate asynchronously. The queues can be processed FIFO (first-in  
first-out), LIFO (last-in first-out), or by key. If user queues and data queues supply  
the same function, which one should you choose for your implementation? The  
following is a comparison of the two and an insight into when you should use one  
queue rather than the other.  
First, your programming experience is an important consideration in selecting a  
queue type. If you are skilled in C or MI programming, you may want to select the  
user queue. C and MI are the only languages that can use MI instructions, which,  
as discussed later, has a bearing on performance. If your expertise is in COBOL or  
RPG, then you should choose the data queue. You cannot implement a user  
queue in COBOL or RPG because neither of these languages can use MI  
instructions.  
Next, performance plays an important part in determining what type of queue to  
use. As stated in Chapter 1, “Application Programming Interface—Overview” on  
page 1-1, APIs generally give better performance than CL commands. Also, MI  
instructions perform better than an external call to an API because APIs have over-  
head associated with them. User queues use MI instructions to manipulate entries;  
data queues use APIs. Therefore, the user queue has better performance than the  
data queue.  
Last, you need to consider how the queue entries are manipulated. For example,  
you need a way to perform enqueue and dequeue operations on entries from a  
queue. As stated earlier, user queues use MI instructions to manipulate entries.  
Specifically, you use the ENQ MI instruction to enqueue a message, and the DEQ  
MI instruction to dequeue a message. If you are running at security level 40 or  
greater, you must ensure that the user queue is created in the user domain in order  
to directly manipulate a user queue using MI instructions. Because data queue  
entries are manipulated by APIs, the security level of the machine does not limit the  
use of the API.  
You cannot create a user queue object in a library that does not permit user-  
domain objects, which is determined by the QALWUSRDMN system value. (See  
“Domain Concepts” on page 2-26 for more information on QALWUSRDMN.) Data  
queues are always created in the system domain, so there is no problem with the  
data queue being created into a specific library.  
The following is a summary to help you select the type of queue that is right for  
your program:  
Ÿ Use user queues when:  
– You have a programming background in or prefer to program in C or MI.  
– You need the additional performance of an API for creating and deleting  
and MI instructions for manipulating entries.  
– You do not need to create a user-domain queue into a library where the  
QALWUSRDMN system value does not permit user-domain user objects  
when at security level 40 or 50.  
Ÿ Use data queues when:  
– You have a programming background in or prefer to program in COBOL or  
RPG.  
Appendix A. Performing Tasks Using APIs—Examples A-15  
Download from Www.Somanuals.com. All Manuals Search And Download.  
– You do not need the additional performance of MI instructions for directly  
manipulating entries.  
– You need to create queues into a library that is not listed in the  
QALWUSRDMN system value.  
Data Queue—ILE C Example  
The following program illustrates how to use APIs to create and manipulate a data  
queue.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍProgram Name: DQUEUEX  
/ᑍ  
/ᑍProgram Language: ILE C  
/ᑍ  
/ᑍDescription: This program illustrates how to use APIs to create  
/ᑍ  
/ᑍ  
/ᑍ  
and manipulate a data queue.  
/ᑍHeader Files Included: <stdio.h>  
/ᑍ  
<string.h>  
<stdlib.h>  
<decimal.h>  
<qrcvdtaq.h>  
<qsnddtaq.h>  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍAPIs Used:  
QSNDDTAQ - Send data queue  
QRCVDTAQ - Receive data queue  
/ᑍ  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Includes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <string.h>  
#include <stdlib.h>  
#include <decimal.h>  
#include <qsnddtaq.h>  
#include <qrcvdtaq.h>  
/ᑍ from QSYSINC/h  
/ᑍ from QSYSINC/h  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
Main  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void main()  
{
decimal(5,ð) DataLength = 1ð.ðd,  
WaitTime = ð.ðd;  
char QueueData[1ð];  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Create library QUEUELIB.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
A-16 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
system("CRTLIB LIB(QUEUELIB)");  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Create a data queue called EXAMPLEQ in library QUEUELIB. The ᑍ/  
/ᑍ queue will have a maximum entry length set at 1ð, and will be ᑍ/  
/ᑍ FIFO (first-in first-out).  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
system("CRTDTAQ DTAQ(QUEUELIB/EXAMPLEQ) MAXLEN(1ð)");  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Send information to the data queue.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QSNDDTAQ("EXAMPLEQ ",  
"QUEUELIB ",  
/ᑍ Data queue name  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Queue library name  
/ᑍ Length of queue entry  
/ᑍ Data sent to queue  
DataLength,  
"EXAMPLE ");  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Receive information from the data queue. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QRCVDTAQ("EXAMPLEQ ",  
"QUEUELIB ",  
&DataLength,  
/ᑍ Data queue name  
/ᑍ Queue library name  
/ᑍ Length of queue entry  
/ᑍ Data received from queue ᑍ/  
/ᑍ Wait time ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
&QueueData,  
WaitTime);  
printf("Queue entry information: %.1ðs\n", QueueData);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Delete the data queue. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
system("DLTDTAQ DTAQ(QUEUELIB/EXAMPLEQ)");  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Delete the library.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
system("DLTLIB LIB(QUEUELIB)");  
}
Note: For examples of the data queue program in additional languages, see “Data  
Queue—Examples” on page B-165.  
User Queue—ILE C Example  
The following program illustrates how to use APIs to create and manipulate a user  
queue.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍProgram Name: UQUEUEX  
/ᑍ  
/ᑍProgram Language: ILE C  
Appendix A. Performing Tasks Using APIs—Examples A-17  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ  
ᑍ/  
/ᑍDescription: This program illustrates how to use APIs to create ᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
and manipulate a user queue.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍHeader Files Included: <stdio.h>  
/ᑍ  
<signal.h>  
<string.h>  
<stdlib.h>  
<miptrnam.h>  
<miqueue.h>  
<pointer.h>  
<quscrtuq.h>  
<qusdltuq.h>  
<qusec.h>  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍAPIs Used:  
QUSCRTUQ - Create a user queue  
QUSDLTUQ - Delete a user queue  
/ᑍ  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Includes  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <signal.h>  
#include <string.h>  
#include <stdlib.h>  
#include <milib.h>  
/ᑍ from QCLE/h  
/ᑍ from QCLE/h  
/ᑍ from QCLE/h  
ᑍ/  
ᑍ/  
ᑍ/  
#include <miptrnam.h>  
#include <miqueue.h>  
#include <pointer.h>  
#include <quscrtuq.h>  
#include <qusdltuq.h>  
#include <qusec.h>  
/ᑍ from QSYSINC/h  
/ᑍ from QSYSINC/h  
/ᑍ from QSYSINC/h  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
Structures  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
Qus_EC_t ec_fields;  
char  
exception_data[1ðð];  
} error_code_struct;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
Main  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void main()  
{
char text_desc[5ð];  
error_code_struct error_code;  
_SYSPTR queuelib_sysptr,  
user_queue_obj_sysptr;  
A-18 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
_RSLV_Template_T rslvsp_template;  
_ENQ_Msg_Prefix_T enq_msg_prefix;  
_DEQ_Msg_Prefix_T deq_msg_prefix;  
char enq_msg[5ð],  
deq_msg[5ð];  
int success=ð;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Create a library to create the user queue into.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
system("CRTLIB LIB(QUEUELIB)");  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize the error code parameter.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the QUSCRTUQ API to create a user queue.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ This will create a user queue called EXAMPLEQ in library  
/ᑍ QUEUELIB, with the following attributes:  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
1. Extended attribute of "VALID  
been any valid ᑍNAME.  
2. A queue type of "F", or First-in, first-out.  
3. A key length of ð. If the queue is not keyed, this  
value must be ð.  
4. A maximum message size of 1ð bytes. This number can  
be as large as 64K bytes.  
5. The initial number of messages set to 1ð.  
6. Additional number of messages set to 1ð.  
7. Public authority of ᑍUSE.  
8. A valid text description.  
9. Replace option of ᑍYES. This means that if a user queue ᑍ/  
", which could have  
already exists by the name specified, in the library  
specified, that it will be replaced by this  
request.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
1ð. Domain value of ᑍUSER.  
11. Pointer value of ᑍNO. Messages in the queue cannot  
contain pointer data.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(text_desc, "THIS IS TEXT FOR THE EXAMPLE USER QUEUE  
5ð);  
",  
QUSCRTUQ("EXAMPLEQ QUEUELIB ", /ᑍ Qualified user queue name  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
"VALID  
"F",  
",  
/ᑍ Extended attribute  
/ᑍ Queue type  
ð,  
/ᑍ Key length  
1ð,  
1ð,  
/ᑍ Maximum message size  
/ᑍ Initial number of messages  
1ð,  
/ᑍ Additional number of messages ᑍ/  
"ᑍALL  
text_desc,  
"ᑍYES  
",  
",  
/ᑍ Public authority  
/ᑍ Text Description  
/ᑍ Replace existing user queue ᑍ/  
/ᑍ Error code ᑍ/  
ᑍ/  
ᑍ/  
&error_code,  
Appendix A. Performing Tasks Using APIs—Examples A-19  
Download from Www.Somanuals.com. All Manuals Search And Download.  
"ᑍUSER  
"ᑍNO  
",  
");  
/ᑍ Domain of user queue  
/ᑍ Allow pointer data  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If an exception occurred, the API would have returned the  
/ᑍ exception in the error code parameter. The bytes available  
ᑍ/  
ᑍ/  
/ᑍ field will be set to zero if no exception occurred and greater ᑍ/  
/ᑍ than zero if an exception did occur.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ᑍ/  
if (error_code.ec_fields.Bytes_Available > ð)  
{
printf("ATTEMPT TO CREATE A USER QUEUE FAILED WITH EXCEPTION:%.7s",  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Send information to the queue.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ We will need to use MI instructions to accomplish this.  
/ᑍ There are three steps that must be done:  
/ᑍ  
/ᑍ 1. Resolve a system pointer to the library containing the user ᑍ/  
/ᑍ  
/ᑍ 2. Using the system pointer to the library, resolve a system  
/ᑍ pointer to user queue object in the library.  
/ᑍ 3. Enqueue the entry using the system pointer for the user  
queue object.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ  
queue.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ First we must resolve to library QUEUELIB.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(rslvsp_template.Obj.Name,' ',3ð);  
memcpy(rslvsp_template.Obj.Name,"QUEUELIB",8);  
rslvsp_template.Obj.Type_Subtype = _Library; /ᑍ found in milib.h ᑍ/  
rslvsp_template.Auth = _AUTH_NONE; /ᑍ found in milib.h  
ᑍ/  
_RSLVSP6(&queuelib_sysptr,  
&rslvsp_template,  
/ᑍ system pointer to be set  
/ᑍ resolve template  
ᑍ/  
ᑍ/  
&rslvsp_template.Auth); /ᑍ authority to set in sysptr ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ We can now resolve to the user queue object. We will pass the ᑍ/  
/ᑍ system pointer to library QUEUELIB to RSLVSP so the resolve  
/ᑍ will only search library QUEUELIB for the user queue object.  
/ᑍ This is necessary so that we ensure that we are using the  
/ᑍ correct object.  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(rslvsp_template.Obj.Name,' ',3ð);  
memcpy(rslvsp_template.Obj.Name, "EXAMPLEQ", 8);  
rslvsp_template.Obj.Type_Subtype = _Usrq; /ᑍ found in milib.h  
rslvsp_template.Auth = _AUTH_ALL; /ᑍ found in milib.h  
ᑍ/  
ᑍ/  
_RSLVSP8(&user_queue_obj_sysptr, /ᑍ system pointer to be set  
ᑍ/  
ᑍ/  
&rslvsp_template,  
/ᑍ resolve template  
A-20 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
&queuelib_sysptr,  
/ᑍ sysptr to library  
ᑍ/  
&rslvsp_template.Auth); /ᑍ authority to set in sysptr ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Enqueue the entry.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
enq_msg_prefix.Msg_Len = 1ð;  
enq_msg_prefix.Msg[ð] = '\ð';  
memcpy(enq_msg, "EXAMPLE ", 1ð);  
/ᑍ Only used for keyed queuesᑍ/  
_ENQ(&user_queue_obj_sysptr,  
&enq_msg_prefix,  
/ᑍ system pointer to user queue ᑍ/  
/ᑍ message prefix  
/ᑍ message text  
ᑍ/  
ᑍ/  
(_SPCPTR)enq_msg);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Dequeue the entry. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
success = _DEQI(&deq_msg_prefix, /ᑍ message prefix  
(_SPCPTR)deq_msg, /ᑍ message text  
ᑍ/  
ᑍ/  
&user_queue_obj_sysptr); /ᑍ sys ptr to user queue ᑍ/  
if(success)  
{
printf("Queue entry information: %.1ðs\n", deq_msg);  
}
else  
{
printf("Entry not dequeued\n");  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Delete the user queue.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSDLTUQ("EXAMPLEQ QUEUELIB ", /ᑍ Qualified user queue name  
&error_code); /ᑍ Error code  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If an exception occurred, the API would have returned the  
/ᑍ exception in the error code parameter. The bytes available  
ᑍ/  
ᑍ/  
/ᑍ field will be set to zero if no exception occurred and greater ᑍ/  
/ᑍ than zero if an exception did occur.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ᑍ/  
if (error_code.ec_fields.Bytes_Available > ð)  
{
printf("ATTEMPT TO DELETE A USER QUEUE FAILED WITH EXCEPTION:%.7s",  
error_code.ec_fields.Exception_Id);  
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Delete the library created for this example.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
system("DLTLIB LIB(QUEUELIB)");  
}
Appendix A. Performing Tasks Using APIs—Examples A-21  
Download from Www.Somanuals.com. All Manuals Search And Download.  
A-22 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Appendix B. Original Examples in Additional Languages  
This appendix contains examples from the following areas of this book. The program examples in this  
appendix are rewritten from the original examples into other programming languages.  
Ÿ Chapter 3, “Common Information across APIs—Basic (OPM) Example”  
Ÿ Chapter 4, “Common Information across APIs—Advanced (ILE) Example”  
Ÿ Chapter 5, “List APIs”  
Ÿ Chapter 6, “Original Program Model (OPM) and Integrated Language Environment (ILE) Differences”  
Ÿ Appendix A, “Performing Tasks Using APIs—Examples”  
This appendix also contains examples written in ILE C, ILE COBOL, and ILE RPG for using the integrated  
file system.  
The following tables describe the example tasks and refer you to the corresponding programming lan-  
guage topic. In these tables, Yes means the task can be accomplished in the language identified but an  
example is not provided. No means the task cannot be accomplished in the language identified.  
Figure B-1. Original Program Model (OPM) API Examples from Chapter 3  
Programming Language and Location of Example  
Task  
ILE C  
OPM COBOL  
ILE COBOL  
OPM RPG  
ILE RPG  
Retrieving the HOLD Parameter (Exception  
Messages)  
B-2  
B-4  
B-4  
3-6  
B-6  
Handling Error Conditions  
No  
No  
No  
3-8  
B-8  
Retrieving the HOLD Parameter (Error Code  
Structure)  
B-10  
B-12  
B-12  
3-11  
B-14  
Accessing the HOLD Attribute  
B-16  
B-22  
B-33  
B-18  
B-25  
B-38  
B-18  
B-25  
B-38  
3-17  
3-19  
3-24  
B-21  
B-29  
B-42  
Accessing a Field Value (Initial Library List)  
Using Keys with List Spooled Files API  
Figure B-2. Integrated Language Environment (ILE) API Examples from Chapter 4  
Programming Language and Location of Example  
Task  
ILE C  
4-9  
OPM COBOL  
B-47  
ILE COBOL  
B-50  
OPM RPG  
B-54  
ILE RPG  
B-58  
Register Exit Point and Add Exit Program  
Retrieve Exit Point and Exit Program Informa-  
tion  
4-13  
B-61  
B-66  
B-71  
B-75  
Remove Exit Program and Deregister Exit  
Point  
4-19  
B-85  
B-87  
B-90  
B-92  
Figure B-3. List API Examples from Chapter 5  
Programming Language and Location of Example  
Task  
ILE C  
B-94  
OPM COBOL  
ILE COBOL  
OPM RPG  
ILE RPG  
Listing Objects  
B-101  
B-101  
5-4  
B-106  
Figure B-4 (Page 1 of 2). Pointer API Examples from Chapter 6  
Programming Language and Location of Example  
Task  
ILE C  
OPM COBOL  
ILE COBOL  
OPM RPG  
ILE RPG  
Logging Software Error (OPM API without  
Pointers)  
6-2  
B-112  
N/A  
B-116  
B-119  
Copyright IBM Corp. 1997  
B-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Figure B-4 (Page 2 of 2). Pointer API Examples from Chapter 6  
Programming Language and Location of Example  
Task  
ILE C  
OPM COBOL  
ILE COBOL  
OPM RPG  
ILE RPG  
Reporting Software Error (ILE API with  
Pointers)  
6-7  
N/A  
B-122  
N/A  
B-126  
Figure B-5. Performing Tasks Using API Examples from Appendix A  
Programming Language and Location of Example  
Task  
ILE C  
B-129  
A-11  
OPM COBOL  
B-136  
ILE COBOL  
B-136  
OPM RPG  
A-3  
ILE RPG  
B-144  
B-155  
B-172  
No  
Program for Packaging a Product  
Retrieving a File Description to a User Space  
Working with Data Queues  
Working with User Queues  
B-152  
B-152  
No  
A-16  
B-165  
B-165  
B-169  
No  
A-17  
No  
No  
Figure B-6. UNIX-Type API Examples  
Programming Language and Location of Example  
Task  
ILE C  
OPM COBOL  
ILE COBOL  
OPM RPG  
ILE RPG  
Using the Integrated File System  
B-175  
No  
B-178  
No  
B-183  
Original Program Model (OPM) APIs—Examples  
This topic includes the examples in Chapter 3, “Common Information across  
APIs—Basic (OPM) Example.”  
Retrieving the Hold Parameter (Exception Message)—ILE C Example  
Refer to “Retrieving the Hold Parameter (Exception Message)—OPM RPG  
Example” on page 3-6 for the original example.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍProgram Name:  
/ᑍ  
JOBDAPI  
/ᑍProgramming Language: ILE C  
/ᑍ  
/ᑍDescription:  
This example expects errors sent as  
escape messages.  
/ᑍ  
/ᑍ  
/ᑍHeader Files Included: SIGNAL - C Error Signalling Routines  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
STDIO - Standard Input/Output  
STRING - String Functions  
QUSEC - Error Code Parameter  
QWDRJOBD - Retrieve Job Description API  
QLIEPT - Entry Point Table  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <signal.h>  
#include <stdio.h>  
#include <string.h>  
B-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
#include <qusec.h>  
/ᑍ Error Code Parameter Include for the APIs ᑍ/  
#include <qwdrjobd.h> .2/  
/ᑍ Retrieve Job Description API Include  
ᑍ/  
#include <qliept.h>  
char received[8];  
/ᑍ Used to receive error msgs signaled  
/ᑍ from QWDRJOBD API.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function: error_handler ᑍ/  
/ᑍ Description: This function handles exceptions signalled from the ᑍ/  
/ᑍ  
/ᑍ  
QWDRJOBD API. The message identifier received is  
assigned to the variable 'received'.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void error_handler(int dummy)  
{
_INTRPT_Hndlr_Parms_T ExcDta = {ð};  
_GetExcData(&ExcDta);  
memcpy(received,ExcDta.Msg_Id,7);  
signal(SIGALL,error_handler);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Error Code Structure  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍ This shows how the user can define the variable length portion of ᑍ/  
/ᑍ error code for the exception data.  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
Qus_EC_t ec_fields;  
char  
Exception_Data[1ðð];  
} error_code_t;  
main(int argc, char ᑍargv[] .8/  
{
error_code_t error_code;  
char  
char  
char  
char  
char  
qual_job_desc[2ð];  
ᑍqual_job_ptr = qual_job_desc;  
rec_var[39ð];  
hold_value[1ð];  
command_string[53];  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Enable error handler. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
signal(SIGALL,error_handler);  
memset(hold_value, ' ', 1ð);  
memset(received, ' ', 7);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Make sure we received the correct number of parameters. The argc ᑍ/  
/ᑍ parameter will contain the number of parameters that was passed ᑍ/  
/ᑍ to this program. This number also includes the program itself,  
/ᑍ so we need to evaluate argc-1.  
ᑍ/  
ᑍ/  
Appendix B. Original Examples in Additional Languages B-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (((argc - 1) < 2) || ((argc - 1 > 2)))  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ We did not receive all of the required parameters so exit the  
/ᑍ program.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
{
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Move the two parameters passed into qual_job_desc. .9/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(qual_job_ptr, argv[1], 1ð);  
qual_job_ptr += 1ð;  
memcpy(qual_job_ptr, argv[2], 1ð); .6/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the error code parameter to ð.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.ec_fields.Bytes_Provided = ð;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the QWDRJOBD API.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QWDRJOBD(rec_var,  
/ᑍ Receiver Variable  
/ᑍ Receiver Length  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
39ð, .3/  
"JOBDð1ðð", .5/ /ᑍ Format Name  
qual_job_desc,  
&error_code);  
/ᑍ Qualified Job Description  
/ᑍ Error Code  
if(memcmp(received, "  
", 7) == ð)  
memcpy(hold_value, ((Qwd_JOBDð1ðð_t ᑍ)rec_var)->Hold_Job_Queue, 1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Let's tell everyone what the hold value was for this job.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
sprintf(command_string,  
"SNDMSG MSG('HOLD value is %.7s') TOUSR(QPGMR)",  
hold_value);  
system(command_string);  
} /ᑍ main ᑍ/  
Retrieving the Hold Parameter (Exception Message)—ILE COBOL  
Example  
Refer to “Retrieving the Hold Parameter (Exception Message)—OPM RPG  
Example” on page 3-6 for the original example. The following program also works  
for OPM COBOL.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name:  
ᑍ
JOBDAPI  
B-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍProgramming Language: COBOL  
ᑍ
ᑍDescription:  
This example expects errors sent as  
escape messages.  
ᑍ
ᑍ
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍ
QWDRJOBD - Retrieve Job Description API  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PROGRAM-ID. JOBDAPI.  
ᑍ
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
ᑍ
DATA DIVISION.  
WORKING-STORAGE SECTION.  
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Retrieve Job Description API Include  
ᑍ
COPY QWDRJOBD OF QSYSINC-QLBLSRC. .2/  
ᑍ
ᑍ Command String Data Structure  
ᑍ
ð1 COMMAND-STRING.  
ð5 TEXT1 PIC X(26) VALUE 'SNDMSG MSG(''HOLD value is'.  
ð5 HOLD PIC X(1ð).  
ð5 TEXT2 PIC X(15) VALUE ''') TOUSR(QPGMR)'.  
ᑍ
ð1 COMMAND-LENGTH PIC S9(1ð)V99999 COMP-3.  
ð1 RECEIVER-LENGTH PIC S9(9) COMP-4. .4/  
ð1 FORMAT-NAME PIC X(8) VALUE 'JOBDð1ðð'. .5/  
ð1 QCMDEXC PIC X(1ð) VALUE 'QCMDEXC'.  
ᑍ
ᑍ Job Description and Library Name Structure  
ᑍ
ð1 JOBD-AND-LIB-NAME.  
ð5 JOB-DESC PIC X(1ð).  
ð5 JOB-DESC-LIB PIC X(1ð).  
ᑍ
LINKAGE SECTION.  
ᑍ
ᑍ Two Parameters are being passed into this program.  
ᑍ
ð1 JOBD PIC X(1ð).  
ð1 JOBDL PIC X(1ð).  
ᑍ
PROCEDURE DIVISION USING JOBD, JOBDL. .8/  
MAIN-LINE.  
ᑍ
ᑍ Beginning of Mainline  
ᑍ
ᑍ Move the two parameters passed into JOB-DESC and JOB-DESC-LIB. .9/  
ᑍ
Appendix B. Original Examples in Additional Languages B-5  
Download from Www.Somanuals.com. All Manuals Search And Download.  
MOVE JOBD TO JOB-DESC.  
MOVE JOBDL TO JOB-DESC-LIB.  
ᑍ
ᑍ Error Code Parameter is set to ð.  
ᑍ
MOVE ð TO BYTES-PROVIDED. .6/  
ᑍ
ᑍ Receiver Length Set to 39ð.  
ᑍ
MOVE 39ð TO RECEIVER-LENGTH. .3/  
ᑍ
ᑍ Call the QWDRJOBD API.  
ᑍ
CALL QWDRJOBD USING QWD-JOBDð1ðð, RECEIVER-LENGTH,  
FORMAT-NAME, JOBD-AND-LIB-NAME, QUS-EC.  
ᑍ
ᑍ Move HOLD-JOB-QUEUE to HOLD so that we can display the value using  
ᑍ the command string.  
ᑍ
MOVE HOLD-JOB-QUEUE TO HOLD.  
ᑍ
ᑍ Let's tell everyone what the hold value was for this job.  
ᑍ
MOVE 51 TO COMMAND-LENGTH.  
CALL QCMDEXC USING COMMAND-STRING, COMMAND-LENGTH.  
ᑍ
STOP RUN.  
Retrieving the Hold Parameter (Exception Message)—ILE RPG  
Example  
Refer to “Retrieving the Hold Parameter (Exception Message)—OPM RPG  
Example” on page 3-6 for the original example.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Program Name: JOBDAPI  
Dᑍ  
Dᑍ Programming Language: ILE RPG  
Dᑍ  
Dᑍ Description: This program retrieves the HOLD value from  
Dᑍ  
Dᑍ  
Dᑍ  
a job description. It expects errors to be  
sent as escape messages.  
Dᑍ Header Files Included: QUSEC - Error Code Parameter  
Dᑍ  
QWDRJOBD - Retrieve Job Description API  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Error Code parameter include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
Dᑍ Retrieve Job Description API Include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QWDRJOBD  
.2/  
B-6 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
Dᑍ Command string data structure  
Dᑍ  
DCMD_STRING  
DS  
D
26  
1ð  
15  
INZ('SNDMSG MSG(''HOLD value is ')  
INZ(''') TOUSR(QPGMR)')  
D HOLD  
D
Dᑍ  
Dᑍ Miscellaneous data structure  
Dᑍ  
.4/  
.2/ .3/  
DRCVLEN  
DFORMAT  
DLENSTR  
Cᑍ  
S
S
S
9B ð INZ(%SIZE(QWDDð1ðð))  
INZ('JOBDð1ðð') .5/  
15 5 INZ(%SIZE(CMD_STRING))  
8
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Two parameters are being passed into this program  
Cᑍ  
C
ᑍENTRY  
PLIST .8/  
PARM  
PARM  
C
JOBD  
JOBD_LIB  
1ð  
1ð  
C
Cᑍ  
Cᑍ Move the two parameters passed into LFNAM  
Cᑍ  
C
JOBD  
CAT  
JOBD_LIB  
LFNAM  
2ð .9/  
Cᑍ  
Cᑍ Error Code Bytes Provided is set to ð  
Cᑍ  
C
Z-ADD  
ð
QUSBPRV  
.6/  
Cᑍ  
Cᑍ Call the API.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
QWDRJOBD  
C
QWDDð1ðð  
RCVLEN  
FORMAT  
LFNAM  
C
C
C
C
QUSEC  
Cᑍ  
C
Cᑍ  
MOVEL  
QWDHJQ  
HOLD  
Cᑍ Let's tell everyone what the hold value was for this job  
Cᑍ  
C
CALL  
PARM  
PARM  
'QCMDEXC'  
C
CMD_STRING  
LENSTR  
C
Cᑍ  
C
C
Cᑍ  
EVAL  
RETURN  
ᑍINLR = '1'  
Cᑍ End of MAINLINE  
Cᑍ  
Appendix B. Original Examples in Additional Languages B-7  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Handling Error Conditions—ILE RPG Example  
Refer to “Handling Error Conditions—OPM RPG Example” on page 3-8 for the ori-  
ginal example. This example can be written only in OPM RPG and ILE RPG.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Program Name: JOBDAPI  
Dᑍ  
Dᑍ Programming Language: ILE RPG  
Dᑍ  
Dᑍ Description: This program retrieves the HOLD value from  
Dᑍ  
Dᑍ  
Dᑍ  
a job description. It expects errors to be  
sent as escape messages.  
Dᑍ Header Files Included: QUSEC - Error Code Parameter  
Dᑍ  
QWDRJOBD - Retrieve Job Description API  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Error Code parameter include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
Dᑍ Retrieve Job Description API Include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QWDRJOBD  
Dᑍ  
Dᑍ Program status DS  
Dᑍ  
DPGMSTS  
D MSG_ID  
Dᑍ  
SDS .12/  
4ð  
46  
Dᑍ Command string data structure  
Dᑍ  
DCMD_STRING  
DS  
D
26  
1ð  
15  
INZ('SNDMSG MSG(''HOLD value is ')  
INZ(''') TOUSR(QPGMR)')  
D HOLD  
D
Dᑍ  
Dᑍ Miscellaneous data structure  
Dᑍ  
DRCVLEN  
DFORMAT  
DLENSTR  
DNO_JOBD  
D
S
S
S
S
9B ð INZ(%SIZE(QWDDð1ðð))  
INZ('JOBDð1ðð')  
15 5 INZ(%SIZE(CMD_STRING))  
INZ('SNDMSG MSG(''No such ᑍJOBD -  
exists'') TOUSR(QPGMR)')  
15 5 INZ(%SIZE(NO_JOBD))  
8
47  
DNO_JOBD_SZ  
Cᑍ  
S
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Two parameters are being passed into this program  
Cᑍ  
C
ᑍENTRY  
PLIST  
PARM  
PARM  
C
JOBD  
JOBD_LIB  
1ð  
1ð  
C
Cᑍ  
B-8 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ Move the two parameters passed into LFNAM  
Cᑍ  
C
JOBD  
CAT  
JOBD_LIB  
LFNAM  
2ð  
Cᑍ  
Cᑍ Error Code Bytes Provided is set to ð  
Cᑍ  
C
Z-ADD  
ð
QUSBPRV  
.11/  
Cᑍ  
Cᑍ Call the API.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
QWDRJOBD  
ð1 .1ð/  
C
QWDDð1ðð  
RCVLEN  
FORMAT  
LFNAM  
C
C
C
C
QUSEC  
Cᑍ  
Cᑍ Test for an error on the API call  
Cᑍ  
C
Cᑍ  
IF  
ᑍINð1 = ᑍON  
Cᑍ If there was an error, exit to ERROR subroutine  
Cᑍ  
C
Cᑍ  
EXSR  
ERROR  
Cᑍ Else, process the HOLD value  
Cᑍ  
C
ELSE  
MOVEL  
C
QWDHJQ  
HOLD  
Cᑍ  
Cᑍ Let's tell everyone what the hold value was for this job  
Cᑍ  
C
CALL  
PARM  
PARM  
END  
'QCMDEXC'  
C
CMD_STRING  
LENSTR  
C
C
Cᑍ  
C
C
Cᑍ  
EVAL  
RETURN  
ᑍINLR = '1'  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ Subroutine to handle errors received on the CALL  
Cᑍ  
C
ERROR  
BEGSR  
IF  
C
MSG_ID = 'CPF98ð1'  
Cᑍ  
Cᑍ Process errors returned from the API  
Cᑍ  
C
C
C
C
C
CALL  
PARM  
PARM  
END  
'QCMDEXC'  
NO_JOBD  
NO_JOBD_SZ  
ENDSR  
Appendix B. Original Examples in Additional Languages B-9  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Retrieving the Hold Parameter (Error Code Structure)—ILE C Example  
Refer to “Retrieving the Hold Parameter (Error Code Structure)—OPM RPG  
Example” on page 3-11 for the original example.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
/ᑍProgram Name:  
/ᑍ  
JOBDAPI  
ᑍ/  
ᑍ/  
/ᑍProgramming Language: ILE C  
/ᑍ  
/ᑍDescription:  
ᑍ/  
ᑍ/  
This example shows how to make use of an  
ᑍ/  
/ᑍ  
/ᑍ  
error returned in the error code structure. ᑍ/  
ᑍ/  
/ᑍHeader Files Included: STDIO - Standard Input/Output  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
STRING - String Functions  
QUSEC - Error Code Parameter  
QWDRJOBD - Retrieve Job Description API  
QLIEPT - Entry Point Table  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <string.h>  
#include <qusec.h> .14/ /ᑍ Error Code Parameter Include for the API ᑍ/  
#include <qwdrjobd.h>  
#include <qliept.h>  
/ᑍ Retrieve Job Description API Include  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Error Code Structure  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍ This shows how the user can define the variable length portion of ᑍ/  
/ᑍ error code for the exception data.  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
Qus_EC_t ec_fields;  
char  
Exception_Data[1ðð];  
} error_code_t;  
main(int argc, char ᑍargv[])  
{
error_code_t error_code;  
char  
char  
char  
char  
char  
char  
char  
qual_job_desc[2ð];  
ᑍqual_job_ptr = qual_job_desc;  
rec_var[39ð];  
hold_value[1ð];  
message_id[7];  
command_string[53];  
message_string[67];  
memset(hold_value, ' ', 1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Make sure we received the correct number of parameters. The argc ᑍ/  
/ᑍ parameter will contain the number of parameters that was passed ᑍ/  
/ᑍ to this program. This number also includes the program itself,  
ᑍ/  
B-10 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ so we need to evaluate argc-1.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (((argc - 1) < 2) || ((argc - 1 > 2)))  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ We did not receive all of the required parameters so exit the  
/ᑍ program.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
{
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Move the two parameter passed in into qual_job_desc.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(qual_job_ptr, argv[1], 1ð);  
qual_job_ptr += 1ð;  
memcpy(qual_job_ptr, argv[2], 1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the error code parameter to 16.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.ec_fields.Bytes_Provided = 16; .15/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the QWDRJOBD API.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QWDRJOBD(rec_var,  
39ð,  
/ᑍ Receiver Variable  
/ᑍ Receiver Length  
/ᑍ Format Name  
/ᑍ Qualified Job Description  
/ᑍ Error Code  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
"JOBDð1ðð",  
qual_job_desc,  
&error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If an error was returned, send an error message.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if(error_code.ec_fields.Bytes_Available > ð) .13/  
{
memcpy(message_id, error_code.ec_fields.Exception_Id, 7);  
sprintf(message_string,  
"SNDMSG MSG('Program failed with message ID %.7s') TOUSR(QPGMR)",  
message_id);  
system(message_string);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Let's tell everyone what the hold value was for this job.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
else  
{
memcpy(hold_value, ((Qwd_JOBDð1ðð_t ᑍ)rec_var)->Hold_Job_Queue, 1ð);  
sprintf(command_string,  
"SNDMSG MSG('HOLD value is %.1ðs') TOUSR(QPGMR)",  
hold_value);  
system(command_string);  
}
} /ᑍ main ᑍ/  
Appendix B. Original Examples in Additional Languages B-11  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Retrieving the Hold Parameter (Error Code Structure)—ILE COBOL  
Example  
Refer to “Retrieving the Hold Parameter (Error Code Structure)—OPM RPG  
Example” on page 3-11 for the original example. The following program also works  
for OPM COBOL.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name:  
ᑍ
JOBDAPI  
ᑍProgramming Language: COBOL  
ᑍ
ᑍDescription:  
This example shows how to make use of an  
error returned in the error code  
structure.  
ᑍ
ᑍ
ᑍ
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍ
QWDRJOBD - Retrieve Job Description API  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PROGRAM-ID. JOBDAPI.  
ᑍ
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
ᑍ
DATA DIVISION.  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC. .14/  
ᑍ
ᑍ Retrieve Job Description API Include  
ᑍ
COPY QWDRJOBD OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Command String Data Structure  
ᑍ
ð1 COMMAND-STRING.  
ð5 TEXT1 PIC X(26) VALUE 'SNDMSG MSG(''HOLD value is'.  
ð5 HOLD PIC X(1ð).  
ð5 TEXT2 PIC X(15) VALUE ''') TOUSR(QPGMR)'.  
ᑍ
ᑍ Message Identifier Data Structure  
ᑍ
B-12 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ð1 MESSAGE-TWO.  
ð5 MSG2A PIC X(43)  
VALUE 'SNDMSG MSG(''Program failed with message ID'.  
ð5 MSGIDD PIC X(7).  
ð5 MSG2B PIC X(15) VALUE ''') TOUSR(QPGMR)'.  
ᑍ
ᑍ
ð1 COMMAND-LENGTH PIC S9(1ð)V99999 COMP-3.  
ð1 RECEIVER-LENGTH PIC S9(9) COMP-4.  
ð1 FORMAT-NAME PIC X(8) VALUE 'JOBDð1ðð'.  
ð1 QCMDEXC PIC X(1ð) VALUE 'QCMDEXC'.  
ᑍ Job Description and Library Name Structure  
ᑍ
ð1 JOBD-AND-LIB-NAME.  
ð5 JOB-DESC PIC X(1ð).  
ð5 JOB-DESC-LIB PIC X(1ð).  
ᑍ
LINKAGE SECTION.  
ᑍ
ᑍ Two Parameters are being passed into this program.  
ᑍ
ð1 JOBD PIC X(1ð).  
ð1 JOBDL PIC X(1ð).  
ᑍ
PROCEDURE DIVISION USING JOBD, JOBDL.  
MAIN-LINE.  
ᑍ
ᑍ Beginning of Mainline  
ᑍ
ᑍ Move the two parameters passed into JOB-DESC and JOB-DESC-LIB.  
ᑍ
MOVE JOBD TO JOB-DESC.  
MOVE JOBDL TO JOB-DESC-LIB.  
ᑍ
ᑍ Error Code Parameter is set to 16.  
ᑍ
MOVE 16 TO BYTES-PROVIDED. .15/  
ᑍ
ᑍ Receiver Length Set to 39ð.  
ᑍ
MOVE 39ð TO RECEIVER-LENGTH.  
ᑍ
ᑍ Call the QWDRJOBD API.  
ᑍ
CALL QWDRJOBD USING QWD-JOBDð1ðð, RECEIVER-LENGTH,  
FORMAT-NAME, JOBD-AND-LIB-NAME, QUS-EC.  
ᑍ
ᑍ See if any errors were returned in the error code parameter.  
ᑍ
PERFORM ERRCOD.  
ᑍ
ᑍ Move HOLD-JOB-QUEUE to HOLD so that we can display the value using  
ᑍ the command string.  
ᑍ
MOVE HOLD-JOB-QUEUE TO HOLD.  
ᑍ
ᑍ Let's tell everyone what the hold value was for this job.  
ᑍ
Appendix B. Original Examples in Additional Languages B-13  
Download from Www.Somanuals.com. All Manuals Search And Download.  
MOVE 51 TO COMMAND-LENGTH.  
CALL QCMDEXC USING COMMAND-STRING, COMMAND-LENGTH.  
ᑍ
ᑍ
STOP RUN.  
ᑍ End of Mainline  
ᑍ
ᑍ
ᑍ Subroutine to handle errors returned in the error code  
ᑍ parameter.  
ᑍ
ERRCOD.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð .13/  
ᑍ
ᑍ Process errors returned from the API.  
ᑍ
MOVE 65 TO COMMAND-LENGTH,  
MOVE EXCEPTION-ID TO MSGIDD,  
CALL QCMDEXC USING MESSAGE-TWO, COMMAND-LENGTH,  
STOP RUN.  
Retrieving the Hold Parameter (Error Code Structure)—ILE RPG  
Example  
Refer to “Retrieving the Hold Parameter (Error Code Structure)—OPM RPG  
Example” on page 3-11 for the original example.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Program Name: JOBDAPI  
Dᑍ  
Dᑍ Programming Language: ILE RPG  
Dᑍ  
Dᑍ Description: This program retrieves the HOLD value from  
Dᑍ  
Dᑍ  
Dᑍ  
a job description. It expects errors to be  
returned via the error code parameter.  
Dᑍ Header Files Included: QUSEC - Error Code Parameter  
Dᑍ  
QWDRJOBD - Retrieve Job Description API  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Error Code parameter include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC .14/  
Dᑍ  
Dᑍ Retrieve Job Description API Include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QWDRJOBD  
Dᑍ  
Dᑍ Command string data structure  
Dᑍ  
DCMD_STRING  
DS  
D
26  
1ð  
INZ('SNDMSG MSG(''HOLD value is ')  
D HOLD  
B-14 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
D
15  
43  
INZ(''') TOUSR(QPGMR)')  
DCMD_STR2  
DS  
D
D
INZ('SNDMSG MSG(''Program failed -  
with message ID ')  
D MSG_ID  
D
Dᑍ  
7
15  
INZ(''') TOUSR(QPGMR)')  
Dᑍ Miscellaneous data structure  
Dᑍ  
DRCVLEN  
DFORMAT  
DLENSTR  
DLENSTR2  
Cᑍ  
S
S
S
S
9B ð INZ(%SIZE(QWDDð1ðð))  
INZ('JOBDð1ðð')  
15 5 INZ(%SIZE(CMD_STRING))  
15 5 INZ(%SIZE(CMD_STR2))  
8
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Two parameters are being passed into this program  
Cᑍ  
C
ᑍENTRY  
PLIST  
PARM  
PARM  
C
JOBD  
JOBD_LIB  
1ð  
1ð  
C
Cᑍ  
Cᑍ Move the two parameters passed into LFNAM  
Cᑍ  
C
JOBD  
CAT  
JOBD_LIB  
LFNAM  
2ð  
Cᑍ  
Cᑍ Error Code Bytes Provided is set to 16  
Cᑍ  
C
EVAL  
QUSBPRV = %SIZE(QUSEC) .15/  
Cᑍ  
Cᑍ Call the API.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
QWDRJOBD  
QWDDð1ðð  
RCVLEN  
FORMAT  
LFNAM  
C
C
C
C
C
QUSEC  
Cᑍ  
Cᑍ Test for an error on the API call  
Cᑍ  
C
IF  
QUSBAVL > ð  
.13/  
Cᑍ  
Cᑍ If there was an error, exit to ERROR subroutine  
Cᑍ  
C
Cᑍ  
EXSR  
ERROR  
Cᑍ Else, process the HOLD value  
Cᑍ  
C
ELSE  
MOVEL  
C
QWDHJQ  
HOLD  
Cᑍ  
Cᑍ Let's tell everyone what the hold value was for this job  
Cᑍ  
C
C
C
C
CALL  
PARM  
PARM  
END  
'QCMDEXC'  
CMD_STRING  
LENSTR  
Appendix B. Original Examples in Additional Languages B-15  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
C
EVAL  
RETURN  
ᑍINLR = '1'  
C
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ Subroutine to handle errors received on the CALL  
Cᑍ  
C
Cᑍ  
ERROR  
BEGSR  
Cᑍ Process errors returned from the API  
Cᑍ  
C
C
C
C
C
MOVEL  
CALL  
PARM  
PARM  
ENDSR  
QUSEI  
MSG_ID  
'QCMDEXC'  
CMD_STR2  
LENSTR2  
Accessing the HOLD Attribute—ILE C Example  
Refer to “Accessing the HOLD Attribute—OPM RPG Example” on page 3-17 for  
the original example.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍProgram Name:  
/ᑍ  
JOBDAPI  
/ᑍProgramming Language: ILE C  
/ᑍ  
/ᑍDescription:  
This example shows how to print messages  
to spool files.  
/ᑍ  
/ᑍ  
/ᑍHeader Files Included: STDIO - Standard Input/Output  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
STRING - String Functions  
QUSEC - Error Code Parameter  
QWDRJOBD - Retrieve Job Description API  
QLIEPT - Entry Point Table  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <string.h>  
#include <qusec.h>  
#include <qwdrjobd.h>  
#include <qliept.h>  
/ᑍ Error Code Parameter Include for the APIs ᑍ/  
/ᑍ Retrieve Job Description API Include  
/ᑍ Entry Point Table Include  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Error Code Structure  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍ This shows how the user can define the variable length portion of ᑍ/  
/ᑍ error code for the exception data.  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
Qus_EC_t ec_fields;  
char  
Exception_Data[1ðð];  
B-16 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
} error_code_t;  
main(int argc, char ᑍargv[])  
{
error_code_t error_code;  
char  
char  
char  
char  
char  
char  
char  
FILE  
qual_job_desc[2ð];  
ᑍqual_job_ptr = qual_job_desc;  
rec_var[39ð];  
hold_value[1ð];  
message_id[7];  
command_string[25];  
message_string[29];  
ᑍstream;  
memset(hold_value, ' ', 1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Make sure we received the correct number of parameters. The argc ᑍ/  
/ᑍ parameter will contain the number of parameters that was passed ᑍ/  
/ᑍ to this program. This number also includes the program itself,  
/ᑍ so we need to evaluate argc-1.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if (((argc - 1) < 2) || ((argc - 1 > 2)))  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ We did not receive all of the required parameters so exit the  
/ᑍ program.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
{
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Move the two parameter passed into qual_job_desc.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(qual_job_ptr, argv[1], 1ð);  
qual_job_ptr += 1ð;  
memcpy(qual_job_ptr, argv[2], 1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the error code parameter to 16.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.ec_fields.Bytes_Provided = 16;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Open QPRINT file so that data can be written to it. If the file ᑍ/  
/ᑍ cannot be opened, print a message and exit.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if((stream = fopen("QPRINT", "wb")) == NULL)  
{
printf("File could not be opened\n");  
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the QWDRJOBD API.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QWDRJOBD(rec_var, /ᑍ Receiver Variable ᑍ/  
Appendix B. Original Examples in Additional Languages B-17  
Download from Www.Somanuals.com. All Manuals Search And Download.  
39ð,  
/ᑍ Receiver Length  
/ᑍ Format Name  
/ᑍ Qualified Job Description  
/ᑍ Error Code  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
"JOBDð1ðð",  
qual_job_desc,  
&error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If an error was returned, print the error message to the QPRINT ᑍ/  
/ᑍ spool file.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if(error_code.ec_fields.Bytes_Available > ð)  
{
memcpy(message_id, error_code.ec_fields.Exception_Id, 7);  
sprintf(message_string,  
"Failed. Error ID - %.7s",  
message_id);  
fprintf(stream, message_string);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Let's tell everyone what the hold value was for this job.  
/ᑍ The result will be printed in the QPRINT spool file.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
else  
{
memcpy(hold_value, ((Qwd_JOBDð1ðð_t ᑍ)rec_var)->Hold_Job_Queue, 1ð);  
sprintf(command_string,  
"HOLD value - %.1ðs",  
hold_value);  
fprintf(stream, command_string);  
}
fclose(stream);  
} /ᑍ main ᑍ/  
Accessing the HOLD Attribute—ILE COBOL Example  
Refer to “Accessing the HOLD Attribute—OPM RPG Example” on page 3-17 for  
the original example. The following example also works for OPM COBOL.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name:  
ᑍ
JOBDAPI  
ᑍProgramming Language: COBOL  
ᑍ
ᑍDescription:  
This example shows how to print messages  
to spool files.  
ᑍ
ᑍ
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍ
QWDRJOBD - Retrieve Job Description API  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PROGRAM-ID. JOBDAPI.  
ᑍ
B-18 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
ᑍ
ᑍ
ᑍ
ᑍ
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
ᑍ
ᑍ
WORKING-STORAGE SECTION.  
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Retrieve Job Description API Include  
ᑍ
COPY QWDRJOBD OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Command String Data Structure  
ᑍ
ð1 HOLD-VALUE.  
ð5 TEXT1 PIC X(13) VALUE 'HOLD value - '.  
ð5 HOLD PIC X(1ð).  
ᑍ
ᑍ Error Message Text  
ᑍ
ð1 MESSAGE-TEXT.  
ð5 MSG1 PIC X(19) VALUE 'Failed. Error ID - '.  
ð5 MSGID PIC X(7).  
ᑍ
ð1 RECEIVER-LENGTH PIC S9(9) COMP-4.  
ð1 FORMAT-NAME PIC X(8) VALUE 'JOBDð1ðð'.  
ð1 QCMDEXC PIC X(1ð) VALUE 'QCMDEXC'.  
ᑍ
ᑍ Job Description and Library Name Structure  
ᑍ
ð1 JOBD-AND-LIB-NAME.  
ð5 JOB-DESC PIC X(1ð).  
ð5 JOB-DESC-LIB PIC X(1ð).  
ᑍ
LINKAGE SECTION.  
Appendix B. Original Examples in Additional Languages B-19  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ Two Parameters are being passed into this program.  
ᑍ
ð1 JOBD PIC X(1ð).  
ð1 JOBDL PIC X(1ð).  
ᑍ
PROCEDURE DIVISION USING JOBD, JOBDL.  
MAIN-LINE.  
ᑍ
ᑍ Beginning of Mainline  
ᑍ
ᑍ Move the two parameters passed into JOB-DESC and JOB-DESC-LIB.  
ᑍ
MOVE JOBD TO JOB-DESC.  
MOVE JOBDL TO JOB-DESC-LIB.  
ᑍ
ᑍ Error Code Parameter is set to 16.  
ᑍ
MOVE 16 TO BYTES-PROVIDED.  
ᑍ
ᑍ Receiver Length Set to 39ð.  
ᑍ
MOVE 39ð TO RECEIVER-LENGTH.  
ᑍ
ᑍ Call the QWDRJOBD API.  
ᑍ
CALL QWDRJOBD USING QWD-JOBDð1ðð, RECEIVER-LENGTH,  
FORMAT-NAME, JOBD-AND-LIB-NAME, QUS-EC.  
ᑍ
ᑍ If no bytes available, API was successful; print HOLD value  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC = ð PERFORM GOOD.  
ᑍ
ᑍ If some bytes available, API failed; print Error message ID  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð PERFORM BAD.  
ᑍ
STOP RUN.  
ᑍ
ᑍ End of Mainline  
ᑍ
ᑍ
ᑍ Subroutine to perform if no errors were encountered.  
ᑍ
GOOD.  
OPEN OUTPUT LISTING.  
MOVE HOLD-JOB-QUEUE TO HOLD.  
WRITE LIST-LINE FROM HOLD-VALUE.  
ᑍ
ᑍ Subroutine to perform if an error was returned in error code.  
ᑍ
BAD.  
OPEN OUTPUT LISTING.  
MOVE EXCEPTION-ID TO MSGID.  
B-20 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
WRITE LIST-LINE FROM MESSAGE-TEXT.  
STOP RUN.  
Accessing the HOLD Attribute—ILE RPG Example  
Refer to “Accessing the HOLD Attribute—OPM RPG Example” on page 3-17 for  
the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program Name: JOBDAPI  
Fᑍ  
Fᑍ Programming Language: ILE RPG  
Fᑍ  
Fᑍ Description: This program retrieves the HOLD value from  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
a job description and then prints the value.  
It expects errors to be returned via the  
error code parameter.  
Fᑍ Header Files Included: QUSEC - Error Code Parameter  
Fᑍ  
QWDRJOBD - Retrieve Job Description API  
Fᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQPRINT  
Dᑍ  
O
F 132  
PRINTER OFLIND(ᑍINOF)  
Dᑍ Error Code parameter include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
Dᑍ Retrieve Job Description API Include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QWDRJOBD  
Dᑍ  
Dᑍ Miscellaneous data structure  
Dᑍ  
DRCVLEN  
DFORMAT  
Cᑍ  
S
S
9B ð INZ(%SIZE(QWDDð1ðð))  
INZ('JOBDð1ðð')  
8
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Two parameters are being passed into this program  
Cᑍ  
C
ᑍENTRY  
PLIST  
PARM  
PARM  
C
JOBD  
JOBD_LIB  
1ð  
1ð  
C
Cᑍ  
Cᑍ Move the two parameters passed into LFNAM  
Cᑍ  
C
JOBD  
CAT  
JOBD_LIB  
LFNAM  
2ð  
Cᑍ  
Cᑍ Error Code Bytes Provided is set to 16  
Cᑍ  
C
EVAL  
QUSBPRV = %SIZE(QUSEC)  
Cᑍ  
Cᑍ Call the API.  
Appendix B. Original Examples in Additional Languages B-21  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
QWDRJOBD  
C
QWDDð1ðð  
RCVLEN  
FORMAT  
LFNAM  
C
C
C
C
QUSEC  
Cᑍ  
Cᑍ If no bytes available, API was successful; print HOLD value  
Cᑍ  
C
IF  
EXCEPT  
ELSE  
QUSBAVL = ð  
GOOD  
C
C
Cᑍ  
Cᑍ If some bytes available, API failed; print Error message ID  
Cᑍ  
C
IF  
QUSBAVL > ð  
BAD  
C
EXCEPT  
END  
C
C
Cᑍ  
END  
Cᑍ End of program  
Cᑍ  
C
C
Cᑍ  
EVAL  
RETURN  
ᑍINLR = '1'  
Cᑍ End of MAINLINE  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Oᑍ  
OQPRINT  
E
GOOD  
1 6  
O
'HOLD value - '  
O
QWDHJQ  
BAD  
OQPRINT  
E
1 6  
O
O
'Failed. Error ID - '  
QUSEI  
Accessing a Field Value (Initial Library List)—ILE C Example  
Refer to “Accessing a Field Value (Initial Library List)—OPM RPG Example” on  
page 3-19 for the original example.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍProgram Name:  
/ᑍ  
JOBDAPI  
/ᑍProgramming Language: ILE C  
/ᑍ  
/ᑍDescription:  
This example shows how to access a field  
value returned from a retrieve API.  
/ᑍ  
/ᑍ  
/ᑍHeader Files Included: STDIO - Standard Input/Output  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
STRING - String Functions  
QUSEC - Error Code Parameter  
QWDRJOBD - Retrieve Job Description API  
QLIEPT - Entry Point Table  
B-22 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <string.h>  
#include <qusec.h>  
#include <qwdrjobd.h>  
#include <qliept.h>  
/ᑍ Error Code Parameter Include for the APIs ᑍ/  
/ᑍ Retrieve Job Description API Include  
/ᑍ Entry Point Table Include  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Error Code Structure  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍ This shows how the user can define the variable-length portion of ᑍ/  
/ᑍ error code for the exception data.  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
Qus_EC_t ec_fields;  
char  
Exception_Data[1ðð]; .7/  
} error_code_t;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ JOBDð1ðð Structure  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍ This shows how the user can define the variable-length portion of ᑍ/  
/ᑍ the JOBDð1ðð format.  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
Qwd_JOBDð1ðð_t data;  
char  
} JOBDð1ðð;  
Lib_Data[61ð]; .19/ .2ð/  
main(int argc, char ᑍargv[])  
{
error_code_t error_code;  
char  
char  
char  
char  
char  
char  
char  
char  
int  
library[1ð];  
qual_job_desc[2ð];  
ᑍqual_job_ptr = qual_job_desc;  
rec_var[1ððð];  
ᑍrec_ptr = rec_var;  
hold_value[1ð];  
message_id[7];  
command_string[49];  
i;  
int  
num_libs;  
int  
offset;  
int  
rec_len = 1ððð;  
memset(hold_value, ' ', 1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Make sure we received the correct number of parameters. The argc ᑍ/  
/ᑍ parameter will contain the number of parameters that was passed ᑍ/  
/ᑍ to this program. This number also includes the program itself,  
/ᑍ so we need to evaluate argc-1.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
Appendix B. Original Examples in Additional Languages B-23  
Download from Www.Somanuals.com. All Manuals Search And Download.  
if (((argc - 1) < 2) || ((argc - 1 > 2)))  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ We did not receive all of the required parameters so exit the  
/ᑍ program.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
{
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Move the two parameter passed into qual_job_desc.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(qual_job_ptr, argv[1], 1ð);  
qual_job_ptr += 1ð;  
memcpy(qual_job_ptr, argv[2], 1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set the error code parameter to 16.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.ec_fields.Bytes_Provided = 16;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call the QWDRJOBD API.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QWDRJOBD(rec_var,  
rec_len,  
/ᑍ Receiver Variable  
/ᑍ Receiver Length  
/ᑍ Format Name  
/ᑍ Qualified Job Description  
/ᑍ Error Code  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
"JOBDð1ðð",  
qual_job_desc,  
&error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If an error was returned, send an error message.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if(error_code.ec_fields.Bytes_Available > ð)  
{
/ᑍ In this example, nothing was done for the error condition.  
ᑍ/  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Let's tell everyone what the library value was for this job.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
else  
{
num_libs = ((JOBDð1ðð ᑍ)rec_var)->data.Number_Libs_In_Lib_list;  
offset = ((JOBDð1ðð ᑍ)rec_var)->data.Offset_Initial_Lib_List;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Advance receiver variable pointer to the location where the  
/ᑍ library list begins.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
rec_ptr += offset;  
for(i=ð; i<num_libs; i++)  
{
memcpy(library, rec_ptr, 1ð);  
sprintf(command_string,  
"SNDMSG MSG('LIBRARY %.1ðs') TOUSR(QPGMR)",  
library);  
system(command_string);  
B-24 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
rec_ptr += 11;  
if((offset + 1ð) >= rec_len)  
break;  
offset += 11;  
}
}
} /ᑍ main ᑍ/  
Accessing a Field Value (Initial Library List)—ILE COBOL Example  
Refer to “Accessing a Field Value (Initial Library List)—OPM RPG Example” on  
page 3-19 for the original example. The following program also works for OPM  
COBOL.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name:  
ᑍ
JOBDAPI  
ᑍProgramming Language: COBOL  
ᑍ
ᑍDescription:  
This example shows how to access a  
field value returned from a retrieve  
API.  
ᑍ
ᑍ
ᑍ
ᑍHeader Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍ
QWDRJOBD - Retrieve Job Description API  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PROGRAM-ID. JOBDAPI.  
ᑍ
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
ᑍ
DATA DIVISION.  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Retrieve Job Description API Include  
ᑍ
ᑍ The header file for the QWDRJOBD API was included in this  
Appendix B. Original Examples in Additional Languages B-25  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ program so that the varying length portion of the structure  
ᑍ can be defined as a fixed portion.  
ᑍ
ᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍHeader File Name: H/QWDRJOBD  
ᑍ
ᑍDescriptive Name: Retrieve Job Description Information API  
ᑍ
ᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994  
ᑍAll rights reserved.  
ᑍUS Government Users Restricted Rights -  
ᑍUse, duplication or disclosure restricted  
ᑍby GSA ADP Schedule Contract with IBM Corp.  
ᑍ
ᑍLicensed Materials-Property of IBM  
ᑍ
ᑍ
ᑍDescription: The Retrieve Job Description Information API  
ᑍ
ᑍ
ᑍ
ᑍ
retrieves information from a job description  
object and places it into a single variable in the  
calling program.  
ᑍHeader Files Included: None.  
ᑍ
ᑍMacros List: None.  
ᑍ
ᑍStructure List: Qwd_JOBDð1ðð_t  
ᑍ
ᑍFunction Prototype List: QWDRJOBD  
ᑍ
ᑍChange Activity:  
ᑍ
ᑍCFD List:  
ᑍ
ᑍFLAG REASON  
LEVEL DATE PGMR  
CHANGE DESCRIPTION  
ᑍ---- ------------ ----- ------ --------- ----------------------  
ᑍ$Að= D2862ððð  
ᑍ
3D1ð 94ð424 ROCH:  
New Include  
ᑍEnd CFD List.  
ᑍ
ᑍAdditional notes about the Change Activity  
ᑍEnd Change Activity.  
ᑍ
ᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍPrototype for QWDRJOBD API  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
77 QWDRJOBD  
PIC X(ððð1ð)  
VALUE "QWDRJOBD".  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍType Definition for the JOBDð1ðð format.  
ᑍᑍᑍᑍ  
ᑍᑍᑍ  
ᑍNOTE: The following type definition defines only the fixed  
ᑍ portion of the format. Any varying length field will  
ᑍ have to be defined by the user.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ð1 RECEIVER-VARIABLE PIC X(ð1ððð).  
B-26 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ð1 QWD-JOBDð1ðð REDEFINES RECEIVER-VARIABLE.  
ð5 BYTES-RETURNED  
PIC S9(ðððð9) BINARY.  
PIC S9(ðððð9) BINARY.  
PIC X(ððð1ð).  
ð5 BYTES-AVAILABLE  
ð5 JOB-DESCRIPTION-NAME  
ð5 JOB-DESCRIPTION-LIB-NAME  
ð5 USER-NAME  
PIC X(ððð1ð).  
PIC X(ððð1ð).  
ð5 JOB-DATE  
PIC X(ðððð8).  
ð5 JOB-SWITCHES  
ð5 JOB-QUEUE-NAME  
PIC X(ðððð8).  
PIC X(ððð1ð).  
ð5 JOB-QUEUE-LIB-NAME  
ð5 JOB-QUEUE-PRIORITY  
ð5 HOLD-JOB-QUEUE  
ð5 OUTPUT-QUEUE-NAME  
ð5 OUTPUT-QUEUE-LIB-NAME  
ð5 OUTPUT-QUEUE-PRIORITY  
ð5 PRINTER-DEVICE-NAME  
ð5 PRINT-TEXT  
PIC X(ððð1ð).  
PIC X(ðððð2).  
PIC X(ððð1ð).  
PIC X(ððð1ð).  
PIC X(ððð1ð).  
PIC X(ðððð2).  
PIC X(ððð1ð).  
PIC X(ððð3ð).  
ð5 SYNTAX-CHECK-SEVERITY  
ð5 END-SEVERITY  
ð5 MESSAGE-LOG-SEVERITY  
ð5 MESSAGE-LOG-LEVEL  
ð5 MESSAGE-LOG-TEXT  
ð5 LOG-CL-PROGRAMS  
ð5 INQUIRY-MESSAGE-REPLY  
ð5 DEVICE-RECOVERY-ACTION  
ð5 TIME-SLICE-END-POOL  
ð5 ACCOUNTING-CODE  
PIC S9(ðððð9) BINARY.  
PIC S9(ðððð9) BINARY.  
PIC S9(ðððð9) BINARY.  
PIC X(ðððð1).  
PIC X(ððð1ð).  
PIC X(ððð1ð).  
PIC X(ððð1ð).  
PIC X(ððð13).  
PIC X(ððð1ð).  
PIC X(ððð15).  
ð5 ROUTING-DATA  
ð5 TEXT-DESCRIPTION  
ð5 RESERVED  
PIC X(ððð8ð).  
PIC X(ððð5ð).  
PIC X(ðððð1).  
ð5 OFFSET-INITIAL-LIB-LIST  
ð5 NUMBER-LIBS-IN-LIB-LIST  
ð5 OFFSET-REQUEST-DATA  
ð5 LENGTH-REQUEST-DATA  
ð5 JOB-MESSAGE-QUEUE-MAX-SIZE  
ð5 JOB-MESSAGE-QUEUE-FULL-ACTION  
ð5 RESERVED2  
PIC S9(ðððð9) BINARY. .19/  
PIC S9(ðððð9) BINARY. .2ð/  
PIC S9(ðððð9) BINARY.  
PIC S9(ðððð9) BINARY.  
PIC S9(ðððð9) BINARY.  
PIC X(ððð1ð).  
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
PIC X(ðððð1).  
Varying length  
ð5 INITIAL-LIB-LIST  
PIC X(ððð11).  
PIC X(ðððð1).  
Varying length  
ð5 REQUEST-DATA  
Varying length  
ᑍ Command String Data Structure  
ᑍ
ð1 COMMAND-STRING.  
ð5 TEXT1 PIC X(22) VALUE 'SNDMSG MSG(''LIBRARY- '.  
ð5 LIB PIC X(1ð).  
ð5 TEXT2 PIC X(15) VALUE ''') TOUSR(QPGMR)'.  
ᑍ
ð1 COMMAND-LENGTH PIC S9(1ð)V99999 COMP-3.  
ð1 RECEIVER-LENGTH PIC S9(9) COMP-4.  
ð1 FORMAT-NAME PIC X(8) VALUE 'JOBDð1ðð'.  
ð1 QCMDEXC PIC X(1ð) VALUE 'QCMDEXC'.  
Appendix B. Original Examples in Additional Languages B-27  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ð1 X PIC S9(9) BINARY.  
ᑍ
ᑍ Job Description and Library Name Structure  
ᑍ
ð1 JOBD-AND-LIB-NAME.  
ð5 JOB-DESC PIC X(1ð).  
ð5 JOB-DESC-LIB PIC X(1ð).  
ᑍ
LINKAGE SECTION.  
ᑍ
ᑍ Two Parameters are being passed into this program.  
ᑍ
ð1 JOBD PIC X(1ð).  
ð1 JOBDL PIC X(1ð).  
ᑍ
PROCEDURE DIVISION USING JOBD, JOBDL.  
MAIN-LINE.  
ᑍ
ᑍ Beginning of Mainline  
ᑍ
ᑍ Move the two parameters passed into JOB-DESC and JOB-DESC-LIB.  
ᑍ
MOVE JOBD TO JOB-DESC.  
MOVE JOBDL TO JOB-DESC-LIB.  
ᑍ
ᑍ Error Code Parameter is set to 1ðð.  
ᑍ
MOVE 1ðð TO BYTES-PROVIDED.  
ᑍ
ᑍ Receiver Length Set to 1ððð.  
ᑍ
MOVE 1ððð TO RECEIVER-LENGTH.  
ᑍ
ᑍ Call the QWDRJOBD API.  
ᑍ
CALL QWDRJOBD USING RECEIVER-VARIABLE, RECEIVER-LENGTH,  
FORMAT-NAME, JOBD-AND-LIB-NAME, QUS-EC.  
ᑍ
ᑍ See if any errors were returned in the error code parameter.  
ᑍ
PERFORM ERRCOD.  
ᑍ
ᑍ Add one to the Initial library list offset because COBOL is a  
ᑍ Base 1 language.  
ᑍ
MOVE OFFSET-INITIAL-LIB-LIST TO X.  
ADD 1 TO X.  
MOVE 47 TO COMMAND-LENGTH.  
ᑍ
ᑍ Let's tell everyone what the library value was for this job.  
ᑍ
PERFORM NUMBER-LIBS-IN-LIB-LIST TIMES  
MOVE RECEIVER-VARIABLE(X:1ð) TO LIB,  
CALL QCMDEXC USING COMMAND-STRING, COMMAND-LENGTH,  
ADD 11 TO X,  
PERFORM RECLEN,  
END-PERFORM.  
B-28 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ
STOP RUN.  
ᑍ End of Mainline  
ᑍ
ᑍ
ᑍ Subroutine to handle errors returned in the error code  
ᑍ parameter.  
ᑍ
ERRCOD.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
ᑍ
ᑍ Process errors returned from the API.  
ᑍ
STOP RUN.  
ᑍ
ᑍ Subroutine to check to see if there is enough room in the  
ᑍ receiver variable for the next library in the list.  
ᑍ
RECLEN.  
ᑍ
IF (X + 1ð) >= RECEIVER-LENGTH  
STOP RUN.  
Accessing a Field Value (Initial Library List)—ILE RPG Example  
Refer to “Accessing a Field Value (Initial Library List)—OPM RPG Example” on  
page 3-19 for the original example.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Program Name: JOBDAPI  
Dᑍ  
Dᑍ Programming Language: ILE RPG  
Dᑍ  
Dᑍ Description: This program retrieves the library list from  
Dᑍ  
Dᑍ  
Dᑍ  
a job description. It expects errors to be  
returned via the error code parameter.  
Dᑍ Header Files Included: QUSEC - Error Code Parameter  
Dᑍ  
Dᑍ Header Files Modified: QWDRJOBD - Retrieve Job Description API  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Error Code parameter include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
Dᑍ The following QWDRJOBD include from QSYSINC is copied into  
Dᑍ this program so that it can be declared as 1ððð bytes in  
Dᑍ size. This size should accommodate the variable length Library  
Dᑍ List array.  
Dᑍ  
Appendix B. Original Examples in Additional Languages B-29  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
DᑍHeader File Name: H/QWDRJOBD  
Dᑍ  
DᑍDescriptive Name: Retrieve Job Description Information API  
Dᑍ  
Dᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994  
DᑍAll rights reserved.  
DᑍUS Government Users Restricted Rights -  
DᑍUse, duplication or disclosure restricted  
Dᑍby GSA ADP Schedule Contract with IBM Corp.  
Dᑍ  
DᑍLicensed Materials-Property of IBM  
Dᑍ  
Dᑍ  
DᑍDescription: The Retrieve Job Description Information API  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
retrieves information from a job description  
object and places it into a single variable in the  
calling program.  
DᑍHeader Files Included: None.  
Dᑍ  
DᑍMacros List: None.  
Dᑍ  
DᑍStructure List: Qwd_JOBDð1ðð_t  
Dᑍ  
DᑍFunction Prototype List: QWDRJOBD  
Dᑍ  
DᑍChange Activity:  
Dᑍ  
DᑍCFD List:  
Dᑍ  
DᑍFLAG REASON  
LEVEL DATE PGMR  
CHANGE DESCRIPTION  
Dᑍ---- ------------ ----- ------ --------- ----------------------  
Dᑍ$Að= D2862ððð  
Dᑍ  
3D1ð 94ð424 ROCH:  
New Include  
DᑍEnd CFD List.  
Dᑍ  
DᑍAdditional notes about the Change Activity  
DᑍEnd Change Activity.  
Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍPrototype for QWDRJOBD API  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
D QWDRJOBD  
C
'QWDRJOBD'  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍType Definition for the JOBDð1ðð format.  
Dᑍᑍᑍᑍ  
ᑍᑍᑍ  
DᑍNOTE: The following type definition defines only the fixed  
Dᑍ portion of the format. Any varying length field will  
Dᑍ have to be defined by the user.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQWDDð1ðð  
Dᑍ  
D QWDBRTN  
Dᑍ  
D QWDBAVL  
Dᑍ  
DS  
1ððð  
4B ð  
8B ð  
Qwd JOBDð1ðð  
1
5
Bytes Returned  
Bytes Available  
B-30 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
D QWDJDN  
Dᑍ  
D QWDJDLN  
Dᑍ  
D QWDUN  
Dᑍ  
D QWDJD  
Dᑍ  
D QWDJS  
Dᑍ  
D QWDJQNðð  
Dᑍ  
D QWDJQLNðð  
Dᑍ  
D QWDJQP  
Dᑍ  
D QWDHJQ  
Dᑍ  
D QWDOQN  
Dᑍ  
D QWDOQLN  
Dᑍ  
D QWDOQP  
Dᑍ  
D QWDPDN  
Dᑍ  
D QWDPT  
Dᑍ  
D QWDSCS  
Dᑍ  
D QWDES  
Dᑍ  
D QWDMLS  
Dᑍ  
D QWDMLL  
Dᑍ  
D QWDMLT  
Dᑍ  
D QWDLCLP  
Dᑍ  
D QWDIMR  
Dᑍ  
D QWDDRA  
Dᑍ  
D QWDTSEP  
Dᑍ  
D QWDAC  
Dᑍ  
D QWDRD  
Dᑍ  
D QWDTD  
Dᑍ  
D QWDERVEDðð  
Dᑍ  
D QWDOILL  
Dᑍ  
9
19  
18  
Job Description Name  
Job Description Lib Name  
User Name  
28  
29  
38  
39  
46  
Job Date  
47  
54  
Job Switches  
55  
64  
Job Queue Name  
65  
74  
Job Queue Lib Name  
Job Queue Priority  
Hold Job Queue  
75  
76  
77  
86  
87  
96  
Output Queue Name  
Output Queue Lib Name  
Output Queue Priority  
Printer Device Name  
Print Text  
97  
1ð6  
1ð7  
1ð9  
119  
149  
153  
157  
161  
162  
172  
182  
192  
2ð5  
215  
23ð  
31ð  
36ð  
361  
365  
1ð8  
118  
148  
152B ð  
156B ð  
16ðB ð  
161  
Syntax Check Severity  
End Severity  
Message Log Severity  
Message Log Level  
Message Log Text  
Log CL Programs  
171  
181  
191  
Inquiry Message Reply  
Device Recovery Action  
Time Slice End Pool  
Accounting Code  
2ð4  
214  
229  
3ð9  
Routing Data  
359  
Text Description  
Reserved  
36ð  
364B ð .19/  
368B ð .2ð/  
Offset Initial Lib List  
Number Libs In Lib list  
D QWDNLILL  
Dᑍ  
Appendix B. Original Examples in Additional Languages B-31  
Download from Www.Somanuals.com. All Manuals Search And Download.  
D QWDORD  
369  
373  
377  
381  
391  
372B ð  
376B ð  
38ðB ð  
39ð  
Dᑍ  
Offset Request Data  
D QWDLRD  
Dᑍ  
Length Request Data  
D QWDJMQMS  
Dᑍ  
Job Message Queue Max Size  
Job Msg Queue Full Action  
D QWDJMQFA  
Dᑍ  
DᑍQWDRSV2  
391  
Dᑍ  
Dᑍ  
Varying length  
4ð2  
DᑍQWDILL  
392  
4ð3  
DIM(ðððð1)  
Dᑍ  
Dᑍ  
Varying length  
DᑍQWDRDðð  
4ð3  
Dᑍ  
Dᑍ  
Dᑍ  
Varying length  
Dᑍ Command string data structure  
Dᑍ  
DCMD_STRING  
DS  
D
22  
1ð  
15  
INZ('SNDMSG MSG(''LIBRARY - ')  
INZ(''') TOUSR(QPGMR)')  
D LIBRARY  
D
Dᑍ  
Dᑍ Miscellaneous data structure  
Dᑍ  
DRCVLEN  
DFORMAT  
DLENSTR  
Cᑍ  
S
S
S
9B ð INZ(%SIZE(QWDDð1ðð))  
INZ('JOBDð1ðð')  
15 5 INZ(%SIZE(CMD_STRING))  
8
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Two parameters are being passed into this program  
Cᑍ  
C
ᑍENTRY  
PLIST  
PARM  
PARM  
C
JOBD  
JOBD_LIB  
1ð  
1ð  
C
Cᑍ  
Cᑍ Move the two parameters passed into LFNAM  
Cᑍ  
C
JOBD  
CAT  
JOBD_LIB  
LFNAM  
2ð  
Cᑍ  
Cᑍ Error Code Bytes Provided is set to 16  
Cᑍ  
C
EVAL  
QUSBPRV = %SIZE(QUSEC)  
Cᑍ  
Cᑍ Call the API.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
QWDRJOBD  
QWDDð1ðð  
RCVLEN  
FORMAT  
LFNAM  
C
C
C
C
C
QUSEC  
Cᑍ  
Cᑍ Test for an error on the API call  
Cᑍ  
B-32 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
Cᑍ  
IF  
QUSBAVL > ð  
Cᑍ If there was an error, exit to ERROR subroutine  
Cᑍ  
C
EXSR  
ELSE  
ERROR  
C
Cᑍ  
Cᑍ Else, add 1 to the Initial library list offset because RPG  
Cᑍ is a Base 1 language  
Cᑍ  
C
QWDOILL  
ADD  
DO  
1
X
5 ð  
C
C
QWDNLILL  
EVAL  
LIBRARY = %SUBST(QWDDð1ðð:X:1ð)  
Cᑍ  
Cᑍ Let's tell everyone what the library value is  
Cᑍ  
C
CALL  
PARM  
PARM  
ADD  
'QCMDEXC'  
C
CMD_STRING  
LENSTR  
X
C
C
11  
C
IF  
(X + 1ð) > RCVLEN  
C
LEAVE  
ENDIF  
ENDDO  
ENDIF  
C
C
C
Cᑍ  
C
C
EVAL  
RETURN  
ᑍINLR = '1'  
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ Subroutine to handle errors returned in the error code parameter  
Cᑍ  
C
Cᑍ  
ERROR  
BEGSR  
Cᑍ Process errors returned from the API. As this sample program  
Cᑍ used /COPY to include the error code structure, only the first  
Cᑍ 16 bytes of the error code structure are available. If the  
Cᑍ application program needed to access the variable length  
Cᑍ exception data for the error, the developer should physically  
Cᑍ copy the QSYSINC include and modify the copied include to  
Cᑍ define additional storage for the exception data.  
Cᑍ  
C
ENDSR  
Using Keys with List Spooled Files API—ILE C Example  
Refer to “Using Keys with List Spooled Files API—Example” on page 3-24 for the  
original example.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Program:  
List Spooled Files for Current User  
ILE C  
/ᑍ  
/ᑍ Language:  
/ᑍ  
/ᑍ Description: This example shows the steps necessary to  
/ᑍ process keyed output from an API  
Appendix B. Original Examples in Additional Languages B-33  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ APIs Used:  
QUSLSPL - List Spooled Files  
/ᑍ  
/ᑍ  
/ᑍ  
QUSCRTUS - Create User Space  
QUSPTRUS - Retrieve Pointer to User Space  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <string.h>  
#include <quslspl.h>  
#include <quscrtus.h>  
#include <qusptrus.h>  
#include <qusgen.h>  
#include <qusec.h>  
#include <qliept.h>  
/ᑍ QUSLSPL API header  
/ᑍ QUSCRTUS API header  
/ᑍ QUSPTRUS API header  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Format Structures for User Space .11/ ᑍ/  
/ᑍ Error Code parameter include for APIs ᑍ/  
/ᑍ Entry Point Table include for APIs  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Global variables ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
char  
int  
char  
char  
int  
spc_name[2ð] = "SPCNAME QTEMP  
spc_size = 2ððð;  
";  
spc_init = ðxðð;  
ᑍspcptr, ᑍlstptr, ᑍlstptr2;  
pages;  
struct keys { int key1;  
int key2;  
.7/  
.8/  
int key3;} keys = {2ð1, 211, 216};  
number_of_keys = 3;  
ext_attr[1ð] = "QUSLSPL ";  
spc_aut[1ð] = "ᑍALL  
spc_text[5ð] = "  
spc_replac[1ð] = "ᑍYES  
spc_domain[1ð] = "ᑍUSER  
format[8] = "SPLFð2ðð";  
usr_prf[1ð] = "ᑍCURRENT ";  
outq[2ð] = "ᑍALL  
int  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
";  
";  
";  
";  
.4/  
";  
formtyp[1ð] = "ᑍALL  
usrdta[1ð] = "ᑍALL  
jobnam[26] = "  
prtfil[1ð];  
";  
";  
";  
opndat[7];  
typedef struct {  
Qus_LSPL_Key_Info_t Key_Info;  
char  
} var_record_t;  
Data_Field[1ðð];  
Qus_EC_t error_code;  
int  
i, j;  
char  
FILE  
prtlin[1ðð];  
ᑍrecord;  
main()  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Open print file for report  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
ᑍ/  
if((record = fopen("QPRINT", "wb, lrecl=132, type=record")) == NULL)  
{ printf("File QPRINT could not be opened\n");  
B-34 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
exit();  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set Error Code structure to use exceptions ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.Bytes_Provided = ð;  
.1/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Create a User Space for the List generated by QUSLSPL ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSCRTUS(spc_name,  
ext_attr,  
/ᑍ User space name and library .2/ ᑍ/  
/ᑍ Extended attribute  
/ᑍ Initial space size  
/ᑍ Initialize value for space  
/ᑍ Public authorization  
/ᑍ Text description  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
spc_size,  
&spc_init,  
spc_aut,  
spc_text,  
spc_replac,  
error_code,  
spc_domain);  
/ᑍ Replace option  
/ᑍ Error code structure  
/ᑍ Domain of space  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call QUSLSPL to get all spooled files for ᑍCURRENT user ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSLSPL( spc_name,  
format,  
/ᑍ User space name and library .3/ ᑍ/  
/ᑍ API format  
/ᑍ User profile  
/ᑍ Output Queue  
/ᑍ Form type  
.4/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
usr_prf,  
outq,  
formtyp,  
usrdta,  
error_code,  
jobnam,  
keys,  
/ᑍ User data  
/ᑍ Error code structure  
/ᑍ Job name  
/ᑍ Keys to return  
.5/  
.6/  
number_of_keys); /ᑍ Number of keys  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Get a resolved pointer to the User Space ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSPTRUS(spc_name,  
&spcptr,  
/ᑍ User space name and library .9/ ᑍ/  
/ᑍ Space pointer  
ᑍ/  
ᑍ/  
error_code);  
/ᑍ Error code structure  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If valid information returned  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if(memcmp\  
(((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)->Structure_Release_Level, .12/  
"ð1ðð", 4) != ð) { printf("Unknown Generic Header"); .13/  
exit();  
}
if((((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)->Information_Status=='C')\ .14/  
|| (((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)->Information_Status\  
== 'P'))  
Appendix B. Original Examples in Additional Languages B-35  
Download from Www.Somanuals.com. All Manuals Search And Download.  
{
if(((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)->Number_List_Entries\ .16/  
> ð)  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ address current list entry  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
{
lstptr = spcptr + (((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)\  
->Offset_List_Data);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ process all the entries  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
for(i = ð; i < (((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)\ .2ð/  
->Number_List_Entries); i++)  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ set lstptr2 to first variable length record for this entry ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
lstptr2 = lstptr + 4;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ process all the variable length records for this entry  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
for(j = ð; j < (((Qus_SPLFð2ðð_t ᑍ)lstptr)\ .22/.23/  
->Num_Fields_Retd); j++)  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ extract spooled file name for report  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if((((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\ .24/.25/  
->Key_Field_for_Field_Retd) == 2ð1)  
{ memcpy(prtfil, "  
", 1ð);  
memcpy(prtfil, (((var_record_t ᑍ)\  
lstptr2)->Data_Field),  
(((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\  
->Data_Length));  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ extract number of pages for report  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if((((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\ .24/.25/  
->Key_Field_for_Field_Retd) == 211)  
{ memcpy(&pages, (((var_record_t ᑍ)\  
lstptr2)->Data_Field),  
(((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\  
->Data_Length));  
}
B-36 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ extract age of spooled file for report  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if((((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\ .24/.25/  
->Key_Field_for_Field_Retd) == 216)  
{ memcpy(opndat, "  
", 7);  
memcpy(opndat, (((var_record_t ᑍ)\  
lstptr2)->Data_Field),  
(((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\  
->Data_Length));  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ bump lstptr2 to next variable length record  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
lstptr2 = lstptr2 +  
(((Qus_LSPL_Key_Info_t ᑍ)lstptr2)\  
->Len_Field_Info_Retd);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ print collected information  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
sprintf(prtlin, "%.1ðs  
%.1ðd  
%.7s", .26/  
prtfil, pages, opndat);  
fwrite(prtlin, 1, 1ðð, record);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ bump lstptr to next list entry  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
lstptr += (((Qus_Generic_Header_ð1ðð_t ᑍ)spcptr)\ .27/  
->Size_Each_Entry);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ exit at end of list  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
fclose(record);  
exit();  
}
}
else  
{ printf("List data not valid");  
.15/  
.28/  
exit();  
}
}
Appendix B. Original Examples in Additional Languages B-37  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Using Keys with List Spooled Files API—ILE COBOL Example  
Refer to “Using Keys with List Spooled Files API—Example” on page 3-24 for the  
original example. The following program also works for OPM COBOL.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
List Spooled Files for Current User  
ᑍ
ᑍ Language:  
ᑍ
ILE COBOL  
ᑍ Description: This example shows the steps necessary to  
ᑍ
ᑍ
process keyed output from an API.  
ᑍ APIs Used:  
QUSLSPL - List Spooled Files  
QUSCRTUS - Create User Space  
QUSPTRUS - Retrieve Pointer to User Space  
ᑍ
ᑍ
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PROGRAM-ID. LSTSPL.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
ᑍ
ᑍ
WORKING-STORAGE SECTION.  
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Listing text  
ᑍ
ð1 PRTLIN.  
ð5 PRTFIL  
ð5 FILLER  
ð5 PAGES  
ð5 FILLER  
PIC X(1ð).  
PIC X(ð5).  
PIC S9(ð9).  
PIC X(ð5).  
B-38 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ð5 OPNDAT  
ð1 LSTERR.  
ð5 TEXT1  
ð1 HDRERR.  
ð5 TEXT2  
PIC X(ð7).  
PIC X(22) VALUE "List data not valid".  
PIC X(22) VALUE "Unknown Generic Header".  
ᑍ
ð1 MISC.  
ð5 SPC-NAME  
PIC X(2ð) VALUE "SPCNAME QTEMP  
PIC S9(ð9) VALUE 2ððð BINARY. .2/  
PIC X(ð1) VALUE X"ðð".  
POINTER.  
".  
ð5 SPC-SIZE  
ð5 SPC-INIT  
ð5 SPCPTR  
ð5 SPC-TYPE  
ð5 EXT-ATTR  
ð5 SPC-AUT  
ð5 SPC-TEXT  
ð5 SPC-REPLAC  
ð5 SPC-DOMAIN  
PIC X(1ð) VALUE "ᑍUSRSPC".  
PIC X(1ð) VALUE "QUSLSPL ". .3/  
PIC X(1ð) VALUE "ᑍALL".  
PIC X(5ð).  
PIC X(1ð) VALUE "ᑍYES".  
PIC X(1ð) VALUE "ᑍUSER".  
ð5 LST-FORMAT-NAME PIC X(ð8) VALUE "SPLFð2ðð". .4/  
ð5 USR-PRF  
ð5 OUTQ  
ð5 FORMTYP  
ð5 USRDTA  
ð5 JOBNAM  
PIC X(1ð) VALUE "ᑍCURRENT ".  
PIC X(2ð) VALUE "ᑍALL".  
PIC X(1ð) VALUE "ᑍALL".  
PIC X(1ð) VALUE "ᑍALL".  
PIC X(26).  
ð1 KEYS.  
.7/  
ð5 KEY1  
ð5 KEY2  
ð5 KEY3  
PIC S9(ð9) BINARY VALUE 2ð1. .8/  
PIC S9(ð9) BINARY VALUE 216.  
PIC S9(ð9) BINARY VALUE 211.  
PIC S9(ð9) BINARY VALUE 3.  
ð1 NUMBER-OF-KEYS  
ð1 MISC2.  
ð5 PAGESA  
ð5 PAGESN  
PIC X(ð4).  
REDEFINES PAGESA  
PIC S9(ð9) BINARY.  
ᑍ
ᑍ
LINKAGE SECTION.  
ᑍ String to map User Space offsets into  
ᑍ
ð1 STRING-SPACE  
PIC X(32ððð).  
ᑍ
ᑍ User Space Generic Header include. These includes will be  
ᑍ mapped over a User Space.  
ᑍ
COPY QUSGEN OF QSYSINC-QLBLSRC.  
.11/  
ᑍ
ᑍ List Spool Files API include. These includes will be  
ᑍ mapped over a User Space. The include is copied into the  
ᑍ source so that we can define the variable length portion  
ᑍ of QUS-LSPL-KEY-INFO.  
ᑍ
ð1 QUS-LSPL-KEY-INFO.  
ð5 LEN-FIELD-INFO-RETD  
ð5 KEY-FIELD-FOR-FIELD-RETD  
ð5 TYPE-OF-DATA  
PIC S9(ðððð9) BINARY.  
PIC S9(ðððð9) BINARY.  
PIC X(ðððð1).  
ð5 RESERV3  
PIC X(ðððð3).  
ð5 DATA-LENGTH  
ð5 DATA-FIELD  
PIC S9(ðððð9) BINARY.  
PIC X(ðð1ðð).  
ᑍ
ᑍ
Varying length  
Appendix B. Original Examples in Additional Languages B-39  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ
ᑍ
ð5 RESERVED  
PIC X(ðððð1).  
Varying length  
ð1 QUS-SPLFð2ðð.  
ð5 NUM-FIELDS-RETD  
ð5 KEY-INFO.  
PIC S9(ðððð9) BINARY.  
ð9 LEN-FIELD-INFO-RETD  
PIC S9(ðððð9) BINARY.  
PIC S9(ðððð9) BINARY.  
PIC X(ðððð1).  
ð9 KEY-FIELD-FOR-FIELD-RETD  
ð9 TYPE-OF-DATA  
ð9 RESERV3  
PIC X(ðððð3).  
ð9 DATA-LENGTH  
ð9 DATA-FIELD  
ð9 RESERVED  
PIC S9(ðððð9) BINARY.  
PIC X(ðððð1).  
PIC X(ðððð1).  
ᑍ
ᑍ
ᑍ
ᑍ
Varying length  
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
ᑍ
ᑍ Open LISTING file  
ᑍ
OPEN OUTPUT LISTING.  
ᑍ
ᑍ Set Error Code structure to use exceptions  
ᑍ
MOVE ð TO BYTES-PROVIDED OF QUS-EC.  
ᑍ
.1/  
ᑍ Create a User Space for the List generated by QUSLSPL  
ᑍ
CALL "QUSCRTUS" USING SPC-NAME, EXT-ATTR, SPC-SIZE, .2/  
SPC-INIT, SPC-AUT, SPC-TEXT,  
SPC-REPLAC, QUS-EC, SPC-DOMAIN  
ᑍ
ᑍ Call QUSLSPL to get all spooled files for ᑍCURRENT user  
ᑍ
CALL "QUSLSPL" USING SPC-NAME, LST-FORMAT-NAME, USR-PRF, .3/.4/  
OUTQ, FORMTYP, USRDTA, QUS-EC,  
JOBNAM, KEYS, NUMBER-OF-KEYS. .5/.6/  
ᑍ
ᑍ Get a resolved pointer to the User Space for performance  
ᑍ
CALL "QUSPTRUS" USING SPC-NAME, SPCPTR, QUS-EC.  
.9/  
ᑍ
ᑍ If valid information was returned  
ᑍ
SET ADDRESS OF QUS-GENERIC-HEADER-ð1ðð TO SPCPTR.  
IF STRUCTURE-RELEASE-LEVEL OF QUS-GENERIC-HEADER-ð1ðð .12/  
NOT EQUAL "ð1ðð" WRITE LIST-LINE FROM HDRERR, .13/  
STOP RUN.  
IF (INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð = "C" .14/  
OR INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð = "P")  
AND NUMBER-LIST-ENTRIES OF QUS-GENERIC-HEADER-ð1ðð > ð .16/  
ᑍ
B-40 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ address current list entry  
ᑍ
SET ADDRESS OF STRING-SPACE TO SPCPTR,  
SET ADDRESS OF QUS-SPLFð2ðð TO  
ADDRESS OF STRING-SPACE((OFFSET-LIST-DATA  
OF QUS-GENERIC-HEADER-ð1ðð + 1):1),  
.18/  
ᑍ
ᑍ and process all of the entries  
ᑍ
PERFORM PROCES  
NUMBER-LIST-ENTRIES OF QUS-GENERIC-HEADER-ð1ðð TIMES, .2ð/  
ELSE  
WRITE LIST-LINE FROM LSTERR.  
STOP RUN.  
.15/  
.28/  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROCES.  
ᑍ
ᑍ address the first variable length record for this entry  
ᑍ
SET ADDRESS OF QUS-LSPL-KEY-INFO TO ADDRESS OF  
QUS-SPLFð2ðð(5:).  
ᑍ
ᑍ process all variable length records associated with this entry  
ᑍ
PERFORM PROCES2 NUM-FIELDS-RETD TIMES. .22/.23/  
WRITE LIST-LINE FROM PRTLIN.  
.26/  
ᑍ
ᑍ after each entry, increment to the next entry  
ᑍ
SET ADDRESS OF STRING-SPACE TO ADDRESS OF QUS-SPLFð2ðð. .27/  
SET ADDRESS OF QUS-SPLFð2ðð TO ADDRESS OF STRING-SPACE  
((SIZE-EACH-ENTRY OF QUS-GENERIC-HEADER-ð1ðð + 1):1).  
ᑍ
ᑍ Process each variable length record based on key  
ᑍ
PROCES2.  
ᑍ
ᑍ extract spooled file name for report  
ᑍ
IF KEY-FIELD-FOR-FIELD-RETD OF QUS-LSPL-KEY-INFO = 2ð1 .24/.25/  
MOVE SPACES TO PRTFIL,  
MOVE DATA-FIELD OF QUS-LSPL-KEY-INFO(  
1:DATA-LENGTH OF QUS-LSPL-KEY-INFO)  
TO PRTFIL.  
ᑍ
ᑍ extract number of pages for report  
ᑍ
IF KEY-FIELD-FOR-FIELD-RETD OF QUS-LSPL-KEY-INFO = 211 .24/.25/  
MOVE DATA-FIELD OF QUS-LSPL-KEY-INFO(  
1:DATA-LENGTH OF QUS-LSPL-KEY-INFO)  
TO PAGESA,  
MOVE PAGESN TO PAGES.  
ᑍ
Appendix B. Original Examples in Additional Languages B-41  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ extract age of spooled file for report  
ᑍ
IF KEY-FIELD-FOR-FIELD-RETD OF QUS-LSPL-KEY-INFO = 216 .24/.25/  
MOVE SPACES TO OPNDAT,  
MOVE DATA-FIELD OF QUS-LSPL-KEY-INFO(  
1:DATA-LENGTH OF QUS-LSPL-KEY-INFO)  
TO OPNDAT.  
ᑍ
ᑍ address next variable length entry  
ᑍ
SET ADDRESS OF STRING-SPACE TO ADDRESS OF QUS-LSPL-KEY-INFO.  
SET ADDRESS OF QUS-LSPL-KEY-INFO TO ADDRESS OF  
STRING-SPACE(  
LEN-FIELD-INFO-RETD OF QUS-LSPL-KEY-INFO + 1:1).  
Using Keys with List Spooled Files API—ILE RPG Example  
Refer to “Using Keys with List Spooled Files API—Example” on page 3-24 for the  
original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program:  
List Spooled Files for Current User  
Fᑍ  
Fᑍ Language:  
Fᑍ  
ILE RPG  
Fᑍ Description: This example shows the steps necessary to  
Fᑍ  
Fᑍ  
process keyed output from an API.  
Fᑍ APIs Used:  
QUSLSPL - List Spooled Files  
QUSCRTUS - Create User Space  
QUSPTRUS - Retrieve Pointer to User Space  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQPRINT  
Dᑍ  
O
F 132  
PRINTER OFLIND(ᑍINOF)  
Dᑍ Error Code parameter include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
.11/  
DSPC_NAME  
DSPC_SIZE  
DSPC_INIT  
DLSTPTR  
DLSTPTR2  
DSPCPTR  
DARR  
S
2ð  
1
INZ('SPCNAME QTEMP  
.2/  
')  
S
9B ð INZ(2ððð)  
S
INZ(X'ðð')  
S
ᑍ
ᑍ
ᑍ
S
S
S
1
BASED(LSTPTR) DIM(32767)  
D
DS  
DPAGES#  
DPAGESA  
DKEYS  
D
1
1
4B ð  
4
DS  
.7/  
.8/  
9B ð INZ(2ð1)  
9B ð INZ(216)  
9B ð INZ(211)  
D
D
B-42 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DKEY#  
S
9B ð INZ(3)  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ The following QUSGEN include from QSYSINC is copied into .11/  
Dᑍ this program so that it can be declared as BASED on SPCPTR  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSHð1ðð  
Dᑍ  
D QUSUA  
Dᑍ  
D QUSSGH  
Dᑍ  
D QUSSRL  
Dᑍ  
D QUSFN  
Dᑍ  
D QUSAU  
Dᑍ  
D QUSDTC  
Dᑍ  
D QUSIS  
Dᑍ  
D QUSSUS  
Dᑍ  
D QUSOIP  
Dᑍ  
D QUSSIP  
Dᑍ  
D QUSOHS  
Dᑍ  
D QUSSHS  
Dᑍ  
D QUSOLD  
Dᑍ  
D QUSSLD  
Dᑍ  
D QUSNBRLE  
Dᑍ  
D QUSSEE  
Dᑍ  
D QUSSIDLE  
Dᑍ  
D QUSCID  
Dᑍ  
D QUSLID  
Dᑍ  
D QUSSLI  
Dᑍ  
D QUSERVEDðð  
Dᑍ  
DS  
BASED(SPCPTR)  
Qus Generic Header ð1ðð  
1
65  
64  
User Area  
68B ð  
72  
Size Generic Header  
Structure Release Level  
Format Name  
69  
73  
8ð  
81  
9ð  
API Used  
91  
1ð3  
Date Time Created  
Information Status  
Size User Space  
Offset Input Parameter  
Size Input Parameter  
Offset Header Section  
Size Header Section  
Offset List Data  
Size List Data  
1ð4  
1ð5  
1ð9  
113  
117  
121  
125  
129  
133  
137  
141  
145  
147  
15ð  
151  
1ð4  
1ð8B ð  
112B ð  
116B ð  
12ðB ð  
124B ð  
128B ð  
132B ð  
136B ð  
14ðB ð  
144B ð  
146  
Number List Entries  
Size Each Entry  
CCSID List Ent  
Country ID  
149  
Language ID  
15ð  
Subset List Indicator  
192  
Reserved  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ The following QUSLSPL include from QSYSINC is copied into  
Dᑍ this program so that it can be declared as BASED  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Appendix B. Original Examples in Additional Languages B-43  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DᑍPrototype for calling List Spooled File API QUSLSPL  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
D QUSLSPL  
C
'QUSLSPL'  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍType definition for the SPLFð2ðð format.  
Dᑍᑍᑍᑍᑍᑍᑍ  
DᑍNOTE: The following type definition only defines the fixed  
Dᑍ portion of the format. Any varying length field will  
Dᑍ have to be defined by the user.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSSPLKI  
DS  
1ðð  
BASED(LSTPTR2)  
Qus LSPL Key Info  
Dᑍ  
D QUSLFIRð2  
1
5
4B ð  
Dᑍ  
Len Field Info Retd  
Key Field for Field Retd  
Type of Data  
D QUSKFFFRðð  
8B ð  
9
Dᑍ  
D QUSTODð2  
9
Dᑍ  
D QUSR3ðð  
1ð  
13  
17  
12  
Dᑍ  
Reserv3  
D QUSDLð2  
Dᑍ  
16B ð  
17  
Data Length  
DᑍQUSDATAð8  
Dᑍ  
Dᑍ  
DᑍQUSERVED34  
Dᑍ  
Dᑍ  
DQUSFð2ðð  
Dᑍ  
D QUSNBRFRðð  
Dᑍ  
DᑍQUSKIðð  
Dᑍ QUSLFIRð3  
Dᑍ QUSKFFFRð1  
Dᑍ QUSTODð3  
Dᑍ QUSR3ð1  
Dᑍ QUSDLð3  
Dᑍ QUSDATAð9  
Dᑍ QUSERVED35  
Dᑍ  
Varying length  
18  
18  
Varying length  
DS  
BASED(LSTPTR)  
Qus SPLFð2ðð  
1
4B ð  
Num Fields Retd  
18  
5
9
13  
14  
17  
21  
22  
8B ð  
12B ð  
13  
16  
2ðB ð  
21  
22  
Dᑍ  
Cᑍ  
Varying length  
Cᑍ Start of mainline  
Cᑍ  
Cᑍ  
Cᑍ Set Error Code structure to use exceptions  
Cᑍ  
C
Cᑍ  
Z-ADD  
ð
QUSBPRV  
.1/  
Cᑍ Create a User Space for the List generated by QUSLSPL  
Cᑍ  
C
C
C
C
C
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
'QUSCRTUS'  
.2/  
SPC_NAME  
'QUSLSPL ' EXT_ATTR  
SPC_SIZE  
1ð  
1ð  
SPC_INIT  
SPC_AUT  
'ᑍALL'  
B-44 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
PARM  
PARM  
PARM  
PARM  
ᑍBLANKS  
'ᑍYES'  
SPC_TEXT  
SPC_REPLAC  
QUSEC  
5ð  
1ð  
C
C
C
Cᑍ  
'ᑍUSER'  
SPC_DOMAIN  
1ð  
Cᑍ Call QUSLSPL to get all spooled files for ᑍCURRENT user  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'QUSLSPL'  
.3/  
SPC_NAME  
FORMAT  
USR_PRF  
OUTQ  
FORMTYP  
USRDTA  
QUSEC  
JOBNAM  
KEYS  
KEY#  
'SPLFð2ðð'  
'ᑍCURRENT'  
'ᑍALL'  
'ᑍALL'  
'ᑍALL'  
8 .4/  
1ð  
2ð  
1ð  
1ð  
26  
.5/  
.6/  
Cᑍ Get a resolved pointer to the User Space for performance  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
'QUSPTRUS'  
.9/  
C
SPC_NAME  
SPCPTR  
QUSEC  
C
C
Cᑍ  
Cᑍ If valid information was returned  
Cᑍ  
C
QUSSRL  
QUSIS  
QUSIS  
IFEQ  
IFEQ  
OREQ  
'ð1ðð'  
'C'  
'P'  
.12/  
.14/  
C
C
Cᑍ  
Cᑍ and list entries were found  
Cᑍ  
C
QUSNBRLE  
IFGT  
ð
.16/  
Cᑍ  
Cᑍ set LSTPTR to the first byte of the User Space  
Cᑍ  
C
Cᑍ  
EVAL  
LSTPTR = SPCPTR  
Cᑍ increment LSTPTR to the first List entry  
Cᑍ  
C
Cᑍ  
EVAL  
LSTPTR = %ADDR(ARR(QUSOLD + 1)) .18/  
Cᑍ and process all of the entries  
Cᑍ  
C
DO  
QUSNBRLE  
.2ð/  
Cᑍ  
Cᑍ set LSTPTR2 to the first variable length record for this entry  
Cᑍ  
C
Z-ADD  
EVAL  
DO  
5
X
9 ð  
C
LSTPTR2 = %ADDR(ARR(X)) .22/  
C
Cᑍ  
QUSNBRFRðð  
.23/  
Cᑍ process the data based on key type  
Cᑍ  
C
C
QUSKFFFRðð  
QUSKFFFRðð  
CASEQ  
CASEQ  
2ð1  
211  
FILNAM  
PAGES  
.24/  
Appendix B. Original Examples in Additional Languages B-45  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
QUSKFFFRðð  
CASEQ  
CAS  
END  
216  
AGE  
ERROR  
C
C
Cᑍ  
Cᑍ increment LSTPTR2 to next variable length record  
Cᑍ  
C
ADD  
EVAL  
END  
QUSLFIRð2  
X
C
LSTPTR2 = %ADDR(ARR(X))  
C
C
Cᑍ  
EXCEPT  
PRTLIN .26/  
Cᑍ after each entry, increment LSTPTR to the next entry  
Cᑍ  
C
EVAL  
END  
LSTPTR = %ADDR(ARR(QUSSEE + 1)) .27/  
C
C
END  
C
ELSE  
EXCEPT  
END  
ELSE  
EXCEPT  
END  
C
LSTERR  
HDRERR  
.15/  
.13/  
C
C
C
C
Cᑍ  
Cᑍ Exit the program  
Cᑍ  
C
EVAL  
ᑍINLR = '1'  
.28/  
C
RETURN  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
FILNAM  
BEGSR  
ᑍBLANKS  
PRTFIL  
1ð  
Cᑍ extract number of pages for report  
Cᑍ  
C
C
EVAL  
PAGESA = %SUBST(QUSSPLKI:17:QUSDLð2) .25/  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
AGE  
BEGSR  
Cᑍ extract age of spooled file for report  
Cᑍ  
C
C
C
MOVE  
EVAL  
ENDSR  
ᑍBLANKS  
OPNDAT  
7
OPNDAT = %SUBST(QUSSPLKI:17:QUSDLð2) .25/  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
C
C
C
C
ERROR  
QUSKFFFRðð  
BEGSR  
DSPLY  
EVAL  
ᑍINLR = '1'  
RETURN  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
OQPRINT PRTLIN  
E
1
B-46 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
O
PRTFIL  
PAGES#  
OPNDAT  
LSTERR  
1ð  
25  
4ð  
O
O
OQPRINT  
E
E
1
1
O
22 'List data not valid'  
OQPRINT  
O
HDRERR  
22 'Unknown Generic Header'  
Integrated Language Environment (ILE) APIs—Examples  
This section includes the examples in Chapter 4, “Common Information across  
APIs—Advanced (ILE) Example.”  
Register Exit Point and Add Exit Program—OPM COBOL Example  
Refer to “Register Exit Point and Add Exit Program—ILE C Example” on page 4-9  
for the original example.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
Register an Exit Point  
Add an Exit Program  
ᑍ
ᑍ
ᑍ Language:  
ᑍ
OPM COBOL  
ᑍ Description: This program registers an exit point with the  
ᑍ
registration facility. After the successful  
completion of the registration of the exit point,  
an exit program is added to the exit point.  
ᑍ
ᑍ
ᑍ
ᑍ APIs Used:  
ᑍ
ᑍ
QUSRGPT - Register Exit Point  
QUSADDEP - Add Exit Program  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-ID. REGFAC1.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Keyed Variable Length Record includes  
ᑍ
COPY QUS OF QSYSINC-QLBLSRC.  
Appendix B. Original Examples in Additional Languages B-47  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Error message text  
ᑍ
ð1 BAD-REG.  
ð5 TEXT1  
PIC X(39)  
VALUE "Attempt to register exit point failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ð1 BAD-ADD.  
ð5 TEXT1  
PIC X(36)  
VALUE "Attempt to add exit program failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 VARREC.  
ð5 NBR-RECORDS PIC S9(ð9) BINARY.  
ð5 VAR-RECORDS PIC X(1ððð).  
ð1 MISC.  
ð5 VAR-OFFSET  
PIC S9(ð9) VALUE 1.  
ð5 BINARY-NUMBER PIC S9(ð9) BINARY.  
ð5 BINARY-CHAR REDEFINES BINARY-NUMBER PIC X(ð4).  
ð5 X  
PIC S9(ð9) BINARY.  
ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".  
ð5 EXIT-PGM  
PIC X(2ð) VALUE "EXAMPLEPGMEXAMPLELIB".  
PIC S9(ð9) VALUE 1 BINARY.  
ð5 EXIT-PGM-NBR  
ð5 EXIT-PGM-DATA PIC X(25)  
VALUE "EXAMPLE EXIT PROGRAM DATA".  
PIC X(ð8) VALUE "EXMPð1ðð".  
ð5 FORMAT-NAME  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
ᑍ
ᑍ Register the exit point with the registration facility. If the  
ᑍ registration of the exit point is successful, add an exit  
ᑍ program to the exit point.  
ᑍ
ᑍ Initialize the error code parameter. To signal exceptions to  
ᑍ this program by the API, you need to set the bytes provided  
ᑍ field of the error code to zero. Because this program has  
ᑍ exceptions sent back through the error code parameter, it sets  
ᑍ the bytes provided field to the number of bytes it gives the  
ᑍ API for the parameter.  
ᑍ
MOVE 16 TO BYTES-PROVIDED.  
ᑍ
ᑍ Set the exit point controls. Each control field is passed to  
B-48 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ the API using a variable length record. Each record must  
ᑍ start on a 4-byte boundary.  
ᑍ
ᑍ Set the total number of controls that are being specified on  
ᑍ the call. This program lets the API take the default for the  
ᑍ controls that are not specified.  
ᑍ
MOVE 2 TO NBR-RECORDS.  
ᑍ
ᑍ Set the values for the two controls that are specified:  
ᑍ Maximum number of exit programs = 1ð  
ᑍ Exit point description = 'EXIT POINT EXAMPLE'  
ᑍ
MOVE 3 TO CONTROL-KEY OF QUS-VLEN-REC-4.  
MOVE 4 TO LENGTH-DATA OF QUS-VLEN-REC-4.  
MOVE 1ð TO BINARY-NUMBER.  
MOVE BINARY-CHAR TO VAR-RECORDS((VAR-OFFSET + 12):4).  
PERFORM CALCULATE-NEXT-OFFSET.  
MOVE 8 TO CONTROL-KEY OF QUS-VLEN-REC-4.  
MOVE 5ð TO LENGTH-DATA OF QUS-VLEN-REC-4.  
MOVE "EXIT POINT EXAMPLE"  
TO VAR-RECORDS((VAR-OFFSET + 12):5ð).  
PERFORM CALCULATE-NEXT-OFFSET.  
Cᑍ  
Cᑍ Call the API to add the exit point.  
Cᑍ  
CALL "QUSRGPT" USING EXIT-POINT-NAME OF MISC,  
FORMAT-NAME OF MISC,  
VARREC, QUS-EC.  
Cᑍ  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-REG,  
WRITE LIST-LINE FROM BAD-REG,  
STOP RUN.  
ᑍ
ᑍ If the call to register an exit point is successful, add  
ᑍ an exit program to the exit point.  
ᑍ
ᑍ Set the total number of exit program attributes that are being  
ᑍ specified on the call. This program lets the API take the  
ᑍ default for the attributes that are not specified. Each  
ᑍ attribute record must be 4-byte aligned.  
ᑍ
MOVE 2 TO NBR-RECORDS.  
MOVE 1 TO VAR-OFFSET.  
ᑍ
ᑍ Set the values for the two attributes that are being specified:  
ᑍ Replace exit program  
= 1  
ᑍ Exit program data CCSID = 37  
ᑍ
MOVE 4 TO CONTROL-KEY OF QUS-VLEN-REC-4.  
Appendix B. Original Examples in Additional Languages B-49  
Download from Www.Somanuals.com. All Manuals Search And Download.  
MOVE 1 TO LENGTH-DATA OF QUS-VLEN-REC-4.  
MOVE 1 TO VAR-RECORDS((VAR-OFFSET + 12):1).  
PERFORM CALCULATE-NEXT-OFFSET.  
MOVE 3 TO CONTROL-KEY OF QUS-VLEN-REC-4.  
MOVE 4 TO LENGTH-DATA OF QUS-VLEN-REC-4.  
MOVE 37 TO BINARY-NUMBER.  
MOVE BINARY-CHAR TO VAR-RECORDS((VAR-OFFSET + 12):4).  
PERFORM CALCULATE-NEXT-OFFSET.  
ᑍ
ᑍ Call the API to register the exit program.  
ᑍ
CALL "QUSADDEP" USING EXIT-POINT-NAME OF MISC,  
FORMAT-NAME OF MISC,  
EXIT-PGM-NBR OF MISC,  
EXIT-PGM OF MISC,  
EXIT-PGM-DATA OF MISC,  
BY CONTENT LENGTH OF EXIT-PGM-DATA OF MISC,  
VARREC, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-ADD,  
WRITE LIST-LINE FROM BAD-ADD,  
STOP RUN.  
ᑍ
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
ᑍ
ᑍ
ᑍ Calculate 4-byte aligned offset for next variable length record  
ᑍ
CALCULATE-NEXT-OFFSET.  
COMPUTE BINARY-NUMBER = LENGTH-DATA OF QUS-VLEN-REC-4 + 12.  
DIVIDE BINARY-NUMBER BY 4 GIVING BINARY-NUMBER REMAINDER X.  
IF X = ð COMPUTE LENGTH-VLEN-RECORD OF QUS-VLEN-REC-4 =  
LENGTH-DATA OF QUS-VLEN-REC-4 + 12  
ELSE COMPUTE LENGTH-VLEN-RECORD OF QUS-VLEN-REC-4 =  
LENGTH-DATA OF QUS-VLEN-REC-4 + 12 +  
( 4 - X ).  
MOVE QUS-VLEN-REC-4 TO VAR-RECORDS(VAR-OFFSET:12).  
COMPUTE VAR-OFFSET = VAR-OFFSET + LENGTH-VLEN-RECORD OF  
QUS-VLEN-REC-4.  
Register Exit Point and Add Exit Program—ILE COBOL Example  
Refer to “Register Exit Point and Add Exit Program—ILE C Example” on page 4-9  
for the original example.  
B-50 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
Register an Exit Point  
Add an Exit Program  
ᑍ
ᑍ
ᑍ Language:  
ᑍ
ILE COBOL  
ᑍ Description: This program registers an exit point with the  
ᑍ
registration facility. After the successful  
completion of the registration of the exit point,  
an exit program is added to the exit point.  
ᑍ
ᑍ
ᑍ
ᑍ APIs Used:  
ᑍ
ᑍ
QusRegisterExitPoint - Register Exit Point  
QusAddExitProgram - Add Exit Program  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-ID. REGFAC1.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Keyed Variable Length Record includes  
ᑍ
COPY QUS OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Error message text  
ᑍ
ð1 BAD-REG.  
ð5 TEXT1  
PIC X(39)  
VALUE "Attempt to register exit point failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ð1 BAD-ADD.  
Appendix B. Original Examples in Additional Languages B-51  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ð5 TEXT1  
PIC X(36)  
VALUE "Attempt to add exit program failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 VARREC.  
ð5 NBR-RECORDS PIC S9(ð9) BINARY.  
ð5 VAR-RECORDS PIC X(1ððð).  
ð1 MISC.  
ð5 VAR-OFFSET  
PIC S9(ð9) VALUE 1.  
ð5 BINARY-NUMBER PIC S9(ð9) BINARY.  
ð5 BINARY-CHAR REDEFINES BINARY-NUMBER PIC X(ð4).  
ð5 X  
PIC S9(ð9) BINARY.  
ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".  
ð5 EXIT-PGM  
PIC X(2ð) VALUE "EXAMPLEPGMEXAMPLELIB".  
PIC S9(ð9) VALUE 1 BINARY.  
ð5 EXIT-PGM-NBR  
ð5 EXIT-PGM-DATA PIC X(25)  
VALUE "EXAMPLE EXIT PROGRAM DATA".  
PIC X(ð8) VALUE "EXMPð1ðð".  
ð5 FORMAT-NAME  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
ᑍ
ᑍ Register the exit point with the registration facility. If the  
ᑍ registration of the exit point is successful, add an exit  
ᑍ program to the exit point.  
ᑍ
ᑍ Initialize the error code parameter. To signal exceptions to  
ᑍ this program by the API, you need to set the bytes provided  
ᑍ field of the error code to zero. Because this program has  
ᑍ exceptions sent back through the error code parameter, it sets  
ᑍ the bytes provided field to the number of bytes it gives the  
ᑍ API for the parameter.  
ᑍ
MOVE 16 TO BYTES-PROVIDED.  
ᑍ
ᑍ Set the exit point controls. Each control field is passed to  
ᑍ the API using a variable length record. Each record must  
ᑍ start on a 4-byte boundary.  
ᑍ
ᑍ Set the total number of controls that are being specified on  
ᑍ the call. This program lets the API take the default for the  
ᑍ controls that are not specified.  
ᑍ
MOVE 2 TO NBR-RECORDS.  
ᑍ
ᑍ Set the values for the two controls that are specified:  
ᑍ Maximum number of exit programs = 1ð  
ᑍ Exit point description = 'EXIT POINT EXAMPLE'  
ᑍ
MOVE 3 TO CONTROL-KEY OF QUS-VLEN-REC-4.  
MOVE 4 TO LENGTH-DATA OF QUS-VLEN-REC-4.  
MOVE 1ð TO BINARY-NUMBER.  
MOVE BINARY-CHAR TO VAR-RECORDS((VAR-OFFSET + 12):4).  
PERFORM CALCULATE-NEXT-OFFSET.  
B-52 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
MOVE 8 TO CONTROL-KEY OF QUS-VLEN-REC-4.  
MOVE 5ð TO LENGTH-DATA OF QUS-VLEN-REC-4.  
MOVE "EXIT POINT EXAMPLE"  
TO VAR-RECORDS((VAR-OFFSET + 12):5ð).  
PERFORM CALCULATE-NEXT-OFFSET.  
ᑍ
ᑍ Call the API to add the exit point.  
ᑍ
CALL PROCEDURE "QusRegisterExitPoint" USING  
EXIT-POINT-NAME OF MISC,  
FORMAT-NAME OF MISC,  
VARREC, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-REG,  
WRITE LIST-LINE FROM BAD-REG,  
STOP RUN.  
ᑍ
ᑍ If the call to register an exit point is successful, add  
ᑍ an exit program to the exit point.  
ᑍ
ᑍ Set the total number of exit program attributes that are being  
ᑍ specified on the call. This program lets the API take the  
ᑍ default for the attributes that are not specified. Each  
ᑍ attribute record must be 4-byte aligned.  
ᑍ
MOVE 2 TO NBR-RECORDS.  
MOVE 1 TO VAR-OFFSET.  
ᑍ
ᑍ Set the values for the two attributes that are being specified:  
ᑍ Replace exit program  
= 1  
ᑍ Exit program data CCSID = 37  
ᑍ
MOVE 4 TO CONTROL-KEY OF QUS-VLEN-REC-4.  
MOVE 1 TO LENGTH-DATA OF QUS-VLEN-REC-4.  
MOVE 1 TO VAR-RECORDS((VAR-OFFSET + 12):1).  
PERFORM CALCULATE-NEXT-OFFSET.  
MOVE 3 TO CONTROL-KEY OF QUS-VLEN-REC-4.  
MOVE 4 TO LENGTH-DATA OF QUS-VLEN-REC-4.  
MOVE 37 TO BINARY-NUMBER.  
MOVE BINARY-CHAR TO VAR-RECORDS((VAR-OFFSET + 12):4).  
PERFORM CALCULATE-NEXT-OFFSET.  
ᑍ
ᑍ Call the API to register the exit program.  
ᑍ
CALL PROCEDURE "QusAddExitProgram" USING  
EXIT-POINT-NAME OF MISC,  
FORMAT-NAME OF MISC,  
EXIT-PGM-NBR OF MISC,  
EXIT-PGM OF MISC,  
EXIT-PGM-DATA OF MISC,  
Appendix B. Original Examples in Additional Languages B-53  
Download from Www.Somanuals.com. All Manuals Search And Download.  
BY CONTENT LENGTH OF EXIT-PGM-DATA OF MISC,  
VARREC, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-ADD,  
WRITE LIST-LINE FROM BAD-ADD,  
STOP RUN.  
ᑍ
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
ᑍ
ᑍ
ᑍ Calculate 4-byte aligned offset for next variable length record  
ᑍ
CALCULATE-NEXT-OFFSET.  
COMPUTE BINARY-NUMBER = LENGTH-DATA OF QUS-VLEN-REC-4 + 12.  
DIVIDE BINARY-NUMBER BY 4 GIVING BINARY-NUMBER REMAINDER X.  
IF X = ð COMPUTE LENGTH-VLEN-RECORD OF QUS-VLEN-REC-4 =  
LENGTH-DATA OF QUS-VLEN-REC-4 + 12  
ELSE COMPUTE LENGTH-VLEN-RECORD OF QUS-VLEN-REC-4 =  
LENGTH-DATA OF QUS-VLEN-REC-4 + 12 +  
( 4 - X ).  
MOVE QUS-VLEN-REC-4 TO VAR-RECORDS(VAR-OFFSET:12).  
COMPUTE VAR-OFFSET = VAR-OFFSET + LENGTH-VLEN-RECORD OF  
QUS-VLEN-REC-4.  
Register Exit Point and Add Exit Program—OPM RPG Example  
Refer to “Register Exit Point and Add Exit Program—ILE C Example” on page 4-9  
for the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program:  
Register an Exit Point  
Add an Exit Program  
Fᑍ  
Fᑍ  
Fᑍ Language:  
Fᑍ  
OPM RPG  
Fᑍ Description: This program registers an exit point with the  
Fᑍ  
registration facility. After the successful  
completion of the registration of the exit point,  
an exit program is added to the exit point.  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ APIs Used:  
QUSRGPT - Register Exit Point  
QUSADDEP - Add Exit Program  
Fᑍ  
Fᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
B-54 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
FQPRINT O F  
132  
PRINTER  
1ððð 1  
UC  
Eᑍ COMPILE TIME ARRAY  
E
Iᑍ  
REC  
Iᑍ Keyed Variable Length Record includes  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUS  
Iᑍ  
Iᑍ Error Code parameter include. As this sample program  
Iᑍ uses /COPY to include the error code structure, only the first  
Iᑍ 16 bytes of the error code structure are available. If the  
Iᑍ application program needs to access the variable length  
Iᑍ exception data for the error, the developer should physically  
Iᑍ copy the QSYSINC include and modify the copied include to  
Iᑍ define additional storage for the exception data.  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSEC  
Iᑍ  
Iᑍ Miscellaneous data  
Iᑍ  
IVARREC  
DS  
1ðð8  
I
I
I I  
Iᑍ  
B 1 4ðNBRREC  
51ðð4 REC  
1
B1ðð51ðð8ðVO  
IOVRLAY  
I
DS  
DS  
B 1 4ðBINARY  
1 4 BINC  
I
Iᑍ  
I
I I  
I I  
I I  
I
'EXAMPLE_EXIT_POINT '  
1 2ð EPNTNM  
'EXAMPLEPGMEXAMPLELIB' 21 4ð EPGM  
'EXAMPLE EXIT PROGRAM- 41 65 EPGMDT  
' DATA'  
I I  
I
I I  
Cᑍ  
'EXAMPLE POINT EXAMPL- 66 115 EPTXT  
'E'  
25  
B 68 71ðEPGMSZ  
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Register the exit point with the registration facility. If the  
Cᑍ registration of the exit point is successful, add an exit  
Cᑍ program to the exit point.  
Cᑍ  
Cᑍ Initialize the error code parameter. To signal exceptions to  
Cᑍ this program by the API, you need to set the bytes provided  
Cᑍ field of the error code to zero. Because this program has  
Cᑍ exceptions sent back through the error code parameter, it sets  
Cᑍ the bytes provided field to the number of bytes it gives the  
Cᑍ API for the parameter.  
Cᑍ  
C
Z-ADD16  
QUSBNB  
Cᑍ  
Cᑍ Set the exit point controls. Each control field is passed to  
Cᑍ the API using a variable length record. Each record must  
Cᑍ start on a 4-byte boundary.  
Cᑍ  
Cᑍ Set the total number of controls that are being specified on  
Appendix B. Original Examples in Additional Languages B-55  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ the call. This program lets the API take the default for the  
Cᑍ controls that are not specified.  
Cᑍ  
C
Z-ADD2  
NBRREC  
Cᑍ  
Cᑍ Set the values for the two controls that are specified:  
Cᑍ Maximum number of exit programs = 1ð  
Cᑍ Exit point description = 'EXIT POINT EXAMPLE'  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
Cᑍ  
Z-ADD3  
QUSBCC  
QUSBCD  
BINARY  
OF  
Z-ADD4  
Z-ADD1ð  
ADD VO  
MOVEABINC  
EXSR CALCVO  
Z-ADD8  
Z-ADD5ð  
ADD VO  
MOVEAEPTXT  
EXSR CALCVO  
12  
12  
5ð  
5ð  
REC,OF  
QUSBCC  
QUSBCD  
OF  
REC,OF  
Cᑍ Call the API to register the exit point.  
Cᑍ  
C
CALL 'QUSRGPT'  
PARM  
PARM 'EXMPð1ðð'FORMAT 8  
PARM  
PARM  
C
EPNTNM  
C
C
VARREC  
QUSBN  
C
Cᑍ  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
QUSBNC  
IFGT ð  
C
OPEN QPRINT  
EXCPTERREPT  
EXSR DONE  
ENDIF  
C
C
C
Cᑍ  
Cᑍ If the call to register an exit point is successful, add  
Cᑍ an exit program to the exit point.  
Cᑍ  
Cᑍ Set the total number of exit program attributes that are being  
Cᑍ specified on the call. This program lets the API take the  
Cᑍ default for the attributes that are not specified. Each  
Cᑍ attribute record must be 4-byte aligned.  
Cᑍ  
C
C
Z-ADD2  
Z-ADD1  
NBRREC  
VO  
Cᑍ  
Cᑍ Set the values for the two attributes that are being specified:  
Cᑍ Replace exit program  
= 1  
Cᑍ Exit program data CCSID = 37  
Cᑍ  
C
C
C
Z-ADD4  
Z-ADD1  
ADD VO  
QUSBCC  
QUSBCD  
OF  
12  
5ð  
B-56 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
MOVE '1'  
EXSR CALCVO  
Z-ADD3  
REC,OF  
C
C
QUSBCC  
QUSBCD  
BINARY  
OF  
C
Z-ADD4  
C
Z-ADD37  
ADD VO  
MOVEABINC  
EXSR CALCVO  
C
12  
5ð  
C
REC,OF  
C
Cᑍ  
Cᑍ Call the API to add the exit program.  
Cᑍ  
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL 'QUSADDEP'  
PARM  
EPNTNM  
PARM 'EXMPð1ðð'FORMAT  
PARM 1  
PARM  
PARM  
PARM  
PARM  
PARM  
BINARY  
EPGM  
EPGMDT  
EPGMSZ  
VARREC  
QUSBN  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
QUSBNC  
IFGT ð  
C
OPEN QPRINT  
EXCPTERRPGM  
EXSR DONE  
ENDIF  
C
C
C
C
EXSR DONE  
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ  
Cᑍ Return to programs caller  
C
DONE  
BEGSR  
SETON  
RETRN  
ENDSR  
C
LR  
C
C
Cᑍ  
Cᑍ Calculate 4-byte aligned offset for next variable length record  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
C
C
C
CALCVO  
QUSBCD  
BEGSR  
ADD 12  
DIV 4  
MVR  
IFEQ ð  
ADD 12  
ELSE  
SUB BINARY  
ADD QUSBCD  
ADD 12  
END  
MOVEAQUSBC  
ADD QUSBCB  
ENDSR  
BINARY  
BINARY  
BINARY  
BINARY  
QUSBCD  
QUSBCB  
4
QUSBCB  
QUSBCB  
QUSBCB  
REC,VO  
VO  
Appendix B. Original Examples in Additional Languages B-57  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Oᑍ  
OQPRINT E 1ð6  
ERREPT  
O
'Attempt to register exit'  
' point failed: '  
O
O
QUSBND  
ERRPGM  
OQPRINT E 1ð6  
O
O
O
'Attempt to add an exit'  
' program failed: '  
QUSBND  
Register Exit Point and Add Exit Program—ILE RPG Example  
Refer to “Register Exit Point and Add Exit Program—ILE C Example” on page 4-9  
for the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program:  
Register an Exit Point  
Add an Exit Program  
Fᑍ  
Fᑍ  
Fᑍ Language:  
Fᑍ  
ILE RPG  
Fᑍ Description: This program registers an exit point with the  
Fᑍ  
registration facility. After the successful  
completion of the registration of the exit point,  
an exit program is added to the exit point.  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ APIs Used:  
QusRegisterExitPoint - Register Exit Point  
Fᑍ  
Fᑍ  
QusAddExitProgram  
- Add Exit Program  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQPRINT  
Dᑍ  
O
F 132  
PRINTER OFLIND(ᑍINOF) USROPN  
Dᑍ Keyed Variable Length Record includes  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUS  
Dᑍ  
Dᑍ Error Code parameter include. As this sample program  
Dᑍ uses /COPY to include the error code structure, only the first  
Dᑍ 16 bytes of the error code structure are available. If the  
Dᑍ application program needs to access the variable length  
Dᑍ exception data for the error, the developer should physically  
Dᑍ copy the QSYSINC include and modify the copied include to  
Dᑍ define additional storage for the exception data.  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍPrototype for calling Register Exit Point API.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
D QUSREPð5  
C
'QusRegisterExitPoint'  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍPrototype for calling Add Exit Program API.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
D QUSAEPGM  
C
'QusAddExitProgram'  
B-58 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
Dᑍ Miscellaneous data  
Dᑍ  
DVARREC  
D NBR_RECS  
D RECS  
DV_OFFSET  
Dᑍ  
DOVERLAYS  
D BINARY  
D BINARY_C  
Dᑍ  
DS  
9B ð  
1ððð  
S
9 ð INZ(1)  
DS  
9B ð  
4
OVERLAY(BINARY)  
DEPNTNAME  
DEPGM  
DEPGMDTA  
DEPGMDTA_SZ  
Cᑍ  
S
S
S
S
2ð  
2ð  
25  
INZ('EXAMPLE_EXIT_POINT')  
INZ('EXAMPLEPGMEXAMPLELIB')  
INZ('EXAMPLE EXIT PROGRAM DATA')  
9B ð INZ(%SIZE(EPGMDTA))  
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Register the exit point with the registration facility. If the  
Cᑍ registration of the exit point is successful, add an exit  
Cᑍ program to the exit point.  
Cᑍ  
Cᑍ Initialize the error code parameter. To signal exceptions to  
Cᑍ this program by the API, you need to set the bytes provided  
Cᑍ field of the error code to zero. Because this program has  
Cᑍ exceptions sent back through the error code parameter, it sets  
Cᑍ the bytes provided field to the number of bytes it gives the  
Cᑍ API for the parameter.  
Cᑍ  
C
EVAL  
QUSBPRV = %SIZE(QUSEC)  
Cᑍ  
Cᑍ Set the exit point controls. Each control field is passed to  
Cᑍ the API using a variable length record. Each record must  
Cᑍ start on a 4-byte boundary.  
Cᑍ  
Cᑍ Set the total number of controls that are being specified on  
Cᑍ the call. This program lets the API take the default for the  
Cᑍ controls that are not specified.  
Cᑍ  
C
EVAL  
NBR_RECS = 2  
Cᑍ  
Cᑍ Set the values for the two controls that are specified:  
Cᑍ Maximum number of exit programs = 1ð  
Cᑍ Exit point description = 'EXIT POINT EXAMPLE'  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
Cᑍ  
EVAL  
EVAL  
EVAL  
EVAL  
EXSR  
EVAL  
EVAL  
EVAL  
QUSCK = 3  
QUSLD = 4  
BINARY = 1ð  
%SUBST(RECS:V_OFFSET+12) = BINARY_C  
CALC_VOFF  
QUSCK = 8  
QUSLD = 5ð  
%SUBST(RECS:V_OFFSET+12:5ð) = 'EXIT +  
POINT EXAMPLE'  
EXSR  
CALC_VOFF  
Cᑍ Call the API to register the exit point.  
Appendix B. Original Examples in Additional Languages B-59  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
C
CALLB  
PARM  
PARM  
PARM  
PARM  
QUSREPð5  
C
EPNTNAME  
FORMAT  
VARREC  
QUSEC  
C
'EXMPð1ðð'  
8
C
C
Cᑍ  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
QPRINT  
ERRAEPNT  
DONE  
C
OPEN  
EXCEPT  
EXSR  
ENDIF  
C
C
C
Cᑍ  
Cᑍ If the call to register an exit point is successful, add  
Cᑍ an exit program to the exit point.  
Cᑍ  
Cᑍ Set the total number of exit program attributes that are being  
Cᑍ specified on the call. This program lets the API take the  
Cᑍ default for the attributes that are not specified. Each  
Cᑍ attribute record must be 4-byte aligned.  
Cᑍ  
C
C
EVAL  
EVAL  
NBR_RECS = 2  
V_OFFSET = 1  
Cᑍ  
Cᑍ Set the values for the two attributes that are being specified:  
Cᑍ Replace exit program  
= 1  
Cᑍ Exit program data CCSID = 37  
Cᑍ  
C
C
C
C
C
C
C
C
C
Cᑍ  
EVAL  
EVAL  
EVAL  
EXSR  
EVAL  
EVAL  
EVAL  
EVAL  
EXSR  
QUSCK = 4  
QUSLD = 1  
%SUBST(RECS:V_OFFSET+12) = '1'  
CALC_VOFF  
QUSCK = 3  
QUSLD = 4  
BINARY = 37  
%SUBST(RECS:V_OFFSET+12) = BINARY_C  
CALC_VOFF  
Cᑍ Call the API to add the exit program.  
Cᑍ  
C
C
C
C
C
C
C
C
C
Cᑍ  
CALLB  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
QUSAEPGM  
EPNTNAME  
FORMAT  
BINARY  
EPGM  
EPGMDTA  
EPGMDTA_SZ  
VARREC  
QUSEC  
'EXMPð1ðð'  
1
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
B-60 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
QPRINT  
ERRAEPGM  
DONE  
C
OPEN  
EXCEPT  
EXSR  
ENDIF  
EXSR  
C
C
C
C
DONE  
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ  
Cᑍ Return to programs caller  
C
DONE  
BEGSR  
EVAL  
RETURN  
ENDSR  
C
ᑍINLR = '1'  
C
C
Cᑍ  
Cᑍ Calculate 4-byte aligned offset for next variable length record  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
C
Oᑍ  
CALC_VOFF  
BEGSR  
EVAL  
DIV  
BINARY = QUSLD + 12  
4
BINARY  
BINARY  
MVR  
IF  
BINARY = ð  
EVAL  
ELSE  
EVAL  
END  
QUSLVRðð = (QUSLD + 12)  
QUSLVRðð = (QUSLD + 12 + (4 - BINARY))  
EVAL  
EVAL  
ENDSR  
%SUBST(RECS:V_OFFSET:12) = QUSVR4  
V_OFFSET = V_OFFSET + QUSLVRðð  
OQPRINT  
E
E
ERRAEPNT  
1 6  
1 6  
O
'Attempt to register exit -  
point failed: '  
O
O
QUSEI  
ERRAEPGM  
OQPRINT  
O
O
O
'Attempt to add exit -  
program failed: '  
QUSEI  
Retrieve Exit Point and Exit Program Information—OPM COBOL  
Example  
Refer to “Retrieve Exit Point and Exit Program Information—ILE C Example” on  
page 4-13 for the original example.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
Retrieve Exit Point and Exit Program Information  
ᑍ
ᑍ Language:  
ᑍ
OPM COBOL  
ᑍ Description: This program retrieves exit point and exit  
ᑍ
program information. After retrieving the  
Appendix B. Original Examples in Additional Languages B-61  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
exit point information, the program calls each  
exit program.  
ᑍ
ᑍ
ᑍ APIs Used:  
QUSCRTUS - Create User Space  
ᑍ
ᑍ
ᑍ
QUSPTRUS - Retrieve Pointer to User Space  
QUSRTVEI - Retrieve Exit Information  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PROGRAM-ID. REGFAC2.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Error message text  
ᑍ
ð1 BAD-EXIT-POINT.  
ð5 TEXT1  
PIC X(4ð)  
VALUE "Attempt to retrieve information failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ð1 BAD-EXIT-PGM.  
ð5 TEXT1  
PIC X(42)  
VALUE "Attempt to retrieve Exit Programs failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ð1 BAD-CREATE.  
ð5 TEXT1  
PIC X(37)  
VALUE "Allocation of RCVVAR storage failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 MISC.  
ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".  
ð5 EXIT-PGM-NBR  
PIC S9(ð9) VALUE -1 BINARY.  
ð5 EXIT-PARAMETERS PIC X(1ð).  
B-62 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ð5 FORMAT-NAME  
PIC X(ð8) VALUE "EXTIð1ðð".  
ð5 FORMAT-NAME-1 PIC X(ð8) VALUE "EXTIð2ðð".  
ð5 FORMAT-NAME-2 PIC X(ð8) VALUE "EXMPð1ðð".  
ð5 NBR-OF-SELECT-CRITERIA PIC S9(ð9) VALUE ð BINARY.  
ð5 CONTINUATION-HDL PIC X(16).  
ð5 BASE-POINTER  
ð5 INFO-POINTER  
ð5 SPACE-NAME  
ð5 SPACE-ATTR  
ð5 SPACE-SIZE  
ð5 SPACE-VALUE  
ð5 SPACE-AUTH  
ð5 SPACE-TEXT  
POINTER.  
POINTER.  
PIC X(2ð) VALUE "RCVVAR  
PIC X(1ð).  
PIC S9(ð9) VALUE 35ðð BINARY.  
PIC X(ð1) VALUE X"ðð".  
PIC X(1ð) VALUE "ᑍUSE".  
PIC X(5ð).  
QTEMP  
".  
ð5 SPACE-REPLACE PIC X(1ð) VALUE "ᑍNO".  
ð5 SPACE-DOMAIN PIC X(1ð) VALUE "ᑍUSER".  
ᑍ
ᑍ
LINKAGE SECTION.  
ᑍ Variable to hold results of QUSRTVEI. The storage for this  
ᑍ variable will be allocated by way of a User Space.  
ᑍ
ð1 RCVVAR  
PIC X(35ðð).  
ᑍ
ᑍ Registration Facility API include. These includes will be  
ᑍ mapped over the RCVVAR (User Space) previously defined.  
ᑍ
COPY QUSREG OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
ᑍ
ᑍ Retrieve the exit point information first. If the current  
ᑍ number of exit programs is not zero, retrieve the exit  
ᑍ programs. It is not necessary to call for the exit point  
ᑍ information to determine if the exit point has any exit  
ᑍ programs. It is done here for illustrative purposes only.  
ᑍ You can make one call to the API for the exit program  
ᑍ information and check the number of exit program entries  
ᑍ returned field to see if there are any exit programs to call.  
ᑍ
ᑍ Initialize the error code to inform the API that all  
ᑍ exceptions should be returned through the error code parameter.  
ᑍ
MOVE 16 TO BYTES-PROVIDED OF QUS-EC.  
ᑍ
ᑍ Create a User Space for RCVVAR.  
ᑍ
CALL "QUSCRTUS" USING SPACE-NAME, SPACE-ATTR, SPACE-SIZE,  
SPACE-VALUE, SPACE-AUTH, SPACE-TEXT,  
SPACE-REPLACE, QUS-EC, SPACE-DOMAIN.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
Appendix B. Original Examples in Additional Languages B-63  
Download from Www.Somanuals.com. All Manuals Search And Download.  
IF BYTES-AVAILABLE OF QUS-EC > ð  
IF EXCEPTION-ID OF QUS-EC = "CPF987ð"  
CONTINUE  
ELSE  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-CREATE,  
WRITE LIST-LINE FROM BAD-CREATE,  
STOP RUN.  
ᑍ
ᑍ Assign BASE-POINTER to address RCVVAR  
ᑍ
CALL "QUSPTRUS" USING SPACE-NAME, BASE-POINTER, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-CREATE,  
WRITE LIST-LINE FROM BAD-CREATE,  
STOP RUN.  
ᑍ
SET ADDRESS OF RCVVAR TO BASE-POINTER.  
ᑍ
ᑍ Blank out the continuation handle to let the API know that this  
ᑍ is a first attempt at the retrieve operation.  
ᑍ
MOVE SPACES TO CONTINUATION-HDL.  
ᑍ
ᑍ Call the API to retrieve the exit programs  
ᑍ
CALL "QUSRTVEI" USING CONTINUATION-HDL, RCVVAR,  
BY CONTENT LENGTH OF RCVVAR,  
FORMAT-NAME OF MISC,  
EXIT-POINT-NAME OF MISC,  
FORMAT-NAME-2, EXIT-PGM-NBR,  
NBR-OF-SELECT-CRITERIA, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-EXIT-POINT,  
WRITE LIST-LINE FROM BAD-EXIT-POINT,  
STOP RUN.  
ᑍ
ᑍ If the call to retrieve exit point information is successful,  
ᑍ check to see if there are any exit programs to call.  
ᑍ
SET ADDRESS OF QUS-EXTIð1ðð TO BASE-POINTER.  
B-64 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
SET ADDRESS OF QUS-EXTIð2ðð TO BASE-POINTER.  
ᑍ
IF NUMBER-POINTS-RETURNED OF QUS-EXTIð1ðð > ð  
SET ADDRESS OF QUS-EXTIð1ðð-ENTRY TO  
ADDRESS OF RCVVAR((OFFSET-EXIT-POINT-ENTRY OF  
QUS-EXTIð1ðð + 1):)  
ELSE STOP RUN.  
ᑍ
ᑍ
IF NUMBER-EXIT-PROGRAMS OF QUS-EXTIð1ðð-ENTRY > ð  
ᑍ There are some exit programs to call. Blank out the continuation  
ᑍ handle to let the API know that this is a first attempt at the  
ᑍ retrieve operation.  
ᑍ
MOVE SPACES TO CONTINUATION-HDL,  
ᑍ
ᑍ Call the exit programs  
ᑍ
PERFORM CALL-EXIT-PROGRAMS,  
ᑍ
ᑍ If the continuation handle field in the receiver variable is  
ᑍ not set to blanks, the API has more information to return than  
ᑍ what could fit in the receiver variable. Call the API for  
ᑍ more exit programs to call.  
ᑍ
PERFORM UNTIL CONTINUE-HANDLE OF QUS-EXTIð2ðð = SPACES  
MOVE CONTINUE-HANDLE OF QUS-EXTIð2ðð  
TO CONTINUATION-HDL,  
PERFORM CALL-EXIT-PROGRAMS,  
END-PERFORM.  
ᑍ
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
ᑍ
ᑍ
ᑍ Process exit programs in receiver variable  
ᑍ
CALL-EXIT-PROGRAMS.  
ᑍ
ᑍ Call the API to retrieve the exit program information  
ᑍ
CALL "QUSRTVEI" USING CONTINUATION-HDL, RCVVAR,  
BY CONTENT LENGTH OF RCVVAR,  
FORMAT-NAME-1,  
EXIT-POINT-NAME OF MISC,  
FORMAT-NAME-2, EXIT-PGM-NBR,  
NBR-OF-SELECT-CRITERIA, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-EXIT-PGM,  
Appendix B. Original Examples in Additional Languages B-65  
Download from Www.Somanuals.com. All Manuals Search And Download.  
WRITE LIST-LINE FROM BAD-EXIT-PGM,  
STOP RUN.  
ᑍ
ᑍ If the call to retrieve exit program information is successful,  
ᑍ check to see if there are any exit programs to call.  
ᑍ
ᑍ The receiver variable offers enough room for a minimum of one  
ᑍ exit program entry because the receiver variable was declared  
ᑍ as 35ðð bytes. Therefore, this example only checks the  
ᑍ number of exit programs returned field. If the receiver  
ᑍ variable were not large enough to hold at least one entry,  
ᑍ the bytes available field would need to be checked as well as  
ᑍ the number of exit programs returned field. If the number of  
ᑍ exit programs returned field is set to zero and the bytes  
ᑍ available field is greater than the bytes returned field, the  
ᑍ API had at least one exit program entry to return but was  
ᑍ unable to because the receiver variable was too small.  
ᑍ
SET ADDRESS OF QUS-EXTIð2ðð-ENTRY  
TO ADDRESS OF RCVVAR(OFFSET-PROGRAM-ENTRY  
OF QUS-EXTIð2ðð + 1:).  
PERFORM CALL-PGMS  
NUMBER-PROGRAMS-RETURNED OF QUS-EXTIð2ðð TIMES.  
ᑍ
CALL-PGMS.  
ᑍ
ᑍ Call the exit program while ignoring failures on the call  
ᑍ
CALL PROGRAM-NAME OF QUS-EXTIð2ðð-ENTRY USING  
EXIT-PARAMETERS  
ON EXCEPTION CONTINUE.  
ᑍ
ᑍ Address the next exit program entry  
ᑍ
SET ADDRESS OF QUS-EXTIð2ðð-ENTRY  
TO ADDRESS OF RCVVAR(OFFSET-NEXT-ENTRY  
OF QUS-EXTIð2ðð-ENTRY + 1:).  
Retrieve Exit Point and Exit Program Information—ILE COBOL  
Example  
Refer to “Retrieve Exit Point and Exit Program Information—ILE C Example” on  
page 4-13 for the original example.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
Retrieve Exit Point and Exit Program Information  
ᑍ
ᑍ Language:  
ᑍ
ILE COBOL  
ᑍ Description: This program retrieves exit point and exit  
ᑍ
program information. After retrieving the  
exit point information, the program calls each  
exit program.  
ᑍ
ᑍ
ᑍ
ᑍ APIs Used:  
QUSCRTUS - Create User Space  
B-66 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ
ᑍ
ᑍ
QUSPTRUS - Retrieve Pointer to User Space  
QusRetrieveExitInformation - Retrieve Exit  
Information  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PROGRAM-ID. REGFAC2.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Error message text  
ᑍ
ð1 BAD-EXIT-POINT.  
ð5 TEXT1  
PIC X(4ð)  
VALUE "Attempt to retrieve information failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ð1 BAD-EXIT-PGM.  
ð5 TEXT1  
PIC X(42)  
VALUE "Attempt to retrieve Exit Programs failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ð1 BAD-CREATE.  
ð5 TEXT1  
PIC X(37)  
VALUE "Allocation of RCVVAR storage failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 MISC.  
ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".  
ð5 EXIT-PGM-NBR  
PIC S9(ð9) VALUE -1 BINARY.  
ð5 EXIT-PARAMETERS PIC X(1ð).  
ð5 FORMAT-NAME  
PIC X(ð8) VALUE "EXTIð1ðð".  
ð5 FORMAT-NAME-1 PIC X(ð8) VALUE "EXTIð2ðð".  
ð5 FORMAT-NAME-2 PIC X(ð8) VALUE "EXMPð1ðð".  
Appendix B. Original Examples in Additional Languages B-67  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ð5 NBR-OF-SELECT-CRITERIA PIC S9(ð9) VALUE ð BINARY.  
ð5 CONTINUATION-HDL PIC X(16).  
ð5 BASE-POINTER  
ð5 INFO-POINTER  
ð5 SPACE-NAME  
ð5 SPACE-ATTR  
ð5 SPACE-SIZE  
ð5 SPACE-VALUE  
ð5 SPACE-AUTH  
ð5 SPACE-TEXT  
POINTER.  
POINTER.  
PIC X(2ð) VALUE "RCVVAR  
PIC X(1ð).  
PIC S9(ð9) VALUE 35ðð BINARY.  
PIC X(ð1) VALUE X"ðð".  
PIC X(1ð) VALUE "ᑍUSE".  
PIC X(5ð).  
QTEMP  
".  
ð5 SPACE-REPLACE PIC X(1ð) VALUE "ᑍNO".  
ð5 SPACE-DOMAIN PIC X(1ð) VALUE "ᑍUSER".  
ᑍ
ᑍ
LINKAGE SECTION.  
ᑍ Variable to hold results of QusRetrieveExitInformation. The  
ᑍ storage for this variable will be allocated by way of a User  
ᑍ Space.  
ᑍ
ð1 RCVVAR  
PIC X(35ðð).  
ᑍ
ᑍ Registration Facility API include. These includes will be  
ᑍ mapped over the RCVVAR (User Space) previously defined.  
ᑍ
COPY QUSREG OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
ᑍ
ᑍ Retrieve the exit point information first. If the current  
ᑍ number of exit programs is not zero, retrieve the exit  
ᑍ programs. It is not necessary to call for the exit point  
ᑍ information to determine if the exit point has any exit  
ᑍ programs. It is done here for illustrative purposes only.  
ᑍ You can make one call to the API for the exit program  
ᑍ information and check the number of exit program entries  
ᑍ returned field to see if there are any exit programs to call.  
ᑍ
ᑍ Initialize the error code to inform the API that all  
ᑍ exceptions should be returned through the error code parameter.  
ᑍ
MOVE 16 TO BYTES-PROVIDED OF QUS-EC.  
ᑍ
ᑍ Create a User Space for RCVVAR.  
ᑍ
CALL "QUSCRTUS" USING SPACE-NAME, SPACE-ATTR, SPACE-SIZE,  
SPACE-VALUE, SPACE-AUTH, SPACE-TEXT,  
SPACE-REPLACE, QUS-EC, SPACE-DOMAIN.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
IF EXCEPTION-ID OF QUS-EC = "CPF987ð"  
B-68 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
CONTINUE  
ELSE  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-CREATE,  
WRITE LIST-LINE FROM BAD-CREATE,  
STOP RUN.  
ᑍ
ᑍ Assign BASE-POINTER to address RCVVAR  
ᑍ
CALL "QUSPTRUS" USING SPACE-NAME, BASE-POINTER, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-CREATE,  
WRITE LIST-LINE FROM BAD-CREATE,  
STOP RUN.  
ᑍ
SET ADDRESS OF RCVVAR TO BASE-POINTER.  
ᑍ
ᑍ Blank out the continuation handle to let the API know that this  
ᑍ is a first attempt at the retrieve operation.  
ᑍ
MOVE SPACES TO CONTINUATION-HDL.  
ᑍ
ᑍ Call the API to retrieve the exit programs  
ᑍ
CALL PROCEDURE "QusRetrieveExitInformation" USING  
CONTINUATION-HDL,  
RCVVAR,  
BY CONTENT LENGTH OF RCVVAR,  
FORMAT-NAME OF MISC,  
EXIT-POINT-NAME OF MISC,  
FORMAT-NAME-2, EXIT-PGM-NBR,  
NBR-OF-SELECT-CRITERIA, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-EXIT-POINT,  
WRITE LIST-LINE FROM BAD-EXIT-POINT,  
STOP RUN.  
ᑍ
ᑍ If the call to retrieve exit point information is successful,  
ᑍ check to see if there are any exit programs to call.  
ᑍ
SET ADDRESS OF QUS-EXTIð1ðð TO BASE-POINTER.  
Appendix B. Original Examples in Additional Languages B-69  
Download from Www.Somanuals.com. All Manuals Search And Download.  
SET ADDRESS OF QUS-EXTIð2ðð TO BASE-POINTER.  
ᑍ
IF NUMBER-POINTS-RETURNED OF QUS-EXTIð1ðð > ð  
SET ADDRESS OF QUS-EXTIð1ðð-ENTRY TO  
ADDRESS OF RCVVAR((OFFSET-EXIT-POINT-ENTRY OF  
QUS-EXTIð1ðð + 1):)  
ELSE STOP RUN.  
ᑍ
ᑍ
IF NUMBER-EXIT-PROGRAMS OF QUS-EXTIð1ðð-ENTRY > ð  
ᑍ There are some exit programs to call. Blank out the continuation  
ᑍ handle to let the API know that this is a first attempt at the  
ᑍ retrieve operation.  
ᑍ
MOVE SPACES TO CONTINUATION-HDL,  
ᑍ
ᑍ Call the exit programs  
ᑍ
PERFORM CALL-EXIT-PROGRAMS,  
ᑍ
ᑍ If the continuation handle field in the receiver variable is  
ᑍ not set to blanks, the API has more information to return than  
ᑍ what could fit in the receiver variable. Call the API for  
ᑍ more exit programs to call.  
ᑍ
PERFORM UNTIL CONTINUE-HANDLE OF QUS-EXTIð2ðð = SPACES  
MOVE CONTINUE-HANDLE OF QUS-EXTIð2ðð  
TO CONTINUATION-HDL,  
PERFORM CALL-EXIT-PROGRAMS,  
END-PERFORM.  
ᑍ
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
ᑍ
ᑍ
ᑍ Process exit programs in receiver variable  
ᑍ
CALL-EXIT-PROGRAMS.  
ᑍ
ᑍ Call the API to retrieve the exit program information  
ᑍ
CALL PROCEDURE "QusRetrieveExitInformation" USING  
CONTINUATION-HDL, RCVVAR,  
BY CONTENT LENGTH OF RCVVAR,  
FORMAT-NAME-1,  
EXIT-POINT-NAME OF MISC,  
FORMAT-NAME-2, EXIT-PGM-NBR,  
NBR-OF-SELECT-CRITERIA, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
B-70 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
TO EXCEPTION-ID OF BAD-EXIT-PGM,  
WRITE LIST-LINE FROM BAD-EXIT-PGM,  
STOP RUN.  
ᑍ
ᑍ If the call to retrieve exit program information is successful,  
ᑍ check to see if there are any exit programs to call.  
ᑍ
ᑍ The receiver variable offers enough room for a minimum of one  
ᑍ exit program entry because the receiver variable was declared  
ᑍ as 35ðð bytes. Therefore, this example only checks the  
ᑍ number of exit programs returned field. If the receiver  
ᑍ variable were not large enough to hold at least one entry,  
ᑍ the bytes available field would need to be checked as well as  
ᑍ the number of exit programs returned field. If the number of  
ᑍ exit programs returned field is set to zero and the bytes  
ᑍ available field is greater than the bytes returned field, the  
ᑍ API had at least one exit program entry to return but was  
ᑍ unable to because the receiver variable was too small.  
ᑍ
SET ADDRESS OF QUS-EXTIð2ðð-ENTRY  
TO ADDRESS OF RCVVAR(OFFSET-PROGRAM-ENTRY  
OF QUS-EXTIð2ðð + 1:).  
PERFORM CALL-PGMS  
NUMBER-PROGRAMS-RETURNED OF QUS-EXTIð2ðð TIMES.  
ᑍ
CALL-PGMS.  
ᑍ
ᑍ Call the exit program while ignoring failures on the call  
ᑍ
CALL PROGRAM-NAME OF QUS-EXTIð2ðð-ENTRY USING  
EXIT-PARAMETERS  
ON EXCEPTION CONTINUE.  
ᑍ
ᑍ Address the next exit program entry  
ᑍ
SET ADDRESS OF QUS-EXTIð2ðð-ENTRY  
TO ADDRESS OF RCVVAR(OFFSET-NEXT-ENTRY  
OF QUS-EXTIð2ðð-ENTRY + 1:).  
Retrieve Exit Point and Exit Program Information—OPM RPG Example  
Refer to “Retrieve Exit Point and Exit Program Information—ILE C Example” on  
page 4-13 for the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program:  
Retrieve Exit Point and Exit Program Information  
Fᑍ  
Fᑍ Language:  
Fᑍ  
OPM RPG  
Fᑍ Description: This program retrieves exit point and exit  
Fᑍ  
program information. After retrieving the  
exit point information, the program calls each  
exit program.  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ APIs Used:  
Fᑍ  
QUSRTVEI - Retrieve Exit Information  
Appendix B. Original Examples in Additional Languages B-71  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQPRINT O F  
Iᑍ  
132  
PRINTER  
UC  
Iᑍ Error Code parameter include. As this sample program  
Iᑍ uses /COPY to include the error code structure, only the first  
Iᑍ 16 bytes of the error code structure are available. If the  
Iᑍ application program needs to access the variable length  
Iᑍ exception data for the error, the developer should physically  
Iᑍ copy the QSYSINC include and modify the copied include to  
Iᑍ define additional storage for the exception data.  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSEC  
Iᑍ  
Iᑍ Formats for the Retrieve Exit Information API.  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSREG  
Iᑍ  
Iᑍ Miscellaneous data  
Iᑍ  
I
DS  
I I  
I I  
I I  
I
'EXAMPLE_EXIT_POINT '  
1 2ð EPNTNM  
B 21 24ðEPGMNB  
B 25 28ðRCVSZ  
B 29 32ðX  
-1  
35ðð  
I
I
IRCV  
Cᑍ  
B 33 36ðY  
37 57 CALLPG  
35ðð  
DS  
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Retrieve the exit point information first. If the current  
Cᑍ number of exit programs is not zero, retrieve the exit  
Cᑍ programs. It is not necessary to call for the exit point  
Cᑍ information to determine if the exit point has any exit  
Cᑍ programs. It is done here for illustrative purposes only.  
Cᑍ You can make one call to the API for the exit program  
Cᑍ information and check the number of exit program entries  
Cᑍ returned field to see if there are any exit programs to call.  
Cᑍ  
Cᑍ Initialize the error code to inform the API that all  
Cᑍ exceptions should be returned through the error code parameter.  
Cᑍ  
C
Cᑍ  
Z-ADD16  
QUSBNB  
Cᑍ Blank out the continuation handle to let the API know that this  
Cᑍ is a first attempt at the retrieve operation.  
Cᑍ  
C
Cᑍ  
MOVE ᑍBLANKS CONTHD 16  
Cᑍ Call the API to retrieve the exit point information  
Cᑍ  
C
C
C
C
C
CALL 'QUSRTVEI'  
PARM  
PARM  
PARM  
CONTHD  
RCV  
RCVSZ  
PARM 'EXTIð1ðð'FORMAT 8  
B-72 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
PARM  
EPNTNM  
C
PARM 'EXMPð1ðð'EPTFMT 8  
C
PARM  
PARM ð  
PARM  
EPGMNB  
QUSCCB  
QUSBN  
C
C
Cᑍ  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
QUSBNC  
IFGT ð  
C
OPEN QPRINT  
EXCPTERREPT  
EXSR DONE  
ENDIF  
C
C
C
Cᑍ  
Cᑍ If the call to retrieve exit point information is successful,  
Cᑍ check to see if there are any exit programs to call.  
Cᑍ  
C
36  
QUSCGG  
1
2ð1  
QUSCFF  
SUBSTRCV:1  
IFGT ð  
ADD QUSCGF  
SUBSTRCV:X  
IFGT ð  
QUSCG  
C
C
X
C
QUSCF  
C
Cᑍ  
Cᑍ There are some exit programs to call. Blank out the continuation  
Cᑍ handle to let the API know that this is a first attempt at the  
Cᑍ retrieve operation.  
Cᑍ  
C
MOVE ᑍBLANKS CONTHD  
Cᑍ  
Cᑍ Call the exit programs  
Cᑍ  
C
Cᑍ  
EXSR CUSREI  
Cᑍ If the continuation handle field in the receiver variable is  
Cᑍ not set to blanks, the API has more information to return than  
Cᑍ what could fit in the receiver variable. Call the API for  
Cᑍ more exit programs to call.  
Cᑍ  
C
QUSCGD  
DOWNEᑍBLANKS  
MOVELQUSCGD  
EXSR CUSREI  
ENDDO  
C
CONTHD  
C
C
C
ENDIF  
C
ENDIF  
EXSR DONE  
C
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ Process exit programs in receiver variable  
Cᑍ  
C
Cᑍ  
CUSREI  
BEGSR  
Cᑍ Call the API to retrieve the exit program information  
Cᑍ  
C
CALL 'QUSRTVEI'  
Appendix B. Original Examples in Additional Languages B-73  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
C
C
C
C
C
C
C
C
Cᑍ  
PARM  
PARM  
PARM  
CONTHD  
RCV  
RCVSZ  
PARM 'EXTIð2ðð'FORMAT 8  
PARM  
EPNTNM  
PARM 'EXMPð1ðð'EPTFMT 8  
PARM  
PARM ð  
PARM  
EPGMNB  
QUSCCB  
QUSBN  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
QUSBNC  
IFGT ð  
C
OPEN QPRINT  
EXCPTERRPGM  
EXSR DONE  
ENDIF  
C
C
C
Cᑍ  
Cᑍ If the call to retrieve exit program information is successful,  
Cᑍ check to see if there are any exit programs to call.  
Cᑍ  
Cᑍ The receiver variable offers enough room for a minimum of one  
Cᑍ exit program entry because the receiver variable was declared  
Cᑍ as 35ðð bytes. Therefore, this example only checks the  
Cᑍ number of exit programs returned field. If the receiver  
Cᑍ variable were not large enough to hold at least one entry,  
Cᑍ the bytes available field would need to be checked as well as  
Cᑍ the number of exit programs returned field. If the number of  
Cᑍ exit programs returned field is set to zero and the bytes  
Cᑍ available field is greater than the bytes returned field, the  
Cᑍ API had at least one exit program entry to return but was  
Cᑍ unable to because the receiver variable was too small.  
Cᑍ  
C
36  
1
72  
SUBSTRCV:1  
ADD QUSCJF  
SUBSTRCV:Y  
DO QUSCJG  
QUSCJ  
Y
QUSCH  
C
C
C
Cᑍ  
Cᑍ Get the exit program name and library  
Cᑍ  
C
MOVE ᑍBLANKS CALLPG  
C
MOVELQUSCHL  
CAT '/':ð  
CALLPG  
CALLPG  
C
C
Cᑍ  
CALLPG  
CALLPG  
CAT QUSCHK:ð CALLPG  
Cᑍ Call the exit program while ignoring failures on the call  
Cᑍ  
C
CALL CALLPG  
PARM  
ð1  
C
EXTPRM 1ð  
Cᑍ  
Cᑍ Set Y to point to the next exit program entry  
Cᑍ  
C
C
C
1
72  
ADD QUSCHB  
SUBSTRCV:Y  
ENDDO  
Y
QUSCH  
B-74 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
ENDSR  
Cᑍ  
Cᑍ Return to programs caller  
C
DONE  
BEGSR  
SETON  
RETRN  
ENDSR  
C
LR  
C
C
Oᑍ  
OQPRINT E 1ð6  
ERREPT  
O
'Attempt to retrieve infor'  
'mation failed: '  
O
O
QUSBND  
ERRPGM  
OQPRINT E 1ð6  
O
O
O
'Attempt to retrieve Exit'  
' Programs failed: '  
QUSBND  
Retrieve Exit Point and Exit Program Information—ILE RPG Example  
Refer to “Retrieve Exit Point and Exit Program Information—ILE C Example” on  
page 4-13 for the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program:  
Retrieve Exit Point and Exit Program Information  
Fᑍ  
Fᑍ Language:  
Fᑍ  
ILE RPG  
Fᑍ Description: This program retrieves exit point and exit  
Fᑍ  
program information. After retrieving the  
exit point information, the program calls each ,  
exit program.  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ APIs Used:  
QusRetrieveExitInformation - Retrieve Exit  
Information  
Fᑍ  
Fᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQPRINT  
Dᑍ  
O
F 132  
PRINTER OFLIND(ᑍINOF) USROPN  
Dᑍ The following QUSREG include from QSYSINC is copied into  
Dᑍ this program so that the data structures can be declared as  
Dᑍ BASED.  
Dᑍ  
Dᑍᑍᑍ START HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
DᑍHeader File Name: H/QUSREG  
Dᑍ  
DᑍDescriptive Name: Standard Registration Structures.  
Dᑍ  
Dᑍ5763-SS1 (C) Copyright IBM Corp. 1994,1994  
DᑍAll rights reserved.  
DᑍUS Government Users Restricted Rights -  
DᑍUse, duplication or disclosure restricted  
Dᑍby GSA ADP Schedule Contract with IBM Corp.  
Dᑍ  
Appendix B. Original Examples in Additional Languages B-75  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DᑍLicensed Materials-Property of IBM  
Dᑍ  
Dᑍ  
DᑍDescription: All of the structures that are used in the  
Dᑍ  
Dᑍ  
Dᑍ  
Registration facilities are kept here to avoid  
conflict due to repetition.  
DᑍHeader Files Included: None.  
Dᑍ  
DᑍMacros List: None.  
Dᑍ  
DᑍStructure List: Qus_Prep_Exit_t  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Qus_Qmff_t  
Qus_Selcrtr_t  
Qus_Select_Entry_t  
Qus_Program_Data_t  
Qus_EXTIð1ðð_t  
Qus_EXTIð1ðð_Entry_t  
Qus_EXTIð2ðð_t  
Qus_EXTIð2ðð_Entry_t  
Qus_EXTIð3ðð_t  
Qus_EXTIð3ðð_Entry_t  
DᑍFunction Prototype List: none.  
Dᑍ  
DᑍChange Activity:  
Dᑍ  
DᑍCFD List:  
Dᑍ  
DᑍFLAG REASON  
LEVEL DATE PGMR  
CHANGE DESCRIPTION  
Dᑍ---- ------------ ----- ------ --------- ----------------------  
Dᑍ$Að= D2862ððð  
Dᑍ  
3D1ð 94ð327 LUPA:  
New Include  
DᑍEnd CFD List.  
Dᑍ  
DᑍAdditional notes about the Change Activity  
DᑍEnd Change Activity.  
Dᑍᑍᑍ END HEADER FILE SPECIFICATIONS ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍFormat structure for the Preprocessing Exit Program Format for  
DᑍQusRegisterExitPoint API.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSPE  
Dᑍ  
D QUSPPN  
Dᑍ  
D QUSPPLIB  
Dᑍ  
D QUSPPF  
Dᑍ  
DS  
Qus Prep Exit  
1
11  
21  
1ð  
2ð  
28  
Prep Prog Name  
Prep Prog Library  
Prep Prog Format  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍFormat structure for the Qualified Message File Format for the  
Dᑍentire service program.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSQMFF  
Dᑍ  
D QUSMFIL  
Dᑍ  
DS  
Qus Qmff  
1
1ð  
Message File  
B-76 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
D QUSMLIB  
Dᑍ  
D QUSMI  
Dᑍ  
11  
21  
2ð  
27  
Message Library  
Message Id  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍFormat structure for the Exit Program Selection Criteria of the  
DᑍQusRetrieveExitInformation API.  
Dᑍᑍᑍᑍ  
ᑍᑍᑍ  
DᑍNOTE: This structure only defines fixed fields. Any varying  
Dᑍ length or repeating field will have to be defined by  
Dᑍ the user.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSSE  
Dᑍ  
D QUSSEðð  
Dᑍ  
D QUSCO  
Dᑍ  
D QUSSPD  
Dᑍ  
DS  
Qus Select Entry  
Size Entry  
1
5
4B ð  
8B ð  
12B ð  
16B ð  
17  
Comp Operator  
Start Pgm Data  
Length Comp Data  
9
D QUSLCD  
Dᑍ  
13  
17  
DᑍQUSCD  
Dᑍ  
Dᑍ  
Varying length  
DQUSS  
DS  
Dᑍ  
Qus Selcrtr  
D QUSNBRSC  
Dᑍ  
1
4B ð  
17  
Number Sel Criteria  
DIM(ðððð1)  
DᑍQUSARRAY  
Dᑍ QUSSEð1  
Dᑍ QUSCOðð  
Dᑍ QUSSPDðð  
Dᑍ QUSLCDðð  
Dᑍ QUSCDðð  
Dᑍ  
9B ð OVERLAY(QUSARRAY:ðððð1)  
9B ð OVERLAY(QUSARRAY:ðððð5)  
9B ð OVERLAY(QUSARRAY:ðððð9)  
9B ð OVERLAY(QUSARRAY:ððð13)  
1
OVERLAY(QUSARRAY:ððð17)  
Dᑍ  
Varying length  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍFormat Structure for the Program Data. This structure has  
Dᑍset up to facilitate COBOL and RPG pointer basing.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSPGMD  
DS  
Dᑍ  
Qus Program Data  
Varying length  
D QUSDATAð1  
Dᑍ  
1
1
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍFormat structure for the EXTIð1ðð Format for the  
DᑍQusRetrieveExitInformation API.  
Dᑍᑍᑍᑍ  
ᑍᑍᑍ  
DᑍNOTE: This structure only defines fixed fields. Any varying  
Dᑍ length or repeating field will have to be defined by  
Dᑍ the user.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSð1ððE  
Dᑍ  
D QUSEPNðð  
Dᑍ  
D QUSFNð8  
DS  
BASED(INFSPCPTR)  
Qus EXTIð1ðð Entry  
1
2ð  
28  
Exit Point Name  
21  
Appendix B. Original Examples in Additional Languages B-77  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
Format Name  
D QUSMEP  
29  
33  
32B ð  
36B ð  
37  
Dᑍ  
Max Exit Programs  
Number Exit Programs  
Allow Deregistration  
Allow Change Control  
Registered Exit Point  
Prep Name Add Pgm  
Prep Lib Add Pgm  
Prep Format Add  
Prep Name Rmv Pgm  
Prep Lib Rmv Pgm  
Prep Format Rmv  
Prep Name Rtv Info  
Prep Lib Rtv Info  
Prep Format Rtv  
Desc Indicator  
D QUSNBREP  
Dᑍ  
D QUSAD  
37  
Dᑍ  
D QUSACC  
38  
38  
Dᑍ  
D QUSREP  
39  
39  
Dᑍ  
D QUSPNAP  
4ð  
49  
Dᑍ  
D QUSPLAP  
5ð  
59  
Dᑍ  
D QUSPFA  
6ð  
67  
Dᑍ  
D QUSPNRP  
68  
77  
Dᑍ  
D QUSPLRP  
78  
87  
Dᑍ  
D QUSPFR  
88  
95  
Dᑍ  
D QUSPNRI  
96  
1ð5  
Dᑍ  
D QUSPLRI  
1ð6  
116  
124  
125  
135  
145  
152  
2ð2  
115  
123  
124  
134  
144  
151  
2ð1  
2ð2  
Dᑍ  
D QUSPFRðð  
Dᑍ  
D QUSDI  
Dᑍ  
D QUSDMFIL  
Dᑍ  
Desc Msg File  
D QUSDMLIB  
Dᑍ  
Desc Msg Library  
Desc Msg Id  
D QUSDMI  
Dᑍ  
D QUSTD  
Dᑍ  
Text Description  
DᑍQUSERVEDð3  
Dᑍ  
Dᑍ  
Varying length  
BASED(BASSPCPTR)  
Qus EXTIð1ðð  
DQUSIð1ðð  
DS  
Dᑍ  
D QUSBRTN  
1
5
4B ð  
8B ð  
24  
Dᑍ  
Bytes Returned  
D QUSBAVLðð  
Dᑍ  
Bytes Available  
D QUSCH  
9
Dᑍ  
Continue Handle  
D QUSOEPE  
25  
29  
33  
37  
28B ð  
32B ð  
36B ð  
37  
Dᑍ  
Offset Exit Point Entry  
Number Points Returned  
Length Exit Point Entry  
D QUSNBRPR  
Dᑍ  
D QUSLEPE  
Dᑍ  
DᑍQUSERVEDð4  
Dᑍ  
B-78 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
Varying length  
DᑍQUSARRAYðð  
Dᑍ QUSEPNð1  
Dᑍ QUSFNð9  
Dᑍ QUSMEPðð  
Dᑍ QUSNBREPðð  
Dᑍ QUSADðð  
Dᑍ QUSACCðð  
Dᑍ QUSREPðð  
Dᑍ QUSPNAPðð  
Dᑍ QUSPLAPðð  
Dᑍ QUSPFAðð  
Dᑍ QUSPNRPðð  
Dᑍ QUSPLRPðð  
Dᑍ QUSPFRð1  
Dᑍ QUSPNRIðð  
Dᑍ QUSPLRIðð  
Dᑍ QUSPFRð2  
Dᑍ QUSDIðð  
Dᑍ QUSDMFILðð  
Dᑍ QUSDMLIBðð  
Dᑍ QUSDMIðð  
Dᑍ QUSTDðð  
Dᑍ QUSERVEDð5  
Dᑍ  
2ð2  
2ð  
8
DIM(ðððð1)  
OVERLAY(QUSARRAYðð:ðððð1)  
OVERLAY(QUSARRAYðð:ððð21)  
9B ð OVERLAY(QUSARRAYðð:ððð29)  
9B ð OVERLAY(QUSARRAYðð:ððð33)  
1
1
1
1ð  
1ð  
8
1ð  
1ð  
8
OVERLAY(QUSARRAYðð:ððð37)  
OVERLAY(QUSARRAYðð:ððð38)  
OVERLAY(QUSARRAYðð:ððð39)  
OVERLAY(QUSARRAYðð:ððð4ð)  
OVERLAY(QUSARRAYðð:ððð5ð)  
OVERLAY(QUSARRAYðð:ððð6ð)  
OVERLAY(QUSARRAYðð:ððð68)  
OVERLAY(QUSARRAYðð:ððð78)  
OVERLAY(QUSARRAYðð:ððð88)  
OVERLAY(QUSARRAYðð:ððð96)  
OVERLAY(QUSARRAYðð:ðð1ð6)  
OVERLAY(QUSARRAYðð:ðð116)  
OVERLAY(QUSARRAYðð:ðð124)  
OVERLAY(QUSARRAYðð:ðð125)  
OVERLAY(QUSARRAYðð:ðð135)  
OVERLAY(QUSARRAYðð:ðð145)  
OVERLAY(QUSARRAYðð:ðð152)  
OVERLAY(QUSARRAYðð:ðð2ð2)  
1ð  
1ð  
8
1
1ð  
1ð  
7
5ð  
1
Dᑍ  
Varying length  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍFormat structure for the EXTIð2ðð Format for the  
DᑍQusRetrieveExitInformation API.  
Dᑍᑍᑍᑍ  
ᑍᑍᑍ  
DᑍNOTE: This structure only defines fixed fields. Any varying  
Dᑍ length or repeating field will have to be defined by  
Dᑍ the user.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSð2ððE  
DS  
BASED(INFSPCPTR)  
Qus EXTIð2ðð Entry  
Dᑍ  
D QUSONE  
Dᑍ  
1
5
4B ð  
24  
Offset Next Entry  
Exit Point Name  
Format Name  
D QUSEPNð2  
Dᑍ  
D QUSFN1ð  
25  
33  
34  
35  
37  
41  
51  
61  
65  
32  
Dᑍ  
D QUSREPð1  
33  
Dᑍ  
Registered Exit Pt  
Complete Entry  
Reserved  
D QUSCE  
34  
Dᑍ  
D QUSERVEDð6  
36  
Dᑍ  
D QUSPGMN  
4ðB ð  
5ð  
Dᑍ  
Program Number  
Program Name  
D QUSPGMNðð  
Dᑍ  
D QUSPGML  
Dᑍ  
6ð  
Program Library  
Data CCSID  
D QUSDC  
Dᑍ  
D QUSOED  
Dᑍ  
64B ð  
68B ð  
Offset Exit Data  
Appendix B. Original Examples in Additional Languages B-79  
Download from Www.Somanuals.com. All Manuals Search And Download.  
D QUSLED  
Dᑍ  
DᑍQUSERVEDð6  
Dᑍ  
Dᑍ  
69  
73  
72B ð  
73  
Length Exit Data  
Varying length  
DᑍQUSPD  
Dᑍ QUSDATAð2  
Dᑍ  
1
74  
74  
Dᑍ  
Varying length  
BASED(BASSPCPTR)  
DQUSIð2ðð  
Dᑍ  
DS  
Qus EXTIð2ðð  
D QUSBRTNðð  
Dᑍ  
D QUSBAVLð1  
Dᑍ  
D QUSCHðð  
Dᑍ  
1
5
4B ð  
8B ð  
24  
Bytes Returned  
Bytes Available  
9
Continue Handle  
D QUSOPGME  
Dᑍ  
D QUSNBRPRðð  
Dᑍ  
D QUSLPGME  
Dᑍ  
DᑍQUSERVEDð7  
Dᑍ  
Dᑍ  
25  
29  
33  
37  
28B ð  
32B ð  
36B ð  
37  
Offset Program Entry  
Number Programs Returned  
Length Program Entry  
Varying length  
DIM(ðððð1)  
DᑍQUSARRAYð1  
Dᑍ QUSONEðð  
Dᑍ QUSEPNð3  
Dᑍ QUSFN11  
Dᑍ QUSREPð2  
Dᑍ QUSCEðð  
Dᑍ QUSERVEDð8  
Dᑍ QUSPGMNð1  
Dᑍ QUSPGMNð2  
Dᑍ QUSPGMLðð  
Dᑍ QUSDCðð  
Dᑍ QUSOEDðð  
Dᑍ QUSLEDðð  
Dᑍ QUSERVEDð8  
Dᑍ QUSPDðð  
Dᑍ QUSDATAð3  
Dᑍ  
74  
9B ð OVERLAY(QUSARRAYð1:ðððð1)  
2ð  
OVERLAY(QUSARRAYð1:ðððð5)  
OVERLAY(QUSARRAYð1:ððð25)  
OVERLAY(QUSARRAYð1:ððð33)  
OVERLAY(QUSARRAYð1:ððð34)  
OVERLAY(QUSARRAYð1:ððð35)  
8
1
1
2
9B ð OVERLAY(QUSARRAYð1:ððð37)  
1ð  
1ð  
OVERLAY(QUSARRAYð1:ððð41)  
OVERLAY(QUSARRAYð1:ððð51)  
9B ð OVERLAY(QUSARRAYð1:ððð61)  
9B ð OVERLAY(QUSARRAYð1:ððð65)  
9B ð OVERLAY(QUSARRAYð1:ððð69)  
1
1
1
OVERLAY(QUSARRAYð1:ððð73)  
OVERLAY(QUSARRAYð1:ðððð1)  
Varying length  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍFormat structure for the EXTIð3ðð Format for the  
DᑍQusRetrieveExitInformation API.  
Dᑍᑍᑍᑍ  
ᑍᑍᑍ  
DᑍNOTE: This structure only defines fixed fields. Any varying  
Dᑍ length or repeating field will have to be defined by  
Dᑍ the user.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSð3ððE  
DS  
Dᑍ  
Qus EXTIð3ðð Entry  
Offset Next Entry  
Exit Point Name  
D QUSONEð1  
Dᑍ  
D QUSEPNð4  
Dᑍ  
1
5
4B ð  
24  
B-80 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
D QUSFN12  
25  
33  
32  
Dᑍ  
Format Name  
D QUSREPð3  
33  
Dᑍ  
Registered Exit Point  
Complete Entry  
Reserved  
D QUSCEð1  
34  
34  
Dᑍ  
D QUSERVEDð9  
35  
36  
Dᑍ  
D QUSPGMNð3  
37  
4ðB ð  
5ð  
Dᑍ  
Program Number  
Program Name  
Program Library  
Desc Indicator  
Message File  
Message File Library  
Message Id  
D QUSPGMNð4  
41  
Dᑍ  
D QUSPGMLð1  
51  
6ð  
Dᑍ  
D QUSDIð1  
61  
61  
Dᑍ  
D QUSMFILðð  
62  
71  
Dᑍ  
D QUSMFILL  
72  
81  
Dᑍ  
D QUSMIðð  
82  
88  
Dᑍ  
D QUSTDð1  
89  
138  
Dᑍ  
Text Desc  
D QUSRSV2ð1  
139  
141  
145  
149  
153  
14ð  
Dᑍ  
Reserved2  
D QUSDCð1  
144B ð  
148B ð  
152B ð  
153  
Dᑍ  
Data CCSID  
D QUSOPD  
Dᑍ  
Offset Pgm Data  
Length Pgm Data  
D QUSLPD  
Dᑍ  
DᑍQUSERVEDð9  
Dᑍ  
Dᑍ  
Varying length  
DᑍQUSPDð1  
Dᑍ QUSDATAð4  
Dᑍ  
Dᑍ  
1
154  
154  
Varying length  
Qus EXTIð3ðð  
DQUSIð3ðð  
Dᑍ  
DS  
D QUSBRTNð1  
1
5
4B ð  
8B ð  
24  
Dᑍ  
Bytes Returned  
D QUSBAVLð2  
Dᑍ  
Bytes Available  
D QUSCHð1  
9
Dᑍ  
Continue Handle  
D QUSOPGMEðð  
25  
29  
33  
37  
28B ð  
32B ð  
36B ð  
37  
Dᑍ  
Offset Program Entry  
Number Programs Returned  
Length Program Entry  
D QUSNBRPRð1  
Dᑍ  
D QUSLPGMEðð  
Dᑍ  
DᑍQUSERVED1ð  
Dᑍ  
Dᑍ  
DᑍQUSARRAYð2  
Dᑍ QUSONEð2  
Varying length  
DIM(ðððð1)  
154  
9B ð OVERLAY(QUSARRAYð2:ðððð1)  
Appendix B. Original Examples in Additional Languages B-81  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ QUSEPNð5  
Dᑍ QUSFN13  
Dᑍ QUSREPð4  
Dᑍ QUSCEð2  
Dᑍ QUSERVED11  
Dᑍ QUSPGMNð5  
Dᑍ QUSPGMNð6  
Dᑍ QUSPGMLð2  
Dᑍ QUSDIð2  
Dᑍ QUSMFILð1  
Dᑍ QUSMFILLðð  
Dᑍ QUSMIð1  
Dᑍ QUSTDð2  
Dᑍ QUSRSV2ð2  
Dᑍ QUSDCð2  
Dᑍ QUSOPDðð  
Dᑍ QUSLPDðð  
Dᑍ QUSERVED11  
Dᑍ QUSPDð2  
Dᑍ QUSDATAð5  
Dᑍ  
2ð  
8
OVERLAY(QUSARRAYð2:ðððð5)  
OVERLAY(QUSARRAYð2:ððð25)  
OVERLAY(QUSARRAYð2:ððð33)  
OVERLAY(QUSARRAYð2:ððð34)  
OVERLAY(QUSARRAYð2:ððð35)  
1
1
2
9B ð OVERLAY(QUSARRAYð2:ððð37)  
1ð  
1ð  
1
1ð  
1ð  
7
OVERLAY(QUSARRAYð2:ððð41)  
OVERLAY(QUSARRAYð2:ððð51)  
OVERLAY(QUSARRAYð2:ððð61)  
OVERLAY(QUSARRAYð2:ððð62)  
OVERLAY(QUSARRAYð2:ððð72)  
OVERLAY(QUSARRAYð2:ððð82)  
OVERLAY(QUSARRAYð2:ððð89)  
OVERLAY(QUSARRAYð2:ðð139)  
5ð  
2
9B ð OVERLAY(QUSARRAYð2:ðð141)  
9B ð OVERLAY(QUSARRAYð2:ðð145)  
9B ð OVERLAY(QUSARRAYð2:ðð149)  
1
1
1
OVERLAY(QUSARRAYð2:ðð153)  
OVERLAY(QUSARRAYð2:ðððð1)  
Varying length  
Dᑍ  
Dᑍ  
Dᑍ Error Code parameter include. As this sample program  
Dᑍ uses /COPY to include the error code structure, only the first  
Dᑍ 16 bytes of the error code structure are available. If the  
Dᑍ application program needs to access the variable length  
Dᑍ exception data for the error, the developer should physically  
Dᑍ copy the QSYSINC include and modify the copied include to  
Dᑍ define additional storage for the exception data.  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍPrototype for calling Retrieve Exit Information  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
D QUSREI  
Dᑍ  
C
'QusRetrieveExitInformation'  
Dᑍ Miscellaneous data  
Dᑍ  
DEPNTNAME  
DEPGM_NBR  
DRCVVAR  
S
S
S
S
S
S
S
2ð  
1
INZ('EXAMPLE_EXIT_POINT')  
9B ð INZ(-1)  
DIM(35ðð)  
9B ð INZ(%SIZE(RCVVAR:ᑍALL))  
DRCVVAR_SZ  
DBASSPCPTR  
DINFSPCPTR  
DCALL_PGM  
Cᑍ  
ᑍ
ᑍ
21  
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Retrieve the exit point information first. If the current  
Cᑍ number of exit programs is not zero, retrieve the exit  
Cᑍ programs. It is not necessary to call for the exit point  
Cᑍ information to determine if the exit point has any exit  
Cᑍ programs. It is done here for illustrative purposes only.  
Cᑍ You can make one call to the API for the exit program  
Cᑍ information and check the number of exit program entries  
Cᑍ returned field to see if there are any exit programs to call.  
B-82 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
Cᑍ Initialize the error code to inform the API that all  
Cᑍ exceptions should be returned through the error code parameter.  
Cᑍ  
C
Cᑍ  
EVAL  
QUSBPRV = %SIZE(QUSEC)  
Cᑍ Blank out the continuation handle to let the API know that this  
Cᑍ is a first attempt at the retrieve operation.  
Cᑍ  
C
MOVE  
ᑍBLANKS  
CONTIN_HDL  
16  
Cᑍ  
Cᑍ Call the API to retrieve the exit programs  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
Cᑍ  
CALLB  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
QUSREI  
CONTIN_HDL  
RCVVAR  
RCVVAR_SZ  
FORMAT  
EPNTNAME  
EPNT_FMT  
EPGM_NBR  
QUSNBRSC  
QUSEC  
'EXTIð1ðð'  
'EXMPð1ðð'  
ð
8
8
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
QPRINT  
ERRAEPNT  
DONE  
C
OPEN  
EXCEPT  
EXSR  
ENDIF  
C
C
C
Cᑍ  
Cᑍ If the call to retrieve exit point information is successful,  
Cᑍ check to see if there are any exit programs to call.  
Cᑍ  
C
EVAL  
IF  
EVAL  
IF  
BASSPCPTR = %ADDR(RCVVAR)  
QUSNBRPR > ð  
INFSPCPTR = %ADDR(RCVVAR(QUSOEPE+1))  
QUSNBREP > ð  
C
C
C
Cᑍ  
Cᑍ There are some exit programs to call. Blank out the continuation  
Cᑍ handle to let the API know that this is a first attempt at the  
Cᑍ retrieve operation.  
Cᑍ  
C
EVAL  
CONTIN_HDL = ᑍBLANKS  
Cᑍ  
Cᑍ Call the exit programs  
Cᑍ  
C
EXSR  
CUSREI  
Cᑍ  
Cᑍ If the continuation handle field in the receiver variable is  
Cᑍ not set to blanks, the API has more information to return than  
Cᑍ what could fit in the receiver variable. Call the API for  
Cᑍ more exit programs to call.  
Cᑍ  
Appendix B. Original Examples in Additional Languages B-83  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
DOW  
QUSCHðð <> ᑍBLANKS  
CONTIN_HDL = QUSCHðð  
CUSREI  
C
EVAL  
EXSR  
ENDDO  
ENDIF  
ENDIF  
EXSR  
C
C
C
C
C
DONE  
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ Process exit programs in receiver variable  
Cᑍ  
C
Cᑍ  
CUSREI  
BEGSR  
Cᑍ Call the API to retrieve the exit program information  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
Cᑍ  
CALLB  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
QUSREI  
CONTIN_HDL  
RCVVAR  
RCVVAR_SZ  
FORMAT  
EPNTNAME  
EPNT_FMT  
EPGM_NBR  
QUSNBRSC  
QUSEC  
'EXTIð2ðð'  
'EXMPð1ðð'  
ð
8
8
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
QPRINT  
ERRAEPGM  
DONE  
C
OPEN  
EXCEPT  
EXSR  
ENDIF  
C
C
C
Cᑍ  
Cᑍ If the call to retrieve exit program information is successful,  
Cᑍ check to see if there are any exit programs to call.  
Cᑍ  
Cᑍ The receiver variable offers enough room for a minimum of one  
Cᑍ exit program entry because the receiver variable was declared  
Cᑍ as 35ðð bytes. Therefore, this example only checks the  
Cᑍ number of exit programs returned field. If the receiver  
Cᑍ variable were not large enough to hold at least one entry,  
Cᑍ the bytes available field would need to be checked as well as  
Cᑍ the number of exit programs returned field. If the number of  
Cᑍ exit programs returned field is set to zero and the bytes  
Cᑍ available field is greater than the bytes returned field, the  
Cᑍ API had at least one exit program entry to return but was  
Cᑍ unable to because the receiver variable was too small.  
Cᑍ  
C
EVAL  
DO  
INFSPCPTR = %ADDR(RCVVAR(QUSOPGME+1))  
QUSNBRPRðð  
C
Cᑍ  
Cᑍ Get the exit program name and library  
Cᑍ  
B-84 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
EVAL  
CALL_PGM = %TRIMR(QUSPGML) +  
'/' + QUSPGMNðð  
C
Cᑍ  
Cᑍ Call the exit program while ignoring failures on the call  
Cᑍ  
C
CALL  
PARM  
CALL_PGM  
ð1  
C
Cᑍ  
EXIT_PARMS  
1ð  
Cᑍ Set INFSPCPTR to point to the next exit program entry  
Cᑍ  
C
EVAL  
ENDDO  
ENDSR  
INFSPCPTR = %ADDR(RCVVAR(QUSONE+1))  
C
C
Cᑍ  
Cᑍ Return to programs caller  
C
DONE  
BEGSR  
EVAL  
RETURN  
ENDSR  
C
ᑍINLR = '1'  
C
C
Oᑍ  
OQPRINT  
E
E
ERRAEPNT  
1 6  
1 6  
O
'Attempt to retrieve infor-  
mation failed: '  
O
O
QUSEI  
OQPRINT  
ERRAEPGM  
O
O
O
'Attempt to retrieve Exit -  
Programs failed: '  
QUSEI  
Remove Exit Program and Deregister Exit Point—OPM COBOL  
Example  
Refer to “Remove Exit Program and Deregister Exit Point—ILE C Example” on  
page 4-19 for the original example.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
Remove an Exit Program  
Deregister an Exit Point  
ᑍ
ᑍ
ᑍ Language:  
ᑍ
OPM COBOL  
ᑍ Description: This program removes an exit program and  
ᑍ
deregisters an exit point from the registration  
facility.  
ᑍ
ᑍ
ᑍ APIs Used:  
QUSRMVEP - Remove Exit Program  
QUSDRGPT - Deregister Exit Point  
ᑍ
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-ID. REGFAC1.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
Appendix B. Original Examples in Additional Languages B-85  
Download from Www.Somanuals.com. All Manuals Search And Download.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Error message text  
ᑍ
ð1 BAD-EXIT-POINT.  
ð5 TEXT1  
PIC X(41)  
VALUE "Attempt to deregister exit point failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ð1 BAD-EXIT-PGM.  
ð5 TEXT1  
PIC X(39)  
VALUE "Attempt to remove exit program failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 MISC.  
ð5 PGM-NBR  
PIC S9(ð9) VALUE 1 BINARY.  
ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".  
ð5 FORMAT-NAME PIC X(ð8) VALUE "EXMPð1ðð".  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
ᑍ
ᑍ Remove an exit program from the exit point and then deregister  
ᑍ the exit point. It is not necessary to remove exit programs  
ᑍ from an exit point before deregistering the exit point. It is  
ᑍ done here only for illustrative purposes.  
ᑍ
ᑍ Initialize the error code parameter. To signal exceptions to  
ᑍ this program by the API, you need to set the bytes provided  
ᑍ field of the error code to zero. Because this program has  
ᑍ exceptions sent back through the error code parameter, it sets  
ᑍ the bytes provided field to the number of bytes it gives the  
ᑍ API for the parameter.  
ᑍ
B-86 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
MOVE 16 TO BYTES-PROVIDED OF QUS-EC.  
ᑍ
ᑍ Call the API to remove the exit program.  
ᑍ
CALL "QUSRMVEP" USING EXIT-POINT-NAME, FORMAT-NAME,  
PGM-NBR, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-EXIT-POINT,  
WRITE LIST-LINE FROM BAD-EXIT-POINT,  
STOP RUN.  
ᑍ
ᑍ If the call to remove the exit program is successful,  
ᑍ deregister the exit point.  
ᑍ
ᑍ Call the API to deregister the exit point.  
ᑍ
CALL "QUSDRGPT" USING EXIT-POINT-NAME, FORMAT-NAME, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-EXIT-PGM,  
WRITE LIST-LINE FROM BAD-EXIT-PGM,  
STOP RUN.  
ᑍ
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
ᑍ
Remove Exit Program and Deregister Exit Point—ILE COBOL Example  
Refer to “Remove Exit Program and Deregister Exit Point—ILE C Example” on  
page 4-19 for the original example.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
Remove an Exit Program  
Deregister an Exit Point  
ᑍ
ᑍ
ᑍ Language:  
ᑍ
ILE COBOL  
ᑍ Description: This program removes an exit program and  
Appendix B. Original Examples in Additional Languages B-87  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
deregisters an exit point from the registration  
facility.  
ᑍ
ᑍ
ᑍ APIs Used:  
QusRemoveExitProgram - Remove Exit Program  
QusDeregisterExitPoint - Deregister Exit Point  
ᑍ
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-ID. REGFAC3.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Error message text  
ᑍ
ð1 BAD-EXIT-POINT.  
ð5 TEXT1  
PIC X(41)  
VALUE "Attempt to deregister exit point failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ð1 BAD-EXIT-PGM.  
ð5 TEXT1  
PIC X(39)  
VALUE "Attempt to remove exit program failed: ".  
ð5 EXCEPTION-ID PIC X(ð7).  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 MISC.  
ð5 PGM-NBR  
PIC S9(ð9) VALUE 1 BINARY.  
ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".  
ð5 FORMAT-NAME PIC X(ð8) VALUE "EXMPð1ðð".  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
B-88 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ Remove an exit program from the exit point and then deregister  
ᑍ the exit point. It is not necessary to remove exit programs  
ᑍ from an exit point before deregistering the exit point. It is  
ᑍ done here only for illustrative purposes.  
ᑍ
ᑍ Initialize the error code parameter. To signal exceptions to  
ᑍ this program by the API, you need to set the bytes provided  
ᑍ field of the error code to zero. Because this program has  
ᑍ exceptions sent back through the error code parameter, it sets  
ᑍ the bytes provided field to the number of bytes it gives the  
ᑍ API for the parameter.  
ᑍ
MOVE 16 TO BYTES-PROVIDED OF QUS-EC.  
ᑍ
ᑍ Call the API to remove the exit program.  
ᑍ
CALL PROCEDURE "QusRemoveExitProgram" USING  
EXIT-POINT-NAME, FORMAT-NAME,  
PGM-NBR, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-EXIT-POINT,  
WRITE LIST-LINE FROM BAD-EXIT-POINT,  
STOP RUN.  
ᑍ
ᑍ If the call to remove the exit program is successful,  
ᑍ deregister the exit point.  
ᑍ
ᑍ Call the API to deregister the exit point.  
ᑍ
CALL PROCEDURE "QusDeregisterExitPoint" USING  
EXIT-POINT-NAME, FORMAT-NAME, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
OPEN OUTPUT LISTING,  
MOVE EXCEPTION-ID OF QUS-EC  
TO EXCEPTION-ID OF BAD-EXIT-PGM,  
WRITE LIST-LINE FROM BAD-EXIT-PGM,  
STOP RUN.  
ᑍ
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
ᑍ
Appendix B. Original Examples in Additional Languages B-89  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Remove Exit Program and Deregister Exit Point—OPM RPG Example  
Refer to “Remove Exit Program and Deregister Exit Point—ILE C Example” on  
page 4-19 for the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program:  
Remove an Exit Program  
Deregister an Exit Point  
Fᑍ  
Fᑍ  
Fᑍ Language:  
Fᑍ  
OPM RPG  
Fᑍ Description: This program removes an exit program and  
Fᑍ  
deregisters an exit point from the registration  
facility.  
Fᑍ  
Fᑍ  
Fᑍ APIs Used:  
QUSRMVEP - Remove Exit Program  
QUSDRGPT - Deregister Exit Point  
Fᑍ  
Fᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQPRINT O F  
Iᑍ  
132  
PRINTER  
UC  
Iᑍ Error Code parameter include. As this sample program  
Iᑍ uses /COPY to include the error code structure, only the first  
Iᑍ 16 bytes of the error code structure are available. If the  
Iᑍ application program needs to access the variable length  
Iᑍ exception data for the error, the developer should physically  
Iᑍ copy the QSYSINC include and modify the copied include to  
Iᑍ define additional storage for the exception data.  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSEC  
Iᑍ  
Iᑍ  
Iᑍ Miscellaneous data  
Iᑍ  
I
DS  
I
B 1 4ðPGMNBR  
'EXAMPLE_EXIT_POINT ' 5 24 EPNTNM  
I I  
Cᑍ  
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Remove an exit program from the exit point and then deregister  
Cᑍ the exit point. It is not necessary to remove exit programs  
Cᑍ from an exit point before deregistering the exit point. It is  
Cᑍ done here only for illustrative purposes.  
Cᑍ  
Cᑍ Initialize the error code parameter. To signal exceptions to  
Cᑍ this program by the API, you need to set the bytes provided  
Cᑍ field of the error code to zero. Because this program has  
Cᑍ exceptions sent back through the error code parameter, it sets  
Cᑍ the bytes provided field to the number of bytes it gives the  
Cᑍ API for the parameter.  
Cᑍ  
C
Z-ADD16  
QUSBNB  
Cᑍ  
Cᑍ Call the API to remove the exit program.  
B-90 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
C
CALL 'QUSRMVEP'  
PARM  
C
EPNTNM  
C
PARM 'EXMPð1ðð'FORMAT 8  
C
PARM 1  
PARM  
PGMNBR  
QUSBN  
C
Cᑍ  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
QUSBNC  
IFGT ð  
C
OPEN QPRINT  
EXCPTERRPGM  
EXSR DONE  
ENDIF  
C
C
C
Cᑍ  
Cᑍ If the call to remove the exit program is successful,  
Cᑍ deregister the exit point.  
Cᑍ  
Cᑍ Call the API to deregister the exit point.  
Cᑍ  
C
CALL 'QUSDRGPT'  
PARM  
PARM 'EXMPð1ðð'FORMAT  
PARM QUSBN  
C
EPNTNM  
C
C
Cᑍ  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
QUSBNC  
IFGT ð  
C
OPEN QPRINT  
EXCPTERREPT  
EXSR DONE  
ENDIF  
C
C
C
C
EXSR DONE  
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ  
Cᑍ Return to programs caller  
C
DONE  
BEGSR  
SETON  
RETRN  
ENDSR  
C
LR  
C
C
Oᑍ  
OQPRINT E 1ð6  
ERREPT  
O
'Attempt to deregister '  
'exit point failed: '  
O
O
QUSBND  
ERRPGM  
OQPRINT E 1ð6  
O
O
O
'Attempt to remove exit '  
'program failed: '  
QUSBND  
Appendix B. Original Examples in Additional Languages B-91  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Remove Exit Program and Deregister Exit Point—ILE RPG Example  
Refer to “Remove Exit Program and Deregister Exit Point—ILE C Example” on  
page 4-19 for the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program:  
Remove an Exit Program  
Deregister an Exit Point  
Fᑍ  
Fᑍ  
Fᑍ Language:  
Fᑍ  
ILE RPG  
Fᑍ Description: This program removes an exit program and  
Fᑍ  
deregisters an exit point from the registration  
facility.  
Fᑍ  
Fᑍ  
Fᑍ APIs Used:  
QusRemoveExitProgram - Remove Exit Program  
QusDeregisterExitPoint - Deregister Exit Point  
Fᑍ  
Fᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQPRINT  
Dᑍ  
O
F 132  
PRINTER OFLIND(ᑍINOF) USROPN  
Dᑍ Error Code parameter include. As this sample program  
Dᑍ uses /COPY to include the error code structure, only the first  
Dᑍ 16 bytes of the error code structure are available. If the  
Dᑍ application program needs to access the variable length  
Dᑍ exception data for the error, the developer should physically  
Dᑍ copy the QSYSINC include and modify the copied include to  
Dᑍ define additional storage for the exception data.  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍPrototype for calling Deregister Exit Point API.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
D QUSDEP  
C
'QusDeregisterExitPoint'  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍPrototype for calling Remove Exit Program API.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
D QUSREPGM  
Dᑍ  
C
'QusRemoveExitProgram'  
Dᑍ Miscellaneous data  
Dᑍ  
DPGM_NBR  
DEPNTNAME  
Cᑍ  
9B ð  
2ð  
S
INZ('EXAMPLE_EXIT_POINT')  
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Remove an exit program from the exit point and then deregister  
Cᑍ the exit point. It is not necessary to remove exit programs  
Cᑍ from an exit point before deregistering the exit point. It is  
Cᑍ done here only for illustrative purposes.  
Cᑍ  
Cᑍ Initialize the error code parameter. To signal exceptions to  
Cᑍ this program by the API, you need to set the bytes provided  
Cᑍ field of the error code to zero. Because this program has  
B-92 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ exceptions sent back through the error code parameter, it sets  
Cᑍ the bytes provided field to the number of bytes it gives the  
Cᑍ API for the parameter.  
Cᑍ  
C
EVAL  
QUSBPRV = %SIZE(QUSEC)  
Cᑍ  
Cᑍ Call the API to remove the exit program.  
Cᑍ  
C
CALLB  
PARM  
PARM  
PARM  
PARM  
QUSREPGM  
C
EPNTNAME  
FORMAT  
PGM_NBR  
QUSEC  
C
'EXMPð1ðð'  
1
8
C
C
Cᑍ  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
QPRINT  
ERRAEPGM  
DONE  
C
OPEN  
EXCEPT  
EXSR  
ENDIF  
C
C
C
Cᑍ  
Cᑍ If the call to remove the exit program is successful,  
Cᑍ deregister the exit point.  
Cᑍ  
Cᑍ Call the API to deregister the exit point.  
Cᑍ  
C
CALLB  
PARM  
PARM  
PARM  
QUSDEP  
C
EPNTNAME  
FORMAT  
QUSEC  
C
'EXMPð1ðð'  
C
Cᑍ  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
QPRINT  
ERRAEPNT  
DONE  
C
OPEN  
EXCEPT  
EXSR  
ENDIF  
EXSR  
C
C
C
C
DONE  
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ  
Cᑍ Return to programs caller  
C
DONE  
BEGSR  
EVAL  
RETURN  
ENDSR  
C
ᑍINLR = '1'  
C
C
Oᑍ  
OQPRINT  
O
E
ERRAEPNT  
1 6  
'Attempt to deregister -  
Appendix B. Original Examples in Additional Languages B-93  
Download from Www.Somanuals.com. All Manuals Search And Download.  
O
exit point failed: '  
O
QUSEI  
ERRAEPGM  
OQPRINT  
E
1 6  
O
O
O
'Attempt to remove exit -  
program failed: '  
QUSEI  
List Object API—Examples  
This section includes the examples in “List Object API—OPM RPG Example” on  
page 5-4.  
List Object API—ILE C Example  
Refer to “List Object API—OPM RPG Example” on page 5-4 for the original  
example. This example uses includes from the QSYSINC library.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Program:  
List objects that adopt owner authority  
ILE C  
/ᑍ  
/ᑍ Language:  
/ᑍ  
/ᑍ Description: This program prints a report showing all objects  
/ᑍ  
that adopt owner authority. The two parameters  
passed to the program are the profile to be  
checked and the type of objects to be listed.  
The parameter values are the same as those  
accepted by the QSYLOBJP API.  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ APIs Used:  
QSYLOBJP - List Objects that Adopt Owner Authority ᑍ/  
QUSCRTUS - Create User Space  
QUSPTRUS - Retrieve Pointer to User Space  
QUSROBJD - Retrieve Object Description  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdio.h>  
#include <string.h>  
#include <qsylobjp.h>  
#include <quscrtus.h>  
#include <qusptrus.h>  
#include <qusrobjd.h>  
#include <qusgen.h>  
#include <qusec.h>  
/ᑍ QSYLOBJP API Header  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ QUSCRTUS API Header  
/ᑍ QUSPTRUS API Header  
/ᑍ QUSROBJD API Header  
/ᑍ Format Structures for User Space  
/ᑍ Error Code Parameter Include for the APIs ᑍ/  
/ᑍ Entry Point Table Include  
#include <qliept.h>  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Error Code Structure  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍ This shows how the user can define the variable length portion of ᑍ/  
/ᑍ error code for the exception data.  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
typedef struct {  
Qus_EC_t ec_fields;  
B-94 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
char  
Exception_Data[1ðð];  
} error_code_t;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Global Variables ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
char  
int  
api_name[1ð];  
cont_hdl[2ð];  
ext_attr[1ð];  
list_status;  
mbr_list[8];  
obj_type[1ð];  
rcvvar[8];  
rjobd_fmt[8];  
space_auth[1ð];  
space_dmn[1ð];  
space_init;  
space_name[2ð];  
space_rep[1ð];  
space_text[5ð];  
space_type[1ð];  
usr_prf[1ð];  
ᑍusrspc_ptr, ᑍusrspc_base;  
rcvlen = 8;  
size_entry;  
space_size = 1;  
int  
int  
error_code_t error_code;  
FILE  
ᑍrecord;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function:  
/ᑍ  
done  
ᑍ/  
ᑍ/  
/ᑍ Description: This function prints the end of listing print line ᑍ/  
/ᑍ  
and returns to the caller.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void done()  
{
char command_string[32];  
fwrite("ᑍᑍᑍ End of List",1, 15, record);  
fclose(record);  
exit();  
} /ᑍ done ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function:  
/ᑍ  
apierr  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Description: This function prints the API name, and exception  
/ᑍ  
identifier of an error that occurred.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void apierr()  
{
printf("API: %.1ðs\n", api_name);  
printf("Failed with exception: %.7s\n",  
error_code.ec_fields.Exception_Id);  
done();  
Appendix B. Original Examples in Additional Languages B-95  
Download from Www.Somanuals.com. All Manuals Search And Download.  
} /ᑍ apierr ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function:  
/ᑍ  
getlst  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Description: This function calls QSYLOBJP to build a list.  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void getlst()  
{
memcpy(mbr_list, "OBJPð2ðð", 8);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call QSYLOBJP API to generate a list. The continuation handle ᑍ/  
/ᑍ is set by the caller of this function.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QSYLOBJP(space_name,  
mbr_list,  
/ᑍ User space and library  
/ᑍ Member list  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
usr_prf,  
/ᑍ User profile  
obj_type,  
cont_hdl,  
&error_code);  
/ᑍ Object type  
/ᑍ Continuation handle .3/  
/ᑍ Error code  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Check for errors on QSYLOBJP.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if(error_code.ec_fields.Bytes_Available > ð)  
{
memcpy(api_name, "QSYLOBJP ", 1ð);  
apierr();  
}
} /ᑍ getlst ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function:  
/ᑍ  
init  
ᑍ/  
ᑍ/  
/ᑍ Description: This function does all the necessary initialization ᑍ/  
/ᑍ  
for this program.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void init()  
{
memcpy(space_name, "ADOPTS  
space_init = ðxðð;  
QTEMP  
", 2ð);  
memcpy(mbr_list, "OBJPð2ðð", 8);  
memcpy(rjobd_fmt, "OBJDð1ðð", 8);  
memcpy(space_type, "ᑍUSRSPC ", 1ð);  
memcpy(ext_attr, "QSYLOBJP ", 1ð);  
memcpy(space_auth, "ᑍALL  
memcpy(space_rep, "ᑍYES  
memcpy(space_dmn, "ᑍUSER  
", 1ð);  
", 1ð);  
", 1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Open QPRINT file so that data can be written to it. If the file ᑍ/  
/ᑍ cannot be opened, print a message and exit.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if((record = fopen("QPRINT", "wb, lrecl=132, type=record")) == NULL)  
B-96 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
{
}
printf("File could not be opened\n");  
exit(1);  
error_code.ec_fields.Bytes_Provided = sizeof(error_code_t);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Call QUSROBJD to see if the user space was previously created in ᑍ/  
/ᑍ QTEMP. If it was, simply reuse it.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSROBJD(rcvvar,  
rcvlen,  
/ᑍ Receiver variable  
/ᑍ Receiver variable length  
/ᑍ Format  
/ᑍ User space name and library  
/ᑍ User object type  
/ᑍ Error code  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
rjobd_fmt,  
space_name,  
space_type,  
&error_code);  
if(error_code.ec_fields.Bytes_Available > ð)  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If a CPF98ð1 error was received, then the user space was not ᑍ/  
/ᑍ found.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if(memcmp(error_code.ec_fields.Exception_Id, "CPF98ð1", 7) == ð)  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Create a user space for the list generated by QSYLOBJP.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSCRTUS(space_name,  
ext_attr,  
/ᑍ User space name and library  
/ᑍ Extended attribute  
/ᑍ Size of the user space  
/ᑍ Space initialization  
/ᑍ Public authority to user space ᑍ/  
/ᑍ User space text ᑍ/  
/ᑍ Replace existing user space? ᑍ/  
/ᑍ Error Code ᑍ/  
/ᑍ Domain of created user space ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
space_size,  
&space_init,  
space_auth,  
space_text,  
space_rep,  
&error_code,  
space_dmn);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Check for errors on QUSCRTUS.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if(error_code.ec_fields.Bytes_Available > ð)  
{
memcpy(api_name, "QUSCRTUS ", 1ð);  
apierr();  
}
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ An error occurred accessing the user space.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
else  
{
memcpy(api_name, "QUSRJOBD ", 1ð);  
apierr();  
}
}
Appendix B. Original Examples in Additional Languages B-97  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Set QSYLOBJP (via GETLST) to start a new list.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(cont_hdl, ' ', 2ð);  
getlst();  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Get a resolved pointer to the user space for performance.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
QUSPTRUS(space_name,  
&usrspc_ptr,  
/ᑍ User space name and library  
/ᑍ User space pointer  
/ᑍ Error Code  
ᑍ/  
ᑍ/  
ᑍ/  
&error_code);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Check for errors on QUSPTRUS.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if(error_code.ec_fields.Bytes_Available > ð)  
{
memcpy(api_name, "QUSPTRUS ", 1ð);  
apierr();  
}
usrspc_base = usrspc_ptr;  
} /ᑍ init ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function:  
/ᑍ  
proces2  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Description: This function processes each entry returned by  
/ᑍ  
/ᑍ  
QSYLOBJP.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void proces2()  
{
char obj_type[112];  
sprintf(obj_type, "Object: %.1ðs Library: %.1ðs Type: %.1ðs Text: %.5ðs\n",  
((Qsy_OBJPð2ðð_List_T ᑍ)usrspc_ptr)->Object.Name,  
((Qsy_OBJPð2ðð_List_T ᑍ)usrspc_ptr)->Object.Library,  
((Qsy_OBJPð2ðð_List_T ᑍ)usrspc_ptr)->Object_Type,  
((Qsy_OBJPð2ðð_List_T ᑍ)usrspc_ptr)->Object_Text);  
fwrite(obj_type, 1, 112, record);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ After each entry, increment to the next entry.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
usrspc_ptr += size_entry;  
.7/  
} /ᑍ proces2 ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function:  
/ᑍ  
proces1  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Description: This function processes each entry returned by  
/ᑍ  
/ᑍ  
QSYLOBJP.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
B-98 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
void proces1()  
{
int i;  
int num_entries;  
int offset;  
num_entries = ((Qus_Generic_Header_ð1ðð_t ᑍ)\  
usrspc_ptr)->Number_List_Entries;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If valid information was returned. .1/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if((((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Information_Status == 'C') ||  
(((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Information_Status == 'P'))  
{
if(num_entries > ð)  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Get the size of each entry to use later. .4/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
size_entry = ((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Size_Each_Entry;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Increment to the first list entry.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
offset = ((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Offset_List_Data; .5/  
usrspc_ptr += offset;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Process all of the entries.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
for(i=ð; i<num_entries; i++)  
proces2();  
.6/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Reset the user space pointer to the beginning. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
usrspc_ptr = usrspc_base;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If all entries in this user space have been processed, check ᑍ/  
/ᑍ if more entries exist than can fit in one user space.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if(((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Information_Status == 'P')  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Address the input parameter header.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
offset = ((Qus_Generic_Header_ð1ðð_t ᑍ)\  
usrspc_ptr)->Offset_Input_Parameter;  
usrspc_ptr += offset;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If the continuation handle in the input parameter header ᑍ/  
/ᑍ is blank, then set the list status to complete.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
if(memcmp(((Qsy_OBJP_Input_T ᑍ)usrspc_ptr)->Continuation_Handle,  
"
", 2ð) == ð)  
Appendix B. Original Examples in Additional Languages B-99  
Download from Www.Somanuals.com. All Manuals Search And Download.  
{
}
list_status = 'C';  
else  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Else, call QSYLOBJP reusing the user space to get more  
/ᑍ list entries.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
{
memcpy(cont_hdl, ((Qsy_OBJP_Input_T ᑍ)\  
usrspc_ptr)->Continuation_Handle, 2ð);  
.2/  
getlst();  
list_status = ((Qus_Generic_Header_ð1ðð_t ᑍ)\  
usrspc_ptr)->Information_Status;  
}
}
}
else  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ If there exists an unexpected status, log an error (not shown) ᑍ/  
/ᑍ and exit.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
{
done();  
}
}
} /ᑍ proces1 ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function:  
/ᑍ  
proces  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Description: Processes entries until they are complete.  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void proces()  
{
list_status = ((Qus_Generic_Header_ð1ðð_t ᑍ)usrspc_ptr)->Information_Status;  
do  
{
proces1();  
} while (list_status != 'C');  
} /ᑍ proces ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ main  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
main(int argc, char ᑍargv[])  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Make sure we received the correct number of parameters. The argc ᑍ/  
/ᑍ parameter will contain the number of parameters that was passed ᑍ/  
/ᑍ to this program. This number also includes the program itself, ᑍ/  
/ᑍ so we need to evaluate argc-1.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
B-100 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
if (((argc - 1) < 2) || ((argc - 1 > 2)))  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ We did not receive all of the required parameters so exit the  
/ᑍ program.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
{
exit(1);  
}
else  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Copy parameters into local variables.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
{
memcpy(usr_prf, argv[1], 1ð);  
memcpy(obj_type, argv[2], 1ð);  
}
init();  
proces();  
done();  
} /ᑍ main ᑍ/  
List Object API—ILE COBOL Example  
Refer to “List Object API—OPM RPG Example” on page 5-4 for the original  
example. The following program also works for OPM COBOL.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
List objects that adopt owner authority  
ᑍ
ᑍ Language:  
ᑍ
COBOL  
ᑍ Description: This program prints a report showing all objects  
ᑍ
that adopt owner authority. The two parameters  
passed to the program are the profile to be  
checked and the type of objects to be listed.  
The parameter values are the same as those  
accepted by the QSYLOBJP API.  
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ APIs Used:  
QSYLOBJP - List Objects that Adopt Owner Authority  
QUSCRTUS - Create User Space  
QUSPTRUS - Retrieve Pointer to User Space  
QUSROBJD - Retrieve Object Description  
ᑍ
ᑍ
ᑍ
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PROGRAM-ID. LISTADOPT.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
Appendix B. Original Examples in Additional Languages B-101  
Download from Www.Somanuals.com. All Manuals Search And Download.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
ᑍ
ᑍ
WORKING-STORAGE SECTION.  
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Listing text  
ᑍ
ð1 OBJ-ENTRY.  
ð5 OBJECT.  
ð9 TEXT1  
ð9 NAME  
PIC X(ð8) VALUE "Object: ".  
PIC X(1ð).  
ð9 TEXT2  
ð9 LIBRARY  
PIC X(1ð) VALUE " Library: ".  
PIC X(1ð).  
ð5 TEXT3  
PIC X(ð7) VALUE " Type: ".  
ð5 OBJECT-TYPE PIC X(1ð).  
ð5 TEXT4  
PIC X(ð7) VALUE " Text: ".  
ð5 OBJECT-TEXT PIC X(5ð).  
ð1 END-LIST.  
ð5 TEXT1  
PIC X(15) VALUE "ᑍᑍᑍ End of List".  
ᑍ
ð1 MISC.  
ð5 SPC-NAME  
ð5 SPC-SIZE  
ð5 SPC-INIT  
ð5 SPCPTR  
PIC X(2ð) VALUE "ADOPTS  
PIC S9(ð9) VALUE 1 BINARY.  
PIC X(ð1) VALUE X"ðð".  
POINTER.  
QTEMP  
".  
ð5 RCVVAR  
PIC X(ð8).  
ð5 RCVVARSIZ  
ð5 LST-STATUS  
ð5 MBR-LIST  
ð5 CONTIN-HDL  
ð5 APINAM  
ð5 ROBJD-FMT  
ð5 SPC-TYPE  
ð5 EXT-ATTR  
ð5 SPC-AUT  
PIC S9(ð9) VALUE 8 BINARY.  
PIC X(ð1).  
PIC X(ð8) VALUE "OBJPð2ðð".  
PIC X(2ð).  
PIC X(1ð).  
PIC X(ð8) VALUE "OBJDð1ðð".  
PIC X(1ð) VALUE "ᑍUSRSPC".  
PIC X(1ð) VALUE "QSYLOBJP".  
PIC X(1ð) VALUE "ᑍALL".  
PIC X(5ð).  
PIC X(1ð) VALUE "ᑍYES".  
PIC X(1ð) VALUE "ᑍUSER".  
ð5 SPC-TEXT  
ð5 SPC-REPLAC  
ð5 SPC-DOMAIN  
ᑍ
ᑍ
LINKAGE SECTION.  
B-102 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ Input parameters.  
ᑍ
ð1 USR-PRF  
ð1 OBJ-TYPE  
ᑍ
PIC X(1ð).  
PIC X(1ð).  
ᑍ String to map User Space offsets into  
ᑍ
ð1 STRING-SPACE  
PIC X(32ððð).  
ᑍ
ᑍ User Space Generic Header include. These includes will be  
ᑍ mapped over a User Space.  
ᑍ
COPY QUSGEN OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ List Objects that Adopt API include. These includes will be  
ᑍ mapped over a User Space.  
ᑍ
COPY QSYLOBJP OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION USING USR-PRF, OBJ-TYPE.  
MAIN-LINE.  
PERFORM INIT.  
PERFORM PROCES.  
PERFORM DONE.  
ᑍ
ᑍ Start of subroutines  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROCES.  
ᑍ
ᑍ Do until the list is complete  
ᑍ
MOVE INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð TO  
LST-STATUS.  
ᑍ
PERFORM PROCES1 WITH TEST AFTER UNTIL LST-STATUS = "C".  
ᑍ
PROCES1.  
ᑍ
ᑍ This subroutine processes each entry returned by QSYLOBJP  
ᑍ
ᑍ
ᑍ If valid information was returned  
ᑍ
IF (INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð = "C"  
OR INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð = "P")  
IF NUMBER-LIST-ENTRIES OF QUS-GENERIC-HEADER-ð1ðð > ð  
ᑍ
ᑍ increment to the first list entry  
ᑍ
SET ADDRESS OF QSY-OBJPð2ðð-LIST TO  
ADDRESS OF STRING-SPACE(  
(OFFSET-LIST-DATA OF QUS-GENERIC-HEADER-ð1ðð + 1):1), .5/  
SET ADDRESS OF STRING-SPACE TO ADDRESS OF  
QSY-OBJPð2ðð-LIST,  
ᑍ
Appendix B. Original Examples in Additional Languages B-103  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ and process all of the entries  
ᑍ
PERFORM PROCES2  
NUMBER-LIST-ENTRIES OF QUS-GENERIC-HEADER-ð1ðð TIMES, .6/  
ᑍ
ᑍ If all entries in this User Space have been processed, check  
ᑍ if more entries exist than can fit in one User Space  
ᑍ
IF INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð = "P"  
ᑍ
ᑍ by addressing the input parameter header  
ᑍ
SET ADDRESS OF STRING-SPACE TO SPCPTR,  
SET ADDRESS OF QSY-OBJP-INPUT TO  
ADDRESS OF STRING-SPACE((OFFSET-INPUT-PARAMETER  
OF QUS-GENERIC-HEADER-ð1ðð + 1):1),  
ᑍ
ᑍ If the continuation handle in the Input Parameter Header is  
ᑍ blank, then set the List status to Complete  
ᑍ
IF CONTINUATION-HANDLE OF QSY-OBJP-INPUT = SPACES  
MOVE "C" TO LST-STATUS  
ELSE  
ᑍ
ᑍ Else, call QSYLOBJP reusing the User Space to get more  
ᑍ List entries  
ᑍ
MOVE CONTINUATION-HANDLE OF QSY-OBJP-INPUT  
TO CONTIN-HDL OF MISC,  
PERFORM GETLST,  
.2/  
MOVE INFORMATION-STATUS OF QUS-GENERIC-HEADER-ð1ðð  
TO LST-STATUS,  
END-IF,  
END-IF,  
END-IF,  
ELSE  
ᑍ
ᑍ And if an unexpected status, log an error (not shown) and exit  
ᑍ
PERFORM DONE,  
END-IF.  
ᑍ
PROCES2.  
MOVE CORRESPONDING QSY-OBJPð2ðð-LIST TO OBJ-ENTRY.  
WRITE LIST-LINE FROM OBJ-ENTRY.  
ᑍ
ᑍ after each entry, increment to the next entry  
ᑍ
SET ADDRESS OF QSY-OBJPð2ðð-LIST TO ADDRESS OF  
STRING-SPACE(  
(SIZE-EACH-ENTRY OF QUS-GENERIC-HEADER-ð1ðð + 1):1). .7/  
SET ADDRESS OF STRING-SPACE TO ADDRESS OF QSY-OBJPð2ðð-LIST.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
GETLST.  
ᑍ
ᑍ Call QSYLOBJP to generate a list  
ᑍ The continuation handle is set by the caller of this  
ᑍ subroutine.  
B-104 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
MOVE "OBJPð2ðð" TO MBR-LIST.  
ᑍ
ᑍ
CALL "QSYLOBJP" USING SPC-NAME, MBR-LIST, USR-PRF,  
OBJ-TYPE, CONTIN-HDL, QUS-EC. .3/  
ᑍ Check for errors on QSYLOBJP  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QSYLOBJP" TO APINAM,  
PERFORM APIERR.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
INIT.  
ᑍ
ᑍ One time initialization code for this program  
ᑍ
ᑍ Open LISTING file  
ᑍ
OPEN OUTPUT LISTING.  
ᑍ
ᑍ Set Error Code structure to not use exceptions  
ᑍ
MOVE LENGTH OF QUS-EC TO BYTES-PROVIDED OF QUS-EC.  
ᑍ
ᑍ Check to see if the User Space was previously created in  
ᑍ QTEMP. If it was, simply reuse it.  
ᑍ
CALL "QUSROBJD" USING RCVVAR, RCVVARSIZ, ROBJD-FMT,  
SPC-NAME, SPC-TYPE, QUS-EC.  
ᑍ
ᑍ Check for errors on QUSROBJD  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
ᑍ
ᑍ If CPF98ð1, then User Space was not found  
ᑍ
IF EXCEPTION-ID OF QUS-EC = "CPF98ð1"  
ᑍ
ᑍ So create a User Space for the List generated by QSYLOBJP  
ᑍ
CALL "QUSCRTUS" USING SPC-NAME, EXT-ATTR, SPC-SIZE,  
SPC-INIT, SPC-AUT, SPC-TEXT,  
SPC-REPLAC, QUS-EC, SPC-DOMAIN  
ᑍ
ᑍ Check for errors on QUSCRTUS  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QUSCRTUS" TO APINAM,  
PERFORM APIERR,  
ELSE  
CONTINUE,  
ELSE  
ᑍ
ᑍ Else, an error occurred accessing the User Space  
ᑍ
MOVE "QUSROBJD" TO APINAM,  
PERFORM APIERR.  
ᑍ
ᑍ Set QSYLOBJP (via GETLST) to start a new list  
Appendix B. Original Examples in Additional Languages B-105  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ
MOVE SPACES TO CONTIN-HDL.  
PERFORM GETLST.  
ᑍ Get a resolved pointer to the User Space for performance  
ᑍ
CALL "QUSPTRUS" USING SPC-NAME, SPCPTR, QUS-EC.  
ᑍ
ᑍ Check for errors on QUSPTRUS  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QUSPTRUS" TO APINAM,  
PERFORM APIERR.  
ᑍ
ᑍ If no error, then set addressability to User Space  
ᑍ
SET ADDRESS OF QUS-GENERIC-HEADER-ð1ðð TO SPCPTR.  
SET ADDRESS OF STRING-SPACE TO SPCPTR.  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
APIERR.  
ᑍ
ᑍ Log any error encountered, and exit the program  
ᑍ
DISPLAY APINAM.  
DISPLAY EXCEPTION-ID OF QUS-EC.  
PERFORM DONE.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DONE.  
ᑍ
ᑍ Exit the program  
ᑍ
WRITE LIST-LINE FROM END-LIST.  
STOP RUN.  
List Object API—ILE RPG Example  
Refer to “List Object API—OPM RPG Example” on page 5-4 for the original  
example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program:  
List objects that adopt owner authority  
Fᑍ  
Fᑍ Language:  
Fᑍ  
ILE RPG  
Fᑍ Description: This program prints a report showing all objects  
Fᑍ  
that adopt owner authority. The two parameters  
passed to the program are the profile to be  
checked and the type of objects to be listed.  
The parameter values are the same as those  
accepted by the QSYLOBJP API.  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ APIs Used:  
QSYLOBJP - List Objects that Adopt Owner Authority  
QUSCRTUS - Create User Space  
QUSPTRUS - Retrieve Pointer to User Space  
QUSROBJD - Retrieve Object Description  
Fᑍ  
Fᑍ  
Fᑍ  
B-106 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Fᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQPRINT  
Dᑍ  
O
F 132  
PRINTER OFLIND(ᑍINOF)  
Dᑍ Error Code parameter include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
DSPC_NAME  
DSPC_SIZE  
DSPC_INIT  
DLSTPTR  
S
S
S
S
S
S
S
S
2ð  
INZ('ADOPTS  
INZ(X'ðð')  
QTEMP  
')  
9B ð INZ(1)  
1
ᑍ
ᑍ
DSPCPTR  
DARR  
DRCVVAR  
DRCVVARSIZ  
1
8
BASED(LSTPTR) DIM(32767)  
9B ð INZ(8)  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ The following QUSGEN include from QSYSINC is copied into  
Dᑍ this program so that it can be declared as BASED on SPCPTR  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQUSHð1ðð  
Dᑍ  
D QUSUA  
Dᑍ  
D QUSSGH  
Dᑍ  
D QUSSRL  
Dᑍ  
D QUSFN  
Dᑍ  
D QUSAU  
Dᑍ  
D QUSDTC  
Dᑍ  
D QUSIS  
Dᑍ  
D QUSSUS  
Dᑍ  
D QUSOIP  
Dᑍ  
D QUSSIP  
Dᑍ  
D QUSOHS  
Dᑍ  
D QUSSHS  
Dᑍ  
D QUSOLD  
Dᑍ  
D QUSSLD  
Dᑍ  
D QUSNBRLE  
Dᑍ  
DS  
BASED(SPCPTR)  
Qus Generic Header ð1ðð  
1
65  
64  
User Area  
68B ð  
72  
Size Generic Header  
Structure Release Level  
Format Name  
69  
73  
8ð  
81  
9ð  
API Used  
91  
1ð3  
Date Time Created  
Information Status  
Size User Space  
1ð4  
1ð5  
1ð9  
113  
117  
121  
125  
129  
133  
137  
1ð4  
1ð8B ð  
112B ð  
116B ð  
12ðB ð  
124B ð  
128B ð  
132B ð  
136B ð  
14ðB ð  
Offset Input Parameter  
Size Input Parameter  
Offset Header Section  
Size Header Section  
Offset List Data  
Size List Data  
Number List Entries  
Size Each Entry  
D QUSSEE  
Dᑍ  
Appendix B. Original Examples in Additional Languages B-107  
Download from Www.Somanuals.com. All Manuals Search And Download.  
D QUSSIDLE  
141  
145  
147  
15ð  
151  
144B ð  
146  
Dᑍ  
CCSID List Ent  
Country ID  
D QUSCID  
Dᑍ  
D QUSLID  
149  
Dᑍ  
Language ID  
D QUSSLI  
15ð  
Dᑍ  
Subset List Indicator  
Reserved  
D QUSERVEDðð  
Dᑍ  
192  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ The following QSYLOBJP include from QSYSINC is copied into  
Dᑍ this program so that it can be declared as BASED on LSTPTR  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
D QSYLOBJP  
C
'QSYLOBJP'  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍHeader structure for QSYLOBJP  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQSYOBJPH  
Dᑍ  
D QSYUNðð  
Dᑍ  
D QSYCVðð  
Dᑍ  
DS  
BASED(LSTPTR)  
Qsy OBJP Header  
1
1ð  
User name  
3ð  
Continuation Value  
11  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍRecord structure for OBJPð2ðð format  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQSYð2ððLð2  
DS  
BASED(LSTPTR)  
Qsy OBJPð2ðð List  
Dᑍ  
D QSYNAMEð6  
1
11  
21  
31  
32  
42  
1ð  
2ð  
3ð  
31  
41  
91  
Dᑍ  
Name  
D QSYBRARYð6  
Dᑍ  
Library  
D QSYOBJT13  
Dᑍ  
Object Type  
Object In Use  
Object Attribute  
Object Text  
D QSYOBJIUðð  
Dᑍ  
D QSYOBJA11  
Dᑍ  
D QSYOBJT14  
Dᑍ  
Cᑍ  
Cᑍ Start of mainline  
Cᑍ  
C
ᑍENTRY  
PLIST  
PARM  
PARM  
EXSR  
EXSR  
EXSR  
C
USR_PRF  
OBJ_TYPE  
1ð  
1ð  
C
C
INIT  
C
PROCES  
DONE  
C
Cᑍ  
Cᑍ Start of subroutines  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
PROCES  
BEGSR  
B-108 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ This subroutine processes each entry returned by QSYLOBJP  
Cᑍ  
Cᑍ  
Cᑍ Do until the list is complete  
Cᑍ  
C
MOVE  
QUSIS  
LST_STATUS  
1
Cᑍ  
C
Cᑍ  
LST_STATUS  
DOUEQ  
'C'  
Cᑍ If valid information was returned  
Cᑍ  
C
QUSIS  
QUSIS  
IFEQ  
OREQ  
'C'  
'P'  
C
Cᑍ  
Cᑍ and list entries were found  
Cᑍ  
C
QUSNBRLE  
IFGT  
ð
Cᑍ  
Cᑍ set LSTPTR to the first byte of the User Space  
Cᑍ  
C
Cᑍ  
EVAL  
LSTPTR = SPCPTR  
Cᑍ increment LSTPTR to the first List entry  
Cᑍ  
C
Cᑍ  
EVAL  
LSTPTR = %ADDR(ARR(QUSOLD + 1)) .5/  
Cᑍ and process all of the entries  
Cᑍ  
C
DO  
QUSNBRLE  
.6/  
C
EXCEPT  
OBJ_ENTRY  
Cᑍ  
Cᑍ after each entry, increment LSTPTR to the next entry  
Cᑍ  
C
EVAL  
END  
LSTPTR = %ADDR(ARR(QUSSEE + 1)) .7/  
C
C
END  
Cᑍ  
Cᑍ If all entries in this User Space have been processed, check  
Cᑍ if more entries exist than can fit in one User Space  
Cᑍ  
C
Cᑍ  
QUSIS  
IFEQ  
'P'  
Cᑍ by resetting LSTPTR to the start of the User Space  
Cᑍ  
C
Cᑍ  
EVAL  
LSTPTR = SPCPTR  
Cᑍ and then incrementing LSTPTR to the Input Parameter Header  
Cᑍ  
C
EVAL  
LSTPTR = %ADDR(ARR(QUSOIP + 1))  
Cᑍ  
Cᑍ If the continuation handle in the Input Parameter Header is  
Cᑍ blank, then set the List status to Complete  
Cᑍ  
C
QSYCVðð  
IFEQ  
MOVE  
ELSE  
ᑍBLANKS  
'C'  
C
LST_STATUS  
C
Cᑍ  
Cᑍ Else, call QSYLOBJP reusing the User Space to get more  
Appendix B. Original Examples in Additional Languages B-109  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ List entries  
Cᑍ  
C
MOVE  
EXSR  
MOVE  
END  
QSYCVðð  
GETLST  
QUSIS  
CONTIN_HDL .2/  
C
C
LST_STATUS  
C
C
END  
C
ELSE  
Cᑍ  
Cᑍ And if an unexpected status, log an error (not shown) and exit  
Cᑍ  
C
C
C
C
EXSR  
END  
DONE  
END  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
GETLST  
BEGSR  
Cᑍ Call QSYLOBJP to generate a list  
Cᑍ The continuation handle is set by the caller of this  
Cᑍ subroutine.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
QSYLOBJP  
C
SPC_NAME  
MBR_LIST  
USR_PRF  
OBJ_TYPE  
CONTIN_HDL  
QUSEC  
C
'OBJPð2ðð'  
8
C
C
C
2ð .3/  
C
Cᑍ  
Cᑍ Check for errors on QSYLOBJP  
Cᑍ  
C
C
C
C
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
'QSYLOBJP'  
APIERR  
APINAM  
1ð  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
INIT  
BEGSR  
Cᑍ  
Cᑍ One time initialization code for this program  
Cᑍ  
Cᑍ Set Error Code structure not to use exceptions  
Cᑍ  
C
Z-ADD  
16  
QUSBPRV  
Cᑍ  
Cᑍ Check to see if the User Space was previously created in  
Cᑍ QTEMP. If it was, simply reuse it.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'QUSROBJD'  
C
RCVVAR  
C
RCVVARSIZ  
ROBJD_FMT  
SPC_NAME  
SPC_TYPE  
QUSEC  
C
'OBJDð1ðð'  
'ᑍUSRSPC'  
8
C
C
1ð  
C
Cᑍ  
Cᑍ Check for errors on QUSROBJD  
B-110 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
C
Cᑍ  
QUSBAVL  
IFGT  
ð
Cᑍ If CPF98ð1, then User Space was not found  
Cᑍ  
C
Cᑍ  
QUSEI  
IFEQ  
'CPF98ð1'  
Cᑍ So create a User Space for the List generated by QSYLOBJP  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'QUSCRTUS'  
SPC_NAME  
'QSYLOBJP ' EXT_ATTR  
SPC_SIZE  
1ð  
SPC_INIT  
SPC_AUT  
'ᑍALL'  
ᑍBLANKS  
'ᑍYES'  
1ð  
5ð  
1ð  
SPC_TEXT  
SPC_REPLAC  
QUSEC  
'ᑍUSER'  
SPC_DOMAIN  
1ð  
Cᑍ Check for errors on QUSCRTUS  
Cᑍ  
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
C
'QUSCRTUS'  
APIERR  
APINAM  
1ð  
C
C
Cᑍ  
Cᑍ Else, an error occurred accessing the User Space  
Cᑍ  
C
ELSE  
MOVEL  
EXSR  
END  
C
'QUSROBJD'  
APIERR  
APINAM  
1ð  
C
C
C
END  
Cᑍ  
Cᑍ Set QSYLOBJP (via GETLST) to start a new list  
Cᑍ  
C
MOVE  
EXSR  
ᑍBLANKS  
GETLST  
CONTIN_HDL  
C
Cᑍ  
Cᑍ Get a resolved pointer to the User Space for performance  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
'QUSPTRUS'  
C
SPC_NAME  
SPCPTR  
QUSEC  
C
C
Cᑍ  
Cᑍ Check for errors on QUSPTRUS  
Cᑍ  
C
C
C
C
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
'QUSPTRUS'  
APIERR  
APINAM  
1ð  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
APIERR  
BEGSR  
Cᑍ  
Cᑍ Log any error encountered, and exit the program  
Appendix B. Original Examples in Additional Languages B-111  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
C
APINAM  
QUSEI  
DSPLY  
DSPLY  
EXSR  
C
C
C
DONE  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
DONE  
BEGSR  
Cᑍ  
Cᑍ Exit the program  
Cᑍ  
C
EXCEPT  
EVAL  
RETURN  
ENDSR  
END_LIST  
C
ᑍINLR = '1'  
C
C
OQPRINT  
E
E
OBJ_ENTRY  
1
1
O
'Object: '  
' Library: '  
' Type: '  
O
QSYNAMEð6  
O
O
QSYBRARYð6  
QSYOBJT13  
O
O
O
' Text: '  
O
QSYOBJT14  
END_LIST  
OQPRINT  
O
'ᑍᑍᑍ End of List'  
OPM API without Pointers—Examples  
This section includes the examples in “Reporting Software Error (ILE API with  
Pointers)—ILE C Example” on page 6-7.  
Logging Software Error (OPM API without Pointers)—OPM COBOL  
Example  
Refer to “Logging Software Error (OPM API without Pointers)—ILE C Example” on  
page 6-2 for the original example. This example uses two programs: CBLERR1  
causes the error, and ERRHDL1 shows how to log the software error using the  
QPDLOGER API.  
CBLERR1 Program  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
Register an OPM COBOL Error Handler  
Cause a data decimal exception to demonstrate  
logging of software errors  
ᑍ
ᑍ
ᑍ
ᑍ Language:  
ᑍ
COBOL  
ᑍ Description: This program registers an OPM COBOL Error  
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ
Handler. After the successful completion of  
the registration of the error handler, this  
program creates a data decimal error. This  
exception causes the error handler to be  
called which then logs the software error.  
,
B-112 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ APIs Used:  
ᑍ
QLRSETCE - Set COBOL Error Handler  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-ID. CBLERR1.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
DATA DIVISION.  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 MISC.  
ð5 Y  
ð5 ERROR-HANDLER PIC X(2ð) VALUE "ERRHDL1 ᑍLIBL  
ð5 SCOPE PIC X(ð1) VALUE "C".  
PIC S9(ð9) VALUE ð.  
".  
ð5 ERROR-HANDLER-LIBRARY PIC X(1ð).  
ð5 PRIOR-ERROR-HANDLER PIC X(2ð).  
ð1 NUMERIC-GROUP.  
ð5 X  
PIC 9(ð3).  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
ᑍ
ᑍ Register the COBOL Error Handler.  
ᑍ
ᑍ Initialize the error code parameter. To signal exceptions to  
ᑍ this program by the API, you need to set the bytes provided  
ᑍ field of the error code to zero. Because this program has  
ᑍ exceptions sent back through the error code parameter, it sets  
ᑍ the bytes provided field to the number of bytes it gives the  
ᑍ API for the parameter.  
ᑍ
MOVE 16 TO BYTES-PROVIDED.  
ᑍ
ᑍ
ᑍ Call the API to register the exit point.  
ᑍ
CALL "QLRSETCE" USING ERROR-HANDLER OF MISC,  
SCOPE OF MISC,  
ERROR-HANDLER-LIBRARY OF MISC,  
Appendix B. Original Examples in Additional Languages B-113  
Download from Www.Somanuals.com. All Manuals Search And Download.  
PRIOR-ERROR-HANDLER OF MISC,  
QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
DISPLAY "Error setting handler",  
STOP RUN.  
ᑍ
ᑍ If the call to register an error handler is successful, then  
ᑍ cause a the data decimal error (X is initialized to blanks).  
ᑍ
ADD X TO Y.  
ᑍ
ᑍ Should not get here due to data decimal error  
ᑍ
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
ᑍ
ERRHDL1 Program  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
Log a software error  
ᑍ
ᑍ Language:  
ᑍ
COBOL  
ᑍ Description: This program receives control for exceptions  
ᑍ
within a COBOL run unit. This program is used  
in conjunction with CBLERR1.  
Any exception causes this error handler to be  
called which then logs the software error.  
ᑍ
,
ᑍ
ᑍ
ᑍ
ᑍ APIs Used:  
ᑍ
QPDLOGER - Log Software Error  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-ID. ERRHDL1.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
DATA DIVISION.  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
B-114 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 MISC.  
ð5 LOG-EXCEPTION-ID PIC X(12).  
ð5 MESSAGE-KEY  
PIC X(ð4).  
ð5 POINT-OF-FAILURE PIC S9(ð9) BINARY VALUE 1.  
ð5 PRINT-JOBLOG PIC X(ð1) VALUE "Y".  
ð5 NBR-OF-ENTRIES PIC S9(ð9) BINARY.  
ð5 NBR-OF-OBJECTS PIC S9(ð9) BINARY VALUE 1.  
ð1 MESSAGE-INFO.  
ð5 MSG-OFFSET  
ð5 MSG-LENGTH  
PIC S9(ð9) BINARY.  
PIC S9(ð9) BINARY.  
ð1 OBJECT-LIST.  
ð5 OBJECT-NAME  
ð5 LIBRARY-NAME  
ð5 OBJECT-TYPE  
LINKAGE SECTION.  
ð1 CBL-EXCEPTION-ID  
ð1 VALID-RESPONSES  
ð1 PGM-IN-ERROR.  
ð5 PGM-NAME  
PIC X(3ð).  
PIC X(3ð).  
PIC X(1ð) VALUE "ᑍPGM  
".  
PIC X(ð7).  
PIC X(ð6).  
PIC X(1ð).  
ð5 LIB-NAME  
PIC X(1ð).  
ð1 SYS-EXCEPTION-ID  
ð1 MESSAGE-TEXT  
ð1 MESSAGE-LENGTH  
ð1 SYS-OPTION  
PIC X(ð7).  
PIC X(ð1).  
PIC S9(ð9) BINARY.  
PIC X(ð1).  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION USING CBL-EXCEPTION-ID,  
VALID-RESPONSES,  
PGM-IN-ERROR,  
SYS-EXCEPTION-ID,  
MESSAGE-TEXT,  
MESSAGE-LENGTH,  
SYS-OPTION.  
MAIN-LINE.  
ᑍ
ᑍ Initialize the error code parameter. To signal exceptions to  
ᑍ this program by the API, you need to set the bytes provided  
ᑍ field of the error code to zero. Because this program has  
ᑍ exceptions sent back through the error code parameter, it sets  
ᑍ the bytes provided field to the number of bytes it gives the  
ᑍ API for the parameter.  
ᑍ
MOVE 16 TO BYTES-PROVIDED.  
ᑍ
ᑍ Record the COBOL Exception id  
ᑍ
MOVE SYS-EXCEPTION-ID TO LOG-EXCEPTION-ID.  
ᑍ
ᑍ Record the length of the message replacement data (if any)  
Appendix B. Original Examples in Additional Languages B-115  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ
IF MESSAGE-LENGTH > ð  
MOVE 1 TO MSG-OFFSET,  
MOVE MESSAGE-LENGTH TO MSG-LENGTH,  
MOVE 1 TO NBR-OF-ENTRIES,  
ELSE  
MOVE ð TO MSG-OFFSET,  
MOVE ð TO MSG-LENGTH,  
MOVE ð TO NBR-OF-ENTRIES.  
ᑍ For illustration purposes, dump the program object  
ᑍ
MOVE PGM-NAME TO OBJECT-NAME.  
MOVE LIB-NAME TO LIBRARY-NAME.  
.1/  
ᑍ
ᑍ Call the API to log the software error.  
ᑍ
CALL "QPDLOGER" USING PGM-NAME,  
LOG-EXCEPTION-ID,  
MESSAGE-KEY,  
POINT-OF-FAILURE,  
PRINT-JOBLOG,  
MESSAGE-TEXT,  
MESSAGE-INFO,  
NBR-OF-ENTRIES,  
OBJECT-LIST,  
NBR-OF-OBJECTS,  
QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
DISPLAY "Cannot log error".  
ᑍ
ᑍ End the current run unit  
ᑍ
MOVE "C" TO SYS-OPTION.  
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
ᑍ
Logging Software Error (OPM API without Pointers)—OPM RPG  
Example  
Refer to “Logging Software Error (OPM API without Pointers)—ILE C Example” on  
page 6-2 for the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program:  
Fᑍ  
Fᑍ Language:  
Demonstrate use of OPM-based Log Software Error  
OPM RPG  
B-116 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Fᑍ  
Fᑍ Description:  
This program performs a divide-by-ð operation  
to cause an exception. This exception is  
caught using RPG ᑍPSSR support,  
and the exception is then logged as a  
software error.  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ APIs used:  
Fᑍ  
QPDLOGER  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Eᑍ  
Eᑍ Arrays used to extract source line number where error happened  
Eᑍ  
E
SRC  
TGT  
8 1  
8 1  
E
Iᑍ  
Iᑍ Error Code parameter include. As this sample program uses  
Iᑍ /COPY to include the error code structure, only the first  
Iᑍ 16 bytes of the error code structure are available. If the  
Iᑍ application program needs to access the variable length  
Iᑍ exception data for the error, the developer should physically  
Iᑍ copy the QSYSINC include and modify the copied include to  
Iᑍ define additional storage for the exception data.  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSEC  
Iᑍ  
Iᑍ Define Program Status Data Structure  
Iᑍ  
IPSDS  
SDS  
I
1 1ð PGMNAM  
11 15ðSTATUS  
21 28 SRC  
4ð 46 EXCPID  
81 9ð LIBNAM  
I
I
I
I
Iᑍ  
Iᑍ Some miscellaneous fields  
Iᑍ  
IMISC  
DS  
I
B 1 4ðFAILPT  
B 5 8ðDATA#  
B 9 12ðOBJS#  
13 2ð TGT  
I
I
I
I
13 2ððLIN#C  
Iᑍ  
Iᑍ DATA represents the data items to report as part of problem  
Iᑍ  
IDATA  
Iᑍ  
DS  
4ð96  
Iᑍ DATAPT defines (via offset and length values) how to read DATA  
Iᑍ  
IDATAPT  
DS  
256  
I
B 1 4ðDTAOFF  
B 5 8ðDTALEN  
I
Iᑍ  
Iᑍ OBJS represents the list of objects to spool as part of problem  
Iᑍ  
IOBJS  
I
DS  
259ð  
1 3ð OBJ1N  
Appendix B. Original Examples in Additional Languages B-117  
Download from Www.Somanuals.com. All Manuals Search And Download.  
I
31 6ð OBJ1L  
61 7ð OBJ1T  
I
Cᑍ  
Cᑍ Prepare for divide-by-zero situation  
Cᑍ  
C
Z-ADD1ð  
Z-ADDð  
FACT1 5ð  
FACT2 5ð  
C
Cᑍ  
Cᑍ and divide by ð  
Cᑍ  
C
FACT1  
DIV FACT2  
RESULT 5ð  
Cᑍ  
Cᑍ should not get here due to divide-by-ð exception  
Cᑍ  
C
MOVE '1'  
RETRN  
ᑍINLR  
C
Cᑍ  
Cᑍ Program exception subroutine:  
Cᑍ  
C
Cᑍ  
ᑍPSSR  
BEGSR  
Cᑍ Make sure we are not catching an exception due to the ᑍPSSR  
Cᑍ subroutine itself  
Cᑍ  
C
SWITCH  
IFEQ ' '  
MOVE '1'  
C
Cᑍ  
SWITCH 1  
Cᑍ Set API error code to work in nonexception mode  
Cᑍ  
C
Cᑍ  
Z-ADD16  
QUSBNB  
Cᑍ Record the source listing line number that caused the failure  
Cᑍ  
Cᑍ  
Cᑍ  
C
First, extract the numeric portion of the PSDS line number  
Z-ADD8  
Z-ADD8  
Z-ADDð  
DOWEQ' '  
SUB 1  
END  
DOWGTð  
MOVE SRC,X  
SUB 1  
SUB 1  
END  
X
1ð  
1ð  
C
Y
C
LIN#C  
C
SRC,X  
X
C
X
C
C
C
TGT,Y  
C
X
Y
C
C
Cᑍ  
Cᑍ  
Cᑍ  
C
Then record it:  
Z-ADDLIN#C  
FAILPT  
Cᑍ  
Cᑍ Record the status code for the failure  
Cᑍ  
C
Cᑍ  
MOVELSTATUS  
DATA  
Cᑍ Record where to find the status data within DATA  
Cᑍ  
C
Z-ADDð  
DTAOFF  
B-118 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
Z-ADD5  
Z-ADD1  
DTALEN  
DATA#  
C
Cᑍ  
Cᑍ For illustration purposes also dump the program object as  
Cᑍ part of logging the software error  
Cᑍ  
C
MOVELPGMNAM  
MOVELLIBNAM  
MOVEL'ᑍPGM'  
Z-ADD1  
OBJ1N  
OBJ1L  
OBJ1T  
OBJS#  
.1/  
C
C
C
Cᑍ  
Cᑍ Call the Log Software Error API  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL 'QPDLOGER'  
PARM  
PARM EXCPID  
PARM  
PARM  
PGMNAM  
MSGID 12  
MSGKEY 4  
FAILPT  
JOBLOG 1  
DATA  
PARM 'Y'  
PARM  
PARM  
DATAPT  
DATA#  
PARM  
PARM  
OBJS  
PARM  
OBJS#  
PARM  
QUSBN  
Cᑍ If an error on the API call, then indicate a terminal error  
Cᑍ  
C
QUSBNC  
IFGT ð  
'TERM ERR'DSPLY  
C
C
END  
ELSE  
C
Cᑍ  
Cᑍ If error within ᑍPSSR, then indicate ᑍPSSR error  
Cᑍ  
C
'ᑍPSSR 'DSPLY  
END  
C
Cᑍ  
Cᑍ No matter how the program got to the ᑍPPSR, end the program  
Cᑍ  
C
C
C
MOVE '1'  
RETRN  
ENDSR  
ᑍINLR  
Logging Software Error (OPM API without Pointers)—ILE RPG Example  
Refer to “Logging Software Error (OPM API without Pointers)—ILE C Example” on  
page 6-2 for the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program:  
Demonstrate use of OPM based Log Software Error  
Fᑍ  
Fᑍ Language:  
Fᑍ  
ILE RPG  
Fᑍ Description: This program performs a divide by ð operation to  
Fᑍ  
Fᑍ  
cause an exception. This exception is caught using  
RPG's ᑍPSSR support, and the exception is then  
Appendix B. Original Examples in Additional Languages B-119  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Fᑍ  
Fᑍ  
logged as a software error.  
Fᑍ APIs used: QPDLOGER  
Fᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Include Error Code Parameter  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
Dᑍ Misc. data elements  
Dᑍ  
Dfactor1  
Dfactor2  
Dresult  
Dline_nbr  
Ddata  
Ddatapt  
D data_off  
D data_len  
Ddata#  
S
5B ð INZ(1ð)  
5B ð INZ(ð)  
5B ð  
S
S
S
DS  
DS  
9B ð  
4ð96  
9B ð  
9B ð  
9B ð  
S
DS  
S
Dobjl  
Dobjl#  
259ð  
9B ð  
Dᑍ  
Dᑍ Program status data structure  
Dᑍ  
DPSDS  
SDS  
D pgm_name  
D status  
D src_line  
D exception  
D lib_name  
Cᑍ  
1
11  
21  
4ð  
81  
1ð  
15 ð  
28  
46  
9ð  
Cᑍ Attempt to divide by ð  
Cᑍ  
C
factor1  
div  
factor2  
result  
Cᑍ  
Cᑍ Should not get here due to divide by ð exception  
Cᑍ  
C
move  
return  
'1'  
ᑍINLR  
C
Cᑍ  
Cᑍ Program exception subroutine:  
Cᑍ  
C
Cᑍ  
ᑍPSSR  
BEGSR  
Cᑍ Make sure we are not catching an exception due to the ᑍPSSR  
Cᑍ subroutine itself  
Cᑍ  
C
switch  
ifeq  
move  
' '  
'1'  
C
Cᑍ  
switch  
1
Cᑍ Set API error code to work in non-exception mode  
Cᑍ  
C
Cᑍ  
eval  
qusbprv = %size(qusec)  
Cᑍ Record line number where error happened  
Cᑍ  
B-120 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
move  
src_line  
line_nbr  
data  
Cᑍ  
Cᑍ Record the status code as data  
Cᑍ  
C
Cᑍ  
movel  
status  
Cᑍ Record where status located in data  
Cᑍ  
C
eval  
eval  
eval  
data_off = 1  
data_len = 5  
data# = 1  
C
C
Cᑍ  
Cᑍ For illustration purposes, dump the program object  
Cᑍ  
C
eval  
eval  
eval  
eval  
%SUBST(objl:1:3ð) = pgm_name .1/  
%SUBST(objl:31:3ð) = lib_name  
%SUBST(objl:61:1ð) = 'ᑍPGM'  
objl# = 1  
C
C
C
Cᑍ  
Cᑍ Call the Report Software Error API  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
C
Cᑍ  
call  
parm  
parm  
parm  
parm  
parm  
parm  
parm  
parm  
parm  
parm  
parm  
'QPDLOGER'  
pgm_name  
msgid  
msgkey  
line_nbr  
joblog  
data  
exception  
12  
4
'Y'  
1
datapt  
data#  
objl  
objl#  
qusec  
Cᑍ If an error on the API call, then indicate a terminal error  
Cᑍ  
C
qusbavl  
ifgt  
ð
C
'Terminal err'dsply  
C
end  
else  
C
Cᑍ  
Cᑍ If error within ᑍPSSR, then indicate ᑍPSSR error  
Cᑍ  
C
'ᑍPSSR error' dsply  
end  
C
Cᑍ  
Cᑍ No matter how the program got to the ᑍPSSR, end the program  
Cᑍ  
C
C
C
move  
return  
endsr  
'1'  
ᑍinlr  
Appendix B. Original Examples in Additional Languages B-121  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ILE API with Pointers—Examples  
This section includes the examples in “Reporting Software Error (ILE API with  
Pointers)—ILE C Example” on page 6-7.  
Reporting Software Error (ILE API with Pointers)—ILE COBOL Example  
Refer to “Reporting Software Error (ILE API with Pointers)—ILE C Example” on  
page 6-7 for the original example. This example uses two programs: CBLERR2  
causes the error, and ERRHDL2 shows how to report the software error using the  
QPDLOGER API.  
CBLERR2 Program  
PROCESS NOMONOPRC.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
Register an ILE COBOL Error Handler  
Cause a decimal data exception to demonstrate  
logging of software errors  
ᑍ
ᑍ
ᑍ
ᑍ Language:  
ᑍ
ILE COBOL  
ᑍ Description: This program registers an ILE COBOL Error  
ᑍ
Handler. After the successful completion of  
the registration of the error handler, this  
program creates a decimal data error. This  
exception causes the error handler to be  
called which then logs the software error.  
ᑍ
,
ᑍ
ᑍ
ᑍ
ᑍ
ᑍ APIs Used:  
QlnSetCobolErrorHandler  
ᑍ
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-ID. CBLERR2.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
SPECIAL-NAMES.  
LINKAGE TYPE PROCEDURE FOR "QlnSetCobolErrorHandler".  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
DATA DIVISION.  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
B-122 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
COPY QUSEC OF QSYSINC-QCBLLESRC.  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 MISC.  
ð5 Y  
PIC S9(ð9) VALUE ð.  
PROCEDURE-POINTER.  
ð1 ERROR-HANDLER  
ð1 OLD-ERROR-HANDLER PROCEDURE-POINTER.  
ð1 NUMERIC-GROUP.  
ð5 X  
PIC 9(ð3).  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
ᑍ
ᑍ Register the COBOL Error Handler.  
ᑍ
ᑍ Initialize the error code parameter. To signal exceptions to  
ᑍ this program by the API, you need to set the bytes provided  
ᑍ field of the error code to zero. Because this program has  
ᑍ exceptions sent back through the error code parameter, it sets  
ᑍ the bytes provided field to the number of bytes it gives the  
ᑍ API for the parameter.  
ᑍ
MOVE 16 TO BYTES-PROVIDED.  
ᑍ
ᑍ Set ERROR-HANDLER procedure pointer to entry point of  
ᑍ ERRHDL1 ᑍPGM  
ᑍ
SET ERROR-HANDLER TO ENTRY LINKAGE PROGRAM "ERRHDL2".  
ᑍ
ᑍ
ᑍ Call the API to register the exit point.  
ᑍ
CALL "QlnSetCobolErrorHandler" USING ERROR-HANDLER,  
OLD-ERROR-HANDLER,  
QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE > ð  
DISPLAY "Error setting handler",  
STOP RUN.  
ᑍ
ᑍ If the call to register an error handler is successful, then  
ᑍ cause a the data decimal error (X is initialized to blanks).  
ᑍ
ADD X TO Y.  
ᑍ
ᑍ Should not get here due to data decimal error  
ᑍ
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
Appendix B. Original Examples in Additional Languages B-123  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ERRHDL2 Program  
PROCESS NOMONOPRC.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
Log a software error  
ᑍ
ᑍ Language:  
ᑍ
ILE COBOL  
ᑍ Description: This program receives control for exceptions  
ᑍ
within a COBOL run unit. This program is used  
in conjunction with CBLERR2.  
Any exception causes this error handler to be  
called which then logs the software error.  
ᑍ
,
ᑍ
ᑍ
ᑍ
ᑍ APIs Used:  
ᑍ
QpdReportSoftwareError  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-ID. ERRHDL2.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
SPECIAL-NAMES.  
LINKAGE TYPE PROCEDURE FOR "QpdReportSoftwareError".  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
DATA DIVISION.  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QCBLLESRC.  
ᑍ
ᑍ QpdReportSoftwareError include  
ᑍ
COPY QPDSRVPG OF QSYSINC-QCBLLESRC.  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 MISC.  
ð5 NBR-OF-RECORDS PIC S9(ð9) BINARY VALUE ð.  
ð5 MSG-KEYWORD  
PIC X(ð3) VALUE "MSG".  
ð1 PROBLEM-RECORDS.  
ð5 PROBLEM-POINTER POINTER OCCURS 1ðð TIMES.  
LINKAGE SECTION.  
B-124 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ð1 CBL-EXCEPTION-ID  
ð1 VALID-RESPONSES  
ð1 PGM-IN-ERROR.  
ð5 PGM-NAME  
PIC X(ð7).  
PIC X(ð6).  
PIC X(1ð).  
PIC X(1ð).  
PIC X(ð7).  
PIC X(ð1).  
PIC S9(ð9) BINARY.  
PIC X(ð1).  
PIC X(1ð).  
PIC X(256).  
ð5 LIB-NAME  
ð1 SYS-EXCEPTION-ID  
ð1 MESSAGE-TEXT  
ð1 MESSAGE-LENGTH  
ð1 SYS-OPTION  
ð1 ERR-MODULE-NAME  
ð1 CBL-PGM-NAME  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION USING CBL-EXCEPTION-ID,  
VALID-RESPONSES,  
PGM-IN-ERROR,  
SYS-EXCEPTION-ID,  
MESSAGE-LENGTH,  
SYS-OPTION,  
MESSAGE-TEXT,  
ERR-MODULE-NAME,  
CBL-PGM-NAME.  
MAIN-LINE.  
ᑍ
ᑍ Initialize the error code parameter. To signal exceptions to  
ᑍ this program by the API, you need to set the bytes provided  
ᑍ field of the error code to zero. Because this program has  
ᑍ exceptions sent back through the error code parameter, it sets  
ᑍ the bytes provided field to the number of bytes it gives the  
ᑍ API for the parameter.  
ᑍ
MOVE 16 TO BYTES-PROVIDED.  
ᑍ
ᑍ Record the COBOL Program and Library names  
ᑍ
MOVE 1ð1 TO KEY-FIELD OF QPD-SUSPECTED-PROGRAM.  
MOVE 1ð TO PROGRAM-NAME-LENGTH OF QPD-SUSPECTED-PROGRAM.  
MOVE 1ð TO LIBRARY-NAME-LENGTH OF QPD-SUSPECTED-PROGRAM.  
SET PROGRAM-NAME OF QPD-SUSPECTED-PROGRAM  
TO ADDRESS OF PGM-NAME OF PGM-IN-ERROR.  
SET LIBRARY-NAME OF QPD-SUSPECTED-PROGRAM  
TO ADDRESS OF LIB-NAME OF PGM-IN-ERROR.  
ADD 1 TO NBR-OF-RECORDS.  
SET PROBLEM-POINTER (NBR-OF-RECORDS) TO  
ADDRESS OF QPD-SUSPECTED-PROGRAM.  
.2/  
ᑍ
ᑍ Record the message id  
ᑍ
MOVE 2ðð TO KEY-FIELD OF QPD-SYMPTOM.  
MOVE 3 TO KEYWORD-LENGTH OF QPD-SYMPTOM.  
MOVE 7 TO DATA-LENGTH OF QPD-SYMPTOM.  
MOVE "C" TO DATA-TYPE OF QPD-SYMPTOM.  
SET KEYWORD OF QPD-SYMPTOM TO ADDRESS OF MSG-KEYWORD.  
SET DATA-FIELD OF QPD-SYMPTOM TO ADDRESS OF SYS-EXCEPTION-ID.  
ADD 1 TO NBR-OF-RECORDS.  
SET PROBLEM-POINTER (NBR-OF-RECORDS) TO  
ADDRESS OF QPD-SYMPTOM.  
Appendix B. Original Examples in Additional Languages B-125  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ For illustration purposes, dump the program object  
ᑍ
MOVE 3ð2 TO KEY-FIELD OF QPD-NAMED-SYSTEM-OBJECT.  
MOVE PGM-NAME OF PGM-IN-ERROR  
TO OBJECT-NAME OF QPD-NAMED-SYSTEM-OBJECT.  
MOVE LIB-NAME OF PGM-IN-ERROR  
TO OBJECT-LIBRARY OF QPD-NAMED-SYSTEM-OBJECT.  
MOVE "ᑍPGM" TO OBJECT-TYPE OF QPD-NAMED-SYSTEM-OBJECT.  
ADD 1 TO NBR-OF-RECORDS.  
SET PROBLEM-POINTER (NBR-OF-RECORDS) TO  
ADDRESS OF QPD-NAMED-SYSTEM-OBJECT.  
ᑍ
ᑍ Call the API to log the software error.  
ᑍ
CALL "QpdReportSoftwareError" USING PROBLEM-RECORDS,  
NBR-OF-RECORDS,  
QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE > ð DISPLAY "Cannot log error".  
ᑍ
ᑍ End the current run unit  
ᑍ
MOVE "C" TO SYS-OPTION.  
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
ᑍ
Reporting Software Error (ILE API with Pointers)—ILE RPG Example  
Refer to “Reporting Software Error (ILE API with Pointers)—ILE C Example” on  
page 6-7 for the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program:  
Demonstrate use of ILE-based Report Software Error  
Fᑍ  
Fᑍ Language:  
Fᑍ  
ILE RPG  
Fᑍ Description: This program performs a divide-by-ð operation to  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
cause an exception. This exception is caught using  
RPGs ᑍPSSR support, and the exception is then logged  
as a software error.  
Fᑍ APIs used: QpdReportSoftwareError  
Fᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Include Error Code Parameter  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
B-126 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ Include API structures and constants  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QPDSRVPG  
Dᑍ  
Dᑍ Array of problem record description pointers and index to array  
Dᑍ  
Dpdr  
Dx  
Dᑍ  
S
S
ᑍ dim(2ð)  
5B ð INZ(1)  
Dᑍ Misc. data elements  
Dᑍ  
Dfactor1  
Dfactor2  
Dresult  
Drc  
S
S
S
S
5B ð INZ(1ð)  
5B ð INZ(ð)  
5B ð  
2
INZ('RC')  
Dᑍ  
Dᑍ Program status data structure  
Dᑍ  
DPSDS  
SDS  
D pgm_name  
D status  
D src_line  
D exception  
D lib_name  
Cᑍ  
1
11  
21  
4ð  
81  
1ð  
15 ð  
28  
46  
9ð  
Cᑍ Attempt to divide by ð  
Cᑍ  
C
factor1  
div  
factor2  
result  
Cᑍ  
Cᑍ Should not get here due to divide-by-ð exception  
Cᑍ  
C
move  
return  
'1'  
ᑍINLR  
C
Cᑍ  
Cᑍ Program exception subroutine:  
Cᑍ  
C
Cᑍ  
ᑍPSSR  
BEGSR  
Cᑍ Make sure we are not catching an exception due to the ᑍPSSR  
Cᑍ subroutine itself  
Cᑍ  
C
switch  
ifeq  
move  
' '  
'1'  
C
Cᑍ  
switch  
1
Cᑍ Set API error code to work in nonexception mode  
Cᑍ  
C
Cᑍ  
eval  
qusbprv = %size(qusec)  
Cᑍ Record the suspected program and library name  
Cᑍ  
C
eval  
eval  
eval  
eval  
eval  
qpdkð1 = 1ð1  
C
qpdpgmnl = %SIZE(pgm_name)  
qpdlibnl = %SIZE(lib_name)  
qpdpgmn = %ADDR(pgm_name) .2/  
qpdlibn = %ADDR(lib_name)  
C
C
C
Cᑍ  
Cᑍ  
Cᑍ  
and record the key:  
Appendix B. Original Examples in Additional Languages B-127  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
eval  
eval  
pdr(x) = %addr(qpdspgm)  
x = x + 1  
C
Cᑍ  
Cᑍ Record the failing source statement number  
Cᑍ  
C
eval  
eval  
eval  
eval  
eval  
eval  
qpdkð7 = 2ðð  
C
qpdkl = %SIZE(rc)  
qpddl = %SIZE(src_line)  
qpddt = 'C'  
C
C
C
qpdkð8 = %ADDR(rc)  
qpdd = %ADDR(src_line)  
C
Cᑍ  
Cᑍ  
Cᑍ  
C
and record the key:  
eval  
eval  
pdr(x) = %addr(qpds)  
x = x + 1  
C
Cᑍ  
Cᑍ Record the status code as data  
Cᑍ  
C
eval  
eval  
eval  
eval  
qpdk11 = 3ð1  
C
qpddlðð = %SIZE(status)  
qpddi = 1  
C
C
qpddðð = %ADDR(status)  
Cᑍ  
Cᑍ  
Cᑍ  
C
and record the key:  
eval  
eval  
pdr(x) = %addr(qpds)  
x = x + 1  
C
Cᑍ  
Cᑍ For illustration purposes, dump the program object  
Cᑍ  
C
eval  
eval  
eval  
eval  
qpdk12 = 3ð2  
C
qpdobjn = pgm_name  
qpdobjlib = lib_name  
qpdobjt = 'ᑍPGM'  
C
C
Cᑍ  
Cᑍ  
Cᑍ  
C
and record the key:  
eval  
eval  
pdr(x) = %addr(qpdnsot)  
x = x + 1  
C
Cᑍ  
Cᑍ Call the Report Software Error API  
Cᑍ  
C
callb  
parm  
parm  
parm  
qpdrse  
C
pdr  
x
qusec  
C
C
Cᑍ  
Cᑍ If an error on the API call, then indicate a terminal error  
Cᑍ  
C
qusbavl  
ifgt  
ð
C
'Terminal err'dsply  
C
C
Cᑍ  
end  
else  
Cᑍ If error within ᑍPSSR, then indicate ᑍPSSR error  
Cᑍ  
C
'ᑍPSSR error' dsply  
B-128 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
Cᑍ  
end  
Cᑍ No matter how the program got to the ᑍPSSR, end the program  
Cᑍ  
C
C
C
move  
return  
endsr  
'1'  
ᑍinlr  
Program for Packaging a Product—Examples  
This section includes the examples in “Packaging Your Own Software Products” on  
page A-1.  
Program for Packaging a Product—ILE C Example  
Refer to “Program for Packaging a Product—OPM RPG Example” on page A-3 for  
the original example.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Program Name:  
SFTWPRDEX  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ  
/ᑍ Program Language:  
ILE C  
/ᑍ  
/ᑍ Description:  
This example shows you the steps necessaryᑍ/  
to package your product like IBM's.  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Header Files Included: <stdlib.h>  
/ᑍ  
<signal.h>  
<string.h>  
<stdio.h>  
/ᑍ  
/ᑍ  
/ᑍ  
<qszcrtpd.h>  
<qszcrtpl.h>  
<qszpkgpo.h>  
<qlicobjd.h>  
<qusec.h>  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍ  
<qliept.h>  
/ᑍ  
/ᑍ APIs Used:  
QSZCRTPD - Create Product Definition  
QSZCRTPL - Create Product Load  
QSZPKGPO - Package Product Option  
QLICOBJD - Change Object Description  
/ᑍ  
/ᑍ  
/ᑍ  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdlib.h>  
#include <signal.h>  
#include <string.h>  
#include <stdio.h>  
#include <qszcrtpd.h>  
#include <qszcrtpl.h>  
#include <qszpkgpo.h>  
#include <qlicobjd.h>  
#include <qusec.h>  
#include <qliept.h>  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function:  
Create_Prod_Def_Obj  
ᑍ/  
/ᑍ Description: Create the product definition ABCðð5ð for product ᑍ/  
/ᑍ  
ABC.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
Appendix B. Original Examples in Additional Languages B-129  
Download from Www.Somanuals.com. All Manuals Search And Download.  
void Create_Prod_Def_Obj()  
{
Qsz_Prd_Inf_t prod_info;  
Qsz_Prd_Opt_t prod_opt_list;  
Qsz_Lng_Lod_t prod_lang_load;  
Qus_EC_t error_code;  
char text_desc[5ð];  
/ᑍ Product information  
/ᑍ Product option list  
ᑍ/  
ᑍ/  
/ᑍ Product language load list ᑍ/  
/ᑍ Error code parameter  
/ᑍ Text description  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Fill in the product information. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(&prod_info,' ',sizeof(prod_info));  
memcpy(prod_info.PID,"ðABCABC",7);  
memcpy(prod_info.Rls_Lvl,"V3R1Mð",6);  
memcpy(prod_info.Msg_File,"ABCMSG  
",1ð);  
memcpy(prod_info.Fst_Cpyrt,"ᑍCURRENT ",1ð);  
memcpy(prod_info.Cur_Cpyrt,"ᑍCURRENT ",1ð);  
memcpy(prod_info.Rls_Date,"9412ð1",6);  
memcpy(prod_info.Alw_Mult_Rls,"ᑍNO ",4);  
memcpy(prod_info.Reg_ID_Type,"ᑍPHONE  
memcpy(prod_info.Reg_ID_Val,"5ð7253ð927  
",1ð);  
",14);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Fill in the product option list. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(&prod_opt_list,' ',sizeof(prod_opt_list));  
memcpy(prod_opt_list.Opt,"ðððð",4);  
memcpy(prod_opt_list.Msg_ID,"ABCððð1",7);  
memcpy(prod_opt_list.Alw_Dyn_Nam,"ᑍNODYNNAM ",1ð);  
memcpy(prod_opt_list.Cod_Lod,"5ðð1",4);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Fill in the product language load list.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(&prod_lang_load,' ',sizeof(prod_lang_load));  
memcpy(prod_lang_load.Lng_Lod,"2924  
memcpy(prod_lang_load.Opt,"ðððð",4);  
",8);  
memset(text_desc,' ',5ð);  
memcpy(text_desc,"Product ABC",11);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize the error code to have the API send errors through ᑍ/  
/ᑍ the error code parameter.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.Bytes_Provided=sizeof(error_code);  
QSZCRTPD("ABCðð5ð ABC  
&prod_info,  
&prod_opt_list,  
1,  
", /ᑍ Product definition name  
/ᑍ Product definition info  
/ᑍ Product option list  
/ᑍ Number of options  
/ᑍ Language load list  
/ᑍ Number languages  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
&prod_lang_load,  
1,  
text_desc,  
/ᑍ Text description  
"ᑍUSE  
",  
/ᑍ Public authority  
/ᑍ Error code  
&error_code);  
if (error_code.Bytes_Available > ð)  
{
printf("Failed in QSZCRTPD API with error: %.7s",  
error_code.Exception_Id);  
B-130 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
exit(1);  
}
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function: Create_Prod_Load_Obj ᑍ/  
/ᑍ Description: Create the product loads ABCðð5ð (MRM object) and ᑍ/  
/ᑍ  
ABCðð29 (MRI object) for product ABC.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void Create_Prod_Load_Obj()  
{
Qsz_Lod_Inf_t prod_load_info;  
Qsz_Lib_Inf_t prin_lib_info;  
Qsz_Add_Lib_t add_libs;  
Qsz_Pre_Ext_t preop_expgm;  
Qsz_Flr_Lst_t folder_list;  
Qus_EC_t error_code;  
/ᑍ Product load information  
/ᑍ Principal library info  
/ᑍ Additional library list  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Preoperational exit program ᑍ/  
/ᑍ Folder list  
/ᑍ Error code parameter  
/ᑍ Text description  
ᑍ/  
ᑍ/  
ᑍ/  
char text_desc[5ð];  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Fill in the product load information. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(&prod_load_info,' ',sizeof(prod_load_info));  
memcpy(prod_load_info.PID,"ðABCABC",7);  
memcpy(prod_load_info.Rls_Lvl,"V3R1Mð",6);  
memcpy(prod_load_info.Opt,"ðððð",4);  
memcpy(prod_load_info.Lod_Type,"ᑍCODE  
",1ð);  
memcpy(prod_load_info.Lod_ID,"ᑍCODEDFT",8);  
memcpy(prod_load_info.Reg_ID_Type,"ᑍPRDDFN ",1ð);  
memcpy(prod_load_info.Min_Tgt_Rls,"ᑍCURRENT ",1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Fill in the principal library information. There are no  
/ᑍ additional libraries.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(prin_lib_info.Dev_Lib,"ABC  
memcpy(prin_lib_info.Prim_Lib,"ABC  
",1ð);  
",1ð);  
memcpy(prin_lib_info.Post_Exit_Pgm,"ABCPGMMRM2",1ð);  
memset(&add_libs,' ',sizeof(add_libs));  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Fill in the preoperational exit program.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(preop_expgm.Pre_Ext_Pgm,"ABCPGMMRM1",1ð);  
memcpy(preop_expgm.Dev_Lib,"ABC  
",1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ There are no folders. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(&folder_list,' ',sizeof(folder_list));  
memset(text_desc,' ',5ð);  
memcpy(text_desc,"Product ABC",11);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize the error code to have the API send errors through ᑍ/  
Appendix B. Original Examples in Additional Languages B-131  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍ the error code parameter.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.Bytes_Provided=sizeof(error_code);  
QSZCRTPL("ABCðð5ð ",  
&prod_load_info,  
/ᑍ Product load name  
ᑍ/  
ᑍ/  
/ᑍ Product load information  
"
",  
/ᑍ Secondary language lib name ᑍ/  
/ᑍ Principal library  
/ᑍ Additional libraries  
&prin_lib_info,  
&add_libs,  
ð,  
&preop_expgm,  
1,  
&folder_list,  
ð,  
ᑍ/  
ᑍ/  
/ᑍ Number of additional libs ᑍ/  
/ᑍ Preoperational exit program ᑍ/  
/ᑍ Number of preop exit pgms ᑍ/  
/ᑍ Folder list  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Number of folders  
/ᑍ Text description  
/ᑍ Public authority  
/ᑍ Error code  
text_desc,  
"ᑍUSE  
",  
&error_code);  
if (error_code.Bytes_Available > ð)  
{
printf("Failed in QSZCRTPL API with error: %.7s",  
error_code.Exception_Id);  
exit(1);  
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Fill in the product load information. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(prod_load_info.Lod_Type,"ᑍLNG  
memcpy(prod_load_info.Lod_ID,"2924  
",1ð);  
",8);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Fill in the principal library information. There are no  
/ᑍ additional libraries.  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(prin_lib_info.Post_Exit_Pgm,"ABCPGMMRI2",1ð);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Fill in the preoperational exit program.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memcpy(preop_expgm.Pre_Ext_Pgm,"ABCPGMMRI1",1ð);  
QSZCRTPL("ABCðð29 ",  
&prod_load_info,  
"ABC2924 ",  
&prin_lib_info,  
&add_libs,  
ð,  
/ᑍ Product load name  
ᑍ/  
ᑍ/  
/ᑍ Product load information  
/ᑍ Secondary language lib name ᑍ/  
/ᑍ Principal library  
/ᑍ Additional libraries  
ᑍ/  
ᑍ/  
/ᑍ Number of additional libs ᑍ/  
/ᑍ Preoperational exit program ᑍ/  
/ᑍ Number of preop exit pgms ᑍ/  
&preop_expgm,  
1,  
&folder_list,  
ð,  
/ᑍ Folder list  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Number of folders  
/ᑍ Text description  
/ᑍ Public authority  
/ᑍ Error code  
text_desc,  
"ᑍUSE  
",  
&error_code);  
if (error_code.Bytes_Available > ð)  
{
printf("Failed in QSZCRTPL API with error: %.7s",  
B-132 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
error_code.Exception_Id);  
exit(1);  
}
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function:  
Change_Obj_Descr  
ᑍ/  
ᑍ/  
/ᑍ Description: Change object descriptions for all objects  
/ᑍ  
/ᑍ  
that make up Product ABC. Currently there are 15 ᑍ/  
objects. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void Change_Obj_Descr()  
{
typedef struct {  
char obj_name_lib[21];  
char obj_type[11];  
char prd_opt_id[5];  
char prd_opt_ld[5];  
char lp_id[4];  
} obj_info_t;  
typedef struct {  
int numkey;  
Qus_Vlen_Rec_3_t PID_rec;  
char PID[4];  
Qus_Vlen_Rec_3_t LID_rec;  
char LID[4];  
Qus_Vlen_Rec_3_t LP_rec;  
char LP[13];  
} change_obj_info_t;  
int i;  
obj_info_t obj_info[15] = {"ABCPGMMRM1ABC  
","ᑍPGM  
"ðððð","5ðð1","ðABCABCV3R1Mð",  
"ABCPGMMRM2ABC ","ᑍPGM  
"ðððð","5ðð1","ðABCABCV3R1Mð",  
"ABCPGMMRI1ABC ","ᑍPGM  
"ðððð","2924","ðABCABCV3R1Mð",  
"ABCPGMMRI2ABC ","ᑍPGM  
"ðððð","2924","ðABCABCV3R1Mð",  
"ABCPGM ABC ","ᑍPGM  
"ðððð","5ðð1","ðABCABCV3R1Mð",  
"QCLSRC ABC ","ᑍFILE  
"ðððð","2924","ðABCABCV3R1Mð",  
"ABCDSPF ABC ","ᑍFILE  
"ðððð","2924","ðABCABCV3R1Mð",  
"ABCPF ABC ","ᑍFILE  
"ðððð","2924","ðABCABCV3R1Mð",  
"ABCMSG ABC ","ᑍMSGF  
"ðððð","2924","ðABCABCV3R1Mð",  
"ABC ABC ","ᑍCMD  
"ðððð","2924","ðABCABCV3R1Mð",  
"ABCPNLGRP ABC ","ᑍPNLGRP ",  
",  
",  
",  
",  
",  
",  
",  
",  
",  
",  
"ðððð","2924","ðABCABCV3R1Mð",  
"ABCðð5ð ABC  
","ᑍPRDDFN ",  
"ðððð","5ðð1","ðABCABCV3R1Mð",  
"ABCðð5ð ABC  
","ᑍPRDLOD ",  
Appendix B. Original Examples in Additional Languages B-133  
Download from Www.Somanuals.com. All Manuals Search And Download.  
"ðððð","5ðð1","ðABCABCV3R1Mð",  
"ABCðð29 ABC  
","ᑍPRDLOD ",  
"ðððð","2924","ðABCABCV3R1Mð",  
"ABC  
ABC  
","ᑍLIB  
",  
"ðððð","5ðð1","ðABCABCV3R1Mð"};  
/ᑍ Change object information ᑍ/  
change_obj_info_t cobji;  
Qus_EC_t error_code;  
char rtn_lib[1ð];  
/ᑍ Error code parameter  
/ᑍ Return library  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Fill in the changed object information. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
cobji.numkey=3;  
cobji.PID_rec.Key=13;  
cobji.PID_rec.Length_Vlen_Record=4;  
cobji.LID_rec.Key=12;  
cobji.LID_rec.Length_Vlen_Record=4;  
cobji.LP_rec.Key=5;  
cobji.LP_rec.Length_Vlen_Record=13;  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize the error code to have the API send errors through ᑍ/  
/ᑍ the error code parameter.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.Bytes_Provided=sizeof(error_code);  
for (i=ð; i<15; i++)  
{
memcpy(cobji.PID,obj_info[i].prd_opt_id,4);  
memcpy(cobji.LID,obj_info[i].prd_opt_ld,4);  
memcpy(cobji.LP,obj_info[i].lp_id,13);  
QLICOBJD(rtn_lib,  
/ᑍ Return library  
ᑍ/  
ᑍ/  
ᑍ/  
obj_info[i].obj_name_lib, /ᑍ Object name  
obj_info[i].obj_type,  
&cobji,  
&error_code);  
/ᑍ Object type  
/ᑍ Changed object informationᑍ/  
/ᑍ Error code ᑍ/  
if (error_code.Bytes_Available > ð)  
{
printf("Failed in QLICOBJD API with error: %.7s",  
error_code.Exception_Id);  
exit(1);  
}
}
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Function:  
Package_Prod  
ᑍ/  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Description: Package Product ABC so that all the SAVLICPGM,  
/ᑍ  
/ᑍ  
RSTLICPGM and DLTLICPGM commands work with the  
product.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void Package_Prod()  
{
Qsz_Prd_Opt_Inf_t prod_opt_info; /ᑍ Product option information ᑍ/  
Qus_EC_t error_code;  
/ᑍ Error code parameter  
ᑍ/  
B-134 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Fill in the product option information. ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
memset(&prod_opt_info,' ',sizeof(prod_opt_info));  
memcpy(prod_opt_info.Opt,"ðððð",4);  
memcpy(prod_opt_info.PID,"ðABCABC",7);  
memcpy(prod_opt_info.Rls_Lvl,"V3R1Mð",6);  
memcpy(prod_opt_info.Lod_ID,"ᑍALL  
",8);  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Initialize the error code to have the API send errors through ᑍ/  
/ᑍ the error code parameter.  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
error_code.Bytes_Provided=sizeof(error_code);  
QSZPKGPO(&prod_opt_info,  
"ᑍYES",  
/ᑍ Product option information ᑍ/  
/ᑍ Repackage  
ᑍ/  
ᑍ/  
ᑍ/  
"ᑍNO ",  
/ᑍ Allow object change  
/ᑍ Error code  
&error_code);  
if (error_code.Bytes_Available > ð)  
{
printf("Failed in QSZPKGPO API with error: %.7s",  
error_code.Exception_Id);  
exit(1);  
}
}
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Start of main procedure  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
void main()  
{
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Create Product Definition Object  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
Create_Prod_Def_Obj();  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Create Product Load Objects  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
Create_Prod_Load_Obj();  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Change Object Description  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
Change_Obj_Descr();  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ Package Product ABC  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
Package_Prod();  
}
Appendix B. Original Examples in Additional Languages B-135  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Program for Packaging a Product—ILE COBOL Example  
Refer to “Program for Packaging a Product—OPM RPG Example” on page A-3 for  
the original example. The following program also works for OPM COBOL.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍProgram Name: SFTWPRDEX  
ᑍ
ᑍLanguage: COBOL  
ᑍ
ᑍDescriptive Name: Software Product Example  
ᑍ
ᑍDescription: This example shows you the steps necessary to  
ᑍ
ᑍ
package your product like IBM products.  
ᑍHeader Files Included: QUSEC  
- Error Code Parameter  
ᑍ
ᑍ
ᑍ
ᑍ
QSZCRTPD - Create Product Definition API  
QSZCRTPL - Create Product Load API  
QSZPKGPO - Package Product Option API  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PROGRAM-ID. SFTWPRDEX.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
ᑍ
ᑍ
WORKING-STORAGE SECTION.  
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Create Product Definition API Include  
ᑍ
B-136 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
COPY QSZCRTPD OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Create Product Load API Include  
ᑍ
COPY QSZCRTPL OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Package Product Option API Include  
ᑍ
COPY QSZPKGPO OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Error message text  
ᑍ
ð1 BAD-NEWS.  
ð5 TEXT1  
PIC X(14) VALUE "Failed in API ".  
ð5 API-NAME  
ð5 TEXT2  
ð5 EXCEPTION-ID PIC X(ð7).  
PIC X(1ð).  
PIC X(11) VALUE "with error ".  
ᑍ
ᑍ Compile Time Array  
ᑍ
ð1 OBJ-INFO.  
ð5 ELEMENT-ð1 PIC X(41)  
VALUE "ABCPGMMRM1ᑍPGM  
ð5 ELEMENT-ð2 PIC X(41)  
VALUE "ABCPGMMRM2ᑍPGM  
ð5 ELEMENT-ð3 PIC X(41)  
VALUE "ABCPGMMRI1ᑍPGM  
ð5 ELEMENT-ð4 PIC X(41)  
VALUE "ABCPGMMRI2ᑍPGM  
ðððð5ðð1ðABCABCV3R1Mð".  
ðððð5ðð1ðABCABCV3R1Mð".  
ðððð2924ðABCABCV3R1Mð".  
ðððð2924ðABCABCV3R1Mð".  
ðððð5ðð1ðABCABCV3R1Mð".  
ðððð2924ðABCABCV3R1Mð".  
ðððð2924ðABCABCV3R1Mð".  
ðððð2924ðABCABCV3R1Mð".  
ðððð2924ðABCABCV3R1Mð".  
ðððð2924ðABCABCV3R1Mð".  
ð5 ELEMENT-ð5 PIC X(41)  
VALUE "ABCPGM  
ᑍPGM  
ð5 ELEMENT-ð6 PIC X(41)  
VALUE "QCLSRC  
ᑍFILE  
ð5 ELEMENT-ð7 PIC X(41)  
VALUE "ABCDSPF ᑍFILE  
ð5 ELEMENT-ð8 PIC X(41)  
VALUE "ABCPF  
ð5 ELEMENT-ð9 PIC X(41)  
VALUE "ABCMSG  
ð5 ELEMENT-1ð PIC X(41)  
VALUE "ABC  
ð5 ELEMENT-11 PIC X(41)  
ᑍFILE  
ᑍMSGF  
ᑍCMD  
VALUE "ABCPNLGRP ᑍPNLGRP ðððð2924ðABCABCV3R1Mð".  
ð5 ELEMENT-12 PIC X(41)  
VALUE "ABCðð5ð ᑍPRDDFN ðððð5ðð1ðABCABCV3R1Mð".  
ð5 ELEMENT-13 PIC X(41)  
VALUE "ABCðð5ð ᑍPRDLOD ðððð5ðð1ðABCABCV3R1Mð".  
ð5 ELEMENT-14 PIC X(41)  
VALUE "ABCðð29 ᑍPRDLOD ðððð2924ðABCABCV3R1Mð".  
ð5 ELEMENT-15 PIC X(41)  
VALUE "ABC  
ᑍLIB  
ðððð5ðð1ðABCABCV3R1Mð".  
ᑍ
ð1 OBJECT-TABLE REDEFINES OBJ-INFO.  
ð5 OBJ-INFO-I OCCURS 15 TIMES.  
1ð OBJ-NAME  
1ð OBJ-TYPE  
1ð PRD-OPT-ID  
1ð PRD-OPT-LD  
PIC X(1ð).  
PIC X(1ð).  
PIC X(ð4).  
PIC X(ð4).  
Appendix B. Original Examples in Additional Languages B-137  
Download from Www.Somanuals.com. All Manuals Search And Download.  
1ð LP-ID  
PIC X(13).  
ᑍ
ᑍ Change Object Information parameter  
ᑍ
ð1 COBJI.  
ð5 NUMKEY  
ð5 KEY13  
ð5 LEN13  
ð5 PID13  
ð5 KEY12  
ð5 LEN12  
ð5 LID12  
ð5 KEY5  
ð5 LEN5  
ð5 LP5  
PIC S9(ð9) VALUE 3 BINARY.  
PIC S9(ð9) VALUE 13 BINARY.  
PIC S9(ð9) VALUE 4 BINARY.  
PIC X(ð4).  
PIC S9(ð9) VALUE 12 BINARY.  
PIC S9(ð9) VALUE 4 BINARY.  
PIC X(ð4).  
PIC S9(ð9) VALUE 5 BINARY.  
PIC S9(ð9) VALUE 13 BINARY.  
PIC X(13).  
ᑍ
ᑍ Miscellaneous data  
ᑍ
ð1 MISC.  
ð5 FIRST-ERR  
ð5 PROD-ID  
ð5 PROD-NAME  
ð5 RLS-LVL  
ð5 NBR-OPTS  
ð5 NBR-LANGS  
ð5 TEXT-DESC  
ð5 PUB-AUT  
ð5 NBR-ADD-LB  
ð5 NBR-PE  
ð5 NBR-FLDRS  
ð5 OBJNAM  
ð5 PROD-ID-NM  
ð5 SEC-LANG  
ð5 I  
PIC X(ð1) VALUE "ð".  
PIC X(ð7) VALUE "ðABCABC".  
PIC X(2ð) VALUE "ABCðð5ð ABC".  
PIC X(ð6) VALUE "V3R1Mð".  
PIC S9(ð9) VALUE 1 BINARY.  
PIC S9(ð9) VALUE 1 BINARY.  
PIC X(5ð) VALUE "ABC Product".  
PIC X(1ð) VALUE "ᑍUSE".  
PIC S9(ð9) VALUE ð BINARY.  
PIC S9(ð9) VALUE 1 BINARY.  
PIC S9(ð9) VALUE ð BINARY.  
PIC X(2ð).  
PIC X(1ð).  
PIC X(1ð).  
PIC S9(ð9) BINARY.  
PIC X(1ð).  
PIC X(1ð).  
PIC X(ð4) VALUE "ᑍYES".  
PIC X(ð5) VALUE "ᑍNO".  
ð5 RTN-LIB  
ð5 OBJ-TYPE-2  
ð5 REPKG  
ð5 ALWCHG  
ᑍ
ᑍ Beginning of Mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
ᑍ
ᑍ Initialize the error code parameter. To signal exceptions to  
ᑍ this program by the API, you need to set the bytes provided  
ᑍ field of the error code to zero. Because this program has  
ᑍ exceptions sent back through the error code parameter, it sets  
ᑍ the bytes provided field to the number of bytes it gives the  
ᑍ API for the parameter.  
ᑍ
MOVE LENGTH OF QUS-EC TO BYTES-PROVIDED OF QUS-EC.  
ᑍ
ᑍ Create Product Definition Object - ABCðð5ð  
ᑍ
PERFORM PRDDFN. .1/  
ᑍ
ᑍ Create Product Load Objects - ABCðð5ð (MRM) and ABCðð29 (MRI)  
B-138 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ
PERFORM PRDLOD. .2/  
ᑍ Change Object Description for all objects associated with  
ᑍ ABC Product.  
ᑍ
PERFORM COBJD. .3/  
ᑍ
ᑍ Package the ABC Product so that all the SAVLICPGM, RSTLIBPGM,  
ᑍ and DLTLICPGM commands work with the product.  
ᑍ
PERFORM PKGPO. .4/  
ᑍ
ᑍ All done, product is ready to ship.  
ᑍ
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Subroutine: PRDDFN  
ᑍ
ᑍ Descriptive Name: Create product definitions.  
ᑍ
ᑍ Description: This subroutine will create the product definition  
ᑍ
ᑍ
ABCðð5ð for the ABC Product.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PRDDFN.  
ᑍ
ᑍ Setup for Product Definition  
ᑍ Fill Product Definition Information Parameter  
ᑍ
MOVE PROD-ID OF MISC TO PID OF QSZ-PRD-INF.  
MOVE RLS-LVL OF MISC TO RLS-LVL OF QSZ-PRD-INF.  
MOVE "ABCMSG" TO MSG-FILE OF QSZ-PRD-INF.  
MOVE "ᑍCURRENT" TO FST-CPYRT OF QSZ-PRD-INF.  
MOVE "ᑍCURRENT" TO CUR-CPYRT OF QSZ-PRD-INF.  
MOVE "9412ð1" TO RLS-DATE OF QSZ-PRD-INF.  
MOVE "ᑍNO" TO ALW-MULT-RLS OF QSZ-PRD-INF.  
MOVE "ᑍPHONE" TO REG-ID-TYPE OF QSZ-PRD-INF.  
MOVE "5ð72535ð1ð" TO REG-ID-VAL OF QSZ-PRD-INF.  
ᑍ
ᑍ Fill Product Load Parameter  
ᑍ
MOVE "ðððð" TO OPT OF QSZ-PRD-OPT.  
MOVE "ABCððð1" TO MSG-ID OF QSZ-PRD-OPT.  
MOVE "ᑍNODYNNAM" TO ALW-DYN-NAM OF QSZ-PRD-OPT.  
MOVE "5ðð1" TO COD-LOD OF QSZ-PRD-OPT.  
MOVE SPACES TO RESERVED OF QSZ-PRD-OPT.  
ᑍ
ᑍ Fill Language Load List Parameter  
ᑍ
MOVE "2924" TO LNG-LOD OF QSZ-LNG-LOD.  
Appendix B. Original Examples in Additional Languages B-139  
Download from Www.Somanuals.com. All Manuals Search And Download.  
MOVE "ðððð" TO OPT OF QSZ-LNG-LOD.  
MOVE SPACES TO RESERVED OF QSZ-LNG-LOD.  
ᑍ
ᑍ Create the Product Definition for the ABC Product  
ᑍ
MOVE 1 TO NBR-OPTS.  
MOVE 1 TO NBR-LANGS.  
CALL "QSZCRTPD" USING PROD-NAME, QSZ-PRD-INF, QSZ-PRD-OPT,  
NBR-OPTS, QSZ-LNG-LOD, NBR-LANGS,  
TEXT-DESC, PUB-AUT, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QSZCRTPD" TO API-NAME,  
PERFORM ERRCOD.  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Subroutine: PRDLOD  
ᑍ
ᑍ Descriptive Name: Create product loads.  
ᑍ
ᑍ Description: This subroutine will create the product loads,  
ᑍ
ᑍ
ABCðð5ð and ABCðð29, for the ABC Product.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PRDLOD.  
ᑍ
ᑍ Setup for Product Load for MRM Objects  
ᑍ Fill Product Load Information Parameter  
ᑍ
MOVE PROD-ID OF MISC TO PID OF QSZ-LOD-INF.  
MOVE RLS-LVL OF MISC TO RLS-LVL OF QSZ-LOD-INF.  
MOVE "ðððð" TO OPT OF QSZ-LOD-INF.  
MOVE "ᑍCODE" TO LOD-TYPE OF QSZ-LOD-INF.  
MOVE "ᑍCODEDFT" TO LOD-ID OF QSZ-LOD-INF.  
MOVE "ᑍPRDDFN" TO REG-ID-TYPE OF QSZ-LOD-INF.  
MOVE SPACES TO REG-ID-VAL OF QSZ-LOD-INF.  
MOVE "ᑍCURRENT" TO MIN-TGT-RLS OF QSZ-LOD-INF.  
MOVE SPACES TO RESERVED OF QSZ-LOD-INF.  
ᑍ
ᑍ Fill Principal Library Information Parameter  
ᑍ
MOVE "ABC" TO DEV-LIB OF QSZ-LIB-INF.  
MOVE "ABC" TO PRIM-LIB OF QSZ-LIB-INF.  
MOVE "ABCPGMMRM2" TO POST-EXIT-PGM OF QSZ-LIB-INF.  
ᑍ
ᑍ Fill Preoperation Exit Programs Parameter  
ᑍ
MOVE "ABCPGMMRM1" TO PRE-EXT-PGM OF QSZ-PRE-EXT.  
MOVE "ABC" TO DEV-LIB OF QSZ-PRE-EXT.  
B-140 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ Fill Additional Library List Parameter  
ᑍ
ᑍ
None  
ᑍ Fill Folder List Parameter  
ᑍ
ᑍ
None  
ᑍ Let's create the product load for the ABC Product - MRM Objects  
ᑍ
MOVE "ABCðð5ð" TO PROD-ID-NM.  
MOVE SPACES TO SEC-LANG.  
ᑍ
CALL "QSZCRTPL" USING PROD-ID-NM, QSZ-LOD-INF, SEC-LANG,  
QSZ-LIB-INF, QSZ-ADD-LIB,  
NBR-ADD-LB, QSZ-PRE-EXT, NBR-PE,  
QSZ-FLR-LST, NBR-FLDRS, TEXT-DESC,  
PUB-AUT, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QSZCRTPL" TO API-NAME,  
PERFORM ERRCOD.  
ᑍ
ᑍ Setup for Product Load for MRI Objects  
ᑍ Fill Product Load Information Parameter  
ᑍ
MOVE "ᑍLNG" TO LOD-TYPE OF QSZ-LOD-INF.  
MOVE "2924" TO LOD-ID OF QSZ-LOD-INF.  
ᑍ
ᑍ Fill Principal Library Information Parameter  
ᑍ
MOVE "ABCPGMMRI2" TO POST-EXIT-PGM OF QSZ-LIB-INF.  
ᑍ
ᑍ Fill Preoperation Exit Programs Parameter  
ᑍ
MOVE "ABCPGMMRI1" TO PRE-EXT-PGM OF QSZ-PRE-EXT.  
ᑍ
ᑍ Fill Additional Library List Parameter  
ᑍ
ᑍ
None  
ᑍ Fill Folder List Parameter  
ᑍ
ᑍ
None  
ᑍ Let's create the product load for the ABC Product - MRI Objects  
ᑍ
MOVE "ABCðð29" TO PROD-ID-NM.  
MOVE "ABC2924" TO SEC-LANG.  
ᑍ
CALL "QSZCRTPL" USING PROD-ID-NM, QSZ-LOD-INF, SEC-LANG,  
QSZ-LIB-INF, QSZ-ADD-LIB,  
NBR-ADD-LB, QSZ-PRE-EXT, NBR-PE,  
QSZ-FLR-LST, NBR-FLDRS, TEXT-DESC,  
PUB-AUT, QUS-EC.  
ᑍ
Appendix B. Original Examples in Additional Languages B-141  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QSZCRTPL" TO API-NAME,  
PERFORM ERRCOD.  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Subroutine: COBJD  
ᑍ
ᑍ Descriptive Name: Change object descriptions for ABC Product.  
ᑍ
ᑍ Description: This subroutine will change the object  
ᑍ
ᑍ
ᑍ
ᑍ
descriptions for all objects that make up the  
ABC Product. Currently that is 15 objects. They  
are listed at the end of this program.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
COBJD.  
ᑍ
ᑍ Need to associate all objects with the ABC Product  
ᑍ
PERFORM CHG-OBJD VARYING I FROM 1 BY 1 UNTIL I > 15.  
ᑍ
CHG-OBJD.  
STRING OBJ-NAME(I), "ABC" DELIMITED BY SIZE INTO OBJNAM.  
MOVE LP-ID(I) TO LP5.  
MOVE PRD-OPT-ID(I) TO PID13.  
MOVE PRD-OPT-LD(I) TO LID12.  
MOVE OBJ-TYPE(I) TO OBJ-TYPE-2.  
ᑍ
CALL "QLICOBJD" USING RTN-LIB, OBJNAM, OBJ-TYPE-2,  
COBJI, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QLICOBJD" TO API-NAME,  
PERFORM ERRCOD.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Subroutine: PKGPO  
ᑍ
ᑍ Descriptive Name: Package software ABC Product.  
ᑍ
ᑍ Description: This subroutine will package the ABC Product.  
ᑍ
ᑍ
It makes sure that all objects exist that are  
associated with the product.  
B-142 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
PKGPO.  
ᑍ
ᑍ Setup for packing the ABC Product.  
ᑍ Fill Product Option Information Parameter  
ᑍ
MOVE "ðððð" TO OPT OF QSZ-PRD-OPT-INF.  
MOVE PROD-ID OF MISC TO PID OF QSZ-PRD-OPT-INF.  
MOVE RLS-LVL OF MISC TO RLS-LVL OF QSZ-PRD-OPT-INF.  
MOVE "ᑍALL" TO LOD-ID OF QSZ-PRD-OPT-INF.  
MOVE SPACES TO RESERVED OF QSZ-PRD-OPT-INF.  
ᑍ
ᑍ Let's package the ABC Product.  
ᑍ
CALL "QSZPKGPO" USING QSZ-PRD-OPT-INF, REPKG,  
ALWCHG, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QSZPKGPO" TO API-NAME,  
PERFORM ERRCOD.  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Subroutine: ERRCOD  
ᑍ
ᑍ Descriptive Name: Process API errors.  
ᑍ
ᑍ Description: This subroutine will print a line to a spooled  
ᑍ
ᑍ
ᑍ
file if any errors are returned in the error code  
parameter.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ERRCOD.  
ᑍ
ᑍ Process errors returned from the API.  
ᑍ
ᑍ If first error found, then open QPRINT ᑍPRTF  
ᑍ
IF FIRST-ERR = "ð"  
OPEN OUTPUT LISTING,  
MOVE "1" TO FIRST-ERR.  
ᑍ
ᑍ Output the error and the API that received the error  
ᑍ
MOVE EXCEPTION-ID OF QUS-EC TO EXCEPTION-ID OF BAD-NEWS.  
WRITE LIST-LINE FROM BAD-NEWS.  
Appendix B. Original Examples in Additional Languages B-143  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Program for Packaging a Product—ILE RPG Example  
Refer to “Program for Packaging a Product—OPM RPG Example” on page A-3 for  
the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FᑍProgram Name: SFTWPRDEX  
Fᑍ  
FᑍLanguage: ILE RPG  
Fᑍ  
FᑍDescriptive Name: Software Product Example  
Fᑍ  
FᑍDescription: This example shows you the steps necessary to  
Fᑍ  
Fᑍ  
package your product like IBM products.  
FᑍHeader Files Included: QUSEC  
- Error Code Parameter  
Fᑍ  
Fᑍ  
Fᑍ  
Fᑍ  
QSZCRTPD - Create Product Definition API  
QSZCRTPL - Create Product Load API  
QSZPKGPO - Package Product Option API  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQPRINT  
Dᑍ  
O
F 132  
PRINTER OFLIND(ᑍINOF) USROPN  
Dᑍ Error Code parameter include. As this sample program  
Dᑍ uses /COPY to include the error code structure, only the first  
Dᑍ 16 bytes of the error code structure are available. If the  
Dᑍ application program needs to access the variable length  
Dᑍ exception data for the error, the developer should physically  
Dᑍ copy the QSYSINC include and modify the copied include to  
Dᑍ define additional storage for the exception data.  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
Dᑍ Create Product Definition API Include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QSZCRTPD  
Dᑍ  
Dᑍ Create Product Load API Include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QSZCRTPL  
Dᑍ  
Dᑍ Package Product Option API Include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QSZPKGPO  
Dᑍ  
Dᑍ Compile Time Array  
Dᑍ  
DOBJ_INFO  
Dᑍ  
S
41  
DIM(15) CTDATA PERRCD(1)  
BASED(OBJ_PTR)  
DOBJ_INFO_I  
D OBJ_NAME  
D OBJ_TYPE  
D PRD_OPT_ID  
D PRD_OPT_LD  
D LP_ID  
DS  
1ð  
1ð  
4
4
13  
B-144 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
Dᑍ Change Object Information parameter  
Dᑍ  
DCOBJI  
D NUMKEY  
D KEY13  
D LEN13  
D PID13  
D KEY12  
D LEN12  
D LID12  
D KEY5  
D LEN5  
D LP5  
DS  
9B ð INZ(3)  
9B ð INZ(13)  
9B ð INZ(4)  
4
9B ð INZ(12)  
9B ð INZ(4)  
4
9B ð INZ(5)  
9B ð INZ(13)  
13  
Dᑍ  
Dᑍ Miscellaneous data  
Dᑍ  
DAPI_NAME  
DFIRST_ERR  
DPROD_ID  
DPROD_NAME  
DRLS_LVL  
DNBR_OPTS  
DNBR_LANGS  
DTEXT_DESC  
DPUB_AUT  
DNBR_ADD_LB  
DNBR_PE  
S
S
S
S
S
S
S
S
S
S
S
S
S
1ð  
1
INZ('ð')  
7
INZ('ðABCABC')  
INZ('ABCðð5ð ABC  
INZ('V3R1Mð')  
2ð  
6
')  
9B ð INZ(1)  
9B ð INZ(1)  
5ð  
1ð  
INZ('ABC Product')  
INZ('ᑍUSE')  
9B ð INZ(ð)  
9B ð INZ(1)  
9B ð INZ(ð)  
DNBR_FLDRS  
DOBJNAM  
2ð  
Cᑍ  
Cᑍ Beginning of Mainline  
Cᑍ  
Cᑍ Initialize the error code parameter. To signal exceptions to  
Cᑍ this program by the API, you need to set the bytes provided  
Cᑍ field of the error code to zero. Because this program has  
Cᑍ exceptions sent back through the error code parameter, it sets  
Cᑍ the bytes provided field to the number of bytes it gives the  
Cᑍ API for the parameter.  
Cᑍ  
C
EVAL  
QUSBPRV = %SIZE(QUSEC)  
Cᑍ  
Cᑍ Create Product Definition Object - ABCðð5ð  
Cᑍ  
C
Cᑍ  
EXSR  
PRDDFN  
.1/  
Cᑍ Create Product Load Objects - ABCðð5ð (MRM) and ABCðð29 (MRI)  
Cᑍ  
C
Cᑍ  
EXSR  
PRDLOD  
.2/  
Cᑍ Change Object Description for all objects associated with  
Cᑍ the ABC Product.  
Cᑍ  
C
EXSR  
COBJD  
.3/  
Cᑍ  
Cᑍ Package the ABC Product so that all the SAVLICPGM, RSTLIBPGM,  
Cᑍ and DLTLICPGM commands work with the product.  
Cᑍ  
Appendix B. Original Examples in Additional Languages B-145  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
Cᑍ  
EXSR  
PKGPO  
.4/  
Cᑍ All done, product is ready to ship.  
Cᑍ  
C
EVAL  
RETURN  
ᑍINLR = '1'  
C
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
Cᑍ Subroutine: PRDDFN  
Cᑍ  
Cᑍ Descriptive Name: Create product definitions.  
Cᑍ  
Cᑍ Description: This subroutine will create the product definition  
Cᑍ  
Cᑍ  
ABCðð5ð for the ABC product.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
PRDDFN  
BEGSR  
Cᑍ Setup for Product Definition  
Cᑍ Fill Product Definition Information Parameter  
Cᑍ  
C
C
C
C
C
C
C
C
C
Cᑍ  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
QSZPID = PROD_ID  
QSZRL = RLS_LVL  
QSZMFIL = 'ABCMSG'  
QSZFC = 'ᑍCURRENT'  
QSZCC = 'ᑍCURRENT'  
QSZRD = '9412ð1'  
QSZAMR = 'ᑍNO'  
QSZRIDT = 'ᑍPHONE'  
QSZRIDV = '5ð72535ð1ð'  
Cᑍ Fill Product Load Parameter  
Cᑍ  
C
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
QSZOPT = 'ðððð'  
C
QSZMID = 'ABCððð1'  
QSZADN = 'ᑍNODYNNAM'  
QSZCL = '5ðð1'  
C
C
C
Cᑍ  
QSZERVEDðð = ᑍBLANKS  
Cᑍ Fill Language Load List Parameter  
Cᑍ  
C
EVAL  
EVAL  
EVAL  
QSZLLðð = '2924'  
QSZOPTðð = 'ðððð'  
QSZERVEDð1 = ᑍBLANKS  
C
C
Cᑍ  
Cᑍ Create the Product Definition for the ABC Product  
Cᑍ  
C
C
C
C
CALL  
PARM  
PARM  
PARM  
'QSZCRTPD'  
PROD_NAME  
QSZPI  
QSZPO  
B-146 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
1
1
NBR_OPTS  
QSZLL  
NBR_LANGS  
TEXT_DESC  
PUB_AUT  
QUSEC  
C
C
C
C
C
Cᑍ  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
API_NAME = 'QSZCRTPD'  
ERRCOD  
C
EVAL  
EXSR  
ENDIF  
C
C
Cᑍ  
C
Cᑍ  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
Cᑍ Subroutine: PRDLOD  
Cᑍ  
Cᑍ Descriptive Name: Create product loads.  
Cᑍ  
Cᑍ Description: This subroutine will create the product loads,  
Cᑍ  
Cᑍ  
ABCðð5ð and ABCðð29, for the ABC product.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
PRDLOD  
BEGSR  
Cᑍ Setup for Product Load for MRM Objects  
Cᑍ Fill Product Load Information Parameter  
Cᑍ  
C
C
C
C
C
C
C
C
C
Cᑍ  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
QSZPIDðð = PROD_ID  
QSZRLðð = RLS_LVL  
QSZOPTð1 = 'ðððð'  
QSZLT = 'ᑍCODE'  
QSZLID = 'ᑍCODEDFT'  
QSZRIDTðð = 'ᑍPRDDFN'  
QSZRIDVðð = ᑍBLANKS  
QSZMTR = 'ᑍCURRENT'  
QSZERVEDð2 = ᑍBLANKS  
Cᑍ Fill Principal Library Information Parameter  
Cᑍ  
C
EVAL  
EVAL  
EVAL  
QSZDL = 'ABC'  
QSZPL = 'ABC'  
QSZPEP = 'ABCPGMMRM2'  
C
C
Cᑍ  
Cᑍ Fill Preoperation Exit Programs Parameter  
Cᑍ  
C
EVAL  
EVAL  
QSZPEPðð = 'ABCPGMMRM1'  
QSZDLðð = 'ABC'  
C
Cᑍ  
Appendix B. Original Examples in Additional Languages B-147  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ Fill Additional Library List Parameter  
Cᑍ  
Cᑍ  
None  
Cᑍ Fill Folder List Parameter  
Cᑍ  
Cᑍ  
None  
Cᑍ Let's create the product load for the ABC Product - MRM Objects  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'QSZCRTPL'  
'ABCðð5ð'  
PROD_ID_NM  
QSZLI  
SEC_LANG  
QSZLIðð  
QSZAL  
NBR_ADD_LB  
QSZPE  
NBR_PE  
QSZFL  
NBR_FLDRS  
TEXT_DESC  
PUB_AUT  
QUSEC  
1ð  
1ð  
ᑍBLANKS  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
API_NAME = 'QSZCRTPL'  
ERRCOD  
C
EVAL  
EXSR  
ENDIF  
C
C
Cᑍ  
Cᑍ Setup for Product Load for MRI Objects  
Cᑍ Fill Product Load Information Parameter  
Cᑍ  
C
EVAL  
EVAL  
QSZLT = 'ᑍLNG'  
QSZLID = '2924'  
C
Cᑍ  
Cᑍ Fill Principal Library Information Parameter  
Cᑍ  
C
Cᑍ  
EVAL  
QSZPEP = 'ABCPGMMRI2'  
Cᑍ Fill Preoperation Exit Programs Parameter  
Cᑍ  
C
EVAL  
QSZPEPðð = 'ABCPGMMRI1'  
Cᑍ  
Cᑍ Fill Additional Library List Parameter  
Cᑍ  
Cᑍ  
Cᑍ Fill Folder List Parameter  
Cᑍ  
Cᑍ  
None  
None  
Cᑍ Let's create the product load for the ABC Product - MRI Objects  
Cᑍ  
C
C
C
CALL  
PARM  
PARM  
'QSZCRTPL'  
'ABCðð29'  
PROD_ID_NM  
QSZLI  
B-148 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
C
C
C
C
C
C
C
C
C
C
Cᑍ  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'ABC2924'  
SEC_LANG  
QSZLIðð  
QSZAL  
NBR_ADD_LB  
QSZPE  
NBR_PE  
QSZFL  
NBR_FLDRS  
TEXT_DESC  
PUB_AUT  
QUSEC  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
API_NAME = 'QSZCRTPL'  
ERRCOD  
C
EVAL  
EXSR  
ENDIF  
C
C
Cᑍ  
C
Cᑍ  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
Cᑍ Subroutine: COBJD  
Cᑍ  
Cᑍ Descriptive Name: Change object descriptions for ABC Product.  
Cᑍ  
Cᑍ Description: This subroutine will change the object  
Cᑍ  
Cᑍ  
Cᑍ  
Cᑍ  
descriptions for all objects that make up the  
ABC Product. Currently that is 15 objects. They  
are listed at the end of this program.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
COBJD  
BEGSR  
Cᑍ Need to associate all objects with the ABC Product  
Cᑍ  
C
1
DO  
15  
I
3 ð  
C
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
OBJ_PTR = %ADDR(OBJ_INFO(I))  
OBJNAM = OBJ_NAME + 'ABC'  
LP5 = LP_ID  
C
C
C
PID13 = PRD_OPT_ID  
LID12 = PRD_OPT_LD  
TYPE = OBJ_TYPE  
C
C
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
'QLICOBJD'  
RTN_LIB  
OBJNAM  
TYPE  
C
1ð  
1ð  
C
C
C
COBJI  
C
QUSEC  
Cᑍ  
Appendix B. Original Examples in Additional Languages B-149  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
API_NAME = 'QLICOBJD'  
ERRCOD  
C
EVAL  
EXSR  
ENDIF  
C
C
Cᑍ  
C
Cᑍ  
C
Cᑍ  
ENDDO  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
Cᑍ Subroutine: PKGPO  
Cᑍ  
Cᑍ Descriptive Name: Package software ABC Product.  
Cᑍ  
Cᑍ Description: This subroutine will package the ABC Product.  
Cᑍ  
Cᑍ  
Cᑍ  
It makes sure that all objects exist that are  
associated with the product.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
PKGPO  
BEGSR  
Cᑍ Setup for packing the ABC Product.  
Cᑍ Fill Product Option Information Parameter  
Cᑍ  
C
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
QSZOPTð2 = 'ðððð'  
QSZPIDð1 = PROD_ID  
QSZRLð1 = RLS_LVL  
QSZLIDðð = 'ᑍALL'  
QSZERVEDð3 = ᑍBLANKS  
C
C
C
C
Cᑍ  
Cᑍ Let's package the ABC Product.  
Cᑍ  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
'QSZPKGPO'  
C
QSZPOI  
REPKG  
ALWCHG  
QUSEC  
C
'ᑍYES'  
'ᑍNO'  
4
5
C
C
Cᑍ  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
API_NAME = 'QSZPKGPO'  
ERRCOD  
C
EVAL  
EXSR  
ENDIF  
C
C
Cᑍ  
B-150 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
Cᑍ  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
Cᑍ Subroutine: ERROR  
Cᑍ  
Cᑍ Descriptive Name: Process API errors.  
Cᑍ  
Cᑍ Description: This subroutine will print a line to a spooled  
Cᑍ  
Cᑍ  
Cᑍ  
file if any errors are returned in the error code  
parameter.  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
ERRCOD  
BEGSR  
Cᑍ Process errors returned from the API.  
Cᑍ  
Cᑍ If first error found, then open QPRINT ᑍPRTF  
Cᑍ  
C
IF  
FIRST_ERR = 'ð'  
QPRINT  
C
OPEN  
EVAL  
ENDIF  
C
FIRST_ERR = '1'  
C
Cᑍ  
Cᑍ Output the error and the API that received the error  
Cᑍ  
C
EXCEPT  
BAD_NEWS  
Cᑍ  
C
ENDSR  
OQPRINT  
E
BAD_NEWS  
1
O
O
O
O
'Failed in API '  
'with error '  
API_NAME  
QUSEI  
ᑍᑍCTDATA OBJ_INFO  
ABCPGMMRM1ᑍPGM  
ABCPGMMRM2ᑍPGM  
ABCPGMMRI1ᑍPGM  
ABCPGMMRI2ᑍPGM  
ðððð5ðð1ðABCABCV3R1Mð  
ðððð5ðð1ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ðððð5ðð1ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ðððð2924ðABCABCV3R1Mð  
ABCPGM  
QCLSRC  
ᑍPGM  
ᑍFILE  
ABCDSPF ᑍFILE  
ABCPF  
ABCMSG  
ABC  
ᑍFILE  
ᑍMSGF  
ᑍCMD  
ABCPNLGRP ᑍPNLGRP ðððð2924ðABCABCV3R1Mð  
ABCðð5ð ᑍPRDDFN ðððð5ðð1ðABCABCV3R1Mð  
ABCðð5ð ᑍPRDLOD ðððð5ðð1ðABCABCV3R1Mð  
ABCðð29 ᑍPRDLOD ðððð2924ðABCABCV3R1Mð  
ABC  
ᑍLIB  
ðððð5ðð1ðABCABCV3R1Mð  
Appendix B. Original Examples in Additional Languages B-151  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Retrieving a File Description to a User Space—Examples  
This section includes the examples in “Retrieving a File Description to a User  
Space—ILE C Example” on page A-11.  
Retrieving a File Description to a User Space—ILE COBOL Example  
Refer to “Retrieving a File Description to a User Space—ILE C Example” on  
page A-11 for the original example. The following program also works with OPM  
COBOL.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program:  
RTVFD  
ᑍ
ᑍ Language:  
ᑍ
COBOL  
ᑍ Description: This program retrieves a file definition  
ᑍ
template to a user space.  
ᑍ
ᑍ APIs Used:  
QDBRTVFD - Retrieve File Description  
QUSCRTUS - Create User Space  
QUSCUSAT - Change User Space Attributes  
QUSPTRUS - Retrieve a pointer to a User Space  
ᑍ
ᑍ
ᑍ
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-ID. RTVFD.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
DATA DIVISION.  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include. As this sample program  
ᑍ uses COPY to include the error code structure, only the first  
ᑍ 16 bytes of the error code structure are available. If the  
ᑍ application program needs to access the variable length  
ᑍ exception data for the error, the developer should physically  
ᑍ copy the QSYSINC include and modify the copied include to  
ᑍ define additional storage for the exception data.  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Misc. elements  
ᑍ
ð1 MISC.  
ð5 EXIT-POINT-NAME PIC X(2ð) VALUE "EXAMPLE_EXIT_POINT".  
ð5 EXIT-PGM-NBR  
PIC S9(ð9) VALUE -1 BINARY.  
ð5 EXIT-PARAMETERS PIC X(1ð).  
ð5 FILE-USED  
ð5 LIBRARY-NAME  
ð5 SPACE-SIZE  
ð5 SPACE-INIT  
PIC X(2ð).  
PIC X(1ð).  
PIC S9(ð9) BINARY.  
PIC X(ð1) VALUE "X'ðð'".  
ð5 SPACE-POINTER POINTER.  
B-152 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ð5 FORMAT-NAME-1 PIC X(ð8).  
ð5 OVERRIDES  
ð5 SYSTEM  
ð5 FORMAT-1  
ð5 EXT-ATTR  
ð5 SPACE-AUT  
ð5 SPACE-TEXT  
PIC X(ð1) VALUE "ð".  
PIC X(1ð) VALUE "ᑍLCL".  
PIC X(1ð) VALUE "ᑍINT".  
PIC X(1ð).  
PIC X(1ð) VALUE "ᑍCHANGE".  
PIC X(5ð) VALUE "QDBRTVFD".  
ð5 SPACE-REPLACE PIC X(1ð) VALUE "ᑍYES".  
ð5 SPACE-DOMAIN  
ð5 API-NAME  
PIC X(1ð) VALUE "ᑍUSER".  
PIC X(1ð).  
ð1 CHG-US-ATTR.  
ð5 NBR-OF-ATTR  
ð5 ATTR-KEY  
ð5 DATA-SIZE  
ð5 ATTR-DATA  
PIC S9(ð9) VALUE 1 BINARY.  
PIC S9(ð9) VALUE 3 BINARY.  
PIC S9(ð9) VALUE 1 BINARY.  
PIC X(ð1) VALUE "1".  
ᑍ
ᑍ
LINKAGE SECTION.  
ð1 SPACE-NAME  
PIC X(2ð).  
PIC X(2ð).  
PIC X(1ð).  
ð1 FILE-NAME  
ð1 FORMAT-NAME-PARM  
ᑍ Retrieve File Description API include.  
ᑍ
COPY QDBRTVFD OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION USING SPACE-NAME, FILE-NAME,  
FORMAT-NAME-PARM.  
MAIN-LINE.  
ᑍ
PERFORM INITIALIZE-SPACE.  
PERFORM PROCESS-SPACE.  
PERFORM PROGRAM-DONE.  
ᑍ
ᑍ Start of subroutines  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROCESS-SPACE.  
ᑍ
ᑍ The template returned from QDBRTVFD is now addressable by way  
ᑍ of SPACE-POINTER; as an example the program will now display  
ᑍ the access method for the file:  
ᑍ
DISPLAY QDBFPACT OF QDB-QDBFH.  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
INITIALIZE-SPACE.  
ᑍ
ᑍ One time initialization code for this program  
ᑍ
ᑍ Set Error Code structure to not use exceptions  
ᑍ
MOVE 16 TO BYTES-PROVIDED OF QUS-EC.  
ᑍ
ᑍ Create a User Space for QDBRTVFD  
ᑍ
Appendix B. Original Examples in Additional Languages B-153  
Download from Www.Somanuals.com. All Manuals Search And Download.  
MOVE 1ð24 TO SPACE-SIZE.  
CALL "QUSCRTUS" USING SPACE-NAME, EXT-ATTR, SPACE-SIZE,  
SPACE-INIT, SPACE-AUT, SPACE-TEXT,  
SPACE-REPLACE, QUS-EC, SPACE-DOMAIN.  
ᑍ
ᑍ Check for errors on QUSCRTUS  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QUSCRTUS" TO API-NAME,  
PERFORM API-ERROR-FOUND.  
ᑍ
ᑍ Change the User Space so that it is extendable  
ᑍ
CALL "QUSCUSAT" USING LIBRARY-NAME, SPACE-NAME,  
CHG-US-ATTR, QUS-EC.  
ᑍ
ᑍ Check for errors on QUSCUSAT  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QUSCUSAT" TO API-NAME,  
PERFORM API-ERROR-FOUND.  
ᑍ
ᑍ Get a resolved pointer to the User Space  
ᑍ
CALL "QUSPTRUS" USING SPACE-NAME, SPACE-POINTER, QUS-EC.  
ᑍ
ᑍ Check for errors on QUSPTRUS  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QUSPTRAT" TO API-NAME,  
PERFORM API-ERROR-FOUND.  
ᑍ
ᑍ If no errors, then call QDBRTVFD passing the address of the  
ᑍ User Space as the receiver variable. To accomplish this,  
ᑍ assign the address of QDB-QDBFH to SPACE-POINTER and then  
ᑍ pass QDB-QDBFH.  
ᑍ
SET ADDRESS OF QDB-QDBFH TO SPACE-POINTER.  
ᑍ
MOVE 167767ð4 TO SPACE-SIZE.  
MOVE "FILDð1ðð" TO FORMAT-NAME-1.  
ᑍ
CALL "QDBRTVFD" USING QDB-QDBFH, SPACE-SIZE, FILE-USED,  
FORMAT-NAME-1, FILE-NAME,  
FORMAT-NAME-PARM, OVERRIDES,  
SYSTEM OF MISC, FORMAT-1, QUS-EC.  
ᑍ
ᑍ Check for errors on QDBRTVFD  
ᑍ
IF BYTES-AVAILABLE OF QUS-EC > ð  
MOVE "QDBRTVFD" TO API-NAME,  
PERFORM API-ERROR-FOUND.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
API-ERROR-FOUND.  
ᑍ
ᑍ Log any error encountered, and exit the program  
ᑍ
DISPLAY API-NAME.  
B-154 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
DISPLAY EXCEPTION-ID OF QUS-EC.  
PERFORM PROGRAM-DONE.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-DONE.  
ᑍ
ᑍ Exit the program  
ᑍ
STOP RUN.  
Retrieving a File Description to a User Space—ILE RPG Example  
Refer to “Retrieving a File Description to a User Space—ILE C Example” on  
page A-11 for the original example.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Program:  
Dᑍ  
RTVFD  
Dᑍ Language:  
Dᑍ  
ILE RPG  
Dᑍ Description: This program retrieves a file definition  
Dᑍ  
template to a user space.  
Dᑍ  
Dᑍ APIs Used:  
QDBRTVFD - Retrieve File Description  
QUSCRTUS - Create User Space  
QUSCUSAT - Change User Space Attributes  
QUSPTRUS - Retrieve a pointer to a User Space  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Error Code parameter include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
Dᑍ Not shown due to its size, this program also includes QDBRTVFD  
Dᑍ and defines all of the data structures in QDBRTVFD as being  
Dᑍ BASED(SPCPTR). For illustrative purposes, this sample shows  
Dᑍ only the first significant data structure.  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
DᑍFile Definition Template (FDT) Header  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DᑍThis section is always located at the beginning of the  
Dᑍreturned data.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
DQDBQ25  
DS  
BASED(SPCPTR)  
Header information - The  
FDT starts here  
Dᑍ  
Dᑍ  
D QDBFYRET  
1
5
4B ð  
Dᑍ  
Dᑍ  
Bytes returned - The length  
of the data returned  
8B ð  
D QDBFYAVL  
Dᑍ  
Dᑍ  
Bytes available - The number  
of bytes provided for the  
Appendix B. Original Examples in Additional Languages B-155  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
file definition template  
data  
Dᑍ  
DᑍQDBFHFLG  
2
D QDBBITS27  
9
2
1
1
1
1
1
1
1
1
1
1
2
1
1
1ð  
Dᑍ QDBRSV1ðð  
BITS  
Dᑍ QDBFHFPLðð  
BIT  
Dᑍ QDBRSV2ðð  
BIT  
Dᑍ QDBFHFSUðð  
BIT  
Dᑍ QDBRSV3ðð  
BIT  
Dᑍ QDBFHFKYðð  
BIT  
Dᑍ QDBRSV4ðð  
BIT  
Dᑍ QDBFHFLCðð  
BIT  
Dᑍ QDBFKFSOðð  
BIT  
Dᑍ QDBRSV5ðð  
BIT  
Dᑍ QDBFHSHRðð  
BIT  
Dᑍ QDBRSV6ðð  
BITS  
Dᑍ QDBFIGCDðð  
BIT  
BIT  
Dᑍ QDBFIGCLðð  
Dᑍ  
Attribute Bytes  
D QDBRSV7  
11  
15  
14  
Dᑍ  
Reserved.  
16B ð  
Number Of Data Members  
1 = Externally described  
physical file, or program  
described physical file  
that is NOT linked to a  
Data Dictionary.  
1-32 = Number of Data  
Dictionary record  
D QDBLBNUM  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
formats for a program  
described physical  
file that is linked to  
a Data Dictionary.  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
1-32 = Number of based-on  
physical files for  
Dᑍ  
Dᑍ  
a logical file.  
DᑍQDBFKDAT  
D QDBFKNUMðð  
D QDBFKMXLðð  
Dᑍ QDBFKFLGðð  
D QDBBITS28  
Dᑍ QDBRSV8ð2  
Dᑍ QDBFKFCSð2  
Dᑍ QDBRSV9ð2  
Dᑍ QDBFKFRCð2  
Dᑍ QDBFKFLTð2  
D QDBFKFDMðð  
D QDBRSV1ððð  
Dᑍ  
14  
17  
19  
18B ð  
2ðB ð  
1
21  
1
21  
BIT  
BIT  
BITS  
BIT  
BIT  
1
4
1
1
22  
23  
22  
3ð  
Keyed Sequence Access Path  
D QDBFHAUT  
Dᑍ  
31  
4ð  
Public Authority (AUT)  
'ᑍCHANGE ' = Public change  
authority.  
Dᑍ  
Dᑍ  
Dᑍ  
'ᑍALL  
' = Public all  
authority.  
' = Public use  
authority.  
Dᑍ  
Dᑍ  
'ᑍUSE  
Dᑍ  
B-156 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
'ᑍEXCLUDE ' = Public exclude  
authority.  
Dᑍ  
Dᑍ  
'authorization-list-name'  
= Name of the  
Dᑍ  
Dᑍ  
authorization  
Dᑍ  
list whose  
Dᑍ  
authority is  
Dᑍ  
used for the  
Dᑍ  
file.  
Dᑍ  
This is the original public  
authority that the file was  
created with, NOT the current  
public authority for the file.  
Dᑍ  
Dᑍ  
Dᑍ  
D QDBFHUPL  
41  
41  
Dᑍ  
Preferred Storage Unit (UNIT)  
X'ðð' = The storage space for  
the file and its  
members can be  
allocated on any  
available auxiliary  
storage unit (ᑍANY).  
X'ð1'-X'FF' = The unit  
identifier (a  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
number from 1  
to 255 assigned  
when the disk  
device is  
configured) of  
a specific  
auxiliary  
storage unit on  
the system.  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
D QDBFHMXM  
42  
43B ð  
Maximum Members (MAXMBRS)  
ð = No maximum is specified  
for the number of members,  
the system maximum of  
32,767 members is used  
(ᑍNOMAX).  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
1-32,767 = The value for the  
maximum number of  
Dᑍ  
Dᑍ  
members that the  
file can have  
Dᑍ  
Dᑍ  
(maximum-members).  
D QDBFWTFI  
44  
45B ð  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Maximum File Wait Time  
(WAITFILE)  
-1 = The default wait time  
specified in the class  
description is used as  
the wait time for the  
file (ᑍCLS).  
ð = A program does NOT wait  
for the file, an  
immediate allocation of  
the file is required  
(ᑍIMMED).  
1-32,767 = The number of  
Appendix B. Original Examples in Additional Languages B-157  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
seconds that a  
program waits for  
the file (number-  
of-seconds).  
Dᑍ  
Dᑍ  
Dᑍ  
D QDBFHFRT  
46  
47B ð  
Dᑍ  
Records To Force A Write  
(FRCRATIO)  
Dᑍ  
Dᑍ  
ð = There is NO force write  
ratio, the system  
determines when the  
records are written to  
auxiliary storage (ᑍNONE).  
1-32,767 = The number of  
inserted, updated,  
or deleted records  
that are processed  
before they are  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
explicitly forced  
to auxiliary  
storage (number-  
of-records-before-  
force).  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
D QDBHMNUM  
48  
49B ð  
Dᑍ  
Number Of Members  
ð-32,767 = The current number  
of members for the  
file.  
Dᑍ  
Dᑍ  
Dᑍ  
D QDBRSV11  
5ð  
59  
58  
Dᑍ  
Reserved.  
D QDBFBRWT  
6ðB ð  
Dᑍ  
Maximum Record Wait Time  
Dᑍ  
(WAITRCD)  
Dᑍ  
-2 = The wait time is the  
maximum allowed by the  
system, 32,767 seconds  
(ᑍNOMAX).  
-1 = A program does NOT wait  
for the record, an  
immediate allocation of  
the record is required  
(ᑍIMMED).  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
1-32,767 = The number of  
seconds that a  
Dᑍ  
Dᑍ  
program waits for  
the record  
(number-of-  
seconds).  
Dᑍ  
Dᑍ  
Dᑍ  
DᑍQDBQAAFðð  
1
61  
D QDBBITS29  
61  
7
1
Dᑍ QDBRSV12ðð  
BITS  
BIT  
Dᑍ QDBFPGMDðð  
Dᑍ  
Additional Attribute Flags  
D QDBMTNUM  
62  
63B ð  
Dᑍ  
Total Number Of Record  
Dᑍ  
Formats  
Dᑍ  
1-32 = Number of record  
formats for the file.  
Dᑍ  
DᑍQDBFHFL2  
2
B-158 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
D QDBBITS3ð  
64  
1
65  
Dᑍ QDBFJNAPðð  
BIT  
Dᑍ QDBRSV13ðð  
1
BIT  
Dᑍ QDBFRDCPðð  
1
BIT  
Dᑍ QDBFWTCPðð  
1
BIT  
Dᑍ QDBFUPCPðð  
1
BIT  
Dᑍ QDBFDLCPðð  
1
BIT  
Dᑍ QDBRSV14ðð  
9
BITS  
Dᑍ QDBFKFNDðð  
1
BIT  
Dᑍ  
Additional Attribute Flags  
D QDBFVRM  
66  
67B ð  
First Supported  
Dᑍ  
Dᑍ  
Version Release Modification  
Level  
X'ðððð' = Pre-Version 2  
Release 1  
Modification ð file.  
X'15ðð' = Version 2 Release 1  
Modification ð,  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
V2R1Mð, file.  
Dᑍ  
X'15ð1' = Version 2 Release 1  
Modification 1,  
Dᑍ  
Dᑍ  
V2R1M1, file.  
Dᑍ  
X'16ðð' = Version 2 Release 2  
Modification ð,  
Dᑍ  
Dᑍ  
V2R2Mð, file.  
Dᑍ  
New Database support is used  
in the file which will  
prevent it from being saved  
and restored to a prior  
Version Release and  
Modification level.  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
DᑍQDBQAAF2  
D QDBBITS31  
Dᑍ QDBFHMCSðð  
Dᑍ QDBRSV15ðð  
Dᑍ QDBFKNLLðð  
Dᑍ QDBFNFLDðð  
Dᑍ QDBFVFLDðð  
Dᑍ QDBFTFLDðð  
Dᑍ QDBFGRPHðð  
Dᑍ QDBRSV16ðð  
Dᑍ  
1
68  
68  
1
BIT  
1
BIT  
1
BIT  
1
BIT  
1
BIT  
1
BIT  
1
BIT  
1
BIT  
Additional Attribute Flags  
D QDBRSV17  
Dᑍ  
69  
7ð  
69  
82  
Reserved.  
D QDBFHCRT  
Dᑍ  
File Level Identifier  
The date of the file in  
internal standard format  
(ISF), CYYMMDDHHMMSS.  
Dᑍ  
Dᑍ  
Dᑍ  
DᑍQDBFHTX  
D QDBRSV18ðð  
D QDBFHTXTðð  
Dᑍ  
D QDBRSV19  
Dᑍ  
52  
84  
83  
85  
134  
File Text Description  
Reserved  
135  
147  
DᑍQDBFSRC  
D QDBFSRCFðð  
3ð  
157  
148  
Appendix B. Original Examples in Additional Languages B-159  
Download from Www.Somanuals.com. All Manuals Search And Download.  
D QDBFSRCMðð  
158  
168  
167  
177  
D QDBFSRCLðð  
Dᑍ  
Source File Fields  
D QDBFKRCV  
178  
178  
Dᑍ  
Access Path Recovery  
(RECOVER)  
'A' = The file has its access  
path built after the  
IPL has been completed  
(ᑍAFTIPL).  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
'N' = The access path of the  
file is NOT built  
Dᑍ  
Dᑍ  
during or after an IPL  
(ᑍNO). The file's  
access path is built  
when the file is next  
opened.  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
'S' = The file has its access  
path built during the  
IPL (ᑍIPL).  
Dᑍ  
Dᑍ  
D QDBRSV2ð  
179  
2ð2  
2ð1  
Dᑍ  
Reserved.  
D QDBFTCID  
2ð3B ð  
Dᑍ  
Coded Character Set  
Dᑍ  
Identifier, CCSID, For  
Text Description (TEXT)  
ð = There is NO text  
description for the file.  
1-65,535 = The CCSID for the  
file's text  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
description.  
D QDBFASP  
2ð4  
2ð5  
Dᑍ  
Auxiliary Storage Pool (ASP)  
X'ðððð' = The file is  
located on the  
system auxiliary  
storage pool.  
X'ððð2'-X'ðð1ð' = The user  
auxiliary storage  
pool the file is  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
located on  
(asp-identifier).  
Dᑍ  
D QDBRSV21  
2ð6  
2ð7  
2ð6  
Dᑍ  
Reserved.  
D QDBXFNUM  
2ð8B ð  
Dᑍ  
Maximum Number Of Fields  
Dᑍ  
1-8ððð = The number of fields  
in the file's record  
format that contains  
the largest number  
of fields.  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
D QDBRSV22  
2ð9  
285  
284  
Dᑍ  
Reserved.  
D QDBFODIC  
288B ð  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Offset from the start of the  
FDT header, Qdbfh, to the  
IDDU/SQL Data Dictionary  
Area, Qdbfdic.  
B-160 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
D QDBRSV23  
289  
3ð3  
3ð2  
Dᑍ  
Reserved.  
3ð4B ð  
File Generic Key Length  
D QDBFFIGL  
Dᑍ  
Dᑍ  
ð-2ððð = The length of the  
key before the first  
ᑍNONE key field for  
Dᑍ  
Dᑍ  
Dᑍ  
the file.  
Dᑍ  
If this file has an arrival  
sequence access path, this  
field is NOT applicable.  
Dᑍ  
Dᑍ  
D QDBFMXRL  
3ð5  
3ð6B ð  
Dᑍ  
Maximum Record Length  
1-32766 = The length of the  
record in the  
Dᑍ  
Dᑍ  
Dᑍ  
file's record  
Dᑍ  
format that  
Dᑍ  
contains the  
Dᑍ  
largest number of  
bytes.  
Dᑍ  
D QDBRSV24  
3ð7  
315  
314  
Dᑍ  
Reserved.  
D QDBFGKCT  
316B ð  
Dᑍ  
File Generic Key Field Count  
Dᑍ  
ð-12ð = The count of the  
number of key fields  
before the first  
Dᑍ  
Dᑍ  
Dᑍ  
ᑍNONE key field for  
the file.  
If this file has an arrival  
sequence access path, this  
field is NOT applicable.  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
D QDBFOS  
317  
32ðB ð  
Dᑍ  
Offset from the start of the  
FDT header, Qdbfh, to the  
File Scope Array, Qdbfb.  
Dᑍ  
Dᑍ  
D QDBRSV25  
321  
329  
328  
Dᑍ  
Reserved.  
D QDBFOCS  
332B ð  
Dᑍ  
Offset from the start of the  
Dᑍ  
FDT header, Qdbfh, to the  
Alternative Collating  
Sequence Table section,  
Qdbfacs.  
Dᑍ  
Dᑍ  
Dᑍ  
D QDBRSV26  
333  
337  
336  
338  
Dᑍ  
Reserved.  
D QDBFPACT  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Access Path Type  
'AR' = Arrival sequence  
access path.  
'KC' = Keyed sequence access  
path with duplicate  
keys allowed.  
Duplicate keys are  
accessed in first-  
changed-first-out  
(FCFO) order.  
'KF' = Keyed sequence access  
Appendix B. Original Examples in Additional Languages B-161  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
path with duplicate  
keys allowed.  
Dᑍ  
Dᑍ  
Duplicate keys are  
accessed in first-  
in-first-out  
Dᑍ  
Dᑍ  
Dᑍ  
(FIFO) order.  
Dᑍ  
'KL' = Keyed sequence access  
path with duplicate  
keys allowed.  
Dᑍ  
Dᑍ  
Dᑍ  
Duplicate keys are  
accessed in last-  
in-first-out  
Dᑍ  
Dᑍ  
Dᑍ  
(LIFO) order.  
Dᑍ  
'KN' = Keyed sequence access  
path with duplicate  
keys allowed.  
Dᑍ  
Dᑍ  
Dᑍ  
No order is guaranteed  
when accessing  
duplicate keys.  
Dᑍ  
Dᑍ  
Dᑍ  
Duplicate keys are  
accessed in one of the  
following methods:  
(FCFO) (FIFO) (LIFO).  
'KU' = Keyed sequence access  
path with NO duplicate  
keys allowed (UNIQUE).  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
D QDBFHRLS  
339  
344  
Dᑍ  
File Version Release  
Modification Level  
'VxRyMz' = Where x is the  
Version, y is the  
Release, and z is  
the Modification  
level  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
Dᑍ  
example V2R1M1  
Version 2 Release  
1 Modification 1  
Dᑍ  
Dᑍ  
D QDBRSV27  
345  
365  
364  
Dᑍ  
Reserved.  
D QDBPFOF  
368B ð  
Dᑍ  
Offset from the start of the  
Dᑍ  
FDT header, Qdbfh, to the  
Physical File Specific  
Dᑍ  
Dᑍ  
Attributes section, Qdbfphys.  
D QDBLFOF  
Dᑍ  
369  
372B ð  
Offset from the start of the  
FDT header, Qdbfh, to the  
Logical File Specific  
Dᑍ  
Dᑍ  
Dᑍ  
Attributes section, Qdbflogl.  
DᑍQDBFSSFPðð  
Dᑍ QDBFNLSBð1  
D QDBBITS58  
Dᑍ QDBFSSCSð2  
Dᑍ QDBR1ð3ð2  
D QDBFLANGð1  
D QDBFCNTYð1  
Dᑍ  
6
1
373  
3
373  
BITS  
BITS  
5
374  
377  
376  
378  
Sort Sequence Table  
D QDBFJORN  
379  
382B ð  
B-162 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍ  
Offset from the start of the  
FDT header, Qdbfh, to the  
Journal Section, Qdbfjoal.  
Dᑍ  
Dᑍ  
D QDBRSV28  
Dᑍ  
383  
4ðð  
Reserved.  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
DᑍThe FDT header ends here.  
Dᑍ  
Dᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Misc. elements  
Dᑍ  
DSPC_NAME  
DFILE_NAME  
DFMT_NAME  
DFILE_USED  
DLIB_NAME  
DSPC_SIZE  
DSPC_INIT  
DSPCPTR  
DFORMAT  
DOVERRIDES  
DSYSTEM  
DFORMAT_1  
DCHG_ATTR  
D NBR_ATTR  
D ATTR_KEY  
D DATA_SIZE  
D ATTR_DATA  
Cᑍ  
S
S
S
S
S
S
S
S
S
S
S
S
DS  
2ð  
2ð  
1ð  
2ð  
1ð  
9B ð  
1
INZ(X'ðð')  
ᑍ
8
1
1ð  
1ð  
INZ('ð')  
INZ('ᑍLCL')  
INZ('ᑍINT')  
9B ð INZ(1)  
9B ð INZ(3)  
9B ð INZ(1)  
1
INZ('1')  
Cᑍ Start of mainline  
Cᑍ  
C
ᑍENTRY  
PLIST  
PARM  
PARM  
PARM  
C
SPC_NAME  
FILE_NAME  
FMT_NAME  
C
C
Cᑍ  
C
EXSR  
EXSR  
EXSR  
INIT  
PROCES  
DONE  
C
C
Cᑍ  
Cᑍ Start of subroutines  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
PROCES  
BEGSR  
Cᑍ The template returned from QDBRTVFD is now addressable by way  
Cᑍ of SPCPTR; as an example the program will now display the  
Cᑍ access method for the file:  
Cᑍ  
C
DSPLY  
ENDSR  
QDBFPACT  
C
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
INIT  
BEGSR  
Cᑍ One time initialization code for this program  
Appendix B. Original Examples in Additional Languages B-163  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
Cᑍ Set Error Code structure to not use exceptions  
Cᑍ  
C
Cᑍ  
Z-ADD  
16  
QUSBPRV  
Cᑍ Create a User Space for QDBRTVFD  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'QUSCRTUS'  
SPC_NAME  
EXT_ATTR  
SPC_SIZE  
SPC_INIT  
SPC_AUT  
ᑍBLANKS  
1ð24  
1ð  
'ᑍCHANGE'  
'QDBRTVFD'  
'ᑍYES'  
1ð  
5ð  
1ð  
SPC_TEXT  
SPC_REPLAC  
QUSEC  
'ᑍUSER'  
SPC_DOMAIN  
1ð  
Cᑍ Check for errors on QUSCRTUS  
Cᑍ  
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
C
'QUSCRTUS'  
APIERR  
APINAM  
1ð  
C
C
Cᑍ  
Cᑍ Change the User Space so that it is extendable  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
'QUSCUSAT'  
C
LIB_NAME  
SPC_NAME  
CHG_ATTR  
QUSEC  
C
C
C
Cᑍ  
Cᑍ Check for errors on QUSCUSAT  
Cᑍ  
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
C
'QUSCUSAT'  
APIERR  
APINAM  
1ð  
C
C
Cᑍ  
Cᑍ Get a resolved pointer to the User Space  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
'QUSPTRUS'  
C
SPC_NAME  
SPCPTR  
QUSEC  
C
C
Cᑍ  
Cᑍ Check for errors on QUSPTRUS  
Cᑍ  
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
C
'QUSPTRUS'  
APIERR  
APINAM  
1ð  
C
C
Cᑍ  
Cᑍ If no errors, then call QDBRTVFD passing the address of the  
Cᑍ User Space as the receiver variable. As Data Structure  
Cᑍ QDBQ25 is defined as BASED(SPCPTR) and SPCPTR is set to the  
Cᑍ first byte of the User Space, simply passing QDBQ25 will cause  
B-164 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ QDBRTVFD to use the User Space.  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'QDBRTVFD'  
QDBQ25  
167767ð4  
SPC_SIZE  
FILE_USED  
FORMAT  
'FILDð1ðð'  
FILE_NAME  
FMT_NAME  
OVERRIDES  
SYSTEM  
FORMAT_1  
QUSEC  
Cᑍ Check for errors on QDBRTVFD  
Cᑍ  
C
C
C
C
C
QUSBAVL  
IFGT  
MOVEL  
EXSR  
END  
ð
'QDBRTVFD'  
APIERR  
APINAM  
1ð  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
APIERR  
BEGSR  
Cᑍ Log any error encountered, and exit the program  
Cᑍ  
C
C
C
C
APINAM  
QUSEI  
DSPLY  
DSPLY  
EXSR  
DONE  
ENDSR  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
C
Cᑍ  
DONE  
BEGSR  
Cᑍ Exit the program  
Cᑍ  
C
EVAL  
RETURN  
ENDSR  
ᑍINLR = '1'  
C
C
Data Queue—Examples  
This section includes the examples in “Using Data Queues versus User Queues” on  
page A-15.  
Data Queue—ILE COBOL Example  
Refer to “Data Queue—ILE C Example” on page A-16 for the original example.  
The following program also works with OPM COBOL.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍ Program Name: DQUEUEX  
ᑍ
ᑍ Programming Language: COBOL  
ᑍ
ᑍ Description: This program illustrates how to use APIs to  
Appendix B. Original Examples in Additional Languages B-165  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ
create and manipulate a ᑍDTAQ.  
ᑍ Header Files Included: QUSEC - Error Code Parameter  
ᑍ
ᑍ
QCAPCMD - Process Command API  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-ID. DQUEUEX.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
WORKING-STORAGE SECTION.  
ᑍ
ᑍ Error Code parameter include  
ᑍ
COPY QUSEC OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Process Command API Include  
ᑍ
COPY QCAPCMD OF QSYSINC-QLBLSRC.  
ᑍ
ᑍ Command strings  
ᑍ
ð1 CRTLIB PIC X(5ð) VALUE "CRTLIB QUEUELIB".  
ð1 DLTLIB PIC X(5ð) VALUE "DLTLIB QUEUELIB".  
ð1 CRTDQ PIC X(5ð)  
VALUE "CRTDTAQ QUEUELIB/EXAMPLEQ MAXLEN(1ð)".  
ð1 DLTDQ PIC X(5ð) VALUE "DLTDTAQ QUEUELIB/EXAMPLEQ".  
ᑍ
ᑍ Error message text  
ᑍ
ð1 BAD-NEWS.  
ð5 TEXT1  
PIC X(14) VALUE "Failed in API ".  
PIC X(1ð) VALUE "QCAPCMD".  
ð5 API-NAME  
ð5 TEXT2  
ð5 EXCEPTION-ID PIC X(ð7).  
PIC X(11) VALUE "with error ".  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 COMMAND-LENGTH PIC S9(ð9) VALUE 5ð BINARY.  
ð1 RECEIVER  
PIC X(ð1).  
ð1 RECEIVER-LENGTH PIC S9(ð9) VALUE ð BINARY.  
ð1 OPTIONS-SIZE  
ð1 FORMAT-NAME  
ð1 FIRST-ERROR  
PIC S9(ð9) VALUE 2ð BINARY.  
PIC X(ð8) VALUE "CPOPð1ðð".  
PIC X(ð1) VALUE "ð".  
ð1 NAME-OF-QUEUE PIC X(1ð) VALUE "EXAMPLEQ".  
B-166 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ð1 NAME-OF-LIBRARY PIC X(1ð) VALUE "QUEUELIB".  
ð1 SIZE-OF-MSG  
ð1 WAIT-TIME  
ð1 MSG  
PIC S9(ð5) VALUE 1ð PACKED-DECIMAL.  
PIC S9(ð5) VALUE ð PACKED-DECIMAL.  
PIC X(1ð) VALUE "EXAMPLE".  
PIC X(1ð).  
ð1 MSG-BACK  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
ᑍ
ᑍ Initialize the error code parameter. To signal exceptions to  
ᑍ this program by the API, you need to set the bytes provided  
ᑍ field of the error code to zero. Because this program has  
ᑍ exceptions sent back through the error code parameter, it sets  
ᑍ the bytes provided field to the number of bytes it gives the  
ᑍ API for the parameter.  
ᑍ
MOVE 16 TO BYTES-PROVIDED.  
ᑍ
ᑍ Initialize QCAPCMD options control block for CL processing  
ᑍ
MOVE ð TO COMMAND-PROCESS-TYPE.  
MOVE "ð" TO DBCS-DATA-HANDLING.  
MOVE "ð" TO PROMPTER-ACTION.  
MOVE "ð" TO COMMAND-STRING-SYNTAX.  
MOVE SPACES TO MESSAGE-KEY.  
MOVE LOW-VALUES TO RESERVED OF QCA-PCMD-CPOPð1ðð.  
ᑍ
ᑍ Create library QUEUELIB  
ᑍ
CALL QCAPCMD USING CRTLIB, COMMAND-LENGTH, QCA-PCMD-CPOPð1ðð,  
OPTIONS-SIZE, FORMAT-NAME, RECEIVER,  
RECEIVER-LENGTH, RECEIVER-LENGTH, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
ᑍ
IF BYTES-AVAILABLE > ð PERFORM ERROR-FOUND.  
ᑍ
ᑍ Create a data queue called EXAMPLEQ in library QUEUELIB. The  
ᑍ queue will have a maximum entry length set at 1ð, and will be  
ᑍ FIFO (first-in first-out).  
ᑍ
CALL QCAPCMD USING CRTDQ, COMMAND-LENGTH, QCA-PCMD-CPOPð1ðð,  
OPTIONS-SIZE, FORMAT-NAME, RECEIVER,  
RECEIVER-LENGTH, RECEIVER-LENGTH, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
ᑍ
IF BYTES-AVAILABLE > ð PERFORM ERROR-FOUND.  
Appendix B. Original Examples in Additional Languages B-167  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ Send information to the data queue.  
ᑍ
CALL "QSNDDTAQ" USING NAME-OF-QUEUE, NAME-OF-LIBRARY,  
SIZE-OF-MSG, MSG.  
ᑍ
ᑍ Retrieve information from the data queue.  
ᑍ
CALL "QRCVDTAQ" USING NAME-OF-QUEUE, NAME-OF-LIBRARY,  
SIZE-OF-MSG, MSG-BACK, WAIT-TIME.  
ᑍ
ᑍ Display the returned message  
ᑍ
DISPLAY MSG-BACK.  
ᑍ
ᑍ Delete the data queue  
ᑍ
CALL QCAPCMD USING DLTDQ, COMMAND-LENGTH, QCA-PCMD-CPOPð1ðð,  
OPTIONS-SIZE, FORMAT-NAME, RECEIVER,  
RECEIVER-LENGTH, RECEIVER-LENGTH, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
ᑍ
IF BYTES-AVAILABLE > ð PERFORM ERROR-FOUND.  
ᑍ
ᑍ Delete the library  
ᑍ
CALL QCAPCMD USING DLTLIB, COMMAND-LENGTH, QCA-PCMD-CPOPð1ðð,  
OPTIONS-SIZE, FORMAT-NAME, RECEIVER,  
RECEIVER-LENGTH, RECEIVER-LENGTH, QUS-EC.  
ᑍ
ᑍ If an exception occurs, the API returns the exception in the  
ᑍ error code parameter. The bytes available field is set to  
ᑍ zero if no exception occurs and greater than zero if an  
ᑍ exception does occur.  
ᑍ
ᑍ
IF BYTES-AVAILABLE > ð PERFORM ERROR-FOUND.  
ᑍ
STOP RUN.  
ᑍ
ᑍ End of MAINLINE  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ERROR-FOUND.  
ᑍ
ᑍ Process errors returned from the API.  
ᑍ
ᑍ If first error found, then open QPRINT ᑍPRTF  
ᑍ
IF FIRST-ERROR = "ð" OPEN OUTPUT LISTING,  
MOVE "1" TO FIRST-ERROR.  
ᑍ
B-168 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ Print the error and the API that received the error  
ᑍ
MOVE EXCEPTION-ID OF QUS-EC TO EXCEPTION-ID OF BAD-NEWS.  
WRITE LIST-LINE FROM BAD-NEWS.  
Data Queue—OPM RPG Example  
Refer to “Data Queue—ILE C Example” on page A-16 for the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program Name: DQUEUEX  
Fᑍ  
Fᑍ Programming Language: OPM RPG  
Fᑍ  
Fᑍ Description: This program illustrates how to use APIs to  
Fᑍ  
Fᑍ  
create and manipulate a ᑍDTAQ.  
Fᑍ Header Files Included: QUSEC - Error Code Parameter  
Fᑍ  
Fᑍ  
QCAPCMD - Process Command API  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQPRINT O F  
132  
PRINTER  
UC  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Iᑍ  
Iᑍ Error Code parameter include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QUSEC  
Iᑍ  
Iᑍ Process Command API Include  
Iᑍ  
I/COPY QSYSINC/QRPGSRC,QCAPCMD  
Iᑍ  
Iᑍ Command strings  
Iᑍ  
I
DS  
I I  
I I  
I I  
I
'CRTLIB LIB(QUEUELIB)'  
1 2ð CRTLIB  
'DLTLIB LIB(QUEUELIB)' 21 4ð DLTLIB  
'CRTDTAQ DTAQ(QUEUELI- 41 82 CRTDQ  
'B/EXAMPLEQ) MAXLEN(1-  
I
'ð)'  
I I  
I
Iᑍ  
'DLTDTAQ DTAQ(QUEUELI- 83 113 DLTDQ  
'B/EXAMPLEQ)'  
Iᑍ Miscellaneous data structure  
Iᑍ  
I
DS  
I
1 1ðð CMDSTR  
B 1ð1 1ð4ðLENSTR  
B 1ð5 1ð8ðSIZE  
B 1ð9ð112ðRCVSIZ  
113 113 FSTERR  
114 123 APINAM  
I
I I  
I I  
I I  
I
2ð  
ð
'ð'  
Cᑍ  
Cᑍ Beginning of mainline  
Cᑍ  
Appendix B. Original Examples in Additional Languages B-169  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ Initialize the error code parameter. To signal exceptions to  
Cᑍ this program by the API, you need to set the bytes provided  
Cᑍ field of the error code to zero. Because this program has  
Cᑍ exceptions sent back through the error code parameter, it sets  
Cᑍ the bytes provided field to the number of bytes it gives the  
Cᑍ API for the parameter.  
Cᑍ  
C
Z-ADD16  
QUSBNB  
Cᑍ  
Cᑍ Initialize QCAPCMD options control block for CL processing  
Cᑍ  
C
Z-ADDð  
QCABCB  
QCABCC  
QCABCD  
QCABCF  
C
MOVE 'ð'  
MOVE 'ð'  
MOVE 'ð'  
C
C
C
MOVE ᑍBLANKS QCABCG  
MOVE ᑍLOVAL  
C
QCABCH  
Cᑍ  
Cᑍ Create library QUEUELIB  
Cᑍ  
C
MOVELCRTLIB  
CMDSTR  
LENSTR  
C
Z-ADD2ð  
Cᑍ  
C
Cᑍ  
EXSR EXCCMD  
Cᑍ Create a data queue called EXAMPLEQ in library QUEUELIB. The  
Cᑍ queue will have a maximum entry length set at 1ð, and will be  
Cᑍ FIFO (first-in first-out).  
Cᑍ  
C
MOVELCRTDQ  
Z-ADD42  
CMDSTR  
LENSTR  
C
Cᑍ  
C
Cᑍ  
EXSR EXCCMD  
Cᑍ Send information to the data queue.  
Cᑍ  
C
CALL 'QSNDDTAQ'  
PARM 'EXAMPLEQ'QUENAM 1ð  
PARM 'QUEUELIB'LIBNAM 1ð  
PARM 1ð  
PARM 'EXAMPLE' MSG  
C
C
C
MSGSZ 5ð  
1ð  
C
Cᑍ  
Cᑍ Retrieve information from the data queue.  
Cᑍ  
C
CALL 'QRCVDTAQ'  
PARM 'EXAMPLEQ'QUENAM 1ð  
PARM 'QUEUELIB'LIBNAM 1ð  
PARM 1ð  
PARM  
PARM ð  
C
C
C
MSGSZ 5ð  
MSGBCK 1ð  
WAITTM 5ð  
C
C
Cᑍ  
Cᑍ Display the returned message  
Cᑍ  
C
DSPLY  
MSGBCK  
CMDSTR  
Cᑍ  
Cᑍ Delete the data queue  
Cᑍ  
C
MOVELDLTDQ  
B-170 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
Z-ADD31  
LENSTR  
Cᑍ  
C
Cᑍ  
EXSR EXCCMD  
Cᑍ Delete the library  
Cᑍ  
C
C
MOVELDLTLIB  
Z-ADD2ð  
CMDSTR  
LENSTR  
Cᑍ  
C
EXSR EXCCMD  
Cᑍ  
C
C
SETON  
RETRN  
LR  
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
EXCCMD  
BEGSR  
Cᑍ Process requested CL command  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL 'QCAPCMD'  
PARM  
PARM  
PARM  
PARM  
CMDSTR  
LENSTR  
QCABC  
SIZE  
PARM 'CPOPð1ðð'FORMAT 8  
PARM  
PARM ð  
PARM  
PARM  
RCVVAR 1  
RCVSIZ  
RCVSIZ  
QUSBN  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
QUSBNC  
IFGT ð  
C
MOVEL'QCAPCMD' APINAM  
EXSR ERRCOD  
ENDIF  
C
C
C
ENDSR  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
ERRCOD  
BEGSR  
Cᑍ Process errors returned from the API.  
Cᑍ  
Cᑍ If first error found, then open QPRINT ᑍPRTF  
Cᑍ  
C
FSTERR  
IFEQ 'ð'  
OPEN QPRINT  
MOVEL'1'  
ENDIF  
C
C
FSTERR  
C
Cᑍ  
Cᑍ Print the error and the API that received the error  
Appendix B. Original Examples in Additional Languages B-171  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
C
EXCPTBADNEW  
Cᑍ  
C
ENDSR  
OQPRINT E 1ð6  
BADNEW  
O
O
O
O
'Failed in API '  
'with error '  
APINAM  
QUSBND  
Data Queue—ILE RPG Example  
Refer to “Data Queue—ILE C Example” on page A-16 for the original example.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Program Name: DQUEUEX  
Fᑍ  
Fᑍ Programming Language: ILE RPG  
Fᑍ  
Fᑍ Description: This program illustrates how to use APIs to  
Fᑍ  
Fᑍ  
create and manipulate a ᑍDTAQ.  
Fᑍ Header Files Included: QUSEC - Error Code Parameter  
Fᑍ  
Fᑍ  
QCAPCMD - Process Command API  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
FQPRINT  
O
F 132  
PRINTER OFLIND(ᑍINOF) USROPN  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Dᑍ  
Dᑍ Error Code parameter include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QUSEC  
Dᑍ  
Dᑍ Process Command API Include  
Dᑍ  
D/COPY QSYSINC/QRPGLESRC,QCAPCMD  
Dᑍ  
Dᑍ Command strings  
Dᑍ  
D
DCRTLIB  
DDLTLIB  
DCRTDQ  
D
C
C
C
'CRTLIB LIB(QUEUELIB)'  
'DLTLIB LIB(QUEUELIB)'  
'CRTDTAQ DTAQ(QUEUELIB/+  
EXAMPLEQ) MAXLEN(1ð)'  
'DLTDTAQ DTAQ(QUEUELIB/EXAMPLEQ)'  
DDLTDQ  
Dᑍ  
C
Dᑍ Miscellaneous data structure  
Dᑍ  
DCMD_STR  
DLEN_STR  
DCAPð1ðð_SZ  
DRCVVAR_SZ  
DAPI_NAME  
DFIRST_ERR  
Cᑍ  
S
S
S
S
S
S
1ðð  
9B ð  
9B ð INZ(%SIZE(QCAPð1ðð))  
9B ð INZ(ð)  
1ð  
1
INZ('ð')  
B-172 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ Beginning of mainline  
Cᑍ  
Cᑍ Initialize the error code parameter. To signal exceptions to  
Cᑍ this program by the API, you need to set the bytes provided  
Cᑍ field of the error code to zero. Because this program has  
Cᑍ exceptions sent back through the error code parameter, it sets  
Cᑍ the bytes provided field to the number of bytes it gives the  
Cᑍ API for the parameter.  
Cᑍ  
C
EVAL  
QUSBPRV = %SIZE(QUSEC)  
Cᑍ  
Cᑍ Initialize QCAPCMD options control block for CL processing  
Cᑍ  
C
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
EVAL  
QCACMDPT = ð  
QCABCSDH = 'ð'  
QCAPA = 'ð'  
QCACMDSS = 'ð'  
QCAMK = ᑍBLANKS  
QCAERVED = ᑍLOVAL  
C
C
C
C
C
Cᑍ  
Cᑍ Create library QUEUELIB  
Cᑍ  
C
EVAL  
EVAL  
CMD_STR = CRTLIB  
LEN_STR = %SIZE(CRTLIB)  
C
Cᑍ  
C
Cᑍ  
EXSR  
EXEC_CMD  
Cᑍ Create a data queue called EXAMPLEQ in library QUEUELIB. The  
Cᑍ queue will have a maximum entry length set at 1ð, and will be  
Cᑍ FIFO (first-in first-out).  
Cᑍ  
C
EVAL  
EVAL  
CMD_STR = CRTDQ  
LEN_STR = %SIZE(CRTDQ)  
C
Cᑍ  
C
Cᑍ  
EXSR  
EXEC_CMD  
Cᑍ Send information to the data queue.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
'QSNDDTAQ'  
C
'EXAMPLEQ ' NAME_OF_Q  
'QUEUELIB ' NAME_OF_LB  
1ð  
1ð  
C
C
1ð  
MSG_SZ  
5 ð  
C
'EXAMPLE ' MSG  
1ð  
Cᑍ  
Cᑍ Retrieve information from the data queue.  
Cᑍ  
C
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
'QRCVDTAQ'  
C
'EXAMPLEQ ' NAME_OF_Q  
'QUEUELIB ' NAME_OF_LB  
C
C
1ð  
MSG_SZ  
MSG_BACK  
WAIT_TIME  
C
1ð  
5 ð  
C
ð
Cᑍ  
Cᑍ Display the returned message  
Cᑍ  
C
DSPLY  
MSG_BACK  
Cᑍ  
Cᑍ Delete the data queue  
Appendix B. Original Examples in Additional Languages B-173  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
C
C
EVAL  
EVAL  
CMD_STR = DLTDQ  
LEN_STR = %SIZE(DLTDQ)  
Cᑍ  
C
Cᑍ  
EXSR  
EXEC_CMD  
Cᑍ Delete the library  
Cᑍ  
C
EVAL  
CMD_STR = DLTLIB  
C
EVAL  
LEN_STR = %SIZE(DLTLIB)  
Cᑍ  
C
Cᑍ  
C
C
EXSR  
EXEC_CMD  
EVAL  
ᑍINLR = '1'  
RETURN  
Cᑍ  
Cᑍ End of MAINLINE  
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
EXEC_CMD  
BEGSR  
Cᑍ Process the requested CL command  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
Cᑍ  
CALL  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
PARM  
'QCAPCMD'  
CMD_STR  
LEN_STR  
QCAPð1ðð  
CAPð1ðð_SZ  
FORMAT  
'CPOPð1ðð'  
ð
8
1
RCVVAR  
RCVVAR_SZ  
RCVVAR_SZ  
QUSEC  
Cᑍ If an exception occurs, the API returns the exception in the  
Cᑍ error code parameter. The bytes available field is set to  
Cᑍ zero if no exception occurs and greater than zero if an  
Cᑍ exception does occur.  
Cᑍ  
C
IF  
QUSBAVL > ð  
API_NAME = 'QCAPCMD'  
ERRCOD  
C
EVAL  
EXSR  
ENDIF  
ENDSR  
C
C
C
Cᑍ  
Cᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Cᑍ  
C
Cᑍ  
ERRCOD  
BEGSR  
Cᑍ Process errors returned from the API.  
Cᑍ  
Cᑍ If first error found, then open QPRINT ᑍPRTF  
Cᑍ  
C
C
C
C
IF  
FIRST_ERR = 'ð'  
QPRINT  
OPEN  
EVAL  
ENDIF  
FIRST_ERR = '1'  
B-174 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
Cᑍ Print the error and the API that received the error  
Cᑍ  
C
EXCEPT  
BAD_NEWS  
Cᑍ  
C
ENDSR  
OQPRINT  
E
BAD_NEWS  
1
O
O
O
O
'Failed in API '  
'with error '  
API_NAME  
QUSEI  
UNIX-Type APIs—Examples  
The simple example program on the following pages illustrates the use of several  
integrated file system functions. The program performs the following operations:  
.1/ Uses the getuid() function to determine the real user ID (uid).  
.2/ Uses the getcwd() function to determine the current directory.  
.3/ Uses the open() function to create a file. The owner (the person who created  
the file) is given read, write, and execute authority to the file.  
.4/ Uses the write() function to write a byte string to the file. The file is identified  
by the file descriptor that was provided in the open operation (.3/).  
.5/ Uses the close() function to close the file.  
.6/ Uses the open() function to open the file for read only.  
.7/ Uses the read() function to read a byte string from the file. The file is identi-  
fied by the file descriptor that was provided in the open operation (.6/).  
.8/ Uses the close() function to close the file.  
.9/ Uses the unlink() function to remove the link to the file.  
Using the Integrated File System—ILE C Example  
This example program uses the integrated file system from ILE C.  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
/ᑍ  
ᑍ/  
ᑍ/  
ᑍ/  
/ᑍ Language:  
ILE C  
/ᑍ  
/ᑍ Description:  
Demonstrate use of integrated file system ᑍ/  
from ILE C  
/ᑍ  
/ᑍ  
ᑍ/  
ᑍ/  
/ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ/  
#include <stdlib.h>  
#include <stdio.h>  
#include <fcntl.h>  
#include <unistd.h>  
#include <sys/types.h>  
#define BUFFER_SIZE  
#define TEST_FILE  
2ð48  
"test.file"  
Appendix B. Original Examples in Additional Languages B-175  
Download from Www.Somanuals.com. All Manuals Search And Download.  
#define TEST_DATA  
#define USER_ID  
"Hello World!"  
"user_id_"  
char InitialFile[BUFFER_SIZE];  
char InitialDirectory[BUFFER_SIZE] = ".";  
char Buffer[32];  
int FilDes = -1;  
int BytesRead;  
int BytesWritten;  
uid_t UserID;  
void CleanUpOnError(int level)  
{
printf("Error encountered, cleaning up.\n");  
switch ( level )  
{
case 1:  
printf("Could not get current working directory.\n");  
break;  
case 2:  
printf("Could not create file %s.\n",TEST_FILE);  
break;  
case 3:  
printf("Could not write to file %s.\n",TEST_FILE);  
close(FilDes);  
unlink(TEST_FILE);  
break;  
case 4:  
printf("Could not close file %s.\n",TEST_FILE);  
close(FilDes);  
unlink(TEST_FILE);  
break;  
case 5:  
printf("Could not open file %s.\n",TEST_FILE);  
unlink(TEST_FILE);  
break;  
case 6:  
printf("Could not read file %s.\n",TEST_FILE);  
close(FilDes);  
unlink(TEST_FILE);  
break;  
case 7:  
printf("Could not close file %s.\n",TEST_FILE);  
close(FilDes);  
unlink(TEST_FILE);  
break;  
case 8:  
printf("Could not unlink file %s.\n",TEST_FILE);  
unlink(TEST_FILE);  
break;  
default:  
break;  
}
printf("Program ended with Error.\n"\  
"All test files and directories may not have been removed.\n");  
}
B-176 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
int main ()  
{
.1/  
/ᑍ Get and print the real user id with the getuid() function. ᑍ/  
UserID = getuid();  
printf("The real user id is %u. \n",UserID);  
.2/  
/ᑍ Get the current working directory and store it in InitialDirectory. ᑍ/  
if ( NULL == getcwd(InitialDirectory,BUFFER_SIZE) )  
{
perror("getcwd Error");  
CleanUpOnError(1);  
return ð;  
}
printf("The current working directory is %s. \n",InitialDirectory);  
.3/  
/ᑍ Create the file TEST_FILE for writing, if it does not exist.  
Give the owner authority to read, write, and execute. ᑍ/  
FilDes = open(TEST_FILE, O_WRONLY | O_CREAT | O_EXCL, S_IRWXU);  
if ( -1 == FilDes )  
{
perror("open Error");  
CleanUpOnError(2);  
return ð;  
}
printf("Created %s in directory %s.\n",TEST_FILE,InitialDirectory);  
.4/  
/ᑍ Write TEST_DATA to TEST_FILE via FilDes ᑍ/  
BytesWritten = write(FilDes,TEST_DATA,strlen(TEST_DATA));  
if ( -1 == BytesWritten )  
{
perror("write Error");  
CleanUpOnError(3);  
return ð;  
}
printf("Wrote %s to file %s.\n",TEST_DATA,TEST_FILE);  
.5/  
/ᑍ Close TEST_FILE via FilDes ᑍ/  
if ( -1 == close(FilDes) )  
{
perror("close Error");  
CleanUpOnError(4);  
return ð;  
}
FilDes = -1;  
printf("File %s closed.\n",TEST_FILE);  
.6/  
/ᑍ Open the TEST_FILE file for reading only. ᑍ/  
if ( -1 == (FilDes = open(TEST_FILE,O_RDONLY)) )  
{
Appendix B. Original Examples in Additional Languages B-177  
Download from Www.Somanuals.com. All Manuals Search And Download.  
perror("open Error");  
CleanUpOnError(5);  
return ð;  
}
printf("Opened %s for reading.\n",TEST_FILE);  
.7/  
/ᑍ Read from the TEST_FILE file, via FilDes, into Buffer. ᑍ/  
BytesRead = read(FilDes,Buffer,sizeof(Buffer));  
if ( -1 == BytesRead )  
{
perror("read Error");  
CleanUpOnError(6);  
return ð;  
}
printf("Read %s from %s.\n",Buffer,TEST_FILE);  
if ( BytesRead != BytesWritten )  
{
printf("WARNING: the number of bytes read is "\  
"not equal to the number of bytes written.\n");  
}
.8/  
/ᑍ Close the TEST_FILE file via FilDes. ᑍ/  
if ( -1 == close(FilDes) )  
{
perror("close Error");  
CleanUpOnError(7);  
return ð;  
}
FilDes = -1;  
printf("Closed %s.\n",TEST_FILE);  
.9/  
/ᑍ Unlink the file TEST_FILE ᑍ/  
if ( -1 == unlink(TEST_FILE) )  
{
perror("unlink Error");  
CleanUpOnError(8);  
return ð;  
}
printf("Unlinking file %s.\n",TEST_FILE);  
printf("Program completed successfully.\n");  
return ð;  
}
Using the Integrated File System—ILE COBOL Example  
This example program uses the integrated file system from ILE COBOL.  
PROCESS NOMONOPRC.  
IDENTIFICATION DIVISION.  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
B-178 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ Language:  
ᑍ
COBOL  
ᑍ Description: Demonstrate use of integrated file system  
ᑍ
ᑍ
from ILE COBOL  
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
ᑍ
ᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
PROGRAM-ID. IFS.  
ENVIRONMENT DIVISION.  
CONFIGURATION SECTION.  
SOURCE-COMPUTER. IBM-AS4ðð.  
OBJECT-COMPUTER. IBM-AS4ðð.  
SPECIAL-NAMES.  
ᑍ LINKAGE TYPE PROCEDURE FOR "geterrno",  
LINKAGE TYPE PROCEDURE FOR "getuid",  
LINKAGE TYPE PROCEDURE FOR "getcwd",  
LINKAGE TYPE PROCEDURE FOR "open",  
LINKAGE TYPE PROCEDURE FOR "write",  
LINKAGE TYPE PROCEDURE FOR "close",  
LINKAGE TYPE PROCEDURE FOR "read",  
LINKAGE TYPE PROCEDURE FOR "unlink".  
INPUT-OUTPUT SECTION.  
FILE-CONTROL.  
SELECT LISTING ASSIGN TO PRINTER-QPRINT  
ORGANIZATION IS SEQUENTIAL.  
DATA DIVISION.  
ᑍ
FILE SECTION.  
FD LISTING RECORD CONTAINS 132 CHARACTERS  
LABEL RECORDS ARE STANDARD  
DATA RECORD IS LIST-LINE.  
ð1 LIST-LINE  
PIC X(132).  
ᑍ
ᑍ
WORKING-STORAGE SECTION.  
ᑍ Report lines  
ᑍ
ð1 REALID.  
ð5 PRT-TEXT  
PIC X(2ð) VALUE "The real user id is ".  
PIC X(12).  
ð5 USER  
ð1 CURDIR.  
ð5 PRT-TEXT  
ð5 INITIALDIR  
ð1 NEWFIL.  
ð5 PRT-TEXT  
ð5 FILENAME  
ð1 DATAIN.  
PIC X(21) VALUE "Current directory is ".  
PIC X(1ðð).  
PIC X(2ð) VALUE "Created file:  
PIC X(1ðð).  
".  
ð5 PRT-TEXT  
ð5 DATA-READ  
PIC X(2ð) VALUE "Successfully read: ".  
PIC X(1ðð).  
ð1 ERRLIN.  
ð5 PRT-TEXT  
ð5 ERRVAL  
PIC X(2ð) VALUE "The errno value is: ".  
PIC X(12).  
ᑍ
ᑍ Miscellaneous elements  
ᑍ
ð1 BUFFER  
ð1 LENGTH-OF-BUFFER  
PIC X(32767).  
PIC S9(ð9) BINARY VALUE 32767.  
Appendix B. Original Examples in Additional Languages B-179  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ð1 TESTFILE.  
ð5 TEST-FILE  
ð5 NULL-TERMINATE PIC X(ð1) VALUE LOW-VALUE.  
PIC X(ð9) VALUE "test.file".  
ð1 OFLAG  
PIC X(ð4) VALUE X"ðððððð1A".  
PIC X(ð4) VALUE X"ððððððð1".  
PIC X(ð4) VALUE X"ððððð1Cð".  
PIC X(12) VALUE "Hello World!".  
PIC S9(ð9) BINARY VALUE 12.  
PIC S9(ð9) BINARY.  
ð1 OFLAG-READ  
ð1 OMODE  
ð1 TEST-DATA  
ð1 SIZE-TEST-DATA  
ð1 FILE-DESCRIPTOR  
ð1 BYTES-READ  
ð1 BYTES-WRITTEN  
ð1 RETURN-INT  
ð1 RETURN-PTR  
PIC S9(ð9) BINARY.  
PIC S9(ð9) BINARY.  
PIC S9(ð9) BINARY.  
POINTER.  
ᑍ
ᑍ Beginning of mainline  
ᑍ
PROCEDURE DIVISION.  
MAIN-LINE.  
OPEN OUTPUT LISTING.  
ᑍ
ᑍ Get and print the real user id with the getuid function.  
ᑍ
CALL "getuid" GIVING RETURN-INT.  
ᑍ
ᑍ Check for error and report status.  
ᑍ
IF RETURN-INT = -1 MOVE "Error getting real user id"  
TO LIST-LINE,  
PERFORM ERROR-FOUND,  
ELSE  
MOVE RETURN-INT TO USER,  
WRITE LIST-LINE FROM REALID.  
ᑍ
ᑍ Get the current working directory and store it in BUFFER  
ᑍ
CALL "getcwd" USING BY VALUE ADDRESS OF BUFFER,  
BY VALUE LENGTH-OF-BUFFER,  
GIVING RETURN-PTR.  
ᑍ
ᑍ Check for error and report status.  
ᑍ
IF RETURN-PTR = NULL MOVE "Error getting real current dir"  
TO LIST-LINE,  
PERFORM ERROR-FOUND,  
MOVE BUFFER TO INITIALDIR,  
WRITE LIST-LINE FROM CURDIR.  
ELSE  
ᑍ
ᑍ Create the file test.file for writing. If it does not exist,  
ᑍ give the owner authority to read, write, and execute.  
ᑍ
CALL "open" USING BY VALUE ADDRESS OF TESTFILE,  
BY VALUE OFLAG,  
BY VALUE OMODE,  
GIVING FILE-DESCRIPTOR.  
ᑍ
ᑍ Check for error and report status.  
ᑍ
IF FILE-DESCRIPTOR = -1 MOVE "Could not create file"  
TO LIST-LINE,  
B-180 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
PERFORM ERROR-FOUND,  
MOVE TEST-FILE TO FILENAME,  
WRITE LIST-LINE FROM NEWFIL.  
ELSE  
ᑍ
ᑍ Write TEST-DATA to test.file via file descriptor from open  
ᑍ
CALL "write" USING BY VALUE FILE-DESCRIPTOR,  
BY VALUE ADDRESS OF TEST-DATA,  
BY VALUE SIZE-TEST-DATA,  
GIVING BYTES-WRITTEN.  
ᑍ
ᑍ Check for error and report status.  
ᑍ
IF BYTES-WRITTEN = -1 MOVE "Could not write to file"  
TO LIST-LINE,  
PERFORM ERROR-FOUND,  
ELSE  
MOVE "Wrote to file successfully"  
TO LIST-LINE,  
WRITE LIST-LINE.  
ᑍ
ᑍ Close test.file via file descriptor  
ᑍ
CALL "close" USING BY VALUE FILE-DESCRIPTOR,  
GIVING RETURN-INT.  
ᑍ
ᑍ Check for error and report status.  
ᑍ
IF RETURN-INT  
= -1 MOVE "Could not close file"  
TO LIST-LINE,  
PERFORM ERROR-FOUND,  
MOVE "Successfully closed file"  
TO LIST-LINE,  
ELSE  
WRITE LIST-LINE.  
ᑍ
ᑍ Open the file test.file for reading.  
ᑍ
CALL "open" USING BY VALUE ADDRESS OF TESTFILE,  
BY VALUE OFLAG-READ,  
GIVING FILE-DESCRIPTOR.  
ᑍ
ᑍ Check for error and report status.  
ᑍ
IF FILE-DESCRIPTOR = -1 MOVE "Could not open file"  
TO LIST-LINE,  
PERFORM ERROR-FOUND,  
ELSE  
MOVE "File open successful"  
TO LIST-LINE,  
WRITE LIST-LINE.  
ᑍ
ᑍ Read from test.file via file descriptor from open  
ᑍ
CALL "read" USING BY VALUE FILE-DESCRIPTOR,  
BY VALUE ADDRESS OF BUFFER,  
BY VALUE LENGTH-OF-BUFFER,  
GIVING BYTES-READ.  
ᑍ
ᑍ Check for error and report status.  
ᑍ
Appendix B. Original Examples in Additional Languages B-181  
Download from Www.Somanuals.com. All Manuals Search And Download.  
IF BYTES-READ = -1 MOVE "Read failed"  
TO LIST-LINE,  
PERFORM ERROR-FOUND,  
ELSE IF BYTES-READ = BYTES-WRITTEN  
MOVE BUFFER TO DATA-READ,  
WRITE LIST-LINE FROM DATAIN,  
ELSE MOVE "Data Truncation on Read"  
TO LIST-LINE,  
PERFORM ERROR-FOUND.  
ᑍ
ᑍ Close test.file via file descriptor  
ᑍ
CALL "close" USING BY VALUE FILE-DESCRIPTOR,  
GIVING RETURN-INT.  
ᑍ
ᑍ Check for error and report status.  
ᑍ
IF RETURN-INT  
= -1 MOVE "Could not close file"  
TO LIST-LINE,  
PERFORM ERROR-FOUND,  
MOVE "Successfully closed file"  
TO LIST-LINE,  
ELSE  
WRITE LIST-LINE.  
ᑍ
ᑍ Unlink test.file  
ᑍ
CALL "unlink" USING BY VALUE ADDRESS OF TESTFILE,  
GIVING RETURN-INT.  
ᑍ
ᑍ Check for error and report status.  
ᑍ
IF RETURN-INT  
= -1 MOVE "Unlink of file failed"  
TO LIST-LINE,  
PERFORM ERROR-FOUND,  
MOVE "Unlink of file successful"  
TO LIST-LINE,  
ELSE  
WRITE LIST-LINE.  
ᑍ
ᑍ
MOVE "Program run is successful" TO LIST-LINE.  
WRITE LIST-LINE.  
STOP RUN.  
ᑍ End of MAINLINE  
ᑍ
ᑍ
ᑍ Common error reporting subroutine  
ᑍ
ᑍ If errors occur, the Integrated File System exports the  
ᑍ variable 'errno' to assist in determining the problem. As  
ᑍ 'errno' is lowercase, ILE COBOL cannot directly import this  
ᑍ variable and must use a C module to access it. If the  
ᑍ developer has ILE C available, the following sample C code  
ᑍ will import 'errno' and make it available to the COBOL  
ᑍ application  
ᑍ
ᑍ
ᑍ
ᑍ
#include <errno.h>  
int geterrno()  
{
B-182 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
ᑍ
ᑍ
ᑍ
return errno;  
}
ᑍ To activate this C module remove the comment identifiers  
ᑍ following the WRITE statement and remove the comment  
ᑍ identifier from the geterrno declaration in the Configuration  
ᑍ Section. Definitions for the returned errno are found in  
ᑍ file QSYSINC/SYS member ERRNO.  
ᑍ
ERROR-FOUND.  
WRITE LIST-LINE.  
ᑍ
ᑍ
ᑍ
CALL "geterrno" GIVING RETURN-INT.  
MOVE RETURN-INT TO ERRVAL.  
WRITE LIST-LINE FROM ERRLIN.  
STOP RUN.  
Using the Integrated File System—ILE RPG Example  
This example program uses the integrated file system from ILE RPG.  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
Fᑍ  
Fᑍ Language:  
Fᑍ  
ILE RPG  
Fᑍ Description: Demonstrate use of integrated file system  
Fᑍ  
Fᑍ  
from ILE RPG  
Fᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍᑍ  
FQSYSPRT O  
Dᑍ  
F 132  
PRINTER  
Dᑍ Prototype the Integrated File System APIs  
Dᑍ  
Dgetuid  
PR  
PR  
9B ð EXTPROC('getuid')  
ᑍ EXTPROC('getcwd')  
ᑍ VALUE  
Dgetcwd  
D
D
9B ð VALUE  
Dopen  
PR  
PR  
9B ð EXTPROC('open')  
ᑍ VALUE  
4A VALUE  
4A VALUE  
9B ð EXTPROC('write')  
9B ð VALUE  
ᑍ VALUE  
9B ð VALUE  
9B ð EXTPROC('close')  
9B ð VALUE  
9B ð EXTPROC('open')  
ᑍ VALUE  
4A VALUE  
9B ð EXTPROC('read')  
9B ð VALUE  
ᑍ VALUE  
9B ð VALUE  
D
D
D
Dwrite  
D
D
D
Dclose  
PR  
PR  
D
Dopen2  
D
D
Dread  
PR  
PR  
D
D
D
Dunlink  
9B ð EXTPROC('unlink')  
ᑍ VALUE  
D
Dᑍ  
Dᑍ errno prototype; see error subroutine for further information  
Dᑍ  
Appendix B. Original Examples in Additional Languages B-183  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Dᑍerrno  
PR  
S
S
S
S
S
S
S
S
S
S
S
S
C
9B ð EXTPROC('geterrno')  
12A  
32767A  
ᑍ
DUser  
DBuffer  
DReturnPtr  
DReturnInt  
DFileDesc  
Dtest_file  
DInitialDir  
Dtest_data  
DBytesWrt  
DBytesRead  
DFileName  
DPrintLine  
DNull  
9B ð  
9B ð  
2ð48A INZ('test.file')  
2ð48A  
12A INZ('Hello World!')  
9B ð  
9B ð  
2ð49A  
1ððA  
CONST(X'ðð')  
Cᑍ  
Cᑍ Get and print the real user id with the getuid function.  
Cᑍ  
C
Cᑍ  
eval  
ReturnInt = getuid  
Cᑍ Check for error and report status.  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
Cᑍ  
if  
ReturnInt = -1  
eval  
exsr  
eval  
return  
else  
move  
eval  
PrintLine = 'Error getting real user id'  
error  
ᑍINLR = '1'  
ReturnInt  
PrintLine = 'The real user id is '  
+ %TRIML(User)  
User  
except  
endif  
Cᑍ Get the current working directory and store it in Buffer.  
Cᑍ  
C
C
Cᑍ  
eval  
ReturnPtr=getcwd(%ADDR(Buffer)  
: %SIZE(Buffer))  
Cᑍ Check for error and report status.  
Cᑍ  
C
if  
ReturnPtr = ᑍNULL  
C
eval  
exsr  
eval  
return  
else  
PrintLine = 'Error getting current directory'  
C
error  
ᑍINLR = '1'  
C
C
C
Cᑍ  
Cᑍ Print current directory name remembering to scan for null terminator.  
Cᑍ  
C
Null  
scan  
eval  
eval  
Buffer  
NullFound  
5 ð  
C
InitialDir = %SUBST(Buffer:1:NullFound)  
PrintLine = 'Current Directory is '  
+ InitialDir  
C
C
C
except  
endif  
C
Cᑍ  
Cᑍ Create the file TEST_FILE for writing. If it does not exist,  
Cᑍ give the owner authority to read, write, and execute.  
B-184 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
C
eval  
eval  
FileName = %TRIMR(test_file) + Null  
FileDesc = open(%ADDR(FileName)  
: x'ðððððð1A' : x'ððððð1Cð')  
C
C
Cᑍ  
Cᑍ Check for error and report status.  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
Cᑍ  
if  
FileDesc = -1  
eval  
exsr  
eval  
return  
else  
eval  
PrintLine = 'Could not create file'  
error  
ᑍINLR = '1'  
PrintLine = 'File '  
+ %TRIMR(test_file)  
+ ' created successfully'  
except  
end  
Cᑍ Write test_data to test_file via FileDesc returned by open  
Cᑍ  
C
eval  
BytesWrt = write(FileDesc  
: %ADDR(Test_Data)  
: %SIZE(Test_Data))  
C
C
Cᑍ  
Cᑍ Check for error and report status. If an error occurs,  
Cᑍ attempt cleanup.  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
C
C
Cᑍ  
if  
BytesWrt = -1  
PrintLine = 'Could not write to file'  
error  
ReturnInt = close(FileDesc)  
ReturnInt = unlink(%ADDR(FileName))  
ᑍINLR = '1'  
eval  
exsr  
eval  
eval  
eval  
return  
else  
eval  
PrintLine = 'Wrote to '  
+ %TRIMR(test_file)  
+ ' successfully'  
except  
endif  
Cᑍ Close test_file via FileDesc  
Cᑍ  
C
eval  
ReturnInt = close(FileDesc)  
Cᑍ  
Cᑍ Check for error and report status. If an error occurs,  
Cᑍ attempt cleanup.  
Cᑍ  
C
C
C
C
C
C
C
C
C
if  
ReturnInt = -1  
PrintLine = 'Could not close file'  
error  
ReturnInt = close(FileDesc)  
ReturnInt = unlink(%ADDR(FileName))  
ᑍINLR = '1'  
eval  
exsr  
eval  
eval  
eval  
return  
else  
eval  
PrintLine = 'File '  
Appendix B. Original Examples in Additional Languages B-185  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
+ %TRIMR(test_file)  
+ ' closed successfully'  
C
C
C
Cᑍ  
except  
endif  
Cᑍ Open the file for read only  
Cᑍ  
C
eval  
FileDesc = open2(%ADDR(FileName)  
: x'ððððððð1')  
C
Cᑍ  
Cᑍ Check for error and report status. If an error occurs,  
Cᑍ attempt cleanup.  
Cᑍ  
C
if  
FileDesc = -1  
PrintLine = 'Open of file failed'  
error  
ReturnInt = unlink(%ADDR(FileName))  
ᑍINLR = '1'  
C
eval  
exsr  
eval  
eval  
return  
else  
eval  
except  
endif  
C
C
C
C
C
C
PrintLine = 'Open of file successful'  
C
C
Cᑍ  
Cᑍ Read from file  
Cᑍ  
C
eval  
BytesRead = read(FileDesc  
C
: %ADDR(Buffer) : %SIZE(Buffer))  
Cᑍ  
Cᑍ Check for error and report status. If an error occurs,  
Cᑍ attempt cleanup.  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
Cᑍ  
if  
BytesRead = -1  
PrintLine = 'Read failed'  
error  
ReturnInt = close(FileDesc)  
ReturnInt = unlink(%ADDR(FileName))  
ᑍINLR = '1'  
eval  
exsr  
eval  
eval  
eval  
return  
else  
if  
BytesRead = BytesWrt  
PrintLine = 'Data successfully read: '  
+ %TRIMR(Buffer)  
eval  
else  
eval  
endif  
except  
endif  
PrintLine = 'Data truncation on read'  
ReturnInt = close(FileDesc)  
Cᑍ Close the LinkName file  
Cᑍ  
C
eval  
Cᑍ  
Cᑍ Check for error and report status. If an error occurs,  
Cᑍ attempt cleanup.  
Cᑍ  
C
C
if  
eval  
ReturnInt = -1  
PrintLine = 'Close of link failed'  
B-186 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
C
exsr  
error  
C
eval  
ReturnInt = close(FileDesc)  
ReturnInt = unlink(%ADDR(FileName))  
ᑍINLR = '1'  
C
eval  
eval  
return  
else  
eval  
except  
endif  
C
C
C
C
PrintLine = 'Close of link successful'  
C
C
Cᑍ  
Cᑍ Unlink test_file  
Cᑍ  
C
eval  
ReturnInt = unlink(%ADDR(FileName))  
Cᑍ  
Cᑍ Check for error and report status. If an error occurs,  
Cᑍ attempt cleanup.  
Cᑍ  
C
C
C
C
C
C
C
C
C
C
Cᑍ  
if  
ReturnInt = -1  
PrintLine = 'Unlink of file failed'  
error  
ReturnInt = unlink(%ADDR(FileName))  
ᑍINLR = '1'  
eval  
exsr  
eval  
eval  
return  
else  
eval  
except  
endif  
PrintLine = 'Unlink of file successful'  
Cᑍ End of main program  
Cᑍ  
C
eval  
PrintLine = 'Program run is successful'  
ᑍINLR = '1'  
C
except  
eval  
return  
C
C
Cᑍ  
Cᑍ Common error reporting subroutine  
Cᑍ  
Cᑍ If errors occur, the integrated file system exports the variable  
Cᑍ 'errno' to assist in determining the problem. As 'errno' is  
Cᑍ lowercase, ILE RPG cannot directly import this variable and must  
Cᑍ use a C module to access it. If the developer has ILE C  
Cᑍ available, the following sample C code will import 'errno' and  
Cᑍ make it available to the RPG application.  
Cᑍ  
Cᑍ  
Cᑍ  
Cᑍ  
Cᑍ  
Cᑍ  
Cᑍ  
#include <errno.h>  
int geterrno()  
{
return errno;  
}
Cᑍ To activate this C module, remove the four comment identifiers  
Cᑍ following the 'except' statement and remove the comment identifier  
Cᑍ from the errno prototype. Definitions for the returned errno  
Cᑍ are found in the file QSYSINC/SYS member ERRNO.  
Cᑍ  
C
C
Cᑍ  
error  
begsr  
except  
eval  
ReturnInt = errno  
Appendix B. Original Examples in Additional Languages B-187  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cᑍ  
move  
ReturnInt  
Errnoval  
9
Cᑍ  
eval  
PrintLine = 'Errno is ' + Errnoval  
Cᑍ  
except  
eval  
except  
endsr  
C
PrintLine = 'Program ended in error'  
C
C
OQSYSPRT E  
O
1
PrintLine  
1ðð  
B-188 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Bibliography  
Bibliography  
This bibliography lists printed information that you need  
to use the OS/400 APIs, background information for the  
functions the APIs perform, and other information rele-  
vant to specific types of applications. The books are  
grouped in these categories:  
Ÿ Security – Reference, SC41-5302, provides tech-  
nical information about OS/400 security.  
Ÿ System Manager Use, SC41-5321, provides infor-  
mation about the commands and functions available  
when the System Manager for AS/400 licensed  
program is installed on one or more AS/400  
Ÿ General-purpose books  
Ÿ OS/400 API books  
Ÿ Programming language books  
systems in a network. System Manager Use  
describes packaging software products so that they  
can be distributed, installed, and serviced the same  
way IBM licensed programs are managed.  
If you want more information on a topic while you are  
using this guide, see the Publications Reference,  
SC41-5003, for related AS/400 publications.  
OS/400 API Books  
General-Purpose Books  
These books contain OS/400 APIs:  
Ÿ Common Programming APIs Toolkit/400 Reference,  
SC41-4802, describes considerations for creating,  
running, and debugging Common Programming  
APIs Toolkit/400 (CPA) programs and provides  
details on APIs supported by CPA. This book also  
includes examples of CPA programs. CPA is an  
optionally installable feature of OS/400.  
These books provide general-purpose and background  
information for the OS/400 licensed program:  
Ÿ CL Programming, SC41-5721, discusses OS/400  
functions and concepts that are relevant to pro-  
gramming.  
Ÿ CL Reference, SC41-5722, provides a description of  
the AS/400 control language (CL) and its com-  
mands. Each command description includes a  
syntax diagram, parameters, default values,  
keywords, and an example.  
Ÿ CPI Communications Reference, SC26-4399, pro-  
vides information about writing applications that  
adhere to the Systems Application Architecture  
(SAA) Communications interface. The manual  
defines the elements of the SAA Communications  
Common Programming Interface (CPI), which pro-  
vides a programming interface that allows program-  
to-program communications using IBM’s Systems  
Network Architecture (SNA) logical unit 6.2 (LU6.2).  
Ÿ AS/400 Licensed Internal Code Diagnostic Aids –  
Volume 1, LY44-5900, and AS/400 Licensed  
Internal Code Diagnostic Aids – Volume 2,  
LY44-5901, provide a list of available object types in  
hexadecimal format for use with the object APIs.  
Ÿ DB2 for AS/400 Query Management Programming,  
SC41-5703, provides information on how to deter-  
mine database files to be queried for a report,  
define a structured query language (SQL) query  
definition, define a report form definition, and use  
and write procedures that use query management  
commands. It also includes information on how to  
use the query management global variable support  
and understand the relationship between the  
OS/400 query management and the Query/400  
licensed program.  
Ÿ ILE Concepts, SC41-5606, describes the concepts  
and terminology of the Integrated Language Envi-  
ronment of the OS/400 operating system.  
Ÿ Integrated File System Introduction, SC41-5711,  
describes the concepts of the integrated file system  
and briefly describes the user interfaces and pro-  
gramming support for interacting with the integrated  
file system.  
Ÿ Printer Device Programming, SC41-5713, provides  
information to help you understand and control  
printing. This book provides specific information on  
printing elements and concepts of the AS/400  
system, printer file and print spooling support for  
printing operations, and printer connectivity.  
Ÿ GDDM Programming Guide, SC41-0536, provides  
information about using OS/400 graphical data  
display manager (GDDM) to write graphics applica-  
tion programs.  
Ÿ Guide to Enabling C2 Security, SC41-0103, pro-  
vides information about planning, installing, setting  
up, and managing your AS/400 system to meet the  
requirements for C2 security. C2 is a level of secu-  
rity defined by the United States Department of  
Defense.  
Ÿ Machine Interface Functional Reference,  
SC41-5810, is a comprehensive reference to  
machine interface (MI) instructions.  
Ÿ PrintManager API Reference, S544-3699, provides  
information the user needs to create and maintain  
Copyright IBM Corp. 1997  
H-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Bibliography  
print descriptors used by the PrintManager inter-  
face.  
Ÿ ILE COBOL/400 Programmer’s Guide, SC09-2072,  
describes how to write, compile, bind, run, debug,  
and maintain ILE COBOL programs on the AS/400  
system. It provides programming information on  
how to call other ILE COBOL and non-ILE COBOL  
programs, share data with other programs, use  
pointers, and handle exceptions. It also describes  
how to perform input/output operations on externally  
attached devices, database files, display files, and  
ICF files.  
Ÿ REXX/400 Programmer’s Guide, SC41-5728,  
explains REXX/400 programming concepts and dis-  
cusses considerations in using this language on the  
AS/400 system. It also describes REXX APIs and  
provides examples that you can use to learn  
REXX/400.  
Ÿ REXX/400 Reference, SC41-5729, provides an  
overview of the REXX/400 concepts and includes  
information about keyword instruction syntax, func-  
tion syntax, numerics, arithmetic, conditions, input  
and output streams, testing, and double-byte char-  
acter set (DBCS) support. The book also describes  
REXX APIs.  
Ÿ ILE COBOL/400 Reference, SC09-2073, describes  
the ILE COBOL programming language. It provides  
information on the structure of the ILE COBOL pro-  
gramming language and on the structure of an ILE  
COBOL source program. It also describes all Iden-  
tification Division paragraphs, Environment Division  
clauses, Data Division paragraphs, Procedure Divi-  
sion statements, and Compiler-Directing statements.  
Ÿ Sockets Programming, SC41-5422, describes the  
sockets programming functions available on AS/400  
systems and provides reference information on the  
sockets programming interface.  
Ÿ ILE RPG/400 Programmer’s Guide, SC09-2074, is a  
guide for using the ILE RPG programming lan-  
guage, which is an implementation of the RPG IV  
language in the Integrated Language Environment  
(ILE) on the AS/400 system. It includes information  
on creating and running programs, with consider-  
ations for procedure calls and interlanguage pro-  
gramming. The guide also covers debugging and  
exception handling and explains how to use AS/400  
files and devices in RPG programs. Appendixes  
include information on migration to RPG IV and  
sample compiler listings. It is intended for people  
with a basic understanding of data processing con-  
cepts and of the RPG language.  
Ÿ System API Reference, SC41-5801, describes  
OS/400 APIs. It is intended for experienced appli-  
cation programmers who are developing system-  
level and other OS/400 applications.  
Ÿ Ultimedia System Facilities Programming,  
SC41-4652, provides information to programmers  
for using Ultimedia System Facilities APIs to add  
multimedia interfaces to existing applications and to  
develop AS/400 programmable workstation (PWS)  
multimedia applications.  
Ÿ ILE RPG/400 Reference, SC09-2077, provides  
information needed to write programs for the  
AS/400 system using the ILE RPG programming  
language. This book describes, position by position  
and keyword by keyword, the valid entries for all  
RPG specifications, and provides a detailed  
description of all the operation codes and built-in  
functions. This book also contains information on  
the RPG logic cycle, arrays and tables, editing func-  
tions, and indicators.  
Programming Language Books  
You might refer to these programming language books  
while writing applications with the OS/400 APIs:  
Ÿ COBOL/400 User’s Guide, SC09-1812, provides  
information needed to design, write, test, and main-  
tain COBOL programs on the AS/400 system.  
Ÿ ILE C/400 Programmer’s Guide, SC09-2069, pro-  
vides information on how to develop applications  
using the ILE C language. It includes information  
about creating, running, and debugging programs.  
It also includes programming considerations for  
interlanguage program and procedure calls, locales,  
exception handling, database files, externally  
described files, and device files. Some perfor-  
mance tips are also described. An appendix  
includes information on migrating source code from  
extended program model (EPM) C/400 or System  
C/400 to ILE C.  
Ÿ RPG/400 Reference, SC09-1817, provides informa-  
tion needed to write programs for the AS/400  
system using the RPG programming language.  
This book describes, position by position, the valid  
entries for all RPG specifications, and provides a  
detailed description of all the operation codes. This  
book also contains information on the RPG logic  
cycle, arrays and tables, editing functions, and indi-  
cators.  
Ÿ RPG/400 User’s Guide, SC09-1816, provides infor-  
mation needed to write, test, and maintain RPG pro-  
grams on the AS/400 system. The book provides  
information on data organizations, data formats, file  
processing, multiple file processing, automatic  
Ÿ ILE C/400 Programmer’s Reference, SC09-2070,  
provides information about how to write programs  
that adhere to the Systems Application Architecture  
C Level 2 definition and use ILE C specific functions  
such as record I/O. It also provides information on  
ILE C machine interface library functions.  
report function, RPG command statements, testing  
H-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Bibliography  
and debugging functions, application design tech-  
niques, problem analysis, and compiler service  
information. The differences between the System/38  
RPG III, System/38 compatible RPG, and RPG are  
identified.  
Bibliography H-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Bibliography  
H-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
Index  
Advanced Peer-to-Peer Networking (APPN) topology  
information APIs  
use of 8-9  
AFP documents  
AFP to ASCII Transform (QWPZTAFP) API 8-17  
AFP to ASCII Transform (QWPZTAFP) API  
use of 8-17  
Special Characters  
*EXT (external) format type  
example A-14  
*INT (internal) format type  
example A-14  
AFPDS (Advanced Function Printing data stream)  
AFP to ASCII Transform (QWPZTAFP) API  
use of 8-17  
Numerics  
5250 pass-through session 8-29  
ALCOBJ (Allocate Object) command 2-16  
alert APIs  
use of 8-10  
Allocate Object (ALCOBJ) command 2-16  
allocating  
object 2-16  
AnyMail/400 Mail Server Framework APIs  
use of 8-15  
API (application programming interface)  
Add Exit Program (QUSADDEP)  
OPM COBOL example B-47  
OPM RPG example B-54  
Add Exit Program (QusAddExitProgram)  
example of keyed interface 4-3  
ILE C example 4-9  
A
accessing  
field value (initial library list)  
ILE C example B-22  
ILE COBOL example B-25  
ILE RPG example B-29  
OPM COBOL example B-25  
field value in variable-length array  
RPG example 3-19  
HOLD attribute  
ILE C example B-16  
ILE COBOL example B-18  
ILE RPG example B-21  
OPM COBOL example B-18  
OPM RPG example 3-17  
action of API 1-3  
Add Client (QZCAADDC, QzcaAddClient) API  
use of 8-2  
Add Environment Variable (ADDENVVAR)  
command 8-22  
Add Exit Program (QUSADDEP) API  
OPM COBOL example B-47  
OPM RPG example B-54  
Add Exit Program (QusAddExitProgram) API  
example of keyed interface 4-3  
ILE C example 4-9  
ILE COBOL example B-50  
ILE RPG example B-58  
Add Problem Log Entry (QsxAddProblemLogEntry)  
API 8-19  
ILE COBOL example B-50  
ILE RPG example B-58  
authorities and locks 3-2  
backup and recovery APIs  
use of 8-1  
benefits of using 1-2  
categories 1-3  
client support APIs  
use of 8-1  
common information across APIs  
advanced example 4-1  
basic example 3-1  
communications APIs  
use of 8-2  
compatibility with future releases 1-1  
configuration APIs  
use of 8-3  
ADDENVVAR (Add Environment Variable)  
command 8-22  
adding  
Create Product Definition (QSZCRTPD)  
OPM RPG example A-3  
Create Product Load (QSZCRTPL)  
OPM RPG example A-3  
Create Program (QPRCRTPG) 7-5  
Create User Space (QUSCRTUS)  
description 2-13  
exit program  
ILE C example 4-9  
ILE COBOL example B-50  
ILE RPG example B-58  
OPM COBOL example B-47  
OPM RPG example B-54  
Advanced Function Printing data stream (AFPDS)  
AFP to ASCII Transform (QWPZTAFP) API  
use of 8-17  
example B-66  
ILE C example B-94  
ILE COBOL example B-101  
ILE RPG example B-106  
Copyright IBM Corp. 1997  
X-1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
API (application programming interface) (continued)  
Create User Space (QUSCRTUS) (continued)  
OPM COBOL example B-61, B-101  
OPM RPG example 5-4, B-71  
debugger APIs  
API (application programming interface) (continued)  
List Objects That Adopt Owner Authority  
(QSYLOBJP)  
ILE C example B-94  
ILE COBOL example B-101  
ILE RPG example B-106  
OPM COBOL example B-101  
OPM RPG example 5-4  
locating field in receiver variable 3-5  
locating for use 2-1  
Log Software Error (QPDLOGER)  
ILE C example 6-2  
ILE RPG example B-119  
OPM COBOL example B-112  
OPM RPG example B-116  
message handling APIs  
use of 8-8  
use of 8-3  
definition 1-1  
Deregister Exit Point (QusDeregisterExitPoint)  
ILE C example 4-19  
ILE COBOL example B-87  
ILE RPG example B-92  
Deregister Exit Point (QUSDRGPT)  
OPM COBOL example B-85  
OPM RPG example B-90  
description  
authorities and locks 3-2  
error messages 3-5  
field descriptions 3-5  
format 3-5  
miscellaneous APIs  
use of 8-29  
optional parameter group 3-5  
parameters 3-2  
name  
locating 3-1  
required parameter group 3-3  
Dynamic Screen Manager (DSM) APIs  
use of 8-4  
national language support (NLS) APIs  
use of 8-9  
network management APIs  
use of 8-9  
edit function APIs  
use of 8-5  
error messages 3-5  
examples B-1  
extracting field from format 3-5  
field descriptions 3-5  
file APIs  
network security APIs  
NetWare authentication entry APIs 8-20  
NetWare connection APIs 8-20  
use of 8-20  
object APIs  
data queue APIs 8-12  
object APIs 8-14  
use of 8-5  
format 3-5  
use of 8-11  
getting started 2-1  
hardware resource APIs  
use of 8-6  
hierarchical file system (HFS) APIs  
use of 8-6  
high-level language (HLL) APIs  
use of 8-6  
user index APIs 8-13  
user queue APIs 8-13  
user space APIs 8-14  
office APIs  
AnyMail/400 Mail Server Framework APIs 8-15  
SNADS File Server APIs 8-16  
use of 8-15  
ILE APIs for the CEE environment 2-5  
integrated file system 2-6  
examples B-175  
Operational Assistant APIs  
use of 8-17  
OptiConnect APIs  
Integrated Language Environment (ILE)  
error code 4-1  
use of 8-3  
optional parameter group 3-5  
original program model (OPM)  
error code 3-1  
example 4-1  
introduction 2-5, 4-1  
registration facility using 4-2  
Integrated Language Environment (ILE) CEE APIs  
naming conventions 8-7  
use of 8-7  
example 3-1  
introduction 2-4  
Package Product Option (QSZPKGPO)  
OPM RPG example A-3  
parameters 3-2  
introduction 2-1  
list API example  
performance collector APIs  
use of 8-17  
print APIs  
List Objects That Adopt Owner Authority  
(QSYLOBJP) 5-12  
QSYLOBJP (List Objects That Adopt Owner  
Authority) 5-12  
use of 8-17  
X-2 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
API (application programming interface) (continued)  
problem management APIs  
use of 8-18  
API (application programming interface) (continued)  
Set COBOL Error Handler (QLRSETCE)  
OPM COBOL example B-112  
software product APIs  
process open list APIs  
use of 8-29  
use of 8-20  
program and CL command APIs  
use of 8-19  
types of 1-3  
UNIX-type APIs 2-6  
Register Exit Point (QusRegisterExitPoint)  
ILE C example 4-9  
use of 8-21  
use of 8-1  
ILE COBOL example B-50  
ILE RPG example B-58  
user interface APIs  
use of 8-27  
Register Exit Point (QUSRGPT)  
OPM COBOL example B-47  
OPM RPG example B-54  
registration facility APIs  
user interface manager APIs  
use of 8-27  
versus CL commands 1-3  
virtual terminal APIs  
use of 8-19  
use of 8-28  
Remove Exit Program (QusRemoveExitProgram)  
ILE C example 4-19  
work management APIs  
use of 8-28  
ILE COBOL example B-87  
ILE RPG example B-92  
work station support APIs  
use of 8-28  
Remove Exit Program (QUSRMVEP)  
OPM COBOL example B-85  
OPM RPG example B-90  
Report Software Error (QpdReportSoftwareError)  
ILE COBOL example B-122  
required parameter group 3-3  
Retrieve Exit Information  
Application Development Manager APIs  
use of 8-6  
application programming interface (API)  
Add Exit Program (QUSADDEP)  
OPM COBOL example B-47  
OPM RPG example B-54  
Add Exit Program (QusAddExitProgram)  
example of keyed interface 4-3  
ILE C example 4-9  
(QusRetrieveExitInformation)  
ILE C example 4-13  
ILE COBOL example B-66  
ILE RPG example B-75  
ILE COBOL example B-50  
ILE RPG example B-58  
authorities and locks 3-2  
backup and recovery APIs  
use of 8-1  
Retrieve Exit Information (QUSRTVEI)  
OPM COBOL example B-61  
OPM RPG example B-71  
Retrieve Job Description Information  
(QWDRJOBD) 3-29  
benefits of using 1-2  
categories 1-3  
Retrieve Object Description (QUSROBJD)  
ILE C example B-94  
client support APIs  
use of 8-1  
ILE COBOL example B-101  
ILE RPG example B-106  
OPM COBOL example B-101  
OPM RPG example 5-4  
common information across APIs  
advanced example 4-1  
basic example 3-1  
communications APIs  
Retrieve Pointer to User Space (QUSPTRUS)  
example B-66  
use of 8-2  
compatibility with future releases 1-1  
configuration APIs  
ILE C example B-94  
ILE COBOL example B-101  
ILE RPG example B-106  
OPM COBOL example B-61, B-101  
OPM RPG example 5-4, B-71  
Retrieve User Space (QUSRTVUS) 2-13  
SAA Common Execution Environment (CEE) 2-5  
security APIs  
use of 8-3  
Create Product Definition (QSZCRTPD)  
OPM RPG example A-3  
Create Product Load (QSZCRTPL)  
OPM RPG example A-3  
Create Program (QPRCRTPG) 7-5  
Create User Space (QUSCRTUS) B-66  
description 2-13  
use of 8-20  
Set COBOL Error Handler  
(QlnSetCobolErrorHandler)  
ILE COBOL example B-122  
example B-66  
ILE C example B-94  
ILE COBOL example B-101  
ILE RPG example B-106  
Index X-3  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
application programming interface (API) (continued)  
Create User Space (QUSCRTUS) (continued)  
OPM COBOL example B-61, B-101  
OPM RPG example 5-4, B-71  
debugger APIs  
application programming interface (API) (continued)  
List Objects That Adopt Owner Authority  
(QSYLOBJP)  
ILE C example B-94  
ILE COBOL example B-101  
ILE RPG example B-106  
OPM COBOL example B-101  
OPM RPG example 5-4  
locating field in receiver variable 3-5  
locating for use 2-1  
use of 8-3  
definition 1-1  
Deregister Exit Point (QusDeregisterExitPoint)  
ILE C example 4-19  
ILE COBOL example B-87  
ILE RPG example B-92  
Deregister Exit Point (QUSDRGPT)  
OPM COBOL example B-85  
OPM RPG example B-90  
description  
Log Software Error (QPDLOGER)  
ILE C example 6-2  
ILE RPG example B-119  
OPM COBOL example B-112  
OPM RPG example B-116  
message handling APIs  
use of 8-8  
authorities and locks 3-2  
error messages 3-5  
field descriptions 3-5  
format 3-5  
miscellaneous APIs  
use of 8-29  
optional parameter group 3-5  
parameters 3-2  
name  
locating 3-1  
required parameter group 3-3  
Dynamic Screen Manager (DSM) APIs  
use of 8-4  
national language support (NLS) APIs  
use of 8-9  
network management APIs  
use of 8-9  
edit function APIs  
use of 8-5  
error handling 2-30  
error messages 3-5  
examples B-1  
network security APIs  
NetWare authentication entry APIs 8-20  
NetWare connection APIs 8-20  
object APIs  
extracting field from format 3-5  
field descriptions 3-5  
file APIs  
data queue APIs 8-12  
object APIs 8-14  
use of 8-11  
use of 8-5  
format 3-5  
getting started 2-1  
hardware resource APIs  
use of 8-6  
user index APIs 8-13  
user queue APIs 8-13  
user space APIs 8-14  
office APIs  
AnyMail/400 Mail Server Framework APIs 8-15  
SNADS File Server APIs 8-16  
use of 8-15  
hierarchical file system (HFS) APIs  
use of 8-6  
high-level language (HLL) APIs  
use of 8-6  
Operational Assistant APIs  
use of 8-17  
ILE APIs for the CEE environment 2-5  
integrated file system 2-6  
examples B-175  
Integrated Language Environment (ILE)  
error code 4-1  
OptiConnect APIs  
use of 8-3  
optional parameter group 3-5  
original program model (OPM)  
error code 3-1  
example 4-1  
example 3-1  
introduction 2-5, 4-1  
introduction 2-4  
registration facility using 4-2  
Integrated Language Environment (ILE) CEE APIs  
naming conventions 8-7  
use of 8-7  
Package Product Option (QSZPKGPO)  
OPM RPG example A-3  
parameter  
length 2-17  
introduction 2-1  
parameters 3-2  
list API example  
performance 2-31  
List Objects That Adopt Owner Authority  
(QSYLOBJP) 5-12  
performance collector APIs  
use of 8-17  
QSYLOBJP (List Objects That Adopt Owner  
Authority) 5-12  
X-4 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
application programming interface (API) (continued)  
print APIs  
application programming interface (API) (continued)  
Set COBOL Error Handler  
(QlnSetCobolErrorHandler)  
ILE COBOL example B-122  
Set COBOL Error Handler (QLRSETCE)  
OPM COBOL example B-112  
software product APIs  
use of 8-20  
use of 8-17  
problem management APIs  
use of 8-18  
process open list APIs  
use of 8-29  
program and CL command APIs  
use of 8-19  
types of 1-3  
Register Exit Point (QusRegisterExitPoint)  
ILE C example 4-9  
UNIX-type APIs 2-6  
use of 8-21  
ILE COBOL example B-50  
ILE RPG example B-58  
use of 8-1  
user interface APIs  
Register Exit Point (QUSRGPT)  
OPM COBOL example B-47  
OPM RPG example B-54  
registration facility APIs  
use of 8-27  
user interface manager APIs  
use of 8-27  
versus CL commands 1-3  
virtual terminal APIs  
use of 8-19  
Remove Exit Program (QusRemoveExitProgram)  
ILE C example 4-19  
use of 8-28  
work management APIs  
use of 8-28  
work station support APIs  
use of 8-28  
ILE COBOL example B-87  
ILE RPG example B-92  
Remove Exit Program (QUSRMVEP)  
OPM COBOL example B-85  
OPM RPG example B-90  
Report Software Error (QpdReportSoftwareError)  
ILE C example 6-7  
APPN (Advanced Peer-to-Peer Networking) topology  
information APIs  
use of 8-9  
array  
ILE COBOL example B-122  
ILE RPG example B-126  
required parameter group 3-3  
Retrieve Exit Information  
(QusRetrieveExitInformation)  
&cx2x. example 4-13  
programming language use of 2-3  
ASCII printers  
AFP to ASCII Transform (QWPZTAFP) API 8-17  
asynchronous communications using user  
queue 8-13  
Attention key buffering  
definition 8-28  
authorities and locks  
description 3-2  
ILE COBOL example B-66  
ILE RPG example B-75  
Retrieve Exit Information (QUSRTVEI)  
OPM COBOL example B-61  
OPM RPG example B-71  
Retrieve Job Description Information  
(QWDRJOBD) 3-29  
automatic storage 7-36  
B
backup and recovery APIs  
List Save File (QSRLSAVF) API  
use of 8-1  
Retrieve Object Description (QUSROBJD)  
ILE C example B-94  
ILE COBOL example B-101  
ILE RPG example B-106  
OPM COBOL example B-101  
OPM RPG example 5-4  
Open List of Objects to be Backed Up (QEZOLBKL)  
API 8-29  
use of 8-29  
Operational Assistant backup APIs  
use of 8-1  
Retrieve Device Capabilities (QTARDCAP) API  
use of 8-1  
Save Object List (QSRSAVO) API  
use of 8-1  
Retrieve Pointer to User Space (QUSPTRUS)  
example B-66  
ILE C example B-94  
ILE COBOL example B-101  
ILE RPG example B-106  
OPM COBOL example B-61, B-101  
OPM RPG example 5-4, B-71  
Retrieve User Space (QUSRTVUS) 2-13  
SAA Common Execution Environment (CEE) 2-5  
security APIs  
use of 8-1  
BASIC  
data type use 2-3  
PRPQ 5799-FPK 2-3  
use of 8-20  
Index X-5  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
BASIC language  
Character Data Representation Architecture (CDRA)  
APIs  
data type use 2-3, 2-4  
beginning  
use of 8-9  
instruction stream 7-22  
benefits of using APIs 1-2  
bibliography H-1  
CHGENVVAR (Change Environment Variable)  
command 8-22  
CHGVAR (Change Variable) command 2-3, 2-4  
choosing  
binary data  
programming language use of 2-3  
binding directory  
high-level language to use 2-3  
CL (control language)  
definition 4-1  
See also command, CL  
BLDPART (Build Part) command 8-6  
breakpoint  
data type use 2-3, 2-4  
example  
setting  
receiving error messages 2-10  
programming example  
MI instruction program 7-7  
Build Part (BLDPART) command 8-6  
by reference, passing parameters 2-7  
by value directly, passing parameters 2-7  
by value indirectly, passing parameters 2-7  
byte alignment, defining 9-22  
bytes available field 2-23  
bytes returned field 2-23  
listing database file members 2-22  
CL (control language) program  
packaging your own software products  
example for creating objects and library A-2  
classification of parameter 2-8  
client program 8-28  
client support APIs  
Add Client (QZCAADDC, QzcaAddClient) API  
use of 8-2  
Get Client Handle (QzcaGetClientHandle) API  
use of 8-2  
Refresh Client (QZCAREFC, QzcaRefreshClientInfo)  
API  
C
C language  
See ILE C language  
C/400 language  
See ILE C language  
use of 8-2  
calling  
Remove Client (QZCARMVC, QzcaRemoveClient)  
API  
MI CL05 program 7-18  
CDRA (Character Data Representation Architecture)  
APIs  
use of 8-2  
Update Client Information (QZCAUPDC,  
QzcaUpdateClientInfo) API  
use of 8-2  
use of 8-9  
Change Configuration Description (QDCCCFGD) API  
use of 8-3  
Change Environment Variable (CHGENVVAR)  
command 8-22  
use of 8-1  
Close List (QGYCLST) API 8-30  
COBOL APIs  
Change Library List (QLICHGLL) API 8-14  
Change Object Description (QLICOBJD) API 8-14  
Change Problem Log Entry  
(QsxChangeProblemLogEntry) API 8-19  
change request management APIs  
use of 8-11  
use of 8-7  
COBOL language  
data type use 2-3, 2-4  
command, CL  
Add Environment Variable (ADDENVVAR)  
command 8-22  
Change User Space (QUSCHGUS) API  
effect on user space 2-17  
example 2-20, 2-21  
used with pointer data 2-16  
used without pointer data 2-17  
Change Variable (CHGVAR) command 2-3, 2-4  
changing  
ALCOBJ (Allocate Object) 2-16  
Allocate Object (ALCOBJ) 2-16  
Build Part (BLDPART) 8-6  
Change Environment Variable (CHGENVVAR) 8-22  
Change Variable (CHGVAR) 2-3, 2-4  
CHGVAR (Change Variable) 2-3, 2-4  
Create Command (CRTCMD) 8-14  
Create Edit Description (CRTEDTD) 8-5  
Create Menu (CRTMNU) 8-14  
Deallocate Object (DLCOBJ) 2-16  
Display Job Description (DSPJOBD) 3-30  
Display Library (DSPLIB) 8-15  
Display Message Description (DSPMSGD) 4-6  
object usage data 2-16  
user space  
example 2-20, 2-21  
variable 2-3, 2-4  
character data  
programming language use of 2-3  
X-6 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
command, CL (continued)  
Display Object Description (DSPOBJD) 8-14  
Display Programs That Adopt (DSPPGMADP) 5-12  
DLCOBJ (Deallocate Object) 2-16  
DSPJOBD (Display Job Description) 3-30  
DSPMSGD (Display Message Description) 4-6  
DSPPGMADP (Display Programs That Adopt) 5-12  
Retrieve Object Description (RTVOBJD) 8-15  
versus API 1-3  
Convert Type (QLICVTTP) API 8-14  
converting  
SNA-character-string data stream to ASCII data  
stream 8-17  
CPF3CAA, list greater than available space 2-22  
CPF3CF1 message 4-5  
CPF9872 message 4-5  
Create Command (CRTCMD) command 8-14  
Create Edit Description (CRTEDTD) command 8-5  
Create Menu (CRTMNU) command 8-14  
Create Problem Log Entry  
(QsxCreateProblemLogEntry) API 8-19  
Create Product Definition (QSZCRTPD) API  
OPM RPG example A-3  
Work with Filter Action Entry (WRKFTRACNE) 8-11  
Work with Registration Information  
(WRKREGINF) 2-27  
WRKREGINF (Work with Registration  
Information) 2-27  
commitment control APIs  
use of 8-8  
Create Product Load (QSZCRTPL) API  
OPM RPG example A-3  
Common Execution Environment (CEE) API,  
SAA 2-5  
Create Program (QPRCRTPG) API 7-5  
use of 8-19  
common programming techniques  
MI (machine interface) instruction program 7-32  
communications APIs  
Create User Space (QUSCRTUS) API  
description 2-13  
example B-66  
OptiConnect APIs  
use of 8-3  
use of 8-2  
listing database file members 2-22  
receiving error messages 2-10  
ILE C example B-94  
compatibility with future AS/400 releases  
application programming interface 1-1  
include files 2-28  
ILE COBOL example B-101  
ILE RPG example B-106  
OPM COBOL example B-61, B-101  
OPM RPG example 5-4, B-71  
creating  
compiling  
program  
MI instruction program 7-4  
configuration APIs  
MI MICRTPG program 7-18  
MI version of CLCRTPG program 7-11  
product definition  
Change Configuration Description (QDCCCFGD) API  
use of 8-3  
OPM RPG example A-3  
List Configuration Descriptions (QDCLCFGD) API  
use of 8-3  
product load  
OPM RPG example A-3  
Retrieve Configuration Status (QDCRCFGS) API  
use of 8-3  
use of 8-3  
program  
MI instruction program 7-5, 7-6  
user space  
continuation handle  
example B-66  
definition 2-25  
example 4-13  
OPM COBOL example B-61  
OPM RPG example B-71  
using 2-25  
control language (CL)  
Cross System Product (CSP) language 2-3, 2-4  
CRTCMD (Create Command) command 8-14  
CRTEDTD (Create Edit Description) command 8-5  
CRTMNU (Create Menu) command 8-14  
CSP (Cross System Product) language 2-3, 2-4  
See also command, CL  
data type use 2-3, 2-4  
example  
receiving error messages 2-10  
programming example  
D
listing database file members 2-22  
control language (CL) program  
packaging your own software products  
example for creating objects and library A-2  
Convert Date and Time Format (QWCCVTDT)  
API 8-29  
data description specifications (DDS) format type  
format type *EXT example A-14  
format type *INT example A-14  
data queue  
ILE C example A-15  
working with  
Convert Edit Code (QECCVTEC) API 8-5  
use of 8-5  
ILE COBOL example B-165  
ILE RPG example B-172  
Index X-7  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
data queue (continued)  
working with (continued)  
OPM COBOL example B-165  
OPM RPG example B-169  
data queue APIs  
deregistering (continued)  
exit point (continued)  
OPM COBOL example B-85  
OPM RPG example B-90  
description  
advantages 8-12  
API  
comparisons with using database files 8-12  
similarities to message queues 8-13  
use of 8-12  
authorities and locks 3-2  
error messages 3-5  
field descriptions 3-5  
data structure  
format 3-5  
defining 9-5  
optional parameter group 3-5  
parameters 3-2  
required parameter group 3-3  
determining  
processing lists 3-29  
programming language use of 2-3  
data type  
programming language use of 2-3, 2-4  
database  
API name 3-1  
whether error occurred  
error recovery 2-30  
database file API  
example 4-5  
diagnosing errors  
List Database File Members (QUSLMBR)  
example 2-22  
See error handling  
directory  
date  
in example program B-175  
Directory Search exit program 8-16  
Directory Supplier exit program 8-16  
Directory Verification exit program 8-16  
displacement 2-23  
Display Directory Panels (QOKDSPDP) API 8-15  
Display Directory X.400 Panels (QOKDSPX4)  
API 8-15  
of changing  
user space 2-16  
of retrieving user space 2-16  
Deallocate Object (DLCOBJ) command 2-16  
deallocating  
object 2-16  
debugger APIs  
use of 8-3  
debugging  
Display Job Description (DSPJOBD)  
command 3-30  
program  
Display Library (DSPLIB) command 8-15  
Display Message Description (DSPMSGD)  
command 4-6  
MI instruction program 7-7  
decimal data  
programming language use of 2-3  
zoned 2-3  
Display Object Description (DSPOBJD)  
command 8-14  
declare statements  
Display Programs That Adopt (DSPPGMADP)  
command 5-12  
setting  
MI instruction program 7-2  
declaring  
displaying  
all message data for exception  
example 4-6  
pointers 7-17  
structure for MICRTPG program 7-16  
defining  
job description 3-30  
program adopt 5-12  
external call 7-17  
Distributed Protocol Interface (DPI)  
definition 8-25  
DLCOBJ (Deallocate Object) command 2-16  
Document Conversion exit program 8-16  
Document Handling exit program 8-16  
domain  
concept 2-26  
DPI (Distributed Protocol Interface)  
definition 8-25  
Delete Problem Log Entry  
(QsxDeleteProblemLogEntry) API 8-19  
Deregister Exit Point (QusDeregisterExitPoint) API  
ILE C example 4-19  
ILE COBOL example B-87  
ILE RPG example B-92  
Deregister Exit Point (QUSDRGPT) API  
OPM COBOL example B-85  
OPM RPG example B-90  
deregistering  
DSM (Dynamic Screen Manager) APIs  
use of 8-4  
exit point  
DSPJOBD (Display Job Description)  
command 3-30  
ILE C example 4-19  
ILE COBOL example B-87  
ILE RPG example B-92  
X-8 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
DSPLIB (Display Library) command 8-15  
DSPMSGD (Display Message Description)  
command 4-6  
environment variable APIs  
getenv()  
use of 8-21  
DSPOBJD (Display Object Description)  
command 8-14  
putenv()  
use of 8-21  
DSPPGMADP (Display Programs That Adopt)  
command 5-12  
Qp0zGetEnv()  
use of 8-21  
Dynamic Screen Manager (DSM) APIs  
use of 8-4  
Qp0zPutEnv()  
use of 8-21  
use of 8-21  
error code  
E
description 3-4  
error code parameter  
handling exceptions 4-5  
initializing 4-5  
e-mail  
AnyMail/400 Mail Server Framework APIs  
use of 8-15  
Edit (QECEDT) API  
use of 8-5  
edit code  
introduction 2-8  
optional 2-8  
using 9-2  
definition 8-5  
error code structure  
example 4-3  
Edit Code (EDTCDE) API  
use of 8-5  
format 3-12  
edit function APIs  
Convert Edit Code (QECCVTEC) API  
use of 8-5  
introduction 2-8  
retrieving hold parameter  
RPG example 3-11  
error handling  
Edit (QECEDT) API  
use of 8-5  
Edit Code (EDTCDE) API  
use of 8-5  
Edit Word (EDTWRD) API  
use of 8-5  
use of 8-5  
by programming language 2-3  
error determination  
example 4-5  
exception message 3-8  
ILE RPG example B-8  
job log use in 2-10  
OPM RPG example 3-8  
error code structure 3-6, 3-11  
using API to signal 4-6  
using error code parameter  
description 4-5  
introduction 2-8  
optional 2-8  
edit mask  
definition 8-5  
edit word  
definition 8-5  
Edit Word (EDTWRD) API  
use of 8-5  
EDTCDE (Edit Code) API  
use of 8-5  
EDTWRD (Edit Word) API  
use of 8-5  
error message  
CPF3CF1 4-5  
CPF9872 4-5  
End Problem Log Services  
(QsxEndProblemLogServices) API 8-19  
entry point  
description 3-5  
error, common programming  
examples  
setting  
incorrect coding with regard to new function 9-36  
incorrectly defined byte alignment 9-22  
incorrectly defined data structures 9-5  
incorrectly defined list entry format lengths 9-14  
incorrectly defined receiver variables 9-10  
incorrectly using null pointers with OPM  
APIs 9-18  
MI instruction program 7-2  
environment  
APIs for CEE environment 2-5  
APIs for ILE environment  
introduction 2-5  
APIs for OPM environment  
introduction 2-4  
incorrectly using offsets 9-27  
APIs for UNIX environment 2-6  
environment variable  
definition 8-21  
incorrectly using the error code parameter 9-2  
table of examples 9-1  
escape (*ESCAPE) message  
using 8-21  
See error handling  
Index X-9  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
example  
example (continued)  
accessing field value in variable-length array 3-19  
differences chapter (continued)  
logging software error (OPM API without  
Pointers), ILE RPG B-119  
logging software error (OPM API without  
pointers), OPM COBOL B-112  
logging software error (OPM API without  
Pointers), OPM RPG B-116  
reporting software error (ILE API with pointers),  
ILE C 6-7  
accessing HOLD attribute 3-17  
Add Exit Program (QUSADDEP) API  
OPM COBOL B-47  
OPM RPG B-54  
Add Exit Program (QusAddExitProgram) API  
ILE C 4-9  
ILE COBOL B-50  
ILE RPG B-58  
API use  
reporting software error (ILE API with pointers),  
ILE COBOL B-122  
reporting software error (ILE API with pointers),  
ILE RPG B-126  
Change User Space (QUSCHGUS) 2-20, 2-21  
Create User Space (QUSCRTUS) 2-10, 2-22  
List Database File Members (QUSLMBR) 2-22  
Appendix A  
Set COBOL Error Handler  
program for packaging product, ILE C B-129  
program for packaging product, ILE  
COBOL B-136  
(QlnSetCobolErrorHandler) API B-122  
setting COBOL error handler, OPM  
COBOL B-112  
program for packaging product, ILE RPG B-144  
program for packaging product, OPM  
COBOL B-136  
error code parameter 9-2  
error code structure 3-11  
exit program 4-9  
retrieving file description to user space B-152,  
B-155  
retrieving file description to user space, ILE  
COBOL B-152  
external (*EXT) format type A-14  
handling errors as escape messages 3-8  
header file  
error code structure 4-3  
working with data queues, ILE COBOL B-165  
working with data queues, ILE RPG B-172  
working with data queues, OPM COBOL B-165  
working with data queues, OPM RPG B-169  
changing  
how to use 4-2  
variable-length structure 4-3  
ILE chapter  
Add Exit Program (QUSADDEP) API, OPM  
COBOL B-47  
user space 2-20, 2-21  
Add Exit Program (QUSADDEP) API, OPM  
RPG B-54  
Add Exit Program (QusAddExitProgram) API, ILE  
COBOL B-50  
Add Exit Program (QusAddExitProgram) API, ILE  
RPG B-58  
Create User Space (QUSCRTUS) API, ILE  
COBOL B-66  
coding techniques for integrating new function 9-36  
continuation handle, use of 4-13  
Create Product Definition (QSZCRTPD) API  
OPM RPG A-3  
Create Product Load (QSZCRTPL) API  
OPM RPG A-3  
Create User Space (QUSCRTUS) API B-66  
OPM COBOL B-61  
Create User Space (QUSCRTUS) API, OPM  
COBOL B-61  
OPM RPG B-71  
data description specifications (DDS) format  
type A-14  
Create User Space (QUSCRTUS) API, OPM  
RPG B-71  
data queue  
Deregister Exit Point (QusDeregisterExitPoint)  
API, ILE COBOL B-87  
Deregister Exit Point (QusDeregisterExitPoint)  
API, ILE RPG B-92  
Deregister Exit Point (QUSDRGPT) API, OPM  
COBOL B-85  
Deregister Exit Point (QUSDRGPT) API, OPM  
RPG B-90  
creating and manipulating A-15  
defining byte alignment 9-22  
defining data structures 9-5  
defining list entry format lengths 9-14  
defining receiver variables 9-10  
Deregister Exit Point (QusDeregisterExitPoint) API  
ILE C 4-19  
ILE COBOL B-87  
ILE RPG B-92  
Register Exit Point (QusRegisterExitPoint) API,  
ILE COBOL B-50  
Deregister Exit Point (QUSDRGPT) API  
OPM COBOL B-85  
Register Exit Point (QusRegisterExitPoint) API,  
ILE RPG B-58  
OPM RPG B-90  
differences chapter  
Register Exit Point (QUSRGPT) API, OPM  
COBOL B-47  
logging software error (OPM API without  
Pointers), ILE C 6-2  
Register Exit Point (QUSRGPT) API, OPM  
RPG B-54  
X-10 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
example (continued)  
example (continued)  
ILE chapter (continued)  
machine interface (MI) instruction program  
beginning instruction stream 7-22  
calling CL05 program 7-18  
Remove Exit Program (QusRemoveExitProgram)  
API, ILE COBOL B-87  
Remove Exit Program (QusRemoveExitProgram)  
API, ILE RPG B-92  
common programming techniques 7-32  
compiling program 7-4  
Remove Exit Program (QUSRMVEP) API, OPM  
COBOL B-85  
Remove Exit Program (QUSRMVEP) API, OPM  
RPG B-90  
creating MI version of CLCRTPG program 7-11  
creating MICRTPG program 7-18  
creating MICRTPG2 program 7-27  
creating program 7-5, 7-6  
Retrieve Exit Information  
(QusRetrieveExitInformation) API, ILE  
COBOL B-66  
Retrieve Exit Information  
(QusRetrieveExitInformation) API, ILE  
RPG B-75  
debugging program 7-7  
declaring pointers 7-17  
declaring structure for MICRTPG program 7-16  
defining external call 7-17  
enhanced version of MICRTPG program 7-18  
handling exceptions 7-9  
Retrieve Exit Information (QUSRTVEI) API, OPM  
COBOL B-61  
Retrieve Exit Information (QUSRTVEI) API, OPM  
RPG B-71  
MICRTPG program 7-16  
MICRTPG2 complete program 7-23  
MICRTPG2 complete program (enhanced) 7-28  
program storage 7-36  
Retrieve Pointer to User Space (QUSPTRUS)  
API, ILE COBOL B-66  
Retrieve Pointer to User Space (QUSPTRUS)  
API, OPM COBOL B-61  
Retrieve Pointer to User Space (QUSPTRUS)  
API, OPM RPG B-71  
setting breakpoints 7-7  
setting declare statements 7-2  
setting entry point 7-2  
starting instruction stream 7-3  
null pointers 9-18  
offsets in a user space 9-27  
OPM chapter  
include file 4-2  
integrated file system B-175, B-178, B-183  
ILE C B-175  
accessing field value (initial library list), ILE  
C
B-22  
ILE COBOL B-178  
ILE RPG B-183  
accessing field value (initial library list), ILE  
COBOL B-25  
internal (*INT) format type A-14  
keyed interface  
accessing field value (initial library list), ILE  
RPG B-29  
variable-length record 4-3  
list API  
accessing field value (initial library list), OPM  
COBOL B-25  
List Objects That Adopt Owner Authority  
(QSYLOBJP) 5-12  
list chapter  
List Objects That Adopt Owner Authority  
(QSYLOBJP) API B-101  
List Objects That Adopt Owner Authority  
(QSYLOBJP) API  
accessing the hold attribute, ILE C B-16  
accessing the hold attribute, ILE COBOL B-18  
accessing the hold attribute, ILE RPG B-21  
accessing the hold attribute, OPM COBOL B-18  
handling error conditions, ILE RPG B-8  
retrieving the hold parameter (error code struc-  
ture), ILE C B-10  
ILE C B-94  
ILE COBOL B-101  
retrieving the hold parameter (error code struc-  
ture), ILE COBOL B-12  
ILE RPG B-106  
OPM COBOL B-101  
retrieving the hold parameter (error code struc-  
ture), ILE RPG B-14  
OPM RPG 5-4  
listing  
retrieving the hold parameter (error code struc-  
ture), OPM COBOL B-12  
database file members 2-22  
logging software error (OPM API without pointers)  
ILE C 6-2  
retrieving the hold parameter (exception  
message), ILE C B-2  
retrieving the hold parameter (exception  
message), ILE COBOL B-4  
ILE RPG B-119  
OPM COBOL B-112  
OPM RPG B-116  
retrieving the hold parameter (exception  
message), ILE RPG B-6  
logging software error (QPDLOGER) API, without  
pointers  
using keys with List Spooled Files API, ILE  
C
B-33  
OPM COBOL B-112  
using keys with List Spooled Files API, ILE  
COBOL B-38  
Index X-11  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
example (continued)  
example (continued)  
Retrieve Exit Information (QUSRTVEI) API (con-  
tinued)  
OPM chapter (continued)  
using keys with List Spooled Files API, ILE  
RPG B-42  
OPM RPG B-71  
using keys with List Spooled Files API, OPM  
COBOL B-38  
Retrieve Pointer to User Space (QUSPTRUS)  
API B-66  
original program model (OPM) 3-1  
Package Product Option (QSZPKGPO) API  
OPM RPG A-3  
OPM COBOL B-61  
OPM RPG B-71  
retrieving  
packaging your own software products  
CL program for creating objects and library A-2  
program for packaging product B-136  
ILE C B-129  
exit information 4-13  
file description to user space A-11  
retrieving file description to user space  
ILE COBOL B-152  
ILE RPG B-155  
ILE COBOL B-136  
ILE RPG B-144  
introduction A-1  
OPM COBOL B-136  
OPM RPG A-3  
OPM COBOL B-152  
retrieving hold parameter  
error code structure 3-11  
exception message 3-6  
RPG call statement 3-2  
setting COBOL error handler  
ILE COBOL B-122  
OPM COBOL B-112  
UNIX-type APIs B-175  
user queue A-15  
user space format 2-14  
variable-length structure 4-3  
work management 3-1  
working with data queues  
ILE COBOL B-165  
ILE RPG B-172  
programming language use  
control language (CL) 2-10  
ILE RPG 2-20  
RPG 2-21  
qusec.h header file  
error code structure 4-3  
variable-length structure 4-3  
receiver variable 4-7  
receiving an error message from the job log 2-10  
Register Exit Point (QusRegisterExitPoint) API  
ILE C 4-9  
ILE COBOL B-50  
ILE RPG B-58  
Register Exit Point (QUSRGPT) API  
OPM COBOL B-47  
OPM COBOL B-165  
OPM RPG B-169  
exception  
OPM RPG B-54  
displaying all message data  
example 4-6  
handling  
MI instruction program 7-9  
handling errors as escape messages  
RPG example 3-8  
registration facility using ILE APIs 4-9  
Remove Exit Program (QusRemoveExitProgram) API  
ILE C 4-19  
ILE COBOL B-87  
ILE RPG B-92  
Remove Exit Program (QUSRMVEP) API  
OPM COBOL B-85  
retrieving hold parameter  
RPG example 3-6  
OPM RPG B-90  
repeating entry type  
exception (*EXCP) message  
See error handling  
fixed-length fields 4-7  
exit point  
variable-length fields 4-8  
variable-length fields using offsets 4-8  
reporting software error (ILE API with pointers)  
ILE C 6-7  
definition 2-27, 8-19  
registration facility 2-27  
exit point provider  
responsibilities 2-28  
exit program  
ILE COBOL B-122  
ILE RPG B-126  
definition 2-27, 8-19  
example using registration facility 4-9  
include file 2-29  
Retrieve Exit Information  
(QusRetrieveExitInformation) API  
ILE C 4-13  
office  
ILE COBOL B-66  
use of 8-16  
ILE RPG B-75  
Retrieve Exit Information (QUSRTVEI) API  
OPM COBOL B-61  
registration facility 2-27  
using 2-27  
X-12 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
external format type (*EXT)  
example A-14  
extracting  
format (continued)  
user space 2-14  
format JOBD0100  
description 3-5  
field from format 3-5  
format name  
description 3-4  
function of APIs, system 1-3  
functions  
F
field description  
description 3-5  
in example program B-175  
file  
See header file  
See include file  
See source include file  
pointer  
G
Generate CD-ROM Premastering Information  
(QlpGenerateCdPremasteringInfo, QLPCDINF) API  
use of 8-21  
See pointer  
file APIs  
Get Client Handle (QzcaGetClientHandle) API  
use of 8-2  
Get List Entry (QGYGTLE) API 8-29  
getenv()  
commitment control APIs  
use of 8-8  
journal APIs  
use of 8-8  
use of 8-21  
Query (QQQQRY) API  
use of 8-5  
getting started with APIs 2-1  
Retrieve Display File (QDFRTVFD) API  
use of 8-5  
Retrieve File Override Information (QDMRTVFO) API  
use of 8-6  
H
handle 2-12  
See also continuation handle  
Handle CD-ROM Premastering State  
(QlpHandleCdState, QLPCDRST) API  
use of 8-21  
use of 8-5  
file description  
retrieving to user space  
ILE COBOL example B-152  
ILE RPG example B-155  
OPM COBOL example B-152  
file operations  
example program B-175  
filter  
definition 8-11  
filtering  
handling  
error conditions  
ILE RPG example B-8  
exceptions  
MI instruction program 7-9  
hardware resource  
definition 8-6  
hardware resource APIs  
use of 8-6  
header file  
definition 8-18  
problem management APIs  
use of 8-18  
See also include file  
ILE example 4-2  
Find Entry Number in List (QGYFNDE) API 8-30  
Find Entry Number in Message List (QGYFNDME)  
API 8-30  
QSYSINC library 2-28  
header file qusec.h  
error code structure example 4-3  
variable-length structure example 4-3  
Hewlett Packard LaserJet  
AFP to ASCII Transform (QWPZTAFP) API 8-17  
HFS (hierarchical file system) APIs  
use of 8-6  
hierarchical file system (HFS) APIs  
use of 8-6  
high-level language (HLL)  
differences 2-3  
Find Field Numbers in List (QGYFNDF) API 8-30  
finding  
API name 3-1  
floating-point data 2-3  
format  
See also list API  
See also retrieve API  
description 3-5  
displacements 2-23  
error code structure 3-12  
locating field in receiver variable 3-5  
offsets 2-23  
high-level language (HLL) APIs  
Application Development Manager APIs  
use of 8-6  
processing lists 3-29  
Index X-13  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
high-level language (HLL) APIs (continued)  
COBOL APIs  
ILE COBOL example (continued)  
report software error (ILE API with pointers) B-122  
Retrieve Exit Information  
use of 8-7  
use of 8-6  
HLL (high-level language)  
differences 2-3  
HLL (high-level language) APIs  
use of 8-6  
host print transform 8-17  
Host Print Transform (QWPZHPTR) API  
use of 8-17  
(QusRetrieveExitInformation) API B-66  
retrieving file description to user space B-152  
retrieving the hold parameter (error code  
structure) B-12  
retrieving the hold parameter (exception  
message) B-4  
setting COBOL error handler B-122  
using integrated file system B-178  
using keys with List Spooled Files API B-38  
working with data queues B-165  
ILE COBOL language  
I
ILE (Integrated Language Environment) APIs  
binding directory 4-1  
data type use 2-3, 2-4  
ILE RPG example  
CEE environment  
introduction 2-5  
example 4-1  
example using registration facility 4-9  
introduction 2-5, 4-1  
accessing field value (initial library list) B-29  
accessing the hold attribute B-21  
Add Exit Program (QusAddExitProgram) API B-58  
Deregister Exit Point (QusDeregisterExitPoint)  
API B-92  
registration facility using 4-2  
ILE (Integrated Language Environment) CEE APIs  
naming conventions 8-7  
use of 8-7  
ILE C example  
handling error conditions B-8  
keys with List Spooled Files API B-42  
List Objects That Adopt Owner Authority  
(QSYLOBJP) API B-106  
logging software error (OPM API without  
pointers) B-119  
packaging your own software products B-144  
Register Exit Point (QusRegisterExitPoint) API B-58  
Remove Exit Program (QusRemoveExitProgram)  
API B-92  
reporting software error (ILE API with  
pointers) B-126  
accessing field value (initial library list) B-22  
accessing the hold attribute B-16  
Add Exit Program (QusAddExitProgram) API 4-9  
List Objects That Adopt Owner Authority  
(QSYLOBJP) API B-94  
logging software error (OPM API without  
pointers) 6-2  
packaging your own software products B-129  
Register Exit Point (QusRegisterExitPoint) API 4-9  
reporting software error (ILE API with pointers) 6-7  
retrieving the hold parameter (error code  
structure) B-10  
Retrieve Exit Information  
(QusRetrieveExitInformation) API B-75  
retrieving file description to user space B-155  
retrieving the hold parameter (error code  
structure) B-14  
retrieving the hold parameter (exception  
message) B-6  
retrieving the hold parameter (exception  
message) B-2  
using integrated file system B-175  
using keys with List Spooled Files API B-33  
ILE C language  
data type use 2-3, 2-4  
ILE COBOL example  
using integrated file system B-183  
working with data queues B-172  
ILE RPG language  
data type use 2-3, 2-4  
example  
accessing field value (initial library list) B-25  
accessing the hold attribute B-18  
Add Exit Program (QusAddExitProgram) API B-50  
Deregister Exit Point (QusDeregisterExitPoint)  
API B-87  
changing user space 2-20  
include file  
See also header file  
exit program 2-29  
ILE example 4-2  
QSYSINC library 2-28  
List Objects That Adopt Owner Authority  
(QSYLOBJP) API B-101  
initializing  
packaging your own software products B-136  
Register Exit Point (QusRegisterExitPoint) API B-50  
Remove Exit Program (QusRemoveExitProgram)  
API B-87  
error code parameter 4-5  
input parameter 2-8  
input/output parameter 2-8  
X-14 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
instruction stream  
beginning 7-22  
starting  
MI instruction program 7-3  
integrated file system  
examples  
job description  
displaying 3-30  
job description API  
Retrieve Job Description Information  
(QWDRJOBD) 3-29  
job description name, qualified  
description 3-4  
ILE C B-175  
ILE COBOL B-178  
ILE RPG B-183  
integrated file system APIs  
UNIX environment 2-6  
use of 8-22  
journal APIs  
commitment control APIs  
use of 8-8  
use of 8-8  
Integrated Language Environment (ILE) APIs  
binding directory 4-1  
CEE environment  
K
key 2-24  
keyboard buffering  
definition 8-28  
keyed interface  
definition 2-24  
variable-length record 2-24  
example 4-3  
kill()  
introduction 2-5  
example 4-1  
example using registration facility 4-9  
introduction 2-5, 4-1  
registration facility using 4-2  
Integrated Language Environment (ILE) CEE APIs  
naming conventions 8-7  
use of 8-7  
use of 8-24  
internal format type (*INT)  
example A-14  
L
internal identifier 2-12  
internal job identifier 2-12  
internal spooled file identifier 2-12  
interprocess communications (IPC) APIs  
msgget()  
language  
See programming language  
last-changed date 2-16  
last-retrieved date 2-16  
length  
in API parameter 2-17  
length of receiver variable  
description 3-3  
use of 8-23  
semget()  
use of 8-23  
shmget()  
use of 8-23  
use of 8-22  
library  
See also QSYSINC (system include) library  
optionally installed  
QSYSINC (system include) 2-28  
QSYSINC (system include)  
member name 2-28  
QUSRTOOL 2-30  
IPC (interprocess communications) APIs  
msgget()  
use of 8-23  
semget()  
use of 8-23  
shmget()  
use of 8-23  
use of 8-22  
link  
in example program B-175  
list API  
continuation handle 2-25  
length parameter 2-17  
List Database File Members (QUSLMBR)  
example 2-22  
List Objects That Adopt Owner Authority  
(QSYLOBJP)  
J
job  
log 2-10  
synchronizing 2-16  
job API  
ILE C example B-94  
ILE COBOL example B-101  
ILE RPG example B-106  
list format 5-14  
OPM COBOL example B-101  
OPM RPG example 5-4  
List Objects That Adopt Owner Authority  
(QSYLOBJP)  
list format 5-14  
Retrieve Job Description Information  
(QWDRJOBD) 3-29  
Index X-15  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
list API (continued)  
using user space 2-13  
list API example  
Log Software Error (QPDLOGER) API (continued)  
without pointers  
ILE C example 6-2  
objects that adopt owner authority 5-12  
List Configuration Descriptions (QDCLCFGD) API  
use of 8-3  
List Database File Members (QUSLMBR) API  
example 2-22  
ILE RPG example B-119  
OPM COBOL example B-112  
OPM RPG example B-116  
logging  
message  
list entry format lengths, defining 9-14  
list format  
for error diagnosis and recovery 2-10  
software error (ILE API with pointers)  
ILE C example 6-7  
See format  
See list API  
ILE COBOL example B-122  
ILE RPG example B-126  
software error (OPM API without pointers)  
ILE C example 6-2  
List Objects (QUSLOBJ) API 8-14  
List Objects That Adopt Owner Authority  
(QSYLOBJP) API  
ILE C example B-94  
ILE RPG example B-119  
OPM COBOL example B-112  
OPM RPG example B-116  
ILE COBOL example B-101  
ILE RPG example B-106  
list format 5-14  
OPM COBOL example B-101  
OPM RPG example 5-4  
List Objects That Adopt Owner Authority  
(QSYLOBJP) API—example 5-12  
list of entries  
M
machine interface (MI) instruction  
See also machine interface (MI) instruction program  
introduction 7-1  
Lock Object (LOCK) 2-16  
processing 3-29  
Lock Space Location (LOCKSL) 2-16  
Unlock Object (UNLOCK) 2-16  
Unlock Space Location (UNLOCKSL) 2-16  
machine interface (MI) instruction program  
See also machine interface (MI) instruction  
data type use 2-3, 2-4  
data structures 3-24  
logic flow 2-15  
List Save File (QSRLSAVF) API  
use of 8-1  
listing  
See also format  
See also list API  
See also retrieve API  
See also retrieving  
objects that adopt authority  
ILE C example B-94  
example  
beginning instruction stream 7-22  
calling CL05 program 7-18  
common programming techniques 7-32  
compiling program 7-4  
creating MI version of CLCRTPG program 7-11  
creating MICRTPG program 7-18  
creating MICRTPG2 program 7-27  
creating program 7-5, 7-6  
debugging program 7-7  
declaring pointers 7-17  
declaring structure for MICRTPG program 7-16  
defining external call 7-17  
enhanced version of MICRTPG program 7-18  
handling exceptions 7-9  
ILE COBOL example B-101  
ILE RPG example B-106  
OPM COBOL example B-101  
OPM RPG example 5-4  
locating  
API name 3-1  
API to use 2-1  
field in receiver variable 3-5  
lock  
for synchronizing jobs 2-16  
LOCK (Lock Object) MI instruction 2-16  
Lock Object (LOCK) MI instruction 2-16  
Lock Space Location (LOCKSL) MI instruction 2-16  
LOCKSL (Lock Space Location) MI instruction 2-16  
log API  
Log Software Error (QPDLOGER) API, without  
pointers  
OPM COBOL example B-112  
Log Software Error (QPDLOGER) API 8-19  
OPM COBOL example B-112  
MICRTPG program 7-16  
MICRTPG2 complete program 7-23  
MICRTPG2 complete program (enhanced) 7-28  
program storage 7-36  
setting breakpoints 7-7  
setting declare statements 7-2  
setting entry point 7-2  
starting instruction stream 7-3  
mail server framework  
AnyMail/400 Mail Server Framework APIs  
use of 8-15  
X-16 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
mail server framework (continued)  
SNADS File Server APIs  
use of 8-16  
miscellaneous APIs  
Convert Date and Time Format (QWCCVTDT) API  
use of 8-29  
message  
process open list APIs  
See also error handling  
See also user queue  
CPF3CF1 4-5  
CPF9872 4-5  
Close List (QGYCLST) API 8-30  
Find Entry Number in List (QGYFNDE) API 8-30  
Find Entry Number in Message List  
(QGYFNDME) API 8-30  
Find Field Numbers in List (QGYFNDF)  
API 8-30  
logging  
for error diagnosis and recovery 2-10  
message data  
Get List Entry (QGYGTLE) API 8-29  
use of 8-29  
displaying for exception  
example 4-6  
message handling  
Remove All Bookmarks from a Course  
(QEARMVBM) API  
message key 2-12  
use of 8-29  
message handling APIs  
Open List of Job Log Messages (QGYOLJBL) API  
use of 8-29  
Retrieve Data (QPARTVDA) API  
use of 8-29  
Start Pass-Through (QPASTRPT) API  
use of 8-29  
Open List of Messages (QGYOLMSG) API  
use of 8-29  
use of 8-29  
use of 8-8  
message key 2-12  
message queue  
modifying  
See changing  
moving  
through returned information 2-23  
msgget()  
use of 8-23  
multiple entries  
processing list of  
logic flow 2-15  
definition 8-22  
MI (machine interface) instruction  
introduction 7-1  
Lock Object (LOCK) 2-16  
Lock Space Location (LOCKSL) 2-16  
Unlock Object (UNLOCK) 2-16  
Unlock Space Location (UNLOCKSL) 2-16  
MI (machine interface) instruction program  
data type use 2-3, 2-4  
N
name  
example  
locating API 3-1  
national language data conversion APIs  
use of 8-9  
national language support (NLS) APIs  
Character Data Representation Architecture (CDRA)  
APIs  
beginning instruction stream 7-22  
calling CL05 program 7-18  
common programming techniques 7-32  
compiling program 7-4  
creating MI version of CLCRTPG program 7-11  
creating MICRTPG program 7-18  
creating MICRTPG2 program 7-27  
creating program 7-5, 7-6  
debugging program 7-7  
declaring pointers 7-17  
declaring structure for MICRTPG program 7-16  
defining external call 7-17  
enhanced version of MICRTPG program 7-18  
handling exceptions 7-9  
MICRTPG program 7-16  
MICRTPG2 complete program 7-23  
MICRTPG2 complete program (enhanced) 7-28  
program storage 7-36  
use of 8-9  
national language data conversion APIs  
use of 8-9  
use of 8-9  
NetWare authentication entry APIs  
use of 8-20  
NetWare connection APIs  
use of 8-20  
network management  
Advanced Peer-to-Peer Networking (APPN) topology  
information APIs  
use of 8-9  
alert APIs  
use of 8-10  
change request management APIs  
use of 8-11  
setting breakpoints 7-7  
setting declare statements 7-2  
setting entry point 7-2  
starting instruction stream 7-3  
node list APIs  
use of 8-11  
Index X-17  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
network management (continued)  
registered filter APIs  
object type  
domain 2-26  
use of 8-11  
office APIs  
SNA/Management Services Transport (SNA/MS  
Transport) APIs  
AnyMail/400 Mail Server Framework APIs  
use of 8-15  
use of 8-10  
network management APIs  
use of 8-9  
network security APIs  
NetWare authentication entry APIs 8-20  
NetWare connection APIs 8-20  
NLS (national language support) APIs  
Character Data Representation Architecture (CDRA)  
APIs  
Display Directory Panels (QOKDSPDP) API  
use of 8-15  
Display Directory X.400 Panels (QOKDSPX4) API  
use of 8-15  
Search System Directory (QOKSCHD) API  
use of 8-15  
SNADS File Server APIs  
use of 8-16  
use of 8-15  
use of 8-9  
office exit program  
national language data conversion APIs  
use of 8-9  
Directory Search exit program  
use of 8-16  
use of 8-9  
node list  
Directory Supplier exit program  
use of 8-16  
definition 8-11  
node list APIs  
Directory Verification exit program  
use of 8-16  
use of 8-11  
null pointers, using 9-18  
Document Conversion exit program  
use of 8-16  
Document Handling exit program  
use of 8-16  
use of 8-16  
User Application Administration exit program  
use of 8-16  
O
object  
See also user space  
allocating 2-16  
deallocating 2-16  
lock 2-16  
offset 2-23  
incorrectly using 9-27  
locating field in receiver variable 3-5  
offset value  
object APIs  
Change Library List (QLICHGLL) API 8-14  
Change Object Description (QLICOBJD) API 8-14  
Convert Type (QLICVTTP) API 8-14  
data queue APIs  
definition 2-17  
used with pointer data 2-16  
used without pointer data 2-17  
open list APIs  
advantages 8-12  
Open List of Job Log Messages (QGYOLJBL)  
API 8-29  
Open List of Messages (QGYOLMSG) API 8-29  
Open List of Objects (QGYOLOBJ) API 8-29  
Open List of Objects to be Backed Up (QEZOLBKL)  
API 8-29  
comparisons with using database files 8-12  
similarities to message queues 8-13  
use of 8-12  
List Objects (QUSLOBJ) API 8-14  
Open List of Objects (QGYOLOBJ) API  
use of 8-29  
Open List of Objects to be Backed Up (QEZOLBKL)  
API  
Open List of Printers (QGYRPRTL) API 8-29  
Open List of Spooled Files (QGYOLSPL) API 8-29  
Open List of Job Log Messages (QGYOLJBL)  
API 8-29  
use of 8-29  
Rename Object (QLIRNMO) API 8-15  
Retrieve Library Description (QLIRLIBD) API 8-15  
Retrieve Object Description (QUSROBJD) API 8-15  
use of 8-11, 8-14  
user index APIs  
use of 8-13  
user queue APIs  
Open List of Messages (QGYOLMSG) API 8-29  
Open List of Objects (QGYOLOBJ) API 8-29  
Open List of Objects to be Backed Up (QEZOLBKL)  
API 8-29  
Open List of Printers (QGYRPRTL) API 8-29  
Open List of Spooled Files (QGYOLSPL) API 8-29  
Operational Assistant APIs  
use of 8-17  
use of 8-13  
user space APIs  
Operational Assistant backup APIs  
use of 8-1  
use of 8-14  
X-18 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
Operational Assistant exit program  
use of 8-17  
OptiConnect APIs  
use of 8-3  
operations  
optional parameter group  
description 3-5  
example program B-175  
OPM (original program model)  
API  
original program model (OPM)  
API  
null pointer 9-18  
example 3-1  
null pointer 9-18  
example 3-1  
introduction 2-4  
OPM COBOL example  
introduction 2-4  
OS/400 signal management 8-24  
output  
See list API  
output parameter 2-8  
accessing field value (initial library list) B-25  
accessing the hold attribute B-18  
Add Exit Program (QUSADDEP) API B-47  
Create User Space (QUSCRTUS) API B-61  
Deregister Exit Point (QUSDRGPT) API B-85  
List Objects That Adopt Owner Authority  
(QSYLOBJP) API B-101  
Log Software Error (QPDLOGER) API, without  
pointers B-112  
logging software error (OPM API without  
pointers) B-112  
packaging your own software products B-136  
Register Exit Point (QUSRGPT) API B-47  
Remove Exit Program (QUSRMVEP) API B-85  
Retrieve Exit Information (QUSRTVEI) API B-61  
Retrieve Pointer to User Space (QUSPTRUS)  
API B-61  
P
Package Product Option (QSZPKGPO) API  
OPM RPG example A-3  
packaging  
product option  
OPM RPG example A-3  
your own software products  
example of CL program for creating objects and  
library A-2  
ILE C example B-129  
ILE COBOL example B-136  
ILE RPG example B-144  
introduction of OPM RPG example A-1  
OPM COBOL example B-136  
OPM RPG example A-3  
retrieving file description to user space B-152  
retrieving the hold parameter (error code  
structure) B-12  
packed decimal data  
in programming languages 2-3  
parameter  
classification 2-8  
description 3-2  
example RPG call statement 3-2  
parameter passing  
by reference 2-7  
by value directly 2-7  
by value indirectly 2-7  
to procedures 2-7  
parent process  
definition 8-25  
Pascal  
retrieving the hold parameter (exception  
message) B-4  
Set COBOL Error Handler (QLRSETCE) API B-112  
setting COBOL error handler B-112  
using keys with List Spooled Files API B-38  
working with data queues B-165  
OPM RPG example  
Add Exit Program (QUSADDEP) API B-54  
Create Product Definition (QSZCRTPD) API A-3  
Create Product Load (QSZCRTPL) API A-3  
Create User Space (QUSCRTUS) API B-71  
Deregister Exit Point (QUSDRGPT) API B-90  
List Objects That Adopt Owner Authority  
(QSYLOBJP) API 5-4  
PRPQ 5799-FRJ 2-3  
Pascal language  
logging software error (OPM API without  
pointers) B-116  
data type use 2-3, 2-4  
passing parameters  
by reference 2-7  
Package Product Option (QSZPKGPO) API A-3  
packaging your own software products A-3  
introduction A-1  
by value directly 2-7  
by value indirectly 2-7  
to procedures 2-7  
performance collector APIs  
use of 8-17  
Register Exit Point (QUSRGPT) API B-54  
Remove Exit Program (QUSRMVEP) API B-90  
Retrieve Exit Information (QUSRTVEI) API B-71  
Retrieve Pointer to User Space (QUSPTRUS)  
API B-71  
performing  
working with data queues B-169  
tasks using APIs  
packaging your own software products, CL  
program example A-2  
Index X-19  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
performing (continued)  
problem management APIs (continued)  
Delete Problem Log Entry  
(QsxDeleteProblemLogEntry) API (continued)  
use of 8-19  
tasks using APIs (continued)  
packaging your own software products, ILE  
C
B-129  
packaging your own software products, ILE  
COBOL B-136  
packaging your own software products, ILE  
RPG B-144  
End Problem Log Services  
(QsxEndProblemLogServices) API  
use of 8-19  
error reporting APIs  
packaging your own software products, introduc-  
tion A-1  
use of 8-19  
filtering 8-18  
packaging your own software products, OPM  
COBOL B-136  
Log Software Error (QPDLOGER) API  
use of 8-19  
packaging your own software products, OPM  
RPG A-3  
problem log entry APIs  
use of 8-19  
retrieving file description to user space A-11  
using data queues versus user queues A-15  
Personal Printer Data Stream  
AFP to ASCII Transform (QWPZTAFP) API 8-17  
PL/I  
Report Software Error (QpdReportSoftwareError) API  
use of 8-19  
Retrieve Problem Log Entry  
(QsxRetrieveProblemLogEntry) API  
use of 8-19  
PRPQ 5799-FPJ 2-3  
PL/I language  
Start Problem Log Services  
(QsxStartProblemLogServices) API  
use of 8-19  
data type use 2-3, 2-4  
pointer  
use of 8-18  
manipulating user spaces with 2-16  
manipulating user spaces without 2-17  
programming language use of 2-3  
restoring 8-14  
Work with Problem (QPDWRKPB) API  
use of 8-19  
procedural language  
data type use  
using offset values with 2-16  
position values 2-17  
REXX 2-3, 2-4  
procedure  
PostScript data stream  
AFP to ASCII Transform (QWPZTAFP) API 8-17  
print APIs  
passing parameters to 2-7  
process group  
definition 8-25  
Host Print Transform (QWPZHPTR) API 8-17  
Open List of Printers (QGYRPRTL) API  
use of 8-29  
process open list APIs  
Close List (QGYCLST) API  
use of 8-30  
print APIs  
Find Entry Number in List (QGYFNDE) API  
use of 8-30  
Find Entry Number in Message List (QGYFNDME)  
API  
AFP to ASCII Transform (QWPZTAFP) API 8-17  
use of 8-17  
Print Driver exit program 8-18  
spooled file APIs  
use of 8-30  
Open List of Spooled Files (QGYOLSPL)  
API 8-29  
Find Field Numbers in List (QGYFNDF) API  
use of 8-30  
use of 8-18  
use of 8-17  
Get List Entry (QGYGTLE) API  
use of 8-29  
Print Driver exit program 8-18  
problem management APIs  
Add Problem Log Entry (QsxAddProblemLogEntry)  
API  
use of 8-29  
process-related APIs  
use of 8-27  
processing  
use of 8-19  
list of entries  
Change Problem Log Entry  
(QsxChangeProblemLogEntry) API  
use of 8-19  
Create Problem Log Entry  
(QsxCreateProblemLogEntry) API  
use of 8-19  
logic flow 2-15  
lists  
data structures 3-29  
processing time 2-31  
program  
See also example  
Delete Problem Log Entry  
(QsxDeleteProblemLogEntry) API  
See also programming language  
X-20 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
program (continued)  
programming language (continued)  
compiling  
ILE C example (continued)  
MI instruction program 7-4  
creating  
MI instruction program 7-5, 7-6  
packaging your own software products B-129  
Register Exit Point (QusRegisterExitPoint)  
API 4-9  
creating MI MICRTPG2 program 7-27  
debugging  
reporting software error (ILE API with  
pointers) 6-7  
MI instruction program 7-7  
MI MICRTPG2 complete program (enhanced)  
example 7-28  
retrieving the hold parameter (error code struc-  
ture) B-10  
retrieving the hold parameter (exception  
message) B-2  
MI MICRTPG2 complete program example 7-23  
program activation 7-36  
program adopt  
using integrated file system B-175  
using keys with List Spooled Files API B-33  
ILE COBOL example  
displaying 5-12  
program and CL command APIs  
Create Program (QPRCRTPG) API  
use of 8-19  
accessing field value (initial library list) B-25  
accessing the hold attribute B-18  
Add Exit Program (QusAddExitProgram)  
API B-50  
use of 8-19  
program invocation 7-36  
program storage  
Deregister Exit Point (QusDeregisterExitPoint)  
API B-87  
MI (machine interface) instruction program 7-36  
programming error, common  
examples  
List Objects That Adopt Owner Authority  
(QSYLOBJP) API B-101  
packaging your own software products B-136  
Register Exit Point (QusRegisterExitPoint)  
API B-50  
Remove Exit Program (QusRemoveExitProgram)  
API B-87  
reporting software error (ILE API with  
pointers) B-122  
incorrect coding with regard to new function 9-36  
incorrectly defined byte alignment 9-22  
incorrectly defined data structures 9-5  
incorrectly defined list entry format lengths 9-14  
incorrectly defined receiver variables 9-10  
incorrectly using null pointers with OPM  
APIs 9-18  
Retrieve Exit Information  
incorrectly using offsets 9-27  
incorrectly using the error code parameter 9-2  
table of examples 9-1  
(QusRetrieveExitInformation) API B-66  
retrieving file description to user space B-152  
retrieving the hold parameter (error code struc-  
ture) B-12  
programming language  
control language (CL)  
retrieving the hold parameter (exception  
message) B-4  
example (listing database file members) 2-22  
example (receiving error messages) 2-10  
Cross System Product (CSP) 2-3, 2-4  
data type use  
setting COBOL error handler B-122  
using integrated file system B-178  
using keys with List Spooled Files API B-38  
working with data queues B-165  
ILE RPG example  
BASIC 2-4  
CL (control language) 2-4  
COBOL 2-4  
ILE C 2-4  
ILE CL (control language) 2-4  
ILE COBOL 2-4  
accessing field value (initial library list) B-29  
accessing the hold attribute B-21  
Add Exit Program (QusAddExitProgram)  
API B-58  
machine interface (MI) instructions 2-4  
Pascal 2-4  
PL/I 2-4  
changing user space 2-20  
Deregister Exit Point (QusDeregisterExitPoint)  
API B-92  
REXX 2-4  
RPG 2-4  
VisualAge C++ for OS/400 2-4  
ILE C example  
handling error conditions B-8  
keys with List Spooled Files API B-42  
list API B-106  
logging software error (OPM API without  
pointers) B-119  
packaging your own software products B-144  
Register Exit Point (QusRegisterExitPoint)  
API B-58  
accessing field value (initial library list) B-22  
accessing the hold attribute B-16  
Add Exit Program (QusAddExitProgram) API 4-9  
list API B-94  
logging software error (OPM API without  
pointers) 6-2  
Remove Exit Program (QusRemoveExitProgram)  
API B-92  
Index X-21  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
programming language (continued)  
ILE RPG example (continued)  
programming language (continued)  
OPM RPG example (continued)  
Register Exit Point (QUSRGPT) API B-54  
Remove Exit Program (QUSRMVEP) API B-90  
Retrieve Exit Information (QUSRTVEI) API B-71  
Retrieve Pointer to User Space (QUSPTRUS)  
API B-71  
reporting software error (ILE API with  
pointers) B-126  
Retrieve Exit Information  
(QusRetrieveExitInformation) API B-75  
retrieving file description to user space B-155  
retrieving the hold parameter (error code struc-  
ture) B-14  
retrieving the hold parameter (exception  
message) B-6  
working with data queues B-169  
packaging your own software products  
creating objects and library, CL example A-2  
parameter passing 2-8  
using integrated file system B-183  
working with data queues B-172  
introduction of OPM RPG example  
packaging your own software products A-1  
machine interface (MI) instruction  
See machine interface (MI) instruction  
See machine interface (MI) instruction program  
OPM COBOL example  
programming technique, common  
MI (machine interface) instruction program 7-32  
putenv()  
use of 8-21  
Q
QDCCCFGD (Change Configuration Description) API  
use of 8-3  
accessing field value (initial library list) B-25  
accessing the hold attribute B-18  
Add Exit Program (QUSADDEP) API B-47  
Create User Space (QUSCRTUS) API B-61  
Deregister Exit Point (QUSDRGPT) API B-85  
list API B-101  
Log Software Error (QPDLOGER) API, without  
pointers B-112  
logging software error (OPM API without  
pointers) B-112  
packaging your own software products B-136  
Register Exit Point (QUSRGPT) API B-47  
Remove Exit Program (QUSRMVEP) API B-85  
Retrieve Exit Information (QUSRTVEI) API B-61  
Retrieve Pointer to User Space (QUSPTRUS)  
API B-61  
retrieving file description to user space B-152  
retrieving the hold parameter (error code struc-  
ture) B-12  
retrieving the hold parameter (exception  
message) B-4  
Set COBOL Error Handler (QLRSETCE)  
API B-112  
QDCLCFGD (List Configuration Descriptions) API  
use of 8-3  
QDCRCFGS (Retrieve Configuration Status) API  
use of 8-3  
QDFRTVFD (Retrieve Display File) API  
use of 8-5  
QDMRTVFO (Retrieve File Override Information) API  
use of 8-6  
QEARMVBM (Remove All Bookmarks from a  
Course) API 8-29  
QECCVTEC (Convert Edit Code) API 8-5  
use of 8-5  
QECEDT (Edit) API  
use of 8-5  
QEZOLBKL (Open List of Objects to be Backed Up)  
API 8-29  
QGYCLST (Close List) API 8-30  
QGYFNDE (Find Entry Number in List) API 8-30  
QGYFNDF (Find Field Numbers in List) API 8-30  
QGYFNDME (Find Entry Number in Message List)  
API 8-30  
QGYGTLE (Get List Entry) API 8-29  
QGYOLJBL (Open List of Job Log Messages)  
API 8-29  
QGYOLMSG (Open List of Messages) API 8-29  
QGYOLOBJ (Open List of Objects) API 8-29  
QGYOLSPL (Open List of Spooled Files) API 8-29  
QGYRPRTL (Open List of Printers) API 8-29  
QLICHGLL (Change Library List) API 8-14  
QLICOBJD (Change Object Description) API 8-14  
QLICVTTP (Convert Type) API 8-14  
QLIRLIBD (Retrieve Library Description) API 8-15  
QLIRNMO (Rename Object) API 8-15  
QlnSetCobolErrorHandler (Set COBOL Error  
Handler) API  
setting COBOL error handler B-112  
using keys with List Spooled Files API B-38  
working with data queue B-165  
OPM RPG example  
Add Exit Program (QUSADDEP) API B-54  
changing user space 2-21  
Create Product Definition (QSZCRTPD) API A-3  
Create Product Load (QSZCRTPL) API A-3  
Create User Space (QUSCRTUS) API B-71  
Deregister Exit Point (QUSDRGPT) API B-90  
list API 5-4  
logging software error (OPM API without  
pointers) B-116  
Package Product Option (QSZPKGPO) API A-3  
packaging your own software products A-3  
ILE COBOL example B-122  
X-22 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
QLPCDINF (Generate CD-ROM Premastering Infor-  
mation) API  
QsxStartProblemLogServices (Start Problem Log  
Services) API 8-19  
use of 8-21  
QSYLOBJP (List Objects That Adopt Owner  
Authority) API  
QLPCDRST (Handle CD-ROM Premastering State)  
API  
ILE C example B-94  
use of 8-21  
ILE COBOL example B-101  
ILE RPG example B-106  
list format 5-14  
OPM COBOL example B-101  
OPM RPG example 5-4  
QlpGenerateCdPremasteringInfo (Generate CD-ROM  
Premastering Information) API  
use of 8-21  
QlpHandleCdState (Handle CD-ROM Premastering  
State) API  
QSYLOBJP (List Objects That Adopt Owner  
Authority) API—example 5-12  
QSYSINC (system include) library 2-28  
example of header file 4-2  
member name 2-28  
use of 8-21  
QLRSETCE (Set COBOL Error Handler) API  
OPM COBOL example B-112  
QOKDSPDP (Display Directory Panels) API 8-15  
QOKDSPX4 (Display Directory X.400 Panels)  
API 8-15  
QSZCRTPD (Create Product Definition) API  
OPM RPG example A-3  
QOKSCHD (Search System Directory) API 8-15  
Qp0sEnableSignals()  
QSZCRTPL (Create Product Load) API  
OPM RPG example A-3  
use of 8-24  
Qp0zGetEnv()  
QSZPKGPO (Package Product Option) API  
OPM RPG example A-3  
use of 8-21  
Qp0zPutEnv()  
qualified job description name  
description 3-4  
use of 8-21  
Query (QQQQRY) API  
QPARTVDA (Retrieve Data) API 8-29  
QPASTRPT (Start Pass-Through) API 8-29  
QPDLOGER (Log Software Error) API 8-19  
without pointers  
use of 8-5  
querying  
See list API  
qus.h header file 4-4  
ILE C example 6-2  
ILE RPG example B-119  
OPM COBOL example B-112  
OPM RPG example B-116  
QpdReportSoftwareError (Report Software Error)  
API 8-19  
QUSADDEP (Add Exit Program) API  
OPM COBOL example B-47  
OPM RPG example B-54  
QusAddExitProgram (Add Exit Program) API  
example of keyed interface 4-3  
ILE C example 4-9  
with pointers  
ILE COBOL example B-50  
ILE RPG example B-58  
ILE C example 6-7  
ILE COBOL example B-122  
ILE RPG example B-126  
QPDWRKPB (Work with Problem) API 8-19  
QPRCRTPG (Create Program) API 7-5  
use of 8-19  
QUSCHGUS (Change User Space) API  
effect on user space 2-17  
example 2-20, 2-21  
used with pointer data 2-16  
used without pointer data 2-17  
QUSCRTUS (Create User Space) API  
description 2-13  
QQQQRY (Query) API  
use of 8-5  
QsxAddProblemLogEntry (Add Problem Log Entry)  
API 8-19  
QsxChangeProblemLogEntry (Change Problem Log  
Entry) API 8-19  
example B-66  
listing database file members 2-22  
receiving error messages 2-10  
ILE C example B-94  
QsxCreateProblemLogEntry (Create Problem Log  
Entry) API 8-19  
QsxDeleteProblemLogEntry (Delete Problem Log  
Entry) API 8-19  
QsxEndProblemLogServices (End Problem Log Ser-  
vices) API 8-19  
ILE COBOL example B-101  
ILE RPG example B-106  
OPM COBOL example B-61, B-101  
OPM RPG example 5-4, B-71  
QusDeregisterExitPoint (Deregister Exit Point) API  
ILE C example 4-19  
QsxRetrieveProblemLogEntry (Retrieve Problem  
Log Entry) API 8-19  
ILE COBOL example B-87  
ILE RPG example B-92  
Index X-23  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
QUSDRGPT (Deregister Exit Point) API  
OPM COBOL example B-85  
OPM RPG example B-90  
QZCAADDC (Add Client) API  
use of 8-2  
QzcaAddClient (Add Client) API  
use of 8-2  
qusec.h header file  
error code structure 4-2  
QUSLMBR (List Database File Members) API  
example 2-22  
QUSLOBJ (List Objects) API 8-14  
QUSPTRUS (Retrieve Pointer to User Space) API  
example B-66  
QzcaGetClientHandle (Get Client Handle) API  
use of 8-2  
QZCAREFC (Refresh Client) API  
use of 8-2  
QzcaRefreshClientInfo (Refresh Client) API  
use of 8-2  
ILE C example B-94  
ILE COBOL example B-101  
ILE RPG example B-106  
QzcaRemoveClient (Remove Client) API  
use of 8-2  
QZCARMVC (Remove Client) API  
use of 8-2  
QzcaUpdateClientInfo (Update Client Information)  
API  
OPM COBOL example B-61, B-101  
OPM RPG example 5-4, B-71  
QusRegisterExitPoint (Register Exit Point) API  
ILE C example 4-9  
use of 8-2  
ILE COBOL example B-50  
ILE RPG example B-58  
QZCAUPDC (Update Client Information) API  
use of 8-2  
QusRemoveExitProgram (Remove Exit Program) API  
example 4-19  
R
ILE COBOL example B-87  
ILE RPG example B-92  
raise()  
use of 8-24  
receiver variable  
QusRetrieveExitInformation (Retrieve Exit Informa-  
tion) API  
See also user space  
bytes available field 2-23  
bytes returned field 2-23  
continuation handle 2-25  
defining 9-10  
description 2-23, 3-3  
repeating entry type with fixed-length fields  
example 4-7  
ILE C example 4-13  
ILE COBOL example B-66  
ILE RPG example B-75  
qusrgfa1.h header file 4-4  
QUSRGPT (Register Exit Point) API  
OPM COBOL example B-47  
OPM RPG example B-54  
QUSRMVEP (Remove Exit Program) API  
OPM COBOL example B-85  
OPM RPG example B-90  
repeating entry type with variable-length fields  
example using offsets 4-8  
retrieve API 2-23  
QUSROBJD (Retrieve Object Description) API 8-15  
ILE C example B-94  
receiving  
See list API  
recovery considerations  
See error handling  
Refresh Client (QZCAREFC, QzcaRefreshClientInfo)  
API  
ILE COBOL example B-101  
ILE RPG example B-106  
OPM COBOL example B-101  
OPM RPG example 5-4  
QUSRTOOL library 2-30  
use of 8-2  
QUSRTVEI (Retrieve Exit Information) API  
OPM COBOL example B-61  
OPM RPG example B-71  
Register Exit Point (QusRegisterExitPoint) API  
ILE C example 4-9  
ILE COBOL example B-50  
ILE RPG example B-58  
Register Exit Point (QUSRGPT) API  
OPM COBOL example B-47  
OPM RPG example B-54  
registered filter APIs  
use of 8-11  
QUSRTVUS (Retrieve User Space) API 2-13  
used with pointer data 2-16  
used without pointer data 2-17  
QWCCVTDT (Convert Date and Time Format)  
API 8-29  
QWDRJOBD (Retrieve Job Description Information)  
API—example 3-29  
QWPZHPTR (Host Print Transform) API  
use of 8-17  
registering  
exit point  
ILE C example 4-9  
ILE COBOL example B-50  
ILE RPG example B-58  
QWPZTAFP (AFP to ASCII Transform) API  
use of 8-17  
X-24 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
registering (continued)  
exit point (continued)  
required parameter group  
description 3-3  
OPM COBOL example B-47  
OPM RPG example B-54  
registration facility  
error code 3-4  
format name 3-4  
length of receiver variable 3-3  
qualified job description name 3-4  
receiver variable 3-3  
resource entry  
description 2-27  
registration facility APIs 2-27  
using ILE APIs  
concepts 4-2  
definition 8-6  
examples 4-9  
restoring  
registration facility APIs 2-27  
use of 8-19  
pointer to user space 8-14  
user index 8-14  
registration facility repository 8-19  
service programs 4-2  
user queue 8-13  
user space 8-14  
related printed information H-1  
Remove All Bookmarks from a Course  
(QEARMVBM) API 8-29  
Remove Client (QZCARMVC, QzcaRemoveClient)  
API  
retrieve API  
continuation handle 2-25  
user space example A-11  
using receiver variable 2-23  
using user space 2-25  
use of 8-2  
Retrieve Configuration Status (QDCRCFGS) API  
use of 8-3  
Retrieve Data (QPARTVDA) API 8-29  
Retrieve Device Capabilities (QTARDCAP) API  
use of 8-1  
Retrieve Display File (QDFRTVFD) API  
use of 8-5  
Retrieve Exit Information  
Remove Exit Program (QusRemoveExitProgram) API  
example 4-19  
ILE COBOL example B-87  
ILE RPG example B-92  
Remove Exit Program (QUSRMVEP) API  
OPM COBOL example B-85  
OPM RPG example B-90  
removing  
(QusRetrieveExitInformation) API  
ILE C example 4-13  
exit program  
example 4-19  
ILE COBOL example B-66  
ILE COBOL example B-87  
ILE RPG example B-92  
OPM COBOL example B-85  
OPM RPG example B-90  
Rename Object (QLIRNMO) API 8-15  
repeating entry type  
ILE RPG example B-75  
Retrieve Exit Information (QUSRTVEI) API  
OPM COBOL example B-61  
OPM RPG example B-71  
Retrieve File Override Information (QDMRTVFO) API  
use of 8-6  
fixed-length fields  
Retrieve Job Description Information (QWDRJOBD)  
API—example 3-29  
example 4-7  
variable-length fields  
Retrieve Library Description (QLIRLIBD) API 8-15  
Retrieve Object Description (QUSROBJD) API 8-15  
ILE C example B-94  
example 4-8  
offsets example 4-8  
Report Software Error (QpdReportSoftwareError)  
API 8-19  
ILE COBOL example B-101  
ILE RPG example B-106  
with pointers B-122  
OPM COBOL example B-101  
OPM RPG example 5-4  
ILE C example 6-7  
ILE COBOL example B-122  
ILE RPG example B-126  
reporting  
Retrieve Object Description (RTVOBJD)  
command 8-15  
Retrieve Pointer to User Space (QUSPTRUS) API  
example B-66  
software error (ILE API with pointers)  
ILE C example 6-7  
ILE C example B-94  
ILE COBOL example B-122  
ILE RPG example B-126  
software error (OPM API without pointers)  
ILE C example 6-2  
ILE COBOL example B-101  
ILE RPG example B-106  
OPM COBOL example B-61, B-101  
OPM RPG example 5-4, B-71  
Retrieve Problem Log Entry  
(QsxRetrieveProblemLogEntry) API 8-19  
ILE RPG example B-119  
OPM COBOL example B-112  
OPM RPG example B-116  
Index X-25  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
Retrieve User Space (QUSRTVUS) API 2-13  
used with pointer data 2-16  
used without pointer data 2-17  
retrieving  
RTVOBJD (Retrieve Object Description)  
command 8-15  
S
See also list API  
exit information  
SAA Common Execution Environment (CEE)  
API 2-5  
ILE C example 4-13  
Save Object List (QSRSAVO) API  
use of 8-1  
saving  
ILE COBOL example B-66  
ILE RPG example B-75  
OPM COBOL example B-61  
OPM RPG example B-71  
file description to user space  
ILE C A-11  
ILE COBOL example B-152  
ILE RPG example B-155  
OPM COBOL example B-152  
hold parameter (error code structure)  
ILE C example B-10  
user index 8-14  
user queue 8-13  
user space 8-14  
Search System Directory (QOKSCHD) API 8-15  
security  
handle 2-12  
security APIs  
example  
List Objects That Adopt Owner Authority  
(QSYLOBJP) 5-12  
use of 8-20  
ILE COBOL example B-12  
ILE RPG example B-14  
OPM COBOL example B-12  
OPM RPG example 3-11  
hold parameter (exception message)  
ILE C example B-2  
ILE COBOL example B-4  
ILE RPG example B-6  
OPM COBOL example B-4  
OPM RPG example 3-6  
information using receiver variable 2-23  
information using user space 2-25  
job description information 3-29  
pointer to user space  
selecting  
high-level language to use 2-3  
semaphore  
definition 8-23  
semget()  
use of 8-23  
server program 8-28  
Set COBOL Error Handler  
(QlnSetCobolErrorHandler) API  
ILE COBOL example B-122  
Set COBOL Error Handler (QLRSETCE) API  
OPM COBOL example B-112  
setting  
example B-66  
OPM COBOL example B-61  
OPM RPG example B-71  
returned information  
continuation handle 2-25  
receiver variable 2-23  
user space 2-13, 2-25  
returning  
See list API  
See retrieve API  
REXX language  
data type use 2-3, 2-4  
RPG call statement  
breakpoints  
MI instruction program 7-7  
COBOL error handler  
ILE COBOL example B-122  
OPM COBOL example B-112  
declare statements  
MI instruction program 7-2  
entry point  
MI instruction program 7-2  
shared memory  
definition 8-23  
shmget()  
use of 8-23  
signal  
definition 8-23  
differences from UNIX systems 8-25  
signal action  
parameter example 3-2  
RPG example  
accessing field value in variable-length array 3-19  
accessing HOLD attribute 3-17  
handling errors as escape messages 3-8  
retrieving hold parameter  
error code structure 3-11  
exception message 3-6  
RPG language  
definition 8-24  
signal action vector  
definition 8-24  
signal APIs  
data type use 2-3, 2-4  
example  
kill()  
use of 8-24  
changing user space 2-21  
X-26 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
signal APIs (continued)  
OS/400 signal management 8-24  
Qp0sEnableSignals()  
use of 8-24  
software product APIs (continued)  
Generate CD-ROM Premastering Information  
(QlpGenerateCdPremasteringInfo, QLPCDINF) API  
(continued)  
raise()  
use of 8-21  
use of 8-24  
use of 8-23  
signal controls  
Handle CD-ROM Premastering State  
(QlpHandleCdState, QLPCDRST) API  
use of 8-21  
definition 8-24  
use of 8-20  
signal default action  
definition 8-24  
signal monitor  
source include file  
QSYSINC library 2-28  
space  
definition 8-24  
See also user space  
Simple Network Management Protocol (SNMP) APIs  
SNMP manager APIs  
use of 8-25  
locking 2-16  
spooled file APIs  
Open List of Spooled Files (QGYOLSPL) API  
use of 8-29  
use of 8-18  
SNMP subagent APIs  
use of 8-25  
use of 8-25  
spooling  
size  
internal spooled file identifier 2-12  
Start Pass-Through (QPASTRPT) API 8-29  
Start Problem Log Services  
(QsxStartProblemLogServices) API 8-19  
starting  
of user space 8-14  
SNA Management Services Transport (SNA/MS  
Transport) APIs  
use of 8-10  
SNA/Management Services Transport (SNA/MS  
Transport) APIs  
use of 8-10  
SNA/MS Transport (SNA/Management Services  
Transport) APIs  
use of 8-10  
SNADS file server APIs  
use of 8-16  
instruction stream  
MI instruction program 7-3  
static storage 7-36  
stream file  
in example program B-175  
structure used in programming languages 2-3  
syntax  
See format  
SNMP (Simple Network Management Protocol) APIs  
SNMP manager APIs  
use of 8-25  
system  
index 2-30  
performance 2-31  
SNMP subagent APIs  
use of 8-25  
system domain  
object types 2-26  
use of 8-25  
sockets APIs  
system function of APIs 1-3  
system include (QSYSINC) library  
description 2-28  
datagrams 8-26  
raw sockets 8-26  
example of header file 4-2  
member name 2-28  
Systems Network Architecture Management Ser-  
vices Transport APIs  
use of 8-10  
sequenced-packet sockets 8-26  
stream sockets 8-26  
use of 8-26  
software product  
packaging  
example of CL program for creating objects and  
library A-2  
T
tasks using APIs  
ILE C example B-129  
ILE COBOL example B-136  
ILE RPG example B-144  
introduction of OPM RPG example A-1  
OPM COBOL example B-136  
OPM RPG example A-3  
software product APIs  
Generate CD-ROM Premastering Information  
(QlpGenerateCdPremasteringInfo, QLPCDINF) API  
packaging your own software products  
CL program example for creating objects and  
library A-2  
ILE C example B-129  
ILE COBOL B-136  
ILE RPG example B-144  
introduction of OPM RPG example A-1  
OPM COBOL B-136  
Index X-27  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
tasks using APIs (continued)  
packaging your own software products (continued)  
OPM RPG A-3  
Unlock Object (UNLOCK) MI instruction 2-16  
Unlock Space Location (UNLOCKSL) MI  
instruction 2-16  
retrieving file description to user space A-11  
ILE COBOL example B-152  
ILE RPG example B-155  
OPM COBOL example B-152  
using data queues versus user queues A-15  
working with data queues  
UNLOCKSL (Unlock Space Location) MI  
instruction 2-16  
Update Client Information (QZCAUPDC,  
QzcaUpdateClientInfo) API  
use of 8-2  
updating  
ILE COBOL example B-165  
ILE RPG example B-172  
OPM COBOL example B-165  
OPM RPG example B-169  
Tutorial System Support course 8-29  
type-ahead  
See changing  
User Application Administration exit program 8-16  
user domain  
object types 2-26  
user index  
definition 8-13  
definition 8-28  
error recovery 2-30  
saving and restoring 8-14  
user index APIs  
use of 8-13  
user index considerations 2-30  
user interface APIs  
U
understanding  
API description 3-2  
authorities and locks 3-2  
error messages 3-5  
field descriptions 3-5  
format 3-5  
use of 8-27  
user interface manager APIs  
DDS advantages over UIM 8-28  
UIM advantages over DDS 8-27  
use of 8-27  
optional parameter group 3-5  
parameters 3-2  
user queue  
required parameter group 3-3  
MI MICRTPG2 program 7-18  
MICRTPG program 7-16  
UNIX-type APIs  
definition 8-13  
ILE C example A-15  
saving and restoring 8-13  
user queue APIs  
use of 8-13  
user space  
environment variable APIs  
use of 8-21  
examples B-175  
See also receiver variable  
changing  
example 2-17 2-21  
concept 2-13  
continuation handle 2-25  
definition 2-16, 8-14  
format 2-14  
ILE C example A-11  
list API 2-13  
manipulating with pointers 2-16  
manipulating without pointers 2-17  
pointer 2-16, 8-14  
ILE C B-175  
ILE COBOL B-178  
ILE RPG B-183  
—
integrated file system APIs  
use of 8-22  
interprocess communications APIs  
use of 8-22  
process-related APIs  
use of 8-27  
signal APIs  
use of 8-23  
Simple Network Management Protocol (SNMP) APIs  
SNMP manager APIs 8-25  
SNMP subagent APIs 8-25  
use of 8-25  
sockets APIs  
use of 8-26  
use of 8-21  
retrieve API 2-25  
retrieving file description to  
ILE COBOL example B-152  
ILE RPG example B-155  
OPM COBOL example B-152  
saving and restoring 8-14  
size 8-14  
UNIX-type environment  
APIs for 2-6  
UNLOCK (Unlock Object) MI instruction 2-16  
usage information 2-16  
user space APIs  
Change User Space (QUSCHGUS)  
effect on user space 2-17  
example 2-20, 2-21  
X-28 System API Programming V4R1  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Index  
user space APIs (continued)  
Change User Space (QUSCHGUS) (continued)  
used with pointer data 2-16  
used without pointer data 2-17  
Create User Space (QUSCRTUS)  
example (listing database file members) 2-22  
example (receiving error messages) 2-10  
Retrieve User Space (QUSRTVUS)  
used with pointer data 2-16  
used without pointer data 2-17  
use of 8-14  
work management APIs (continued)  
use of 8-28  
work station support APIs  
use of 8-28  
Work with Filter Action Entry (WRKFTRACNE)  
command 8-11  
Work with Problem (QPDWRKPB) API 8-19  
Work with Registration Information (WRKREGINF)  
command 2-27  
working with  
data queues  
using  
ILE COBOL example B-165  
ILE RPG example B-172  
OPM COBOL example B-165  
OPM RPG example B-169  
data queues versus user queues  
ILE C example A-15  
exit programs 2-27  
integrated file system  
writing  
examples B-175  
ILE C example B-175  
machine interface (MI) program  
beginning instruction stream 7-22  
calling CL05 program 7-18  
ILE COBOL example B-178  
ILE RPG example B-183  
keys with List Spooled Files API  
ILE C example B-33  
ILE COBOL example B-38  
ILE RPG example B-42  
OPM COBOL example B-38  
UNIX-type APIs  
common programming techniques 7-32  
compiling program 7-4  
creating MI version of CLCRTPG program 7-11  
creating MICRTPG program 7-18  
creating MICRTPG2 program 7-27  
creating program 7-5, 7-6  
debugging program 7-7  
examples B-175  
declaring pointers 7-17  
ILE C example B-175  
ILE COBOL example B-178  
ILE RPG example B-183  
declaring structure for MICRTPG program 7-16  
defining external call 7-17  
enhanced version of MICRTPG program 7-18  
handling exceptions 7-9  
MICRTPG program 7-16  
V
MICRTPG2 complete program (enhanced) 7-28  
MICRTPG2 complete program example 7-23  
program storage 7-36  
setting breakpoints 7-7  
setting declare statements 7-2  
setting entry point 7-2  
variable  
changing 2-3, 2-4  
variable-length record  
definition 2-24  
variable-length structure  
example 4-3  
starting instruction stream 7-3  
WRKFTRACNE (Work with Filter Action Entry)  
command 8-11  
WRKREGINF (Work with Registration Information)  
command 2-27  
virtual terminal  
definition 8-28  
virtual terminal APIs  
use of 8-28  
VisualAge C++ for OS/400  
data type use 2-3  
VisualAge C++ for OS/400 language  
data type use 2-4  
Z
zoned decimal data 2-3  
W
work management  
internal job identifier 2-12  
original program model (OPM) example 3-1  
work management APIs  
Retrieve Job Description Information  
(QWDRJOBD) 3-29  
Index X-29  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Reader Comments—We'd Like to Hear from You!  
AS/400 Advanced Series  
System API Programming  
Version 4  
Publication No. SC41-5800-00  
Overall, how would you rate this manual?  
Very  
Dissatis-  
fied  
Very  
Satisfied  
Dissatis-  
fied  
Satisfied  
Overall satisfaction  
How satisfied are you that the information in this manual is:  
Accurate  
Complete  
Easy to find  
Easy to understand  
Well organized  
Applicable to your tasks  
T H A N K  
Y O U !  
Please tell us how we can improve this manual:  
May we contact you to discuss your responses? __ Yes __ No  
Phone: (____) ___________ Fax: (____) ___________ Internet: ___________  
To return this form:  
Ÿ Mail it  
Ÿ Fax it  
United States and Canada: 800+937-3430  
Other countries: (+1)+507+253-5192  
Ÿ Hand it to your IBM representative.  
Note that IBM may use or distribute the responses to this form without obligation.  
Name  
Address  
Company or Organization  
Phone No.  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Cut or Fold  
Along Line  
Reader Comments—We'd Like to Hear from You!  
SC41-5800-00  
IBM  
Fold and Tape  
Please do not staple  
Fold and Tape  
NO POSTAGE  
NECESSARY  
IF MAILED IN THE  
UNITED STATES  
BUSINESS REPLY MAIL  
FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK  
POSTAGE WILL BE PAID BY ADDRESSEE  
ATTN DEPT 542 IDCLERK  
IBM CORPORATION  
3605 HWY 52 N  
ROCHESTER MN 55901-9986  
Fold and Tape  
Please do not staple  
Fold and Tape  
Cut or Fold  
Along Line  
SC41-5800-00  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Download from Www.Somanuals.com. All Manuals Search And Download.  
IBM  
Printed in the United States of America  
on recycled paper containing 10%  
recovered post-consumer fiber.  
SC41-58ðð-ðð  
Download from Www.Somanuals.com. All Manuals Search And Download.  
Spine information:  
IBM  
AS/400 Advanced Series  
System API Programming  
Version 4  
Download from Www.Somanuals.com. All Manuals Search And Download.  

Graco Inc Pressure Washer 1035 User Manual
Grizzly Noise Reduction Machine TR8803 User Manual
Hafler Stereo Amplifier DH 200 User Manual
Haier Refrigerator PRTS User Manual
Honeywell Tablet Accessory SL22 42 User Manual
Hotpoint Outdoor Gas Burner GX 641 F G K User Manual
Hotpoint Oven SD 52K SD 52 User Manual
HP Hewlett Packard Photo Printer Z6600 User Manual
HP Hewlett Packard Server 595166 001 User Manual
Hunter Fan Outdoor Ceiling Fan 41462 01 User Manual