Cics Runtime Integration with Non-3270s Terminal

Interface

Non-3270s terminal should submit request and get response through Tuxedo ATMI tpcall(). The service name of tpcall() should follow the convention described in the following section; in addition, data buffer type exchanged with server ARTWTRN/ARTWTR1 could only be Tuxedo FML32. The detailed FML32 fields and each data structure will be described in the following section.

Service Name Convention

In order to distinguish the service invoked by non-3270s clients from the service invoked by TN3270 terminal, ARTWTRN/ARTWTR1 sever advertises each CICS transaction as a Tuxedo service with the name prefix WEB_. When client submits the request to ARTWTRN/ARTWTR1, the service name of tpcall must follow the convention.

Fml32 Buffer Definition

The interface between non-3270s client and ARTWTRN/ARTWTR1 could only be Tuxedo FML32 buffer. All the application data and some terminal control information will be encapsulated in the FML32 buffer.

Table 5‑2 lists all FML32 FIELDs, which will be published in $KIXDIR/include/msgflds32.

Table 5‑2FML 32 Buffer Definition for CICS Runtime Integration with Non-3270s Terminal

Field Name	Type	Tuxedo Buffer Type	Length	Comments
CX_WEB_TRANSID	Outbound	CARRAY	4	Transaction name to be invoked. This field will be added/changed by ARTWTRN/1. Client can get the transaction name from this field and use it for the next tpcall.
CX_WEB_MAPSET_NAME	Outbound	CARRAY	7	The name of the current MAPSET, which will be displayed in Client’s UI. This field will be added/changed by ARTWTRN/1. Client can get the MAPSET name from this field.
CX_WEB_MAP_NAME	Outbound	CARRAY	7	The name of the current MAP, which will be displayed in Client’s UI. This field will be added/changed by ARTWTRN/1. Client can get the MAP name from this field.
CX_WEB_APPDATA	Outbound / Inbound	CARRAY	Depends on Copybook	The application data requiring to be displayed in the Client’s UI or processed by transaction. This field will be added/changed/read by both ARTWTRN/1 and Client. When Client receives the FML buffer, it needs to get the application data from this field and split into each map filed according to Copybook. Client could also re-organize latest application data according to Copybook and send it to ARTWTRN/1. When receiving the FML buffer, ARTWTRN/1 will get the application data from this field and pass the data to transaction for processing.
CX_WEB_CTRL_CHAR	Outbound	CARRAY	12	The terminal control characters of the command “CICS SEND”, “CICS SEND MAP”, “CICS SEND TEXT”, and “CICS SEND CONTROL”. At times, CICS APIs above will be invoked with some control options, such as FREEKB, ALARM, ERASE, ERASEUP, CURSOR, etc; therefore, these control options should be inserted to this FML field. The field will be added/changed by ARTWTRN/1. Client can get the control options from this field and handle them accordingly.
CX_WEB_AID	Inbound	CARRAY	3	The attention ID and cursor position when doing “CICS RECEIVE” and “CICS RECEIVE MAP”. When 3270 terminal sends the application data to the CICS runtime, it will always contain the AID and current cursor position of the screen; therefore, this filed will be added/changed by Client. ARTWTRN/1 will get data from this field and pass the data to transaction for processing.
CX_SESSIONID	Outbound / Inbound	STRING	16	The session ID of client. If it’s not filled in client side, ARTWTRN/1 will generate one randomly.
CX_TERMID	Outbound / Inbound	CARRAY	4	The term ID of client. If it’s not filled in client side, ARTWTRN/1 will generate one by randomly.
CX_USERID	Outbound / Inbound	CARRAY	8	The user ID of client. If it’s not filled in client side, ARTWTRN/1 will fill it with “WEBGUEST”.
Note: Outbound means the field is only included in the FML buffer from ARTWTRN/1 to Client; Inbound means the field is only included in the FML buffer from Client to ARTWTRN/1.

CX_WEB_APPDATA

Mainframe CICS provides a utility to generate the Copybook from the Mapset file. The Copybook is used to define the structure of the application data when transaction invokes CICS SEND/RECEIVE MAP.

At ART CICS runtime, we also provide a corresponding utility tcxmapgen, which generates the Copybook from Mapset file; regarding that the structure of Copybook generated by tcxmapgen is almost the same as the one generated in Mainframe CICS, application data exchanged between the Client and ARTWTRN/1 must follow the definition in the Copybook of each Mapset.

For CICS SEND/RECEIVE and CICS SEND TEXT, ARTWTRN/1 and Client just need to insert the plain textual characters into the field CX_WEB_APPDATA.

The head file might not match the copybook generated from BMS file by ART CICS offline utility tcxmapgen at runtime due to data structure alignment on open system. It might need customers to adjust copybook by padding appropriate FILLER.

CX_WEB_CTRL_CHAR

In Mainframe CICS, an outbound data stream is a data stream sent from the application program to the terminal with the following format:

| Command | Write Control Character | Indicate Cursor | Orders | Data | Orders | Data | ...

CMD defines the function to be performed by the terminal. ARTWTRN/1 will support W and EW. It’s a one byte.

WCC instructs how to perform the CMD function. It’s a one byte with the following format:

| 0 | 1 | 2/3 | 4 | 5 | 6 | 7 |

| * | Reset | Printout | Start | Sound | Keyboard | Reset |

| | | Format | Print | Alarm | Restore | MDT |

If SEND MAP/TEXT command sets cursor option, IC should be inserted into the header of 3270 data stream with the following format in the case of SEND command without cursor option. If this command sets option ERASE, the cursor will set to the upper left corner of the screen.

| SBA | ROW | COL | IC |

Besides CMD, WCC, and IC described above, other control characters could be also contained in the header of 3270 data stream, such as EUA.

At ART CICS runtime, we define a FML field CX_WEB_CTRL_CHAR, a CARRAY with 12 bytes, to store these control characters; however, in this release, we plan to support CMD, WCC, and IC, all of which are mostly used. The data sequence of this field is as below:

| CMD | WCC | SBA | ROW | COL | IC | ...

Only the first 6 characters will be used in this field, the rest 6 characters will be reserved with X’00’, and the code of these characters will be set as EBCDIC, not ASCII. SBA, ROW, COL, and IC will be set with X’00’ in the buffer if there is no need to set cursor; If IC is not set via the option cursor of CICS commands, but set in MAPSET/MAP file, no IC will be set in this field and customers need to handle IC themselves.

CX_WEB_AID

In Mainframe CICS, an inbound data stream is sent from the terminal to the application program and contains an attention identifier (AID) followed by cursor or by data directly. The AID describes the action that caused the transmission of the inbound data stream with the following format:

| AID | ROW | COL |

At ART CICS runtime, we defined a FML field CX_WEB_AID to store these three characters and AID will always be function key of the keyboard, such as Enter, Clear, F01~F24, etc. ROW and COL mean the current cursor position when terminal sends the inbound data stream to application program. The code of these characters will be set as EBCDIC, not ASCII.