04-Feb 2011 IBM z/OS Communications Server Network Utility Assistant =========== ======================================================== Version 1 Note about printing the README.txt file: ---------------------------------------- Open it with Windows WORDPAD, in the Edit pulldown select "Select All", in the Format pulldown select "Font...", change font size to 9, change Font Style to Bold, click OK - and then print. If you use this method, the lines will print without breaking into two lines on a normal size sheet of paper. *********************************************************************** * * * Licensed Materials - Property of IBM * * Restricted Materials of IBM * * IBM z/OS Communications Server Network Utility Assistant * * program number 5694-A01 * * Copyright IBM Corp. 2011 * * All Rights Reserved. * * US Government Users Restricted Rights - Use, duplication or * * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. * * * ****************************************************************** * * * * CHANGE ACTIVITY: * * Flag Reason Release Date Origin Description * * ---- -------- -------- ------ -------- ------------------------ * * $xxx xxxxxxxx xxxxxxx yymmdd xxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxx * * * *********************************************************************** ======== Abstract ======== The "IBM z/OS Communications Server Network Utility Assistant" tool is a TSO/ISPF front-end to the z/OS Communications Server TSO NETSTAT line-mode command. The tool executes on your system as a traditional TSO ISPF application. ===================== Installation overview ===================== The tool is shipped as a single binary file that must be uploaded to the target z/OS system using a binary transfer type. The recommended method for this upload is a binary FTP transfer, but you can use other similar file transfer technologies. Allocate the target data set on z/OS as a sequential MVS data set with RECFM=FB and LRECL=80. If you use a block size of 27920, the data set requires approximately 120 such blocks. This data set is generally referred to as the UPLOAD data set. This sequential data set must then be "RECEIVED" using a TSO RECEIVE command into a PDS(E) library (also with RECFM=FB and LRECL=80). Assuming you transferred the binary file to MVS giving it the name of 'NETSTAT.ASSIST.UPLOAD' - use the following TSO command to process it: =>receive indataset('netstat.assist.upload') Dataset USER1.NETSTAT.ZOSV1R12.ALL from USER1 on MVS1 Enter restore parameters or 'DELETE' or 'END' + =>dataset('netstat.assist.install') The library that is created by this RECEIVE command is generally referred to as the INSTALL library. The BUILD member in the INSTALL library is a batch job that must be edited to provide installation-specific values for data set high level qualifiers, job name, accounting information, etc. //BUILD JOB 1,name,CLASS=?,MSGCLASS=?,NOTIFY=yourid //* //* Modify the above JOB card as needed //* //BUILD PROC INSTDSN='NETSTAT.ASSIST.INSTALL', // USERHLQ='NETSTAT.ASSIST', // SEZATCP='SYS1.SEZATCP', // USERVOL=yourvol, // USERUNIT=SYSDA //* //* Modify above JCL PROC varaiables as needed: //* //* INSTDSN: fully qualifed install data set - the data set you //* built when when you executed the TSO RECEIVE command //* //* USERHLQ: High-level qualifier(s) for the libraries that will be //* allocated and populated by this install job: //* - CNTL Various install job library //* - ASM Assembler source library //* - REXX REXX program library //* - PANELS ISPF panel library //* - MSGS ISPF message library //* - LOADLIB Load library //* //* SEZATCP: Your hlq.SEZATCP library (needed to pick up EZASOKET //* by the EZANETCI load module) //* //* USERVOL: Volume where libraries are to be allocated //* //* USERUNIT: UNIT name where libraries are to be allocated //* Update the job card with values that are acceptable to you. Specify the fully qualified name of the INSTALL library as the value of the INSTDSN keyword on the PROC statement. Additionally on the PROC statement, specify the high level qualifier(s) of the tool libraries as the value of the USRHLQ keyword, the fully qualified name of your current tcpip.SEZATCP library on the SEZATCP keyword, the DASD volume serial upon which you want the tool libraries to be allocated on the USERVOL keyword, and the DASD UNIT type as the value of of the USERUNIT keyword. After having made the necessary modifications to the BUILD member, submit it to JES for execution as a normal batch job. The BUILD job will create 6 PDS libraries with the following low level qualifiers: - CNTL Various install job library - ASM Assembler source library - REXX REXX program library - PANELS ISPF panel library - MSGS ISPF message library - LOADLIB Load library The BUILD job will populate the libraries by copying members from the INSTALL library and by running assembly/link edits of a few supplied source modules. The BUILD job should end with RC=0. RC=4 may be acceptable from one or more of the link edit steps. Any RC greater than 4 should be analyzed before re-submitting the BUILD job. When the BUILD job has ended, the tool has been successfully installed on your system. =============================== Post-Installation Modifications =============================== You can execute the tool from pre-allocated ISPF libraries, or from dynamically allocated ISPF libraries. Pre-allocated ISPF libraries means that you allocate the libraries to your TSO session permanently by means of your TSO logon JCL procedure, or by means of a logon CLIST. Dynamically allocated ISPF libraries means that the ISPF libraries needed by the tool are allocated when the tool is started and de-allocated when the tool terminates. In both cases, you need to look at the customization section in the EZANS REXX program that is part of the tool. Locate the section that is enclosed by the comments: CUSTOMIZATION SECTION - START CUSTOMIZATION SECTION - END /***************************************************************** */ /* */ /* CUSTOMIZATION SECTION - START */ /* ============================= */ /* */ /* If you have pre-allocated the ISPF libraries, specify the names */ /* as empty strings (panelds = '') - if not, specify the full */ /* data set names below and they will be LIBDEF'ed into the current*/ /* ISPF concatenation for ISPMLIB, ISPPLIB, and ISPLLIB. */ /* */ /* If you want this rexx to deallocate SYSTCPD and allocate it */ /* to a specific TCPIP.DATA data set, specify the name of that */ /* data set as the value of tcpdat. Please specify a fully */ /* qualified MVS data set name. */ /* Leave tcpdat as an empty string to use whatever TCPIP.DATA TSO */ /* will dynamically allocate (or use the one that is already */ /* allocated to DD name SYSTCPD. */ /* */ /***************************************************************** */ hlq = '' /*ISPF library HLQ */ panelds = hlq||'.PANELS' /*ISPF Panel library dsn */ msgsds = hlq||'.MSGS' /*ISPF Message library dsn */ loadds = hlq||'.LOADLIB' /*ISPF Load module dsn */ rexxds = hlq||'.REXX' /*REXX library */ tcpdat = 'yourhlq.tcpip.data' /*TCPIP.DATA data set */ /***************************************************************** */ /* */ /* CUSTOMIZATION SECTION - END */ /* =========================== */ /* */ /***************************************************************** */ The tcpdat customization variable can be used to have the EZANS REXX re-allocate your TCPIP.DATA data set - if you so need. You do not need to have the EZANS REXX program do this re-allocation if the correct TCPIP.DATA is pre-allocated to TSO via a permanent SYSTCPD DD statement, or the TCPIP.DATA data set that may be found via the standard TCPIP.DATA dynamic allocation process is the one you want to use. If that is the case then specify: tcpdat = '' /*TCPIP.DATA data set */ If you want to ensure that a specific TCPIP.DATA data set is used by the tool, specify: tcpdat = 'yourhlq.tcpip.data' /*TCPIP.DATA data set */ In this latter case, the tool will attempt to de-allocate SYSTCPD, and then allocate SYSTCPD to the data set you specified here. Pre-allocated ISPF libraries ---------------------------- If you use pre-allocated ISPF libraries, make the following changes: hlq = '' /*ISPF library HLQ */ panelds = '' /*ISPF Panel library dsn */ msgsds = '' /*ISPF Message library dsn */ loadds = '' /*ISPF Load module dsn */ rexxds = '' /*REXX library */ Dynamically allocated ISPF libraries: ------------------------------------- If you want to use dynamically allocated ISPF libraries, the EZANS REXX needs to add those libraries dynamically to your ISPF environment when it starts, and remove them again when it terminates. The ISPF panels, msgs, and load libraries are added by use of an ISPF LIBDEF service. The REXX library is added by use of the TSO ALTLIB service. To do so, the EZANS REXX program needs to know the names of those libraries. hlq = 'NETSTAT.ASSIST' /*ISPF library HLQ */ panelds = hlq||'.PANELS' /*ISPF Panel library dsn */ msgsds = hlq||'.MSGS' /*ISPF Message library dsn */ loadds = hlq||'.LOADLIB' /*ISPF Load module dsn */ rexxds = hlq||'.REXX' /*REXX library */ ======== Test it! ======== If you start the EZANS REXX from a library that is pre-allocated to your TSO environment, you should be able to just type in EZANS in ISPF option 6: Enter TSO or Workstation commands below: ===> ezans If the library into which you copied EZANS is not pre-allocated to your TSO session, you can use the following syntax to start it: Enter TSO or Workstation commands below: ===> exec 'netstat.assist.rexx(ezans)' Where netstat.assist.rexx is the library into which you copied EZANS and made the modifications mentioned above. You can of course also add a new option to one of your existing ISPF menus to invoke EZANS when a user selects a specific menu option. If things work correctly, you should see a panel that looks somewhat as follows: *--------------------- z/OS V1R12 CS TCP/IP NETSTAT --------------------------* Select a report option by number or name ==> 1 ALL 2 ALLConn 3 ARp 4 BYTEInfo 5 CLients 6 CONFig 7 CONN 8 DEVlinks 9 Gate 10 HOme 11 PORTList 12 ROUTe 13 SOCKets 14 TELnet 15 UP 16 CACHinfo 17 SLAP 18 VIPADYn 19 VIPADCFG 20 VCRT 21 VDPT 22 IDS 23 STATS 24 ND 25 SRCIP 26 DROP 27 TTLS 28 RESCache 29 DEFADDRT 90 TN3270 91 CICSsock 92 FTP 93 CICSTS Enter optional command modifiers and selection filters: Do you want to specify optional command modifiers ==> Y (Y/N) Do you want to specify optional selection filters ==> Y (Y/N) Enter optional TCP/IP stack name and general options: Stack name ==> TCPCS Leave blank for default stack Interval ==> 5 Seconds for interval display Report format ==> LONG (Short/Long) Leave blank for stack-default Excl. TN3270 ==> N (Y/N) Reply Y to exclude TN3270 connections Netstat debug ==> N (Y/N) Reply Y to see debug messages from Netstat EZANS debug ==> N (Y/N) Reply Y to see debug messages from EZANS Enter required arguments for ARP and DROP commands: ARP address ==> ALL ARP (specify an IPv4 address or ALL) Conn id ==> DROP (Specify connection ID to drop) From here-on, things are relatively self-explanatory. If you're in doubt about something, try pressing PF1 for help. ============================= Netstat modifiers and filters ============================= Many of the NETSTAT reports support modifier options (used to modify the type of information that will be displayed), and filters (used to limit the report output to specific entries). Many times, you just want to run a report without any modifiers or filters. To do so, enter N to specify modifiers and N to specify filters. As soon as you hit ENTER from this main panel, the full NETSTAT report will be displayed using its defaults. If you want to have the opportunity to use modifiers and/or filters, you enter a Y to the questions about specifying modifiers and filters. The tool will then, depending on the report you have selected, guide you through selection of the specific modifiers and filters that are supported by the report you selected. ============================ The Interval Display Support ============================ There's a field on the initial data entry panel where you can enter the interval time value in seconds (range is 5 to 3600 seconds). When output from the NETSTAT command is displayed, you have the following options: - Scroll back or forward in the output - At any point press ENTER to refresh the current panel contents - Type in F(ind) string and press ENTER to search for specific string in the NETSTAT output (if found, the line will be positioned as the first line displayed; another FIND command with the same argument will find the next occurance, and so on) - Type in GO and press ENTER - an interval display will be started. The keyboard will be locked and the panel content will be refreshed at each interval as specified by you. You exit the interval display loop by pressing the ATTN key. - Exit the display of NETSTAT output by pressing PF3 =========== Help panels =========== HELP panels are provided for each individual NETSTAT option, modifier, and filter type. When you have selected, for example, BYTEINFO - the BYTEINFO specific HELP panel will be displayed if you hit PF1 when looking at the output from a BYTEINFO NETSTAT command. ========= Debugging ========= As always, things may not work as you had intended. The tool supports two options on the main panel to request two levels of tracing. The EZANS debug option will trace information generated by the tool code itself (from the REXX modules and from the load modules invoked by the tool). The NETSTAT debug option will run the underlying NETSTAT commands with the normal NETSTAT debug option enabled (this may generate a lot of output!). All trace output will be sent to your TSO terminal. To verify that you are using a specific version of the tool, press PF1 on the main panel, and then select option 7 on the main help panel: About IBM z/OS Communications Server Network Utility Assistant This is Version 1 supporting all z/OS releases from z/OS V1R4 through z/OS V1R12. This version of the tool was packaged for download February 4, 2011 You are running the tool on z/OS V1R12 ===== NOTE: ===== This is not officially supported code from z/OS CS development. It has been developed in my spare time and not as part of normal z/OS CS development efforts. It is made available on an as-is basis. There is no guarantee that it works in all installations. There is no support, apart from what I will be able to find time for. If you find errors, please send me a note so I can try and fix them in the next version of the tool. There is no commitment to make this code officially part of z/OS CS. Good luck Alfred B Christensen alfredch@us.ibm.com