Documentation errata for IBM COBOL for AIX, V4.1.1

Content

Installation Guide
The following corrections and additions apply to the IBM COBOL for AIX, V4.1 Installation Guide:

Global changes
All occurrences of 4.1 in the documentation should now be 4.1.1.
Any reference to PL/I for AIX, Version 2 is now PL/I for AIX, Version 2 or later.


Before installing COBOL for AIX
Upgrading the evaluation copy of the COBOL for AIX compiler
You can upgrade the evaluation version of the compiler to the licensed version by installing the licensed product package on top of the evaluation package. By following the installation procedure for the licensed product package, the compiler license can be installed. Shared filesets between the evaluation and licensed versions that have already been installed are reported as Already installed.

The installation image and filesets
The installation image for COBOL for AIX is available physically on an installation CD and electronically in the cobol.4.1.1.aix.GM.tar.Z installation package, in the /usr/sys/inst.images directory.

Fileset information

Fileset name	Fileset description	Installation locations
cobol.license	COBOL for AIX electronic license LANG = [en_US, ja_JP, Ja_JP]	/usr/swlag/cobol/GM/411/LANG/cobol.la
cobol.man	COBOL for AIX compiler invocation command man pages COBOL for AIX utility (scu and gdgmgr) man pages	/usr/share/man/man1 /usr/lpp/cobol/man/man1

SMARTdata Utilities filesets

Important: SdU filesets are backward compatible with COBOL for AIX, Version 2 or later and PL./I for AIX, Version 2 or later.

Preparing the electronic distribution package
If you have downloaded the COBOL for AIX electronic distribution package, cobol.4.1.1.aix.GM.tar.Z, follow these steps before attempting to install:

Remember: You must be logged in as root user or have superuser authority.

1. To uncompress and unpack the file, use the command:
   zcat cobol.4.1.1.aix.GM.tar.Z | tar -xvf -
2. Use the command inutoc directory_name to generate a .toc file in the specified directory.

The following example shows the steps to prepare the electronic distribution package, cobol.4.1.1.aix.GM.tar.Z, located in the new directory, /compiler/install/ for installation.

cd /compiler/install
zcat cobol.4.1.1.aix.GM.tar.Z | tar -xvf -
cd usr/sys/inst.images
inutoc .

Refer to “System prerequisites” to ensure that system prerequisites are met and the installation method described in Chapter 2, “Installation,” on page 7 to install the compiler.

System prerequisites
Software requirements: Optional programs

CICS:

• COBOL applications that embed EXEC CICS statements require TXSeries for Multiplatforms:
• When you use the integrated translator: TXSeries for Multiplatforms, Version 6.2 with PTF 2 or TXSeries for Multiplatforms, Version 7.1.
• When you use the precompiler: TXSeries for Multiplatforms, Version 6.1 with PTF 4, or TXSeries for Multiplatforms, Version 6.2 with PTF 2, or TXSeries for Multiplatforms, Version 7.1.
• When you use both the integrated translator and the precompiler: TXSeries for Multiplatforms, Version 6.2 with PTF 2 or TXSeries for Multiplatforms, Version 7.1.

Verifying the filesets are installed

Fileset name	Fileset description
AIX 5.3: bos.rte.aio.5.3.9.0 or later AIX 6.1: bos.rte.aio.6.1.2.0 or later AIX 7.1: bos.rte.aio.7.1.0.0	Base operating system run time posix asynchronous I/O

You need to enable posix asynchronous I/O (AIO) in order for it to work. For instructions about how to enable posix I/O, see the AIX documentation about AIO.


Update installation
Product version migration
If you have a previous version of the compiler, you can replace it with the current version.

If you are upgrading to COBOL for AIX, V4.1.1 using Chapter 2, “Installation,” on page 7, any previous versions of the filesets already installed on your system are automatically detected and migrated to the current version.

Once COBOL for AIX, V4.1.1 is installed, older compiler versions cannot be installed unless V4.1.1 is uninstalled first.


After installing COBOL for AIX
Setting environment variables

MANPATH

Optionally specifies the directory search path for finding man pages. MANPATH must contain /usr/lpp/cobol/man before the default man path.

To run the COBOL for AIX utilities, add the following directory to the PATH environment variable by entering this command:

export PATH=$PATH:/usr/lpp/cobol/bin

Enabling the man pages
man pages are provided for the compiler invocation commands and other compiler utilities (scu and gdgmgr).

Before you can view the COBOL for AIX utility man pages, you must add the man page directory to the MANPATH environment variable by entering the following command:

export MANPATH=$MANPATH:/usr/lpp/cobol/man

The directory search path for finding the compiler invocation command man pages is already set in the default man path.

To test whether the man pages have been successfully installed, open one or more of the man pages, as described in Viewing the man pages.

Viewing the man pages
man pages are included for all compiler invocation commands and utilities.

For instructions about how to enable the man pages for viewing, see Enabling the man pages.

To invoke a man page, run this command:

man command

command is any COBOL for AIX invocation or utility command.

Examples:
man cob2
man scu
man gdgmgr


Uninstalling COBOL for AIX
Uninstalling the electronic license agreement
To remove the license agreement text file, run the commands:

ODMDIR=/usr/lib/objrepos; odmdelete -o lag -q "fileset=cobol.license"
rm -rf /usr/swlag/cobol/GM/411/*/cobol.la

--------------------------------------------------------------------------------------
Programming Guide
The following corrections and additions apply to the IBM COBOL for AIX, V4.1 Programming Guide:


Chapter 7. Processing files
Identifying files

RAW Raw file system.

RSD
You can specify RSD only for SEQUENTIAL files that have fixed and variable-length records.

For SEQUENTIAL files that have fixed and variable-length records, RSD is also a valid choice.

File systems
RSD files are sequential only, with fixed and variable-length records, and support all COBOL data types in records.

RAW file system: lets COBOL programs access QSAM files transferred (using z/OS FTP) using specific options from z/OS to AIX.

RAW file system
The RAW file system supports fixed, variable, and spanned records, and enables you to directly access a QSAM file that you transferred (using z/OS FTP) from z/OS to AIX using the options "binary" and "quote site rdw".

RAW files provide good performance. They give you the ability to port files easily between AIX, Windows-based systems, and the mainframe.

RAW files support all COBOL data types in the record.

The RAW file system is safe for use with threads. However, you must ensure that multiple threads do not access the level-01 records for the file at the same time. Multiple threads can perform operations on the same RAW file, but you must add pthread_cont_wait call or its equivalent to force all but one of the threads to wait for the file access to complete on the active thread.

You can obtain a RAW file from the mainframe using FTP with the options "binary" and "quote site rdw". If the file contains EBCDIC character data, the AIX COBOL program should be compiled with -host to read or write the character data as EBCDIC. You can upload the same RAW file to the mainframe provided the file already exists. If the file does not exist, then you must create it using the correct data set attributes.

RSD file system
The RSD (record sequential delimited) file system supports sequential files that have fixed and variable-length records.

RSD files support all COBOL data types in records of fixed and variable length.

If you edit an RSD file with a text editor, you must ensure that the length of each
record is maintained. For example, if you edit file infile, and want to ensure that
each record has 80 characters, you can pad each record to column 80 with spaces
and write the result to file outfile by issuing this command:
awk ’{printf("\%-80s\n",$0)}’ infile > outfile

Attempting a WRITE statement with the AFTER ADVANCING or BEFORE ADVANCING
phrase to an RSD file causes the statement to fail with the file status key set to 30.

File system summary

In COBOL for AIX, Version 3 and Version 4.1, you could indicate that a COBOL for AIX program should create small or large-format files by specifying a runtime option FILEMODE(SMALL) or FILEMODE(LARGE), respectively. Beginning with version 4.1.1 of COBOL for AIX, you can no longer indicate that a COBOL for AIX program should create small or large-format files. Instead, by default, a COBOL for AIX Version 4.1.1 program will ignore the FILEMODE option and create large-format files.

For compatibility with COBOL for AIX Version 2, Version 3 and Version 4.1, you can read files created in small-format.

The following table, which applies to COBOL for AIX, Version 3 and Version 4.1, uses these terms:
(See the table in the Programming Guide)

Small-format
For STL and SdU files, indicates that they are limited to a maximum size of
2 GB. (STL and SdU files created by COBOL for AIX programs before
Version 3 had small format.)

For DB2 sequential and relative files, indicates that the maximum number
of records is 2 ** 32. DB2 indexed files have no COBOL limit.

To indicate that a COBOL for AIX program should create small-format
files, specify runtime option FILEMODE(SMALL).

Large-format
For STL and SdU files, indicates that they can exceed a size of 2 GB; file
size is limited to the maximum record size times the maximum number of
records.

For DB2 sequential and relative files, indicates that the maximum number
of records is 2 ** 64. DB2 indexed files have no COBOL limit.

To indicate that a COBOL for AIX program should create large-format files,
specify (or default to) FILEMODE(LARGE).


Table 11. COBOL for AIX, Version 3 and Version 4.1 file-system summary

File system and format

Is size > 2 GB supported?

32-bit COBOL for AIX Version 3 or Version 4.1 program with current runtime library

64-bit COBOL for AIX Version 3 or Version 4.1 program with current runtime library

COBOL for AIX Version 2 program with current runtime library

Chapter 9. Handling errors
Using file system status codes
You can get more detailed information about DB2, NAT, RSD, RAW, SdU, SFS, and STL file-system requests by coding a second data item in the FILE STATUS clause.

NAT(line-sequential), RAW, RSD, STL and SdU files: For NAT, RAW, RSD and SdU file system input and output requests, if data-name-8 is 6 bytes long, it contains the file status code. If data-name-8 is longer than 6 bytes, it also contains a message with further information:

01  my-file-status-2.
    02 exception-return-value PIC 9(6).
   02 additional-info        PIC X(100).

If you attempt to open a file using a different definition than the one with which the file was created, and use the file status code structure shown above, 39 is returned in exception-return-value, and a message that tells which keys you need in order to perform the open request is returned in additional-info.
additional-info might contain further diagnostic information to help you diagnose the problem.

SdU and SFS files: For SdU and SFS file-system input and output requests, define data-name-8 with PICTURE X(n) and USAGE DISPLAY attributes, where n is 6 or greater.


Chapter 12. Compiling, linking and running programs
Runtime environment variables
COBOL_BCD_NOVALIDATE
Specifies if the packed-decimal data item prior to conversion and arithmetic operations is validated.

When this environment variable is set to 1, the digit and sign validation done prior to conversion and arithmetic operations is skipped.

Using this environment variable does not affect the numeric class test that tests whether a data item IS NUMERIC or IS NOT NUMERIC.


Chapter 14. Compiler options

WSCLEAR

WSCLEAR option syntax

>>------- NOWSCLEAR--------------------------------><
     |                                        |  
    | -- WSCLEAR-----------------------------
                      |___(nnn)____|  

Default is: NOWSCLEAR

The WSCLEAR size, nnn, is any integer from 0 to 255. WSCLEAR without the suboption is the same as WSCLEAR(0).

Use NOWSCLEAR to bypass the storage-clearing process.

If you use WSCLEAR(nnn), the byte value represented by nnn will be used to initialize each byte of WORKING-STORAGE data to a specific value. This applies only to data items that do not have a VALUE attributed specified.


Chapter 16. Runtime options

Table 37. Runtime options

Option	Description	Default	Abbreviation
FILEMODE on page 319	Specifies whether DB2, SdU, and STL files created by COBOL for AIX programs have large-format or small-format internal representation, which determines the maximum size limit of these files	FILEMODE(LARGE)	FM(L|S)
FILESYS on page 320	Specifies the file system to use for files which no explicit files-system selection is made, either through the ASSIGN clause or an environment variable.	FILESYS(VSA)	FS(DB2|RAW|RSD|SdU| SFS|STL|VSA|VSAM)

FILEMODE
Beginning with version 4.1.1 of COBOL for AIX, you can no longer indicate that a COBOL for AIX program should create small or large-format files. Instead, by default, a COBOL for AIX Version 4.1.1 program will ignore the FILEMODE option and create large-format files.

For compatibility with COBOL for AIX Version 2, Version 3 and Version 4.1, you can read files created in small-format.

FILEMODE specifies whether DB2, SdU, and STL files created by using OPEN OUTPUT statements will have large-format or small-format metadata (internal control information), which affects their maximum size.

FILEMODE option syntax
                  ---LARGE--------
                   |              |
>>------FILEMODE(-----SMALL-----------)-------------------------><

Default is: FILEMODE(LARGE)
Abbreviation is: FM(L|S)

LARGE Specifies that OPEN OUTPUT statements for DB2, SdU, and STL files create
large-format files. SdU and STL large-format files can exceed 2 GB. DB2
sequential and relative large-format files have a maximum record count of
(2 ** 63) - 1. DB2 indexed files have no COBOL limit.

SMALL Specifies that OPEN OUTPUT statements for DB2, SdU and STL files create
small-format files. SdU and STL small-format files have a maximum size of
2 GB. DB2 sequential and relative small-format files have a maximum
record count of (2 ** 31) - 1. DB2 indexed files have no COBOL limit.

You can process large-format and small-format files with either 32-bit or 64-bit
COBOL for AIX programs. File processing is not sensitive to the value of the ADDR
compiler option.

Restriction: DB2 files that will interoperate with CICS TXSeries must be created
with FILEMODE(SMALL) in effect.

FILEMODE does not affect the processing of line-sequential, Encina SFS, or RSD files.
These files do not have a maximum COBOL size limit.


FILESYS

FILESYS option syntax

               |--VSA--|
>>---FILESYS( ---|--DB2--|----)----------------------------------------------------><
|--RAW--|
|--RSD--|
|--SdU--|
|--SFS--|
                 |--STL--|
|--VSAM-|

RAW The file system is host compatible for QSAM files.

Appendix A. Migration from earlier versions, and compatibility
Packed decimal conversion
Beginning with version 4.1.1 of COBOL for AIX, during the conversion of a numeric data item to and from a packed-decimal data item, negative zero is no longer converted to positive zero. Negative zero behaves the same as positive zero computationally, for example, it compares equal to positive zero. In most cases, negative zero will keep the negative sign when converted from zoned to packed, or vice versa. Negative zero appears rarely in computation. An example is adding -1 to -99 into a PIC 9(2) field. The result is -0 because the high-order 1 digit is truncated.

File format
Beginning with version 4.1.1 of COBOL for AIX, you can no longer indicate that a COBOL for AIX program should create small or large-format files. Instead, by default, a COBOL for AIX Version 4.1.1 program will ignore the FILEMODE option and create large-format files.

For compatibility with COBOL for AIX Version 2, Version 3 and Version 4.1, you can read files created in small-format.


Appendix B. Summary of differences from host COBOL
Input and output
COBOL for AIX supports input and output for sequential, relative, and indexed files with the DB2, SdU, SFS, and STL file systems, and also supports input and output for fixed and variable-length sequential files with the RSD file system and RAW file system. These file systems do not exist on the host.

Glossary
RSD file system
An RSD file supports all COBOL data types in fixed and variable-length records, can be edited by most file editors, and can be read by programs written in other languages. This system only supports sequential files.


Chapter 17. Debugging
Using the debugger
To invoke the debugger to examine an executable file, start the IBM Debugger for AIX Windows client and then the debug engine on AIX by issuing the command irmtdbgc -qhost=host filename where host specifies the host name of the machine running the debugger user interface, and filename is the name of your program.

For more information about the syntax of the irmtdbgc command, see IBM Debugger for AIX (Starting the debugger engine),

Debugging user exits
2. Debug the user exit as follows:

irmtdbgc -qhost=host IGYCCOB2 -q"EXIT(ADEXIT(IWZRMGUX))" pgmname.cbl

Debugging assembler routines
For example,

irmtdbgc -qhost=myhost progname

--------------------------------------------------------------------------------------
Language Reference
The following corrections and additions apply to the IBM COBOL for AIX, V4.1 Language Reference:

Chapter 16. Input-Output section

FILE-CONTROL paragraph

File organization	File system
Sequential	VSAM, SdU, SFS, STL, RSD, DB2, RAW(3)

2. The RSD file system supports fixed and variable-length record sequential files.
3. The RAW file system supports fixed, variable, and spanned records.

Line-sequential organization

The record length is determined by one of the following:

• The requested read length
• The location of the new-line character (\n)

The only special character in a line sequential file is the new-line character (\n). Any other character including NULL (0x00) is valid and will not cause read or write errors.

The following are not supported for line-sequential files:

• LINAGE clause
• WRITE ... AFTER ADVANCING mnemonic-name
• WRITE ... BEFORE ADVANCING
  

File status clause
STL, RSD, RAW, and native platform file systems


Chapter 18. Data division file-description entries

File section
All the record description entries under the file description entry (FD) for an RSD
file must be described with the same number of bytes. The following example
illustrates the file section for an RSD file with level 01 records that are of a fixed
length:
FILE SECTION.
FD an-RSD-file . . . RECORD CONTAINS 80 CHARACTERS.
01 record-1 PIC X(80).
01 record-2.
02 PIC X(10).
02 PIC X(70).

RECORD clause
For an RSD file, the RECORD clause, if specified, must describe fixed-length
records.

LINAGE clause
The LINAGE clause is effective for sequential files opened as OUTPUT or
EXTEND, except that the clause cannot be specified for RSD files.

RECORDING MODE clause
F Record descriptions are validated as fixed. Do not specify RECORDING MODE F if the record descriptions are variable. This is the only valid value for RSD files.


Chapter 20. Procedure division structure
File status key

Table 39: File status key values and meanings

High-order digit	Meaning	Low-order digit	Meaning
3	Permanent error condition	0	A WRITE statement with the BEFORE, AFTER phrase was attempted on an RSD file.
		9	An RSD file was declared with the indexed or relative organization, variable-length records, or the LINAGE clause.

Effect of CLOSE statement on file types
Non-reel/unit
A file whose input or output medium is such that rewinding, reels, and units have no meaning. All SdU, SFS, RAW, RSD, DB2, and STL files are non-reel/unit file types.

Sequential single volume
A sequential file that is contained entirely on one volume. More than one file can be contained on this volume. All SdU, SFS, RAW, RSD, DB2, and STL files are single volume.

Sequential multivolume
A sequential file that is contained on more than one volume. The concept of volume has no meaning for SdU, SFS, RAW, RSD, DB2, or STL files.


Chapter 21. Procedure division statements
Format 1: WRITE statement for sequential files
2. The BEFORE and AFTER phrases are not valid for RSD files.

ADVANCING phrase
7. The BEFORE ADVANCING and AFTER ADVANCING phrases are not supported for RSD files.



Appendix A: IBM Extensions
Table 60. IBM Extension Language Elements
XML-NAMESPACE, XML-NAMESPACE-PREFIX, XML-NNAMESPACE, and XML-NNAMESPACE-PREFIX are special registers for Enterprise COBOL. These registers should not be listed in the table. See Implicit items and special registers in the table.

Appendix B. Compiler limits
File input-output limitations
Beginning with version 4.1.1 of COBOL for AIX, you can no longer indicate that a COBOL for AIX program should create small or large-format files. Instead, by default, a COBOL for AIX Version 4.1.1 program will ignore the FILEMODE option and create large-format files.

For compatibility with COBOL for AIX Version 2, Version 3 and Version 4.1, you can read files created in small-format.

Line-sequential files

• Maximum record size: 2**64 -2
• Maximum number of records: no maximum
• Maximum record key value: not applicable
• Maximum number of bytes allocated for a file: 2**64 -1

SFS files

• Maximum record size: 2**32 -1
• Maximum number of records: 2**64
• Maximum record key value: 2**32 -1
• Maximum number of bytes allocated for a file: 64GB

SdU files

• Minimum record size: 1 byte
• Maximum record size: 64,000 bytes
• Maximum record key length: 255 bytes
• Maximum relative key value: 2**31 -1
• Maximum record size:
• If FILEMODE(LARGE) is in effect: 2**64 -2
• If FILEMODE(SMALL) is in effect: 2**32 -1
• Maximum number of records:
• If FILEMODE(LARGE) is in effect: 2**64
• If FILEMODE(SMALL) is in effect: 2**32
• Maximum record key value:
• If FILEMODE(LARGE) is in effect: 2**64 -1
• If FILEMODE(SMALL) is in effect: 2**32 -1
• Maximum number of bytes allocated per file:
• If FILEMODE(LARGE) is in effect: 2**64 -2
• If FILEMODE(SMALL) is in effect: 2**64 -2

STL files

• Minimum record size: 1 byte
• Maximum record size: 1,048,576 bytes
• Maximum record key length: 255 bytes
• Maximum number of alternate keys: 253
• Maximum relative key value: 2**31 -1
• Maximum record size:
• If FILEMODE(LARGE) is in effect: 2**32 -1
• If FILEMODE(SMALL) is in effect: 2**32 -1
• Maximum number of records:
• If FILEMODE(LARGE) is in effect: 2**64
• If FILEMODE(SMALL) is in effect: 2**32
• Maximum record key value:
• If FILEMODE(LARGE) is in effect: 2**32 -1
• If FILEMODE(SMALL) is in effect: 2**64 -1
• Maximum number of bytes allocated per file:
• If FILEMODE(LARGE) is in effect: 2**64 -2
• If FILEMODE(SMALL) is in effect: 2**64 -2

RSD files

• Fixed and variable records
• Minimum record size: 1 byte
• Maximum record size: 2**64 -2
• Maximum number of records: no maximum
• Maximum record key value: not applicable
• Maximum number of bytes allocated for a file: 2**64 -2

DB2 files

The limitations listed below assume simple tables and the default 4 KB database
page size.

• Minimum record size: 0 bytes
• Maximum row length: 4005 bytes
• Maximum record size for fixed-length records:
• Indexed records: 4005 bytes
• Small-format relative or sequential records: 4001 bytes
• Large-format relative or sequential records: 3997 bytes

Because keys must be at a fixed location in an indexed file record, there are separate constraints for indexed files that end with a variable-length data segment.

• Maximum record size for variable-length records:
• For VARCHAR columns, the limits are 4 bytes fewer than for fixed-length records, because the data for the VARCHAR type is maintained directly in the row, and is preceded by a 4-byte descriptor.
• For other variable length types, such as BLOB, only the descriptor is stored in the row. The data is stored separately, and has a maximum size of 2 GB.
• Maximum number of records for relative and sequential files:
• For small filemode: 2**32
• For large filemode: 2**64
• Maximum number of records or alternate keys: 500
• Maximum record key value:
• For small filemode: 2**32 -1
• For large filemode: 2**64 -1
• Maximum number of bytes allocated for a file: 64 GB

Appendix F: Reserved Words
Table 64. Reserved Words
XML-SCHEMA is a reserved word for AIX and should show in the list of reserved words shown in table 64.

Glossary
RSD file system
The record sequential delimited file system is a workstation file system that supports sequential files. An RSD file supports all COBOL data types in fixed and variable-length records, can be edited by most file editors, and can be read by programs written in other languages. This system only supports sequential files.