Coding SNA Communications Server conversion exit routines - Revision history

JDamon: Exit routines must be written to be re-entrant.

2017-12-05T00:53:01Z

Exit routines must be written to be re-entrant.

← Older revision		Revision as of 00:53, 5 December 2017
Line 14:		Line 14:
	</li>		</li>

	<li>Exit routines must be ~~serially reusable~~.</li>		<li>Exit routines must be written to be re-entrant.</li>

	<li>Exit routines must avoid issuing any I/O or WAIT macros that adversely affect the performance of the whole <var class="product">Model 204</var> Online job.</li>		<li>Exit routines must avoid issuing any I/O or WAIT macros that adversely affect the performance of the whole <var class="product">Model 204</var> Online job.</li>
Line 42:		Line 42:
	<li>Assemble or compile exit routines after you code them and link the object modules into the appropriate <var class="product">Model 204</var> load modules. </li>		<li>Assemble or compile exit routines after you code them and link the object modules into the appropriate <var class="product">Model 204</var> load modules. </li>
	</ul>		</ul>

	==X3270CHK (check for terminal characteristics)==		==X3270CHK (check for terminal characteristics)==
	<p>		<p>

Admin: link repair

2017-03-24T22:40:07Z

link repair

← Older revision		Revision as of 22:40, 24 March 2017
Line 1:		Line 1:
	==Overview==		==Overview==
	<p>		<p>
	Exit routines that perform data conversion external to the [[SNA Communications Server ~~terminal~~\|Model 204 SNA Communications Server]] (formerly VTAM) 3270 interface provide support for full-screen SNA Communications Server terminals that are not 3270 compatible. </p>		Exit routines that perform data conversion external to the [[Using SNA Communications Server terminals\|Model 204 SNA Communications Server]] (formerly VTAM) 3270 interface provide support for full-screen SNA Communications Server terminals that are not 3270 compatible. </p>
	<p>		<p>
	This appendix explains the rules for coding, checking, and using these routines.</p>		This appendix explains the rules for coding, checking, and using these routines.</p>

JAL: /* Overview */ add link

2017-03-24T19:34:36Z

Overview: add link

← Older revision		Revision as of 19:34, 24 March 2017
Line 1:		Line 1:
	==Overview==		==Overview==
	<p>		<p>
	Exit routines that perform data conversion external to the ~~<var class="product">~~Model 204~~</var>~~ SNA Communications Server (formerly VTAM) 3270 ~~Interface~~ provide support for full-screen SNA Communications Server terminals that are not 3270 compatible. </p>		Exit routines that perform data conversion external to the [[SNA Communications Server terminal\|Model 204 SNA Communications Server]] (formerly VTAM) 3270 interface provide support for full-screen SNA Communications Server terminals that are not 3270 compatible. </p>
	<p>		<p>
	This appendix explains the rules for coding, checking, and using these routines.</p>		This appendix explains the rules for coding, checking, and using these routines.</p>

	==Rules governing data conversion exit routines==		==Rules governing data conversion exit routines==
	<p>		<p>

JAL: add category

2017-03-24T19:24:18Z

add category

← Older revision		Revision as of 19:24, 24 March 2017
Line 253:		Line 253:
	[[Category:System management]]		[[Category:System management]]
	[[Category:System-level capabilities of Model 204]]		[[Category:System-level capabilities of Model 204]]
			[[Category:SNA Communications Server]]

JALWiccan: Automatically generated page update

2014-11-06T17:08:05Z

Automatically generated page update

← Older revision		Revision as of 17:08, 6 November 2014
Line 251:		Line 251:
	</ul>		</ul>

	[[Category:System ~~Manager~~]]		[[Category:System management]]
	[[Category:System-level capabilities of Model 204]]		[[Category:System-level capabilities of Model 204]]

JALWiccan: Automatically generated page update

2014-11-05T17:13:03Z

Automatically generated page update

← Older revision		Revision as of 17:13, 5 November 2014
Line 252:		Line 252:

	[[Category:System Manager]]		[[Category:System Manager]]
	[[Category:System-level capabilities ~~available in~~ Model 204]]		[[Category:System-level capabilities of Model 204]]

JAL at 21:18, 29 October 2014

2014-10-29T21:18:55Z

← Older revision		Revision as of 21:18, 29 October 2014
Line 252:		Line 252:

	[[Category:System Manager]]		[[Category:System Manager]]
			[[Category:System-level capabilities available in Model 204]]

Admin: 1 revision: converted system mgr pages

2014-10-17T20:27:53Z

1 revision: converted system mgr pages

← Older revision	Revision as of 20:27, 17 October 2014
(No difference)

JAL: more conversion cleanup

2014-10-17T19:22:02Z

more conversion cleanup

New page

==Overview==

Exit routines that perform data conversion external to the <var class="product">Model 204</var> SNA Communications Server (formerly VTAM) 3270 Interface provide support for full-screen SNA Communications Server terminals that are not 3270 compatible. 

This appendix explains the rules for coding, checking, and using these routines.

==Rules governing data conversion exit routines==

The following rules apply when you convert exit routines:
<ul>
<li>Exit routines must acquire and release their own work areas.

These work areas are allocated out of the storage reserved by <var>[[SPCORE parameter|SPCORE]]</var> for 24-bit addressing systems. If z/OS is available, the exit routines might allocate space above the 16 megabyte line.
</li>

<li>Exit routines must be serially reusable.</li>

<li>Exit routines must avoid issuing any I/O or WAIT macros that adversely affect the performance of the whole <var class="product">Model 204</var> Online job.</li>

<li>Exit routines must not issue STAE, SPIE, ESTAE, or ESPIE macros.</li>

<li>Exit routines must preserve addressing mode and program interrupt mode.
<blockquote class="note">
Note:
The value of <code>AMODE</code> must be 31 to ensure compatibility with z/OS.

For addresses above the 16MB line, the correct addressing mode is set by the following instruction, which restores the addressing mode in effect when the exit first gained control: 
BSM 0,R14
</blockquote></li>

<li>Exit routines must be named:
<ul>
<li>X3270CHK (check for terminal characteristics)</li>

<li>X3270OUT (convert output from 3270 format)</li>

<li>X3270IN (convert input to 3270 format)</li>
</ul></li>

<li>Define each exit routine as a separate entry point or CSECT. </li>

<li>Assemble or compile exit routines after you code them and link the object modules into the appropriate <var class="product">Model 204</var> load modules. </li>
</ul>

==X3270CHK (check for terminal characteristics)==

Information about the terminal that is attempting to establish a session with <var class="product">Model 204</var> is passed to the X3270CHK routine. Provide the following information:
<ul>
<li>Eight-character SNA Communications Server logical terminal identifier</li>

<li>Terminal's session parameters</li>

<li>SNA Communications Server LOGMSG associated with the terminal</li>
</ul>

The exit routine then returns a fullword that <var class="product">Model 204</var> passes to the conversion exit routines. The fullword can be used to determine various options, such as:
<ul>
<li>Whether to convert the data streams for this terminal</li>

<li>What terminal type is connecting to <var class="product">Model 204</var>, allowing for the handling of more than one terminal type in the conversion exit routines </li>
</ul>

In addition to setting a value to the informational fullword, this exit routine can modify the SNA Communications Server LOGMSG associated with the terminal or move in a message to use as the SNA Communications Server LOGMSG.

===Communication protocols===

The X3270CHK routine communicates with the <var class="product">Model 204</var> SNA Communications Server 3270 Interface in the following manner.

====Upon entry====

Register 1 – Contains the address of a parameter list in the following format:
<ul>
<li>The first word contains the address of a fullword that holds an error return code value when leaving the exit routine.</li>

<li>The second word contains the address of the 8-character SNA Communications Server logical terminal identifier.</li>

<li>The third word contains the address of the session parameters associated with the terminal.</li>

<li>The fourth word contains the address of the SNA Communications Server LOGMSG associated with the terminal. The fourth word always holds a valid address, even if there is no SNA Communications Server LOGMSG.</li>

<li>The fifth word contains the address of a fullword that stores the maximum allowed length of the SNA Communications Server LOGMSG.</li>

<li>The sixth word contains the address of a fullword that holds the current length of the SNA Communications Server LOGMSG. A length of zero means there was no SNA Communications Server LOGMSG.</li>

<li>The seventh word contains the address of a fullword that has information to pass to the conversion exit routines. The initial value of the fullword is zero. The high-order bit of this word is on to indicate the end of the parameter list. </li>
</ul>

Register 13 – Contains the address of an 18-fullword register savearea.

Register 14 – Contains the address in the <var class="product">Model 204</var> SNA Communications Server 3270 Interface to which the X3270CHK exit routine must branch when it finishes processing.

Register 15 – Contains the address of the X3270CHK exit routine. 

Registers 2-12 must be preserved by the X3270CHK exit routine for
<var class="product">Model 204</var>. 

====Upon leaving====

The arguments pointed to by the parameter list can be modified by the exit routine in the following ways:
<ul>
<li>Set the error return code field. It cannot be assumed that it is set to zero upon entry. A value of zero indicates that the exit routine had no problem checking for the terminal characteristics it was looking for. If the value is nonzero, the <var class="product">Model 204</var> SNA Communications Server 3270 Interface does the following:
<ul>
<li>Issues an error message about a problem with the terminal, giving the terminal's logical SNA Communications Server identifier and the error return code value to the audit trail.</li>

<li>Issues a CLSDST to the terminal to terminate the terminal's request for a session. The fullword to be passed to the conversion exit routines should be set. If the SNA Communications Server LOGMSG is modified, the current length argument must be updated. </li>
</ul></li>

<li>If the exit routine is written in Assembler Language, the copy member X3270CPL in the Rocket Software-supplied macro library can be used to define the routine's parameter list. The labels used in this copy member are as follows:
<ul>
<li>X3270CPL is the DSECT name. </li>

<li>X3270CRC is the address of the return code field.</li>

<li>X3270CID is the address of the terminal's logical network ID.</li>

<li>X3270CSP is the address of the terminal's session parameters.</li>

<li>X3270CLG is the address of the terminal's SNA Communications Server LOGMSG.</li>

<li>X3270CML is the address of the maximum SNA Communications Server LOGMSG length.</li>

<li>X3270CLL is the address of the current SNA Communications Server LOGMSG length.</li>

<li>X3270CCW is the address of the word to be generated by X3270CHK. </li>
</ul></li>
</ul>

==X3270OUT (convert output from 3270 format)==

The X3270OUT routine is responsible for converting an output data stream in 3270 format from <var class="product">Model 204</var> to the appropriate device protocol. The exit routine is given the address of the actual output buffer that <var class="product">Model 204</var> passes to SNA Communications Server, into which the converted output data stream must be placed. This exit routine must be able to handle all the 3270 output commands and attributes.

If this conversion exit is linked into the <var class="product">Model 204</var> Online job, it is then responsible for moving the output data into the <var class="product">Model 204</var> SNA Communications Server output buffer even if no actual conversion is performed.

The X3270OUT routine communicates with the <var class="product">Model 204</var> SNA Communications Server 3270 Interface in the following manner.

====Upon entry====

Register 1 – Contains the address of a parameter list in the following format:
<ul>
<li>The first word contains the address of a fullword that encloses a return code value when leaving the exit routine.</li>

<li>The second word includes the address of the fullword generated by the exit routine, X3270CHK.</li>

<li>The third word contains the address of a <var class="product">Model 204</var> SNA Communications Server output buffer. The converted output data stream must occupy the SNA Communications Server output buffer upon leaving the X3270OUT routine.</li>

<li>The fourth word contains the address of the fullword that includes the length of the <var class="product">Model 204</var> SNA Communications Server output buffer. The fourth word corresponds to the <var class="product">Model 204</var> parameter, <var>[[LOUTPB parameter|LOUTPB]]</var>, on the first SNA Communications Server 3270 thread. The length of the converted output data stream must not exceed the <var>LOUTPB</var> value.</li>

<li>The fifth word includes the address of the 3270 output data stream.</li>

<li>The sixth word contains the address of the fullword enclosing the current length of the 3270 output data stream. The high-order bit of this word is on to indicate the end of the parameter list. </li>
</ul>

Register 13 – Contains the address of an 18-fullword register savearea.

Register 14 – Contains the address in the <var class="product">Model 204</var> SNA Communications Server 3270 Interface to which the X3270OUT exit routine must branch when it finishes processing.

Register 15 – Contains the address of the X3270OUT exit routine.

Registers 2-12 must be preserved by the X3270OUT exit routine for
<var class="product">Model 204</var>.

====Upon leaving====

The following arguments pointed to by the parameter list must be modified by the exit routine:
<ul>
<li>The return code field must be set. (It cannot be assumed that it is set to zero upon entry.) A value of zero indicates that the data stream conversion was successful. If the value is nonzero, the <var class="product">Model 204</var> SNA Communications Server 3270 Interface does the following:
<ul>
<li>Issues an error message stating the failure of the output data stream conversion, with the return code value, to the audit trail.</li>

<li>Takes a SNAP of the user's thread for diagnostic information.</li>

<li>Performs a soft restart of the user's thread. The length of the converted output data stream field must be set in the current output length argument.</li>
</ul></li>

<li>If the exit routine is written in Assembler Language, the copy member X3270OPL in the Rocket Software-supplied macro library can be used to define the routine's parameter list. The labels used in this copy member are as follows:
<ul>
<li> X3270OPL is the DSECT name.</li>

<li> X3270ORC is the address of the return code field.</li>

<li> X3270OCW is the address of the word generated by X3270CHK.</li>

<li> X3270OBF is the address of the <var class="product">Model 204</var> SNA Communications Server output buffer.</li>

<li> X3270OML is the address of the maximum SNA Communications Server buffer length.</li>

<li> X3270ODA is the address of the 3270 output data stream.</li>

<li> X3270ODL is the address of the 3270 output data stream length. </li>
</ul></li>
</ul>

==X3270IN (convert input to 3270 format)==

The X3270IN exit routine is responsible for converting an input data stream from the appropriate device protocol to 3270 format for input to <var class="product">Model 204</var>. 

===Communications protocols===

The X3270IN routine communicates with the <var class="product">Model 204</var> SNA Communications Server 3270 Interface in the following manner.

====Upon entry====

Register 1 – Contains the address of a parameter list in the following format:
<ul>
<li>The first word contains the address of a fullword that includes a return code value when leaving the exit routine.</li>

<li>The second word contains the address of the fullword generated by the exit routine X3270CHK.</li>

<li>The third word contains the address of a <var class="product">Model 204</var> SNA Communications Server input buffer. The converted input data stream must occupy this buffer upon leaving this routine.</li>

<li>The fourth word contains the address of a fullword that holds the length of the input data stream. The length of the converted 3270 input data stream is passed back in this argument.</li>

<li>The fifth word contains the address of a fullword that holds the length of the <var class="product">Model 204</var> SNA Communications Server input buffer. This corresponds to the <var class="product">Model 204</var> <var>LOUTPB</var> parameter on the first SNA Communications Server 3270 thread. The length of the converted input data stream must not exceed the <var>LOUTPB</var> value. The high-order bit of this word is on to indicate the end of the parameter list. </li>
</ul>

Register 13 – Contains the address of an 18-fullword register savearea.

Register 14 – Contains the address in the <var class="product">Model 204</var> SNA Communications Server 3270 Interface to which the X3270IN exit routine must branch when it finishes processing.

Register 15 – Contains the address of the X3270IN exit routine. 

Registers 2-12 must be preserved by the X3270IN exit routine for <var class="product">Model 204</var>.

====Upon leaving====

The following arguments pointed to by the parameter list must be modified by the exit routine:
<ul>
<li>The return code field must be set. (Do not assume that it is set to zero upon entry.) A value of zero indicates that the conversion of the data stream was successful. If the value is nonzero, the <var class="product">Model 204</var> SNA Communications Server 3270 Interface does the following:
<ul>
<li>Issues an error message about the failure of the conversion of the input data stream, with the return code value to the audit trail.</li>

<li>Takes a SNAP of the user's thread for diagnostic information.</li>

<li>Performs a soft restart of the user's thread. The length of the converted 3270 input data stream must be set in the argument that held the length of the original input data stream. </li>
</ul></li>

<li>If the exit routine is written in Assembler Language, the copy member X3270IPL in the Rocket Software-supplied macro library can be used to define the routine's parameter list. The labels used in this copy member are as follows:
<ul>
<li> X3270IPL is the DSECT name.</li>

<li> X3270IRC is the address of the return code field.</li>

<li> X3270ICW is the address of the word generated by X3270CHK.</li>

<li> X3270IBF is the address of the <var class="product">Model 204</var> SNA Communications Server input buffer.</li>

<li> X3270IDL is the address of the input data length.</li>

<li> X3270IML is the address of the maximum SNA Communications Server input buffer length. </li>
</ul></li>
</ul>

[[Category:System Manager]]