Preliminary processing of TSO/3270 passthrough mode requests

Preliminary error checks are performed on all TSO/3270 passthrough mode requests received while the TTY is in TSO/3270 passthrough mode. If the preliminary check fails, the request is not passed to TSO, and the error is reported in the response.

The following severe errors can be reported:

__error

Error description

0xC1

First byte of TSO/3270 passthrough mode request is not 0xFF.

When the TSO/E OMVS command reads a TSO/3270 passthrough mode request from the master TTY, it expects the first byte of data to be 0xFF, the TSO/3270 passthrough mode request introductory byte. If the first byte is not 0xFF, this error occurs.

This error can occur if non-TSO/3270 data is written to the slave TTY, or if the length field in the previous TSO/3270 passthrough mode request was shorter than the amount of 3270 data following it. 3270 application errors can also cause this problem.

Non-3270 data can be written to the TTY from background processes, from the job-control shell, or by inter-user message programs. This non-3270 data can get intermixed with the 3270 data stream, causing the end of the 3270 data to be treated as the start of the next (bad) TSO3270 request.

0xC2

Length field is too long.

This error occurs when the __l field in the TSO/3270 passthrough mode request is longer than 32767 bytes, which is not allowed for any request.

Note: In addition to passing back the __error field listed in the TSO/3270 passthrough mode response, the __rc field is set to -1. OMVS also ends TSO/3270 passthrough mode when one of these severe errors occurs. OMVS passes back a TSO/3270 passthrough mode response with __error set to the error code. OMVS then waits a few seconds, in case the 3270 application has not already issued read() to get the TSO/3270 passthrough mode response. OMVS then ends TSO/3270 passthrough mode. The TTY is set back to normal (non-TSO/3270 passthrough) mode. The TSO/E OMVS command then sends SIGWINCH to all processes in the foreground process group. The 3270 application may end when this error is detected (either SIGWINCH is received or the __error field is seen). It should catch SIGWINCH or else do frequent tcgetattr() to detect when OMVS ends TSO/3270 passthrough mode on the TTY.

The following error conditions are also detected in the preliminary error check. When one of these errors occurs, the requested TSO function is not invoked. The __error field in the TSO/3270 passthrough mode response is set to the value indicated, and the __rc field is set to -1.

__error: Error description
0x81: The __fcn field contains an unknown TSO function code.
This error occurs when the __fcn field is not one of the known coded values.
0x82: This TSO function required no data, but data was provided.
This error occurs when the TSO function accepts no 3270 data, but the __l field in the TSO/3270 passthrough mode request was non-zero. The __l field must be zero in this case, and no data can be passed in the TSO/3270 passthrough mode request. When processing the failing request, OMVS steps past __l bytes of data in the __d field and then looks for the start of the next TSO/3270 passthrough mode request.
0x91: The __p1 field contains an unknown coded value for this TSO/E function.
This error occurs when the requested TSO function uses the __p1 field as an input parameter. The __p1 field does not contain one of the allowed values for this TSO function.
0x92: The __p2 field contains an unknown coded value for this TSO/E function.
This error occurs when the requested TSO function uses the __p2 field as an input parameter. The __p2 field does not contain one of the allowed values for this TSO function.
0x93: The __p3 field contains an unknown coded value for this TSO/E function.
This error occurs when the requested TSO function uses the __p3 field as an input parameter. The __p3 field does not contain one of the allowed values for this TSO function.
0xA1: Not enough storage was available to invoke the requested TSO/E function.
This error occurs when the TSO/E OMVS command cannot get enough storage (usually only a few hundred bytes) to call the requested TSO/E function. The lack of storage may be of short or long duration. If this TSO/3270 passthrough mode request is reissued, it may succeed, or it could fail again.

In addition, the following warning conditions can be detected. If one of these errors is detected, the __error field in the response is set as indicated, and the requested TSO/E service is invoked. The __rc field, and the __l and __d fields are set based on the TSO/E return code and any returned data. (See the discussion of TSO return code processing that follows.) These warning conditions can be reported:

__error: Error description
0x41: Reserved __p1 field should be 0, but was non-zero.
This error occurs when the __p1 field in the TSO/3270 passthrough mode request is not used for the requested TSO/E function. This unused field is reserved, and should be set to zero in the TSO/3270 passthrough mode request.
0x42: Reserved __p2 field should be 0, but was non-zero.
This error occurs when the __p2 field in the TSO/3270 passthrough mode request is not used for the requested TSO/E function. This unused field is reserved, and should be set to zero in the TSO/3270 passthrough mode request.
0x43: Reserved __p3 field should be 0, but was non-zero.
This error occurs when the __p3 field in the TSO/3270 passthrough mode request is not used for the requested TSO/E function. This unused field is reserved, and should be set to zero in the TSO/3270 passthrough mode request.
0x49: One or more reserved bits in the __p1 field were on. This error occurs when at least one of the reserved bits in the __p1 field is not used for the requested TSO/E function. All unused bits are reserved, and should be set to zero in the TSO/3270 passthrough mode request.
0x4A: One or more reserved bits in the __p2 field were on.
This error occurs when at least one of the reserved bits in the __p2 field is not used for the requested TSO/E function. All unused bits are reserved, and should be set to zero in the TSO/3270 passthrough mode request.

Only one of these warning conditions is reported. The user 3270 application can choose to ignore these warnings, but the application may fail in the future if a reserved bit or field becomes meaningful. The 3270 application should treat these warnings as unexpected errors. The 3270 application may be designed to fail whenever the __error field is non-zero.

If none of these errors or warnings is detected, the __error field in the response will be set to 0, and the requested TSO/E service is invoked. The __rc field, and the __l and __d fields will be set based on the TSO/E return code and any returned data.