Natural Net Data Interface NATNETTO

This document provides information on the Natural Net Data Interface and the net data protocol definition.

It covers the following topics:

• Natural Net Data Driver Functional Description

• General Message Layout

• Layout of Header

• Format Buffer Layout

• Value Buffer Layout

• Attribute Buffer

See also:

• Installing Natural Net Data Interface on z/OS in the Installation for z/OS documentation.

• Installing Natural Net Data Interface on BS2000/OSD in the Installation for BS2000/OSD documentation.

Natural Net Data Driver Functional Description

The Natural Net Data Driver NATNETTO is a component that was introduced to support the EntireX CICS 3270 Bridge and similar client/server solutions in message oriented server environments, that is, TP monitors.

NATNETTO implements a protocol driver, which allows program-to-program communication with Natural (legacy) applications from client applications, using a net-data protocol. One typical scenario is a desktop client (for example, built with Natural for Windows or VBA) accessing a Natural application that runs under a TP monitor such as CICS, IMS TM or openUTM.

"Net data" means, that the protocol neither contains format data such as text constants nor any device-dependent control sequences. All data is communicated in printable format. This implies that eventually necessary marshaling and unmarshaling of non-alpha fields has to be done by the clients.

Basically, the protocol consists of two parts:

• A header or control block and a value buffer which contains the raw net data. This part is mandatory. The header contains control, environment and session information and maintains pointers to the other parts of the data buffer. The value buffer contains the actual net data which is to be exchanged between client and server.

• In addition, optional variable parts are available: format buffer and/or attribute buffer. The optional format buffer has an entry with descriptive data for each field in the value buffer. The attribute buffer consists of one byte with a preset value of 0 for each field in the value buffer. The client has to switch this value to 1 for each modified field, if the appropriate option is set, thus emulating the setting of MDT bits.

Header, value buffer and attribute buffer are parts of outbound and inbound messages; only the format buffer may occur in the outbound message only. The header maintains a transaction number which has to be mirrored by the client for flow-control purposes. Since legacy applications are mostly designed to be driven from block mode terminals, the protocol supports 3270 like functionality such as PF keys and cursor position.

General Message Layout

The following parts of the general message layout are mandatory:

• Header (the first two rows in the table below)

• Value buffer

The following parts are optional:

• Format buffer

• Attribute buffer

For detailed information on the layout parts, refer to Table 1.

Layout of Header

Table 1: Control Block - Fixed Part

*) If the cursor field number notation is set in NATCONFG, the cursor line will always be 000 and the cursor column will contain the absolute number of the field, where the cursor shall be placed (outbound) or was located at send time (inbound).

Note:
Not all header fields are currently used!

Table 2: Modes of Field Separation

Format A1

Table 3: Architecture of Sending Partner

Mask in Format A2

Table 4: Call Type

Format A2

Table 5: Aid Character Table

Format A2

Note:
CS - Close Session - allows clients to enforce an immediate close of the server session. Therefore, it is in fact not a real PF key, but a command code for the server.

Table 6: Message Type

Table 7: Option Flags for Natural Net-Data Communication

All flags are of format A1.

Format Buffer Layout

Base Part

Each format buffer entry is a variable length string consisting of four elements:

• Identifier

• Protection indicator

• Format indicator

• Printable field length

Table 8: Format Buffer Entry

Element	Value	Meaning
Identifier	F	Field
	S	Subfield
Protection	M	Modifiable field
	O	Output only field, protected field
Format	A	Alpha
	N	Numeric
Field length	L - LLL,L	Length specification according to Natural standard

Examples:

FMA20	Field, modifiable, format alpha 20
SMN12,4	Subfield, modifiable, format numeric 12.4
O	Output only field, protected field

Note:
The precision part of a numeric length is always separated by a comma (,), regardless of the current values of delimiter and decimal character profile parameters! For alpha type fields the precision part is omitted.

Subfields are used to determine fields which had been separated out of a base field using the Natural dynamic attribute facility. If a field is dynamically divided into various subfields, this is marked as follows:

The first subfield is marked with identifier F as usual, all other subfields are identified by S.

Extension 1

The following figure shows a part of a DSECT, which describes layout of the Natural internal screen attribute buffer. If the format buffer extension option 1 is set, for each field those attribute bytes (PATTR1 - PATTR4) will be brought into printable format and added to the appropriate fields format buffer entry. The extension is separated by a "/" (slash) from the base format entry.

Example:

An extended format buffer entry 18820300 means, the field is numeric and shall be presented highlighted italic in reversed video mode. The color of the field is pink!

Value Buffer Layout

Three modes of value buffer structure are possible:

• Fixed Format
  All parameters are simply concatenated without any delimitation. This means, that the single parameters have to be separated either according to the format description in the format buffer or by covering them with a C-structure, a data area or a DSECT.

• Delimited Format
  The parameters are separated by an configurable delimiter character.

• Length Preceded Format
  Each parameter is preceded by a length field of format N3. The length notation is explicit.

Attribute Buffer

The attribute buffer is optional. It consists of a one-byte entry for each parameter field, which represents the MDT flag. The MDT has to be set by the client for each modified field. The value of this flag is "0" or "1". A value of 1 means the MDT is set.

Example:

This example shows the screen image of a 3270 format in Figure 1 and the generated net-data stream for the same format in Figure 2. The name of the Natural map is NETM002.

                             TESTMAP NWI

  
  
  AL20.0 ABCDEFGHIJKLMNOPQRST 
  NL20.0 1234567890 
  NL10.4 0000001234.5678 
  AL20C AAAAABBBBBCCCCDDDDDZ 
  N20.0 999999999999999999 

  
  
  
  Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12- 
        Help                                -     +                       %%

Figure 1: NETM002 on a 3270 Device

  FSCBNAT010000000206000000038000000004710000120000100006
    F 04MD0000LNATvrsXSEN0000010000000465B3E0C25A1A1DE4000000000000I.,%01NETT     
  O NETM002 000000170   D  FSAP 1 ABCDEFGHIJKLMNOPQRST1234567890 
    0000001234.5678AAAAABBBBBCCCCDDDDDZ999999999999999999 
                            FMA20/08100024FOA20/
  38102024FMA15/08102024FOA20/38101624FOA20/38102024FOA79/70000035.000000
  

where vrs represents the relevant product version.

Figure 2: Net-Data Stream Generated from NETM002 Execution

Configuration Settings: Fixed format, format buffer + extended format buffer, attribute buffer option, cursor position represented as field number.