IBM

IBM i
Programming
API overview and concepts
7.1
IBM

IBM i
Programming
API overview and concepts
7.1
 Note
Before using this information and the product it supports, read the information in Notices, on
page 573.

This edition applies to IBM i 7.1 (product number 5770-SS1) and to all subsequent releases and modifications until
otherwise indicated in new editions. This version does not run on all reduced instruction set computer (RISC)
models nor does it run on CISC models.
Copyright IBM Corporation 1998, 2010.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
 Contents
Application programming interfaces . . 1 User spaces and receiver variables . . . . . . 67
APIs overview . . . . . . . . . . . . . . 1 User spaces . . . . . . . . . . . . 67
| What's new for IBM i 7.1 . . . . . . . . . . 3 General data structure . . . . . . . . 68
PDF file for APIs . . . . . . . . . . . . . 4 Common data structure formats . . . . 69
API concepts . . . . . . . . . . . . . . 4 Example: User space format . . . . . . 72
API terminology . . . . . . . . . . . . 5 List sections . . . . . . . . . . . 73
Generic library names . . . . . . . . . . 5 Receiver variables . . . . . . . . . . 73
API naming conventions . . . . . . . . . 6 Bytes available and bytes returned fields 74
Language selection considerations . . . . . . 8 Keyed interface . . . . . . . . . . 75
Types of APIs. . . . . . . . . . . . . 10 User space alternative . . . . . . . . 75
APIs for the program-based environment . . 10 Continuation handle . . . . . . . . . . 76
APIs for the service-program-based List APIs overview . . . . . . . . . . . 76
environment . . . . . . . . . . . . 10 General data structure for list APIs . . . . 76
APIs for the ILE Common Execution User spaces for list APIs . . . . . . . . 79
Environment . . . . . . . . . . . . 12 Logic flow of processing a list of entries . . 80
Differences between program-based APIs and Manipulating a user space with pointers . 81
service-program-based APIs . . . . . . . 12 Manipulating a user space without pointers 82
Example in ILE C: Logging software errors Examples: Changing a user space . . . . 82
(program API without pointers) . . . . 13 Additional information about list APIs and
Example in OPM COBOL: Logging user spaces . . . . . . . . . . . 86
software errors (program API without Example in CL: Listing database file
pointers) . . . . . . . . . . . . 18 members . . . . . . . . . . . . 86
Example in OPM RPG: Logging software Example in OPM RPG: List APIs . . . . . 87
errors (program API without pointers) . . 21 Example in ILE CL: List APIs . . . . . . 94
Example in ILE RPG: Logging software Example in ILE C: List APIs . . . . . . . 98
error (program API without pointers). . . 24 Example in ILE RPG: List APIs . . . . . 104
Example in ILE C: Reporting software Example in ILE COBOL: List APIs . . . . 109
errors (bindable API with pointers) . . . 26 Domains . . . . . . . . . . . . . . 114
Example in ILE COBOL: Reporting Exit programs . . . . . . . . . . . . 114
software errors (bindable API with User index considerations . . . . . . . . 115
pointers) . . . . . . . . . . . . 30 Performance considerations. . . . . . . . 116
Example in ILE RPG: Reporting software APIs and system objects . . . . . . . . . 116
errors (bindable API with pointers) . . . 33 Open list information format . . . . . . . 116
APIs for the UNIX-type environment . . . . 36 Path name format . . . . . . . . . . . 118
Examples: UNIX-type APIs . . . . . . 36 Using APIs . . . . . . . . . . . . . . 120
API information format . . . . . . . . . 47 Examples: Program-based APIs . . . . . . 120
API description . . . . . . . . . . . 47 Example in OPM RPG: Retrieving the HOLD
API format . . . . . . . . . . . . 50 parameter (exception message) . . . . . 121
API field descriptions . . . . . . . . . 51 Example in ILE COBOL: Retrieving the
API error messages . . . . . . . . . . 51 HOLD parameter (exception message) . . . 126
Extracting a field from the format . . . . . 51 Example in ILE C: Retrieving the HOLD
Processing lists that contain data structures . . 52 parameter (exception message) . . . . . 127
API parameters . . . . . . . . . . . . 52 Example in ILE RPG: Retrieving the HOLD
Passing parameters . . . . . . . . . . 53 parameter (exception message) . . . . . 129
Input and output parameters . . . . . . 53 Example in OPM RPG: Retrieving the HOLD
Offset values and lengths . . . . . . . . 54 parameter (error code structure) . . . . . 133
Offset versus displacement considerations for Example in ILE COBOL: Retrieving the
structures . . . . . . . . . . . . . 54 HOLD parameter (error code structure) . . 139
Error code parameter . . . . . . . . . 54 Example in ILE C: Retrieving the HOLD
Error code parameter format . . . . . 55 parameter (error code structure) . . . . . 141
Examples: Receiving error conditions . . . 57 Example in ILE RPG: Retrieving the HOLD
Using the job log to diagnose API errors. . 58 parameter (error code structure) . . . . . 143
Include files and the QSYSINC library . . . . 59 Example in OPM RPG: Printing the HOLD
Internal object types . . . . . . . . . . 62 value . . . . . . . . . . . . . . 145
Data types and APIs . . . . . . . . . . 66 Example in ILE COBOL: Printing the HOLD
Internal identifiers . . . . . . . . . . . 67 value . . . . . . . . . . . . . . 147

Copyright IBM Corp. 1998, 2010 iii

 Example in ILE C: Printing the HOLD value 149 Example in ILE RPG: Packaging a product 260
Example in ILE RPG: Printing the HOLD Examples: Retrieving a file description to a
value . . . . . . . . . . . . . . 151 user space . . . . . . . . . . . . 267
Example in OPM RPG: Accessing a field Example in ILE C: Retrieving a file
value (initial library list) . . . . . . . . 153 description to a user space . . . . . . 267
Example in ILE COBOL: Accessing a field Example in ILE COBOL: Retrieving a file
value (initial library list) . . . . . . . . 158 description to a user space . . . . . . 270
Example in ILE C: Accessing a field value Example in ILE RPG: Retrieving a file
(initial library list) . . . . . . . . . . 162 description to a user space . . . . . . 273
Example in ILE RPG: Accessing a field value Examples: Using data queues or user queues 282
(initial library list) . . . . . . . . . . 165 Considerations for using data queues and
Example in OPM RPG: Using keys with the user queues . . . . . . . . . . . 282
List Spooled Files (QUSLSPL) API . . . . 168 Example in ILE C: Using data queues . . 283
Example in ILE COBOL: Using keys with the Example in ILE COBOL: Using data
List Spooled Files (QUSLSPL) API . . . . 174 queues . . . . . . . . . . . . 285
Example in ILE C: Using keys with the List Example in OPM RPG: Using data queues 288
Spooled Files (QUSLSPL) API . . . . . . 177 Example in ILE RPG: Using data queues 291
Example in ILE RPG: Using keys with the Example in ILE C: Using user queues . . 294
List Spooled Files (QUSLSPL) API . . . . 181 Examples: APIs and exit programs . . . . . . 297
Examples: Service-program-based APIs . . . . 185 Example: Changing an active job . . . . . . 297
Example in ILE C: Registering exit points Example: Changing a job schedule entry . . . 302
and adding exit programs . . . . . . . 186 Example: Creating a batch machine . . . . . 306
Example in OPM COBOL: Registering exit Example: Creating and manipulating a user
points and adding exit programs . . . . . 189 index . . . . . . . . . . . . . . . 309
Example in ILE COBOL: Registering exit Example: Creating your own telephone
points and adding exit programs . . . . . 192 directory . . . . . . . . . . . . . . 314
Example in OPM RPG: Registering exit Example: Defining queries . . . . . . . . 317
points and adding exit programs . . . . . 195 Example: Deleting old spooled files . . . . . 339
Example in ILE RPG: Registering exit points Example: Diagnostic reporting. . . . . . . 354
and adding exit programs . . . . . . . 198 Example: Generating and sending an alert. . . 361
Example in ILE C: Removing exit programs Example: Listing directories . . . . . . . 363
and deregistering exit points . . . . . . 201 Example: Listing subdirectories . . . . . . 369
Example in OPM COBOL: Removing exit Example: Saving to multiple devices. . . . . 373
programs and deregistering exit points . . . 203 Example: Saving and restoring system-level
Example in ILE COBOL: Removing exit environment variables . . . . . . . . . 375
programs and deregistering exit points . . . 205 Examples: Scanning string patterns . . . . . 380
Example in OPM RPG: Removing exit Example: Using a COBOL/400 program to call
programs and deregistering exit points . . . 207 APIs . . . . . . . . . . . . . . . 382
Example in ILE RPG: Removing exit Examples: Using the Control Device
programs and deregistering exit points . . . 209 (QTACTLDV) API . . . . . . . . . . . 385
Example in ILE C: Retrieving exit point and Examples: Processing data queue entries . . . 390
exit program information . . . . . . . 211 Example: Using environment variables . . . . 395
Example in OPM COBOL: Retrieving exit Examples: Using ILE Common Execution
point and exit program information . . . . 216 Environment APIs . . . . . . . . . . . 397
Example in ILE COBOL: Retrieving exit point Example: Using generic terminal APIs . . . . 399
and exit program information . . . . . . 221 Example: Using profile handles . . . . . . 402
Example in OPM RPG: Retrieving exit point Example: Using registration facility APIs . . . 404
and exit program information . . . . . . 225 Example: Using semaphore set and shared
Example in ILE RPG: Retrieving exit point memory functions . . . . . . . . . . . 408
and exit program information . . . . . . 229 Example: Using SNA/Management Services
Performing tasks using APIs . . . . . . . 238 Transport APIs . . . . . . . . . . . . 414
Examples: Packaging your own software Example: Using source debugger APIs . . . . 426
products . . . . . . . . . . . . . 238 Example: Using process-related APIs . . . . 450
Creating the example product . . . . . 238 Example: Using the user-defined
Example in CL: Creating objects for communications programs for file transfer. . . 459
packaging a product . . . . . . . . 239 Example: Working with stream files . . . . . 491
Example in OPM RPG: Packaging a Example: Creating a program temporary fix exit
product . . . . . . . . . . . . 240 program . . . . . . . . . . . . . . 494
Example in ILE C: Packaging a product 247 Example: Creating an exit program for
Example in ILE COBOL: Packaging a Operational Assistant backup . . . . . . . 496
product . . . . . . . . . . . . 253 Machine interface programming . . . . . . . 497

iv IBM i: Programming API overview and concepts

Machine interface instructions . . . . . . . 497 Common API programming errors . . . . . . 529
Example: Writing an MI program. . . . . . 498 Using the error code parameter . . . . . . 530
Compiling an MI program . . . . . . . . 500 Defining data structures . . . . . . . . . 532
Creating an MI version of the CLCRTPG Defining receiver variables . . . . . . . . 535
program . . . . . . . . . . . . . . 507 Defining list-entry format lengths . . . . . 539
Enhanced version of the MICRTPG program 513 Using null pointers with program-based APIs 543
Writing the MICRTPG2 program (by sections Defining byte alignment . . . . . . . . . 546
of code) . . . . . . . . . . . . . 514 Using offsets in a user space . . . . . . . 550
Beginning the instruction stream . . . . . 516 Coding for new functions . . . . . . . . 558
Using static storage to your advantage . . . 517
MI code example: MICRTPG2 complete Appendix. Notices . . . . . . . . . 573
program . . . . . . . . . . . . . 518 Programming interface information . . . . . . 574
Updated CL06 program . . . . . . . . 520 Trademarks . . . . . . . . . . . . . . 575
Creating the MICRTPG2 program . . . . . 521 Terms and conditions. . . . . . . . . . . 575
Example: Common MI programming techniques 525
Program storage . . . . . . . . . . . 529

Contents v
vi IBM i: Programming API overview and concepts
Application programming interfaces
IBM i application programming interfaces (APIs) allow your application program written in a high-level
language to use specific data or functions of the i operating system.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer
information on page 571.

APIs overview
This API information describes most of the IBM i APIs and some APIs for related licensed programs that
run on the i operating system.

Who should use APIs

APIs are intended for experienced application programmers to develop system-level and other IBM i
applications. The API information provides reference only. It is neither an introduction to IBM i nor a
guide to writing IBM i applications.

How the API information is organized

The API information can be found either by the API name through the API finder or by category through
the API categories page.

In the API finder, you can search for APIs by category, by API name, by descriptive name, or by part of
the name. You can also search for new APIs, changed APIs, and exit programs.

The API categories are major functional categories, such as backup and recovery, objects, and work
management. Within the individual categories, the APIs are organized in alphabetical order as follows:
v By the spelled-out name for the program-based APIs, the service-program-based APIs, and the
Integrated Language Environment (ILE) Common Execution Environment (CEE) APIs.
v By the function name for the UNIX-type APIs.

Compatibility with future releases

IBM intends that the APIs will continue to work as they originally worked, and any existing applications
that use the APIs will continue to work without any incompatible changes. Significant architectural
changes, however, might necessitate incompatible changes.

Additionally, some API definitions, such as the UNIX type of API definitions, are established by industry
standards organizations, where the degree of compatibility is determined by the organizations.

In future releases, IBM also intends that one of the following statements is true:
v If additional input or output parameters are provided for any of the APIs, the new parameters will be
placed after the current parameters and will be optional parameters. The existing APIs will continue to
work without any changes.
v If an additional data structure is provided, a new format (layout of that data structure) will be created.
v New information might be added to the end of an existing format.

To ensure better compatibility with future releases, retrieve and use all of the following values when you
work with user spaces that are generated by list APIs:

Copyright IBM Corp. 1998, 2010 1

v Offset values to the list data section
v Size of the list data section
v Number of list entries
v Size of each entry

System APIs or CL commands--when to use each

An API is designed to be used as a programming interface, and a CL command is intended to be entered

either interactively or in a CL program.

Before system APIs were offered on the system, 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 system 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 system.

APIs are not provided as a replacement for CL commands, although in many cases there might 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.

Some APIs have no equivalent CL commands. These APIs have been provided in areas where customers
and business partners have indicated that they need high-level language (HLL) access.

Actions and system functions of APIs

An API can be categorized by the type of action it performs and by the system function that it relates to.

Listed here are some of the types of APIs that perform actions; several examples of these APIs are
discussed in more detail in later topics.
v List APIs, which return lists of information about something on the system.
v Retrieve APIs, which return information to the application program.
v Create, change, and delete APIs, which work with objects of a specified type on the system.
v Other APIs, which perform a variety of actions on the system.

Although many APIs are used alone, some APIs can be used together to perform tasks or functions as in
these examples:
v Defining, creating, distributing, and maintaining your own software products.
v Controlling systems and networks, which includes configuration, spooled files, network management,
and problem management.
v Handling objects, which includes creating, changing, copying, deleting, moving, and renaming objects
on the system.
Related reference:
Examples: Using data queues or user queues on page 282
Both data queues and user queues provide a means for one or more processes to communicate
asynchronously. Both queues can be processed by first-in first-out (FIFO), last-in first-out (LIFO), or by
key.

2 IBM i: Programming API overview and concepts

| What's new for IBM i 7.1
| Read about new or significantly changed information for the Application programming interfaces topic
| collection.

| You can find a list of new APIs or changed APIs for this release using the API finder.

| In addition, the following categories of APIs have been enhanced this release.
| v PowerHA for i APIs
| A sub-category of PowerHA for i APIs has been added in the Cluster category.
| v Sockets-related User Exit Programs
| A new subcategory of exit programs has been added in the Unix-type category, Sockets sub-category.

| What's new as of October 2015

| Miscellaneous technical updates have been made to several APIs.

| What's new as of February 2013

| Several APIs have been updated to support new SSL protocols and cipher suites.

| GSKit API updates have been made to support several new security attributes.

| Miscellaneous minor technical updates were also made to a few APIs.

| What's new as of October 2012

| The new Change Processor Multitasking Information (QWCCHGPR) and Retrieve Processor Multitasking
| Information (QWCRTVPR) APIs have been added to the Work Management category.

| Miscellaneous minor technical updates were also made to a few APIs.

| What's new as of 24 April 2012

| The new Suspend System Exit Programs and the Resume System Exit Programs exit points for partition
| migration and hibernation have been added to the Work Management category.

| The Command Analyzer Retrieve Exit Program added a new "Before or after indicator" to specify when
| an exit program should be called (either before or after the command processing program has run.)

| Miscellaneous technical updates were made to a number of other APIs.

| What's new as of 12 October 2011

| The new Compress Files and Directories and the Decompress Files and Directories APIs have been added
| to the UNIX-Type category under the Integrated File System APIs sub-category.

| The new Configure Activation Engine API was added to the Configuration category.

| API updates have been made to support Ethernet Link Aggregation and Ethernet Bridging.

| Miscellaneous technical updates were made to a number of other APIs.

Application programming interfaces 3

| What's new as of 12 April 2011

| Miscellaneous minor technical updates have been made.

| What's new as of 10 September 2010

| The new Retrieve Workload Capping Group Information API was added to the Software Product
| category.

| Miscellaneous technical updates were made to a number of other APIs.

| What's new as of 30 June 2010

| Miscellaneous minor technical updates have been made to a number of APIs.

| How to see what's new or changed

| To help you see where technical changes have been made, the information center uses:
| v The image to mark where new or changed information begins.
| v The image to mark where new or changed information ends.

| In PDF files, you might see revision bars (|) in the left margin of new and changed information.

| To find other information about what's new or changed this release, see the Memo to users.

PDF file for APIs

| You can view and print a PDF file of this information.

| To view or download the PDF version of overview and concept information for APIs, select API overview
| and concepts (about 4500 KB). PDFs for API descriptions are no longer provided.

Saving PDF files

To save a PDF on your workstation for viewing or printing:

1. Right-click the PDF link in your browser.
2. Click the option that saves the PDF locally.
3. Navigate to the directory in which you want to save the PDF.
4. Click Save.

Downloading Adobe Reader

You need Adobe Reader installed on your system to view or print these PDFs. You can download a free
copy from the Adobe Web site (www.adobe.com/products/acrobat/readstep.html) .

API concepts
An application programming interface (API) is a functional interface supplied by the operating system or a
separately orderable licensed program that allows an application program written in a high-level
language to use specific data or functions of the operating system or the licensed program.

4 IBM i: Programming API overview and concepts

Some APIs provide the same functions as control language (CL) commands and output file support.
Some APIs provide functions that CL commands do not. Most APIs work more quickly and use less
system overhead than the CL commands.

API use has the following advantages:

v APIs provide better performance when getting system information or when using system functions that
are provided by CL commands or output file support.
v APIs provide system information and functions that are not available through CL commands.
v You can use calls from high-level languages to APIs.
v You can access system functions at a lower level than what was initially provided on the system.
v Data is often easier to work with when returned by an API.

API terminology
Before using the IBM i APIs, you need to understand several terms that refer to IBM i objects.

The system-recognized identifiers are shown in parentheses.

Note: Each term does not apply to every API.

binding directory (*BNDDIR)
An object that contains a list of names of modules and service programs.
data queue (*DTAQ)
An object that is used to communicate and store data used by several programs in a job or
between jobs.
module (*MODULE)
An object that is made up of the output of the compiler.
program (*PGM)
A sequence of instructions that a computer can interpret and run. A program can contain one or
more modules.
service program (*SRVPGM)
An object that packages externally supported callable routines into a separate object.
user index (*USRIDX)
An object that provides a specific order for byte data according to the value of the data.
user queue (*USRQ)
An object consisting of a list of messages that communicate information to other application
programs. Only programming languages that can use machine interface (MI) instructions can
access *USRQ objects.
user space (*USRSPC)
An object consisting of a collection of bytes used for storing any user-defined information.

Generic library names

These special values refer to IBM i libraries. You can often use them in API calls in place of specific
library names.
*ALL All libraries, including the QSYS library.
*ALLUSR
All user-defined libraries with names that do not begin with the letter Q. Although the following
libraries with names that begin with the letter Q are provided by IBM, they typically contain user
data that changes frequently. Therefore, these libraries are also considered user libraries.

Application programming interfaces 5

QDSNX QSRVAGT QUSRNOTES
QGPL QSYS2 QUSROND
QGPL38 QSYS2xxxxx QUSRPOSGS
QMGTC QS36F QUSRPOSSA
QMGTC2 QUSER38 QUSRPYMSVR
QMPGDATA QUSRADSM QUSRRDARS
QMQMDATA QUSRBRM QUSRSYS
QMQMPROC QUSRDIRCF QUSRVI
QPFRDATA QUSRDIRCL QUSRVxRxMx
QRCL QUSRDIRDB
QRCLxxxxx QUSRIJS
QUSRINFSKR

*ALLUSR excludes System/36 libraries that have names starting with the symbol # and that do
not contain user data. The following table lists those libraries.

#CGULIB #RPGLIB
#COBLIB #SDALIB
#DFULIB #SEULIB
#DSULIB

xxxxx is the number of a primary auxiliary storage pool (ASP).

A different library name, in the format QUSRVxRxMx, can be created by the user for each
previous release supported by IBM to contain any user commands to be compiled in a CL
program for the previous release. For the QUSRVxRxMx user library, VxRxMx is the version,
release, and modification level of a previous release that IBM continues to support.
For more information about QUSRVxRxMx libraries or the *ALLUSR special value, see Special
values for the SAVLIB command.
*CURLIB
The job's current library. If no current library is specified for the job, the QGPL library is used.
*LIBL The user and system portions of the job's library list.
*USRLIBL
The user portion of the job's library list.
Related reference:
Special values for the SAVLIB command

API naming conventions

Program-based APIs and service-program-based APIs follow similar naming conventions.

Except for the APIs that are defined by formal standards organizations (for example, UNIX-type APIs), an
API name starts with the letter Q, followed by 2, 3, or 4 letters that comprise an internal component
identifier. The last part of the API name identifies the action or function of the API.

The following table contains all of the verbs that are either part of an API name or are implied verbs
associated with an API name.
Table 1. Verbs and abbreviations for program-based and service-program-based APIs
Verb Abbreviation
access access
Add ADD, Add
Change C, CHG, Chg, ch

6 IBM i: Programming API overview and concepts

Table 1. Verbs and abbreviations for program-based and service-program-based APIs (continued)
Verb Abbreviation
Check C, CHK, CHECK
Clear CLR, Clr
Close CLO, close
Complete Cmp
Control CTL
Convert CVT, CVRT, Convert
Copy CPY, Cpy
Create CRT, Crt, create
Customize CST
Delete DLT, Dlt
Deregister DRG, Deregister
Disable D
Display DSP, Dsp
Dump DMP, Dump
duplicate dup
Edit EDT
Enable E
End END, End
Execute (run) EXC, EXEC
Filter FTR
Force FRC
Generate GEN
Get (fetch) G, GET, Get, get
Initialize Inz
Insert Ins
link link
List L, LST, List
Lock/unlock LUL
make mk
Map Map
Maximize Mxz
Move MOV, Mov
Open OPN, open
Pad Pad
Print PRT, Prt
Put PUT, Put
PutGet PutGet
Query Q, QRY, Qry
Read RD, Read, read
Receive R, RCV, RECV

Application programming interfaces 7

Table 1. Verbs and abbreviations for program-based and service-program-based APIs (continued)
Verb Abbreviation
Register RG, REG, R, Register
Release RLS
Remove RMV, Rmv, Remove, rm
Rename RNM, rename
Report Report
Resend RSN
Reserve Reserve
Restore RST, Rst, Restore
reset rewind
Resize Rsz
Retrieve R, RTV, Rtv, Retrieve
Roll Roll
Save SAV, Sav, Save
Scan for SCAN
Send S, SND, SEND, Send
Set SET, Set
Shift Shf
Start Start, STR, Str
Submit Submit
Switch Set
Test T
Toggle Tgl
Transform T
Translate TR, TRN, XLATE
truncate truncate
Unregister U
Update UPD
Validate V
Work with WK, WRK, Wrk
Write WRT, Wrt, write, W

Related concepts:
Types of APIs on page 10
IBM i APIs exist in several operating environments on a system.

Language selection considerations

You can directly use APIs, other than service-program-based APIs, with all the languages that are
available with the IBM i operating system.

ILE APIs that are implemented as service programs (*SRVPGM) can be directly accessed only by ILE
languages. For non-ILE languages, the Call Service Program Procedure (QZRUCLSP) API is available to
indirectly access service-program-based APIs. In some cases, an ILE API also provides a program (*PGM)
interface so that non-ILE languages can access the function.

8 IBM i: Programming API overview and concepts

Some APIs also require that particular data types and particular parameter passing conventions be used.
The following table shows the languages that are available with the IBM i operating system and the data
types that they provide.
Table 2. Language selection considerationsdata types
Language Pointers Binary 2 Binary 4 Character Zoned Packed Floating Structures Single Exception
decimal decimal point array handling
1 1
BASIC X X X X X X X X
(PRPQ
5799-FPK)
6
ILE C X X X X X X X X X
VisualAge X X X X X 7
X X X X
C++ for
IBM i
2
CL X X X X X X X X
2
ILE CL X X X X X X X X
3
COBOL X X X X X X X X X
3
ILE X X X X X X X X X X
COBOL
MI X X X X X X X X X X
4 4
Pascal X X X X X X X X X X
(PRPQ
5799-FRJ)
PL/I X X X X X X X X X X
(PRPQ
5799-FPJ)
2 2
REXX X X X X
5
RPG X X X X X X X X
5
ILE RPG X X X X X X X X X X
Notes:
1. Refer to the CNVRT$ intrinsic function.
2. There is no direct support, but you can use the substring capability to simulate structures and arrays.
3. 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.
4. There is no direct support, but you can use extended program model (EPM) conversion routines to convert to and from zoned and packed
decimal.
5. RPG programs cannot monitor for specific messages, but these programs can define an error handler to run when a program ends because of an
error.
6. Packed decimal is implemented in ILE C with the decimal() data type.
7. Packed decimal is implemented in VisualAge C++ for IBM i 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.

The following table shows the languages that are available with the IBM i operating system and the
parameter support that they provide. See the reference information for the specific programming
language that you plan to use.
Table 3. Language selection considerationscall conventions
1
Language Function return values Pass by reference Pass by value
BASIC X
ILE C X X X
VisualAge C++ for IBM i X X X
CL X
2
ILE CL X X X2
3
COBOL X
ILE COBOL X X X

Application programming interfaces 9

Table 3. Language selection considerationscall conventions (continued)
1
Language Function return values Pass by reference Pass by value
MI X X
Pascal X
PL/I X
REXX X
RPG X
ILE RPG X X X
Notes:
1. Return values are used by the UNIX-type APIs and the Dynamic Screen Manager (DSM) APIs.
2. This support is available only when using the Call Bound Procedure (CALLPRC) command.
3. COBOL provides a by-content phrase, but it does not have the same semantics as ILE C pass-by-value.

Related concepts:
User spaces for list APIs on page 79
List APIs require a user space to contain returned information.

Types of APIs
IBM i APIs exist in several operating environments on a system.

APIs for the program-based environment

Program-based APIs are called as programs (*PGMs). They are the initial APIs on the system.

Program-based APIs use the following naming conventions:

v Names of program APIs start with the letter Q.
v Names of program APIs are followed by a 2-, 3-, or 4-letter internal component identifier.
v Names of program APIs are limited to 8 characters.
v Names of program APIs must be uppercase.
Related concepts:
API information format on page 47
The format of the IBM i API information includes sections such as parameters, authorities and locks,
required parameter group, format, field descriptions, and error messages.
Examples: Program-based APIs on page 120
These examples demonstrate the use of program-based APIs in several different high-level language
programs.

APIs for the service-program-based environment

APIs based on service programs are called as procedures exported from ILE service programs
(*SRVPGM).

Bindable procedure APIs, exported from ILE service programs (*SRVPGM), are independent of the
high-level languages. This can be useful when mixed languages are involved.

Here are some of the functions provided by the service-program-based APIs:

v Dynamic screen management (DSM)
v National language support
v Mail server framework
v Problem management
v Programming and control language (CL)

10 IBM i: Programming API overview and concepts

v Registration facility
v Source debugger

APIs based on service programs that are defined by IBM use the following naming conventions:
v Start with the letter Q.
v Are followed by a 2-, 3-, or 4-character internal component identifier.
v Can be up to 30 characters.
v Are case sensitive.

APIs based on service programs that are defined by industry standards follow the industry naming
conventions.

ILE service programs (*SRVPGM) use the following naming conventions:

v Start with the letter Q.
v Are followed by a 2-, 3-, or 4-character internal component identifier.
v Are limited to 8 characters.
v Are uppercase.

Bindable APIs are contained within service programs to which the calling program binds. Some bindable
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 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 export bindable APIs are in the QUSAPIBD binding directory. This binding directory is implicitly
used by ILE compilers to resolve the bindable API references; therefore, it is not necessary to explicitly
name the service program or the API binding directory when you create programs that use bindable
APIs. If you provide your own APIs with the same name, make sure that you also provide your own
binding directory or service program.

Most APIs (program-based and service-program-based) have a header file supplied by the IBM i
operating system. These header files reside in the optionally installable library QSYSINC. The header files
provide the prototypes for the API and 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 you code 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.

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 no errors occur when APIs are used, the requested function is completed
successfully.
Related concepts:
API information format on page 47
The format of the IBM i API information includes sections such as parameters, authorities and locks,
required parameter group, format, field descriptions, and error messages.
Examples: Service-program-based APIs on page 185
These program examples demonstrate the use of service-program-based APIs in several different
high-level language programs. The example APIs represent two general functions of APIs: change and

Application programming interfaces 11

retrieve.

APIs for the ILE Common Execution Environment

The service-program-based APIs with names that begin with CEE are based on an IBM cross-platform
language environment specification. The Common Execution Environment (CEE) APIs are intended to be
consistent across the IBM systems.

The CEE APIs with names that begin with CEE4 or CEES4 are specific to business computing systems.

The CEE APIs provide the following functions:

v Activation group and control flow management
v Condition management
v Date and time manipulation
v Math functions
v Message services
v Program or procedure call management and operational descriptor access
v Storage management
Related reference:
ILE CEE APIs

Differences between program-based APIs and service-program-based APIs

Program-based APIs and service-program-based APIs are different in API names, parameters, error
conditions, and pointer use.

APIs based on service programs include the UNIX-type APIs and the ILE Common Execution
Environment (CEE) APIs. You must have the ILE language compiler on your system to develop
applications that use any bindable APIs.

The following table shows the differences between program-based APIs and service-program-based APIs.
Table 4. Comparison of program-based and service-program-based APIs
Description Program APIs Bindable APIs
API name Maximum number of characters: 8. Maximum number of characters: 30.
Not case sensitive. Case sensitive.
Required parameters1 Displayed in the parameter box. Displayed in the parameter box.
Optional parameters Can include optional parameters. The No optional parameters.
optional parameters form a group.
You must either include or exclude
the entire group.
Omitted parameters No omitted parameters. Can include omitted parameters.
When these parameters are omitted,
you must pass a null pointer.
Error conditions2 The error code parameter is common The error code parameter is common
to most of the program-based APIs. It to most of the bindable APIs whose
is used to return error codes and names start with the letter Q. The ILE
exception data to the application. The CEE APIs use feedback codes and
errors that are returned for a given conditions. The UNIX-type APIs
API are in the form of an error generally use errnos to provide
message and a 7-character message error-related information.
identifier.

12 IBM i: Programming API overview and concepts

Table 4. Comparison of program-based and service-program-based APIs (continued)
Description Program APIs Bindable APIs
Pointers Can be used, but are used less Because of the greater availability of
frequently than with the bindable pointer support in ILE languages,
APIs. there is a much greater use of
pointers in the bindable APIs. The
use of pointers can provide a
performance advantage.
Notes:
1. The UNIX-type APIs include parameters in a syntax box.
2. Error conditions
v The UNIX-type APIs use errnos and return values.
v 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.

In the examples that follow, a program-based API and a service-program-based API are used to perform
similar functions (log or report software errors). The bindable API uses pointers while the program API
does not. Both APIs log software errors by using first-failure data capture (FFDC).
Related concepts:
API parameters on page 52
After you decide which API to use, you need to code a call to the API and pass to the API the set of
parameters that are appropriate for it.
Related reference:
Errno Values for UNIX-Type Functions

Example in ILE C: Logging software errors (program API without pointers):

This ILE C program calls the Log Software Error (QPDLOGER) API to perform first-failure data capture
(FFDC) without using pointers.

The ILE C program physically moves the data that is pointed to, as shown at (1), which slows down
performance.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer
information on page 571.
/*********************************************************************/
/* */
/*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 */
/* */
/*********************************************************************/
/*********************************************************************/

Application programming interfaces 13

/*********************************************************************/
/* System Includes */
/*********************************************************************/
#include <except.h> /* from QSYSINC/H */
#include <stdio.h> /* from QSYSINC/H */
#include <string.h> /* from QSYSINC/H */

/*********************************************************************/
/* Miscellaneous Includes */
/*********************************************************************/
#include <qmhchgem.h>
#include <qpdloger.h>
#include <qusec.h>

/*********************************************************************/
/* 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[0] contains the program name, and the */
/* parameter(s) starts with argv[1]. */
/*******************************************************************/

char *nulptr; /* Pointer used to generate error */

char pgm_name[30]; /* 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];

14 IBM i: Programming API overview and concepts

 ffdc_info.pgm_name = pgm_name;
memcpy(pgm_name, argv[0], strlen(argv[0]));
ffdc_info.pgm_name_size = strlen(argv[0]);

/*******************************************************************/
/* Enable the exception handler, and pass ffdc_info into the */
/* exception handler via the communications area so that data */
/* can be used for FFDC. */
/*******************************************************************/

#pragma exception_handler (UNEXPECTED_HDLR, ffdc_info, 0, _C2_MH_ESCAPE)

/*******************************************************************/
/* Set the pointer to null, then try to increment. This will */
/* generate an MCH3601 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[30];
char obj_lib[30];
char obj_type[10];
} obj_info_t;

typedef struct {
int data_offset;
int data_length;
} data_info_t;

char pgm_suspected[10],
msg_id[12],
msg_key[4],
print_job_log,
data[2*(sizeof(char *))],
*data_item,
ile_mod_name[11];
int point_of_failure,
num_items,
num_objs;
data_info_t data_info[2];
obj_info_t obj_info[1];
ffdc_info_t *ffdc_info;
Qus_EC_t ErrorCode;

Application programming interfaces 15

 ErrorCode.Bytes_Provided = 0;

/*******************************************************************/
/* 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 */
0, /* Call stack counter */
(char *)&errmsg->Msg_Ref_Key,/* Message key */
"*HANDLE ", /* Modification option */
"", /* Reply text */
0, /* Reply text length */
&ErrorCode); /* Error code */

/*******************************************************************/
/* Set up the suspected program. */
/*******************************************************************/
memcpy(pgm_suspected, "*PRV ", 10);

/*******************************************************************/
/* 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 = 100;

/*******************************************************************/
/* Set up to print the job log. */
/*******************************************************************/
print_job_log = Y;

/*******************************************************************/
/* Set up data items. */
/*******************************************************************/
data_item = data;

/*******************************************************************/
/* Put in first parameter. */
/*******************************************************************/
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. */

16 IBM i: Programming API overview and concepts

 /*******************************************************************/
data_item -= sizeof(char *);

/*******************************************************************/
/* Set up data item offset/length information. */
/*******************************************************************/
data_info[0].data_offset = 0;
data_info[0].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[0].obj_name, "OBJUSRSPC ", 30);
memcpy(obj_info[0].obj_lib, "QTEMP ", 30);
memcpy(obj_info[0].obj_type, "*USRSPC ", 10);

/*******************************************************************/
/* Set the number of objects in name array. */
/*******************************************************************/
num_objs = 0;

/*******************************************************************/
/* 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,
num_objs,
&ErrorCode,
ile_mod_name);

} /* UNEXPECTED_HDLR */
Related reference:
Example in OPM COBOL: Logging software errors (program API without pointers) on page 18
One OPM COBOL program registers an error handler. After successful completion of the registration, this
program creates a data decimal error. The error causes the error handler, the other OPM COBOL
program, to call the Log Software Error (QPDLOGER) API without using pointers.
Example in OPM RPG: Logging software errors (program API without pointers) on page 21
This OPM RPG program performs a divide-by-zero operation to cause an exception. The exception is
caught with RPG *PSSR support, which calls the Log Software Error (QPDLOGER) API to perform FFDC
without using pointers.
Example in ILE RPG: Logging software error (program API without pointers) on page 24
This ILE RPG program performs a divide-by-zero operation to cause an exception. The exception is
caught with RPG *PSSR support, which calls the Log Software Error (QPDLOGER) API to perform FFDC
Application programming interfaces 17
without using pointers.

Example in OPM COBOL: Logging software errors (program API without pointers):

One OPM COBOL program registers an error handler. After successful completion of the registration, this
program creates a data decimal error. The error causes the error handler, the other OPM COBOL
program, to call the Log Software Error (QPDLOGER) API without using pointers.

The program CBLERR1 registers the error handler and causes the error. The program ERRHDL1 receives
control and calls the QPDLOGER API to perform FFDC.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer
information on page 571.

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.
*
* APIs Used: QLRSETCE - Set COBOL Error Handler
*
***************************************************************
*
***************************************************************
PROGRAM-ID. CBLERR1.
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
*
01 MISC.
05 Y PIC S9(09) VALUE 0.
05 ERROR-HANDLER PIC X(20) VALUE "ERRHDL1 *LIBL ".
05 SCOPE PIC X(01) VALUE "C".
05 ERROR-HANDLER-LIBRARY PIC X(10).
05 PRIOR-ERROR-HANDLER PIC X(20).
01 NUMERIC-GROUP.
05 X PIC 9(03).
*
* Beginning of mainline

18 IBM i: Programming API overview and concepts

 *
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,
PRIOR-ERROR-HANDLER OF MISC,
QUS-EC.
*
* If an exception occurs, the API returns the exception in the
* error code parameter. The bytes available field is set to
* zero if no exception occurs and greater than zero if an
* exception does occur.
*
IF BYTES-AVAILABLE OF QUS-EC > 0
DISPLAY "Error setting handler",
STOP RUN.
*
* If the call to register an error handler is successful, then
* cause a the data decimal error (X is initialized to blanks).
*
ADD X TO Y.
*
* Should not get here due to data decimal error
*
STOP RUN.
*
* End of MAINLINE
*

ERRHDL1 program
IDENTIFICATION DIVISION.
****************************