ILE COBOL Programmer's GuideModule Object(s)
Program Object(s)
Running Programs
Debug Mode
Create a module (CRTCBLMOD)
Create a Program (CRTPGM)
Call a Program (CALL)
Design your ILE COBOL source program
Compile your source program into a module object.
Create the program object by binding one or more module objects.
7.
Source Code Member
END PROGRAM Z. END PROGRAM A.
ILE Procedure B: ID DIVISION. PROGRAM-ID. B.
ILE Procedure C: ID DIVISION. PROGRAM-ID. C.
END PROGRAM C.
END PROGRAM D.
Compile Process CRTCBLMOD
Bind Process CRTPGM
Compile Process CRTCBLMOD
Compile Process CRTCBLMOD
PEP
is
to
be
used
as
the
PEP
for
the
program
object.
Also,
the
order
in
which
module
objects
and
service
programs
are
specified
in
the
CRTPGM
command
affects
the
way
symbols
ILE COBOL for AS/400 Source Program, Externally Described Files, Copy Source Code
Runnable Program Object(s)
Runnable Program Object(s)
Module Object(s)
For
an
item
of
category
date
or
time,
if
a
format
literal
is
not
explicitly
specified
in
the
data
description
entry
one
can
be
specified
in
the
SPECIAL-NAMES
paragraph.
An
example
is
shown
below:
SPECIAL-NAMES.
FORMAT
OF
DATE
IS
#Abbreviated
weekday
names
(%a)
abday
"<S><u><n>";"<M><o><n>";"<T><u><e>";"<W><e><d>";\
"<T><h><u>";"<F><r><i>";"<S><a><t>"
#
#Full
weekday
names
(%A)
day
"<S><u><n><d><a><y>";"<M><o><n><d><a><y>";\
"<T><u><e><s><d><a><y>";"<W><e><d><n><e><s><d><a><y>";\
"<T><h><u><r><s><d><a><y>";"<F><r><i><d><a><y>";\
"<S><a><t><u><r><d><a><y>"
#
#Abbreviated
month
names
(%b)
abmon
#
#Full
month
names
(%B)
mon
"<J><a><n><u><a><r><y>";"<F><e><b><r><u><a><r><y>";\
"<M><a><r><c><h>";"<A><p><r><i><l>";"<M><a><y>";\
"<J><u><n><e>";"<J><u><l><y>";"<A><u><g><u><s><t>";\
#
alt_digits
"<0><t><h>";"<1><s><t>";"<2><n><d>";"<3><r><d>";\
"<4><t><h>";"<5><t><h>";"<6><t><h>";"<7><t><h>";\
#
dstname
Figure
52.
Nested
Program
Structure
with
Directly
and
Indirectly
Contained
Programs
Chapter
9.
Calling
and
Sharing
Data
Between
ILE
COBOL
Programs
209
C program
COBOL program
C program
COBOL program
Is there a USE procedure?
Is there a
What is leftmost character
Figure
90.
Processing
of
I/O
Verbs
(Part
1
of
2)
Chapter
15.
ILE
COBOL
Error
and
Exception
Handling
353
Note:
Follow
the
parts
of
the
diagram
that
apply
to
your
statements.
Detecting
End-of-File
Conditions
(AT
END
Phrase)
An
end-of-file
condition
may
or
may
not
represent
an
error.
In
many
designs,
reading
sequentially
to
the
end
of
a
file
is
done
intentionally,
and
the
AT
END
condition
is
expected.
In
some
cases,
however,
the
end-of-file
condition
will
reflect
an
error.
You
code
the
AT
END
phrase
of
the
READ
statement
to
handle
either
case,
according
you
your
program
design.
If
you
code
an
AT
END
phrase,
the
imperative
statement
identified
by
the
phrase
is
performed
when
an
end-of-file
condition
occurs.
If
you
do
not
code
an
AT
END
phrase,
the
associated
USE
AFTER
EXCEPTION/ERROR
declarative
is
performed.
Any
NOT
AT
END
phrase
that
you
code
is
performed
only
if
the
READ
statement
completed
successfully.
If
the
READ
operation
fails
because
of
any
condition
other
than
end-of-file,
neither
the
AT
END
nor
the
NOT
AT
END
phrase
is
performed.
Instead,
control
passes
to
the
end
of
the
READ
statement
after
performing
the
associated
USE
AFTER
EXCEPTION/ERROR
declarative
procedure.
If
you
have
coded
neither
an
AT
END
phrase
nor
a
USE
AFTER
EXCEPTION/ERROR
declarative
procedure,
but
you
have
coded
a
STATUS
KEY
clause
for
the
file,
control
passes
to
the
next
sequential
instruction
after
the
0?
0?
Run NOT INVALID KEY
Continue COBOL program
(assigment-name)
Printer
DEV(QPRINT)
Printer
DEV(QPRINT)
DEV(QDKT)
FILEX
DEV(QPRINT)
Diskette
Compile Time
Run Time
FILEA
SPOOL(*YES) OUTQ(QPRINT)
DELETE
READ
READ
READ
REWRITE
START
START
START
WRITE
WRITE
Without Commitment Control
With Commitment Control
Without Commitment Control
*CHG *CS *ALL
Without Commitment Control
Without Commitment Control
Without Commitment Control
Without Commitment Control
Without Commitment Control
Without Commitment Control
Note:
Update
operations
include
a
START,
READ,
REWRITE,
or
DELETE
operation
for
the
same
file
(regardless
of
whether
it
is
successful
or
unsuccessful),
and
closing
the
file.
A
WRITE
operation
is
not
considered
an
update
operation;
therefore,
no
lock
will
be
set
or
released
as
the
result
of
a
WRITE
operation.
Figure
99.
Record
Locking
Considerations
with
and
without
Commitment
Control
396
ILE
COBOL
Prerequisite and Related Information
Whats New This Release?
Whats New in V5R2?
Whats New in V5R1?
Whats New in V4R4?
Whats New in V4R2?
Whats New in V3R7?
Whats New in V3R6/V3R2?
Whats New in V3R1?
Part 1. Compiling, Running, and Debugging ILE COBOL Programs
Chapter 1. Introduction
Integrated Language Environment
Major Steps in Creating a Runnable ILE COBOL Program Object
Designing Your ILE COBOL Source Program
Entering Source Statements into a Source Member
Compiling a Source Program into Module Objects
Creating a Program Object
Running a Program Object
Chapter 2. Entering Source Statements into a Source Member
Creating a Library and Source Physical File
Entering Source Statements Using the Source Entry Utility
COBOL Source File Format
Example of Entering Source Statements into a Source Member
Using Coded Character Set Identifiers
Assigning a CCSID to a Source Physical File
Including Copy Members with Different CCSIDs in Your Source File
Setting the CCSID for the COBOL Syntax Checker in SEU
Assigning a CCSID to a Locale
Runtime CCSID Considerations
Handling Different CCSIDs with the ILE Source Debugger
Chapter 3. Compiling Source Programs into Module Objects
Definition of a Module Object
Using the Create COBOL Module (CRTCBLMOD) Command
Using Prompt Displays with the CRTCBLMOD Command
Syntax for the CRTCBLMOD Command
Parameters of the CRTCBLMOD Command
Example of Compiling a Source Program into a Module Object
Specifying a Different Target Release
Specifying National Language Sort Sequence in CRTCBLMOD
Collecting Profiling Data
Using the PROCESS Statement to Specify Compiler Options
PROCESS Statement Options
Understanding Compiler Output
Time-Separation Characters
A Sample Program and Listing
Command Summary
Source Listing
Data Division Map
Definition of a Program Object
The Binding Process
Example of Binding Multiple Modules to Create a Program Object
Using the Create Bound COBOL (CRTBNDCBL) Command
Using Prompt Displays with the CRTBNDCBL Command
Syntax for the CRTBNDCBL Command
Parameters of the CRTBNDCBL Command
Invoking CRTPGM Implicitly from CRTBNDCBL
Example of Binding One Module Object to Create a Program Object
Specifying National Language Sort Sequence in CRTBNDCBL
Reading a Binder Listing
A Sample Binder Listing
Modifying a Module Object and Binding the Program Object Again
Changing the ILE COBOL Source Program
Changing the Optimization Levels
Definition of a Service Program
Using Service Programs
Writing the Binder Language Commands for an ILE COBOL Service Program
Using the Create Service Program (CRTSRVPGM) Command
Example of Creating a Service Program
Using the Retrieve Binder Source (RTVBNDSRC) Command as Input
Calling Exported ILE Procedures in Service Programs
Sharing Data with Service Programs
Canceling an ILE COBOL Program in a Service Program
Chapter 6. Running an ILE COBOL Program
Running a COBOL Program Using the CL CALL Command
Passing Parameters to an ILE COBOL Program Through the CL CALL Command
Running an ILE COBOL Program Using a HLL CALL Statement
Running an ILE COBOL Program From a Menu-Driven Application
Running an ILE COBOL Program Using a User Created Command
Ending an ILE COBOL Program
Replying to Run Time Inquiry Messages
Chapter 7. Debugging a Program
The ILE Source Debugger
Using a Listing View
Using a Source View
Using a Statement View
STRDBG Example
Adding Program Objects and Service Programs to a Debug Session
Removing Program Objects or Service Programs from a Debug Session
Viewing the Program Source
Changing the View of the Module Object that is Shown
Setting and Removing Breakpoints
Setting
Removing
Setting
Removing
Using the Work with Module Breakpoints Display
Using the TBREAK or CLEAR Debug Commands
Removing All Breakpoints
Characteristics of Watches
Setting Watch Conditions
Running a Program Object or ILE Procedure After a Breakpoint
Resuming a Program Object or ILE Procedure
Stepping Through the Program Object or ILE Procedure
Stepping Over Program Objects or ILE Procedures
Stepping Into Program Objects or ILE Procedures
Displaying Variables, Constant-names, Expressions, Records, Group Items, and Arrays
Displaying Variables and Expressions
Displaying a Substring of a Character String Variable
Displaying the address of a level-01 or level-77 data item
Displaying Records, Group Items, and Arrays
Changing the Value of Variables
Equating a Name with a Variable, Expression, or Command
National Language Support for the ILE Source Debugger
Changing and Displaying Locale-Based Variables
Support for User-Defined Data Types
Part 2. ILE COBOL Programming Considerations
Chapter 8. Working with Data Items
General ILE COBOL View of Numbers (PICTURE Clause)
Defining Numeric Items
Extra Positions for Displayable Symbols (Numeric Editing)
How to Use Numeric-Edited Items as Numbers
Computational Data Representation (USAGE Clause)
External Decimal (USAGE DISPLAY) Items
What USAGE DISPLAY Items Are For
Should You Use Them for Arithmetic
Internal Decimal (USAGE PACKED-DECIMAL or COMP-3)
Why Use Packed Decimal
How Much Storage BINARY Occupies
Truncation of Binary Data (*STDTRUNC Compiler Option)
Internal Floating-Point (USAGE COMP-1 and COMP-2) Items
External Floating-Point (USAGE DISPLAY) Items
Creating User-Defined Data Types
Sign Representation and Processing
Checking for Incompatible Data (Numeric Class Test)
How to Do a Numeric Class Test
Performing Arithmetic
When to Use Other Arithmetic Statements
Arithmetic Expressions
Intrinsic Function Examples
Converting to Uppercase or Lowercase (UPPER-CASE, LOWER-CASE)
Converting to Reverse Order (REVERSE)
Converting to Numbers (NUMVAL, NUMVAL-C)
Converting to Date-Time Data Items (CONVERT-DATE-TIME)
Converting to UTF-8 (UTF8STRING)
Evaluating Single Characters for Collating Sequence (CHAR, ORD)
Returning Variable-Length Results with Alphanumeric Functions
Finding the Largest or Smallest Data Item (MAX, MIN, ORD-MAX, ORD-MIN)
Finding the Length of Data Items (LENGTH)
Finding the Date of Compilation (WHEN-COMPILED)
Testing for Date-Time Data Items (TEST-DATE-TIME)
Working with Date and Time Durations (ADD-DURATION, FIND-DURATION, SUBTRACT-DURATION)
Formatting Dates and Times Based On Locales (LOCALE-DATE, LOCALE-TIME)
Fixed-Point versus Floating-Point Arithmetic
Processing Table Items
Example 1:
Example 2:
Example 3:
Long-Term Solution
Short-Term Solution
MOVE Considerations for Date-Time Data Items
Translation of @p to Uppercase
Conversion of 2-Digit Years to 4-Digit Years or Centuries
Conversion of Times to Microseconds
Working With Locales
Setting a Current Locale for Your Application
Identification and Scope of Locales
LC_MONETARY Locale Category
LC_MONETARY—Example
LC_TIME Category
Escape Sequences
LC_TIME Example
LC_TOD Category
LC_TOD Example
Chapter 9. Calling and Sharing Data Between ILE COBOL Programs
Run Time Concepts
Identifying the Linkage Type of Called Programs and Procedures
Calling Nested Programs
Calling Hierarchy for Nested Programs
Scope of Names within a Nested Structure
Using Static Procedure Calls and Dynamic Program Calls
Performing Static Procedure Calls using CALL literal
Performing Dynamic Program Calls using CALL literal
Using CALL identifier
Using CALL procedure-pointer
Using Recursive Calls
Returning from a Main Program
Returning from a *NEW Activation Group
Returning from a Named Activation Group
Returning from the Default (*DFTACTGRP) Activation Group
Returning from a Subprogram
Examples of Returning from an ILE COBOL Program
Passing Return Code Information (RETURN-CODE Special Register)
Passing and Sharing Data Between Programs
Comparing Local and Global Data
Passing Data Using CALL...BY REFERENCE, BY VALUE, or BY CONTENT
Describing Arguments in the Calling Program
Describing Parameters in the Called Program
Grouping Data to be Passed
Sharing EXTERNAL Data
Sharing EXTERNAL Files
Using Local Data Area
Using Program Initialization Parameters (PIP) Data Area
Effect of EXIT PROGRAM, STOP RUN, GOBACK, and CANCEL on Internal Files
Canceling an ILE COBOL Program
Canceling from Another ILE COBOL Program
Canceling from Another Language
COBOL and XML
Calling Java Methods from a COBOL Program
Code the COBOL Program
Create the COBOL Program
Code the Java Program
Compile the Java Program
Member JNI
Member JDK11INIT
XML parser in COBOL
Using XML-TEXT and XML-NTEXT
Restriction on your processing procedure
Ending your processing procedure
Handling errors in XML documents
Unhandled exceptions
Handling exceptions
Sharing External Data with an ILE C Program or Procedure
Returning Control from an ILE C Program or Procedure
Examples of an ILE C Procedure Call from an ILE COBOL Program
Sample Code for ILE C Procedure Call Example 1
Sample Code for ILE C Procedure Call Example 2
Creating and Running the ILE C Procedure Call Examples
Example of an ILE C Program Call from an ILE COBOL Program
Sample Code for ILE C Program Call Example
Creating and Running the ILE C Program Call Example
Calling ILE RPG Programs and Procedures
Passing Data to an ILE RPG Program or Procedure
Data Type Compatibility between ILE RPG and ILE COBOL
Returning Control from an ILE RPG Program or Procedure
Calling ILE CL Programs and Procedures
Passing Data to an ILE CL Program or Procedure
Data Type Compatibility between ILE CL and ILE COBOL
Returning Control from an ILE CL Program or Procedure
Calling OPM Languages
Issuing a CL Command from an ILE COBOL Program
Including Structured Query Language (SQL) Statements in Your ILE COBOL Program
Calling an ILE API to Retrieve Current Century
Using Intrinsic Functions or the ACCEPT Statement to Retrieve Current Century
Calling IFS API
Defining Pointers
Pointer Alignment
Writing the File Section and Working-Storage Section for Pointer Alignment
Redefining Pointers
Reading and Writing Pointers
Setting the Address of Linkage Section Items
Using ADDRESS OF and the ADDRESS OF Special Register
Using Pointers in a MOVE Statement
Using Pointers in a CALL Statement
Adjusting the Value of Pointers
Accessing User Spaces Using Pointers and APIs
Processing a Chained List Using Pointers
Passing Pointers between Programs and Procedures
Check for the End of the Chained List
Processing the Next Record
Chapter 14. Preparing ILE COBOL Programs for Multithreading
How Language Elements Are Interpreted in a Multithreaded Environment
Working with Run-Unit Scoped Elements
Working with Program Invocation Instance Scoped Elements
Choosing THREAD for Multithreading Support
Language Restrictions under THREAD
Limitations on ILE COBOL in a Multithreaded Environment
Example of Using ILE COBOL in a Multithreaded Environment
Sample Code for the Multithreading Example
Creating and Running the Multithreading Example
Chapter 15. ILE COBOL Error and Exception Handling
ILE Condition Handling
Using Error Handling Bindable Application Programming Interfaces (APIs)
Initiating Deliberate Dumps
Program Status Structure
Processing of Input-Output Verbs
Detecting Invalid Key Conditions (INVALID KEY Phrase)
Using EXCEPTION/ERROR Declarative Procedures (USE Statement)
Determining the Type of Error Through the File Status Key
Interpreting Major and Minor Return Codes
Handling Messages through Condition Handlers
Handling Errors in Sort/Merge Operations
Handling Exceptions on the CALL Statement
User-Written Error Handling Routines
Recovery After a Failure
TRANSACTION File Recovery
Handling Errors in Locale Operations
Part 3. ILE COBOL Input-Output Considerations
Chapter 16. Defining Files
Types of File Descriptions
Using Externally Described Files in an ILE COBOL Program
Specifying Nonkeyed and Keyed Record Retrieval
Level Checking the Externally Described Files
Chapter 17. Processing Files
Input Spooling
Output Spooling
Locking and Releasing Files
Locking and Releasing Records
Unblocking Input Records and Blocking Output Records
Using File Status and Feedback Areas
FILE STATUS
OPEN-FEEDBACK Area
I-O-FEEDBACK Area
Sorting and Merging Files
Floating-Point Considerations
Sorting Variable Length Records
Declaring Data Items Using SAA Data Types
Variable-length Fields
Class Date-Time
Class Alphanumeric
Examples of How the *DATETIME Compiler Option Works with *DATE
Null-Capable Fields
Using Null Maps and Null Key Maps in Input and Output Operations
Positioning to a Null-Capable Record in a Database File
Deleting a Null-Capable Record in a Database File
Example of Using Null Maps and Null Key Maps
DBCS-Graphic Fields
Floating-point Fields
Types of Device Files
Writing to Printer Files
Example of Using FORMATFILE Files in an ILE COBOL Program
Accessing Files Stored on Tape Devices
Naming Files Stored on Tape Devices
Describing Files Stored on Tape Devices
Describing Tape Files with Variable Length Records
Reading and Writing Files Stored on Tape Devices
Reading and Writing Tape Files with Variable Length Records
Accessing Files Stored on Diskette Devices
Naming Files Stored on Diskette Devices
Describing Files Stored on Diskette Devices
Reading and Writing Files Stored on Diskette Devices
Accessing Display Devices and ICF Files
Chapter 19. Using DISK and DATABASE Files
Differences between DISK and DATABASE Files
File Organization and iSeries File Access Paths
File Processing Methods for DISK and DATABASE Files
Processing Sequential Files
Processing Relative Files
Processing Indexed Files
Valid RECORD KEYs
Alternate Record Keys
Describing DISK Files with Variable Length Records
Opening DISK Files with Variable Length Records
Reading and Writing DISK Files with Variable Length Records
Examples of Processing DISK and DATABASE Files
Sequential File Creation
Relative File Creation
Relative File Updating
Relative File Retrieval
Indexed File Creation
Indexed File Updating
OS/400 System Files
Using DDM Files with Non-OS/400 Systems
DDM Programming Considerations
Distributed Files
When Distributed Data Processing is Overridden
When Distributed Data Processing is NOT Overridden
Input/Output Considerations for Distributed Files
Example of How Records are Retrieved for Insert, Update, and Delete
SQL Statement Additions for Distributed Data Files
Examples of Processing Distributed Files
Processing Files with Constraints
Checking that Constraints Have Been Successfully Added or Removed
Order of Operations
Handling Constraint Violations
Journaling
Defining Transaction Files Using Data Description Specifications
Processing an Externally Described Transaction File
Writing Programs That Use Transaction Files
Naming a Transaction File
Describing a Transaction File
Processing a Transaction File
Opening a Transaction File
Dropping Program Devices
Using Indicators with Transaction Files
Passing Indicators in a Separate Indicator Area
Passing Indicators in the Record Area
Examples of Using Indicators in ILE COBOL Programs
Using Subfile Transaction Files
Using Subfiles for a Display File
Accessing Single Device Files and Multiple Device Files
Writing Programs That Use Subfile Transaction Files
Naming a Subfile Transaction File
Describing a Subfile Transaction File
Processing a Subfile Transaction File
Opening a Subfile Transaction File
Acquiring Program Devices
Replacing (Rewriting) a Subfile Record
Dropping Program Devices
Example of Using WRITE SUBFILE in an Order Inquiry Program
Example of Using READ SUBFILE...NEXT MODIFIED and REWRITE SUBFILE in a Payment Update Program
Part 4. Appendixes
COBOL Standard
System Application Architecture® (SAA®) Common Programming Interface (CPI) Support
Appendix B. The Federal Information Processing Standard (FIPS) Flagger
Appendix C. ILE COBOL Messages
COBOL Message Descriptions
Using DBCS Characters in Literals
How to Specify Literals Containing DBCS Characters
Other Considerations
How to Continue Mixed Literals on a New Line
Syntax-Checker Considerations
Where You Can Use DBCS Characters in a COBOL Program
How to Write Comments
Appendix E. Example of a COBOL Formatted Dump
Appendix F. XML reference material
XML exceptions that allow continuation
XML exceptions that do not allow continuation
XML conformance
Appendix G. Migration and Compatibility Considerations between OPM COBOL/400 and ILE COBOL
Migration Strategy
Compatibility Considerations
General Considerations
Area Checking
Attributes Field in the Data Division Map Section of the Compiler Listing
MIXED, COMMUNICATIONS, and BSC files
Reserved Words
CL Commands
Coded Character Set Identifiers (CCSID)
Default Source Member Type
Compiler-Directing Statements
COPY Statement
PROCESS Statement
FILE-CONTROL and I-O-CONTROL Paragraphs
FD or SD Entries
CALL Statement
CANCEL Statement
COMPUTE Statement
DELETE Statement
EVALUATE Statement
IF Statement
INSPECT Statement
MOVE Statement
OPEN Statement
PERFORM Statement
READ Statement
REWRITE Statement
SET Statement
SORT/MERGE Statements
Error Messages
Appendix H. Glossary of Abbreviations
Appendix I. ILE COBOL Documentation
Online Information
Hardcopy Information