Performing File Transfers using the ISPF Work Station Agent
by Dave Salt

Introduction

If you've ever had to transfer files between a host mainframe and a PC workstation, you already know it can be time consuming and tedious. This is especially true if you need to transfer multiple members of a Partitioned Data Set (PDS). Don't you wish there was an easy way to simply select the members to be transferred directly from a member list? If so, good news!

One of ISPF's "best kept secrets" is the Work Station Agent, or WSA for short. It's an executable file that's downloaded from the mainframe and installed on a PC. Once the WSA has been installed, a "connection" between the mainframe and PC allows any of the following to occur:

• ISPF can be executed in "GUI" mode
• Workstation files can be edited on the mainframe (or vice versa)
• Files can easily be transferred between the mainframe and PC

As each of these is a topic in itself, this article will focus on the third point: Using WSA to perform file transfers.

Two points need to be noted before proceeding.

• The WSA has been stabilized by IBM. This means that it will receive no further upgrades or enhancements.
• The remainder of this articles assumes that a site is at least at a release level of OS/390 V2R8.

Installing the Work Station Agent

Installation of the Work Station Agent is a one-time process completed as follows:

1. On the mainframe, select ISPF option 3.7.1 (Utilities, Transfer, ISPF C/S).
2. Select the download method and workstation type. For the purpose of this exercise we'll select option "3" for Manual Download and "1" for Windows.
3. After pressing ENTER, a panel shows which member to download, the data set to download it from, and what to call it when it gets to the PC. For example, it might show to download something like 'ISP.SISPGUI(ISPGUINX)' to a file called ispfinst.exe.
4. Using the values shown on the panel and your regular file transfer procedures, download the specified member in binary format to a directory on the PC. For example, transfer 'ISP.SISPGUI(ISPGUINX)' to C:\ISPF\ISPFINST.EXE.
5. Once the file has been downloaded, execute it. This creates a file called WSA.EXE in whichever directory you specify, and creates an icon to launch it. Tip: Copy the generated icon next to the icon you use to launch your 3270 emulator session.

Establishing a Workstation Connection

After performing a one-time installation of the Work Station Agent, there are various ways to establish a workstation connection. For example:

1. If you don't already know the IP address of your PC, enter IPCONFIG at a DOS prompt or go to the http://www.ipchicken.com website. If these give you different IP addresses, refer to the "troubleshooting" section below for more information.
2. Launch the 3270-host session (if not already active) and launch WSA.EXE (if not already active). Note that these can be launched in any order.
3. On any ISPF command line type WSCON (Work Station CONnect).
4. On the "Initiate Workstation Connection" panel, enter the Workstation Connection field as "2" (Without GUI Display), enter the "GUI Network Protocol" field as "1" (TCP/IP), and just below the words "TCP/IP Address" enter the IP address of your PC.
5. After pressing ENTER, a window with "Connection" in the title should open on your desktop. If you don't see the window open, look for it behind one of the other active windows, or you may see an icon flashing on the tool bar. Once you find it click "Yes" to "Accept connection". If you don't see the window, refer to the "troubleshooting" section.
6. After accepting the connection you'll see a short message in the top right corner of the ISPF session that says "Connected".
7. When you no longer need the workstation connection, type WSDISCON on any ISPF command line or simply exit the ISPF session.

Performing File Transfer

Once a Workstation Connection has been established, performing file transfers is very simple. The following steps explain how to transfer multiple members of a PDS from the mainframe to the PC:

1. On the mainframe, select ISPF option 3.7.2 (Utilities, Transfer, Data Set)
2. Enter the name of the PDS to transfer members from, and in the field called "Workstation File" enter the full path of the directory you wish to transfer to. For example, enter C:\MYFILES\*.TXT. Note that a wildcard (i.e. an asterisk) can be entered in place of the file name, and the file transfer facility will automatically substitute this with the names of the member(s) selected for download.
3. Enter the "Transfer Option" as "1" (Download to Workstation) and put a forward slash in any "Options" you wish to select. For example, if you are downloading readable text files then select the "Transfer in Text Mode" option.
4. Press ENTER to display the member list, and use line command "S" to select any member(s) you wish to transfer. You can also enter "S pattern" on the member list command line to select all members matching a specified pattern; e.g. enter S ABC* to download all members beginning with ABC.
5. The word "*XFER" appears in the Prompt field next to each selected member to confirm the member was successfully transferred. That's all there is to it!

Troubleshooting

If the WSCON command fails to establish a connection, then the first thing to check is that the Work Station Agent (wsa.exe) is running on the PC. If it is, and if you still don't see a "Connection" window prompting you to accept an incoming connection (and the mainframe session simply seems to "hang" for several minutes), then the most likely cause of the problem is either an incorrect IP address was specified and/or the PC is behind some sort of firewall.

From personal experience it's usually easier to establish a Workstation Connection to a PC while at work than it is to establish one while working from a PC at home. So, if you're having difficulties establishing a connection at home, try it from work. That way, you'll know what to expect when you try it from home, and if you have any difficulty at work you might be able to get support from your help desk.

If you try the process at home and you can't establish a workstation connection, here are some tips that might help you resolve the problem:

• Determining which IP address to use

  Depending on your particular configuration you might have several IP addresses to choose from. If you connect to a mainframe through a VPN (Virtual Private Network) then the IP address to use is the one supplied by the VPN. In addition, if the VPN has a check box or setting that's labeled something like "Enable WINS/DNS via VPN Gateway", you should ensure this setting is enabled.

  If you don't use a VPN and you don't have a router (i.e. you just have one computer at home that's directly connected to the internet through a modem) you can use the IP address supplied by the IPCONFIG command, or the address supplied by the www.ipchicken.com website, as both of these addresses should be the same.

  If you have a router at home (i.e. you have two or more PC's on a home network) then you must use the public IP address supplied by www.ipchicken.com and not the private IP address assigned by your router and displayed by IPCONFIG.

• Firewall

  When you tell ISPF the IP address you wish to connect to, the mainframe sends a message to that address. The Work Station Agent (wsa.exe) that's running at that address looks for the incoming message and responds to it.

  If the PC is behind a firewall, the incoming message from the mainframe may be seen as "unsolicited" and therefore blocked. Most firewalls are configurable so that incoming messages from a particular IP address (which should be displayed in the firewall log) can be allowed to pass thru. Explaining all the different types of firewalls is beyond the scope of this article, so if in doubt, shut down any firewalls you may have to see if this allows the connection to go through.

  If you have several PC's at home, you might need to configure your router so that incoming messages are passed to the particular PC you're working on. You might also need to enable the routers "DMZ" (DeMilitariZed) setting. Please refer to the software settings of your router for further information.

If you perform any amount of file transfers between the mainframe and PC, the few minutes it takes to perform the one-time set up of the WSA is well worth the effort. From then on, performing file transfers is as simple as selecting members from a list!

Dave Salt is the president of Soft-Center Solutions Inc (www.soft-center.com). He has many years of TSO/ISPF development to his credit and has written many ISPF productivity aids in his career.

•
•
•
•
•
•

•