Running COBOL in a z/OS Unicode Environment

This chapter discusses how to:

• Use the PeopleTools COBOL Unicode conversion utility for z/OS

• Identify converted COBOL programs.

• Understand converted data.

• Use error, exception and summary logging.

• Fine-tune converted COBOL programs.

Understanding Running COBOL in a z/OS Unicode Environment

This section discusses:

• Unicode encodings in PeopleSoft COBOL on z/OS.

• Data usage for Unicode storage.

• Input/output in the z/OS Unicode environment.

Unicode Encodings in PeopleSoft COBOL on z/OS

The character set that you use for PeopleSoft COBOL processing must match the character set for your database. If you create a Unicode database for a PeopleSoft system, you must also run COBOL in Unicode.

Note. In this chapter, the word character refers to a single character in any language, regardless of how many bytes are required to store the character.

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. Two main encodings that are important to understand are:

On Unix and Microsoft Windows servers, PeopleSoft uses UTF-8 encoding to support Unicode in COBOL. PeopleSoft uses UTF-8 since it is a superset of the US-ASCII character set, which is the native character set of these operating systems. PeopleSoft can support Unicode in these environments without requiring any special support from the COBOL compiler.

However, in the z/OS environment the native character set is EBCDIC. UTF-8 is not compatible with EBCDIC, and the COBOL runtime environment on z/OS does not recognize the data in UTF-8 correctly as it expects data encoded in EBCDIC. As a result, PeopleSoft supports Unicode COBOL on z/OS by relying on the IBM Enterprise COBOL compiler’s native Unicode support, which uses UCS-2.

See Also

The Unicode Standard

Data Usage for Unicode Storage

Moving to a z/OS COBOL Unicode environment means that character data in COBOL programs, including numbers, dates and time, is stored and processed in the UCS-2 encoding of Unicode. IBM Enterprise COBOL uses special usage NATIONAL to store Unicode data, instead of usage DISPLAY.

The usage NATIONAL should be used for all storage and literal declarations, except for limited special cases. PeopleSoft has worked with IBM to ensure that all the statements that process string data can work with data fields declared with usage NATIONAL.

The PeopleSoft system provides a COBOL Unicode conversion utility for z/OS that automatically converts the data field usage for Unicode storage. When the file server is installed with the “Unicode database” option selected, the conversion utility runs behind the server transfer process, and JCL files pre-configured for compiling Unicode COBOL programs are copied to the server. The Unicode support is provided out-of-the box, with no additional configuration required.

Unlike Unicode COBOL on Unix and Microsoft Windows, there is no need to explicitly expand storage size for Unicode processing in the z/OS Unicode environment. To store ten characters on DB2 UDB for OS/390 and z/OS, declare the database column as VARGRAPHIC(10). This column can be fetched into PIC N(10) field in Unicode COBOL programs running on z/OS.

See Also

Running the COBOL Unicode Conversion Utility for z/OS

Input/Output in the z/OS Unicode Environment

Even when character data in a PeopleSoft z/OS COBOL program is stored and processed internally in Unicode, there are some cases where data is needed in a native non-Unicode character set of the system. This is especially true for the purpose of input and output operations, and because external systems may not fully support Unicode.

Database Input/Output

PeopleSoft uses COBOL mainly for high-performance SQL batch jobs. DB2 UDB for OS/390 and z/OS supports communication with COBOL programs in Unicode using GRAPHIC and VARGRAPHIC data types.

All PeopleSoft-delivered COBOL programs are designed to communicate through the single central database access program PTPSQLRT. This program is enhanced to support communication with databases using Unicode.

Note. You may need to manually modify custom COBOL programs if they do not use PTPSQLRT or PTPDYSQL for database communication. The PeopleSoft-provided COBOL Unicode conversion utility for z/OS does not update SQL communication logic automatically.

Logging

PeopleSoft COBOL programs output logs using DISPLAY statements. The logs are mainly for displaying informational and debug messages. As these may need to be displayed on z/OS terminal screens which cannot display Unicode data, the PeopleSoft COBOL Unicode conversion utility inserts the DISPLAY-OF() COBOL intrinsic function to convert data to the system EBCDIC character set in the context of the DISPLAY statement.

Note. Because logs are generated in the system EBCDIC code page, not all the Unicode characters display on the log file. Characters not included in the system code page will be lost. Do not attempt to display international characters on the COBOL log. For reporting purpose, use Crystal Reports or the Structured Query Report (SQR) language instead of COBOL.

File Processing

A small number of PeopleTools COBOL programs use file input/output using READ and WRITE statements, for parameter input from JCL or writing logs. As these input/output can be better done using the system EBCDIC character set rather than Unicode, the PeopleTools COBOL programs performing file input/output are updated to convert to and from EBCDIC when accessing files. Because of the very limited use of file input/output, the COBOL Unicode conversion utility does not perform any special work for file input/output.

Note. Use Application Engine for processes that involve file input and output.

Miscellaneous Input/Output Operations

There are other cases where you should use the EBCDIC character set for string data, such as when accessing environment variables. PeopleSoft delivered programs are modified to convert internal Unicode representation of strings just before passing it to external data area, or convert from EBCDIC to internal Unicode representation, when required. However, the COBOL source conversion utility will not automatically update them. If you have custom COBOL programs that access external data, you may need to test them thoroughly after running the conversion utility, and insert DISPLAY-OF() or NATIONAL-OF() COBOL intrinsic functions where data conversions are required.

See Also

Running the COBOL Unicode Conversion Utility for z/OS

Understanding the COBOL Unicode Conversion Utility for z/OS

This discusses the PeopleTools COBOL Unicode conversion utility for z/OS and applying patches.

COBOL Unicode Conversion Utility for z/OS

As delivered by PeopleSoft, all COBOL programs are written to run on non-Unicode databases. To run the PeopleSoft-delivered COBOL on z/OS against a Unicode database, you must use the PeopleTools COBOL conversion utility for z/OS.

This utility is typically called automatically by the PeopleSoft server transfer process; however in certain circumstances, such as when you adapt COBOL code or apply a PeopleSoft-provided patch to a COBOL program, you may need to run the utility manually.

All internal data definitions for character-type data in COBOL programs, including data field groups and literals, must have usage NATIONAL instead of usage DISPLAY. The conversion utility changes the usage of the applicable data fields and also makes related changes in procedure division of the COBOL program source.

Applying Patches

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 use national data items as you go. Once your adaptation or patch is complete and you are ready to compile the program, first run it through the COBOL Unicode 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 tests 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, you must run the patched source code through the COBOL converter. If you had already modified the post-converted source, converting again would obliterate your modifications.

Under very limited conditions, you may still need to customize your COBOL source code after the conversion and maintain the Unicode version of the source. In this case, you may need to manually apply patch delivered by PeopleSoft to your source code.

Running the COBOL Unicode Conversion Utility for z/OS

This section discusses running the PeopleTools COBOL Unicode conversion utility for z/OS and discusses how to:

• Automatically run the COBOL Unicode conversion utility for z/OS.

• Manually run the COBOL Unicode conversion utility for z/OS.

Automatically Running the COBOL Unicode Conversion Utility for z/OS

By default, the PeopleTools COBOL Unicode conversion utility for z/OS runs in the background of the server transfer process if you select the Unicode database option during installation.

Manually Running the COBOL Unicode Conversion Utility for z/OS

You may want to run the utility manually in situations such as when converting PeopleSoft-delivered COBOL program patches or converting custom COBOL programs.

Use the following command syntax to run the COBOL Unicode conversion utility on the Microsoft Windows file server:

PS_HOME\bin\client\winx86\pscblucvrtz.exe -s:Source_Directory -t:Destination_⇒
Directory -r:Log_Directory [-psfs]

The following table provides a description of the commands:

The utility produces a new source file for each .CBL file that is found. These new files are placed under the specified target directory. If you specify the –psfs flag, the files are placed in \BASE and \MVS subdirectories under the target directory.

When you manually run the conversion utility you must transfer the generated .CBL files under the target directory to SRCLIB and COPYLIB data sets on the z/OS server, and compile the programs by submitting JCLs.

Note. The PeopleSoft COBOL conversion program for the Unicode environment on Unix and Microsoft Windows is named pscblucvrt. The COBOL conversion program for the z/OS environment is named pscblucvrtz. Do not use pscblucvrt for COBOL programs running on z/OS because the conversion logic used for z/OS COBOL programs is completely different from that used for Unix and Microsoft Windows.

Identifying Converted COBOL Programs

When the COBOL Unicode conversion utility for z/OS runs, it places a comment at the beginning of each COBOL program that it converts:

******* Converted for Unicode (national support)  (date converted)
********************* DO NOT MODIFY THIS FILE ********************
**** ALL SOURCE CODE CHANGES MUST BE DONE TO THE ANSI VERSION ****
******************** FOUND IN %PS_HOME%/SRC/CBL ******************

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 converting this program file again.

Note. Conversion utility comments for the z/OS Unicode environment include “(national support)” on the first line. The first line of comments generated by the COBOL conversion utility for Unix and Microsoft Windows environments read “Converted for Unicode”.

Understanding Converted Data

The PeopleTools COBOL Unicode conversion utility for z/OS reads COBOL sources under the source directory, analyzes their structures and statements, and applies a set of conversion rules to each statement.

Copybook Conversion

The utility converts copybooks on the fly: the first time that a copybook is referenced inside data division or procedure division of any program, it is processed 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.

The utility assumes that the COBOL programs are using PeopleSoft-standard COBOL program naming conventions, including that program sources are named “??P?????.cbl” and copybook sources are named “??C?????.cbl” The convention ? means any single character.

Note. The PeopleTools COBOL Unicode conversion utility for z/OS is designed to process an entire set of COBOL modules, including all programs and copybooks. The utility processes the COBOL COPY statement and checks for the existence of a copybook called from the program. If a copybook called from a program cannot be found in the source directory, the conversion process stops with an error, since the content of the copybook may affect the conversion result of the calling program.

Data Division Conversion Rules

All data field declarations with usage DISPLAY are converted to usage NATIONAL.

• A PIC X field is converted to a PIC N field.

• A string literal in the context of PIC N field is prefixed with N symbol.

• A PIC 9 field whose usage is DISPLAY is added USAGE NATIONAL clause to make its usage NATIONAL.

• A group that all of its members can be converted to usage NATIONAL is added GROUP USAGE NATIONAL clause to make the group NATIONAL item.

Example 1: PIC X Field Converted to PIC N and String Literal Prefixed with N Symbol

The following example shows the PIC X field converted to PIC N. In addition the prefix N is added to the VALUE clause.

02  RECNAME-TBLB            PIC X(9)    VALUE 'APPL_TBLB'

Is converted to:

02  RECNAME-TBLB            PIC N(9)    VALUE N'APPL_TBLB'

Example 2: Usage NATIONAL clause added to PIC 9 Field

The following example shows the Usage NATIONAL clause added to the PIC 9 field.

02  CURR-COUNT              PIC 9(4)

Is converted to:

02  CURR-COUNT              PIC 9(4) USAGE NATIONAL

Example 3: GROUP-USAGE NATIONAL Clause Added to Group W-LIT

The utility adds the GROUP-USAGE NATIONAL clause to the group W-LIT, because all the members of the group can be converted to the national data type. W-CALC-FIELDS is not added GROUP-USAGE NATIONAL because it includes item that cannot be converted to national data type. Packed decimal, binary, pointer items are not converted to national type, and groups including these data types are not added GROUP-USAGE NATIONAL.

01  W-LIT GROUP-USAGE NATIONAL .
02  PROGRAM-NAME            PIC N(8)    VALUE N'PTPDEC31'.
02  JOBID                   PIC N(10)   VALUE N'PTPDEC31'.
02  DESCR                   PIC N(16)   VALUE
N'TEST DEC31'.
01  W-CALC-FIELDS.
02  INIT-CHAR-DEF           PIC N(10).
02  COMP-REDEF-OF-CHAR REDEFINES INIT-CHAR-DEF
PIC S9(8) COMP.

Exceptions to Data Division Conversion Rules

There are a few exceptions to the data division rules to make the program compile and work correctly. For the utility to recognize these exceptional cases, strict adherence to the PeopleSoft COBOL coding standards is required. The utility looks for certain code-style patterns to make these decisions.

This section discusses the following areas where there are exceptions to data division rules:

• SQL buffer setup area.

• SQL buffer data area.

• File status field.

• FD entry in file section.

SQL Buffer Setup Area

For the interface to PTPSQLRT a COBOL program passes a SELECT list (SELECT-DATA) and a descriptor area (SELECT-SETUP). The program also passes similar data and setup areas for bind variables. The descriptors that are passed are always character-type data with embedded values that signal the actual data type and length of the data fields.

Because PTPSQLRT is designed to process the descriptors as alphanumeric character arrays (instead of national character arrays), the conversion utility does not convert the data type of the descriptor fields. However, it doubles the size of the descriptor field that is representing character-type data. Each data field in the descriptor area has associated field in SELECT-DATA or BIND-DATA field, and the byte size of the corresponding field in –DATA area doubles because of the change from PIC X to PIC N. Because of this implicit field size expansion, the corresponding field in –SETUP area should be doubled in size. Example: The following BIND-SETUP area is converted to match with BIND-DATA in byte size. Character fields are converted to double of the original size, to match with the size of the field in BIND-DATA area. Numeric and delimiter (‘Z’) items are not converted.

05  BIND-SETUP.
10  FILLER              PIC X(22)   VALUE ALL 'C'.
10  FILLER              PIC X(8)    VALUE ALL 'H'.
10  FILLER              PIC X(02)   VALUE ALL 'S'.
10  FILLER              PIC X(01)   VALUE 'Z'.

05  BIND-DATA.
10  EMPLID              PIC N(11).
10  ACAD-CAREER         PIC N(04).
10  STDNT-CAR-NBR-REAL  PIC S9(04)              COMP.
10  FILLER              PIC N(01)   VALUE N'Z'.

SQL Buffer Data Area

In the SQL buffer data area the conversion utility does not convert character data that is redefining numeric data. By convention in PeopleSoft application COBOL programs, this type of redefinition is used only for the purpose of using one data area for different number of variables. This type of character field can be in PIC X type that the conversion utility will not change the data type to PIC N.Example: PAGE-NO-FILLER, which is redefining binary field and in SQL buffer data area, is not converted to PIC N.02 BIND-DATA.

03  COMPANY             PIC N(10).
03  PAYGROUP            PIC N(10).
03  PAY-END-DT          PIC N(10).
03  OFF-CYCLE           PIC N.
03  PAGE-NO             PIC 9999                COMP.
03  PAGE-NO-FILLER REDEFINES PAGE-NO
                        PIC XX.
03  FILLER              PIC N       VALUE N'Z'.

File Status Field

The conversion utility does not convert a file status field (that includes “FILE-STAT” in name), because file status field (specified in FILE STATUS clause of FILE-CONTROL paragraph) must have the form of two-character alphanumeric or numeric item. It cannot be two-character national item.

Example: FILE-STAT-CTLFILE is not converted because it is file status field.

INPUT-OUTPUT SECTION.

FILE-CONTROL.

     SELECT CTLFILE  ASSIGN TO UT-S-CTLFILE
     FILE STATUS IS FILE-STAT-CTLFILE.


DATA DIVISION.




WORKING-STORAGE SECTION.

01  PROGRAM-IDENTITY       PIC N(8)    VALUE N'PTPCTL'.
01  FILE-STAT-CTLFILE      PIC XX      VALUE '00'.
01  MORE-INPUT             PIC N(1)    VALUE SPACES.

FD Entry in File Section

A line containing the RECORD CONTAINS clause in the FD data field will be commented out. If this line is not commented out, the program may cause an error at compile time because the record field is normally converted to a PIC N field and the record size will not match with the size specified in RECORD CONTAINS clause.

Note. This conversion eliminates compile errors. To read and write files either in Unicode or in EBCDIC, you may need to further modify the program manually to guarantee the correct file operation.

Example: Line containing “RECORD CONTAINS” clause is commented out in FD field declaration.

FD  TESTFILE
*   RECORD CONTAINS 80 CHARACTERS
     RECORDING MODE IS F
     LABEL RECORDS OMITTED.
01   TESTFILE-RECORD              PIC N(80).

Procedure Division Conversion Rules

In procedure division, the COBOL Unicode conversion utility for z/OS applies the following conversion rules to ensure that the correct operations on data fields convert to usage NATIONAL. These conversion rules are based on statement type.

Example 1: Prefix “N” Added to Literals in the Context of STRING Statements

IBM Enterprise COBOL compiler complains if both national and non-national items are contained in the context of some statements, including STRING, UNSTRING, and INSPECT. Since SQL-STMT of ICST-DYSQL is a national character field, the statement cannot be compiled unless we add “N” prefix to the literals.

STRING
     N'%ROUND(TLP_COST,2), ' DELIMITED BY SIZE
     N'%ROUND(LLP_COST,2), ' DELIMITED BY SIZE
     INTO SQL-STMT OF ICST-DYSQL
     WITH POINTER SQL-STMT-LEN OF ICST-DYSQL
     ON OVERFLOW PERFORM ZS000-STRING-ERROR
END-STRING

Example 2: Insert DISPLAY-OF() Intrinsic Function Around National Data Items

The conversion utility inserts DISPLAY-OF() intrinsic function around national data items in the context of DISPLAY statements, so that the data is converted to EBCDIC.

The DISPLAY-OF() function only accepts the PIC N parameter. To convert the PIC 9 USAGE NATIONAL item to non-Unicode using the DISPLAY-OF() function, you must add a reference modification (in the following example (1:)) to the PIC 9 USAGE NATIONAL ITEM, so that the item is first converted to a PIC N item.

DISPLAY 'RUNID= ' FUNCTION DISPLAY-OF(RUNID OF KBDPR)
DISPLAY 'OPRID= '  FUNCTION DISPLAY-OF(OPRIDX OF KBDPR)
DISPLAY 'RUNID OF SQLRT=' FUNCTION DISPLAY-OF(BATCH-RUN-ID OF SQLRT)
DISPLAY 'PROCESS-INSTANCE = ' FUNCTION
DISPLAY-OF(PROCESS-INSTANCE OF KBDPR(1:))

Example 3: Add FUNCTION DISPLAY-OF() if the First Parameter is National Data Field

If the first parameter of a CALL statement, which specifies the called subprogram, is a national data item, the conversion utility adds the DISPLAY-OF() function to the parameter, because the national data item cannot be used for the CALL parameter.

CALL FUNCTION DISPLAY-OF(COBOL-PROG OF W-WK) USING SQLRT
                                         LOGMS
                                         BMSET
                                         DYSQL
                                         SPARM
                                         SBIND
                                         SCACH
                                         ECURS

Example 4: Add FUNCTION DISPLAY-OF() to the Parameter of FUNCTION NUMVAL()

If the data field passed to function NUMVAL() is national data type, the conversion utility adds function DISPLAY-OF() to convert the data item to EBCDIC data, as NUMVAL() function cannot process national data.

COMPUTE W-COMPARE-GPA =
            FUNCTION NUMVAL ( FUNCTION DISPLAY-OF(W-CONDITION-DATA
))

Columns

The COBOL Unicode conversion utility ensures that edited lines do not go past the column 72. If the conversion would normally cause a line to exceed column 72, the utility inserts a line break before column 72 to make the long line into two separate lines.

The COBOL Unicode conversion utility for Microsoft Windows and Unix environments accepts various directives in the first six columns of COBOL code to that COBOL programs can use to tailor the conversion for specific code. The COBOL Unicode conversion utility for z/OS does not use any directive, therefore, the above rules applies to all the COBOL code.

Using Error, Exception and Summary Logging

This section discusses how to:

• Set logging parameters.

• View messages from the exception log.

• View messages from the summary log.

Understanding Error, Exception and Summary Logs

The COBOL Unicode conversion utility for z/OS produces a set of error and informational logs with messages that identify inconsistencies and problems. The utility also logs conversion exceptions that may require manual review.

Setting Logging Parameters

To set logging parameters, set the following parameters on the conversion utility command line:

When called from the server transfer process, the conversion utility produces the summary log in the staging directory, but does not produce an exception log.

Viewing Exception Log Messages

The following table summarizes all of the messages that can appear in the exception log file.

Viewing Summary Log Messages

The summary log lists the number of programs and copybooks read, modified, and not modified. The following is an example of the summary log.

If you are converting PeopleSoft- delivered application program sources, it is typical that not all the programs and copybooks are modified. The utility converts a copybook when it is called from data division or procedure division of any program source using COPY statement. There are several PeopleSoft delivered copybooks that are not called from data division or procedure division of any program. PeopleSoft also provides Unicode-specific COBOL source code that the utility does not modify and counts as a “not modified” program or copybook.

Fine-Tuning COBOL Programs for the z/OS Unicode Environment

This section discusses:

• Identifying Unicode data for z/OS, Unicode data for Microsoft Windows/Unix and non-Unicode data.

• Character fields and byte size.

• Character set conversion.

Understanding Fine-Tuning Converted COBOL Programs for the z/OS Unicode Environment

Although the COBOL Unicode conversion utility for z/OS makes most of the changes that are needed to run COBOL in a Unicode environment on z/OS, some manual fine-tuning may still be necessary.

Identifying Unicode Data for z/OS, Unicode Data for Microsoft Windows/Unix and Non-Unicode Data

A COBOL program may need to determine whether it’s dealing with non-Unicode data, Unicode data for Microsoft Windows/Unix in UTF-8 format, or Unicode data for the z/OS environment in UCS-2 format.

The conversion utility can get this information from the ENCODING-MODE-SW data field in the PTCSQLRT copy library. ANSI-mode is the same as non-Unicode. Unicode-mode represents Unicode processing on Microsoft Windows/Unix using UTF-8, and National-mode represents Unicode processing on z/OS using UCS-2.

03  ENCODING-MODE-SW    PIC X(1)    VALUE SPACE.
88  ANSI-MODE                       VALUE 'A'.
88  UNICODE-MODE                    VALUE 'U'.
88  NATIONAL-MODE                   VALUE 'N'.

The ENCODING-MODE-SW field value is set by default during installation. If when installing the file server you select the Unicode database option and build the PeopleSoft Process Scheduler environment on z/OS by running the PeopleSoft server transfer process, the value is automatically set to National-mode in the z/OS Unicode environment.

Note. It is very important to distinguish Unicode processing on Microsoft Windows/Unix from Unicode processing on z/OS. Unicode processing on Microsoft Windows/Unix requires expanding storage size by explicitly updating the field length. In the z/OS environment, Unicode values are stored using different data type (national), and you need not expand the storage size explicitly.

Understanding Character Fields and Byte Size

The COBOL Unicode conversion utility for z/OS changes the usage of alphanumeric character fields (PIC X) to usage NATIONAL (PIC N). This change works for the majority of the data fields, but may have side effects.

As in UCS-2 encoding, any character takes up two bytes. The size of one PIC N element is two bytes. The conversion from PIC X to PIC N implicitly doubles the field size. This can be a problem when a field must be a specific byte size. For example, in the following example, the PIC X field is used as filler to extract a portion of byte stream from numeric data field. This type of PIC X field should not be converted to PIC N.

01  W-WORK.

           03  NUM-OUT-AREA            PIC X(16).
           03  NUM-OUT-0               REDEFINES NUM-OUT-AREA
                                       PIC S9(31) COMP-3.
           03  NUM-OUT-1               REDEFINES NUM-OUT-AREA
                                       PIC S9(30)V9(1) COMP-3.
           03  NUM-OUT-2               REDEFINES NUM-OUT-AREA
                                       PIC S9(29)V9(2) COMP-3.
           03  NUM-OUT-3               REDEFINES NUM-OUT-AREA
                                       PIC S9(28)V9(3) COMP-3.

           03  FILLER                  REDEFINES NUM-OUT-AREA.
               05  FILLER              PIC X(12).
               05  NUM-OUT-INT         PIC S9(8) COMP.
           03  FILLER                  REDEFINES NUM-OUT-AREA.
               05  FILLER              PIC X(14).
05  NUM-OUT-SMALLINT    PIC S9(4) COMP.

The utility converts all alphanumeric character fields to PIC N, except for a very limited case where it can detect it should not convert this field data type. For the cases like that shown in the previous example, you must manually modify the code and test it.

Additional Considerations

Consider the following:

• Be very careful when deciding not to convert a PIC X field. COBOL does not allow moving data between PIC X and PIC N field without character set conversion between EBCDIC and Unicode, which adds extra complexity in your program and can cause performance overhead.

• You cannot use national and non-national data in some statements, such as STRING and UNSTRING.

• PIC N is two-byte field but content is not limited to Unicode strings. You can store binary, packed decimal or pointer values in the PIC N field (using redefinition) and can copy the value to another PIC N field. Therefore, it is not always necessary to use PIC X field to store non-Unicode values. Use the PeopleSoft-delivered COBOL Unicode conversion utility for z/OS to convert all fields to PIC N unless the field cannot be converted to PIC N (instead of trying to convert only the field that can contain international characters).

Understanding Character Set Conversion

The COBOL Unicode conversion utility for z/OS updates COBOL programs to use Unicode for all character data for internal processing, including numbers and date. However, there maybe cases where the Unicode data must be converted to non-Unicode character set, typically when communicating with external systems that do not fully support Unicode.

The following table lists IBM Enterprise COBOL statements and functions that convert between Unicode and non-Unicode character sets.

move PIC X field or alphanumeric string literal ⇒
to PIC N field