SYSTEM BY ROBERT SIMPSON STRATEGIES ISPF Client/Server - Part I: Download and Startup

his article begins a four-part series on the client/server feature of ISPF Version 4. Normally, ISPF panel display functions are han- dled by ISPF code running on the mainframe. The panels are T transmitted in a 3270 data stream to a terminal or to a PC running a terminal emulation program. In client/server mode, the panel display func- tions are handled by a program that is shipped with ISPF, but which runs on a The client/server feature PC under OS/2 or Windows. The data is transmitted to this client program using of ISPF Version 4 offers APPC or TCP/IP communication protocols. the same features as previous versions, but Note: Testing for preparation of this article pushbuttons which allow the correspond- adds new functionality was performed on a host system running MVS, ing commands to be executed with a single TSO, and ISPF Version 4.1. The clients for mouse click. through Graphical User testing were PCs running OS/2 Version 2.1, OS/2 Warp Version 3, and Windows 3.1. This ■ You can cut and paste between input Interfaces. article is not intended as a tutorial on either fields using Shift-Delete and Shift-Insert TCP/IP or APPC, so a working communica- (but since multiple line input areas are tions connection is assumed. displayed with one input field for each The most noticeable difference between line, this works for single lines only). the Graphical User Interface (GUI) and the traditional terminal emulation interface is ■ In split–screen mode, each screen appears with the “look and feel” of the ISPF panels. as a separate window containing a full 24 Standard panels appear as windows with a x 80 (or larger) display area. white background containing colored text and various GUI controls, including input ■ You can switch between ISPF windows fields, push buttons, and check boxes. Dialogs using the mouse or Ctrl-Esc, even when and messages are displayed in separate windows there is no PF key assigned to the SWAP of various sizes. This has both advantages command. However, this is not the same and disadvantages: as doing the SWAP command; for exam- ple, SWAP will clear the command line of Advantages: the window being displayed, switching to the window with the mouse will not. ■ The GUI interface. ■ ISPF Version 4.2 will allow up to 32 – The mouse can be used to position separate ISPF windows. the cursor to input fields and other GUI controls. ■ The window dimensions can be specified, allowing window sizes larger than model 4 – Check boxes can be selected (44 x 80) or model 5 (28 x 132) terminal and deselected using the mouse. screens. For example, you can specify a window size which takes up the entire – The action bar works as a PC screen area without having scroll bars, pull-down menu. or you can specify a full 134–column width and do horizontal scrolling on the – PF key descriptions in the function key PC rather than with ISPF LEFT and area and “point-and-shoot” fields appear as RIGHT commands.

TECHNICAL SUPPORT APRIL 1996 Disadvantages: see this by comparing how the Insert ■ When you exit ISPF, the client window key operates in a Windows Properties ma y not close as exp e c t e d . If the window ■ There are no keyboard equivalents to the dialog box and on an OS/2 Settings remains with a clo c k curso r , swi t c h to the new line key (Return is used as the Enter notebook page. This makes it somewhat emu l at o r wi n d o w and page through any key) and a few other 3270 functions such more difficult to use the Windows remaining TSO messages or output by as Erase Input. interface than the OS/2 or traditional pressing Enter at the “***” prompt until terminal interface (imagine having the TSO READY prompt is displayed and ■ The up and down cursor keys can move to use a terminal with insert mode the window is closed. only between adjacent input fields. This always on). makes it easy to move the cursor to the Another difference is that the client ■ Having it simply beep and display the last job in SDSF held output queue by program displays only ISPF output; TSO message in a background emulator win holding down the down arrow key, but output still appears in the terminal emula- dow rather than overlaying the screen can be annoying at other times. tor window. When running in terminal with the NOTIFY message when a job mode, TSO output is displayed automati- completes is nice, but it takes a few more ■ Because output fields appear as static text cally and you simply hit Enter (or right keys t ro k es to swi t c h to the backg round on the window background, the cursor Ctrl) at the “***” prompt to return to emu l a tor window when it has been com- cannot be positioned to output fields. This ISPF. In client/server mode, you must pletely covered by other windows. Keep makes it impossible to scroll a line to the switch to the terminal emulator window pa r t of the emul a tor window showing so top or bottom using cursor positioning in to see TSO messages (including job you can swi t c h windows with a single the SDSF LOG or output display (use SE submission and completion messages) mouse click. instead of S) or in BROWSE (use VI E W or output from TSO commands. This has instead of BROWS E ) . a few side effects: ■ You must swi t c h to the terminal emul a tor w i n d ow to rep ly to a prompt for input ■ You can’t mark and copy/paste multiple to a TSO command, s u ch as the lines as in the terminal emulator. responses to a TSO RECEIVE com- The most noticeable m a n d, or when running a progra m , ■ In addi t i o n , the cursor cannot be positioned difference between the s u ch as QMF, wh i ch uses GDDM to an output field by code in the panel instead of ISPF display serv i c e s . or in the program which displays the Graphical User Interface panel. Instead, the cursor is positioned (GUI) and the traditional PREREQUISITES to the first input field. For example, when Obviously, some communications software executing a FIND command on terminal emulation is needed to provide the connection between the BROWSE or SDSF LOG screen, the interface is with the the mainframe and the PC. For an OS/2 client, cursor is positioned on the command line you need either Communications Manager/2 rather than on the text that matched the “look and feel” of the for an APPC connection or IBM TCP/IP for search string. In terminal mode, the ISPF panels. OS/2. For Windows, you need IBM TCP/IP cursor is placed on the matching text, and for DOS with corrective service level 2.1.0.4 if the search is repeated without moving or higher, or version 4.1 of Novell’s LAN the cursor using a PF key which has been ■ You can continue working in the ISPF Workplace for DOS.We attempted to use the assigned the RFIND command, the next window without having to scroll through Windows ISPF client with a Windows TCP/IP occurrence of the search string will be all of the TSO output. You can switch to package, specifically SuperTCP Version 2.13 located. In client/server mode, the same the emulator window at any time and f rom Frontier Te ch n o l ogies Corp o rat i o n operation repeatedly finds the same text then scroll through the output by hitting ( F T C ) , and sure enough, it didn’t wo rk . on the first line of the screen, because Enter (right Ctrl) at the “***” prompt. Finally, APPC and/or TCP/IP must be running RFIND starts searching from on the mainfram e . Be sure the prer equisites are the beginning of the screen when the cur- ■ In some cases, when there is enough out met befor e proc e e d i n g . sor is on the command line. put to fill the TSO output buf fer , you must There are three steps to getting the ISPF respond to enough of the “* * * ” pr ompts to GUI working: download the client code, set ■ Although IBM recommends doing get the TSO command to complete before up the PC to accept a connection, then start IND$FILE file transfers only from the the next ISPF panel will be displayed. the GUI from the mainframe. TSO READY prompt (see information AP AR II06984), some terminal emul at o rs , ■ When the TSO command completes, the DOWNLOADING THE CLIENT CODE such as CM/2, can transfer files from th e ISPF panel is redisplayed whi c h brings it Although ISPF provides option 3.7 to ISPF “TSO Command” panel (option 6). to the for egrou n d , often while you are still d ownload the client code to a PC with In cli e n t / s e r ver mode, there is no menu lo o k i n g at the TSO output. For example, T C P / I P, an FTP server daemon (FTPD) option to initiate file transfers. Another do a TSO LISTALC STATUS and imme- must be running on the PC. It may be method, such as AFTP in the APPC diately switch to the terminal emulator easier to just download the client code Application Suite, or TCP/IP’s FTP, window to see the output from the com- m a nu a l ly as described by the Help or must be used. ma n d . Press Enter and wait a few seconds M a nual Install option of the ISPF at each “***” prompt. Shortly, the ISPF C l i e n t / S e rver Component Install panel. ■ The Windows API does not support w i n d ow will ove rl ay the emu l ator Since the client code needs to be dow n- use of the Insert key to toggle between w i ndo w and you will have to swi t c h loaded only once, a ny ava i l able file tra n s fe r “insert” and “overtype” modes in data ba c k to the emul at o r window again to c ap ability may be used. A l t e rn at ive dow n- entry fields while OS/2 does. You can view the rest of the LISTALC output. load methods incl u d e : SYSTEM STRATEGIES

■ Use the file transfer capability of your terminal emulator (such STARTING THE CLIENT/SERVER GUI as the “Receive file from host” option on the CM/2 Transfer To start the client/server GUI, go to the ISPF Settings panel (option menu) Note: If you are using CM/2, be sure that the “Tab to point- 0). Place the cursor on “GUI” on the action bar, hit Enter to display the and-shoot fields” option on the Version 4 ISPF Settings (option 0) pull-down menu, then enter option 1, “Start GUI”, as shown in Figure 2. panel is not selected. The “Initiate GUI Session” panel shown in Figure 3 will be displayed. For TCP/IP, enter “1” under “GUI Network Protocol” and put the IP ■ If you are using TCP/IP and have an FTP server running on the address of your PC in the “TCP/IP Address” field. For example: mainframe, the files can be transferred using FTP or FTPPM on the PC. For ISPF Version 4.1, the members of the ISPF SISPGUI 123.45.67.89 PDS which are needed are shown in Figure 1. For APPC, enter “2” under “GUI Network Protocol”, and put the Note that the name of the DLL file depends on the version of ISPF fully qualified case-sensitive name for the workstation in the “APPC that you are running. Address” field. For example, if the network name is USMYCO01 and the APPC LU is MYLUNAME, use: SETTING UP THE CLIENT The way the ISPF client program (ISPFCS) is written, there is no USMYCO01.MYLUNAME need to set up an APPC transaction program or a TCP/IP port for the program. It dynamically defines a transaction program if APPC services Although the workstation’s control point (CP) name may be used as are available, and dynamically defines a TCP/IP port if socket services are the LU name, consider setting up a local LU name specifically for the available. If both types of services are available, both are dynamically ISPF connection. defined, and you can use either type of connection. In fact, you can If you want something other than your user ID to appear in the title even switch between one type of connection and the other without shut- bar of the ISPF window, enter the text you want under “GUI Title”. ting down the client program. When these fields have been completed, enter a slash (/) in front of “Start Therefore, setting up the client is as easy as making sure the EXE GUI Session” and press Enter. If the communication is working proper- and DLL files are in the proper directories, making sure the communi- ly, an ISPF window will be created that will overlay the terminal emu- cations software is running with the appropriate protocols enabled, and lator window as shown in Figure 4. then starting up the ISPFCS client program. Under OS/2, the DLL file You will notice that the new window shows the ISPF Settings panel, should be in a directory in the LIBPATH, and the EXE file should be but the terminal emulator window in the background still shows the in a directory in the execution PATH. The client program can be start- “Initiate GUI Session” panel. Actually, as far as ISPF is concerned, after ed from an icon or from the OS/2 command line. For example, in an starting the GUI session, it has exited that panel and returned to the OS/2 Window, the client program can be started with the command:

START ISPFCS Figure 3: Initiate GUI Session Panel

A small “ISPF Client/Server” window is displayed which can be minimized if desired. This command can be added to OS/2’s STARTUP.CMD, or an icon can be created for the ISPFCS program and placed in the OS/2 Startup folder or the Windows StartUp group.

Figure 1: Members of the ISPF SISPGUI PDS

Host Member Name PC File Name

OS/2: ISPGUIOX ISPFCS.EXE ISPGUIOL ISPF41E.DLL

Windows: ISPGUIWX ISPFCS.EXE ISPGUIWL ISPF41E.DLL Figure 4: ISPF Settings After Starting the GUI

Figure 2: ISPF Settings With Start GUI Pull-Down

TECHNICAL SUPPORT APRIL 1996 SYSTEM STRATEGIES

ISPF Settings panel. All ISPF output is now going to the new window; If you are a CompuServe subscri b e r, and need additional help, t ry the terminal emulator window in the background is no longer being seeking help from IBM and other users in the ap p ro p ri at e updated by ISPF, so any remaining data from the ISPF panel that ha d C o m p u S e rve fo ru m s : been there should be ignored. At this point, there is no way to graceful- ly return to terminal emulation mode; the only way to exit client/serv- ■ APPC: GO APPC; and er mode is to exit ISPF. ■ TCP/IP: GO IBMTCP.

PROBLEM DETERMINATION INITIATING THE ISPF CLIENT/SERVER GUI If ISPF is unable to establish the connection to the work s t at i o n , ma k e If everything went well, you are now able to manually initiate the su r e commun i c a tions are working for other applications such as PING ISPF client/server GUI. Part II will explain how to automatically start for TCP/IP or APING for APPC. Check to make sure you are using ISPF in client/server mode when a user logs onto TSO. ts the correct address for the workstation. Make sure the APPC or TCP/IP c o m mu n i c ations softwa re is running on both the host and the wo rk- s t ation. Close the ISPF Client/Server window and restart the ISPFCS pr ogram to ver ify that the program was started after the communications s o f t wa re was fully initialize d. Make sure the program was start e d s u ccessfully by using Alt+Tab or Ctrl+Esc to switch to the ISPF Client/Server window, then attempt to start the GUI from the host again. If you are still unable to establish the connection, refer to Appendix A of the ISPF User’s Guide. In addition, the following IBM AP ARs may provide some useful inform at i o n : N a S PA member Robert Simpson has more than 16 years of computing ■ AP P C : II07895 ISPF Client/Server APPC Protocol Inform a tion; and experience, specializing in systems software support. He is experienced in installing and supporting OS/2 and related communications software, ■ TC P / I P : II07897 ISPF Client/Server TCP/IP Protocol Inform at i o n . as well as data base and communications software on the MVS/ESA platform. He can be reached via CompuServe ID: 71520,737 or Internet address: If you are using TCP/IP for OS/2, the command: [email protected].

netstat -s ©1996 Technical Enterprises, Inc. Reprinted with permission of Technical Support ma gaz i n e . For subscription info rm at i o n ,e m a i l will produce a display similar to Fi g u re 5. The last line shows that [email protected] or call 414-768-8000, Ext. 116. the p o rt was successfully initialize d, and that the ISPF Client/ Serve r p rogram is listening for a connection from the host. Other TCP/IP packages have similar commands. For example, to ve rify that the Wi n d ows ISPF client did not wo rk with FTC’s SuperTCP, we selected the “UDP Table” option from the “Net Stats” menu to di s p l a y the ports in use befor e and after starti n g the ISPF client. After starting the client,the listener and its port assignment should show up in the list; unfort u n at e l y, in our case, it didn’t.