Preparing to Use the OS 2200 Open DTP Data Source Wizards

An Open Distributed Transaction Processing (Open DTP) application (or portion of the application) on the OS 2200 can be modernized with ClearPath ePortal Developer only if it has all of the following characteristics:

The client does not initiate two-phase commit (2PC) transactions. However, note that the Open DTP service on the OS 2200 system might use 2PC.
The client only directly calls one or more Open DTP services hosted on the OS 2200 system. However, note that the Open DTP Services might invoke other services hosted on other systems.
The application uses the simple request/response programming model, not the conversational programming model. That is, the client invokes the service using a TPCALL or TPACALL, and the service returns a single response to the client.

Before using ClearPath ePortal Developer to modernize your Open DTP application, do the following:

Review information for each of the OS 2200 Open DTP Data Source Wizards, in this section, to determine which wizard(s) apply to your situation; note that you can use more than one wizard in a single Data Source project.
Review the information in the section Translation Considerations.
Review the information in the section Metadata Fields.
Review the information in the section Open DTP Configuration Considerations.
After reviewing the sections above, go to Creating an OS 2200 Open DTP Data Source Project.

Preparing to Use the OS 2200 Open DTP View Data Source Wizard

If your Open DTP application uses one or more XATMI View buffers, you should use the OS 2200 Open DTP View Data Source Wizard to import the View definitions.

Locate the source file for each View definition. If you cannot locate a View source file, you can generate the View source from an installed binary View using the OS 2200 Open DTP VGET utility with the V option. Consult the Open Distributed Transaction Processing Administration Guide Volume 2: Building Applications.

You must capture every View definition associated with the Open DTP application that will be used in the new ePortal presentation method. The View Wizard creates a ClearPath ePortal server message (.eprec) and a DTP record (.dtpxml) for each selected View definition.

Preparing to Use the OS 2200 Open DTP X_OCTET Data Source Wizard

If your Open DTP application uses unstructured blobs of data rather than XATMI View buffers, you should use the OS 2200 Open DTP X_OCTET Data Source Wizard.

Using an X_OCTET buffer has the advantage that you do not need to define an XATMI View buffer. However, the user application must determine how to interpret the blob of data.

Since there is no View buffer definition, the X_OCTET wizard does not require a source file as input. The wizard creates a ClearPath ePortal server message (.eprec) and a DTP record (.dtpxml) to represent the X_OCTET record.

Preparing to Use the OS 2200 Open DTP COBOL Data Source Wizard

If you are writing a new Open DTP application in COBOL, or if you are willing to modify your existing Open DTP application written in COBOL, you may want to use the OS 2200 Open DTP COBOL Data Source Wizard instead of the OS 2200 Open DTP View Data Source Wizard.

Importing COBOL provides some advantages over importing Views:

Your COBOL 01 record can include structures that cannot be easily represented by a View. For example, your COBOL 01 record can include a group of fields with an OCCURS clause. Your ePortal presentation project can represent the multiple occurrences of the group using a data grid control on a Web page, for example.
Your COBOL 01 record can include level 88 items to represent possible enumerated values for a particular field. Your ePortal presentation project can represent such a field as a set of radio buttons or as a dropdown list on a Web page, for example.
At run time, the ePortal software uses X_OCTET buffers to send and receive the COBOL data. Therefore, you do not need to define, install, and maintain View definitions on your OS 2200 system.

You must capture every 01 data description associated with the COBOL program that will be used in the new ePortal presentation method. The COBOL 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 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 OS 2200 application.

Before you use the COBOL Wizard, you must understand the following restrictions and guidelines:

All Fields Must Have Display Usage
The ePortal COBOL Record Subtype
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

All Fields Must Have Display Usage

In order to use the COBOL wizard, each field in the 01 COBOL record must use one of the following USAGE types:

DISPLAY (or DISP)
DISP-I18N
DISPLAY-2 (DISP-2)

Note that the default usage for a field is DISPLAY if you do not explicitly specify it.

So, you could import the following record using the COBOL wizard:

01 EMPLOYEE-REC.
    05 ID          PIC 9(6).
    05 NAME        PIC X(30).
    05 SALARY      PIC 9(6)V99.

However, you cannot use the COBOL wizard to import the following record; in this case, you would need to model the record using a View and import the View using the View Wizard.

01 EMPLOYEE-REC.
    05 ID          PIC S9(9) COMP-5.
    05 NAME        PIC X(30).
    05 SALARY      COMP-1.

The ePortal COBOL Record Subtype

If you create an ePortal server message using the View wizard, at run time the ePortal software uses an XATMI record type of either “X_COMMON” or “X_C_TYPE”. The XATMI record subtype is set to the name of the View that you imported.

Conversely, if you create an ePortal server message using the COBOL wizard, at run time the ePortal software uses an XATMI record type of “X_OCTET”. Normally, the XATMI record subtype is unused or ignored for an X_OCTET buffer. However, ePortal has a special record subtype of “EPORTAL_COBOL” which is used to differentiate an ePortal server message which was created using the COBOL wizard from an ePortal server message which was created using the X_OCTET wizard.

This means that when you receive the service request record in your COBOL Open DTP server application, the REC-TYPE field in TPTYPE-REC is set to “X_OCTET” and the SUB-TYPE field in TPTYPE-REC is set to “EPORTAL_COBOL”.

Similarly, before you call TPRETURN to return your response, you must set the REC-TYPE field in TPTYPE-REC to “X_OCTET” and the SUB-TYPE field in TPTYPE-REC to “EPORTAL_COBOL”. Refer to this example code below:

* XATMI-SPECIFIC CODE TO RETURN ACOUNTS-OUT RECORD
      MOVE 0 TO APPL-CODE.
      MOVE 0 TO TP-RETURN-VAL.
     COMPUTE LEN = FUNCTION
             LENGTH (ACCOUNTS-OUT).
     MOVE "X_OCTET" TO REC-TYPE.
     MOVE "EPORTAL_COBOL" TO SUB-TYPE.
     CALL "TPRETURN"
         USING TPSVCRET-REC
               TPTYPE-REC
               ACCOUNTS-OUT.

Planning the Data Identification Strategy

At run time, the ePortal software needs to identify output data that is received from the OS 2200 COBOL 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 COBOL 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 7 characters of the data description would be used for all server messages received from the OS 2200 COBOL 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 COBOL 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 COBOL 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 OS 2200 COBOL 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 LEN field in TPTYPE-REC. For example:

* XATMI-SPECIFIC CODE TO RETURN ACOUNTS-OUT RECORD
     MOVE 0 TO APPL-CODE.
     MOVE 0 TO TP-RETURN-VAL.
     COMPUTE LEN = 
     FUNCTION LENGTH (ACCOUNTS-OUT).
     MOVE "X_OCTET" TO REC-TYPE.
     MOVE "EPORTAL_COBOL" TO SUB-TYPE.
     CALL "TPRETURN" 
         USING TPSVCRET-REC
               TPTYPE-REC
               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 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 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.