Web/QuickRef R1.2 User’s Guide - Chicago-Soft, Ltd. · RACF S/390 z/OS Web/QuickRef User’s...

Web/QuickRef R1.2User’s Guide

Sunday, January 7, 2001

Chicago-Soft, Ltd.1 Maple Street

Hanover, NH 03755 Phone: (603) 643-4002

FAX: (603) 643-4571

Web: www.chicago-soft.com

Web/QuickRef User’s Guide

Trademarks or copyrights used in this publication:

Web/QuickRef © 2001 Chicago-Soft, Ltd.MVS/QuickRef © 1988, 2000 Chicago-Soft, Ltd.

UNIX® is a registered trademark of The Open Group in the United States and other countries.

The following terms are trademarks of the International Business Machines Corporation in the UnitedStates, other countries, or both: IBMOpenEditionOS/390RACFS/390z/OS


TESTING: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Page 13Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Page 13Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Page 11Generic Item Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Page 10Looking Up a Specific Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Page 7Clickable Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Page 6Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Page 5Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Page 5Web/QuickRef Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Page 5Web/QuickRef Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Page 5Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Page 5Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Page 4What’s New for This Release? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


What’s New for This Release?Enhancements in this release of Web/QuickRef:� The installation process has been improved; Web/QuickRef is now packaged and installed using the

UNIX® System Services (USS) ‘pax’ utility. Product elements are placed in their own directoriesin the USS HFS to isolate them from other IBM and/or ISV web products at your site.

� Miscellaneous technical and performance improvements have been made to the ‘qw’ REXX CGIexec.

� The documentation shipped with Web/QuickRef has been improved.


IntroductionThis document is the user’s guide for Web/QuickRef, a web-based interface to MVS/QuickRef execut-ing on your mainframe computer system. This user’s guide describes the capabilities and features ofWeb/QuickRef, how to install and use the product, and the prerequisites required before Web/Quick-Ref can be made operational.

OverviewWeb/QuickRef is a web-based interface to Chicago-Soft’s MVS/QuickRef product.MVS/QuickRef resides on an IBM or compatible mainframe system and executes under the MVS orOS/390 operating system. Web/QuickRef itself also resides completely on the same mainframe systemand executes under the OS/390 operating system; however, it uses the facilities of IBM’s HTTP webserver to permit browser-based access to information from the MVS/QuickRef main data base or fromone or more MVS/QuickRef user data bases. If your mainframe system is connected to a LAN (LocalArea Network) based intranet or to the Internet, then web browsers executing on any connectedsystem can access MVS/QuickRef data base content through that connection.

Web/QuickRef Elements

Web/QuickRef consists of the following elements:� An assembler program which provides an interface to MVS/QuickRef� a script, written in REXX, which is executed to dynamically create web page content� predefined web pages written in HTML� documentation, including this user guide

Web/QuickRef Prerequisites

Web/QuickRef has the following minimum prerequisites:

� OS/390 V2R5 or a later release level is required� IBM’s HTTP web server must be installed and active (the web server is shipped with the operating

system by IBM to all customers using OS/390 V2R5 or higher)� MVS/QuickRef R5.0 or higher must be installed and active� web browsers must be used that support the HTML 3.2 or higher standard; examples of acceptable

web browsers include Netscape Navigator 3.0 or higher, Microsoft Internet Explorer 3.0 or higher,or Opera Software’s Opera 3.1 or higher

Features


Web/QuickRef HTML screens are used to display the information that each browser user requests.Initial screens are presented that display a list of simple choices; the browser user either clicks on achoice or types in the name of a data base item to display and then presses the Enter key on the PC;Web/QuickRef then either displays the requested reference information or asks the browser user formore information. Figure 1 shows the initial display you will see when Web/QuickRef is first invoked.

Figure 1 - Web/QuickRef Initial Screen

The initial display screen shown in Figure 1 is divided into two sections or frames. The frame on top is amenu from which you can choose the reference information to display, and the frame on the bottom iswhere the information chosen for display in the top frame is actually presented. Initially, the bottomframe contains a short paragraph of ‘help’ text for Web/QuickRef. When a selection is made from themenu in the top frame, and that selection results in a display of reference text or a list of reference textitems from which a choice is to be made, the output is displayed in the bottom frame. When an item listis shown in the bottom frame, you can click with your left mouse button on items in the list to view thereference text for that item.

Categories

Information contained in the MVS/QuickRef main data base is generally of two types, message descrip-tions and non-message oriented reference text. Non-message oriented reference text is grouped into‘categories’ within the data base. The display shown in Figure 2 lists the categories found in the


MVS/QuickRef main data base. Figure 2 was produced by clicking the ‘Categories’ tab on the topframe of the Web/QuickRef screen shown in Figure 1.

Figure 2 - Category Display

Clickable Links

Each link that is available for you to click on in the display is shown underlined. For example, you canget additional information about the ‘codes’ category by clicking on the ‘CODES’ link shown in Figure2. You could get a list of all programming languages whose syntax is documented in the MVS/QuickRefmain data base by clicking on the ‘PROGLANG’ link, and so on.

Figure 3 shows the display that would result when you click on the ‘CODES’ link in Figure 2.


Figure 3 - Products within the ‘CODES’ category

Figure 4 - System Abend Code Item list for OS/390 V2R8


In Figure 3, a list of the products found in the MVS/QuickRef data base for the ‘CODES’ category isshown. You can view all of the items that comprise a product by clicking on that product’s link in thedisplay. For example, if you clicked on the OS/390 SYSTEM CODES link for V2R8 shown in Figure3, the display shown in Figure 4 would result. Figure 4 shows a list of all the system abend codes thatcan be issued under OS/390 V2R8. The output in Figure 4 is in turn another list of clickable links; youcan choose to view the reference text for an item in the list by clicking on it with your left mouse button.,or you can scroll the list up and down as needed.

Suppose you wanted to see information describing the cause and remedies for the A78 abend; to viewthe additional information, just click on the A78 item in the item list shown in Figure 4 and the displayshown in Figure 5 would result, providing you with the desired information.

When there is more information available in the output display than will fit in the current display window,browser scroll bars will appear and you can scroll the display frame down or up to view the additionalinformation.

Whenever information is being displayed and regardless of where you are in the information hierarchy,you can use your browser’s back and forward buttons to navigate backward and forward through thedisplay screens that you have already viewed.

Figure 5 - System A78 Abend Description


Looking Up a Specific Item

If you know which reference item you want to view, rather than clicking various links to find the itemname, you can type its name in the item name entry box which appears in the menu frame shown at thetop of Figure 1.

For example, suppose you wanted to view the reference text for message IEC141I, a description of thecauses for a S013 abend. To see the text, just type the item name IEC141I in the item name box foundin the top frame and click on the ‘submit’ button. The display shown in Figure 6 would result.

When more than one matching item exists in the MVS/QuickRef data base, Web/QuickRef will alwaysdisplay the item that is most appropriate for the release level of OS/390 in use.


Figure 6 - IEC141I Message Description

Generic Item Names

If you are unsure of the exact spelling for an item name, you can type a generic item name prefix; thisis an item name ending in an asterisk, such as IEC16* or ABEN*. When you enter a generic item nameprefix into the item name box shown in the top frame in Figure 1, Web/QuickRef will display a list of all


items found in the data base which match that generic item name prefix. Figure 7 is an example of such alist, generated when an item name of MOVE* was chosen.

Figure 7 - Generic Item Selection List

While viewing the list shown in Figure 7, you can click on the desired item within the item list to view thereference text for that item.


InstallationWeb/QuickRef is distributed electronically via the Internet, or on computer media, either floppy disk,CD-ROM or magnetic tape.

Installation Steps

Web/QuickRef is installed by following these steps:

1) Unzip the .ZIP file in which Web/QuickRef is packaged. You can unzip the file on a PC, or under theUNIX System Services side of OS/390 if you have a zip file utility there.

2) Upload or move the pax archive file (IN BINARY) to a Hierarchical File System (HFS) on theUNIX System Services side of your OS/390 system. If you are uploading, we suggest that you use FTPto perform the upload. Once again, make sure that you perform a BINARY file transfer!

3) Make sure you have the proper authority to create directories in the HFS where you will installWeb/QuickRef. Decide which directory in the HFS will be the parent directory for the Web/QuickRef elements, then enter the OMVS shell on your OS/390 system and use the 'cd' command to switch tothat directory.

We suggest that you install Web/QuickRef in the HFS at the '/u' mountpoint. This will keepWeb/QuickRef out of the system HFS's and permit you to perform z/OS or OS/390 upgrades withouthaving to re-install Web/QuickRef. We recommend that you create a directory called 'local' in your '/u'HFS and install Web/QuickRef there. Here are the commands to use to create the directory and switchto it:

cd /u /* change to '/u' directory */ mkdir local /* create a new directory called 'local'*/ cd local /* change to new directory */

If you don't want to install Web/QuickRef in our suggested location, you can install it in any directory, aslong as you define the directory in your web server's directive file correctly. This will be done later instep 5) below.

4) You will now use the 'pax' command to extract all files from the Web/QuickRef archive file. The paxcommand will extract the files and create a directory and subdirectories to contain all Web/QuickRef elements. The directory name is 'webqref'. Three subdirectories will be created just below the'webqref' directory; they are 'html' for HTML files, 'images' for web image files, and 'cgi-bin' for CGIscript and parm files. All extracted files except the one you are viewing now will be stored with lower-case file names.


If you follow our installation location suggestion, here is what the directory hiercharchy will look likeafter pax archive extraction:

u | local | webqref | +-------------+------------+ | | | cgi-bin html images

Example: If you placed the 'webqref.pax' archive file into an HFS file named '/u/p390/webqref.pax',then here is the pax command string that you would enter to extract the elements of Web/QuickRef intothe directory structure shown above, if you invoke pax from the '/u/local' directory:

pax -rv -f /u/p390/webqref.pax

5) Edit your web server's 'httpd.conf' file (usually /etc/httpd.conf) containing the congifuration definitionfor your web server and add the following directives to the section containing your other 'Exec' and'Pass' statements:

Exec /webqref/cgi-bin/* /u/local/webqref/cgi-bin/* Pass /webqref/* /u/local/webqref/* Pass /qw /u/local/webqref/html/qw.html

Note: If you elected to install Web/QuickRef at a location other than '/u/local', then you will have tomodify the above web server directives accordingly.

6) Allocate a RECFM=U,BLKSIZE=6233 linklib PDS on your OS/390 system. This will be theWeb/QuickRef linklib. Space needed is 30 tracks primary, 10 tracks secondary, with 5 directoryblocks.

7) Under TSO/E, OGET the file qwiwebrx.obj from file /u/local/webqref/qwiwebrx.obj in the HFS intoa PDS member named 'qwiwebrx' on your S390 system. This is the object code for the Web/QuickRefREXX 'called' function. This program is written in Assembler and is NOT APF authorized, but is RENTand REUS, AMODE(31), RMODE(ANY).

8) Under TSO/E, OGET file iewl.jcl from file /u/local/webqref/iewl.jcl in the HFS into a PDS memberon your OS/390 system. This file is linkedit JCL to link the QWIWEBRX object code into an executa-ble load module. Edit the JCL, add a JOB statement, point the SYSLIB DD to the Web/QuickReflinklib that you just allocated, then submit the job to link the QWIWEBRX object code into the linklib.


9) Under TSO/E, OGET file zaps.jcl from file /u/local/webqref/zaps.jcl in the HFS into a PDS member.Copy module QWIKREF1 from your production MVS/QuickRef linklib into the Web/QuickRef linklibyou just allocated. Edit the zaps JCL member that you just created, add a JOB statement, point theSYSLIB DD in the ZAPS member to the Web/QuickRef linklib, then submit the job for execution. Thisjob zaps module QWIKREF1 with several ZAPs that are needed in order to make Web/QuickRefoperational. Without these ZAPs, Web/QuickRef will not operate. The ZAPs will NOT affect thenormal operation of MVS/QuickRef, and will be transparent to all other MVS/QuickRef users.

10) In this step, you will prepare your web server to allocate the MVS/QuickRef data base(s).

Web/QuickRef uses your production MVS/QuickRef data base. The data base will be dynamicallyallocated, either by Web/QuickRef or MVS/QuickRef.

If you are already using the MVS/QuickRef options table 'QWIKOPTS' to make MVS/QuickRefdynamically allocate your MVS/QuickRef main and user data bases, then just copy the productionQWIKOPTS table to the Web/QuickRef linklib and go on to step 11).

If you DO NOT use QWIKOPTS to dynamically allocate the MVS/QuickRef data bases, then youmust define the name of your MVS/QuickRef data bases to Web/QuickRef so that Web/QuickRef candynamically allocate them. You do this by using the OEDIT command to edit the Web/QuickRef parmfile, 'qwiparms'.

OEDIT file /u/local/webqref/cgi-bin/qwiparms and specify the data set name(s), in single quotes, of yourmain and user data bases. The MVS/QuickRef main data base data set name is specified via the 'data-base=' variable. The name of your MVS/QuickRef user data base is specified using the'user_database=' variable. Save the changed 'qwiparms' file. If you have more than one MVS/QuickRefuser data base, then you should use QWIKOPTS instead of 'qwiparms' to enable dynamic data baseallocation.

11) OEDIT the 'httpd.envvars' file in use by your web server. This file is usually stored in the '/etc'directory. Find the STEPLIB= statement. If the statement says STEPLIB=CURRENT, then add aSTEPLIB DD statement to the IMWEBSRV JCL; the STEPLIB should point to the Web/QuickReflinklib where the ZAP'ed copy of QWIKREF1, the QWIKOPTS table, and the QWIWEBRX modulereside.

If the STEPLIB= statement in your 'httpd.envvars' file specifies STEPLIB=dsn1:dsn2:... then add thedata set name of the Web/QuickRef linklib you allocated previously to the list of data sets defined for the STEPLIB= variable. In this case, you do not need to add a STEPLIB DD to the IMWEBSRVJCL.

Restart the OS/390 HTTP web server IMWEBSRV by issuing this command at an OS/390 or z/OSconsole:


F IMWEBSRV,APPL=-restart

12) Under OMVS, 'cd' to the directory where the 'qwimain.html' file is stored; this is/u/local/webqref/html/. OEDIT the 'qwimain.html' file and change all occurrences of the string'204.254.171.15' to the IP address of the system on which your IBM OS/390 HTTP web server executes. If you don't know the IP address, then change all occurrences of '204.254.171.15' to the fullyqualified domain name (like www.yahoo.com) of the system on which your OS/390 HTTP web serverexecutes. Save the changed HTML file.

The installation of Web/QuickRef is now complete.

Testing

To access Web/QuickRef, point to the URL with your web browser. For example, if your web site isnamed 'www.zippyco.com', then you would invoke Web/QuickRef by typing this URL into yourbrowser:

http://www.zippyco.com/qw

The above testing example presumes that the 'qw' HTML file is stored in your default Web/QuickRefHTML directory.


Web/QuickRef R1.2 User’s Guide - Chicago-Soft, Ltd. · RACF S/390 z/OS Web/QuickRef User’s...

Documents

Transcript of Web/QuickRef R1.2 User’s Guide - Chicago-Soft, Ltd. · RACF S/390 z/OS Web/QuickRef User’s...