Preparing to Use the OS 2200 COBOL Data Source Wizard

You can use ePortal to modernize a COBOL TIP application that does not use DPS forms; however, note the following restriction:

All fields in the COBOL 01 records must explicitly or implicitly be defined with one of the following USAGE clause values:
- DISPLAY (or DISP)
- DISP-I18N
- DISPLAY-2 (or DISP-2)

You must capture every 01 data description associated with the TIP application. The COBOL wizard creates a ClearPath ePortal server message (.eprec) and a COBOL record (.cobxml) for each selected data description.

Before you use the OS 2200 COBOL Data Source Wizard, you must understand the following restrictions and guidelines:

Planning the Data Identification Strategy
Handling Records with the REDEFINES Clause
Capturing Copied Data Descriptions
Handling Applications without Static Data Descriptions
Controlling the Size of the Data Received from the OS 2200 Application
Guidelines for Numeric Edited Fields
Guidelines for Nested Array Fields
Translation Considerations
Metadata Fields

Planning the Data Identification Strategy

If a server message is to be received from the OS 2200, you can optionally select a field or several fields of the data description that contain unique text strings to create a unique identifier for the ClearPath ePortal server message. At run time, the ePortal software uses this unique identifier to select the correct ePortal server message when data is received from the existing TIP application.

There are two data identification strategies:

Defining a Unique identifier for the server message
Using orchestration to identify the server message that you expect to receive

Defining a Unique Identifier

To define a unique identifier for a server message, select a data identifier or a combination of several identifiers from the data that will be unique at runtime. To ensure that your identifier is unique, it is important to plan the data identification strategy before using the OS 2200 COBOL Data Source Wizard.

A data identifier must be identified by using a data description field that is an elementary item. The identifier field cannot contain or be subordinate to an item with an OCCURS clause, and must be a static set of characters.

Unisys recommends that the identifier field be in the same position in all COBOL data descriptions and be the same length.

For example, the first seven characters of the data description would be used for all server messages received from the OS 2200 TIP application.

If a data description does not have a field or fields that qualify as a data identifier field, such a field or fields can be added to the data description before using the COBOL wizard. For example, the following data description does not contain an identifier:

01 MY-RETURNED-ADDRESS.
      05 NAME      PIC X(30).
      05 ADDRESS   PIC X(30).

The following example shows the same data description after an identifier has been added:

01 MY-RETURNED-ADDRESS.
      05 FILLER    PIC X(7) VALUE "RETADDR".
      05 NAME      PIC X(30).
      05 ADDRESS   PIC X(30).                            .

Using Orchestration

If an output data description does not contain a unique identifier, and it is impractical to add one, then you can elect not to provide an identifier when you import the data description. However, if you do not provide a unique identifier, then you must use orchestration to identify which server message you expect ePortal to receive.

Refer to Using Orchestration to Identify an Output Server Message for more information.

Handling Records with the REDEFINES Clause

When a data description contains a REDEFINES clause, the COBOL wizard presents each data description for consideration. Only one redefined data description is valid for each ClearPath server message that is created. If the new interface uses multiple redefined data areas, multiple ClearPath server messages need to be created.

For example, in the following sample code, the BUFIN-REMAINDER input area is redefined and used to create a customer record and inquire about a customer. In addition, the input area is used to inquire on account information. As a result, there are three potential ClearPath ePortal server messages.

01 BUFIN.
   05 REQUEST-METHOD-NAME     PIC X(32).
      88 CREATE-CUSTOMER      VALUE "CREATE-CUSTOMER                 ".
      88 INQUIRE-CUSTOM       VALUE "INQUIRE-CUSTOMER                ".
      88 INQUIRE-ACCOUNT      VALUE "INQUIRE-ACCOUNT                 ".
   05 BUFIN-REMAINDER         PIC X(600).
   05 CUST-REC-IN REDEFINES BUFIN-REMAINDER.
      10 CUST-USERNAME-IN     PIC X(08).
      10 CUST-PIN-IN          PIC X(08).
      10 CUST-FIRSTNAME-IN    PIC X(15).
      10 CUST-LASTNAME-IN     PIC X(15).
      10 CUST-EMAIL-IN        PIC X(25).
      10 CUST-ADDRESS-IN      PIC X(50).
      10 CUST-NUMBER-IN       PIC X(06).
      10 FILLER               PIC X(473).
   05 INQ-CUST-REC-IN REDEFINES BUFIN-REMAINDER.
      10 INQ-CUST-USERNAME-IN PIC X(08).
      10 FILLER               PIC X(592).
   05 INQ-ACCT-REC-IN REDEFINES BUFIN-REMAINDER.
      10 INQ-ACCT-NUMBER-IN   PIC X(06).
      10 FILLER               PIC X(594).

If a presentation project needs to allow the creation of a customer record, select the redefine path that includes all information before the REDEFINES clause and all information in the first REDEFINES clause. As a result, a ClearPath ePortal server message, named BUFIN_CUST_REC_IN, is created and available to the orchestration process. All the fields of the COBOL data description are identified in the ClearPath ePortal server message.

If a presentation project needs to allow the inquiry of a customer record, select the redefine path that includes all information before the first REDEFINES clause and all information in the second REDEFINES clause. As a result, a ClearPath ePortal server message, named BUFIN_INQ_CUST_REC_IN, is created and available to the orchestration process. All the fields of the COBOL data description are identified in the server message.

Capturing Copied Data Descriptions

If the COBOL source file that you provide to the OS 2200 COBOL Data Source wizard contains the COPY statement, note that the COBOL wizard is not able to find data descriptions which are located in a COPY procedure file.

However, the COPY procedure file itself can be used as input to the COBOL wizard if:

The COPY procedure file is completely contained.
The REPLACING phrase is not specified in the COPY statement.

If the COBOL application contains a COPY statement that uses the REPLACING phrase, a new file must be created manually that contains the data descriptions found in the COPY procedure file. For instance, assume that the code is:

  WORKING-STORAGE SECTION.
     COPY MYRECORD
          REPLACING "XXX" BY "001".

And assume that the COPY procedure file contains:

01 MY-INPUT-RECORD.
   05 FILLER            PIC X(5) VALUE IS "INPUT".
   05 INPUT-FUNC-XXX    PIC XX VALUE SPACES.
   05 INPUT-ID          PIC 9.

The new file that can be used as input to the COBOL wizard should contain:

< 01 MY-INPUT-RECORD.
   05 FILLER           PIC X(5) VALUE IS "INPUT".
   05 INPUT-FUNC-001   PIC XX VALUE SPACES.
   05 INPUT-ID         PIC 9.

Handling Applications without Static Data Descriptions

If your application does not have a static data description and programmatically constructs the returned data in a common buffer area, do the following:

Create a file that contains all the possible data descriptions that need to be captured by the OS 2200 COBOL Data Source wizard.
Use that file as input to the wizard.

Controlling the Size of the Data Received from the OS 2200 Application

The ePortal runtime code requires that the TIP application sends the precise size of the data expected. If you are using UCOB, Unisys recommends that you use the function LENGTH to set the P-LENGTH field in MCB packet. For example:

* TIP-SPECIFIC CODE TO RETURN ACOUNTS-OUT RECORD      MOVE FUNCTION LENGTH (ACCOUNTS-OUT) TO P-LENGTH.      
      MOVE 0 TO P-MCB-STATUS.
      MOVE P-SENDD TO P-FUNC.
      MOVE 0 TO P-ID.   
      MOVE 1 TO P-START. 
      MOVE 4 TO P-AUX. 
      MOVE 0 TO P-FLAGS. 
      MOVE 1 TO P-BIT0. 
      CALL 'MCB$ENT' USING P-MCB-PACKET, P-MCB-STATUS,
           ACCOUNTS-OUT.

Guidelines for Numeric Edited Fields

The COBOL data description may contain one or more numeric edited fields. A numeric edited field is used to define the display format for a numeric value, including edit characters such as decimal points, commas, currency symbols, sign characters, and the like.

A numeric edited field is defined in COBOL as follows:

The PIC character string is restricted to certain combinations of the following symbols.
The PIC character string must contain at least one of the following symbols.

B	P	V
Z	0	9
/	,	.
*	+	-
CR	DB	currency symbol

Because a numeric edited field contains edit characters, ePortal represents a numeric edited field with the string data type in the generated server message. Since a numeric edited field is intended for display purposes, it is most appropriate for use in an output message returned from the OS 2200 server.

Guidelines for Nested Array Fields

A COBOL 01 record can contain one or more fields which are in nested arrays.

Consider the following examples:

01 REC1.
   05 REC1-GROUP OCCURS 5 TIMES.
      10 REC1-FIELD1 PIC XX OCCURS 6 TIMES.
      10 REC1-FIELD2 PIC 99.

01 REC2.
   05 REC2-GROUP1 OCCURS 5 TIMES.
      10 REC2-GROUP2 OCCURS 6 TIMES.
         15 REC2-FIELD1  PIC XX.
         15 REC2-FIELD2  PIC 99.
      10 REC2-FIELD3    PIC XXX.

In the above examples, the fields REC1-FIELD1, REC2-FIELD1, and REC2-FIELD2 are all fields in nested arrays.

If you import a COBOL 01 record that contains fields in nested arrays, and you generate an MVC presentation, a web forms presentation, or a web forms mobile (smartphone or tablet) presentation, the fields in nested arrays will not appear in the generated web pages. Any fields that are not in nested arrays will appear in the generated web pages. However, note that you can use fields in nested arrays with a web service presentation.