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:
- First, the data consumer sends a request containing a JSON data query to the OpenLegacy MF Natural service.
- After receiving the request, the OpenLegacy MF Natural service converts the JSON data query to an MF Natural file.
- The service then sends the file to the mainframe host and port.
- 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:
- First, create an MF Natural module.
- Second, create a JSON-based MF Natural asset by parsing a local IDL source file.
- Third, test the connection to the remote MF Natural mediated data source.
- 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.
-
Navigate to the module folder:
> mf-natural-module
$ mf-natural-module
-
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
- 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.
-
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/
-
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.
-
In in.json, type the values of the input properties.
-
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
Updated 4 months ago