File Transfer Using the ISPF C/S

                 

The purpose of this document is to help ISPF users set up the ISPF Client/Server (ISPFCS) component in order to enable file transfer between the MVS system and their work station.

           

Introduction

During the 1980s, MVS installations started to replace 3270-type terminals with work-stations (WS) such as IBM PCs. Using 3270 Emulator software and various protocols and servers, these WSs could appear to the host (MVS) as 3270 terminals. 3270 Emulators soon were given file transfer capabilities, using an IBM program called IND$FILE. Other software companies followed suit with enhanced versions of IND$FILE or other methods based on proprietary protocols. But IND$FILE remains, to this day, the most common way for a TSO user to transfer files between MVS and a work-station.

Since the early 1990s, as TCP/IP increases its presence in MVS installations, its file transfer protocol (FTP) has gained some acceptance, allowing files to be transferred to the work-station (or to other hosts) using the FTP command, both in TSO and in batch. The FTPB dialog, written by Lionel Dyck and available at no charge from the Share organization, provides ISPF users with a user-friendly interface to FTP.

With Version 4, ISPF gained a Client/Server Component (ISPFCS), whose most visible part was the GUI, convincing many people that ISPFCS=GUI. In contrast, the file transfer capability, also an integral part of the ISPFCS, received little publicity and few people really paid much attention to it.

Each of the three transfer methods (IND$FILE, FTP and ISPFCS) have their strong and weak points (see Pros and Cons, at the end of this document). Having used IND$FILE, then FTP, for a number of years, I find myself using ISPFCS now each time it is available simply because I find it more convenient than IND$FILE and FTP. Since setting up the ISPFCS can be complex, and there is no documentation that covers the various aspects of the procedure, I decided to put my experience on paper to help others implement, test and hopefully use the file transfer capability of the ISPFCS.

ISPF Client/Server Component

The ISPF Client/Server Component was introduced in ISPF V4. The ISPFCS consists of two parts:

  1. a server, called the Work-station Agent (WSA) which must be installed and activated on the Workstation (WS)
  2. a client, which is an integral part of (and runs inside) ISPF on MVS

The ISPFCS provides two types of services:

The ISPFCS can use TCP/IP or APPC to communicate between MVS and the work-station. As I don't know anything about APPC, I won't further mention it here.

As said earlier, the ISPFCS is an integral part of ISPF V4 and no additional software needs to be purchased (or installed) to activate its facilities. Some of the ISPFCS code, however, must be configured to enable file transfer, as further discussed in this document.

Can I establish a connection?

In order to establish a connection between ISPF and the WSA, the user must ensure that TCP/IP is available on the work-station and determine what the IP address is. This can be done by entering a command on the work-station such as NETSTAT, HOSTID, WINIPCFG, etc, depending on the OS used at the work-station. If TCP/IP is not installed or the IP address cannot be determined, help from a network or work-station administrator may be needed.

If TCP/IP is available and active on the work-station, the TSO PING command can be issued to determine if a route exists between MVS and the work-station, which is a prerequisite to establishing a session. The format of the PING command is PING 123.45.67.89 where 123.45.67.89 is the work-station's IP address. If PING is successful, then a valid connection has been established and the prospects for using the WSA are good. If PING fails, it's probably because:

  1. TCP/IP is not installed (or not active) on MVS, or
  2. there is no route between MVS and the work-station, or
  3. a firewall between MVS and the work-station blocks PING, or
  4. the job name of the MVS TCP/IP address-space is not "TCPIP"

There isn't much an ISPF user can do to correct the former three problems, but the latter is quite easy to fix. First of all, the correct job name of the TCP/IP address-space must be determined, for example by asking the MVS Network administrators. In their absence, here is a small REXX exec that displays the name(s) of the TCP/IP address-space(s) on an MVS system (TCP/IP 3.2 or above).

       cvt = C2D(STORAGE(10,4))
       ecvt = C2D(STORAGE(D2X(cvt+140),4))
       tsab = C2D(STORAGE(D2X(ecvt+176),4))
       DO i=1 to 8
         tseb=tsab + 64 + (i-1)*128
         SAY i STORAGE(D2X(tseb+16),8)
       END 

Once the correct job name is known, it must be communicated to the TCP/IP routines. There are several ways to do this; the simplest way is to create a one-line text file containing:

 TCPIPJOBNAME jobname 

where TCPIPJOBNAME is a key-word starting in pos 1 and jobname is the name of the TCP/IP address-space. This text file, which is a minimal TCPDATA file, is made available to the TSO session by allocating it under the name SYSTCPD:

 ALLOC DD(SYSTCPD) DS(dataset.name) SHR 

Once this is in place, the PING command should be re-issued.

Here is the result of a successful PING:

  PING 123.45.67.89
  EZA0458I Ping V3R2: Pinging host 123.45.67.89. Use ATTN to interrupt.
  EZA0463I PING: Ping #1 response took 0.012 seconds. Successes so far 1. 

Here are the messages obtained when trying to PING an invalid or inaccessible address:

  PING 99.99.99.99
  EZA0458I Ping V3R2: Pinging host 99.99.99.99. Use ATTN to interrupt.
  EZA0464I PING: Ping #1 timed out 

Here are the messages issued when TCP/IP is not active or the jobname is incorrect:

  PING 123.45.67.89
  EZA0455E BeginTcpIp failed: Fatal inter-address communications error (VMCF Rc=5 User=TCPIP) (8529) 

If TCP/IP is not installed on the system, unexpected results can occur, such as a S0C4 abend.

Install the WSA

The ISPF Work-station Agent (WSA) is a small server that must be installed on the work-station. PDF option 3.7 (enhanced in OS/390 2.5), helps with downloading and installing the WSA for the following environments:

  1. AIX
  2. HP/UX
  3. OS/2
  4. Solaris
  5. Windows 3.1
  6. Windows 32

See Appendix 1 in the ISPF User's Guide.

The SISPGUI PDS contains six binary files that correspond to the supported environments in the list above. Each binary file is an installation executable program, packaged in a self-extracting archive, with a size varying between 500KB and 1.5 MB. The proper SISPGUI member must be downloaded to the work-station using IND$FILE or FTP; the file should be renamed, as indicated on the PDF 3.7 Panel. For example, to install the WSA on Windows 95 or NT, ISPGUINX must be downloaded under a name that ends in .EXE, such as ISPFINST.EXE.

A directory should be created on the work-station and the installation program run in it, which creates a dozen or so files. Executing the program called WSA (or WSA.EXE) starts the WSA. It's a good idea to add the WSA to the work-station's start-up procedure.

Once the WSA is started, select the "options" choice to activate TCP/IP and, optionally, set the TCP/IP port number (the default port is 15993). It is sometimes necessary to exit and re-enter the WSA multiple times during this process.

Note for Windows users: the WinSock path parameter is sometimes a source of error. Check your system for duplicate WINSOCK.DLL programs and make sure the WSA has access to the right one.

SAS/C Transient Library

The ISPF main task must have access to the SAS/C transient library (SISPSASC) in order to establish a connection. If SISPSASC is not already part of the system libraries (link-list or LPA), it can be added in the LOGON proc's STEPLIB or activated from the READY prompt with a TSOLIB command; for example:

 TSOLIB ACT DS('ISP.SISPSASC') 

Notes:

First connection

Once the WSA agent is installed and running and the port number is set, it's time to set up ISPF and attempt a first connection. To set up ISPF, enter the Settings command (or option 0 on the main PDF menu) and select option 1 off of the Workstation pull-down menu. The panel titled "Initiate Workstation Connection" is displayed; enter the following values:

     Workstation connection        GUI Network Protocol
     2  1. With GUI display        1  1. TCP/IP
        2. Without GUI display        2. APPC

     GUI Window Frame              Default window background color
     1  1. Standard (STD)          1  1. Dialog (DLG)
        2. Fixed (FIX)                2. Standard (STD)
        3. Dialog (DLG)

     GUI Title
    (leave blank) 
     TCP/IP Address
      123.45.67.89:15993
     APPC Address
    (leave blank)  

Notes:

  1. Replace 123.45.67.89 with the work-station's IP address and 15993 with the port number you specified to the WSA.
  2. In ISPF 4.5 (OS/390 V2R5), the screen layout is somewhat different from what is shown above.
  3. This set-up is needed once only; ISPF saves the values entered in the user's profile data set from one session to the next.

Now's the moment of truth: press ENTER and two things can happen:

  1. the ISPF client succeeds in establishing a connection, in which case the WSA brings up a screen asking to confirm the connection, or
  2. ISPF fails to connect and displays error messages, which could be caused by:
    • missing or invalid parameters
    • inconsistency between the WSA options and the parameters on the "Initiate Workstation Connection" screen (RC=48)
    • SAS/C transient modules could not be found
    • the IP address is invalid or inaccesible (RC=49)
    • ISPF currently in split-screen mode, etc.

Once established, the connection stays active until the end of the ISPF session. To break the connection without exiting ISPF, stop the WSA. Each time the user starts ISPF, the connection must be established before services such as file transfer are available.

Testing the connection

Once established, the connection must be validated.

  1. The simplest way to test the connection is to select PDF option 1 or 2 and browse, view or edit a file on the work-station by entering its name as follows:
    	Workstation File:
    	    File Name . . . . . c:\config.sys 
  2. A second test consists in transferring a file between the host and the work-station using ISPF option 3.7.
  3. A third test consists in editing an MVS data set using a work-station editor, such as the system editor in OS/2 which is called "E". First, we must identify the work-station editor to ISPF by entering the Settings command, then selecting the Workstation Tool Integration choice from the Workstation pull-down menu. Here is an example:
    	Description  Code  Data    Mode      Command
    	View         V     TEXT    MODELESS  E
    	Edit         E     TEXT    MODAL     E 

    Once this is done, select PDF option 1 (View), enter the name of an MVS data set or PDS member, and select the "View on work-station" option. When you press Enter, ISPF transfers the data to the WSA, which then launches the work-station editor specified previously.

Automating the connection

Users who intend to use their work-station connection frequently should consider connecting automatically when entering ISPF. The PDF, ISPF and ISPSTART commands provide the GUI parameter for this purpose; for example:

 PDF GUI(IP:123.45.67.89:15993,NOGUIDSP) 

Note: Starting with OS/390 2.5, ISPF accepts the specification of each user's IP address in a text file allocated to DD(ISPDTPRF). See Chapter 7 (Settings) of the ISPF User's Guide for details.

When the work-station's IP address is dynamic, the user must retrieve it from the work-station and respecify it to ISPF before establishing a connection to the WSA. This inconvenient situation occurs, for example, when the network administrator uses DHCP to manage IP addresses, or when work-station users connect to MVS through a dial-up facility.

Under some circumstances, the process of retrieving a dynamic IP address and passing it to ISPF can be automated. A REXX exec called IPADDR can be invoked from from a LOGON CLIST to retrieve the IP address from the MVS Telnet server and return it into a variable. The value of the variable is then passed in the GUI option of the PDF command, as shown here:

	REXXTRY RETURN IPADDR()
	IF &lastcc=0 THEN +
	  PDF GUI(IP:&result:15993,NOGUIDSP)
	ELSE +
	  PDF 

REXXTRY executes a REXX exec called IPADDR which retrieves the IP address after the work-station has established a direct connection to the Telnet server on the same MVS system as the TSO session. In other situations, IPADDR fails to retrieve the IP address and the process of connecting ISPF to the WSA can not be automated. In any case, IPADDR requires the TSO user to be properly authorised to issue the NETSTAT command. REXXTRY and IPADDR are free GSF Utilities.

The IPADDR2 program was written in 2004 to work around the limitations of the IPADDR exec on OS/390 R10 and z/OS systems. When executed as an authorised program or TSO command, IPADDR2 returns the IP address and Host name of the TSO Terminal, even if the TSO session was established on a TN3270 server running on a different MVS system. Example of an invocation of IPADDR2 as a program:

	CALL 'SYS1.AUTHLIB(IPADDR2)'
	IF &lastcc=0 THEN +
	  PDF GUI(IP:&ipaddr:15993,NOGUIDSP)
	ELSE +
	  PDF  

Security Considerations

In many respects, the WSA is similar to an FTP server. Once the WSA is up and running on the work-station, any ISPF user (and other non-ISPF malicious hackers also) can attempt to connect to the WSA using the work-station's IP address. To prevent unauthorized access to the work-station (maliciously or accidentally), the WSA prompts the work-station user each time a client tries to establish a connection. If the work-station user replies NO, the connection attempt fails. If the work-station user replies YES, whoever established the connection can read or update work-station files remotely.

Recent levels of the WSA (but not older ones) display the IP address and TSO User-ID of the client as a means to identify the source of the connection. If your WSA does not display the client's address and TSO User-ID, consider getting the latest WSA code for your work-station. For all practical purposes, a user should deny all requests for connection he/she did not directly request.

With recent levels of the WSA (but not older ones), replying to the confirmation screen can be automated for specified IP addresses and TSO user-IDs. On the WSA, click on Options then System Register and define the MVS system, IP address and TSO user-ID that you (or other people you trust) normally use.

It should be noted that the WSA supports more than one connection at a time. It can be perfectly normal for a user to have several TSO sessions active at a given moment, on the same or different MVS system, in which case, each ISPF client can open its own connection with the WSA.

ISPF Services

ISPF provides three services to communicate with the WSA:

The FILEXFER and FILESTAT ISPF services can be invoked in a dialog written, for example, as a CLIST. Here is a simple CLIST to transfer a PC file to MVS and display it with Browse.

	SET file = C:\CONFIG.SYS
	SET dsn  = '&SYSUID..ISPFCS.TEXT'
	ISPEXEC FILESTAT FILE(file) LRECL(maxrec)
	SET lrecl = &maxrec+4
	ALLOCATE DS(&dsn) NEW CATALOG RECFM(V B) LRECL(&lrecl)
	ISPEXEC FILEXFER HOST(dsn) WS(file) TO(HOST) TEXT
	ISPEXEC BROWSE DATASET(&dsn)
	FREE DS(&dsn) DELETE 

The following sample REXX code runs in batch ISPF to transfer a work-station file to the MVS host. Note that the WSCON service was added to ISPF 4.8 with OS/390 R8.

 IPADDR = '9.16.136.24'
 OUTFILE = 'OUTFILE'
 WSFN = 'D:\TEMP\PROG126.ASM'
           /* WSCON - CONNECT TO THE WSA */
 "ISPEXEC WSCON IP(IPADDR) CODEPAGE(0037) CHARSET(0697) NOGUIDSP"
 IF RC>0 THEN . . .
           /* FILEXFER - Transfer WS file to the Host */
 "ALLOCATE DS("OUTFILE") NEW CATAL RECF(V B) LRECL(255)"
 IF RC>0 THEN . . .
 "ISPEXEC FILEXFER WS(WSFN) HOST(OUTFILE) TO(HOST)"
 IF RC>0 THEN . . . 

GSF Utilities

Some of the utilities distributed in file 183 of the CBT tape have been enhanced to support the ISPF CS and new ones have been written.

Note: FASTPATH, ROUTE, IPADDR and REXXTRY are available in the Freeware section of this Web site and in file 183 of the CBT tape. To obtain a copy of the XFER exec, please contact the author.

WSA for Linux

There is currently no version of the Work-Station Agent (WSA) for the Linux environment. The requirement for a Linux WSA, at least for the I86 environment, has been brought forth to the ISPF developers who understand the need for a Linux WSA, but seem to await a larger pool of Linux users to deliver it. If you would like IBM to port the WSA to Linux, please post a message to that effect on the ISPF-L list or the bit.listserv.ispf-l news group.

In recent years, the author of this document (who uses Linux on his desktop and laptop PCs) has tried several alternatives:

Running the WSA under Wine is the best alternative, in spite of two significant limitations: (1) text files transferred to the host using FILEXREF are corrupted, due to some confusion between LF and CRLF, and (2) the SELECT WSCMD service does not seem to work at all. Transfer of text files from the host, and of binary files in both directions, work fine.

Pros and Cons

   IND$FILE
    + ubiquitous
    - cumbersome (READY prompt)
    - slow transfer, slow setup
    - synchronous (locks 3270 session)
    - somewhat emulator-dependent
    - difficult to automate
   FTP
    + fast xfer, slow authentication
    + can connect MVS to MVS directly
    + asynchronous (can run in batch)
    - automation requires FTP server on work-station
    - not always available
   ISPFCS
    + faster transfer than IND$FILE
    + easy to automate
    - synchronous (locks 3270 session)
    - not always available 

Bibliography