Coding SNA Communications Server conversion exit routines

Overview

Exit routines that perform data conversion external to the Model 204 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:

• Exit routines must acquire and release their own work areas.

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

• Exit routines must be written to be re-entrant.
• Exit routines must avoid issuing any I/O or WAIT macros that adversely affect the performance of the whole Model 204 Online job.
• Exit routines must not issue STAE, SPIE, ESTAE, or ESPIE macros.
• Exit routines must preserve addressing mode and program interrupt mode.

  Note: The value of AMODE 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

• Exit routines must be named:
  • X3270CHK (check for terminal characteristics)
  • X3270OUT (convert output from 3270 format)
  • X3270IN (convert input to 3270 format)
• Define each exit routine as a separate entry point or CSECT.
• Assemble or compile exit routines after you code them and link the object modules into the appropriate Model 204 load modules.

X3270CHK (check for terminal characteristics)

Information about the terminal that is attempting to establish a session with Model 204 is passed to the X3270CHK routine. Provide the following information:

• Eight-character SNA Communications Server logical terminal identifier
• Terminal's session parameters
• SNA Communications Server LOGMSG associated with the terminal

The exit routine then returns a fullword that Model 204 passes to the conversion exit routines. The fullword can be used to determine various options, such as:

• Whether to convert the data streams for this terminal
• What terminal type is connecting to Model 204, allowing for the handling of more than one terminal type in the conversion exit routines

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 Model 204 SNA Communications Server 3270 Interface in the following manner.

Upon entry

Register 1 – Contains the address of a parameter list in the following format:

• The first word contains the address of a fullword that holds an error return code value when leaving the exit routine.
• The second word contains the address of the 8-character SNA Communications Server logical terminal identifier.
• The third word contains the address of the session parameters associated with the terminal.
• 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.
• The fifth word contains the address of a fullword that stores the maximum allowed length of the SNA Communications Server LOGMSG.
• 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.
• 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.

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

Register 14 – Contains the address in the Model 204 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 Model 204.

Upon leaving

The arguments pointed to by the parameter list can be modified by the exit routine in the following ways:

• 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 Model 204 SNA Communications Server 3270 Interface does the following:
  • 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.
  • 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.
• 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:
  • X3270CPL is the DSECT name.
  • X3270CRC is the address of the return code field.
  • X3270CID is the address of the terminal's logical network ID.
  • X3270CSP is the address of the terminal's session parameters.
  • X3270CLG is the address of the terminal's SNA Communications Server LOGMSG.
  • X3270CML is the address of the maximum SNA Communications Server LOGMSG length.
  • X3270CLL is the address of the current SNA Communications Server LOGMSG length.
  • X3270CCW is the address of the word to be generated by X3270CHK.

X3270OUT (convert output from 3270 format)

The X3270OUT routine is responsible for converting an output data stream in 3270 format from Model 204 to the appropriate device protocol. The exit routine is given the address of the actual output buffer that Model 204 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 Model 204 Online job, it is then responsible for moving the output data into the Model 204 SNA Communications Server output buffer even if no actual conversion is performed.

The X3270OUT routine communicates with the Model 204 SNA Communications Server 3270 Interface in the following manner.

Upon entry

Register 1 – Contains the address of a parameter list in the following format:

• The first word contains the address of a fullword that encloses a return code value when leaving the exit routine.
• The second word includes the address of the fullword generated by the exit routine, X3270CHK.
• The third word contains the address of a Model 204 SNA Communications Server output buffer. The converted output data stream must occupy the SNA Communications Server output buffer upon leaving the X3270OUT routine.
• The fourth word contains the address of the fullword that includes the length of the Model 204 SNA Communications Server output buffer. The fourth word corresponds to the Model 204 parameter, LOUTPB, on the first SNA Communications Server 3270 thread. The length of the converted output data stream must not exceed the LOUTPB value.
• The fifth word includes the address of the 3270 output data stream.
• 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.

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

Register 14 – Contains the address in the Model 204 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 Model 204.

Upon leaving

The following arguments pointed to by the parameter list must be modified by the exit routine:

• 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 Model 204 SNA Communications Server 3270 Interface does the following:
  • Issues an error message stating the failure of the output data stream conversion, with the return code value, to the audit trail.
  • Takes a SNAP of the user's thread for diagnostic information.
  • 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.
• 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:
  • X3270OPL is the DSECT name.
  • X3270ORC is the address of the return code field.
  • X3270OCW is the address of the word generated by X3270CHK.
  • X3270OBF is the address of the Model 204 SNA Communications Server output buffer.
  • X3270OML is the address of the maximum SNA Communications Server buffer length.
  • X3270ODA is the address of the 3270 output data stream.
  • X3270ODL is the address of the 3270 output data stream length.

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 Model 204.

Communications protocols

The X3270IN routine communicates with the Model 204 SNA Communications Server 3270 Interface in the following manner.

Upon entry

Register 1 – Contains the address of a parameter list in the following format:

• The first word contains the address of a fullword that includes a return code value when leaving the exit routine.
• The second word contains the address of the fullword generated by the exit routine X3270CHK.
• The third word contains the address of a Model 204 SNA Communications Server input buffer. The converted input data stream must occupy this buffer upon leaving this routine.
• 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.
• The fifth word contains the address of a fullword that holds the length of the Model 204 SNA Communications Server input buffer. This corresponds to the Model 204 LOUTPB parameter on the first SNA Communications Server 3270 thread. The length of the converted input data stream must not exceed the LOUTPB value. The high-order bit of this word is on to indicate the end of the parameter list.

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

Register 14 – Contains the address in the Model 204 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 Model 204.

Upon leaving

The following arguments pointed to by the parameter list must be modified by the exit routine:

• 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 Model 204 SNA Communications Server 3270 Interface does the following:
  • Issues an error message about the failure of the conversion of the input data stream, with the return code value to the audit trail.
  • Takes a SNAP of the user's thread for diagnostic information.
  • 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.
• 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:
  • X3270IPL is the DSECT name.
  • X3270IRC is the address of the return code field.
  • X3270ICW is the address of the word generated by X3270CHK.
  • X3270IBF is the address of the Model 204 SNA Communications Server input buffer.
  • X3270IDL is the address of the input data length.
  • X3270IML is the address of the maximum SNA Communications Server input buffer length.