Start Pass-Through (STRPASTHR)

Where allowed to run: Interactive environments (*INTERACT *IPGM *IREXX *EXEC)
Threadsafe: No 		Parameters
Examples
Error messages

The Start Pass-Through (STRPASTHR) command allows you to pass through to a target system where you can sign on as if you were attached locally. For information on configuring or operating the pass-through function, refer to the Remote Work Station Support book.

Restriction:

  1. This command cannot be entered at a work station with a display that has 12 lines by 80 characters.

Top

 

Parameters

Keyword Description Choices Notes
RMTLOCNAME Remote location Communications name, *CNNDEV Required, Positional 1
CNNDEV APPC device Single values: *LOC
Other values (up to 16 repetitions): Name 		Optional
VRTCTL Virtual controller Name, *NONE Optional, Positional 2
VRTDEV Virtual display device Single values: *NONE
Other values (up to 32 repetitions): Name 		Optional, Positional 3
MODE Mode Communications name, *NETATR Optional
LCLLOCNAME Local location Communications name, *LOC, *NETATR Optional
RMTNETID Remote network identifier Communications name, *LOC, *NETATR, *NONE Optional
SRQ10PGM System request program Single values: *SRQMNU
Other values: Qualified object name 		Optional
Qualifier 1: System request program Name
Qualifier 2: Library Name, *LIBL, *CURLIB
RMTUSER User profile Character value, *NONE, *CURRENT Optional
RMTPWD User password Character value, *NONE Optional
RMTINLPGM Initial program to call Name, *RMTUSRPRF, *NONE Optional
RMTINLMNU Initial menu Name, *RMTUSRPRF, *SIGNOFF Optional
RMTCURLIB Current library Name, *RMTUSRPRF Optional
PASTHRSCN Display option Character value, *YES, *NO Optional

Top

 

Remote location (RMTLOCNAME)

Specifies one of the following:

remote-location-name

Specify the remote location name that is the target of the pass-through session or the first system that does intermediate pass-through routing. APPN determines the route to this location.

*CNNDEV

Use the APPC devices specified with the APPC device prompt (CNNDEV parameter).

Top

 

APPC device (CNNDEV)

Specifies the names of the device descriptions that connect the first system to do pass-through routing with the target system. If *CNNDEV is specified on the Remote location prompt (RMTLOCNAME parameter), the first device specified on this parameter is on the source system. If the name of a remote location is specified on the Remote location prompt (RMTLOCNAME parameter), the first device specified on this parameter is on the system in that remote location. If another system connects the source system to the target system and pass-through must establish the intermediate sessions, then specify a list of APPC device descriptions. The APPC device names must be listed in the order that the systems are passed through to get to the target system.

You can enter multiple values for this parameter.

*LOC

The Remote location prompt (RMTLOCNAME parameter) specifies the name of the remote location that is the target of the pass-through session.

device-name(s)

Specify the names of the device descriptions that complete the route from the source system to the target system. Up to 16 names can be specified.

Top

 

Virtual controller (VRTCTL)

Specifies the name of the virtual controller on the remote system that is used to do pass-through jobs. If you specify a virtual controller, one of the virtual display devices attached to it is selected for the pass-through job. A device on the target system is selected based on a comparison of device type and model.

This entry is mutually exclusive with an entry on the Virtual display device prompt (VRTDEV parameter); *NONE must be specified when one or more devices are specified on the Virtual display device prompt (VRTDEV parameter).

*NONE

No controller is specified. If *NONE is also specified on the Virtual display device prompt (VRTDEV parameter), you are requesting automatic configuration.

virtual-controller-name

Specify the name of the virtual controller description on the target system.

Top

 

Virtual display device (VRTDEV)

Specifies one or more devices on the target system that are connected to a virtual controller used for the pass-through session. A device on the target system from the list is selected based on a comparison of device type and model.

This entry is mutually exclusive with an entry on the Virtual controller prompt (VRTCTL parameter); *NONE must be specified when a controller name is specified on the Virtual controller prompt (VRTCTL parameter).

You can enter multiple values for this parameter.

*NONE

No device names are specified. If *NONE is also specified on the Virtual controller prompt (VRTCTL parameter), you are requesting automatic configuration.

virtual-display-device-name

Specify the names of the virtual display device descriptions on the target system. Up to 32 names can be specified.

Top

 

Mode (MODE)

Specifies the mode name used.

*NETATR

The mode in the network attributes is used.

mode-name

Specify a mode name.

Top

 

Local location (LCLLOCNAME)

Specifies the local location name.

*LOC

The local location name is chosen by the system.

*NETATR

The LCLLOCNAME value specified in the system network attributes is used.

APPN-location-name

Specify the local location name that is associated with the source system. If the local location name is not valid, an escape message is sent.

Top

 

Remote network identifier (RMTNETID)

Specifies the network ID of the network where the remote location resides.

*LOC

Any remote network ID for the remote location may be used.

*NETATR

The LCLNETID value specified in the system network attributes is used.

*NONE

The remote location does not support network identifiers.

APPN-network-identifier

Specify a remote network ID.

Top

 

System request program (SRQ10PGM)

Specifies that the system request menu is displayed, or specifies the name of the program that starts on the source system when system request option 10 is selected.

The user program can display a menu that allows you to select the system you want to access, and then transfer to a group job that sends the Start Pass-Through (STRPASTHR) command to the desired system. For more information, see the Remote Work Station Support book.

*SRQMNU

The system request menu on the source system is displayed.

program-name

Specify the program and library names of the program started when system request option 10 is selected.

The possible library values are:

*LIBL

The library list is used to locate the program.

*CURLIB

The current library for the job is used to locate the program. If no current library entry exists in the library list, QGPL is used.

library-name

Specify the library where the program is located.

Top

 

User profile (RMTUSER)

Specifies the user profile for automatic sign-on to the target system. If a profile is specified for this parameter and password security is active on the target system, (*NONE) is not valid for the User password prompt (RMTPWD parameter).

*NONE

No user profile name is sent, and no automatic sign-on occurs.

*CURRENT

The user profile of the job using this command is sent. If the target system allows it, and the user profile exists on the target system, and the password specified in the RMTPWD parameter is valid for the profile, the user is automatically signed on. Otherwise, the user is presented with a sign-on display on the target system or a failure message on the source system, depending on the configuration of the target system.

profile-name

Specify a user profile name to use that exists on the target system. If the target system allows it, and if the user profile exists on the target system, the user is automatically signed on. Otherwise, the user is presented with a sign-on display on the target system or a failure message on the source system, depending on the configuration of the target system. If a profile is specified and password security is active on the target system, a password must be specified, even if the profile specified is the same as the current profile.

Top

 

User password (RMTPWD)

Specifies the password being sent to the target system.

*NONE

The system does not send a password. If a profile is specified on the User profile prompt (RMTUSER parameter), and password security is active on the target system, this value is not allowed.

password

Specify a password being sent to the target system to verify the sign-on of the user specified in the RMTUSER parameter. This password is encrypted before being sent across the communication line.

Top

 

Initial program to call (RMTINLPGM)

Specifies the program that is called immediately after you sign on.

*RMTUSRPRF

The initial program specified in the remote user profile is called immediately after automatic sign-on.

*NONE

No program is run before the initial menu is shown, even if an initial program is specified in the remote user profile.

program

Specify the name of a program that is called immediately after automatic sign-on.

Top

 

Initial menu (RMTINLMNU)

Specifies the first menu shown when you are automatically signed on to the target system after the initial program is run.

*RMTUSRPRF

The initial menu specified in the remote user profile is shown immediately after the initial program is run.

*SIGNOFF

A menu is not shown after the initial program is run, even if an initial menu is specified in the remote user profile. After the initial program ends, the user is signed off, and the pass-through session ends.

menu

Specify the menu that is shown immediately after the initial program is run.

Top

 

Current library (RMTCURLIB)

Specifies the name of the library that becomes the current library in the library list of the job after automatic sign-on.

*RMTUSRPRF

The current library specified in the remote user profile becomes the current library in the library list after automatic sign-on.

library

Specify the library that becomes the current library in the library list after automatic sign-on.

Top

 

Display option (PASTHRSCN)

Specifies whether the pass-through display and associated status messages appear before the pass-through session is established.

*YES

The pass-through display and information messages are shown before the pass-through session is established.

*NO

The pass-through display and information messages are not shown before the pass-through session is established.

Top

 

Examples

Example 1: Pass-Through to Toronto 

 STRPASTHR   RMTLOCNAME(*CNNDEV)  CNNDEV(DET CHI TOR)  VRTCTL(VWSC)

This command specifies starting a pass-through to the Toronto system by going through Detroit and Chicago. More information is in the Remote Work Station Support book located in the Information Center.

Example 2: Pass-Through to Detroit 

 STRPASTHR   RMTLOCNAME(DETROIT)  VRTCTL(VWSC)

This command specifies a pass-through to the Detroit system. APPN establishes the route to Detroit.

Example 3: Pass-Through to Toronto 

 STRPASTHR   RMTLOCNAME(DETROIT)  CNNDEV(CHI TOR)  VRTCTL(VWSC)

This command specifies another way to pass-through to the Toronto system by going through Chicago and Detroit. APPN establishes the route to Detroit.

Example 4: Pass-Through to Detroit 

 STRPASTHR   RMTLOCNAME(DETROIT)  RMTUSER(*CURRENT)

This command specifies a pass-through to the DETROIT system and an automatic sign-on using the user profile with the same name as the one currently used on the source system. It also specifies that the DETROIT system automatically configures a virtual device for the pass-through session, since a virtual controller or virtual device was not specified.

Top

 

Error messages

*ESCAPE Messages

CPF2702

Device description &1 not found.

CPF2703

Controller description &1 not found.

CPF5383

Mode &7 specified for device &4 not valid.

CPF5536

System cannot automatically select an APPC device description for the remote location.

CPF5546

Class-of-service for device &4 not valid.

CPF8901

Virtual device &1 not varied on.

CPF8902

Virtual device &1 not available.

CPF8903

Device &1 not valid for pass-through.

CPF8904

Pass-through request not accepted.

CPF8905

Pass-through not allowed on this system.

CPF8906

Error during session initialization. Reason code &1.

CPF8907

Communications failure for device &1.

CPF8908

Controller &1 not varied on.

CPF8909

Old software release. Pass-through ended.

CPF8910

Controller &1 not valid for pass-through.

CPF8911

Communications failure. Session was not started.

CPF8912

Pass-through session ended. Reason code &1.

CPF8913

Pass-through ended abnormally.

CPF8916

Cannot select virtual device &1 at system &2.

CPF8917

Not authorized to &1.

CPF8918

Job canceled at system &1.

CPF8919

Device &1 not accessed by system &2.

CPF8920

Pass-through failed. &1 must be varied off and on.

CPF8921

APPC failure. Failure code is &3.

CPF8922

Negative response from device &1 at system &2.

CPF8923

Data stream received at system &1 not valid.

CPF8924

No available virtual controller.

CPF8925

Device &1 not created.

CPF8928

Device &1 could not be changed.

CPF8929

Device &1 could not be varied on.

CPF8931

Location &1 not an APPC location.

CPF8932

Device &1 must be non-networking APPC device.

CPF8933

Route to specified location not found.

CPF8935

Pass-through not allowed to system &1.

CPF8936

Pass-through failed for security reasons.

CPF8937

Automatic sign on not allowed.

CPF8938

Error in QRMTSIGN program. Pass-through failed.

CPF8939

Trying to send too much data.

CPF8940

Cannot automatically select virtual device.

CPF8941

Incorrect internal use of pass-through.

CPF8943

Pass-through not allowed from server TELNET session.

*STATUS Messages

CPI8901

No matching device on remote system. Function limited.

CPI8902

Pass-through started at system &1.

CPI8903

Virtual device &1 selected at system &2.

CPI8906

Automatic sign-on not allowed.

Top