• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Ibm tivoli web access for information management sg246823
 

Ibm tivoli web access for information management sg246823

on

  • 2,666 views

 

Statistics

Views

Total Views
2,666
Views on SlideShare
2,666
Embed Views
0

Actions

Likes
0
Downloads
3
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    Ibm tivoli web access for information management sg246823 Ibm tivoli web access for information management sg246823 Document Transcript

    • Front coverIBM Tivoli Web Accessfor InformationManagementMove your help desk to the WebGet tips for installing Web AccessLearn about the HTMLgenerator Don Miller Mimi Michelet Michael Bacon Maryann Goldman Rollin Hippler Pete Louis Tom Shultzibm.com/redbooks
    • International Technical Support OrganizationIBM Tivoli Web Access for Information ManagementApril 2003 SG24-6823-00
    • Note: Before using this information and the product it supports, read the information in “Notices” on page vii.First Edition (April 2003)This edition applies to Release 1 of IBM Tivoli Web Access for Information Management (product number5698-WAI).© Copyright International Business Machines Corporation 2003. All rights reserved.Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP ScheduleContract with IBM Corp.
    • Contents Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x Notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiPart 1. Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapter 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Data flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.1 The details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Chapter 2. Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.1 Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.1.1 Hardware and software prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.1.2 Check for record identifier conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.1.3 Ensure that the HTTP Sever is installed and working. . . . . . . . . . . . . . . . . . . . . . 11 2.2 Performing the SMP/E installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.2.1 Installation reference table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.3 Customizing your Information Management installation . . . . . . . . . . . . . . . . . . . . . . . . 14 2.3.1 Update your session member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.3.2 Update your BLX-SP parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.3.3 Update your IBM panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.3.4 Load the sample records into your data session. . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.3.5 Load the data model records into your DMRDB session . . . . . . . . . . . . . . . . . . . 16 2.3.6 Create static data views from the data model records . . . . . . . . . . . . . . . . . . . . . 16 2.3.7 Verify your Information Management customizations . . . . . . . . . . . . . . . . . . . . . . 17 2.3.8 Set up e-mail notification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.3.9 Configure your HTTP Server for Web Access . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.3.10 Update your BLQPARMS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.3.11 Start the HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 2.3.12 Verify your Web Access installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 2.3.13 Generate HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Chapter 3. Enabling your community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 3.1 Assigning privilege class users and roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Part 2. Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Chapter 4. Implementing a Web solution using Web Access . . . . . . . . . . . . . . . . . . . . 33 4.1 Data model record overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 4.2 BLQPARMS definitions needed to support a record type . . . . . . . . . . . . . . . . . . . . . . . 36 4.3 Business logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.3.1 Predisplay user exit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.3.2 Validation user exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.3.3 Post-file update and create user exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.3.4 TSXs and TSPs used by business logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39© Copyright IBM Corp. 2003 iii
    • 4.3.5 JavaScript in HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.3.6 The home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Chapter 5. Building a customized Web application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 5.1 Getting started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 5.2 Data model and HTML considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 5.2.1 Date format and universal time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 5.2.2 Special processing s-words and table names. . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 5.2.3 Audit information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 5.3 Integrating business logic into your application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 5.3.1 REXX global variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 5.3.2 BLQUEXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Chapter 6. Generating user application HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 6.1 The HTML generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 6.2 Auto Build specifics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Chapter 7. Converting a 3270 application. . . ....... ...... ....... ...... ....... 71 7.1 Panel layouts. . . . . . . . . . . . . . . . . . . . . . . . ....... ...... ....... ...... ....... 73 7.1.1 Standard tasks . . . . . . . . . . . . . . . . . . ....... ...... ....... ...... ....... 75 7.2 Fields and groups . . . . . . . . . . . . . . . . . . . . ....... ...... ....... ...... ....... 78 Chapter 8. Using existing privilege class records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Chapter 9. Using shadow s-words and data attribute records . . . . . . . . . . . . . . . . . . . 91 9.1 Shadow s-words in Web Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 9.2 Status shadow s-words and data attribute records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 9.2.1 The BLQPARMS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 9.2.2 Status shadow s-words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 9.2.3 Status shadow data attribute records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 9.2.4 Groups that include the status shadows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 9.3 Building a shadow scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 9.3.1 Several other variations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Chapter 10. Type-based HTML . . . . . . . . . . . . . . . . . . . . . . . . . ....... ...... ...... 101 10.1 Type-based HTML in Web Access . . . . . . . . . . . . . . . . . . . ....... ...... ...... 102 10.2 Understanding type-based HTML in the problem record . . ....... ...... ...... 105 10.3 Key points to remember . . . . . . . . . . . . . . . . . . . . . . . . . . . ....... ...... ...... 108 Chapter 11. Updating the style file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Part 3. Administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Chapter 12. Web administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 12.1 Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 12.1.1 Navigation area tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 12.1.2 Field-initiated tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 12.2 Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Part 4. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Appendix A. Business logic examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 BLQUXPRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 BLQUXVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 BLQUXFIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Using dates, date formats, and time zones in business logic . . . . . . . . . . . . . . . . . . . . . . 144iv IBM Tivoli Web Access for Information Management
    • Obtaining the current date and time in the user’s format and time zone. . . . . . . . . . . . 144 Converting a date in the user’s preferred format to internal format. . . . . . . . . . . . . . . . 145 Converting an internal date to a user-preferred external date format . . . . . . . . . . . . . . 146 Rules to remember when handling dates in business logic . . . . . . . . . . . . . . . . . . . . . 147 Calculating a duration: An example using BLQUXVAL. . . . . . . . . . . . . . . . . . . . . . . . . 148Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Appendix B. Hints and tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Your changes to Web Access do not seem to take effect . . . . . . . . . . . . . . . . . . . . . . . . . 154Listing groups and layouts in data views using BLGDVLAY . . . . . . . . . . . . . . . . . . . . . . . 154Changing Web page titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Changing the Tivoli logo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Date formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Using Java Desktop data view and data attribute records . . . . . . . . . . . . . . . . . . . . . . . . . 157Sharing the Web server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Data views and data attributes used in the attaching process . . . . . . . . . . . . . . . . . . . . . . 158 Add attachments to your data views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159General considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Appendix C. Web Access configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 163Updating the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Debug option directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Data set name directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 General control directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 User ID and privilege class directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Directives that control the Information Management API . . . . . . . . . . . . . . . . . . . . . . . 166 UNIX System Services path and file reference directives. . . . . . . . . . . . . . . . . . . . . . . 168 Server side include (SSI) directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Business logic exit routine directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 User profile directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Record type directives (used for all record types). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Generic database search directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 HTML generation directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 S-words to left-zero pad and create hyperlinks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... ...... 175IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... ...... 175 Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... ...... 175How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... ...... 176 IBM Redbooks collections. . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... ...... 176Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Contents v
    • vi IBM Tivoli Web Access for Information Management
    • NoticesThis information was developed for products and services offered in the U.S.A.IBM may not offer the products, services, or features discussed in this document in other countries. Consultyour local IBM representative for information on the products and services currently available in your area.Any reference to an IBM product, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product, program, or service that doesnot infringe any IBM intellectual property right may be used instead. However, it is the users responsibility toevaluate and verify the operation of any non-IBM product, program, or service.IBM may have patents or pending patent applications covering subject matter described in this document. Thefurnishing of this document does not give you any license to these patents. You can send license inquiries, inwriting, to:IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.The following paragraph does not apply to the United Kingdom or any other country where such provisionsare inconsistent with local law : INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer ofexpress or implied warranties in certain transactions, therefore, this statement may not apply to you.This information could include technical inaccuracies or typographical errors. Changes are periodically madeto the information herein; these changes will be incorporated in new editions of the publication. IBM may makeimprovements and/or changes in the product(s) and/or the program(s) described in this publication at any timewithout notice.Any references in this information to non-IBM Web sites are provided for convenience only and do not in anymanner serve as an endorsement of those Web sites. The materials at those Web sites are not part of thematerials for this IBM product and use of those Web sites is at your own risk.IBM may use or distribute any of the information you supply in any way it believes appropriate withoutincurring any obligation to you.Information concerning non-IBM products was obtained from the suppliers of those products, their publishedannouncements or other publicly available sources. IBM has not tested those products and cannot confirm theaccuracy of performance, compatibility or any other claims related to non-IBM products. Questions on thecapabilities of non-IBM products should be addressed to the suppliers of those products.This information contains examples of data and reports used in daily business operations. To illustrate themas completely as possible, the examples include the names of individuals, companies, brands, and products.All of these names are fictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.COPYRIGHT LICENSE:This information contains sample application programs in source language, which illustrates programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programs inany form without payment to IBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operating platform for which the sampleprograms are written. These examples have not been thoroughly tested under all conditions. IBM, therefore,cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, anddistribute these sample programs in any form without payment to IBM for the purposes of developing, using,marketing, or distributing application programs conforming to IBMs application programming interfaces.© Copyright IBM Corp. 2003. All rights reserved. vii
    • TrademarksThe following terms are trademarks of the International Business Machines Corporation in the United States,other countries, or both: ™ NetView® RACF® ^™ OS/390® Tivoli® eServer™ Planet Tivoli® z/OS™ IBM® Redbooks™ MVS™ Redbooks(logo) ™The following terms are trademarks of other companies:ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the UnitedStates, other countries, or both.Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in theUnited States, other countries, or both.Java and all Java-based trademarks and logos are trademarks or registered trademarks of SunMicrosystems, Inc. in the United States, other countries, or both.C-bus is a trademark of Corollary, Inc. in the United States, other countries, or both.UNIX is a registered trademark of The Open Group in the United States and other countries.SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure ElectronicTransaction LLC.Other company, product, and service names may be trademarks or service marks of others.viii IBM Tivoli Web Access for Information Management
    • Preface This new add-on product to the popular and powerful IBM® Tivoli® Information Management for z/OS™ is a drop-in Web solution for problem and change management. This product provides Web Access for the help desk, developer, manager, and end user. In addition to problems and changes, it can be used to build HTML Web browser interfaces for any record type, utilizing the power of the OS/390® server with a Web browser, while requiring only common industry standard skills. Users have access to their data from any machine with a Web browser. Would it be helpful to have: A graphical user interface that addresses usability and accessibility concerns? Instant access to an integrated database through the Web? A way to quickly identify what is down and what action is being done to correct it? A product that can easily be used to add additional record types to interface with problems or changes, or both, and to be able to do it with little to no programming? Value IBM Tivoli Web Access for Information Management1 provides the power of the Information Management for z/OS database together with flexibility and usability to the end user through the use of a Web browser. An intended benefit of this product is to reduce your training and development costs. With the ability to generate HTML using records in the database, providing Web access to your records is an administration task, rather than a programming task, helping to reduce the need for a programming skill set. This technology eliminates the need to code HTML pages from scratch. Sample business logic is provided, and additional logic can be easily added by writing simple REXX executables. The Web administrator can easily add new record types to accompany the problems and changes included. From an IT perspective, this product should eliminate the hours of 3270 training that were previously required. Benefits The following are some of the many benefits of Web Access: Provides out-of-the-box problem and change management through a Web browser Quick implementation and installation Reduced training and development costs Rapid time-to-value Graphical user interface functionality Fully customizable to fit business needs Security through Web server, RACF®, and Information Management for z/OS privilege classes Powerful search capabilities, allowing searches on virtually any data contained in the database Ongoing support File attachments for records 1 Hereafter, called simply Web Access.© Copyright IBM Corp. 2003 ix
    • Personal profile and saved settings Business logic Customization using a Web interface The Evolution of Tivoli Information Management Information Management was first introduced in 1981. It was originally a 3270 product used for problem and change management. Most customers were, and continue to be, Fortune 500 companies that have a strong need for a problem and change management application that has the power and flexibility to meet changing business requirements. There were several versions of the product over the past two decades. Each release introduced powerful and timely functionality to meet customer requirements. Most recently, the market requirements for a Web solution were communicated from Information Management for z/OS customers. Web Access meets the requirements of a Web solution. It provides a graphical user interface that is user-friendly and easily installed and customized. The fact that it is using an OS/390 or z/OS database is transparent to the users. The database can be accessed from any Web browser worldwide, thus opening the door for new user communities that would otherwise be unwilling or disinterested in a 3270 interface.The team that wrote this redbook This redbook was produced by a team of specialists from Tivoli Information Management Development and Support in Raleigh. Don Miller joined IBM in 1977 as a Hardware Customer Engineer (CE). He began his software career at the IBM Tampa Software Support Center in 1984, where his area of specialty was MVS™, including JES2, JES3, and SMP/E. In 1988, Don moved to Raleigh and joined the Information Management support team, where he undertook change team and development assignments. In 1995, he was assigned to the team developing and supporting the Web Connector interface to Information Management. He joined Tivoli Services in 1999, where he provided custom Web solutions to IBM customers using Information Management. Don was the Web subject matter expert and provided technical leadership for the Web Access project. Don rejoined the Information Management development team in July 2002. Mimi Michelet has been a Developer on the Information Management team since 1988. She has worked on a number of features in the product, including the BLX-SP, APIs, workstation clients, ODBC driver, and Desktop. She served as the project manager for the Web Access project and also helped develop the business logic implemented by the drop-in problem and change management solution. Michael Bacon joined IBM in 1998, where his first position was in Level 2 Information Management Support. In October of 2000, he became the Level 2 and Level 3 Support Manager, and later assumed development manager responsibilities for the product as well. He was Release Manager for Information Management for z/OS (which shipped in August 2001), as well as Web Access (which shipped in May 2002). Prior to joining IBM, Michael worked for NationsBank (now Bank of America), where he was a development team lead for the Information Management product. Maryann Goldman has worked on the Information Management team since 1991. During that time, she has done Level 2, Level 3, and development. Her favorite area of the product is the API, where her expertise is often sought out. She was Managing Editor of the Structured Word newsletter from 1996 to 1998. She has presented at many user groups and at Planet Tivoli®. Her major contribution to the Web Access project was understanding and piecing together the specifications for the HTML generator.x IBM Tivoli Web Access for Information Management
    • Rollin Hippler joined the Information Management development team in 1989, when hehelped design and implement the V5 BLX-SP. Since that time, he has worked onenhancements to increase database capacity, improve database integrity, and improveperformance. He has also worked on logical database partitioning and sysplex exploitation. Inaddition, Rollin has been a member of the service team providing resolutions for problemsrelated to the BLX-SP and database integrity. His primary responsibility for the Web Accessproject was infrastructure development.Pete Louis has worked on the Information Management team since 1991, doingdevelopment and support, as well as acting as system programmer for the teamsdevelopment/test systems. He generally concentrates on the “behind the scenes” andinfrastructure areas of the product (such as VSAM, parallel sysplex, multitasking,serialization, system services interfaces, and packaging). His primary contribution to the WebAccess project was the redesign of the Information Management API to support running in theHTTP Server multitasking environment.Tom Shultz has been a member of the Information Management team since 2000 and hasbeen working with the product since 1995. As part of the Information Management team, hehas done Level 2 support and development, specializing in PMF, REXX/TSX, and theDesktop. Tom helped code HTML for the Web Access project and provided assistance withdeveloping this redbook.Editorial staffThanks to the following people for their contributions to this project:Buck Stearns was managing editor. He is a Solution Development IT Specialist for IGSBusiness Development at the ITSO, Raleigh Center. Prior to joining ITSO, he worked twoyears as a mobile employee assigned to Tivoli Services and specializing in InformationManagement for z/OS and Tivoli Business Systems Manager. Before that, he logged over 25years in the banking and insurance industries, including the last 12 as problem, change, andconfiguration system administrator, architect, and programmer for Wachovia, now thenation’s fourth-largest financial holding company. Buck has spoken on configurationmanagement at the national Information Management users conference and is ITIL-certified.2He has extensive experience in IT management disciplines and holds undergraduate andgraduate degrees in English from the University of North Carolina at Chapel Hill.Elizabeth Barnes of ITSO Austin served as executive editor.Linda Robinson of ITSO Raleigh was our graphics designer.ReviewersThanks to the following people for their contributions to this project:Julie BerghIBM Minneapolis, MNArt EisenhourIBM Gaithersburg, MD2 The Information Technology Infrastructure Library (ITIL) is a set of books developed by the United Kingdoms Officeof Government Commerce (OGC). These books describe an integrated, process-based, best-practice framework formanaging IT services. To date, they are the only comprehensive, non-proprietary, publicly available guidance for ITservice management. ITIL was conceived in the late 1980s. It was initiated to improve IT Service Management in theUK central government and is relevant to all organizations, public or private sector, large or small, centralized ordistributed. Today, ITIL represents more than books alone. It has generated an entire industry that includes training,certification, consultancy, software tools, and trade association (itSMF). Preface xi
    • Lynn Kearney IBM Dallas, TX Greg Herbert IBM Austin, TX Sergio Juri IBM Raleigh, NC Cindy Purdy IBM Roanoke, VA Other contributors Special thanks to these two outstanding individuals (both now retired from IBM and sorely missed) for their long-term commitment to Information Management and more specifically to the processes and overall design of Web Access. Nancy Leavell Cary, NC Larry Schultz Markham, OntarioNotice This publication is intended to help Information Management administrators install and customize IBM Tivoli Web Access for Information Management. The information in this publication is not intended as the specification of any programming interfaces that are provided by IBM Tivoli Web Access for Information Management. See the PUBLICATIONS section of the IBM Programming Announcement for IBM Tivoli Web Access for Information Management for more information about what publications are considered to be product documentation.Become a published author Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. Youll team with IBM technical professionals, Business Partners and/or customers. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, youll develop a network of contacts in IBM development labs, and increase your productivity and marketability. Find out more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.htmlxii IBM Tivoli Web Access for Information Management
    • Comments welcome Your comments are important to us! We want our Redbooks™ to be as helpful as possible. Send us your comments about this or other Redbooks in one of the following ways: Use the online Contact us review redbook form found at: ibm.com/redbooks Send your comments in an Internet note to: redbook@us.ibm.com Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HZ8 Building 662 P.O. Box 12195 Research Triangle Park, NC 27709-2195 Preface xiii
    • xiv IBM Tivoli Web Access for Information Management
    • Part 1Part 1 Basics Part 1 contains a Web Access product overview and installation instructions.© Copyright IBM Corp. 2003 1
    • 2 IBM Tivoli Web Access for Information Management
    • 1 Chapter 1. Overview IBM Tivoli Web Access for Information Management is a sophisticated Web application based on the concepts described in the Tivoli Information Management for z/OS World Wide Web Interface Guide, Version 7.1, SC31-8757 (BLGW1E10). Web Access provides the ability to access dynamically defined data in the Information Management for z/OS database using a Web browser and includes a drop-in problem and change management Web solution. However, Web Access is more than just a complex Web application. It also provides functions that allow you to administer the application from the Web and provides support for customized applications. Web Access supplies the core set of REXX programs that manage the applications and drive access to your Information Management for z/OS database, whether you use the drop-in solution or your own application. If you need a customized application, tools are provided to build the HTML for your application, and exit points are also available for you to hook in your own business logic processes. Web Access consists of three primary pieces: 1. Application—Data model records, HTML, and business logic. These items uniquely define either the drop-in solution or your customized application. Data model records define the data that can be accessed, whereas the HTML defines the presentation of that data. 2. Infrastructure—Common REXX programs that support all applications and provide the HLAPI/REXX interface to the Information Management for z/OS database. This also includes functions that allow you to build the HTML for your applications and administer those applications from the Web. 3. Configuration—Application configuration information, including such things as API operating characteristics, the session-parameters member, business logic exit routine names, and the mapping of record types to HTML names.3 An IBM HTTP Server is also required to serve your Web Access application requests. 3 More information can be found in “Updating the configuration file” on page 164.© Copyright IBM Corp. 2003 3
    • 1.1 Data flow Your Web browser clients and your server machines communicate using TCP/IP protocol and must be part of the same IP network. This network could either be the Internet itself or a private network (intranet) that has no external connections or is connected to the Internet through a firewall. Web browser transactions are received by TCP/IP and queued for processing by the HTTP Server. The HTTP Server Go Webserver API (GWAPI) REXX interface is used to process Web browser transactions. The HTTP Server invokes the GWAPI REXX DLL, which establishes a REXX environment and invokes the REXX programs in the Web Access application. Requests for static HTML are served immediately by reading the information either from the HTML UNIX System Services directory (/usr/lpp/InfoMan/web/html) or from an internal cache. If access to the Information Management for z/OS database is required, the Web Access REXX programs use HLAPI/REXX calls to communicate with the database, formatting data they receive into HTML code that they pass back to the HTTP Server to be returned to the client.1.1.1 The details Figure 1-1 depicts the components of the Web Access application. httpd.conf TCP/IP Network HTTP Server for z/OS httpd.envvars SAF/LDAP HTML Database Directory z/OS Tables TSXs (PIDT and alias) Caches Core REXX Business HTML BLQWSWRT Logic User data BLQWRGET BLQUXPRE Session data Database, P-class BLQWRVAL (cached record) HLAPI env BLQUXFIL Data Model BLQWRUPD Records SRL BLQUXVAL BLQWRNEW BLQPARMs BLQWRUPD Session data (cached record) Home Page BLQWRINQ ... BLQHOME HLAPI/REXX Information Tivoli Web Access Management HLAPI/REXX Figure 1-1 Web Access application flow4 IBM Tivoli Web Access for Information Management
    • The HTTP Server for z/OS, Information Management for z/OS, and Web Access, along withyour existing TCP/IP network and workstations, work together to enable a user to work withrecords in your Information Management for z/OS database using a Web browser. Accessingthe Information Management for z/OS database in this way is done using a URL that caneither be typed into the browser’s address box or (more likely) hyperlinked from an existingHTML page that your users frequent. When a Web user addresses the HTTP Server forz/OS, it authenticates that user using either SAF (RACF) or Lightweight Directory AccessProtocol (LDAP) directories. If the user cannot be authenticated, processing stops and theuser is not allowed access to the Information Management for z/OS database. After the Webuser has been authenticated, the HTTP Server calls Web Access to process the request.Web Access performs the request and returns HTML to the HTTP Server, which then sendsthe HTML over your TCP/IP network to the Web browser to display to the user.To process requests, Web Access interacts with your Information Management for z/OSdatabase using the Information Management HLAPI/REXX interface and the HTTP Server forz/OS GWAPI, both of which are documented and supported general application programminginterfaces.4Following is a breakdown of the components and functionality of the HTTP Server, WebAccess, and Information Management for z/OS:HTTP Server for z/OSThe HTTP Server for z/OS does the following: Authenticates the Web user. Serves up static HTML directly from files stored in UNIX System Services directories in the Hierarchical File System (HFS). Sends requests for dynamic HTML (any record display, search, update, or create) to Web Access using the GWAPI.5Web AccessWeb Access provides the infrastructure required to display, update, create, or search forrecords stored in the Information Management for z/OS database. This infrastructure consistsof the following: Core REXX—Modules that are executed to process the requests, including: – BLQWSWRT: • Parses and translates the HTTP protocol request. • Calls Web Access routines to process the request. • Manages each Web user’s profile (user data cache). • Obtains and frees a HLAPI session for each request. • Manages the HLAPI environment cache. • Handles error recovery. – BLQWRGET: • Using HLAPI/REXX, reads a record from the Information Management for z/OS database. • Loads the record data into the user’s session data cache.64 No undocumented or unsupported interfaces are used by Web Access.5 A Common Gateway Interface (CGI)-like interface.6 A cached copy of the record data for use by other Web Access routines and business logic user exits. Chapter 1. Overview 5
    • • Inserts data from Information Management for z/OS into the HTML and uses the GWAPI to send the HTML back to the HTTP Server. • Calls the business logic predisplay_exit routine (which can modify data and redirect the HTML file used to display that data). • Manages privilege class cache and loads HTML cache. – BLQWRVAL: • Validates data entered by Web users updating or creating records in the Information Management for z/OS database. • If the data is valid, updates the session data for that user and calls the business logic validation_exit routine. – BLQWRUPD: • Uses updated session data to update records in the Information Management for z/OS database. • Updates user transaction history. • Calls the business logic postfile_update_exit routine. – BLQWRNEW: • Uses session data to create records in the Information Management for z/OS database. • Adds any record relationships.7 • Updates user transaction history. • Calls the business logic postfile_create_exit routine. – BLQWRINQ: • Validates and performs searches. • Sorts the search results. • Creates and manages the SRL cache (which is used when scrolling the SRL). Caches —Web Access uses in-memory caches to improve performance. These caches include: – HTML cache—BLQWRGET and BLQWRINQ processing reads HTML from a UNIX System Services directory in the HFS and saves it in the HTML cache. Some processing of the HTML is done before it is cached. For example, data attribute and validation records are read to populate drop-down lists in the HTML. – User data cache—Key fields from the Web user’s people record profile, including fields such as the user’s date format and time zone. – Privilege class (P-Class)—The authority codes for each privilege class are cached. – HLAPI environments—Each HLAPI session started is cached. These sessions are shared among all Web Access users. The maximum number of concurrent HLAPI sessions is defined by the max_sessions parameter in the Web Access BLQPARMS configuration file. – SRL cache—The record numbers returned by a search are cached. These cached record numbers are used to access the Information Management for z/OS database in order to populate the HTML page when a user scrolls through search results. This avoids reading all records returned by the search, because only enough records are read to populate each SRL page and additional records are read only as needed when the user scrolls through the results. 7 Parent/child6 IBM Tivoli Web Access for Information Management
    • – BLQPARMS cache—The parameters in the Web Access configuration file are cached and retrieved by the Core REXX programs as needed. These parameters are also available to business logic routines. – Session data cache—A cache of all the data for a specific record and user. If two users display the same record, there are two copies of the record in the session data cache (one for each user). Since the session data is used for all subsequent accesses by a user, data can be added or removed from the session data based on the user’s authority, role, or as business logic dictates. When a user creates or updates a record, only the session data is changed. When a user files the record, the session data is used to create or update the record in the Information Management for z/OS database. This allows the user to cancel the create/update any time prior to the actual file. Session data is also used to pass data to and from the Core REXX routines and the business logic user exits. Session data is destroyed when the user files or cancels the update or create request. This prevents duplicate creates or updates should the user click the browser’s Back button or refresh or reload the HTML. Business logic exit points—Though Web Access handles the mechanics for updating, creating, displaying, or searching for records, your business processes might require additional checking of data entered by your users. For example, although Web Access can ensure that the required fields Change Risk and Change Implementation Target Date are filled in and contain data in the proper format, it does not know that your process requires 21 days lead time for a medium-risk change. User exits allow you to code your own business logic to implement this rule. If a user enters a date that does not allow enough lead time, your business logic can display a message stating this, as well as flagging the field that the user should correct. Optionally, this logic might simply change the target implementation date to one that allows enough lead time. Web Access thus provides exits that allow you to implement your own business logic processing without having to touch the Core REXX. There are four business logic exit points: – Predisplay_exit—Runs before each HTML page is displayed. – Validation_exit—Runs when the user leaves an HTML page or files a record. – Postfile_create_exit—Runs after a record is created. – Postfile_update_exit—Runs after a record is updated. In addition, your business logic can control what information is displayed on the user’s Web Access home page (BLQHOME). Refer to Appendix A, “Business logic examples” on page 123 and 5.3, “Integrating business logic into your application” on page 47 for more information regarding business logic implementation.Information Management for z/OSComponents of Information Management include: The Information Management for z/OS database, which contains: – Your records – Web Access records, including: • Data model • Privilege class • Message • Reference TSX data sets, which contain: – Information Management for z/OS TSXs Chapter 1. Overview 7
    • – Your TSXs – Web Access TSXs Virtual Storage Access Method (VSAM) panel data sets, which contain: – Information Management for z/OS panels – Your panels – Web Access panels Report format table (RFT) data sets, which contain: – Information Management for z/OS program interface data tables (PIDTs) and program interface pattern tables (PIPTs) – Your PIDTs, PIPTs, and program interface alias tables (PALTs) – Web Access PIDTs, PIPTs, and PALTs8 IBM Tivoli Web Access for Information Management
    • 2 Chapter 2. Installation This chapter includes a checklist and detailed instructions about how to plan for and install the product. Note: Because the product is SMP/E installed, those steps are covered in the IBM Tivoli Web Access for Information Management Program Directory, GI10-3232.© Copyright IBM Corp. 2003 9
    • 2.1 Planning Before you begin installing Web Access: Verify that you have the hardware and software prerequisites. Check for record identifier conflicts (existing Information Management for z/OS customers only). Ensure that the HTTP Server is installed and working. After you perform these checks, you should: Perform the SMP/E installation of Web Access. Obtain the following guides: – Tivoli Information Management for z/OS Planning and Installation Guide and Reference, Version 7. 1, GC31-8751 (BLGP2E10) – Tivoli Information Management for z/OS Operation and Maintenance Reference, Version 7.1, SC31-8749 (BLGO1E10) Complete the installation reference table. Customize your Information Management for z/OS installation for Web Access. Configure your HTTP Server for Web Access. Verify your Web Access installation.2.1.1 Hardware and software prerequisites This section describes what you need to install to use Web Access. Hardware requirements Web Access can run in any hardware environment that supports the required software. Software requirements To use Web Access, you must have the following. For the host: OS/390 Version 2.8 (5647-A01) or later, or z/OS Version 1.1 (5694-A01) or later Tivoli Information Management for z/OS Version 7.1 (5697-SD9) or later, with the fixes for the APARs shown in Table 2-1 applied8 Table 2-1 Required PTFs PTFs APAR fixed UW87419 OW53441 UW92102 OW54084 UW92212 & UW92213 OW54215 UW92070 & UW92071 OW54576 UW92090 OW54626 UW92186 OW55367 UW92562 OW55489 8 Check the PSP bucket, UPGRADE INFO710 SUBSET HOYB120, for the latest maintenance.10 IBM Tivoli Web Access for Information Management
    • The fix for Web Access APAR OW54661 (PTF UW92115) The fix for Web Access APAR OW55409 (PTF UW93644) For the workstation: Netscape Version 6.0 or later, or Microsoft Internet Explorer Version 5.5 or later2.1.2 Check for record identifier conflicts Note: Existing Information Management for z/OS customers only. If you have been using Information Management for z/OS, it is possible that records could have been created in your database or databases using record identifiers that Web Access requires. You need to resolve these conflicts before you install Web Access. Using the COPY command and giving the record new identifiers should be enough in most cases. The records shipped by Web Access start with the BLQ prefix. You can also enter the following freeform search on the command line to verify that you do not have records that start with BLQ that might be a conflict: SEARCH RNID/BLQ. Hopefully, you get the following message: BLG19214I No records satisfy the specified search criteria. If the search does not locate any records, you should not experience any record name conflicts and you can continue. If the search does locate records that start with BLQ, you should note these record IDs. If you do not have a copy of these records, use the COPY command and create copies of these records (you will have to use new record IDs). Then continue with the installation. After you have loaded all of the data model records, you should display the records you noted and see if they were changed. If they were changed (replaced) by the Web Access install, you will need to resolve the conflicts.2.1.3 Ensure that the HTTP Sever is installed and working When customizing the installation of Web Access, the HTTP Web server configuration is updated. Therefore, you should verify that the HTTP Server is installed and active by entering the following URL in your browser address bar: httpd://your_host_name_or_ip_address:your_port_number/ Note: Here, you should substitute your actual host name (or IP address) and port number. A port number (:your_port_number) is needed only if you are using a port other than 80 for your Web server. After entering this URL in your browser address window, you should receive an IBM HTTP Server Web page. If not, you will need to stop the Web Access install process and determine why this page did not successfully load. For more information about setting up the IBM HTTP Server for OS/390, see IBM HTTP Server Planning, Installing, and Using, SC31-8690 for Version 5.2, or SC34-4826 for Version 5.3. Chapter 2. Installation 11
    • 2.2 Performing the SMP/E installation Refer to the IBM Tivoli Web Access for Information Management Program Directory, GI10-3232, that came with your Web Access tape. It is recommended that you use the same DDDEFs for Web Access that you did for Information Management for z/OS so that the common data sets are shared.2.2.1 Installation reference table When you install Web Access, you will need to reference and change various files and data sets. To speed Web Access installation, please take the time to fill in the information in Table 2-2. Make a copy of the table for your test and production systems. Keep it handy when you are customizing the installation of Web Access. Refer to this table when you need to locate one of the files or data sets needed during the install.Table 2-2 Installation reference table Name Location and description BLX-PROC MVS PROCLIB:_______________________________________________________________ MVS procedure used to run the BLX service provider (BLX-SP).a BLXPRM MVS PDS name and member:____________________________________________________ Parameters used to control the BLX-SP. The BLXPRM DD in BLX-PROC points to the PDS. The BLX-SP parameters member is typically named BLX100.a SBLMMOD1 MVS PDS name: ______________________________________________________________ Contains the load modules and session members used by Information Management for z/OS.b You may use multiple load libraries, so list them all. SBLMSAMP MVS PDS name: ______________________________________________________________ Contains the sample JCL members for Information Management for z/OS and Web Access. SBLMPNLS MVS PDS name: ______________________________________________________________ Contains the panels needed by Information Management for z/OS and Web Access.c SBLMRCDS MVS PDS name: ______________________________________________________________ Contains data model records used by Information Management for z/OS and Web Access. SBLMTSX MVS PDS name: ______________________________________________________________ Contains the TSX executables used by Information Management for z/OS and Web Access. SBLMFMT MVS PDS name: ______________________________________________________________ Contains the report format tables, program data tables (PIDTs), and alias tables for Information Management for z/OS and Web Access. SBLMDICT MVS PDS name: ______________________________________________________________ Contains the dictionary for Information Management for z/OS and Web Access. WEBPROC MVS PROCLIB:_______________________________________________________________ MVS procedure used to run the HTTP Server. The procedure was created during the installation of the HTTP Server. See IBM HTTP Server Planning, Installing, and Using, SC31-8690 for Version 5.2, or SC34-4826 for Version 5.3.12 IBM Tivoli Web Access for Information Management
    • Name Location and descriptionBLG-Source MVS PDS name: ______________________________________________________________ Contains the source code used to create one or more session parameter members. It is often used to store the JCL used to run the Information Management for z/OS utilities and create the Information Management for z/OS database. You might want to use this PDS for the JCL employed to run the Information Management for z/OS utilities for Web Access. Keeping the Information Management for z/OS and Web Access JCL in the same PDS is recommended. Session members are named BLGSESnn.d Session member you want Web Access to use when Web users create, update, and so on, problem and change records: ___________ (data session) Session member used to access your data model record database e as database 5 (read/write mode) if different than your data session: ___________ (DMRDB session) Session member used when you use the Information Management Panel Modification Facility (PMF) if different than your data session: ___________ (PMF session) Browse the session-parameters member source for the data session and locate the following data set names coded on the BLGCLDSN macros: The IBM Panels data set: _______________________________ The dictionary data: _______________________________RFTDD MVS PDS name: ______________________________________________________________ Data set that contains your modified RFTs, PIDTs, and alias tables. If you do not currently have one, then allocate one. Model it after SBLMFMT.TSX MVS PDS name: ______________________________________________________________ Data set that contains your modified TSXs. If you do not currently have one, allocate one. Model it after SBLMTSX.httpd.envvars Path and file name:____________________________________________________________ The HTTP Server environment variables file. The default environment variables file is /etc/httpd.envvars. An environment variables file can be specified in your WEBPROC used to run your HTTP Server. The file is pointed to by _CEE_ENFILE ENVAR. The _CEE_ENFILE file can specify a path or a DD name. Examples: //IMWPROC PROC ICSPARM=-r /etc/httpd.conf, // LEPARM=ENVAR(“_CEE_ENVFILE=/etc/httpd.envvars “) //WEBSRV EXEC PGM=IMWHTTPD,REGION=0K, // PARM=(&LEPARM/&ICSPARM),TIME=NOLIMIT or //IMWPROC PROC ICSPARM=-r /etc/httpd.conf, // LEPARM=ENVAR(“_CEE_ENVFILE=DD:WENV “) //WEBSRV EXEC PGM=IMWHTTPD,REGION=0K, // PARM=(&LEPARM/&ICSPARM),TIME=NOLIMIT //WENV DD PATH=/etc/httpd.envvars, // PATHOPTS=(ORDONLY) Chapter 2. Installation 13
    • Name Location and description httpd.conf Path and file name:____________________________________________________________ Configuration file used by the HTTP Server. The HTTP Server configuration file is specified in the -r parameter on the ICSPARM parameter in your HTTP Server startup procedure. If the -r parameter is not specified on ICSPARM, or if ICSPARM is not specified, the configuration file defaults to /etc/httpd.conf. If you specify the -r parameter, but do not specify a fully qualified file name, the path for the configuration file defaults to the /etc directory. BLQPARMS Path and file name:____________________________________________________________ Web Access configuration file. Loaded into an HFS directory during the SMP/E install. Pointed to by the INFOMANWEBTOOLKITCONF= keyword in the httpd.envvars file. The Web Access-supplied file is BLQPARMS and is installed in the /usr/lpp/InfoMan/web/samples directory. HTML Path:_______________________________________________________________________ Contains the HTML used by Web Access. Contains subdirectories js/, css/, and images/. The Web Access installation directory is /usr/lpp/InfoMan/web/html. REXX Path:_______________________________________________________________________ Contains the REXX programs used by Web Access. The Web Access installation directory is /usr/lpp/InfoMan/web/rexx. a. See Chapter 10, “Setting Up Your BLX-SP,” in Tivoli Information Management for z/OS Planning and Installation Guide and Reference, Version 7.1, GC31-8751 (BLGP2E10). b. Typically, there is one load library that contains the Information Management for z/OS code and one or more load libraries that contain your code (such as program exits and session members). Include all the PDSs here and use them whenever you are instructed to add SBLMMOD1 to the //STEPLIB, for example. Browse your BLX-PROC for a STEPLIB. If it uses a STEPLIB, note each data set. If it does not have a STEPLIB, then SBLMMOD1 is in LINKLIST. c. It is possible that two different PDSs are used for the Information Management for z/OS and Web Access parts during the SMP/E install. To see if a PDS is shared (recommended) by the two products, browse the PDS. Web Access members begin with the letters BLQ, and Information Management for z/OS members with BLG and BLM (also BLH and BTN, but BLG and BLM are the key prefixes). If you find BLQ members along with BLG or BLM mem- bers, or both, in a PDS, the two products share the PDS. If the PDS does not contain both member prefixes, contact your local SMP/E expert to obtain the PDS names used. d. See Appendix D, ”Defining Tivoli Information Management for z/OS Session-Parameters Members,” in Tivoli In- formation Management for z/OS Planning and Installation Guide and Reference, Version 7.1, GC31-8751 (BLGP2E10). e. You can put your data records (problem, change, and so on) and your data model records into the same data- base. It is also possible to have your data model records in databases different from your data records. Putting all the records into one database simplifies the installation of Web Access. Using different databases can make it eas- ier to move your Web Access application from your development/test system to your production system. If your data model records are not in the same database as your data records, your data session needs to refer to the MOD- ELDB parameter (also see Footnote d).2.3 Customizing your Information Management installation The following steps assume that Information Management for z/OS Version 7.1 has been fully installed using the steps in Chapter 1 of the Tivoli Information Management for z/OS Planning and Installation Guide and Reference, Version 7.1, GC31-8751 (BLGP2E10). Many of the steps here reference back to this guide and to the Tivoli Information Management for z/OS Operation and Maintenance Reference, Version 7.1, SC31-8749 (BLGO1E10). You should also have available Table 2-2 on page 12 that you completed at the beginning of this chapter.14 IBM Tivoli Web Access for Information Management
    • 2.3.1 Update your session member Web Access requires that you use TEXTAUDIT=NO (the default) on the BLGPARMS macro of your session. See BLG-Source in Table 2-2 on page 12 for the location of your session member source. If you are using TEXTAUDIT=YES, change it to NO and reassemble and relink your session member. Also see See Appendix D, “Defining Tivoli Information Management for z/OS Session-Parameters Members,” in Tivoli Information Management for z/OS Planning and Installation Guide and Reference, Version 7.1, GC31-8751 (BLGP2E10).2.3.2 Update your BLX-SP parameters Web Access requires that APISECURITY=OFF be used in your BLXPRM member. See BLXPRM in Table 2-2 on page 12 for the location of the BLX-SP parameters member. Also see Appendix E, “Defining BLX-SP Parameters Members,” in Tivoli Information Management for z/OS Planning and Installation Guide and Reference, Version 7.1, GC31-8751 (BLGP2E10). You should specify a value for APICHKOUTLIMIT in your BLXPRM member. A 30-minute (APICHKOUTLIMIT=00300000) or 60-minute (APICHKOUTLIMIT=00600000) value is recommended. You should also specify DBCS=NO in your BLXPRM member. If any values in the BLXPRM member were changed, stop and restart the BLX-PROC.2.3.3 Update your IBM panels You must edit the JCL executing the Information Management for z/OS utilities that load the panels as described in the following steps: 1. Copy the sample JCL BLGUT6J from SBLMSAMP to a PDS in which you can edit and save your changes. Your might want to call this new JCL member BLQUT6, since it is used to load the Web Access panels into the IBM panels data set. Do not delete this PDS, because you will use this JCL in the future when you install maintenance for Web Access. 2. Edit your copy, following the comments in the JCL: a. Change the job card information. b. Update //STEPLIB to point to SBLMMOD1. c. Change DSN= on //BLGPDS DD to the SBLMPNLS data set. d. Change DSN= on //BLGPNLS DD to the IBM panels data set associated with your BLG-Source data session. 3. Submit the JCL and examine the output. There should be no error messages (it should complete with CC=0).2.3.4 Load the sample records into your data session Web Access ships several types of records, including privilege class records (for example, BLQALST), reference records (for example, BLQWALST), and message records (for example, BLQMAPPR) that must be loaded into your data session database. 1. Using TSO/ISPF, log on to Information Management for z/OS using your data session.9 2. If you are not in the Master privilege class, change to that class now. 9 See BLG-Source in Table 2-2 on page 12 for the name of your data session. Chapter 2. Installation 15
    • 3. At the Information Management for z/OS command line, enter the following command to load the records: RUN BLHRCDSL your_sblmrcds_pds BLQL5WEB REPLACE Replace your_sblmrcds_pds with your SBLMRCDS data set. The records should unflatten without errors.2.3.5 Load the data model records into your DMRDB session Web Access ships data view, data attribute, and data validation records that must be loaded into your data model record database. To do so, the data model record database (DMRDB) must be accessed as database 5 in the session member, since that is the read/write database.10 The DMRDB session may be the same as your data session. If you use the same session for data and data model records, use the data session in the following steps instead of the DMRDB session: 1. Using TSO/ISPF, log on to Information Management for z/OS using your DMRDB session. 2. If you are not in the Master privilege class, change to that class now. 3. At the Information Management for z/OS command line, enter the following command to load the data model records: RUN BLHRCDSL your_sblmrcds_pds BLQL4WEB REPLACE Replace your_sblmrcds_pds with your SBLMRCDS data set. The Web Access data model records should unflatten into your data model database without errors. 4. Web Access also requires data model records that ship with Information Management. At the Information Management for z/OS command line, enter the following command to load the Information Management records into your data model database: RUN BLHRCDSL your_sblmrcds_pds BLHLRBAS REPLACE Replace your_sblmrcds_pds with your SBLMRCDS data set. The Information Management data model records should unflatten into your data model database without errors.2.3.6 Create static data views from the data model records For best performance, you should create static data views from the data model records, as follows: 1. If you do not have a user RFTDD data set, you should allocate one now. 2. Copy the BLQUT18J sample JCL from SBLMSAMP to a PDS in which you can edit and save your changes. 3. Edit your copy, and following the comments in the JCL: a. Change the job card information. b. Update //STEPLIB to point to SBLMMOD1. c. Change the parameters on the EXEC card to match your Information Management for z/OS installation: i. CLASS—Typically MASTER ii. APPLID —Your user ID iii. SESS—The last two digits of your DMRDB session name. d. Change DSN= on //BLGRFT DD to the RFTDD data set. 10 See BLG-Source in Table 2-2 on page 12 for the name of your DMRDB session.16 IBM Tivoli Web Access for Information Management
    • 4. Submit the JCL and examine the output. There should be no error messages (it should complete with CC=0).112.3.7 Verify your Information Management customizations Using your data session, log on to Information Management for z/OS in TSO/ISPF and do the following: 1. Switch to the Master privilege class. 2. Enter the command UPDATE R rnid, where rnid is the record ID of your Master privilege class record.12 3. Select option 1 (Class Description Entry). 4. Enter Administrator into field 10 (Privilege Class Role). If you do not have a matching field 10, either you failed to install the Information Management for z/OS PTF to support Web Access for z/OS, or you have a customized version of panel BLG0J100. Use your PMF session to locate the BLG0J100 panel for use with Web Access and either add your modification to that panel or add the control information for field 10 to your customized BLG0J100. 5. If Administrator is accepted for the role, you have successfully loaded the panels and data model records for Web Access. If Administrator is not accepted, review the steps in 2.2, “Performing the SMP/E installation” on page 12. 6. File the record. 7. Now add your user ID to the following privilege classes: – BLQADMN – BLQALST – BLQSUPP – BLQMGT – BLQUSER If these classes are not found, review the steps you performed in 2.3.4, “Load the sample records into your data session” on page 15.2.3.8 Set up e-mail notification Web Access uses the Information Management for z/OS notification feature to send e-mail messages. You can disable Web Access notification, but as shipped, it is enabled. If you have not already set up e-mail notification for your Information Management installation, you must do so now. Copy the Information Management TSX BLGTNMAN (which is located in your Information Management SBLMTSX data set) to the TSX data set that contains your customized TSXs. Update BLGTNMAN with your SMTP server host name (or IP address) and port number. Review the other SMTP parameters in this TSX and update them as appropriate. You can find more details in “Defining TCP/IP SMTP Server Information (Editing the BLGTNMAN TSX)” in Tivoli Information Management for z/OS Program Administration Guide and Reference, Version 7.1, SC31-8753 (BLGS1E10). 11 Note: When you begin to customize data views for your own use, you will need to run this JCL. You can add or remove the data view names to //SYSIN DD * to control which data views will have static data views created. 12 Typically, the record ID is MASTER. Chapter 2. Installation 17
    • Web Access also supplies a set of message model records, which are listed in Appendix A, “Business logic examples” on page 123. At a minimum, you should update message records BLQMAPPR and BLQMRSET and replace yourhostname and yourport in the URL in the message text to refer to your Web Access host and port: http://yourhostname:yourport/IMWA/BLQWRGET.REXX?html_view=BLQ0C209.html&rnid_symbol=!S0CCF All of the message records include a From field for the send-from address that appears in your e-mail messages. As shipped, the records are set to a default of IMWA@hostname.com. You may want to modify the message records to specify a From address as appropriate for your installation. To update the message records, log on to Information Management. If you are not already in the Master privilege class, switch to that class. Use the UPDATE command or any method you are accustomed to using to update the message records.2.3.9 Configure your HTTP Server for Web Access Perform the following steps to ensure that the HTTP Server is set up properly for the Web Access application: 1. Verify the following information before proceeding with the HTTP Server setup for Web Access: a. Tivoli Information Management for z/OS v7.1 or later is installed and working. b. Perform the SMP/E install of Web Access. c. Verify that the Web Access components have been installed on the host system by making sure that you have completed the installation reference table in 2.2.1, “Installation reference table” on page 12. In that table, you should have identified the HTTP Server file names, data sets, and so forth to which you will be making changes for Web Access. d. If you have not already done so, copy BLQWAPII and BLQWAPIT from the Information Management SBLMREXX data set to your Web Access REXX directory (typically /usr/lpp/InfoMan/web/rexx). e. IBM HTTP Server for OS/390 Version 5.2 or later is installed and working in OS/390 UNIX System Services. Before making any changes to the HTTP Server, you should verify that the server is installed and active by entering the following URL in your browser address window: httpd://your_host_name_or_ip_address:your_port_number/ Note: Here you should substitute your actual host name (or IP address) and port number. A port number (:your_port_number) is needed only if you are using a port other than 80 for your Web server. After entering this URL in your browser address window, you should receive an IBM HTTP Server Web page. If not, you will need to stop the Web Access install process and determine why this page did not successfully load. For more information about setting up the IBM HTTP Server for OS/390, refer to IBM HTTP Server Planning, Installing, and Using, SC31-8690 for Version 5.2, or SC34-4826 for Version 5.3.18 IBM Tivoli Web Access for Information Management
    • 2. Have your RACF administrator perform the following RACF functions: a. Define the IMWAUSER surrogate user ID: Create this surrogate for users accessing the Web server started task for Web Access. This surrogate will be used in UNIX to serve requests made by Web Access users. Determine the default group to which the user should be defined (or add a new group). The UID does not need to be 0. The default group must have a GID. At a TSO command prompt, type the following information: ADDUSER IMWAUSER - DFLTGRP(EXTERNAL)OMVS(UID(xxx)Home(/)PROG(/bin/sh)) - NOPASSWORD OWNER(________) If the default group does not have a GID, perform the following: ALTGROUP EXTERNAL OMVS(GID(xxx)) b. If this is a new started task for the Web Access Web server, define the started task to RACF. The following assumes that the group STCGRP already exists: ADDUSER WEBSRV DLFTGRP(stcgrp) OWNER(_____) NOPASSWORD Define the started task to the RACF STARTED class. The following assumes that the group STCGRP already exists. The GROUP here needs to be the same as the DFLTGRP on the ADDUSER in the previous step: RDEFINE STARTED WEBSRV.* OWNER(stcgrp) STDATA(USER(WEBSRV) GROUP(stcgrp) TRUSTED(NO)) SETR CLASSACT(STARTED) RACLIST(STARTED) Or SETR REFRESH RACLIST(STARTED) c. Permit the Web Access USER access to the Web server, where WEBSRV is the user ID of the started task: RDEFINE SURROGAT BPX.SRV.IMWAUSER UACC(NONE) OWNER(_______) PERMIT BPX.SRV.IMWAUSER CLASS(SURROGAT)ID(WEBSRV)ACCESS(READ) SETR CLASSACT(SURROGAT) RACLIST(SURROGAT) Or SETR RACLIST(SURROGAT)REFRESH Note: These constitute the basic tasks required to start a Web server started task. There are other considerations in starting a new Web server started task. Refer to IBM HTTP Server Planning, Installing, and Using, SC31-8690 for Version 5.2, or SC34-4826 for Version 5.3, for a complete list. d. If the JESSPOOL RACF class is active, have the RACF security administrator permit access to the WEBSRV spool data for the appropriate people. e. If you are running with RACF Program Control support activated, ensure that Program Control is turned on for the SBLMMOD1 data set: RALTER PROGRAM RADDMEM(your_SBLMMOD1_dataset_name//NOPADCHK) UACC(READ) SETROPTS WHEN(PROGRAM)REFRESH Note: It is assumed that WEBSRV is the user ID assigned to your Web server started task. This user ID appears in the RACF commands and was defined or decided upon when you installed the HTTP Server. Chapter 2. Installation 19
    • f. Web administrator and UNIX access bits: When the SMP/E install was performed, and the files were placed into the HFS directory, the file owner was probably set to UID 0 and the access mode bits were set to 755, which are the typical SMP/E default values. The Web Access administrator will be allowed to edit and build HTML by Web Access.13 However, unless this user ID is also a super user, it will not be able to update the files in the HTML directory. To avoid the need to be a super user in order to update these files, do one of the following: i. Have the file owner set the access mode to 775. This will allow users with the GID to update the files. It may be necessary to use the chgid command to set the group to a group that the Web administrator is permitted to use. ii. Have the file owner change the owner to your user ID. Then, you can use the chggid command to permit group access to the files. iii. Create a directory of your own. Copy all of the files and subdirectories in /html to your directory. Create the softlink for IMWX00.so in your directory and update the Pass and Service directives in the httpd.conf file to point to your directory. Also update html_path in the BLQPARMS file to point to your directory. You may want to have your RACF administrator set up a group for Web Access administrators. 3. Update the WEBPROC and add a //STEPLIB pointing to SBLMMOD1 if SBLMMOD1 is not in LINKLIST. 4. Create an external link to the GWAPI REXX DLL, IMWX00. From an OS/390 UNIX System Services session, enter the following: ln -e IMWX00 /usr/lpp/InfoMan/web/html/IMWX00.so 5. Modify your HTTP Server configuration file (httpd.conf) to include the following Web Access directives: Protection IMWAmaster { AuthType Basic Mask All PasswdFile %%SAF%% ServerId Restricted UserID %%CLIENT%% } Protection IMWA { AuthType Basic Mask All PasswdFile %%SAF%% ServerId Restricted UserID IMWAUSER } Protect /IMWA/* IMWA Protect /IMWAmaster/* IMWAmaster Note: For this Web Access Protection directive, the %%CLIENT%% can or should be the surrogate ID. If you decide to use %%CLIENT%%, your users must have an OE segment defined for each user ID. If you use the surrogate ID, though your users will not need an OE segment, the surrogate ID will. 13A Web Access administrator is any user ID that is defined in the privilege class record identified by the admin_class parameter in your BLQPARMS configuration file. Typically, the privilege class record is BLQADMN.20 IBM Tivoli Web Access for Information Management
    • 6. Modify your HTTP Server configuration file (httpd.conf) to include the following Web Access directives. Important: The lines that follow must each appear on one continuous line and are case-sensitive. a. The ServerInit BLQWCINI directive is used to parse the BLQPARMS file. BLQPARMS is described in the next section. ServerInit /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWCINI b. The ServerInit BLQWAPII directive is used to initialize the API for multitasking mode: ServerInit /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWAPII c. The ServerTerm BLQWAPIT directive shuts down all of the threads in a multitasking API environment, and the ServerTerm BLQWCTRM directive cleans up and releases data areas established by the BLQWCINI directive: ServerTerm /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWAPIT ServerTerm /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWCTRM d. The Map directive allows lowercase REXX extensions to be processed in the same manner as uppercase. This Map must appear before the first Service directive for *.REXX. The Service directives allow the GWAPI to be called to run the REXX routines that make up Web Access: Map /IMWA/*.rexx /IMWA/*.REXX Service /IMWA/*.REXX /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWSWRT/*.REXX Service /IMWA/*.BIN /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWSWRT/*.BIN Service /IMWAmaster/*.REXX /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWSWRT/*.REXX e. The Pass directives allow the Web server to locate the static (HTML, JavaScript) files used by Web Access and to support the use of attachments. The Pass for attachments must appear before the Pass for the document root as in the following: Pass /IMWA/attachments/* /usr/lpp/InfoMan/web/tmp/* Pass /IMWA/* /usr/lpp/InfoMan/web/html/* Pass /IMWAmaster/* /usr/lpp/InfoMan/web/html/* The /usr/lpp/InfoMan/web/tmp/ path on the Pass directive for attachments can be any read/write directory in the HFS, but the path must match the value coded in the BLQPARMS configuration file on the attachment_path keyword. You must create the directory and set the access mode to 777. f. Add a Welcome directive for the Web Access welcome page: Welcome BLQINDEX.html g. Locate the AddType .txt directive and change it to the following to allow your users to be able to attach and retrieve text files (add this directive if it is not already in your httpd.conf file): AddType .txt text/plain 8bit 0.5 # Plain text You will also need to add or change the following AddType directives in your httpd.conf file: AddType .css text/css ebcdic 1.0 # W3C Cascading Style Sheet Chapter 2. Installation 21
    • AddType .js text/plain ebcdic 1.0 # Javascript files h. To allow for additional information regarding error handling, you may choose to add the following statements to the httpd.conf file: AccessLog /usr/lpp/InfoMan/web/logs/httpd-log AgentLog /usr/lpp/InfoMan/web/logs/agent-log RefererLog /usr/lpp/InfoMan/web/logs/referer-log ErrorLog /usr/lpp/InfoMan/web/logs/httpd-errors CgiErrorLog /usr/lpp/InfoMan/web/logs/cgi-error If desired, substitute your own file paths for the paths listed above. Note: The log files are shared by all Web applications running on the HTTP Server. If the Web server is being used for other web applications, changing these log directives may interfere with the other web applications. Before making changes to these log directives, you should check with the other HTTP Server application users. Normally, Web Access will be running on an HTTP Server by itself (at least during development), so you can associate the above directives with your own file paths. 7. Modify your HTTP Server environment variables file (httpd.envvars): a. Modify the PATH statement to specify where to find the REXX routines (EXECs) used with Web Access. The following is an example of what your path statement might contain: PATH=/bin:.:/usr/lpp/internet/bin:/usr/lpp/InfoMan/web/rexx b. Add the following statement: INFOMANWEBTOOLKITCONF=/usr/lpp/InfoMan/web/BLQPARMS2.3.10 Update your BLQPARMS file Once you have completed the HTTP Server changes, you will need to update your BLQPARMS file. The BLQPARMS file in use is pointed to by the INFOMANWEBTOOLKITCONF= keyword in the httpd.envvars file. Following are some of the required parameters in BLQPARMS that need to be modified: session_member—Change to reflect the name of your BLGSESxx data session. tsx_dsname —Change to reflect the names of your TSX and SBLMTSX data sets. Include a tsx_dsname parameter for each data set. rft_dsname—Change to reflect the names of your RFTDD and SBLMFMT data sets. Include a rft_dsname parameter for each data set. error_log_path—This needs to be the same as the path defined in your ErrorLog directive in the httpd.conf file. attachment_path—This must match the Pass directive for attachments in your httpd.conf file. The default directory is /usr/lpp/InfoMan/web/tmp/, but any read/write directory in the HFS can be used. You must create the directory and set the access mode to 777. max_attachment_size—Set to the maximum size of an attachment. The default limit is 1048576 (1 MB). Refer to “Updating the configuration file” on page 164 for more information about the BLQPARMS file.22 IBM Tivoli Web Access for Information Management
    • 2.3.11 Start the HTTP Server If you are starting the HTTP Server as a catalogued procedure, add the Information Management for z/OS SBLMMOD1 data set and your session member load library into your STEPLIB concatenation. If you are starting the HTTP Server from a UNIX session, be sure to include all of the previously-mentioned data sets in its STEPLIB global variable. If the HTTP Server is currently active, stop and restart it. Otherwise, start the HTTP Server.2.3.12 Verify your Web Access installation Open your Web browser and enter the following: http://yourhostname:yourportnumber/IMWA/ The Web Access welcome page should appear in your browser. If %%CLIENT%% was coded as the user ID in the http.conf file, you have to enter a valid user ID and password before seeing this page. On the Welcome page, click the Web Access logo. If you have not already entered your user ID and password, you should be prompted to enter them now. If this is the first time you have used Web Access, you should be taken to a page where you can create and update your Web Access profile. After entering your profile data, you should be taken to the home page (BLQHOME.REXX). If you are not taken to the profile create and update page or the home page after completing your profile, type the following in your browser: http://yourhostname:yourportnumber/IMWA/BLQADMIN.html This should take you to the administration page, where you can click the Test Web Server link to determine what might be wrong. This link verifies that the various configuration files can be found, that the paths to the routines are correct, and that the Web server can access the Information Management for z/OS database. If you experience problems, you can start the HTTP Server with the -v (verbose) or -vv (very verbose) parameters, which can help you to diagnose problems. Note that the use of these parameters can adversely affect your system performance. You can also refer to the HLAPILOG, APIPRINT, and the various error logs listed in the httpd.conf file (for example, the httpd-errors log file). To obtain the HLAPILOG and APIPRINT, you will need to add HLAPILOG and APIPRINT DD statements to your Web server PROC. For APIPRINT, output to a data set is not supported, so the DD statement must point to SYSOUT instead. The HLAPILOG can be coded to go to SYSOUT or a data set. If a data set is used, specify DISP=MOD. In addition, you will need to set the following parameters in your BLQPARMS configuration file:14 hlimsg_option—set to B apimsg_option—set to B spool_interval—set to a value greater than 0 debug – api—set to on Once you are taken to the home page, you should be able to use the Administer Web task and generate the HTML before you attempt to create records. If you do not see an Administer Web hyperlink, you did not add your ID to the BLQADMN class. 14 Refer to Appendix C, “Web Access configuration parameters” on page 163 for additional information regarding the configuration file. Chapter 2. Installation 23
    • 2.3.13 Generate HTML Web Access ships HTML for the following record types: Incident Problem Change Activity Request Work People Solution To make sure that the HTML includes the latest changes made to the data views for these record types, select the Create HTML using the Auto Build File button on the Web Administration page (see Figure 2-1).Figure 2-1 The Web Administration page24 IBM Tivoli Web Access for Information Management
    • Refer to the Create HTML section of Figure 2-1 on page 24 and locate the Create HTML using the Auto Build File? Yes button. Click that button and the build process begins. That process can take up to 15 minutes, so be patient. The process provides a message telling you what data view record is currently being processed so that you can see that it is working and making progress. You will receive output similar to the output in Figure 2-2. If you get an error or the page is not updated or remains blank, make sure that your user ID has write authority to html_path and the HTML files in that directory (access mode of 775).Figure 2-2 Sample HTML build output Web Access ships an Auto Build file called BLQBATCH, which contains the necessary information to rebuild all the Web Access shipped HTML. You should never modify the BLQBATCH file directly. Tools are provided to dynamically modify or create various Auto Build input parameter files. For additional information about using the HTML generator or this Auto Build process, please refer to Chapter 6, “Generating user application HTML” on page 63. Chapter 2. Installation 25
    • After you receive the Auto Build HTML Completed message from the Auto Build process, make sure to use the Return to BLQADMIN link to return to the Web Administration page. Otherwise, if you use the browser’s Back button, the Auto Build process will run again. From the Web Administration page, you can return to the Home page and create records using the generated HTML. Common errors Please note the following common errors: If you cannot generate HTML or edit files using the Web, make sure that your user ID has write authority to html_path and the HTML files in that directory (access mode of 775).15 If you are unable to attach an image to your people record or a file to a record, make sure that you created a temporary directory. Check the attachment_path in the BLQPARMS file. The access mode for this directory should be 777. If you attempt to create or update a record, and when you click FINISH you get a failure, make sure you set up notification.16 If you do not have a Switch Role hyperlink on a home page, make sure that your user ID is in more than one privilege class. If you do not have an Administer Web hyperlink on your home page, your user ID is not in the BLQADMN class. Note that you cannot switch to that class. It is only used to verify that a user ID can perform Web administration functions. 15 See the UNIX access mode bits information in 2.3.7, “Verify your Information Management customizations” on page 17. 16 See 2.3.8, “Set up e-mail notification” on page 17.26 IBM Tivoli Web Access for Information Management
    • 3 Chapter 3. Enabling your community Access to Web Access, the actions a user can perform, and processing within Web Access are controlled by privilege classes. The privilege class a user is currently running in determines the user’s Web Access home page and the authorities the user has to certain records. Other privilege class records are used for special Web Access processing, including identifying whether you are authorized to perform Web Administration tasks. You should evaluate the privilege class records that Web Access provides, understand the privilege class roles, and determine whether you want to use them. This chapter discusses the Web Access privilege class records and provides information about how to set up your community to use them. If you decide that you would prefer to use your own privilege class records or define your own privilege class roles, or both, refer to Chapter 8, “Using existing privilege class records” on page 83.© Copyright IBM Corp. 2003 27
    • 3.1 Assigning privilege class users and roles After you have successfully installed Web Access, you can enable your user community to use it. To do so, you will need to work with privilege class records and so you must be authorized to access them. Preferably, you should log on to Information Management using your data session and run in your Master class. Refer to the Tivoli Information Management for z/OS Program Administration Guide and Reference, SC31-8753 (BLGS1E10) to familiarize yourself with basic privilege class administration, such as managing eligible users. Web Access ships a set of privilege class records that we installed in Chapter 2, “Installation” on page 9. Some of these records determine the users home page and the record tasks the user is authorized to perform (in the same manner as on 3270), while others are used solely by Web Access to perform behind-the-scenes work. The classes used to perform record functions that also determine the user’s home page and authority over certain records are as follows: BLQALST—Analyst role BLQMGT—Manager role BLQSUPP—Support role BLQUSER—User role The following classes are used behind the scenes: BLQADMN—The behind-the-scenes class that determines whether you are allowed to perform Web Administration tasks 17 BLQWORK—The class used to perform behind-the-scenes Web work 18 By default, the Web Access privilege classes specify an eligible user of either IMWAADM, IMWAUSER, or IBMUSER. As the administrator, you should add your own TSO user ID to all Web Access classes except BLQWORK. If you followed the steps in Chapter 2, “Installation” on page 9 and performed those detailed in 2.3.7, “Verify your Information Management customizations” on page 17, you will already have added your user ID to these classes. BLQADMN is a special privilege class used by Web Access solely to determine who is entitled to perform Web Administration tasks. It does not contain any Information Management authorities. It only contains the TSO user IDs that you want to have Web Administration capabilities. Any user in this privilege class will see an Administer Web hyperlink in the navigation area on the left side of the Web Access home page. This link takes you to the page where you perform Web Administration tasks.19 If there are users other than yourself who should have Web administration capability, you should add them to the eligible user list for BLQADMN. BLQWORK is also a special privilege class. It is used to do behind-the-scenes processing required by Web Access not directly requested by the user. One example is that BLQWORK is used to determine the users date format and time zone specifications from the user’s people record (profile). Because no Web Access users perform work with BLQWORK, no one needs to be included in the eligible user list for BLQWORK. 17 The Web Administration class is identified by the admin_class parameter in your Web Access configuration file. As shipped, BLQADMN is the default. 18 The Web Access work class is identified by the work_class parameter in your Web Access configuration file. As shipped, BLQWORK is the default. 19 See Chapter 12, “Web administration” on page 115 for additional information.28 IBM Tivoli Web Access for Information Management
    • Although BLQUSER20 is a privilege class used by some users, it is also a special class ofsorts. BLQUSER has very basic authorities. If a user logs on to Web Access for the first timeand is not in any privilege class, this user will be placed in BLQUSER. BLQUSER is also usedby Web Access to perform privilege class checks for users, such as checking to see if theuser is in a class and what authorities a given class has. Since users will automatically beadded to BLQUSER if they are not in any other privilege class, you do not need to add themto this class. But if a user is in another privilege class, and you also want that user inBLQUSER, you will need to add that user.The following parameters are in your Web Access configuration file (BLQPARMS). Asshipped, they are set to the following values. Refer to Appendix C, “Web Access configurationparameters” on page 163 for more information about these parameters. application_id—IMWAUSER privilege_class—BLQUSER admin_class—BLQADMN word_id—IMWAADM work_class—BLQWORKIMWAUSER and IMWAADM are not TSO user IDs and require no special RACF setup. If youdo not like those names, you can change them in your Web Access configuration file and inthe eligible user lists in the privilege class records. The only places that these entries show upis in the HLAPI log and in the record history for the privilege class identified by theprivilege_class parameter when Web Access adds a user to that class. New people recordsare also created using the ID identified by work_id.The privilege_class, admin_class, and work_class parameters identify privilege class recordsBLQUSER, BLQADMN, and BLQWORK. You can use these records or change them. Theyprimarily show up in the HLAPI log. One special note about the admin_class is that, since itsonly use is to identify the users entitled to perform Web Access administrative tasks,whatever class you specify for it will not appear in the list of classes to which you can switchroles on your Web Access home page. Therefore, we recommend that you do not specify anyprivilege class used to provide record access (including your Master class) as theadmin_class, since you will be unable to switch to that class.BLQMGT, BLQALST, and BLQSUPP are other classes into which you may want to put youruser. Each of these classes (as well as BLQUSER) has a unique home page on Web Accessthat provides a set of functions specific to the role associated with that class: BLQMGT is the class for managers. BLQALST is the class for users who create or update records on behalf of other users (for example, help desk analysts). BLQSUPP is the class for users who need to resolve problems assigned to them and to implement changes (for example, application programmers or production control operators).You can also define your own roles and use your own privilege class records as well. You mayalso want to modify lookup reference records to provide your own set of canned searches thatappear on a particular home page. These topics are described in Chapter 8, “Using existingprivilege class records” on page 83.20The class is identified by the privilege_class parameter in your Web Access configuration file. As shipped,BLQUSER is the default. Chapter 3. Enabling your community 29
    • Remember that prior to Information Management Version 7.1, the product, as shipped, only allowed 24 users per privilege class, so you may have had many privilege class records filling the identical purpose just to accommodate additional users. Starting with Version 7.1, nearly 20,000 users are permitted in each class. So, if you plan to use your own privilege class records, now may be a good time to consolidate and merge your classes.30 IBM Tivoli Web Access for Information Management
    • Part 2Part 2 Customization Part 2 covers the following topics: Implementing a Web solution using Web Access Building a customized Web application Generating user application HTML Converting a 3270 application Using existing privilege class records Using shadow s-words and data attribute records Type-based HTML Updating the style file© Copyright IBM Corp. 2003 31
    • 32 IBM Tivoli Web Access for Information Management
    • 4 Chapter 4. Implementing a Web solution using Web Access Web Access is record- and search-centric. Generally, some type of search is done and records are located in the Information Management for z/OS database. The located records are accessed one at a time. Based on data in the record and the authority or role of the user, HTML is used to present the record. The Web user chooses the next record or a different HTML view of the current record. As the user moves from page to page, Web Access can dynamically change the data or HTML used to display the record based on logic that your process requires. This logic is known as business logic. Business logic is also used to relate one record to another. If the user changes any data, Web Access validates that data before the user is allowed to continue. If your process is not record-specific, or it requires access to data outside the Information Management for z/OS database, it will be difficult to implement using Web Access. However, data stored in the UNIX System Services HFS or an MVS data set is easily accessed using Web Access. For a given Information Management record type that you want to access using Web Access, you need: Data model records (data view, attribute, and validation) HTML for display and print, update, create, copy, and search Definitions in the BLQPARMS configuration file to support the record type Business logic to control how the records will be processed and the relationship of this record to other records in the database© Copyright IBM Corp. 2003 33
    • 4.1 Data model record overview The first thing that you need to build are the data model records for your Web solution. If you are not familiar with data model records, spend some time reading Chapter 29 in Tivoli Information Management for z/OS Panel Modification Facility Guide, Version 7.1, SC31-8750 (BLGP6E10). It is essential that you understand data model records before you proceed. Since you might decide to use them or model yours based on them, you should also familiarize yourself with the Web Access-supplied data model records. You should never modify these. Instead, always make a copy and work with that. If you have a 3270 application that you want to convert to the Web, Chapter 7, “Converting a 3270 application” on page 71, provides information about how you can automatically create the data model records for that application and how you should modify them to work with Web Access. When you work with a data view record, you should think of the items on the panel layout panel as the tasks you want to be able to perform with your record. Associated with each item is the data that you want to appear on the HTML page for that particular task. Figure 4-1 shows the items on the Panel Layout Definition panel for the Web Access data view, BLQVPROB. Figure 4-1 Panel Layout Definition panel When you generate the HTML for a data view, you choose the panel layout items that you want to appear as tasks on the HTML page. In the HTML generated for this data view (Figure 4-2 on page 35), you can see the correlation between the items on the Panel Layout Definition panel and the tasks that appear in the navigation area on the left side of the Web Access page. In this example, display-mode HTML was generated for all of the panel layout items except Audit Information, which only applies to search-mode HTML.34 IBM Tivoli Web Access for Information Management
    • Figure 4-2 Display-mode HTML page for the Summary task Figure 4-2 shows the display-mode HTML page that was generated for the Summary task. Notice that the fields and information shown on the page are based on the data that was associated with the Summary panel layout item in the data view record. For additional information regarding data model records, refer to 5.2, “Data model and HTML considerations” on page 43, which contains information you should consider as you build data model records for your Web Access application. Chapter 7, “Converting a 3270 application” on page 71 also contains general information of interest to anyone working with data model records. When you are ready to generate the HTML for your data model records, refer to Chapter 6, “Generating user application HTML” on page 63, which explains this process. Chapter 4. Implementing a Web solution using Web Access 35
    • 4.2 BLQPARMS definitions needed to support a record type The Core REXX routines supplied by Web Access handle displaying (and printing), updating, creating, and searching for a record type. To do this, each record type that will be accessed by Web Access must be defined using a record_type entry in the BLQPARMS file. The record_type and its associated keywords define the type of record, the transactions that can be performed on that record type, and the views (HTML and data view/PIDTs) used for that record type. Besides the record s-word index, you will need the following in order to support a given record type: The transactions to be supported The data view or PIDT name to be used for that transaction The HTML file name to be used as the first page for that transaction The transactions are as follows: Copy Create Retrieve Search Update Any transactions you omit will not be processed by Web Access. You can use data views or PIDTs. Data views are recommended and required to generate HTML and when updating or creating a record. It is possible to use a PIDT for the other transactions; however, mixing data views and PIDTs can easily lead to confusion. Start by coding the record_type keyword that defines the name of the record type, the record s-word index, and the unique HTML qualifier (P in this case, but you can use multiple letters, such as PRB if you want): record_type PROBLEM S0032 P Then, specify a data view and HTML file for each transaction you want to support. Because you are using a data view, append _view to the transaction to denote that a data view is used, as in create_view, where create is the transaction and _view indicates that a data view is used on the create. The HTML file should be the first page that you want to appear for that transaction. Example 4-1 Specify a data view and HTML file record_type PROBLEM S0032 P create_view BLQVPROB BLQ0P001.html update_view BLQVPROB BLQ0P101.html retrieve_view BLQVPROB BLQ0P200.html search_view BLQVPROB BLQ0P301.html BLQWSRLP.html copy_view BLQVPROB BLQ0P001.html If you will be supporting search, you should also code an SRL HTML file on the search transaction. This SRL HTML file will be used to display the records in the search results list. If you do not code an SRL HTML file, the SRL HTML from the find_all_xxxx parameter in the configuration file is used.36 IBM Tivoli Web Access for Information Management
    • Within a record_type, the order and the indentation of the transactions are not important. If you duplicate record_type entries or transactions, the last one is used. A record_type and its transactions are ended when the next record_type is found (or end of file). In Example 4-1 on page 36, the BLQVPROB data view is used for each transaction, but this is not required. You can use different data views for different transactions. For example, you would very likely want to use a different data view for copy_view, since using BLQVPROB would copy all the data from the source record to the new record. Typically, you want to copy only selected fields from the source record to the new record. You do that by creating another data view that contains only the data attribute records that define the fields you want to be copied. You do not have to use the same data view that you used to generate the HTML with these transactions. Just be careful that the data view you are using has the same data attribute records as the data view you used to generate the HTML. You might find it handy to generate test HTML using a copy of your data view as follows: 1. Copy your current data view. 2. Update the copy, making changes related to the layouts and the groups. 3. Generate the HTML using that copy. 4. Test those changes without updating the transactions in record_type. Note: Until you generate your HTML, you may not know the HTML file names to specify in the transaction directives. While this information is required in order to run your Web Access application, it is not required to build the HTML for that application. Once the HTML files have been generated, you can then update your configuration file with the appropriate transactions and actual HTML file names. Initially, you may want to include a record_type directive in your configuration file with no transactions. When you include a record_type directive, the HTML generator will use the HTML qualifier for that record type in the default HTML file names. If there is no record_type that matches the s-word index for the data view for which you are generating HTML, the default HTML file names will be comprised solely of the HTML prefix you choose and the layout index number. Although the HTML build process generates a default HTML file name for using these rules, you can always change that file name to one you want. Simply overtype the HTML file name that was generated for you on the Create HTML Web page.4.3 Business logic There are numerous places where you can perform business logic: Predisplay user exit—Data can be added or removed from a record being viewed (update, create, display, print). You can also change which HTML file will be used to view the record. Validation user exit—Enables you to add or remove data when the user is updating or creating a record and enforces your process. Post-file user exits—After the file, you can do additional processing. TSXs—Called from any of the business logic user exits. TSXs or TSPs—Called by the record update or record create coded in a data view. JavaScript in the HTML—Used in auto-filling fields, navigation, help processing, and validating required fields. Chapter 4. Implementing a Web solution using Web Access 37
    • The home page—Controls what is displayed when the user clicks home (home_page_exit). Which of these you will need to use or modify depends on the requirements of your process. The exits and the home page have full access to the Information Management for z/OS database. The exits can use predefined functions, TSXs, or you can write your own REXX modules. Web Access creates the JavaScript needed to navigate page-to-page, display field-level help, and check required fields. Any additional JavaScript you wish to write can be used. Additional information about writing business logic exit routines is in 5.3, “Integrating business logic into your application” on page 47. The business logic used by the drop-in problem and change management Web solution is documented in Appendix A, “Business logic examples” on page 123. You can use that information as examples of how to write your own business logic.4.3.1 Predisplay user exit When the user chooses a record in create, update, display mode, Web Access reads data from the Information Management for z/OS database and places the data into a variable pool in the Web server memory. The predisplay user exit is called and allowed to examine and change the data in the variable pool. The predisplay exit can also override the HTML page that will be used to display the data. This allows different roles to use different HTML if needed. Note: When adding data to the pool in update or create mode, be sure the data is valid. Web Access will validate this data and, if invalid, will stop the update or create processing. However, because the invalid data was added by the exit, the user will have no idea what is wrong.4.3.2 Validation user exit In update or create mode, Web Access uses the Information Management for z/OS HLAPI to validate the data the user typed, data that was copied, or data that was added in a user exit. If the Information Management for z/OS HLAPI indicates the data is valid, Web Access places the data into a variable pool and calls the validation user exit. This can examine, change, add, or remove data from the pool. The validation exit can also override the HTML page used to display the data. Typically, the validation user exit is used to test conditionally required fields or do calculations, such as the number of days the record was open. The bulk of the logic needed to control your process will be included in the validation user exit. Note: If the Information Management for z/OS HLAPI finds invalid data, Web Access will flag the fields that the HLAPI indicated were invalid. The variable pool remains unchanged, and the validation exit is not called. Instead, error HTML indicating what is wrong with the data is displayed to the user.38 IBM Tivoli Web Access for Information Management
    • 4.3.3 Post-file update and create user exits After a record is updated or created, Web Access also calls exits. These exits have access to the data that was just used to update or create the record. However, if the exit changes the data in the variable pool, those changes will be ignored, since the record has already been filed. The post-file user exits typically are where you would update related records or do e-mail notification. The main difference between the post-file update exit and the post-file create exit is that the record that was updated is still checked out until the post-file update exit completes. But the record just created prior to execution of the post-file create exit is not checked out. Therefore, if your business logic must update the created record, it will have to perform check-out and check-in processing.4.3.4 TSXs and TSPs used by business logic TSXs (and in some cases TSPs) can be used for business logic. Either can be invoked from any of the Web Access user exits, or from a data view (Create record file time TSP and Update record file time TSP) by Information Management for z/OS. TSXs are preferred and are more flexible than TSPs when it comes to getting data (GetAPIdata) from Web Access and returning data (SetAPIdata) to it. Web Access itself uses TSXs. However, existing Information Management for z/OS users can review their TSPs and see if they can be reused. Often a TSX can be used to get data from Web Access, place that data into the TSCAVDA, and LINK to an existing TSP. Then when the TSP completes, the TSX can examine messages or other items related to the TSP and return them for use by the business logic. Little or no change to the TSP would be needed. However, each TSP is different and will have to be reviewed. The only limitation on what you can do with a TSX is your coding ability and the time it takes to process. Keep in mind that whatever processing your TSX does will have to complete before the Web user will see the next HTML page. Avoid doing large amounts of processing. Instead, use Information Management for z/OS resource queues and server address spaces for complex processing. Queued e-mail notification is an example of this. You can also submit job control language (JCL) from Web Access or from a TSX. Using UNIX System Services, Web Access can also write a message (WTO) to the MVS console where automation can occur. For examples, see Appendix A, “Business logic examples” on page 123.4.3.5 JavaScript in HTML Web Access itself does not execute JavaScript (Web Access is not server-side JavaScript). Web Access creates JavaScript that is executed by the browser (client-side JavaScript). This client-side JavaScript typically would set values into JavaScript variables. These variables are then used in JavaScript functions supplied by Web Access in .js files. The .js files are imbedded into the HTML using the src= on the <script> tags. For example: <script type=”text/javascript” src=”js/BLQJSSEL.js”></script> Imbedded JavaScript files are used for several reasons: They help performance, because the browser caches them once, and all pages that refer to JavaScript file use the cached copy. They allow functions to be written once, and these common functions are reused across all HTML pages. Web Access does not parse through or otherwise process these JavaScript files. This allows free use of single quotes. Note: Because the JavaScript is cached by your browser, any changes you make to the .js file may not take effect until you delete your temporary Internet files. Chapter 4. Implementing a Web solution using Web Access 39
    • JavaScript is very powerful and it should be used where needed. However, JavaScript can be difficult to code and debug. When JavaScript is used in the HTML processed by Web Access, less JavaScript is better. Save the advanced effects that JavaScript can add to HTML pages until last. Get your pages working and tested first. Then once all that work is complete, you can consider using some of the more advanced JavaScript techniques, such as pop-up calendars, sorting tables, and scrolling banners.4.3.6 The home page Web Access builds the home page using data from the users people record, the privilege class that the user is currently in, and data from a lookup record for the role determined by the privilege class. The basic functions for the Web Access-supplied home page are as follows: Determines if the user is in more that one privilege class. If so, enables the link to the switch role function. Checks if the current privilege class has a role. If so, locates the lookup record 21 for the role. If the class does not have a role, use the default role of User and the BLQWUSER lookup record. Using the lookup record RNID, adds a .html suffix, and then loads and processes the HTML page. For example, if the role is User, BLQWUSER.html would be loaded from the HTML directory (usr/lpp/InfoMan/web/html). Retrieves the lookup record and performs the searches defined in the lookup record. Adds the result of the search to the HTML along with the hyperlinks to produce a search results list. Enables links to allow searches and creates for the records over which the privilege class has authority. You can use a different name for your own home page routine. The BLQPARMS file parameter home_page_exit can be used to tell the Web Access routines what the home page routine name is in case you decide to create your own home page routine (some Web Access routines send the user to the home page). In addition to the home_page_exit parameter to change the home page routine, change the occurrences of BLQHOME.REXX in BLQJNAVM.js and BLQJNAVU.js. Because the home pages are generally referred to in HTML and JavaScript files, you can use other methods to create a home page. Static HTML can be used. 21 Lookup records are described in Chapter 8, “Using existing privilege class records” on page 83.40 IBM Tivoli Web Access for Information Management
    • 5 Chapter 5. Building a customized Web application To build a customized Web Access application, you can start with your own data view and data attribute (data model) records or use the ones supplied by Web Access. To help you decide, you should become familiar with the data view and data attribute records that Web Access supplies. Those data model records implement features of Web Access that you are likely to want to use in your custom Web application. If you decide to use modified versions of Web Access-supplied data model records, you should make a copy of them and work with the copy. You can either update your copies of the Web Access-supplied data view records, or add the Web Access-supplied data attribute records to your own data view records. In either case, you should use Web Access-supplied records to guide your customization. Web Access ships HTML and data view records for the following record types: Incident—BLQVINC Problem—BLQVPROB Change—BLQVCHNG Activity—BLQVACT Request—BLQVREQ Work—BLQVWORK People—BLQVPEOP Solution—BLQVSOL© Copyright IBM Corp. 2003 41
    • 5.1 Getting started After you become familiar with the data views supplied by Web Access, you should decide if you will use modified copies of these views and attributes or use your own data model records. If you decide to modify a Web Access-supplied data view or data attribute, start by copying it and giving it your own unique name. This way, you will not lose your modifications when Web Access-supplied data model records are updated by new releases or maintenance. You can use the COPY command to copy data views and data attributes just like any other records in the database. If you have a 3270 application that you want to convert to the Web, Chapter 7, “Converting a 3270 application” on page 71 provides information about how you can automatically create the data model records for that application. That chapter also has information of general interest to anyone working with data model records. Section 5.2, “Data model and HTML considerations” on page 43 contains information you should also consider as you build data model records for your Web Access application. Once you have created or decided on your data view names, update your BLQPARMS configuration file and specify your data view names on the appropriate record_type transaction directives. The record_type transaction directives also contain the name of the HTML file to use as the first page for the transaction, but until you generate the HTML, you may not know these names. When you do generate the HTML, update your BLQPARMS configuration file again to specify the actual HTML file names. Refer to 4.2, “BLQPARMS definitions needed to support a record type” on page 36 for additional information about setting up the record type parameters in your configuration file. Be sure to use the Reload Configuration File task on the Web Administration page to reload your configuration file whenever you make any changes to it (see Chapter 12, “Web administration” on page 115). When creating a custom Web application, you should start by building the display-mode HTML for each record type you will use. Oftentimes, you will want all of your fields to appear on the display HTML, so working with this mode first will help to identify and create all the data attributes that you will need. Since the organization of these fields across and within the layouts for display will often also match the appearance that you want for update and create pages, you may find that a layout you define for the display-mode HTML can also be used for the other HTML modes. As you proceed with create, update, and inquiry, you may see that the bulk of the work was already done preparing the display-mode HTML, and that you may only need to update the field usage information in the panel layouts. Another advantage to starting with display-mode HTML is that as you identify and build all of the data attributes for a particular record type, you may find that certain fields are common across your records types. So instead of creating new data attributes for another record type, you may be able to use the same data attribute records for the common fields. After you create the display-mode HTML using the panel layout information in your data views, you will have a better idea of what you want your users to see on the HTML pages that they will use to update or create records using Web Access. Generate the HTML for update next. Keep in mind required and display-only fields, such as record ID. Also keep in mind that some fields may not be needed on update. For example, you may want the Audit Information fields 22 to appear on display-mode HTML, but you would not want these fields to be available in update mode. The layouts for create are often nearly identical to those for update. Generally, it is only necessary to change a few usage fields in the layouts to allow the create-mode HTML to be generated. As you generate the HTML, add the HTML file names to your BLQPARMS configuration file so that you can test the HTML.23 For now, do not concern yourself with business logic or process flow. Focus instead on generating all of the HTML 22 For example, the date a record was created and the user who last modified it. 23 Remember to use the Web Administration page to reload the configuration file whenever you change it.42 IBM Tivoli Web Access for Information Management
    • pages that your application will need and make sure they are grouped or ordered in a manner that is understandable to your users. If you have existing 3270 screens, they can be used as a guide. Do not try and perfect the HTML at this time. Just get it generated to the point where you are able to view or update any fields that you need. Once you have the create, update, and display HTML generated and the corresponding record_type and transaction directives defined in your BLQPARMS configuration file, you can add the inquiry HTML. When doing so, try and include only the fields that your users are likely to use for search arguments. A single HTML page is often enough. After the HTML is created, you can add the business logic and decide what items you would like on your home page. The next few chapters and the remainder of this chapter describe those items in more detail.24 Once the business logic is written, and you have tested its functions, you can go back and perfect your HTML pages. Then, you may want to have others test your Web Access application, verifying these pages and associated business logic. Often the feedback received by testing can help you decide what areas would benefit most by editing the HTML by hand or with an HTML editor. Bear in mind that if you edit HTML that was generated from a data view, you could lose your changes the next time you generate that HTML. So, save any of these special HTML changes until you are sure that your HTML pages are perfect in every other way.5.2 Data model and HTML considerations This section covers the following topics: 5.2.1, “Date format and universal time” on page 43 5.2.2, “Special processing s-words and table names” on page 44 5.2.3, “Audit information” on page 46 5.3.1, “REXX global variables” on page 48 5.3.2, “BLQUEXIT” on page 545.2.1 Date format and universal time Web Access uses many Information Management for z/OS features, including user date format and universal time support. These are included in the user preferences section of the people record HTML. If you decide to update the data view for people records, we recommend that you keep the date format data attribute record (BLQ&DFMT) in the people record data view (BLQVPEOP) and within the HTML generated from that data view. This allows the user to choose a date format. Date format is automatically used by Web Access; there is no Information Management for z/OS administrative effort needed to support it. The ability to set a time zone depends on whether or not the Information Management for z/OS administrator has specified the TIMEZONE parameter in the session-parameters member. Specifying TIMEZONE is one of the steps required to turn on universal time (UT) support. If TIMEZONE is not in the session, specifying a time zone in the user preferences of the people record HTML will have no effect. Therefore, leaving the time zone in your HTML might confuse your Web Access users. If UT is not enabled, you might want to remove the time zone field from the user preferences group in the people data view record and 24 Section 4.3, “Business logic” on page 37 provides an overview of business logic, and 5.3, “Integrating business logic into your application” on page 47 describes how to implement business logic using REXX routines. Chapter 8, “Using existing privilege class records” on page 83 includes home page information. Use Chapter 9, “Using shadow s-words and data attribute records” on page 91 to learn what shadow s-words are and how to set them up. Use Chapter 10, “Type-based HTML” on page 101 to learn about type-based HTML and how to set it up. Chapter 5. Building a customized Web application 43
    • regenerate the HTML so that it no longer appears in the user preferences HTML. Do not remove the time zone data attribute record (BLQ&UTZN) from the people record data view. Instead, update the people record (BLQVPEOP) and de-select it from the USER group. Rebuild the static PIDT using BLGUT18. Then, regenerate the HTML. For a better understanding of UT and the session-parameters member, refer to the Tivoli Information Management for z/OS Planning and Installation Guide and Reference, Version 7.1, GC31-8751 (BLGP2E10), as well as “Using dates, date formats, and time zones in business logic” on page 144 for guidance in using TIME_ZONE and DATE_FORMAT control PDBs in your business logic.5.2.2 Special processing s-words and table names When you generate HTML, there are s-word indexes that will cause additional processing if included in a layout (either at HTML generation or run time). The data attribute record that contains the s-word is not important. The existence of the s-word is the trigger. Also, there are list table names that when used in HTML layouts cause unique processing. Print record s-word index S0EF7 S-word index S0EF7 is a special s-word for print record processing. When a data attribute record for S0EF7 is included in a layout, the HTML generated for that layout has the following unique features: When the page is loaded into the browser, the operating system print dialog launches. When a data attribute record for freeform text is processed, the text includes associated audit data. Text appears in a <table> instead of a <textarea>. Hyperlinks are not created for record identifier data attribute records that appear in the layout. The data attribute record for S0EF7 will be suppressed and not appear in the generated HTML layout. Web Access ships a data attribute record for S0EF7 named BLQ&0EF7 that you may want to use. History display s-word index S0ED1 S-word index S0ED1 is a special s-word for history data display. When a data attribute record for S0ED1 is included in a layout, the HTML generated for that layout has the following unique features: A table that contains the history data is placed at the end of the HTML layout. The data attribute record for S0ED1 is suppressed and does not appear in the HTML layout. The history table only appears in print or display HTMLs. Web Access ships a data attribute record for S0ED1 named BLQ&0ED1 that you may want to use.44 IBM Tivoli Web Access for Information Management
    • Record identifiers in HTML layoutsThe rnid_SWord_List parameter in the BLQPARMS configuration file is used to list the s-wordindexes for record ID fields. When record ID fields for any of the s-words in thernid_SWord_list parameter appear in an HTML layout, the following additional processing isperformed: When generating display HTML that includes data attribute records for any of the record identifiers, non-blank values are converted into hyperlinks. S0CCF is a special case. It will not appear in the display HTML layout as a hyperlink.25 When a record identifier in rnid_SWord_List is processed as input to any transaction, it is left zero-padded to eight digits if the record identifier is numeric. When a record identifier in rnid_SWord_List is processed as input to any transaction, it is translated to uppercase if the record identifier is user-assigned.Approval s-word indexes S12DE and S12DFS-word indexes S12DE (Approver) and S12DF (Approval Status) are used for approvalprocessing. When a data attribute record for S12DE or S12DF is included in a display HTMLlayout, that layout has the following unique features: A <table> is created that includes both S12DE and S12DF. There is one row for each list processor index in S12DE. Based on the classes the current user is entitled to use, the approval status actions for an approver class (S12DE) might include an Approve or Reject hyperlink in this table.Web Access ships data attribute records for S12DE and S12DF that you may want to use.The data attribute record for S12DE (Approver) is BLQ&APVR, while that for S12DF(Approval Status) is BLQ&APST. Since the drop-in problem and change management Websolution provided with Web Access also uses approval processing, you may want to reviewthe Web Access-supplied data view for change records (BLQVCHNG) to see how it includesthese data attribute records.Parent child s-word index S0CBCWhen processing HTML layouts for change or request records, and an HTML layout containsa data attribute record for s-word index S0CBC, the following occurs: In display, print, or update mode, HTML layouts that contain a data attribute record for S0CBC (typically used for NAMA/) will have a table inserted. This table replaces S0CBC and contains a row for each child record for the parent. The fields from the child used to populate the table are defined in BLQWA9TR.html. The heading for the table is defined in BLQWA9TT.html, and the footing of the table is defined in BLQWA9TB.html. Buttons appear that allow new child records to be created in update mode. In create mode, the data attribute record for S0CBC will appear as an input field. Therefore, it is recommended that you not include a create-mode usage value for any s-word index S0CBC data attribute records.Type s-word S0C09When using type-based HTML for create, update, or inquiry, do not include the data attributerecord for S0C09 (Type) in a type-based group, or in a layout that includes type-basedgroups. In display or print layout, this restriction does not apply. Type-based HTML isdescribed in Chapter 10, “Type-based HTML” on page 101.25 Since S0CCF is the currently displayed record, the hyperlink is not needed. Chapter 5. Building a customized Web application 45
    • Showing a list of privilege classes for a user When a data attribute record for s-word S1152 appears in an HTML layout, it will be replaced by a <select> list showing the privilege classes that contain a given user ID. Validation checker Web Access uses a validation checker s-word to intercept data validation errors on update and create transactions. Any data view records that you use for update and create transactions must contain the data attribute record for the validation checker (see the validation_checker parameter in Appendix C, “Web Access configuration parameters” on page 163). Web Access ships a validation checker data attribute record that you can use. It is named BLQ&9999 and is for s-word index S0BCC. If you use S0BCC in your records as a data field (it is the field for transfer to class), you can use another s-word. The s-word (and the data attribute record) must use program exit BLG01053. See the Tivoli Information Management for z/OS Panel Modification Facility Guide, Version 7.1, SC31-8750 for more information about using program exit BLG01053. The validation checker data attribute record must be the last data attribute record in the attribute list in your data view records. If you sort the list of data attribute records in your data view, take care to move it to the end after sorting. Tip: You might want to copy BLQ&9999 and call it Z99#9999 (assuming your data attribute trigger character is #). Then, use Z99#9999 in all your data views. That name will always sort to the end. Attach table ATTACH is a restricted data view table name that causes the table or <fieldset> used in display layouts to have buttons required to add, view, and remove attachments. All of the data attribute records included in the ATTACH table grouping must be list items. See “Add attachments to your data views” on page 159 for more information about how to enable attachments. Saved search table SAVESRCH is a restricted data view table name. When used, HTML is generated that allows a search to be performed. All of the data attribute records included in the SAVESRCH table grouping must be list items.5.2.3 Audit information The data views for any type of record that your Web Access application will create or update must include data attribute records for audit information. You can use the data attribute records that Web Access ships or you can use your own. The Web Access-supplied data attribute records for audit information are as follows: BLQ&DATE—Date Created BLQ&TIME—Time Created BLQ&CLAE—Class Created BLQ&RLOC—Create Source BLQ&DATM—Date Modified BLQ&TIMM—Time Modified BLQ&USER —User Modified BLQ&RLOU—Update Source46 IBM Tivoli Web Access for Information Management
    • If you use your own data attribute records for any of these audit information fields, make sure they use the same s-words contained in the Web Access records. In addition, if you use your own data attribute records for Date Created or Date Modified, they must include the =DATE validation pattern. If you use your own data attribute records for Time Created or Time Modified, they must include the =TIME validation pattern.5.3 Integrating business logic into your application Web Access supports customized business logic in several ways. Through the traditional Information Management for z/OS data model records, you can run Information Management for z/OS program exits and you can run file time TSPs or TSXs. Within Web Access, there are exit points where you can hook in additional business logic processes. In the exits, you can perform business processes that do things, such as automatically prefilling fields on a page or notifying a user when a problem is assigned to that user. The following paragraphs describe how to use the business logic exit points. Refer to 4.3, “Business logic” on page 37 for an overview of all of the business logic methods that you can implement in your Web Access application. The business logic exits are REXX routines that you provide. Since they run in the Web Access environment, the functionality of HLAPI/REXX is available for them to use, too. So not only do they have access to your Web Access data, but by using HLAPI/REXX, they also have access to your Information Management for z/OS data and have the power to run your own TSXs. There are five exit points for you to integrate into your own business logic. You specify the names of the REXX routines to run at each exit point in your BLQPARMS file. home_page_exit predisplay_exit validation_exit postfile_create_exit postfile_update_exit The home_page_exit routine runs whenever you go to the home page. The predisplay_exit, validation_exit, postfile_create_exit, and postfile_update_exit routines run from the HTML pages that are used to present the data for your Information Management for z/OS records. Refer to 4.3.6, “The home page” on page 40 for information about how to set up the home_page_exit routine. Using the home_page_exit routine, you can do such things as dynamically define the home page for your users. For example, the drop-in problem and change management Web solution uses a home_page_exit routine to dynamically define a user’s home page based on that user’s role. A user whose role is User is displayed a different home page than a user whose role is Analyst. The predisplay_exit routine runs before an HTML page appears. Using a predisplay_exit routine, you can do such things as prefill fields on the page. The validation_exit routine runs when you leave an HTML page while creating, copying, or updating a record. You leave a page when you select a different HTML page or you file a record. Using a validation_exit, you can do such things as automatically set values in fields based on values that were entered on the page or do conditional processing and return a message if something is wrong. Chapter 5. Building a customized Web application 47
    • The postfile_create_exit routine runs after you file a new record. Using a postfile_create_exit routine, you can do such things as send e-mail notification. The postfile_update_exit routine is similar to the postfile_create_exit routine, except that it runs after you file an updated record. Refer to 4.3, “Business logic” on page 37 for additional usage examples for the business logic exit points. Appendix A, “Business logic examples” on page 123 contains business logic used by the drop-in problem and change management Web solution. You can use those examples to help develop your own business logic.5.3.1 REXX global variables When you write your business logic REXX routines, you have access to variables in the REXX global variable pool. Data in the pool includes variables associated with the record with which you are working, as well as Web Access variables that contain information pertaining to the operating characteristics of your Web Access application and to the user running Web Access. Record data Record data can be accessed using the s-word index of the field. The variable name for a field is in Snnnn format, where nnnn is the s-word index. For example, the status field is index 0BEE, so the REXX variable is S0BEE. All fields except freeform text and lists are represented in this manner. Freeform text and list fields are also identified by the s-word, but the data is stored in compound variables. This is described a little later. If your business logic adds data to the record, you must set the type of data that is in the s-word variable in addition to assigning a value to the variable. The data type goes into the Snnnn.?type compound variable. For example, the REXX compound variable for the status field data type is S0BEE.?type. The following are valid data types: X—Freeform text L—List D—All others The data type for the status field is D. Your business logic can also access the Snnnn.?type variable if there is a need to check the data type of any record data field. To set the status to OPEN, code the following. Example 5-1 Set status to OPEN S0BEE = ‘OPEN’ S0BEE.?type = ‘D This sets your local status variable but is not reflected in the record with which you are working. To add data to the record, you need to change the value in the REXX global variable pool. This is described later with BLQUEXIT. In some cases, you may want to work with the current data in a field; but if there is no data, the variable may not exist. Therefore, you may want to verify that the variable exists before you attempt to access the data. You can use the REXX SYMBOL function to test the state of the variable. If the state is VAR, a value has been assigned to the variable.48 IBM Tivoli Web Access for Information Management
    • The following example checks if there is status data and assigns its value to a local variable: status = If SYMBOL(S0BEE) = VAR then status = S0BEE If you are working with freeform text data, the lines of text are set or contained in compound variables. The stem is the s-word index of the freeform text field. The tail is the index of the line of freeform text. The tail with index 0 contains the total number of lines of freeform text. The following example shows how to set the problem description freeform text field (S0E01) to contain four lines of freeform text: S0E01.?type = X S0E01.0 = 4 S0E01.1 = This is the first line of freeform text. S0E01.2 = Heres the second line. The third is blank. S0E01.3 = S0E01.4 = This is the last line of freeform text. This sets your local REXX variables. You will also need to update the values in the REXX global variable pool, which is described later. List data is handled similarly to freeform text. However, Snnnn.?type is now L. Each row in the list is in the corresponding Snnnn.n variable, with Snnnn.0 containing the total number of rows in the list. Web Access data Web Access provides a number of REXX global variables that provide the operating characteristics of your Web Access application, along with information about the current user and the functions that user is performing. Your business logic may need to refer to this data. Table 5-1 identifies these variables.Table 5-1 Web Access variables Variable name Values Description ?USER_PROFILE_ID The ID of the current users people record. ?ROLE User The current users role. Analyst Support Manager Administrator ?RECORD_TYPE ACTIVITY The type of record with which the current user is working. CHANGE These values may vary, depending on your implementation. INCIDENT PEOPLE PROBLEM REQUEST SOLUTION WORK ?MODE CREATE How the current user is working with the record (create, UPDATE update, or copy). COPY Chapter 5. Building a customized Web application 49
    • Variable name Values Description ?CALLER_ID The people record ID of the person for whom the record is being created. This might or might not be the same as the ?USER_PROFILE_ID. ?VIEW_NAME The name of the data model used for the current record. These values vary, based on your implementation. Record access is defined in your BLQPARMS file. ?VIEW_TYPE PIDT_NAME The type of data model used for the current record. Record DATA_VIEW_NAME access is defined in your BLQPARMS file. ?PEOPLE_VIEW_NAME BLQVPEOP The data model used to access people records. The users profile is a people record in the Information Management for z/OS database. Access to people records is defined in your BLQPARMS file. Web Access provides a data view for people records named BLQVPEOP. ?PEOPLE_VIEW_TYPE DATA_VIEW_NAME The type of data model used to access people records. Record access is defined in your BLQPARMS file. If you use the data view for people records supplied by Web Access (BLQVPEOP), ?PEOPLE_VIEW_TYPE will be DATA_VIEW_NAME. ?DATE_FORMAT MM/DD/YY The current users external date format. The user sets the MM-DD-YY external date format in his or her profile. The default is MM.DD.YY MM/DD/YYYY. In addition to these values, your Information MM/DD/YYYY Management for z/OS administrator can also set up a MM-DD-YYYY user-defined format. MM.DD.YYYY DD/MM/YY DD-MM-YY DD.MM.YY DD/MM/YYYY DD-MM-YYYY DD.MM.YYYY YY/MM/DD YY-MM-DD YY.MM.DD YYYY/MM/DD YYYY-MM-DD YYYY.MM.DD DDMMMYY DDMMMYYYY YYDDD YYYYDDD50 IBM Tivoli Web Access for Information Management
    • Variable name Values Description?TIME_ZONE NZT The current users time zone. The user sets the time zone EAT in his or her profile. The default is ET (North America EAST eastern with daylight saving time). TASMANIA CAT CAST KST JST CHINA WAST INDIA MSK EET SAFRICA CDT WET UT NDT AT CHILE ET EST CT MT MST PT AKT HST?FILE 1 User clicked Finish to file the record. 0 User is still working with the record. ?FILE should only be used by a validation_exit routine.?SEPARATOR_CHARACTER The separator character used for multiple response fields. Record access data Your business logic can also refer to record access directives specified in your BLQPARMS file. You may want to use the record access information if your code invokes HLAPI/REXX transactions that access records in your Information Management for z/OS database. If directives for the type of record your code accesses are specified in your BLQPARMS file, you can dynamically retrieve the information from the REXX global variable pool rather than hardcoding the values in your program. You can dynamically retrieve whether to use a PIDT or a data view and its name (data model type and name), and then pass these values on your HLAPI/REXX transaction. All you need to know is the name of the record or its s-word as defined in your BLQPARMS file. So, how does this work? Web Access assigns record access directives to compound variables that are stored in an array in the REXX global variable pool. You use the record type name or the record type s-word to obtain the index of the entry for that record type. You use that index along with the record function (create, update, retrieve, and so forth) to obtain the data model type and the data model name, which you can then pass on to the HLAPI/REXX transaction. You can also use the index along with the record function to obtain the default HTML page. Chapter 5. Building a customized Web application 51
    • Record access information is assigned to compound variables that all begin with a stem of CFG., and to obtain the set of variables associated with the record type with which you are working, you first need to get its index into the array. Use the record type name as the tail of the compound variable (CFG.recordtypename) to obtain the index. For a record type named PROBLEM, the index is in the following variable: CFG.PROBLEM Alternatively, use the record type s-word (CFG.recordsword) instead of the name to obtain the index. For PROBLEM records with record type s-word defined as S0032, the index is in the following variable: CFG.S0032 Use this index along with the record function (create, update, retrieve, and so on) to obtain the data model type and the data model name. The data model name is contained in the variable: CFG.index.recordfunction Where index is the value of CFG.recordtypename or CFG.recordsword, and recordfunction is create, update, retrieve, and so forth. To get the data model type, tack .?viewtype to the end of the data model name variable, as in: CFG.index.recordfunction.?viewtype Where index is the value of CFG.recordtypename or CFG.recordsword, and recordfunction is create, update, retrieve, and so forth. The data model type will be DATA_VIEW_NAME if your directive specified a data view, or PIDT_NAME if your directive specified a PIDT. Suppose that your business logic must retrieve a problem record, and that in your BLQPARMS file there are directives for problem record access, including one for retrieve. Example 5-2 Directives for problem record access record_type PROBLEM S0032 P create_view BLQVPROB BLQ0P001.html update_view BLQVPROB BLQ0P101.html retrieve_view BLQVPROB BLQ0P200.html search_view BLQVPROB BLQ0P301.html BLQWSRLP.html copy_view BLQVPROB BLQ0P001.html history_view BLQVPROB BLQ0P205.html print_view BLQVPROB BLQ0P206.html text_append S0E01 dar_shadows S0BEE S5140 S5141 S5142 dar_shadows S0C0E S5145 S5146 S5147 S5148 S5149 The HLAPI/REXX RETRIEVE transaction requires that you specify a control PDB identifying the data model to use on the retrieve. Assuming that you can use the same data view specified in the directives (BLQVPROB), you can hardcode the model on the transaction, as shown in Example 5-3 on page 53.52 IBM Tivoli Web Access for Information Management
    • Example 5-3 Hardcode model on the transactiondata_view_name=BLQVPROBrnid_symbol=00000025control.1=data_view_namecontrol.2=rnid_symbolcontrol.0=2parms=RETRIEVE,CONTROL,,OUTPUTaddress LINK BLGYRXM parmsOr, you can dynamically retrieve the model information from the REXX global variable pool,thus ensuring that your business logic uses the same model as your Web Access application.To dynamically retrieve the data model information, all you need to know is the name of therecord type or its s-word as defined in the BLQPARMS file. In this example, the name isPROBLEM.Using the same sample code as above to retrieve a problem record, you can dynamicallyobtain the data model type and name to pass on the HLAPI/REXX transaction, as shown inExample 5-4.Example 5-4 Dynamically obtain data model type and name/* Get index for problem record directives */problem_index=CFG.Problem/* Get the type of data model used on a retrieve transaction */modeltype=CFG.problem_index.Retrieve.?viewtype/* Assign the data model name used on a retrieve transaction *//* to the value of the modeltype variable. (If modeltype is *//* DATA_VIEW_NAME, DATA_VIEW_NAME is assigned the data model *//* name. If modeltype is PIDT_NAME, PIDT_NAME is assigned *//* the data model name.) */call value modeltype, CFG.problem_index.Retrievernid_symbol=00000025control.1=modeltype /* Assign modeltype to control PDB */control.2=rnid_symbolcontrol.0=2parms=RETRIEVE,CONTROL,,OUTPUTaddress LINK BLGYRXM parmsThe record access variables are summarized in Table 5-2.Table 5-2 Record access variables CFG.recordtypename Index of the directives for the specified record type. CFG.recordsword Index of the directives for the specified record type. This is an alternate method of deriving the index. CFG.index.recordfunction Data model name for the specified record type and function. Chapter 5. Building a customized Web application 53
    • CFG.index.recordfunction.?viewtype Data model type for the specified record type and function. Values are: DATA_VIEW_NAME PIDT_NAME CFG.index.recordfunction.?htmlfile Default HTML file for the specified record type and function. Where: recordtypename Record type name as specified in the record_type directive recordsword Record type s-word as specified in the record_type directive index Value of CFG.recordtypename or CFG.recordsword recordfunction Create, update, retrieve, and so forth (per directive) Restrictions When writing your business logic, you can define whatever REXX variables you need. However, there is a set of restricted variables reserved by Web Access that you cannot use. Do not assign values to the following restricted variables: iii nnn zzz ?changed ?type module pool_id pool_items pool_save_needed user_id var_name var_type var_value In addition, your variables cannot begin with: CFG BLG ? You also cannot use compound variables that have the following stem: !.5.3.2 BLQUEXIT BLQUEXIT is a template REXX routine supplied with Web Access. It provides all the infrastructure you need to implement your own business logic, including access to the REXX global variable pools and a set of common subroutines that your logic can invoke. You should always use a copy of BLQUEXIT as a starting point. A comment block in BLQUEXIT indicates where you should insert your unique business logic. Look for the following, as shown in Example 5-5 on page 55.54 IBM Tivoli Web Access for Information Management
    • Example 5-5 Insert unique business logic/**********************************************************************//* Put business logic code here. Use Update_Data subroutine to *//* write an updated or new variable and value to the read/write *//* pool. *//**********************************************************************/ Note: Your main logic goes after the block comment./*********************************************************************//* Externalize pool updates before returning to the caller. *//*********************************************************************/Call Save_Pool_Data /* Update REXX pool */EndREXX: /* Module exit */Exit 200 error_item error_text /* Return completion code */ Note: Your subroutine logic goes after the Exit statement.In your business logic, you can update record data variables. As with Example 5-1 onpage 48, you can set the status to OPEN by coding the following.Example 5-6 Set the status to OPENS0BEE = ‘OPEN’S0BEE.?type = ‘D’This updates your local variables, but it does not externalize the changes to Web Access. Toexternalize the change, you must first prepare the s-word variable for externalization. Then,you must update the REXX global variable pool.You prepare an s-word variable for externalization by calling the Update_Data subroutineprovided with the BLQUEXIT template and passing the s-word variable name to it. Asubsequent call to the Save_Pool_Data subroutine (which is also provided with theBLQUEXIT template) actually adds or replaces the variables in the REXX global variablepool. Update_Data must be called for each new or modified variable that you want toexternalize. Save_Pool_Data updates the REXX global variable pool en masse, so it onlyneeds to be called once, after all local updates and calls to Update_Data have been made.Depending on your logic, you may not have to add a statement to call Save_Pool_Data, sincethe BLQUEXIT template automatically calls it for you immediately before exiting. As you cansee in Example 5-5, the statement before the EndREXX label is a call to Save_Pool_Data.As you develop your business logic, you may want to leave the exit processing provided bythe BLQUEXIT template as is, or you may want to modify it to suit your design. For example,if your code detects an error, it might not be appropriate for your logic to update the REXXglobal variable pool. You could exit at that point, you could Signal EndREXX to go directly tothe EndREXX label and exit, or you could do any of a variety of things, whatever your logicdictates.You may also want to change the Exit statement or implement different Exit statements asrequired by your business logic. You should code the Exit statement based on Web Accessguidelines described later. Chapter 5. Building a customized Web application 55
    • Common use subroutines The following procedures and subroutines or functions are provided with BLQUEXIT. Many of these are used by BLQUXVAL, which you may want to review. BLQUXVAL is the validation_exit routine used by the drop-in problem and change management solution and is described in Appendix B, “Hints and tips” on page 153. Update_Data Update_Data prepares record data for externalization. Table 5-3 Update_Data Input Snnnn, where Snnnn is the s-word variable name Returned N/A Example S0BEE = ‘OPEN’ S0BEE.?type = ‘D’ Call Update_Data ‘S0BEE’ Changed Changed tests if the record data value was changed. Table 5-4 Changed Input Snnnn, where Snnnn is the s-word variable name 1 The value was changed. Returned 0 The value was not changed. Example if Changed(‘S0BEE’) then /* if the status was changed */ Just_Changed Just_Changed tests if the record data value was changed on the HTML page just exited. Table 5-5 Just_Changed Input Snnnn, where Snnnn is the s-word variable name 1 The value was just changed. Returned 0 The value was not just changed. Example if Just_Changed(S0BEE) then /* if status was just changed */ Userid_to_Name Userid_to_Name returns the name associated with a profile ID. The name is retrieved from the S151F field (NAME) in the people record for that ID. A typical name follows the format: John Smith Table 5-6 Userid_to_Name Input Profile ID Returned Name Example callers_name = Userid_to_Name(S14FD) callers_name = Userid_to_Name(?caller_id) callers_name = Userid_to_Name(JSMITH)56 IBM Tivoli Web Access for Information Management
    • Parse_NameParse_Name parses a name into searchable formats. An input name in a typical format suchas John Smith is returned in a string of four words, for example: Smith/John Smith/J Smith JohnTable 5-7 Parse_Name Input Name Returned lastname/firstname lastname/firstinitial lastname firstname Example set_of_names = Parse_Name(S0B59) set_of_names = Parse_Name(John Smith)Add_SeparatorAdd_Separator inserts the HLAPI separator character between words. Usage is for multipleresponse fields.Table 5-8 Add_Separator Input Blank separated string of words Returned Input string with blanks replaced by separator character Example list_of_names = Add_Separator(set_of_names)Error handlingAs you develop your business logic routines, you may need to handle errors that your logicdetects. For some types of errors, you may want to stop processing, collect diagnosticinformation, and display the information back to the user. BLGUEXIT provides error handlingroutines that you can use if you detect a fatal error. Depending on the error and which routineyou invoke, you can also set simple message text and a condition code to include in theinformation displayed to the user, where. cc—the condition code variable text—the message text variableNon-fatal errors can also be returned to Web Access on the Exit statement. This is describedlater. The following routines can be used to handle fatal errors.API_BombedAPI_Bombed is an error handler for HLAPI/REXX failures. If your business logic invokesHLAPI/REXX calls that fail with fatal errors, you can do the following to collect diagnostics andexit: Signal API_BombedBefore you signal API_Bombed, you should set cc to the rc from the HLAPI/REXX call.Message text (text) does not apply when you use API_Bombed. API_Bombed processingflows to Bomb_Out. Chapter 5. Building a customized Web application 57
    • Example 5-7 API_Bombed parms = RETRIEVE,CONTROL,INPUT,OUTPUT address LINK BLGYRXM parms if blg_rc = 12 & blg_reas = 31 then rc = 0 /* ignore record not found */ cc = rc /* set cc to rc from call */ if cc > 0 then /* handle fatal API error*/ Signal API_Bombed QueueIt QueueIt is an error handler to display a message. If your business logic fails with a fatal error, you can do the following to collect diagnostics and exit: Call QueueIt msgtext The message text passed to QueueIt is included in the diagnostic information displayed to the user. Condition code (cc) does not apply when you use QueueIt. QueueIt processing signals Bomb_Out. Example 5-8 QueueIt call QueueIt some data is missing Bomb_Out Bomb_Out is an error handler for non-HLAPI/REXX failures. If your business logic fails with a fatal error, you can do the following to collect diagnostics and exit: Signal Bomb_Out If you want to record a unique message or condition code in the diagnostics, you can set simple message text in the text variable and a condition code in the cc variable. The text and cc variables are both included in the diagnostic information displayed to the user. The routines API_Bombed and QueueIt both flow to Bomb_Out. Example 5-9 Bomb_Out text = routine xyz failed cc = 10111 Signal Bomb_Out /* handle fatal error */ Exit statement Exit processing in the BLQUEXIT template calls Save_Pool_Data to externalize changes to the REXX global variable pool, and then exits. You may want to change this processing or implement your own exit processing, depending on the needs of your business logic. If you code or modify the Exit statement, you must follow the syntax required by Web Access. The Exit statement as coded in the template returns a completion code of 200 and the values for error_item and error_text. Processing in BLQUEXIT initializes both the error_item and error_text variables to , but you can set them as required by your business logic. Typically, you would set them if your logic detects a field that is in error, or you want to redirect Web Access to a specific HTML page. You are not required to use either error_item or error_text. Rather, all that is required is that you code Exit statements based on the syntax that Web Access requires.58 IBM Tivoli Web Access for Information Management
    • Example 5-10 shows the exit processing provided by the BLQUEXIT template. Notice howthe Exit statement is coded.Example 5-10 Exit processing provided by BLQUEXIT template/*********************************************************************//* Externalize pool updates before returning to the caller. *//*********************************************************************/Call Save_Pool_Data /* Update REXX pool */EndREXX: /* Module exit */Exit 200 error_item error_text /* Return completion code */Exit statement syntaxAt a minimum, you must return a completion code on the Exit statement. It must be the firstargument returned. Valid completion codes are 200 and 201. Use completion code 201 tosignify a fatal error.The syntax for the Exit statement varies based on the completion code. The variations aredocumented below. Data that can be optionally returned is enclosed in brackets [ ].Example 5-11 SuccessExit 200Success.Example 5-12 Field in errorExit 200 Snnnn [message_text]Where Snnnn is an s-word variable name, and message_text is message text.The Snnnn field is in error. Changes to data in the REXX global variable pool are discarded.The HTML page redisplays, and the Snnnn field is flagged. If you provide message_text, thattext is displayed at the top of the page. The user can correct the error and retry.Example 5-13 Override HTML pageExit 200 HTML html_page [message_text]Where html_page is the file name of the HTML page to be displayed, and message_text ismessage text.Return the HTML keyword and an html_page to override processing and display the specifiedhtml_page. If you provide message_text, the text is displayed at the top of the page. Sincechanges to the REXX global variable pool are not discarded, you should only redirect thepage if all data collected up to that point is valid.Example 5-14 Fatal errorExit 201Fatal error. No processing is performed. Changes to data in the REXX global variable poolare discarded. Any diagnostic or error data that may have been collected is displayed. Chapter 5. Building a customized Web application 59
    • Tip: When you return an s-word variable name to exit with a field in error, make sure you return the name of the variable, not the value. If you return Snnnn on the Exit without quotation marks, the value of the Snnnn variable is returned. Since it is the name you need to return, you should enclose Snnnn in quotation marks to identify the constant. See the following Exit statement examples. Also, when you exit with a field in error, Web Access places a generic message at the top of the page: Fields marked by an (*) are in error. If you return a message with the field in the error exit, your message is placed immediately after the generic message. You may want to place the <b> HTML tag at the beginning of your message text to force the browser to display your message on a new line. Exit statement examples The following are Exit statement examples: Redirect the user to the problem-tracking information page and display the message Please enter an assignee ID at the top of the page. In the following example, the HTML keyword, html_page, and the message text are all returned as constants, so single quotes surround the entire string: Exit 200 HTML BLQ0P002.html Please enter an assignee ID. Redirect the user to the same page, but return a message variable instead of a constant string. Since the HTML keyword and html_page are constants, they must be enclosed in quotation marks, either individually or together, as in the following: message_text = Please enter an assignee ID Exit 200 HTML BLQ0P002.html message_text Flag a field in error and display an error message to the user. Since the s-word variable name is a constant, it must be enclosed in quotation marks. In the following example, the message is also returned as a constant, so it must be enclosed in quotes as well. Both constants can be enclosed in the same quotation marks. The field in error is S0C43. The <b> HTML tag forces the browser to display your message on a new line. Exit 200 S0C43 <b>You entered an actual start time with no actual start date. Redirect the user to the same page, but return a message variable instead of a constant string: message_text=<b>You entered an actual start time with no actual start date. Exit 200 S0C43 message_text HLAPI/REXX calls If your business logic invokes HLAPI/REXX transactions, you should use the following syntax on the HLAPI/REXX call. Though not mandatory, placing the HLAPI/REXX parameters into the REXX variable parms enables Web Access error processing to display and format error data for those parameters. address LINK BLGYRXM parms Where parms is set to the HLAPI/REXX transaction, control, input, and output PDBS.26 26For example, if you invoke a retrieve transaction with control, input, and output PDBs named, respectively, CONTROL, INPUT and OUTPUT, you can set parms as follows: parms=RETRIEVE,CONTROL,INPUT,OUTPUT60 IBM Tivoli Web Access for Information Management
    • One technique you could use to invoke a HLAPI/REXX transaction is demonstrated inExample 5-15, which invokes the HLAPI/REXX RETRIEVE transaction to retrieve the status(S0BEE) and description (S0E0F) from a problem record whose ID is 25.Example 5-15 Invoke HLAPI/REXX RETRIEVE transaction/* set data model type and name for problem record retrieve */problem_index=CFG.Problemmodeltype=CFG.problem_index.Retrieve.?viewtypecall value modeltype, CFG.problem_index.Retrievernid_symbol=00000025control.1=modeltype /* Assign modeltype to control PDB */control.2=rnid_symbol /* Assign record ID to control PDB */control.0=2input.=input.1.?name=S0BEE /* Retrieve status */input.2.?name=S0E0F /* Retrieve description */input.0=2parms=RETRIEVE,CONTROL,INPUT,OUTPUTaddress LINK BLGYRXM parmsif blg_rc = 12 & blg_reas = 31 then rc = 0 /* ignore record not found */cc = rc /* set cc to rc from call */if cc > 0 then /* handle fatal API error */ Signal API_Bombed Chapter 5. Building a customized Web application 61
    • 62 IBM Tivoli Web Access for Information Management
    • 6 Chapter 6. Generating user application HTML Generating HTML from data model records stored in your Information Management for z/OS database is a task you will need to perform many times. For the most part, any time you modify a data view record, you will have to regenerate the HTML associated with it. First, you create your data attribute and data view records, including your tables, groups, and panel layouts, using 3270 access to Information Management. If you use static PIDTs, you should next run BLGUT18 to rebuild them. Then, using the Web Administration page, you generate the HTML to display, print, update, create, and search for records defined by those data views. After you generate a particular HTML mode for a record, you can save the choices you made into an Auto Build file that you can then use to repeat the generation of the HTML as often as you need. If you make new choices or add additional data views to support more record types, you can add or replace entries in the Auto Build file. You may find it helpful to have more than one Auto Build file. You can have as many of these files as you want and switch between them by updating and reloading the configuration file.© Copyright IBM Corp. 2003 63
    • 6.1 The HTML generator Web Access provides an HTML generator to dynamically generate HTML based on the group, table, and panel layout information in a data view record. The Web Access administrator can run this generator from the Web Administration page (see Figure 6-1).Figure 6-1 The Web Access Web Administration page There are two methods that can be used to generate the HTML: 1. A hands-on method where the Web Access administrator makes selections, such as what mode to build (create, update, display, or inquiry) 2. Using the Auto Build file For any given data view record, you must use the first method the first time through to build the HTML for each mode separately. At the end of the run for each mode, you can save the settings in an Auto Build file. Later, you can use this file employing method 2 to repeat the generation of the HTML with the settings you saved.64 IBM Tivoli Web Access for Information Management
    • Building HTML is simple. Just specify the name of the data view record for which you want to build the HTML. Then, specify a root HTML name, and decide if you want boxes around groups and for which mode you want the HTML generated. In this example, we create the HTML for the BLQVPROB data view record (see Figure 6-2). We construct the create-mode HTML with boxes around groups. The generated .html file names start with MTG0. To do this, type the data view name (BLQVPROB) and the root HTML name (MTG0) into the corresponding fields in the Create HTML section of the Web Administration page. Select the Boxes around groups? check box and the Create option next to the Create HTML for label.Figure 6-2 BLQVPROB Create HTML Chapter 6. Generating user application HTML 65
    • Having knowledge of the data in the various tasks, you next select the layouts you want, depending on the mode you are building. For example, here are the tasks defined for BLQVPROB: Summary Reporter Information Details Tracking Information Completion Information Audit Information History Data Print Record In Figure 6-3, we choose Reporter Information, Details, and Tracking Information for the create-mode HTML.Figure 6-3 Create-mode task selection66 IBM Tivoli Web Access for Information Management
    • When you build HTML for any mode, choose the layouts as appropriate. For example, if youare creating the display-mode HTML, you should select History Data so that you can view thehistory data associated with a record. Not all layouts are needed for a given mode. Leaveunwanted layouts unchecked so that they will not be included in the HTML generated for thatgiven mode.If desired, you can overtype the HTML file name generated on the Create HTML page. Thesedefault to the Root HTML whose name you provided on the Web Administration page, alongwith the record type information from the configuration file (BLQPARMS) and the indexingdata from the data view record.You can also overtype the HTML title, which defaults to the name that appears on the 3270data view record panel layouts. This title information will be used in the <TITLE> tag in the<HEAD> information for the generated HTML and will also appear at the top of the page andas the task name in the navigation area along the left side of the page.After you select the tasks and complete your changes, click the Create button to generate theHTML.There are several things that you can do after the HTML is generated: You can specify the ID of a record that matches the type of record you intend to use with the generated HTML and click the Go button. This allows you to see actual values from the record in the generated HTML. See Figure 6-4 on page 68 and Figure 6-5 on page 69.27 You can display the HTML without Web Access substituting any of the internal values. You can edit the HTML. You can save or replace the entry in the Auto Build file. This allows you to use this file later to repeat HTML generation using the settings you saved. Refer to 6.2, “Auto Build specifics” on page 70 for information about how to set up an Auto Build file.Figure 6-4 on page 68 illustrates the page that displays after you create the HTML. Thisexample shows that HTML was created for the Reporter Information, Details, and TrackingInformation tasks for data view BLQVPROB. Here is where you can review the HTML, edit it,and save the entry in the Auto Build file. In this example, the Display rnid feature is used toreview the HTML generated for the Reporter Information task. Assuming that record ID 89 isan existing problem record in your Information Management database, Figure 6-5 on page 69displays the requested record ID 89 on the newly built HTML page.27 The record display is provided to allow you to review the generated HTML; you cannot change the record here. Ifyou want to test the generated HTML by changing the record contents, note the HTML file, and then use the TestHTML section of the Web Administration page. Chapter 6. Generating user application HTML 67
    • Figure 6-4 Generated HTML page68 IBM Tivoli Web Access for Information Management
    • Figure 6-5 Display Reporter Information HTML with record ID 89 There are several items that should be reviewed: Are the required fields shown using the color you chose in the Style File?28 Is the title in the browser window bar correct? Is the title at the top of the page correct? Does the title also appear as a task name in the navigation area on the left side of the page? Is there a task in the navigation area for each layout you chose? Please remember that you cannot use the navigation links at this time or use the buttons that may appear at the bottom of the HTML. When you use the Display rnid feature to review HTML, Web Access neither checks out the record nor creates a pool for it. Use your browser Back button to return to the prior page. 28 See Chapter 11, “Updating the style file” on page 109. Chapter 6. Generating user application HTML 69
    • As you can see, it is easy to review your HTML. You can make any adjustments to the data view and generate the HTML again until it meets your needs.29 The manual method should be used until you have decided what layouts you want included in the generated HTML. Then, you can use the Auto Build process. Since you can have more than one Auto Build file by specifying a different file name and path on the directive in the BLQPARMS configuration file, you may find it easier to have an Auto Build file just for the record type with which you are currently working. If you change the BLQPARMS configuration file, be sure to reload it using the Web Administration page. In this example, if we go through the HTML generate process again for update, display, and inquiry and add to the Auto Build file each time, it will then contain all parameters necessary to rebuild the HTML for the BLQVPROB data view record without having to specify any input parameters. This is very useful as you make changes to data view record groups, tables, and tasks and want to rebuild the HTML so that you can see those changes. Building the HTML for one data view record one mode at a time is not terribly difficult, but if you have to build the HTML for multiple data view records as Web Access does, that method can get very tedious.6.2 Auto Build specifics Web Access ships an Auto Build file called BLQBATCH. It resides in UNIX System Services in the following: /usr/lpp/InfoMan/web/samples/BLQBATCH Do not modify BLQBATCH or allow the HTML generator to modify it. At some point in the future, you may need to rebuild the HTML that Web Access ships, and BLQBATCH contains all the parameters necessary to do that. Therefore, it is important not to change it. Before you add or replace any entries using the HTML generator Auto Build process, you need to change the following parameter in your BLQPARMS configuration file: Auto_Build_file /usr/lpp/InfoMan/web/samples/BLQBATCH To something similar to the following: Auto_Build_file /usr/lpp/InfoMan/web/samples/MYHTML You change the Auto_build_file parameter by editing your BLQPARMS configuration file. You must also reload the configuration file using the Web Administration page so that this change will take effect. Then when you run the HTML generator and save the settings in the Auto Build file, they will be saved in this file. You do not have to create the MYHTML file, since the Auto Build process will create it for you if it does not exist already. The location of any Auto Build file must be in a directory within which you have write access. When you add or replace an entry in the Auto Build file, you will receive a message that your entry was added or replaced successfully. If you specify replace, and an entry does not exist in the Auto Build file, that entry will be added. If you specify add, and an entry already exists in the Auto Build file, another entry will be added. Therefore, you will typically only want to specify replace. 29 Remember that if you use static PIDTs, you must run BLGUT18 before you generate the HTML. So, until you have ironed out your data views, you may not want to build the static PIDTs.70 IBM Tivoli Web Access for Information Management
    • 7 Chapter 7. Converting a 3270 application So, you have decided to convert your 3270 application to the Web? Maybe you tried the Desktop, but were really interested in a Web browser solution. Or, maybe you tried to go to the Web, but found that building the HTML from scratch and modifying the necessary REXX code was just too time consuming and difficult. Now that Web Access is here, the tasks necessary to move a 3270 application to the Web should be greatly reduced. Before you can really think about the Web aspect, you have to do a little work on your data model. That is, you need to build the necessary data model records, data view and data attribute. If these concepts are new to you, spend some time reading Chapter 29 in the Tivoli Information Management for z/OS Panel Modification Facility Guide, Version 7.1, SC31-8750 (BLGP6E10). It is essential for your understanding of how Web Access works and of how to customize it that you understand data model records. Once you are familiar with the concepts, you need to build the corresponding data model records for your existing 3270 application. Information Management for z/OS provides a TSX called BLGTDMBL that will do the work for you. BLGTDMBL is also discussed in Chapter 29 of the Tivoli Information Management for z/OS Panel Modification Facility Guide, Version 7.1, SC31-8750 (BLGP6E10). BLGTDMBL was written to scan through your 3270 panels and to create the necessary data model records. It was tested on several applications, including the Integration Facility (IIF); but the more customized your 3270 application is, the more likely the chance that it may miss something. You should start by running it with FUNCTION=SCAN and FLOW=Y. Do one record type at a time, and specify the summary panel for that record type as the START panel. You may find it necessary to do the runs again with a STOP panel (which could mean doing several runs with different START and STOP panels). A data attribute record should be determined for each field on a panel, and even for direct ADD control lines in any control panels through which your application flows. If you are content with the output from SCAN and FLOW, run BLGTDMBL with FUNCTION=CREATE to actually create the data attribute records. However, if you do not seem to be getting the right results, you might try a different approach. You could specify each data-entry panel in your record type as the START and STOP panel on a BLGTDMBL© Copyright IBM Corp. 2003 71
    • run and then do the same thing for all the control panels in your record type. Make sure that you run BLGTDMBL with a session that has your data model database as database 5 (read/write database). That is, if you specify MODELDB as database 4 (read-only) in your session, you need to run BLGTDMBL on a session that has that database defined as database 5 so that records get created on the correct database. After you have created the majority of your data model records, you need to do some clean-up work on them. Specifically, you need to make sure that the “Field prompt” in the data attribute records that were created by BLGTDMBL contain valid data. A new table panel, BLG1TDAR, is shipped with APAR OW54084 (PTF UW92102) and can be used to help with this task. Use the TABLE command to switch to that panel. Then, perform a search that will pick up all the data attribute records you just created with BLGTDMBL: SEARCH RNID/rnidprefix Where rnidprfx is the value you specified as input to BLGTDMBL for the record ID prefix on your data attribute records. You will be able to see the Description abstract and the Field prompt on the search results list. Update the necessary records. Whatever you specify for the Field prompt will be the label of the field on the Web after the HTML is generated. Because Field prompt and Description abstract are pulled into the data view record that was created by BLGTDMBL, now that you have made changes to those values, you need to update the data view record so that those changes are incorporated. Update the data view record and select 3. Data attribute records from the Data View Summary panel. Type over the data attribute record names and press Enter to pull in the changes. It is very important to do this before you start making other changes to the data view record. One of the things that you have to understand about using Information Management for z/OS on the Web versus using it on 3270 is that it does not have to be identical. As a matter of fact, you probably do not want it to look the same. For example, on 3270, you cannot include freeform text on a panel with fields, but on the Web you can. On the “Problem Record Reporter Information” HTML in the Web Access sample, you can enter all of the reporter information, as well as the problem description on one HTML page. You can take the approach of having all of your record fields on one HTML page, or you can spread them out over several pages. The latter is probably the way to go, since no user wants to scroll down endlessly when looking for data. Being able to see everything without scrolling is optimal. Therefore, although you may start out by making your HTML layouts similar to the fields on your data-entry panel, there is no reason why once you have that basic prototype completed that you cannot start moving things around.72 IBM Tivoli Web Access for Information Management
    • 7.1 Panel layouts To set up your Web Access application record layout, you need to modify the data view record that BLGTDMBL created for your record-type data model. Now would be a good time to make a backup of your data view record by using the COPY command. You may want to continue to make copies of your data view before you make large changes. This way, you can easily undo any changes by replacing the data view from one of the copies. We begin by looking at the 3270 data view record summary panel for the data view used for Web Access problem records, BLQVPROB (see Figure 7-1). We use the command UPDATE R BLQVPROB to get into the data view. You should update your data view instead. Figure 7-1 The 3270 Data View Record Summary panel We focus on “5. Web and Desktop field groups” and “6. Web and Desktop panel layouts.” Selecting option 6 returns the panel shown in Figure 7-2 on page 74. Chapter 7. Converting a 3270 application 73
    • Figure 7-2 Desktop Panel Layout Think of the items on the panel layout panel as the tasks that you want to be able to perform with your record (for example, print the record or enter reporter information). You can easily see that there is a direct correlation between the items entered here and the tasks that appear in the navigation area on the left side of the Web Access page (see Figure 7-3 on page 75). Compare the navigation frame of Figure 7-3 on page 75 to Figure 7-2.74 IBM Tivoli Web Access for Information Management
    • Figure 7-3 Problem Summary (Web version)7.1.1 Standard tasks Each of the data view records that you create should probably have tasks for Print Record, History Data, Summary, and Audit Information. Typically, the Print Record, History Data, and Summary tasks only apply when you display a record. The Audit Information task only applies to a search. It contains audit data for searches and includes fields, such as the date the record was created, the date the record was last modified, and the user who last modified the record. Additional details for the Print Record, History Data, and Summary tasks follow. Chapter 7. Converting a 3270 application 75
    • Print Record task The Print Record layout in the data view record tells the HTML generator to include a print task for that type of record. When you select Print Record on the HTML page, a print pop-up dialog box opens on your workstation (see Figure 7-4). The Print Record layout should include all the fields that you want to print when you print that type of record. In addition, it must include a data attribute for the special print record s-word index S0EF7 (see “Print record s-word index S0EF7” on page 44).Figure 7-4 Print pop-up dialog box76 IBM Tivoli Web Access for Information Management
    • History Data task The History Data layout in the data view record tells the HTML generator to include history data for that type of record. When you select History Data on the HTML page, the history data for the record is displayed (see Figure 7-5). The History Data layout must include a data attribute for the special history display s-word index S0ED1 (see “History display s-word index S0ED1” on page 44).Figure 7-5 History Data page Chapter 7. Converting a 3270 application 77
    • Summary task The Summary layout in the data view record tells the HTML generator to include a summary task for that type of record. When you select Summary on the HTML page, the summary data for the record is displayed (see Figure 7-6). The Summary layout should include all the fields that you want to display on the Summary page.Figure 7-6 The Summary data page7.2 Fields and groups When you generate HTML, selecting a task causes it to show up in the navigation area on the left side of the HTML page. The information behind that task, however, is what determines which fields and information are viewed or displayed with that task. For example, consider the Print Record task. Typically, you would want every field in your record (including text) to be printed. So, the Print Record task contains many items (see Figure 7-7 on page 79).78 IBM Tivoli Web Access for Information Management
    • Figure 7-7 Print Record task specificationNow that you have a feel for the “standard” tasks, it is time to discuss record-specific tasks.Spend a few minutes deciding what fields you want grouped together (called a group), andwhat groups and fields you want to be shown on a given HTML page.If you want several fields to be grouped together as a unit on your HTML pages, you shoulddefine them in a group. Using a group is a quick way to include a certain set of fields in acertain order in a task without having to select each field individually and then order them.Groups are especially useful if they are employed in multiple tasks. When you use the HTMLgenerator to build your HTML from your data view record specifications, you can request thatgroups have boxes drawn around them (see Figure 7-9 on page 81). All of the Web AccessHTML is built with boxes around groups.In the Web Access problem record, the Reporter Information task has several associatedgroups and fields (see Figure 7-8 on page 80). Chapter 7. Converting a 3270 application 79
    • Figure 7-8 Grouping example The fields are Problem ID and Description text, and the group is REPORTER. Now take a look at the problem record display-mode HTML page that was generated for the Reporter Information task (see Figure 7-9 on page 81).80 IBM Tivoli Web Access for Information Management
    • Figure 7-9 Example of boxes around groups In this example, the HTML was generated with the Boxes around groups? option selected, so the REPORTER fields are enclosed in a box. Freeform text fields always have a box around them regardless of whether you generate the HTML with boxes around groups or not. As you can see, the Problem ID and Description text fields are outside of the REPORTER group box. Also notice that the group description (Reporter Information) for the REPORTER group in the data views Reporter Information task (see Figure 7-8 on page 80) appears as the title of the box. Every data attribute record in a data view record can be both a field and part of a group. It can also be part of a table. Consider all of the groups defined to data view record BLQVPROB (see Figure 7-10 on page 82). Chapter 7. Converting a 3270 application 81
    • Figure 7-10 Groups defined to BLQVPROB All of the Web Access data view records have a group called SUMHIST that includes record history data, such as date created, date modified, and user modified. This group is included in the Summary, Audit Information, and Print Record tasks. You should consider creating a similar group in your customized data view records. The other groups in Figure 7-10 are record specific. Try defining groups for your fields and specifying those fields as part of tasks. The HTML generator is easy to run and will allow you to see what you are building, get feedback, and help you decide what needs revision. Refer to Chapter 6, “Generating user application HTML” on page 63 for more information about generating the HTML.82 IBM Tivoli Web Access for Information Management
    • 8 Chapter 8. Using existing privilege class records For several reasons, you may not want to use the privilege classes shipped with Web Access. However, before you decide that you do not, please be aware that starting in Version 7.1 of Tivoli Information Management for z/OS, the privilege class eligible-user lists are stored in list processor (LP) format. This enhancement gives you the ability to store hundreds (or even thousands) of users in one privilege class. The old data-entry panel came with only 24. As part of the Version 7.1 install, you were asked to consider running TSX BLGTPRIV to migrate your privilege classes to the list processor format. If you did not do that during the Version 7.1 install, you should do so now.30 Assuming that you want to use your current privilege classes, there are steps you must take so that Web Access will recognize them. You do not have to do anything to get a privilege class to show up in the Switch Roles list. But, if you do not follow the rest of the steps below, you will find yourself on the default home page (BLQWUSER.html) when you switch to one of your privilege classes, which may not be what you want. The Privilege class role defined in the privilege class record is what Web Access uses to determine your home page (see Figure 8-1 on page 84). If your privilege class record does not include a Privilege class role, or there is no lookup record for that role, Web Access assumes a default page of BLQWUSER.html. This processing is performed by business logic in the home_page_exit routine, BLQHOME. You can modify this routine or write your own REXX routine. Refer to 4.3.6, “The home page” on page 40 for more information. 30 Refer to Tivoli Information Management for z/OS Planning and Installation Guide and Reference, GC31-8751 (BLGP2E10).© Copyright IBM Corp. 2003 83
    • Figure 8-1 Defining the Privilege class role If you are satisfied with the five roles and corresponding home pages supplied by Web Access, you can simply update your classes and add a Privilege class role, choosing from among the following: Administrator role—Uses BLQWADMN.html as the home page HTML.31 Analyst role—Uses BLQWALST.html as the home page HTML. Manager role—Uses BLQWMGT.html as the home page HTML. Support role—Uses BLQWSUPP.html as the home page HTML. User role—Uses BLQWUSER.html as the home page HTML. This HTML is also the default used when a privilege class does not have a role. 31 The Administrator role applies to your Information Management for z/OS administrator. The Information Management administrator typically performs the tasks necessary to keep your companys processes running smoothly, such as archiving records or defining a new privilege class. This is not to be confused with a Web administrator, whose purpose is to manage your Web Access application.84 IBM Tivoli Web Access for Information Management
    • If you want to define different roles and home pages, there are several steps that you musttake:1. Update the validation for Privilege class role and add the name of the new desired role or roles. To do this, update data attribute record BLQ&ROLE and add the new role names under 11. Validation data basic. In the example illustrated by Figure 8-2, the new role is Newrole.Figure 8-2 Adding a new role Then, make the same change to data attribute record BLQ&CLRL. Chapter 8. Using existing privilege class records 85
    • 2. Update your privilege class so that it specifies the new role (see Figure 8-3). Figure 8-3 Reflecting the new role in your privilege class record Also, in order for your privilege class record to work with Web Access, it should at least have the following authorities: – Update and display authority for people records – Display authority for privilege class records Depending on the tasks that users will perform while in this privilege class, the class may need other authorities such as solution record display, create, and update. Adjust the other record-specific authorities as needed.86 IBM Tivoli Web Access for Information Management
    • 3. Create a lookup record for the new role (see Figure 8-4). This is a type of reference record. To create it, simply copy one of the existing lookup records: – BLQWADMN —Lookup work items for administrator – BLQWALST—Lookup work items for analyst role – BLQWMGT—Lookup work items for management role – BLQWSUPP—Lookup work items for support role – BLQWUSER—Lookup work items for Web user role Assign a record ID and specify the new role in the Role for this Lookup record field.Figure 8-4 Creating the lookup record Chapter 8. Using existing privilege class records 87
    • 4. Now, create the HTML for your new role. In UNIX System Services, copy existing HTML for one of the Web Access roles. The name of the new HTML file needs to be the same as the name of the lookup record you created in step 3, followed by .html (for example, NEWROLE.html). Edit the new HTML and issue the following: FIND ‘current role’ If the line was located, the located line and the line following it should be similar to the following: <td>Current role</td> <td class=”text_bold”>xxxxxxxx&nbsp.</td> Where xxxxxxxx is a role. Change xxxxxxxx to your new role and save the change. You are now ready to test to make sure that you can get your new home page to display when you choose your privilege class (see Figure 8-5).Figure 8-5 The new home page88 IBM Tivoli Web Access for Information Management
    • Depending on which lookup record you copied, there may be predefined search results thatdisplay at the bottom of the HTML. These predefined searches are defined in the lookuprecord, and all of the Web Access lookup records except BLQWUSER include them. You canchange the predefined search results by updating your new lookup record and selecting 2.Lookup item list. Figure 8-6 shows the predefined searches (Lookup Item List) for theBLQWALST lookup record.Figure 8-6 Changing predefined search resultsThe Item column needs to stay in the same format. Use w.1 - w.x consecutively. The w is forWeb and the number corresponds to the $.labelx and $.datax values that appear in theHTML. If you use another letter, or leave the item blank, Web Access will ignore this line.The Description column is the description of the search that shows up on the HTML. TheRelated information column contains the actual search arguments. In all of the searches inthe example shown in Figure 8-6, the first argument is an s-word index. In these cases, thes-word indexes identify unique record type s-words. If you just did a search on STAC/OPEN,you would get every OPEN record in the database. By putting !S5078 in front of STAC/OPEN,you restrict the search to incident records only.The record type s-words for Web Access records are as follows: S5078—Incident S0B01—Problem S0B06—Change S0B07—Activity S500B—Work S5002—Request S0B05—Solution S0031—People Chapter 8. Using existing privilege class records 89
    • Modify these search arguments as needed. If you include an s-word index in the search argument, it must be preceded by an exclamation point (!). After you file the record, click Home on your Web Access home page (see Figure 8-5 on page 88) to refresh the values and see your changes. Some information that shows up in the navigation area on the left side of the home page is based on the authorities granted in your privilege class. If your class has problem record create authority, the HTML for your new role will automatically show a Create Problem selection (or Incident or Request, depending on what HTML you copied in step 4.) So, the items on the left are dynamically determined and are not directly controlled by the lookup record. Making changes there requires changes using a JavaScript writeln(). You can copy the existing JavaScript if statements and add your own writeln() to add additional dynamic content. Also, BLQHOME is the REXX module that processes the privilege class and lookup records to add content to the home page. You can change the REXX code in BLQHOME if desired, or replace BLQHOME with your own routine. See 4.3.6, “The home page” on page 40 for more information about changing or replacing BLQHOME.90 IBM Tivoli Web Access for Information Management
    • 9 Chapter 9. Using shadow s-words and data attribute records Information Management for z/OS allows you to have a given field on more than one panel within a record. Often, the valid values for the field on the various panels are different. When that is the case, multiple assisted-entry panels or data attribute records are used so that different validation patterns and values may be specified. However, the s-word for the field is always the same and unique to that field. A good example of where this comes into play is with the Status field in Integration Facility problem records. Assisted-entry panel BTN6STAT is used for the Status field on the status data panel, and BTN6STA1 is used for the Status field on the resolve/close panel. You cannot CLOSE the call from the status panel, nor can you OPEN the call on the close panel. Web Access provides a method that allows you to accomplish this same type of customization and flexibility. That process is implemented using a concept that we refer to as using shadow s-words and data attribute records.© Copyright IBM Corp. 2003 91
    • 9.1 Shadow s-words in Web Access Notice in Figure 9-1 that only INITIAL and OPEN are allowed for the Status field.Figure 9-1 Problem Reporter Information page Then, after the problem record has been filed and on a subsequent update, Figure 9-2 on page 93 shows valid values for Status of OPEN, BYPASSED, RESOLVED, and CLOSED.92 IBM Tivoli Web Access for Information Management
    • Figure 9-2 Problem Completion Information page9.2 Status shadow s-words and data attribute records Now, we take a closer look at how shadow s-words actually work. Remember there is a rule that you can only have one data attribute record in a data view record with the same s-word. For example, we could not have data attribute records BLQ&STAT and BLQ&STA1 both in the same data view record for the status s-word S0BEE. Therefore, to get around this restriction, shadow s-words and shadow data attribute records come into play. We have to use multiple data attribute records and specify a shadow s-word in place of the real s-word. A shadow s-word is a unique s-word in the dictionary that is mapped back to the s-word being shadowed by means of using an entry in the BLQPARMS file (see 9.2.1, “The BLQPARMS file” on page 94). Chapter 9. Using shadow s-words and data attribute records 93
    • Web Access ships the following shadow s-words for your use: 5140 XDAR/A1 5141 XDAR/A2 5142 XDAR/A3 5143 XDAR/A4 5144 XDAR/A5 5145 XDAR/B1 5146 XDAR/B2 5147 XDAR/B3 5148 XDAR/B4 5149 XDAR/B5 514A XDAR/C1 514B XDAR/C2 514C XDAR/C3 514D XDAR/C4 514E XDAR/C5 514F XDAR/D1 5150 XDAR/D2 5151 XDAR/D3 5152 XDAR/D4 5153 XDAR/D5 5154 XDAR/E1 5155 XDAR/E2 5156 XDAR/E3 5157 XDAR/E4 5158 XDAR/E5 5159 XDAR/E6 515A XDAR/E7 515B XDAR/E8 515C XDAR/E9 515D XDAR/E10 There is nothing special per se about these s-words. XDAR at the beginning of each s-word just serves as a visual clue that you are working with a data attribute record shadow s-word. The /An - /Enn is just a group scheme to help you keep track of which ones you have used thus far. These same s-words can be used in all record types. The /An s-words could be used for status in problem records, as well as change records. No data is ever stored in a record using these s-words. They merely serve as placeholders for the actual s-word (S0BEE in our example). If you need additional shadow s-words, you can create them in the user 8000 section of the dictionary.9.2.1 The BLQPARMS file In the BLQPARMS file, there is a record_type statement for each record type. Under that statement, you should include a dar_shadows statement for each of your shadow s-word scenarios.94 IBM Tivoli Web Access for Information Management
    • Example 9-1 BLQPARMS file record_type PROBLEM S0032 P create_view BLQVPROB BLQ0P001.html update_view BLQVPROB BLQ0P101.html retrieve_view BLQVPROB BLQ0P200.html search_view BLQVPROB BLQ0P301.html BLQWSRLP.html copy_view BLQVPROB BLQ0P001.html history_view BLQVPROB BLQ0P205.html print_view BLQVPROB BLQ0P206.html text_append S0E01 dar_shadows S0BEE S5140 S5141 S5142 dar_shadows S0C0E S5154 S5155 S5156 S5157 S51589.2.2 Status shadow s-words In Example 9-1, S5140, S5141, and S5142 are shadows for S0BEE. What this means is that when S5140, S5141, and S5142 are encountered during processing, they are replaced with S0BEE so that S0BEE is actually stored with the data in the record. Example 9-1 also shows that completion code S0C0E has five shadows. You need a dar_shadow list for each s-word for which you want to have shadow data attribute records. Use as many dar_shadows keywords as you need.9.2.3 Status shadow data attribute records Each of these shadow s-words has a corresponding shadow data attribute record, as shown in Example 9-2. Example 9-2 Shadow data attribute record S5140 BLQ&PSA1 Problem initial status S5141 BLQ&PSA2 Problem tracking status S5142 BLQ&PSA3 Problem closing Status9.2.4 Groups that include the status shadows If you look at the REPORTER group in data view record BLQVPROB, you see data attribute record BLQ&PSA1 (see Figure 9-5 on page 97); in the TRACK group data attribute record, BLQ&PSA2; and in the CLOSE group data attribute record, BLQ&PSA3. However, in Figure 9-5 on page 97, you also see that data attribute record BLQ&PSAL is selected. BLQ&PSAL (see Figure 9-3 on page 96) includes all the validation patterns that are in data attribute records BLQ&PSA1 (see Figure 9-4 on page 96), BLQ&PSA2, and BLQ&PSA3. 32 32 BLG&PSAL also specifies the real Status s-word S0BEE. Chapter 9. Using shadow s-words and data attribute records 95
    • Figure 9-3 Values in data attribute record BLQ&PSAL Figure 9-4 Values in data attribute record BLQ&PSA1 The important thing to notice in the REPORTER group is the field usage for data attribute records BLQ&PSA1 and BLQ&PSAL.33 Our shadow data attribute record BLQ&PSA1 is required in create and update mode and is display-only in display mode. This means that you can specify OPEN or INITIAL only when in update or create mode. However, since in inquiry mode data attribute record BLQ&PSAL is used, this allows the user there to specify all valid values for the status field throughout the record (see Figure 9-5 on page 97). 33 Note that the values in BLQ&PSA1 are also in BLQ&PSAL.96 IBM Tivoli Web Access for Information Management
    • Figure 9-5 Fields in group REPORTER Internally, Web Access requires that a data attribute record with the real s-word be used in the data view record. The value entered by the user for the shadow data attribute record must pass validation information for the data attribute record with the real s-word. This means that if you add a new value to a shadow data attribute record, you must remember to add the value to the data attribute record with the real s-word. Although it is acceptable to code a pattern 34 in the data attribute record with the real s-word that will cover all of the literal values in the shadow data attribute record, you probably do not want to do that. This is because in inquiry mode, the user could waste time trying to search with values that were never used in any record, since a validation pattern such as CCV8 would allow the user to enter any nine characters.9.3 Building a shadow scenario Before you try to implement shadowing in your application, you should have the basic group and task layout completed. In our example above, you would use one data attribute record (BLQ&PSAL) for each of the groups or tasks, or both, in which you want to include the Status field. Once you have your basic layout completed, then you can start thinking about the fields for which you would like to have different validation patterns in different places. Keep it simple, and implement one field at a time. Here are some basic steps: 1. Choose the field for which you want to set up shadowing. 2. Make a note of the name of the data attribute record for that field and the s-word that field uses. 3. Determine how many shadows you need, that is, how many different groups of validation patterns you need. 34 For example, CCV8. Chapter 9. Using shadow s-words and data attribute records 97
    • 4. Pick which group of shadow dictionary entries are appropriate: a. Start with the /An sequence if there are no other shadows in this data view record type yet, and if the number of shadows you need is less than five. b. Use the /En sequence if available and if the number of shadows you need is more than 5 but less than 10. c. Define your own 8000-level shadow s-word entries if the number of shadows you need is more than 10 or if the /An - /En sequences have already been used in this record type. You could use several of the sequences if you prefer. For example, if you needed eight items, you could use the five /Cn values and three of the /Dn values. Use whatever you find the most convenient for you. 5. Copy the original data attribute record, give it one of the new data attribute record names, and change the real s-word to one of the shadow s-words. Remove the validation patterns from the shadow data attribute record that are not desired. Repeat until you have used all of the new data attribute record names and all of the shadow s-words needed for those data attribute records. 6. Update your record type data view record so that you can update your groups and add the appropriate new shadow data attribute records. Remember that you should leave the original data attribute record in the group and simply add the new data attribute record by selecting it. It is recommended that you move the new data attribute record above or below the original data attribute record so that when working with the group at a later time, you will have the original and shadow data attribute records next to each other. 7. Determine unique data attribute record names for each of the shadow data attribute records that you need. 8. Update the field usage values in your group (see Figure 9-5 on page 97). The original data attribute record should have a blank (“_”) for all modes except inquiry. The shadow data attribute record should have a blank for inquiry, and R, U, or D for the other modes. 9. Update the BLQPARMS file and add the dar_shadows parameter under the correct record_type parameter. 10.Reload the configuration file. 11.Use the HTML generator to rebuild the HTML for your data view record. 12.Drop the HTML cache. 13.Test your changes.9.3.1 Several other variations It is also possible to have shadowing with fields in a task (as opposed to within a group). You just select the original data attribute record and the shadow data attribute record in the task and follow the field usage rules outlined above (see Figure 9-6 on page 99).98 IBM Tivoli Web Access for Information Management
    • Figure 9-6 Shadow a field in a taskIt is also possible to use multiple shadow data attribute records within one group or task. Forexample, you could specify BLQ&PSA1, BLQ&PSA2, BLQ&PSA3, and BLQ&PSAL all in onegroup (see Figure 9-7). The key is that you still have to follow the field usage rules.Figure 9-7 Multiple shadow data attribute records Chapter 9. Using shadow s-words and data attribute records 99
    • 100 IBM Tivoli Web Access for Information Management
    • 10 Chapter 10. Type-based HTML Information Management for z/OS provides the ability to display different panels for different types of problems, changes, and so forth. For example, some of the panels in a problem record are the same, while others may be different based on the value entered into a designated field (usually the problem type field). Software problem records have a unique panel with fields pertinent to software problems, and hardware problem records have a unique panel with fields pertinent to hardware problems, and so forth. This technique is often referred to as nested panels, or may be part of a conditionally required fields scheme. Web Access also provides this capability. The HTML displayed to a user can vary based on the value entered into the type field. Web Access is restricted in that only the type field (data attribute record with S0C09) may be used to determine what HTML to display.© Copyright IBM Corp. 2003 101
    • 10.1 Type-based HTML in Web Access We take a look at an example of how Web Access uses type-based HTML. Notice that the Problem type field in this problem record create scenario has HARDWARE - Hardware problem specified.Figure 10-1 Creating a HARDWARE - Hardware problem record102 IBM Tivoli Web Access for Information Management
    • Then, on the Details HTML page, we see a box for the Hardware Details group.Figure 10-2 The Hardware Details group box Chapter 10. Type-based HTML 103
    • In this problem create scenario, we have specified SOFTWARE - Software problem for the Problem type field.Figure 10-3 Creating a SOFTWARE - Software problem record104 IBM Tivoli Web Access for Information Management
    • On the Details HTML page, we get the Software Details group.Figure 10-4 The Software Details group box10.2 Understanding type-based HTML in the problem record The key to understanding how type-based HTML is set up in Web Access is the data attribute record for the type field and how to set up special groups in the data view record. The Web Access problem record data view record (BLQVPROB) includes a data attribute record (BLQ&PTYP) for S0C09. BLQ&PTYP contains the following list of valid values, as shown in Figure 10-5 on page 106. Chapter 10. Type-based HTML 105
    • Figure 10-5 The BLQ&PTYP data attribute record The list of valid values may be specified directly in the data attribute record as they are for BLQ&PTYP, or they may be specified in a validation record. You do not have to specify literal values (you can use validation patterns such as CCV8), but literal values are highly recommended because follow-on processing depends on the value specified matching up with a group name defined in the data view record.106 IBM Tivoli Web Access for Information Management
    • The following corresponding groups are defined in the BLQVPROB data view record, asshown in Figure 10-6.Figure 10-6 The BLQVPROB data view recordThe Group ID must start with the @ sign for groups based on type. You must also use asecond character to help identify the group. In our example, D helps us remember that thosegroups are for the Details task, and C helps us remember that those groups are for theCompletion Information task. The second character serves as a visual reminder when we arepicking the fields and groups that comprise a given task. The remaining six characters areused to match up to the type value specified above. The six characters must be a subset ofone of the valid values specified in the BLQ&PTYP data attribute record. For example, in&DHARDWA, the last six characters (HARDWA) are a subset of HARDWARE, and therefore,that group will be used for the details task when HARDWARE is specified for the type.There is a reserved group name that you might find helpful. If there is no value for S0C09 inthe record, Web Access uses a value of BLANK@ for S0C09. For example, assume that theuser is doing a search. Typically, type is not a required field on a search. So, it is possible thatthe user could go to the Detail panel without choosing a type. The value of S0C09 would,therefore, be blank. Since the blank value would not match any of the type groups youdefined, the user would end up seeing no type group at all. To avoid that, Web Access willuse a value of BLANK@ for S0C09, and if you define a @DBLANK@ type group, the fields inthat group will be shown. If the user went to the completion page, you would need a@CBLANK@. If these is no BLANK@ group, no type group is shown.3535 Note: You might see a group called @ATTACH. This is a special group used to attach documents, not atype-based group. Chapter 10. Type-based HTML 107
    • Figure 10-7 Groups and fields in the Details task10.3 Key points to remember Please consider the following key points. This type of processing is only supported for data attribute records with S0C09 as the s-word. The type value entered must match one of the data attribute record group names. Otherwise, the group will not display the expected HTML. The type field (as an entry field) must be on a different panel than the corresponding group-based HTML.108 IBM Tivoli Web Access for Information Management
    • 11 Chapter 11. Updating the style file The Web Access application uses an external style sheet to manage the way it displays HTML elements. The style sheet is named blqstyle.css and is installed in the /usr/lpp/InfoMan/web/html/css directory. In the style sheet, you can define such things as the background colors for required and optional fields and the font size and weight of the title at the top of each page. You can modify the style sheet to set the look and feel that you desire; but before you do, make a backup copy of blqstyle.css. You should also be familiar with HTML tags and attributes and cascading style sheets before you make any modifications. Web Access primarily uses classes to define the look of its HTML elements. The following list identifies the classes in blqstyle.css that you may be most interested in modifying. You will see the class name, how Web Access uses it, and the set of attributes that it sets. You can change the value for an attribute, delete an attribute, add an attribute, and so forth. When you change blqstyle.css, you will need to refresh the page displayed on your browser to see any changes. In some cases, you may need to delete your temporary Internet files to see the change.© Copyright IBM Corp. 2003 109
    • Table 11-1 Web Access style sheet classes Class Used for Attribute Value pagetitle The title at the top of each page font-family verdana font-size 14pt font-weight bold color black required Required fields background-color #FFF7DE border-color #A5A684 #CCCCCC #CCCCCC #A5A684 border-style solid border-top-width 1px border-right-width 1px border-bottom-width 1px border-left-width 2px optional Optional fields background-color #ffffff srlodd Odd rows in a search results list background-color #99ccff srleven Even rows in a search results list background-color #ffffff error_message Error messages that appear at the font-weight bold top of a page color red font-size 10pt text-align center padding-top 4px buttons Buttons at the bottom of a page text-align right lp_button List processor buttons Add, Edit, and font-family verdana Remove font-size 8pt submenu The menu items that appear down font-family verdana the left side of a page and across the top of a page font-size 10pt font-weight bold color white text-decoration none lp_table List processor data font-family verdana font-size 10pt font-weight normal color black110 IBM Tivoli Web Access for Information Management
    • Class Used for Attribute Value lp_row_even Even rows on a list processor table background-color #99ccff lp_row_odd Odd rows on a list processor table background-color #ffffff approver_table Change approver table font-family verdana font-size 10pt font-weight normal color black border-collapse separate approved Change approver “Approved” status color #32CD32 pending Change approver “Pending” status color black reject Change approver “Reject” status. color red fft_table_with_audit_data Freeform text data for records font-family verdana accessed in display mode font-size 10pt font-weight normal color black border-style double fft_table_with_audit_data_caption Freeform text field labels for records font-family verdana accessed in display mode font-size 10pt font-weight bold color black The blqstyle.css file also sets attributes for the table and a (anchor) tags and the pseudo-class hover for the a tag.Table 11-2 Web Access style sheet tags Tag Used for Attribute Value table (All Web Access pages are tables. This tag controls the font-family verdana table elements on the page not controlled by other styles.) font-size 10pt color black td.menu Formatting the text that makes up the menu across the top padding-top 4px of a page. padding-bottom 5px background-color #50589F td.menuframe The menu down the left side of a page. vertical-align top background-color #50589F a a (anchor) elements that do not have a class coded. this color #333399 includes anchors, such as the record numbers in search results lists. Chapter 11. Updating the style file 111
    • Tag Used for Attribute Value a:hover The hover pseudo-class for a (anchor) elements that dont background-color #d3d3d3 have a class coded. This sets the hover for anchors, such as the record numbers in search results lists. a.submenu:hover The hover pseudo-class for a (anchor) elements that have color #9fcfcf class=”submenu”. This sets the hover for the menu items that appear down the left side of a page and across the top background-color #50589F of a page.112 IBM Tivoli Web Access for Information Management
    • Part 3Part 3 Administration Part 3 covers Web administration tasks and procedures.© Copyright IBM Corp. 2003 113
    • 114 IBM Tivoli Web Access for Information Management
    • 12 Chapter 12. Web administration Web Access provides a set of administrative tasks that, as the Web Administrator, you will need to perform to manage your Web Access application. These tasks, including such things as generating HTML and refreshing the HTML cache, are available to authorized users on the Web Administration page. To authorize a user as a Web Administrator, you must specify that user as an eligible user in the privilege class identified by the admin_class parameter in your configuration file.36 This privilege class is a special class used by Web Access exclusively to determine who is entitled to perform Web administration. Any user listed in this class is authorized to perform Web Administration and will see an Administer Web hyperlink on his home page. Clicking the Administer Web hyperlink takes him to the Web Administration page. The tasks that are available on the Web Administration page are described in 12.1, “Tasks” on page 116. As you change and manage your Web Access application, you may need to run some of these tasks. Section 12.2, “Procedures” on page 119 identifies typical changes that you may make to your application and the tasks you may need to run to ensure those changes are enabled. 36Refer to Appendix C, “Web Access configuration parameters” on page 163 for information regarding the configuration file.© Copyright IBM Corp. 2003 115
    • 12.1 Tasks The following are the administrative tasks that are available on the Web Administration page.Figure 12-1 The Web Administration page12.1.1 Navigation area tasks The following describes the tasks in the navigation area on the left side of the Web Administration page. View Configuration File Clicking this link allows you to view the current settings in your configuration file. The configuration file is pointed to by the environment variable INFOMANWEBTOOLKITCONF and is commonly referred to as the BLQPARMS file.116 IBM Tivoli Web Access for Information Management
    • View TraceThis task displays the contents of the ErrorLog file (httpd-errors) in your browser. This filecontains REXX trace, debugging messages, and other information helpful when trying totrack data or user problems. It can be viewed as a flat file or in a text box (which allows easiercut and paste).Drop User Information PoolThis task destroys the cached data for all users (their current class, time zone, and dateformat). The data will be re-cached the next time each user performs a transaction thatinteracts with the Web server.Drop HTML CacheUse this feature when making changes to any HTML pages so that other users will be able toobtain the most current HTML page updates.Drop Privilege Class PoolIf changes are made to any of the privilege class records, select this option to allow the mostcurrent information in the record to be accessed.Reload Configuration FileThis task causes the configuration file pointed to by the environment variableINFOMANWEBTOOLKITCONF (in the httpd.envvars file) to be refreshed. This is commonlyreferred to as the BLQPARMS file.Free PoolsThis task releases all the sessions the Web server has with the BLX-SP so that the sessionscan be used. Certain errors detected by the Web server do not allow BLQWSWRT to receivecontrol when a Web transaction completes. When this occurs, the session is not freed. If thisoccurs enough times, Web users will receive the message No free sessions on theirbrowsers. Using this link should free those sessions, avoiding the need to stop and restart theWeb server. Look in the ErrorLog file (httpd-errors) for errors and correct them. Using freepools will lead to storage shortages on the Web server.Recycle HLAPIThis function enables you to terminate the active sessions the Web server has with BLX-SP.Each session will be restarted as needed when a new request is processed. This allowsfuture requests to use updated data model records that were cached, privilege classes thatwere cached, and cached PMF panels.Validate HTMLThis is a link to a Web site that enables you to verify the syntax of your HTML pages. Refer tothe instructions at the Web site for more information.37Test Web ServerClicking this link verifies that you are properly communicating with the HTTP Web server.Debug OptionsThis is a feature that should help debug REXX code, as well as turn on PDB tracing in theHLAPILOG.37 This Web site is on the Internet. However, your companys firewall may prevent you from accessing this site. Chapter 12. Web administration 117
    • 12.1.2 Field-initiated tasks The following describes the fields on the Web Administration page. You can enter data into a field and click the corresponding button to initiate a particular task. API return code By entering data in these fields and clicking the Display button, you can view the error description text for the given API return and reason code. HTML member name If you know the name of the HTML page that you would like to edit, it can be entered in this field. Then click the Edit button. If you need to view a list of all the HTML pages, click the List of HTML link to show it. Using this method to edit HTML automatically drops the HTML cache after making any changes to HTML pages. If you edit the panels using ISPF, you need to drop the HTML cache using the Drop HTML Cache feature. Create HTML Use this feature to create your own HTML page from an existing data view record (see 6.1, “The HTML generator” on page 64). Test HTML This task enables you to supply a record number and HTML page and view the record. You can choose to use update mode (which checks out the record) and select whether your profile data should be used. If you do select Get Profile data, you can then use the equal sign to add equal sign data from your profile to the HTML being tested. Run A TSP/TSX This option enables you to run either a TSP or TSX, as well as pass parameters to it. If desired, the TSP/TSX can be run using the debug option, which causes any output data and messages returned by the TSX to be shown. If you use the TSP/TSX name of BLQTWIRC and enter the following into the User parameter data field, Web Access will display the users in the BLQADMN class when you click the Run button: ;;DISPLAY,1,5,2,BLQADMN,,2, The ability to run and test an Immediate Response Chain (IRC)38 can be very useful when you are writing your business logic. The two semicolons that start the IRC cause TSX BLQTWIRC to return the last screen displayed. 38 See Tivoli Information Management for z/OS User’s Guide, Version 7.1, SC31-8756 (BLGU2E10), pages 235-239.118 IBM Tivoli Web Access for Information Management
    • 12.2 Procedures Making changes in Information Management for z/OS or the Web Access environment requires you to use Web Administration tools so that Web Access will pick up your changes. Stopping and restarting the Web server is the equivalent of executing these tasks, since it refreshes and reloads everything, and there are people who like to do that when they are in test mode. But once you are in production mode, following these rules will allow you to do only what is necessary to allow a change to take effect: You must select Drop HTML Cache any time you change the HTML using ISPF or FTP. However, if you change the HTML using the HTML edit page in Web Access, Web Access drops the HTML cache for you when you save your HTML. You must select Drop HTML Cache whenever you change a data attribute or validation record that has literals (which are used to build the drop-downs). When you generate HTML, Web Access drops the HTML cache for you. If you add or remove a user ID from a privilege class record, you should select Recycle HLAPI. We recommend that you remove or add all of the user IDs and then do one recycle after you are done. If you add or remove a data attribute record from a data view record, you must select Recycle HLAPI.39 On the other hand, if you are just rearranging the data attribute records in the data view and working with groups and layouts, a recycle is not needed. If you change the authorities in a privilege class (such as adding, updating, or removing close authority), you must select Drop Privilege Class Pool. If you change the configuration file, you must select Reload Configuration File. However, if you change any of the following, you must select Recycle HLAPI after you Reload Configuration File: – debug api – tsx_dsname – rft_dsname – application_id – privilege_class – admin_class – work_id – work_class – session_member – databases – model_database – text_width – hlimsg_option – apimsg_option – spool_interval – table_count – class_count – timeout_interval – bypass_panel_processing – default_data_storage_size – model_rnid_prefix 39 For performance, we recommend you run BLGUT18 to build static PIDTs of your data views. If you use static PIDTs, you must run BLGUT18 before you Recycle HLAPI (see Chapter 6, “Generating user application HTML” on page 63). Chapter 12. Web administration 119
    • If you delete a people record for a Web user (which you can do using 3270), you must select Drop User Information Pool so that Web Access will create a new people record for that user the next time he or she accesses the Web. Otherwise, cached user information may be used, and the user will then receive a Record not found message and fail with a RC12 reason 10 when Web Access needs to access a non-cached people record data for that user. If you delete a privilege class record (which you can do using 3270), you must select Drop User Information Pool and Drop Privilege Class Pool so that Web Access will not attempt to use the deleted class. Be aware that if you delete a privilege class record that is the only class for a given user, this does not prevent the user from using Web Access, because Web Access will add the user to the default class (BLQUSER). If you want to prevent a user from using Web Access, you should remove that user’s user ID from SAF or remove that user’s user ID from all current privilege class records and add it to a class that has NO authority. If Web Access finds the user in at least one class, it does not add the user to the default class. The lack of authority in this class prevents the user from doing anything with Web Access. If you receive a message on your Web browser that No sessions are available, try Free Pools. If this message occurs enough times, using Free Pools will lead to storage shortages on the Web server. Having to free sessions using Free Pools indicates that an error is occurring. Should this happen, you should review your logs and traces and correct the indicated error.120 IBM Tivoli Web Access for Information Management
    • Part 4Part 4 Appendixes Part 4 contains the following appendixes: Appendix A, “Business logic examples” on page 123 Appendix B, “Hints and tips” on page 153 Appendix C, “Web Access configuration parameters” on page 163© Copyright IBM Corp. 2003 121
    • 122 IBM Tivoli Web Access for Information Management
    • A Appendix A. Business logic examples The Web Access drop-in problem and change management solution uses three business logic exit routines: 1. BLQUXPRE is the predisplay_exit routine. Logic in BLQUXPRE prefills fields in a new record with information about the person for which the record is being created. It also prefills some fields based on the type of record being created. If a User 40 running Web Access chooses to create an incident, the logic redirects that user to a different HTML page. 2. BLQUXVAL is the validation_exit routine. Logic in BLQUXVAL sets name fields so that they are searchable in various formats. If you are filing a new problem, it also verifies that the record has been assigned: – For problem and incident records that have just been closed, it calculates and sets the duration for the time that they were open. – For change and activity records that have just been closed, it calculates and sets the duration that it took to complete them. – For records that are being assigned to a different assignee, it resets the assigned date and time to the current date and time. 3. BLQUXFIL is both the postfile_create_exit routine and the postfile_update_exit routine. Logic in BLQUXFIL primarily does e-mail notification. It uses the notification method identified by the email_tsx parameter in the BLQPARMS file. As shipped, the email_tsx parameter is set for immediate notification, but it can be modified to use queued notification. You might want to use queued notification for performance reasons.41 Refer to “Business logic exit routine directives” on page 169 for more information on the email_tsx parameter. Additional processing in BLQUXFIL also automatically creates a solution record from a problem record when that problem is closed. 40 Please note that “User” (capitalized) denotes the particular role in which a user or individual (denoted by the lowercase “u”) is running. 41 See “Sending E-mail Messages” in the Tivoli Information Management for z/OS Program Administration Guide and Reference, Version 7.1, SC31-8753, page 95© Copyright IBM Corp. 2003 123
    • BLQUXPRE BLQUXPRE runs before an HTML page appears. The main business logic code is placed after the block comment that instructs you to Put business logic code here. This code calls a couple of subroutines. These subroutines are placed after the Exit statement. The REXX code is included below. The text in blue is code from the BLQUEXIT template that was copied and renamed BLQUXPRE. The other text is the code that was added for the business logic. Example: A-1 BLQUXPRE /*********************************************************************/ /* Put business logic code here. Use Update_Data subroutine to */ /* write an updated or new variable and value to the read/write */ /* pool. */ /*********************************************************************/ Note: The following code prefills fields with user information and other defaults. User information is obtained from the users profile, which is a people record in the Information Management for z/OS database. Fields are prefilled only when a new record is being created. If a record is being copied, the date entered, time entered, and entry class fields are set to = in the copy so that they will be set with current values when the copy is filed. If a record is being created: Call the subroutine Get_People_Data to retrieve user information from the users profile and prefill those fields. Set the reporter or requester ID (S14FD) to the users ID. Set the status (S0BEE) to OPEN. If a problem is being created, set the severity (S7D42) and priority (S0BE7) to 3. If an incident is being created, set the severity (S7D42) and priority (S0BE7) to 4. Call the subroutine Get_Coordinator_Data to prefill coordinator data. If a User running Web Access is creating an incident, redirect that user to the BLQ0I001.html page.a This code uses the Web Access REXX global variables ?MODE to determine if the user is copying or creating a record, ?RECORD_TYPE to determine if the user is working with a problem or incident record, and ?ROLE to determine if the user is running as a User. It uses the Update_data subroutine provided with the BLQUEXIT template to set the value for a field and put the variable into the REXX global variable pool. To set the value for a field, set the s-word variable to the value and set the s-word.?type to the type of data. Then call Update_data. In the following example, S0BEE is the s-word for the status field. The type of data is D.b S0BEE = OPEN /* Set default status */ S0BEE.?type = D /* Set data type */ Call Update_Data S0BEE /* Add to pool */ a. Note that the redirected HTML page is returned on the Exit statement. b. D is the type for all fields except freeform text and lists. /*********************************************************************/ /* Normally you do not want the business logic to run for the Admin */ /* Role. This allows the Administrator to control all the data. */ /* You can remove/relocate this line if you want all or part of the */ /* business logic to run in the Admin role. @01A*/ If translate(?ROLE) = ADMINISTRATOR then exit 200 /*@01A*/ new_html = /* Clear the new html */124 IBM Tivoli Web Access for Information Management
    • Select When ?record_type = PEOPLE Then /* No prefill logic */ Signal EndREXX /* Return to caller */ When ?mode = UPDATE Then /* No update prefill logic */ Signal EndREXX /* Return to caller */ When ?mode = COPY Then /* Do copy logic */ Do S0C34 = = /* Replace DATE/ */ S0C34.?type = D /* Set data type */ Call Update_Data S0C34 /* Add to pool */ S0C61 = = /* Replace TIME/ */ S0C61.?type = D /* Set data type */ Call Update_Data S0C61 /* Add to pool */ S0BB1 = = /* Replace CLAE/ */ S0BB1.?type = D /* Set data type */ Call Update_Data S0C61 /* Add to pool */ If ?record_type = INCIDENT, /* Incident record @02A*/ & ?role = User Then /@02A*/ new_html = HTML BLQ0I001.html /* User HTML name @02A*/Signal EndREXX /* Return to caller */ End When ?role = Administrator Then Nop; /* No prefill data for Admin*/ When ?mode = CREATE Then /* Create prefill logic */ Do /***************************************************************/ /* If the reporter/requester id hasnt been specified yet, */ /* prefill the fields. */ /***************************************************************/ if SYMBOL(S14FD)=LIT then /* If reporter id not present, */ do /* prefill the fields */ Call Get_People_Data /* Retrieve info for caller */ S14FD = ?caller_id /* Set reporter/requester ID */ S14FD.?type = D /* Set data type */ Call Update_Data S14FD /* Add to pool */ S0BEE = OPEN /* Set default status */ S0BEE.?type = D /* Set data type */ Call Update_Data S0BEE /* Add to pool */ If ?record_type = PROBLEM then /* Creating Problem */ Do S7D42 = 3 /* Set default severity */ S7D42.?type = D /* Set data type */ Call Update_Data S7D42 /* Add to pool */ S0BE7 = 3 /* Set default priority */ S0BE7.?type = D /* Set data type */ Call Update_Data S0BE7 /* Add to pool */ End else if ?record_type = INCIDENT then /* Creating Incident */ do S7D42 = 4 /* Set default severity */ S7D42.?type = D /* Set data type */ Call Update_Data S7D42 /* Add to pool */ if ?role=User then do S0BE7 = 4 /* Set default priority */ S0BE7.?type = D /* Set data type */ Call Update_Data S0BE7 /* Add to pool */ end end Appendix A. Business logic examples 125
    • if ?record_type=INCIDENT & , /* If self-service */ ?role=User then Nop; /* incident, do nothing */ else /* Anything else, get */ Call Get_Coordinator_Data /* coordinator data for user */ end else Nop; /***************************************************************/ /* If creating an incident record and the users current role */ /* is USER, then this is a self-service request. Show */ /* simplified HTML page to this user. */ /***************************************************************/ If ?record_type = INCIDENT, /* Incident record */ & ?role = User Then Do new_html = HTML BLQ0I001.html /* User HTML name */ Signal EndREXX /* Return to caller */ End End Otherwise Signal EndREXX /* Return to caller */ End /* End SELECT */ /*********************************************************************/ /* Externalize pool updates before returning to the caller. */ /*********************************************************************/ EndREXX: /* Module exit */ Call Save_Pool_Data /* Update REXX pool */ Exit 200 new_html /* Return completion code */ Note: The subroutine Get_People_Data retrieves information from the users profile, which is a people record in the Information Management for z/OS database. The user is identified by the Web Access REXX global variable ?CALLER_ID, which is also the record ID of the user’s people record. This code invokes the HLAPI/REXX RETRIEVE transaction to retrieve the people record for the user. It uses data view BLQVRPEO, which is a scaled-down version of the people record. Input PDBs identify the fields to be returned. These are the fields to be prefilled in the current record. Most of these fields are defined in the people record by the same s-word as they are in problem, change, and other records. However, the users name, department, and phone use different s-words. Alias table BLQYREPA is used to map these fields from the people record to the corresponding fields in problem, change, and other records. The requested data is returned in output PDBs. The code loops through the output PDBs, sets the value for each prefilled field, and calls the Update_data subroutine provided with the BLQUEXIT template to put each prefilled field into the REXX global variable pool. /*********************************************************************/ /* Get the information from the People record about this caller. */ /*********************************************************************/ Get_People_Data: routine = Get_People_Data trans = RETRIEVE Drop blg_envp blg_envp = blg_envp_db5 rnid_symbol = ?caller_id data_view_name = BLQVRPEO alias_table = BLQYREPA126 IBM Tivoli Web Access for Information Management
    • control.1 = modulecontrol.2 = routinecontrol.3 = data_view_namecontrol.4 = rnid_symbolcontrol.5 = alias_tablecontrol.0 = 5/*********************************************************************//* Only get the fields from the People record that are needed to *//* fill the reporter/requester information. *//*********************************************************************/input. = /* Clear input values */input.1.?name = S0B59 /* Name */input.2.?name = S0B9B /* Department */input.3.?name = S0B2D /* Phone */input.4.?name = S01D2 /* Contact method */input.5.?name = S01D1 /* E-mail address */input.6.?name = S15F7 /* Company */input.7.?name = S152A /* Address */input.8.?name = S152C /* City/State */input.9.?name = S50A0 /* Cubicle */input.10.?name = S152E /* Zip code */input.11.?name = S15F3 /* Mobile phone */input.0 = 11output. = output.0 = 0parms = trans,CONTROL,INPUT,OUTPUTaddress LINK BLGYRXM parmsIf blg_rc = 12 & blg_reas = 31 Then rc=0cc = rcIf cc > 0 Then Signal API_BombedDo i = 1 To output.0 rname = output.i.?name If symbol(rname) = BAD Then Iterate i If rname = SEPARATOR_CHARACTER Then Do separator_character = retout.rname Iterate i End If output.rname = Then /* Data is not blank */ Do /* Add to pool */ Call Value rname,strip(output.rname,B) Call Value rname.?type,D Call Update_Data rname EndEnd /* End do loop */Return Appendix A. Business logic examples 127
    • Note: The subroutine Get_Coordinator_Data retrieves information from the coordinators profile, which is a people record in the Information Management for z/OS database. The coordinator is identified by the Web Access REXX global variable ?user_profile_id, which is also the record ID of the user’s people record. The coordinator is the person creating the record. The coordinator might or might not be the user for which the record is being created. That user is identified by ?caller_id. This code invokes the HLAPI/REXX RETRIEVE transaction to retrieve the people record for the coordinator. It uses data view BLQVRPEO, which is a scaled-down version of the people record. Input PDBs identify the fields to be returned. Only the name, department, and phone are requested. The data is returned in output PDBs. The code loops through the output PDBs. It maps each field from the people record to the coordinator field, sets the value, and calls the Update_data subroutine provided with the BLQUEXIT template to put the coordinator field into the REXX global variable pool. Before the subroutine returns, it also sets the coordinator ID field (S50DB) to the coordinators ID (?user_profile_id) using the Update_data subroutine. /*********************************************************************/ /* Get the information from the People record about this user. */ /*********************************************************************/ Get_Coordinator_Data: routine = Get_Coordinator_Data trans = RETRIEVE Drop blg_envp blg_envp = blg_envp_db5 rnid_symbol = ?user_profile_id data_view_name = BLQVRPEO control.1 = module control.2 = routine control.3 = data_view_name control.4 = rnid_symbol control.0 = 4 /*********************************************************************/ /* Only get the fields from the People record that needed to fill */ /* the reporter/requester information. */ /*********************************************************************/ input. = /* Clear input values */ input.1.?name = S151F /* Name */ input.2.?name = S151E /* Department */ input.3.?name = S15F0 /* Phone */ input.0 = 3 output. = output.0 = 0 parms = trans,CONTROL,INPUT,OUTPUT address LINK BLGYRXM parms If blg_rc = 12 & blg_reas = 31 Then rc=0 cc = rc If cc > 0 Then Signal API_Bombed128 IBM Tivoli Web Access for Information Management
    • Do i = 1 To output.0 rname = output.i.?name If symbol(rname) = BAD Then Iterate i If rname = SEPARATOR_CHARACTER Then Do separator_character = retout.rname Iterate i End /******************************************************************/ /* Copy returned data to the correct field in the record. */ /******************************************************************/ Select When rname = S151F Then /* Name */ fname = S0B5C /* Coordinator name */ When rname = S151E Then /* Department */ fname = S0B9E /* Coordinator department */ When rname = S15F0 Then /* Phone */ fname = S0B30 /* Coordinator phone */ Otherwise Iterate i End /* End Select */ If output.rname = Then /* Data is not blank */ Do /* Add to pool */ Call Value fname,strip(output.rname,B) Call Value fname.?type,D Call Update_Data fname End End /* End do loop */ S50DB = ?user_profile_id /* Set coordinator ID */ S50DB.?type = D /* Set data type */ Call Update_Data S50DB /* Add to pool */ ReturnBLQUXVAL BLQUXVAL runs when you switch to a different HTML view or file a record. The main business logic code is placed after the block comment that instructs you to “Put business logic code here.” This code calls one subroutine. This subroutine is placed after the Exit statement. The REXX code is included below. The text in blue is code from the template BLQUEXIT, which was copied and renamed to BLQUXVAL. The other text is the code that was added for the business logic. Example: A-2 BLQUXVAL /*********************************************************************/ /* Put business logic code here. Use Update_Data subroutine to */ /* write an updated or new variable and value to the read/write */ /* pool. */ /*********************************************************************/ Note: The following code automatically sets a name field using the ID from the ID field. If an ID was entered or changed, the code gets the name associated with the ID and puts that name into the corresponding name field. It uses the Just_Changed subroutine provided with the BLQUEXIT template to test whether an ID field was just changed. It uses the Userid_to_Name and Update_Data subroutines also provided with the BLQUEXIT template to get the name associated with the ID and put it into the REXX global variable pool. Appendix A. Business logic examples 129
    • /*********************************************************************/ /* Normally you do not want the business logic to run for the Admin */ /* Role. This allows the Administrator to control all the data. */ /* You can remove/relocate this line if you want all or part of the */ /* business logic to run in the Admin role. @01A*/ If translate(?ROLE) = ADMINISTRATOR then exit 200 /*@01A*/ If Just_Changed(S14FD) Then /* Caller ID */ Do S0B59.?type = D S0B59 = Userid_to_Name(S14FD) If S0B59 = Then Exit 200 S14FD <br />No data for S14FD found Call Update_Data S0B59 End If Just_Changed(S50E0) Then /* Requester ID */ Do S5069.?type = D S5069 = Userid_to_Name(S50E0) If S5069 = Then Exit 200 S50E0 <br />No data for S50E0 found Call Update_Data S5069 End If Just_Changed(S50C5) Then Do S0B5A.?type = D S0B5A = Userid_to_Name(S50C5) If S0B5A = Then Exit 200 S50C5 <br />No data for S50C5 found Call Update_Data S0B5A End If Just_Changed(S50CF) Then Do S0B5B.?type = D S0B5B = Userid_to_Name(S50CF) If S0B5B = Then Exit 200 S50CF <br />No data for S50CF found Call Update_Data S0B5B End If Just_Changed(S50DB) Then Do S0B5C.?type = D S0B5C = Userid_to_Name(S50DB) If S0B5C = Then Exit 200 S50DB <br />No data for S50DB found Call Update_Data S0B5C End130 IBM Tivoli Web Access for Information Management
    • Note: The following code runs when the user files a record. It runs before the record is actually filed in the Information Management for z/OS database. Web Access REXX global variable ?FILE is used to determine if the user is filing a record. If you are filing a record, the code: Sets additional name fields so that names are searchable in various formats. Verifies that it has been assigned if you are filing a new problem. If has not been assigned, you are redirected to the Tracking Information page (BLQ0P002.html). Verifies the completion date is after the date occurred and calculates that duration if a problem or incident was just closed. Verifies that the completion date is after the start date and calculates that duration if a change or activity was just finished. Sets the date and time assigned to “=” if the assignee changed. The first two bullets are described below and that code immediately follows. The details for the other bullets and their corresponding code appear later This code uses the Changed subroutine provided with the BLQUEXIT template to test whether a name field was changed. It uses the Parse_Name, Add_Separator, and Update_Data subroutines also provided with the BLQUEXIT template to make each name searchable in different formats: John Smith, Smith/John, Smith/J, Smith, John Web Access REXX global variable ?MODE is used to determine if the user is copying or creating a record, and ?RECORD_TYPE is used to determine if the user is working with a problem. If this is a new problem, it must be assigned. If there is no assignee ID (S50C5), the user is redirected to the Tracking Information page.If ?file = 1 Then Do If Changed(S500D) Then /* Approver Name */ Do S50E5.?type = D S50E5 = Parse_Name(S500D) S50E5 = Add_Separator(S50E5) Call Update_Data S50E5 End If Changed(S5106) Then /* Backup Name */ Do S50E6.?type = D S50E6 = Parse_Name(S5106) S50E6 = Add_Separator(S50E6) Call Update_Data S50E6 End If Changed(S5105) Then /* Manager Name */ Do S50E7.?type = D S50E7 = Parse_Name(S5105) S50E7 = Add_Separator(S50E7) Call Update_Data S50E7 End If Changed(S151F) Then /* Name (in people record ) */ Do S50E8.?type = D S50E8 = Parse_Name(S151F) S50E8 = Add_Separator(S50E8) Call Update_Data S50E8 End Appendix A. Business logic examples 131
    • If Changed(S0B5B) Then /* Resolver Name */ Do S50E9.?type = D S50E9 = Parse_Name(S0B5B) S50E9 = Add_Separator(S50E9) Call Update_Data S50E9 End If Changed(S0B59) Then /* Reporter/requester name */ Do S50EA.?type = D S50EA = Parse_Name(S0B59) S50EA = Add_Separator(S50EA) Call Update_Data S50EA End If Changed(S5069) Then /* Requested By Name */ Do S50EB.?type = D S50EB = Parse_Name(S5069) S50EB = Add_Separator(S50EB) Call Update_Data S50EB End If Changed(S0B5C) Then /* Coordinator Name */ Do S50EC.?type = D S50EC = Parse_Name(S0B5C) S50EC = Add_Separator(S50EC) Call Update_Data S50EC End If Changed(S0B5A) Then /* Assignee Name */ Do S50ED.?type = D S50ED = Parse_Name(S0B5A) S50ED = Add_Separator(S50ED) Call Update_Data S50ED End If (?mode = CREATE | ?mode = COPY) & , (?record_type = PROBLEM) Then Do If S50C5 = S50C5 | S50C5 = Then Exit 200 HTML BLQ0P002.html Please enter an assignee ID. End132 IBM Tivoli Web Access for Information Management
    • Note: The following code runs when a problem or incident is closed. It verifies the completion dateand time is after the date and time it occurred and calculates the duration between them.Web Access REXX global variable ?RECORD_TYPE is used to determine if the user is working witha problem or incident, and the Changed subroutine provided with the BLQUEXIT template is used totest that the status (S0BEE) is newly CLOSED.The HLAPI/REXX USERTSP transaction is invoked to convert the date occurred (S0C3D) and datecompleted (S0C40) from the users external format to the Information Management for z/OS internalformat using Web Access TSX BLQTXCVT. The slashes are dropped from the internal format, andthe date and time completed are verified as being after the date and time occurred. If not, you areredirected to the Completion Information page (BLQ0P104.html) to specify a valid completion dateand time.The duration between the date and time completed and the date and time occurred is nowcalculated. The REXX function Date is used along with subroutine hhmm2min to determine thedifference. The result is formatted into dddd:hh:mm and set in the total duration field (S50B9). TheUpdate_data subroutine provided with the BLQUEXIT template is used to put the total duration intothe REXX global variable pool.Additional details are in “Using dates, date formats, and time zones in business logic” on page 144. /* Calculate the total duration when a problem record is closed */ /* using date/time occurred and date/time completed. */ If Changed(S0BEE) & S0BEE = CLOSED & , ((?record_type = PROBLEM) | (?record_type = INCIDENT)) then Do input.= /* Clear input stem variable */ trans=USERTSP /* Set the API transaction */ DATE_FORMAT = ?date_format /* Date calculations need user */ TIME_ZONE = ?time_zone /* settings... */ control.1 = DATE_FORMAT; control.2 = TIME_ZONE; control.0 = 2; tsp_name = BLQTXCVT /* Date converter TSX */ CDATE.1 = S0C3D /* Date occurred */ CDATE.2 = S0C40 /* Date completed */ CDATE.0 = 2 /* Values to be converted */ CONVERT = EXTTOINT /* Convert external to internal */ input.1.?name = tsp_name /* Put tsx name in input variable*/ input.2.?name = CDATE. input.3.?name = CONVERT input.0 = 3 parms=trans,CONTROL,INPUT,OUTPUT address LINK BLGYRXM parms /* call the API */ cc = rc /* Save the return code */ if cc = 0 then /* Bad return code? */ signal API_Bombed /* code goes here */ date1 = output.uintdate.1 date2 = output.uintdate.2 Appendix A. Business logic examples 133
    • /* Get rid of slashes in internal date */ date1 = Translate(01235689,date1,0123456789) date2 = Translate(01235689,date2,0123456789) If date2 < date1 | (date2 = date1 & S0C71 < S0C6A) then Exit 200 HTML BLQ0P104.html Date/time completed must be , greater than date/time occurred: S0C3D S0C6A. days = date(b,date2,s) - date(b,date1,s) minutes1 = hhmm2min(S0C6A) /* Convert time occurred to mins */ minutes2 = hhmm2min(S0C71) /* Convert time completed to mins */ total_minutes = minutes2 - minutes1 /* Fix minutes to be positive if negative...borrow from days */ if total_minutes < 0 then do days = days - 1 total_minutes = total_minutes + 1440 end hours = total_minutes % 60 minutes = total_minutes // 60 /* Total duration is in the DDDD:HH:MM format */ days = RIGHT(days,4,0) hours = RIGHT(hours,2,0) minutes = RIGHT(minutes,2,0) S50B9 = days||:||hours||:||minutes S50B9.?type = D /* Set data type */ Call Update_Data S50B9 /* Set Total Duration */ End Note: The following code runs when a change or activity is finished. It verifies the completion date and time is after the start date and time and calculates the duration between them. Web Access REXX global variable ?RECORD_TYPE is used to determine if the user is working with a change or activity, and the Changed subroutine provided with the BLQUEXIT template is used to test that the status (S0BEE) is newly CLOSED, COMPLETE, INSTALLED, or CANCELLED. The HLAPI/REXX USERTSP transaction is invoked to convert the start date (S0C43) and date completed (S0C40) from the users external format to the Information Management for z/OS internal format using Web Access TSX BLQTXCVT. The slashes are dropped from the internal format, and the completion date and time are verified as being after the start date and time. If not, you are redirected to the Completion Information page (BLQ0C105.html) to specify a valid completion date and time. The duration between the completion date and time and the start date and time is now calculated. The REXX function Date is used along with subroutine hhmm2min to determine the difference. The result is formatted into dddd:hh:mm and set in the actual duration field (S0C97). The Update_data subroutine provided with the BLQUEXIT template is used to put the actual duration into the REXX global variable pool. Additional details are in “Using dates, date formats, and time zones in business logic” on page 144. /* Calculate the actual duration when the date and/or time */ /* completed in a change or activity record changes. */ If Changed(S0BEE) & (S0BEE = CLOSED | S0BEE = COMPLETE , S0BEE = INSTALLED | S0BEE = CANCELLED) & , ((?record_type = CHANGE) | (?record_type = ACTIVITY)) then Do input.= /* Clear input stem variable */ trans=USERTSP /* Set the API transaction */ DATE_FORMAT = ?date_format /* Date calculations need user */134 IBM Tivoli Web Access for Information Management
    • TIME_ZONE = ?time_zone /* settings... */ control.1 = DATE_FORMAT; control.2 = TIME_ZONE; control.0 = 2; tsp_name = BLQTXCVT /* Date converter TSX */ CDATE.1 = S0C43 /* Actual start date */ CDATE.2 = S0C40 /* Date completed */ CDATE.0 = 2 /* Values to be converted */ CONVERT = EXTTOINT /* Convert external to internal */ input.1.?name = tsp_name /* Put tsx name in input variable*/ input.2.?name = CDATE. input.3.?name = CONVERT input.0 = 3 parms=trans,CONTROL,INPUT,OUTPUT address LINK BLGYRXM parms /* call the API */ cc = rc /* Save the return code */ if cc = 0 then /* Bad return code? */ signal API_Bombed /* code goes here */ date1 = output.uintdate.1 date2 = output.uintdate.2 /* Get rid of slashes in internal date */ date1 = Translate(01235689,date1,0123456789) date2 = Translate(01235689,date2,0123456789) If date2 < date1 | (date2 = date1 & S0C71 < S0C70) then Exit 200 HTML BLQ0C105.html Date/time completed must be , greater than actual start date/time: , S0C43 S0C70. days = date(b,date2,s) - date(b,date1,s) minutes1 = hhmm2min(S0C70) /* Cvt actual start time to mins */ minutes2 = hhmm2min(S0C71) /* Cvt time completed to mins */ total_minutes = minutes2 - minutes1 /* Fix minutes to be positive if negative...borrow from days */ if total_minutes < 0 then do days = days - 1 total_minutes = total_minutes + 1440 end hours = total_minutes % 60 minutes = total_minutes // 60 /* Total duration is in the DDDD:HH:MM format */ days = RIGHT(days,4,0) hours = RIGHT(hours,2,0) minutes = RIGHT(minutes,2,0) S0C97 = days||:||hours||:||minutes S0C97.?type = D /* Set data type */ Call Update_Data S0C97 /* Set Actual Duration */End Appendix A. Business logic examples 135
    • Note: Since Web Access runs with EQUAL_SIGN_PROCESSING enabled, setting date and time fields to = lets the Information Management for z/OS HLAPI automatically set those fields to the current date and time when the record is filed. This code runs after all previous processing that occurs when a user files a record has successfully run. If the assignee changed, set the date and time assigned to = to let Information Management for z/OS reset the date and time assigned to the current date and time when the record is filed. /* all other file time checks have been done. Now check if the */ /* assignee changed. If it did, reset the date/time assigned. */ if Changed(S50C5) then /* If the assignee id was changed */ do /* reset the date/time assigned */ S0C37.?type = D /* Let api set the date and time */ S0C37 = = /* assigned, to the current */ Call Update_Data S0C37 /* date and time */ S0C64.?type = D S0C64 = = Call Update_Data S0C64 end End /*********************************************************************/ /* END sample code. */ /*********************************************************************/ /*********************************************************************/ /* Externalize pool updates before returning to the caller. */ /*********************************************************************/ Call Save_Pool_Data /* Update REXX pool */ EndREXX: /* Module exit */ Exit 200 error_item error_text /* Return completion code */ Note: hhmm2min is a subroutine that converts a time in hh:mm format to a total number of minutes. It is used by the code that calculates durations. hhmm2min: procedure arg hh : mm return hh * 60 + mm136 IBM Tivoli Web Access for Information Management
    • BLQUXFIL BLQUXFIL runs after a new or updated record is filed. The main business logic code is placed after the block comment that instructs you to Put business logic code here. The text in blue is code from the template BLQUEXIT, which was copied and renamed to BLQUXFIL. The other text is the code that was added for the business logic. Example: A-3 BLQUXFIL /*********************************************************************/ /* Put business logic code here. Use Update_Data subroutine to */ /* write an updated or new variable and value to the read/write */ /* pool. */ /*********************************************************************/ Note: The following code notifies change approvers when there is a change ready for their review. A change is ready for approval when its status is set to LOCKED. The code also checks whether a change must be reapproved. A change must be reapproved if its due date is modified. If so, the approval statuses are reset to PENDING, and change approvers are notified that they must reapprove the change. This code uses the notification method identified by the email_tsx parameter in the BLQPARMS file. As shipped, the email_tsx parameter is set for immediate notification.a Two message model records are shipped with Web Access for change approval notification, BLQMAPPR and BLQMRSET. This code uses the Web Access REXX global variables ?MODE to determine if the user is updating a record, and ?RECORD_TYPE to determine if the user is working with a change record. It uses the Changed subroutine provided with the BLQUEXIT template to test whether the status (S0BEE) was changed and, if not, whether the due date changed (S0C49). If the due date changed, the HLAPI/REXX USERTSP transaction is invoked to reset the approval statuses to PENDING, using the Information Management for z/OS TSX BLGTRPND. Change approvers are notified by invoking the HLAPI/REXX USERTSP transaction using the notification TSX specified by email_tsx and passing parameters msg_tsx set to BLQTCHGA, and the msg_rec set to the message model record. The message is either that the change is ready for approval (BLQMAPPR), or that the change must be reapproved (BLQMRSET). a. Immediate and queued notification methods are described in Tivoli Information Management for z/OS Program Administration Guide and Reference, Version 7.1, SC31-8753. /*********************************************************************/ /* Normally you do not want the business logic to run for the Admin */ /* Role. This allows the Administrator to control all the data. */ /* You can remove/relocate this line if you want all or part of the */ /* business logic to run in the Admin role. @01A*/ If translate(?ROLE) = ADMINISTRATOR then exit 200 /*@01A*/ /* If updating a change record and status is now LOCKED, notify the */ /* approvers. Otherwise, check if the due date changed. If it did, */ /* reset the approval status to PENDING and notify approvers */ if ?MODE=UPDATE & ?RECORD_TYPE=CHANGE then do msg_rec= /* clear notification msg id */ rnid_symbol=S0CCF /* Get the record id */ trans=USERTSP /* Set the API transaction */ if Changed(S0BEE) then /* If status changed */ do upper S0BEE /* Uppercase the status */ if S0BEE=LOCKED then /* If status is now LOCKED, */ msg_rec=BLQMAPPR /* Set notification message rnid */ Appendix A. Business logic examples 137
    • end if msg_rec= then /* If status wasnt set to Locked*/ if Changed(S0C49) then /* If due date changed */ do msg_rec=BLQMRSET /* Set notification message rnid */ input.= /* Clear input stem variable */ tsp_name=BLGTRPND /* Set the TSX name */ input.1.?name=tsp_name /* Put tsx name in input variable*/ input.2.?name=rnid_symbol /* Put rnid in input variable */ input.0=2 parms=trans,,INPUT address LINK BLGYRXM parms /* call the API */ cc = rc /* Save the return code */ if cc = 0 then /* Bad return code? */ signal API_Bombed end if msg_rec = then /* If notification message, */ do /* notify the approvers */ /* Notify approvers that they need to approve or re-approve */ /* the change (depending on the msg_rec). */ /* Processing uses immediate notification. To queue the */ /* message, set up queueing (see PAGR) and use tsx BLGTXQUE */ input.= /* Clear input stem variable */ tsp_name=CFG_Email_TSX /* Set the tsx name @002C*/ msg_tsx=BLQTCHGA /* Set e-mail tsx */ input.1.?name=tsp_name /* Put tsx name in input variable*/ input.2.?name=rnid_symbol /* Put rnid in input variable */ input.3.?name=msg_rec /* Put e-mail message in i/p var */ input.4.?name=msg_tsx /* Put e-mail message tsx in i/p */ input.0=4 parms=trans,,INPUT address LINK BLGYRXM parms /* call the API */ if blg_rc = 12 & , /* ignore no Approvers and no */ (blg_reas = 901 | blg_reas = 902) then /* e-mail addresses */ rc = 0 cc = rc /* Save the return code */ if cc = 0 then /* Bad return code? */ signal API_Bombed end end138 IBM Tivoli Web Access for Information Management
    • Note: The following code notifies an assignee when a problem, change, or activity is assigned to that user. It uses the Web Access REXX global variable ?MODE to determine if the user is creating or updating a record, and ?RECORD_TYPE to determine the kind of record with which the user is working. It uses the Changed subroutine provided with the BLQUEXIT template to test whether the assignee (S50C5) was changed. This code uses the notification method identified by the email_tsx parameter in the BLQPARMS file. As shipped, the email_tsx parameter is set for immediate notification.a Web Access provides a message model record for problem notification (BLQMPNOT), change notification (BLQMCNOT), and activity notification (BLQMANOT). The assignee is notified by invoking the HLAPI/REXX USERTSP transaction using the notification TSX specified by email_tsx and passing parameters msg_tsx set to BLQTNCNM, and msg_rec set to the message model record. a. Immediate and queued notification methods are described in the Tivoli Information Management for z/OS Program Administration Guide and Reference, Version 7.1, SC31-8753./* If problem, change, or activity is assigned, notify assignee. *//* Processing uses immediate notification. To queue the message, *//* set up queueing (see PAGR) and use tsx BLGTXQUE *//* if create or update and problem, change or activity and *//* assignee changed */if (?MODE=UPDATE | ?MODE=CREATE) & , (?RECORD_TYPE=PROBLEM | ?RECORD_TYPE=CHANGE | , ?RECORD_TYPE=ACTIVITY) & Changed(S50C5) then do input.= /* Clear input stem variable */ trans=USERTSP /* Set the API transaction */ tsp_name=CFG_Email_TSX /* Set the tsx name @002C*/ rnid_symbol=S0CCF /* Get and set the rnid */ /* Set e-mail message record ID based on record type */ Select when ?RECORD_TYPE=PROBLEM then msg_rec=BLQMPNOT /* problem */ when ?RECORD_TYPE=CHANGE then msg_rec=BLQMCNOT /* change */ otherwise msg_rec=BLQMANOT /* activity*/ end msg_tsx=BLQTNCNM /* Set e-mail tsx (builds e-mail)*/ input.1.?name=tsp_name /* Put tsx name in input variable*/ input.2.?name=rnid_symbol /* Put rnid in input variable */ input.3.?name=msg_rec /* Put e-mail message in i/p var */ input.4.?name=msg_tsx /* Put e-mail message tsx in i/p */ input.0=4 parms=trans,,INPUT address LINK BLGYRXM parms /* Call the API */ if blg_rc = 12 & , /* ignore no People record and */ (blg_reas = 902 | blg_reas = 903) then /* no e-mail address */ rc = 0 cc = rc /* Save the return code */ if cc = 0 then /* Bad return code? */ signal API_Bombed end Appendix A. Business logic examples 139
    • Note: The following code sends e-mail to a user who reports an incident or makes a request. It is confirmation that the user’s incident or request has been reported. This code uses the Web Access REXX global variable ?MODE to determine if the user is creating a record, and ?RECORD_TYPE to determine if the user is working with an incident or request. It also uses the notification method identified by the email_tsx parameter in the BLQPARMS file. As shipped, the email_tsx parameter is set for immediate notification.a Web Access provides a message model record for incident notification (BLQMINOT) and request notification (BLQMRNOT). The confirmation e-mail is sent to the user by invoking the HLAPI/REXX USERTSP transaction using the notification TSX specified by email_tsx and passing parameters msg_tsx set to BLQTNREP, and msg_rec set to the message model record. a. Immediate and queued notification methods are described in the Information Management for z/OS Pro- gram Administration Guide and Reference, Version 7.1, SC31-8753. /* If creating incident or request, return message to reporter */ /* Processing uses immediate notification. To queue the message, */ /* set up queueing (see PAGR) and use tsx BLGTXQUE */ if ?MODE=CREATE & , (?RECORD_TYPE=INCIDENT | ?RECORD_TYPE=REQUEST) then do input.= /* Clear input stem variable */ trans=USERTSP /* Set the API transaction */ tsp_name=CFG_Email_TSX /* Set the tsx name @002C*/ rnid_symbol=S0CCF /* Get and set the rnid */ /* Set e-mail message record ID based on record type */ Select when ?RECORD_TYPE=INCIDENT then msg_rec=BLQMINOT /* incident*/ otherwise msg_rec=BLQMRNOT /* request */ end msg_tsx=BLQTNREP /* Set e-mail tsx (builds e-mail)*/ input.1.?name=tsp_name /* Put tsx name in input variable*/ input.2.?name=rnid_symbol /* Put rnid in input variable */ input.3.?name=msg_rec /* Put e-mail message in i/p var */ input.4.?name=msg_tsx /* Put e-mail message tsx in i/p */ input.0=4 parms=trans,,INPUT address LINK BLGYRXM parms /* Call the API */ if blg_rc = 12 & blg_reas = 901 then /* ignore no e-mail address */ rc = 0 cc = rc /* Save the return code */ if cc = 0 then /* Bad return code? */ signal API_Bombed end140 IBM Tivoli Web Access for Information Management
    • Note: The following code automatically creates a solution from a problem that has just been closed. If the record just filed was a problem, if its status is newly CLOSED, if it contains description text and resolution text, if it is not a duplicate of another problem, and if there is not already a solution for this problem, it creates a solution from the problem and adds the solutions record ID to the problem. This code uses the Web Access REXX global variable ?RECORD_TYPE to determine if the user is working with a problem. It uses the Changed subroutine provided with the BLQUEXIT template to test whether the status (S0BEE) was changed. It checks that the status is CLOSED, that the completion code (S0C0E) is not DUPLICATE, and that there is description text (S0E01) and resolution text (S0E03). If these checks are met, it then invokes the HLAPI/REXX SEARCH transaction to verify that there is not already a solution for the problem. Rather than hardcoding a PIDT or data view name on the SEARCH transaction, this code retrieves the information from the Web Access REXX global variable pool. This information was specified in your BLQPARMS file and was loaded into the pool at startup. You can get the type of table (whether it is a PIDT or data view) and the name of the table from the pool. If a solution does not already exist, one is created using the HLAPI/REXX CREATE transaction. Here also, the type of table and its name is dynamically retrieved from the pool. When the solution is created, data is automatically copied from the problem to the solution using the BLG01439 program exit included with the BLQ&RNPD data attribute. Audit data (date entered, date last modified, and so forth) is set in this code. The CREATE transaction runs with control PDB EQUAL_SIGN_PROCESSING enabled. This tells the Information Management for z/OS HLAPI to automatically set the data for fields that contain an = to the values that correspond to =. For example, setting the date entered field to an = causes the Information Management for z/OS HLAPI to set its value to the current date. When the solution record is created, its record ID is then added to the problem using a HLAPI/REXX UPDATE transaction.upper S0BEEupper S0C0E/* if a problem record is being filed, its status is newly closed, *//* it is not a duplicate and there is description freeform text and *//* resolution freeform text, create a solution record. */if ?record_type=PROBLEM & changed(S0BEE) & , S0BEE = CLOSED & symbol(S0C0E)=VAR & , S0C0E =DUPLICATE & S0E01.0=S0E01.0 & , S0E03.0=S0E03.0 then if S0E01.0>0 & S0E03.0>0 then do probrnid = S0CCF /* save problem rnid */ /***************************************************************/ /* search solution records for RNPD/problemrnid to verify */ /* there isnt already a solution for this problem */ /***************************************************************/ control.= /* Clear stem variables */ input.= output.= trans = SEARCH /* get the type of table (pidt or dataview) and the name from */ /* the configuration information. */ solution_view = CFG.Solution solution_viewtype = CFG.solution_view.trans.?viewtype call value solution_viewtype, CFG.solution_view.trans Appendix A. Business logic examples 141
    • number_of_hits=1 /* 1 hit is 1 too many */ control.1 = solution_viewtype control.2 = number_of_hits control.0=2 S0CE6=probrnid /* Search for RNPD/problemrnid */ input.1.?name=S0CE6 /* Put rnpd problem id on chain */ input.0=1 parms = trans,CONTROL,INPUT,OUTPUT address LINK BLGYRXM parms /* call the API */ cc = rc /* Save the return code */ if cc = 0 then /* Bad return code? */ signal API_Bombed else if output.?total=0 then /* Dont already have a solution */ do /* for the problem, so create one*/ /*********************************************************/ /* Create a solution record. */ /*********************************************************/ control.= /* Clear stem variables */ input.= output.= trans = CREATE /* get the type of table (pidt or dataview) and the name */ /* from the configuration information. */ solution_view = CFG.Solution solution_viewtype = CFG.solution_view.trans.?viewtype call value solution_viewtype, CFG.solution_view.trans SEPARATOR_CHARACTER = ?separator_character EQUAL_SIGN_PROCESSING = YES control.1 = solution_viewtype control.2 = SEPARATOR_CHARACTER control.3 = EQUAL_SIGN_PROCESSING control.0=3 S5103 = WEB /* Set Web record */ S0C34 = = /* Set Date entered */ S0C61 = = /* Set Time entered */ S0C35 = = /* Set Date modified */ S0C62 = = /* Set Time modified */ S0BB1 = = /* Set Class entered */ S0B5E = ?user_profile_id /* Set User modified */ /*********************************************************/ /* put data on the input chain. We only need to supply */ /* S0CE6 because the 1439 program exit copies the rest */ /* of the data from the problem into the new solution */ /*********************************************************/ input.1.?name=S0CE6 /* Put rnpd problem id on chain */ input.2.?name=S5103 /* Put Web location on chain */ input.3.?name=S0C34 /* Put Date entered on chain */ input.4.?name=S0C61 /* Put Time entered on chain */ input.5.?name=S0C35 /* Put Date modified on chain */ input.6.?name=S0C62 /* Put Time modified on chain */ input.7.?name=S0B5E /* Put User modified on chain */ input.8.?name=S0BB1 /* Put Class created on chain */142 IBM Tivoli Web Access for Information Management
    • input.0=8 parms = trans,CONTROL,INPUT,OUTPUT address LINK BLGYRXM parms /* call the API */ cc = rc /* Save the return code */ if cc = 0 then /* Bad return code? */ cc = 0 /* Ignore errors */ else do /* Solution filed successfully so add the solution */ /* rnid to the problem record */ kw_rnid = RNID_SYMBOL new_rnid = output.kw_rnid /* save the solution rnid */ control.= input.= output.= trans = UPDATE probview = CFG.Problem prob_viewtype = CFG.probview.trans.?viewtype call value prob_viewtype, CFG.probview.trans control.1 = RNID_SYMBOL control.2 = prob_viewtype control.0 = 2 rnid_symbol = probrnid S0CE6 = new_rnid /* Set the solution rnid */ input.1.?name = S0CE6 input.0 = 1 parms = trans,CONTROL,INPUT,OUTPUT address LINK BLGYRXM parms /* call the API */ if cc = 0 then /* Ok return code? */ Exit 200 HTML BLQHSOLC.html End end end/*********************************************************************//* Externalize pool updates before returning to the caller. *//*********************************************************************/Call Save_Pool_Data /* Update REXX pool */EndREXX: /* Module exit */Exit 200 error_item error_text /* Return completion code */ Appendix A. Business logic examples 143
    • Using dates, date formats, and time zones in business logic When writing business logic for Web Access, you are very likely to have to work with dates and do date math. Fortunately, REXX has a powerful Date() function. However, this function only supports a few of the more than 20 date formats from which Web Access users have to choose. For example, suppose a Web Access Web user chooses “mm/dd/yy” as the preferred date format, and then must add seven days to that date in order to calculate the change due date (S0C49). Since “mm/dd/yy” is one of the date formats supported by REXX, this is a simple calculation, as shown in Example A-4. Example: A-4 Calculating change due date using REXX today = Date(B) /* today in Base date form */ next_week = today + 7 /* add 7 days to today */ S0C49 = Date(U,next_week,B) /* Change due date */ /* back to mm/dd/yy */ If the last line in Example A-4 seems confusing, read the TSO/E REXX reference for your release of z/OS. Basically, the REXX Date() function has three parameters: The desired format of your output A value for input date 42 The format of your input date So, Date(U,next_week,B) would return next_week in U.S. format (mm/dd/yy). 43 But what if the user chose “mm-dd-yyyy” for the preferred date format and then provided the starting date? The REXX Date() function does not support this format. Of course, it is possible to use the REXX parse instruction to reformat the date into the necessary format required to do the date math and then to parse and reformat it back into the user’s preferred format. This approach might be acceptable if there were only one or two date formats available; but with more than 20, using the parse method is impractical. Fortunately, Web Access has infrastructure that enables business logic to manipulate dates in any format. In order to do this, it passes ?DATE_FORMAT and ?TIME_ZONE for the current user as parameters to all business logic routines. When used in conjunction with TSXs BLQTXDAT and BLQTXCVT, the REXX Date() and Translate() functions allow you to work with dates and times in any format the user may have chosen as the preferred date format.Obtaining the current date and time in the user’s format and time zone TSX BLQTXDAT takes the users date format and time zone preferences and returns current date and time in his or her preferred external format. Here, BLQTXDAT is invoked by REXX routine BLQWRGET using an HLAPI/REXX USERTSP transaction. The date and time values returned by BLQTXDAT are placed into the HTML before it is sent to the browser. Therefore, when the user enters an equal sign to denote current date or time, these values are used, rather than the default Date() and Time(), in order to reflect the format preferred by the user. Example A-5 on page 145 demonstrates how this might be accomplished. 42 The function defaults to current date if you do not provide a value in this parameter. 43 By default, next_week is a date in Base date format (an integer starting January 1 in the year 1).144 IBM Tivoli Web Access for Information Management
    • Example: A-5 Using BLGTXDAT to return current data and time in user’s preferred format trans = USERTSP tsp_name = BLQTXDAT /* Run TSX to get date and time */ time_zone = ?time_zone date_format = ?date_format control.1 = time_zone control.2 = date_format control.0 = 2 input. = /* Clear input stem */ input.1.?name = tsp_name input.0 = 1 /* Set number of inputs */ output. = output.0 = 0 parms = trans,CONTROL,INPUT,OUTPUT address LINK BLGYRXM parms today = output.uextdate /* Date in users external */ /* format AND time zone. */ now = output.uexttime /* Time in users external */ /* format AND time zone. */ Note: If you are not using UT, time zone is ignored. However, you should still use time_zone in your business logic so that you will not have to recode anything if you should eventually implement UT. In Example A-4 on page 144, todays date (in Base form) was obtained using Date(B). That date was based on the local date and time of the processor rather than the local time for the user (which could be in a different time zone). In Example A-5, on the other hand, time_zone and date_format are used on the control stem so that the correct local date and time are returned.44Converting a date in the user’s preferred format to internal format After executing the code shown in Example A-6 on page 146, the variable today would have the local date (that is, todays date adjusted for the users current time zone) in the users preferred external date format.45 If we want to add seven days to that date as we did in Example A-5, we must convert today into Base date format. Since we want to avoid having more than 20 parse statements in our REXX code, we use BLQTXCVT to convert the date contained in the variable today into internal format (YYYY/MM/DD). Then, we can then use the REXX Translate function to convert to the Standard form (YYYYMMDD) supported by the REXX Date() function (see Example A-6 on page 146). 44 Since in this example we are only interested in the date, we do not use the time value that was returned by BLQTXDAT. 45 We are assuming “mm/dd/yyyy” in this example. Appendix A. Business logic examples 145
    • Example: A-6 Using BLGTXCVT to convert user’s external format date to database 5 internal format tsp_name = BLQTXCVT /* Date converter TSX */ CDATE.1 = today /* Date in external format */ CDATE.0 = 1 /* Values to be converted */ CONVERT = EXTTOINT /* Convert external to internal */ input.1.?name = tsp_name /* TSX to run */ input.2.?name = CDATE. /* Stem with the dates. */ input.3.?name = CONVERT /* What to do. */ input.0 = 3 output. = output.0 = 0 parms = trans,CONTROL,INPUT,OUTPUT address LINK BLGYRXM parms today_int = output.uintdate.1 /* Remove slashes in internal date to create Standard date*/ today_std = Translate(01235689,today_int,0123456789) today = Date(B,today_std,S) /* Standard to Base */ next_week = today + 7 /* add 7 days */ next_week = Date(S,next_week,B) /* Base to Standard */ /* Add slashes to standard date to get internal date */ next_week_int = Translate(0123/45/67,next_week,01234567)Converting an internal date to a user-preferred external date format In Example A-6, after BLQTXCVT changed the date in the user’s external date format into the internal format, it was translated to Standard format, which was then used by the Date() function to get the Base format, so we could add seven days and set the variable next_week. This same variable was then converted from Base to Standard form and then translated from Standard format to internal format. Once the date is in internal format, BLQTXCVT can be used to convert the internal form back to the user’s external date format (see Example A-7). Example: A-7 Using BLGTXCVT to convert database 5 internal format date to a user’s external format tsp_name = BLQTXCVT /* Date converter TSX */ CDATE.1 = next_week_int /* Date in external format */ CDATE.0 = 1 /* Values to be converted */ CONVERT = INTTOEXT /* Convert internal to external */ input.1.?name = tsp_name /* TSX to run */ input.2.?name = CDATE. /* Stem with the dates. */ input.3.?name = CONVERT /* What to do. */ input.0 = 3 output. = output.0 = 0 parms = trans,CONTROL,INPUT,OUTPUT address LINK BLGYRXM parms next_week = output.uextdate.1 S0C47 = next_week146 IBM Tivoli Web Access for Information Management
    • Rules to remember when handling dates in business logic Consider the following rules when handling dates in business logic: Make sure you know the date type definitions: External format—Any of the more than 20 formats from which a Web Access user can choose. The external format is what is seen on any HTML page or 3270 screen. It is the format that the user employs when the user enters dates. Web Access allows each user to choose an external date format preference. If UT is in effect, all external format date and time pairs defined in the TIMEZONE reference record are adjusted using the users time zone preference.46 Internal format—There is only one internal date format, and it is “YYYY/MM/DD.” TSX BLQTXCVT can be used to convert any of the more than 20 external formats to and from the internal format. Web users do not know of or use the internal format. The internal format is important to business logic because it can be easily translated to the REXX “Standard” date format. Standard format—Dates in “YYYYMMDD” format (that are used by the REXX Date() function). Standard format dates can easily be translated to internal format. Base format—Dates in integer format, defined by the REXX Date() function as the number of days that have passed since January 1 of the year 1. Since Base format dates are integers, they can easily be added and subtracted. All dates used by Web Access in CREATE, UPDATE, and RETRIEVE HLAPI/REXX transactions are in external format. Use BLQTXDAT to obtain the current date and time. Avoid using the REXX Date() and Time() functions to obtain the current date and time, since those functions do not support user date and time zone preferences. For calculations, convert all external dates to internal dates using BLQTXCVT. This TSX can convert more than one date at a time.47 Use the REXX code to translate internal dates to Standard format dates and then to Base date and back. See the sample code included in Example A-8. Example: A-8 Translating internal dates to Standard to Base and back /* REXX */ date_int = 2002/05/13 /* Remove slashes to create Standard date*/ date_std = Translate(01235689,date_int,0123456789) date_base = Date(B,date_std,S) /* Standard to Base */ /* Then to go from Base to Standard to internal. */ date_std = Date(S,date_base,B) /* Add slashes to standard date to get internal date */ date_int = Translate(0123/45/67,date_std,01234567) Even if you are not using UT, build your code as though you were. Use time_zone and date_format on any HLAPI/REXX transaction that could have dates. This way, you do not have to recode your business logic in the event that UT is eventually implemented. 46 See the validation data in Data Attribute record BLQ&DFMT for the complete list used by Web Access. See BLG&DFMT for the list used by 3270 users. 47 See “Calculating a duration: An example using BLQUXVAL” on page 148 for instructions about handling multiple dates. Appendix A. Business logic examples 147
    • Avoid pursuing a JavaScript solution. Using the JavaScript Date() function has the same limitation of not supporting the more than 20 Web Access external date and time formats.Calculating a duration: An example using BLQUXVAL One of the most frequent types of business logic requests is date calculation. Web Access provides sample date calculations and code that can be used by Web application developers to develop additional calculations. Business logic exit module BLQUXVAL contains a routine that calculates the total duration when a problem record is closed using the date and time occurred and completed. In order to calculate duration, you must know the s-words associated with the date and time fields involved. In this case, S0C3D contains date occurred, and S0C40 holds date completed. The dates in these s-word variables are in the users external date format. In order to perform calculations on them, you have to convert them to internal date format. TSX BLQTXCVT is provided to perform such calculations. BLQUXVAL calls BLQTXCVT using a HLAPI/REXX USERTSP transaction. Example: A-9 Using BLGUXVAL to calculate a duration tsp_name = BLQTXCVT /* Date converter TSX */ CDATE.1 = S0C3D /* Date occurred */ CDATE.2 = S0C40 /* Date completed */ CDATE.0 = 2 /* Values to be converted */ CONVERT = EXTTOINT /* Convert external to internal */ input.1.?name = tsp_name /* Put tsx name in input variable*/ input.2.?name = CDATE. input.3.?name = CONVERT input.0 = 3 The CDATE compound variable can contain as many dates as need to be converted. The CONVERT variable might contain EXTTOINT (external to internal) or INTOEXT (internal to external), depending on which type of conversion must be performed. BLQTXCVT returns the results in one of several output variables. Requested external dates go into OUTPUT.UEXTDATE.n, and requested internal dates go into OUTPUT.UINTDATE.n. Here, OUTPUT is assumed to be the name of your output stem. In our example, you can access the output as: date1 = output.uintdate.1 date2 = output.uintdate.2 In order to perform calculations on dates in REXX, you must put them into a special format (which is basically the Information Management for z/OS internal format with the slashes removed). /* Get rid of slashes in internal date */ date1 = Translate(01235689,date1,0123456789) date2 = Translate(01235689,date2,0123456789) Since you are working with two date and time pairs, you should ensure that the second pair really occurred after the first pair: If date2 < date1 | (date2 = date1 & S0C71 < S0C6A) then Exit 200 HTML BLQ0P104.html Date/time completed must be , greater than date/time occurred: S0C3D S0C6A.148 IBM Tivoli Web Access for Information Management
    • Although it is permissible to do a string comparison using the internal date format with the slashes removed as in this comparison, you must use the REXX Date() function with Base dates in order to do any real mathematical processing: days = date(b,date2,s) - date(b,date1,s) The time values must also be converted for processing to minutes: minutes1 = hhmm2min(S0C6A) /* Convert time occurred to mins */ minutes2 = hhmm2min(S0C71) /* Convert time completed to mins */ total_minutes = minutes2 - minutes1 It is possible for time 2 to be less than time 1 even though the date and time pair 2 actually occurred after the date and time pair 1. In that case, total_minutes will be negative and a day must be borrowed to make it positive: /* Fix minutes to be positive if negative. */ if total_minutes < 0 then do days = days - 1 total_minutes = total_minutes + 1440 end Before storing the calculated duration back into the Web Access record, the duration needs to be reformatted: hours = total_minutes % 60 minutes = total_minutes // 60 /* Total duration is in the DDDD:HH:MM format */ days = RIGHT(days,4,0) hours = RIGHT(hours,2,0) minutes = RIGHT(minutes,2,0) S50B9 = days||:||hours||:||minutes S50B9.?type = D /* Set data type */ Call Update_Data S50B9 /* Set Total Duration */ BLQUXVAL contains a similar routine to calculate the actual duration when the date completed or time completed, or both, in a change or activity record changes. The actual start date is used as the date and time pair 1. Processing similar to this can be added for other date fields in Web Access, or this technique can be employed in user Web applications.Notification The business logic for the Web Access drop-in problem and change management solution uses the Information Management for z/OS notification feature to send e-mail messages when certain conditions are met. The code uses the notification method identified by the email_tsx parameter in the BLQPARMS file. As shipped, the email_tsx parameter is set for immediate notification, but it can be modified to use queued notification. Both notification methods are described in the Tivoli Information Management for z/OS Program Administration Guide and Reference, Version 7.1, SC31-8753 (BLGS1E10), and the email_tsx parameter is described in “Business logic exit routine directives” on page 169. Web Access supplies a set of message model records and TSXs that, coupled with the Information Management for z/OS notification TSXs, build and route the notification messages used by the drop-in problem and change management solutions business logic. Appendix A. Business logic examples 149
    • Table 12-1 Web Access TSXs and message model records Process Message model records Message TSX BLQMAPPR Change approval Change approval BLQTCHGA BLQMRSET Change reapproval BLQMANOT Activity assigned Record assigned BLQMCNOT Change assigned BLQTNCNM BLQNPNOT Problem assigned BLQMINOT Incident opened Record opened BLQTNREP BLQMRNOT Request opened E-mail recipients are defined by the e-mail address in their user profile, which is a people record in the Information Management for z/OS database. If a notification message is intended for you, but you do not have an e-mail address in your profile, the e-mail will not be sent. The message TSXs determine to whom the e-mail is to be routed. Web Access does not currently send e-mail to carbon copy (cc:) or blind carbon copy (bcc:), but it can be modified to do this. Following is a brief description of the message TSXs used by Web Access: BLQTCHGA—Change approval Messages are sent to the eligible users in approver privilege classes whose approval status is Pending. BLQTNCNM—Record assigned A message is sent to the assignee identified by s-word index 50C5. BLQTNREP—Record opened A message is sent to the person reporting an incident or submitting a request as identified by the e-mail address in the incident or request. The message templates follow. The message variables are substituted with actual data when the message is built. Example: A-10 BLQMAPPR: Change approval Record !S0CCF is ready for you to approve. Click on the link below to approve or reject this record. http://yourhostname:yourport/IMWA/BLQWRGET.REXX?html_view=BLQ0C209.html&rnid_symbol=!S0CCF Example: A-11 BLQMRSET: Change reapproval The due date for change record !S0CCF was modified so the approvals have been reset. The new due date is !S0C49. Click on the link below to approve or reject this record. http://yourhostname:yourport/IMWA/BLQWRGET.REXX?html_view=BLQ0C209.html&rnid_symbol=!S0CCF150 IBM Tivoli Web Access for Information Management
    • Example: A-12 BLQMANOT: Activity assignedChange activity record !S0CCF has been assigned to you.The activity name is: !S0CBC.This activity was requested by !S0B59 (e-mail: !S01D1,phone number: !S0B2D) for change record !S0CD0.The current status is !S0BEE. The activity is requiredby !P00D5 !P0288.Description: !S0E0FActivity Description Text:!T0E01Example: A-13 BLQMCNOT: Change assignedChange record !S0CCF has been assigned to you. This changewas requested by !S0B59 (e-mail: !S01D1,phone number: !S0B2D). The current status is !S0BEE.The change is required by !P00D5 !P0288.Description: !S0E0FChange Description Text:!T0E01Example: A-14 BLQMPNOT: Problem assignedProblem record !S0CCF has been assigned to you to fix. This problemwas reported by !S0B59 (e-mail: !S01D1,phone number: !S0B2D) on !P00E3 at !P0293.The current status is !S0BEE, the severity is !S7D42 and thepriority is !S0BE7.A fix is required by !P00D5 !P0288.Description: !S0E0FProblem Description Text:!T0E01Example: A-15 BLQMINOT: Incident openedIncident record !S0CCF was created for youon !S0C34 at !S0C61.Description: !S0E0FDescription text:!T0E01Example: A-16 BLQMRNOT: Request openedRequest record !S0CCF was created for youon !S0C34 at !S0C61.Description: !S0E0FDescription text:!T0E01 Appendix A. Business logic examples 151
    • 152 IBM Tivoli Web Access for Information Management
    • B Appendix B. Hints and tips This appendix documents some of the more common tasks or questions that you may find useful as you implement Web Access.© Copyright IBM Corp. 2003 153
    • Your changes to Web Access do not seem to take effect As you make changes to the data views, data attributes, privilege class, and other items used by Web Access, it may seem like your changes are not taking effect. That could be happening because both Web Access and your browser cache data. You should review Chapter 12, “Web administration” on page 115 (specifically 12.2, “Procedures” on page 119) for common administrative tasks that if not performed can prevent changes you make from taking effect. Here are some other considerations: Did you create static PIDTs of your data views using BLGUT18? If yes, and you add or remove data attributes, be sure to run BLGUT18 again. If changes to the .js files or style file do not seem to take effect, hold your Shift key and click your browser’s Reload or Refresh button. On some browsers, you may have to hold Ctrl and click Reload or Refresh. In some cases, browsers will not reload source type files. The Shift or Ctrl keys tell the browser to reload all parts of the page. Delete your browser’s cache or temporary HTML files and retry. Stopping and restarting the Web server may be required in some cases.Listing groups and layouts in data views using BLGDVLAY You can generate a list of the groups, fields, and tables associated with a data view record by running a TSX named BLGDVLAY interactively in Information Management for z/OS. To run this TSX, enter the following at a Information Management for z/OS command line. Note that in this command line that the brackets are not part of the syntax, but are used to indicate optional parameters. RUN BLGDVLAY rnid [FILE [dsname]] Where rnid is the name of the data view record, FILE indicates that the report should be written to a pre-allocated data set,48 and dsname is the name of a pre-allocated data set to which the output should be written.49 If you choose to write the output to a data set, whether to a data set that you specify or to the default data set hlq.BLGDVLAY, you must pre-allocate the data set before running TSX BLGDVLAY. The DCB parameters for the output data set are as follows: Data set organization= Sequential Device type= DASD Record format= Fixed block or variable block Record length= 80 or greater The following example illustrates how to run BLGDVLAY to print the panel layouts, groups, tables, and fields for the data view record BLQVPROB to the screen: RUN BLGDVLAY BLQVPROB 48 If dsname is specified, the output is written to the named data set. If dsname is not specified, the output is written to a data set named hlq.BLGDVLAY, where hlq is your high-level qualifier. FILE is an optional parameter. If FILE is not specified, the output is written to the screen. 49 If you specify dsname, specify the fully qualified data set name without quotation marks. Dsname is an optional parameter. If you specify FILE and do not specify dsname, the output is written to a data set named hlq.BLGDVLAY, where hlq is your high-level qualifier. If FILE is not specified, dsname is ignored.154 IBM Tivoli Web Access for Information Management
    • The next example writes the output to the default data set hlq.BLGDVLAY. First pre-allocate hlq.BLGDVLAY with fixed block record format and record length 80, and then specify: RUN BLGDVLAY BLQVPROB FILE The last example shows how to run BLGDVLAY to print the panel layouts, groups, tables, and fields for the data view record BLQVPROB to a data set named CHIRON.BLQVPROB. This is a pre-allocated sequential data set with fixed block record format and record length 80: RUN BLGDVLAY BLQVPROB FILE CHIRON.BLQVPROB For more information about BLGDVLAY, see Appendix A, pages 177-198, of the Tivoli Information Management for z/OS Desktop User’s Guide, Version 7.1, SC31-8740 (BLGJ1E10). For a comprehensive discussion of data model records, see Chapter 29, pages 539-618, of the Tivoli Information Management for z/OS Panel Modification Facility Guide, Version 7.1, SC31-8750 (BLGP6E10).Changing Web page titles Many of the HTML pages shipped with this product contain the title “Web Access.” This title can be changed to reflect whatever you would like it to say (for example, the name of your company). To make a change to the title of any HTML page, access the UNIX System Services (USS) utility for searching on string data and enter the substring to be searched (in this case, “Web Access”) and the UNIX directory where the pages are stored. The resulting list should show all the members in the HTML directory that have the given substring in them. You should only have to change the HTML pages that do not begin with “BLQ0”. You then need to edit each HTML document in order to make the change to the title. The title string is located between the <title> and </title> HTML tags in the body of the document. After the desired changes have been made to the title text, you need to drop the HTML cache; you can do this by selecting the Administer Web tab from the home page, and then clicking Drop HTML Cache, which is located on the left side of the page. These changes should be noticed when the page is reloaded on the browser. Another option would be to restart the Web server after making your changes.Changing the Tivoli logo The Web pages shipped with Web Access all have a small Tivoli Software logo at the top of the page. You can replace the Tivoli Software logo by replacing logo_tiny.gif in the images directory (/usr/lpp/InfoMan/web/html/images) with your companys logo. Your logo has to be a .gif, and you must call it logo_tiny.gif. The size should be kept small; the Tivoli logo is 81 x 18 pixels, but you can use any size. The height impacts the display more so than the width. Appendix B. Hints and tips 155
    • Date formats Web Access allows users to choose the format in which they would like to see dates displayed. This date format is often referred to as the users external date format. Users can either choose from the following formats, or their administrator can create a user-defined format: MM/DD/YY DD/MM/YY YY/MM/DD DDMMMYY MM/DD/YYYY DD/MM/YYYY YYYY/MM/DD DDMMMYYYY MM-DD-YY DD-MM-YY YY-MM-DD YYDDD MM-DD-YYYY DD-MM-YYYY YYYY-MM-DD YYYYDDD MM.DD.YY DD.MM.YY YY.MM.DD MM.DD.YYYY DD.MM.YYYY YYYY.MM.DD The user specifies the preferred format in his or her Web Access profile (which is a people record in the Information Management database). To access this profile, the user selects View Profile on the home page. The external date format is located under User Preferences.156 IBM Tivoli Web Access for Information Management
    • Figure B-1 Specifying your date formatUsing Java Desktop data view and data attribute records Can I use the data view records and data attribute records that I created for the Java Desktop with Web Access? For the most part, the data attribute records created for the Java Desktop can be used as is or with little modification. The data view records, however, cannot be used directly. The reason is that the Java Desktop and Web Access have different requirements for how you go about defining tasks. For example, the Java Desktop requires a special “Display R” task in each data view record so that a given record type can be printed. The Web Access HTML generator will try to use that task as it does any other and present it in an HTML form. Web Access, on the other hand, builds a change approval table when s-words 12DE and 12DF are recognized in a group or task, or both. Appendix B. Hints and tips 157
    • The good news is that you can copy the data view records that you worked on for the Java Desktop and save them with a new RNID. That saves you the time of building the list of data attribute records in the data view record. Some of the groups and tables might also be okay, but the tasks will probably have to be deleted and rebuilt to meet the Web Access HTML generator requirements.Sharing the Web server What about sharing the Web server? Can I use the same Web server for the Java Desktop and Web Access, as well as other Web applications? In the past, it was difficult to use the OS/390 Information Management Web Connector and the Java Desktop on the same Web server. While that is still true, you should be able to run the Java Desktop and Web Access on the same Web server, or you can run your existing Information Management Web Connector for OS/390 Web application and Web Access on the same server. The difficulty in the past was that the OS/390 Information Management Web Connector and the Java Desktop used some of the same parts, names, and definitions, which prevented both from being used on the same Web server. Since the parts and definitions used by Web Access are all unique with Web Access, there is no conflict with the existing Java Desktop or Information Management Web Connector for OS/390 parts and definitions. Your Web applications are unique to your installation, but Web Access should be able to share the Web server with those Web applications. Web Access only uses documented general programming interfaces and facilities. Though it does need to use server-side includes (CGI-only) and has a somewhat unique Addtype requirements for .txt files, as long the other Web applications on the server are not impacted by those two directives, they should be able to coexist.Data views and data attributes used in the attaching process Attachments are stored in the Information Management for z/OS record as freeform text. Each attachment requires a freeform text s-word defined by a data attribute record. Each of the data attribute records for the freeform text s-words must be included in the BLQATTCH data view. You cannot change the name of this data view, but you can include as many freeform text data attributes as needed. You can also remove unneeded freeform text data attributes if desired. As shipped, there are 10 freeform text data attributes included in BLQATTCH, as shown in Table B-1. Table B-1 BLGATTCH freeform text data attributes Data attribute RNID Freeform text S-word Use BLQ&AT01 5201 Attachment 1 BLQ&AT02 5202 Attachment 2 BLQ&AT03 5203 Attachment 3 BLQ&AT04 5204 Attachment 4 BLQ&AT05 5205 Attachment 5 BLQ&AT06 5206 Attachment 6 BLQ&AT07 5207 Attachment 7 BLQ&AT08 5208 Attachment 8158 IBM Tivoli Web Access for Information Management
    • Data attribute RNID Freeform text S-word Use BLQ&AT09 5209 Attachment 9 BLQ&AT10 520A Attachment 10 There are other data attributes in the BLQATTCH data view. These additional data attributes are used to manage the attachments, are required, and cannot be removed. Table B-2 Additional data attributes Required data attribute Use BLQ&AUSR Attachment user BLQ&ADES Attachment description BLQ&ANAM Attachment name BLQ&ATTI Attachment index BLQ&DATA Attachment date BLQ&TIMA Attachment time BLQ&DATM Date modified BLQ&TIMM Time modified BLQ&USER User modified BLQ&RLOU Update sourceAdd attachments to your data views You can attach files to any record type that you can update using Web Access by following these steps: 1. Identify the data view used to update the desired record. 2. Update that data view and include all of the following data attributes. Table B-3 Attachment data views Data attribute name S-word Description BLQ&ANAM 5117 Attachment name BLQ&ADES 5116 Attachment Description BLQ&ATTI 5118 Attachment index BLQ&AUSR 5115 Attachment user BLQ&DATA 5113 Attachment date BLQ&TIMA 5114 Attachment time Appendix B. Hints and tips 159
    • 3. Using Web and Desktop tables, select only the fields that you want to see on the browser by entering ATTACH in the table name field. Normally, the attachment name and description will be enough, but you might want to include the attach date and time along with the user ID of whoever attached the file. Attachment index is used internally and never needs to be shown in the HTML. The Web Access code still accesses and updates these fields, even though they are not included in the Desktop table or visible in the HTML. 4. Using Web and Desktop panel layouts, choose a Panel Name in which you want to include the ATTACH table by entering the F line command. 5. Select the ATTACH table by entering S and position it within the other groups of fields. Change the field description for the ATTACH table if desired. Blank out or change the usage to U for inquiry. 6. Finish your Desktop Panel Field List Entry and you are taken to the Desktop Table Field Usage Definition panel. Change the field description if desired. Blank out the create usage field. Attaching files is not possible in create mode. Set the update and display usage with the desired values (U, D, or R). 7. End the panel, file the data view record, and create the HTML using the Web Administration page. Other considerations Attachments can only be viewed under Web Access. They cannot be viewed by the traditional 3270 Information Management user and should not be included in report format tables (RFTs). Web Access adds the date, time, and user ID of the user attaching a file. If you would like this information to appear in the journalized history data, you need to update data attributes BLQ&DATA, BLQ&TIMA, and BLQ&AUSR and set “cognize data” to YES and “journalize” to ORDER. These attributes are shipped with these settings turned off in order to avoid generating large volumes of history data. Do not include the data attributes for the freeform text s-words in your data view.50 Including those data attributes will impact performance, since the attachment text will be retrieved with the rest of the data in the record when your data view is used. The Web Access code will access the attachment freeform text using data view BLQATTCH when needed. The exception to this rule is to include them when you want an attachment to appear in-line in the HTML when displaying a record, as exemplified by showing a JPG or GIF image (such as a persons picture) on the summary panel of the people record display. Attachment freeform text data attribute BLQ&AT01 is included in the list of data attributes in BLQVPEOP so that the image can be shown without the user executing a Get attachment.General considerations When defining tables in a data view, consider the following: ATTACH is a reserved table name and causes Web Access to do attachment-specific processing of the list processor data. SAVESRCH is a reserved table name for saved search data. It causes Web Access to do saved search-specific processing. S-words with special meaning in display-mode task HTML: – S0EF7—The existence of this field in a task causes the Web Administration page to add the code necessary to print. 50 See Table B-1 on page 158 for the data attribute names used to store attachments in freeform text.160 IBM Tivoli Web Access for Information Management
    • – S0ED1—The existence of this field in a task causes history (journal) data to be formatted using Show_History?().– S12DE or S12DF—Causes Show_Approvers?() to be added to the HTML.– S0CBC—In a change record, causes Show_Childern?() to be added.S-words with special meaning in update/create-mode task HTML:– S1152—Causes Select_With_My_Classes?() to be added.– S0CD0—In an activity in create mode, causes the field to be changed to a hidden <input> display-only field for the parent RNID. In update or display mode, it turns into an active link to the parent. Appendix B. Hints and tips 161
    • 162 IBM Tivoli Web Access for Information Management
    • C Appendix C. Web Access configuration parameters Web Access requires parameters to operate. These parameters are contained in a configuration file. A sample configuration file named BLQPARMS should have been installed in the /usr/lpp/InfoMan/web/samples directory as part of the Web Access product installation process. You should make a copy of this file for use in your environment (for example, BLQPARMS.conf) and change the parameters to fit your installation needs. The Web server locates the configuration file using the INFOMANWEBTOOLKITCONF environment variable, which must have been added to the Web server’s httpd.envvars file. You must supply the complete file name and path using the environment variable. Be sure the access mode of your configuration file is at least 755.© Copyright IBM Corp. 2003 163
    • Updating the configuration file Web Access configuration parameters are stored in a file in the form of configuration directives. The file can also contain comment text. The syntax for the configuration file content is as follows: Lines starting with the # character are treated as comments. Blank lines are ignored. Text up to a # character is interpreted as a directive and its associated data values. Text after a # character on a directive line is ignored. Be sure that your BLQPARMS file has read access for all users, and that the path and file names are coded in your Web servers httpd.envvars file using the INFOMANWEBTOOLKITCONF environment variable. As you modify your copy of the configuration file to support your Web Access application, you may see some record_type directives for records that you may think your application does not use. Since they are required and used internally by Web Access, do not remove them. These include, but are not limited to, CLASS, LOOKUP, VALIDATION, DATAVIEW, ATTRIBUTE, and REFERENCE. The following lists describe the configuration file parameters. Unless noted, each parameter is required.Debug option directive The following is the debug option directive: debug name option Used for REXX and API tracing and debugging purposes. You can specify multiple debug directives. name—Component to be traced/debugged. You may specify ALL, API, or a REXX module name. Specify a REXX module name to debug that individual module. Specify API for API tracing. ALL specifies the default for components not explicitly named. option—The level of debugging for the specified name. Values allowed: off, on, verbose, and vverbose.Data set name directives The following are data set name directives: tsx_dsname Used to specify TSX data set names. Use multiple TSX_DSNAME directives to concatenate data sets. rft_dsname Used to specify RFT data set names. Use this directive multiple times to cause data sets to be concatenated. The first rft_dsname directive can also specify a DD name, and should be written in the following format: rft_dsname your_rft_data_set_name RFTDD The RFTDD should match the FILE= value coded on the BLGCLDSN in your session member. Any additional rft_dsname directives should only have the data set name. If you do not specify a DD name on the first rft_dsname directive, the DD name defaults to RFTDD.164 IBM Tivoli Web Access for Information Management
    • General control directives The following are general control directives: max_sessions Number of active HLAPI sessions allowed with the HTTP Server. This directive is optional. If omitted, the default is 5. web_master URI for Administration pages.User ID and privilege class directives The following are User ID and privilege class directives: admin_class A privilege class that contains the user IDs of any user that should be allowed to perform the administrator functions of Web Access, such as generating HTML, editing HTML using Web Access, and refreshing the various caches used by Web Access. This privilege class needs no authority. It is used simply to contain user IDs.51 application_id Contains a 1-to-8 character uppercase application ID that Information Management for z/OS uses to initialize each HLAPI session. You must specify a value and the ID must be an eligible user in the privilege class identified by the privilege_class parameter. privilege_class Contains a 1-to-8 character privilege class name. This class is used to initialize the HLAPI session with the HTTP Server. BLQUSER is the IBM-supplied class. You can use this class or one of your own that has the following authorities: – Display authority for privilege class, people, solution, problem, and change records – Update authority for people records If you implement the Web Access User role, this class should have create and update authority for problem and change records. Web Access will add user IDs to this class if an authenticated user accesses Web Access and is not currently in any other privilege classes. This allows the new user to do basic functions, such as create and update their own incident and request records. work_class Contains a 1-to-8 character privilege class name. BLQWORK is the IBM-supplied class. You can use one of your classes, but it must have at least the following authority: – Privilege class display – Privilege class update – Database administration – People record display – People record create – People record update 51 Note: The admin_class class is not the same as the administrator role. The admin_class is for the webmaster. The administrator role is for your Information Management for z/OS database administrator who may or may not need to be your Web Access webmaster. Appendix C. Web Access configuration parameters 165
    • This class is used to create the people record when a user ID first accesses Web Access. It is also used along with work_id to update the privilege class record identified by the privilege_class parameter when an authenticated user ID accesses Web Access and does not have any other privilege class. work_id Contains a 1-to-8 character uppercase application ID that must be in work_class. Web Access will switch to this ID when it needs to use this class to perform a transaction that a Web user ID would not have authority to do (such as updating a privilege class).Directives that control the Information Management API The following are directives that control the Information Management API: apimsg_option Contains a one-character LLAPI message option parameter (C, P, or B): – C—LLAPI chains messages and passes them from the LLAPI to the HLAPI for conversion into message PDBs. – P—LLAPI writes messages to the APIPRINT data set. – B—Performs both C and P. This directive is used only if SPOOL_INTERVAL is not set to 0. To obtain APIPRINT, you need to add an APIPRINT DD statement to your Web server PROC. The DD statement must point to SYSOUT. C is recommended for production and non-production servers to improve overall performance. bypass_panel_processing Set this to YES to specify that no panels are to be used in record processing other than those used by the delete transaction. If you specify any other value, the HLAPI performs panel processing. If you are using the drop-in problem and change management Web solution provided with Web Access, you must specify YES. If you use Web Access to implement your own unique Web application, choose the value required by your application. It is recommended that you use YES even for your unique Web applications so that they can make full use of the features supplied by Web Access. class_count Indicates the maximum number of Information Management for z/OS privilege class records that can be maintained in storage (cached) during the life of this Information Management for z/OS session. If you specify 0, the Information Management for z/OS session operates with a single privilege class record in storage at a time. It is recommended that you use a value of at least 10 or more to improve over all performance. databases Specifies a one-character ID number of the database or databases to be used for Information Management for z/OS records. You may specify multiple database IDs, delimited by a space.166 IBM Tivoli Web Access for Information Management
    • default_data_storage_sizeSpecifies how much additional storage is allocated to hold default response data from analias table when your application is creating records. When the HLAPI creates records, itcalculates the size of the response buffer it needs by totalling the lengths of all the inputdata PDBs and adding the specified default data storage size. When the HLAPI performscreate response processing, it always checks to make sure the response will not overlaystorage. If the response will overlay storage, the HLAPI transaction ends with an errorcode. The drop-in problem and change management Web solution provided with WebAccess does not use default response data. However, if your unique application usesdefault data, code this to meet your needs.hlimsg_optionContains a one-character HLAPI message option parameter (C, P, or B):– C—HLAPI chains messages on the PDB message chain.– P—HLAPI writes messages to the HLAPILOG data set.– B—Performs both C and P.This directive is used only if SPOOL_INTERVAL is not set to 0. To obtain the HLAPILOG,you need to add a HLAPILOG DD statement to your Web server PROC. The HLAPILOGcan be coded to go to SYSOUT or a data set. If a data set is used, specify DISP=MOD.B is recommended for non-production Web Access Web servers for easier debugging. Cis recommended for production servers to maximize performance.model_databaseContains a one-character ID number of the database where the data model records arestored. This directive is optional. If omitted, database 5 is the default.session_memberContains a seven- or eight-character load library session parameter member name thatInformation Management for z/OS uses for this session. Session member names cannotcontain imbedded blanks.spool_intervalSpecifies the number of minutes that the HLAPI spools the activity logs HLAPILOG andAPIPRINT when messages are printed. If the HLAPI is spooling to a data set, and this timeinterval has passed, the activity logs are recycled and new log information is writtenstarting at the top of the data set, writing over any existing information. If you specify 0, theHLAPI does not log messages, and the settings in APIMSG_OPTION andHLIMSG_OPTION are ignored. Set this value to 1440 for non-production Web AccessWeb servers. Use 0 for production servers to maximize performance.table_countIndicates the maximum number of alias tables, data views, and PIDTs that the HLAPI canmaintain in storage during the life of a Information Management for z/OS session. It isrecommended that you use a value of at least 50 for table_count.text_widthSpecifies the maximum number of characters contained on a freeform text line. In updateand create mode, lines will be wrapped to this value. Display and print lines are formattedto this length. This value defaults to 60 if you specify a value of 0 or a value greater than132. Text width can be any value between 1 and 132. The default of 60 works well with thegenerated HTML. If you expect users to update freeform text using the 3270 panels, youmay want to use 72, or possibly 80. When both the Web and 3270 users will be usingfreeform text, you will have to experiment with text width and set it to a value that allows allusers to be able to view freeform text easily. Appendix C. Web Access configuration parameters 167
    • timeout_interval Specifies the number of seconds that an LLAPI transaction can run before it is terminated (timed out). If you specify a value between 0 and 45 seconds, the HLAPI uses a value of 45 seconds. If you specify a value of 0, the HLAPI uses a default value of 300 seconds (five minutes). Sixty seconds is recommended for production Web Access Web servers. Use at least 200 on non-production servers so that large un-cached data views can be used.UNIX System Services path and file reference directives The following are UNIX System Services path and file reference directives: attachment_path Specifies where temporary attachment files are placed. It must match the path on the Pass directive for attachments in your httpd.conf file. This directory should have access mode of 777. error_log_path Path used on the ErrorLog directive in your httpd.conf file. Web Access will allow the Web administrator to view the error log using a Web browser. html_path Path to be searched for requested HTML files. Code one html_path for each directory that contains the HTML you generated using Web Access. The first html_path is written to when generating HTML using Web Access. HTML is read from the first directory that contains the HTML file. max_attachment_size Largest attachment file size (in bytes). Each attachment can be up to this size. The value 1048576 (1 MB) or less is recommended. Values more than 1 MB or many attachments will increase the time to process the record. This directive is optional. If omitted, the default is 1048576.Server side include (SSI) directives For SSI to work, you must use “imbeds on” or “imbeds on ssi” only (recommended) in your httpd.conf file. For ssi_type_and_path (below), two forms are supported: VIRTUAL=”/Web Access/BLQHHEAD.html” and FILE=”/usr/lpp/InfoMan/web/BLQHHEAD.html” Either form can be used. The Virtual= form is recommended and allows you to use the URI to locate the file, which is controlled by the matching Map and Pass directives in your httpd.conf file. See IBM HTTP Server Planning, Installing, and Using, SC31-8690 for Version 5.2, or SC34-4826 for Version 5.3 for more information in server side includes. The following are server side include directives: html_down_ssi (ssi_type_and_path) Displayed when the Web Access Web server is up, but the BLX-SP is down, or the database is not available. html_epilog_ssi (ssi_type_and_path) Include at the end of the HTML generate to capture errors and display Web Access Web information.168 IBM Tivoli Web Access for Information Management
    • html_mailto_ssi (ssi_type_and_path) The HTML that is included in any Web Access errors so that the error information can be captured. html_poolbad_ssi (ssi_type_and_path) Use when the global variable pool used to hold data for a given user is no longer valid. This occurs when the user has done more than max_searches, or the update or create has completed and the user attempts to use the browser’s Back button to access the now out-of-date data. html_prolog_ssi (ssi_type_and_path) Included at the top of all error HTML and displays of Web Access Web information.Business logic exit routine directives For more information about using and coding business logic exits, see Chapter 4, “Implementing a Web solution using Web Access” on page 33. The following are business logic exit routine directives: email_tsx Name of the TSX used to perform e-mail notifications. This directive is optional. If omitted, no e-mail notification will be performed by Web Access. home_page_exit Name of the REXX module used to create the home page. Used by the Web Access REXX routines when they generate a hyperlink to go to the home page. postfile_create_exit REXX routine called after a record is successfully created by Web Access. The exit can examine the data used to create the record, but any changes made to the data by postfile_create_exit are not saved by Web Access. It is possible to update the just created record in postfile_create_exit. However, care must be taken, since the record is not checked out to the user who created the record. This directive is optional. If omitted, no exit is called. postfile_update_exit REXX routine called after a record is successfully updated by Web Access, but before the record is checked in so that other users can update the record. The exit can examine the data used by the update, but any changes made to the data by postfile_update_exit are not saved by Web Access. It is possible for post_update_exit to file the record if necessary, since the record is still checked out to the same user. This directive is optional. If omitted, no exit is called. predisplay_exit REXX routine called after Web Access has obtained all the data to be displayed and just before Web Access retrieves an HTML file used to display and format the data. The predislay_exit routine can add and remove data and change the HTML file name used to display and format the data. This directive is optional. If omitted, no exit is called. Appendix C. Web Access configuration parameters 169
    • validation_exit REXX routine called after the HLAPI has validated the changed data52 and just prior to updating the session variables. The validation_exit can add, remove, or change existing data, and this data is saved into the session variables and used by Web Access if validation_exit exits with a successful return code. The validation_exit routine can also flag a data item as invalid and issue an error message describing the error. In this case, the session variables are not updated. If the record is filed before HTML is returned to the browser, the validation can prevent the file from occurring and cause HTML to be displayed. The validation_exit routine can specify the next HTML file to be displayed to the user if the record is not going to be filed. This directive is optional. If omitted, no exit is called.User profile directives The following are user profile directives: saved_user_searches Number of saved user-defined search arguments that can be stored in a Web user’s profile. Once this number is reached, the oldest search argument is deleted when a new search is saved. This directive is optional. If omitted, the default is 5. saved_user_transactions Number of saved user update or create transactions that can be stored in a Web users profile. Once this number is reached, the oldest update or create transaction information is deleted when a new one is added. The user can view his or her transaction history by selecting the List Last Records Updated hyperlink on the home page. This directive is optional. If omitted, the default is 10. max_hits Maximum number of records that can be seen on a search results list (SRL). This directive is optional. If omitted, the default is 500. max_user_searches Number of searches a user can perform before their oldest cached search is deleted from the cache. This directive is optional. If omitted, the default is 5.Record type directives (used for all record types) The record_type directive is required once for each type of record you would like to access using Web Access. An xxxx_view or xxxx_pidt is needed for each type of transaction you would like to support for that record type. For example: record_type CLASS S0B1C J search_view BLQCLASS update_view BLQCLASS retrieve_view BLQCLASS Web Access can search (to verify that a user is in the class), update (to add a user to a class), and retrieve a privilege class record (to get the authority codes) using the BLQCLASS data view. However, since create_view is not coded, Web Access cannot create a class. Also, no html_file is coded on any of the xxxx_view directives. This means that Web Access can work with privilege classes internally, but a user cannot search, update, or retrieve them using Web Access. Generating the HTML and adding html_file to the directive could add user access for privilege classes if desired. 52 Unchanged data is not validated.170 IBM Tivoli Web Access for Information Management
    • You can use views or PIDTs or mix them for the same record type. Each record_typedirective begins a new grouping. record_type name s-word html_qualifier name—A unique single word in uppercase that is used to identify the type of record that this directive applies to, for example, PROBLEM. s-word—An “S” followed by a four-digit hexadecimal number that is the record s-word index for this record type, for example, S0032. html_qualifier—One or more characters that will be used with other data to form the HTML file name when generating HTML for this record type. The HTML qualifier should be unique for each record type. For example, do not use “P” for both problem and people. Consider using more than one character; you may want to use “PRB” for problem and “PEO” for people. copy_pidt name html_file or copy_view name html_file name—Data view used to retrieve the record being copied. This data view should only include the fields that you would like to be copied from the source record to the new record. html_file—Default HTML file name displayed when the user chooses to copy a record of this type. create_pidt name html_file or create_view name html_file name—Data view used when a new record of this type is created by Web Access. html_file—Default HTML file name displayed when the user chooses to create a record of this type. retrieve_pidt name html_file or retrieve_view name html_file name—Data view used when a new record of this type is retrieved by Web Access. html_file—Default HTML file name displayed when the user chooses to display a record of this type. search_pidt name html_file srl_file or search_view name html_file srl_file name—Data view used by Web Access when searching for records of this type. html_file—Default HTML file name displayed when the user chooses to search for records of this type. This HTML is where the Web user enters the keywords or otherwise supplies search criteria. srl_file—HTML file used to display and format the records located in the search. text_append s-word … s-word s-word—Freeform text s-words that will have their contents appended to any existing text for this record type. Code one or more s-words separated by a space. The format is “S” followed by the s-word index of the freeform text field. Appendix C. Web Access configuration parameters 171
    • dar_shadows s-word shadow1...shadowN A list of shadow s-words that will be replaced by s-word. This allows data attribute records that contain a shadow s-word to be used in place of the s-word data attribute record so that a drop-down list created using the shadow data attribute record can contain different values than a drop-down list created using the s-word data attribute record. The list created from the shadow data attribute records will be used in place of the list from the s-word data attribute record in the HTML. See Chapter 9, “Using shadow s-words and data attribute records” on page 91 for more information. You may specify multiple dar_shadows directives. update_pidt name html_file or update_view name html_file name—Data view used when a record of this type is updated by Web Access. html_file—Default HTML file displayed when the user chooses to update a record of this type.Generic database search directives The following are generic database search directives: find_all_pidt name html_file srl_file or find_all_view name html_file srl_file name—Used for generic database searches. Data view or PIDT used by Web Access when searching for records of unknown type. This view or PIDT is used by Web Access to determine the record type of a specific record identifier so that the record can be processed using the correct view or PIDT for its type. html_file—Default HTML file name displayed when the user chooses to do a search that is not specific to any record type. This HTML is where the Web user enters the keywords or otherwise supplies search criteria. srl_file—HTML file used to display and format the records located when the search does not include a specific record type.HTML generation directives The following are HTML generation directives: approver_html html_file html_file—HTML file to display after an approve or reject is performed. Auto_Build_file The fully qualified file name of your Auto Build file. When you generate HTML and opt to save the settings in the Auto Build file, they are saved here. This file is also used by the HTML generator to automatically repeat generation of the HTML using the settings saved in it. You do not have to create the file, since the Auto Build process will create it for you if it does not exist already. The location of the Auto Build file must be in a directory to which you have write access. Additional information about the HTML generator and the Auto Build file is in Chapter 6, “Generating user application HTML” on page 63.172 IBM Tivoli Web Access for Information Management
    • box_display html_filehtml_file—HTML template file used when generating display and print HTML when<fieldset> tags are used. Field set tags cause a box to be drawn around groups.box_input html_filehtml_file—HTML template file used when generating update and create HTML when<fieldset> tags are used.box_inquiry html_filehtml_file—HTML template file used when generating inquiry HTML when <fieldset> tagsare used.HL01_during_build YES | NOCauses a new HLAPI session with the BLX-SP to be performed just prior to generatingHTML. This insures that the latest changes made to data model records are used whenthe HTML is generated. However, this causes the generating process to take longer.This directive is optional. If omitted, the default is NO.html_file_mode nnnUNIX System Services mode used when new HTML files are created in a directory. Thisdirective is optional. If omitted, the default is 755.model_rnid_prefixOne to six characters used to create the RNID for model records. Model records are“generic,” mimic all record types, and are used to validate data using the HLAPI withoutactually changing the database. Web Access appends a number from 01 to max_sessionsto this prefix to form the RNID of the model record for each HLAPI session Web Accessuses.table_display html_filehtml_file—HTML template file used when generating display and print HTML when<table> tags are used to format groups of HTML fields.table_input html_filehtml_file—HTML template file used when generating create and update HTML when<table> tags are used to format groups of HTML fields.table_inquiry html_filehtml_file—HTML template file used when generating inquiry HTML when <table> tags areused to format groups of HTML fields.validation_checkerS-word used to induce a known error into an update or create transaction so that the file ofthe record does not occur. When the only data error indicated by the HLAPI is the s-wordfor validation_checker, all other input data is valid. When an error is not induced, and allthe data is valid, the record is filed. By manipulation of the validation_checker s-word,Web Access can use the HLAPI update transaction to validate the data without filing arecord.The validation_checker s-word is in the form S followed by the four-digit hexadecimals-word index. You may want to use S0BCC as your validation_checker s-word since WebAccess provides a data attribute record for it that you can use. Refer to 5.2.2, “Specialprocessing s-words and table names” on page 44 for more information about thevalidation checker. Appendix C. Web Access configuration parameters 173
    • S-words to left-zero pad and create hyperlinks A list of record identifier s-words. When Web Access processes one of the record identifiers, it left-zero pads any all-numeric value the user might have entered. When displaying the data for any of these s-words, Web Access adds the necessary HTML anchor tag to create a hyperlink. List those record identifier s-words that you want Web Access to do this additional processing for. The format of a record identifier s-word is S followed immediately by the s-word index of the record identifier. You can specify multiple record identifier s-words separated by a space. You can also specify multiple rnid_SWord_list directives. The order and case is not significant. The configuration file (BLQPARMS) provided with Web Access contains rnid_SWord_list directives that include the following record identifier s-words. You may want to include this set of record identifier s-words in your configuration file (removing those for which you do not want Web Access to do this additional processing) and add your record identifier s-words to it: rnid_SWord_list S0CCF S0CD0 S0CD1 S0CD2 S0CD3 S0CD4 S0CD5 S0CD7 rnid_SWord_list S0CD8 S0CD9 S0CDA S0CDB S0CDC S0CDD S0CDE S0CDF rnid_SWord_list S0CE0 S0CE1 S0CE4 S0CE5 S0CE6 S1291 S1292 S1293 rnid_SWord_list S1294 S1299 S129A174 IBM Tivoli Web Access for Information Management
    • Related publications The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook.IBM Redbooks For information on ordering these publications, see “How to get IBM Redbooks” on page 176. Tivoli Business Systems Manager: A Complete End-to-End Management Solution, SG24-6202 Tivoli NetView® 6.01 and Friends, SG24-6019 Tivoli Service Desk V6.0: IT Infrastructure Planning Guide, SG24-5312Other resources These publications are also relevant as further information sources: IBM HTTP Server for OS/390 Planning, Installing, and Using, Version 5.2, SC31-8690 IBM Tivoli Web Access for Information Management Program Directory, GI10-3232 Tivoli Information Management for z/OS Application Program Interface Guide, Version 7.1, SC31-8737 (BLGA6E10) Tivoli Information Management for z/OS Data Reporting User’s Guide, Version 7.1, SC31-8739 (BLGR8E10) Tivoli Information Management for z/OS Desktop User’s Guide, Version 7.1, SC31-8740 (BLGJ1E10) Tivoli Information Management for z/OS Diagnosis Guide, Version 7.1, GC31-8741 (BLGD1E10) Tivoli Information Management for z/OS General Information, Version 7.1, GC31-8743 (BLGA0E10) Tivoli Information Management for z/OS Guide to Integrating with Tivoli Applications, Version 7.1, SC31-8744 (BLGB2E10) Tivoli Information Management for z/OS Integration Facility Guide, Version 7.1, SC31-8745 (BLGI8E10) Tivoli Information Management for z/OS Messages and Codes, Version 7.1, GC31-8748 (BLGM9E10) Tivoli Information Management for z/OS Operation and Maintenance Reference, Version 7.1, SC31-8749 (BLGO1E10) Tivoli Information Management for z/OS Panel Modification Facility Guide, Version 7.1, SC31-8750 (BLGP6E10) Tivoli Information Management for z/OS Planning and Installation Guide and Reference, Version 7. 1, GC31-8751 (BLGP2E10) Tivoli Information Management for z/OS Problem, Change, and Configuration Management, Version 7.1, SC31-8752 (BLGU1E10)© Copyright IBM Corp. 2003 175
    • Tivoli Information Management for z/OS Program Administration Guide and Reference, Version 7.1, SC31-8753 (BLGS1E10) Tivoli Information Management for z/OS Reference Summary, Version 7.1, SC31-8754 (BLGR3E10) Tivoli Information Management for z/OS Terminal Simulator Guide and Reference, Version 7.1, SC31-8755 (BLGS2E10) Tivoli Information Management for z/OS User’s Guide, Version 7.1, SC31-8756 (BLGU2E10) Tivoli Information Management for z/OS World Wide Web Interface Guide, Version 7.1, SC31-8757 (BLGW1E10) z/OS HTTP Server Planning, Installing, and Using, Version 5.3, SC34-4826How to get IBM Redbooks You can order hardcopy Redbooks, as well as view, download, or search for Redbooks at the following Web site: ibm.com/redbooks You can also download additional materials (code samples or diskette/CD-ROM images) from that site.IBM Redbooks collections Redbooks are also available on CD-ROMs. Click the CD-ROMs button on the Redbooks Web site for information about all the CD-ROMs offered, as well as updates and formats.176 IBM Tivoli Web Access for Information Management
    • Index APISymbols operating characteristics 3.js files 39, 154 return code option 118=DATE 47 API_Bombed 57=TIME 47 apimsg_option 23, 119, 166–167?CALLER_ID 50, 126 APIPRINT 23, 167?DATE_FORMAT 50, 144 data set 166?FILE 51, 131 application_id 29, 119, 165?MODE 49, 124, 131, 137, 139–140 approval processing 45?PEOPLE_VIEW_NAME 50 approved class 111?PEOPLE_VIEW_TYPE 50 approver_html 172?RECORD_TYPE 49, 124, 131, 133–134, 137, 139–141 approver_table class 111?ROLE 49, 124 assisted-entry panels 91?SEPARATOR_CHARACTER 51 ATTACH 46?TIME_ZONE 51, 144 reserved table name 160?TYPE 124 table 160?USER_PROFILE_ID 49, 128 attachment_path 21–22, 26, 168?VIEW_NAME 50 ATTRIBUTE directive 164?VIEW_TYPE 50 audit information 34, 46, 75@ signs 107 Auto Build@ATTACH 107 file 25, 63–64, 67, 70_view suffix 36 process 70 Auto_Build_file 70, 172Numerics3270 B access 63 background-color 110–112 applications 34, 42, 71 Base date format 145, 147 data view record BLANK@ 107 panel layouts 67 BLG01053 46 summary panel 73 BLG01439 141 deleting BLG0J100 17 people records 120 BLG1TDAR 72 privilege class records 120 BLGCLDSN 164 panels 71, 167 macros 13 screens 43, 147 BLGDVLAY 154 users 147, 160, 167 BLGPARMS 15 using Information Management for z/OS 72 BLG-Source 13 data session 15A BLGTDMBL 71–72a class 111 BLGTNMAN 17a.submenu_hover class 112 BLGTPRIV 83a_hover class 112 BLGTRPND 137activity BLGUEXIT 57 logs 167 BLGUT18 44, 63, 70, 119, 154 notification 139 BLGUT6J 15Add_Separator 57, 131 BLQ&0ED1 44AddType directives 21 BLQ&0EF7 44ADDUSER 19 BLQ&9999 46admin_class 28–29, 115, 119, 165 BLQ&APST 45Administer Web hyperlink 115 BLQ&APVR 45administrator role 84, 165 BLQ&AUSR 160alias tables 8, 12–13, 126, 167 BLQ&CLAE 46analyst role 28, 84 BLQ&CLRL 85APARs 10, 72 BLQ&DATA 160© Copyright IBM Corp. 2003 177
    • BLQ&DATE 46 BLQVINC 41BLQ&DATM 46 BLQVPEOP 41, 43–44, 50, 160BLQ&DFMT 43, 147 BLQVPROB 34, 37, 41, 65–67, 70, 73, 81, 95, 105, 107,BLQ&PSA1 95–96, 99 154BLQ&PSA2 95, 99 BLQVREQ 41BLQ&PSA3 95, 99 BLQVRPEO 126, 128BLQ&PSAL 95–96, 99 BLQVSOL 41BLQ&PTYP 105, 107 BLQVWORK 41BLQ&RLOC 46 BLQWA9TB.html. 45BLQ&RLOU 46 BLQWA9TR.html 45BLQ&RNPD 141 BLQWA9TT.html 45BLQ&ROLE 85 BLQWADMN 87BLQ&TIMA 160 BLQWADMN.html 84BLQ&TIME 46 BLQWALST 15, 87, 89BLQ&TIMM 46 BLQWALST.html 84BLQ&USER 46 BLQWAPII 21BLQ&UTZN 44 BLQWAPIT 21BLQ0C105.html 134 BLQWCINI 21BLQ0I001.html 124 BLQWCTRM 21BLQ0P002.html 131 BLQWMGT 87BLQ0P104.html 133 BLQWMGT.html 84BLQADMN 17, 23, 26, 28–29, 118 BLQWORK 28–29, 165BLQALST 15, 17, 28–29 BLQWRGET 5, 144BLQATTCH 158–160 BLQWRVAL 6BLQBATCH 25, 70 BLQWSUPP 87BLQCLASS 170 BLQWSUPP.html 84BLQHOME 7, 83, 90 BLQWSWRT 5, 117BLQHOME.REXX 23, 40 BLQWUSER 40, 87, 89BLQJNAVM.js 40 BLQWUSER.html 83–84BLQJNAVU.js 40 BLQYREPA 126BLQMANOT 139 BLXPRM 12BLQMAPPR 15, 18, 137 member 15BLQMCNOT 139 BLX-PROC 12, 14BLQMGT 17, 28–29 BLX-SP 12, 117, 173BLQMINOT 140 parameters 15BLQMPNOT 139 Bomb_Out 58BLQMRNOT 140 border-bottom-width 110BLQMRSET 18, 137 border-collapse 111BLQPARMS 14, 20–23, 29, 33, 36, 40, 42, 45, 47, border-color 11050–53, 67, 70, 93–94, 98, 116–117, 123, 137, 139–141, border-left-width 110163, 174 border-right-width 110 cache 7 border-style 110–111BLQPARMS.conf 163 border-top-width 110blqstyle.css 109, 111 box_display 173BLQSUPP 17, 28–29 box_input 173BLQTCHGA 137 box_inquiry 173BLQTNCNM 139 boxes 79, 81BLQTNREP 140 BTN6STA1 91BLQTXCVT 133–134, 144–148 BTN6STAT 91BLQTXDAT 144–145, 147 building the home page 40BLQUEXIT 48, 54–55, 58, 124, 126, 128–129, 131, business logic 3, 33, 37, 39, 42–44, 47, 49, 52–53, 55,133–134, 137, 139, 141 57, 60, 83, 118, 124, 129, 137, 144, 148BLQUSER 17, 28–29, 120, 165 exitBLQUT18J 16 points 7, 48BLQUXFIL 123, 137 routine directives 169BLQUXPRE 123–124 routines 38BLQUXVA 56 predisplay_exit routine 6BLQUXVAL 123, 129, 148–149 REXX routines 48BLQVACT 41 user exits 7BLQVCHNG 41, 45 validation_exit routine 6178 IBM Tivoli Web Access for Information Management
    • buttons class 110 DATA_VIEW_NAME 50, 52bypass_panel_processing 119, 166 database 4 72 database 5 16, 72 databases directive 166C DATAVIEW directive 164cached data 4–5, 7, 39, 98, 115, 117–119, 154–155, Date (REXX function) 133–134165–166, 168, 170 date formatcascading style sheets 109 selecting 43CDATE compound variable 148 Date() 144–149CFG.index.recordfunction 52–53 DATE_FORMAT 44, 145CFG.recordsword 52–53 debugCFG.recordtypename 52–53 api 23, 119change option directives 164 approval 137 options 117 notification 139 default HTML page 51Changed subroutine 56 default_data_storage_size 119, 167check-in processing 39 determining your home page 83check-out processing 39 DFLTGRP 19CHIRON.BLQVPROB 155 directives that control the Information Management APICLASS directive 164 166class_count 119, 166 display-mode HTML 42, 67color attribute 110–112 DMRDB session 13, 16conditionally required fields scheme 101 name 16configuration drop-in solution 3 directives 164 dropping file 7, 14, 20–21, 23, 28–29, 33, 36–37, 42, 45, 63, HTML cache 117–119 70, 98, 115–116, 119, 163, 174 privilege class pool 117, 119 parameter 164 user information pool 117, 120 file content syntax 164 information 3 server 11 ECONVERT variable 148 e-mail notification 17, 39, 48, 123copy_pidt 171 email_tsx 123, 137, 139–140, 169copy_view 171 environment variable 163Core REXX 5, 7, 36 EQUAL_SIGN_PROCESSING 136, 141create HTML option 118 errorcreate_pidt 171 handling 57create_view 170–171 recovery 5create-mode HTML 65–66 error_log_path 22, 168 error_message class 110 ErrorLogD directive 168dar_shadows 172 file 117 parameter 98 external date format 50, 147 statement 94 externalizing local variables 55data attribute records 16, 33, 37, 41–42, 44–46, 63, EXTTOINT 14871–72, 76, 81, 85, 91, 93–97, 99, 101, 105, 107–108, 119,147, 154, 157–160, 172–173data model records 3, 11, 14, 16, 33–35, 41–42, 47, 50, F63, 71–72, 117, 173 fft_table_with_audit_data class 111 database 16, 72 fft_table_with_audit_data_caption class 111data session 13, 16 field prompt 72 database 15 find_all_pidt 172data set name directives 164 find_all_view 172data storage size 167 font-family 110–111data validation font-size 110–111 errors 46 font-weight 110–111 records 16, 33, 119 free pools 117data view records 16, 33–37, 41, 43, 46, 51, 63, 65, 67, freeform text 72, 81, 158, 160, 167, 17170–72, 75, 79, 81–82, 93, 95, 97–98, 105, 107, 119, 126, data 49128, 141, 154, 157, 159–160, 167, 171–172 FTP 119 Index 179
    • G html_path 25–26, 168general control directives 165 html_poolbad_ssi 169generic database search directives 172 html_prolog_ssi 169get profile data 118 HTMLcache 119Get_Coordinator_Data 124, 128 HTTPGet_People_Data 124, 126 protocol request 5GetAPIdata 39 Server 3–4, 11–14, 18–20, 22–23global for Web Access 10 variable pool 169 for z/OS 5 variables 48 Planning, Installing, and Using 11–12, 18–19groups 79, 81–82 server 165 based on type 107 Web server 117GWAPI 5, 21 http.conf 23 REXX httpd.conf 14, 20–23, 168 DLL 20 httpd.envvars 13–14, 117, 163 interface 4 httpd-errors 23, 117H Ihardware requirements 10 IBMUSER 28HFS 5, 14, 20–22, 33 ICSPARM parameter 14hhmm2min 133–134 images directory 155history data 77 IMWAADM 28–29 display 44 IMWAUSER 19, 28–29HL01_during_build 173 IMWX00 20HLAPI 38 incident notification 140 environment cache 5 indexing data 67 HL14 transaction 148 INFOMANWEBTOOLKITCONF 14, 22, 116–117, 163 log 29 Information Management for z/OS session 5, 165 database 3–5, 7, 23, 33, 38, 63, 124, 126, 128, 131 initialization 165 HLAPI 38HLAPI/REXX Operation and Maintenance Reference 10, 14 CREATE transaction 141 Panel Modification Facility Guide 34, 46, 71 fatal error 57 Planning and Installation Guide and Reference 10, functionality 47 14–15, 44 interface 3, 5 World Wide Web Interface Guide 3 RETRIEVE transaction 52, 126, 128 installation reference table 10, 12 SEARCH transaction 141 Integration Facility 71, 91 transactions 51, 53 internal date format 147 UPDATE transaction 141 INTOEXT 148 USERTSP transaction 133–134, 137, 139–140, 144 IP network 4HLAPILOG 23, 117, 167 IRCs 118hlimsg_option 23, 119, 167 ISPF 118–119hlq.BLGDVLAY 154home_page_exit 38, 40, 47, 83, 169 JHTML 3, 14 Java Desktop 71, 157–158, 160 cache 6, 98, 118 JavaScript 37–40, 90, 148 directory 155 JESSPOOL 19 elements 109 Just_Changed 56, 129 generate process 70 generation 172 generator 25, 37, 64, 70, 76–79, 82, 98, 157 L member name option 118 LDAP directory 5 view 33 list data 49html_down_ssi 168 LLAPI 168html_epilog_ssi 168 message option parameter 166html_file 170 local status variable 48html_file_mode 173 lookuphtml_mailto_ssi 169 directive 164html_page 59–60 records 40, 87, 89180 IBM Tivoli Web Access for Information Management
    • lp_button class 110 postfile_create_exit 7, 47, 123, 169lp_row_even class 111 postfile_update_exit 7, 47, 123, 169lp_row_odd class 111 predefined searches 89lp_table class 110 predisplay user exit 37 predisplay_exit 6–7, 47, 123, 169 print record 76M processing 44manager role 28, 84 privilege class 27Map directive 21, 168 cache 6max_attachment_size 22, 168 list processor format 83max_hits 170 records 30max_searches 169 privilege_class 29, 119, 165–166max_sessions 165, 173 problem notification 139max_user_searches 170 Program Directory 9message model record 137, 139–140 PTFs 10, 72message_text 59model_database 119, 167model_rnid_prefix 119, 173 QMODELDB 72 queued e-mail notification 39 parameter 14 queued notification 123msg_rec 137, 139–140 QueueIt 58msg_tsx 137, 139–140 RN RACF 5, 29NAMA/ 45 functions 19nested panels 101 Program Control support 19non-HLAPI/REXX fatal error 58 read/write database 16, 72notification read-only database 72 feature 17 record TSX 137, 139–140 access directives 51 variables 53O history data 82optional class 110 ID fields 45OUTPUT.UEXTDATE.n 148 identifier conflicts 11OUTPUT.UINTDATE.n 148 type directives 170 types 24P record_type 36–37, 171padding-bottom 111 directives 37, 43, 164padding-top 110–111 parameter 98pagetitle class 110 statement 94PALTs 8 transaction directives 42Panel Layout Definition panel 34 record-specific tasks 79Parse_Name 57, 131 recycling HLAPI 117, 119Pass directive 21–22, 168 Redbooks Web site 176PATH statement 22 Contact us xiiiPDB message chain 167 REFERENCE directive 164PDBs 126, 128, 141, 166–167 reject class 111 tracing 117 reloading configuration file 117, 119pending class 111 request notification 140people records 43, 50, 120, 124, 126, 128, 156 required class 110PIDT_NAME 50, 52 resource queues 39PIDTs 8, 12–13, 36, 44, 51–52, 63, 70, 119, 141, 154, restricted variables 54167, 171–172 retrieve_pidt 171PIPTs 8 retrieve_view 171PMF REXX 14 panels 117 compound variables 48, 51 session 13 global variable pool 48–49, 51, 54–55, 58–59, 124,pop-up calendars 40 126, 128–129, 133–134, 141post-file user exits 37, 39 global variables 49, 131, 139–140 Index 181
    • routines 22 Snnnn.?type compound variable 48 SYMBOL function 48 software requirements 10rft_dsname 22, 119, 164 sorting tables 40RFTDD 13, 22, 164 spool_interval 23, 119, 166–167 data set 16 SRLRFTs 8, 13, 164 See search results listrnid_SWord_List 45, 174 srleven class 110run a TSP/TSX option 118 srlodd class 110 SSI See server side includeS ssi_type_and_path 168S0BCC 46, 173 StandardS0C09 45, 101, 105, 107–108 date format 147S0CBC 45, 161 standardS0CCF 45 tasks 79S0CD0 161 static data views 16S0E01 49 STCGRP 19S0ED1 44, 161 styleS0EF7 44, 76, 160 files 154S1152 46, 161 sheet 109S12DE 45, 161 Style File 69S12DF 45, 161 submenu class 110SAF 120 SUMHIST 82 directory 5 summary data 78Save_Pool_Data 55, 58 support role 28, 84saved_user_searches 170 surrogate user ID 19saved_user_transactions 170 s-words to left-zero pad and create hyperlinks 174SAVESRCH 46 reserved table name 160SBLMDICT 12 TSBLMFMT 12–13, 22 table class 111SBLMMOD1 12, 14–16, 19, 23 table_count 119, 167SBLMPNLS 12, 15 table_display 173SBLMRCDS 12 table_input 173 data set 16 table_inquiry 173SBLMSAMP 12, 15–16 TCP/IPSBLMTSX 12–13, 22 network 5 data set 17 protocol 4scrolling banners 40 td.menu class 111search results list 170 td.menuframe class 111 HTML files 36 testSEARCH transaction 141 HTML option 118search_pidt 171 Web server 117search_view 171 text_append 171searching 33 text_width 119, 167Select_With_My_Classes?() 161 text-align 110server text-decoration 110 address spaces 39 time zone setting 43 side include (SSI) directives 168 Time() 144, 147session TIME_ZONE 44, 145 data cache 5, 7 timeout_interval 119, 168 variables 170 TIMEZONEsession_member 22, 119, 167 parameter 43session-parameters member 3, 44 reference record 147SetAPIdata 39 Tivoli logo 155shadow s-words 91, 93–94, 97–98, 172 today variable 145Show_Approvers?() 161 total_minutes 149Show_Childern?() 161 tracking information 131Show_History?() 161 transaction directives 43SMP/E installation 10, 12, 14, 18, 20 Translate() 144SMTP parameters 17 TSCAVDA 39182 IBM Tivoli Web Access for Information Management
    • TSO/E REXX reference 144 WEBSRV 19TSPs 37, 39, 47, 118 word_id 29tsx_dsname 22, 119, 164 work_class 28–29, 119, 165–166TSXs 13, 37–39, 47, 118, 144, 154, 169 work_id 29, 119, 166 data sets 7 WTO 39 execs 12ttpd.conf 168type-based HTML 45, 102 X XDAR 94UUniversal Time 145 Yuniversal time 43–44, 147 your_port_number 11, 18UNIX directory 155 your_sblmrcds_pds 16UNIX System Services 4–5, 18, 20, 33, 39, 70, 88, 155,173 path and file reference directive 168Update_Data 55–56, 124, 128–129, 131, 133–134update_pidt 172update_view 172user data cache 5 preferences HTML 44 role 28, 84user ID/privilege class directives 165user profile directives 170Userid_to_Name 56, 129UT See universal timeVvalidate HTML 117validation checker data attribute record 46 s-word 46 patterns 91, 97–98, 106 user exit 37–38VALIDATION directive 164validation_checker 173validation_exit 6–7, 47, 56, 123, 170VAR state 48variable pools 38vertical-align 111view configuration file 116 trace 117VSAM panel data sets 8WWeb Access data view 34 utilities 13Web Administration 27–28 page 115, 118Web Connector for OS/390 158web_master 165WEBPROC 12–13, 20 Index 183
    • 184 IBM Tivoli Web Access for Information Management
    • IBM Tivoli Web Access for Information Management
    • Back cover ®IBM Tivoli Web Accessfor InformationManagementMove your help desk IBM Tivoli Web Access for Information Management is a sophisticated Web application that combines the power of INTERNATIONALto the Web Information Management for z/OS with the flexibility and usability TECHNICAL of a Web browser to enable customers to manage their business SUPPORTGet tips for installingWeb Access environments from the Web. A drop-in problem and change ORGANIZATION management solution designed for help desk, developer, manager, and end user personnel is provided, along with a toolkitLearn about the HTML for customization support. Also included with the toolkit aregenerator administrative tasks that allow you to manage your application BUILDING TECHNICAL from the Web. Web Access supports e-mail and pager INFORMATION BASED ON notification, change approval, document attachments, and PRACTICAL EXPERIENCE personal profiles and preferences. IBM Redbooks are developed Using Information Management for z/OS and Web Access, you by the IBM International can easily add or modify record types for a customized Technical Support application. The HTML generator supplied with the toolkit lets you Organization. Experts from IBM, Customers and Partners create the HTML for your records so that you do not have to from around the world create create it from scratch. Sample business logic is provided, and timely technical information additional logic can be easily added by writing simple REXX based on realistic scenarios. routines. Specific recommendations are provided to help you implement IT solutions more To provide a complete solution, a guidebook is required. This IBM effectively in your Redbook describes product usage, installation, customization, environment. and other pertinent information regarding the product. For more information: ibm.com/redbooks SG24-6823-00 ISBN 073842613X