An MCP COBOL application can be modernized with ClearPath ePortal Developer only if the application is:

You must capture every 01 data description associated with the COBOL program that will be used in the new ePortal presentation method. The MCP COBOL Data Source Wizard creates a ClearPath ePortal server message (.eprec) and a COBOL record (.cobxml) for each selected data description.

If a server message is to be received from the MCP, 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 MCP application.

Before you use the MCP COBOL Data Source Wizard, you should read and understand the following topics:

Before importing data descriptions, gather the following information, and then go to Creating an MCP COBOL Data Source Project.

Planning the Data Identification Strategy

At run time, the ePortal software needs to identify the output data that is received from the MCP application. There are two data identification strategies:

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 uniqueness, it is important to plan the data identification strategy before using the MCP COBOL Data Source Wizard. A data identifier must be identified by using a data description field that is an elementary DISPLAY, KANJI, or NATIONAL 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 7 characters of the data description would be used for all server messages received from the MCP 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 MCP COBOL Data Source 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 as described above, then you can elect not to provide an identifier when you import the data description. If you do not provide a unique identifier, you must use orchestration to identify the server message that 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 MCP COBOL Data Source 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(20).
       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.

If a presentation project needs to allow the inquiry of an account record, select the redefine path that includes all information before the first REDEFINES clause and all information in the third REDEFINES clause. As a result, a ClearPath ePortal server message, named BUFIN_INQ_ACCT_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 Included Data Descriptions

If the MCP application uses the INCLUDE statement to reference a data description, do one of the following:

Another source file called NEWSOURCE is created and contains all the data definitions. The new source file can then be used as input to the MCP COBOL Data Source Wizard.

Capturing Copied Data Descriptions

MCP applications that contain the COPY statement cannot be used as input to the MCP COBOL Data Source Wizard; however, the COPY book file can be used as input to the MCP COBOL Data Source Wizard if:

COPY <text> OF <library> ON <family>

If the MCP application contains a COPY statement that uses the FROM <sequence number> TO <sequence number> syntax or includes the REPLACING phrase, a new file must be created manually that contains the data descriptions found in the COPY book file. For instance, assume that the code is

WORKING-STORAGE SECTION.
       COPY "EPORTAL/COPYLIB/INPUT AREA"
       REPLACING "XXX" BY "001".

And assume that the COPY book 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 MCP COBOL Data Source 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:

Translation Considerations

At run time, the calling client application sends Unicode strings, and those strings are converted to MCP character strings. When data is returned to the calling client application, MCP character strings are converted to Unicode strings.

This conversion is possible because the ClearPath ePortal record that is created when the code is captured contains the character string information and the Message Editor allows the Data Type property of a particular field to be modified.

COBOL code that uses the following MCP character sets is supported. The desired MCP Coded Character Sets (CCS) is defined in the ClearPath ePortal Application Configuration dialog box. Refer to Viewing or Changing ePortal Application Configuration Properties.

For more information on character sets in the MCP environment, refer to the MultiLingual System Administration, Operations, and Programming Guide.

Handling Multiple Character Encodings in a Single ePortal Message

Multi-byte or double-byte COBOL record definitions can contain data items that use different character encodings. The USAGE clause associated with a data item provides a hint as to which character encoding should be used to process the item.

The USAGE clause of DISPLAY is used for data items that contain multi-byte values. The configured MCP CCS described above is used to process this type of item. In addition, record definitions can also contain a USAGE clause of KANJI or NATIONAL to indicate that the data item contains double-byte characters.

To handle data items that contain double-byte characters, ClearPath ePortal provides a mapping to a double-byte character encoding that is based on the configured MCP CCS. The following table shows that mapping.

Support for Dynamic Character Mapping

If you configure one of the multi-byte MCP CCS, you can optionally define a dynamic character map. Refer to Dynamic Character Mapping for more information.

Handling Multiple Outputs from the MCP Application in Response to a Single Input

An MCP COBOL data source project can support an MCP application that includes initiating a SEND statement after every FIND statement and finally issuing a final 0-byte SEND statement with the end-of-group indicator (EGI) flag. This coding approach is used when multiple calls to a database are needed to respond to a request for data.

To establish the multiple outputs capability initially

Refer to Procedure 4 in Creating an MCP COBOL Data Source Project for information about indicating that the MCP application does use the EGI flag.

To change the setting of multiple output capability after the first data descriptions are captured

Example of MCP Application Code

This COBOL85 example shows how multiple outputs might be sent as a result of one request using the CobolFirstBank sample program:

01 CUSTOMER-LIST-OUT. 
05 FILLER                            PIC X(20) VALUE IS "CUSTOMER-LIST        ". 
05 CUSTLIST-NUMBER-OUT               PIC X(06). 
05 CUSTLIST-FIRSTNAME-OUT            PIC X(15). 
05 CUSTLIST-LASTNAME-OUT             PIC X(15). 
05 CUSTLIST-EMAIL-OUT                PIC X(25). 
05 CUSTLIST-ADDRESS-OUT              PIC X(50).

INQ-CUSTOMER-LIST3.
     IF CUST-INDEX = -1 AND TEMP-INDEX = 0
        MOVE NO-CUSTOMER TO ERROR-TEXT
        PERFORM SEND-ERROR THRU SEND-ERROR-EXIT
        GO TO INQ-CUSTOMER-LIST-EXIT.
    IF CUST-INDEX = -1
       MOVE TEMP-INDEX TO CUST-INDEX
       MOVE 1 TO EGI-INDICATOR
    ELSE
       MOVE CUST-INDEX TO TEMP-NUM
       MOVE TEMP-INDEX TO CUST-INDEX
       MOVE TEMP-NUM TO TEMP-INDEX
       MOVE 0 TO EGI-INDICATOR.
    MOVE CUST-FIRSTNAME(CUST-INDEX)
 TO CUSTLIST-FIRSTNAME-OUT.
    MOVE CUST-LASTNAME(CUST-INDEX)
  TO CUSTLIST-LASTNAME-OUT.
    MOVE CUST-EMAIL(CUST-INDEX)
     TO CUSTLIST-EMAIL-OUT.
    MOVE CUST-ADDRESS(CUST-INDEX)
   TO CUSTLIST-ADDRESS-OUT.
    MOVE CUST-NUMBER(CUST-INDEX)
    TO CUSTLIST-NUMBER-OUT.
    COMPUTE COMS-OUT-TEXT-LENGTH =
            FUNCTION FORMATTED-SIZE (CUSTOMER-LIST-OUT).
    IF EGI-INDICATOR = 0
       MOVE TEMP-INDEX TO CUST-INDEX
       SEND COMS-OUT FROM CUSTOMER-LIST-OUT WITH EMI
       GO TO INQ-CUSTOMER-LIST2
   ELSE
       SEND COMS-OUT FROM CUSTOMER-LIST-OUT WITH EGI. 
INQ-CUSTOMER-LIST3-EXIT.

Controlling the Size of the Data Received from the MCP Application

Since the ePortal runtime code requires that the MCP COBOL application send the precise size of the data, Unisys recommends that the function FORMATTED-SIZE be used in the MCP COBOL code. For instance, the following might be coded:

COMPUTE TEMP-LENGTH=FUNCTION FORMATED-SIZE(RESOURCE-MONITOR)
 MOVE TEMP-LENGTH TO TEXTLENGTH OF COMS-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:

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 MCP system.

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 page. Any fields that are not in nested arrays will appear in the generated web page. However, note that you can use fields in nested arrays with a web service presentation.