Display Station Pass-through (DSPT) is a system-provided Advanced Program-to- Program Communications (APPC) function that you will need to work with in your AS/400 network. Simply configuring your AS/400s into an Advanced Peer-to-Peer Networking (APPN) network provides the machine-to-machine connectivity DSPT requires. However, you'll have to do several things before using DSPT. I'll describe the features of DSPT that you'll encounter by leading you through the steps needed to configure your systems for DSPT, sign-on to another system, work between systems, and finally end your pass-through sessions.

I assume that you have two or more AS/400s configured in an APPN network. Although you can use DSPT to sign-on to the S/36 and S/38, I will not be covering those options or explaining how to use DSPT with APPC connection devices. If you need to use those options, I suggest that you first learn about DSPT between AS/400s, then work with the other systems and connection options.

Services Provided by DSPT

DSPT is simply a means of letting you establish an interactive job on another system (the target system) from your workstation. Your workstation can be directly connected or remotely connected to the home, or source system (the terms are synonymous to a point, then take on additional meaning that I will explain later). The home system is the system that you initially sign-on to.

From the home system you can pass-through, or start an interactive job, on another AS/400 that has active and available APPC sessions with the home AS/400. If you have many AS/400s in an APPN network, you can pass-through from the home system to another system anywhere in the network. You can also establish pass-through sessions to more than one AS/400 at a time, depending upon the number of jobs or sessions that are available to your workstation.

Until V3R1, there was no printer pass-through. If you created spool files on the target system, you had to use the SNADS Send Network Spool File (SNDNETSPLF) command to transmit those files back to the source system. The situation is somewhat ameliorated with V3R1. It provides a remote writer construct that uses output queue configuration options and the new Start Remote Writer (STRRMTWTR) command. This construct is based on a SNADS configuration between the source and target machines, so you still need to provide that configuration. STRRMTWTR helps automate sending spool files back to your source system. (Printer pass-through will be covered in a future article.)

Getting Started

Before you start using DSPT, you need to check several things. Most of your concerns and problems will be on the target system, since that is where you are starting the new job. Although this may be controversial, I suggest that you initially relax some of the security-related items that affect pass-through. The purpose is to allow you to easily pass-through to target systems by having those systems perform automatic configuration. Once you establish a pass- through session, you can immediately set security to the required level. The alternative is to have a knowledgeable person at the target site who can change system and configuration values.

The steps that you will take to get DSPT working are as follows:

o Verify that your APPN network is working and that you can establish a connection to the target machine.

o Decide if you want to use automatic creation of virtual controllers and virtual devices on the target machine.

o Decide if you want to use automatic or manual sign-on procedures at the target machine.

o Configure the target machine for DSPT.

o Pass-through from your source machine to the target. Verify that DSPT is working as required.

o Create any required programs you need to control DSPT including the QRMTSIGN program.

Quick Start

If you already have an APPC connection available to another system or if you have several systems in an APPN network, you can quickly start using pass- through. You'll have to do only four things:

1. Get the local location name of the system that you'll be passing-through to. Use the Display Network Attributes (DSPNETA) command on the remote system. The value you want is identified as the default local location.

2. Also on the remote system, check that system value QAUTOVRT is set to a value other than zero. Use the Work with System Value (WRKSYSVAL) command to verify and change this system value.

3. Check that your communications configuration is active to the system that you want to pass-through to.

4. Use the Start Pass-Through (STRPASTHR) command to start pass-through to the remote system. The only parameter you'll need is the remote location name (RMTLOCNAME). Enter the location name from step 1.

Assuming that the remote system accepts your pass-through request, you will be connected to the remote system for an interactive session. The remote system will either create a virtual controller and device for you or assign you to an existing device.

To help you understand more about the factors that affect pass-through, we'll now take a detailed look at settings and options.

System Values Affecting DSPT

There are five system values that you have to consider when using DSPT. The values are listed in 1. All are set on the target system.

There are five system values that you have to consider when using DSPT. The values are listed in Figure 1. All are set on the target system.

QAUTOVRT is probably the most important when getting started with DSPT. This value indicates how many virtual devices you will let the target system automatically create. The shipped value is zero, meaning that you have to manually create virtual controllers and devices on the target system. You can set this value as high as 9999.

To get started, you may want to set the value to 10. That lets you use automatic configuration to get started; after you have the connection working, you can set the value back to zero depending on your security requirements. (I suggest starting at 10 rather than at one. That way, if the one virtual device that is automatically created becomes disabled and you can't pass-through, the target system will create another virtual device for you. You can then pass- through to the target system and correct the problem.)

The other value that you should check is QRMTSIGN. QRMTSIGN controls what happens when a session is requested at the target system. Your initial setting should be *FRCSIGNON, to force the sign-on display. You can change the value later to allow automated sign-on.

The other system values-QLMTSECOFR, QMAXSIGN, and QMAXSGNACN-affect more than just DSPT. I include them because they are system values that you need to consider when designing security for networked systems. (For more information about these system values, see "V3R1 Security Enhancements" MC, January 1995.) Virtual Controllers and Devices

Unfortunately, I can't discuss DSPT without using the V word. I feel that virtual has lost its ability to convey meaning in computer contexts due to overuse. Although I will use the AS/400 virtual controller and virtual device terminology, I find it more meaningful to think of those objects as pass- through controllers and pass-through devices.

Virtual controllers and devices exist on the target machine. Their purpose is to mimic the functions provided by physical controller and device descriptions used on your source machine. For example, when editing a source member, SEU display file I/O is directed to a particular physical device on a controller. If you start DSPT to edit source on a remote machine, SEU still directs its I/O to a display file. However, because the request is from another machine, there is no physical controller and device on the target machine to direct I/O to. To accommodate that, the virtual controller and device are used.

Virtual objects are hybrids between actual physical devices and pure APPC communications devices. The virtual device has characteristics of an underlying display device and indicates its capabilities (such as color, graphics, and 132-column support). The virtual device also is designed for communications; it takes the 5250 data stream that is output from a program and sends it to the source system. On the source system, the pass-through program is responsible for converting the remote data stream to a form that can be used at your physical workstation.

How Automatic Creation Works

To let the target system automatically create virtual controllers and devices, you need to set QAUTOVRT to something other than zero. Once that is done, the target system can create virtual objects as required, up to the limit of the number of virtual devices.

2 shows how the target system uses the QAUTOVRT value to determine whether or not to create more controllers and devices. When creating virtual controllers, the system starts with controller QPACTL01 (pass-through controller 01). Virtual devices are added to that controller (starting with pass-through device QPADEV0001), up to the limit of 250 virtual devices per automatically created controller. Upon hitting the 250 device limit, the system creates a new controller (QPACTL02) and begins adding devices to that.

Figure 2 shows how the target system uses the QAUTOVRT value to determine whether or not to create more controllers and devices. When creating virtual controllers, the system starts with controller QPACTL01 (pass-through controller 01). Virtual devices are added to that controller (starting with pass-through device QPADEV0001), up to the limit of 250 virtual devices per automatically created controller. Upon hitting the 250 device limit, the system creates a new controller (QPACTL02) and begins adding devices to that.

The value of using automatic configuration is obvious: the system does the work for you. The disadvantage is that the controllers and devices do not indicate any particular grouping based on their names. You may want to create your own configuration objects for that purpose.

PC Support (Client Access) also creates virtual controllers and devices. The QAUTOVRT value does not control how many virtual devices PC Support can create. Manually Creating Virtual Objects

You may want to manually create virtual controllers and devices. You can assign your own names and group devices with controllers of your choosing. For example, you may want to create a controller and devices for programmers who will be passing-through to the system and another group for accounting personnel who need access. Manually creating objects implies that you will be selecting a specific virtual controller or group of virtual devices when you start pass-through. Specific selection has its own advantages and disadvantages, which I will review shortly.

3 shows the CL commands that you use on the target system. These are rather simple commands, compared to many other communications configuration commands. The most important parameter values are TYPE and MODEL on the Create Device Display (CRTDEVDSP) command. You want to set TYPE and MODEL to correspond to the physical workstation that you use on your source system. For example, if you are starting pass-through on a color terminal that supports 132-column display, you will want to pass-through to a virtual device that supports those features. If you pass-through to the 5251 device shown in the command, you will lose much of the enhanced functionality of your physical workstation.

Figure 3 shows the CL commands that you use on the target system. These are rather simple commands, compared to many other communications configuration commands. The most important parameter values are TYPE and MODEL on the Create Device Display (CRTDEVDSP) command. You want to set TYPE and MODEL to correspond to the physical workstation that you use on your source system. For example, if you are starting pass-through on a color terminal that supports 132-column display, you will want to pass-through to a virtual device that supports those features. If you pass-through to the 5251 device shown in the command, you will lose much of the enhanced functionality of your physical workstation.

Once you have set up your target system for automatic configuration or have manually created objects required for pass-through, you are ready to start pass-through.

The STRPASTHR Command

You start pass-through from your system to another with the Start Pass-Through (STRPASTHR) command. The parameters you'll use depend on your APPN configuration, virtual object configuration, and sign-on requirements. 4 shows an example of the STRPASTHR command prompt. 5 lists the STRPASTHR parameters in logical groups.

You start pass-through from your system to another with the Start Pass-Through (STRPASTHR) command. The parameters you'll use depend on your APPN configuration, virtual object configuration, and sign-on requirements. Figure 4 shows an example of the STRPASTHR command prompt. Figure 5 lists the STRPASTHR parameters in logical groups.

The remote system identification group is used to identify the target system. In your APPN network, you will usually only need to specify the target system name in the RMTLOCNAME parameter. In fact, assuming an APPN network, RMTLOCNAME is the only required parameter on the STRPASTHR command. There are a number of ways that you can determine the target system's name; the simplest way is to use the Display Network Attributes (DSPNETA) command and record the default local location name (LCLLOCNAME).

If you are starting pass-through to a system in another APPN network, you need to specify the other network ID in RMTNETID. Use CNNDEV if you need to connect to a system that is not APPN capable; for example, when you need to establish pass-through to a S/38.

The virtual object parameters (VRTCTL and VRTDEV) are used to select a specific virtual controller or device on the target system. If you used automatic configuration for all of the virtual objects, you would not want to select specific objects. When you start pass-through, the target system will select the next available virtual device if you do not specify VRTCTL and VRTDEV. You can specify either a controller or a list of up to 32 virtual devices. You can use these parameters to select manually created virtual objects. When you enter a controller or device, you are limiting pass-through to establishing a session on the controller or one of the devices. If the controller does not have an available device or if there is not an available device in the list of devices, the pass-through session will not start.

The MODE and LCLLOCNAME parameters control the APPC/APPN session that you use to access the target system. If you have multiple routes to the target, you can control APPN route selection. The mode has an associated class-of-service which APPN uses to calculate the route.

Remote user options are used to request automatic sign-on and to specify what initial program or menu is used. RMTUSER and RMTPWD are used together to identify you to the target system. The target system examines those values when using automatic sign-on. The additional parameters (RMTINLPGM, RMTINLMNU, and RMTCURLIB) let you specify the program or menu to be presented at sign-on, rather than the default sign-on program.

If you are embedding the STRPASTHR command within an application, you can supply remote user options as a convenience for your users. By specifying valid options, the pass-through session can be established without the user having to sign-on at the target system. Obviously, there are security implications on the source system, as you do have to supply a password to get remote sign-on to work.

The last two STRPASTHR parameters, SRQ10PGM and PASTHRSCN, let you control the system request display and the displays presented when pass-through is started. The system request program is important with pass-through, as it contains options that let you go from the target system to the source or home system. Rather than use the default system request menu, you can create your own program that is called when system request is used.

The PASTHRSCN (pass-through screen) parameter is used to suppress the pass- through start up display and messages sent during session establishment ("Pass- through selected device..."). If you are creating an automatic pass-through program for your users, you may want to use PASTHRSCN. By suppressing the display and message, you can make it less obvious that pass-through is being used.

How the Target System Controls Sign-on

When you configure a system to use pass-through, you are opening it up to other systems. The target system differentiates between its local users and pass- through users at session start. You control how the target system handles pass- through session start requests with the QRMTSIGN system value.

6 shows the values that you can specify for QRMTSIGN. The target system action is based on whether or not automatic remote sign-on is requested. For values other than *REJECT and the program option, the target system always displays the system sign-on panel if automatic sign-on is not used (RMTUSER and RMTPWD are not supplied on STRPASTHR).

Figure 6 shows the values that you can specify for QRMTSIGN. The target system action is based on whether or not automatic remote sign-on is requested. For values other than *REJECT and the program option, the target system always displays the system sign-on panel if automatic sign-on is not used (RMTUSER and RMTPWD are not supplied on STRPASTHR).

*FRCSIGNON displays the sign-on panel, regardless of the automatic sign-on request. *SAMEPRF means that the user profile specified in RMTUSER must be the same as the user profile that started the source system session and that a corresponding user profile must exist on the target system. You use *SAMEPRF to force the usage of the same user profile for the source and target systems. *VERIFY simply checks for a valid automatic remote sign-on request. If valid RMTUSER and RMTPWD values are supplied, *VERIFY allows the target session to start, even if it is for a different user profile than is used at the source system.

The QRMTSIGN Program

If you need more control than the QRMTSIGN values provide, you can create a program that determines whether or not the pass-through session should be started. The program is called when pass-through session start is requested. If a pass-through session is started, the program is also called when the session ends. You can use that feature of the program to log pass-through session activity.

Two parameters are passed to the program. Those parameters are documented in the Remote Work Station Support manual, along with an example program. The first parameter contains subfields that identify the source and target systems, the user profile and password if provided, and other information that the program can use to determine if it should start the session. The second parameter is a return code that is set in the program. Based on the value of the return code, the pass-through session is either started or rejected.

You can use the QRMTSIGN program to control when users are allowed to establish pass-through sessions. For example, you may want to limit most users so that they can use pass-through only during working hours. You can also use a QRMTSIGN program to control the initial program, regardless of what was specified on the STRPASTHR command.

Moving Among Systems

It's not uncommon to start pass-through and then have to go back to the source system. Because of the relatively high cost (resource intensive activities) of establishing a pass-through session, it is advantageous to keep the pass- through session established, rather than end it to go back to the source system temporarily. The system request menu and Transfer Pass-Through (TFRPASTHR) command are used to go from the target system to the source or home system.

At this point, I need to distinguish between source and home. If you are simply using pass-through between two machines, then source and home refer to the same machine, the one where the STRPASTHR command is used. If you start pass-through to a target system, and then start pass-through from that system to another system, the machine used for the first STRPASTHR is the home system. The middle machine is the source system to the second target system.

You need to understand this terminology to use the TFRPASTHR command. 7 shows values that can be used in the TOJOB parameter on that command.

You need to understand this terminology to use the TFRPASTHR command. Figure 7 shows values that can be used in the TOJOB parameter on that command.

When you use TFRPASTHR, you have the option of requesting the system request menu or transferring to an alternate job. If you transfer to an alternate job, you are first shown the sign-on display. This is the same as starting a secondary job on the source or home system (the same as the TFRSECJOB command). Once you have signed on and started a program, future TFRPASTHR requests to an alternate job from the target system take you directly into that program. As shown in the figure, the parameter values have equivalent menu options on the default system request menu. If you want to create your own system request menu, you can use these equivalencies as a guide for menu options that you might want to provide.

Ending Pass-through

There are two commands you can use to end a session on the target system. You can use either the End Pass-through (ENDPASTHR) or SIGNOFF command to end the session and return to the source system.

ENDPASTHR has only one parameter, which controls whether or not a job log is produced for the session on the target system. When you use ENDPASTHR, you are returned to the source system. You need to use STRPASTHR again to return to a session on the target system.

It used to be that you couldn't use the SIGNOFF command to end pass-through. Since V2R3, SIGNOFF includes the ENDCNN (end connection) parameter that you can use to sign-off and end pass-through. If you use SIGNOFF in a target session without ENDCNN, and if automatic sign-on was not used to establish the session, you simply sign-off the target system. You are presented with the sign-on display at the target system. Using ENDCNN(*YES) is the same as using ENDPASTHR.

The SIGNOFF command also includes the DROP parameter, to drop switched line connections. However, DROP is not used with pass-through; it is used only for remote workstations.

Pass Out

Despite all of the factors presented here, pass-through is simple to configure and use once your AS/400 network is established. All of the configuration work is done on the target system. Security concerns are also the responsibility of the target system. On the source system, you may choose to automate the start pass-through process with the remote user ID and password.

In a future article, I'll describe how to configure and use the new V3R1 remote printer pass-through function.

Craig Pelkie can be contacted through Midrange Computing.

Reference Remote Work Station Support (SC41-3402, CD-ROM QBKANC00).

Understanding Display Station Pass-through

Figure 1 System Values that Affect Pass-through

 QAUTOVRT maximum number of virtual devices that can be automatically crea QRMTSIGN remote sign-on action QLMTSECOFR limit security officer access to specifically authorized devices QMAXSIGN maximum number of sign-on attempts allowed QMAXSGNACN action taken when maximum sign-on attempts is exceeded for a use profile or device 
 
 Understanding Display Station Pass-through
 
 Figure 2 Algorithm for Automatic Virtual Controller/Device
 
 UNABLE TO REPRODUCE GRAPHICS 
 
 Understanding Display Station Pass-through
 
 Figure 3 CL Commands Used to Manually Create Virtual Contro
 
 Create a virtual controller: CRTCTLVWS CTLD(VRTCTL01) + TEXT('Manually created virtual controller 01') Create a virtual device: CRTDEVDSP DEVD(VRTDSP01) DEVCLS(*VRT) + TYPE(5251) MODEL(0011) ONLINE(*YES) + CTL(VRTCTL01) TEXT('Manually created virtual device 01') 
 
 Understanding Display Station Pass-through
 
 Figure 4 STRPASTHR Command Prompt
 
 UNABLE TO REPRODUCE GRAPHICS 
 
 Understanding Display Station Pass-through
 
 Figure 5 Parameter Groups on STRPASTHR Command
 
 Remote System Identification RMTLOCNAME-Remote location name RMTNETID-Remote APPN network ID CNNDEV-APPC connection device list Virtual Objects on Target System VRTCTL-Virtual Controller to use VRTDEV-Virtual Device selection list APPC/APPN Control MODE-APPC mode to use LCLLOCNAME-Local system name requesting STRPASTHR Remote User Options RMTUSER-Remote user profile RMTPWD-Remote user profile password RMTINLPGM-Remote initial program RMTINLMNU-Remote initial menu RMTCURLIB-Remote current library Miscellaneous Options SRQ10PGM-System Request Option 10 program PASTHRSCN-Show/suppress pass-through display and messages 
 
 Understanding Display Station Pass-through
 
 Figure 6 Effect of System Value QRMTSIGN on Pass-through
 
 Value RMTUSER/RMTPWD Target System Action *FRCSIGNON Supplied Automatic sign-on not allowed; system sign-on display presented. Not Supplied System sign-on display presented. *REJECT N/A All pass-through attempts rejected. (CPF8935) *SAMEPRF Supplied If RMTUSER is different from source system USRPRF, pass-through fails at source system (CPF8936). If same RMTUSER and valid RMTPWD, automatic sign-on. If same RMTUSER and invalid RMTPWD, fails at source system (CPF8936). Not Supplied System sign-on display presented. Can sign-on using any valid target system user profile/password. *VERIFY Supplied If valid RMTUSER/RMTPWD, automatic sign-on. If invalid RMTUSER/RMTPWD, fails at source system (CPF8936). Not Supplied System sign-on display presented. lib/pgm N/A Program dependent. 
 
 Understanding Display Station Pass-through
 
 Figure 7 TOJOB Parameter Values for TFRPASTHR Command
 
 Value: *SRC Action: Start system request at source system. How done: Transfers back to the source system, gives control to SRQ10PGM program. Equivalent: System Request Menu option 10. Value: *ALT Action: Transfer to alternate job on source system. How done: Transfers back to source system. If alternate job is active, transfers to that job. Otherwise, shows sign-on display at source system. Equivalent: System Request Menu option 11. Value: *HOME Action: Start system request at home system. How done: Transfers back to home system, gives control to SRQ10PGM program. Equivalent: System Request Menu option 13. Value: *HOMEALT Action: Transfer to alternate job on home system. How done: Transfers back to home system. If alternate job is active, transfers to that job. Otherwise, shows sign-on display at home system. Equivalent: System Request Menu option 14.