MF Natural Connector Guide

The MF Natural connector enables data consumers to communicate with mainframe applications developed with the Natural programming language that uses ADABAS (Adaptable Database System) as a back-end database.  

With the help of the OpenLegacy CLI and the MF Natural connector, you can create assets based on the metadata extracted from a Natural coded application. You can then upload the asset to the OpenLegacy Hub. Finally, you can generate a service based on your uploaded asset that exposes a working API to an ADABAS-backed Natural application. 

Runtime data flow

The MF Natural connector data flow consists of the following steps:

  1. First, the data consumer sends a request containing a JSON data query to the OpenLegacy MF Natural service. 
  2. After receiving the request, the OpenLegacy MF Natural service converts the JSON data query to an MF Natural file. 
  3. The service then sends the file to the mainframe host and port. 
  4. Finally, after a  response coded in Natural is received from the main frame, the OpenLegacy MF Natural service converts it to JSON and passes it to the data consumer.

Prerequisites

The MF Natural connector has no prerequisites. 

Guide topics

The MF Natural connector guide includes the following topics:

  • Create MF Natural modules and assets: a detailed step-by-step tutorial on creating MF Natural modules and assets.
  • Connector properties: a list of all the MF Natural connector properties and their explanations.

Create MF Natural module and assets

To create an MF Natural asset, you will perform the following steps:

  1. First, create an MF Natural module.
  2. Second, create a JSON-based MF Natural asset by parsing a local IDL source file.
  3. Third, test the connection to the remote MF Natural mediated data source. 
  4. Finally, test the created asset by sending a test query to the remote CORBA-mediated data source. 

Step 1. Before you start

Before starting, ensure you have a data source file containing an SYSTRANS formatted Natural application.

*S*** The first few lines of a Natural systrans data source sample -    *      

*S*** ---------------------------------------------------------------------*       

*S**DEFINE DATA         

*S***       

*S**PARAMETER           

*S***       

*S**01 ACCOUNT-DATA     

*S**  02 CRT-ACCOUNT-IN 

*S**    03 ACTI-CUSTOMER-ID                 (A16)           

*S**    03 ACTI-CUSTOMER-NAME               (A16)           

*S**    03 ACTI-TYPCD                       (A01)           

*S**    03 ACTI-SUB-TYPCD                   (A03)           

*S**    03 ACTI-CNTRY-CD                    (A02)           

*S**    03 ACTI-BNK-ID                      (A04)           

*S**    03 ACTI-BRNCH-ID                    (N06)           

*S**    03 ACTI-INITIAL-DEPOSIT             (P14.3)         

*S**    03 ACTI-CURRENCY                    (A03)           

*S***       

Step 2. Create a module

First, create the mf-natural module. 

> ol create module mf-natural-module --connector mf-natural
$ ol create module mf-natural-module --connector mf-natural

Step 3. Test the connection to the remote MF Natural server

Run the ol test connection command to verify that the connection properties are correct and hence that the  Natural application on the remote mainframe is accessible. 

  1. Navigate to the module folder:

    > mf-natural-module
    
    $ mf-natural-module
    
  2. From under the module directory, display the help menu of the ol test connection command to review the mf-natural connector connection properties.

    > ol test connection --help
    
    $ ol test connection --help
    

The ol test connection help menu displays the connector property list:

Options:
  --verbose                               Enables verbose mode
  --verbose-debug                         Enables debug mode
  --verbose-trace                         Enables trace mode
  --code-page TEXT                        Specify code page (default: utf-8)
  --msg-level TEXT                        (default: 0)
  --protocol-version TEXT                 (default: 03)
  --base-url TEXT                         Define the datasource hostname/ip (required)
  --port TEXT                             Define the datasource port (default: 12345)
  --uri-map TEXT                          Specify mainframe uri-map (required)
  --allow-self-signed TEXT                (default: true)
  --timeout TEXT                          (default: -1)
  --client-certificate TEXT               PEM formatted client certificate key
  --client-private-key TEXT               PEM formatted client private key
  --payload-length TEXT
  --spaces-are-null TEXT                  (default: true)
  --exclude-spaces-are-null TEXT          Exclude type from treat spaces as null[STRING, NUMBER, DATA, ENUM, BOOLEAN, CHARACTER] (default: [])
  --init-buffer-fill-value TEXT           Default value to populate buffers before inserting values from entities (default: 40)
  --treat-empty-string-as-low-value TEXT  Feel empty/null strings with low_value (00) instead of space (40) (default: false)
  --space-char TEXT                       Set value of space char (default: 40)
  --auth-type TEXT                        (default: NONE)
  --depending-on-mode TEXT                (default: false)
  --user TEXT                             Specify user name to connect to the datasource
  --password TEXT                         Specify password to connect to the datasource
  --pool.max-size TEXT                    (default: 10)
  --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
  1. Run ol test connection.
    > ol test connection --base-url http://192.86.33.88 --port 12346 --uri-map /CICS/OLBA/OLBRKRDV --code-page 037
    
    $ ol test connection --base-url http://192.86.33.88 --port 12346 --uri-map /CICS/OLBA/OLBRKRDV --code-page 037
    

Step 4. Add an asset to the MF Natural module

After verifying the connection parameters, you can create an MF Natural asset by executing the ol add command. The command parses the SYSTRANS Natural data source file and creates a JSON file containing the data source metadata.

[module-name]> ol add --source-path ../OLN06.systrans
[module-name]$ ol add --source-path ../OLN06.systrans

Step 5. Test the MF Natural 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/olno6/test_data/case1/:

    [module-name]> assets/olno6/test_data/case1/
    
    [module-name]$ assets/olno6/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 that the business operation requires. 

  3. In in.json, type the values of the input properties. 

  4. Now you are ready to run test-asset:

    [module-name]> ol test asset olno6
    
    [module-name]$ ol test asset olno6
    

The response from the ADABAS-backed Natural application is displayed.

Properties

--additional

key-value pairs of dynamic options

--additional [missing_value]

--source-path

The path to a local data-source Natural systrans formatted file. The path is used by the CLI ol add command to access the file and parse it to extract its metadata.

--source-path ../OLN06.systrans

--code-page

The Mainframe Natural code page

Default: 037

--code-page CP037

--msg-level

Default: 0

--msg-level 1

--protocol-version

Default: 03

--protocol-version 04

--base-url

The Mainframe hostname/IP

--base-url http://192.86.33.88

--port

The data source port

--port 12345

--uri-map

The Mainframe URI map

--uri-map --uri-map /CICS/OLBA/OLBRKRDV

--allow-self-signed

Allow self-signed certificates. Not recommended - preferable to use signed certificates or import the certificate in your JVM truststore. Default: false.

--allow-self-signed true

--timeout

The waiting period for the response message in milliseconds

--timeout 5000

--client-certificate

PEM formatted client certificate key

--client-certificate [missing_value]

--client-private-key

PEM formatted client's private key

--client-private-key [missing-value]

--payload-length

The payload length regardless of entity size. The buffer will be padded with 0x00 to be equal in length to the property value

--payload-length 5000

--spaces-are-null

Treat spaces (For example, 0x40 in an EBCDIC code page) as null instead of blanks (default: true)

--spaces-are-null false

--exclude-spaces-are-null

Exclude type from treat spaces as null[STRING, NUMBER, DATA, ENUM, BOOLEAN, CHARACTER] (default: [])

--init-buffer-fill-value

The buffer's default value before inserting values from the entities (default: 40)

--init-buffer-fill-value 60

--treat-empty-string-as-low-value

Fill an empty or null string with the low_value (00) instead of the space value (40) (default: false)

--treat-empty-string-as-low-value true

--space-char

The space-char value (default: 40)

--space-char [some_value]

--auth-type

The authentication type (http-header/soap header). Default: soap-header

--auth-type http-header

--depending-on-mode

[missing_value] (default: false)

--depending-on-mode true

--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

--pool.max-size

The maximal size of the thread pool

--pool.max-size 5