Version 4.2.6 for Mainframes	SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

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 the Natural Net Data Interface in the Installation 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 UTM.

"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

Examples:

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 approriate fields format buffer entry. The extension is separated by a "/" (slash) from the base format entry.

          
PATTR1 

          
DS 

          
X 

          
ATTRIBUTE BYTE 1

          
P1TMP 

          
EQU 

          
X'80' 

          
1000 0000 

          
TEMPORARY PROTECTED (ONLY PAGE)

          
P1EXTLNG 

          
EQU 

          
X'80' 

          
1000 0000 

          
EXTENDED LENGTH (ONLY SCREEN)

          
P1RPA 

          
EQU 

          
X'40' 

          
0100 0000 

          
FIELD CAN BE REPEATED

          
P1PROT 

          
EQU 

          
X'20' 

          
0010 0000 

          
FIELD IS PROTECTED

          
P1NUM 

          
EQU 

          
X'10' 

          
0001 0000 

          
FIELD IS NUMERIC

          
P1SKIP 

          
EQU 

          
P1PROT+P1NUM 
  (X'30')

          
FIELD WILL BE SKIPPED AUTOMATICALLY

          
P1HIGH 

          
EQU 

          
X'08' 

          
0000 1000 

          
FIELD IS HIGHLIGHTED

          
P1BLINK 

          
EQU 

          
X'04' 

          
0000 0100 

          
FIELD IS BLINKING

          
P1NOND 

          
EQU 

          
P1HIGH+P1BLINK 
  (X'0C')

          
FIELD IS NON-DISPLAY

          
P1NHC 

          
EQU 

          
X'02' 

          
0000 0010 

          
FIELD MAY NOT BE PRINTED

          
P1CURS 

          
EQU 

          
X'01' 

          
0000 0001 

          
SET CURSOR HERE (ONLY UNPROT)

          
SPACE 

          
PATTR2 

          
DS 

          
X 

          
ATTRIBUTE BYTE 2

          
P2ITAL 

          
EQU 

          
X'80' 

          
1000 0000 

          
ITALIC/CURSIVE

          
P2MAND 

          
EQU 

          
X'40' 

          
0100 0000 

          
INPUT MANDATORY

          
P2MFILL 

          
EQU 

          
X'20' 

          
0010 0000 

          
MANDATORY FILL

          
P2LC 

          
EQU 

          
X'10' 

          
0001 0000 

          
DO NOT TRANSLATE (LOWER CASE)

          
P2CS2 

          
EQU 

          
X'08' 

          
0000 1000 

          
SECOND CHARACTER SET

          
P2UL 

          
EQU 

          
X'04' 

          
0000 0100 

          
UNDERLINED

          
P2RVID 

          
EQU 

          
X'02' 

          
0000 0010 

          
REVERSED VIDEO

          
P2RL 

          
EQU  

          
X'01'

          
0000 0001

          
RIGHT-LEFT

          
SPACE 

          
PATTR3 

          
DS 

          
X 

          
COLOR ATTRIBUTE 

          
ATTRIBUTE BYTE 3

          
P3TP 

          
EQU 

          
X'80' 

          
1000 0000 

          
TERMINAL PROGRAM AVAILABLE

          
P3PFK 

          
EQU 

          
X'40' 

          
0100 0000 

          
*COM FIELD

          
P3NUM 

          
EQU 

          
X'20' 

          
0010 0000 

          
NUMERIC FIELDS

          
P3HELPR 

          
EQU 

          
X'10' 

          
0001 0000 

          
HELP ROUTINE AVAILABLE

          
P3FRAME 

          
EQU 

          
X'08' 

          
0000 1000 

          
FRAME ATTRIBUTE

          
P3NEUTR 

          
EQU 

          
X'07' 

          
0000 0111 

          
NEUTRAL

          
P3YELL 

          
EQU 

          
X'06' 

          
0000 0110 

          
YELLOW

          
P3TURQ 

          
EQU 

          
X'05' 

          
0000 0101 

          
TURQUOISE

          
P3GREEN 

          
EQU 

          
X'04' 

          
0000 0100 

          
GREEN

          
P3PINK 

          
EQU 

          
X'03' 

          
0000 0011 

          
PINK

          
P3RED 

          
EQU 

          
X'02' 

          
0000 0010 

          
RED

          
P3BLUE 

          
EQU 

          
X'01' 

          
0000 0001 

          
BLUE

          
* 

          
FBI (DB)

          
(FIELD PROCESSING INFORMATION)

          
SPACE 

          
PATTR4 

          
DS 

          
X 

          
INTERNAL PROCESSING ATTRIBUTES

          
P4TEXT 

          
EQU 

          
X'80' 

          
1000 0000 

          
FIELD IS TEXT CONSTANT

          
P4SAME 

          
EQU 

          
X'40' 

          
0100 0000 

          
SAME ATTRIBUTE AS BEFORE

          
P4NATTR 

          
EQU 

          
X'20' 

          
0010 0000 

          
FIELD NEW ATTRIBUTE

          
* 

          
PAGE BUFFER, DYNAMIC ATTRIBUTE

          
P4OVL 

          
EQU 

          
X'10' 

          
0001 0000 

          
FIELD BELONGS TO OVERLAY BUFFER

          
P4MDT 

          
EQU 

          
X'08' 

          
0000 1000 

          
FIELD HAS BEEN MODIFIED

          
P4MDTH 

          
EQU 

          
X'04' 

          
0000 0100 

          
UPDATE FROM HELP (PAGE BUFFER)

          
P4NFLD 

          
EQU 

          
X'04' 

          
0000 0100 

          
FIELD NEW ON SCREEN

          
* 

          
IF SET FOR OVL, NEW LINE

          
P4CONT 

          
EQU 

          
X'02' 

          
0000 0010 

          
FIELD IS CONT OF BEFORE

          
P4LAST 

          
EQU 

          
X'01' 

          
0000 0001 

          
LAST ATTRIBUTE IN BUFFER

          
**P4HELP 

          
EQU 

          
P4TEXT+P4MDT

          
HELP REQUEST FOR THIS FIELD

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
  

Figure 2: Net-Data Stream Generated from NETM002 Execution

Where NATvrs stands for version, release, system maintenance level of the current Natural version.

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

www.softwareag.com

Copyright © Software AG 1979-2009. All rights reserved.

SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT