IBM Systems - iSeries

High-Level Language APIs
Version 5 Release 4



IBM Systems - iSeries

High-Level Language APIs
Version 5 Release 4
 Note
Before using this information and the product it supports, be sure to read the information in
“Notices,” on page 61.

Sixth Edition (February 2006)

This edition applies to version 5, release 4, modification 0 of IBM i5/OS (product number 5722-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 International Business Machines Corporation 1998, 2006. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
High-Level Language APIs . . . . . . . 1 Record Types . . . . . . . . . . . . . . 32
APIs . . . . . . . . . . . . . . . . . 1 Processor member start record . . . . . . . 37
Application Development Manager/400 APIs . . . 1 Processors for which this record type applies . . 38
Get Space Status (QLYGETS) API . . . . . . . 2 Field Descriptions . . . . . . . . . . . 38
Authorities and Locks . . . . . . . . . . 2 Processor object start record . . . . . . . . 38
Required Parameter Group . . . . . . . . 2 Processors for which this record type applies . . 39
Error Messages . . . . . . . . . . . . 2 Field Descriptions . . . . . . . . . . . 39
Read Build Information (QLYRDBI) API . . . . . 2 Normal processor end record . . . . . . . 40
Authorities and Locks . . . . . . . . . . 3 Processors for which this record type applies . . 40
Required Parameter Group . . . . . . . . 3 Field Descriptions . . . . . . . . . . . 40
Error Messages . . . . . . . . . . . . 3 Normal processor end call next record . . . . 41
Set Space Status (QLYSETS) API . . . . . . . . 4 Processors for which this record type applies . . 41
Authorities and Locks . . . . . . . . . . 4 Field Descriptions . . . . . . . . . . . 41
Required Parameter Group . . . . . . . . 4 Normal multiple end record . . . . . . . . 42
Error Messages . . . . . . . . . . . . 5 Processors for which this record type applies . . 42
Write Build Information (QLYWRTBI) API . . . . 5 Field Descriptions . . . . . . . . . . . 42
Authorities and Locks . . . . . . . . . . 5 Abnormal processor end record . . . . . . 43
Required Parameter Group . . . . . . . . 5 Processors for which this record type applies . . 43
Error Messages . . . . . . . . . . . . 6 Field Descriptions . . . . . . . . . . . 43
COBOL/400 APIs . . . . . . . . . . . . . 6 Include record . . . . . . . . . . . . 43
Change COBOL Main Program (QLRCHGCM) API . 7 Processors for which this record type applies . . 44
Authorities and Locks . . . . . . . . . . 8 Field Descriptions . . . . . . . . . . . 44
Required Parameter . . . . . . . . . . . 8 File reference record . . . . . . . . . . 45
Error Messages . . . . . . . . . . . . 8 Processors for which this record type applies . . 45
Dump COBOL (QlnDumpCobol) API . . . . . . 9 Field Descriptions . . . . . . . . . . . 45
Authorities and Locks . . . . . . . . . . 10 Module reference record . . . . . . . . . 46
Required Parameter Group . . . . . . . . 10 Processors for which this record type applies . . 46
Error Messages . . . . . . . . . . . . 10 Field Descriptions . . . . . . . . . . . 46
Retrieve COBOL Error Handler Service program reference record . . . . . . 47
(QlnRtvCobolErrorHandler) API . . . . . . . 11 Processors for which this record type applies . . 47
Authorities and Locks . . . . . . . . . . 11 Field Descriptions . . . . . . . . . . . 47
Required Parameter Group . . . . . . . . 11 Bind directory reference record . . . . . . . 47
Error Messages . . . . . . . . . . . . 12 Processors for which this record type applies . . 48
Retrieve COBOL Error Handler (QLRRTVCE) API 12 Field Descriptions . . . . . . . . . . . 48
Authorities and Locks . . . . . . . . . . 12 Record format reference record . . . . . . . 48
Required Parameter Group . . . . . . . . 12 Processors for which this record type is
Error Messages . . . . . . . . . . . . 13 applicable . . . . . . . . . . . . . . 49
Set COBOL Error Handler (QLRSETCE) API . . . 13 Field Descriptions . . . . . . . . . . . 49
Authorities and Locks . . . . . . . . . . 14 Field reference record . . . . . . . . . . 49
Required Parameter Group . . . . . . . . 14 Processors for which this record type applies . . 50
Error Messages . . . . . . . . . . . . 15 Field Descriptions . . . . . . . . . . . 50
Set COBOL Error Handler Message reference record . . . . . . . . . 51
(QlnSetCobolErrorHandler) API . . . . . . . 15 Processors for which this record type applies . . 51
Authorities and Locks . . . . . . . . . . 16 Field Descriptions . . . . . . . . . . . 51
Required Parameter Group . . . . . . . . 16 External reference error record . . . . . . . 52
Error Messages . . . . . . . . . . . . 17 Processors for which this record type applies . . 52
ILE C/C++ Run-Time Library Functions . . . . . 17 Field Descriptions . . . . . . . . . . . 52
REXX/400 Functions . . . . . . . . . . . 28 Object already exists error record . . . . . . 53
Exit Programs . . . . . . . . . . . . . 28 Processors for which this record type applies . . 53
ILE COBOL Error-Handling Exit Procedure . . . . 28 Field Descriptions . . . . . . . . . . . 53
Authorities and Locks . . . . . . . . . . 29 Start of new program record . . . . . . . . 54
Required Parameter Group . . . . . . . . 29 Processors for which this record type applies . . 54
OPM COBOL Error-Handling Exit Program . . . 30 Field Descriptions . . . . . . . . . . . 54
Authorities and Locks . . . . . . . . . . 31 Examples of Records Written . . . . . . . . 55
Required Parameter Group . . . . . . . . 31 Example 1 . . . . . . . . . . . . . . 55
Concepts . . . . . . . . . . . . . . . 32 Example 2 . . . . . . . . . . . . . . 55

© Copyright IBM Corp. 1998, 2006 iii

 Example 3 . . . . . . . . . . . . . . 55 Appendix. Notices . . . . . . . . . . 61
Example 4 . . . . . . . . . . . . . . 55 Programming Interface Information . . . . . . 62
Example 5 . . . . . . . . . . . . . . 56 Trademarks . . . . . . . . . . . . . . 63
Example 6 . . . . . . . . . . . . . . 56 Terms and Conditions . . . . . . . . . . . 64
Using Application Development Manager/400 APIs 56

iv IBM Systems - iSeries: High-Level Language APIs

High-Level Language APIs
The high-level language APIs communicate with compilers, and the DB2(R) Universal Database(TM) for
iSeries(TM) SQL, COBOL/400(R), ILE C/C++, and REXX/400 languages. The high-level language APIs
include:
v “Application Development Manager/400 APIs”
v “COBOL/400 APIs” on page 6
v “ILE C/C++ Run-Time Library Functions” on page 17
v “REXX/400 Functions” on page 28

APIs by category

APIs
These are the APIs for this category.

Application Development Manager/400 APIs

The Application Development Manager/400 (ADM/400) feature is no longer available as of Version 5
Release 3 of iSeries(TM). However, the Application Development Manager/400 APIs can still be used by
applications written in high-level programming languages. The Application Development Manager/400
feature is not required.

The Application Development Manager/400 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 when processing a source member. The term processor is used in these
APIs to mean compiler or preprocessor. A part can be either a source member or an object, such as a file.

The Get and Set Status APIs are used to query and initialize the build information space that is to contain
the Application Development Manager/400 information. The Write and Read Build Information APIs are
used to write or read records of build information to and from the space.

For additional information, see “Using Application Development Manager/400 APIs” on page 56.

For information on the different types of records that can be read or written using the Application
Development Manager/400 APIs, see:
v “Record Types” on page 32
v “Examples of Records Written” on page 55

The Application Development Manager/400 APIs are:

v “Get Space Status (QLYGETS) API” on page 2 (QLYGETS) obtains the status of the space.
v “Read Build Information (QLYRDBI) API” on page 2 (QLYRDBI) reads one or more records from the
space.
v “Set Space Status (QLYSETS) API” on page 4 (QLYSETS) sets the status of the space.
v “Write Build Information (QLYWRTBI) API” on page 5 (QLYWRTBI) writes one or more records to the
space.

Top | “High-Level Language APIs” | APIs by category

© Copyright IBM Corp. 1998, 2006 1

Get Space Status (QLYGETS) API
Required Parameter Group:

1 Status Output Char(10)

2 Error code I/O Char(*)

Default Public Authority: *USE

Threadsafe: No

The Get Space Status (QLYGETS) API obtains the status of the space.

Authorities and Locks

None

Required Parameter Group

Status OUTPUT; CHAR(10)

*READY Information in the space is ready to be processed.

*COMPLETE Information in the space has been processed.
*NONE The space does not exist. Use QLYSETS to create the space.

Error code
I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error Code
Parameter.

Error Messages
Message ID Error Message Text
CPF3CF1 E Error code parameter not valid.
CPF3C90 E Literal value cannot be changed.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R2

Top | “High-Level Language APIs,” on page 1 | APIs by category

Read Build Information (QLYRDBI) API

Required Parameter Group:

1 Buffer Output Char(*)

2 Maximum size Input Binary(4)
3 Read mode Input Char(10)
4 Buffer length Output Binary(4)
5 Number of records Output Binary(4)
6 Error code I/O Char(*)

Default Public Authority: *USE

Threadsafe: No

The Read Build Information (QLYRDBI) API reads one or more records from the space.

2 IBM Systems - iSeries: High-Level Language APIs

QLYRDBI reads the space starting at the first location after the last record was read. If this is the first
time QLYRDBI is called, the first record following the header record is read.

After QLYRDBI has read the final record, the next call to QLYRDBI starts reading the space from the
beginning again.

QLYRDBI reads one or more records depending on the value specified on the Read mode parameter.
QLYRDBI does not read more records than can fit in the buffer. The buffer is determined by the
Maximum-size parameter.

Authorities and Locks

None.

Required Parameter Group

Buffer OUTPUT; CHAR(*)
A character string to contain one or more records of build information.
Maximum size
INPUT; BINARY(4)
The maximum size of the data that is expected to be returned to this call. Maximum size should
be large enough to fit at least one record. If it is too small for one record, an error occurs.
Read mode
INPUT; CHAR(10)
The mode of reading.
The possible read mode values are:

*SINGLE Read only one record.

*MULTIPLE Read more than one record. The maximum number of records that are read is determined by the
size of Maximum size.

Buffer length
OUTPUT; BINARY(4)
The length of the data returned. If records are not read, 0 is returned.
Number of records
OUTPUT; BINARY(4)
The number of records read. Number of records is 0 if no records were read, 1 if one record was
read or greater than 1 if *MULTIPLE was specified on read mode and more than one record
could fit in the buffer.
Error code
I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error Code
Parameter.

Error Messages
The LIBxxxx error messages are located in the message file QLIBMSG in the QSYS library.

Message ID Error Message Text

LIB9005 Value specified for Maximum size parameter is not valid.
LIB9006 Value specified for Read mode parameter is not valid.
LIB9007 Value specified for Maximum size parameter is too small.

High-Level Language APIs 3

Message ID Error Message Text
LIB9009 Build information space does not exist, or it is damaged or deleted.
LIB9010 Build information missing or no more build information.
LIB9011 Build information in the space is not complete.
CPF3CF1 E Error code parameter not valid.
CPF3C90 E Literal value cannot be changed.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R2

Top | “High-Level Language APIs,” on page 1 | APIs by category

Set Space Status (QLYSETS) API

Required Parameter Group:

1 Status Input Char(10)

2 Error code I/O Char(*)

Default Public Authority: *USE

Threadsafe: No

The Set Space Status (QLYSETS) API sets the status of the space.

When QLYSETS is first called to create the space (if the space does not exist already) or to initialize the
space so the information can be written to it by compilers or preprocessors, the Status parameter should
be set to *READY. Then QLYSETS writes a special record (called the HEADER record) at the beginning of
the space and initializes a status flag in that record to *READY. Now the space is ready to accept records
containing build information. Compilers write to the space using the QLYWRTBI API. QLYWRTBI writes
records to the space concatenated to each other. QLYRDBI later reads them sequentially in the order in
which they are written.

Use the QLYSETS API to set the status flag in the space to *COMPLETE after the information in the space
is processed using the QLYRDBI API. This indicates that the information in the space has been processed
and the space can be reused.

Authorities and Locks

None

Required Parameter Group

Status INPUT; CHAR(10)
The status for the space.
The possible status values are:

*READY Initialize the space. If the space does not exist, it is created.
*COMPLETE Information in the space has been processed. The space can now be used by setting it to *READY
with another call to QLYSETS.

Error code
I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error Code
Parameter.

4 IBM Systems - iSeries: High-Level Language APIs

Error Messages
Message ID Error Message Text
LIB9001 Value specified on the Status parameter is not valid.
CPF3CF1 E Error code parameter not valid.
CPF3C90 E Literal value cannot be changed.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R2

Top | “High-Level Language APIs,” on page 1 | APIs by category

Write Build Information (QLYWRTBI) API

Required Parameter Group:

1 Buffer Input Char(*)

2 Buffer length Input Binary(4)
3 Error code I/O Char(*)

Default Public Authority: *USE

Threadsafe: No

The Write Build Information (QLYWRTBI) API writes one or more records to the space.

QLYWRTBI writes records to the space concatenated to each other. QLYRDBI later reads them
sequentially in the order in which they are written.

QLYWRTBI continues to write records to the API space concatenated to previous records written, until
QLYSETS is called. See “Record Types” on page 32 for the records that can be written. See “Examples of
Records Written” on page 55 for examples of the sequence of records written.

Authorities and Locks

None.

Required Parameter Group

Buffer INPUT; CHAR(*)
A character string containing one or more records of build information.
Buffer length
INPUT; BINARY(4)
The length of the buffer in bytes. The buffer length must be equal to the sum of the lengths of all
the concatenated records being passed, otherwise an error occurs.
Error code
I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error Code
Parameter.

The first field in each record indicates the record length. This allows all the records to be read
sequentially using the QLYRDBI API.

High-Level Language APIs 5

Error Messages
Message ID Error Message Text
LIB9002 Value specified for the buffer length parameter is not valid.
LIB9003 Value specified for the buffer length parameter is too small.
LIB9004 Record not in correct sequence.
LIB9008 Record has a record type that is not valid.
LIB9009 Build information space does not exist, or it is damaged or deleted.
CPF3CF1 E Error code parameter not valid.
CPF3C90 E Literal value cannot be changed.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R2

Top | “High-Level Language APIs,” on page 1 | APIs by category

COBOL/400 APIs
The OPM and ILE COBOL/400(R) APIs let you control run units and error handling.

Refer to Using COBOL Program to Call APIs and Error Handler for Example COBOL Program in the API
Examples for illustrations of how to use these APIs.

For a description of how to use the ILE COBOL/400 APIs, refer to the chapter about error and exception

handling in the WebSphere Development Studio: ILE COBOL Programmer″s Guide book.

The COBOL/400 APIs are:

v “Change COBOL Main Program (QLRCHGCM) API” on page 7 (QLRCHGCM) lets you create an
additional run unit (1) by assigning a different System/36-compatible COBOL, System/38-compatible
COBOL, or iSeries OPM COBOL/400 program to serve as a main program.
v “Dump COBOL (QlnDumpCobol) API” on page 9 (QlnDumpCobol) allows you to perform a formatted
dump of an ILE COBOL/400 program.
v “Retrieve COBOL Error Handler (QLRRTVCE) API” on page 12 (QLRRTVCE) allows you to retrieve
the name of the current or pending COBOL error-handling program.
v “Retrieve COBOL Error Handler (QlnRtvCobolErrorHandler) API” on page 11
(QlnRtvCobolErrorHandler) allows you to retrieve the procedure pointer of the current COBOL
error-handling procedure.
v “Set COBOL Error Handler (QLRSETCE) API” on page 13 (QLRSETCE) allows you to specify the
identity of a COBOL error-handling program.
v “Set COBOL Error Handler (QlnSetCobolErrorHandler) API” on page 15 (QlnSetCobolErrorHandler)
allows you to specify the identity of a COBOL error-handling procedure.

The COBOL/400 exit programs are:

v “ILE COBOL Error-Handling Exit Procedure” on page 28 acts as an error handler for an ILE
COBOL\/400 program.
v “OPM COBOL Error-Handling Exit Program” on page 30 acts as an error handler for an OPM COBOL
program.

Top | “High-Level Language APIs,” on page 1 | APIs by category

6 IBM Systems - iSeries: High-Level Language APIs

Change COBOL Main Program (QLRCHGCM) API
Required Parameter

1 Error code I/O Char(*)

Default Public Authority: *USE

Threadsafe: No

The Change COBOL Main Program (QLRCHGCM) API allows you to create an additional run unit by
assigning a different System/36-compatible COBOL, System/38-compatible COBOL, or iSeries OPM
COBOL/400 program to serve as a main program. You can call it from any programming language.

Note: By creating more than one run unit, you cantreat files, storage, and error conditions differently than
you would using an ordinary subprogram.

After you call this API, the next nonactive COBOL program that runs becomes the main program in a
new run unit. An active COBOL program is a program that has been called, and is not in its initial state.

In the following example, System/38-compatible COBOL Program A calls iSeries COBOL/400 Program B.
Because Program A is the first COBOL program, it is the main COBOL program.

COBOL Program B is a menu program that calls CL Program C.

Program C must start a new COBOL application that will pass control back to it, regardless of error
conditions. To accomplish this, Program C calls the QLRCHGCM API before calling the new COBOL
application.

When program C calls the new COBOL application in the form of Program D, Program D becomes the
main program in a new run unit. When Program D’s run unit ends, control returns to the original run
unit, and Program A becomes the current main program again.

If, at the time a run unit is created, a program is active as a subprogram in an existing run unit, and this
program is then called within the new run unit, it will be made available in its last-used state.

High-Level Language APIs 7

Authorities and Locks
None.

Required Parameter
Error code
I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error Code
Parameter.

Error Messages
Message ID Error Message Text
CPF3C90 E Literal value cannot be changed.
LBE7040 E Format of error code parameter is not correct.

API introduced: V2R2

Top | “High-Level Language APIs,” on page 1 | APIs by category

8 IBM Systems - iSeries: High-Level Language APIs

Dump COBOL (QlnDumpCobol) API
Required Parameter Group:

1 Program object name Input Char(10)

2 Library name Input Char(10)
3 Module object name Input Char(10)
4 Program object type Input Char(10)
5 Dump type Input Char(1)
6 Error code I/O Char(*)

Default Public Authority: *USE

Service Program: QLNRMAIN
Threadsafe: No

The Dump COBOL (QlnDumpCobol) API allows you to perform a formatted dump of an ILE
COBOL/400 program. You can call it from any ILE program; however, if the calling program is not an
ILE COBOL/400 program, only a data dump will be performed. Message CPF955F will be issued if this
API is called to dump any module other than those created by the ILE COBOL/400 compiler.

This API provides two types of dumps, a data dump and an extended dump. The data dump contains
the following information:
v The name of each variable
v The data type
v The default value
v The hexadecimal value

Note: Only the first 250 characters of the values will be shown in the dump.

The extended dump contains the following additional information:

v The name of each file
v The system name of each file
v External/internal flag
v Open/close status
v Last I/O operation attempted
v Last file status
v Last extended status
v Blocking information
v Blocking factor
v Linage-counter value
v I/O feedback area information
v Open feedback area information

Variable values may only be requested if an active call stack entry exists for the module object specified
in the job in which this API is called. Values existing in program static or automatic storage are not
accessible by this API unless the program object has a current call stack entry. All variables that were
defined by the compiler and stored in the module object’s HLL symbol table will be returned.

Also, the module object for which variable information is requested must contain debug data. Thus, the
module object must be compiled with a *DBGVIEW option other than *NONE.

High-Level Language APIs 9

Authorities and Locks
None.

Required Parameter Group

Program object name
INPUT; CHAR(10)
The name of the program to be dumped. If this parameter is omitted, the program object name of
the caller is used.
Library name
INPUT; CHAR(10)
The name of the library in which the program to be dumped is found. *CURLIB and *LIBL can
be specified as valid values to indicate the current library and the library list, respectively. If this
parameter is omitted, the library associated with the calling program is used.
Module object name
INPUT; CHAR(10)
The name of the module, within the specified program, to be dumped. If this parameter is
omitted, the module object name of the caller is used.
Program object type
INPUT; CHAR(10)
The object type of the program object.
Valid values are:

*PGM Program object

*SRVPGM Service program

Dump type
INPUT; CHAR(1)
The type of dump.
Valid values are:

D Data dump. Gives a dump of the COBOL identifiers.

F Extended dump. Gives a dump of COBOL identifiers and file-related information.

Error code
I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error Code
Parameter.

Error Messages
Message ID Error Message Text
CPF3C21 E Format name &1 is not valid.
CPF3C90 E Literal value cannot be changed.
CPF3CF1 E Error code parameter not valid.
CPF3CF2 E Error(s) occurred during running of &1 API.
CPF9549 E Error addressing API parameter.
CPF954F E Module &1 not found.
CPF955F E Program &1 not a bound program.
CPF9562 E Module &1 cannot be debugged.

10 IBM Systems - iSeries: High-Level Language APIs

Message ID Error Message Text
CPF956D E Parameter does not match on continuation request.
CPF956E E Program language of module not supported.
CPF956F E Continuation handle parameter not valid.
CPF9573 E Program type parameter not valid.
CPF9574 E Call stack entry does not exist.
CPF9579 E Data option specified not valid.
CPF9801 E Object &2 in library &3 not found.
CPF9802 E Not authorized to object &2 in &3.
CPF9803 E Cannot allocate object &2 in library &3.
CPF9809 E Library &1 cannot be accessed.
CPF9810 E Library &1 not found.
CPF9820 E Not authorized to use library &1.

API introduced: V3R6

Top | “High-Level Language APIs,” on page 1 | APIs by category

Retrieve COBOL Error Handler (QlnRtvCobolErrorHandler) API

Required Parameter Group:

1 Current error-handling exit procedure pointer Output Anyptr

2 Error code I/O Char(*)

Default Public Authority: *USE

Service Program: QLNRMAIN
Threadsafe: No

The Retrieve COBOL Error Handler (QlnRtvCobolErrorHandler) API allows you to retrieve the procedure
pointer of the current COBOL error-handling procedure. You can call it from any ILE programming
language; however, this API only retrieves the procedure pointer of the error handling program that is
called when an error occurs in an ILE COBOL/400 program.

Authorities and Locks

None.

Required Parameter Group

Current error-handling exit procedure pointer
OUTPUT; ANYPTR
Valid values are:

NULL No current error-handling procedure found.

procedure-pointer The procedure pointer of the error handler.

Error code
I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code
parameter.

High-Level Language APIs 11

Error Messages
Message ID Error Message Text
CPF3C90 E Literal value cannot be changed.
LNR7074 E Error code not valid.
LNR7075 E Error addressing API parameters.

API introduced: V2R1.1

Top | “High-Level Language APIs,” on page 1 | APIs by category

Retrieve COBOL Error Handler (QLRRTVCE) API

Required Parameter Group:

1 Current or pending error-handling exit program name Output Char(20)

2 Scope of error-handling exit program Input Char(1)
3 Error code I/O Char(*)

Default Public Authority: *USE

Threadsafe: No

The Retrieve COBOL Error Handler (QLRRTVCE) API allows you to retrieve the name of the current or
pending COBOL error-handling program. You can call it from any programming language; however, this
API only retrieves the name of the error handling program that is called when an error occurs in an OPM
COBOL/400 program.

Authorities and Locks

None.

Required Parameter Group

Current or pending error-handling exit program name
OUTPUT; CHAR(20)
The qualified name of the error-handling program for the current or pending COBOL run unit.
The 20 characters of this parameter are:

1-10 The name of the program object.

Valid values are:

*NONE No user-defined COBOL error handler has been set.

program-name
The name of the error-handling program.
11-20 The library where the program object existed.
The valid value is:

library-name
The library where the program object existed.

Scope of error-handling exit program

INPUT; CHAR(1)
The program can apply to a current or pending run unit.

12 IBM Systems - iSeries: High-Level Language APIs

 Valid values are:

C Current COBOL run unit

P Pending COBOL run unit

Error code
I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error Code
Parameter.

Error Messages
Message ID Error Message Text
CPF3C90 E Literal value cannot be changed.
LBE7040 E Format of error code parameter is not correct.
LBE7051 E Scope parameter not valid.
LBE7052 E Run unit specified for error handler does not exist.
LBE7055 E Severe error while addressing parameter list. The API did not complete.

API introduced: V3R6

Top | “High-Level Language APIs,” on page 1 | APIs by category

Set COBOL Error Handler (QLRSETCE) API

Required Parameter Group:

1 Error-handling exit program name Input Char(20)

2 Scope of error-handling program Input Char(1)
3 New error-handling exit program library Output Char(10)
4 Current or pending error-handling exit program name Output Char(20)
5 Error code I/O Char(*)

Default Public Authority: *USE

Threadsafe: No

The Set COBOL Error Handler (QLRSETCE) API allows you to specify the identity of a COBOL
error-handling program. You can call it from any programming language; however, this API only sets the
name of the error handling program that is called when an error occurs in an OPM COBOL/400
program.

After you call this API, any COBOL/400 program that issues an inquiry message with options C, D, or F
will first call the defined error-handling program. This program receives the message identification and
substitution text, as well as the name of the program that received it, and a list of valid one-character
responses. The defined program is responsible for returning a one-character code (blank, C, D, F, or G)
indicating whether the COBOL program should continue or not.

Note: All messages issued by the operating system during the running of a COBOL program are
monitored by the COBOL program. Only some of the system messages issued will result in a COBOL
inquiry message.

For more information about error handling and the issuing of COBOL inquiry messages, see the chapter

on error handling in the WebSphere Development Studio: ILE COBOL Programmer’s Guide book.

High-Level Language APIs 13

You can define a different error-handling program for each COBOL run unit, but when a new COBOL
run unit starts, it uses the error-handling program from the previous run unit.

Only one error-handling program can be active at a time. If an error occurs in the error-handling
program, the COBOL program does not call the error-handling program again. (In other words, recursive
calls do not occur.) Instead, the inquiry message would be issued as if no error-handling program were
defined.

You cannot change the name of the error-handling program while it is responding to an error in a
COBOL program.

If an error occurs during the calling of the error-handling program, an informational message (LBE7430)
is issued, and processing continues as if no error-handling program were defined.

The error-handling program is defined by the user. The parameters are described under “OPM COBOL
Error-Handling Exit Program” on page 30.

Authorities and Locks

None.

Required Parameter Group

Error-handling exit program name
INPUT; CHAR(20)
The qualified name of the error-handling program.
The 20 characters of this parameter are:

1-10 The name of the program object.

Valid values are:
*NONE No user-defined COBOL error-handling program exists.
program-name
The name of the error-handling program. The name can be an extended one.

11-20 The library where the program object exists.

Valid values are:
*CURLIB
The current library is used.
*LIBL The API searches the library list to find the object.
library-name
The name of the library where the program object exists. The name can be an extended
one.

Scope of error-handling program

INPUT; CHAR(1)
The program can apply to a current or pending run unit.
Valid values are:

C Current COBOL run unit

P Pending COBOL run unit

New error-handling exit program library

OUTPUT; CHAR(10)

14 IBM Systems - iSeries: High-Level Language APIs

 The library where the program object exists. If *CURLIB or *LIBL was specified for the
error-handling exit program name parameter, the library returned for this parameter shows the
library where the program was found. If *CURLIB or *LIBL was not specified, the library
returned here should be the same as character 11 through 20 of the error-handling exit program
name parameter.
Valid value is:

library-name The library where the program object exists.

Current or pending error-handling exit program name

OUTPUT; CHAR(20)
The qualified name of the error-handling program that was in place before the current
error-handling program was set.
The 20 characters of this parameter are:

1-10 The name of the previous error-handling program object.

Valid values are:
*NONE No previous current or pending error-handling program existed.
program-name
The name of the error-handling program.
11-20 The library where the previous error-handling program object existed.
Valid value is:
library-name
The library where the previous error-handling program object existed.

Error code
I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error Code
Parameter.

Error Messages
Message ID Error Message Text
CPF3C90 E Literal value cannot be changed.
LBE7040 E Format of error code parameter is not correct.
LBE7050 E Error handler is already responding to an error in the same run unit.
LBE7051 E Scope parameter not valid.
LBE7052 E Run unit specified for error handler does not exist.
LBE7055 E Severe error while addressing parameter list.The API did not complete.
LBE7060 E Error in program name or availability.
LBE7061 E Error in library name or availability.
LBE7062 E Error in library list.

API introduced: V3R6

Top | “High-Level Language APIs,” on page 1 | APIs by category

Set COBOL Error Handler (QlnSetCobolErrorHandler) API

Required Parameter Group:

1 New error-handling exit procedure pointer Input Anyptr

High-Level Language APIs 15

 2 Current error-handling exit procedure pointer Output Anyptr
3 Error code I/O Char(*)

Default Public Authority: *USE

Threadsafe: No

The Set COBOL Error Handler (QlnSetCobolErrorHandler) API allows you to specify the identity of a
COBOL error-handling procedure. You can call it from any ILE programming language; however, this API
only sets the procedure pointer of the error-handling program that is called when an error occurs in an
ILE COBOL/400 program.

After you call this API, any ILE COBOL/400 program that issues an inquiry message with options C, D,
or F will first call the defined error-handling procedure. This procedure receives the message
identification and substitution text, as well as the name of the program that received it, and a list of valid
1-character responses. The defined procedure is responsible for returning a 1-character code (blank, C, D,
F, or G) indicating whether the COBOL program should continue or not.

Note: All messages issued by the operating system during the running of a COBOL program are
monitored by the COBOL program. Only some of the system messages issued will result in a COBOL
inquiry message.

You can define a different error-handling procedure for each activation group.

Only one ILE error-handling procedure can be active at a time. If an error occurs in the error-handling
procedure, the COBOL program does not call the error-handling procedure again. (In other words,
recursive calls do not occur.) Instead, the inquiry message would be issued as if no error-handling
procedure were defined.

You cannot change the error-handling procedure while it is responding to an error in a COBOL program.

If an error occurs during the calling of the error-handling procedure, an informational message
(LNR7430) is issued, and processing continues as if no error-handling procedure were defined.

The error-handling procedure is defined by the user. The parameters aredescribed under “ILE COBOL
Error-Handling Exit Procedure” on page 28.

Authorities and Locks

None.

Required Parameter Group

New error-handling exit procedure pointer
INPUT; ANYPTR
The pointer to the new error-handling procedure that you want to set.
Current error-handling exit procedure pointer
OUTPUT; ANYPTR
The pointer to the error-handling procedure that was in place before the new error-handling
procedure was set.
Valid values are:

NULL No current error-handling exit procedure was found.

procedure-pointer The pointer to the error-handling procedure.

16 IBM Systems - iSeries: High-Level Language APIs

Error code
I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code
parameter.

Error Messages
Message ID Error Message Text
CPF3C90 E Literal value cannot be changed.
LNR7074 E Error code not valid.
LNR7075 E Error addressing API parameters.
LNR7077 E Procedure reference not valid.

API introduced: V2R2

Top | “High-Level Language APIs,” on page 1 | APIs by category

ILE C/C++ Run-Time Library Functions

The ILE C/C++ run-time library provides functions that can be used when programming ILE C and C++
application programs.

The ILE C/C++ run-time library functions are:

v Access function arguments (va_arg()) accesses the arguments to a function when it takes a fixed
number of required arguments and a variable number of optional arguments.
v Access function arguments (va_end()) accesses the arguments to a function when it takes a fixed
number of required arguments and a variable number of optional arguments.
v Access function arguments (va_start()) accesses the arguments to a function when it takes a fixed
number of required arguments and a variable number of optional arguments.
v Acquire a program device (_Racquire()) acquires the program device specified by the dev parameter
and associates it with the file specified by fp.
v Adjust current file position (rewind()) repositions the file pointer associated with stream to the
beginning of the file.
v Associates stream with file descriptor (fdopen()) associates an input or output stream with the file that
is identified by handle.
v Calculate absolute value of long and long long integer (labs()) produces the absolute value of its long
integer argument n.
v Calculate absolute value of long and long long integer (llabs()) returns the absolute value of its long
long integer operand.
v Calculate arccosine (acos()) calculates the arccosine of x, expressed in radians, in the range 0 to pi.
v Calculate arcsine (asin()) calculates the arcsine of x, in the range -/2 to p /2 radians.
v Calculate arctangent (atan()) calculates the arctangent of x.
v Calculate Arctangent (atan2()) calculate the arctangent of y/x.
v Calculate base 10 logarithm (log10()) calculates the base 10 logarithm of x.
v Calculate cosine (cos()) calculates the cosine of x.
v Calculate error functions (erf()) calculates an error function.
v Calculate error functions (erfc()) computes the value of 1.0 - erf(x).
v Calculate exponential function (exp()) calculates the exponential value of a floating-point argument x (
e^x , where e equals 2.17128128...).

High-Level Language APIs 17

v Calculate floating-point absolute value (fabs()) calculates the absolute value of the floating-point
argument x.
v Calculate floating-point remainder (fmod()) calculates the floating-point remainder of x/y.
v Calculate hyperbolic cosine (cosh()) calculates the hyperbolic cosine of x.
v Calculate hyperbolic sine (sinh()) calculates the hyperbolic sine of x, with x expressed in radians.
v Calculate hyperbolic tangent (tanh()) calculates the hyperbolic tangent of x, where x is expressed in
radians.
v Calculate hypotenuse (hypot) calculates the length of the hypotenuse of a right-angled triangle based
on the lengths of two sides side1 and side2.
v Calculate integer absolute value (abs()) returns the absolute value of an integer argument n.
v Calculate length of wide-character string (wcslen()) computes the number of wide characters in the
string pointed to by string.
v Calculate natural logarithm (log()) calculates the natural logarithm (base e) of x.
v Calculate quotient and remainder (div()) calculates the quotient and remainder of the division of
numerator by denominator.
v Calculate sine (sin()) calculates the sine of x, with x expressed in radians.
v Calculate square root (sqrt()) calculates the nonnegative value of the square root of x.
v Calculate Tangent (tan()) calculates the tangent of x, where x is expressed in radians.
v Change data area (QXXCHGDA()) allows you to change the data area specified by dtaname, starting at
position offset, with the data in the user buffer pointed to by dtaptr of length len.
v Change reserved storage block size (realloc()) changes the size of a previously reserved storage block.
v Change/Add environment variables (putenv()) sets the value of an environment variables by altering
an existing variable or creating a new one.
v Close a file (_Rclose()) closes the file specified by fp.
v Close message catalog (catclose()) closes the previously opened message catalog that is identified by
catd.
v Close stream (fclose()) closes a stream pointed to by stream.
v Commit current record (_Rcommit()) completes the current transaction for the job that calls it and
establishes a new commitment boundary.
v Compare buffers (memcmp()) compares the first count bytes of buf1 and buf2.
v Compare bytes (memicmp()) compares the first cnt bytes of buf1 and buf2 without regard to the case
of letters in the two buffers.
v Compare strings (strcmp()) compares string1 and string2.
v Compare strings (strcoll()) compares two strings using the collating sequence that is specified by the
program’s locale.
v Compare strings (strncmp()) compares string1 and string2 to the maximum of count.
v Compare strings without case sensitivity (strcasecmp()) compares string1 and string2 without
sensitivity to case.
v Compare strings without case sensitivity (strcmpi()) compares string1 and string2 without sensitivity to
case.
v Compare strings without case sensitivity (stricmp()) compares string1 and string2 without sensitivity to
case.
v Compare strings without case sensitivity (strncasecmp()) compares up to count characters of string1
and string2 without sensitivity to case.
v Compare substrings without case sensitivity (strnicmp()) compares, at most, the first n characters of
string1 and string2 without sensitivity to case.
v Compare wide character strings without case sensitivity (_wcsicmp()) compares string1 and string2
without sensitivity to case.

18 IBM Systems - iSeries: High-Level Language APIs

v Compare wide character strings without case sensitivity (_wcsnicmp()) compares up to count
characters of string1 and string2 without sensitivity to case.
v Compare wide-character buffers (wmemcmp()) compares the first n wide characters of the object
pointed to by s1 to the first n wide characters of the object pointed to by s2.
v Compare wide-character strings (wcscmp()) compares two wide-character strings.
v Compare wide-character strings (wcsncmp()) compares up to count wide characters in string1 to
string2.
v Compile regular expression (regcomp()) compiles the source regular expression pointed to by pattern
into an executable version and stores it in the location pointed to by preg.
v Compute power (pow()) calculates the value of x to the power of y.
v Compute time difference (difftime()) computes the difference in seconds between time2 and time1.
v Concatenate strings (strcat()) concatenates string2 to string1 and ends the resulting string with the null
character.
v Concatenate strings (strncat()) appends the first count characters of string2 to string1 and ends the
resulting string with a null character.
v Concatenate wide-character strings (wcscat()) appends a copy of the string pointed to by string2 to the
end of the string pointed to by string1.
v Concatenate wide-character strings (wcsncat()) appends up to count wide characters from string2 to the
end of string1, and appends a wchar_t null character to the result.
v Control buffering (setbuf()) controls buffering for the specified stream, if the operating system supports
user-defined buffers.
v Control buffering (setvbuf()) allows control over the buffering strategy and buffer size for a specified
stream.
v Convert a multibyte character to a wide character (restartable) (mbrtowc()) is the restartable version of
the mbtowc() function.
v Convert a multibyte character to a wide character (restartable) (mbsrtowcs()) converts a sequence of
multibyte characters that begins in the conversion state described by ps from the array indirectly
pointed to by src into a sequence of corresponding wide characters.
v Convert a multibyte string to a wide character string (restartable) (mbstowcs()) determines the length
of the sequence of the multibyte characters pointed to by string.
v Convert a wide character to a multibyte character (restartable) (wcrtomb()) converts a wide character to
a multibyte character.
v Convert character (toascii()) determines to what character c would be mapped to in a 7-bit US-ASCII
locale and returns the corresponding EBCDIC encoding in the current locale.
v Convert character case (tolower()) converts the uppercase letter C to the corresponding lowercase letter.
v Convert character case (toupper()) converts the lowercase letter c to the corresponding uppercase letter.
v Convert character string to double (strtod()) converts a character string to a double-precision value.
v Convert character string to float (atof()) converts a character string to a double-precision floating-point
value.
v Convert character string to integer (atoi()) converts a character string to an integer value.
v Convert character string to long and long long integer (strtol()) converts a character string to a long
integer value.
v Convert character string to long and long long integer (strtoll()) converts a character string to a long
long integer value.
v Convert character string to long or long long integer (atol()) converts a character string to a long value.
v Convert character string to long or long long integer (atoll()) converts a character string to a long long
value.
v Convert character string to unsigned long and unsigned long long integer (strtoul()) converts a
character string to an unsigned long integer value.

High-Level Language APIs 19

v Convert character string to unsigned long and unsigned long long integer (strtoull()) converts a
character string to an unsigned long long integer value.
v Convert date/time to string (strftime()) places bytes into the array pointed to by s as controlled by the
string pointed to by format.
v Convert double to packed decimal (QXXDTOP()) converts the double value specified in value to a
packed decimal number with digits total digits, and fraction fractional digits.
v Convert double to zoned decimal (QXXDTOZ()) converts the double value specified in value to a
zoned decimal number with digits total digits, and fraction fractional digits.
v Convert floating-point to string (_gcvt()) converts a floating-point value to a character string pointed to
by buffer.
v Convert integer to packed decimal (QXXITOP()) converts the integer specified in value to a packed
decimal number with digits total digits, and fraction fractional digits.
v Convert integer to string (_itoa()) converts the digits of the given value to a character string that ends
with a null character and stores the result in string.
v Convert integer to zoned decimal (QXXITOZ()) converts the integer specified in value to a zoned
decimal number with digits total digits, and fraction fractional digits.
v Convert local time (mktime()) converts local time, stored as a tm structure pointed to by time, into a
time_t structure suitable for use with other time functions.
v Convert long integer to string (_ltoa()) converts the digits of the given long integer value to a character
string that ends with a null character and stores the result in string.
v Convert monetary value to string (strfmon()) places characters into the array pointed to by s as
controlled by the string pointed to by format.
v Convert multibyte character to a wide character (mbtowc()) determines the length of the multibyte
character pointed to by string.
v Convert packed decimal to double (QXXPTOD()) converts a packed decimal number to a double.
v Convert packed decimal to integer (QXXPTOI()) converts a packed decimal number to an integer.
v Convert single byte to wide character (btowc()) converts the single byte value c to the wide-character
representation of c.
v Convert string to date/time (strptime()) converts the character string pointed to by buf to values that
are stored in the tm structure pointed to by tm, using the format specified by format.
v Convert time (gmtime()) breaks down the time value, in seconds, and stores it in a tm structure,
defined in <time.h>.
v Convert time (localtime()) converts a time value, in seconds, to a structure of type tm.
v Convert time (restartable) (gmtime_r()) breaks down the time value, in seconds, and stores it in a tm
structure, defined in <time.h>.
v Convert time (restartable) (localtime_r()) converts a time value, in seconds, to a structure of type tm.
v Convert time to a character string (restartable) (asctime_r()) converts time, stored as a structure pointed
to by tm, to a character string.
v Convert time to a character string (restartable) (ctime_r()) is the restartable version of the ctime()
function.
v Convert time to character string (asctime()) converts time, stored as a structure pointed to by time, to a
character string.
v Convert time to character string (ctime()) converts the time value pointed to by time to local time in
the form of a character string.
v Convert to formatted date and time (wcsftime()) converts the time and date specification in the timeptr
structure into a wide-character string.
v Convert unsigned long integer to string (_Ultoa()) converts the digits of the given unsigned long value
to a character string that ends with a null character and stores the result in string.

20 IBM Systems - iSeries: High-Level Language APIs

v Convert wide character case (towlower()) converts the lowercase character wc to the corresponding
uppercase letter.
v Convert wide character case (towupper()) converts the uppercase character wc to the corresponding
lowercase letter.
v Convert wide character string to date/time (wcsptime()) converts the wide character string pointed to
by buf to values that are stored in the tm structure pointed to by tm, using the format specified by
format.
v Convert wide character string to long and long long integer (wcstol()) converts the initial portion of the
wide-character string pointed to by nptr to a long integer value.
v Convert wide character string to long and long long integer (wcstoll()) converts a wide-character string
to a long long integer.
v Convert wide character string to multibyte string (restartable) (wcsrtombs()) converts a sequence of
wide characters from the array indirectly pointed to by src into a sequence of corresponding multibyte
characters that begins in the shift state described by ps.
v Convert wide character string to unsigned long and unsigned long long integer (wcstoul()) converts the
initial portion of the wide-character string pointed to by nptr to an unsigned long integer value.
v Convert wide character string to unsigned long and unsigned long long integer (wcstoull()) converts a
wide-character string to an unsigned long long integer.
v Convert wide character to byte (wctob()) determines whether wc corresponds to a member of the
extended character set, whose multibyte character has a length of 1 byte when in the initial shift state.
v Convert wide character to multibyte character (wctomb()) converts the wchar_t value of character into
a multibyte array pointed to by string.
v Convert wide-character string to double (wcstod()) converts the initial portion of the wide-character
string pointed to by nptr to a double value.
v Convert wide-character string to multibyte string (wcstombs()) converts the wide-character string
pointed to by string into the multibyte array pointed to by dest.
v Convert zoned decimal to double (QXXZTOD()) converts to a double, the zoned decimal number (with
digits total digits, and fraction fractional digits) pointed to by zptr.
v Convert zoned decimal to integer (QXXZTOI()) converts to an integer, the zoned decimal number (with
digits total digits, and fraction fractional digits) pointed to by zptr.
v Copy bytes (memcpy()) copies count bytes of src to dest.
v Copy bytes (memmove()) copies count bytes of src to dest.
v Copy strings (strcpy()) copies string2, including the ending null character, to the location that is
specified by string1.
v Copy strings (strncpy()) copies count characters of string2 to string1.
v Copy wide-character buffer (wmemcpy()) copies n wide characters from the object pointed to by s2 to
the object pointed to by s1.
v Copy wide-character buffer (wmemmove()) copies n wide characters from the object pointed to by s2
to the object pointed to by s1.
v Copy wide-character strings (wcscpy()) copies the contents of string2 (including the ending wchar_t
null character) into string1.
v Copy wide-character strings (wcsncpy()) copies up to count wide characters from string2 to string1.
v Create temporary file (tmpfile()) creates a temporary binary file.
v Delete a record (_Rdelete()) deletes the record that is currently locked for update in the file specified by
fp.
v Delete file (remove()) deletes the file specified by filename.
v Determine amount of teraspace memory used (_C_TS_malloc_info()) determines the amount of
teraspace memory used and returns the informatoin within the given output_record structure.

High-Level Language APIs 21

v Determine amount of teraspace memory used (with optional dumps and verification)
(_C_TS_malloc_debug()) determines the amount of teraspace memory used and returns the information
within the given output_record structure.
v Determine current time (time()) determines the current calendar time, in seconds.
v Determine file handle (fileno()) determines the file handle that is currently associated with stream.
v Determine length of a multibyte character (mblen()) determines the length in bytes of the multibyte
character pointed to by string.
v Determine length of a multibyte character (restartable) (mbrlen()) determines the length of a multibyte
character.
v Determine processor time (clock()) returns an approximation of the processor time used by the
program since the beginning of an implementation-defined time-period that is related to the process
invocation.
v Determine stream orientation (fwide()) determines the orientation of the stream pointed to by stream.
v Determine string length (strlen()) determines the length of string excluding the ending null character.
v Determine the display width of a wide character (wcwidth()) determines the number of printing
positions that a graphic representation of wc occupies on a display device.
v Determine the display width of a wide character string (wcswidth()) determines the number of printing
positions that a graphic representation of n wide characters in the wide string pointed to by wcs
occupies on a display device.
v Duplicate string (strdup()) reserves storage space for a copy of string by calling malloc.
v End program (exit()) returns control to the host environment from the program.
v Execute a command (system()) passes the given string to the CL command processor for processing.
v Execute compiled regular expression (regexec()) compares the null-ended string against the compiled
regular expression preg to find a match between the two.
v Find characters in string (strpbrk()) locates the first occurrence in the string pointed to by string1 of
any character from the string pointed to by string2.
v Find integer <= argument (floor()) calculates the largest integer that is less than or equal to x.
v Find integer >= argument (ceil()) computes the smallest integer that is greater than or equal to x.
v Find offset of first character match (strcspn()) finds the first occurrence of a character in string1 that
belongs to the set of characters that is specified by string2.
v Find offset of first non-matching character (strspn()) finds the first occurrence of a character in string1
that is not contained in the set of characters that is specified by string2.
v Find offset of first non-matching wide character (wcsspn()) computes the number of wide characters in
the initial segment of the string pointed to by string1, which consists entirely of wide characters from
the string pointed to by string2.
v Find offset of first wide-character match (wcscspn()) determines the number of wchar_t characters in
the initial segment of the string pointed to by string1 that do not appear in the string pointed to by
string2.
v Force the end-of-data (_Rfeod()) forces an end-of-data condition for a device or member associated
with the file specified by fp.
v Force the end-of-file (_Rfeov()) forces an end-of-volume condition for a tape file that is associated with
the file that is specified by fp.
v Format and write wide characters to buffer (swprintf()) formats and stores a series of wide characters
and values into the wide-character buffer wcsbuffer.
v Format and write wide characters to buffer (vswprintf()) formats and stores a series of wide characters
and values in the buffer wcsbuffer.
v Format argument data as wide characters and print (vwprintf()) is equivalent to the wprintf() function,
except that the variable argument list is replaced by arg, which the va_start macro (and possibly
subsequent va_arg calls) will have initialized.

22 IBM Systems - iSeries: High-Level Language APIs

v Format argument data as wide characters and write to a stream (vfwprintf()) is equivalent to the
fwprintf() function, except that the variable argument list is replaced by arg, which the va_start macro
(and possibly subsequent va_arg calls) will have initialized.
v Format data as wide characters and print (wprintf()) is equivalent to fwprintf(stdout,format,...).
v Format data as wide characters and write to a stream (fwprintf()) writes output to the stream pointed
to by stream, under control of the wide string pointed to by format.
v Free memory for regular expression (regfree()) frees any memory that was allocated by the regcomp()
function to implement the regular expression preg.
v Gamma function (gamma()) computes the natural logarithm of the absolute value of G(x) (ln(
v Get current position (ftell()) finds the current position of the file associated with stream.
v Get current position (ftello()) finds the current position of the file associated with stream.
v Get device attributes (_Rdevatr()) returns a pointer to a copy of the device attributes feedback area for
the file pointed to by fp, and the device specified by dev.
v Get exception data (_GetExcData()) returns information about the current exception from within a C
signal handler.
v Get file position (fgetpos()) stores the current position of the file pointer that is associated with stream
into the object pointed to by pos.
v Get handle for character mapping (wctrans()) constructs a value with type wctrans_t.
v Get handle for character property classification (wctype()) determines values of wctype_t according to
rules of the coded character set that are defined by character type information in the program’s locale
(category LC_CTYPE).
v Get wide character from stdin (getwchar()) reads the next multibyte character from stdin, converts it to
a wide character, and advances the associated file position indicator for stdin.
v Handle interrupt signals (signal()) allows a program to choose one of several ways to handle an
interrupt signal from the operating system or from the raise() function.
v Handle to a C session (_C_Get_Ssn_Handle()) Returns a handle to the C session for use with Dynamic
Screen Manager (DSM) APIs.
v Language collation string comparison (wcscoll()) compares the wide-character strings pointed to by
wcs1 and wcs2, both interpreted as appropriate to the LC_COLLATE category of the current locale.
v Locate last occurrence of character in string (strrchr()) finds the last occurrence of c (converted to a
character) in string.
v Locate last occurrence of wide character in string (wcsrchr()) locates the last occurrence of character in
the string pointed to by string.
v Locate substring (strstr()) finds the first occurrence of string2 in string1.
v Locate wide character in wide-character buffer (wmemchr()) locates the first occurrence of c in the
initial n wide characters of the object pointed to by s.
v Locate wide characters in string (wcspbrk()) locates the first occurrence in the string pointed to by
string1 of any wide character from the string pointed to by string2.
v Locate wide-character substring (wcsstr()) locates the first occurrence of wcs2 in wcs1.
v Locate wide-character substring (wcswcs()) locates the first occurrence of string2 in the wide-character
string pointed to by string1.
v Multiply by a power of two (ldexp()) calculates the value of x *(2^exp).
v Obtain I/O feedback information (_Riofbk()) returns a pointer to a copy of the I/O feedback area for
the file that is specified by fp.
v Obtain open feedback information (_Ropnfbk()) returns a pointer to a copy of the open feedback area
for the file that is specified by fp.
v Open a record file for I/O operations (_Ropen()) opens the record file specified by filename according
to the mode parameter, which may be followed by optional parameters, if the varparm keyword
parameter is specified in the mode parameter.

High-Level Language APIs 23

v Open files (fopen()) opens the file that is specified by filename.
v Open files (wfopen()) accepts file name and mode as wide characters and assumes CCSID 13488 if
neither CCSID nor codepage keyword is specified.
v Open message catalog (catopen()) opens a message catalog, which must be done before a message can
be retrieved.
v Perform long and long long division (ldiv()) calculates the quotient and remainder of the division of
numerator by denominator.
v Perform long and long long division (lldiv()) computes the quotient and remainder of the numerator
parameter by the denominator parameter.
v Position a record (_Rlocate()) positions to the record in the file associated with fp and specified by the
key, klen_rrn and opts parameters.
v Preserve environment (setjmp()) saves a stack environment that can subsequently be restored by the
longjmp() function.
v Print argument data (vprintf()) formats and prints a series of characters and values to stdout.
v Print argument data to buffer (vsnprintf()) formats and stores a series of characters and values in the
buffer target-string.
v Print argument data to stream (vfprintf()) formats and writes a series of characters and values to the
output stream.
v Print error message (perror()) prints an error message to stderr.
v Print formatted characters (printf()) formats and prints a series of characters and values to the standard
output stream stdout.
v Print formatted data to buffer (snprintf()) formats and stores a series of characters and values in the
array buffer.
v Print formatted data to buffer (sprintf()) formats and stores a series of characters and values in the
array buffer.
v Produce temporary file name (tmpnam()) produces a valid file name that is not the same as the name
of any existing file.
v Provide information on last I/O operation (_Rupfb()) updates the feedback structure associated with
the file specified by fp with information about the last I/O operation.
v Push character onto input stream (ungetc()) pushes the unsigned character c back onto the given input
stream.
v Push wide character onto input stream (ungetwc()) pushes the wide character wc back onto the input
stream.
v Read a character (fgetc()) reads a single unsigned character from the input stream at the current
position and increases the associated file pointer, if any, so that it points to the next character.
v Read a character (getc()) reads a single character from the current stream position and advances the
stream position to the next character.
v Read a character (getchar()) reads a single character from the current stream position and advances the
stream position to the next character.
v Read a line (gets()) reads a line from the standard input stream stdin and stores it in buffer.
v Read a record by key (_Rreadk()) reads the record in the keyed access path that is currently being used
for the file that is associated with fp.
v Read a record by relative record number (_Rreadd()) reads the record that is specified by rrn in the
arrival sequence access path for the file that is associated with fp.
v Read a string (fgets()) reads characters from the current stream position up to and including the first
new-line character (), up to the end of the stream, or until the number of characters read is equal to
n-1, whichever comes first.
v Read data (scanf()) reads data from the standard input stream stdin into the locations that is given by
each entry in argument-list.

24 IBM Systems - iSeries: High-Level Language APIs

v Read data (sscanf()) reads data from buffer into the locations that are given by argument-list.
v Read data from stream using wide character (fwscanf()) reads input from the stream pointed to by
stream, under control of the wide string pointed to by format.
v Read data using wide-character format string (wscanf()) is equivalent to the fwscanf() function with the
argument stdin interposed before the arguments of the wscanf() function.
v Read formatted data (fscanf()) reads data from the current position of the specified stream into the
locations that are given by the entries in argument-list, if any.
v Read formatted data (vfscanf()) reads data from a stream into locations specified by a variable number
of arguments.
v Read formatted data (vscanf()) reads data from stdin into locations specified by a variable number of
arguments.
v Read formatted data (vsscanf()) reads data from a buffer into locations specified by a variable number
of arguments.
v Read formatted wide character data (vfwscanf()) reads wide data from a stream into locations specified
by a variable number of arguments.
v Read formatted wide character data (vswscanf()) reads wide data from a buffer into locations specified
by a variable number of arguments.
v Read formatted wide character data (vwscanf()) reads wide data from stdin into locations specified by
a variable number of arguments.
v Read from an invited device (_Rreadindv()) reads data from an invited device.
v Read items (fread()) reads up to count items of size length from the input stream and stores them in
the given buffer.
v Read the first record (_Rreadf()) reads the first record in the access path that is currently being used for
the file specified by fp.
v Read the last record (_Rreadl()) reads the last record in the access path currently being used for the file
specified by fp.
v Read the next changed record in a subfile (_Rreadnc()) reads the next changed record from the current
position in the subfile that is associated with fp.
v Read the next record (_Rreadn()) reads the next record in the access path that is currently being used
for the file that is associated with fp.
v Read the previous record (_Rreadp()) reads the previous record in the access path that is currently
being used for the file that is associated with fp.
v Read the same record (_Rreads()) reads the current record in the access path that is currently being
used for the file that is associated with fp.
v Read wide character data (swscanf()) specifies a wide string from which the input is to be obtained,
rather than from a stream.
v Read wide character from stream (fgetwc()) reads the next multibyte character from the input stream
pointed to by stream, converts it to a wide character, and advances the associated file position indicator
for the stream (if defined).
v Read wide character from stream (getwc()) reads the next multibyte character from stream, converts it
to a wide character, and advances the associated file position indicator for stream.
v Read wide-character string from stream (fgetws()) reads at most one less than the number of wide
characters specified by n from the stream pointed to by stream.
v Record program ending function (atexit()) records the function, pointed to by func, that the system
calls at normal program end.
v Redirect open files (freopen()) closes the file that is currently associated with stream and reassigns
stream to the file that is specified by filename.
v Release a program device (_Rrelease()) releases the program device that is specified by dev from the
file that is associated with fp.

High-Level Language APIs 25

v Release a record lock (_Rrlslck()) releases the lock on the currently locked record for the file specified
by fp.
v Release storage blocks (free()) frees a block of storage.
v Rename file (rename()) renames the file specified by oldname to the name given by newname.
v Reposition file position (fseek()) changes the current file position that is associated with stream to a
new location within the file.
v Reposition file position (fseeko()) changes the current file position that is associated with stream to a
new location within the file.
v Reserve and initialize storage (calloc()) reserves storage space for an array of num elements, each of
length size bytes.
v Reserve Storage Block (malloc()) reserves a block of storage of size bytes.
v Reset error indicators (clearerr()) resets the error indicator and end-of-file indicator for the specified
stream.
v Restore stack environment (longjmp()) restores a stack environment previously saved in env by the
setjmp()function.
v Retrieve a message from a message catalog (catgets()) retrieves message msg_id, in setset_id from the
message catalog that is identified by catd.
v Retrieve data area (QXXRTVDA()) retrieves a copy of the data area specified by dtaname starting at
position offset with a length of len.
v Retrieve information from the environment (localeconv()) sets the components of a structure having
type struct lconv to values appropriate for the current locale.
v Retrieve locale information (nl_langinfo()) retrieves from the current locale the string that describes the
requested information specified by item.
v Retrieve wide locale information (wcslocaleconv()) sets the components of a structure having type
structure wcslconv to values appropriate for the current locale.
v Return error message for regular expression (regerror()) finds the description for the error code errcode
for the regular expression preg.
v Roll back commitment control changes (_Rrollbck()) reestablishes the last commitment boundary as the
current commitment boundary.
v Search arrays (bsearch()) performs a binary search of an array of num elements, each of size bytes.
v Search buffer (memchr()) searches the first count bytes of buf for the first occurrence of c converted to
an unsigned character.
v Search for character (strchr()) finds the first occurrence of a character in a string.
v Search for environment variables (getenv()) searches the list of environment variables for an entry
corresponding to varname.
v Search for wide character (wcschr()) searches the wide-character string for the occurrence of character.
v Send signal (raise()) sends the signal sig to the running program.
v Separate floating-point value (frexp()) breaks down the floating-point value x into a term m for the
mantissa and another term n for the exponent.
v Separate floating-point value (modf()) breaks down the floating-point value x into fractional and
integral parts.
v Set bytes to value (memset()) sets the first count bytes of dest to the value c.
v Set characters in string (strnset()) sets, at most, the first n characters of string to c (converted to a char).
If n is greater than the length of string, the length of string is used in place of n.
v Set characters in string (strset()) sets all characters of string to c.
v Set default program device (_Rpgmdev()) sets the current program device for the file that is associated
with fp to dev.
v Set file position (fsetpos()) moves any file position that is associated with stream to a new location
within the file according to the value pointed to by pos.

26 IBM Systems - iSeries: High-Level Language APIs

v Set locale (setlocale()) changes or queries variables that are defined in the <locale.h> include file, that
indicate location.
v Set pointer to run-time error message (strerror()) maps the error number in errnum to an error message
string.
v Set seed for rand() function (srand()) sets the starting point for producing a series of pseudo-random
integers.
v Set separate indicator area (_Rindara()) registers indic_buf as the separate indicator area to be used by
the file specified by fp.
v Set the record format name (_Rformat()) sets the record format to fmt for the file specified by fp.
v Set wide character buffer to a value (wmemset()) copies the value of c into each of the first n wide
characters of the object pointed to by s.
v Solve equations (Bessel Functions) solves certain types of differential equations.
v Sort array (qsort()) sorts an array of num elements, each of width bytes in size.
v Stop a Program (abort()) causes an abnormal end to the program and returns control to the host
environment.
v Test end-of-file indicator (feof()) indicates whether the end-of-file flag is set for the given stream.
v Test for ASCII value (isascii()) tests if an EBCDIC character, in the current locale, is a valid 7-bit
US-ASCII character.
v Test for blank or tab character (isblank()) tests if a character is either the EBCDIC space or EBCDIC tab
character.
v Test for character property (iswctype()) determines whether the wide character wc has the property
wc_prop.
v Test for read/write errors (ferror()) tests for an error in reading from or writing to the given stream.
v Test integer value (isalnum()) tests a character with an integer value.
v Test integer value (isxdigit()) tests a character with an integer value.
v Test state object for initial state (mbsinit()) specifies whether the pointed to mbstate_t object describes
an initial conversion state.
v Test wide integer value (iswalnum()) tests a given wide integer value.
v Test wide integer value (iswxdigit()) tests a given wide integer value.
v Tokenize string (strtok()) reads string1 as a series of zero or more tokens, and string2 as the set of
characters serving as delimiters of the tokens in string1.
v Tokenize string (restartable) (strtok_r()) reads string as a series of zero or more tokens, and seps as the
set of characters serving as delimiters of the tokens in string.
v Tokenize wide-character string (wcstok()) reads wcs1 as a series of zero or more tokens and wcs2 as the
set of wide characters serving as delimiters for the tokens in wcs1.
v Transform a wide-character string (wcsxfrm()) transforms the wide-character string pointed to by wcs2
to values which represent character collating weights and places the resulting wide-character string
into the array pointed to by wcs1.
v Transform string (strxfrm()) transforms the string pointed to by string2 and places the result into the
string pointed to by string1.
v Translate wide character (towctrans()) maps the wide character wc using the mapping that is described
by desc.
v Update a record (_Rupdate()) updates the record that is currently locked for update in the file that is
specified by fp.
v Verify condition (assert()) prints a diagnostic message to stderr and aborts the program if expression is
false (zero).
v Write a character (putc()) converts c to unsigned char and then writes c to the output stream at the
current position.

High-Level Language APIs 27

v Write a character (putchar()) converts c to unsigned char and then writes c to the output stream at the
current position.
v Write a record directly (_Rwrited()) writes a record to the file associated with fp at the position
specified by rrn.
v Write a string (puts()) writes the given string to the standard output stream stdout; it also appends a
new-line character to the output.
v Write and read a record (_Rwriterd()) performs a write and then a read operation on the file that is
specified by fp.
v Write and read a record (separate buffers) (_Rwrread()) performs a write and then a read operation on
the file that is specified by fp.
v Write buffer to file (fflush()) causes the system to empty the buffer that is associated with the specified
output stream, if possible.
v Write character (_fputchar()) writes the single character c to the stdout stream at the current position.
v Write character (fputc()) converts c to an unsigned char and then writes c to the output stream at the
current position and advances the file position appropriately.
v Write formatted data to a stream (fprintf()) formats and writes a series of characters and values to the
output stream.
v Write items (fwrite()) writes up to count items, each of size bytes in length, from buffer to the output
stream.
v Write string (fputs()) copies string to the output stream at the current position.
v Write the next record (_Rwrite()) appends a record to the file specified by fp.
v Write wide character (fputwc()) converts the wide character wc to a multibyte character and writes it to
the output stream pointed to by stream at the current position.
v Write wide character (putwc()) converts the wide character wc to a multibyte character, and writes it to
the stream at the current position.
v Write wide character to stdout (putwchar()) converts the wide character wc to a multibyte character
and writes it to stdout.
v Write wide-character string (fputws()) converts the wide-character string wcs to a multibyte-character
string and writes it to stream as a multibyte-character string.

Top | “High-Level Language APIs,” on page 1 | APIs by category

REXX/400 Functions

REXX/400 Programmer’s Guide provides information about programming with REXX/400.

REXX/400 Reference gives detailed descriptions of REXX/400 functions.

Top | “High-Level Language APIs,” on page 1 | APIs by category

Exit Programs
These are the Exit Programs for this category.

ILE COBOL Error-Handling Exit Procedure

Required Parameter Group:

1 COBOL message identification Input Char(7)

28 IBM Systems - iSeries: High-Level Language APIs

 2 Valid responses to message Input Char(6)
3 Name of program issuing error Input Char(20)
4 System message causing COBOL message Input Char(7)
5 Length of passed message text Input Binary(4)
6 Return code Output Char(1)
7 Message text Input Char(*)
8 Module name Input Char(10)
9 COBOL program name Input Char(256)

This is a user-defined program that acts as an error handler for an ILE COBOL/400 program. Use the Set
COBOL Error Handler (QlnSetCobolErrorHandler) API to establish this relationship between the two
programs.

Authorities and Locks

None.

Required Parameter Group

COBOL message identification
INPUT; CHAR(7)
A 3-character prefix followed by a 4-character number.
Valid responses to message
INPUT; CHAR(6)
The list of valid 1-character responses. This list is variable in length and consists of uppercase
letters in alphabetical order. The list always ends with a space.
The following are examples of lists of valid responses:

CG
CDFG

Name of program issuing error

INPUT; CHAR(20)
The qualified name of the ILE COBOL/400 program that issued the error.
The 20 characters of this parameter are:

1-10 The name of the program object.

The valid value is:
program-name
The name of the program object.

11-20 The library where the program object existed.

The valid value is:
library-name
The library where the program object existed.

System message causing COBOL message

INPUT; CHAR(7)
Some COBOL error messages are issued because of error messages received from the system. This
parameter identifies such system messages.
High-Level Language APIs 29
 Valid values are:

*NONE No system message is available.

message-id A 3-character message prefix followed by a 4-character number.

Length of passed message text

INPUT; BINARY(4)
If the original message was a system message, the substitution text for the system message is
passed. In the absence of an original system message, Parameter 4 has a value of *NONE, and the
substitution text for the COBOL message is passed.
Return code
OUTPUT; CHAR(1)
Must be one of the values specified in Parameter 2, or a space. If the value is not one of these, a
response of a space is assumed.
Valid values are:

blank Issue the COBOL message that was passed to the error-handling program.
G Continue running the COBOL program.
C End the current COBOL run unit.
D Same as C, but produce a formatted dump of user-defined COBOL variables.
F Same as D, but also dump COBOL’s file-related internal variables.

Message text
INPUT; CHAR(*)
The substitution text of the message. Its length is determined by Parameter 5.
Module name
INPUT; CHAR(10)
The module within the program object that issued the error.
COBOL program name
INPUT; CHAR(256)
The name of the COBOL program, from the PROGRAM-ID paragraph, that issued the error.

Exit program introduced: V3R2

Top | “High-Level Language APIs,” on page 1 | APIs by category

OPM COBOL Error-Handling Exit Program

Required Parameter Group:

1 COBOL message identification Input Char(7)

2 Valid responses to message Input Char(6)
3 Name of program issuing error Input Char(20)
4 System message causing COBOL message Input Char(7)
5 Message text Input Char(*)
6 Length of passed message text Input Binary(4)
7 Return code Output Char(1)

This is a user-defined program that acts as an error handler for an OPM COBOL program. Use the Set
COBOL Error Handler (QLRSETCE) API to establish this relationship between the two programs.

30 IBM Systems - iSeries: High-Level Language APIs

Authorities and Locks
None.

Required Parameter Group

COBOL message identification
INPUT; CHAR(7)
A 3-character prefix followed by a 4-character number.
Valid responses to message
INPUT; CHAR(6)
The list of valid 1-character responses. The list is variable in length and consists of uppercase
letters in alphabetical order. The list always ends with a space.
Examples of lists of valid responses:

CG
CDFG

Name of program issuing error

INPUT; CHAR(20)
The qualified name of the COBOL/400 program that issued the error.
The 20 characters of this parameter are:

1-10 The name of the program object.

The valid value is:
program-name
The name of the program object.
The library where the program object existed.
The valid value is:
library-name
The library where the program object existed.

System message causing COBOL message

INPUT; CHAR(7)
Some COBOL error messages are issued because of error messages received from the system. This
parameter identifies such system messages.
Valid values are:

*NONE No system message is available.

message-id A 3-character message prefix followed by a 4-character number.

Message text
INPUT; CHAR(*)
The substitution text of the message, its length determined by Parameter 6.
Length of passed message text
INPUT; Binary(31)
If the original message was a system message, the substitution text for the system message is
passed. In the absence of an original system message, Parameter 4 has a value of *NONE, and the
substitution text for the COBOL message is passed.

High-Level Language APIs 31

Return code
OUTPUT; CHAR(1)
Must be one of the values specified in Parameter 2, or a space. If the value is not one of these, a
response of a space is assumed.
Valid values are:

blank Issue the COBOL message that was passed to the error-handling program.
G Continue running the COBOL program.
C End the current COBOL run unit.
D Same as C, but produce a formatted dump of user-defined COBOL variables.
F Same as D, but also dump COBOL’s file-related internal variables.

Exit Program Introduced: V3R2

Top | “High-Level Language APIs,” on page 1 | APIs by category

Concepts
These are the concepts for this category.

Record Types
This section describes the information contained in all the different record types. Typically a compiler
writes records and an application reads them.

Names, field types and other information passed through the different record types are not validated and
no authority is checked by QLYWRTBI. The QLYWRTBI API assumes that all that validation and
checking has been done.

There are the following record types:

v Processor member start record
v Processor object start record
v Normal processor end record
v Normal processor end call next record
v Normal multiple end record
v Abnormal processor end record
v Include record
v File reference record
v Module reference record
v Service program reference record
v Bind directory reference record
v Record format reference record
v Field reference record
v Message reference record
v External reference error record
v Object already exists error record
v Start of new program record

The following table shows the records that can be written by each compiler.

32 IBM Systems - iSeries: High-Level Language APIs

All fields where information is not available to put in these records should be filled with blanks.

The following is true for the Library specified fields for all records and compilers:
v When *CURLIB is specified for the Library specified fields, *CURLIB is passed.
v When *LIBL is specified for the Library specified fields, or implied by not being specified, *LIBL is
passed.

Notes and restrictions are explained in the footnotes following the tables.

Record Types and Processors (Part 1)

DDS:
CRTPF
RPG/400(R): COBOL/400(R):CLD: CRTLF CL: CMD:
Record Type Record ID
CRTRPGPGMCRTCBLPGM CRTCLD CRTDSPF CRTCLPGM CRTCMD
CRTICFF
CRTPRTF
Processor ’01’ X(1, 3) X X(1, 3) X X(1, 3, 5) X(1)
member start
Processor ’50’
object start
Normal ’20’ X X X X X(5) X
processor
end
Normal ’21’
processor
end call next
Normal ’65’
multiple end
record
Abnormal ’30’ X X X X X(5) X
processor
end
Include ’02’ X(11) X
File reference ’03’ X X X X(1, 5)
Module ’55’
reference
Service ’60’
program
reference
Bind ’75’
directory
reference
Record ’04’ X X X X(1, 5)
format
reference
Field ’05’ X(2)
reference
Message ’06’ X(2, 9) X(1, 2, 6, 9)
reference

High-Level Language APIs 33

 DDS:
CRTPF
RPG/400(R): COBOL/400(R):CLD: CRTLF CL: CMD:
Record Type Record ID
CRTRPGPGMCRTCBLPGM CRTCLD CRTDSPF CRTCLPGM CRTCMD
CRTICFF
CRTPRTF
External ’15’ X(10) X X(10) X(1, 4, 5)
reference
error
Object ’16’ X
already
exists error
Start of new ’40’ X(20)
program

Record Types and Processors (Part 2)

DB2(R) UDB ILE DB2 UDB

ILE
for ILE RPG/400: ILE C: ILE CL: for iSeries:
Record (TM) COBOL/400:
Record ID iSeries : CRTRPGMOD CRTCMOD CRTCLMOD CRTSQLRPGI
Type CRTCBLMOD
CRTSQLRPG CRTBNDRPG CRTBNDC CRTBNDCL CRTSQLCBLI
CRTBNDCBL
CRTSQLCBL CRTSQLCI
Processor ’01’ X(1) X(1, 3) X X(3) X(1, 3) X(1)
member
start
Processor ’50’
object start
Normal ’20’ X X X X X X
processor
end
Normal ’21’ X X(14) X(14) X(14) X(14) X
processor
end call
next
Normal ’65’
multiple
end record
Abnormal ’30’ X X X X X X
processor
end
Include ’02’ X(1, 7) X(11) X X(8, 12) X(1, 7)
File ’03’ X(1) X X X X(1) X(1)
reference
Module ’55’
reference
Service ’60’
program
reference
Bind ’75’ X
directory
reference

34 IBM Systems - iSeries: High-Level Language APIs

 DB2(R) UDB ILE DB2 UDB
ILE
for ILE RPG/400: ILE C: ILE CL: for iSeries:
Record (TM) COBOL/400:
Record ID iSeries : CRTRPGMOD CRTCMOD CRTCLMOD CRTSQLRPGI
Type CRTCBLMOD
CRTSQLRPG CRTBNDRPG CRTBNDC CRTBNDCL CRTSQLCBLI
CRTBNDCBL
CRTSQLCBL CRTSQLCI
Record ’04’ X(1) X X X X(1) X(1)
format
reference
Field ’05’
reference
Message ’06’
reference
External ’15’ X(1) X(10) X X(10, 13) X(1, 4) X(1)
reference
error
Object ’16’
already
exists error
Start of ’40’ X(20) X(20)
new
program

Record Types and Processors (Part 3)

ILE UDT:
ILE UIM: UDT:
Record Type Record ID SRVPGM: CRTMNU SYSTYPE
CRTPGM CRTPNLGRP member
CRTSRVPGM (*NONE)
Processor ’01’ X(18) X X(17) X
member start
Processor ’50’ X(16) X(19)
object start
Normal ’20’ X X X X X
processor
end
Normal ’21’ X
processor
end call next
Normal ’65’ X(19)
multiple end
record
Abnormal ’30’ X X X X X(19) X
processor
end
Include ’02’ X X X
File reference ’03’ X
Module ’55’ X X
reference
Service ’60’ X X
program
reference

High-Level Language APIs 35

 ILE UDT:
ILE UIM: UDT:
Record Type Record ID SRVPGM: CRTMNU SYSTYPE
CRTPGM CRTPNLGRP member
CRTSRVPGM (*NONE)
Bind ’75’ X X
directory
reference
Record ’04’ X
format
reference
Field ’05’ X
reference
Message ’06’ X X X
reference
External ’15’ X(15) X(15) X X X
reference
error
Object ’16’ X
already
exists error
Start of new ’40’ X
program

Notes and Restrictions for the Above Tables:

1. If *CURLIB is specified for the Library specified fields (this includes the Source library specified field on
the Processor member start record), the resolved library name is passed instead of *CURLIB.
2. If *LIBL is specified for the Library specified fields, or implied by not being specified, the resolved
library name is passed instead of *LIBL.
3. If *CURLIB is specified for the Target library field, the resolved library name is passed instead of
*CURLIB.
4. For most Used fields, when a file being referenced on the DCLF command cannot be found, CL puts
blanks in this field. There is no actual file or library name when the file is not found.
5. For all fields marked Reserved, CL initializes them to hex zeros. However, fields that are not reserved
are set to blanks when they do not apply and are defined as characters. For example, Target member
on the Processor member start record does not have meaning for the CL compiler and is initialized
to blanks.
6. Message reference records are written only for messages specified on the PROMPT parameter of the
PARM, ELEM, or QUAL command definition statement.
7. The SQL compilers do not write include records for the following statements:
EXEC SQL INCLUDE SQLCA
EXEC SQL INCLUDE SQLDA
These statements are not true includes in the sense that the SQL compiler does not read source from
another member or source file.
8. The ILE C compiler does not write API Include records for system include files. File names enclosed
in angle brackets, (< ... >), designate system include files. File names enclosed in double quotation
marks, (″ ... ″), designate user include files.
9. The Message file used and Library used fields are always blank.
10. If *LIBL is specified in the source, or implied by not being specified (Library specified is *LIBL), the
Library used field is set to *LIBL because no specific library can be determined if the file is not found
in the library list.

36 IBM Systems - iSeries: High-Level Language APIs

11. The RPG/400 compiler puts *LIBL in the Library specified field if it is not already specified, and
QRPGSRC in the File specified field if it is not already specified.
The ILE RPG/400 compiler puts *LIBL in the Library specified field if it is not already specified, and
QRPGLESRC in the File specified field if it is not already specified.
12. The Library specified field is the resolved library name if the library name is not already specified. The
Include file specified field contains the resolved file name if the file name is not already specified.
13. If *CURLIB is specified in the source (Library specified is *CURLIB), the Library used field is set to
*CURLIB because no specific library can be determined if the file is not found in the library list.
14. This record is written only by the CRTBNDxxx commands.
15. This record is written only when a SRVPGM or MODULE does not exist, and this causes the
compilation to fail.
16. The object fields in this record refer to the ENTMOD parameter for the CRTPGM command.
17. CRTMNU only writes records when TYPE(*UIM) is specified.
18. The source used fields contain the same information as the source specified fields.
19. User-defined types are part types that the user created.
20. Any COBOL/400 source may contain more than one program.

Processor member start record

This, or the Processor object start record, must be the first record that is passed by the compiler or
preprocessor on its first call to the QLYWRTBI API. Its purpose is to identify the source that is being
compiled, and also to describe the expected output object, if any.

Note: This record was previously called the processor start record, but the format remains the same.

The Processor member start record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) Processor command
18 12 CHAR(10) Source object name specified
28 1C CHAR(10) Source library name specified
38 26 CHAR(7) Source object type
45 2D CHAR(10) Source member name specified
55 37 CHAR(10) Source object name used
65 41 CHAR(10) Source library name used
75 4B CHAR(10) Source member name used
85 55 CHAR(10) Target object name specified
95 5F CHAR(10) Target library name specified
105 69 CHAR(7) Target object type
112 70 CHAR(10) Target member name specified
122 7A CHAR(2) Reserved

High-Level Language APIs 37

Processors for which this record type applies
All compilers and preprocessors listed in Record Types and Processors (Part 1) except CRTPGM, and the
processor processing the user-defined types added with SYSTYPE(*NONE) on the ADDADMTYPE
command.

Field Descriptions
Processor command. The compiler or preprocessor that wrote this record, for example, CRTRPGPGM.

Record length. The length of this record is 124.

Record type. The type of this record is ’01’.

Reserved. An ignored field.

Source library name used. The actual name of the library that was used. The library name could be
different from the specified library name because *LIBL or *CURLIB was specified, or an override was
used. This field contains the name the library resolves to.

Source library name specified. The library name of the source file specified on the compiler or
preprocessor command.

Source member name used. The actual name of the source member that was used. This field is required,
even if the two member names are the same.

Source member name specified. The source member name specified on the compiler or preprocessor
command.

Source object name used. The actual name of the object that was used. The object name could be
different from the specified object name if an override was used.

Source object name specified. The object name specified on the compiler or preprocessor command.

Source object type. The i5/OS(TM) type of the source object (for example, *FILE).

Target library name specified. The library of the target object specified on the compiler or preprocessor
command.

Target member name specified. The name of the member to be created, if applicable, specified on the
compiler or preprocessor command.

Target object name specified. The name of the object to be created, called the target object, specified on
the compiler or preprocessor command. The actual name of the object that was created is passed through
the Normal processor end record. (See “Normal processor end record” on page 40.)

Target object type. The i5/OS type of the object to be created (for example, *FILE).

Processor object start record

This, or the Processor member start record, must be the first record that is passed by the compiler or
preprocessor on its first call to the QLYWRTBI API. Its purpose is to identify the object that is being
processed, and also to describe the expected output object, or, for user-defined types, the expected
location of the output members, if any.

User-defined types added with SYSTYPE(*NONE) on the ADDADMTYPE command must write this
record before any other record.

38 IBM Systems - iSeries: High-Level Language APIs

The Processor object start record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) Processor command
18 12 CHAR(10) Object name specified
28 1C CHAR(10) Object library name specified
38 26 CHAR(7) Object type specified
45 2D CHAR(10) Object name used
55 37 CHAR(10) Object library name used
65 41 CHAR(7) Object type used
72 48 CHAR(10) Target object name specified
82 52 CHAR(10) Target object library name specified
92 5C CHAR(7) Target object type specified
99 63 CHAR(1) Reserved

Processors for which this record type applies

CRTPGM and the processor processing the user-defined types added with SYSTYPE(*NONE) on the
ADDADMTYPE command.

Field Descriptions
Object library name specified. The library name of the object specified on the compiler or preprocessor
command. If the object type specified is a user-defined type with SYSTYPE(*NONE), the library name
specified should be the group library name.

Object library name used. The actual name of the library that the object was found in. The library name
could be different from the specified library name because, for example, *LIBL or *CURLIB was specified.
This field contains the name the library resolves to.

Object name specified. The object name specified on the command. If the object type specified is a
user-defined type with SYSTYPE(*NONE), the object name specified should be the part name.

Object name used. The actual name of the object that was used. The object name could be different from
the specified object name if an override was used.

Object type specified. The object type specified on the command. For user-defined types this must be left
blank. If the object type specified is a user-defined type with SYSTYPE(*NONE), the object type specified
should be the part type.

Object type used. The actual type of the object used. For example, *MODULE. For user-defined types
this can be left blank.

Processor command. The compiler or preprocessor that wrote this record, for example, CRTPGM.

Record length. The length of this record is 100.

High-Level Language APIs 39

Record type. The type of this record is ’50’.

Reserved. An ignored field.

Target object library name specified. The library of the target object specified on the command. For
user-defined types, the library where the output members are created, as specified on the command.

Target object name specified. The name of the object to be created, or modified as specified on the
command. For user-defined types this can be left blank.

Target object type specified. The type of the object to be created. For example, *PGM. The actual name of
the object that was created is passed through the Normal processor end record. (See “Normal processor
end record.”) For user-defined types, the names of the output members are passed through the Normal
multiple end record. For user-defined types this value must be *MBR.

Normal processor end record

This is the last record passed by the compiler or preprocessor to indicate that processing ended
successfully.

The Normal processor end record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) Object name created
18 12 CHAR(10) Library
28 1C CHAR(7) Object type
35 23 CHAR(10) Member
45 2D CHAR(7) Message identifier

Processors for which this record type applies

All compilers and preprocessors listed in Record Types and Processors (Part 1), except the processor
processing the user-defined types added with SYSTYPE(*NONE) on the ADDADMTYPE command.

Field Descriptions
Library name. The library where the object was created.

Member name. The name of the member created, if applicable.

Message identifier. The message identification of the completion message.

Object name created. The object created by the compiler or preprocessor. If an object is not created, this
field stores the value of ’*NONE’.

Object type. The type of object created.

Record length. The length of this record is 52.

40 IBM Systems - iSeries: High-Level Language APIs

Record type. The type of this record is ’20’.

Reserved. An ignored field.

Normal processor end call next record

When a preprocessor successfully creates an object or a member and needs to call another compiler or
preprocessor, it should pass this record instead of passing the Normal processor end record as the final
record. For example, if the CRTSQLCI command is entered with OPTION(*GEN), and the member is
created successfully, the last record written by CRTSQLCI is the Normal processor end call next record.
The preprocessor then calls the CRTBNDC command that eventually writes the Normal or Abnormal
processor end record.

The Normal processor end call next record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) Object name
18 12 CHAR(10) Library name
28 1C CHAR(7) Object type
35 23 CHAR(10) Member name
45 2D CHAR(7) Message identifier

Processors for which this record type applies

CRTSQLRPG CRTSQLCBL CRTSQLRPGI CRTSQLCBLI
CRTBNDRPG CRTBNDCBL CRTBNDC CRTBNDCL
CRTSQLCI when processor processing the user-defined types represented as members
OPTION(*GEN) is specified

Field Descriptions
Library name. The library where the object was created.

Member name. The name of the member created, if applicable.

Message identifier. The message identification of the completion message.

Object name. The name of the object created.

Object type. The type of object created.

Record length. The length of this record is 52.

Record type. The type of this record is ’21’.

Reserved. An ignored field.

High-Level Language APIs 41

Normal multiple end record
This is the last record passed by a user-defined type added with SYSTYPE(*NONE) on the
ADDADMTYPE command. It identifies Normal multiple end processing of all the output members. One
Normal multiple end record is written per member generated. The Normal processor end record should
not be written.

Note: It is possible that the processor generated 10 members on the last build, and because of a change,
now needs to regenerate just 2 of those members. For the build process to preserve the relationships to
the remaining 8 members, the processor must write all members to the API, regardless of whether the
member was actually regenerated. The build process ignores those parts (members) that have either not
changed (because the processor did not regenerate them), or do not exist (because the processor did not
generate them, and they may exist higher in the hierarchy).

The Normal multiple end record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) Library
18 12 CHAR(10) File name created
28 1C CHAR(10) Member
38 26 CHAR(32) Part type
70 46 CHAR(32) Part language
102 66 CHAR(22) Reserved

Processors for which this record type applies

The processor processing the user-defined types added with SYSTYPE(*NONE) on the ADDADMTYPE
command.

Field Descriptions
File name created. The file name that was created or used to hold the member.

Library. The library where the member was created.

Member. The name of the member created.

Part language. The language of the part to represent this member.

Part type. The type of the part to represent this member.

Record length. The length of this record is 124.

Record type. The type of this record is ’65’.

Reserved. An ignored field.

42 IBM Systems - iSeries: High-Level Language APIs

Abnormal processor end record
This is the last record passed if the compiler or preprocessor fails because of an error. For example, an
object or a member was not created because of compile errors, or REPLACE(*NO) was specified on the
command and the object existed.

If the command failed because an external reference to a file, message file, module, bind directory or
service program could not be found, the command passes the External reference error record before
passing this one. See “External reference error record” on page 52 for more information on this record.

The Abnormal processor end record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(7) Message identifier
15 F CHAR(1) Reserved

Processors for which this record type applies

All compilers and preprocessors listed in Record Types and Processors (Part 1).

Field Descriptions
Message identifier. The message identification of the completion message.

Record length. The length of this record is 16.

Record type. The type of this record is ’30’.

Reserved. An ignored field.

Include record
This record is passed when the compiler or preprocessor processes an include. An include statement is a
statement that causes the compiler to replace the include statement with the contents of the specified
header or file. If the include is not found, the compiler or preprocessor passes the Abnormal processor
end record.

The Include record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 BINARY(4) Nesting level
12 C CHAR(10) Include file name specified
22 16 CHAR(10) Include file library name specified
32 20 CHAR(10) Include file member name specified

High-Level Language APIs 43

 Offset
Dec Hex Type Field
42 2A CHAR(7) Object type
49 31 CHAR(10) Include file name used
59 3B CHAR(10) Include file library name used
69 45 CHAR(10) Include file member name used
79 4F CHAR(1) Reserved

Processors for which this record type applies

CRTRPGPGM CRTCBLPGM CRTRPGMOD CRTBNDRPG
CRTCBLMOD CRTBNDCBL CRTCMOD CRTBNDC
CRTSQLRPGI CRTSQLCBLI CRTSQLCI CRTPNLGRP
CRTMNU processor processing the user-defined types represented as members

Field Descriptions
Include file used. The actual name of the include file that was used. For example, the default include file
used by the compiler and implied in the source, or the file different from the one specified in the source
as a result of an override. This name must always be filled in.

Include file specified. The name of the file that contains the include. This is the name specified in the
source (if the include was file qualified), otherwise it is blank.

Include file library used. The name of the actual library that contains the include file that was used (for
example, a specific library name instead of *CURLIB or *LIBL, as specified in the source, or a library
different from the one specified in the source, as a result of an override).

Include file library specified. The name of the library where the include file resides, as specified in the
source (if the include was library qualified), otherwise it is blank.

Include file member used. The actual name of the source member containing the include that was used.
This name must always be filled in.

Include file member specified. The name of the source member containing the include, as specified in
the source.

Nesting level. The level of nesting of the include. Includes found in the root source have a nesting level
of 1, includes found in level 1 have a nesting level of 2 and so on.

Object type. The object type of the object containing the include, for example *FILE.

Record length. The length of this record is 80.

Record type. The type of this record is ’02’.

Reserved. An ignored field.

The nesting level should be indicated even by those compilers that do not allow include nesting. In that
case, the nesting level passed should be equal to 1.

44 IBM Systems - iSeries: High-Level Language APIs

File reference record
This record is passed when the compiler or preprocessor encounters a reference to an externally described
file but not its record format or field.

For example, a reference is made in DDS source using the PFILE or JFILE keywords. Another example is
when a compiler or preprocessor copies all the record format declares from a file. This is not considered
to be a dependency on any specific record format and is treated as a dependency on the file, so this
record must be passed, not the Record format reference records for all the individual record formats.

The File reference record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) File name specified
18 12 CHAR(10) File library name specified
28 1C CHAR(1) Based on indicator
29 1D CHAR(10) File name used
39 27 CHAR(10) File library name used
49 31 CHAR(3) Reserved
52 34 BINARY(4) Nesting level

Processors for which this record type applies

CRTRPGPGM CRTCBLPGM CRTPF CRTLF
CRTDSPF CRTICFF CRTPRTF CRTCLPGM
CRTSQLRPG CRTSQLCBL CRTRPGMOD CRTBNDRPG
CRTCBLMOD CRTBNDCBL CRTCMOD CRTBNDC
CRTCLMOD CRTBNDCL CRTSQLRPGI CRTSQLCBLI
CRTSQLCI processor processing the user-defined types represented as members

Field Descriptions
Based on indicator. Indicates whether the referenced file is used to base another file on. Possible values
are N (no) and Y (yes).

File name used. The name of the actual file that was referenced. This name must always be filled in.

File name specified. The name of the file referenced, as specified in the source.

File library name used. The name of the actual library that contains the file that was referenced. The
library name could be different from the specified library name because *LIBL or *CURLIB was specified,
or an override was used.

File library name specified. The name of the library of the file referenced, as specified in the source.

High-Level Language APIs 45

Nesting level. If this file reference is made within an include, this field has value of N + 1, where N is
the nesting level of the include. Otherwise, the value of this field is 1.

Record length. The length of this record is 56.

Record type. The type of this record is ’03’.

Reserved. An ignored field.

Module reference record

This record is passed when a module is successfully referenced by a processor. This record is not to be
written for the ENTMOD module, on the CRTPGM command.

The Module reference record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) Module name specified
18 12 CHAR(10) Module library name specified
28 1C CHAR(10) Module name used
38 26 CHAR(10) Module library name used

Processors for which this record type applies

CRTSRVPGM and CRTPGM.

Field Descriptions
Module name used. The name of the actual module that was referenced. This name must always be
filled in.

Module name specified. The name of the module referenced, as specified on the command, or in the
bind directory.

Module library name used. The name of the actual library that contains the module that was referenced.
The library name could be different from the specified library name because *LIBL or *CURLIB was
specified.

Module library name specified. The name of the library of the module referenced, as specified on the
command, or in the bind directory.

Record length. The length of this record is 92.

Record type. The type of this record is ’55’.

Reserved. An ignored field.

46 IBM Systems - iSeries: High-Level Language APIs

Service program reference record
This record is passed when a service program is successfully referenced by a processor.

The Service program reference record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) Service program name specified
18 12 CHAR(10) Service program library name specified
28 1C CHAR(10) Service program name used
38 26 CHAR(10) Service program library name used
48 30 CHAR(16) Service program signature used

Processors for which this record type applies

CRTSRVPGM and CRTPGM.

Field Descriptions
Record length. The length of this record is 64.

Record type. The type of this record is ’60’.

Service program name used. The name of the actual service program that was referenced. This name
must always be filled in.

Service program name specified. The name of the service program as specified on the command.

Service program library name used. The name of the actual library that contains the service program
that was referenced. The library name could be different from the specified library name because *LIBL or
*CURLIB was specified.

Service program library name specified. The name of the library of the service program referenced, as
specified on the command.

Service program signature used. The current signature of the service program used.

Bind directory reference record

This record is passed when a module is successfully referenced by a processor. This record is not to be
written for the ENTMOD module, on the CRTPGM command.

The Bind directory reference record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type

High-Level Language APIs 47

 Offset
Dec Hex Type Field
6 6 CHAR(2) Reserved
8 8 CHAR(10) Bind directory name specified
18 12 CHAR(10) Bind directory library name specified
28 1C CHAR(10) Bind directory name used
38 26 CHAR(10) Bind directory library name used

Processors for which this record type applies

CRTSRVPGM and CRTPGM.

Field Descriptions
Bind directory name used. The name of the actual bind directory that was referenced. This name must
always be filled in.

Bind directory name specified. The name of the bind directory referenced, as specified on the command.

Bind directory library name used. The name of the actual library that contains the bind directory that
was referenced. The library name could be different from the specified library name because *LIBL or
*CURLIB was specified.

Bind directory library name specified. The name of the library of the bind directory referenced, as
specified on the command.

Record length. The length of this record is 48.

Record type. The type of this record is ’75’.

Reserved. An ignored field.

Record format reference record

This record is passed when the compiler or preprocessor encounters a reference to a record format of an
externally described file (but not to any single field). For example, a reference is made in DDS source
using the FORMAT keyword or in the RPG, COBOL, CL, DB2 UDB for iSeries SQL, ILE RPG, ILE
COBOL, ILE CL, or ILE C processors whenever a declaration of a record format structure from a
DDS-described file is generated by the compiler or preprocessor.

The Record format reference record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) File name specified
18 12 CHAR(10) File library name specified
28 1C CHAR(10) Record format name
38 26 CHAR(13) Record format level ID

48 IBM Systems - iSeries: High-Level Language APIs

 Offset
Dec Hex Type Field
51 33 CHAR(10) File name used
61 3D CHAR(10) File library name used
71 47 CHAR(1) Reserved
72 48 BINARY(4) Nesting level

Processors for which this record type is applicable

CRTRPGPGM CRTCBLPGM CRTPF CRTLF
CRTDSPF CRTICFF CRTPRTF CRTCLPGM
CRTSQLRPG CRTSQLCBL CRTRPGMOD CRTBNDRPG
CRTCBLMOD CRTBNDCBL CRTCMOD CRTBNDC
CRTCLMOD CRTBNDCL CRTSQLRPGI CRTSQLCBLI
CRTSQLCI processor processing the user-defined types represented as members

Field Descriptions
File name used. The name of the actual file that was referenced. This name must always be filled in.

File name specified. The name of the file being referenced, as specified in the source.

File library name used. The name of the actual library that contains the file that was referenced. The
library name could be different from the specified library name because *LIBL or *CURLIB was specified,
or an override was used. This field contains the name the library resolves to.

File library name specified. The name of the library of the file being referenced, as specified in the
source.

Nesting level. If this record format reference is made within an include, this field has value of N + 1,
where N is the nesting level of the include. Otherwise, the value of this field is 1.

Record format level ID. The level ID of the record format referenced.

Record format name. The name of the record format referenced.

Record length. The length of this record is 76.

Record type. The type of this record is ’04’.

Reserved. An ignored field.

Field reference record

This record is passed when the compiler or preprocessor encounters a reference to a field in an externally
described file. For example, a reference is made in DDS source using the REF and REFFLD keywords.

The Field reference record has the following format:

High-Level Language APIs 49

 Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) File name specified
18 12 CHAR(10) File library name specified
28 1C CHAR(10) Record format name
38 26 CHAR(13) Record format level ID
51 33 CHAR(10) Field
61 3D CHAR(3) Reserved
64 40 BINARY(4) Field length
68 44 BINARY(4) Decimal positions
72 48 CHAR(1) Data type
73 49 CHAR(1) Fixed/variable length indicator
74 4A CHAR(10) File name used
84 54 CHAR(10) File library name used
94 5E CHAR(2) Reserved

Processors for which this record type applies

CRTPF CRTLF CRTDSPF CRTICFF
CRTPRTF processor processing the user-defined types represented as members

Field Descriptions
Data type. The field data type in DDS. For example, P, S, B, F, A, or H.

Decimal positions. The number of decimal positions if the field is numeric, otherwise 0.

Field. The name of the referenced field.

Field length. The length of the field in bytes. If the field is a variable-length field, the maximum length
should be passed.

File name used. The name of the actual file that was referenced. This name must always be filled in.

File name specified. The name of the file being referenced, as specified in the source.

Fixed/variable length indicator. Contains F if the field is of fixed length, or V if variable length.

File library name used. The name of the actual library that contains the file that was referenced.

File library name specified. The name of the library of the file being referenced, as specified in the
source.

Record format level ID. The level ID of the record format referenced.

50 IBM Systems - iSeries: High-Level Language APIs

Record format name. The name of the record format referenced.

Record length. The length of this record is 96.

Record type. The type of this record is ’05’.

Reserved. An ignored field.

Message reference record

This record is passed when the compiler encounters a reference to a message ID in a message file. For
example, a reference is made in DDS source using the MSGCON keyword.

The Message reference record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(7) Message identifier
15 F CHAR(10) Message file name specified
25 19 CHAR(10) Message file library name specified
35 23 CHAR(10) Message file name used
45 2D CHAR(10) Message file library name used
55 37 CHAR(1) Reserved
56 38 BINARY(4) Nesting Level

Processors for which this record type applies

CRTPF CRTLF CRTDSPF CRTPRTF
CRTICFF CRTCMD CRTPNLGRP CRTMNU
processor processing the user-defined types represented as members

Field Descriptions
Message file library used. The name of the actual library that contains the message file. This may be
*CURLIB or *LIBL if the compiler does not resolve to the library name.

Message file library specified. The name of the library that contains the message file, as specified in the
source.

Message file name used. The name of the actual message file that was referenced. This name must
always be filled in.

Message file name specified. The name of the message file referenced, as specified in the source.

Message identifier. The message ID referenced.

High-Level Language APIs 51

Nesting Level. The level of nesting of the MSGF. MSGFs referenced in the root source have a nesting
level of 1, MSGFs found in level 1 have a nesting level of 2 and so on.

Record length. The length of this record is 60.

Record type. The type of this record is ’06’.

Reserved. An ignored field.

External reference error record

This record is passed when processing fails because a referenced object, such as a file, message file,
module, bind directory or service program cannot be found. This record does not apply to includes.

After passing one or more of these records, the compiler or preprocessor also passes the Abnormal
processor end record (see “Abnormal processor end record” on page 43).

The External reference error record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) Object name specified
18 12 CHAR(10) Object library name specified
28 1C CHAR(7) Object type
35 23 CHAR(10) Object name used
45 2D CHAR(10) Object library name used
55 37 CHAR(1) Based on indicator

Processors for which this record type applies

CRTRPGPGM CRTCBLPGM CRTPF CRTLF
CRTDSPF CRTICFF CRTPRTF CRTCLPGM
CRTSQLRPG CRTSQLCBL CRTRPGMOD CRTBNDRPG
CRTCBLMOD CRTBNDCBL CRTCMOD CRTBNDC
CRTCLMOD CRTBNDCL CRTSQLRPGI CRTSQLCBLI
CRTSQLCI CRTSRVPGM CRTPGM CRTPNLGRP
CRTMNU processor processing the user-defined types represented as members

Field Descriptions
Based on indicator. Whether the referenced file is used to base another file on. Possible values are N (no)
and Y (yes). This field is used by the CRTLF processor.

Object library name used. The actual name of the library that contains the object that was referenced.

Object library name specified. The name of the library that contains the object that was not found.

52 IBM Systems - iSeries: High-Level Language APIs

Object name used. The actual name of the object that was referenced. This name must always be filled
in.

Object name specified. The name of the object referenced that was not found.

Object type. The type of object that was not found.

Record length. The length of this record is 56.

Record type. The type of this record is ’15’.

Reserved. An ignored field.

Object already exists error record

This record is passed when the compiler or preprocessor fails because the object that was to be created
exists. There is no REPLACE parameter on the command because the compiler or preprocessor expects
the object not to exist.

After passing this record, the compiler or preprocessor must also pass the Abnormal processor end record
(see “Abnormal processor end record” on page 43).

The Object already exists error record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) Object name that already exists
18 12 CHAR(10) Object library name
28 1C CHAR(7) Object type
35 23 CHAR(1) Reserved

Processors for which this record type applies

CRTPF CRTLF CRTDSPF CRTICFF
CRTPRTF processor processing the user-defined types represented as members

Field Descriptions
Object library name. The name of the library that contains the object that already exists. A specific
library name, not *CURLIB or *LIBL must be passed.

Object name that already exists. The name of the object that already exists and could not be replaced.

Object type. The type of the object that already exists.

Record length. The length of this record is 36.

Record type. The type of this record is ’16’.

High-Level Language APIs 53

Reserved. An ignored field.

Start of new program record

The COBOL/400 compiler is able to compile source that contains more than one program. This record is
passed by the COBOL/400 compiler when the beginning of a new program is encountered.

The Start of new program record has the following format:

Offset
Dec Hex Type Field
0 0 BINARY(4) Record length
4 4 CHAR(2) Record type
6 6 CHAR(2) Reserved
8 8 CHAR(10) New program name
18 12 CHAR(10) Object name created
28 1C CHAR(10) Object library name
38 26 CHAR(7) Message identifier
45 2D CHAR(3) Reserved
48 30 CHAR(7) Object type
55 37 CHAR(1) Reserved

Processors for which this record type applies

CRTCBLPGM CRTCBLMOD CRTBNDCBL CRTSQLCBLI
processor processing the user-defined types represented as members

Field Descriptions
Message identifier. The message ID of the completion message.

New program name. The name of the new program, per IDENTIFICATION DIVISION.

Object library name. The library where the object was created. This field contains blank if an error
occurred.

Object name created. The name of the object created in the previous step. If an object was not created
because of syntax errors or because REPLACE(*NO) was specified and the object already existed, this
field contains ’*ERROR’.

Object type. The type of object created. For example, *PGM or *MODULE.

Record length. The length of this record is 56.

Record type. The type of this record is ’40’.

Reserved. An ignored field.

Top | “High-Level Language APIs,” on page 1 | APIs by category

54 IBM Systems - iSeries: High-Level Language APIs

Examples of Records Written
The following examples illustrate how compilers and preprocessors communicate with the Application
Development Manager/400 APIs in different circumstances. In all these examples, assume that the
compiles are submitted by an Application Development Manager/400 BLDPART command, which means
it has called QLYSETS to set the status of the space to *READY before calling the compiler or
preprocessor.

It is also assumed that a cleanup is done after the compile by calling QLYSETS again to set the status of
the space to *COMPLETE.

Example 1
RPG/400(R) compiler successfully compiles source that has one include in it.

The compiler first calls QLYGETS and determines that it was started by the BLDPART command. Then it
calls QLYWRTBI to pass records of the following record types and in the following order:
1. Processor member start
2. Include
3. Normal processor end

Example 2
DDS compiler successfully compiles source of type LF and creates a logical file based on two physical
files.

The compiler first calls QLYGETS and determines that it was started by the BLDPART command. Then it
calls QLYWRTBI to pass records of the following record types and in the following order:
1. Processor member start
2. File reference
This record is called for the first physical file on which the logical file is based. The based-on indicator
is set to Y (yes).
3. File reference
This record is called for the second physical file on which the logical file is based. The based-on
indicator is set to Y (yes).
4. Normal processor end

Example 3
COBOL/400(R) compiler fails when compiling source that has one include in it because the include was
not found in *LIBL.

The compiler first calls QLYGETS and determines that it was started by a BLDPART command. Then it
calls QLYWRTBI to pass records of the following record types and in the following order:
1. Processor member start
2. Abnormal processor end

Example 4
COBOL/400 compiler fails when compiling source that references a record format of a database file
because the file was not found in *LIBL.

The compiler first calls QLYGETS and determines that it was started by a BLDPART command. Then it
calls QLYWRTBI to pass records of the following record types and in the following order:
1. Processor member start

High-Level Language APIs 55

2. External reference error
The name of the Library specified passed to QLYWRTBI is *LIBL.
3. Abnormal processor end

Example 5
ILE C CRTBNDC compiler successfully compiles a *PGM from a source that has one include in it.

The compiler calls QLYGETS and determines that it was started by the BLDPART command. Then it calls
QLYWRTBI to pass records of the following record types and in the following order:
1. Processor member start
2. Include
3. Normal processor end call next
4. Processor object start
5. Normal processor end

Note: The Processor object start and the Normal processor end records are written by the CRTPGM
processor internally called by the CRTBNDC compiler.

Example 6
CRTPGM binder successfully binds objects from 2 modules, and references a bind directory and a service
program.

The compiler calls QLYGETS and determines that it was started by the BLDPART command. Then it calls
QLYWRTBI to pass records of the following record types and in the following order:
1. Processor object start
2. Module reference
3. Module reference
4. Bind directory reference
5. Service program reference
6. Normal processor end.

Top | “High-Level Language APIs,” on page 1 | APIs by category

Using Application Development Manager/400 APIs

The following compilers and preprocessors use the the Application Development Manager/400 APIs.

Table 1. Compilers and preprocessors that can be used with the Application Development
Manager/400 feature

Compiler/ Compiler/Preprocessor i5/OS(TM) Supported if *PRV is Specified for

Preprocessor Command Target Release
Language

RPG/400(R) CRTRPGPGM Yes

ILE RPG/400 No
(R)
COBOL/400 CRTCBLPGM Yes
ILE COBOL/400 No

56 IBM Systems - iSeries: High-Level Language APIs

Compiler/ Compiler/Preprocessor i5/OS(TM) Supported if *PRV is Specified for
Preprocessor Command Target Release
Language

ILE CL No
ILE C Yes
CRTPF, CRTLF, CRTDSPF, CRTPRTF, Not applicable
CRTICFF
CL CRTCLPGM Yes
CLD CRTCLD Yes
CMD CRTCMD Not applicable
CRTSQLRPG, CRTSQLCBL, Yes
CRTSQLCI
CRTSQLRPGI, CRTSQLCBLI No
CRTSRVPGM CRTSRVPGM Yes
CRTPGM CRTPGM Yes
MENU CRTMNU TYPE(*UIM) Not applicable
PNLGRP CRTPNLGRP Not applicable
Notes:
1. Default command is used by the BLDPART command.
2. Appropriate default compiler command is used based on the part type and the language.

The following diagram shows the proper usage and order in which the APIs should be called.

Overall Application Development Manager/400 API Usage

High-Level Language APIs 57

QLYGETS should be called by the application or compiler before calling the other three APIs: QLYSETS,
QLYWRTBI, and QLYRDBI to verify that the space is available for use.

The following table describes the API space status values that can be received by calling the QLYGETS
API, and the action that should be taken by the application or compiler that is calling the API.

Table 2. API Space Status

Status Application Compiler

*COMPLETE The space is available for use. Call Do not write API records.
QLYSETS to set to *READY.

58 IBM Systems - iSeries: High-Level Language APIs

Status Application Compiler
*NONE The space does not exist. The Do not write API records.
application calls QLYSETS to create
and set the space to *READY.
*READY The space is in use by a compiler. The space is available for writing.
The other APIs should not be called.

Compilers use the APIs to write to the space. Applications use the APIs to read from the space.

Note: Unpredictable results can occur when the APIs are not properly used or are used in the incorrect
order.

Calling multiple API-supporting compilers simultaneously in a single interactive session (one possible
way of doing this is by pressing the Attention key and then command key F9 to get to the command
line) may cause unpredictable results. The compiler can fail, for example, or incorrect or incomplete
information can be put in the work space.

Top | “High-Level Language APIs,” on page 1 | APIs by category

High-Level Language APIs 59

60 IBM Systems - iSeries: High-Level Language APIs
Appendix. Notices
This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. 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. Any functionally equivalent product, program,
or service that does not infringe any IBM intellectual property right may be used instead. However, it is
the user’s responsibility to evaluate and verify the operation of any non-IBM product, program, or
service.

IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can send
license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some
states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this
statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in
any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of
the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.

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:

© Copyright IBM Corp. 1998, 2006 61

IBM Corporation
Software Interoperability Coordinator, Department YBWA
3605 Highway 52 N
Rochester, MN 55901
U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.

The licensed program described in this information and all licensed material available for it are provided
by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement,
IBM License Agreement for Machine Code, or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have
been made on development-level systems and there is no guarantee that these measurements will be the
same on generally available systems. Furthermore, some measurements may have been estimated through
extrapolation. Actual results may vary. Users of this document should verify the applicable data for their
specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.

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

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform for
which the sample programs are written. These examples have not been thoroughly tested under all
conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs.

Each copy or any portion of these sample programs or any derivative work, must include a copyright
notice as follows:

(C) IBM 2006. Portions of this code are derived from IBM Corp. Sample Programs. (C) Copyright IBM
Corp. 1998, 2006. All rights reserved.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Programming Interface Information

This Application Programming Interfaces (API) publication documents intended Programming Interfaces
that allow the customer to write programs to obtain the services of IBM i5/OS.

62 IBM Systems - iSeries: High-Level Language APIs

Trademarks
The following terms are trademarks of International Business Machines Corporation in the United States,
other countries, or both:
Advanced 36
Advanced Function Printing
Advanced Peer-to-Peer Networking
AFP
AIX
AS/400
COBOL/400
CUA
DB2
DB2 Universal Database
Distributed Relational Database Architecture
Domino
DPI
DRDA
eServer
GDDM
IBM
Integrated Language Environment
Intelligent Printer Data Stream
IPDS
i5/OS
iSeries
Lotus Notes
MVS
Netfinity
Net.Data
NetView
Notes
OfficeVision
Operating System/2
Operating System/400
OS/2
OS/400
PartnerWorld
PowerPC
PrintManager
Print Services Facility
RISC System/6000
RPG/400
RS/6000
SAA
SecureWay
System/36
System/370
System/38
System/390
VisualAge
WebSphere
xSeries

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.

Appendix. Notices 63
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other
countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other company, product, and service names may be trademarks or service marks of others.

Terms and Conditions

Permissions for the use of these Publications is granted subject to the following terms and conditions.

Personal Use: You may reproduce these Publications for your personal, noncommercial use provided that
all proprietary notices are preserved. You may not distribute, display or make derivative works of these
Publications, or any portion thereof, without the express consent of IBM.

Commercial Use: You may reproduce, distribute and display these Publications solely within your
enterprise provided that all proprietary notices are preserved. You may not make derivative works of
these Publications, or reproduce, distribute or display these Publications or any portion thereof outside
your enterprise, without the express consent of IBM.

Except as expressly granted in this permission, no other permissions, licenses or rights are granted, either
express or implied, to the Publications or any information, data, software or other intellectual property
contained therein.

IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use of
the Publications is detrimental to its interest or, as determined by IBM, the above instructions are not
being properly followed.

You may not download, export or re-export this information except in full compliance with all applicable
laws and regulations, including all United States export laws and regulations. IBM MAKES NO
GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THE PUBLICATIONS ARE
PROVIDED ″AS-IS″ AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,
NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE

64 IBM Systems - iSeries: High-Level Language APIs




Printed in USA