Running a PeopleSoft COBOL in a Unicode Environment
The character set that is used for PeopleSoft COBOL processing must match the character set for your database. If you created a Unicode database for the PeopleSoft system, you must also run COBOL in Unicode.
The Unicode standard provides several methods of encoding Unicode characters into a byte stream. Each encoding has specific properties that make it suitable for use in different environments. The two main encodings that are important to understanding how PeopleSoft COBOL operates when running in Unicode are:
- UCS-2 (2-byte Universal Character Set) — which is the Unicode encoding that PeopleTools uses internally for data that is held in memory on the application server. UCS-2 encodes all characters into a fixed storage space of two bytes.
- UTF-8 (8-bit Unicode Transformation Format) — which is the encoding that the PeopleSoft system uses in COBOL. UTF-8 uses a format that varies from one to four bytes per character.
The PeopleSoft system transparently handles the conversion between UCS-2 and UTF-8 when data is passed into the COBOL program from the database. If you are reading or writing files directly from a COBOL program, the input and output files are UTF-8 encoded when running PeopleSoft COBOL programs in Unicode.
Storage Requirements in a Unicode Environment
Moving to a COBOL Unicode environment means that character data can potentially require three times the storage space that is required in a single-character environment, given the variable length of a character that is encoded in UTF-8 from one to three bytes.
To allow for this, all internal data definitions for character-type data in COBOL programs must be expanded to allow for three times as many bytes. This expansion is critical because in a Unicode PeopleSoft database, column sizes are calculated based on a character length, not a byte length. So, a CHAR(10) column on a Unicode database allows the storage of 10 characters, regardless of how many bytes each character takes to store.
Given the three-bytes-per-character maximum requirement of UTF-8 (four-byte UTF-8 characters are not yet supported by the PeopleSoft system), the maximum byte size of this CHAR(10) column is 30 bytes. Therefore, a COBOL type of PIC X(30) may be required to store the contents of a CHAR(10) field on a Unicode database.
The PeopleSoft system provides a COBOL conversion utility to automatically expand the character-data fields in the working storage to accommodate the number of bytes in the UTF-8 encoding scheme.
Common Unicode Specific Error Messages
These error messages can occur when you are running a COBOL program against a Unicode database:
- Fetch failed: unsuccessful UCS-2 to UTF-8 conversion on column column_number.
- Bind of parameter failed: unsuccessful UTF-8 to UCS-2 conversion on column column_number.
- Attempting to use a non-Unicode API to access a Unicode database.
- Attempting to use a non-Unicode COBOL with a Unicode database.
- Attempting to use a Unicode API to access a non-Unicode database.
- Fetch failed: the converted Unicode length of length exceeds the allocated buffer length length for column column_number.
These messages appear in the COBOL output log file.
PeopleSoft Cobol Conversion Utility
As delivered, PeopleSoft COBOL programs are configured to run only on non-Unicode databases. To run the PeopleSoft-delivered COBOL on a Unicode database, it first must be converted by using the PeopleTools COBOL conversion utility.
When doing the PeopleSoft installation, this utility is typically called automatically, however, in an existing PeopleSoft environment, which has been created as Non-Unicode, you may need to run the COBOL conversion utility manually.
Adapt and apply patches to only one set of COBOL source code—non-Unicode source. It is much easier to write COBOL programs without having to remember to triple the size of your working storage as you go.
Once your adaptation or patch is complete and you are ready to compile the program, first run it through the COBOL conversion utility, then compile it. This approach has several benefits over customizing the converted code:
- You maintain a single source tree for all of your COBOL—the non-Unicode source. This way you don’t run the risk of accidentally adapting both the non-Unicode COBOL programs and the Unicode-converted COBOL programs and potentially losing the modifications to the converted programs the next time you run the converter.
- Although PeopleSoft developers test all delivered COBOL programs and patches in both Unicode and non-Unicode environments, only non-Unicode versions of the source are delivered.
Therefore, any time you apply a PeopleSoft COBOL patch to a Unicode system, the patched source code must be run through the COBOL converter. If you had already modified the post-converted source, the reconversion would obliterate your modifications.
If the COBOL conversion utility makes modifications to your code that are undesirable, instead of modifying the postconverted code, the PeopleSoft system provides a series of directives to the utility that can tell it how specific lines of code should (or should not be) converted. This enables you to limit your changes only to the nonconverted code and to make the conversion completely automated.
Running the PeopleSoft Cobol Conversion Utility
Use the following command syntax to run the COBOL conversion utility:
PS_HOME\bin\client\winx86\pscblucvrt.exe -s:Source_Directory -t:Destination_⇒ Directory [-r:TEMP_Directory]
Command Description
-s:Source_Directory Specify the source directory where the non-Unicode version of COBOL resides. For the directory, you must specify where the COBOL subdirectories reside
(\BASE, \WIN32, \Unix, and so on).
Example: -s:d:\PT849\SRC\CBL
-t:Destination_Directory Specify where you want to place the expanded version of COBOL. The utility puts the modified source file in the same COBOL subdirectory in which it was found.
Example: -t:d:\PT849\SRC\CBLUNICODE
-r or -rd:Temp_directory -r generates only the summary log file; -rd generates all of the log files.
The utility produces a new source file for each .CBL file that is found. These new files are placed in the PS_HOME\src\ directory. As delivered, the PeopleSoft batch utilities that compile your COBOL programs include logic to convert all programs and copybooks before compiling. This logic is triggered only when the Unicode version of PeopleTools is installed.
Compiling COBOL in Microsoft Windows
Use the PS_HOME\setup\cbl2uni.bat command to convert all of the COBOL programs and copybooks that are found in the PS_HOME\src\cbl directory. After the conversion, PS_HOME\src\cbl Unicode contains the expanded COBOL source codes.
Compiling COBOL in Unix/Linux
Use the PS_HOME/install/pscbl.mak command to trigger the conversion before any COBOL programs are compiled. This utility stores all converted programs in the PS_HOME/src/cblunicode directory.
Identifying Converted COBOL Programs
When the COBOL conversion utility runs, it places a comment at the beginning of each COBOL program that it converts. This comment line identifies converted programs in two ways:
- A person looking at the program can tell whether it has been converted.
- If you attempt to convert the COBOL source file again, this comment line prevents the conversion utility program from expanding the working storage of this COBOL source file again.
Understanding What Is Expanded
For the utility to recognize when it is appropriate to expand data, strict adherence to the PeopleSoft COBOL coding standards is required. The utility looks for certain code-style patterns to make these decisions. The conversion utility expands all PIC X[(N)] data fields to triple their original size, with the following exceptions:
- Exception 1: SQL buffer setup data.
- Exception 2: Redefined character fields.
- Exception 3: Fields that appear to be dates.
- Exception 4: Arrays comprising a single character.
The utility also converts copybooks on the fly: the first time that a copybook is referenced inside a code module, it is expanded immediately. The utility processes an entire set of COBOL modules in a single run. It maintains a record of what it has converted to avoid converting copybooks twice.
Note. The COBOL conversion utility ensures that edited lines do not go past the 72nd column. If the conversion would normally cause a line to exceed that limitation, the utility removes some of the blank spaces between the field name and the PIC X string so that the line fits in the allowed area.
PeopleSoft Cobol Conversion Utility Error Logs
The COBOL conversion utility produces a set of error and warning logs with messages that identify nonstandard code styles and inconsistencies. The utility also logs expansion actions that may require manual review. The utility produces the following logs:
Exception log – This log contains warnings that occurred because of ambiguous working storage definitions. You may need to modify code or add utility directives to resolve the issues logged.
Exception BIND/SELECT log – This log contains warnings and errors that occurred because of ambiguous BIND and SETUP definitions.
Exception date log – This log lists all group-level date fields that are detected by the utility.
Summary log – This log provides general statistics regarding the number of programs that are processed. When you specify the -4 flag, you see only the summary log. Set the -rd flag on the conversion utility command line if you want the utility to produce all of the detail logs: exception, BIND/SELECT, and exception date.
