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
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 (
The ISPF Client/Server Component was introduced in ISPF V4. The ISPFCS consists of two parts:
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.
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:
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.
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:
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
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.
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:
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:
Now's the moment of truth: press ENTER and two things can happen:
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.
Once established, the connection must be validated.
Workstation File: File Name . . . . . c:\config.sys
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.
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
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 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 . . .
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.
ed c:\config.sys
on the ISPF command line to edit the corresponding file on the work-station. This capability, associated to the CUT and PASTE commands, provides a simple way to transfer text data to the work-station, for example from the SDSF spool to the work-station.
ROUTE c:\ccc.text
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.
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.
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