IBM Version 4 RZABPMST User Manual To The B175aa40 2073 490d 99cc 71e55a67baee

User Manual: IBM Version 4 to the manual

Open the PDF directly: View PDF .
Page Count: 505

Download
Open PDF In Browser	View PDF

AS/400 Advanced Series

IBM

System API Programming
Version 4

SC41-5800-00

AS/400 Advanced Series

IBM

System API Programming
Version 4

SC41-5800-00

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 IDCLERK@RCHVMW2.VNET.IBM.COM; 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.

Contents
Notices . . . . . . . . . . . . . . .
Programming Interface Information
Trademarks . . . . . . . . . . . . .

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

About System API Programming (SC41-5800)
Who Should Use This Book . . . . . . . . . . . .
Prerequisite and Related Information . . . . . .
Information Available on the World Wide Web .

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

Chapter 1. Application Programming Interface—Overview
API Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . .
Using APIs—Benefits . . . . . . . . . . . . . . . . . . . . . . .
System APIs or CL Commands—When to Use Each . . . . .
Actions and System Functions of APIs . . . . . . . . . . . . .
Related Information
. . . . . . . . . . . . . . . . . . . . . . . .

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

Chapter 2. Getting Started with APIs . . . . . . . . . . . . . .
Locating the API to Use . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . .
Selecting the High-Level Language To Use
API Environments
. . . . . . . . . . . . . . . . . . . . . . . . . .
APIs for the Original Program Model Environment . . . . . .
APIs for the Integrated Language Environment . . . . . . . .
APIs for the ILE Common Execution Environment (CEE) . .
APIs for the UNIX Environment . . . . . . . . . . . . . . . . .
API Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Parameter Passing . . . . . . . . . . . . . . . . . . . . . . . .
Parameter Classification . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . .
Manipulating a User Space with Pointers . . . . . . . . . . .
. . . . . . . . .
Manipulating a User Space without Pointers
Additional Information about List APIs and a User Space . .
Listing Database File Members with a CL Program—Example
Receiver Variables . . . . . . . . . . . . . . . . . . . . . . . . . .
Bytes Available and Bytes Returned Fields . . . . . . . . . .
Keyed Interface . . . . . . . . . . . . . . . . . . . . . . . . . .
User Space Alternative . . . . . . . . . . . . . . . . . . . . . .
Related Information . . . . . . . . . . . . . . . . . . . . . . . .
Continuation Handle . . . . . . . . . . . . . . . . . . . . . . . . .
Using a Continuation Handle
. . . . . . . . . . . . . . . . . .
Domain Concepts
. . . . . . . . . . . . . . . . . . . . . . . . . .
Exit Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exit Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
APIs and the QSYSINC Library
. . . . . . . . . . . . . . . . . .
APIs and the QUSRTOOL Library . . . . . . . . . . . . . . . . .
User Index Considerations . . . . . . . . . . . . . . . . . . . . .
 Copyright IBM Corp. 1997

xi
xii
xii
xiii
xiii
xiii
xiii
1-1
1-1
1-2
1-3
1-3
1-4

2-1
. 2-1
. 2-3
. 2-4
. 2-4
. 2-5
. 2-5
. 2-6
. 2-6
. 2-7
. 2-8
. 2-8
2-10
2-12
2-13
2-14
2-15
2-16
2-17
2-22
2-22
2-23
2-23
2-24
2-25
2-25
2-25
2-25
2-26
2-27
2-27
2-28
2-30
2-30

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

iii

APIs and Internal System Objects
Performance Considerations . .

2-31
2-31

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

Chapter 3. Common Information across APIs—Basic (OPM) Example .
Original Program Model (OPM) API–Scenario . . . . . . . . . . . . . . . . . .
Finding the API Name to Use . . . . . . . . . . . . . . . . . . . . . . . . . .
Description of an API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Extracting a Field from the Format . . . . . . . . . . . . . . . . . . . . . . .
Retrieving the Hold Parameter (Exception Message)—OPM RPG Example
Retrieving the Hold Parameter (Error Code Structure)—OPM RPG
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing the HOLD Attribute—OPM RPG Example . . . . . . . . . . . . . .
Accessing a Field Value (Initial Library List)—OPM RPG Example
. . . .
Using Keys with List Spooled Files API—Example
. . . . . . . . . . . . . . .
Processing Lists That Contain Data Structures . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . .
Retrieve Job Description Information API—Example
Authorities and Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
Required Parameter Group
JOBD0100 Format
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.

3-1
3-1
3-1
3-2
3-5
3-5
3-5
3-5
3-6
3-11
3-17
3-19
3-24
3-29
3-29
3-30
3-30
3-30
3-32
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 . . . . . . . . . . . . . . . . . . .
Characteristics of a List API . . . . . . . . . . . . . . . .
General Data Structure . . . . . . . . . . . . . . . . .
Processing a List . . . . . . . . . . . . . . . . . . . . . .
List Object API—OPM RPG Example . . . . . . . . . .
List Objects That Adopt Owner Authority API—Example
Authorities and Locks . . . . . . . . . . . . . . . . . .
Required Parameter Group
. . . . . . . . . . . . . .
User Space Variables . . . . . . . . . . . . . . . . . .
Error Messages . . . . . . . . . . . . . . . . . . . . .

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

Chapter 6. Original Program Model (OPM) and Integrated Language
Environment (ILE) Differences . . . . . . . . . . . . . . . . . . . . . .
Contrasting OPM and ILE APIs . . . . . . . . . . . . . . . . . . . . . . . .
API Name
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

System API Programming V4R1

5-1
. 5-1
. 5-1
. 5-4
. 5-4
5-12
5-12
5-12
5-14
5-16

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

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

6-1
6-1
6-1
6-1
6-1

Pointers

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

Chapter 7. Machine Interface Programming . . . . . . . . . .
Machine Interface Instructions—Introduction . . . . . . . . . . . .
Writing an MI Program—Example . . . . . . . . . . . . . . . . . .
Setting the Entry Point . . . . . . . . . . . . . . . . . . . . . . .
Setting the Declare Statements . . . . . . . . . . . . . . . . . .
Starting the Instruction Stream
. . . . . . . . . . . . . . . . . .
Compiling a Program
. . . . . . . . . . . . . . . . . . . . . . . . .
Using CLCRTPG to Create an MI Program . . . . . . . . . . .
Creating the MI Example Program . . . . . . . . . . . . . . . .
Debugging the MI Program
. . . . . . . . . . . . . . . . . . . .
Setting Breakpoints in the MI Program . . . . . . . . . . . . . .
Handling Exceptions in the MI Program . . . . . . . . . . . . .
Creating an MI Version of CLCRTPG . . . . . . . . . . . . . . . .
Source for the CL03 Program . . . . . . . . . . . . . . . . . . .
Source for the CL04 Program . . . . . . . . . . . . . . . . . . .
Source for the CL05 Program . . . . . . . . . . . . . . . . . . .
Source for the MICRTPG Program . . . . . . . . . . . . . . . .
Understanding the MICRTPG Program (by Sections of Code)
Enhanced Version of the MICRTPG Program . . . . . . . . . . .
Understanding the MICRTPG2 Program (by Sections of Code)
Beginning the Instruction Stream . . . . . . . . . . . . . . . . .
MICRTPG2 Complete Program—MI Code Example . . . . . .
Creating the MICRTPG2 Program . . . . . . . . . . . . . . . . . .
Handling Exceptions in the MICRTPG2 Program . . . . . . . .
MI Common Programming Techniques—Examples . . . . . . . .
AS/400 Program Storage . . . . . . . . . . . . . . . . . . . . . . .
Chapter 8. Use of OS/400 APIs . . . . . . . . . . .
Backup and Recovery APIs . . . . . . . . . . . . .
Client Support APIs . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . .
Communications APIs
. . . . . . . . . . . . . . . . . .
Configuration APIs
Debugger APIs
. . . . . . . . . . . . . . . . . . . .
Dynamic Screen Manager APIs . . . . . . . . . . .
Edit Function APIs
. . . . . . . . . . . . . . . . . .
File APIs . . . . . . . . . . . . . . . . . . . . . . . .
Hardware Resource APIs
. . . . . . . . . . . . . .
Hierarchical File System (HFS) APIs . . . . . . . .
High-Level Language APIs . . . . . . . . . . . . . .
Integrated Language Environment (ILE) CEE APIs
Journal and Commit APIs . . . . . . . . . . . . . .
Message Handling APIs . . . . . . . . . . . . . . .
National Language Support APIs . . . . . . . . . .
Network Management APIs . . . . . . . . . . . . .
Object APIs
. . . . . . . . . . . . . . . . . . . . . .
Office APIs . . . . . . . . . . . . . . . . . . . . . . .
Operational Assistant APIs . . . . . . . . . . . . . .
Performance Collector APIs . . . . . . . . . . . . .
Print APIs . . . . . . . . . . . . . . . . . . . . . . . .
Problem Management APIs . . . . . . . . . . . . .
Program and CL Command APIs . . . . . . . . . .
Registration Facility APIs . . . . . . . . . . . . . . .

6-2

7-1
7-1
. 7-2
. 7-2
. 7-2
. 7-3
. 7-4
. 7-5
. 7-6
. 7-7
. 7-7
. 7-9
7-11
7-13
7-13
7-14
7-15
7-16
7-18
7-18
7-22
7-23
7-27
7-27
7-32
7-36

8-1
. 8-1
. 8-1
. 8-2
. 8-3
. 8-3
. 8-4
. 8-5
. 8-5
. 8-6
. 8-6
. 8-6
. 8-7
. 8-8
. 8-8
. 8-9
. 8-9
8-11
8-15
8-17
8-17
8-17
8-18
8-19
8-19

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

Contents

Security APIs
. . . . . . .
Software Product APIs . .
UNIX-Type APIs . . . . . .
User Interface APIs . . . .
Virtual Terminal APIs . . .
Work Management APIs .
Work Station Support APIs
Miscellaneous APIs . . . .

Chapter 9. Common API Programming Errors . . . . . . . . . . .
Using the Error Code Parameter . . . . . . . . . . . . . . . . . . . . .
Using the Error Code Parameter—Example of Incorrect Coding .
Using the Error Code Parameter—Example of Correct Coding . .
Defining Data Structures
. . . . . . . . . . . . . . . . . . . . . . . . .
Defining a Data Structure—Example of Incorrect Coding . . . . .
Defining A Data Structure—Example of Correct Coding . . . . . .
Defining Receiver Variables . . . . . . . . . . . . . . . . . . . . . . . .
Defining Receiver Variables—Example of Incorrect Coding . . . .
Defining Receiver Variables—Example of Correct Coding . . . . .
Defining List Entry Format Lengths
. . . . . . . . . . . . . . . . . . .
Defining List Entry Format Lengths—Example of Incorrect Coding
Defining List Entry Format Lengths—Example of Correct Coding
Using Null Pointers with OPM APIs . . . . . . . . . . . . . . . . . . .
Using Null Pointers with OPM APIs—Example of Incorrect Coding
Using Null Pointers with OPM APIs—Example of Correct Coding
Defining Byte Alignment . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining Byte Alignment—Example of Incorrect Coding . . . . . .
Defining Byte Alignment—Example of Correct Coding . . . . . . .
Using Offsets in a User Space . . . . . . . . . . . . . . . . . . . . . .
Using Offsets in a User Space—Example of Incorrect Coding . .
Using Offsets in a User Space—Example of Correct Coding . . .
Coding for New Function . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . .
Coding for New Function—Example of Incorrect Coding
Coding for New Function—Example of Correct Coding . . . . . .
Appendix A. Performing Tasks Using APIs—Examples .
Packaging Your Own Software Products . . . . . . . . . . . .
Retrieving a File Description to a User Space—ILE C Example
Using Data Queues versus User Queues . . . . . . . . . . . .
Data Queue—ILE C Example . . . . . . . . . . . . . . . . .
User Queue—ILE C Example . . . . . . . . . . . . . . . . .

System API Programming V4R1

9-1
9-2
. 9-2
. 9-3
. 9-5
. 9-5
. 9-7
9-10
9-10
9-12
9-14
9-14
9-16
9-18
9-18
9-19
9-22
9-22
9-25
9-27
9-27
9-31
9-36
9-36
9-43

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

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

Appendix B. Original Examples in Additional Languages . . . . . . . . .
Original Program Model (OPM) APIs—Examples . . . . . . . . . . . . . . . .
Retrieving the Hold Parameter (Exception Message)—ILE C Example . .
Retrieving the Hold Parameter (Exception Message)—ILE COBOL Example
Retrieving the Hold Parameter (Exception Message)—ILE RPG Example
Handling Error Conditions—ILE RPG Example . . . . . . . . . . . . . . . .
Retrieving the Hold Parameter (Error Code Structure)—ILE C Example
.
Retrieving the Hold Parameter (Error Code Structure)—ILE COBOL
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving the Hold Parameter (Error Code Structure)—ILE RPG Example
Accessing the HOLD Attribute—ILE C Example
. . . . . . . . . . . . . . .
Accessing the HOLD Attribute—ILE COBOL Example . . . . . . . . . . . .

8-20
8-20
8-21
8-27
8-28
8-28
8-28
8-29

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

A-1
A-1
A-11
A-15
A-16
A-17
B-1
B-2
B-2
B-4
B-6
B-8
B-10
B-12
B-14
B-16
B-18

Accessing the HOLD Attribute—ILE RPG Example
. . . . . . . . . . . . . B-21
Accessing a Field Value (Initial Library List)—ILE C Example
. . . . . . . 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 . . . . . . B-38
Using Keys with List Spooled Files API—ILE RPG Example . . . . . . . . B-42
Integrated Language Environment (ILE) APIs—Examples . . . . . . . . . . . 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 . B-71
Retrieve Exit Point and Exit Program Information—ILE RPG Example
. . 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
. . . . . . . . . . . . . . . . . . . . . B-106
List Object API—ILE RPG Example
OPM API without Pointers—Examples
. . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . B-129
Program for Packaging a Product—ILE COBOL Example . . . . . . . . . B-136
Program for Packaging a Product—ILE RPG Example
. . . . . . . . . . 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
Data Queue—ILE COBOL Example . . . . . . . . . . . . . . . . . . . . . B-165
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 . . . . . . . . . .
General-Purpose Books . . . .
OS/400 API Books . . . . . . .
Programming Language Books
Index

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

H-1
H-1
H-1
H-2

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

X-1

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

Contents

vii

viii

System API Programming V4R1

Figures
1-1.
2-1.
2-2.
2-3.
2-4.
2-5.
5-1.
7-1.
8-1.
9-1.
A-1.
A-2.
B-1.
B-2.
B-3.
B-4.
B-5.
B-6.

 Copyright IBM Corp. 1997

How APIs Fit into the AS/400 Business Computing System Structure 1-2
OPM and ILE API Verbs and Abbreviations . . . . . . . . . . . . . . . 2-2
Language Selection Considerations — Data Types . . . . . . . . . . . 2-3
Language Selection Considerations — Call Conventions
. . . . . . . 2-4
Methods for Passing Parameters . . . . . . . . . . . . . . . . . . . . . 2-7
Include Files Shipped with the QSYSINC Library . . . . . . . . . . . 2-28
General Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Program Flow for Creating the MICRTPG Program . . . . . . . . . . 7-12
Simplified Sequence of Events for a Sockets Program Example . . 8-26
Common Programming Errors . . . . . . . . . . . . . . . . . . . . . . . 9-1
ABC Software Packaging . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Steps for Creating a Software Product . . . . . . . . . . . . . . . . . A-2
Original Program Model (OPM) API Examples from Chapter 3 . . . B-1
Integrated Language Environment (ILE) API Examples from Chapter
4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1
List API Examples from Chapter 5
. . . . . . . . . . . . . . . . . . .
B-1
Pointer API Examples from Chapter 6 . . . . . . . . . . . . . . . . . B-1
Performing Tasks Using API Examples from Appendix A . . . . . . B-2
. . . . . . . . . . . . . . . . . . . . . . . .
B-2
UNIX-Type API Examples

System API Programming V4R1

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 furnishing 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 interoperability 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

Programming Interface Information
This publication is intended to help experienced programmers create application programs. This publication 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
Application System/400
APPN
AS/400
C/400
COBOL/400
DB2
FORTRAN/400
GDDM
IBM
Integrated Language Environment
NetView
OfficeVision

Operating System/2
Operating System/400
Operational Assistant
OS/400
PrintManager
RPG IV
RPG/400
SAA
SOM
SOMobjects
System/38
System/370
Systems Application Architecture
Ultimedia
400

Microsoft, Windows, and the Windows 95 logo are trademarks or registered trademarks of Microsoft Corporation.
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

About System API Programming (SC41-5800)
This book provides introductory, conceptual, and
guidance information about how to use OS/400
application programming interfaces (APIs) with
your application programs. It includes examples
and discusses the following:
Benefits of using APIs
When to use APIs versus CL commands
How to locate an API in the System API Reference book, SC41-5801
Which high-level language (HLL) to use for
APIs
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
Tips for common API programming errors
This book provides introductory and guidance
information only; it does not contain API reference
information. For reference information, see the
System API Reference book.
For a list of related publications, see the
“Bibliography” on page H-1.

Prerequisite and Related
Information
For information about other AS/400 publications
(except Advanced 36), see either of the following:
The Publications Reference book, SC41-5003,
in the AS/400 Softcopy Library.
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.

Information Available on the
World Wide Web
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:
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.

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

xiv

System API Programming V4R1

API Compatibility

Chapter 1. Application Programming Interface—Overview
Application programming interfaces (APIs) that are used on AS/400 business computing systems provide paths into system functions. APIs are intended for experienced 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 compatibility, 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 established by industry standards organizations where the degree of compatibility is
determined by the organizations.

 Copyright IBM Corp. 1997

1-1

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

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 analyzer.
– Using the system function in the ILE C language that processes commands.

1-2

System API Programming V4R1

Your application is more straightforward if you are coding in a programming language 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 programmer 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 interface.
Some APIs have no equivalent CL command. These APIs have been provided in
areas where customers and business partners have indicated that they need highlevel 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

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 documentation for more information.
Client Access
OfficeVision for AS/400
OSI File Services, OSI Message Services, and OSI Communications Subsystem
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

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 information 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 component 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

Figure 2-1. OPM and ILE API Verbs and Abbreviations

Verb

Abbreviation

Verb

Abbreviation

access

Put

PUT, Put

Add

ADD, Add

PutGet

Change

C, CHG, Chg, ch

Query

Q, QRY, Qry

Check

C, CHK, CHECK

Read

RD, Read, read

Clear

CLR, Clr

Receive

R, RCV, RECV

CLO, close

RG, REG, R, Register

Complete

Cmp

Release

RLS

Control

CTL

Remove

RMV, Rmv, Remove, rm

Convert

CVT, CVRT, Convert

Rename

RNM, rename

Copy

CPY, Cpy

Report

Create

CRT, Crt, create

Resend

RSN

Customize

CST

Reserve

Delete

DLT, Dlt

Restore

Deregister

DRG, Deregister

reset

rewind

Disable

Resize

Rsz

Display

DSP, Dsp

Retrieve

R, RTV, Rtv, Retrieve

Dump

DMP, Dump

Roll

duplicate

dup

Save

SAV, Sav, Save

Edit

EDT

Scan for

SCAN

Enable

Send

S, SND, SEND, Send

End

END, End

Set

SET, Set

Execute (run)

EXC, EXEC

Shift

Shf

Filter

FTR

Start

Start, STR, Str

Force

FRC

Submit

Generate

GEN

Switch

Set

Get (fetch)

G, GET, Get, get

Test

Initialize

Inz

Toggle

Tgl

Insert

Ins

Transform

link

Translate

TR, TRN, XLATE

List

L, LST, List

truncate

Lock/unlock

LUL

Unregister

make

Update

UPD

Map

Validate

Maximize

Mxz

Work with

WK, WRK, Wrk

Move

MOV, Mov

Write

WRT, Wrt, write, W

Open

OPN, open

Pad

Note: Refer to “APIs for the ILE Common Execution Environment (CEE)” on page 2-5 for information about ILE CEE API names.

PRT, Prt

2-2

System API Programming V4R1

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 programs (*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

Language1

Pointers

BASIC (PRPQ
5799-FPK)
ILE C
VisualAge C++ for
OS/400

X
X

Binary
2

Binary
4

Character

Zoned
Decimal

Packed
Decimal

Floating
Point

X
X

Single
Array

Exception
Handling

Structures

X10

ILE CL

COBOL

ILE COBOL

Pascal (PRPQ
5799-FRJ)

PL/I (PRPQ
5799-FPJ)

REXX

RPG
ILE RPG

Notes:
1
2
3
4
5
6
7
8
9
10

You cannot develop Cross System Product (CSP) programs on an AS/400 system. However, you can develop CSP programs on a System/370 system and run them on your AS/400 system.
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.
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.
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 compatible with the decimal() data type.

Chapter 2. Getting Started with APIs

2-3

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

Language1

Function
Return
Values2

BASIC

Pass by
Reference

Pass
by
Value

ILE C

VisualAge C++ for OS/400

ILE CL

COBOL

Pascal

PL/I

REXX

ILE COBOL

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 passby-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:

2-4

Start with the letter Q.
Are followed by a 2- or 3-letter internal component identifier.
Are limited to 8 characters.
Must be uppercase.

System API Programming V4R1

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 languages
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 specific 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

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 supporting an open environment on the AS/400 system. The socket functions and integrated 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 standards 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 specified 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

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 documentation 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
by value, indirectly

by reference

The value of the data object is placed directly into the
parameter list.
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.
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
pointer

the actual argument
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 proChapter 2. Getting Started with APIs

2-7

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 (indirectly) 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 structures 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 parameter 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

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 contains the following:
Field

INPUT

OUTPUT

Bytes provided

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 parameter (see “Receiving the Error Code with the Exception Data—Example”).
Field

INPUT

OUTPUT

Bytes provided

Bytes available

Ignored

Exception ID

Ignored

CPF7B03

Reserved

Ignored

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 bytesprovided 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

OUTPUT

Bytes provided

116

Bytes available

Ignored

Chapter 2. Getting Started with APIs

2-9

Field

INPUT

OUTPUT

Exception ID

Ignored

CPF7B03

Reserved

Ignored

Exception data

Ignored

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 following:
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
\/
/\
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

MSGID(CPF3Cð1) EXEC(GOTO CMDLBL(GETDIAGS))

CALL

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

IF
ELSE
SNDPGMMSG
GOTO
ENDDO

2-10

System API Programming V4R1

PGMQ(\SAME) MSGQ(\PGMQ) MSGTYPE(\DIAG) +
WAIT(3) RMV(\NO) MSGDTA(&MSGDATA) +
MSGDTALEN(&MSGLEN) MSGID(&MSGID)
COND(&MSGID = '
') THEN(GOTO +
CMDLBL(ALLDONE))
CMD(DO)
MSG(&MSGID)
CMDLBL(GETDIAGS)

\/
\/
\/
\/
\/
\/

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\
ERROR CODE PARAMETER.
\
H\
\
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\
1
INPUT
PATHNM - NAME OF DIRECTORY
\
H\
2
INPUT
PATHLN - LENGTH OF PATHNM PARAMETER
\
H\
3
OUTPUT SUCCES - INDICATES SUCCESS OR FAILURE
\
H\
'ð' SUCCESS
\
H\
'1' FAILURE
\
H\ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ISUCCES
DS
I
B
1
4ðRETCOD
IPLENG
DS
I
B
1
4ðPATHLN
IBINS
DS
I
B
1
4ðRETDTA
I
B
5
8ðATTRLN
IERROR
DS
I
B
1
4ðBYTPRV
I
B
5
8ðBYTAVA
I
9 15 ERRID
I
16 16 ERR###
I
17 272 INSDTA
C
\ENTRY
PLIST
C
PARM
PATHNM 8ð
C
PARM
PLENG
C
PARM
SUCCES
C\
C\ INITIALIZE BYTES PROVIDED AND THE ATTRIBUTE LENGTH VARIABLE
C\
C
Z-ADD272
BYTPRV
C
Z-ADDð
ATTRLN
C\
C\ RETRIEVE DIRECTORY ENTRY ATTRIBUTES
C\
C
CALL 'QHFRTVAT'
C
PARM
PATHNM
C
PARM
PATHLN
C
PARM
ATTR
1
C
PARM
ATTRLN
C
PARM
ATTR
C
PARM
ATTRLN
C
PARM
RETDTA
C
PARM
ERROR
C\
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

C
C
C
C
C\
C\
C\
C\
C\
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C
C\
C
C
C
C
C\
C\
C\
C

Z-ADDð
RETCOD
ELSE
'CPF1Fð2' IFEQ ERRID
'CPF1F22' OREQ ERRID
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
THERE IS NO NEED TO REINITIALIZE THE ERROR CODE PARAMETER.
ONLY BYTES PROVIDED IS INPUT TO THE API; IT WILL RESET THE
ERROR CODE PARAMETER FOR US. AFTER THE CALL TO QHFCRTDR,
BYTES AVAILABLE WILL EITHER BE ð IF SUCCESSFUL OR NONZERO
IF THE CREATE FAILS. WE DO NOT HAVE TO WORRY ABOUT THE
PREVIOUS ERROR CODE BEING LEFT IN THE ERROR CODE PARAMETER.
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
CALL 'QHFCRTDR'
PARM
PATHNM
PARM 2ð
PATHLN
PARM
ATTR
1
PARM ð
ATTRLN
PARM
ERROR
BYTAVA
IFEQ \ZERO
Z-ADDð
RETCOD
ELSE
Z-ADD1
RETCOD
END
ELSE
Z-ADD1
END
END

RETCOD

PROGRAM END
SETON

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 commands) 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

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. Generally, 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.

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

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 ───│─────────────────┐
│
│
│
│ Variable locations in the
1st entry ───│──┐
│
│ user space
│ 6
6
│ ─────────────────────────
│AAAAABBBBCCCDDDEEAAAABB │────5 List of entries
│BBBCCCDDDEEAAAABBBBBCCD │
│DDDEEAAAABBBBCCCDDDEE.. │
└────────────────────────┘

2-14

System API Programming V4R1

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
│ YES
┌───────5│
entries been
├───────┐
│
│
processed?
│
│
│
└────────────┬───────────┘
│
│
│NO
List is
│
6
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

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 application 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 programs 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 operation 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

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

Manipulating a User Space without Pointers

Area that will change
after using the
Change User Space
(QUSCHGUS) API

2-18

System API Programming V4R1

RV3F089-0

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

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\
AREA IN THE USER SPACE USING A POINTER
H\
H\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D\
DUSRSPCNAM
S
2ð
INZ('TEMPSPACE QTEMP
')
DNEWVALUE
S
64
INZ('Big String padded with blanks')
DUSRSPCPTR
S
\
DUSERAREA
DS
BASED(USRSPCPTR)
D CHARFIELD
1
64
D\
D\ Following QUSEC structure copied from QSYSINC library
D\
DQUSEC
DS
D\
Qus EC
D QUSBPRV
1
4B ð
D\
Bytes Provided
D QUSBAVL
5
8B ð
D\
Bytes Available
D QUSEI
9
15
D\
Exception Id
D QUSERVED
16
16
D\
Reserved
D\ End of QSYSINC copy
D\
C\
C\ Initialize Error code structure to return error ids
C\
C
Z-ADD
16
QUSBPRV
C\
C\ Set USRSPCPTR to the address of the User Space
C\
C
CALL
'QUSPTRUS'
C
PARM
USRSPCNAM
C
PARM
USRSPCPTR
C
PARM
QUSEC
C\
C\ Check for successful setting of pointer
C\
C
QUSBAVL
IFGT
ð
C\
C\ If an error, then display the error message id
C\
C
DSPLY
QUSEI
C
ELSE
C\
C\ Otherwise, update the User Space via the based structure
C\
C
MOVEL
NEWVALUE
USERAREA
C
END
C\
C\ And return to our caller
C\
C
SETON
LR
C
RETURN

2-20

System API Programming V4R1

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\
INFORMATION IN THE USER AREA IN THE USER SPACE \
H\
(FIRST 64 BYTES).
\
H\
\
H\ APIs USED: QUSCHGUS
\
H\
\
H\ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
H\ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
E
ARY
1
1 2ð
E
CHG
1
1 64
IUSRSPC
DS
I
1 1ð USNAME
I
11 2ð USLIB
I
DS
I
B
1
4ðLENDTA
I
B
5
8ðSTRPOS
C\
\
C\ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
\
C\
OPERABLE CODE STARTS HERE
\
C\
\
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
MOVELARY,1
USRSPC
C
MOVELCHG,1
NEWVAL 64
C\
\
C
Z-ADD64
LENDTA
LEN OF USERAREA
C
Z-ADD1
STRPOS
STARTING POS
C
MOVE '1'
FORCE
1
FORCE PARM
C\
\
C\ CALL THE QUSCHGUS API WHICH WILL CHANGE THE USER AREA IN THE \
C\ USER SPACE.
\
C\
\
C
CALL 'QUSCHGUS'
C
PARM
USRSPC
C
PARM
STRPOS
C
PARM
LENDTA
C
PARM
NEWVAL
C
PARM
FORCE
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
SETON
LR
C
RETRN
\\ ARY
TEMPSPACE QGPL
\\ CHG
Big String padded with blanks

Chapter 2. Getting Started with APIs

2-21

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
QGPL
' /\ USER SPACE NAME AND LIB
\/
'EXAMPLE
'
/\ EXTENDED ATTRIBUTE
\/
X'ððððð12C'
/\ SIZE OF USER SPACE
\/
' '
/\ INITIALIZATION VALUE
\/
'\CHANGE
'
/\ AUTHORITY
\/
'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
QGPL
' /\ USER SPACE NAME AND LIB
\/
'MBRLð2ðð'
/\ FORMAT NAME
\/
'QCLSRC
QGPL
' /\ DATABASE FILE AND LIBRARY \/
'M\
'
/\ MEMBER NAME
\/
'1')
/\ OVERRIDE PROCESSING
\/
ENDPGM

2-22

System API Programming V4R1

+
+
+
+
+
+

+
+
+
+
+

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 indicates 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 information that is needed. The caller knows how the information is returned by the documented 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

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 allocated.
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 information 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 associated 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 variablelength 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 examples 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

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

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 attributes 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

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 systemsupplied (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.

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

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 “Register 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 registration 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 supported, 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 contents 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

2-28

Operating
Environment

Language

File Name

Member Name (Header File)

OPM APIs

ILE C1

OPM API program name

RPG

QRPGSRC

OPM API program name or OPM
API program name with the letter
E replacing the letter Q for
members containing array definitions

ILE RPG

QRPGLESRC

OPM API program name

COBOL

QLBLSRC

OPM API name

ILE COBOL

QCBLLESRC

OPM API program name

System API Programming V4R1

Figure 2-5 (Page 2 of 2). Include Files Shipped with the QSYSINC Library
Operating
Environment

Language

File Name

Member Name (Header File)

ILE APIs

ILE C

Service program name or API
program name2

ILE RPG

QRPGLESRC

Service program name or API
program name2

ILE COBOL

QCBLLESRC

Service program name or API
program name2

ILE C

ARPA

Industry defined

ILE C

Industry defined

ILE C

NET

Industry defined

ILE C

NETINET

Industry defined

ILE C

SYS

Industry defined

UNIX type

Notes:
1
2

CEE ILE APIs are included in this part of the table.
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 programs.
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 statement; 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

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 information 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

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 characteristics. 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

Performance Considerations

2-32

System API Programming V4R1

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 foundation 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
*YES

The job is not held.
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 function. 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 alphabetical 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 information 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

nonobject information that represents data known to the system, such as job information 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 Parameters 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 variable. 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
QWDBH
PARM
RCVLEN
PARM
FORMAT
PARM
LFNAM
PARM
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 information, and you will need to find the specific location within the data structure 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

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 information 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 performance 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 information 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 specified 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 variable 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

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 specified 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 qualifier beginning in the 11th character. If you want JOBD1 in LIBX, you would
specify:
1
.
.
JOBD1

11
.
.
LIBX

2ð
.
.

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 errorcode 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

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

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 information 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 examples 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\
messages.
I\
I\Header Files Included: QUSEC - Error Code Parameter
I\
QWDRJOBD - Retrieve Job Description API
I\
I\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
I\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
I\
I\ Error Code Parameter Include for the APIs
I\
I/COPY QSYSINC/QRPGSRC,QUSEC

3-6

System API Programming V4R1

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
'SNDMSG MSG(''HOLD 1 26 CMD1
I
'value is '
I
27 36 HOLD
I I
''') TOUSR(QPGMR)'
37 51 CMD2
I\
I\ Miscellaneous Data Structure
I\
I
DS
I\
.3/
.4/
I I
39ð
B
1
4ðRCVLEN
I I
'JOBDð1ðð'
5 12 FORMAT
I\
.5/
C\
C\ Beginning of Mainline
C\
C\ Two parameters are being passed into this program.
C\
C
\ENTRY
PLIST .8/
C
PARM
JOBD
1ð
C
PARM
JOBDL 1ð
C\
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
QWDBH
Receiver Var.
C
PARM
RCVLEN
Length RCVVAR
C
PARM
FORMAT
Format Name
C
PARM
LFNAM
Qual. Job Desc
C
PARM
QUSBN
Error Code
C\
C
MOVELQWDBHN
HOLD
C\
C\ Let's tell everyone what the hold value was for this jobd.
C\
C
Z-ADD51
LENSTR 155
C
CALL 'QCMDEXC'
C
PARM
CMDSTR
C
PARM
LENSTR
C\
C
SETON
LR
C
RETRN
C\
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

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
Queue . . . . . :
QPGMR
Library . . . :
QUSRSYS
Severity . . . :
ðð
Type reply (if required), press Enter.
From . . . :
SMITH
ð7/23/94
HOLD value is \NO

System:
Program . . . . :
Library . . . :
Delivery . . . :

GENSYS9ð
\DSPMSG
\HOLD

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

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
SDS
I
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 conditions 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 errorcode 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 condition, 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\
returned
I\
I\Header Files Included: QUSEC - Error Code Parameter
I\
QWDRJOBD - Retrieve Job Description API
I\
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
I\
I\ Command String Data Structure
I\
ICMDSTR
DS
I I
'SNDMSG MSG(''HOLD 1 26 CMD1
I
'value is '
I
27 36 HOLD
I I
''') TOUSR(QPGMR)'
37 51 CMD2
I\
IMSG3
DS
Chapter 3. Common Information across APIs—Basic (OPM) Example

3-9

I I
'SNDMSG MSG(''No such1 35 MSG3A
I
' \JOBD exists'') '
I I
'TOUSR(QPGMR)'
36 47 MSG3B
I\
I\ Miscellaneous Data Structure
I\
I
DS
I I
39ð
B
1
4ðRCVLEN
I I
'JOBDð1ðð'
5 12 FORMAT
C\
C\ Beginning of Mainline
C\
C\ Two parameters are being passed into this program.
C\
C
\ENTRY
PLIST
C
PARM
JOBD
1ð
C
PARM
JOBDL 1ð
C\
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'
ð1 .1ð/
C
PARM
QWDBH
Receiver Var.
C
PARM
RCVLEN
Length RCVVAR
C
PARM
FORMAT
Format Name
C
PARM
LFNAM
Qual. Job Desc
C
PARM
QUSBN
Error Code
C
ð1
EXSR ERROR
Error Subroutine
C\
C Nð1
MOVELQWDBHN
HOLD
C\
C\ Let's tell everyone what the hold value was for this job.
C\
C Nð1
Z-ADD51
LENSTR 155
C Nð1
CALL 'QCMDEXC'
C
PARM
CMDSTR
C
PARM
LENSTR
C\
C
SETON
LR
C
RETRN
C\
C\ End of MAINLINE
C\
C\ Subroutine to handle errors received on the CALL
C\
C
ERROR
BEGSR
C
MSGIDD
IFEQ 'CPF98ð1'
C\
C\ Process errors returned from the API.
C\
C
Z-ADD47
LENSTR 155
C
CALL 'QCMDEXC'
C
PARM
MSG3
C
PARM
LENSTR
C
END
C
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

ð
Display Messages

Queue . . . . . :
QPGMR
Library . . . :
QUSRSYS
Severity . . . :
ðð
Type reply (if required), press Enter.
From . . . :
SMITH
ð7/25/94
No such \JOBD exists

System:
Program . . . . :
Library . . . :
Delivery . . . :

GENSYS9ð
\DSPMSG
\HOLD

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 subroutine 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 qualifier 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 conditions. The example in this topic uses an error-code data structure as an alternative 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 specifics 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 information 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 messages 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

Format of an Error Code Structure
The format of the error code structure (QUSBN) is:
Offset
Dec

Hex

Use

Type

Field

INPUT

BINARY(4)

Bytes provided

OUTPUT

BINARY(4)

Bytes available

OUTPUT

CHAR(7)

Exception ID

OUTPUT

CHAR(1)

Reserved

OUTPUT

CHAR(*)

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 language. 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) information 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\
returned in the error code parameter.
I\
I\Header Files Included: QUSEC - Error Code Parameter
I\
QWDRJOBD - Retrieve Job Description API
I\
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

I\
I/COPY QSYSINC/QRPGSRC,QWDRJOBD
I\
I\ Command String Data Structure
I\
ICMDSTR
DS
I I
'SNDMSG MSG(''HOLD 1 26 CMD1
I
'value is '
I
27 36 HOLD
I I
''') TOUSR(QPGMR)'
37 51 CMD2
I\
IMSG2
DS
I I
'SNDMSG MSG(''Progr1 43 MSG2A
I
'am failed with mesI
'sage ID '
I
44 5ð MSGIDD
I I
''') TOUSR(QPGMR)'
51 65 MSG2B
I\
I\ Miscellaneous Data Structure
I\
I
DS
I I
39ð
B
1
4ðRCVLEN
I I
'JOBDð1ðð'
5 12 FORMAT
C\
C\ Beginning of Mainline
C\
C\ Two parameters are being passed into this program.
C\
C
\ENTRY
PLIST
C
PARM
JOBD
1ð
C
PARM
JOBDL 1ð
C\
C\ Move the two parameters passed into the LFNAM.
C\
C
JOBD
CAT JOBDL
LFNAM 2ð
C\
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
CALL 'QWDRJOBD'
C
PARM
QWDBH
Receiver Var.
C
PARM
RCVLEN
Length RCVVAR
C
PARM
FORMAT
Format Name
C
PARM
LFNAM
Qual. Job Desc
C
PARM
QUSBN
Error Code
C\ See if any errors were returned in the error code parameter.
C
EXSR ERRCOD
C\
C\
C\
C Nð1
MOVELQWDBHN
HOLD
C\
C\ Let's tell everyone what the hold value was for this job.
C\
C Nð1
Z-ADD51
LENSTR 155
C Nð1
CALL 'QCMDEXC'
C
PARM
CMDSTR
C
PARM
LENSTR
C\
C
SETON
LR
C
RETRN
C\
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

C
ERRCOD
BEGSR
C
QUSBNC
IFGT ð .13/
C\
C\ Process errors returned from the API.
C\
C
SETON
ð1
C
Z-ADD65
LENSTR 155
C
MOVELQUSBND
MSGIDD
C
CALL 'QCMDEXC'
C
PARM
MSG2
C
PARM
LENSTR
C
END
C
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

Queue . . . . . :
QPGMR
Library . . . :
QUSRSYS
Severity . . . :
ðð
Type reply (if required), press Enter.
From . . . :
SMITH
ð7/23/94
HOLD value is \NO

System:
Program . . . . :
Library . . . :
Delivery . . . :

GENSYS9ð
\DSPMSG
\HOLD

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

ð
Display Messages
Queue . . . . . :
QPGMR
Library . . . :
QUSRSYS
Severity . . . :
ðð
Type reply (if required), press Enter.
From . . . :
SMITH
ð7/23/94
Program failed with message ID CPF98ð1

System:
Program . . . . :
Library . . . :
Delivery . . . :

GENSYS9ð
\DSPMSG
\HOLD

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
Queue . . . . . :
QPGMR
Library . . . :
QUSRSYS
Severity . . . :
ðð
Type reply (if required), press Enter.
From . . . :
SMITH
ð7/23/94
Program failed with message ID CPF981ð

System:
Program . . . . :
Library . . . :
Delivery . . . :

GENSYS9ð
\DSPMSG
\HOLD

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\
way of using the offset in a user space in RPG.
I\
I\Header Files Included: QUSEC - Error Code Parameter
I\
(Copied into Program)
I\
QWDRJOBD - Retrieve Job Description API
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\\\ 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

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ððð
3D1ð 9312ð1 DPOHLSON: New Include
I\
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\
portion of the format. Varying-length field exception
I\
data is not defined here.
I\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
IQUSBN
DS
I\
Qus EC
I
B
1
4ðQUSBNB
I\
Bytes Provided
I
B
5
8ðQUSBNC
I\
Bytes Available
I
9 15 QUSBND
I\
Exception Id
I
16 16 QUSBNF
I\
Reserved
I\
17 17 QUSBNG
I\
I\
Varying length
I
17 2ðð QUSBNG .16/
.
.
.
C
C\
C
C
C
C
C
C

Z-ADD2ðð

QUSBNB

CALL 'QWDRJOBD'
PARM
QWDBH
PARM
RCVLEN
PARM
FORMAT
PARM
LFNAM
PARM
QUSBN

Receiver Var.
Length RCVVAR
Format Name
Qual. Job Desc
Error Code

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

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 messages. 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\
the job description or prints an error if the
F\
API could not find the job description name
F\
specified.
F\
F\
F\Header Files Included: QUSEC - Error Code Parameter
F\
QWDRJOBD - Retrieve Job Description API
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\ JOBDAPIR - Print value of HOLD parameter using API
F\
Uses error-code data structure
F\
FQPRINT O
F
132
OF
PRINTER
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\
I\
I\ Dummy data structure used to declare binary field .19/
I\
I
DS
I I
39ð
B
1
4ðRCVLEN
I I
'JOBDð1ðð'
5
12FORMAT

Chapter 3. Common Information across APIs—Basic (OPM) Example

3-17

C\
C\ Beginning of Mainline
C\
C\ Two parameters are being passed into this program.
C\
C
\ENTRY
PLIST
Parm list
C
PARM
JOBD
1ð
Job descrp
C
PARM
JOBDL 1ð
Jobd library
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
CALL 'QWDRJOBD'
Parm list
C
PARM
QWDBH
Receiver Var.
C
PARM
RCVLEN
Length RCVVAR
C
PARM
FORMAT
Format Name
C
PARM
LFNAM
Qual. Job Desc
C
PARM
QUSBN
Error Code
C\ If no bytes available, API was successful; print HOLD value
C
QUSBNC
IFEQ ð
C
EXCPTGOOD
C
ENDIF
C\ If some bytes available, API failed; print error message ID
C
QUSBNC
IFGT ð
C
EXCPTBAD
C
ENDIF
C\ End of program
C
SETON
LR
C
RETRN
C\
C\ End of MAINLINE
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
O\
OQPRINT E 1ð6
GOOD
O
'HOLD value - '
O
QWDBHN
OQPRINT E 1ð6
BAD
O
'Failed. Error ID - '
O
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

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 variablelength 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\
way of using the offset in a user space in RPG.
I\
I\Header Files Included: QUSEC - Error Code Parameter
I\
(Copied into Program)
I\
QWDRJOBD - Retrieve Job Description API
I\
(Copied into Program)
I\
I\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

Chapter 3. Common Information across APIs—Basic (OPM) Example

3-19

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ððð
3D1ð 9312ð1 DPOHLSON: New Include
I\
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\
portion of the format. Varying-length field exception
I\
data is not defined here.
I\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
IQUSBN
DS
I\
Qus EC
I
B
1
4ðQUSBNB
I\
Bytes Provided
I
B
5
8ðQUSBNC
I\
Bytes Available
I
9 15 QUSBND
I\
Exception Id
I
16 16 QUSBNF
I\
Reserved
I\
Varying length, had to define len
I
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

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\
retrieves information from a job description
I\
object and places it into a single variable in the
I\
calling program.
I\
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ððð
3D1ð 94ð424 ROCH:
New Include
I\
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\
portion of the format. Any varying-length fields have
I\
to be defined by the user.
I\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
IQWDBH
DS
1ððð
I\
Qwd JOBDð1ðð
I
B
1
4ðQWDBHB
I\
Bytes Returned
I
B
5
8ðQWDBHC
I\
Bytes Available
I
9 18 QWDBHD
I\
Job Description Name
I
19 28 QWDBHF
I\
Job Description Lib Name
I
29 38 QWDBHG
I\
User Name
I
39 46 QWDBHH
I\
Job Date
I
47 54 QWDBHJ
I\
Job Switches
I
55 64 QWDBHK
I\
Job Queue Name

Chapter 3. Common Information across APIs—Basic (OPM) Example

3-21

I
65 74 QWDBHL
I\
Job Queue Lib Name
I
75 76 QWDBHM
I\
Job Queue Priority
I
77 86 QWDBHN
I\
Hold Job Queue
I
87 96 QWDBHP
I\
Output Queue Name
I
97 1ð6 QWDBHQ
I\
Output Queue Lib Name
I
1ð7 1ð8 QWDBHR
I\
Output Queue Priority
I
1ð9 118 QWDBHS
I\
Printer Device Name
I
119 148 QWDBHT
I\
Print Text
I
B 149 152ðQWDBHV
I\
Syntax Check Severity
I
B 153 156ðQWDBHW
I\
End Severity
I
B 157 16ððQWDBHX
I\
Message Log Severity
I
161 161 QWDBHY
I\
Message Log Level
I
162 171 QWDBHZ
I\
Message Log Text
I
172 181 QWDBHð
I\
Log CL Programs
I
182 191 QWDBH1
I\
Inquiry Message Reply
I
192 2ð4 QWDBH2
I\
Device Recovery Action
I
2ð5 214 QWDBH3
I\
Time Slice End Pool
I
215 229 QWDBH4
I\
Accounting Code
I
23ð 3ð9 QWDBH5
I\
Routing Data
I
31ð 359 QWDBH6
I\
Text Description
I
36ð 36ð QWDBH7
I\
Reserved
I
B 361 364ðQWDBH8 .19/
I\
Offset Initial Lib List
I
B 365 368ðQWDBH9 .2ð/
I\
Number Libs In Lib list
I
B 369 372ðQWDBJB
I\
Offset Request Data
I
B 373 376ðQWDBJC
I\
Length Request Data
I
B 377 38ððQWDBJH
I\
Job Message Queue Max Size
I
381 39ð QWDBJJ
I\
Job Message Queue Full Actio
I\
391 391 QWDBJD
I\
I\
Varying length
I\
392 4ð2 QWDBJF
I\
I\
Varying length
I\
4ð3 4ð3 QWDBJG
I\
I\
I\ Command String Data Structure
I\
ICMDSTR
DS
I I
'SNDMSG MSG(''LIBRARY1 22 CMD1
I
' - '
I
23 32 LIB
I I
''') TOUSR(QPGMR)'
33 47 CMD2
I\
I\ Miscellaneous Data Structure

3-22

System API Programming V4R1

I\
I
DS
I I
1ððð
B
1
4ðRCVLEN
I I
ð
B
5
8ðX
I I
'JOBDð1ðð'
9 16 FORMAT
C\
C\ Beginning of Mainline
C\
C\ Two parameters are being passed into this program.
C\
C
\ENTRY
PLIST
C
PARM
JOBD
1ð
C
PARM
JOBDL 1ð
C\
C\ Move the two parameters passed into LFNAM.
C\
C
JOBD
CAT JOBDL
LFNAM 2ð
C\
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
CALL 'QWDRJOBD'
C
PARM
QWDBH
Receiver Var.
C
PARM
RCVLEN
Length RCVVAR
C
PARM
FORMAT
Format Name
C
PARM
LFNAM
Qual. Job Desc
C
PARM
QUSBN
Error Code
C\ See if any errors were returned in the error code parameter.
C
EXSR ERRCOD
C\
C Nð1
Z-ADD47
LENSTR 155
C\
C Nð1
QWDBH8
ADD 1
X
C Nð1
1
DO
QWDBH9
C
1ð
SUBSTQWDBH:X
LIB
C\
C\ Let's tell everyone what the library value is.
C\
C
CALL 'QCMDEXC'
C
PARM
CMDSTR
C
PARM
LENSTR
C
ADD 11
X
C
X
IFGE RCVLEN
C
LEAVE
C
ENDIF
C
ENDDO
C\
C
SETON
LR
C
RETRN
C\
C\ End of MAINLINE
C\
C\
C\ Subroutine to handle errors returned in the error code
C\ parameter.
C\
C
ERRCOD
BEGSR
C
QUSBNC
IFGT ð
C
SETON
ð1
Error on API Call
C\
C\ Process errors returned from the API.
C\
C
END
C
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

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
Queue . . . . . :
QPGMR
Library . . . :
QUSRSYS
Severity . . . :
ðð
Type reply (if required), press Enter.
LIBRARY - SMITH
From . . . :
SMITH
ð7/23/94
LIBRARY - QTEMP
From . . . :
SMITH
ð7/23/94
LIBRARY - QGPL
From . . . :
SMITH
ð7/23/94
LIBRARY - QBLDCPF
From . . . :
SMITH
ð7/23/94
LIBRARY - UTIL
From . . . :
SMITH
ð7/23/94
LIBRARY - OPENTEST

System:
Program . . . . :
Library . . . :
Delivery . . . :

GENSYS9ð
\DSPMSG
\HOLD

12:29:38
12:29:38
12:29:38
12:29:38
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 addition 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 messages.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:
This example shows the steps necessary
F\
to process keyed output from an API.

3-24

System API Programming V4R1

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
F\
QUSCRTUS - Create User Space
F\
QUSRTVUS - Retrieve User Space
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
FQSYSPRT O
F
132
OF
PRINTER
I\
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
DS
I I
'SPCNAME
'
1 1ð SPC
I I
'QTEMP
'
11 2ð LIB
I\
I\ Data structure to hold requested key values
I\
IKEYARA
DS
.5/ .7/
I I
2ð1
B
1
4ðKEY1
I I
216
B
5
8ðKEY2
I I
211
B
9 12ðKEY3
.8/
I\
I\ Receiver variable for QUSRTVUS
I\
IRECVR
DS
1ððð
I\
I\ Other assorted variables
I\
I
DS
I
B
1
4ðSIZ
I
B
5
8ðSTART
I
B
9 12ðLENDTA
I
B 13 16ðKEY#
I
B 17 2ððPAGES#
I
17 2ð PAGESA
I I
X'ðð'
21 21 INTVAL
C\
C\ Initialize Error Code structure to accept exceptions
C\
C
Z-ADDð
QUSBNB .1/
C\
C\ Create the User Space to hold the QUSLSPL API results
C\
C
CALL 'QUSCRTUS'
.2/
C
PARM
SPCNAM
C
PARM 'quslspl' EXTATR 1ð
C
PARM 2ððð
SIZ
C
PARM
INTVAL
C
PARM '\ALL'
PUBAUT 1ð
C
PARM
TXTDSC 5ð
C
PARM '\YES'
REPLAC 1ð
C
PARM
QUSBN
C\
C\ Call QUSLSPL to get all spooled files for \CURRENT user
C\
C
CALL 'QUSLSPL'
.3/
C
PARM
SPCNAM

Chapter 3. Common Information across APIs—Basic (OPM) Example

3-25

C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C
C
C
C
C\
C\
C\
C
C
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C
C\
C\
C\
C
C
C
C
C
C
C\
C\
C\
C
C
C
C\
C\
C\
C
C\
C\
C\
C
C\

3-26

PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM

'SPLFð2ðð'FORMAT
'\CURRENT'USRNAM
'\ALL'
OUTQ
'\ALL'
FRMTYP
'\ALL'
USRDTA
QUSBN
JOBNAM
KEYARA
3
KEY#

.4/

8
1ð
2ð
1ð
1ð
26

.5/
.6/

Retrieve information concerning the User Space and its contents
CALL 'QUSRTVUS'
.9/
PARM
SPCNAM
PARM 1
START
PARM 192
LENDTA
PARM
QUSBP
PARM
QUSBN

Start Rtv at 1
for length =192
.1ð/

Check User Space status for good information
QUSBPD
QUSBPJ
QUSBPJ

.12/
.14/

IFEQ 'ð1ðð'
IFEQ 'C'
OREQ 'P'

Header Fmt
Complete
or Partial

Check to see if any entries were put into User Space
QUSBPS

.16/

IFGT ð

Keep count of how many list entries we have processed
Z-ADDð

COUNT

9ð

.17/

Adjust Offset value to Position value
QUSBPQ

ADD

.18/

START

Retrieve the lesser of allocated storage or available data
QUSBPT

IFLT 1ððð
Z-ADDQUSBPT
ELSE
Z-ADD1ððð
ENDIF

.19/
LENDTA
LENDTA

Process all entries returned
COUNT

.2ð/

DOWLTQUSBPS

Retrieve spooled file information
CALL 'QUSRTVUS'
.21/
PARM
SPCNAM
PARM
START
PARM
LENDTA
PARM
RECVR
PARM
QUSBN
Loop through returned fields
4

SUBSTRECVR
Z-ADD5
DO
QUSFVB

QUSFV
X
4ð
.23/

.22/

QUSKR

.24/

Get header information
16

SUBSTRECVR:X

Set Y to location of actual data associated with key

System API Programming V4R1

ADD

4ð

C\ Process the data based on key type
C\
C
QUSKRC
CASEQ2ð1
FILNAM
.25/
C
QUSKRC
CASEQ211
PAGES
C
QUSKRC
CASEQ216
AGE
C
CAS
ERROR
C
END
C\
C\ Adjust X to address next keyed record returned
C\
C
ADD QUSKRB
X
C
ENDDO
C\
C\ Output information on spooled file
C\
C
EXCPTPRTLIN
.26/
C\
C\ Adjust START to address next entry
C\
C
ADD 1
COUNT
.27/
C
ADD QUSBPT
START
C
ENDDO
C
ENDIF
C
ELSE
.15/
C
EXCPTLSTERR
C
ENDIF
C
ELSE
.13/
C
EXCPTHDRERR
C
ENDIF
C
MOVE '1'
\INLR
.28/
C
RETRN
C\
C\ Various subroutines
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
FILNAM
BEGSR
C\
C\ Extract spooled file name for report
C\
C
MOVE \BLANKS
PRTFIL 1ð
C
QUSKRG
SUBSTRECVR:Y
PRTFIL
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
PAGES
BEGSR
C\
C\ Extract number of pages for report
C\
C
QUSKRG
SUBSTRECVR:Y
PAGESA
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
AGE
BEGSR
C\
C\ Extract age of spooled file for report
C\
C
MOVE \BLANKS
OPNDAT 7
C
QUSKRG
SUBSTRECVR:Y
OPNDAT
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
ERROR
BEGSR
C\
C\ If unknown key value, then display the value and end
C\
C
DSPLY
QUSKRC
C
MOVE '1'
\INLR
C
RETRN
C
ENDSR
O\
OQSYSPRT E
PRTLIN
O
PRTFIL
1ð
O
PAGES#
25
O
OPNDAT
4ð
OQSYSPRT E
LSTERR

Chapter 3. Common Information across APIs—Basic (OPM) Example

3-27

O
OQSYSPRT E
O

22 'List data not valid

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 initialized 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 performed 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 following:
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

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 multiple 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 programs. 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

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 characters 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 structure, 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 variable for the JOBD0100 format. For detailed descriptions of the fields, see “Field
Descriptions” on page 3-32.
Offset

3-30

Dec

Hex

Type

Field

BINARY(4)

Bytes returned

BINARY(4)

Bytes available

System API Programming V4R1

Offset
Dec

Hex

Type

Field

CHAR(10)

Job description name

CHAR(10)

Job description library name

CHAR(10)

User name

CHAR(8)

Job date

CHAR(8)

Job switches

CHAR(10)

Job queue name

CHAR(10)

Job queue library name

CHAR(2)

Job queue priority

CHAR(10)

Hold on job queue

CHAR(10)

Output queue name

CHAR(10)

Output queue library name

106

CHAR(2)

Output queue priority

108

CHAR(10)

Printer device name

118

CHAR(30)

Print text

148

BINARY(4)

Syntax check severity

152

BINARY(4)

End severity

156

BINARY(4)

Message logging severity

160

CHAR(1)

Message logging level

161

CHAR(10)

Message logging text

171

CHAR(10)

Logging of CL programs

181

CHAR(10)

Inquiry message reply

191

CHAR(13)

Device recovery action

204

CHAR(10)

Time-slice end pool

214

CHAR(15)

Accounting code

229

CHAR(80)

Routing data

309

135

CHAR(50)

Text description

359

167

CHAR(1)

Reserved

360

168

BINARY(4)

Offset to initial library list .19/

364

16C

BINARY(4)

Number of libraries in initial library list .2ð/

368

170

BINARY(4)

Offset to request data

372

174

BINARY(4)

Length of request data

376

178

BINARY(4)

Job message queue maximum size

380

17C

CHAR(10)

Job message queue full action

390
.1/

186

CHAR(*)

Reserved

ARRAY (*) of
CHAR(11)

Initial library list

CHAR(*)

Request data

Chapter 3. Common Information across APIs—Basic (OPM) Example

3-31

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 available, this value will be less than the bytes available.
Device recovery action. The action to take when an I/O error occurs for the interactive 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

Inquiry message reply. How inquiry messages are answered for jobs that use
this job description.

*RQD

The job requires an answer for any inquiry messages that occur while
the job is running.
*DFT
The system uses the default message reply to answer any inquiry messages 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
2–64

The maximum size set by system value QJOBMSGMX at the time the
job is started.
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

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
2

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:
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:
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 messages 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

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

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 subsystem 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
0–99

The request data is not checked for syntax as CL commands. This is
equivalent to *NOCHK.
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
The job is not moved when it reaches time-slice end.
*BASE
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
CPF24B4 E
CPF3CF1 E
CPF3CF2 E
CPF3C21 E
CPF3C24 E
CPF9801 E
CPF9802 E
CPF9803 E
CPF9804 E
CPF9807 E
CPF9808 E
CPF9810 E
CPF9820 E
CPF9830 E

3-36

System API Programming V4R1

Job description &1 in library &2 damaged.
Severe error while addressing parameter list.
Error code parameter not valid.
Error(s) occurred during running of &1 API.
Format name &1 is not valid.
Length of the receiver variable is not valid.
Object &2 in library &3 not found.
Not authorized to object &2 in &3.
Cannot allocate object &2 in library &3.
Object &2 in library &3 damaged.
One or more libraries in library list deleted.
Cannot allocate one or more libraries on library list.
Library &1 not found.
Not authorized to use library &1.
Cannot assign library &1.

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

3-38

System API Programming V4R1

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 programs. 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; therefore, 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

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 programs 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 registration 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 concepts 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 repository. 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

#include
#include
#include
#include
#include
#include

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/\/
} Qus_EC_t;

/\ Varying length field

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 parameters 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

Type

Field

BINARY(4)

Length of variable-length record

BINARY(4)

Exit program attribute key

BINARY(4)

Length of data

CHAR(*)

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

CHAR(27)

Qualified message file name and message identifier for exit
program description

CHAR(50)

Exit program text description

BINARY(4)

Exit program data CCSID

CHAR(1)

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 structure becomes the exit program attributes parameter on the call to the Add Exit
Program API:
typedef struct {
int
Qus_Vlen_Rec_4_t
char
char

4-4

System API Programming V4R1

num_rec;
replace_rec;
replace;
Reserved[3];

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 variablelength 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 signaled. 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 provided 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

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)
CHAR(256)

Parameter number
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

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

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
#include
#include
#include
#include
#include
#include
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Structures
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
typedef struct {
Qus_EC_t ec_fields;
char
exception_data[1ðð];
} error_code_struct;

/\ Error code

typedef struct {
int
Qus_Vlen_Rec_4_t
int
Qus_Vlen_Rec_4_t
char
} rgpt_controls;

/\ Exit point control keys

num_rec;
max_pgms_rec;
max_pgms;
descrip_rec;
text_desc[5ð];

typedef struct {
int
num_rec;
Qus_Vlen_Rec_4_t replace_rec;
char
replace;
char
Reserved[3];
Qus_Vlen_Rec_4_t CCSID_rec;
int
CCSID;
} addep_attributes;

/\ Exit program attribute keys\/

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
\/
/\
main
\/
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/

4-10

System API Programming V4R1

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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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

"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
#include
#include
#include
#include
#include
#include
#include

Chapter 4. Common Information across APIs—Advanced (ILE) Example

4-13

#include
#include
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Prototypes
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
typedef void Pgm_OS(void \arg,...);
#pragma linkage(Pgm_OS,OS)
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Structures
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
typedef struct {
Qus_EC_t ec_fields;
char
exception_data[1ðð];
} error_code_struct;

/\ Error code

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
FUNCTION NAME: RSLVSP_PGM_HDLR
\/
/\
\/
/\
FUNCTION :
This function handles all exceptions that
\/
/\
may occur while resolving to the exit
\/
/\
program.
\/
/\
\/
/\
INPUT:
Interrupt handler information
\/
/\
\/
/\
OUTPUT:
NONE
\/
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
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

/\
FUNCTION :
This function calls the exit programs that
\/
/\
were retrieved from the registration facility \/
/\
repository.
\/
/\
\/
/\
INPUT:
Information retrieved
\/
/\
\/
/\
OUTPUT:
NONE
\/
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
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=ð; iOffset_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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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

} /\ 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
#include
#include
#include
#include
#include
#include
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Structures
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
typedef struct {
Qus_EC_t ec_fields;
char
exception_data[1ðð];
} error_code_struct;

/\ Error code

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
\/
/\
main
\/
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
int main()
{
int pgm_num=1;
error_code_struct error_code;
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/

Chapter 4. Common Information across APIs—Advanced (ILE) Example

4-19

/\ 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

error_code.ec_fields.Exception_Id);
exit(1);
}

} /\ End program \/

Chapter 4. Common Information across APIs—Advanced (ILE) Example

4-21

4-22

System API Programming V4R1

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 application 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

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
│
+95│ Subsetted list indicator
│
│─────────────────────────┤
│
│
│ Entry 2
│
+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 parameters 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 specific 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

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 possible 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). Possible 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 information 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 continuation 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 continuation 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 specific letter.
For more information about continuation handles and how to use them, see “Continuation Handle” on page 2-25.

Chapter 5. List APIs

5-3

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:
OPM RPG
F\
F\Description: This program prints a report showing all objects
F\
that adopt owner authority. The two parameters
F\
passed to the program are the profile to be
F\
checked and the type of objects to be listed.
F\
The parameter values are the same as those
F\
accepted by the QSYLOBJP API.
F\
F\APIs Used:
QSYLOBJP - List Objects that Adopt Owner Authority
F\
QUSCRTUS - Create User Space
F\
QUSROBJD - Retrieve Object Description
/
F\
QUSRTVUS - Retrieve From User Space
/
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

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\
Qus_ERRCð2ðð_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ððð
3D1ð 9312ð1 DPOHLSON: New Include
I\$B1= D91794ðð
3D6ð 94ð9ð4 GEORGE : Add Qus_ERRCð2ðð_t
I\
structure.
I\
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
DS
I\
Qus EC
I
B
1
4ðQUSBNB
I\
Bytes Provided
I
B
5
8ðQUSBNC
I\
Bytes Available
I
9 15 QUSBND
Chapter 5. List APIs

5-5

I\
Exception Id
I
16 16 QUSBNF
I\
Reserved
I\ Following statement was uncommented and 17 was changed to 1ðð
I
17 1ðð QUSBNG
I\
I\
Varying length
IQUSKY
DS
I\
Qus ERRCð2ðð
I
B
1
4ðQUSKYB
I\
Key
I
B
5
8ðQUSKYC
I\
Bytes Provided
I
B
9 12ðQUSKYD
I\
Bytes Available
I
13 19 QUSKYF
I\
Exception Id
I
2ð 2ð QUSKYG
I\
Reserved
I
B 21 24ðQUSKYH
I\
CCSID
I
B 25 28ðQUSKYJ
I\
Offset Exc Data
I
B 29 32ðQUSKYK
I\
Length Exc Data
I\
33 33 QUSKYL
I\
Reserved2
I\
I\
34 34 QUSKYM
I\
I\
I\ Global Variables
I\
I
DS
I
1 1ð APINAM
I
11 3ð CONHDL
I I
'QSYSLOBJP '
31 4ð EXTATR
I
41 41 LSTSTS
I I
'OBJPð2ðð'
42 49 MBRLST
I I
'OBJDð1ðð'
68 75 RJOBDF
I I
'\ALL
'
76 85 SPCAUT
I I
'\USER
'
86 95 SPCDMN
I I
X'ðð'
96 96 SPCINT
I I
'ADOPTS
QTEMP
'
97 116 SPCNAM
I I
'\YES
'
117 126 SPCREP
I
127 176 SPCTXT
I I
'\USRSPC
'
177 186 SPCTYP
I I
8
B 197 2ðððRCVLEN
I
B 2ð1 2ð4ðSIZENT
I I
1
B 2ð5 2ð8ðSPCSIZ
I
B 2ð9 212ðI
I
B 213 216ðNUMENT
I
B 217 22ððOFFSET
I
B 221 224ðSTRPOS
IRCVVAR
DS
2ððð
C\
C\ Beginning of Mainline
C\

5-6

System API Programming V4R1

C\ Two parameters are being passed into this program.
C\
C
\ENTRY
PLIST
C
PARM
USRPRF 1ð
C
PARM
OBJTYP 1ð
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
EXSR INIT
C
EXSR PROCES
C
EXSR DONE
C\
C\ End of MAINLINE
C\
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Function:
getlst
C\
C\ Description:
This function calls QSYLOBJP to build a list.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
GETLST
BEGSR
C
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
CALL 'QSYLOBJP'
C
PARM
SPCNAM
User space/lib
C
PARM
MBRLST
Member list
C
PARM
USRPRF
User profile
C
PARM
OBJTYP
Object type sc
C
PARM
CONHDL
Continuation ha (.3/
C
PARM
QUSBN
Error Code
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Check for errors on QSYLOBJP.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
QUSBNC
IFGT ð
C
MOVEL'QSYLOBJP'APINAM
C
EXSR APIERR
C
ENDIF
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Function:
INIT
C\
C\ Description:
This function does all the necessary
C\
initialization for this program and the
C\
rest is done in the I specs.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
INIT
BEGSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
Z-ADD1ðð
QUSBNB
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Call QUSROBJD to see if the user space was previously created
C\ in QTEMP. If it was, simply reuse it.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
CALL 'QUSROBJD'
C
PARM
RCVVAR
Receiver Var
Chapter 5. List APIs

5-7

C
PARM
RCVLEN
Rec Var Length
C
PARM
RJOBDF
Format
C
PARM
SPCNAM
Qual User Space
C
PARM
SPCTYP
User object typ
C
PARM
QUSBN
Error Code
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
CALL 'QUSCRTUS'
C
PARM
SPCNAM
Qual User Space
C
PARM
EXTATR
Extended Attrib
C
PARM
SPCSIZ
Size user space
C
PARM
SPCINT
Space Initializ
C
PARM
SPCAUT
Public Authorit
C
PARM
SPCTXT
User space text
C
PARM
SPCREP
Replace existin
C
PARM
QUSBN
Error Code
C
PARM
SPCDMN
Domain of us
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Check for errors on QUSCRTUS.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
QUSBNC
IFGT ð
C
MOVEL'QUSCRTUS'APINAM
C
EXSR APIERR
C
ENDIF
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ An error occurred accessing the user space.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
ELSE
C
MOVEL'QUSROBJD'APINAM
C
EXSR APIERR
C
ENDIF
CPF98ð1 ELSE
C
ENDIF
BYTAVL > ð
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Set QSYLOBJP (via GETLST) to start a new list.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
MOVE \BLANKS
CONHDL
C
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
Z-ADD1
STRPOS
C
Z-ADD192
RCVLEN
Format 1ðð
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
Qual User Space
C
PARM
STRPOS
Start Position
C
PARM
RCVLEN
Length of Data
C
PARM
QUSBP
Receiver Var.
C
PARM
QUSBN
Error Code
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

5-8

System API Programming V4R1

C\ Check for errors on QUSRTVUS.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
QUSBNC
IFGT ð
C
MOVEL'QUSRTVUS'APINAM
C
EXSR APIERR
C
ENDIF
C
1
ADD QUSBPQ
STRPOS
Offset to List .5/
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Function:
proc2
C\
C\ Description:
This function processes each entry returned by
C\
QSYLOBJP.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
PROC2
BEGSR
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
Qual User Space
C
PARM
STRPOS
Start Position
C
PARM
SIZENT
Length of Data
C
PARM
QSYB6
Receiver Var.
C
PARM
QUSBN
Error Code
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Check for errors on QUSRTVUS.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
QUSBNC
IFGT ð
C
MOVEL'QUSRTVUS'APINAM
C
EXSR APIERR
C
ENDIF
C
EXCPTPRTENT
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ After each entry, increment to the next entry.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
STRPOS
ADD SIZENT
STRPOS
.7/
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Function:
proc1
C\
C\ Description:
This function processes each entry returned by
C\
QSYLOBJP.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
PROC1
BEGSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ If valid information was returned.
.1/
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
Z-ADDQUSBPS
NUMENT
C
QUSBPJ
IFEQ 'P'
C
QUSBPJ
OREQ 'C'
C
NUMENT
IFGT ð
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Get the size of each entry to use later.
.4/
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
Z-ADDQUSBPT
SIZENT
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Increment to the first list entry.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
1
ADD QUSBPQ
OFFSET
Chapter 5. List APIs

5-9

C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Process all of the entries.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
1
DO
NUMENT
I
.6/
C
EXSR PROC2
C
ENDDO
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
1
ADD QUSBPL
STRPOS
C
Z-ADD68
RCVLEN
Format 1ðð
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
Qual User Space
C
PARM
STRPOS
Start Position
C
PARM
RCVLEN
Length of Data
C
PARM
QUSBP
Receiver Var.
C
PARM
QUSBN
Error Code
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Check for errors on QUSRTVUS.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
QUSBNC
IFGT ð
C
MOVEL'QUSRTVUS'APINAM
C
EXSR APIERR
C
ENDIF
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ If the continuation handle in the input parameter header
C\ is blank, then set the list status to complete.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
QSYCRJ
IFEQ \BLANKS
C
MOVE 'C'
LSTSTS
C
ELSE
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Else, call QSYLOBJP reusing the user space to get more
C\ list entries.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
MOVELQSYCRJ
CONHDL
.2/
C
EXSR GETLST
C
Z-ADD1
STRPOS
C
Z-ADD192
RCVLEN
Format 1ðð
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
Qual User Space
C
PARM
STRPOS
Start Position
C
PARM
RCVLEN
Length of Data
C
PARM
QUSBP
Receiver Var.
C
PARM
QUSBN
Error Code
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Check for errors on QUSRTVUS.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
QUSBNC
IFGT ð
C
MOVEL'QUSRTVUS'APINAM
C
EXSR APIERR
C
ENDIF
C
MOVE QUSBPJ
LSTSTS

5-10

System API Programming V4R1

C
ENDIF
HDL = BLANKS
C
ENDIF
INFOSTS = ð
C
ELSE
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\If there exists an unexpected status, log an error (not shown)
C\and exit.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
EXSR DONE
done();
C
ENDIF
#ENT > ð
C
ENDIF
USRSPC=P/C
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Function:
proces
C\
C\ Description:
Processes entries until they are complete.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
PROCES
BEGSR
C
MOVELQUSBPJ
LSTSTS
C
LSTSTS
DOUEQ'C'
C
LSTSTS
OREQ 'I'
C
EXSR PROC1
proces1();
C
ENDDO
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Function:
done
C\
C\ Description:
Exits the program.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
DONE
BEGSR
C
EXCPTENDLST
C
SETON
LR
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Function:
apierr
C\
C\ Description:
This function prints the API name, and exception
C\
identifier of an error that occurred.
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
APIERR
BEGSR
C
APINAM
DSPLY
C
QUSBND
DSPLY
C
EXSR DONE
C
ENDSR
O\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
O\ Function:
PRTENT
O\
O\ Description:
This function prints the information returned in
O\
user space.
O\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
OQSYSPRT E 1ð6
PRTENT
O
'Object: '
O
QSYB6C
O
'Library: '
O
QSYB6D
O
'Type: '
O
QSYB6F
Chapter 5. List APIs

5-11

O
'Text: '
O
QSYB6J
O\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
O\ Function:
ENDLST
O\
O\ Description:
This function prints the end of listing print
O\
line and returns to the caller.
O\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
OQSYSPRT E 1ð6
ENDLST
O
'\\\ 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
*LIBL

5-12

System API Programming V4R1

The current library is used to locate the user space. If there is no
current library, QGPL (general purpose library) is used.
The library list is used to locate the user space.

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

OBJP0200

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.
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
Return
Return
Return

entries
entries
entries
entries

for
for
for
for

all object types that adopt authority.
programs that adopt authority.
SQL packages that adopt authority.
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 structure, see "Error Code Parameter" in Chapter 2 of the System API Reference.

Chapter 5. List APIs

5-13

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

Hex

Type

Field

CHAR(10)

User space name specified

CHAR(10)

User space library name specified

CHAR(8)

Format name

CHAR(10)

User name specified

CHAR(10)

Object type

CHAR(20)

Continuation handle .3/

Header Section
Offset
Dec

Hex

Type

Field

CHAR(10)

User name

CHAR(20)

Continuation handle .2/

OBJP0100 Format
Offset
Dec

Hex

Type

Field

CHAR(10)

Object name

CHAR(10)

Library name

CHAR(10)

Object type

CHAR(1)

Object in use

OBJP0200 Format
Offset

5-14

Dec

Hex

Type

Field

CHAR(10)

Object name

CHAR(10)

Library name

CHAR(10)

Object type

CHAR(1)

Object in use

CHAR(10)

Attribute

CHAR(50)

Text description

System API Programming V4R1

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

Error Messages
CPF22FD E
CPF2204 E
CPF2213 E
CPF2217 E
CPF3CF1 E
CPF3C21 E
CPF3C31 E
CPF811A E
CPF9801 E
CPF9802 E
CPF9803 E
CPF9807 E
CPF9808 E
CPF9810 E
CPF9820 E
CPF9830 E
CPF9872 E

5-16

System API Programming V4R1

Continuation handle not valid for API &1.
User profile &1 not found.
Not able to allocate user profile &1.
Not authorized to user profile &1.
Error code parameter not valid.
Format name &1 is not valid.
Object type &1 is not valid.
User space &4 in &9 damaged.
Object &2 in library &3 not found.
Not authorized to object &2 in &3.
Cannot allocate object &2 in library &3.
One or more libraries in library list deleted.
Cannot allocate one or more libraries on library list.
Library &1 not found.
Not authorized to use library &1.
Cannot assign library &1.
Program or service program &1 in library &2 ended. Reason code &3.

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 conditions, 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

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 firstfailure 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 performance.
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
\/
/\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
/\ from QCLE/H
\/
#include
/\ from QCLE/H
\/
#include
/\ from QCLE/H
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Miscellaneous Includes
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
#include
/\ from QSYSINC/H
\/
#include
/\ from QSYSINC/H
\/
#include
/\ from QSYSINC/H
\/

6-2

System API Programming V4R1

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
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.
\/
/\
\/
/\
INPUT:
Two character strings.
\/
/\
\/
/\
OUTPUT:
NONE
\/
/\
\/
/\
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 \/
char pgm_name[3ð];
/\ Program name
\/
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

/\ 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
\/
/\
\/
/\
OUTPUT:
NONE
\/
/\
\/
/\
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
data_offset;
int
data_length;
} data_info_t;
char

int

data_info_t
obj_info_t

6-4

System API Programming V4R1

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[2];
obj_info[1];

ffdc_info_t
Qus_EC_t

\ffdc_info;
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
\/
&ErrorCode);
/\ Error code
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
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
", 3ð);
memcpy(obj_info[ð].obj_lib, "QTEMP
", 3ð);
memcpy(obj_info[ð].obj_type, "\USRSPC
", 1ð);
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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

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
/\ from QCLE/H
\/
#include
/\ from QCLE/H
\/
#include
/\ from QCLE/H
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Miscellaneous Includes
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
#include
/\ from QSYSINC/H
\/
#include
/\ from QSYSINC/H
\/
#include
/\ 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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
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.
\/
/\
\/
/\
INPUT:
Two character strings.
\/
/\
\/
/\
OUTPUT:
NONE
\/
/\
\/
/\
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 \/
char pgm_name[3ð];
/\ Program name
\/
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

#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
\/
/\
\/
/\
OUTPUT:
NONE
\/
/\
\/
/\
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 = ð;
char
pgm_name[3ð],
context_name[3ð],
lib_name[5],
symptom_msg_data[MESSAGE_LEN],
symptom_msg_keyword[MSG_SYMPTOM_LEN];
ffdc_info_t
\ffdc_info;
Qpd_Data_t
data_key,
data_key2;
Qpd_Key_Pointer_t
ffdc_keys[MAX_KEYS];
Qpd_Suspected_Module_t module_key;
Qpd_Symptom_t
symptom_msg_key;
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. \/
Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences

6-9

/\ 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
\/
&ErrorCode);
/\ Error code
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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

&number_of_keys,
&ErrorCode);
} /\ UNEXPECTED_HDLR \/

Chapter 6. Original Program Model (OPM) and Integrated Language Environment (ILE) Differences

6-11

6-12

System API Programming V4R1

Chapter 7. Machine Interface Programming
This chapter is for programmers interested in creating machine interface (MI) programs. 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. Programs come in two flavors: the original program model (OPM) and the Integrated
Language Environment (ILE). MI programs can be created only for the OPM environment. 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 programs, 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.

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

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 particular 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 packeddecimal 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 statements 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

7-2

SPCPTR
SPCPTR
SPCPTR

System API Programming V4R1

ARG1@
ARG2@
RESULT@

PARM;
PARM;
PARM;

To associate these three space pointers with the parameters being passed to the
program, the following operand list (OL) is declared:
DCL

PARM_LIST
(ARG1@,
ARG2@,
RESULT@)
PARM

EXT;

/\
/\
/\
/\
/\

Name of OL is PARM_LIST
The first parameter
The second parameter
The third parameter
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
ARG2
RESULT

PKD(15,5)
PKD(15,5)
PKD(15,5)

BAS(ARG1@);
BAS(ARG2@);
BAS(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 Functional 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

ITS2:

CPYNV

RESULT,ARG2;

The program has now finished processing and ends:
RETURN: RTX
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
SPCPTR
ARG1@
PARM;
DCL
SPCPTR
ARG2@
PARM;
DCL
SPCPTR
RESULT@
PARM;
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);
CPYNV
RESULT,ARG1;
B
RETURN;
ITS2:
CPYNV
RESULT,ARG2;
RETURN: RTX
\;
PEND;

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 Functional Reference for the specific code points required to build MI programs.

7-4

System API Programming V4R1

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 language (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
PARM(&SRCMBR)
DCLF
FILE(MISRC)
DCL
VAR(&SRCMBR) TYPE(\CHAR) LEN(1ð)
DCL
VAR(&MIPGMSRC) TYPE(\CHAR) LEN(2ððð)
DCL
VAR(&MIPGMSRCSZ) TYPE(\CHAR) LEN(4)
DCL
VAR(&OFFSET) TYPE(\DEC) LEN(5 ð) VALUE(1)
DCL
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
VAR(&PGMSRCM) TYPE(\CHAR) LEN(1ð) VALUE(' ')
DCL
VAR(&PGMSRCCHG) TYPE(\CHAR) LEN(13) VALUE(' ')
DCL
VAR(&PRTFNAM) TYPE(\CHAR) LEN(2ð) +
VALUE('QSYSPRT
\LIBL
')
DCL
VAR(&PRTSTRPAG) TYPE(\CHAR) LEN(4) +
VALUE(X'ððððððð1')
DCL
VAR(&PGMPUBAUT) TYPE(\CHAR) LEN(1ð) +
VALUE('\ALL
')
DCL
VAR(&PGMOPTS) TYPE(\CHAR) LEN(22) +
VALUE('\LIST
\REPLACE
')
DCL
VAR(&NUMOPTS) TYPE(\CHAR) LEN(4) +
VALUE(X'ððððððð2')
LOOP:
RCVF

Chapter 7. Machine Interface Programming

7-5

CRTPGM:

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)

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 messages 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 (variable &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
PARM(&ARG1 &ARG2)
DCL
VAR(&ARG1) TYPE(\DEC) LEN(15 5)
DCL
VAR(&ARG2) TYPE(\DEC) LEN(15 5)
DCL
VAR(&RESULT) TYPE(\DEC) LEN(15 5)
DCL
VAR(&MSG) TYPE(\CHAR) LEN(2ð)
DCL
VAR(&USR) TYPE(\CHAR) LEN(1ð)

7-6

System API Programming V4R1

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

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 determine the MI instruction number. Then use that number with the Add Breakpoint
(ADDBKP) CL command. For example, when creating MI01 in the previous exercise, the following listing was generated by QPRCRTPG:
5763SS1 V3R1Mð 94ð9ð9
SEQ.1/INST Offset
Generated Code
ðððð1
ðððð2
ðððð3
ðððð4
ðððð5
ðððð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ð
5763SS1 V3R1Mð 94ð9ð9
MSGID
ODT
ODT Name
5763SS1 V3R1Mð 94ð9ð9
MSGID
MI Instruction Stream Semantic

Generated Output
ð8/ð8/94 ð9:46:36
\... ... 1 ... ... 2 ... ... 3 ... ... 4 ... ... 5 ... ... 6 ... ... 7 ... ...
ENTRY \ (PARM_LIST) EXT
DCL SPCPTR ARG1@ PARM
DCL SPCPTR ARG2@ PARM
DCL SPCPTR RESULT@ PARM
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)
CPYNV RESULT,ARG1
B RETURN
ITS2:
CPYNV RESULT,ARG2
RETURN: RTX \
PEND
Generated Output
ð8/ð8/94 ð9:46:36
Semantics and ODT Syntax Diagnostics
Generated Output
ð8/ð8/94 ð9:46:36
Diagnostics

Page

8
;
;
;
;
;
;
;
;
;
;
;
;
;
;
Page

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 commands:
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

ð
Display Breakpoint
Statement/Instruction
Program . . . . . . .
Recursion level . . .
Start position . . .
Format . . . . . . .
Length . . . . . . .

.
.
.
.
.
.

:
:
:
:
:
:

/ððð5
MIð1
1
1
\CHAR
\DCL

Variable . . . . . . . . . . . . . . . : RESULT
Type . . . . . . . . . . . . . . . . :
PACKED
Length . . . . . . . . . . . . . . . :
15 5
'
6.ððððð'

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
ðððð2

RESULT = MAX(ARG1, ARG2)
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
SPCPTR
ARG1@
PARM;
DCL
SPCPTR
ARG2@
PARM;
DCL
SPCPTR
RESULT@
PARM;
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@);

7-8

System API Programming V4R1

DCL
DD
BRK "ðððð1";
CMPNV(B)
CPYNV
B
ITS2:
CPYNV
BRK "ðððð2";
RETURN: RTX
PEND;

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
Program . . . . . . .
Recursion level . . .
Start position . . .
Format . . . . . . .
Length . . . . . . .

.
.
.
.
.
.

:
:
:
:
:
:

ðððð2 /ððð5
HLLEXAMPLE
1
1
\CHAR
\DCL

Variable . . . . . . . . . . . . . . . : RESULT
Type . . . . . . . . . . . . . . . . :
PACKED
Length . . . . . . . . . . . . . . . :
15 5
'
6.ððððð'

Handling Exceptions in the MI Program
As coded, the MI01 program works fine when it is passed packed decimal parameters. But when the MI01 program is passed other data types, such as in CALL
CL01 (abc 6), exceptions occur. To handle these exceptions, additional statements 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

PARM_LIST
(ARG1@,
ARG2@,
RESULT@,
RC@)
PARM

/\ the new parameter

EXT;

3. Declare the storage addressed by RC@ as a 1-byte character data element:
DCL

CHAR(1)

BAS(RC@);

Chapter 7. Machine Interface Programming

7-9

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
RTX
PEND;

RC,'1';
\;

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 original 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
SPCPTR
ARG1@
PARM;
DCL
SPCPTR
ARG2@
PARM;
DCL
SPCPTR
RESULT@
PARM;
DCL
SPCPTR
RC@
PARM;
DCL
OL
PARM_LIST
(ARG1@,
ARG2@,
RESULT@,
RC@)
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@);

7-10

System API Programming V4R1

DCL
DCL

DD
EXCM
CMPNV(B)
CPYNV
B
ITS2:
CPYNV
RETURN: CPYBLA
RTX
M12ð2: CPYBLA
RTX
PEND;

RC
CHAR(1)
BAS(RC@);
DATAERROR EXCID(H'ðCð2') BP (M12ð2) IMD;
ARG1,ARG2 / LO(ITS2);
RESULT,ARG1;
RETURN;
RESULT,ARG2;
RC,'ð';
\;
RC,'1';
\;

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)
DCL
VAR(&ARG2) TYPE(\DEC) LEN(15 5)
DCL
VAR(&RESULT) TYPE(\DEC) LEN(15 5)
DCL
VAR(&RC) TYPE(\CHAR) LEN(1)
DCL
VAR(&MSG) TYPE(\CHAR) LEN(2ð)
DCL
VAR(&USR) TYPE(\CHAR) LEN(1ð)
RTVJOBA
USER(&USR)
CALL
PGM(MIð1) PARM(&ARG1 &ARG2 &RESULT &RC)
IF
COND(&RC = 'ð') +
THEN(CHGVAR
VAR(&MSG) VALUE(&RESULT))
ELSE +
CHGVAR
VAR(&MSG) VALUE('ERROR FOUND')
SNDMSG
MSG(&MSG) TOUSR(&USR)
ENDPGM
After recompiling the MI01 program and the CL01 program, CALL CL01 (abc
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

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

CL Pgm

MICRTPG

CL05

API
QPRCRTPG
RV3W216-2

Figure 7-1. Program Flow for Creating the MICRTPG Program

7-12

System API Programming V4R1

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
PARM(&FILE &MBR)
DCL
VAR(&FILE) TYPE(\CHAR) LEN(1ð)
DCL
VAR(&MBR) TYPE(\CHAR) LEN(1ð)
DCL
VAR(&SPCNAM) TYPE(\CHAR) LEN(2ð) +
VALUE('
\CURLIB
')
DCL
VAR(&SPCEXTATR) TYPE(\CHAR) LEN(1ð) VALUE(' ')
DCL
VAR(&SPCSIZ) TYPE(\CHAR) LEN(4) +
VALUE(X'ððð1ðððð')
DCL
VAR(&SPCINTVAL) TYPE(\CHAR) LEN(1) VALUE(X'ðð')
DCL
VAR(&SPCSPCAUT) TYPE(\CHAR) LEN(1ð) +
VALUE('\ALL')
DCL
VAR(&SPCTXTDSC) TYPE(\CHAR) LEN(5ð) VALUE(' ')
DCL
VAR(&SPCRPLOPT) TYPE(\CHAR) LEN(1ð) +
VALUE('\YES')
DCL
VAR(&ERRCOD) TYPE(\CHAR) LEN(4) +
VALUE(X'ðððððððð')
DCL
VAR(&SPCDMN) TYPE(\CHAR) LEN(1ð) VALUE('\USER')
DCL
VAR(&BINOFFSET) TYPE(\CHAR) LEN(4) +
VALUE(X'ððððððð1')
CHGVAR
VAR(%SST(&SPCNAM 1 1ð)) VALUE(&MBR)
CALL
PGM(QUSCRTUS) PARM(&SPCNAM &SPCEXTATR +
&SPCSIZ &SPCINTVAL &SPCSPCAUT &SPCTXTDSC +
&SPCRPLOPT &ERRCOD &SPCDMN)
OVRDBF
FILE(MISRC) TOFILE(&FILE) MBR(&MBR)
CALL
PGM(CLð4) PARM(&MBR &BINOFFSET)
CALL
PGM(MICRTPG) PARM(&MBR &BINOFFSET)
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

/\
\/
/\
Description: Load a source physical file member into the
\/
/\
\USRSPC named &MBR.
\/
/\
\/
/\
\/
/\
Header Files Included: None
\/
/\
\/
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
PGM
PARM(&MBR &BINOFFSET)
DCLF
FILE(MISRC)
DCL
VAR(&MBR) TYPE(\CHAR) LEN(1ð)
DCL
VAR(&BINOFFSET) TYPE(\CHAR) LEN(4)
DCL
VAR(&OFFSET) TYPE(\DEC) LEN(8 ð) VALUE(1)
DCL
VAR(&LENGTH) TYPE(\CHAR) LEN(4) +
VALUE(X'ðððððð5ð')
DCL
VAR(&SPCNAM) TYPE(\CHAR) LEN(2ð) +
VALUE('
\LIBL
')
CHGVAR
VAR(%SST(&SPCNAM 1 1ð)) VALUE(&MBR)
LOOP:
RCVF
MONMSG
MSGID(CPFð864) EXEC(GOTO CMDLBL(DONE))
CALL
PGM(QUSCHGUS) PARM(&SPCNAM &BINOFFSET +
&LENGTH &SRCDTA 'ð')
CHGVAR
VAR(&OFFSET) VALUE(&OFFSET + 8ð)
CHGVAR
VAR(%BIN(&BINOFFSET)) VALUE(&OFFSET)
GOTO
CMDLBL(LOOP)
DONE:
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
PARM(&SRCMBR &MIPGMSRC &MIPGMSRCSZ)
DCL
VAR(&SRCMBR) TYPE(\CHAR) LEN(1ð)
DCL
VAR(&MIPGMSRC) TYPE(\CHAR) LEN(1)
DCL
VAR(&MIPGMSRCSZ) TYPE(\CHAR) LEN(4)
DCL
VAR(&PGMNAM) TYPE(\CHAR) LEN(2ð) +
VALUE('
\CURLIB
')
DCL
VAR(&PGMTXT) TYPE(\CHAR) LEN(5ð) +
VALUE(' ')
DCL
VAR(&PGMSRCF) TYPE(\CHAR) LEN(2ð) +
VALUE('\NONE')
DCL
VAR(&PGMSRCM) TYPE(\CHAR) LEN(1ð) VALUE(' ')
DCL
VAR(&PGMSRCCHG) TYPE(\CHAR) LEN(13) VALUE(' ')

7-14

System API Programming V4R1

DCL
DCL
DCL
DCL
DCL
CHGVAR
CALL

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')
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

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 subelements 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 (establishes 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');
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'ðððð');

7-16

System API Programming V4R1

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 demonstrate 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

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 instruction 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

2. Have MICRTPG2 create an automatically extendable space (it can automatically 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

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 previous invocations of the program, you can declare BINOFFSET as being automatic. 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

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
DCL
DCL
DCL
DCL
DCL

SPCPTR CLOVRCMD@ INIT(CLOVRCMD);
SPCPTR CLDLTCMD@ INIT(CLDLTCMD);
DD CLOVRLNG PKD(15,5) INIT(P'65');
SPCPTR CLOVRLNG@ INIT(CLOVRLNG);
DD CLDLTLNG PKD(15,5) INIT(P'12');
SPCPTR CLDLTLNG@ INIT(CLDLTLNG);

/\ Length of OVRDBF CL cmd \/
/\ Length of DLTOVR CL cmd \/

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
DCL
DCL
DCL

SYSPTR CLð6 INIT("CLð6", TYPE(PGM));
DD OFFSET PKD(15,5);
SPCPTR OFFSET@ INIT(OFFSET);
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

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 Instruction Stream” on page 7-22, you should have the program perform the following:

7-22

System API Programming V4R1

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

/\
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
DCL
DCL
DCL

7-24

SYSPTR CLð6 INIT("CLð6", TYPE(PGM));
DD OFFSET PKD(15,5);
SPCPTR OFFSET@ INIT(OFFSET);
OL CLð6OL (USRSPC, OFFSET@) ARG;

System API Programming V4R1

/\ 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

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
PARM(&BUFFER &OFFSET)
DCLF
FILE(MISRC)
DCL
VAR(&BUFFER) TYPE(\CHAR) LEN(16ðð)
DCL
VAR(&OFFSET) TYPE(\DEC) LEN(15 5)
LOOP:
RCVF

7-26

System API Programming V4R1

MONMSG
CHGVAR
CHGVAR
IF
GOTO
ENDPGM

DONE:

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)

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

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 exception 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

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

SYSPTR CLð6 INIT("CLð6", TYPE(PGM));
DD OFFSET PKD(15,5);
SPCPTR OFFSET@ INIT(OFFSET);
OL CLð6OL (USRSPC, OFFSET@) ARG;

/\ Access QTEMP address
DCL SYSPTR QTEMP@

BASPCO

\/
POS(65);

/\ Template for CRTS MI instruction

7-29

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 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

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

B E14ð1;
CPYBWP USRSPC@, EXC_OBJ@;
CPYBLA ACTION, X'ð1ðð';
E14ð1: CPYBWP INV_PTR2, INV_PTR;
RTNEXCP RTNTMPLT@;
PEND;
SAME:

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
system. Within the PCO, there
be used. The first is a space
point table (SEPT), the second
library. The use of any other
supported.

DCL DD PCO CHAR(8ð) BASPCO;
DCL SPCPTR SEPT@
DCL SYSPTR QTEMP@

7-32

System API Programming V4R1

is unique to each job on the
are two data elements that can
pointer to the system entry
is the address of the QTEMP
data element in the PCO is NOT

DEF(PCO)
DEF(PCO)

POS( 1);
POS(65);

/\
/\
/\
/\
/\
/\
/\
/\
/\
/\
/\
/\
/\
/\

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
BIN( 4) DEF(S_RECEIVER) POS( 1) INIT(8);
DCL DD S_BYTAVL
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
CHAR(129) BAS(L_RECEIVER@);
DCL DD L_BYTPRV
BIN( 4) DEF(L_RECEIVER) POS( 1);
DCL DD L_BYTAVL
BIN( 4) DEF(L_RECEIVER) POS( 5);
DCL DD L_CONTEXT
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 \
CHAR( 7) DEF(L_RECEIVER) POS(58);
DCL DD \
CHAR(16) DEF(L_RECEIVER) POS(65);
DCL SYSPTR L_ACC_GROUP;
Chapter 7. Machine Interface Programming

7-33

DCL
DCL
DCL
DCL

DD
DD
DD
DD

L_EXT_ATTR
\
L_TIMESTAMP
L_ENTRY

CHAR( 1)
CHAR( 7)
CHAR( 8)
CHAR(32)

DEF(L_RECEIVER)
DEF(L_RECEIVER)
DEF(L_RECEIVER)
DEF(L_RECEIVER)

POS(81);
POS(82);
POS(89);
POS(97);

/\ Individual object entry layout
DCL DD OBJ_ENTRY
DCL DD OBJ_INFO_X
DCL DD OBJ_TYPE_X
DCL DD OBJ_STYPE_X
DCL DD OBJ_NAME

CHAR(32)
CHAR( 2)
CHAR( 1)
CHAR( 1)
CHAR(3ð)

BAS(OBJ_ENTRY@);
DEF(OBJ_ENTRY) POS(
DEF(OBJ_INFO_X) POS(
DEF(OBJ_INFO_X) POS(
DEF(OBJ_ENTRY) POS(

1);
1);
2);
3);

/\ Define basing pointers:

DCL SPCPTR L_RECEIVER@;
DCL SPCPTR OBJ_ENTRY@;
/\ Define various working variables

DCL DD SIZE
DCL DD NUM_DONE

BIN( 4);
/\ number of objects materialized \/
BIN( 4)
/\ number of objects processed
\/
AUTO INIT(ð);
/\ Define needed parameters for QMHSNDM API
\/
DCL DD MSG_ID
DCL SPCPTR MSG_ID@
DCL DD MSG_FILE
DCL SPCPTR MSG_FILE@
DCL DD MSG_TEXT
DCL DD \

CHAR (7) INIT("
");
INIT(MSG_ID);
CHAR(2ð) INIT("
");
INIT(MSG_FILE);
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

/\ 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)

/\
/\
/\
/\
/\
/\

ITS_AVL:
CONTINUE:

\/
\/
\/
\/
\/
\/

L_BYTPRV, L_BYTAVL / HI(ITS_AVL);
SIZE, L_BYTPRV;
CONTINUE;
SIZE, L_BYTAVL;
SIZE, 96 / ZER(DONE);
SIZE, SIZE, 32;

/\ Address the first object returned
SETSPP

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)
CPYNV
B
CPYNV
SUBN(SB)
DIV

L_BYTPRV, S_BYTAVL;

/\ Materialize the objects within the library
MATCTX

L_RECEIVER@, S_BYTAVL;

/\ Set the bytes provided field to indicate the allocated storage
CPYNV

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

OBJ_ENTRY@, L_ENTRY;

/\ Loop through all materialized entries

MORE:
/\ Convert the hex object type and subtype to character form
CVTHC

OBJ_INFO_C, OBJ_INFO_X;

/\ Copy the object name to the message variable
CPYBLA

OBJ_NAME_T, OBJ_NAME;

/\ 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

CALLX

SEPT(4267), QMHSNDMOL, \;

/\ resume normal array constraint
OVRPGATR

1,4;

/\ and move on to the next entry
ADDN(S)
ADDSPP
CMPNV(B)
/\
/\
/\
/\
/\
/\
/\
/\
/\

NUM_DONE, 1;
OBJ_ENTRY@, OBJ_ENTRY@, 32;
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 initializing static storage for the program. Program invocation is the process of allocating and initializing automatic storage.

Program Activation and Static Storage: Program activation can be done explicitly through the Activate Program (ACTPG) instruction or implicitly by using a call
external (CALLX) instruction when the called program has not been previously activated. 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 initialization 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 applications.

7-36

System API Programming V4R1

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 efficient 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

With the exception of the Get Client Handle API, which is available only through the
Integrated Language Environment (ILE), the client software management and configuration 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 automatically 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 language 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 communications 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

using these APIs range from dedicated point-to-point file transfer to local-areanetwork 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 functions 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

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 appearance 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 interfaces 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

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 specific 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

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 hardware 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 (compilers 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

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 language. 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 conventions 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

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 handling 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 determine 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 appropriate 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

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 connecting 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

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 Transport) functions are used to support the sending and receiving of management services 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 concentration. 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

fied as yes.) The retrieve API allows your application, in conjunction with alert filtering, 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

Data Queue APIs
Data queues are a type of system object that you can create, to which one highlevel 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-infirst-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 purposes, 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

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 permanent 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

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 userdefined 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

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. Currently, 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 interactively 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 directory. 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 document 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

MSF framework processes its messages. These exit programs perform E-mailrelated 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 framework (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

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 individually 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 interface. 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 interested 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

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 communicate 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 notifications from the data queue using existing APIs.

8-18

System API Programming V4R1

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 machinedetected 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 applications.

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 specific 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

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 different 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 compromising 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

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 premastering 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 Programs 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 information 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 specification (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

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 environment. 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, documents 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 interface. 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

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 mechanism 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 structure 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

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

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 management. The set of defined signals is determined by the system. The system specifies 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 attributes, 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 controls). 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

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 represents 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 subagent 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 establish 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 operations. 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 information to the application. No processing occurs in the application until the API

Chapter 8. Use of OS/400 APIs

8-25

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 communications. This interface is based on and compatible with Berkeley Software Distributions 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
├───────────5│
receive
│
│
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

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 processes, 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 functions.
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

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 automatically 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 associated 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

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 miscellaneous 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
Open
Open
Open
Open
Open

List
List
List
List
List
List

of
of
of
of
of
of

Job Log Messages (QGYOLJBL)
Messages (QGYOLMSG)
Objects (QGYOLOBJ)
Objects to be Backed Up (QEZOLBKL)
Printers (QGYRPRTL)
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

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

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

 Copyright IBM Corp. 1997

Task

Location of Example

Using the error code parameter

Page 9-2

Defining data structures

Page 9-5

Defining receiver variables

Page 9-10

Defining list entry format
lengths

Page 9-14

Using null pointers with OPM
APIs

Page 9-18

Defining byte alignment

Page 9-22

Using offsets in user space

Page 9-27

Coding for new function

Page 9-36

9-1

Using the Error Code Parameter
The error code parameter provides a way for you to determine if the API encountered 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
DS
I I
'SPCNAME
'
1 1ð SPC
I I
'PAM
'
11 2ð LIB
\\ OTHER ASSORTED VARIABLES
I
DS
I I
2ððð
B
1
4ðSIZ
I
B
5
8ðSTART
I I
X'ðð'
9
9 INTVAL
\
\ 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

\ 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
CALL 'QUSCRTUS'
C
PARM
SPCNAM
C
PARM 'EXT_ATTR'EXTATR 1ð
C
PARM
SIZ
C
PARM
INTVAL
C
PARM '\ALL
'PUBAUT 1ð
C
PARM 'NO TEXT 'TXTDSC 5ð
C
PARM '\XXXXXXX'REPLAC 1ð
.2/
C
PARM
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 parameter (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
DS
I I
'SPCNAME
'
1 1ð SPC
I I
'QTEMP
'
11 2ð LIB
\\ OTHER ASSORTED VARIABLES
I
DS
I I
2ððð
B
1
4ðSIZ
I
B
5
8ðSTART
I I
X'ðð'
9
9 INTVAL
\
C
Z-ADD16
QUSBNB .1/
\

Chapter 9. Common API Programming Errors

9-3

\ CREATE THE SPACE TO HOLD THE DATA
CALL 'QUSCRTUS'
PARM
SPCNAM
PARM 'EXT_ATTR'EXTATR
PARM
SIZ
PARM
INTVAL
PARM '\ALL
'PUBAUT
PARM 'NO TEXT 'TXTDSC
PARM '\XXXXXXX'REPLAC
PARM
QUSBN
\\
\ DISPLAY EXCEPTION IDENTIFIER TO THE USER
C
QUSBNC
IFGT \ZEROS
C
EXSR DSPERR
C
END
\
C
SETON
\
C
DSPERR BEGSR
C
DSPLY
QUSBND
C
ENDSR
C
C
C
C
C
C
C
C
C

9-4

System API Programming V4R1

1ð

1ð
5ð
1ð

.2/

.4/

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 variable) 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
DS
I I
'\ALL
'
1 1ð JOB
I I
'\ALL
'
11 2ð USER
I I
'\ALL '
21 26 JOBNUM
\\ JOBLð1ðð FORMAT RETURNED FROM QUSLJOB API
\\ INCORRECTLY CODE THE JNAME/USRNAM LENGTHS
IRECVR
DS
I
1 12 JNAME
.5/
Chapter 9. Common API Programming Errors

9-5

I
I
I
I
I
I
I

13
21
27
43
53
54
55

2ð
26
42
52
53
54
56

USRNAM
JOBNBR
JOBID
JSTAT
JTYPE
JSUBT
RESRV

.5/

\\
ISPCNAM
DS
I I
'SPCNAME
'
1 1ð SPC
I I
'QTEMP
'
11 2ð LIB
\\ OTHER ASSORTED VARIABLES
I
DS
I I
2ððð
B
1
4ðSIZ
I I
B
5
8ðSTART
I I
B
9 12ðLENDTA
I I
X'ðð'
13
13INTVAL
\
\ SET UP TO ACCEPT EXCEPTIONS
C
Z-ADD\ZEROS
QUSBNB
\
\ CREATE THE SPACE TO HOLD THE DATA
C
CALL 'QUSCRTUS'
C
PARM
SPCNAM
C
PARM 'EXT_ATTR'EXTATR 1ð
C
PARM
SIZ
C
PARM
INTVAL
C
PARM '\ALL
'PUBAUT 1ð
C
PARM 'TEXT DSC'TXTDSC 5ð
C
PARM '\YES
'REPLAC 1ð
C
PARM
QUSBN
\
\ CALL THE API TO LIST THE ACTIVE JOBS
C
CALL 'QUSLJOB'
C
PARM
SPCNAM
C
PARM 'JOBLð1ðð'FORMAT 8
C
PARM
JOBNAM
C
PARM '\ACTIVE 'STAT
1ð
C
PARM
QUSBN
\
\ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE
C
Z-ADD1
START
C
Z-ADD14ð
LENDTA
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA
C
PARM
QUSBP
C
PARM
QUSBN
\
\ RETRIEVE THE FIRST LIST ENTRY
C
QUSBPQ
ADD 1
START
C
Z-ADD56
LENDTA
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA

9-6

System API Programming V4R1

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
C
CALL 'QUSDLTUS'
C
PARM
SPCNAM
C
PARM
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
DS
I I
'\ALL
'
1 1ð JOB
I I
'\ALL
'
11 2ð USER
I I
'\ALL'
21 26 JOBNUM
\\ JOBLð1ðð FORMAT RETURNED FROM QUSLJOB API
Chapter 9. Common API Programming Errors

9-7

\\
\\
ISPCNAM
DS
I I
'SPCNAME
'
1 1ð SPC
I I
'QTEMP
'
11 2ð LIB
\\ OTHER ASSORTED VARIABLES
I
DS
I I
2ððð
B
1
4ðSIZ
I I
B
5
8ðSTART
I I
B
9 12ðLENDTA
I I
X'ðð'
13 13 INTVAL
\
\ SET UP TO ACCEPT EXCEPTIONS
C
Z-ADD\ZEROS
QUSBNB
\
\ CREATE THE SPACE TO HOLD THE DATA
C
CALL 'QUSCRTUS'
C
PARM
SPCNAM
C
PARM 'EXT_ATTR'EXTATR 1ð
C
PARM
SIZ
C
PARM
INTVAL
C
PARM '\ALL
'PUBAUT 1ð
C
PARM 'TEXT DSC'TXTDSC 5ð
C
PARM '\YES
'REPLAC 1ð
C
PARM
QUSBN
\
\ CALL THE API TO LIST THE ACTIVE JOBS
C
CALL 'QUSLJOB'
C
PARM
SPCNAM
C
PARM 'JOBLð1ðð'FORMAT 8
C
PARM
JOBNAM
C
PARM '\ACTIVE 'STAT
1ð
C
PARM
QUSBN
\
\ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE
C
Z-ADD1
START
C
Z-ADD14ð
LENDTA
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA
C
PARM
QUSBP
C
PARM
QUSBN
\
\ RETRIEVE THE FIRST LIST ENTRY
C
QUSBPQ
ADD 1
START
C
Z-ADD56
LENDTA
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA
C
PARM
QUSDD
C
PARM
QUSBN
\
\ DISPLAY THE JOB NAME
C
DSPLY
QUSDDB >>> Correct job name
\
will now show as
\
'QCPF
'

9-8

System API Programming V4R1

\ DELETE THE SPACE THAT HELD THE DATA
CALL 'QUSDLTUS'
PARM
SPCNAM
PARM
QUSBN
\\
C
SETON
C
C
C

Chapter 9. Common API Programming Errors

9-9

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 programs 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
DS
I I
'\ALL
'
1 1ð JOB
I I
'\ALL
'
11 2ð USER
I I
'\ALL'
21 26 JOBNUM
ISPCNAM
DS
I I
'SPCNAME
'
1 1ð SPC
I I
'QTEMP
'
11 2ð LIB

9-10

System API Programming V4R1

\\ OTHER ASSORTED VARIABLES
I
DS
I I
2ððð
B
1
4ðSIZ
I
B
5
8ðSTART
I
B
9 12ðLENDTA
I I
X'ðð'
13 13 INTVAL
\
\ SET UP TO ACCEPT EXCEPTIONS
C
Z-ADD\ZEROS
QUSBNB
\
\ CREATE THE SPACE TO HOLD THE DATA
C
CALL 'QUSCRTUS'
C
PARM
SPCNAM
C
PARM 'EXT_ATTR'EXTATR 1ð
C
PARM
SIZ
C
PARM
INTVAL
C
PARM '\ALL
'PUBAUT 1ð
C
PARM 'TEXT DSC'TXTDSC 5ð
C
PARM '\YES
'REPLAC 1ð
C
PARM
QUSBN
\
\ CALL THE API TO LIST THE ACTIVE JOBS
C
CALL 'QUSLJOB'
C
PARM
SPCNAM
C
PARM 'JOBLð1ðð'FORMAT 8
C
PARM
JOBNAM
C
PARM '\ACTIVE 'STAT
1ð
C
PARM
QUSBN
\
\ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE
C
Z-ADD1
START
C
Z-ADD14ð
LENDTA
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA
C
PARM
QUSBP
C
PARM
QUSBN
\
\ RETRIEVE THE LIST ENTRIES
C
QUSBPQ
ADD 1
START
\
C
Z-ADD6ð
LENDTA
.8/
\
C
Z-ADD1
X
9ð
C
X
DOWLEQUSBPS
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA
C
PARM
RECVR 5ð .7/
C
PARM
QUSBN
\
C
DSPLY
QUSBN
\
C
ADD QUSBPT
START
C
ADD 1
X
C
END
Chapter 9. Common API Programming Errors

9-11

\ DELETE THE SPACE THAT HELD THE DATA
CALL 'QUSDLTUS'
PARM
SPCNAM
PARM
QUSBN
\
C
SETON
C
C
C

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
DS
I I
'\ALL
'
1 1ð JOB
I I
'\ALL
'
11 2ð USER
I I
'\ALL'
21 26 JOBNUM
ISPCNAM
DS
I I
'SPCNAME
'
1 1ð SPC
I I
'QTEMP
'
11 2ð LIB
\\ OTHER ASSORTED VARIABLES
I
DS
I I
2ððð
B
1
4ðSIZ
I
B
5
8ðSTART
I
B
9 12ðLENDTA
I I
X'ðð'
13 13 INTVAL
\
\ SET UP TO ACCEPT EXCEPTIONS
C
Z-ADD\ZEROS
QUSBNB
\

9-12

System API Programming V4R1

\ CREATE THE SPACE TO HOLD THE DATA
CALL 'QUSCRTUS'
PARM
SPCNAM
PARM 'EXT_ATTR'EXTATR 1ð
PARM
SIZ
PARM
INTVAL
PARM '\ALL
'PUBAUT 1ð
PARM 'TEXT DSC'TXTDSC 5ð
PARM '\YES
'REPLAC 1ð
PARM
QUSBN
\
\ CALL THE API TO LIST THE ACTIVE JOBS
C
CALL 'QUSLJOB'
C
PARM
SPCNAM
C
PARM 'JOBLð1ðð'FORMAT 8
C
PARM
JOBNAM
C
PARM '\ACTIVE 'STAT
1ð
C
PARM
QUSBN
\
\ RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY
C
Z-ADD1
START
C
Z-ADD14ð
LENDTA
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA
C
PARM
QUSBP
C
PARM
QUSBN
\
\ RETRIEVE LIST ENTRIES
C
QUSBPQ
ADD 1
START
\
C
Z-ADD6ð
LENDTA
\
C
Z-ADD1
X
9ð
C
X
DOWLEQUSBPS
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA
C
PARM
RECVR 6ð
C
PARM
QUSBN
\
C
MOVELRECVR
QUSDD
C
ADD QUSBPT
START
C
ADD 1
X
C
END
\ DELETE THE SPACE THAT HELD THE DATA
C
CALL 'QUSDLTUS'
C
PARM
SPCNAM
C
PARM
QUSBN
\
C
SETON
\
C
C
C
C
C
C
C
C
C

FROM THE SPACE

.8/

.9/

Chapter 9. Common API Programming Errors

9-13

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
DS
I I
'\ALL
'
1 1ð JOB
I I
'\ALL
'
11 2ð USER
I I
'\ALL'
21 26 JOBNUM
\ FORMAT JOBLð1ðð FOR QUSLJOB API
\
\\ DATA STRUCTURE CONTAINING SPACE NAME/LIB
ISPCNAM
DS

9-14

System API Programming V4R1

I I
'SPCNAME
'
1 1ð SPC
I I
'QTEMP
'
11 2ð LIB
\\ OTHER ASSORTED VARIABLES
I
DS
I I
2ððð
B
1
4ðSIZ
I
B
5
8ðSTART
I
B
9 12ðLENDTA
I I
X'ðð'
13 13 INTVAL
\
\ SET UP TO ACCEPT EXCEPTIONS
C
Z-ADD\ZEROS
QUSBNB
\
\ CREATE THE SPACE TO HOLD THE DATA
C
CALL 'QUSCRTUS'
C
PARM
SPCNAM
C
PARM 'EXT_ATTR'EXTATR 1ð
C
PARM
SIZ
C
PARM
INTVAL
C
PARM '\ALL
'PUBAUT 1ð
C
PARM 'TEXT DSC'TXTDSC 5ð
C
PARM '\YES
'REPLAC 1ð
C
PARM
QUSBN
\
\ CALL THE API TO LIST THE ACTIVE JOBS
C
CALL 'QUSLJOB'
C
PARM
SPCNAM
C
PARM 'JOBLð1ðð'FORMAT 8
C
PARM
JOBNAM
C
PARM '\ACTIVE 'STAT
1ð
C
PARM
QUSBN
\
\ RETRIEVE INFORMATION ABOUT THE USER SPACE AND ITS CONTENTS
C
Z-ADD1
START
C
Z-ADD14ð
LENDTA
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA
C
PARM
QUSBP
C
PARM
QUSBN
\
\ RETRIEVE LIST ENTRIES
C
QUSBPQ
ADD 1
START
C
Z-ADD52
LENDTA
C
Z-ADD1
X
9ð
C
X
DOWLEQUSBPS
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA
C
PARM
QUSDD
C
PARM
QUSBN
\
\ 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

\ DISPLAY THE INFORMATION RETURNED
MOVELQUSDD
RECVR 52
DSPLY
RECVR
ADD 52
START
.1ð/
ADD 1
X
END
\
\ DELETE THE SPACE THAT HELD THE DATA
C
CALL 'QUSDLTUS'
C
PARM
SPCNAM
C
PARM
QUSBN
\
C
SETON
LR
C
C
C
C
C

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
DS
I I
'\ALL
'
1 1ð JOB
I I
'\ALL
'
11 2ð USER
I I
'\ALL'
21 26 JOBNUM
\
\\ DATA STRUCTURE TO HOLD SPACE NAME
ISPCNAM
DS
I I
'SPCNAME
'
1 1ð SPC
I I
'QTEMP
'
11 2ð LIB
\\ OTHER ASSORTED VARIABLES
I
DS
I I
2ððð
B
1
4ðSIZ
I
B
5
8ðSTART
I
B
9 12ðLENDTA
I I
X'ðð'
13 13 INTVAL
\

9-16

System API Programming V4R1

\ SET UP TO ACCEPT EXCEPTIONS
Z-ADD\ZEROS
QUSBNB
\
\ CREATE THE SPACE TO HOLD THE DATA
C
CALL 'QUSCRTUS'
C
PARM
SPCNAM
C
PARM 'EXT_ATTR'EXTATR 1ð
C
PARM
SIZ
C
PARM
INTVAL
C
PARM '\ALL
'PUBAUT 1ð
C
PARM 'TEXT DSC'TXTDSC 5ð
C
PARM '\YES
'REPLAC 1ð
C
PARM
QUSBN
\
\ CALL THE API TO LIST THE ACTIVE JOBS
C
CALL 'QUSLJOB'
C
PARM
SPCNAM
C
PARM 'JOBLð1ðð'FORMAT 8
C
PARM
JOBNAM
C
PARM '\ACTIVE 'STAT
1ð
C
PARM
QUSBN
\
\ RETRIEVE INFORMATION ABOUT THE USER SPACE AND ITS CONTENTS
C
Z-ADD1
START
C
Z-ADD14ð
LENDTA
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA
C
PARM
QUSBP
C
PARM
QUSBN
\
\ RETRIEVE THE FIRST LIST ENTRY BASED ON THE LIST ENTRY OFFSET
\ FOUND IN THE SPACE HEADER
C
QUSBPQ
ADD 1
START
C
Z-ADD52
LENDTA
C
Z-ADD1
X
9ð
C
X
DOWLEQUSBPS
C
CALL 'QUSRTVUS'
C
PARM
SPCNAM
C
PARM
START
C
PARM
LENDTA
C
PARM
QUSDD
C
PARM
QUSBN
\
\ RETRIEVE THE NEXT LIST ENTRY (SPECIFYING LIST ENTRY LENGTH
\ RETRIEVED FROM THE SPACE HEADER)
C
ADD QUSBPT
START
.11/
\
\ DISPLAY THE INFORMATION RETURNED
C
MOVELQUSDD
RECVR 52
C
DSPLY
RECVR
C
ADD 1
X
C
END
\
\ DELETE THE SPACE THAT HELD THE DATA
C
CALL 'QUSDLTUS'
C
PARM
SPCNAM
C
PARM
QUSBN
\\
C
SETON
LR
C

Chapter 9. Common API Programming Errors

9-17

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 conceptually 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 function 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:
\/
/\

\/
/\

9-18

System API Programming V4R1

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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
", text_description,
"\YES
", &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
NULL, NULL, &error_code); .12/

\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);
}

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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
\/
/\Program Name: PGM2
\/
/\
\/
/\Program Language: ILE C
\/
/\
\/
/\Description: This sample program illustrates the correct
\/
/\
use of ignored and null parameters.
\/
/\
\/
/\Header Files Included:
\/
/\

\/
/\

\/
/\
\/
/\APIs Used: QUSCRTUS - Create User Space
\/
/\
QDBLDBR - List Database Relations
\/
/\
QUSPTRUS - Retrieve Pointer to User Space
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
#include
#include
#include
#include
#include
#include
#include
main()
{
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ initialize program data elements
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
char initial_value = ðxðð;
char text_description[5ð] =
"test of QDBLDBR API
char qualified_usrspc_name[2ð] = "GETLDBR
Qus_EC_t error_code;
Qus_Generic_Header_ð1ðð_t \header_ptr;
error_code.Bytes_Provided = ð;

";
QTEMP

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Create the user space to hold API results
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
QUSCRTUS(qualified_usrspc_name, "SPACE
", 1,
&initial_value, "\ALL
", text_description,
"\YES
", &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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
QDBLDBR(qualified_usrspc_name, "DBRLð1ðð", "\ALL
" ", " ", &error_code);
.13/

\CURLIB

Chapter 9. Common API Programming Errors

9-21

Defining Byte Alignment
Correct byte alignment ensures that data used with an API is correct. Byte alignment 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:
\/
/\

\/
/\

\/
/\
\/
/\ APIs Used:
QusAddExitProgram
- Add an exit program
\/
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Includes
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
#include
#include
#include
#include
#include
#include
#include
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Structures
\/

9-22

System API Programming V4R1

/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
typedef struct {
Qus_EC_t ec_fields;
char
exception_data[1ðð];
} error_code_struct;

/\ Error code

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;
.14/
int
CCSID;
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)
\/
/\
Exit program data CCSID = 37
(BIN(4) field)
\/
/\
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
num_rec;
\/
/\
Qus_Vlen_Rec_4_t replace_rec;
\/
/\
char
replace;
\/
/\
Qus_Vlen_Rec_4_t CCSID_rec;
\/
/\
int
CCSID;
\/
/\
Qus_Vlen_Rec_4_t desc_rec;
\/
/\
char
desc[5ð];
\/
/\
} addep_attributes;
\/
Chapter 9. Common API Programming Errors

9-23

/\
\/
/\ 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;
.15/
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;
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

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:
\/
/\

\/
/\

\/
/\
\/
/\ APIs Used:
QusAddExitProgram
- Add an exit program
\/
/\
\/
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Includes
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
#include
#include
#include
#include
#include
#include
#include
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Structures
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
typedef struct {
Qus_EC_t ec_fields;
char
exception_data[1ðð];
} error_code_struct;

/\ Error code

typedef struct {
int
Qus_Vlen_Rec_4_t
char
char

/\ Exit program attribute keys\/
num_rec;
replace_rec;
replace;
Reserved[3];

.16/

Chapter 9. Common API Programming Errors

9-25

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)
\/
/\
Exit program data CCSID = 37
(BIN(4) field)
\/
/\
Exit program description='THIS IS A TEST EXIT PROGRAM'
\/
/\
(CHAR(5ð) field)
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
attrib_keys.replace_rec.Length_Vlen_Record=16;
.17/
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;
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

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.
base 1 language while the APIs produce information using a base of
pensate for APIs producing information at base 0, the API user must
decimal and hexadecimal offsets to formats that are contained in the
Reference book.

RPG is a
0. To comadd 1 to all
System API

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\
way of using the offset in a user space.
I\
I\Header Files Included: QUSGEN - Generic Header of a User Space
I\
QUSEC - Error Code Parameter
I\
(Copied into Program)
I\
QUSLOBJ - List Objects API
I\
I\APIs Used: QUSCRTUS - Create User Space
I\
QUSLOBJ - List Objects
I\
QUSRTVUS - Retrieve User Space
I\
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

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ððð
3D1ð 9312ð1 DPOHLSON: New Include
I\
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
DS
I\
Qus EC
I
B
1
4ðQUSBNB
I\
Bytes Provided
I
B
5
8ðQUSBNC
I\
Bytes Available
I
9 15 QUSBND
I\
Exception Id
I
16 16 QUSBNF
I\
Reserved
I\
17 17 QUSBNG
I\

9-28

System API Programming V4R1

I\
Varying length
I
17 1ðð QUSBNG
I\
I\ List Objects API Include
I\
I/COPY QSYSINC/QRPGSRC,QUSLOBJ
I\
I\ Qualified User Space Data Structure
I\
IUSERSP
DS
I I
'APIUG1
'
1 1ð USRSPC
I I
'QGPL
'
11 2ð SPCLIB
i\ Qualified Object Name Data Structure
IOBJECT
DS
I I
'\ALL
'
1 1ð OBJNAM
I I
'QGPL
'
11 2ð OBJLIB
I\
I\ Miscellaneous Data Structure
I\
I
DS
I\ Set up parameters for the Create User Space API
I I
'TESTUSRSPC'
1 1ð EXTATR
I I
X'ðð'
11 11 INTVAL
I
12 12 RSVD1
I I
256
B 13 16ðINTSIZ
I I
'\USE
'
17 26 PUBAUT
I I
'TEXT DESCRIPTION 27 76 TEXT
I
'FOR USER SPACE I
'CALLED APIUG1 '
I I
'\YES
'
77 87 REPLAC
I\ Set up parameters for the List Objects API
I I
'OBJLð1ðð'
88 95 FORMAT
I I
'\ALL
'
96 1ð5 OBJTYP
I
1ð6 1ð8 RSVD2
I\ Set up parameters for the Retrieve User Space API
I I
1
B 1ð9 112ðSTRPOS
I I
192
B 113 116ðLENDTA
I
B 117 12ððCOUNT
C\
C\ Create a user space called APIUG1 in library QGPL.
C\
C
Z-ADD1ðð
QUSBNB
C
CALL 'QUSCRTUS'
C
PARM
USERSP
C
PARM
EXTATR
C
PARM
INTSIZ
C
PARM
INTVAL
C
PARM
PUBAUT
C
PARM
TEXT
C
PARM
REPLAC
C
PARM
QUSBN
C\ See if any errors were returned in the error code parameter.
C
EXSR ERRCOD
C\
C\ Get a list of all objects in the QGPL library.
C\
C
CALL 'QUSLOBJ'
C
PARM
USERSP
Chapter 9. Common API Programming Errors

9-29

C
C
C
C
C\
C
C\
C\
C\
C\
C\
C\
C
C
C
C
C
C
C\
C
C\
C\
C\
C\
C\
C\
C\
C\
C
C
C\
C\
C\
C
C
C
C
C\
C
C
C
C
C
C
C
C\
C
C\
C\
C\
C\
C
C
C
C
C\
C\
C\

9-30

PARM
FORMAT
PARM
OBJECT
PARM
OBJTYP
PARM
QUSBN
See if any errors were returned in the error code parameter.
EXSR ERRCOD
Look at the generic header.
The generic header contains information
about the list data section that is needed when processing
the entries.
CALL 'QUSRTVUS'
PARM
USERSP
PARM
STRPOS
PARM
LENDTA
PARM
QUSBP
PARM
QUSBN
See if any errors were returned in the error code parameter.
EXSR ERRCOD
Check the information status field, QUSBPJ, to see if
the API was able to return all the information.
Possible values are:
C -- Complete and accurate
P -- Partial but accurate
I -- Incomplete
QUSBPJ
QUSBPJ

IFEQ 'C'
OREQ 'P'

Check to see if any entries were put into the user space.
QUSBPS

IFGT ð
Z-ADD1
COUNT
Z-ADDQUSBPQ
STRPOS .18/
Z-ADD3ð
LENDTA
Walk through all the entries in the user space.
COUNT
DOWLEQUSBPS
CALL 'QUSRTVUS'
PARM
USERSP
PARM
STRPOS
PARM
LENDTA
PARM
QUSDM
PARM
QUSBN
See if any errors were returned in the error code parameter.
EXSR ERRCOD

Process the objects.
ADD 1
ADD QUSBPT
ENDDO
ENDIF

COUNT
STRPOS

Information in the user space is not accurate

System API Programming V4R1

C
C\
C\
C\
C
C
C
C\
C
C\
C
C
C\
C\
C\
C\
C\
C\
C
C
C\
C\
C\
C
C

ENDIF
Delete the user space called APIUG1 in library QGPL.
CALL 'QUSDLTUS'
PARM
USERSP
PARM
QUSBN
See if any errors were returned in the error code parameter.
EXSR ERRCOD
SETON
RETRN

End of MAINLINE
Subroutine to handle errors returned in the error code
parameter.
ERRCOD
QUSBNC

BEGSR
IFGT ð

Process errors returned from the API.
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\
way of using offsets in user space.
I\
I\Header Files Included: QUSGEN - Generic Header of a User Space
I\
QUSEC - Error Code Parameter
I\
(Copied into Program)
I\
QUSLOBJ - List Objects API
I\
I\APIs Used: QUSCRTUS - Create User Space
I\
QUSLOBJ - List Objects
I\
QUSRTVUS - Retrieve User Space
I\
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

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ððð
3D1ð 9312ð1 DPOHLSON: New Include
I\
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
DS
I\
Qus EC
I
B
1
4ðQUSBNB
I\
Bytes Provided
I
B
5
8ðQUSBNC
I\
Bytes Available
I
9 15 QUSBND
I\
Exception Id
I
16 16 QUSBNF

9-32

System API Programming V4R1

I\
Reserved
I\
17 17 QUSBNG
I\
I\
Varying length
I
17 1ðð QUSBNG
I\
I\ List Objects API Include
I\
I/COPY QSYSINC/QRPGSRC,QUSLOBJ
I\
I\ Qualified User Space Data Structure
I\
IUSERSP
DS
I I
'APIUG1
'
1 1ð USRSPC
I I
'QGPL
'
11 2ð SPCLIB
i\ Qualified Object Name Data Structure
IOBJECT
DS
I I
'\ALL
'
1 1ð OBJNAM
I I
'QGPL
'
11 2ð OBJLIB
I\
I\ Miscellaneous Data Structure
I\
I
DS
I\ Set up parameters for the Create User Space API
I I
'TESTUSRSPC'
1 1ð EXTATR
I I
X'ðð'
11 11 INTVAL
I
12 12 RSVD1
I I
256
B 13 16ðINTSIZ
I I
'\USE
'
17 26 PUBAUT
I I
'TEXT DESCRIPTION 27 76 TEXT
I
'FOR USER SPACE I
'CALLED APIUG2 '
I I
'\YES
'
77 87 REPLAC
I\ Set up parameters for the List Objects API
I I
'OBJLð1ðð'
88 95 FORMAT
I I
'\ALL
'
96 1ð5 OBJTYP
I
1ð6 1ð8 RSVD2
I\ Set up parameters for the Retrieve User Space API
I I
1
B 1ð9 112ðSTRPOS
I I
192
B 113 116ðLENDTA
I
B 117 12ððCOUNT
C\
C\ Create a user space called APIUG1 in library QGPL.
C\
C
Z-ADD1ðð
QUSBNB
C
CALL 'QUSCRTUS'
C
PARM
USERSP
C
PARM
EXTATR
C
PARM
INTSIZ
C
PARM
INTVAL
C
PARM
PUBAUT
C
PARM
TEXT
C
PARM
REPLAC
C
PARM
QUSBN
C\ See if any errors were returned in the error code parameter.
C
EXSR ERRCOD
C\
C\ Get a list of all objects in the QGPL library.
Chapter 9. Common API Programming Errors

9-33

C\
C
C
C
C
C
C
C\
C
C\
C\
C\
C\
C\
C
C
C
C
C
C
C\
C
C\
C\
C\
C\
C\
C\
C\
C\
C
C
C\
C\
C\
C
C
C\
C\
C
C
C\
C
C
C
C
C
C
C
C\
C
C\
C\
C\
C\
C
C
C

9-34

CALL 'QUSLOBJ'
PARM
USERSP
PARM
FORMAT
PARM
OBJECT
PARM
OBJTYP
PARM
QUSBN
See if any errors were returned in the error code parameter.
EXSR ERRCOD
Look at the generic header. This contains information
about the list data section that is needed when processing
the entries.
CALL 'QUSRTVUS'
PARM
USERSP
PARM
STRPOS
PARM
LENDTA
PARM
QUSBP
PARM
QUSBN
See if any errors were returned in the error code parameter.
EXSR ERRCOD

Check the information status field, QUSBPJ, to see if the
API was able to return all the information. Possible values
are: C -- Complete and accurate
P -- Partial but accurate
I -- Incomplete.
QUSBPJ
QUSBPJ

IFEQ 'C'
OREQ 'P'

Check to see if any entries were put into the user space.
QUSBPS

IFGT ð
Z-ADD1
COUNT
Because RPG is Base 1, the offset must be increased by one.
ADD 1
STRPOS
.19/
Z-ADD3ð
LENDTA
Walk through all the entries in the user space.
COUNT
DOWLEQUSBPS
CALL 'QUSRTVUS'
PARM
USERSP
PARM
STRPOS
PARM
LENDTA
PARM
QUSDM
PARM
QUSBN
See if any errors were returned in the error code parameter.
EXSR ERRCOD
QUSBPQ

Process the objects.

System API Programming V4R1

ADD 1
ADD QUSBPT
ENDDO

COUNT
STRPOS

C
C\
C\
C\
C
C\
C\
C\
C\
C
C
C
C\
C
C\
C
C
C\
C\
C\
C\
C\
C\
C
C
C\
C\
C\
C
C

ENDIF
Information in the user space is not accurate.
ENDIF

Delete the user space called APIUG1 in library QGPL.
CALL 'QUSDLTUS'
PARM
USERSP
PARM
QUSBN
See if any errors were returned in the error code parameter.
EXSR ERRCOD
SETON
RETRN

End of MAINLINE
Subroutine to handle errors returned in the error code
parameter.
ERRCOD
QUSBNC

BEGSR
IFGT ð

Process errors returned from the API.
END
ENDSR

Chapter 9. Common API Programming Errors

9-35

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 function 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\
be "broken" by new functions introduced on the AS/4ðð.
D\
D\
D\
D\Header Files Included: QUSGEN Generic Header of a User Space
D\
(Copied Into Program)
D\
QUSEC Error Code Parameter
D\
(Copied Into Program)
D\
QSYLOBJP - List Objects API
D\
(Copied Into Program)
D\
D\APIs Used: QUSCRTUS - Create User Space
D\
QSYLOBJP - List Objects That Adopt Owner Authority
D\
QUSROBJD - Retrieve Object Description
D\
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

D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D/COPY QSYSINC/QRPGLESRC,QUSEC
D\
DSPC_NAME
S
2ð
INZ('ADOPTS
QTEMP
')
DSPC_SIZE
S
9B ð INZ(1)
DSPC_INIT
S
1
INZ(X'ðð')
DLSTPTR
S
\
DSPCPTR
S
\
DARR
S
1
BASED(LSTPTR) DIM(32767)
DRCVVAR
S
8
DRCVVARSIZ
S
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\
for the user space.
D\
D\Header Files Included: none.
D\
D\Macros List: none.
D\
D\Structure List: Qus_Generic_Header_ð1ðð
D\
Qus_Generic_Header_ð3ðð
D\
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ððð
3D1ð 94ð213 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\Type Definition for the User Space Generic Header.
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
DQUSHð1ðð
DS
BASED(SPCPTR)
.21/
Chapter 9. Common API Programming Errors

9-37

D\
Qus Generic Header ð1ðð
D QUSUA
1
64
D\
User Area
D QUSSGH
65
68B ð
D\
Size Generic Header
D QUSSRL
69
72
D\
Structure Release Level
D QUSFN
73
8ð
D\
Format Name
D QUSAU
81
9ð
D\
API Used
D QUSDTC
91
1ð3
D\
Date Time Created
D QUSIS
1ð4
1ð4
D\
Information Status
D QUSSUS
1ð5
1ð8B ð
D\
Size User Space
D QUSOIP
1ð9
112B ð
D\
Offset Input Parameter
D QUSSIP
113
116B ð
D\
Size Input Parameter
D QUSOHS
117
12ðB ð
D\
Offset Header Section
D QUSSHS
121
124B ð
D\
Size Header Section
D QUSOLD
125
128B ð
D\
Offset List Data
D QUSSLD
129
132B ð
D\
Size List Data
D QUSNBRLE
133
136B ð
D\
Number List Entries
D QUSSEE
137
14ðB ð
D\
Size Each Entry
D QUSSIDLE
141
144B ð
D\
CCSID List Ent
D QUSCID
145
146
D\
Country ID
D QUSLID
147
149
D\
Language ID
D QUSSLI
15ð
15ð
D\
Partial List Indicator
D QUSERVEDðð
151
192
D\
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

D\Description: Include header file for the QSYLOBJP API.
D\
D\Header Files Included: H/QSYLOBJP
D\
H/QSY
D\
D\Macros List: None.
D\
D\Structure List: OBJPð1ðð
D\
OBJPð2ðð
D\
Qsy_OBJP_Header
D\
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ððð
3D1ð 931222 XZYð432: New Include
D\
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
DS
BASED(LSTPTR)
.22/
D\
Qsy OBJP Header
D QSYUNðð
1
1ð
D\
User name
D QSYCVðð
11
3ð
D\
Continuation Value
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D\Record structure for OBJPð1ðð format
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
DQSYð1ððLð2
DS
BASED(LSTPTR) .22/
D\
Qsy OBJPð1ðð List
D QSYNAMEð5
1
1ð
D QSYBRARYð5
11
2ð
D\
Qualified object name
D QSYOBJT12
21
3ð
D\
Object type
D QSYOBJIU
31
31
D\
Object in use
C\
C\ Start of mainline
C\
C
EXSR
INIT
C
EXSR
PROCES
C
EXSR
DONE
C\
Chapter 9. Common API Programming Errors

9-39

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
LST_STATUS
1
C
LST_STATUS
DOUEQ
'C'
C\
C\ If valid information was returned
C\
C
QUSIS
IFEQ
'C'
C
QUSIS
OREQ
'P'
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
EVAL
LSTPTR = SPCPTR
C\
C\ increment LSTPTR to the first list entry
C\
C
EVAL
LSTPTR = %ADDR(ARR(QUSOLD + 1))
C\
C\ and process all of the entries
C\
C
DO
QUSNBRLE
C
QSYOBJT12
IFEQ
'\SQLPKG'
C\
C\ Process \SQLPKG type
C\
C
ELSE
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
C
END
C\
C\ after each entry, increment LSTPTR to the next entry
C\
C
EVAL
LSTPTR = %ADDR(ARR(QUSSEE + 1))
C
END
C
END
C\
C\ When all entries in this user space have been processed, check

9-40

System API Programming V4R1

.2ð/
|
|
|
|
|
|
|
|
|
|
|
↓

C\ if more entries exist than can fit in one user space
C\
C
QUSIS
IFEQ
'P'
C\
C\ by resetting LSTPTR to the start of the user space
C\
C
EVAL
LSTPTR = SPCPTR
C\
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
\BLANKS
C
MOVE
'C'
LST_STATUS
C
ELSE
C\
C\ Else, call QSYLOBJP reusing the User Space to get more
C\ List entries
C\
C
MOVE
QSYCVðð
CONTIN_HDL
C
EXSR
GETLST
C
MOVE
QUSIS
LST_STATUS
C
END
C
END
C
ELSE
C\
C\ And if an unexpected status, log an error (not shown) and exit
C\
C
EXSR
DONE
C
END
C
END
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
GETLST
BEGSR
C\
C\ Call QSYLOBJP to generate a list
C\ The continuation handle is set by the caller of this subroutine.
C\
C
CALL
QSYLOBJP
C
PARM
SPC_NAME
C
PARM
'OBJPð1ðð'
MBR_LIST
8
C
PARM
'\CURRENT'
USR_PRF
1ð
C
PARM
'\ALL'
OBJ_TYPE
1ð
C
PARM
CONTIN_HDL
2ð
C
PARM
QUSEC
C\
C\ Check for errors on QSYLOBJP
C\
C
QUSBAVL
IFGT
ð
C
MOVEL
'QSYLOBJP'
APINAM
1ð
C
EXSR
APIERR
C
END
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
INIT
BEGSR
Chapter 9. Common API Programming Errors

9-41

C\
C\
C\
C\
C\
C
C\
C\
C\
C\
C
C
C
C
C
C
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C
C

9-42

One-time initialization code for this program
Set error code structure to not use exceptions
EVAL

QUSBPRV = %SIZE(QUSEC)

Check to see if the user space was previously created in
QTEMP. If it was, simply reuse it.
CALL
PARM
PARM
PARM
PARM
PARM
PARM

'QUSROBJD'
RCVVAR
RCVVARSIZ
ROBJD_FMT
SPC_NAME
OBJ_TYPE
QUSEC

'OBJDð1ðð'
'\USRSPC'

8
1ð

Check for errors on QUSROBJD
QUSBAVL

IFGT

If CPF98ð1, then user space was not found
QUSEI

IFEQ

'CPF98ð1'

So create a user space for the list generated by QSYLOBJP
CALL
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM

'QUSCRTUS'
'QSYLOBJP

'\ALL'
\BLANKS
'\YES'
'\USER'

SPC_NAME
EXT_ATTR
SPC_SIZE
SPC_INIT
SPC_AUT
SPC_TEXT
SPC_REPLAC
QUSEC
SPC_DOMAIN

1ð

1ð
5ð
1ð
1ð

Check for errors on QUSCRTUS
QUSBAVL

IFGT
MOVEL
EXSR
END

ð
'QUSCRTUS'
APIERR

APINAM

1ð

Else, an error occurred accessing the user space
ELSE
MOVEL
EXSR
END
END

'QUSROBJD'
APIERR

APINAM

Set QSYLOBJP (using GETLST) to start a new list

System API Programming V4R1

MOVE
EXSR

\BLANKS
GETLST

CONTIN_HDL

1ð

C\
C\ Get a resolved pointer to the user space for performance
C\
C
CALL
'QUSPTRUS'
C
PARM
SPC_NAME
C
PARM
SPCPTR
C
PARM
QUSEC
C\
C\ Check for errors on QUSPTRUS
C\
C
QUSBAVL
IFGT
ð
C
MOVEL
'QUSPTRUS'
APINAM
1ð
C
EXSR
APIERR
C
END
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
APIERR
BEGSR
C\
C\ Log any error encountered, and exit the program
C\
C
APINAM
DSPLY
QUSEI
C
EXSR
DONE
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
DONE
BEGSR
C\
C\ Exit the program
C\
C
EVAL
\INLR = '1'
C
RETURN
C
ENDSR

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\
be coded to accept new functions introduced on the AS/4ðð.
C\
C\
C\
C\Header Files Included: QUSGEN Generic Header of a User Space
D\
(Copied Into Program)
C\
QUSEC Error Code Parameter
D\
(Copied Into Program)
C\
QSYLOBJP - List Objects API
Chapter 9. Common API Programming Errors

9-43

D\
(Copied Into Program)
C\
C\APIs Used: QUSCRTUS - Create User Space
C\
QSYLOBJP - List Objects That Adopt Owner Authority
C\
QUSROBJD - Retrieve Object Description
C\
QUSPTRUS - Retrieve Pointer to User Space
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
H
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
D/COPY QSYSINC/QRPGLESRC,QUSEC
D\
DSPC_NAME
S
2ð
INZ('ADOPTS
QTEMP
')
DSPC_SIZE
S
9B ð INZ(1)
DSPC_INIT
S
1
INZ(X'ðð')
DLSTPTR
S
\
DSPCPTR
S
\
DARR
S
1
BASED(LSTPTR) DIM(32767)
DRCVVAR
S
8
DRCVVARSIZ
S
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\
for the user space.
D\
D\Header Files Included: none.
D\
D\Macros List: none.
D\
D\Structure List: Qus_Generic_Header_ð1ðð
D\
Qus_Generic_Header_ð3ðð
D\
D\Function Prototype List: none.
D\
D\Change Activity:
D\
D\CFD List:
D\

9-44

System API Programming V4R1

D\FLAG REASON
LEVEL DATE
PGMR
CHANGE DESCRIPTION
D\---- ------------ ----- ------ --------- ---------------------D\$Að= D2862ððð
3D1ð 94ð213 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\Type Definition for the User Space Generic Header.
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
DQUSHð1ðð
DS
BASED(SPCPTR)
.21/
D\
Qus Generic Header ð1ðð
D QUSUA
1
64
D\
User Area
D QUSSGH
65
68B ð
D\
Size Generic Header
D QUSSRL
69
72
D\
Structure Release Level
D QUSFN
73
8ð
D\
Format Name
D QUSAU
81
9ð
D\
API Used
D QUSDTC
91
1ð3
D\
Date Time Created
D QUSIS
1ð4
1ð4
D\
Information Status
D QUSSUS
1ð5
1ð8B ð
D\
Size User Space
D QUSOIP
1ð9
112B ð
D\
Offset Input Parameter
D QUSSIP
113
116B ð
D\
Size Input Parameter
D QUSOHS
117
12ðB ð
D\
Offset Header Section
D QUSSHS
121
124B ð
D\
Size Header Section
D QUSOLD
125
128B ð
D\
Offset List Data
D QUSSLD
129
132B ð
D\
Size List Data
D QUSNBRLE
133
136B ð
D\
Number List Entries
D QUSSEE
137
14ðB ð
D\
Size Each Entry
D QUSSIDLE
141
144B ð
D\
CCSID List Ent
D QUSCID
145
146
D\
Country ID
D QUSLID
147
149
D\
Language ID
D QUSSLI
15ð
15ð
D\
Partial List Indicator
D QUSERVEDðð
151
192
D\
Reserved
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D\
D\ The following QSYLOBJP include is copied into this program so
Chapter 9. Common API Programming Errors

9-45

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\
H/QSY
D\
D\Macros List: None.
D\
D\Structure List: OBJPð1ðð
D\
OBJPð2ðð
D\
Qsy_OBJP_Header
D\
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ððð
3D1ð 931222 XZYð432: New Include
D\
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
DS
BASED(LSTPTR)
.22/
D\
Qsy OBJP Header
D QSYUNðð
1
1ð
D\
User name
D QSYCVðð
11
3ð
D\
Continuation Value
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D\Record structure for OBJPð1ðð format
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
DQSYð1ððLð2
DS
BASED(LSTPTR)
.22/
D\
Qsy OBJPð1ðð List
D QSYNAMEð5
1
1ð

9-46

System API Programming V4R1

D QSYBRARYð5
11
2ð
D\
Qualified object name
D QSYOBJT12
21
3ð
D\
Object type
D QSYOBJIU
31
31
D\
Object in use
C\
C\ Start of mainline
C\
C
EXSR
INIT
C
EXSR
PROCES
C
EXSR
DONE
C\
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
LST_STATUS
1
C\
C
LST_STATUS
DOUEQ
'C'
C\
C\ If valid information was returned
C\
C
QUSIS
IFEQ
'C'
C
QUSIS
OREQ
'P'
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
EVAL
LSTPTR = SPCPTR
C\
C\ increment LSTPTR to the first list entry
C\
C
EVAL
LSTPTR = %ADDR(ARR(QUSOLD + 1))
C\
C\ and process all of the entries
C\
C
DO
QUSNBRLE
C
QSYOBJT12
IFEQ
'\SQLPKG'
C\
C\ Process \SQLPKG type
.23/
C\
|
C
ELSE
|
C
QSYOBJT12
IFEQ
'\PGM'
|
C\
|
C\ Process \PGM type
|
C\
|
C
QSYNAMEð5
DSPLY
|
C
ELSE
|
Chapter 9. Common API Programming Errors

9-47

C
QSYOBJT12
IFEQ
'\SRVPGM'
|
C\
|
C\ Process \SRVPGM type
|
C\
|
C
ELSE
|
C\
↓
C\
C\ Unknown type, log an error and exit from program (maybe..)
C\
C
EXSR
DONE
C
END
C
END
C
END
C\
C\ after each entry, increment LSTPTR to the next entry
C\
C
EVAL
LSTPTR = %ADDR(ARR(QUSSEE + 1))
C
END
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
QUSIS
IFEQ
'P'
C\
C\ by resetting LSTPTR to the start of the user space
C\
C
EVAL
LSTPTR = SPCPTR
C\
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
\BLANKS
C
MOVE
'C'
LST_STATUS
C
ELSE
C\
C\ Else, call QSYLOBJP reusing the user space to get more
C\ list entries
C\
C
MOVE
QSYCVðð
CONTIN_HDL
C
EXSR
GETLST
C
MOVE
QUSIS
LST_STATUS
C
END
C
END
C
ELSE
C\
C\ And if an unexpected status, log an error (not shown) and exit
C\
C
EXSR
DONE
C
END
C
END
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
GETLST
BEGSR

9-48

System API Programming V4R1

C\
C\ Call QSYLOBJP to generate a list
C\ The continuation handle is set by the caller of this subroutine.
C\
C
CALL
QSYLOBJP
C
PARM
SPC_NAME
C
PARM
'OBJPð1ðð'
MBR_LIST
8
C
PARM
'\CURRENT'
USR_PRF
1ð
C
PARM
'\ALL'
OBJ_TYPE
1ð
C
PARM
CONTIN_HDL
2ð
C
PARM
QUSEC
C\
C\ Check for errors on QSYLOBJP
C\
C
QUSBAVL
IFGT
ð
C
MOVEL
'QSYLOBJP'
APINAM
1ð
C
EXSR
APIERR
C
END
C
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
'QUSROBJD'
C
PARM
RCVVAR
C
PARM
RCVVARSIZ
C
PARM
'OBJDð1ðð'
ROBJD_FMT
8
C
PARM
SPC_NAME
C
PARM
'\USRSPC'
OBJ_TYPE
1ð
C
PARM
QUSEC
C\
C\ Check for errors on QUSROBJD
C\
C
QUSBAVL
IFGT
ð
C\
C\ If CPF98ð1, then user space was not found
C\
C
QUSEI
IFEQ
'CPF98ð1'
C\
C\ So create a user space for the list generated by QSYLOBJP
C\
C
CALL
'QUSCRTUS'
C
PARM
SPC_NAME
C
PARM
'QSYLOBJP ' EXT_ATTR
1ð
C
PARM
SPC_SIZE
C
PARM
SPC_INIT
C
PARM
'\ALL'
SPC_AUT
1ð
C
PARM
\BLANKS
SPC_TEXT
5ð
C
PARM
'\YES'
SPC_REPLAC
1ð
C
PARM
QUSEC
Chapter 9. Common API Programming Errors

9-49

C
PARM
'\USER'
SPC_DOMAIN
1ð
C\
C\ Check for errors on QUSCRTUS
C\
C
QUSBAVL
IFGT
ð
C
MOVEL
'QUSCRTUS'
APINAM
1ð
C
EXSR
APIERR
C
END
C\
C\ Else, an error occurred accessing the user space
C\
C
ELSE
C
MOVEL
'QUSROBJD'
APINAM
1ð
C
EXSR
APIERR
C
END
C
END
C\
C\ Set QSYLOBJP (using GETLST) to start a new list
C\
C
MOVE
\BLANKS
CONTIN_HDL
C
EXSR
GETLST
C\
C\ Get a resolved pointer to the user space for performance
C\
C
CALL
'QUSPTRUS'
C
PARM
SPC_NAME
C
PARM
SPCPTR
C
PARM
QUSEC
C\
C\ Check for errors on QUSPTRUS
C\
C
QUSBAVL
IFGT
ð
C
MOVEL
'QUSPTRUS'
APINAM
1ð
C
EXSR
APIERR
C
END
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
APIERR
BEGSR
C\
C\ Log any error encountered, and exit the program
C\
C
APINAM
DSPLY
QUSEI
C
EXSR
DONE
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
DONE
BEGSR
C\
C\ Exit the program
C\
C
EVAL
\INLR = '1'
C
RETURN
C
ENDSR

9-50

System API Programming V4R1

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
9
10
11
12
13
14
15
Note:

ABCPGMMRM1
ABCPGMMRM2
ABCPGMMRI1
ABCPGMMRI2
ABCPGM
QCLSRC
ABCDSPF
ABCPF
ABCMSG
ABC
ABCPNLGRP
ABC0050
ABC0029
ABC0050
ABC

*PGM
*PGM
*PGM
*PGM
*PGM
*FILE(SRCPF)
*FILE(DSPF)
*FILE(PF)
*MSGF
*CMD
*PNLGRP
*PRDDFN
*PRDLOD
*PRDLOD
*LIB

MRM1 preprocessing program
MRM postprocessing program
MRI2 preprocessing program
MRI postprocessing program
CPP3 for ABC command
Source physical file
Display file
Physical file
Message file
Command for ABC Product
Panels for ABC
Product definition
Product load for MRI
Product load for MRM
ABC Product

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 Creating 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

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
Build
Application

Product
Definition
Product
Load

Product
Objects

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

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\
package your product like IBM products.
F\
F\Header Files Included: QUSEC - Error Code Parameter
F\
(Copied into Program)
F\
QSZCRTPD - Create Product Definition API
F\
QSZCRTPL - Create Product Load API
F\
QSZPKGPO - Package Product Option API
F\
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

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ððð
3D1ð 9312ð1 DPOHLSON: New Include
I\
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
DS
I\
Qus EC
I
B
1
4ðQUSBNB
I\
Bytes Provided
I
B
5
8ðQUSBNC
I\
Bytes Available
I
9 15 QUSBND
I\
Exception Id
I
16 16 QUSBNF
I\
Reserved
I\
17 17 QUSBNG
I\
I\
Varying length
I
17 1ðð QUSBNG
I\
I\ Create Product Definition API Include
I\
I/COPY QSYSINC/QRPGSRC,QSZCRTPD

A-4

System API Programming V4R1

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
1
B
1
4ðNUMPOP
I I
1
B
5
8ðNUMLAN
I I
'ABCðð5ð
ABC
'
9 28 PDFN
I I
'ABC Product'
29 78 TEXTD
I I
'5ð72535ð1ð
'
79 92 PHONE
I I
'\NODYNNAM '
93 1ð2 ALWDYN
I I
'\USE
'
1ð3 112 PUBAUT
I I
'ABCPGMMRM2'
113 122 POSTM
I I
'ABCPGMMRM1'
123 132 PREM
I I
'ABCPGMMRI2'
133 142 POSTI
I I
'ABCPGMMRI1'
143 152 PREI
I\
I\ Change Object Information Parameter
ICOBJI
DS
49
I I
3
B
1
4ðNUMKEY
I I
13
B
5
8ðKEY13
I I
4
B
9 12ðLEN13
I
13 16 PID13
I I
12
B 17 2ððKEY12
I I
4
B 21 24ðLEN12
I
25 28 LID12
I I
5
B 29 32ðKEY5
I I
13
B 33 36ðLEN5
I
37 49 LP5
I\
I\ Object Data Structure - Breakdown of fields in Array OBJ
IOBJDS
DS
I
1 1ð NAME
I
11 2ð TYP
I
21 24 PID
I
25 28 LID
I
29 41 LP
I
DS
I
B
1
4ðRCVLEN
I I
ð
B
5
8ðNUMBK
I I
1
B
9 12ðNUMBL
I I
ð
B 13 16ðNUMBM
C\
C\ Beginning of Mainline
C\
C\ Create Product Definition Object - ABCðð5ð
C\
C
EXSR PRDDFN
.1/
C\
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

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
EXSR PKGPO
.4/
C\
C\ Complete; product is ready to ship.
C\
C
SETON
LR
C
RETRN
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\
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
Z-ADD1ðð
QUSBNB
C
MOVEL'ðABCABC' QSZBCB
Product ID
C
MOVEL'V3R1Mð' QSZBCC
Release Level
C
MOVEL'ABCMSG' QSZBCD
Message File
C
MOVEL'\CURRENT'QSZBCF
First Copyright
C
MOVEL'\CURRENT'QSZBCG
Current Copyright
C
MOVEL'9412ð1' QSZBCH
Release Date
C
MOVEL'\NO'
QSZBCJ
Allow multiple rel.
C
MOVEL'\PHONE' QSZBCK
Registration ID Value
C
MOVELPHONE
QSZBCL
Registration ID Value
C\ Fill Product Load Parameter
C
MOVEL'ðððð'
QSZBDB
Product Option Number
C
MOVEL'ABCððð1' QSZBDC
Message ID
C
MOVELALWDYN
QSZBDD
Allow Dynamic Naming
C
MOVEL'5ðð1'
QSZBDF
Code Load ID
C
MOVEL\BLANKS
QSZBDG
Reserved
C\ Fill Language Load List Parameter
C
MOVEL'2924
'QSZBFB
Language Load ID
C
MOVEL'ðððð'
QSZBFC
Product Option Number
C
MOVEL\BLANKS
QSZBFD
Reserved
C\
C\ Create the Product Definition for the ABC Product
C\

A-6

System API Programming V4R1

C
MOVEL'QSZCRTPD'API
1ð
C
CALL 'QSZCRTPD'
C
PARM
PDFN
Qual. Prod. Defn.
C
PARM
QSZBC
Prod. Defn. Info.
C
PARM
QSZBD
Prod. Option List
C
PARM
NUMPOP
# Prod. Options
C
PARM
QSZBF
Lang. Load List
C
PARM
NUMLAN
# Lang. Load List
C
PARM
TEXTD
Text Description
C
PARM
PUBAUT
Public Authority
C
PARM
QUSBN
Error Code
C\ Check for errors returned in the error code parameter.
C
EXSR ERRCOD
C
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\
ABCðð5ð and ABCðð29, for the ABC Product.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
PRDLOD
BEGSR
C\
C\ Setup for Product Load for MRM Objects
C\ Fill Product Load Information Parameter
C
MOVEL'ðABCABC' QSZBHB
Product ID
C
MOVEL'V3R1Mð' QSZBHC
Release Level
C
MOVEL'ðððð'
QSZBHD
Product Option
C
MOVEL'\CODE'
QSZBHF
Product Load Type
C
MOVEL'\CODEDFT'QSZBHG
Load ID
C
MOVEL'\PRDDFN' QSZBHH
Registration ID Type
C
MOVEL\BLANKS
QSZBHJ
Registration ID Value
C
MOVEL'\CURRENT'QSZBCK
Min. Target Release
C
MOVEL\BLANKS
QSZBCL
Reserved
C\
C\ Fill Principal Library Information Parameter
C
MOVEL'ABC'
QSZBJB
Prin. Dev. Lib. Name
C
MOVEL'ABC'
QSZBJC
Prin. Prim. Lib. Name
C
MOVELPOSTM
QSZBJD
Post-Exit Prog. Name
C\
C\ Fill Preoperation Exit Programs Parameter
C
MOVELPREM
QSZBLB
Pre-Exit Prog. Name
C
MOVEL'ABC'
QSZBLC
Dev. Lib. Name
C\
C\ Fill Additional Library List Parameter
C\
None
C\
C\ Fill Folder List Parameter
C\
None
C\
C\ Create the product load for the ABC Product - MRM Objects
Appendix A. Performing Tasks Using APIs—Examples

A-7

C\
C
MOVEL'QSZCRTPL'API
C
CALL 'QSZCRTPL'
C
PARM 'ABCðð5ð' PRDIDN 1ð
Prod. ID Name
C
PARM
QSZBH
Prod. Defn. Info.
C
PARM \BLANKS
SECLIB 1ð
Sec. Lang. Lib
C
PARM
QSZBJ
Principal Lib Info
C
PARM
QSZBK
Add. Library List
C
PARM ð
NUMBK
# Add. Lib. List
C
PARM
QSZBL
Pre-Exit Programs
C
PARM 1
NUMBL
# Pre-Exit Programs
C
PARM
QSZBM
Folder List
C
PARM ð
NUMBM
# Folder List
C
PARM
TEXTD
Text Description
C
PARM '\USE'
PUBAUT
Public Authority
C
PARM
QUSBN
Error Code
C\ Check for errors returned in the error code parameter.
C
EXSR ERRCOD
C\
C\ Setup for Product Load for MRI Objects
C\ Fill Product Load Information Parameter
C
MOVEL'\LNG '
QSZBHF
Product Load Type
C
MOVEL'2924
'QSZBHG
Load ID
C\
C\ Fill Principal Library Information Parameter
C
MOVELPOSTI
QSZBJD
Post-Exit Prog. Name
C\
C\ Fill Preoperation Exit Programs Parameter
C
MOVELPREI
QSZBLB
Pre-Exit Prog. Name
C\
C\ Fill Additional Library List Parameter
C\
None
C\
C\ Fill Folder List Parameter
C\
None
C\
C\ Create the product load for the ABC Product - MRI Objects
C\
C
MOVEL'QSZCRTPL'API
C
CALL 'QSZCRTPL'
C
PARM 'ABCðð29' PRDIDN 1ð
Prod. ID Name
C
PARM
QSZBH
Prod. Defn. Info.
C
PARM 'ABC2924 'SECLIB
Sec. Lang. Lib
C
PARM
QSZBJ
Principal Lib Info
C
PARM
QSZBK
Add. Library List
C
PARM ð
NUMBK
# Add. Lib. List
C
PARM
QSZBL
Pre-Exit Programs
C
PARM 1
NUMBL
# Pre-Exit Programs
C
PARM
QSZBM
Folder List
C
PARM ð
NUMBM
# Folder List
C
PARM
TEXTD
Text Description
C
PARM '\USE'
PUBAUT
Public Authority
C
PARM
QUSBN
Error Code
C\ Check for errors returned in the error code parameter.
C
EXSR ERRCOD
C
ENDSR
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

A-8

System API Programming V4R1

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\
descriptions for all objects that make up the
C\
ABC Product. Currently, 15 objects exist. They
C\
are listed at the end of this program.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
COBJD
BEGSR
C\
C\ Need to associate all objects with the ABC Product
C
1
DO
15
I
3ð
C
MOVE OBJ,I
OBJDS
C
NAME
CAT 'ABC'
QOBJNM 2ð
C
MOVELLP
LP5
C
MOVELPID
PID13
C
MOVELLID
LID12
C
MOVELTYP
TYPE
1ð
C
MOVEL'QLICOBJD'API
C
CALL 'QLICOBJD'
C
PARM
RTNLIB 1ð
Returned Lib. Name
C
PARM
QOBJNM
Qual. Object Name
C
PARM
TYPE
Object Type
C
PARM
COBJI
Chg'd Object Info.
C
PARM
QUSBN
Error Code
C\ Check for any errors returned in the error code parameter.
C
EXSR ERRCOD
C
ENDDO
C
ENDSR
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\
It makes sure that all objects exist that are
C\
associated with the product.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
PKGPO
BEGSR
C\
C\ Setup for packing the ABC Product.
C\ Fill Product Option Information Parameter
C
MOVEL'ðððð'
QSZBRB
Product Option
C
MOVEL'ðABCABC' QSZBRC
Product ID
C
MOVEL'V3R1Mð' QSZBRD
Release Level
Appendix A. Performing Tasks Using APIs—Examples

A-9

C
MOVEL'\ALL
'QSZBRF
Load ID
C
MOVEL\BLANKS
QSZBRG
Reserved
C\
C\ Package the ABC Product.
C\
C\
C
MOVEL'QSZPKGPO'API
C
CALL 'QSZPKGPO'
C
PARM
QSZBR
Prod. Option Info.
C
PARM '\YES'
REPKG
4
Repackage
C
PARM '\NO '
ALWCHG 5
Allow Object Change
C
PARM
QUSBN
Error Code
C\ Check for any errors returned in the error code parameter.
C
EXSR ERRCOD
C
ENDSR
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\
file if any errors are returned in the error code
C\
parameter.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
ERRCOD
BEGSR
C
QUSBNC
IFNE ð
C\
C\ Process errors returned from the API.
C\
C
EXCPTBADNWS
C
END
C
ENDSR
OQPRINT E 1ð6
BADNWS
O
'Failed in API '
O
API
O
'with error '
O
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
ABCPGM
\PGM
QCLSRC
\FILE
ABCDSPF
\FILE

A-10

System API Programming V4R1

ðððð5ðð1ðABCABCV3R1Mð
ðððð5ðð1ðABCABCV3R1Mð
ðððð2924ðABCABCV3R1Mð
ðððð2924ðABCABCV3R1Mð
ðððð5ðð1ðABCABCV3R1Mð
ðððð2924ðABCABCV3R1Mð
ðððð2924ðABCABCV3R1Mð

ABCPF
ABCMSG
ABC
ABCPNLGRP
ABCðð5ð
ABCðð5ð
ABCðð29
ABC

\FILE
\MSGF
\CMD
\PNLGRP
\PRDDFN
\PRDLOD
\PRDLOD
\LIB

ðððð2924ðABCABCV3R1Mð
ðððð2924ðABCABCV3R1Mð
ðððð2924ðABCABCV3R1Mð
ðððð2924ðABCABCV3R1Mð
ðððð5ðð1ðABCABCV3R1Mð
ðððð5ðð1ðABCABCV3R1Mð
ðððð2924ðABCABCV3R1Mð
ðððð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 Information (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 languages, 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 definition 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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Program Name:
RTVFD
\/
/\
\/
/\ Program Language:
ILE C
\/
/\
\/
/\ Description:
Retrieve a file definition template to a \/
/\
user space.
\/
/\
\/
/\ Header Files Included:
\/
/\

\/
/\

\/
/\
\/
/\ APIs Used:
QUSCRTUS - Create User Space
\/
/\
QUSCUSAT - Change User Space Attributes
\/
/\
QUSPTRUS - Retrieve Pointer to User Space \/
/\
QDBRTVFD - Retrieve File Description
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
/\ 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

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
\/
1ð24,
/\ Initial size
\/
&initial_value,
/\ Initial value
\/
"\CHANGE
",
/\ Public authority
\/
descr,
/\ Text description
\/
"\YES
",
/\ Replace if it exists
\/
&error_code,
/\ Error code
\/
"\USER
");
/\ Domain = USER
\/
if (error_flag) {
exit(1);
}
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
Appendix A. Performing Tasks Using APIs—Examples

A-13

/\ Initialize the attributes to change structure.
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
attrib_info.attrib_count = 1;
/\ Number of attributes
\/
attrib_info.keyinfo.Key = 3;
/\ Key of attribute to change \/
attrib_info.keyinfo.Length_Vlen_Record = 1;
/\ Length of data
\/
attrib_info.key_value='1';
/\ Autoextend space
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Change the user space to be automatically extendable.
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
QUSCUSAT(return_lib,
/\ Return library
\/
user_space,
/\ User space name and library \/
&attrib_info,
/\ Attributes to change
\/
&error_code);
/\ 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,
/\ Receiver variable
\/
167767ð4,
/\ Return up to 16MB minus 512 \/
/\ bytes of data
\/
ret_file_lib,
/\ Returned file and library
\/
"FILDð1ðð",
/\ File definition template
\/
file_and_lib,
/\ File and library name
\/
record_fmt,
/\ Record format name
\/
"ð",
/\ No override processing
\/
"\LCL
",
/\ Local system
\/
"\INT
",
/\ Internal formats .1/
\/
&error_code);
/\ 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 Database File Description (QDBRTVFD) API” in the System API Reference book.

A-14

System API Programming V4R1

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 overhead 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 userdomain 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

– 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:
\/
/\

\/
/\

\/
/\
\/
/\APIs Used:
QSNDDTAQ - Send data queue
\/
/\
QRCVDTAQ - Receive data queue
\/
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Includes
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
#include
#include
#include
#include
#include
#include

/\ 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

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 ",
DataLength,
"EXAMPLE
");

/\
/\
/\
/\

Data queue name
Queue library name
Length of queue entry
Data sent to queue

\/
\/
\/
\/

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Receive information from the data queue.
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
QRCVDTAQ("EXAMPLEQ ",
"QUEUELIB ",
&DataLength,
&QueueData,
WaitTime);

/\
/\
/\
/\
/\

Data queue name
Queue library name
Length of queue entry
Data received from queue
Wait time

\/
\/
\/
\/
\/

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

/\
\/
/\Description: This program illustrates how to use APIs to create
\/
/\
and manipulate a user queue.
\/
/\
\/
/\
\/
/\Header Files Included:
\/
/\

\/
/\

\/
/\
\/
/\APIs Used:
QUSCRTUQ - Create a user queue
\/
/\
QUSDLTUQ - Delete a user queue
\/
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\
Includes
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include

/\ from QCLE/h
/\ from QCLE/h
/\ from QCLE/h

\/
\/
\/

/\ from QSYSINC/h
/\ from QSYSINC/h
/\ from QSYSINC/h

\/
\/
\/

A-18

System API Programming V4R1

_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
", which could have
\/
/\
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 \/
/\
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
"VALID
",
"F",
ð,
1ð,
1ð,
1ð,
"\ALL
",
text_desc,
"\YES
",
&error_code,

/\
/\
/\
/\
/\
/\
/\
/\
/\
/\
/\

Qualified user queue name
Extended attribute
Queue type
Key length
Maximum message size
Initial number of messages
Additional number of messages
Public authority
Text Description
Replace existing user queue
Error code

Appendix A. Performing Tasks Using APIs—Examples

\/
\/
\/
\/
\/
\/
\/
\/
\/
\/
\/

A-19

"\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 \/
/\
queue object.
\/
/\ 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.
\/
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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,
&rslvsp_template.Auth);

/\ system pointer to be set
/\ resolve template
/\ 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,
&rslvsp_template,

A-20

System API Programming V4R1

/\ system pointer to be set
/\ resolve template

\/
\/

&queuelib_sysptr,
&rslvsp_template.Auth);

/\ sysptr to library
/\ authority to set in sysptr

\/
\/

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Enqueue the entry.
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
enq_msg_prefix.Msg_Len = 1ð;
enq_msg_prefix.Msg[ð] = '\ð';
/\ Only used for keyed queues\/
memcpy(enq_msg, "EXAMPLE
", 1ð);
_ENQ(&user_queue_obj_sysptr,
&enq_msg_prefix,
(_SPCPTR)enq_msg);

/\ system pointer to user queue \/
/\ message prefix
\/
/\ message text
\/

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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
&error_code);

/\ Qualified user queue name
/\ Error code

\/
\/

Appendix A. Performing Tasks Using APIs—Examples

A-21

A-22

System API Programming V4R1

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 language 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
Retrieving the HOLD Parameter (Exception
Messages)
Handling Error Conditions

ILE C

OPM COBOL

ILE COBOL

OPM RPG

ILE RPG

B-2

B-4

3-6

B-6

3-8

B-8

Retrieving the HOLD Parameter (Error Code
Structure)

B-10

B-12

3-11

B-14

Accessing the HOLD Attribute

B-16

B-18

3-17

B-21

Accessing a Field Value (Initial Library List)

B-22

B-25

3-19

B-29

Using Keys with List Spooled Files API

B-33

B-38

3-24

B-42

Figure B-2. Integrated Language Environment (ILE) API Examples from Chapter 4
Programming Language and Location of Example
Task

ILE C

OPM COBOL

ILE COBOL

OPM RPG

ILE RPG

4-9

B-47

B-50

B-54

B-58

Retrieve Exit Point and Exit Program Information

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

OPM COBOL

ILE COBOL

OPM RPG

ILE RPG

Listing Objects

B-94

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
Logging Software Error (OPM API without
Pointers)

 Copyright IBM Corp. 1997

ILE C

OPM COBOL

ILE COBOL

OPM RPG

ILE RPG

6-2

B-112

N/A

B-116

B-119

B-1

Figure B-4 (Page 2 of 2). Pointer API Examples from Chapter 6
Programming Language and Location of Example
Task
Reporting Software Error (ILE API with
Pointers)

ILE C

OPM COBOL

ILE COBOL

OPM RPG

ILE RPG

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

OPM COBOL

ILE COBOL

OPM RPG

ILE RPG

Program for Packaging a Product

B-129

B-136

A-3

B-144

Retrieving a File Description to a User Space

A-11

B-152

B-155

Working with Data Queues

A-16

B-165

B-169

B-172

Working with User Queues

A-17

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

B-178

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
#include
#include

B-2

System API Programming V4R1

#include
/\ Error Code Parameter Include for the APIs \/
#include .2/
/\ Retrieve Job Description API Include
\/
#include
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
qual_job_desc[2ð];
char
\qual_job_ptr = qual_job_desc;
char
rec_var[39ð];
char
hold_value[1ð];
char
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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
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
\/
39ð, .3/
/\ Receiver Length
\/
"JOBDð1ðð", .5/ /\ Format Name
\/
qual_job_desc,
/\ Qualified Job Description
\/
&error_code);
/\ 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

\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

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\
a job description. It expects errors to be
D\
sent as escape messages.
D\
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

D\
D\ Command string data structure
D\
DCMD_STRING
DS
D
26
INZ('SNDMSG MSG(''HOLD value is ')
D HOLD
1ð
D
15
INZ(''') TOUSR(QPGMR)')
D\
D\ Miscellaneous data structure
D\
.4/
.2/ .3/
DRCVLEN
S
9B ð INZ(%SIZE(QWDDð1ðð))
DFORMAT
S
8
INZ('JOBDð1ðð') .5/
DLENSTR
S
15 5 INZ(%SIZE(CMD_STRING))
C\
C\ Beginning of mainline
C\
C\ Two parameters are being passed into this program
C\
C
\ENTRY
PLIST .8/
C
PARM
JOBD
1ð
C
PARM
JOBD_LIB
1ð
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
QWDRJOBD
C
PARM
QWDDð1ðð
C
PARM
RCVLEN
C
PARM
FORMAT
C
PARM
LFNAM
C
PARM
QUSEC
C\
C
MOVEL
QWDHJQ
HOLD
C\
C\ Let's tell everyone what the hold value was for this job
C\
C
CALL
'QCMDEXC'
C
PARM
CMD_STRING
C
PARM
LENSTR
C\
C
EVAL
\INLR = '1'
C
RETURN
C\
C\ End of MAINLINE
C\

Appendix B. Original Examples in Additional Languages

B-7

Handling Error Conditions—ILE RPG Example
Refer to “Handling Error Conditions—OPM RPG Example” on page 3-8 for the original 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\
a job description. It expects errors to be
D\
sent as escape messages.
D\
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
SDS .12/
D MSG_ID
4ð
46
D\
D\ Command string data structure
D\
DCMD_STRING
DS
D
26
INZ('SNDMSG MSG(''HOLD value is ')
D HOLD
1ð
D
15
INZ(''') TOUSR(QPGMR)')
D\
D\ Miscellaneous data structure
D\
DRCVLEN
S
9B ð INZ(%SIZE(QWDDð1ðð))
DFORMAT
S
8
INZ('JOBDð1ðð')
DLENSTR
S
15 5 INZ(%SIZE(CMD_STRING))
DNO_JOBD
S
47
INZ('SNDMSG MSG(''No such \JOBD D
exists'') TOUSR(QPGMR)')
DNO_JOBD_SZ
S
15 5 INZ(%SIZE(NO_JOBD))
C\
C\ Beginning of mainline
C\
C\ Two parameters are being passed into this program
C\
C
\ENTRY
PLIST
C
PARM
JOBD
1ð
C
PARM
JOBD_LIB
1ð
C\

B-8

System API Programming V4R1

C\
C\
C
C\
C\
C\
C
C\
C\
C\
C
C
C
C
C
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C
C
C\
C\
C\
C
C
C
C
C\
C
C
C\
C\
C\
C\
C\
C
C
C\
C\
C\
C
C
C
C
C

Move the two parameters passed into LFNAM
JOBD

CAT

JOBD_LIB

LFNAM

2ð

Error Code Bytes Provided is set to ð
Z-ADD

CALL
PARM
PARM
PARM
PARM
PARM

QWDRJOBD

.11/

QUSBPRV

Call the API.
ð1 .1ð/
QWDDð1ðð
RCVLEN
FORMAT
LFNAM
QUSEC

Test for an error on the API call
IF

\INð1 = \ON

If there was an error, exit to ERROR subroutine
EXSR

ERROR

Else, process the HOLD value
ELSE
MOVEL

QWDHJQ

HOLD

Let's tell everyone what the hold value was for this job
CALL
PARM
PARM
END

'QCMDEXC'

EVAL
RETURN

\INLR = '1'

CMD_STRING
LENSTR

End of MAINLINE
Subroutine to handle errors received on the CALL
ERROR

BEGSR
IF

MSG_ID = 'CPF98ð1'

Process errors returned from the API
CALL
PARM
PARM
END
ENDSR

'QCMDEXC'
NO_JOBD
NO_JOBD_SZ

Appendix B. Original Examples in Additional Languages

B-9

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
#include
#include
#include
#include

.14/

/\ Error Code Parameter Include for the API
/\ 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
qual_job_desc[2ð];
char
\qual_job_ptr = qual_job_desc;
char
rec_var[39ð];
char
hold_value[1ð];
char
message_id[7];
char
command_string[53];
char
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

/\ 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,
/\ Receiver Variable
\/
39ð,
/\ Receiver Length
\/
"JOBDð1ðð",
/\ Format Name
\/
qual_job_desc,
/\ Qualified Job Description
\/
&error_code);
/\ 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

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

ð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
ð1
ð1
ð1

COMMAND-LENGTH PIC S9(1ð)V99999 COMP-3.
RECEIVER-LENGTH PIC S9(9) COMP-4.
FORMAT-NAME PIC X(8) VALUE 'JOBDð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

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\
a job description. It expects errors to be
D\
returned via the error code parameter.
D\
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
INZ('SNDMSG MSG(''HOLD value is ')
D HOLD
1ð

B-14

System API Programming V4R1

D
15
INZ(''') TOUSR(QPGMR)')
DCMD_STR2
DS
D
43
INZ('SNDMSG MSG(''Program failed D
with message ID ')
D MSG_ID
7
D
15
INZ(''') TOUSR(QPGMR)')
D\
D\ Miscellaneous data structure
D\
DRCVLEN
S
9B ð INZ(%SIZE(QWDDð1ðð))
DFORMAT
S
8
INZ('JOBDð1ðð')
DLENSTR
S
15 5 INZ(%SIZE(CMD_STRING))
DLENSTR2
S
15 5 INZ(%SIZE(CMD_STR2))
C\
C\ Beginning of mainline
C\
C\ Two parameters are being passed into this program
C\
C
\ENTRY
PLIST
C
PARM
JOBD
1ð
C
PARM
JOBD_LIB
1ð
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
QWDRJOBD
C
PARM
QWDDð1ðð
C
PARM
RCVLEN
C
PARM
FORMAT
C
PARM
LFNAM
C
PARM
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
EXSR
ERROR
C\
C\ Else, process the HOLD value
C\
C
ELSE
C
MOVEL
QWDHJQ
HOLD
C\
C\ Let's tell everyone what the hold value was for this job
C\
C
CALL
'QCMDEXC'
C
PARM
CMD_STRING
C
PARM
LENSTR
C
END
Appendix B. Original Examples in Additional Languages

B-15

C\
C
EVAL
\INLR = '1'
C
RETURN
C\
C\ End of MAINLINE
C\
C\ Subroutine to handle errors received on the CALL
C\
C
ERROR
BEGSR
C\
C\ Process errors returned from the API
C\
C
MOVEL
QUSEI
MSG_ID
C
CALL
'QCMDEXC'
C
PARM
CMD_STR2
C
PARM
LENSTR2
C
ENDSR

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
#include
#include
#include
#include

/\ Error Code Parameter Include for the APIs \/
/\ Retrieve Job Description API Include
\/
/\ Entry Point Table Include
\/

B-16

System API Programming V4R1

} error_code_t;
main(int argc, char \argv[])
{
error_code_t error_code;
char
qual_job_desc[2ð];
char
\qual_job_ptr = qual_job_desc;
char
rec_var[39ð];
char
hold_value[1ð];
char
message_id[7];
char
command_string[25];
char
message_string[29];
FILE
\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

39ð,
"JOBDð1ðð",
qual_job_desc,
&error_code);

/\
/\
/\
/\

Receiver Length
Format Name
Qualified Job Description
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

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

ð1

LISTING RECORD CONTAINS 132 CHARACTERS
LABEL RECORDS ARE STANDARD
DATA RECORD IS LIST-LINE.
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

\
\ 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

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\
a job description and then prints the value.
F\
It expects errors to be returned via the
F\
error code parameter.
F\
F\ Header Files Included: QUSEC - Error Code Parameter
F\
QWDRJOBD - Retrieve Job Description API
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\
FQPRINT
O
F 132
PRINTER OFLIND(\INOF)
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\ Miscellaneous data structure
D\
DRCVLEN
S
9B ð INZ(%SIZE(QWDDð1ðð))
DFORMAT
S
8
INZ('JOBDð1ðð')
C\
C\ Beginning of mainline
C\
C\ Two parameters are being passed into this program
C\
C
\ENTRY
PLIST
C
PARM
JOBD
1ð
C
PARM
JOBD_LIB
1ð
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

C\
C
CALL
QWDRJOBD
C
PARM
QWDDð1ðð
C
PARM
RCVLEN
C
PARM
FORMAT
C
PARM
LFNAM
C
PARM
QUSEC
C\
C\ If no bytes available, API was successful; print HOLD value
C\
C
IF
QUSBAVL = ð
C
EXCEPT
GOOD
C
ELSE
C\
C\ If some bytes available, API failed; print Error message ID
C\
C
IF
QUSBAVL > ð
C
EXCEPT
BAD
C
END
C
END
C\
C\ End of program
C\
C
EVAL
\INLR = '1'
C
RETURN
C\
C\ End of MAINLINE
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
O\
OQPRINT
E
GOOD
1 6
O
'HOLD value - '
O
QWDHJQ
OQPRINT
E
BAD
1 6
O
'Failed. Error ID - '
O
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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
#include
#include
#include
#include
#include

/\ 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
Lib_Data[61ð]; .19/ .2ð/
} JOBDð1ðð;
main(int argc, char \argv[])
{
error_code_t error_code;
char
library[1ð];
char
qual_job_desc[2ð];
char
\qual_job_ptr = qual_job_desc;
char
rec_var[1ððð];
char
\rec_ptr = rec_var;
char
hold_value[1ð];
char
message_id[7];
char
command_string[49];
int
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

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,
/\ Receiver Variable
\/
rec_len,
/\ Receiver Length
\/
"JOBDð1ðð",
/\ Format Name
\/
qual_job_desc,
/\ Qualified Job Description
\/
&error_code);
/\ 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= 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

\ 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

ð1

QWD-JOBDð1ðð REDEFINES RECEIVER-VARIABLE.
ð5 BYTES-RETURNED
PIC
ð5 BYTES-AVAILABLE
PIC
ð5 JOB-DESCRIPTION-NAME
PIC
ð5 JOB-DESCRIPTION-LIB-NAME
PIC
ð5 USER-NAME
PIC
ð5 JOB-DATE
PIC
ð5 JOB-SWITCHES
PIC
ð5 JOB-QUEUE-NAME
PIC
ð5 JOB-QUEUE-LIB-NAME
PIC
ð5 JOB-QUEUE-PRIORITY
PIC
ð5 HOLD-JOB-QUEUE
PIC
ð5 OUTPUT-QUEUE-NAME
PIC
ð5 OUTPUT-QUEUE-LIB-NAME
PIC
ð5 OUTPUT-QUEUE-PRIORITY
PIC
ð5 PRINTER-DEVICE-NAME
PIC
ð5 PRINT-TEXT
PIC
ð5 SYNTAX-CHECK-SEVERITY
PIC
ð5 END-SEVERITY
PIC
ð5 MESSAGE-LOG-SEVERITY
PIC
ð5 MESSAGE-LOG-LEVEL
PIC
ð5 MESSAGE-LOG-TEXT
PIC
ð5 LOG-CL-PROGRAMS
PIC
ð5 INQUIRY-MESSAGE-REPLY
PIC
ð5 DEVICE-RECOVERY-ACTION
PIC
ð5 TIME-SLICE-END-POOL
PIC
ð5 ACCOUNTING-CODE
PIC
ð5 ROUTING-DATA
PIC
ð5 TEXT-DESCRIPTION
PIC
ð5 RESERVED
PIC
ð5 OFFSET-INITIAL-LIB-LIST
PIC
ð5 NUMBER-LIBS-IN-LIB-LIST
PIC
ð5 OFFSET-REQUEST-DATA
PIC
ð5 LENGTH-REQUEST-DATA
PIC
ð5 JOB-MESSAGE-QUEUE-MAX-SIZE
PIC
ð5 JOB-MESSAGE-QUEUE-FULL-ACTION
PIC
ð5 RESERVED2
PIC

S9(ðððð9) BINARY.
S9(ðððð9) BINARY.
X(ððð1ð).
X(ððð1ð).
X(ððð1ð).
X(ðððð8).
X(ðððð8).
X(ððð1ð).
X(ððð1ð).
X(ðððð2).
X(ððð1ð).
X(ððð1ð).
X(ððð1ð).
X(ðððð2).
X(ððð1ð).
X(ððð3ð).
S9(ðððð9) BINARY.
S9(ðððð9) BINARY.
S9(ðððð9) BINARY.
X(ðððð1).
X(ððð1ð).
X(ððð1ð).
X(ððð1ð).
X(ððð13).
X(ððð1ð).
X(ððð15).
X(ððð8ð).
X(ððð5ð).
X(ðððð1).
S9(ðððð9) BINARY. .19/
S9(ðððð9) BINARY. .2ð/
S9(ðððð9) BINARY.
S9(ðððð9) BINARY.
S9(ðððð9) BINARY.
X(ððð1ð).
X(ðððð1).

\
\
\
Varying length
\
ð5 INITIAL-LIB-LIST
PIC X(ððð11).
\
\
\
Varying length
\
ð5 REQUEST-DATA
PIC X(ðððð1).
\
\
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

ð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

\
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\
a job description. It expects errors to be
D\
returned via the error code parameter.
D\
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

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\
retrieves information from a job description
D\
object and places it into a single variable in the
D\
calling program.
D\
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ððð
3D1ð 94ð424 ROCH:
New Include
D\
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ðð
DS
1ððð
D\
Qwd JOBDð1ðð
D QWDBRTN
1
4B ð
D\
Bytes Returned
D QWDBAVL
5
8B ð
D\
Bytes Available

B-30

System API Programming V4R1

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\
D QWDNLILL
D\

1ð6

1ð7

1ð8

1ð9

118

119

148

149

152B ð

153

156B ð

157

16ðB ð

161

162

171

172

181

182

191

192

2ð4

2ð5

214

215

229

23ð

3ð9

31ð

359

36ð

361

364B ð .19/

365

368B ð .2ð/

Job Description Name
Job Description Lib Name
User Name
Job Date
Job Switches
Job Queue Name
Job Queue Lib Name
Job Queue Priority
Hold Job Queue
Output Queue Name
Output Queue Lib Name
Output Queue Priority
Printer Device Name
Print Text
Syntax Check Severity
End Severity
Message Log Severity
Message Log Level
Message Log Text
Log CL Programs
Inquiry Message Reply
Device Recovery Action
Time Slice End Pool
Accounting Code
Routing Data
Text Description
Reserved
Offset Initial Lib List
Number Libs In Lib list
Appendix B. Original Examples in Additional Languages

B-31

D QWDORD
369
372B ð
D\
Offset Request Data
D QWDLRD
373
376B ð
D\
Length Request Data
D QWDJMQMS
377
38ðB ð
D\
Job Message Queue Max Size
D QWDJMQFA
381
39ð
D\
Job Msg Queue Full Action
D\QWDRSV2
391
391
D\
D\
Varying length
D\QWDILL
392
4ð2
DIM(ðððð1)
D\
D\
Varying length
D\QWDRDðð
4ð3
4ð3
D\
D\
Varying length
D\
D\ Command string data structure
D\
DCMD_STRING
DS
D
22
INZ('SNDMSG MSG(''LIBRARY - ')
D LIBRARY
1ð
D
15
INZ(''') TOUSR(QPGMR)')
D\
D\ Miscellaneous data structure
D\
DRCVLEN
S
9B ð INZ(%SIZE(QWDDð1ðð))
DFORMAT
S
8
INZ('JOBDð1ðð')
DLENSTR
S
15 5 INZ(%SIZE(CMD_STRING))
C\
C\ Beginning of mainline
C\
C\ Two parameters are being passed into this program
C\
C
\ENTRY
PLIST
C
PARM
JOBD
1ð
C
PARM
JOBD_LIB
1ð
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
QWDRJOBD
C
PARM
QWDDð1ðð
C
PARM
RCVLEN
C
PARM
FORMAT
C
PARM
LFNAM
C
PARM
QUSEC
C\
C\ Test for an error on the API call
C\

B-32

System API Programming V4R1

C
C\
C\
C\
C
C
C\
C\
C\
C\
C
C
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C\
C
C
C\
C\
C\
C\
C\
C
C\
C\
C\
C\
C\
C\
C\
C\
C\
C

QUSBAVL > ð

If there was an error, exit to ERROR subroutine
EXSR
ELSE

ERROR

Else, add 1 to the Initial library list offset because RPG
is a Base 1 language
QWDOILL

ADD
DO
EVAL

1
X
5 ð
QWDNLILL
LIBRARY = %SUBST(QWDDð1ðð:X:1ð)

Let's tell everyone what the library value is
CALL
PARM
PARM
ADD
IF
LEAVE
ENDIF
ENDDO
ENDIF

'QCMDEXC'

EVAL
RETURN

\INLR = '1'

CMD_STRING
LENSTR
11
X
(X + 1ð) > RCVLEN

End of MAINLINE
Subroutine to handle errors returned in the error code parameter
ERROR

BEGSR

Process errors returned from the API. As this sample program
used /COPY to include the error code structure, only the first
16 bytes of the error code structure are available. If the
application program needed 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.
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
\/
/\
\/
/\
Language:
ILE C
\/
/\
\/
/\
Description: This example shows the steps necessary to
\/
/\
process keyed output from an API
\/

Appendix B. Original Examples in Additional Languages

B-33

/\
\/
/\
APIs Used:
QUSLSPL - List Spooled Files
\/
/\
QUSCRTUS - Create User Space
\/
/\
QUSPTRUS - Retrieve Pointer to User Space
\/
/\
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
#include
#include
#include
#include
#include
#include
#include
#include

/\
/\
/\
/\
/\
/\

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
spc_name[2ð] = "SPCNAME
QTEMP
";
int
spc_size = 2ððð;
char
spc_init = ðxðð;
char
\spcptr, \lstptr, \lstptr2;
int
pages;
struct
keys { int key1;
.7/
int key2;
int key3;} keys = {2ð1, 211, 216};
.8/
int
number_of_keys = 3;
char
ext_attr[1ð] = "QUSLSPL
";
char
spc_aut[1ð] = "\ALL
";
char
spc_text[5ð] = "
";
char
spc_replac[1ð] = "\YES
";
char
spc_domain[1ð] = "\USER
";
char
format[8] = "SPLFð2ðð";
.4/
char
usr_prf[1ð] = "\CURRENT ";
char
outq[2ð] = "\ALL
";
char
formtyp[1ð] = "\ALL
";
char
usrdta[1ð] = "\ALL
";
char
jobnam[26] = "
";
char
prtfil[1ð];
char
opndat[7];
typedef struct {
Qus_LSPL_Key_Info_t Key_Info;
char
Data_Field[1ðð];
} var_record_t;
Qus_EC_t error_code;
int
i, j;
char
prtlin[1ðð];
FILE
\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

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,
spc_size,
&spc_init,
spc_aut,
spc_text,
spc_replac,
error_code,
spc_domain);

/\
/\
/\
/\
/\
/\
/\
/\
/\

User space name and library .2/
Extended attribute
Initial space size
Initialize value for space
Public authorization
Text description
Replace option
Error code structure
Domain of space

\/
\/
\/
\/
\/
\/
\/
\/
\/

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Call QUSLSPL to get all spooled files for \CURRENT user
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
QUSLSPL( spc_name,
format,
usr_prf,
outq,
formtyp,
usrdta,
error_code,
jobnam,
keys,
number_of_keys);

/\
/\
/\
/\
/\
/\
/\
/\
/\
/\

User space name and library .3/
API format
.4/
User profile
Output Queue
Form type
User data
Error code structure
Job name
Keys to return
.5/
Number of keys
.6/

\/
\/
\/
\/
\/
\/
\/
\/
\/
\/

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Get a resolved pointer to the User Space
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
QUSPTRUS(spc_name,
&spcptr,
error_code);

/\ User space name and library .9/
/\ Space pointer
/\ 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

{
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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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
prtfil, pages, opndat);
fwrite(prtlin, 1, 1ðð, record);

%.7s", .26/

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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");
exit();
}
}

.15/
.28/

Appendix B. Original Examples in Additional Languages

B-37

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
PIC X(1ð).
ð5 FILLER
PIC X(ð5).
ð5 PAGES
PIC S9(ð9).
ð5 FILLER
PIC X(ð5).

B-38

System API Programming V4R1

ð1
ð1

ð5 OPNDAT
LSTERR.
ð5 TEXT1
HDRERR.
ð5 TEXT2

PIC

X(ð7).

PIC

X(22) VALUE "List data not valid".

PIC

X(22) VALUE "Unknown Generic Header".

\
ð1

ð1

ð1
ð1

MISC.
ð5 SPC-NAME
PIC X(2ð) VALUE "SPCNAME
QTEMP
ð5 SPC-SIZE
PIC S9(ð9) VALUE 2ððð BINARY. .2/
ð5 SPC-INIT
PIC X(ð1) VALUE X"ðð".
ð5 SPCPTR
POINTER.
ð5 SPC-TYPE
PIC X(1ð) VALUE "\USRSPC".
ð5 EXT-ATTR
PIC X(1ð) VALUE "QUSLSPL ". .3/
ð5 SPC-AUT
PIC X(1ð) VALUE "\ALL".
ð5 SPC-TEXT
PIC X(5ð).
ð5 SPC-REPLAC
PIC X(1ð) VALUE "\YES".
ð5 SPC-DOMAIN
PIC X(1ð) VALUE "\USER".
ð5 LST-FORMAT-NAME PIC X(ð8) VALUE "SPLFð2ðð". .4/
ð5 USR-PRF
PIC X(1ð) VALUE "\CURRENT ".
ð5 OUTQ
PIC X(2ð) VALUE "\ALL".
ð5 FORMTYP
PIC X(1ð) VALUE "\ALL".
ð5 USRDTA
PIC X(1ð) VALUE "\ALL".
ð5 JOBNAM
PIC X(26).
KEYS.
.7/
ð5 KEY1
PIC S9(ð9) BINARY VALUE 2ð1. .8/
ð5 KEY2
PIC S9(ð9) BINARY VALUE 216.
ð5 KEY3
PIC S9(ð9) BINARY VALUE 211.
NUMBER-OF-KEYS
PIC S9(ð9) BINARY VALUE 3.
MISC2.
ð5 PAGESA
PIC X(ð4).
ð5 PAGESN
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
PIC S9(ðððð9) BINARY.
ð5 KEY-FIELD-FOR-FIELD-RETD
PIC S9(ðððð9) BINARY.
ð5 TYPE-OF-DATA
PIC X(ðððð1).
ð5 RESERV3
PIC X(ðððð3).
ð5 DATA-LENGTH
PIC S9(ðððð9) BINARY.
ð5 DATA-FIELD
PIC X(ðð1ðð).
\
\
Varying length
Appendix B. Original Examples in Additional Languages

B-39

\
\
\

ð5

ð1

RESERVED

PIC

X(ðððð1).

Varying length
QUS-SPLFð2ðð.
ð5 NUM-FIELDS-RETD
PIC S9(ðððð9) BINARY.
ð5 KEY-INFO.
ð9 LEN-FIELD-INFO-RETD
PIC S9(ðððð9) BINARY.
ð9 KEY-FIELD-FOR-FIELD-RETD
PIC S9(ðððð9) BINARY.
ð9 TYPE-OF-DATA
PIC X(ðððð1).
ð9 RESERV3
PIC X(ðððð3).
ð9 DATA-LENGTH
PIC S9(ðððð9) BINARY.
ð9 DATA-FIELD
PIC X(ðððð1).
ð9 RESERVED
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

\ 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.
.15/
STOP RUN.
.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

\ 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:
ILE RPG
F\
F\ Description: This example shows the steps necessary to
F\
process keyed output from an API.
F\
F\ APIs Used:
QUSLSPL - List Spooled Files
F\
QUSCRTUS - Create User Space
F\
QUSPTRUS - Retrieve Pointer to User Space
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\
FQPRINT
O
F 132
PRINTER OFLIND(\INOF)
D\
D\ Error Code parameter include
D\
D/COPY QSYSINC/QRPGLESRC,QUSEC
.11/
D\
DSPC_NAME
S
2ð
INZ('SPCNAME
QTEMP
')
DSPC_SIZE
S
9B ð INZ(2ððð)
.2/
DSPC_INIT
S
1
INZ(X'ðð')
DLSTPTR
S
\
DLSTPTR2
S
\
DSPCPTR
S
\
DARR
S
1
BASED(LSTPTR) DIM(32767)
D
DS
DPAGES#
1
4B ð
DPAGESA
1
4
DKEYS
DS
.7/
D
9B ð INZ(2ð1)
.8/
D
9B ð INZ(216)
D
9B ð INZ(211)

B-42

System API Programming V4R1

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ðð
DS
BASED(SPCPTR)
D\
Qus Generic Header ð1ðð
D QUSUA
1
64
D\
User Area
D QUSSGH
65
68B ð
D\
Size Generic Header
D QUSSRL
69
72
D\
Structure Release Level
D QUSFN
73
8ð
D\
Format Name
D QUSAU
81
9ð
D\
API Used
D QUSDTC
91
1ð3
D\
Date Time Created
D QUSIS
1ð4
1ð4
D\
Information Status
D QUSSUS
1ð5
1ð8B ð
D\
Size User Space
D QUSOIP
1ð9
112B ð
D\
Offset Input Parameter
D QUSSIP
113
116B ð
D\
Size Input Parameter
D QUSOHS
117
12ðB ð
D\
Offset Header Section
D QUSSHS
121
124B ð
D\
Size Header Section
D QUSOLD
125
128B ð
D\
Offset List Data
D QUSSLD
129
132B ð
D\
Size List Data
D QUSNBRLE
133
136B ð
D\
Number List Entries
D QUSSEE
137
14ðB ð
D\
Size Each Entry
D QUSSIDLE
141
144B ð
D\
CCSID List Ent
D QUSCID
145
146
D\
Country ID
D QUSLID
147
149
D\
Language ID
D QUSSLI
15ð
15ð
D\
Subset List Indicator
D QUSERVEDðð
151
192
D\
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

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)
D\
Qus LSPL Key Info
D QUSLFIRð2
1
4B ð
D\
Len Field Info Retd
D QUSKFFFRðð
5
8B ð
D\
Key Field for Field Retd
D QUSTODð2
9
9
D\
Type of Data
D QUSR3ðð
1ð
12
D\
Reserv3
D QUSDLð2
13
16B ð
D\
Data Length
D\QUSDATAð8
17
17
D\
D\
Varying length
D\QUSERVED34
18
18
D\
D\
Varying length
DQUSFð2ðð
DS
BASED(LSTPTR)
D\
Qus SPLFð2ðð
D QUSNBRFRðð
1
4B ð
D\
Num Fields Retd
D\QUSKIðð
18
D\ QUSLFIRð3
5
8B ð
D\ QUSKFFFRð1
9
12B ð
D\ QUSTODð3
13
13
D\ QUSR3ð1
14
16
D\ QUSDLð3
17
2ðB ð
D\ QUSDATAð9
21
21
D\ QUSERVED35
22
22
D\
D\
Varying length
C\
C\ Start of mainline
C\
C\
C\ Set Error Code structure to use exceptions
C\
C
Z-ADD
ð
QUSBPRV
.1/
C\
C\ Create a User Space for the List generated by QUSLSPL
C\
C
CALL
'QUSCRTUS'
.2/
C
PARM
SPC_NAME
C
PARM
'QUSLSPL
' EXT_ATTR
1ð
C
PARM
SPC_SIZE
C
PARM
SPC_INIT
C
PARM
'\ALL'
SPC_AUT
1ð

B-44

System API Programming V4R1

C
C
C
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C
C
C
C\
C\
C\
C
C

PARM
PARM
PARM
PARM

\BLANKS
'\YES'
'\USER'

SPC_TEXT
SPC_REPLAC
QUSEC
SPC_DOMAIN

5ð
1ð
1ð

Call QUSLSPL to get all spooled files for \CURRENT user
CALL
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM

.3/

'QUSLSPL'
'SPLFð2ðð'
'\CURRENT'
'\ALL'
'\ALL'
'\ALL'

SPC_NAME
FORMAT
USR_PRF
OUTQ
FORMTYP
USRDTA
QUSEC
JOBNAM
KEYS
KEY#

8 .4/
1ð
2ð
1ð
1ð
26
.5/
.6/

Get a resolved pointer to the User Space for performance
CALL
PARM
PARM
PARM

.9/

'QUSPTRUS'
SPC_NAME
SPCPTR
QUSEC

If valid information was returned
QUSSRL
QUSIS
QUSIS

IFEQ
IFEQ
OREQ

.12/
.14/

'ð1ðð'
'C'
'P'

and list entries were found
QUSNBRLE

IFGT

.16/

set LSTPTR to the first byte of the User Space
EVAL

LSTPTR = SPCPTR

increment LSTPTR to the first List entry
EVAL

LSTPTR = %ADDR(ARR(QUSOLD + 1)) .18/

and process all of the entries
DO

.2ð/

QUSNBRLE

set LSTPTR2 to the first variable length record for this entry
Z-ADD
EVAL
DO

5
X
LSTPTR2 = %ADDR(ARR(X)) .22/
QUSNBRFRðð
.23/

9 ð

process the data based on key type
QUSKFFFRðð
QUSKFFFRðð

CASEQ
CASEQ

2ð1
211

FILNAM
PAGES

.24/

Appendix B. Original Examples in Additional Languages

B-45

C
QUSKFFFRðð
CASEQ
216
AGE
C
CAS
ERROR
C
END
C\
C\ increment LSTPTR2 to next variable length record
C\
C
ADD
QUSLFIRð2
X
C
EVAL
LSTPTR2 = %ADDR(ARR(X))
C
END
C
EXCEPT
PRTLIN
.26/
C\
C\ after each entry, increment LSTPTR to the next entry
C\
C
EVAL
LSTPTR = %ADDR(ARR(QUSSEE + 1)) .27/
C
END
C
END
C
ELSE
C
EXCEPT
LSTERR
.15/
C
END
C
ELSE
C
EXCEPT
HDRERR
.13/
C
END
C\
C\ Exit the program
C\
C
EVAL
\INLR = '1'
.28/
C
RETURN
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
FILNAM
BEGSR
C\
C\ extract spooled file name for report
C\
C
MOVE
\BLANKS
PRTFIL
1ð
C
EVAL
PRTFIL = %SUBST(QUSSPLKI:17:QUSDLð2) .25/
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
PAGES
BEGSR
C\
C\ extract number of pages for report
C\
C
EVAL
PAGESA = %SUBST(QUSSPLKI:17:QUSDLð2) .25/
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
AGE
BEGSR
C\
C\ extract age of spooled file for report
C\
C
MOVE
\BLANKS
OPNDAT
7
C
EVAL
OPNDAT = %SUBST(QUSSPLKI:17:QUSDLð2) .25/
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
ERROR
BEGSR
C
QUSKFFFRðð
DSPLY
C
EVAL
\INLR = '1'
C
RETURN
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
OQPRINT
E
PRTLIN
1

B-46

System API Programming V4R1

O
O
O
OQPRINT
O
OQPRINT
O

PRTFIL
PAGES#
OPNDAT
LSTERR

1ð
25
4ð
1

HDRERR

22 'List data not valid'
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

\
\
\
\
\
\
\
\
\

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".
ð5 EXIT-PGM-NBR
PIC S9(ð9) VALUE 1 BINARY.
ð5 EXIT-PGM-DATA
PIC X(25)
VALUE "EXAMPLE EXIT PROGRAM DATA".
ð5 FORMAT-NAME
PIC X(ð8) VALUE "EXMPð1ðð".
\
\ 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

\
\
\
\
\
\
\

the API using a variable length record.
start on a 4-byte boundary.

Each record must

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

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

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

ð5

TEXT1

PIC X(36)
VALUE "Attempt to add exit program failed: ".
EXCEPTION-ID PIC X(ð7).

ð5
\
\ 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".
ð5 EXIT-PGM-NBR
PIC S9(ð9) VALUE 1 BINARY.
ð5 EXIT-PGM-DATA
PIC X(25)
VALUE "EXAMPLE EXIT PROGRAM DATA".
ð5 FORMAT-NAME
PIC X(ð8) VALUE "EXMPð1ðð".
\
\ 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

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

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
F\
Add an Exit Program
F\
F\ Language:
OPM RPG
F\
F\ Description: This program registers an exit point with the
F\
registration facility. After the successful
F\
completion of the registration of the exit point,
F\
an exit program is added to the exit point.
F\
F\ APIs Used:
QUSRGPT - Register Exit Point
F\
QUSADDEP - Add Exit Program
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\

B-54

System API Programming V4R1

FQPRINT O
F
132
PRINTER
UC
E\ COMPILE TIME ARRAY
E
REC
1ððð 1
I\
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
B
1
4ðNBRREC
I
51ðð4 REC
I I
1
B1ðð51ðð8ðVO
I\
IOVRLAY
DS
I
B
1
4ðBINARY
I
1
4 BINC
I\
I
DS
I I
'EXAMPLE_EXIT_POINT '
1 2ð EPNTNM
I I
'EXAMPLEPGMEXAMPLELIB'
21 4ð EPGM
I I
'EXAMPLE EXIT PROGRAM41 65 EPGMDT
I
' DATA'
I I
'EXAMPLE POINT EXAMPL66 115 EPTXT
I
'E'
I I
25
B 68 71ðEPGMSZ
C\
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

C\
C\
C\
C
C\
C\
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C\
C\
C\
C\
C\
C\
C
C
C\
C\
C\
C\
C\
C
C
C

B-56

the call. This program lets the API take the default for the
controls that are not specified.
Z-ADD2

NBRREC

Set the values for the two controls that are specified:
Maximum number of exit programs = 1ð
Exit point description = 'EXIT POINT EXAMPLE'

Z-ADD3
Z-ADD4
Z-ADD1ð
ADD VO
MOVEABINC
EXSR CALCVO
Z-ADD8
Z-ADD5ð
ADD VO
MOVEAEPTXT
EXSR CALCVO

QUSBCC
QUSBCD
BINARY
OF
REC,OF
QUSBCC
QUSBCD
OF
REC,OF

5ð

Call the API to register the exit point.
CALL 'QUSRGPT'
PARM
EPNTNM
PARM 'EXMPð1ðð'FORMAT
PARM
VARREC
PARM
QUSBN

IFGT ð
OPEN QPRINT
EXCPTERREPT
EXSR DONE
ENDIF

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.
Z-ADD2
Z-ADD1

NBRREC
VO

Set the values for the two attributes that are being specified:
Replace exit program
= 1
Exit program data CCSID = 37

System API Programming V4R1

Z-ADD4
Z-ADD1
ADD VO

QUSBCC
QUSBCD
OF

5ð

C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C\
C\
C\
C\
C\
C\
C
C
C
C
C
C
C\
C\
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C
C
C
C

MOVE '1'
EXSR CALCVO
Z-ADD3
Z-ADD4
Z-ADD37
ADD VO
MOVEABINC
EXSR CALCVO

REC,OF
QUSBCC
QUSBCD
BINARY
OF
REC,OF

5ð

Call the API to add the exit program.
CALL 'QUSADDEP'
PARM
EPNTNM
PARM 'EXMPð1ðð'FORMAT
PARM 1
BINARY
PARM
EPGM
PARM
EPGMDT
PARM
EPGMSZ
PARM
VARREC
PARM
QUSBN
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.
QUSBNC

IFGT ð
OPEN QPRINT
EXCPTERRPGM
EXSR DONE
ENDIF
EXSR DONE

End of MAINLINE

Return to programs caller
DONE
BEGSR
SETON
RETRN
ENDSR

Calculate 4-byte aligned offset for next variable length record
CALCVO
QUSBCD

BINARY
QUSBCD
4

BEGSR
ADD 12
DIV 4
MVR
IFEQ ð
ADD 12
ELSE
SUB BINARY
ADD QUSBCD
ADD 12
END
MOVEAQUSBC
ADD QUSBCB
ENDSR

BINARY
BINARY
BINARY
QUSBCB
QUSBCB
QUSBCB
QUSBCB
REC,VO
VO

Appendix B. Original Examples in Additional Languages

B-57

O\
OQPRINT
O
O
O
OQPRINT
O
O
O

1ð6

ERREPT
'Attempt to register exit'
' point failed: '

1ð6

QUSBND
ERRPGM
'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
F\
Add an Exit Program
F\
F\ Language:
ILE RPG
F\
F\ Description: This program registers an exit point with the
F\
registration facility. After the successful
F\
completion of the registration of the exit point,
F\
an exit program is added to the exit point.
F\
F\ APIs Used:
QusRegisterExitPoint - Register Exit Point
F\
QusAddExitProgram
- Add Exit Program
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\
FQPRINT
O
F 132
PRINTER OFLIND(\INOF) USROPN
D\
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

D\
D\ Miscellaneous data
D\
DVARREC
DS
D NBR_RECS
9B ð
D RECS
1ððð
DV_OFFSET
S
9 ð INZ(1)
D\
DOVERLAYS
DS
D BINARY
9B ð
D BINARY_C
4
OVERLAY(BINARY)
D\
DEPNTNAME
S
2ð
INZ('EXAMPLE_EXIT_POINT')
DEPGM
S
2ð
INZ('EXAMPLEPGMEXAMPLELIB')
DEPGMDTA
S
25
INZ('EXAMPLE EXIT PROGRAM DATA')
DEPGMDTA_SZ
S
9B ð INZ(%SIZE(EPGMDTA))
C\
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
EVAL
QUSCK = 3
C
EVAL
QUSLD = 4
C
EVAL
BINARY = 1ð
C
EVAL
%SUBST(RECS:V_OFFSET+12) = BINARY_C
C
EXSR
CALC_VOFF
C
EVAL
QUSCK = 8
C
EVAL
QUSLD = 5ð
C
EVAL
%SUBST(RECS:V_OFFSET+12:5ð) = 'EXIT +
C
POINT EXAMPLE'
C
EXSR
CALC_VOFF
C\
C\ Call the API to register the exit point.
Appendix B. Original Examples in Additional Languages

B-59

C\
C
C
C
C
C
C\
C\
C\
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C\
C\
C\
C\
C\
C\
C
C
C\
C\
C\
C\
C\
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C\
C\
C\
C\

B-60

CALLB
PARM
PARM
PARM
PARM

QUSREPð5
'EXMPð1ðð'

EPNTNAME
FORMAT
VARREC
QUSEC

QUSBAVL > ð
QPRINT
ERRAEPNT
DONE

NBR_RECS = 2
V_OFFSET = 1

Set the values for the two attributes that are being specified:
Replace exit program
= 1
Exit program data CCSID = 37
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

Call the API to add the exit program.
CALLB
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM

QUSAEPGM
'EXMPð1ðð'
1

EPNTNAME
FORMAT
BINARY
EPGM
EPGMDTA
EPGMDTA_SZ
VARREC
QUSEC

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

System API Programming V4R1

C\ exception does occur.
C\
C
IF
QUSBAVL > ð
C
OPEN
QPRINT
C
EXCEPT
ERRAEPGM
C
EXSR
DONE
C
ENDIF
C
EXSR
DONE
C\
C\ End of MAINLINE
C\
C\
C\ Return to programs caller
C
DONE
BEGSR
C
EVAL
\INLR = '1'
C
RETURN
C
ENDSR
C\
C\ Calculate 4-byte aligned offset for next variable length record
C\
C
CALC_VOFF
BEGSR
C
EVAL
BINARY = QUSLD + 12
C
DIV
4
BINARY
C
MVR
BINARY
C
IF
BINARY = ð
C
EVAL
QUSLVRðð = (QUSLD + 12)
C
ELSE
C
EVAL
QUSLVRðð = (QUSLD + 12 + (4 - BINARY))
C
END
C
EVAL
%SUBST(RECS:V_OFFSET:12) = QUSVR4
C
EVAL
V_OFFSET = V_OFFSET + QUSLVRðð
C
ENDSR
O\
OQPRINT
E
ERRAEPNT
1 6
O
'Attempt to register exit O
point failed: '
O
QUSEI
OQPRINT
E
ERRAEPGM
1 6
O
'Attempt to add exit O
program failed: '
O
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

\
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

ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5

FORMAT-NAME
PIC X(ð8) VALUE "EXTIð1ðð".
FORMAT-NAME-1
PIC X(ð8) VALUE "EXTIð2ðð".
FORMAT-NAME-2
PIC X(ð8) VALUE "EXMPð1ðð".
NBR-OF-SELECT-CRITERIA PIC S9(ð9) VALUE ð BINARY.
CONTINUATION-HDL PIC X(16).
BASE-POINTER
POINTER.
INFO-POINTER
POINTER.
SPACE-NAME
PIC X(2ð) VALUE "RCVVAR
QTEMP
SPACE-ATTR
PIC X(1ð).
SPACE-SIZE
PIC S9(ð9) VALUE 35ðð BINARY.
SPACE-VALUE
PIC X(ð1) VALUE X"ðð".
SPACE-AUTH
PIC X(1ð) VALUE "\USE".
SPACE-TEXT
PIC X(5ð).
SPACE-REPLACE
PIC X(1ð) VALUE "\NO".
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

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

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

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

\
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

ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5
ð5

NBR-OF-SELECT-CRITERIA PIC S9(ð9) VALUE ð BINARY.
CONTINUATION-HDL PIC X(16).
BASE-POINTER
POINTER.
INFO-POINTER
POINTER.
SPACE-NAME
PIC X(2ð) VALUE "RCVVAR
QTEMP
SPACE-ATTR
PIC X(1ð).
SPACE-SIZE
PIC S9(ð9) VALUE 35ðð BINARY.
SPACE-VALUE
PIC X(ð1) VALUE X"ðð".
SPACE-AUTH
PIC X(1ð) VALUE "\USE".
SPACE-TEXT
PIC X(5ð).
SPACE-REPLACE
PIC X(1ð) VALUE "\NO".
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

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

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

TO EXCEPTION-ID OF BAD-EXIT-PGM,
WRITE LIST-LINE FROM BAD-EXIT-PGM,
STOP RUN.
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\

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:
OPM RPG
F\
F\ Description: This program retrieves exit point and exit
F\
program information. After retrieving the
F\
exit point information, the program calls each
F\
exit program.
F\
F\ APIs Used:
QUSRTVEI - Retrieve Exit Information
F\

Appendix B. Original Examples in Additional Languages

B-71

F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\
FQPRINT O
F
132
PRINTER
UC
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\ Formats for the Retrieve Exit Information API.
I\
I/COPY QSYSINC/QRPGSRC,QUSREG
I\
I\ Miscellaneous data
I\
I
DS
I I
'EXAMPLE_EXIT_POINT '
1 2ð EPNTNM
I I
-1
B 21 24ðEPGMNB
I I
35ðð
B 25 28ðRCVSZ
I
B 29 32ðX
I
B 33 36ðY
I
37 57 CALLPG
IRCV
DS
35ðð
C\
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
Z-ADD16
QUSBNB
C\
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
CONTHD 16
C\
C\ Call the API to retrieve the exit point information
C\
C
CALL 'QUSRTVEI'
C
PARM
CONTHD
C
PARM
RCV
C
PARM
RCVSZ
C
PARM 'EXTIð1ðð'FORMAT 8

B-72

System API Programming V4R1

C
C
C
C
C
C\
C\
C\
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C\
C\
C\
C
C
C
C
C
C
C
C\
C\
C\
C\
C\
C
C\
C\
C\
C

PARM
EPNTNM
PARM 'EXMPð1ðð'EPTFMT
PARM
EPGMNB
PARM ð
QUSCCB
PARM
QUSBN

IFGT ð
OPEN QPRINT
EXCPTERREPT
EXSR DONE
ENDIF

If the call to retrieve exit point information is successful,
check to see if there are any exit programs to call.
36
QUSCGG
1
2ð1
QUSCFF

SUBSTRCV:1
IFGT ð
ADD QUSCGF
SUBSTRCV:X
IFGT ð

QUSCG
X
QUSCF

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 \BLANKS

CONTHD

Call the exit programs
EXSR CUSREI
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.
QUSCGD

DOWNE\BLANKS
MOVELQUSCGD
EXSR CUSREI
ENDDO
ENDIF
ENDIF
EXSR DONE

CONTHD

End of MAINLINE
Process exit programs in receiver variable
CUSREI

BEGSR

Call the API to retrieve the exit program information
CALL 'QUSRTVEI'
Appendix B. Original Examples in Additional Languages

B-73

C
C
C
C
C
C
C
C
C
C\
C\
C\
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C\
C\
C\
C
C
C

B-74

PARM
CONTHD
PARM
RCV
PARM
RCVSZ
PARM 'EXTIð2ðð'FORMAT
PARM
EPNTNM
PARM 'EXMPð1ðð'EPTFMT
PARM
EPGMNB
PARM ð
QUSCCB
PARM
QUSBN

8
8

IFGT ð
OPEN QPRINT
EXCPTERRPGM
EXSR DONE
ENDIF

SUBSTRCV:1
ADD QUSCJF
SUBSTRCV:Y
DO
QUSCJG

QUSCJ
Y
QUSCH

Get the exit program name and library

CALLPG
CALLPG

MOVE \BLANKS
MOVELQUSCHL
CAT '/':ð
CAT QUSCHK:ð

CALLPG
CALLPG
CALLPG
CALLPG

Call the exit program while ignoring failures on the call
CALL CALLPG
PARM

ð1
EXTPRM 1ð

Set Y to point to the next exit program entry

System API Programming V4R1

1
72

ADD QUSCHB
SUBSTRCV:Y
ENDDO

Y
QUSCH

C
C\
C\ Return to programs
C
DONE
C
C
C
O\
OQPRINT E 1ð6
O
O
O
OQPRINT E 1ð6
O
O
O

ENDSR
caller
BEGSR
SETON
RETRN
ENDSR

ERREPT
'Attempt to retrieve infor'
'mation failed: '
QUSBND
ERRPGM
'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:
ILE RPG
F\
F\ Description: This program retrieves exit point and exit
F\
program information. After retrieving the
F\
exit point information, the program calls each ,
F\
exit program.
F\
F\ APIs Used:
QusRetrieveExitInformation - Retrieve Exit
F\
Information
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\
FQPRINT
O
F 132
PRINTER OFLIND(\INOF) USROPN
D\
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

D\Licensed Materials-Property of IBM
D\
D\
D\Description: All of the structures that are used in the
D\
Registration facilities are kept here to avoid
D\
conflict due to repetition.
D\
D\Header Files Included: None.
D\
D\Macros List: None.
D\
D\Structure List: Qus_Prep_Exit_t
D\
Qus_Qmff_t
D\
Qus_Selcrtr_t
D\
Qus_Select_Entry_t
D\
Qus_Program_Data_t
D\
Qus_EXTIð1ðð_t
D\
Qus_EXTIð1ðð_Entry_t
D\
Qus_EXTIð2ðð_t
D\
Qus_EXTIð2ðð_Entry_t
D\
Qus_EXTIð3ðð_t
D\
Qus_EXTIð3ðð_Entry_t
D\
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ððð
3D1ð 94ð327 LUPA:
New Include
D\
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
DS
D\
Qus Prep Exit
D QUSPPN
1
1ð
D\
Prep Prog Name
D QUSPPLIB
11
2ð
D\
Prep Prog Library
D QUSPPF
21
28
D\
Prep Prog Format
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D\Format structure for the Qualified Message File Format for the
D\entire service program.
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
DQUSQMFF
DS
D\
Qus Qmff
D QUSMFIL
1
1ð
D\
Message File

B-76

System API Programming V4R1

D QUSMLIB
11
2ð
D\
Message Library
D QUSMI
21
27
D\
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
DS
D\
Qus Select Entry
D QUSSEðð
1
4B ð
D\
Size Entry
D QUSCO
5
8B ð
D\
Comp Operator
D QUSSPD
9
12B ð
D\
Start Pgm Data
D QUSLCD
13
16B ð
D\
Length Comp Data
D\QUSCD
17
17
D\
D\
Varying length
DQUSS
DS
D\
Qus Selcrtr
D QUSNBRSC
1
4B ð
D\
Number Sel Criteria
D\QUSARRAY
17
DIM(ðððð1)
D\ QUSSEð1
9B ð OVERLAY(QUSARRAY:ðððð1)
D\ QUSCOðð
9B ð OVERLAY(QUSARRAY:ðððð5)
D\ QUSSPDðð
9B ð OVERLAY(QUSARRAY:ðððð9)
D\ QUSLCDðð
9B ð OVERLAY(QUSARRAY:ððð13)
D\ QUSCDðð
1
OVERLAY(QUSARRAY:ððð17)
D\
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
D QUSDATAð1
1
1
D\
Varying length
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
DS
BASED(INFSPCPTR)
D\
Qus EXTIð1ðð Entry
D QUSEPNðð
1
2ð
D\
Exit Point Name
D QUSFNð8
21
28
Appendix B. Original Examples in Additional Languages

B-77

D\
D QUSMEP
D\
D QUSNBREP
D\
D QUSAD
D\
D QUSACC
D\
D QUSREP
D\
D QUSPNAP
D\
D QUSPLAP
D\
D QUSPFA
D\
D QUSPNRP
D\
D QUSPLRP
D\
D QUSPFR
D\
D QUSPNRI
D\
D QUSPLRI
D\
D QUSPFRðð
D\
D QUSDI
D\
D QUSDMFIL
D\
D QUSDMLIB
D\
D QUSDMI
D\
D QUSTD
D\
D\QUSERVEDð3
D\
D\
DQUSIð1ðð
D\
D QUSBRTN
D\
D QUSBAVLðð
D\
D QUSCH
D\
D QUSOEPE
D\
D QUSNBRPR
D\
D QUSLEPE
D\
D\QUSERVEDð4
D\

B-78

System API Programming V4R1

Format Name
29

32B ð

36B ð

4ð

5ð

6ð

1ð5

1ð6

115

116

123

124

125

134

135

144

145

151

152

2ð1

2ð2

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
Desc Msg File
Desc Msg Library
Desc Msg Id
Text Description

Varying length
BASED(BASSPCPTR)
Qus EXTIð1ðð

DS
1

4B ð

8B ð

Bytes Returned
Bytes Available
9

24
Continue Handle

28B ð

32B ð

36B ð

Offset Exit Point Entry
Number Points Returned
Length Exit Point Entry

D\
Varying length
D\QUSARRAYðð
2ð2
DIM(ðððð1)
D\ QUSEPNð1
2ð
OVERLAY(QUSARRAYðð:ðððð1)
D\ QUSFNð9
8
OVERLAY(QUSARRAYðð:ððð21)
D\ QUSMEPðð
9B ð OVERLAY(QUSARRAYðð:ððð29)
D\ QUSNBREPðð
9B ð OVERLAY(QUSARRAYðð:ððð33)
D\ QUSADðð
1
OVERLAY(QUSARRAYðð:ððð37)
D\ QUSACCðð
1
OVERLAY(QUSARRAYðð:ððð38)
D\ QUSREPðð
1
OVERLAY(QUSARRAYðð:ððð39)
D\ QUSPNAPðð
1ð
OVERLAY(QUSARRAYðð:ððð4ð)
D\ QUSPLAPðð
1ð
OVERLAY(QUSARRAYðð:ððð5ð)
D\ QUSPFAðð
8
OVERLAY(QUSARRAYðð:ððð6ð)
D\ QUSPNRPðð
1ð
OVERLAY(QUSARRAYðð:ððð68)
D\ QUSPLRPðð
1ð
OVERLAY(QUSARRAYðð:ððð78)
D\ QUSPFRð1
8
OVERLAY(QUSARRAYðð:ððð88)
D\ QUSPNRIðð
1ð
OVERLAY(QUSARRAYðð:ððð96)
D\ QUSPLRIðð
1ð
OVERLAY(QUSARRAYðð:ðð1ð6)
D\ QUSPFRð2
8
OVERLAY(QUSARRAYðð:ðð116)
D\ QUSDIðð
1
OVERLAY(QUSARRAYðð:ðð124)
D\ QUSDMFILðð
1ð
OVERLAY(QUSARRAYðð:ðð125)
D\ QUSDMLIBðð
1ð
OVERLAY(QUSARRAYðð:ðð135)
D\ QUSDMIðð
7
OVERLAY(QUSARRAYðð:ðð145)
D\ QUSTDðð
5ð
OVERLAY(QUSARRAYðð:ðð152)
D\ QUSERVEDð5
1
OVERLAY(QUSARRAYðð:ðð2ð2)
D\
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)
D\
Qus EXTIð2ðð Entry
D QUSONE
1
4B ð
D\
Offset Next Entry
D QUSEPNð2
5
24
D\
Exit Point Name
D QUSFN1ð
25
32
D\
Format Name
D QUSREPð1
33
33
D\
Registered Exit Pt
D QUSCE
34
34
D\
Complete Entry
D QUSERVEDð6
35
36
D\
Reserved
D QUSPGMN
37
4ðB ð
D\
Program Number
D QUSPGMNðð
41
5ð
D\
Program Name
D QUSPGML
51
6ð
D\
Program Library
D QUSDC
61
64B ð
D\
Data CCSID
D QUSOED
65
68B ð
D\
Offset Exit Data
Appendix B. Original Examples in Additional Languages

B-79

D QUSLED
69
72B ð
D\
Length Exit Data
D\QUSERVEDð6
73
73
D\
D\
Varying length
D\QUSPD
1
D\ QUSDATAð2
74
74
D\
D\
Varying length
DQUSIð2ðð
DS
BASED(BASSPCPTR)
D\
Qus EXTIð2ðð
D QUSBRTNðð
1
4B ð
D\
Bytes Returned
D QUSBAVLð1
5
8B ð
D\
Bytes Available
D QUSCHðð
9
24
D\
Continue Handle
D QUSOPGME
25
28B ð
D\
Offset Program Entry
D QUSNBRPRðð
29
32B ð
D\
Number Programs Returned
D QUSLPGME
33
36B ð
D\
Length Program Entry
D\QUSERVEDð7
37
37
D\
D\
Varying length
D\QUSARRAYð1
74
DIM(ðððð1)
D\ QUSONEðð
9B ð OVERLAY(QUSARRAYð1:ðððð1)
D\ QUSEPNð3
2ð
OVERLAY(QUSARRAYð1:ðððð5)
D\ QUSFN11
8
OVERLAY(QUSARRAYð1:ððð25)
D\ QUSREPð2
1
OVERLAY(QUSARRAYð1:ððð33)
D\ QUSCEðð
1
OVERLAY(QUSARRAYð1:ððð34)
D\ QUSERVEDð8
2
OVERLAY(QUSARRAYð1:ððð35)
D\ QUSPGMNð1
9B ð OVERLAY(QUSARRAYð1:ððð37)
D\ QUSPGMNð2
1ð
OVERLAY(QUSARRAYð1:ððð41)
D\ QUSPGMLðð
1ð
OVERLAY(QUSARRAYð1:ððð51)
D\ QUSDCðð
9B ð OVERLAY(QUSARRAYð1:ððð61)
D\ QUSOEDðð
9B ð OVERLAY(QUSARRAYð1:ððð65)
D\ QUSLEDðð
9B ð OVERLAY(QUSARRAYð1:ððð69)
D\ QUSERVEDð8
1
OVERLAY(QUSARRAYð1:ððð73)
D\ QUSPDðð
1
D\ QUSDATAð3
1
OVERLAY(QUSARRAYð1:ðððð1)
D\
D\
Varying length
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
D QUSONEð1
1
4B ð
D\
Offset Next Entry
D QUSEPNð4
5
24
D\
Exit Point Name

B-80

System API Programming V4R1

D QUSFN12
D\
D QUSREPð3
D\
D QUSCEð1
D\
D QUSERVEDð9
D\
D QUSPGMNð3
D\
D QUSPGMNð4
D\
D QUSPGMLð1
D\
D QUSDIð1
D\
D QUSMFILðð
D\
D QUSMFILL
D\
D QUSMIðð
D\
D QUSTDð1
D\
D QUSRSV2ð1
D\
D QUSDCð1
D\
D QUSOPD
D\
D QUSLPD
D\
D\QUSERVEDð9
D\
D\
D\QUSPDð1
D\ QUSDATAð4
D\
D\
DQUSIð3ðð
D\
D QUSBRTNð1
D\
D QUSBAVLð2
D\
D QUSCHð1
D\
D QUSOPGMEðð
D\
D QUSNBRPRð1
D\
D QUSLPGMEðð
D\
D\QUSERVED1ð
D\
D\
D\QUSARRAYð2
D\ QUSONEð2

4ðB ð

5ð

6ð

138

139

14ð

141

144B ð

145

148B ð

149

152B ð

153

154

1
154

Format Name
Registered Exit Point
Complete Entry
Reserved
Program Number
Program Name
Program Library
Desc Indicator
Message File
Message File Library
Message Id
Text Desc
Reserved2
Data CCSID
Offset Pgm Data
Length Pgm Data

Varying length

Varying length
DS
Qus EXTIð3ðð
1

4B ð

8B ð

Bytes Returned
Bytes Available
9

24
Continue Handle

28B ð

32B ð

36B ð

Offset Program Entry
Number Programs Returned
Length Program Entry

Varying length
154
DIM(ðððð1)
9B ð OVERLAY(QUSARRAYð2:ðððð1)
Appendix B. Original Examples in Additional Languages

B-81

D\ QUSEPNð5
2ð
OVERLAY(QUSARRAYð2:ðððð5)
D\ QUSFN13
8
OVERLAY(QUSARRAYð2:ððð25)
D\ QUSREPð4
1
OVERLAY(QUSARRAYð2:ððð33)
D\ QUSCEð2
1
OVERLAY(QUSARRAYð2:ððð34)
D\ QUSERVED11
2
OVERLAY(QUSARRAYð2:ððð35)
D\ QUSPGMNð5
9B ð OVERLAY(QUSARRAYð2:ððð37)
D\ QUSPGMNð6
1ð
OVERLAY(QUSARRAYð2:ððð41)
D\ QUSPGMLð2
1ð
OVERLAY(QUSARRAYð2:ððð51)
D\ QUSDIð2
1
OVERLAY(QUSARRAYð2:ððð61)
D\ QUSMFILð1
1ð
OVERLAY(QUSARRAYð2:ððð62)
D\ QUSMFILLðð
1ð
OVERLAY(QUSARRAYð2:ððð72)
D\ QUSMIð1
7
OVERLAY(QUSARRAYð2:ððð82)
D\ QUSTDð2
5ð
OVERLAY(QUSARRAYð2:ððð89)
D\ QUSRSV2ð2
2
OVERLAY(QUSARRAYð2:ðð139)
D\ QUSDCð2
9B ð OVERLAY(QUSARRAYð2:ðð141)
D\ QUSOPDðð
9B ð OVERLAY(QUSARRAYð2:ðð145)
D\ QUSLPDðð
9B ð OVERLAY(QUSARRAYð2:ðð149)
D\ QUSERVED11
1
OVERLAY(QUSARRAYð2:ðð153)
D\ QUSPDð2
1
D\ QUSDATAð5
1
OVERLAY(QUSARRAYð2:ðððð1)
D\
D\
Varying length
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
C
'QusRetrieveExitInformation'
D\
D\ Miscellaneous data
D\
DEPNTNAME
S
2ð
INZ('EXAMPLE_EXIT_POINT')
DEPGM_NBR
S
9B ð INZ(-1)
DRCVVAR
S
1
DIM(35ðð)
DRCVVAR_SZ
S
9B ð INZ(%SIZE(RCVVAR:\ALL))
DBASSPCPTR
S
\
DINFSPCPTR
S
\
DCALL_PGM
S
21
C\
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

C\
C\
C\
C\
C
C\
C\
C\
C\
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C\
C
C
C
C
C\
C\
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C\
C\
C\

Initialize the error code to inform the API that all
exceptions should be returned through the error code parameter.
EVAL

QUSBPRV = %SIZE(QUSEC)

Blank out the continuation handle to let the API know that this
is a first attempt at the retrieve operation.
MOVE

\BLANKS

CONTIN_HDL

Call the API to retrieve the exit programs
CALLB
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM

QUSREI

'EXTIð1ðð'
'EXMPð1ðð'
ð

CONTIN_HDL
RCVVAR
RCVVAR_SZ
FORMAT
EPNTNAME
EPNT_FMT
EPGM_NBR
QUSNBRSC
QUSEC

8
8

QUSBAVL > ð
QPRINT
ERRAEPNT
DONE

If the call to retrieve exit point information is successful,
check to see if there are any exit programs to call.
EVAL
IF
EVAL
IF

BASSPCPTR = %ADDR(RCVVAR)
QUSNBRPR > ð
INFSPCPTR = %ADDR(RCVVAR(QUSOEPE+1))
QUSNBREP > ð

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.
EVAL

CONTIN_HDL = \BLANKS

Call the exit programs
EXSR

CUSREI

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.

Appendix B. Original Examples in Additional Languages

B-83

C
C
C
C
C
C
C
C\
C\
C\
C\
C\
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C
C
C\
C\
C\

B-84

DOW
EVAL
EXSR
ENDDO
ENDIF
ENDIF
EXSR

QUSCHðð <> \BLANKS
CONTIN_HDL = QUSCHðð
CUSREI

DONE

End of MAINLINE
Process exit programs in receiver variable
CUSREI

BEGSR

Call the API to retrieve the exit program information
CALLB
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM

QUSREI

'EXTIð2ðð'
'EXMPð1ðð'
ð

CONTIN_HDL
RCVVAR
RCVVAR_SZ
FORMAT
EPNTNAME
EPNT_FMT
EPGM_NBR
QUSNBRSC
QUSEC

8
8

QUSBAVL > ð
QPRINT
ERRAEPGM
DONE

INFSPCPTR = %ADDR(RCVVAR(QUSOPGME+1))
QUSNBRPRðð

Get the exit program name and library

System API Programming V4R1

C
EVAL
CALL_PGM = %TRIMR(QUSPGML) +
C
'/' + QUSPGMNðð
C\
C\ Call the exit program while ignoring failures on the call
C\
C
CALL
CALL_PGM
ð1
C
PARM
EXIT_PARMS
1ð
C\
C\ Set INFSPCPTR to point to the next exit program entry
C\
C
EVAL
INFSPCPTR = %ADDR(RCVVAR(QUSONE+1))
C
ENDDO
C
ENDSR
C\
C\ Return to programs caller
C
DONE
BEGSR
C
EVAL
\INLR = '1'
C
RETURN
C
ENDSR
O\
OQPRINT
E
ERRAEPNT
1 6
O
'Attempt to retrieve inforO
mation failed: '
O
QUSEI
OQPRINT
E
ERRAEPGM
1 6
O
'Attempt to retrieve Exit O
Programs failed: '
O
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

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.
\
\
\
\
\
\
\
\
\

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

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

\
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

\
\
\
\
\
\
\
\
\
\
\
\
\

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

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
F\
Deregister an Exit Point
F\
F\ Language:
OPM RPG
F\
F\ Description: This program removes an exit program and
F\
deregisters an exit point from the registration
F\
facility.
F\
F\ APIs Used:
QUSRMVEP - Remove Exit Program
F\
QUSDRGPT - Deregister Exit Point
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\
FQPRINT O
F
132
PRINTER
UC
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\
I\ Miscellaneous data
I\
I
DS
I
B
1
4ðPGMNBR
I I
'EXAMPLE_EXIT_POINT '
5 24 EPNTNM
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

C\
C
CALL 'QUSRMVEP'
C
PARM
EPNTNM
C
PARM 'EXMPð1ðð'FORMAT 8
C
PARM 1
PGMNBR
C
PARM
QUSBN
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
C
EXCPTERRPGM
C
EXSR DONE
C
ENDIF
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'
C
PARM
EPNTNM
C
PARM 'EXMPð1ðð'FORMAT
C
PARM
QUSBN
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
C
EXCPTERREPT
C
EXSR DONE
C
ENDIF
C
EXSR DONE
C\
C\ End of MAINLINE
C\
C\
C\ Return to programs caller
C
DONE
BEGSR
C
SETON
LR
C
RETRN
C
ENDSR
O\
OQPRINT E 1ð6
ERREPT
O
'Attempt to deregister '
O
'exit point failed: '
O
QUSBND
OQPRINT E 1ð6
ERRPGM
O
'Attempt to remove exit '
O
'program failed: '
O
QUSBND

Appendix B. Original Examples in Additional Languages

B-91

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
F\
Deregister an Exit Point
F\
F\ Language:
ILE RPG
F\
F\ Description: This program removes an exit program and
F\
deregisters an exit point from the registration
F\
facility.
F\
F\ APIs Used:
QusRemoveExitProgram
- Remove Exit Program
F\
QusDeregisterExitPoint - Deregister Exit Point
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\
FQPRINT
O
F 132
PRINTER OFLIND(\INOF) USROPN
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 Deregister Exit Point API.
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D QUSDEP
C
'QusDeregisterExitPoint'
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D\Prototype for calling Remove Exit Program API.
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D QUSREPGM
C
'QusRemoveExitProgram'
D\
D\ Miscellaneous data
D\
DPGM_NBR
9B ð
DEPNTNAME
S
2ð
INZ('EXAMPLE_EXIT_POINT')
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

B-92

System API Programming V4R1

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
QUSREPGM
C
PARM
EPNTNAME
C
PARM
'EXMPð1ðð'
FORMAT
8
C
PARM
1
PGM_NBR
C
PARM
QUSEC
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 > ð
C
OPEN
QPRINT
C
EXCEPT
ERRAEPGM
C
EXSR
DONE
C
ENDIF
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
QUSDEP
C
PARM
EPNTNAME
C
PARM
'EXMPð1ðð'
FORMAT
C
PARM
QUSEC
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 > ð
C
OPEN
QPRINT
C
EXCEPT
ERRAEPNT
C
EXSR
DONE
C
ENDIF
C
EXSR
DONE
C\
C\ End of MAINLINE
C\
C\
C\ Return to programs caller
C
DONE
BEGSR
C
EVAL
\INLR = '1'
C
RETURN
C
ENDSR
O\
OQPRINT
E
ERRAEPNT
1 6
O
'Attempt to deregister Appendix B. Original Examples in Additional Languages

B-93

O
O
OQPRINT
O
O
O

exit point failed: '
QUSEI
ERRAEPGM

6
'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
\/
/\
\/
/\ Language:
ILE C
\/
/\
\/
/\ 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
#include
#include
#include
#include
#include
#include
#include
#include

/\
/\
/\
/\
/\
/\
/\

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
\/

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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

char
Exception_Data[1ðð];
} error_code_t;
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Global Variables
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
char
api_name[1ð];
char
cont_hdl[2ð];
char
ext_attr[1ð];
char
list_status;
char
mbr_list[8];
char
obj_type[1ð];
char
rcvvar[8];
char
rjobd_fmt[8];
char
space_auth[1ð];
char
space_dmn[1ð];
char
space_init;
char
space_name[2ð];
char
space_rep[1ð];
char
space_text[5ð];
char
space_type[1ð];
char
usr_prf[1ð];
char
\usrspc_ptr, \usrspc_base;
int
rcvlen = 8;
int
size_entry;
int
space_size = 1;
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

} /\ 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,
/\ User space and library
\/
mbr_list,
/\ Member list
\/
usr_prf,
/\ User profile
\/
obj_type,
/\ Object type
\/
cont_hdl,
/\ Continuation handle .3/
\/
&error_code);
/\ 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
QTEMP
", 2ð);
space_init = ðxðð;
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
", 1ð);
memcpy(space_rep, "\YES
", 1ð);
memcpy(space_dmn, "\USER
", 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

{
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,
/\ Receiver variable
\/
rcvlen,
/\ Receiver variable length
\/
rjobd_fmt,
/\ Format
\/
space_name,
/\ User space name and library
\/
space_type,
/\ User object type
\/
&error_code);
/\ 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,
/\ User space name and library
\/
ext_attr,
/\ Extended attribute
\/
space_size,
/\ Size of the user space
\/
&space_init,
/\ Space initialization
\/
space_auth,
/\ Public authority to user space \/
space_text,
/\ User space text
\/
space_rep,
/\ Replace existing user space?
\/
&error_code,
/\ Error Code
\/
space_dmn);
/\ Domain of created user space
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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,
/\ User space name and library
\/
&usrspc_ptr,
/\ 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

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=ð; iInformation_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

{
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

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

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.
\
\
\
\
\
\
\
\
\

COPY QUSEC OF QSYSINC-QLBLSRC.
\
\ Listing text
\
ð1 OBJ-ENTRY.
ð5 OBJECT.
ð9 TEXT1
PIC X(ð8) VALUE "Object: ".
ð9 NAME
PIC X(1ð).
ð9 TEXT2
PIC X(1ð) VALUE " Library: ".
ð9 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
PIC X(2ð) VALUE "ADOPTS
QTEMP
ð5 SPC-SIZE
PIC S9(ð9) VALUE 1 BINARY.
ð5 SPC-INIT
PIC X(ð1) VALUE X"ðð".
ð5 SPCPTR
POINTER.
ð5 RCVVAR
PIC X(ð8).
ð5 RCVVARSIZ
PIC S9(ð9) VALUE 8 BINARY.
ð5 LST-STATUS
PIC X(ð1).
ð5 MBR-LIST
PIC X(ð8) VALUE "OBJPð2ðð".
ð5 CONTIN-HDL
PIC X(2ð).
ð5 APINAM
PIC X(1ð).
ð5 ROBJD-FMT
PIC X(ð8) VALUE "OBJDð1ðð".
ð5 SPC-TYPE
PIC X(1ð) VALUE "\USRSPC".
ð5 EXT-ATTR
PIC X(1ð) VALUE "QSYLOBJP".
ð5 SPC-AUT
PIC X(1ð) VALUE "\ALL".
ð5 SPC-TEXT
PIC X(5ð).
ð5 SPC-REPLAC
PIC X(1ð) VALUE "\YES".
ð5 SPC-DOMAIN
PIC X(1ð) VALUE "\USER".
\
LINKAGE SECTION.
\

B-102

System API Programming V4R1

\ Input parameters.
\
ð1 USR-PRF
PIC X(1ð).
ð1 OBJ-TYPE
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

\ 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,
.2/
PERFORM GETLST,
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

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

\
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:
ILE RPG
F\
F\ Description: This program prints a report showing all objects
F\
that adopt owner authority. The two parameters
F\
passed to the program are the profile to be
F\
checked and the type of objects to be listed.
F\
The parameter values are the same as those
F\
accepted by the QSYLOBJP API.
F\
F\ APIs Used:
QSYLOBJP - List Objects that Adopt Owner Authority
F\
QUSCRTUS - Create User Space
F\
QUSPTRUS - Retrieve Pointer to User Space
F\
QUSROBJD - Retrieve Object Description

B-106

System API Programming V4R1

F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\
FQPRINT
O
F 132
PRINTER OFLIND(\INOF)
D\
D\ Error Code parameter include
D\
D/COPY QSYSINC/QRPGLESRC,QUSEC
D\
DSPC_NAME
S
2ð
INZ('ADOPTS
QTEMP
')
DSPC_SIZE
S
9B ð INZ(1)
DSPC_INIT
S
1
INZ(X'ðð')
DLSTPTR
S
\
DSPCPTR
S
\
DARR
S
1
BASED(LSTPTR) DIM(32767)
DRCVVAR
S
8
DRCVVARSIZ
S
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ðð
DS
BASED(SPCPTR)
D\
Qus Generic Header ð1ðð
D QUSUA
1
64
D\
User Area
D QUSSGH
65
68B ð
D\
Size Generic Header
D QUSSRL
69
72
D\
Structure Release Level
D QUSFN
73
8ð
D\
Format Name
D QUSAU
81
9ð
D\
API Used
D QUSDTC
91
1ð3
D\
Date Time Created
D QUSIS
1ð4
1ð4
D\
Information Status
D QUSSUS
1ð5
1ð8B ð
D\
Size User Space
D QUSOIP
1ð9
112B ð
D\
Offset Input Parameter
D QUSSIP
113
116B ð
D\
Size Input Parameter
D QUSOHS
117
12ðB ð
D\
Offset Header Section
D QUSSHS
121
124B ð
D\
Size Header Section
D QUSOLD
125
128B ð
D\
Offset List Data
D QUSSLD
129
132B ð
D\
Size List Data
D QUSNBRLE
133
136B ð
D\
Number List Entries
D QUSSEE
137
14ðB ð
D\
Size Each Entry
Appendix B. Original Examples in Additional Languages

B-107

D QUSSIDLE
141
144B ð
D\
CCSID List Ent
D QUSCID
145
146
D\
Country ID
D QUSLID
147
149
D\
Language ID
D QUSSLI
15ð
15ð
D\
Subset List Indicator
D QUSERVEDðð
151
192
D\
Reserved
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
DS
BASED(LSTPTR)
D\
Qsy OBJP Header
D QSYUNðð
1
1ð
D\
User name
D QSYCVðð
11
3ð
D\
Continuation Value
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D\Record structure for OBJPð2ðð format
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
DQSYð2ððLð2
DS
BASED(LSTPTR)
D\
Qsy OBJPð2ðð List
D QSYNAMEð6
1
1ð
D\
Name
D QSYBRARYð6
11
2ð
D\
Library
D QSYOBJT13
21
3ð
D\
Object Type
D QSYOBJIUðð
31
31
D\
Object In Use
D QSYOBJA11
32
41
D\
Object Attribute
D QSYOBJT14
42
91
D\
Object Text
C\
C\ Start of mainline
C\
C
\ENTRY
PLIST
C
PARM
USR_PRF
1ð
C
PARM
OBJ_TYPE
1ð
C
EXSR
INIT
C
EXSR
PROCES
C
EXSR
DONE
C\
C\ Start of subroutines
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
PROCES
BEGSR
C\

B-108

System API Programming V4R1

C\
C\
C\
C\
C\
C
C\
C
C\
C\
C\
C
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C
C
C\
C\
C\
C
C
C
C\
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C\
C
C
C
C\
C\

This subroutine processes each entry returned by QSYLOBJP

Do until the list is complete

LST_STATUS

MOVE

QUSIS

DOUEQ

'C'

LST_STATUS

If valid information was returned
QUSIS
QUSIS

IFEQ
OREQ

'C'
'P'

and list entries were found
QUSNBRLE

IFGT

set LSTPTR to the first byte of the User Space
EVAL

LSTPTR = SPCPTR

increment LSTPTR to the first List entry
EVAL

LSTPTR = %ADDR(ARR(QUSOLD + 1)) .5/

and process all of the entries
DO
EXCEPT

.6/

QUSNBRLE
OBJ_ENTRY

after each entry, increment LSTPTR to the next entry
EVAL
END
END

LSTPTR = %ADDR(ARR(QUSSEE + 1)) .7/

If all entries in this User Space have been processed, check
if more entries exist than can fit in one User Space
QUSIS

IFEQ

'P'

by resetting LSTPTR to the start of the User Space
EVAL

LSTPTR = SPCPTR

and then incrementing LSTPTR to the Input Parameter Header
EVAL

LSTPTR = %ADDR(ARR(QUSOIP + 1))

If the continuation handle in the Input Parameter Header is
blank, then set the List status to Complete
QSYCVðð

IFEQ
MOVE
ELSE

\BLANKS
'C'

LST_STATUS

Else, call QSYLOBJP reusing the User Space to get more
Appendix B. Original Examples in Additional Languages

B-109

C\ List entries
C\
C
MOVE
QSYCVðð
CONTIN_HDL .2/
C
EXSR
GETLST
C
MOVE
QUSIS
LST_STATUS
C
END
C
END
C
ELSE
C\
C\ And if an unexpected status, log an error (not shown) and exit
C\
C
EXSR
DONE
C
END
C
END
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
GETLST
BEGSR
C\
C\ Call QSYLOBJP to generate a list
C\ The continuation handle is set by the caller of this
C\ subroutine.
C\
C
CALL
QSYLOBJP
C
PARM
SPC_NAME
C
PARM
'OBJPð2ðð'
MBR_LIST
8
C
PARM
USR_PRF
C
PARM
OBJ_TYPE
C
PARM
CONTIN_HDL
2ð .3/
C
PARM
QUSEC
C\
C\ Check for errors on QSYLOBJP
C\
C
QUSBAVL
IFGT
ð
C
MOVEL
'QSYLOBJP'
APINAM
1ð
C
EXSR
APIERR
C
END
C
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
'QUSROBJD'
C
PARM
RCVVAR
C
PARM
RCVVARSIZ
C
PARM
'OBJDð1ðð'
ROBJD_FMT
8
C
PARM
SPC_NAME
C
PARM
'\USRSPC'
SPC_TYPE
1ð
C
PARM
QUSEC
C\
C\ Check for errors on QUSROBJD

B-110

System API Programming V4R1

C\
C
QUSBAVL
IFGT
ð
C\
C\ If CPF98ð1, then User Space was not found
C\
C
QUSEI
IFEQ
'CPF98ð1'
C\
C\ So create a User Space for the List generated by QSYLOBJP
C\
C
CALL
'QUSCRTUS'
C
PARM
SPC_NAME
C
PARM
'QSYLOBJP ' EXT_ATTR
1ð
C
PARM
SPC_SIZE
C
PARM
SPC_INIT
C
PARM
'\ALL'
SPC_AUT
1ð
C
PARM
\BLANKS
SPC_TEXT
5ð
C
PARM
'\YES'
SPC_REPLAC
1ð
C
PARM
QUSEC
C
PARM
'\USER'
SPC_DOMAIN
1ð
C\
C\ Check for errors on QUSCRTUS
C\
C
QUSBAVL
IFGT
ð
C
MOVEL
'QUSCRTUS'
APINAM
1ð
C
EXSR
APIERR
C
END
C\
C\ Else, an error occurred accessing the User Space
C\
C
ELSE
C
MOVEL
'QUSROBJD'
APINAM
1ð
C
EXSR
APIERR
C
END
C
END
C\
C\ Set QSYLOBJP (via GETLST) to start a new list
C\
C
MOVE
\BLANKS
CONTIN_HDL
C
EXSR
GETLST
C\
C\ Get a resolved pointer to the User Space for performance
C\
C
CALL
'QUSPTRUS'
C
PARM
SPC_NAME
C
PARM
SPCPTR
C
PARM
QUSEC
C\
C\ Check for errors on QUSPTRUS
C\
C
QUSBAVL
IFGT
ð
C
MOVEL
'QUSPTRUS'
APINAM
1ð
C
EXSR
APIERR
C
END
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
APIERR
BEGSR
C\
C\ Log any error encountered, and exit the program
Appendix B. Original Examples in Additional Languages

B-111

C\
C
APINAM
DSPLY
C
QUSEI
DSPLY
C
EXSR
DONE
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
DONE
BEGSR
C\
C\ Exit the program
C\
C
EXCEPT
END_LIST
C
EVAL
\INLR = '1'
C
RETURN
C
ENDSR
OQPRINT
E
OBJ_ENTRY
1
O
'Object: '
O
QSYNAMEð6
O
' Library: '
O
QSYBRARYð6
O
' Type: '
O
QSYOBJT13
O
' Text: '
O
QSYOBJT14
OQPRINT
E
END_LIST
1
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

\
\ 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
PIC S9(ð9) VALUE ð.
ð5 ERROR-HANDLER
PIC X(2ð) VALUE "ERRHDL1
\LIBL
".
ð5 SCOPE
PIC X(ð1) VALUE "C".
ð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

PRIOR-ERROR-HANDLER OF MISC,
QUS-EC.
\
\
\
\
\
\

\
\ 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

\ 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
PIC S9(ð9) BINARY.
ð5 MSG-LENGTH
PIC S9(ð9) BINARY.
ð1 OBJECT-LIST.
ð5 OBJECT-NAME
PIC X(3ð).
ð5 LIBRARY-NAME
PIC X(3ð).
ð5 OBJECT-TYPE
PIC X(1ð) VALUE "\PGM
".
LINKAGE SECTION.
ð1 CBL-EXCEPTION-ID
PIC X(ð7).
ð1 VALID-RESPONSES
PIC X(ð6).
ð1 PGM-IN-ERROR.
ð5 PGM-NAME
PIC X(1ð).
ð5 LIB-NAME
PIC X(1ð).
ð1 SYS-EXCEPTION-ID
PIC X(ð7).
ð1 MESSAGE-TEXT
PIC X(ð1).
ð1 MESSAGE-LENGTH
PIC S9(ð9) BINARY.
ð1 SYS-OPTION
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

\
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.
.1/
MOVE LIB-NAME TO LIBRARY-NAME.
\
\ 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:
Demonstrate use of OPM-based Log Software Error
F\
F\ Language:
OPM RPG

B-116

System API Programming V4R1

F\
F\ Description:
This program performs a divide-by-ð operation
F\
to cause an exception. This exception is
F\
caught using RPG \PSSR support,
F\
and the exception is then logged as a
F\
software error.
F\
F\ APIs used:
QPDLOGER
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
E\
E\ Arrays used to extract source line number where error happened
E\
E
SRC
8 1
E
TGT
8 1
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
I
11 15ðSTATUS
I
21 28 SRC
I
4ð 46 EXCPID
I
81 9ð LIBNAM
I\
I\ Some miscellaneous fields
I\
IMISC
DS
I
B
1
4ðFAILPT
I
B
5
8ðDATA#
I
B
9 12ðOBJS#
I
13 2ð TGT
I
13 2ððLIN#C
I\
I\ DATA represents the data items to report as part of problem
I\
IDATA
DS
4ð96
I\
I\ DATAPT defines (via offset and length values) how to read DATA
I\
IDATAPT
DS
256
I
B
1
4ðDTAOFF
I
B
5
8ðDTALEN
I\
I\ OBJS represents the list of objects to spool as part of problem
I\
IOBJS
DS
259ð
I
1 3ð OBJ1N
Appendix B. Original Examples in Additional Languages

B-117

I
I
C\
C\
C\
C
C
C\
C\
C\
C
C\
C\
C\
C
C
C\
C\
C\
C
C\
C\
C\
C\
C
C
C\
C\
C\
C
C\
C\
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C

B-118

31
61

6ð OBJ1L
7ð OBJ1T

Prepare for divide-by-zero situation
Z-ADD1ð
Z-ADDð

FACT1
FACT2

5ð
5ð

DIV

RESULT

5ð

and divide by ð
FACT1

FACT2

should not get here due to divide-by-ð exception
MOVE '1'
RETRN

\INLR

Program exception subroutine:
\PSSR

BEGSR

Make sure we are not catching an exception due to the \PSSR
subroutine itself
SWITCH

IFEQ ' '
MOVE '1'

SWITCH

Set API error code to work in nonexception mode
Z-ADD16

QUSBNB

Record the source listing line number that caused the failure
First, extract the numeric portion of the PSDS line number

SRC,X

Z-ADD8
Z-ADD8
Z-ADDð
DOWEQ' '
SUB 1
END
DOWGTð
MOVE SRC,X
SUB 1
SUB 1
END

X
Y
LIN#C

1ð
1ð

TGT,Y
X
Y

Then record it:
Z-ADDLIN#C

FAILPT

Record the status code for the failure
MOVELSTATUS

DATA

Record where to find the status data within DATA

System API Programming V4R1

Z-ADDð

DTAOFF

C
C
C\
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C\
C\
C\
C
C
C

Z-ADD5
Z-ADD1

DTALEN
DATA#

For illustration purposes also dump the program object as
part of logging the software error
MOVELPGMNAM
MOVELLIBNAM
MOVEL'\PGM'
Z-ADD1

OBJ1N
OBJ1L
OBJ1T
OBJS#

.1/

Call the Log Software Error API
CALL 'QPDLOGER'
PARM
PGMNAM
PARM EXCPID
MSGID 12
PARM
MSGKEY 4
PARM
FAILPT
PARM 'Y'
JOBLOG 1
PARM
DATA
PARM
DATAPT
PARM
DATA#
PARM
OBJS
PARM
OBJS#
PARM
QUSBN
If an error on the API call, then indicate a terminal error
QUSBNC
IFGT ð
'TERM ERR'DSPLY
END
ELSE
If error within \PSSR, then indicate \PSSR error
'\PSSR

'DSPLY
END

No matter how the program got to the \PPSR, end the program
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:
ILE RPG
F\
F\ Description: This program performs a divide by ð operation to
F\
cause an exception. This exception is caught using
F\
RPG's \PSSR support, and the exception is then

Appendix B. Original Examples in Additional Languages

B-119

F\
logged as a software error.
F\
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
S
5B ð INZ(1ð)
Dfactor2
S
5B ð INZ(ð)
Dresult
S
5B ð
Dline_nbr
S
9B ð
Ddata
DS
4ð96
Ddatapt
DS
D data_off
9B ð
D data_len
9B ð
Ddata#
S
9B ð
Dobjl
DS
259ð
Dobjl#
S
9B ð
D\
D\ Program status data structure
D\
DPSDS
SDS
D pgm_name
1
1ð
D status
11
15 ð
D src_line
21
28
D exception
4ð
46
D lib_name
81
9ð
C\
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
'1'
\INLR
C
return
C\
C\ Program exception subroutine:
C\
C
\PSSR
BEGSR
C\
C\ Make sure we are not catching an exception due to the \PSSR
C\ subroutine itself
C\
C
switch
ifeq
' '
C
move
'1'
switch
1
C\
C\ Set API error code to work in non-exception mode
C\
C
eval
qusbprv = %size(qusec)
C\
C\ Record line number where error happened
C\

B-120

System API Programming V4R1

C
C\
C\
C\
C
C\
C\
C\
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C\
C\
C\
C
C
C

move

src_line

line_nbr

Record the status code as data
movel

status

data

Record where status located in data
eval
eval
eval

data_off = 1
data_len = 5
data# = 1

For illustration purposes, dump the program object
eval
eval
eval
eval

%SUBST(objl:1:3ð) = pgm_name .1/
%SUBST(objl:31:3ð) = lib_name
%SUBST(objl:61:1ð) = '\PGM'
objl# = 1

Call the Report Software Error API
call
parm
parm
parm
parm
parm
parm
parm
parm
parm
parm
parm

'QPDLOGER'
exception

'Y'

pgm_name
msgid
msgkey
line_nbr
joblog
data
datapt
data#
objl
objl#
qusec

12
4
1

If an error on the API call, then indicate a terminal error
qusbavl
ifgt
'Terminal err'dsply
end
else

If error within \PSSR, then indicate \PSSR error
'\PSSR error' dsply
end
No matter how the program got to the \PSSR, end the program
move
return
endsr

'1'

\inlr

Appendix B. Original Examples in Additional Languages

B-121

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

COPY QUSEC OF QSYSINC-QCBLLESRC.
\
\ Miscellaneous elements
\
ð1 MISC.
ð5 Y
PIC S9(ð9) VALUE ð.
ð1 ERROR-HANDLER
PROCEDURE-POINTER.
ð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

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

ð1
ð1
ð1

ð1
ð1
ð1
ð1
ð1
ð1

CBL-EXCEPTION-ID
VALID-RESPONSES
PGM-IN-ERROR.
ð5 PGM-NAME
ð5 LIB-NAME
SYS-EXCEPTION-ID
MESSAGE-TEXT
MESSAGE-LENGTH
SYS-OPTION
ERR-MODULE-NAME
CBL-PGM-NAME

PIC
PIC

X(ð7).
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).

\
\ 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
.2/
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.
\
\ 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

\
\ 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:
ILE RPG
F\
F\ Description: This program performs a divide-by-ð operation to
F\
cause an exception. This exception is caught using
F\
RPGs \PSSR support, and the exception is then logged
F\
as a software error.
F\
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

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
S
\
dim(2ð)
Dx
S
5B ð INZ(1)
D\
D\ Misc. data elements
D\
Dfactor1
S
5B ð INZ(1ð)
Dfactor2
S
5B ð INZ(ð)
Dresult
S
5B ð
Drc
S
2
INZ('RC')
D\
D\ Program status data structure
D\
DPSDS
SDS
D pgm_name
1
1ð
D status
11
15 ð
D src_line
21
28
D exception
4ð
46
D lib_name
81
9ð
C\
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
'1'
\INLR
C
return
C\
C\ Program exception subroutine:
C\
C
\PSSR
BEGSR
C\
C\ Make sure we are not catching an exception due to the \PSSR
C\ subroutine itself
C\
C
switch
ifeq
' '
C
move
'1'
switch
1
C\
C\ Set API error code to work in nonexception mode
C\
C
eval
qusbprv = %size(qusec)
C\
C\ Record the suspected program and library name
C\
C
eval
qpdkð1 = 1ð1
C
eval
qpdpgmnl = %SIZE(pgm_name)
C
eval
qpdlibnl = %SIZE(lib_name)
C
eval
qpdpgmn = %ADDR(pgm_name) .2/
C
eval
qpdlibn = %ADDR(lib_name)
C\
C\
and record the key:
C\
Appendix B. Original Examples in Additional Languages

B-127

C
C
C\
C\
C\
C
C
C
C
C
C
C\
C\
C\
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C

B-128

eval
eval

pdr(x) = %addr(qpdspgm)
x = x + 1

Record the failing source statement number
eval
eval
eval
eval
eval
eval

qpdkð7 = 2ðð
qpdkl = %SIZE(rc)
qpddl = %SIZE(src_line)
qpddt = 'C'
qpdkð8 = %ADDR(rc)
qpdd = %ADDR(src_line)

and record the key:
eval
eval

pdr(x) = %addr(qpds)
x = x + 1

Record the status code as data
eval
eval
eval
eval

qpdk11 = 3ð1
qpddlðð = %SIZE(status)
qpddi = 1
qpddðð = %ADDR(status)

and record the key:
eval
eval

pdr(x) = %addr(qpds)
x = x + 1

For illustration purposes, dump the program object
eval
eval
eval
eval

qpdk12 = 3ð2
qpdobjn = pgm_name
qpdobjlib = lib_name
qpdobjt = '\PGM'

and record the key:
eval
eval

pdr(x) = %addr(qpdnsot)
x = x + 1

Call the Report Software Error API
callb
parm
parm
parm

qpdrse
pdr
x
qusec

If an error on the API call, then indicate a terminal error
qusbavl
ifgt
'Terminal err'dsply
end
else

If error within \PSSR, then indicate \PSSR error

System API Programming V4R1

'\PSSR error' dsply

C
end
C\
C\ No matter how the program got to the \PSSR, end the program
C\
C
move
'1'
\inlr
C
return
C
endsr

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:
\/
/\

\/
/\

\/
/\
\/
/\ APIs Used:
QSZCRTPD - Create Product Definition
\/
/\
QSZCRTPL - Create Product Load
\/
/\
QSZPKGPO - Package Product Option
\/
/\
QLICOBJD - Change Object Description
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Function:
Create_Prod_Def_Obj
\/
/\ Description: Create the product definition ABCðð5ð for product \/
/\
ABC.
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
Appendix B. Original Examples in Additional Languages

B-129

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
",1ð);
memcpy(prod_info.Reg_ID_Val,"5ð7253ð927
",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
",8);
memcpy(prod_lang_load.Opt,"ðððð",4);
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
",
/\ Product definition name
\/
&prod_info,
/\ Product definition info
\/
&prod_opt_list,
/\ Product option list
\/
1,
/\ Number of options
\/
&prod_lang_load,
/\ Language load list
\/
1,
/\ Number languages
\/
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

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;
/\ Product load information
\/
Qsz_Lib_Inf_t prin_lib_info;
/\ Principal library info
\/
Qsz_Add_Lib_t add_libs;
/\ Additional library list
\/
Qsz_Pre_Ext_t preop_expgm;
/\ Preoperational exit program \/
Qsz_Flr_Lst_t folder_list;
/\ Folder list
\/
Qus_EC_t error_code;
/\ Error code parameter
\/
char text_desc[5ð];
/\ Text description
\/

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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
",1ð);
memcpy(prin_lib_info.Prim_Lib,"ABC
",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

/\ the error code parameter.
\/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
error_code.Bytes_Provided=sizeof(error_code);
QSZCRTPL("ABCðð5ð
",
/\ Product load name
\/
&prod_load_info,
/\ Product load information
\/
"
",
/\ Secondary language lib name \/
&prin_lib_info,
/\ Principal library
\/
&add_libs,
/\ Additional libraries
\/
ð,
/\ Number of additional libs
\/
&preop_expgm,
/\ Preoperational exit program \/
1,
/\ Number of preop exit pgms
\/
&folder_list,
/\ Folder list
\/
ð,
/\ Number of folders
\/
text_desc,
/\ Text description
\/
"\USE
",
/\ Public authority
\/
&error_code);
/\ 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
",1ð);
memcpy(prod_load_info.Lod_ID,"2924
",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,
ð,
&preop_expgm,
1,
&folder_list,
ð,
text_desc,
"\USE
",
&error_code);

/\
/\
/\
/\
/\
/\
/\
/\
/\
/\
/\
/\
/\

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
Folder list
Number of folders
Text description
Public authority
Error code

if (error_code.Bytes_Available > ð)
{
printf("Failed in QSZCRTPL API with error: %.7s",

B-132

System API Programming V4R1

\/
\/
\/
\/
\/
\/
\/
\/
\/
\/
\/
\/
\/

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

change_obj_info_t cobji;
Qus_EC_t error_code;
char rtn_lib[1ð];

"ðððð","5ðð1","ðABCABCV3R1Mð",
"ABCðð29
ABC
","\PRDLOD
",
"ðððð","2924","ðABCABCV3R1Mð",
"ABC
ABC
","\LIB
",
"ðððð","5ðð1","ðABCABCV3R1Mð"};
/\ Change object information
/\ 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,
obj_info[i].obj_name_lib,
obj_info[i].obj_type,
&cobji,
&error_code);

/\
/\
/\
/\
/\

Return library
\/
Object name
\/
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

/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ 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,
/\ Product option information \/
"\YES",
/\ 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

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

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
PIC X(1ð).
ð5 TEXT2
PIC X(11) VALUE "with error ".
ð5 EXCEPTION-ID PIC X(ð7).
\
\ Compile Time Array
\
ð1 OBJ-INFO.
ð5 ELEMENT-ð1 PIC X(41)
VALUE "ABCPGMMRM1\PGM
ðððð5ðð1ðABCABCV3R1Mð".
ð5 ELEMENT-ð2 PIC X(41)
VALUE "ABCPGMMRM2\PGM
ðððð5ðð1ðABCABCV3R1Mð".
ð5 ELEMENT-ð3 PIC X(41)
VALUE "ABCPGMMRI1\PGM
ðððð2924ðABCABCV3R1Mð".
ð5 ELEMENT-ð4 PIC X(41)
VALUE "ABCPGMMRI2\PGM
ðððð2924ðABCABCV3R1Mð".
ð5 ELEMENT-ð5 PIC X(41)
VALUE "ABCPGM
\PGM
ðððð5ðð1ðABCABCV3R1Mð".
ð5 ELEMENT-ð6 PIC X(41)
VALUE "QCLSRC
\FILE
ðððð2924ðABCABCV3R1Mð".
ð5 ELEMENT-ð7 PIC X(41)
VALUE "ABCDSPF
\FILE
ðððð2924ðABCABCV3R1Mð".
ð5 ELEMENT-ð8 PIC X(41)
VALUE "ABCPF
\FILE
ðððð2924ðABCABCV3R1Mð".
ð5 ELEMENT-ð9 PIC X(41)
VALUE "ABCMSG
\MSGF
ðððð2924ðABCABCV3R1Mð".
ð5 ELEMENT-1ð PIC X(41)
VALUE "ABC
\CMD
ðððð2924ðABCABCV3R1Mð".
ð5 ELEMENT-11 PIC X(41)
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
PIC X(1ð).
1ð OBJ-TYPE
PIC X(1ð).
1ð PRD-OPT-ID
PIC X(ð4).
1ð PRD-OPT-LD
PIC X(ð4).
Appendix B. Original Examples in Additional Languages

B-137

1ð LP-ID
PIC X(13).
\
\ Change Object Information parameter
\
ð1 COBJI.
ð5 NUMKEY
PIC S9(ð9) VALUE 3 BINARY.
ð5 KEY13
PIC S9(ð9) VALUE 13 BINARY.
ð5 LEN13
PIC S9(ð9) VALUE 4 BINARY.
ð5 PID13
PIC X(ð4).
ð5 KEY12
PIC S9(ð9) VALUE 12 BINARY.
ð5 LEN12
PIC S9(ð9) VALUE 4 BINARY.
ð5 LID12
PIC X(ð4).
ð5 KEY5
PIC S9(ð9) VALUE 5 BINARY.
ð5 LEN5
PIC S9(ð9) VALUE 13 BINARY.
ð5 LP5
PIC X(13).
\
\ Miscellaneous data
\
ð1 MISC.
ð5 FIRST-ERR
PIC X(ð1) VALUE "ð".
ð5 PROD-ID
PIC X(ð7) VALUE "ðABCABC".
ð5 PROD-NAME
PIC X(2ð) VALUE "ABCðð5ð
ABC".
ð5 RLS-LVL
PIC X(ð6) VALUE "V3R1Mð".
ð5 NBR-OPTS
PIC S9(ð9) VALUE 1 BINARY.
ð5 NBR-LANGS
PIC S9(ð9) VALUE 1 BINARY.
ð5 TEXT-DESC
PIC X(5ð) VALUE "ABC Product".
ð5 PUB-AUT
PIC X(1ð) VALUE "\USE".
ð5 NBR-ADD-LB
PIC S9(ð9) VALUE ð BINARY.
ð5 NBR-PE
PIC S9(ð9) VALUE 1 BINARY.
ð5 NBR-FLDRS
PIC S9(ð9) VALUE ð BINARY.
ð5 OBJNAM
PIC X(2ð).
ð5 PROD-ID-NM
PIC X(1ð).
ð5 SEC-LANG
PIC X(1ð).
ð5 I
PIC S9(ð9) BINARY.
ð5 RTN-LIB
PIC X(1ð).
ð5 OBJ-TYPE-2
PIC X(1ð).
ð5 REPKG
PIC X(ð4) VALUE "\YES".
ð5 ALWCHG
PIC X(ð5) VALUE "\NO".
\
\ 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

\
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

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

\
\ 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

\
\
\
\
\

\
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
\
\ 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

\
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
\
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

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\
package your product like IBM products.
F\
F\Header Files Included: QUSEC
- Error Code Parameter
F\
QSZCRTPD - Create Product Definition API
F\
QSZCRTPL - Create Product Load API
F\
QSZPKGPO - Package Product Option API
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\
FQPRINT
O
F 132
PRINTER OFLIND(\INOF) USROPN
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\ 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
S
41
DIM(15) CTDATA PERRCD(1)
D\
DOBJ_INFO_I
DS
BASED(OBJ_PTR)
D OBJ_NAME
1ð
D OBJ_TYPE
1ð
D PRD_OPT_ID
4
D PRD_OPT_LD
4
D LP_ID
13

B-144

System API Programming V4R1

D\
D\ Change Object Information parameter
D\
DCOBJI
DS
D NUMKEY
9B ð INZ(3)
D KEY13
9B ð INZ(13)
D LEN13
9B ð INZ(4)
D PID13
4
D KEY12
9B ð INZ(12)
D LEN12
9B ð INZ(4)
D LID12
4
D KEY5
9B ð INZ(5)
D LEN5
9B ð INZ(13)
D LP5
13
D\
D\ Miscellaneous data
D\
DAPI_NAME
S
1ð
DFIRST_ERR
S
1
INZ('ð')
DPROD_ID
S
7
INZ('ðABCABC')
DPROD_NAME
S
2ð
INZ('ABCðð5ð
ABC
')
DRLS_LVL
S
6
INZ('V3R1Mð')
DNBR_OPTS
S
9B ð INZ(1)
DNBR_LANGS
S
9B ð INZ(1)
DTEXT_DESC
S
5ð
INZ('ABC Product')
DPUB_AUT
S
1ð
INZ('\USE')
DNBR_ADD_LB
S
9B ð INZ(ð)
DNBR_PE
S
9B ð INZ(1)
DNBR_FLDRS
S
9B ð INZ(ð)
DOBJNAM
S
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
EXSR
PRDDFN
.1/
C\
C\ Create Product Load Objects - ABCðð5ð (MRM) and ABCðð29 (MRI)
C\
C
EXSR
PRDLOD
.2/
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\
Appendix B. Original Examples in Additional Languages

B-145

C
EXSR
PKGPO
.4/
C\
C\ All done, product is ready to ship.
C\
C
EVAL
\INLR = '1'
C
RETURN
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\
ABCðð5ð for the ABC product.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
PRDDFN
BEGSR
C\
C\ Setup for Product Definition
C\ Fill Product Definition Information Parameter
C\
C
EVAL
QSZPID = PROD_ID
C
EVAL
QSZRL = RLS_LVL
C
EVAL
QSZMFIL = 'ABCMSG'
C
EVAL
QSZFC = '\CURRENT'
C
EVAL
QSZCC = '\CURRENT'
C
EVAL
QSZRD = '9412ð1'
C
EVAL
QSZAMR = '\NO'
C
EVAL
QSZRIDT = '\PHONE'
C
EVAL
QSZRIDV = '5ð72535ð1ð'
C\
C\ Fill Product Load Parameter
C\
C
EVAL
QSZOPT = 'ðððð'
C
EVAL
QSZMID = 'ABCððð1'
C
EVAL
QSZADN = '\NODYNNAM'
C
EVAL
QSZCL = '5ðð1'
C
EVAL
QSZERVEDðð = \BLANKS
C\
C\ Fill Language Load List Parameter
C\
C
EVAL
QSZLLðð = '2924'
C
EVAL
QSZOPTðð = 'ðððð'
C
EVAL
QSZERVEDð1 = \BLANKS
C\
C\ Create the Product Definition for the ABC Product
C\
C
CALL
'QSZCRTPD'
C
PARM
PROD_NAME
C
PARM
QSZPI
C
PARM
QSZPO

B-146

System API Programming V4R1

C
PARM
1
NBR_OPTS
C
PARM
QSZLL
C
PARM
1
NBR_LANGS
C
PARM
TEXT_DESC
C
PARM
PUB_AUT
C
PARM
QUSEC
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 > ð
C
EVAL
API_NAME = 'QSZCRTPD'
C
EXSR
ERRCOD
C
ENDIF
C\
C
ENDSR
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C\ Subroutine: PRDLOD
C\
C\ Descriptive Name: Create product loads.
C\
C\ Description: This subroutine will create the product loads,
C\
ABCðð5ð and ABCðð29, for the ABC product.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
PRDLOD
BEGSR
C\
C\ Setup for Product Load for MRM Objects
C\ Fill Product Load Information Parameter
C\
C
EVAL
QSZPIDðð = PROD_ID
C
EVAL
QSZRLðð = RLS_LVL
C
EVAL
QSZOPTð1 = 'ðððð'
C
EVAL
QSZLT = '\CODE'
C
EVAL
QSZLID = '\CODEDFT'
C
EVAL
QSZRIDTðð = '\PRDDFN'
C
EVAL
QSZRIDVðð = \BLANKS
C
EVAL
QSZMTR = '\CURRENT'
C
EVAL
QSZERVEDð2 = \BLANKS
C\
C\ Fill Principal Library Information Parameter
C\
C
EVAL
QSZDL = 'ABC'
C
EVAL
QSZPL = 'ABC'
C
EVAL
QSZPEP = 'ABCPGMMRM2'
C\
C\ Fill Preoperation Exit Programs Parameter
C\
C
EVAL
QSZPEPðð = 'ABCPGMMRM1'
C
EVAL
QSZDLðð = 'ABC'
C\
Appendix B. Original Examples in Additional Languages

B-147

C\
C\
C\
C\
C\
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C\
C\
C\
C
C
C
C
C\
C\
C\
C\
C
C
C\
C\
C\
C
C\
C\
C\
C
C\
C\
C\
C\
C\
C\
C\
C\
C\
C
C
C

B-148

Fill Additional Library List Parameter
None
Fill Folder List Parameter
None
Let's create the product load for the ABC Product - MRM Objects
CALL
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM

'QSZCRTPL'
'ABCðð5ð'
\BLANKS

PROD_ID_NM
QSZLI
SEC_LANG
QSZLIðð
QSZAL
NBR_ADD_LB
QSZPE
NBR_PE
QSZFL
NBR_FLDRS
TEXT_DESC
PUB_AUT
QUSEC

1ð
1ð

QUSBAVL > ð
API_NAME = 'QSZCRTPL'
ERRCOD

Setup for Product Load for MRI Objects
Fill Product Load Information Parameter
EVAL
EVAL

QSZLT = '\LNG'
QSZLID = '2924'

Fill Principal Library Information Parameter
EVAL

QSZPEP = 'ABCPGMMRI2'

Fill Preoperation Exit Programs Parameter
EVAL

QSZPEPðð = 'ABCPGMMRI1'

Fill Additional Library List Parameter
None
Fill Folder List Parameter
None
Let's create the product load for the ABC Product - MRI Objects

System API Programming V4R1

CALL
PARM
PARM

'QSZCRTPL'
'ABCðð29'

PROD_ID_NM
QSZLI

C
PARM
'ABC2924'
SEC_LANG
C
PARM
QSZLIðð
C
PARM
QSZAL
C
PARM
NBR_ADD_LB
C
PARM
QSZPE
C
PARM
NBR_PE
C
PARM
QSZFL
C
PARM
NBR_FLDRS
C
PARM
TEXT_DESC
C
PARM
PUB_AUT
C
PARM
QUSEC
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 > ð
C
EVAL
API_NAME = 'QSZCRTPL'
C
EXSR
ERRCOD
C
ENDIF
C\
C
ENDSR
C\
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\
descriptions for all objects that make up the
C\
ABC Product. Currently that is 15 objects. They
C\
are listed at the end of this program.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
COBJD
BEGSR
C\
C\ Need to associate all objects with the ABC Product
C\
C
1
DO
15
I
3 ð
C
EVAL
OBJ_PTR = %ADDR(OBJ_INFO(I))
C
EVAL
OBJNAM = OBJ_NAME + 'ABC'
C
EVAL
LP5 = LP_ID
C
EVAL
PID13 = PRD_OPT_ID
C
EVAL
LID12 = PRD_OPT_LD
C
EVAL
TYPE = OBJ_TYPE
C\
C
CALL
'QLICOBJD'
C
PARM
RTN_LIB
1ð
C
PARM
OBJNAM
C
PARM
TYPE
1ð
C
PARM
COBJI
C
PARM
QUSEC
C\
Appendix B. Original Examples in Additional Languages

B-149

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 > ð
C
EVAL
API_NAME = 'QLICOBJD'
C
EXSR
ERRCOD
C
ENDIF
C\
C
ENDDO
C\
C
ENDSR
C\
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\
It makes sure that all objects exist that are
C\
associated with the product.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
PKGPO
BEGSR
C\
C\ Setup for packing the ABC Product.
C\ Fill Product Option Information Parameter
C\
C
EVAL
QSZOPTð2 = 'ðððð'
C
EVAL
QSZPIDð1 = PROD_ID
C
EVAL
QSZRLð1 = RLS_LVL
C
EVAL
QSZLIDðð = '\ALL'
C
EVAL
QSZERVEDð3 = \BLANKS
C\
C\ Let's package the ABC Product.
C\
C\
C
CALL
'QSZPKGPO'
C
PARM
QSZPOI
C
PARM
'\YES'
REPKG
4
C
PARM
'\NO'
ALWCHG
5
C
PARM
QUSEC
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 > ð
C
EVAL
API_NAME = 'QSZPKGPO'
C
EXSR
ERRCOD
C
ENDIF
C\

B-150

System API Programming V4R1

C
ENDSR
C\
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\
file if any errors are returned in the error code
C\
parameter.
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
ERRCOD
BEGSR
C\
C\ Process errors returned from the API.
C\
C\ If first error found, then open QPRINT \PRTF
C\
C
IF
FIRST_ERR = 'ð'
C
OPEN
QPRINT
C
EVAL
FIRST_ERR = '1'
C
ENDIF
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
'Failed in API '
O
API_NAME
O
'with error '
O
QUSEI
\\CTDATA OBJ_INFO
ABCPGMMRM1\PGM
ðððð5ðð1ðABCABCV3R1Mð
ABCPGMMRM2\PGM
ðððð5ðð1ðABCABCV3R1Mð
ABCPGMMRI1\PGM
ðððð2924ðABCABCV3R1Mð
ABCPGMMRI2\PGM
ðððð2924ðABCABCV3R1Mð
ABCPGM
\PGM
ðððð5ðð1ðABCABCV3R1Mð
QCLSRC
\FILE
ðððð2924ðABCABCV3R1Mð
ABCDSPF
\FILE
ðððð2924ðABCABCV3R1Mð
ABCPF
\FILE
ðððð2924ðABCABCV3R1Mð
ABCMSG
\MSGF
ðððð2924ðABCABCV3R1Mð
ABC
\CMD
ðððð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ð

Appendix B. Original Examples in Additional Languages

B-151

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
PIC X(2ð).
ð5 LIBRARY-NAME
PIC X(1ð).
ð5 SPACE-SIZE
PIC S9(ð9) BINARY.
ð5 SPACE-INIT
PIC X(ð1) VALUE "X'ðð'".
ð5 SPACE-POINTER
POINTER.

B-152

System API Programming V4R1

ð1

ð5 FORMAT-NAME-1
ð5 OVERRIDES
ð5 SYSTEM
ð5 FORMAT-1
ð5 EXT-ATTR
ð5 SPACE-AUT
ð5 SPACE-TEXT
ð5 SPACE-REPLACE
ð5 SPACE-DOMAIN
ð5 API-NAME
CHG-US-ATTR.
ð5 NBR-OF-ATTR
ð5 ATTR-KEY
ð5 DATA-SIZE
ð5 ATTR-DATA

PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC

X(ð8).
X(ð1) VALUE
X(1ð) VALUE
X(1ð) VALUE
X(1ð).
X(1ð) VALUE
X(5ð) VALUE
X(1ð) VALUE
X(1ð) VALUE
X(1ð).

"ð".
"\LCL".
"\INT".
"\CHANGE".
"QDBRTVFD".
"\YES".
"\USER".

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
ð1 FILE-NAME
ð1 FORMAT-NAME-PARM

PIC
PIC
PIC

X(2ð).
X(2ð).
X(1ð).

\
\ 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

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

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:
RTVFD
D\
D\ Language:
ILE RPG
D\
D\ Description: This program retrieves a file definition
D\
template to a user space.
D\
D\ APIs Used:
QDBRTVFD - Retrieve File Description
D\
QUSCRTUS - Create User Space
D\
QUSCUSAT - Change User Space Attributes
D\
QUSPTRUS - Retrieve a pointer to a User Space
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)
D\
Header information - The
D\
FDT starts here
D QDBFYRET
1
4B ð
D\
Bytes returned - The length
D\
of the data returned
D QDBFYAVL
5
8B ð
D\
Bytes available - The number
D\
of bytes provided for the

Appendix B. Original Examples in Additional Languages

B-155

D\
D\
D\QDBFHFLG
D QDBBITS27
D\ QDBRSV1ðð
D\ QDBFHFPLðð
D\ QDBRSV2ðð
D\ QDBFHFSUðð
D\ QDBRSV3ðð
D\ QDBFHFKYðð
D\ QDBRSV4ðð
D\ QDBFHFLCðð
D\ QDBFKFSOðð
D\ QDBRSV5ðð
D\ QDBFHSHRðð
D\ QDBRSV6ðð
D\ QDBFIGCDðð
D\ QDBFIGCLðð
D\
D QDBRSV7
D\
D QDBLBNUM
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
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\
D QDBFHAUT
D\
D\
D\
D\
D\
D\
D\

B-156

System API Programming V4R1

file definition template
data
9
2
1
1
1
1
1
1
1
1
1
1
2
1
1
11
15

17
19
21
1
1
4
1
1
22
23
31

2
1ð
BITS
BIT
BIT
BIT
BIT
BIT
BIT
BIT
BIT
BIT
BIT
BITS
BIT
BIT
Attribute Bytes
14
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
formats for a program
described physical
file that is linked to
a Data Dictionary.
1-32 = Number of based-on
physical files for
a logical file.
14
18B ð
2ðB ð
1
21
BIT
BIT
BITS
BIT
BIT
22
3ð
Keyed Sequence Access Path
4ð
Public Authority (AUT)
'\CHANGE
' = Public change
authority.
'\ALL
' = Public all
authority.
'\USE
' = Public use
authority.

D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D QDBFHUPL
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D QDBFHMXM
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D QDBFWTFI
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\

'\EXCLUDE

' = Public exclude
authority.
'authorization-list-name'
= Name of the
authorization
list whose
authority is
used for the
file.
This is the original public
authority that the file was
created with, NOT the current
public authority for the file.
41

41
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
number from 1
to 255 assigned
when the disk
device is
configured) of
a specific
auxiliary
storage unit on
the system.
43B ð
Maximum Members (MAXMBRS)
ð = No maximum is specified
for the number of members,
the system maximum of
32,767 members is used
(\NOMAX).
1-32,767 = The value for the
maximum number of
members that the
file can have
(maximum-members).
45B ð
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

D\
D\
D\
D\
D QDBFHFRT
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D QDBHMNUM
D\
D\
D\
D\
D QDBRSV11
D\
D QDBFBRWT
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\QDBQAAFðð
D QDBBITS29
D\ QDBRSV12ðð
D\ QDBFPGMDðð
D\
D QDBMTNUM
D\
D\
D\
D\
D\QDBFHFL2

B-158

System API Programming V4R1

seconds that a
program waits for
the file (numberof-seconds).
46

5ð
59

61
7
1
62

47B ð
Records To Force A Write
(FRCRATIO)
ð = 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
explicitly forced
to auxiliary
storage (numberof-records-beforeforce).
49B ð
Number Of Members
ð-32,767 = The current number
of members for the
file.
58
Reserved.
6ðB ð
Maximum Record Wait Time
(WAITRCD)
-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).
1-32,767 = The number of
seconds that a
program waits for
the record
(number-ofseconds).
1
61
BITS
BIT
Additional Attribute Flags
63B ð
Total Number Of Record
Formats
1-32 = Number of record
formats for the file.
2

D QDBBITS3ð
D\ QDBFJNAPðð
D\ QDBRSV13ðð
D\ QDBFRDCPðð
D\ QDBFWTCPðð
D\ QDBFUPCPðð
D\ QDBFDLCPðð
D\ QDBRSV14ðð
D\ QDBFKFNDðð
D\
D QDBFVRM
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
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\
D QDBRSV17
D\
D QDBFHCRT
D\
D\
D\
D\
D\QDBFHTX
D QDBRSV18ðð
D QDBFHTXTðð
D\
D QDBRSV19
D\
D\QDBFSRC
D QDBFSRCFðð

64
1
1
1
1
1
1
9
1
66

68
1
1
1
1
1
1
1
1
69
7ð

83
85
135

148

65
BIT
BIT
BIT
BIT
BIT
BIT
BITS
BIT
Additional Attribute Flags
67B ð
First Supported
Version Release Modification
Level
X'ðððð' = Pre-Version 2
Release 1
Modification ð file.
X'15ðð' = Version 2 Release 1
Modification ð,
V2R1Mð, file.
X'15ð1' = Version 2 Release 1
Modification 1,
V2R1M1, file.
X'16ðð' = Version 2 Release 2
Modification ð,
V2R2Mð, file.
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.
1
68
BIT
BIT
BIT
BIT
BIT
BIT
BIT
BIT
Additional Attribute Flags
69
Reserved.
82
File Level Identifier
The date of the file in
internal standard format
(ISF), CYYMMDDHHMMSS.
52
84
134
File Text Description
147
Reserved
3ð
157

Appendix B. Original Examples in Additional Languages

B-159

D QDBFSRCMðð
D QDBFSRCLðð
D\
D QDBFKRCV
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D QDBRSV2ð
D\
D QDBFTCID
D\
D\
D\
D\
D\
D\
D\
D\
D QDBFASP
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D QDBRSV21
D\
D QDBXFNUM
D\
D\
D\
D\
D\
D\
D QDBRSV22
D\
D QDBFODIC
D\
D\
D\
D\

B-160

System API Programming V4R1

158
168

167
177

178

Source File Fields
Access Path Recovery
(RECOVER)
'A' = The file has its access
path built after the
IPL has been completed
(\AFTIPL).
'N' = The access path of the
file is NOT built
during or after an IPL
(\NO). The file's
access path is built
when the file is next
opened.
'S' = The file has its access
path built during the
IPL (\IPL).
179
2ð2

2ð4

2ð6
2ð7

2ð9
285

2ð1
Reserved.
2ð3B ð
Coded Character Set
Identifier, CCSID, For
Text Description (TEXT)
ð = There is NO text
description for the file.
1-65,535 = The CCSID for the
file's text
description.
2ð5
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
located on
(asp-identifier).
2ð6
Reserved.
2ð8B ð
Maximum Number Of Fields
1-8ððð = The number of fields
in the file's record
format that contains
the largest number
of fields.
284
Reserved.
288B ð
Offset from the start of the
FDT header, Qdbfh, to the
IDDU/SQL Data Dictionary
Area, Qdbfdic.

D QDBRSV23
D\
D QDBFFIGL
D\
D\
D\
D\
D\
D\
D\
D\
D QDBFMXRL
D\
D\
D\
D\
D\
D\
D\
D\
D QDBRSV24
D\
D QDBFGKCT
D\
D\
D\
D\
D\
D\
D\
D\
D\
D QDBFOS
D\
D\
D\
D QDBRSV25
D\
D QDBFOCS
D\
D\
D\
D\
D\
D QDBRSV26
D\
D QDBFPACT
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\

289
3ð3

3ð5

3ð7
315

317

321
329

333
337

3ð2
Reserved.
3ð4B ð
File Generic Key Length
ð-2ððð = The length of the
key before the first
\NONE key field for
the file.
If this file has an arrival
sequence access path, this
field is NOT applicable.
3ð6B ð
Maximum Record Length
1-32766 = The length of the
record in the
file's record
format that
contains the
largest number of
bytes.
314
Reserved.
316B ð
File Generic Key Field Count
ð-12ð = The count of the
number of key fields
before the first
\NONE key field for
the file.
If this file has an arrival
sequence access path, this
field is NOT applicable.
32ðB ð
Offset from the start of the
FDT header, Qdbfh, to the
File Scope Array, Qdbfb.
328
Reserved.
332B ð
Offset from the start of the
FDT header, Qdbfh, to the
Alternative Collating
Sequence Table section,
Qdbfacs.
336
Reserved.
338
Access Path Type
'AR' = Arrival sequence
access path.
'KC' = Keyed sequence access
path with duplicate
keys allowed.
Duplicate keys are
accessed in firstchanged-first-out
(FCFO) order.
'KF' = Keyed sequence access

Appendix B. Original Examples in Additional Languages

B-161

D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D QDBFHRLS
D\
D\
D\
D\
D\
D\
D\
D\
D\
D\
D QDBRSV27
D\
D QDBPFOF
D\
D\
D\
D\
D QDBLFOF
D\
D\
D\
D\
D\QDBFSSFPðð
D\ QDBFNLSBð1
D
QDBBITS58
D\ QDBFSSCSð2
D\ QDBR1ð3ð2
D QDBFLANGð1
D QDBFCNTYð1
D\
D QDBFJORN

B-162

System API Programming V4R1

path with duplicate
keys allowed.
Duplicate keys are
accessed in firstin-first-out
(FIFO) order.
'KL' = Keyed sequence access
path with duplicate
keys allowed.
Duplicate keys are
accessed in lastin-first-out
(LIFO) order.
'KN' = Keyed sequence access
path with duplicate
keys allowed.
No order is guaranteed
when accessing
duplicate keys.
Duplicate keys are
accessed in one of the
following methods:
(FCFO) (FIFO) (LIFO).
'KU' = Keyed sequence access
path with NO duplicate
keys allowed (UNIQUE).
339

344
File Version Release
Modification Level
'VxRyMz' = Where x is the
Version, y is the
Release, and z is
the Modification
level
example V2R1M1
Version 2 Release
1 Modification 1

345
365

369

373
3
5
374
377
379

364
Reserved.
368B ð
Offset from the start of the
FDT header, Qdbfh, to the
Physical File Specific
Attributes section, Qdbfphys.
372B ð
Offset from the start of the
FDT header, Qdbfh, to the
Logical File Specific
Attributes section, Qdbflogl.
6
1
373
BITS
BITS
376
378
Sort Sequence Table
382B ð

D\
Offset from the start of the
D\
FDT header, Qdbfh, to the
D\
Journal Section, Qdbfjoal.
D QDBRSV28
383
4ðð
D\
Reserved.
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D\
D\The FDT header ends here.
D\
D\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
D\
D\ Misc. elements
D\
DSPC_NAME
S
2ð
DFILE_NAME
S
2ð
DFMT_NAME
S
1ð
DFILE_USED
S
2ð
DLIB_NAME
S
1ð
DSPC_SIZE
S
9B ð
DSPC_INIT
S
1
INZ(X'ðð')
DSPCPTR
S
\
DFORMAT
S
8
DOVERRIDES
S
1
INZ('ð')
DSYSTEM
S
1ð
INZ('\LCL')
DFORMAT_1
S
1ð
INZ('\INT')
DCHG_ATTR
DS
D NBR_ATTR
9B ð INZ(1)
D ATTR_KEY
9B ð INZ(3)
D DATA_SIZE
9B ð INZ(1)
D ATTR_DATA
1
INZ('1')
C\
C\ Start of mainline
C\
C
\ENTRY
PLIST
C
PARM
SPC_NAME
C
PARM
FILE_NAME
C
PARM
FMT_NAME
C\
C
EXSR
INIT
C
EXSR
PROCES
C
EXSR
DONE
C\
C\ Start of subroutines
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
PROCES
BEGSR
C\
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
QDBFPACT
C
ENDSR
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
INIT
BEGSR
C\
C\ One time initialization code for this program
Appendix B. Original Examples in Additional Languages

B-163

C\
C\
C\
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C\
C\

B-164

Set Error Code structure to not use exceptions
Z-ADD

QUSBPRV

Create a User Space for QDBRTVFD
CALL
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM
PARM

'QUSCRTUS'
\BLANKS
1ð24
'\CHANGE'
'QDBRTVFD'
'\YES'
'\USER'

SPC_NAME
EXT_ATTR
SPC_SIZE
SPC_INIT
SPC_AUT
SPC_TEXT
SPC_REPLAC
QUSEC
SPC_DOMAIN

1ð

1ð
5ð
1ð
1ð

Check for errors on QUSCRTUS
QUSBAVL

IFGT
MOVEL
EXSR
END

ð
'QUSCRTUS'
APIERR

APINAM

1ð

Change the User Space so that it is extendable
CALL
PARM
PARM
PARM
PARM

'QUSCUSAT'
LIB_NAME
SPC_NAME
CHG_ATTR
QUSEC

Check for errors on QUSCUSAT
QUSBAVL

IFGT
MOVEL
EXSR
END

ð
'QUSCUSAT'
APIERR

APINAM

1ð

Get a resolved pointer to the User Space
CALL
PARM
PARM
PARM

'QUSPTRUS'
SPC_NAME
SPCPTR
QUSEC

Check for errors on QUSPTRUS
QUSBAVL

IFGT
MOVEL
EXSR
END

ð
'QUSPTRUS'
APIERR

APINAM

1ð

If no errors, then call QDBRTVFD passing the address of the
User Space as the receiver variable. As Data Structure
QDBQ25 is defined as BASED(SPCPTR) and SPCPTR is set to the
first byte of the User Space, simply passing QDBQ25 will cause

System API Programming V4R1

C\ QDBRTVFD to use the User Space.
C\
C
CALL
'QDBRTVFD'
C
PARM
QDBQ25
C
PARM
167767ð4
SPC_SIZE
C
PARM
FILE_USED
C
PARM
'FILDð1ðð'
FORMAT
C
PARM
FILE_NAME
C
PARM
FMT_NAME
C
PARM
OVERRIDES
C
PARM
SYSTEM
C
PARM
FORMAT_1
C
PARM
QUSEC
C\
C\ Check for errors on QDBRTVFD
C\
C
QUSBAVL
IFGT
ð
C
MOVEL
'QDBRTVFD'
APINAM
1ð
C
EXSR
APIERR
C
END
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
APIERR
BEGSR
C\
C\ Log any error encountered, and exit the program
C\
C
APINAM
DSPLY
C
QUSEI
DSPLY
C
EXSR
DONE
C
ENDSR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C
DONE
BEGSR
C\
C\ Exit the program
C\
C
EVAL
\INLR = '1'
C
RETURN
C
ENDSR

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

\
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 ".
ð5 API-NAME
PIC X(1ð) VALUE "QCAPCMD".
ð5 TEXT2
PIC X(11) VALUE "with error ".
ð5 EXCEPTION-ID PIC X(ð7).
\
\ 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
PIC S9(ð9) VALUE 2ð BINARY.
ð1 FORMAT-NAME
PIC X(ð8) VALUE "CPOPð1ðð".
ð1 FIRST-ERROR
PIC X(ð1) VALUE "ð".
ð1 NAME-OF-QUEUE
PIC X(1ð) VALUE "EXAMPLEQ".

B-166

System API Programming V4R1

ð1
ð1
ð1
ð1
ð1

NAME-OF-LIBRARY
SIZE-OF-MSG
WAIT-TIME
MSG
MSG-BACK

PIC X(1ð) VALUE "QUEUELIB".
PIC S9(ð5) VALUE 1ð PACKED-DECIMAL.
PIC S9(ð5) VALUE ð PACKED-DECIMAL.
PIC X(1ð) VALUE "EXAMPLE".
PIC X(1ð).

\
\ 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

\
\ 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

\ 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\
create and manipulate a \DTAQ.
F\
F\ Header Files Included: QUSEC
- Error Code Parameter
F\
QCAPCMD - Process Command API
F\
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
'CRTLIB LIB(QUEUELIB)'
1 2ð CRTLIB
I I
'DLTLIB LIB(QUEUELIB)'
21 4ð DLTLIB
I I
'CRTDTAQ DTAQ(QUEUELI41 82 CRTDQ
I
'B/EXAMPLEQ) MAXLEN(1I
'ð)'
I I
'DLTDTAQ DTAQ(QUEUELI83 113 DLTDQ
I
'B/EXAMPLEQ)'
I\
I\ Miscellaneous data structure
I\
I
DS
I
1 1ðð CMDSTR
I
B 1ð1 1ð4ðLENSTR
I I
2ð
B 1ð5 1ð8ðSIZE
I I
ð
B 1ð9ð112ðRCVSIZ
I I
'ð'
113 113 FSTERR
I
114 123 APINAM
C\
C\ Beginning of mainline
C\

Appendix B. Original Examples in Additional Languages

B-169

C\
C\
C\
C\
C\
C\
C\
C
C\
C\
C\
C
C
C
C
C
C
C\
C\
C\
C
C
C\
C
C\
C\
C\
C\
C\
C
C
C\
C
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C
C
C
C
C
C
C\
C\
C\
C
C\
C\
C\
C

B-170

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.
Z-ADD16

QUSBNB

Initialize QCAPCMD options control block for CL processing
Z-ADDð
MOVE 'ð'
MOVE 'ð'
MOVE 'ð'
MOVE \BLANKS
MOVE \LOVAL

QCABCB
QCABCC
QCABCD
QCABCF
QCABCG
QCABCH

Create library QUEUELIB
MOVELCRTLIB
Z-ADD2ð

CMDSTR
LENSTR

EXSR EXCCMD
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).
MOVELCRTDQ
Z-ADD42

CMDSTR
LENSTR

EXSR EXCCMD
Send information to the data queue.
CALL
PARM
PARM
PARM
PARM

'QSNDDTAQ'
'EXAMPLEQ'QUENAM 1ð
'QUEUELIB'LIBNAM 1ð
1ð
MSGSZ
5ð
'EXAMPLE' MSG
1ð

Retrieve information from the data queue.
CALL
PARM
PARM
PARM
PARM
PARM

'QRCVDTAQ'
'EXAMPLEQ'QUENAM 1ð
'QUEUELIB'LIBNAM 1ð
1ð
MSGSZ
5ð
MSGBCK 1ð
ð
WAITTM 5ð

Display the returned message
DSPLY

MSGBCK

Delete the data queue

System API Programming V4R1

MOVELDLTDQ

CMDSTR

C
Z-ADD31
LENSTR
C\
C
EXSR EXCCMD
C\
C\ Delete the library
C\
C
MOVELDLTLIB
CMDSTR
C
Z-ADD2ð
LENSTR
C\
C
EXSR EXCCMD
C\
C
SETON
LR
C
RETRN
C\
C\ End of MAINLINE
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
EXCCMD
BEGSR
C\
C\ Process requested CL command
C\
C
CALL 'QCAPCMD'
C
PARM
CMDSTR
C
PARM
LENSTR
C
PARM
QCABC
C
PARM
SIZE
C
PARM 'CPOPð1ðð'FORMAT 8
C
PARM
RCVVAR 1
C
PARM ð
RCVSIZ
C
PARM
RCVSIZ
C
PARM
QUSBN
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
MOVEL'QCAPCMD' APINAM
C
EXSR ERRCOD
C
ENDIF
C
ENDSR
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
ERRCOD
BEGSR
C\
C\ Process errors returned from the API.
C\
C\ If first error found, then open QPRINT \PRTF
C\
C
FSTERR
IFEQ 'ð'
C
OPEN QPRINT
C
MOVEL'1'
FSTERR
C
ENDIF
C\
C\ Print the error and the API that received the error
Appendix B. Original Examples in Additional Languages

B-171

C\
C
C\
C
OQPRINT
O
O
O
O

EXCPTBADNEW

1ð6

ENDSR
BADNEW
'Failed in API '
APINAM
'with error '
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\
create and manipulate a \DTAQ.
F\
F\ Header Files Included: QUSEC
- Error Code Parameter
F\
QCAPCMD - Process Command API
F\
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
C
'CRTLIB LIB(QUEUELIB)'
DDLTLIB
C
'DLTLIB LIB(QUEUELIB)'
DCRTDQ
C
'CRTDTAQ DTAQ(QUEUELIB/+
D
EXAMPLEQ) MAXLEN(1ð)'
DDLTDQ
C
'DLTDTAQ DTAQ(QUEUELIB/EXAMPLEQ)'
D\
D\ Miscellaneous data structure
D\
DCMD_STR
S
1ðð
DLEN_STR
S
9B ð
DCAPð1ðð_SZ
S
9B ð INZ(%SIZE(QCAPð1ðð))
DRCVVAR_SZ
S
9B ð INZ(ð)
DAPI_NAME
S
1ð
DFIRST_ERR
S
1
INZ('ð')
C\

B-172

System API Programming V4R1

C\
C\
C\
C\
C\
C\
C\
C\
C\
C
C\
C\
C\
C
C
C
C
C
C
C\
C\
C\
C
C
C\
C
C\
C\
C\
C\
C\
C
C
C\
C
C\
C\
C\
C
C
C
C
C
C\
C\
C\
C
C
C
C
C
C
C\
C\
C\
C
C\
C\

Beginning of mainline
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.
EVAL

QUSBPRV = %SIZE(QUSEC)

Initialize QCAPCMD options control block for CL processing
EVAL
EVAL
EVAL
EVAL
EVAL
EVAL

QCACMDPT = ð
QCABCSDH = 'ð'
QCAPA = 'ð'
QCACMDSS = 'ð'
QCAMK = \BLANKS
QCAERVED = \LOVAL

Create library QUEUELIB
EVAL
EVAL

CMD_STR = CRTLIB
LEN_STR = %SIZE(CRTLIB)

EXSR

EXEC_CMD

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).
EVAL
EVAL

CMD_STR = CRTDQ
LEN_STR = %SIZE(CRTDQ)

EXSR

EXEC_CMD

Send information to the data queue.
CALL
PARM
PARM
PARM
PARM

'QSNDDTAQ'
'EXAMPLEQ '
'QUEUELIB '
1ð
'EXAMPLE
'

NAME_OF_Q
NAME_OF_LB
MSG_SZ
MSG

1ð
1ð
5 ð
1ð

Retrieve information from the data queue.
CALL
PARM
PARM
PARM
PARM
PARM

'QRCVDTAQ'
'EXAMPLEQ '
'QUEUELIB '
1ð
ð

NAME_OF_Q
NAME_OF_LB
MSG_SZ
MSG_BACK
WAIT_TIME

1ð
5 ð

Display the returned message
DSPLY

MSG_BACK

Delete the data queue
Appendix B. Original Examples in Additional Languages

B-173

C\
C
EVAL
CMD_STR = DLTDQ
C
EVAL
LEN_STR = %SIZE(DLTDQ)
C\
C
EXSR
EXEC_CMD
C\
C\ Delete the library
C\
C
EVAL
CMD_STR = DLTLIB
C
EVAL
LEN_STR = %SIZE(DLTLIB)
C\
C
EXSR
EXEC_CMD
C\
C
EVAL
\INLR = '1'
C
RETURN
C\
C\ End of MAINLINE
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
EXEC_CMD
BEGSR
C\
C\ Process the requested CL command
C\
C
CALL
'QCAPCMD'
C
PARM
CMD_STR
C
PARM
LEN_STR
C
PARM
QCAPð1ðð
C
PARM
CAPð1ðð_SZ
C
PARM
'CPOPð1ðð'
FORMAT
8
C
PARM
RCVVAR
1
C
PARM
ð
RCVVAR_SZ
C
PARM
RCVVAR_SZ
C
PARM
QUSEC
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 > ð
C
EVAL
API_NAME = 'QCAPCMD'
C
EXSR
ERRCOD
C
ENDIF
C
ENDSR
C\
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\
C
ERRCOD
BEGSR
C\
C\ Process errors returned from the API.
C\
C\ If first error found, then open QPRINT \PRTF
C\
C
IF
FIRST_ERR = 'ð'
C
OPEN
QPRINT
C
EVAL
FIRST_ERR = '1'
C
ENDIF

B-174

System API Programming V4R1

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
'Failed in API '
O
API_NAME
O
'with error '
O
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 identified 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
#include
#include
#include
#include

#define BUFFER_SIZE
#define TEST_FILE

2ð48
"test.file"

Appendix B. Original Examples in Additional Languages

B-175

#define TEST_DATA
#define USER_ID

char
char
char
int
int
int
uid_t

"Hello World!"
"user_id_"

InitialFile[BUFFER_SIZE];
InitialDirectory[BUFFER_SIZE] = ".";
Buffer[32];
FilDes = -1;
BytesRead;
BytesWritten;
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

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

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

\ 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 ".
ð5 USER
PIC X(12).
ð1 CURDIR.
ð5 PRT-TEXT
PIC X(21) VALUE "Current directory is ".
ð5 INITIALDIR
PIC X(1ðð).
ð1 NEWFIL.
ð5 PRT-TEXT
PIC X(2ð) VALUE "Created file:
".
ð5 FILENAME
PIC X(1ðð).
ð1 DATAIN.
ð5 PRT-TEXT
PIC X(2ð) VALUE "Successfully read: ".
ð5 DATA-READ
PIC X(1ðð).
ð1 ERRLIN.
ð5 PRT-TEXT
PIC X(2ð) VALUE "The errno value is: ".
ð5 ERRVAL
PIC X(12).
\
\ Miscellaneous elements
\
ð1 BUFFER
PIC X(32767).
ð1 LENGTH-OF-BUFFER
PIC S9(ð9) BINARY VALUE 32767.
Appendix B. Original Examples in Additional Languages

B-179

ð1

ð1
ð1
ð1
ð1
ð1
ð1
ð1
ð1
ð1
ð1

TESTFILE.
ð5 TEST-FILE
ð5 NULL-TERMINATE
OFLAG
OFLAG-READ
OMODE
TEST-DATA
SIZE-TEST-DATA
FILE-DESCRIPTOR
BYTES-READ
BYTES-WRITTEN
RETURN-INT
RETURN-PTR

PIC X(ð9)
PIC X(ð1)
PIC X(ð4)
PIC X(ð4)
PIC X(ð4)
PIC X(12)
PIC S9(ð9)
PIC S9(ð9)
PIC S9(ð9)
PIC S9(ð9)
PIC S9(ð9)
POINTER.

VALUE "test.file".
VALUE LOW-VALUE.
VALUE X"ðððððð1A".
VALUE X"ððððððð1".
VALUE X"ððððð1Cð".
VALUE "Hello World!".
BINARY VALUE 12.
BINARY.
BINARY.
BINARY.
BINARY.

\
\ 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,
ELSE
MOVE BUFFER TO INITIALDIR,
WRITE LIST-LINE FROM CURDIR.
\
\ 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

ELSE

PERFORM ERROR-FOUND,
MOVE TEST-FILE TO FILENAME,
WRITE LIST-LINE FROM NEWFIL.

\
\ 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,
ELSE
MOVE "Successfully closed file"
TO LIST-LINE,
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

IF BYTES-READ = -1

ELSE

MOVE "Read failed"
TO LIST-LINE,
PERFORM ERROR-FOUND,
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,
ELSE
MOVE "Successfully closed file"
TO LIST-LINE,
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,
ELSE
MOVE "Unlink of file successful"
TO LIST-LINE,
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
\
int geterrno()
\
{

B-182

System API Programming V4R1

\
\
\
\
\
\
\
\
\

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:
ILE RPG
F\
F\
Description: Demonstrate use of integrated file system
F\
from ILE RPG
F\
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
FQSYSPRT
O
F 132
PRINTER
D\
D\ Prototype the Integrated File System APIs
D\
Dgetuid
PR
9B ð EXTPROC('getuid')
Dgetcwd
PR
\
EXTPROC('getcwd')
D
\
VALUE
D
9B ð VALUE
Dopen
PR
9B ð EXTPROC('open')
D
\
VALUE
D
4A
VALUE
D
4A
VALUE
Dwrite
PR
9B ð EXTPROC('write')
D
9B ð VALUE
D
\
VALUE
D
9B ð VALUE
Dclose
PR
9B ð EXTPROC('close')
D
9B ð VALUE
Dopen2
PR
9B ð EXTPROC('open')
D
\
VALUE
D
4A
VALUE
Dread
PR
9B ð EXTPROC('read')
D
9B ð VALUE
D
\
VALUE
D
9B ð VALUE
Dunlink
PR
9B ð EXTPROC('unlink')
D
\
VALUE
D\
D\ errno prototype; see error subroutine for further information
D\

Appendix B. Original Examples in Additional Languages

B-183

D\errno
PR
9B ð EXTPROC('geterrno')
DUser
S
12A
DBuffer
S
32767A
DReturnPtr
S
\
DReturnInt
S
9B ð
DFileDesc
S
9B ð
Dtest_file
S
2ð48A
INZ('test.file')
DInitialDir
S
2ð48A
Dtest_data
S
12A
INZ('Hello World!')
DBytesWrt
S
9B ð
DBytesRead
S
9B ð
DFileName
S
2ð49A
DPrintLine
S
1ððA
DNull
C
CONST(X'ðð')
C\
C\ Get and print the real user id with the getuid function.
C\
C
eval
ReturnInt = getuid
C\
C\ Check for error and report status.
C\
C
if
ReturnInt = -1
C
eval
PrintLine = 'Error getting real user id'
C
exsr
error
C
eval
\INLR = '1'
C
return
C
else
C
move
ReturnInt
User
C
eval
PrintLine = 'The real user id is '
C
+ %TRIML(User)
C
except
C
endif
C\
C\ Get the current working directory and store it in Buffer.
C\
C
eval
ReturnPtr=getcwd(%ADDR(Buffer)
C
: %SIZE(Buffer))
C\
C\ Check for error and report status.
C\
C
if
ReturnPtr = \NULL
C
eval
PrintLine = 'Error getting current directory'
C
exsr
error
C
eval
\INLR = '1'
C
return
C
else
C\
C\ Print current directory name remembering to scan for null terminator.
C\
C
Null
scan
Buffer
NullFound
5 ð
C
eval
InitialDir = %SUBST(Buffer:1:NullFound)
C
eval
PrintLine = 'Current Directory is '
C
+ InitialDir
C
except
C
endif
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

C\
C
C
C
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C
C\
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C\
C\
C\
C\
C
C
C
C
C
C
C
C
C

eval
eval

FileName = %TRIMR(test_file) + Null
FileDesc = open(%ADDR(FileName)
: x'ðððððð1A' : x'ððððð1Cð')

Check for error and report status.
if
eval
exsr
eval
return
else
eval

FileDesc = -1
PrintLine = 'Could not create file'
error
\INLR = '1'

PrintLine = 'File '
+ %TRIMR(test_file)
+ ' created successfully'

except
end
Write test_data to test_file via FileDesc returned by open
eval

BytesWrt = write(FileDesc
: %ADDR(Test_Data)
: %SIZE(Test_Data))

Check for error and report status.
attempt cleanup.
if
eval
exsr
eval
eval
eval
return
else
eval

If an error occurs,

BytesWrt = -1
PrintLine = 'Could not write to file'
error
ReturnInt = close(FileDesc)
ReturnInt = unlink(%ADDR(FileName))
\INLR = '1'

PrintLine = 'Wrote to '
+ %TRIMR(test_file)
+ ' successfully'

except
endif
Close test_file via FileDesc
eval

ReturnInt = close(FileDesc)

Check for error and report status.
attempt cleanup.
if
eval
exsr
eval
eval
eval
return
else
eval

If an error occurs,

ReturnInt =
PrintLine =
error
ReturnInt =
ReturnInt =
\INLR = '1'

-1
'Could not close file'
close(FileDesc)
unlink(%ADDR(FileName))

PrintLine = 'File '

Appendix B. Original Examples in Additional Languages

B-185

C
C
C
C
C\
C\
C\
C
C
C\
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C\
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C\
C\
C\
C\
C
C

B-186

+ %TRIMR(test_file)
+ ' closed successfully'
except
endif
Open the file for read only
eval

FileDesc = open2(%ADDR(FileName)
: x'ððððððð1')

Check for error and report status.
attempt cleanup.

If an error occurs,

if
eval
exsr
eval
eval
return
else
eval
except
endif

FileDesc = -1
PrintLine = 'Open of file failed'
error
ReturnInt = unlink(%ADDR(FileName))
\INLR = '1'

eval

BytesRead = read(FileDesc
: %ADDR(Buffer) : %SIZE(Buffer))

PrintLine = 'Open of file successful'

Read from file

Check for error and report status.
attempt cleanup.
if
eval
exsr
eval
eval
eval
return
else
if
eval
else
eval
endif
except
endif

If an error occurs,

BytesRead =
PrintLine =
error
ReturnInt =
ReturnInt =
\INLR = '1'

-1
'Read failed'
close(FileDesc)
unlink(%ADDR(FileName))

BytesRead = BytesWrt
PrintLine = 'Data successfully read: '
+ %TRIMR(Buffer)
PrintLine = 'Data truncation on read'

Close the LinkName file
eval

ReturnInt = close(FileDesc)

Check for error and report status.
attempt cleanup.

System API Programming V4R1

if
eval

If an error occurs,

ReturnInt = -1
PrintLine = 'Close of link failed'

C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C\
C\
C\
C\
C
C
C
C
C
C
C
C
C
C
C\
C\
C\
C
C
C
C
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C\
C
C
C\

exsr
eval
eval
eval
return
else
eval
except
endif

error
ReturnInt = close(FileDesc)
ReturnInt = unlink(%ADDR(FileName))
\INLR = '1'

eval

ReturnInt = unlink(%ADDR(FileName))

PrintLine = 'Close of link successful'

Unlink test_file

Check for error and report status.
attempt cleanup.
if
eval
exsr
eval
eval
return
else
eval
except
endif

If an error occurs,

ReturnInt = -1
PrintLine = 'Unlink of file failed'
error
ReturnInt = unlink(%ADDR(FileName))
\INLR = '1'

PrintLine = 'Unlink of file successful'

End of main program
eval
except
eval
return

PrintLine = 'Program run is successful'
\INLR = '1'

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 RPG 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 RPG application.
#include
int geterrno()
{
return errno;
}
To activate this C module, remove the four comment identifiers
following the 'except' statement and remove the comment identifier
from the errno prototype. Definitions for the returned errno
are found in the file QSYSINC/SYS member ERRNO.
error

begsr
except
eval

ReturnInt = errno

Appendix B. Original Examples in Additional Languages

B-187

C\
C\
C\
C
C
C
OQSYSPRT
O

B-188

System API Programming V4R1

move
eval
except
eval
except
endsr

ReturnInt
Errnoval
9
PrintLine = 'Errno is ' + Errnoval
PrintLine = 'Program ended in error'

1
PrintLine

1ðð

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 relevant to specific types of applications. The books are
grouped in these categories:
General-purpose books
OS/400 API books
Programming language books
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.

Security – Reference, SC41-5302, provides technical information about OS/400 security.
System Manager Use, SC41-5321, provides information about the commands and functions available
when the System Manager for AS/400 licensed
program is installed on one or more AS/400
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.

OS/400 API Books
General-Purpose Books
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 programming.
CL Reference, SC41-5722, provides a description of
the AS/400 control language (CL) and its commands. Each command description includes a
syntax diagram, parameters, default values,
keywords, and an example.
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.
ILE Concepts, SC41-5606, describes the concepts
and terminology of the Integrated Language Environment 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 programming 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.
Guide to Enabling C2 Security, SC41-0103, provides information about planning, installing, setting
up, and managing your AS/400 system to meet the
requirements for C2 security. C2 is a level of security defined by the United States Department of
Defense.

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.
CPI Communications Reference, SC26-4399, provides 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 provides a programming interface that allows programto-program communications using IBM’s Systems
Network Architecture (SNA) logical unit 6.2 (LU6.2).
DB2 for AS/400 Query Management Programming,
SC41-5703, provides information on how to determine 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.
GDDM Programming Guide, SC41-0536, provides
information about using OS/400 graphical data
display manager (GDDM) to write graphics application programs.
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

H-1

Bibliography

print descriptors used by the PrintManager interface.
REXX/400 Programmer’s Guide, SC41-5728,
explains REXX/400 programming concepts and discusses 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, function syntax, numerics, arithmetic, conditions, input
and output streams, testing, and double-byte character set (DBCS) support. The book also describes
REXX APIs.
Sockets Programming, SC41-5422, describes the
sockets programming functions available on AS/400
systems and provides reference information on the
sockets programming interface.
System API Reference, SC41-5801, describes
OS/400 APIs. It is intended for experienced application programmers who are developing systemlevel 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.

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 maintain COBOL programs on the AS/400 system.
ILE C/400 Programmer’s Guide, SC09-2069, provides 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 performance 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.
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.

H-2

System API Programming V4R1

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.
ILE COBOL/400 Reference, SC09-2073, describes
the ILE COBOL programming language. It provides
information on the structure of the ILE COBOL programming language and on the structure of an ILE
COBOL source program. It also describes all Identification Division paragraphs, Environment Division
clauses, Data Division paragraphs, Procedure Division statements, and Compiler-Directing statements.
ILE RPG/400 Programmer’s Guide, SC09-2074, is a
guide for using the ILE RPG programming language, 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 considerations for procedure calls and interlanguage programming. 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 concepts and of the RPG language.
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 functions, and indicators.
RPG/400 Reference, SC09-1817, provides information 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 indicators.
RPG/400 User’s Guide, SC09-1816, provides information needed to write, test, and maintain RPG programs on the AS/400 system. The book provides
information on data organizations, data formats, file
processing, multiple file processing, automatic
report function, RPG command statements, testing

Bibliography

and debugging functions, application design techniques, 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

Bibliography

H-4

System API Programming V4R1

Index

Index
Special Characters
*EXT (external) format type
example A-14
*INT (internal) format type
example A-14

Numerics
5250 pass-through session

8-29

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
ADDENVVAR (Add Environment Variable)
command 8-22
adding
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

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
AFPDS (Advanced Function Printing data stream)
AFP to ASCII Transform (QWPZTAFP) API
use of 8-17
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
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
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
example B-66
ILE C example B-94
ILE COBOL example B-101
ILE RPG example B-106

X-1

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
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
optional parameter group 3-5
parameters 3-2
required parameter group 3-3
Dynamic Screen Manager (DSM) APIs
use of 8-4
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
use of 8-5
format 3-5
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
ILE APIs for the CEE environment 2-5
integrated file system 2-6
examples B-175
Integrated Language Environment (ILE)
error code 4-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
introduction 2-1
list API example
List Objects That Adopt Owner Authority
(QSYLOBJP) 5-12
QSYLOBJP (List Objects That Adopt Owner
Authority) 5-12

X-2

System API Programming V4R1

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
miscellaneous APIs
use of 8-29
name
locating 3-1
national language support (NLS) APIs
use of 8-9
network management APIs
use of 8-9
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-11
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
Operational Assistant APIs
use of 8-17
OptiConnect APIs
use of 8-3
optional parameter group 3-5
original program model (OPM)
error code 3-1
example 3-1
introduction 2-4
Package Product Option (QSZPKGPO)
OPM RPG example A-3
parameters 3-2
performance collector APIs
use of 8-17
print APIs
use of 8-17

Index

API (application programming interface) (continued)
problem management APIs
use of 8-18
process open list APIs
use of 8-29
program and CL command APIs
use of 8-19
Register Exit Point (QusRegisterExitPoint)
ILE C example 4-9
ILE COBOL example B-50
ILE RPG example B-58
Register Exit Point (QUSRGPT)
OPM COBOL example B-47
OPM RPG example B-54
registration facility APIs
use of 8-19
Remove Exit Program (QusRemoveExitProgram)
ILE C example 4-19
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 COBOL example B-122
required parameter group 3-3
Retrieve Exit Information
(QusRetrieveExitInformation)
ILE C example 4-13
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
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
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-20
Set COBOL Error Handler
(QlnSetCobolErrorHandler)
ILE COBOL example B-122

API (application programming interface) (continued)
Set COBOL Error Handler (QLRSETCE)
OPM COBOL example B-112
software product APIs
use of 8-20
types of 1-3
UNIX-type APIs 2-6
use of 8-21
use of 8-1
user interface APIs
use of 8-27
user interface manager APIs
use of 8-27
versus CL commands 1-3
virtual terminal APIs
use of 8-28
work management APIs
use of 8-28
work station support APIs
use of 8-28
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
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
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
example B-66
ILE C example B-94
ILE COBOL example B-101
ILE RPG example B-106

Index

X-3

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
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
optional parameter group 3-5
parameters 3-2
required parameter group 3-3
Dynamic Screen Manager (DSM) APIs
use of 8-4
edit function APIs
use of 8-5
error handling 2-30
error messages 3-5
examples B-1
extracting field from format 3-5
field descriptions 3-5
file APIs
use of 8-5
format 3-5
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
ILE APIs for the CEE environment 2-5
integrated file system 2-6
examples B-175
Integrated Language Environment (ILE)
error code 4-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
introduction 2-1
list API example
List Objects That Adopt Owner Authority
(QSYLOBJP) 5-12
QSYLOBJP (List Objects That Adopt Owner
Authority) 5-12

X-4

System API Programming V4R1

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
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
miscellaneous APIs
use of 8-29
name
locating 3-1
national language support (NLS) APIs
use of 8-9
network management APIs
use of 8-9
network security APIs
NetWare authentication entry APIs 8-20
NetWare connection APIs 8-20
object APIs
data queue APIs 8-12
object APIs 8-14
use of 8-11
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
Operational Assistant APIs
use of 8-17
OptiConnect APIs
use of 8-3
optional parameter group 3-5
original program model (OPM)
error code 3-1
example 3-1
introduction 2-4
Package Product Option (QSZPKGPO)
OPM RPG example A-3
parameter
length 2-17
parameters 3-2
performance 2-31
performance collector APIs
use of 8-17

Index

application programming interface (API) (continued)
print APIs
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
Register Exit Point (QusRegisterExitPoint)
ILE C example 4-9
ILE COBOL example B-50
ILE RPG example B-58
Register Exit Point (QUSRGPT)
OPM COBOL example B-47
OPM RPG example B-54
registration facility APIs
use of 8-19
Remove Exit Program (QusRemoveExitProgram)
ILE C example 4-19
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
ILE COBOL example B-122
ILE RPG example B-126
required parameter group 3-3
Retrieve Exit Information
(QusRetrieveExitInformation)
&cx2x. example 4-13
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
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
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-20

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
types of 1-3
UNIX-type APIs 2-6
use of 8-21
use of 8-1
user interface APIs
use of 8-27
user interface manager APIs
use of 8-27
versus CL commands 1-3
virtual terminal APIs
use of 8-28
work management APIs
use of 8-28
work station support APIs
use of 8-28
APPN (Advanced Peer-to-Peer Networking) topology
information APIs
use of 8-9
array
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
automatic storage 7-36

B
backup and recovery APIs
List Save File (QSRLSAVF) API
use of 8-1
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
use of 8-1
BASIC
data type use 2-3
PRPQ 5799-FPK 2-3

Index

X-5

Index

BASIC language
data type use 2-3, 2-4
beginning
instruction stream 7-22
benefits of using APIs 1-2
bibliography H-1
binary data
programming language use of 2-3
binding directory
definition 4-1
BLDPART (Build Part) command 8-6
breakpoint
setting
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

C
C language
See ILE C language
C/400 language
See ILE C language
calling
MI CL05 program 7-18
CDRA (Character Data Representation Architecture)
APIs
use of 8-9
Change Configuration Description (QDCCCFGD) API
use of 8-3
Change Environment Variable (CHGENVVAR)
command 8-22
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
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
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

Character Data Representation Architecture (CDRA)
APIs
use of 8-9
CHGENVVAR (Change Environment Variable)
command 8-22
CHGVAR (Change Variable) command 2-3, 2-4
choosing
high-level language to use 2-3
CL (control language)
See also command, CL
data type use 2-3, 2-4
example
receiving error messages 2-10
programming example
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
use of 8-2
Remove Client (QZCARMVC, QzcaRemoveClient)
API
use of 8-2
Update Client Information (QZCAUPDC,
QzcaUpdateClientInfo) API
use of 8-2
use of 8-1
Close List (QGYCLST) API 8-30
COBOL APIs
use of 8-7
COBOL language
data type use 2-3, 2-4
command, CL
Add Environment Variable (ADDENVVAR)
command 8-22
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

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
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
Common Execution Environment (CEE) API,
SAA 2-5
common programming techniques
MI (machine interface) instruction program 7-32
communications APIs
OptiConnect APIs
use of 8-3
use of 8-2
compatibility with future AS/400 releases
application programming interface 1-1
include files 2-28
compiling
program
MI instruction program 7-4
configuration APIs
Change Configuration Description (QDCCCFGD) API
use of 8-3
List Configuration Descriptions (QDCLCFGD) API
use of 8-3
Retrieve Configuration Status (QDCRCFGS) API
use of 8-3
use of 8-3
continuation handle
definition 2-25
example 4-13
using 2-25
control language (CL)
See also command, CL
data type use 2-3, 2-4
example
receiving error messages 2-10
programming example
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
Convert Edit Code (QECCVTEC) API 8-5
use of 8-5

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
Create Product Load (QSZCRTPL) API
OPM RPG example A-3
Create Program (QPRCRTPG) API 7-5
use of 8-19
Create User Space (QUSCRTUS) API
description 2-13
example B-66
listing database file members 2-22
receiving error messages 2-10
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
creating
MI MICRTPG program 7-18
MI version of CLCRTPG program 7-11
product definition
OPM RPG example A-3
product load
OPM RPG example A-3
program
MI instruction program 7-5, 7-6
user space
example B-66
OPM COBOL example B-61
OPM RPG example B-71
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

D
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
ILE COBOL example B-165
ILE RPG example B-172

Index

X-7

Index

data queue (continued)
working with (continued)
OPM COBOL example B-165
OPM RPG example B-169
data queue APIs
advantages 8-12
comparisons with using database files 8-12
similarities to message queues 8-13
use of 8-12
data structure
defining 9-5
processing lists 3-29
programming language use of 2-3
data type
programming language use of 2-3, 2-4
database
error recovery 2-30
database file API
List Database File Members (QUSLMBR)
example 2-22
date
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
program
MI instruction program 7-7
decimal data
programming language use of 2-3
zoned 2-3
declare statements
setting
MI instruction program 7-2
declaring
pointers 7-17
structure for MICRTPG program 7-16
defining
external call 7-17
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
exit point
ILE C example 4-19
ILE COBOL example B-87
ILE RPG example B-92

X-8

System API Programming V4R1

deregistering (continued)
exit point (continued)
OPM COBOL example B-85
OPM RPG example B-90
description
API
authorities and locks 3-2
error messages 3-5
field descriptions 3-5
format 3-5
optional parameter group 3-5
parameters 3-2
required parameter group 3-3
determining
API name 3-1
whether error occurred
example 4-5
diagnosing errors
See error handling
directory
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
Display Job Description (DSPJOBD)
command 3-30
Display Library (DSPLIB) command 8-15
Display Message Description (DSPMSGD)
command 4-6
Display Object Description (DSPOBJD)
command 8-14
Display Programs That Adopt (DSPPGMADP)
command 5-12
displaying
all message data for exception
example 4-6
job description 3-30
program adopt 5-12
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
DSM (Dynamic Screen Manager) APIs
use of 8-4
DSPJOBD (Display Job Description)
command 3-30

Index

DSPLIB (Display Library) command 8-15
DSPMSGD (Display Message Description)
command 4-6
DSPOBJD (Display Object Description)
command 8-14
DSPPGMADP (Display Programs That Adopt)
command 5-12
Dynamic Screen Manager (DSM) APIs
use of 8-4

E
e-mail
AnyMail/400 Mail Server Framework APIs
use of 8-15
Edit (QECEDT) API
use of 8-5
edit code
definition 8-5
Edit Code (EDTCDE) API
use of 8-5
edit function APIs
Convert Edit Code (QECCVTEC) API
use of 8-5
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
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
End Problem Log Services
(QsxEndProblemLogServices) API 8-19
entry point
setting
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
APIs for UNIX environment 2-6
environment variable
definition 8-21
using 8-21

environment variable APIs
getenv()
use of 8-21
putenv()
use of 8-21
Qp0zGetEnv()
use of 8-21
Qp0zPutEnv()
use of 8-21
use of 8-21
error code
description 3-4
error code parameter
handling exceptions 4-5
initializing 4-5
introduction 2-8
optional 2-8
using 9-2
error code structure
example 4-3
format 3-12
introduction 2-8
retrieving hold parameter
RPG example 3-11
error handling
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
error message
CPF3CF1 4-5
CPF9872 4-5
description 3-5
error, common programming
examples
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
incorrectly using offsets 9-27
incorrectly using the error code parameter 9-2
table of examples 9-1
escape (*ESCAPE) message
See error handling

Index

X-9

Index

example
accessing field value in variable-length array 3-19
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
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
program for packaging product, ILE C B-129
program for packaging product, ILE
COBOL B-136
program for packaging product, ILE RPG B-144
program for packaging product, OPM
COBOL B-136
retrieving file description to user space B-152,
B-155
retrieving file description to user space, ILE
COBOL B-152
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
user space 2-20, 2-21
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
OPM RPG B-71
data description specifications (DDS) format
type A-14
data queue
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
Deregister Exit Point (QUSDRGPT) API
OPM COBOL B-85
OPM RPG B-90
differences chapter
logging software error (OPM API without
Pointers), ILE C 6-2

X-10

System API Programming V4R1

example (continued)
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
reporting software error (ILE API with pointers),
ILE COBOL B-122
reporting software error (ILE API with pointers),
ILE RPG B-126
Set COBOL Error Handler
(QlnSetCobolErrorHandler) API B-122
setting COBOL error handler, OPM
COBOL B-112
error code parameter 9-2
error code structure 3-11
exit program 4-9
external (*EXT) format type A-14
handling errors as escape messages 3-8
header file
error code structure 4-3
how to use 4-2
variable-length structure 4-3
ILE chapter
Add Exit Program (QUSADDEP) API, OPM
COBOL B-47
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
Create User Space (QUSCRTUS) API, OPM
COBOL B-61
Create User Space (QUSCRTUS) API, OPM
RPG B-71
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
Register Exit Point (QusRegisterExitPoint) API,
ILE COBOL B-50
Register Exit Point (QusRegisterExitPoint) API,
ILE RPG B-58
Register Exit Point (QUSRGPT) API, OPM
COBOL B-47
Register Exit Point (QUSRGPT) API, OPM
RPG B-54

Index

example (continued)
ILE chapter (continued)
Remove Exit Program (QusRemoveExitProgram)
API, ILE COBOL B-87
Remove Exit Program (QusRemoveExitProgram)
API, ILE RPG B-92
Remove Exit Program (QUSRMVEP) API, OPM
COBOL B-85
Remove Exit Program (QUSRMVEP) API, OPM
RPG B-90
Retrieve Exit Information
(QusRetrieveExitInformation) API, ILE
COBOL B-66
Retrieve Exit Information
(QusRetrieveExitInformation) API, ILE
RPG B-75
Retrieve Exit Information (QUSRTVEI) API, OPM
COBOL B-61
Retrieve Exit Information (QUSRTVEI) API, OPM
RPG B-71
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
include file 4-2
integrated file system B-175, B-178, B-183
ILE C B-175
ILE COBOL B-178
ILE RPG B-183
internal (*INT) format type A-14
keyed interface
variable-length record 4-3
list API
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
ILE C B-94
ILE COBOL B-101
ILE RPG B-106
OPM COBOL B-101
OPM RPG 5-4
listing
database file members 2-22
logging software error (OPM API without pointers)
ILE C 6-2
ILE RPG B-119
OPM COBOL B-112
OPM RPG B-116
logging software error (QPDLOGER) API, without
pointers
OPM COBOL B-112

example (continued)
machine interface (MI) instruction program
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
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
accessing field value (initial library list), ILE
C B-22
accessing field value (initial library list), ILE
COBOL B-25
accessing field value (initial library list), ILE
RPG B-29
accessing field value (initial library list), OPM
COBOL B-25
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 structure), ILE C B-10
retrieving the hold parameter (error code structure), ILE COBOL B-12
retrieving the hold parameter (error code structure), ILE RPG B-14
retrieving the hold parameter (error code structure), OPM COBOL B-12
retrieving the hold parameter (exception
message), ILE C B-2
retrieving the hold parameter (exception
message), ILE COBOL B-4
retrieving the hold parameter (exception
message), ILE RPG B-6
using keys with List Spooled Files API, ILE
C B-33
using keys with List Spooled Files API, ILE
COBOL B-38

Index

X-11

Index

example (continued)
OPM chapter (continued)
using keys with List Spooled Files API, ILE
RPG B-42
using keys with List Spooled Files API, OPM
COBOL B-38
original program model (OPM) 3-1
Package Product Option (QSZPKGPO) API
OPM RPG A-3
packaging your own software products
CL program for creating objects and library A-2
program for packaging product B-136
ILE C B-129
ILE COBOL B-136
ILE RPG B-144
introduction A-1
OPM COBOL B-136
OPM RPG A-3
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 RPG B-54
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
OPM RPG B-90
repeating entry type
fixed-length fields 4-7
variable-length fields 4-8
variable-length fields using offsets 4-8
reporting software error (ILE API with pointers)
ILE C 6-7
ILE COBOL B-122
ILE RPG B-126
Retrieve Exit Information
(QusRetrieveExitInformation) API
ILE C 4-13
ILE COBOL B-66
ILE RPG B-75
Retrieve Exit Information (QUSRTVEI) API
OPM COBOL B-61

X-12

System API Programming V4R1

example (continued)
Retrieve Exit Information (QUSRTVEI) API (continued)
OPM RPG B-71
Retrieve Pointer to User Space (QUSPTRUS)
API B-66
OPM COBOL B-61
OPM RPG B-71
retrieving
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
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
OPM COBOL B-165
OPM RPG B-169
exception
displaying all message data
example 4-6
handling
MI instruction program 7-9
handling errors as escape messages
RPG example 3-8
retrieving hold parameter
RPG example 3-6
exception (*EXCP) message
See error handling
exit point
definition 2-27, 8-19
registration facility 2-27
exit point provider
responsibilities 2-28
exit program
definition 2-27, 8-19
example using registration facility 4-9
include file 2-29
office
use of 8-16
registration facility 2-27
using 2-27

Index

external format type (*EXT)
example A-14
extracting
field from format 3-5

F
field description
description 3-5
file
See header file
See include file
See source include file
pointer
See pointer
file APIs
commitment control APIs
use of 8-8
journal APIs
use of 8-8
Query (QQQQRY) API
use of 8-5
Retrieve Display File (QDFRTVFD) API
use of 8-5
Retrieve File Override Information (QDMRTVFO) API
use of 8-6
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
definition 8-18
problem management APIs
use of 8-18
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
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
processing lists 3-29

format (continued)
user space 2-14
format JOBD0100
description 3-5
format name
description 3-4
function of APIs, system 1-3
functions
in example program B-175

G
Generate CD-ROM Premastering Information
(QlpGenerateCdPremasteringInfo, QLPCDINF) API
use of 8-21
Get Client Handle (QzcaGetClientHandle) API
use of 8-2
Get List Entry (QGYGTLE) API 8-29
getenv()
use of 8-21
getting started with APIs 2-1

H
handle 2-12
See also continuation handle
Handle CD-ROM Premastering State
(QlpHandleCdState, QLPCDRST) API
use of 8-21
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
See also include file
ILE example 4-2
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
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
high-level language (HLL) APIs
Application Development Manager APIs
use of 8-6

Index

8-17

X-13

Index

high-level language (HLL) APIs (continued)
COBOL APIs
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

I
ILE (Integrated Language Environment) APIs
binding directory 4-1
CEE environment
introduction 2-5
example 4-1
example using registration facility 4-9
introduction 2-5, 4-1
registration facility using 4-2
ILE (Integrated Language Environment) CEE APIs
naming conventions 8-7
use of 8-7
ILE C example
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
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
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
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

X-14

System API Programming V4R1

ILE COBOL example (continued)
report software error (ILE API with pointers) B-122
Retrieve Exit Information
(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
data type use 2-3, 2-4
ILE RPG example
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
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
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
using integrated file system B-183
working with data queues B-172
ILE RPG language
data type use 2-3, 2-4
example
changing user space 2-20
include file
See also header file
exit program 2-29
ILE example 4-2
QSYSINC library 2-28
initializing
error code parameter 4-5
input parameter 2-8
input/output parameter 2-8

Index

instruction stream
beginning 7-22
starting
MI instruction program 7-3
integrated file system
examples
ILE C B-175
ILE COBOL B-178
ILE RPG B-183
integrated file system APIs
UNIX environment 2-6
use of 8-22
Integrated Language Environment (ILE) APIs
binding directory 4-1
CEE environment
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
internal format type (*INT)
example A-14
internal identifier 2-12
internal job identifier 2-12
internal spooled file identifier 2-12
interprocess communications (IPC) APIs
msgget()
use of 8-23
semget()
use of 8-23
shmget()
use of 8-23
use of 8-22
IPC (interprocess communications) APIs
msgget()
use of 8-23
semget()
use of 8-23
shmget()
use of 8-23
use of 8-22

J
job
log 2-10
synchronizing 2-16
job API
List Objects That Adopt Owner Authority
(QSYLOBJP)
list format 5-14
Retrieve Job Description Information
(QWDRJOBD) 3-29

job description
displaying 3-30
job description API
Retrieve Job Description Information
(QWDRJOBD) 3-29
job description name, qualified
description 3-4
journal APIs
commitment control APIs
use of 8-8
use of 8-8

K
key 2-24
keyboard buffering
definition 8-28
keyed interface
definition 2-24
variable-length record
example 4-3
kill()
use of 8-24

2-24

L
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
library
See also QSYSINC (system include) library
optionally installed
QSYSINC (system include) 2-28
QSYSINC (system include)
member name 2-28
QUSRTOOL 2-30
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)
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

Index

X-15

Index

list API (continued)
using user space 2-13
list API example
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
list entry format lengths, defining 9-14
list format
See format
See list API
List Objects (QUSLOBJ) API 8-14
List Objects That Adopt Owner Authority
(QSYLOBJP) 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) API—example 5-12
list of entries
processing 3-29
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
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

X-16

System API Programming V4R1

Log Software Error (QPDLOGER) API (continued)
without pointers
ILE C example 6-2
ILE RPG example B-119
OPM COBOL example B-112
OPM RPG example B-116
logging
message
for error diagnosis and recovery 2-10
software error (ILE API with pointers)
ILE C example 6-7
ILE COBOL example B-122
ILE RPG example B-126
software error (OPM API without pointers)
ILE C example 6-2
ILE RPG example B-119
OPM COBOL example B-112
OPM RPG example B-116

M
machine interface (MI) instruction
See also machine interface (MI) instruction program
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
machine interface (MI) instruction program
See also machine interface (MI) instruction
data type use 2-3, 2-4
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
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

Index

mail server framework (continued)
SNADS File Server APIs
use of 8-16
message
See also error handling
See also user queue
CPF3CF1 4-5
CPF9872 4-5
logging
for error diagnosis and recovery 2-10
message data
displaying for exception
example 4-6
message handling
message key 2-12
message handling APIs
Open List of Job Log Messages (QGYOLJBL) API
use of 8-29
Open List of Messages (QGYOLMSG) API
use of 8-29
use of 8-8
message key 2-12
message queue
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
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
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

miscellaneous APIs
Convert Date and Time Format (QWCCVTDT) API
use of 8-29
process open list APIs
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
Get List Entry (QGYGTLE) API 8-29
use of 8-29
Remove All Bookmarks from a Course
(QEARMVBM) API
use of 8-29
Retrieve Data (QPARTVDA) API
use of 8-29
Start Pass-Through (QPASTRPT) API
use of 8-29
use of 8-29
modifying
See changing
moving
through returned information 2-23
msgget()
use of 8-23
multiple entries
processing list of
logic flow 2-15

N
name
locating API 3-1
national language data conversion APIs
use of 8-9
national language support (NLS) APIs
Character Data Representation Architecture (CDRA)
APIs
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
node list APIs
use of 8-11

Index

X-17

Index

network management (continued)
registered filter APIs
use of 8-11
SNA/Management Services Transport (SNA/MS
Transport) APIs
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
use of 8-9
national language data conversion APIs
use of 8-9
use of 8-9
node list
definition 8-11
node list APIs
use of 8-11
null pointers, using 9-18

O
object
See also user space
allocating 2-16
deallocating 2-16
lock 2-16
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
advantages 8-12
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
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
use of 8-13
user space APIs
use of 8-14

X-18

System API Programming V4R1

object type
domain 2-26
office APIs
AnyMail/400 Mail Server Framework APIs
use of 8-15
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
office exit program
Directory Search exit program
use of 8-16
Directory Supplier exit program
use of 8-16
Directory Verification exit program
use of 8-16
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
offset 2-23
incorrectly using 9-27
locating field in receiver variable 3-5
offset value
definition 2-17
used with pointer data 2-16
used without pointer data 2-17
open list APIs
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
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
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
Operational Assistant backup APIs
use of 8-1

Index

Operational Assistant exit program
use of 8-17
operations
example program B-175
OPM (original program model)
API
null pointer 9-18
example 3-1
introduction 2-4
OPM COBOL example
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
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
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
logging software error (OPM API without
pointers) B-116
Package Product Option (QSZPKGPO) API A-3
packaging your own software products A-3
introduction A-1
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
working with data queues B-169

OptiConnect APIs
use of 8-3
optional parameter group
description 3-5
original program model (OPM)
API
null pointer 9-18
example 3-1
introduction 2-4
OS/400 signal management 8-24
output
See list API
output parameter 2-8

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
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
PRPQ 5799-FRJ 2-3
Pascal language
data type use 2-3, 2-4
passing parameters
by reference 2-7
by value directly 2-7
by value indirectly 2-7
to procedures 2-7
performance collector APIs
use of 8-17
performing
tasks using APIs
packaging your own software products, CL
program example A-2

Index

X-19

Index

performing (continued)
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
packaging your own software products, introduction A-1
packaging your own software products, OPM
COBOL B-136
packaging your own software products, OPM
RPG A-3
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
PRPQ 5799-FPJ 2-3
PL/I language
data type use 2-3, 2-4
pointer
manipulating user spaces with 2-16
manipulating user spaces without 2-17
programming language use of 2-3
restoring 8-14
using offset values with 2-16
position values 2-17
PostScript data stream
AFP to ASCII Transform (QWPZTAFP) API 8-17
print APIs
Host Print Transform (QWPZHPTR) API 8-17
Open List of Printers (QGYRPRTL) API
use of 8-29
print APIs
AFP to ASCII Transform (QWPZTAFP) API 8-17
use of 8-17
Print Driver exit program 8-18
spooled file APIs
Open List of Spooled Files (QGYOLSPL)
API 8-29
use of 8-18
use of 8-17
Print Driver exit program 8-18
problem management APIs
Add Problem Log Entry (QsxAddProblemLogEntry)
API
use of 8-19
Change Problem Log Entry
(QsxChangeProblemLogEntry) API
use of 8-19
Create Problem Log Entry
(QsxCreateProblemLogEntry) API
use of 8-19
Delete Problem Log Entry
(QsxDeleteProblemLogEntry) API

X-20

System API Programming V4R1

problem management APIs (continued)
Delete Problem Log Entry
(QsxDeleteProblemLogEntry) API (continued)
use of 8-19
End Problem Log Services
(QsxEndProblemLogServices) API
use of 8-19
error reporting APIs
use of 8-19
filtering 8-18
Log Software Error (QPDLOGER) API
use of 8-19
problem log entry APIs
use of 8-19
Report Software Error (QpdReportSoftwareError) API
use of 8-19
Retrieve Problem Log Entry
(QsxRetrieveProblemLogEntry) API
use of 8-19
Start Problem Log Services
(QsxStartProblemLogServices) API
use of 8-19
use of 8-18
Work with Problem (QPDWRKPB) API
use of 8-19
procedural language
data type use
REXX 2-3, 2-4
procedure
passing parameters to 2-7
process group
definition 8-25
process open list APIs
Close List (QGYCLST) API
use of 8-30
Find Entry Number in List (QGYFNDE) API
use of 8-30
Find Entry Number in Message List (QGYFNDME)
API
use of 8-30
Find Field Numbers in List (QGYFNDF) API
use of 8-30
Get List Entry (QGYGTLE) API
use of 8-29
use of 8-29
process-related APIs
use of 8-27
processing
list of entries
logic flow 2-15
lists
data structures 3-29
processing time 2-31
program
See also example
See also programming language

Index

program (continued)
compiling
MI instruction program 7-4
creating
MI instruction program 7-5, 7-6
creating MI MICRTPG2 program 7-27
debugging
MI instruction program 7-7
MI MICRTPG2 complete program (enhanced)
example 7-28
MI MICRTPG2 complete program example 7-23
program activation 7-36
program adopt
displaying 5-12
program and CL command APIs
Create Program (QPRCRTPG) API
use of 8-19
use of 8-19
program invocation 7-36
program storage
MI (machine interface) instruction program 7-36
programming error, common
examples
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
incorrectly using offsets 9-27
incorrectly using the error code parameter 9-2
table of examples 9-1
programming language
control language (CL)
example (listing database file members) 2-22
example (receiving error messages) 2-10
Cross System Product (CSP) 2-3, 2-4
data type use
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
machine interface (MI) instructions 2-4
Pascal 2-4
PL/I 2-4
REXX 2-4
RPG 2-4
VisualAge C++ for OS/400 2-4
ILE C example
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

programming language (continued)
ILE C example (continued)
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
retrieving the hold parameter (exception
message) B-2
using integrated file system B-175
using keys with List Spooled Files API B-33
ILE COBOL 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
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
Retrieve Exit Information
(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 RPG example
accessing field value (initial library list) B-29
accessing the hold attribute B-21
Add Exit Program (QusAddExitProgram)
API B-58
changing user space 2-20
Deregister Exit Point (QusDeregisterExitPoint)
API B-92
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
Remove Exit Program (QusRemoveExitProgram)
API B-92

Index

X-21

Index

programming language (continued)
ILE RPG example (continued)
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 structure) B-14
retrieving the hold parameter (exception
message) B-6
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
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 structure) B-12
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 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

X-22

System API Programming V4R1

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
working with data queues B-169
packaging your own software products
creating objects and library, CL example A-2
parameter passing 2-8
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
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
ILE COBOL example B-122

Index

QLPCDINF (Generate CD-ROM Premastering Information) API
use of 8-21
QLPCDRST (Handle CD-ROM Premastering State)
API
use of 8-21
QlpGenerateCdPremasteringInfo (Generate CD-ROM
Premastering Information) API
use of 8-21
QlpHandleCdState (Handle CD-ROM Premastering
State) API
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
QOKSCHD (Search System Directory) API 8-15
Qp0sEnableSignals()
use of 8-24
Qp0zGetEnv()
use of 8-21
Qp0zPutEnv()
use of 8-21
QPARTVDA (Retrieve Data) API 8-29
QPASTRPT (Start Pass-Through) API 8-29
QPDLOGER (Log Software Error) API 8-19
without pointers
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
with pointers
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
QQQQRY (Query) API
use of 8-5
QsxAddProblemLogEntry (Add Problem Log Entry)
API 8-19
QsxChangeProblemLogEntry (Change Problem Log
Entry) API 8-19
QsxCreateProblemLogEntry (Create Problem Log
Entry) API 8-19
QsxDeleteProblemLogEntry (Delete Problem Log
Entry) API 8-19
QsxEndProblemLogServices (End Problem Log Services) API 8-19
QsxRetrieveProblemLogEntry (Retrieve Problem
Log Entry) API 8-19

QsxStartProblemLogServices (Start Problem Log
Services) API 8-19
QSYLOBJP (List Objects That Adopt Owner
Authority) 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
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
QSZCRTPD (Create Product Definition) API
OPM RPG example A-3
QSZCRTPL (Create Product Load) API
OPM RPG example A-3
QSZPKGPO (Package Product Option) API
OPM RPG example A-3
qualified job description name
description 3-4
Query (QQQQRY) API
use of 8-5
querying
See list API
qus.h header file 4-4
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
ILE COBOL example B-50
ILE RPG example B-58
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
example B-66
listing database file members 2-22
receiving error messages 2-10
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
QusDeregisterExitPoint (Deregister Exit Point) API
ILE C example 4-19
ILE COBOL example B-87
ILE RPG example B-92

Index

X-23

Index

QUSDRGPT (Deregister Exit Point) API
OPM COBOL example B-85
OPM RPG example B-90
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
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
QusRegisterExitPoint (Register Exit Point) API
ILE C example 4-9
ILE COBOL example B-50
ILE RPG example B-58
QusRemoveExitProgram (Remove Exit Program) API
example 4-19
ILE COBOL example B-87
ILE RPG example B-92
QusRetrieveExitInformation (Retrieve Exit Information) API
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
QUSROBJD (Retrieve Object Description) API 8-15
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
QUSRTOOL library 2-30
QUSRTVEI (Retrieve Exit Information) API
OPM COBOL example B-61
OPM RPG example B-71
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
QWPZTAFP (AFP to ASCII Transform) API
use of 8-17

X-24

System API Programming V4R1

QZCAADDC (Add Client) API
use of 8-2
QzcaAddClient (Add Client) API
use of 8-2
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
QzcaRemoveClient (Remove Client) API
use of 8-2
QZCARMVC (Remove Client) API
use of 8-2
QzcaUpdateClientInfo (Update Client Information)
API
use of 8-2
QZCAUPDC (Update Client Information) API
use of 8-2

R
raise()
use of 8-24
receiver variable
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
repeating entry type with variable-length fields
example using offsets 4-8
retrieve API 2-23
receiving
See list API
recovery considerations
See error handling
Refresh Client (QZCAREFC, QzcaRefreshClientInfo)
API
use of 8-2
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
registering
exit point
ILE C example 4-9
ILE COBOL example B-50
ILE RPG example B-58

Index

registering (continued)
exit point (continued)
OPM COBOL example B-47
OPM RPG example B-54
registration facility
description 2-27
registration facility APIs 2-27
using ILE APIs
concepts 4-2
examples 4-9
registration facility APIs 2-27
use of 8-19
registration facility repository 8-19
service programs 4-2
related printed information H-1
Remove All Bookmarks from a Course
(QEARMVBM) API 8-29
Remove Client (QZCARMVC, QzcaRemoveClient)
API
use of 8-2
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
exit program
example 4-19
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
fixed-length fields
example 4-7
variable-length fields
example 4-8
offsets example 4-8
Report Software Error (QpdReportSoftwareError)
API 8-19
with pointers B-122
ILE C example 6-7
ILE COBOL example B-122
ILE RPG example B-126
reporting
software error (ILE API with pointers)
ILE C example 6-7
ILE COBOL example B-122
ILE RPG example B-126
software error (OPM API without pointers)
ILE C example 6-2
ILE RPG example B-119
OPM COBOL example B-112
OPM RPG example B-116

required parameter group
description 3-3
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
definition 8-6
restoring
pointer to user space 8-14
user index 8-14
user queue 8-13
user space 8-14
retrieve API
continuation handle 2-25
user space example A-11
using receiver variable 2-23
using user space 2-25
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
(QusRetrieveExitInformation) API
ILE C example 4-13
ILE COBOL example B-66
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
Retrieve Job Description Information (QWDRJOBD)
API—example 3-29
Retrieve Library Description (QLIRLIBD) API 8-15
Retrieve Object Description (QUSROBJD) API 8-15
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
Retrieve Object Description (RTVOBJD)
command 8-15
Retrieve Pointer to User Space (QUSPTRUS) API
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 Problem Log Entry
(QsxRetrieveProblemLogEntry) API 8-19

Index

X-25

Index

Retrieve User Space (QUSRTVUS) API 2-13
used with pointer data 2-16
used without pointer data 2-17
retrieving
See also list API
exit information
ILE C example 4-13
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
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
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
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
data type use 2-3, 2-4
example
changing user space 2-21

X-26

System API Programming V4R1

RTVOBJD (Retrieve Object Description)
command 8-15

S
SAA Common Execution Environment (CEE)
API 2-5
Save Object List (QSRSAVO) API
use of 8-1
saving
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
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
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
definition 8-24
signal action vector
definition 8-24
signal APIs
kill()
use of 8-24

Index

signal APIs (continued)
OS/400 signal management 8-24
Qp0sEnableSignals()
use of 8-24
raise()
use of 8-24
use of 8-23
signal controls
definition 8-24
signal default action
definition 8-24
signal monitor
definition 8-24
Simple Network Management Protocol (SNMP) APIs
SNMP manager APIs
use of 8-25
SNMP subagent APIs
use of 8-25
use of 8-25
size
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
SNMP (Simple Network Management Protocol) APIs
SNMP manager APIs
use of 8-25
SNMP subagent APIs
use of 8-25
use of 8-25
sockets APIs
datagrams 8-26
raw sockets 8-26
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
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

software product APIs (continued)
Generate CD-ROM Premastering Information
(QlpGenerateCdPremasteringInfo, QLPCDINF) API
(continued)
use of 8-21
Handle CD-ROM Premastering State
(QlpHandleCdState, QLPCDRST) API
use of 8-21
use of 8-20
source include file
QSYSINC library 2-28
space
See also user space
locking 2-16
spooled file APIs
Open List of Spooled Files (QGYOLSPL) API
use of 8-29
use of 8-18
spooling
internal spooled file identifier 2-12
Start Pass-Through (QPASTRPT) API 8-29
Start Problem Log Services
(QsxStartProblemLogServices) API 8-19
starting
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
system
index 2-30
performance 2-31
system domain
object types 2-26
system function of APIs 1-3
system include (QSYSINC) library
description 2-28
example of header file 4-2
member name 2-28
Systems Network Architecture Management Services Transport APIs
use of 8-10

T
tasks using APIs
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

Index

tasks using APIs (continued)
packaging your own software products (continued)
OPM RPG A-3
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
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
definition 8-28

U
understanding
API description 3-2
authorities and locks 3-2
error messages 3-5
field descriptions 3-5
format 3-5
optional parameter group 3-5
parameters 3-2
required parameter group 3-3
MI MICRTPG2 program 7-18
MICRTPG program 7-16
UNIX-type APIs
environment variable APIs
use of 8-21
examples B-175
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
UNIX-type environment
APIs for 2-6
UNLOCK (Unlock Object) MI instruction 2-16

X-28

System API Programming V4R1

Unlock Object (UNLOCK) MI instruction 2-16
Unlock Space Location (UNLOCKSL) MI
instruction 2-16
UNLOCKSL (Unlock Space Location) MI
instruction 2-16
Update Client Information (QZCAUPDC,
QzcaUpdateClientInfo) API
use of 8-2
updating
See changing
User Application Administration exit program 8-16
user domain
object types 2-26
user index
definition 8-13
error recovery 2-30
saving and restoring 8-14
user index APIs
use of 8-13
user index considerations 2-30
user interface APIs
use of 8-27
user interface manager APIs
DDS advantages over UIM 8-28
UIM advantages over DDS 8-27
use of 8-27
user queue
definition 8-13
ILE C example A-15
saving and restoring 8-13
user queue APIs
use of 8-13
user space
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
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
usage information 2-16
user space APIs
Change User Space (QUSCHGUS)
effect on user space 2-17
example 2-20, 2-21

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
using
data queues versus user queues
ILE C example A-15
exit programs 2-27
integrated file system
examples B-175
ILE C example B-175
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
examples B-175
ILE C example B-175
ILE COBOL example B-178
ILE RPG example B-183

V
variable
changing 2-3, 2-4
variable-length record
definition 2-24
variable-length structure
example 4-3
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

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
ILE COBOL example B-165
ILE RPG example B-172
OPM COBOL example B-165
OPM RPG example B-169
writing
machine interface (MI) program
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 (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
starting instruction stream 7-3
WRKFTRACNE (Work with Filter Action Entry)
command 8-11
WRKREGINF (Work with Registration Information)
command 2-27

Z
zoned decimal data

2-3

W
work management
internal job identifier 2-12
original program model (OPM) example
work management APIs
Retrieve Job Description Information
(QWDRJOBD) 3-29

3-1

Index

X-29

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
Satisfied

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
THANK

YOU!

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

Company or Organization

Phone No.

Address

Dissatisfied

Very
Dissatisfied

Reader Comments—We'd Like to Hear from You!
SC41-5800-00

Fold and Tape

IBM

Please do not staple

Cut or Fold
Along Line



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

SC41-5800-00

Please do not staple

Fold and Tape

Cut or Fold
Along Line

IBM



Printed in the United States of America
on recycled paper containing 10%
recovered post-consumer fiber.

SC41-58ðð-ðð

Spine information:

IBM

AS/400 Advanced Series

System API Programming

Version 4

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.1
Linearized                      : No
Page Count                      : 505
Create Date                     : 1997:08:13 11:41:37
Producer                        : Acrobat Distiller 3.0 for Windows
Creator                         : SCRIPT/VS 4.0.0: DEVICE PSA CHARS PSFTR
Title                           : RZABPMST

EXIF Metadata provided by EXIF.tools

IBM Version 4 RZABPMST User Manual To The B175aa40 2073 490d 99cc 71e55a67baee

Navigation menu

Versions of this User Manual:

Views

Navigation