Home
Guides
Sign in

Micro Focus Connector Guide

Suggest Edits

The Micro Focus connector is instrumental in exposing APIs to Micro Focus applications deployed on remote data source servers. 

Design time activity flow

With the help of the OpenLegacy CLI and the Micro Focus connector, you can create Micro Focus assets based on the metadata extracted from a Micro Focus COBOL source file. You can then upload the asset to the OpenLegacy Hub. Finally, you can generate a service that provides a working API to the remote Micro Focus applications based on your uploaded asset. 

See below for step-by-step instructions on creating Micro Focus assets and modules.

Runtime data flow

The Micro Focus connector data flow consists of the following steps:

  1. First, the data consumer sends a RESTful POST HTTP request to the OpenLegacy Micro Focus service. The request is specified in JSON. 
  2. After receiving the request, the OpenLegacy Micro Focus service converts the JSON data query to binary code.  The service then copies the binary code to a new POST-type HTTP request sent to the URL address of the OpenLegacy adapter installed on the remote Micro Focus data source. The request header includes the name of the application to be invoked by the adapter.
  3. Upon receiving the request, the OpenLegacy adapter passes the binary code to the designated Micro Focus application and returns the results in binary code to the service. 
  4. The service converts the binary code to JSON and returns the response to the data consumer. 

Prerequisites

The OpenLegacy Micro Focus adapter has to be installed on the remote Micro Focus server. See installation instructions.

Guide topics

The Micro Focus connector guide includes the following topics:

  • Create Micro Focus modules and assets: a detailed step-by-step tutorial on creating a Micro Focus module and assets.
  • Connector properties: a list of all the connector properties and their explanations.
  • The OpenLegacy Micro Focus adapter installation guide

Create Micro Focus module and assets

To create a Micro Focus asset, perform the following steps:

  1. First, create a Micro Focus module to contain Micro Focus assets.
  2. Second, create a JSON-based Micro Focus asset by parsing a local Microfocus Visual Cobol source file.
  3. Third, test the connection to the remote Micro Focus server. 
  4. Finally, test the created asset by sending a test query to the remote Micro Focus data source.

Step 1. Before you start

Before creating the Micro Focus module, ensure you have a Micro Focus Visual COBOL data source file and optionally one or more copybook files that the visual COBOL file refers to. In this guide, we use ITEMDET.cbl

IDENTIFICATION DIVISION.
       PROGRAM-ID. ITEMDET.
       DATA DIVISION.
       FILE SECTION.
       WORKING-STORAGE SECTION.
       LINKAGE SECTION.
       01 BUFFER.
           03 ITEM-NUM        PIC 9(8).
           03 ITEM-RECORD.
             05 ITEM-NAME     PIC X(16).
             05 DESCRIPTION   PIC X(30).
             05 WEIGHT        PIC 9(4).
           03 SHIPPING.
             05 SHIPPING-METHOD        PIC X(10).
             05 DAYS          PIC S9(4) COMP.
       PROCEDURE DIVISION USING BUFFER.
       MAIN-PROCEDURE.
            DISPLAY 'ITEM NUMBER: ' ITEM-NUM.
            MOVE 'AIR MAIL  ' TO SHIPPING-METHOD.
            MOVE 2 TO DAYS.
            EVALUATE ITEM-NUM
              WHEN  1000
                 MOVE 'Kid Guitar     ' TO ITEM-NAME
                 MOVE 'Kids Guitar - Musical Toys   ' TO DESCRIPTION
                 MOVE 200 TO WEIGHT
              WHEN 1001
                   MOVE 'Ball Pool      ' TO ITEM-NAME
                   MOVE 'Ball Pool - Novelty Toys   ' TO DESCRIPTION
                   MOVE 100 TO WEIGHT
              WHEN 1002
                   MOVE 'Water Ball     ' TO ITEM-NAME
                   MOVE 'Water Ball - Balls         ' TO DESCRIPTION
                   MOVE 1000 TO WEIGHT
               WHEN 1003
                   MOVE 'Frisbee        ' TO ITEM-NAME
                   MOVE  'Dog Frisbee - Pet Toys     ' TO DESCRIPTION
                   MOVE 5000 TO WEIGHT
              WHEN 1004
                   MOVE 'Pig Bank       ' TO ITEM-NAME
                   MOVE 'Pig Saving Bank - Ceramics ' TO DESCRIPTION
                   MOVE 5000 TO WEIGHT
              WHEN OTHER
                 MOVE 0 TO WEIGHT
                 MOVE 'ERROR          ' TO ITEM-NAME
                 MOVE 'OBJECT NOT FOUND          ' TO DESCRIPTION
            END-EVALUATE.
            DISPLAY 'BUFFER:  ' BUFFER.
           
       END PROGRAM.

Step 2. Create a Micro Focus module

First, create the Micro Focus module: 

> ol create module --connector microfocus-cobol module-micro-focus

$ ol create module --connector micro-focus module-micro-focus

Step 3. View the properties of the Micro Focus connector

Review the connector properties. For more information on the Micro Focus
connection properties, see Properties below.

  1. Navigate to the module folder:

    > cd module-micro-focus

    $ cd module-micro-focus

  2. From under the module directory, display the help menu of the ol add command:

    [module-name]> ol add --help

    [module-name]$ ol add --help

The ol add help menu displays the connector property list.

  --verbose                              Enables verbose mode
  --verbose-debug                        Enables debug mode
  --verbose-trace                        Enables trace mode
  --additional VALUE                     Additional properties
  --program-path TEXT                    Provide the cobol program path. Required when parsing multiple copybooks without cobol file
  --asset-name TEXT                      Provide asset name when parsing multiple copybooks without cobol file
  -i, --input TEXT                       Provide input copybook file path Or multiple input copybooks file paths Or input copybooks directory
  -o, --output TEXT                      Provide output copybook file path Or multiple output copybooks file paths Or output copybooks directory
  --source-path TEXT                     Provide local source or directory to parse cobol files
  --entity                               Indicate parse as entity
  --strict                               strictly parse a resource
  --input-super-class TEXT               Provide input entity super class
  --output-super-class TEXT              Provide output entity super class
  --code-page TEXT                       Specify code page (default: cp037)
  --base-url TEXT                        Define the base url (required)
  --port TEXT                            Define the port (default: 12345)
  --uri-map TEXT                         Specify uri-map (required)
  --allow-self-signed TEXT               (default: true)
  --timeout TEXT                         (default: -1)
  --client-certificate TEXT              PEM formatted client certificate key (default: true)
  --client-private-key TEXT              PEM formatted client's private key (default: true)
  --client-certificate-file TEXT
  --client-private-key-file TEXT
  --payload-length TEXT
  --payload-padding-char TEXT            (default: 40)
  --user TEXT                            Specify user name
  --password TEXT                        Specify password
  --oauth2.token-host TEXT
  --oauth2.token-endpoint TEXT
  --oauth2.client-id TEXT
  --oauth2.client-secret TEXT
  --oauth2.body-client-credentials TEXT  (default: false)
  --oauth2.grant-type TEXT               [CLIENT_CREDENTIALS, AUTHORIZATION_CODE, RESOURCE_OWNER_PASSWORD_CREDENTIALS, IMPLICIT] (default:
                                         CLIENT_CREDENTIALS)
  --oauth2.scope TEXT
  --oauth2.additional-headers VALUE
  --oauth2.additional-body VALUE
  --bidi.response-enabled TEXT           enable bidi logic on response field (default: false)
  --bidi.request-enabled TEXT            enable bidi logic on request field (default: false)
  --profile TEXT                         Configuration profile
  -h, --help                             Show this message and exit

Step 4. Test the connection to the remote Micro Focus server

Run the ol test connection command to verify that the connection properties are correct and hence the OpenLegacy Micro Focus adapter on the remote data source is accessible. 

[module-name]> ol test connection --base-url http://microfocus-dev.openlegacy.com --uri-map /api/v1/endpoint --port 8080 --code-page CP037

[module-name]$ ol test connection --base-url http://microfocus-dev.openlegacy.com --uri-map /api/v1/endpoint --port 8080 --code-page CP037

Step 5. Add an asset to the Micro Focus module

After you verified the connection parameters, you can create a Micro Focus asset. The ol add command parses the COBOL program source file and optionally other copybook files to which the program may refer to. The command then generates an asset folder that contains the asset configuration file ([asset-name].json) and the asset testing resources. 

> ol add --source-path ./ITEMDET.cbl

$ ol add --source-path ./ITEMDET.cbl

Step 6. Test the Micro Focus asset

Test the asset you added to verify that you can request and receive actual business data from the data source.

  1.  From your module folder root go to assets/itemdet/test_data/case1/:

    > cd assets/itemdet/test_data/case1/

    $ cd assets/itemdet/test_data/case1/

  2. To view and edit the test input data, open in.json:

    case-1> notepad in.json

    case-1$ notepad in.json

in.json contains the information sent to the remote business operation. It consists of the input keys and values that the business operation requires. 

{
  "buffer" : {
    "itemNum" : "",
    "itemRecord" : {
      "itemName" : "",
      "description" : "",
      "weight" : 0
    },
    "shipping" : {
      "shippingMethod" : "",
      "days" : 0
    }
  }
}

  1. In in.json, type the values of the input properties. In the example above, for the itemNum essential type 1000.

  2. Now you are ready to run ol test asset:

    > ol test asset itemdet

    $ ol test asset itemdet

The response from the remote Micro Focus server is displayed.

Properties

--source-path

The path to a local data-source COBOL file. The path is used by the CLI ol add command to access the file and parse it to extract its metadata. The property is not required if the input, the output and the program-path properties are populated.

--source-path ../FULLDETAIL.cbl

--input, -i

Input copybook file paths and directories separated by space

--input ../PhoneBookRecord.in.cpy

--output, -o

Output copybook file paths and directories separated by space

--output ../PhoneBookRecord.out.cpy

--program-path

Path to the business operation on the remote data-source machine. The path is used:

  • in design-time by the CLI ol test-asset command to access the business operation on the remote machine.
  • in run-time by the production application to communicate with the business operation on the remote machine.
--program-path /QSYS.LIB/RMR2L1.LIB/FULLDETAIL.PGM

--entity

Generate an entity-type asset. The ol add command flagged by the --entity option adds an entity-type asset to a module. The resulting JSON provides a simple representation of business field data. Entities generated from copybook or COBOL asset source files provide the ability to support copybook superclasses. See input-super-class and output-super-class below.

ol add --source-path ../header.cpy --entity

--asset-name

The asset name defaults to the program path. Pass a value to --asset-name only when it is different that the program path.

--asset-name credit-account

--input-super-class

Specifies the path to an entity-type asset that will serve as an additional data source to the input copybook files. The data defined in the entity type asset represent business fields that are common to all input-related copybook files. A prior execution of an --asset flagged ol add command generates the specified entity type (see entity above).

--input-super-class header

--output-super-class

Specifies the path to an entity-type asset that will serve as an additional data source to the output copybook files. The data defined in the entity type asset represent business fields that are common to all output-related copybook files. A prior execution of an --asset flagged ol add command generates the specified entity type (see the entity property above).

--output-super-class header

--base-url

The base url of the Micro Soft server where the OpenLegacy Micro Focus adapter is deployed

--base-url http://microfocus-dev.openlegacy.com

--port (required)

The Micro Focus adapter port on the remote Micro Focus server

--port 8080

--uri-map

The OpenLegacy Micro Focus adapter endpoint on the Micro Focus server.

--uri-map /api/v1/endpoint

--code-page

The remote data source code page

--code-page CP037

--user

The remote data source user

--user demo

--password

The remote data source password

--password 12345

--profile

The selected connection property set to be added to the ol add or ol test connection commands (see: Connection Profiles).

--profile dev

Install the OpenLegacy Adapter on the Micro Focus server

The OpenLegacy Micro Focus adapter is a lightweight HTTP server that lives on the remote Micro Focus data source. The server has only one endpoint to which all service requests are directed. The adapter receives a request from the service, reads the name of the request target application from the request header, and passes the request payload to the target Micro Focus application. The adapter then returns the target application response to the requesting service. 

To install the adapter, follow the  steps below:

  1. Paste microfocus-http-adapter.jar into a folder in the remote Micro Focus server. 
  2. Create a config.json file in the same folder and set the following configuration properties:
    • root-path - an absolute path to the directory in the file system where the microfocus applications reside.
    • port - the port of the Micro Focus adapter application.
{
    "port": 8080,
    "root-path": "'C:\\openlegacy\cobol_dlls\'",
    "logging": {
        "level": {
            "io.ol.microfocus": "trace"
        }
    }
}

Updated 4 months ago