| 1 | Pass-through information | Input | Char(*) |
| 2 | Length of pass-through information | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Data | Input | Char(*) |
| 5 | Length of data | Input | Binary(4) |
| 6 | Error code | I/O | Char(*) |
The Start Pass-Through (QPASTRPT) API starts a 5250 pass-through session and optionally passes up to 1KB of user data from the source system to the target system. This data can be accessed on the target system with the Retrieve Data (QPARTVDA) API.
Information associated with establishing the 5250 pass-through session.
The length, in bytes, of the pass-through information parameter. This value must be greater than or equal to 8 and less than or equal to 580.
The format of the pass-through information. The supported format names are:
| PAST0100 | Pass-through with up to 10-byte password |
| PAST0200 | Pass-through with up to 128-byte password |
See PAST0100 Format and PAST0200 Format for details.
User-defined data to be passed to the target system. The format of this data is not defined by the API, and is sent to the target system as is.
The length of the data parameter.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following table is the layout of the pass-through information for format PAST0100, which controls how the pass-through session is established for a pass-through with up to a 10-byte password.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Remote location name |
| 8 | 8 | CHAR(10) | Virtual controller |
| 18 | 12 | CHAR(8) | Mode name |
| 26 | 1A | CHAR(8) | Local location name |
| 34 | 22 | CHAR(8) | Remote network ID |
| 42 | 2C | CHAR(10) | System request program name |
| 52 | 34 | CHAR(10) | System request library name |
| 62 | 3E | CHAR(10) | Remote user ID |
| 72 | 48 | CHAR(10) | Remote password |
| 82 | 52 | CHAR(10) | Initial program |
| 92 | 5C | CHAR(10) | Initial menu |
| 102 | 66 | CHAR(10) | Current library |
| 112 | 70 | CHAR(1) | Display option |
| 113 | 71 | CHAR(3) | Reserved |
| 116 | 74 | BINARY(4) | Offset to virtual devices |
| 120 | 78 | BINARY(4) | Number of virtual devices |
| CHAR(*) | Array of virtual devices | ||
The following table is the layout of the pass-through information for format PAST0200, which controls how the pass-through session is established for a pass-through with up to a 128-byte password.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Remote location name |
| 8 | 8 | CHAR(10) | Virtual controller |
| 18 | 12 | CHAR(8) | Mode name |
| 26 | 1A | CHAR(8) | Local location name |
| 34 | 22 | CHAR(8) | Remote network ID |
| 42 | 2C | CHAR(10) | System request program name |
| 52 | 34 | CHAR(10) | System request library name |
| 62 | 3E | CHAR(10) | Remote user ID |
| 72 | 48 | CHAR(10) | Reserved |
| 82 | 52 | CHAR(10) | Initial program |
| 92 | 5C | CHAR(10) | Initial menu |
| 102 | 66 | CHAR(10) | Current library |
| 112 | 70 | CHAR(1) | Display option |
| 113 | 71 | CHAR(3) | Reserved |
| 116 | 74 | BINARY(4) | Offset to virtual devices |
| 120 | 78 | BINARY(4) | Number of virtual devices |
| 124 | 7C | BINARY(4) | Offset to remote password |
| 128 | 80 | BINARY(4) | Phrase length of remote password |
| CHAR(*) | Remote password | ||
| CHAR(*) | Array of virtual devices | ||
Array of virtual devices. An array of 0 through 32 virtual devices on the target system. A device on the target system is selected from this list based on a comparison of device type and model.
Current library. The library to be the current library on the target system. The special value *RMTUSRPRF can be used to indicate that the current library found in the remote user profile should be used.
Display option. Whether the pass-through and associated status messages appear. Special values follow:
| 0 | Do not display pass-through information. |
| 1 | Display pass-through information. |
Initial menu. The menu that is initially shown at the target system. This runs after the initial program. Special values follow:
| *RMTUSRPRF | Show the initial menu as specified by the remote user profile. |
| *SIGNOFF | Sign off the target system after running the initial program. |
Initial program. The program that is called immediately after sign-on to the target system. Special values follow:
| *RMTUSRPRF | Call the initial program as specified by the remote user profile. |
| *NONE | There is no initial program to call. |
Local location name. The name by which the local system is known to other devices in the network. Special values follow:
| *LOC | The local location name is chosen by the system. |
| *NETATR | The local location name, a system network attribute, is used. |
Mode name. The mode to be used. The special value *NETATR can be used to indicate that the system network attribute mode should be used.
Number of virtual devices. The number of virtual devices in the array of virtual devices. If the virtual controller field is not *NONE, this field must be set to 0.
Offset to remote password. The offset from the beginning of the format to the start of the remote password. The phrase length of the remote password field must be a valid value.
Offset to virtual devices. The offset from the beginning of the format to the start of the array of virtual devices. If the virtual controller field is not *NONE, this field must be set to 0.
Phrase length of remote password. The length, in bytes, of the remote password. This value must be greater than 0 and less than or equal to 128.
Remote location name. The name of the location that is the target of the pass-through session.
Remote network ID. The network ID of the network where the remote location resides. Special values follow:
| *LOC | Any remote location name will be used. |
| *NETATR | The local network ID, a system network attribute, is used. |
| *NONE | The remote system does not support network IDs. |
Remote password. The password being sent to the target system. The special value allowed is *NONE. If a profile is specified for the remote user ID field and password security is active on the target system, *NONE is not allowed.
Remote user ID. The user profile for automatic sign-on to the target system. Special values follow:
| *NONE | No user ID is passed to the target system; automatic sign-on is not used. |
| *CURRENT | The user ID that is active in the current job is passed to the remote system. |
Reserved. An ignored field. This field must be blanks.
System request library name. The library in which the system request program can be found. Special values are *LIBL and *CURLIB. If the system request program is *SRQMNU, this field must be set to blanks.
System request program name. The program that is to be called on the source system when system request option 10 is selected. The special value *SRQMNU causes the system-supplied system request menu to be displayed.
Virtual controller. The name of the virtual controller on the target system that is used to do pass-through. If you specify a virtual controller, one of the virtual display devices attached to it is selected for the pass-through job. This entry is mutually exclusive of the array of virtual devices, and must be *NONE if the number of virtual devices field is not 0. The default is *NONE.
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF2702 E | Device description &1 not found. |
| CPF2703 E | Controller description &1 not found. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF5383 E | Mode &7 specified for divice &4 not valid. |
| CPF5536 E | System cannot automatically select an APPC device description for the remote location. |
| CPF5546 E | Class-of-service for device &4 not valid. |
| CPF8901 E | Virtual device &1 not varied on. |
| CPF8902 E | Virtual device &1 not available. |
| CPF8904 E | Pass-through request not accepted. |
| CPF8905 E | Pass-through not allowed on this system. |
| CPF8906 E | Error during session initialization. Reason code &1. |
| CPF8907 E | Communications failure for device &1. |
| CPF8908 E | Controller &1 not varied on. |
| CPF8911 E | Communications failure. Session was not started. |
| CPF8912 E | Pass-through session ended. Reason code &1. |
| CPF8913 E | Pass-through ended abnormally. |
| CPF8916 E | Cannot select virtual device &1 at system &2. |
| CPF8918 E | Job canceled at system &1. |
| CPF8919 E | Device &1 not accessed by system &2. |
| CPF8920 E | Pass-through failed. &1 must be varied off and on. |
| CPF8921 E | APPC failure. Failure code is &3. |
| CPF8922 E | Negative response from device &1 at system &2. |
| CPF8935 E | Pass-through not allowed to system &1. |
| CPF8936 E | Pass-through failed for security reasons. |
| CPF8937 E | Automatic sign on not allowed. |
| CPF8939 E | Trying to send too much data. |
| CPF8944 E | Device &1 no longer communicating with system &2. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |