Developer for System z
COBOL for Windows, Version 7.5, Programming Guide
Contents
About this document
Accessibility of this document
How this document will help you
Abbreviated terms
How to read syntax diagrams
How examples are shown
Summary of changes
Version 7 (December 2006)
Version 6 (May 2005)
How to send your comments
Coding your program
Structuring your program
Identifying a program
Identifying a program as recursive
Marking a program as callable by containing programs
Setting a program to an initial state
Changing the header of a source listing
Describing the computing environment
Example: FILE-CONTROL paragraph
Specifying the collating sequence
Defining symbolic characters
Defining a user-defined class
Identifying files to the operating system
Describing the data
Using data in input and output operations
Comparison of WORKING-STORAGE and LOCAL-STORAGE
Using data from another program
Processing the data
How logic is divided in the PROCEDURE DIVISION
Declaratives
Using data
Using variables, structures, literals, and constants
Using variables
Using data items and group items
Using literals
Using constants
Using figurative constants
Assigning values to data items
Examples: initializing data items
Initializing a structure (INITIALIZE)
Assigning values to elementary data items (MOVE)
Assigning values to group data items (MOVE)
Assigning arithmetic results (MOVE or COMPUTE)
Assigning input from a screen or file (ACCEPT)
Displaying values on a screen or in a file (DISPLAY)
Using intrinsic functions (built-in functions)
Using tables (arrays) and pointers
Working with numbers and arithmetic
Defining numeric data
Displaying numeric data
Controlling how numeric data is stored
Formats for numeric data
External decimal (DISPLAY and NATIONAL) items
External floating-point (DISPLAY and NATIONAL) items
Binary (COMP) items
Native binary (COMP-5) items
Byte reversal of binary data
Packed-decimal (COMP-3) items
Internal floating-point (COMP-1 and COMP-2) items
Examples: numeric data and internal representation
Data format conversions
Conversions and precision
Sign representation of zoned and packed-decimal data
Checking for incompatible data (numeric class test)
Performing arithmetic
Using COMPUTE and other arithmetic statements
Using arithmetic expressions
Using numeric intrinsic functions
Examples: numeric intrinsic functions
Fixed-point contrasted with floating-point arithmetic
Floating-point evaluations
Fixed-point evaluations
Arithmetic comparisons (relation conditions)
Examples: fixed-point and floating-point evaluations
Using currency signs
Example: multiple currency signs
Handling tables
Defining a table (OCCURS)
Nesting tables
Example: subscripting
Example: indexing
Referring to an item in a table
Subscripting
Indexing
Putting values into a table
Loading a table dynamically
Initializing a table (INITIALIZE)
Assigning values when you define a table (VALUE)
Example: PERFORM and subscripting
Example: PERFORM and indexing
Creating variable-length tables (DEPENDING ON)
Loading a variable-length table
Assigning values to a variable-length table
Searching a table
Doing a serial search (SEARCH)
Doing a binary search (SEARCH ALL)
Processing table items using intrinsic functions
Example: processing tables using intrinsic functions
Selecting and repeating program actions
Selecting program actions
Coding a choice of actions
Coding conditional expressions
Repeating program actions
Choosing inline or out-of-line PERFORM
Coding a loop
Looping through a table
Executing multiple paragraphs or sections
Handling strings
Joining data items (STRING)
Example: STRING statement
Splitting data items (UNSTRING)
Example: UNSTRING statement
Manipulating null-terminated strings
Example: null-terminated strings
Referring to substrings of data items
Reference modifiers
Example: arithmetic expressions as reference modifiers
Example: intrinsic functions as reference modifiers
Tallying and replacing data items (INSPECT)
Examples: INSPECT statement
Converting data items (intrinsic functions)
Converting to uppercase or lowercase (UPPER-CASE, LOWER-CASE)
Transforming to reverse order (REVERSE)
Converting to numbers (NUMVAL, NUMVAL-C)
Converting from one code page to another
Evaluating data items (intrinsic functions)
Evaluating single characters for collating sequence
Finding the largest or smallest data item
Finding the length of data items
Finding the date of compilation
Processing files
Identifying files
Identifying Btrieve files
Identifying STL files
Identifying RSD files
File system
STL file system
RSD file system
Protecting against errors when opening files
Specifying a file organization and access mode
File organization and access mode
Setting up a field for file status
Describing the structure of a file in detail
Coding input and output statements for files
Example: COBOL coding for files
File position indicator
Opening a file
Reading records from a file
Adding records to a file
Replacing records in a file
Deleting records from a file
PROCEDURE DIVISION statements used to update files
Sorting and merging files
Sort and merge process
Describing the sort or merge file
Describing the input to sorting or merging
Example: describing sort and input files for SORT
Coding the input procedure
Describing the output from sorting or merging
Coding the output procedure
Restrictions on input and output procedures
Requesting the sort or merge
Setting sort or merge criteria
Choosing alternate collating sequences
Example: sorting with input and output procedures
Determining whether the sort or merge was successful
Sort and merge error numbers
Stopping a sort or merge operation prematurely
Handling errors
Handling errors in joining and splitting strings
Handling errors in arithmetic operations
Example: checking for division by zero
Handling errors in input and output operations
Using the end-of-file condition (AT END)
Coding ERROR declaratives
Using file status keys
Using file system status codes
Handling errors when calling programs
Enabling programs for international environments
Processing data in an international environment
COBOL statements and national data
Intrinsic functions and national data
Unicode and the encoding of language characters
Using national data (Unicode) in COBOL
Defining national data items
Using national literals
Using national-character figurative constants
Defining national numeric data items
National groups
Using national groups
Storage of national data
Converting to or from national (Unicode) representation
Converting alphanumeric, DBCS, and integer data to national data (MOVE)
Converting alphanumeric and DBCS data to national data (NATIONAL-OF)
Converting national data to alphanumeric data (DISPLAY-OF)
Overriding the default code page
Example: converting to and from national data
Processing UTF-8 data
Processing Chinese GB 18030 data
Comparing national (UTF-16) data
Comparing two class national operands
Comparing class national and class numeric operands
Comparing national numeric and other numeric operands
Comparing national character-string and other character-string operands
Comparing national data and alphanumeric-group operands
Coding for use of DBCS support
Declaring DBCS data
Using DBCS literals
Testing for valid DBCS characters
Processing alphanumeric data items that contain DBCS data
Setting the locale
The active locale
Specifying the code page with a locale
Using environment variables to specify a locale
Determination of the locale from system settings
Types of messages for which translations are available
Locales and code pages that are supported
Controlling the collating sequence with a locale
Controlling the alphanumeric collating sequence with a locale
Controlling the DBCS collating sequence with a locale
Controlling the national collating sequence with a locale
Intrinsic functions that depend on collating sequence
Accessing the active locale and code-page values
Example: get and convert a code-page ID
Compiling, linking, running, and debugging your program
Compiling, linking, and running programs
Setting environment variables
Setting environment variables for COBOL for Windows
Compiler environment variables
Linker environment variables
Runtime environment variables
Compiling programs
Compiling from the command line
Compiling using batch files or command files
Specifying compiler options with the PROCESS (CBL) statement
Correcting errors in your source program
Severity codes for compiler error messages
Generating a list of compiler error messages
cob2 options
Options that apply to compiling
Options that apply to linking
Options that apply to both compiling and linking
Linking programs
File names and extensions supported by cob2
Specifying linker options
Linking through the compiler
Linking from the command line
Linker input and output files
File-name defaults
Correcting errors in linking
Linker return codes
Linker errors in program-names
Using NMAKE to update projects
Running NMAKE on the command line
Running NMAKE with a command file
Defining description files for NMAKE
Running programs
Redistributing COBOL for Windows DLLs
Compiling, linking, and running OO applications
Compiling OO applications
Preparing OO applications
Example: compiling and linking a COBOL class definition
Running OO applications
Running OO applications that start with a main method
Running OO applications that start with a COBOL program
Compiler options
Conflicting compiler options
ADATA
ARITH
BINARY
CALLINT
CHAR
CICS
COLLSEQ
COMPILE
CURRENCY
DATEPROC
DIAGTRUNC
DYNAM
ENTRYINT
EXIT
Character string formats
User-exit work area
Linkage conventions
Parameter list for exit modules
Using INEXIT
Using LIBEXIT
Using PRTEXIT
Using ADEXIT
FLAG
FLAGSTD
FLOAT
LIB
LINECOUNT
LIST
LSTFILE
MAP
MDECK
NCOLLSEQ
NSYMBOL
NUMBER
OPTIMIZE
PGMNAME
PGMNAME(UPPER)
PGMNAME(MIXED)
PROBE
QUOTE/APOST
SEPOBJ
Batch compilation
SEQUENCE
SIZE
SOSI
SOURCE
SPACE
SQL
SSRANGE
TERMINAL
TEST
THREAD
TRUNC
TRUNC example 1
TRUNC example 2
VBREF
WSCLEAR
XREF
YEARWINDOW
ZWB
Compiler-directing statements
Linker options
/?
/ALIGNADDR
/ALIGNFILE
/BASE
/CODE
/DATA
/DBGPACK, /NODBGPACK
/DEBUG, /NODEBUG
/DEFAULTLIBRARYSEARCH, /NODEFAULTLIBRARYSEARCH
/DLL
/ENTRY
/EXECUTABLE
/EXTDICTIONARY, /NOEXTDICTIONARY
/FIXED, /NOFIXED
/FORCE, /NOFORCE
/HEAP
/HELP
/INCLUDE
/INFORMATION, /NOINFORMATION
/LINENUMBERS, /NOLINENUMBERS
/LOGO, /NOLOGO
/MAP, /NOMAP
/OUT
/PMTYPE
/SECTION
/SEGMENTS
/STACK
/STUB
/SUBSYSTEM
/VERBOSE, /NOVERBOSE
/VERSION
Runtime options
CHECK
DEBUG
ERRCOUNT
FILESYS
TRAP
UPSI
Debugging
Debugging with source language
Tracing program logic
Finding and handling input-output errors
Validating data
Finding uninitialized data
Generating information about procedures
Debugging using compiler options
Finding coding errors
Finding line sequence problems
Checking for valid ranges
Selecting the level of error to be diagnosed
Finding program entity definitions and references
Listing data items
Using the debugger
Getting listings
Example: short listing
Example: SOURCE and NUMBER output
Example: MAP output
Example: XREF output - data-name cross-references
Example: VBREF compiler output
Debugging user exits
Debugging assembler routines
Accessing databases
Programming for a DB2 environment
DB2 coprocessor
Coding SQL statements
Using SQL INCLUDE with the DB2 coprocessor
Using binary items in SQL statements
Determining the success of SQL statements
Starting DB2 before compiling
Compiling with the SQL option
Separating DB2 suboptions
Using package and bind file-names
Developing COBOL programs for CICS
Coding COBOL programs to run under CICS
Getting the system date under CICS
Making dynamic calls under CICS
Compiling and running CICS programs
Integrated CICS translator
Debugging CICS programs
Open Database Connectivity (ODBC)
Comparison of ODBC and embedded SQL
Background
Installing and configuring software for ODBC
Coding ODBC calls from COBOL: overview
Using data types appropriate for ODBC
Passing pointers as arguments in ODBC calls
Accessing function return values in ODBC calls
Testing bits in ODBC calls
Using COBOL copybooks for ODBC APIs
Example: sample program using ODBC copybooks
Example: copybook for ODBC procedures
Example: copybook for ODBC data definitions
ODBC names truncated or abbreviated for COBOL
Compiling and linking programs that make ODBC calls
Understanding ODBC error messages
Using XML and COBOL together
Processing XML input
XML parser in COBOL
Accessing XML documents
Parsing XML documents
The content of XML-EVENT
Example: processing XML events
Writing procedures to process XML
Understanding the encoding of XML documents
Coded character sets for XML documents
Specifying the code page
Handling exceptions that the XML parser finds
How the XML parser handles errors
Handling conflicts in code pages
Terminating XML parsing
Producing XML output
Generating XML output
Example: generating XML
Enhancing XML output
Example: enhancing XML output
Example: converting hyphens in element names to underscores
Controlling the encoding of generated XML output
Handling errors in generating XML output
Developing object-oriented programs
Writing object-oriented programs
Example: accounts
Subclasses
Defining a class
CLASS-ID paragraph for defining a class
REPOSITORY paragraph for defining a class
WORKING-STORAGE SECTION for defining class instance data
Example: defining a class
Defining a class instance method
METHOD-ID paragraph for defining a class instance method
INPUT-OUTPUT SECTION for defining a class instance method
DATA DIVISION for defining a class instance method
PROCEDURE DIVISION for defining a class instance method
Overriding an instance method
Overloading an instance method
Coding attribute (get and set) methods
Example: defining a method
Defining a client
REPOSITORY paragraph for defining a client
DATA DIVISION for defining a client
Comparing and setting object references
Invoking methods (INVOKE)
Creating and initializing instances of classes
Freeing instances of classes
Example: defining a client
Defining a subclass
CLASS-ID paragraph for defining a subclass
REPOSITORY paragraph for defining a subclass
WORKING-STORAGE SECTION for defining subclass instance data
Defining a subclass instance method
Example: defining a subclass (with methods)
Defining a factory section
WORKING-STORAGE SECTION for defining factory data
Defining a factory method
Example: defining a factory (with methods)
Wrapping procedure-oriented COBOL programs
Structuring OO applications
Examples: COBOL applications that you can run using the java command
Communicating with Java methods
Accessing JNI services
Handling Java exceptions
Managing local and global references
Java access controls
Sharing data with Java
Coding interoperable data types in COBOL and Java
Declaring arrays and strings for Java
Manipulating Java arrays
Manipulating Java strings
Working with more complex applications
Porting applications between platforms
Getting mainframe applications to compile
Getting mainframe applications to run: overview
Fixing differences caused by data representations
Fixing environment differences that affect portability
Fixing differences caused by language elements
Writing code to run on the mainframe
Writing applications that are portable between the Windows-based and AIX workstations
Using subprograms
Main programs, subprograms, and calls
Ending and reentering main programs or subprograms
Calling nested COBOL programs
Nested programs
Example: structure of nested programs
Scope of names
Calling nonnested COBOL programs
CALL identifier and CALL literal
Call interface conventions
CDECL
OPTLINK
SYSTEM
Calling between COBOL and C/C++ programs
Initializing environments
Passing data between COBOL and C/C++
Setting linkage conventions for COBOL and C/C++
Collapsing stack frames and terminating run units or processes
COBOL and C/C++ data types
Example: COBOL program calling C/C++ DLL
Making recursive calls
Sharing data
Passing data
Describing arguments in the calling program
Describing parameters in the called program
Testing for OMITTED arguments
Coding the LINKAGE SECTION
Coding the PROCEDURE DIVISION for passing arguments
Grouping data to be passed
Handling null-terminated strings
Using pointers to process a chained list
Using procedure and function pointers
Dealing with a Windows restriction
Coding multiple entry points
Passing return-code information
Understanding the RETURN-CODE special register
Using PROCEDURE DIVISION RETURNING . . .
Specifying CALL . . . RETURNING
Sharing data by using the EXTERNAL clause
Sharing files between programs (external files)
Example: using external files
Using command-line arguments
Example: command-line arguments
Building dynamic link libraries
Static linking and dynamic linking
How the linker resolves references to DLLs
Creating DLLs
Example: DLL source file and related files
Creating module definition files
Reserved words for module statements
Summary of module statements
BASE
DESCRIPTION
EXPORTS
HEAPSIZE
LIBRARY
NAME
STACKSIZE
STUB
VERSION
Preparing COBOL programs for multithreading
Multithreading
Working with language elements with multithreading
Working with elements that have run-unit scope
Working with elements that have program invocation instance scope
Scope of COBOL language elements with multithreading
Choosing THREAD to support multithreading
Transferring control to multithreaded programs
Ending multithreaded programs
Handling COBOL limitations with multithreading
Example: using COBOL in a multithreaded environment
Source code for thrcob.c
Source code for subd.cbl
Source code for sube.cbl
Preinitializing the COBOL runtime environment
Initializing persistent COBOL environment
Terminating preinitialized COBOL environment
Example: preinitializing the COBOL environment
Processing two-digit-year dates
Millennium language extensions (MLE)
Principles and objectives of these extensions
Resolving date-related logic problems
Using a century window
Using internal bridging
Moving to full field expansion
Using year-first, year-only, and year-last date fields
Compatible dates
Example: comparing year-first date fields
Using other date formats
Example: isolating the year
Manipulating literals as dates
Assumed century window
Treatment of nondates
Using sign conditions
Performing arithmetic on date fields
Allowing for overflow from windowed date fields
Specifying the order of evaluation
Controlling date processing explicitly
Using DATEVAL
Using UNDATE
Example: DATEVAL
Example: UNDATE
Analyzing and avoiding date-related diagnostic messages
Avoiding problems in processing dates
Avoiding problems with packed-decimal fields
Moving from expanded to windowed date fields
Improving performance and productivity
Tuning your program
Using an optimal programming style
Using structured programming
Factoring expressions
Using symbolic constants
Grouping constant computations
Grouping duplicate computations
Choosing efficient data types
Choosing efficient computational data items
Using consistent data types
Making arithmetic expressions efficient
Making exponentiations efficient
Handling tables efficiently
Optimization of table references
Optimizing your code
Optimization
Choosing compiler features to enhance performance
Performance-related compiler options
Evaluating performance
Simplifying coding
Eliminating repetitive coding
Example: using the COPY statement
Manipulating dates and times
Getting feedback from date and time callable services
Handling conditions from date and time callable services
Example: manipulating dates
Example: formatting dates for output
Feedback token
Picture character terms and strings
Example: date-and-time picture strings
Century window
Appendixes
Appendixes
Appendix A. Summary of differences with host COBOL
Compiler options
Data representation
Binary data
Zoned decimal data
Packed-decimal data
Display floating-point data
National data
EBCDIC and ASCII data
Code-page determination for data conversion
DBCS character strings
Environment variables
File specification
Interlanguage communication (ILC)
Input and output
Runtime options
Source code line size
Language elements
Appendix B. zSeries host data format considerations
CICS access
Date and time callable services
Floating-point overflow exceptions
DB2
Object-oriented syntax for Java interoperability
MQ applications
File data
SORT
Appendix C. Intermediate results and arithmetic precision
Terminology used for intermediate results
Example: calculation of intermediate results
Fixed-point data and intermediate results
Addition, subtraction, multiplication, and division
Exponentiation
Example: exponentiation in fixed-point arithmetic
Truncated intermediate results
Binary data and intermediate results
Intrinsic functions evaluated in fixed-point arithmetic
Integer functions
Mixed functions
Floating-point data and intermediate results
Exponentiations evaluated in floating-point arithmetic
Intrinsic functions evaluated in floating-point arithmetic
Arithmetic expressions in nonarithmetic statements
Appendix D. Complex OCCURS DEPENDING ON
Example: complex ODO
How length is calculated
Setting values of ODO objects
Effects of change in ODO object value
Preventing index errors when changing ODO object value
Preventing overlay when adding elements to a variable table
Appendix E. Date and time callable services
CEECBLDY—convert date to COBOL integer format
CEEDATE—convert Lilian date to character format
CEEDATM—convert seconds to character timestamp
CEEDAYS—convert date to Lilian format
CEEDYWK—calculate day of week from Lilian date
CEEGMT—get current Greenwich Mean Time
CEEGMTO—get offset from Greenwich Mean Time to local time
CEEISEC—convert integers to seconds
CEELOCT—get current local date or time
CEEQCEN—query the century window
CEESCEN—set the century window
CEESECI—convert seconds to integers
CEESECS—convert timestamp to seconds
CEEUTC—get coordinated universal time
IGZEDT4—get current date
Appendix F. XML reference material
XML PARSE exceptions that allow continuation
XML PARSE exceptions that do not allow continuation
XML conformance
XML GENERATE exceptions
Appendix G. JNI.cpy
Appendix H. COBOL SYSADATA file contents
Existing compiler options affecting the SYSADATA file
SYSADATA record types
Example: SYSADATA
SYSADATA record descriptions
Common header section
Job identification record - X'0000'
ADATA identification record - X'0001'
Compilation unit start|end record - X'0002'
Options record - X'0010'
External symbol record - X'0020'
Parse tree record - X'0024'
Token record - X'0030'
Source error record - X'0032'
Source record - X'0038'
COPY REPLACING record - X'0039'
Symbol record - X'0042'
Symbol cross-reference record - X'0044'
Nested program record - X'0046'
Library record - X'0060'
Statistics record - X'0090'
EVENTS record - X'0120'
Appendix I. Runtime messages
How to read dotted decimal diagrams
Image description: Account class
Image description: inheritance hierarchy
Image description: inheritance hierarchy 2
Image description: converting to UTF-8
Image description: XML parsing flow overview
Image description: do-until structure
Image description: VBREF compiler output
Image description: embedded cross-reference
Image description: embedded messages
Image description: DATA DIVISION map
Image description: embedded map summary
Image description: short listing
Image description: SOURCE and NUMBER output
Image description: error handling for VSAM files
Image description: ODO storage layout
Image description: updated ODO storage layout
Image description: compiling and linking a class definition
Image description: argument-passing mechanism for CALLINT SYSTEM DESC
Image description: a chained list
Image description: values after the STRING statement
Image description: input data for UNSTRING statement
Image description: converting to GB 18030
Image description: nested program structure
Image description: structure of nested programs
Image description: LINKAGE SECTION
Image description: one-dimensional table
Image description: two-dimensional table
Image description: three-dimensional table
Notices
Trademarks
Glossary
List of resources
COBOL for Windows
Related publications
Index
Terms of use
|
Feedback
Copyright IBM Corporation 1996, 2008.
This information center is powered by Eclipse technology. (http://www.eclipse.org)