IBM Tivoli Web Access For Information Management Sg246823

Front cover
IBM Tivoli Web Access for Information Management

Move your help desk to the Web Get tips for installing Web Access Learn about the HTML generator
Don Miller Mimi Michelet Michael Bacon Maryann Goldman Rollin Hippler Pete Louis Tom Shultz
ibm.com/redbooks
International Technical Support Organization IBM Tivoli Web Access for Information Management April 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 number 5698-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 Schedule Contract 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Part 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Part 2. Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Chapter 4. Implementing a Web solution using Web Access . . . . . . . . . . . . . . . . . . . . 4.1 Data model record overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 BLQPARMS definitions needed to support a record type . . . . . . . . . . . . . . . . . . . . . . . 4.3 Business logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.1 Predisplay user exit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.2 Validation user exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.3 Post-file update and create user exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.4 TSXs and TSPs used by business logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Copyright IBM Corp. 2003
33 34 36 37 38 38 39 39 iii
4.3.5 JavaScript in HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.3.6 The home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Chapter 5. Building a customized Web application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1 Getting started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 Data model and HTML considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.1 Date format and universal time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.2 Special processing s-words and table names. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.3 Audit information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3 Integrating business logic into your application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.1 REXX global variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.2 BLQUEXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 42 43 43 44 46 47 48 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. . . 7.1 Panel layouts. . . . . . . . . . . . . . . . . . . . . . . . 7.1.1 Standard tasks . . . . . . . . . . . . . . . . . . 7.2 Fields and groups . . . . . . . . . . . . . . . . . . . . ....... ....... ....... ....... ...... ...... ...... ...... ....... ....... ....... ....... ...... ...... ...... ...... ....... ....... ....... ....... 71 73 75 78
Chapter 8. Using existing privilege class records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Chapter 9. Using shadow s-words and data attribute records . . . . . . . . . . . . . . . . . . . 9.1 Shadow s-words in Web Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2 Status shadow s-words and data attribute records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.1 The BLQPARMS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.2 Status shadow s-words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.3 Status shadow data attribute records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.4 Groups that include the status shadows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3 Building a shadow scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3.1 Several other variations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 10. Type-based HTML . . . . . . . . . . . . . . . . . . . . . . . . . 10.1 Type-based HTML in Web Access . . . . . . . . . . . . . . . . . . . 10.2 Understanding type-based HTML in the problem record . . 10.3 Key points to remember . . . . . . . . . . . . . . . . . . . . . . . . . . . ....... ....... ....... ....... ...... ...... ...... ...... ...... ...... ...... ...... 91 92 93 94 95 95 95 97 98
101 102 105 108
Chapter 11. Updating the style file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Part 3. Administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Chapter 12. Web administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.1 Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.1.1 Navigation area tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.1.2 Field-initiated tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.2 Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 116 116 118 119
Part 4. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Appendix A. Business logic examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BLQUXPRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BLQUXVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BLQUXFIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using dates, date formats, and time zones in business logic . . . . . . . . . . . . . . . . . . . . . . iv
123 124 129 137 144
Obtaining the current date and time in the users format and time zone. . . . . . . . . . . . Converting a date in the users preferred format to internal format. . . . . . . . . . . . . . . . Converting an internal date to a user-preferred external date format . . . . . . . . . . . . . . Rules to remember when handling dates in business logic . . . . . . . . . . . . . . . . . . . . . Calculating a duration: An example using BLQUXVAL. . . . . . . . . . . . . . . . . . . . . . . . . Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix B. Hints and tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Your changes to Web Access do not seem to take effect . . . . . . . . . . . . . . . . . . . . . . . . . Listing groups and layouts in data views using BLGDVLAY . . . . . . . . . . . . . . . . . . . . . . . Changing Web page titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Tivoli logo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Date formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Java Desktop data view and data attribute records . . . . . . . . . . . . . . . . . . . . . . . . . Sharing the Web server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data views and data attributes used in the attaching process . . . . . . . . . . . . . . . . . . . . . . Add attachments to your data views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix C. Web Access configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . Updating the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Debug option directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data set name directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General control directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User ID and privilege class directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Directives that control the Information Management API . . . . . . . . . . . . . . . . . . . . . . . UNIX System Services path and file reference directives. . . . . . . . . . . . . . . . . . . . . . . Server side include (SSI) directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Business logic exit routine directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User profile directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Record type directives (used for all record types). . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generic database search directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTML generation directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . S-words to left-zero pad and create hyperlinks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . IBM Redbooks collections. . . . . . . . . . . . . . . . . . . . . . ...... ...... ...... ...... ...... ....... ....... ....... ....... ....... ...... ...... ...... ...... ...... ...... ...... ...... ...... ......
144 145 146 147 148 149 153 154 154 155 155 156 157 158 158 159 160 163 164 164 164 165 165 166 168 168 169 170 170 172 172 174 175 175 175 176 176
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Contents
vi
Notices
This 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. Consult your 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 IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate 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. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, 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 provisions are inconsistent with local law : INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "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 of express 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 made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials 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 without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities 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 them as 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 business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs 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, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.
Copyright IBM Corp. 2003. All rights reserved.
vii
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:
^ eServer IBM MVS NetView OS/390 Planet Tivoli Redbooks Redbooks(logo) RACF Tivoli z/OS
The following terms are trademarks of other companies: ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, 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 Electronic Transaction LLC. Other company, product, and service names may be trademarks or service marks of others.
viii
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.
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.
Rollin Hippler joined the Information Management development team in 1989, when he helped design and implement the V5 BLX-SP. Since that time, he has worked on enhancements to increase database capacity, improve database integrity, and improve performance. He has also worked on logical database partitioning and sysplex exploitation. In addition, Rollin has been a member of the service team providing resolutions for problems related to the BLX-SP and database integrity. His primary responsibility for the Web Access project was infrastructure development. Pete Louis has worked on the Information Management team since 1991, doing development and support, as well as acting as system programmer for the team's development/test systems. He generally concentrates on the behind the scenes and infrastructure areas of the product (such as VSAM, parallel sysplex, multitasking, serialization, system services interfaces, and packaging). His primary contribution to the Web Access project was the redesign of the Information Management API to support running in the HTTP Server multitasking environment. Tom Shultz has been a member of the Information Management team since 2000 and has been working with the product since 1995. As part of the Information Management team, he has done Level 2 support and development, specializing in PMF, REXX/TSX, and the Desktop. Tom helped code HTML for the Web Access project and provided assistance with developing this redbook.
Editorial staff
Thanks to the following people for their contributions to this project: Buck Stearns was managing editor. He is a Solution Development IT Specialist for IGS Business Development at the ITSO, Raleigh Center. Prior to joining ITSO, he worked two years as a mobile employee assigned to Tivoli Services and specializing in Information Management for z/OS and Tivoli Business Systems Manager. Before that, he logged over 25 years in the banking and insurance industries, including the last 12 as problem, change, and configuration system administrator, architect, and programmer for Wachovia, now the nations fourth-largest financial holding company. Buck has spoken on configuration management at the national Information Management users conference and is ITIL-certified.2 He has extensive experience in IT management disciplines and holds undergraduate and graduate 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.
Reviewers
Thanks to the following people for their contributions to this project: Julie Bergh IBM Minneapolis, MN Art Eisenhour IBM Gaithersburg, MD
2 The Information Technology Infrastructure Library (ITIL) is a set of books developed by the United Kingdom's Office of Government Commerce (OGC). These books describe an integrated, process-based, best-practice framework for managing IT services. To date, they are the only comprehensive, non-proprietary, publicly available guidance for IT service management. ITIL was conceived in the late 1980s. It was initiated to improve IT Service Management in the UK central government and is relevant to all organizations, public or private sector, large or small, centralized or distributed. 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, Ontario
Notice
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. You'll team with IBM technical professionals, Business Partners and/or customers. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll 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.html
xii
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
Part 1
Part
Basics
Part 1 contains a Web Access product overview and installation instructions.
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. ApplicationData 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. InfrastructureCommon 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. ConfigurationApplication 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.
More information can be found in Updating the configuration file on page 164.
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
HTML
Directory
SAF/LDAP Database
z/OS
Tables
(PIDT and alias)
TSXs
Caches
HTML User data P-class HLAPI env SRL BLQPARMs
Core REXX
BLQWSWRT BLQWRGET BLQWRVAL BLQWRUPD BLQWRNEW BLQWRUPD BLQWRINQ ...
Session data (cached record)
Database, Data Model Records
Business Logic BLQUXPRE BLQUXFIL BLQUXVAL

Home Page BLQHOME
Session data (cached record)
HLAPI/REXX
Information Management
Figure 1-1 Web Access application flow
Tivoli Web Access

HLAPI/REXX
The HTTP Server for z/OS, Information Management for z/OS, and Web Access, along with your existing TCP/IP network and workstations, work together to enable a user to work with records in your Information Management for z/OS database using a Web browser. Accessing the Information Management for z/OS database in this way is done using a URL that can either be typed into the browsers address box or (more likely) hyperlinked from an existing HTML page that your users frequent. When a Web user addresses the HTTP Server for z/OS, it authenticates that user using either SAF (RACF) or Lightweight Directory Access Protocol (LDAP) directories. If the user cannot be authenticated, processing stops and the user is not allowed access to the Information Management for z/OS database. After the Web user 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 sends the 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/OS database using the Information Management HLAPI/REXX interface and the HTTP Server for z/OS GWAPI, both of which are documented and supported general application programming interfaces.4 Following is a breakdown of the components and functionality of the HTTP Server, Web Access, and Information Management for z/OS:
HTTP Server for z/OS

The 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.5
Web Access
Web Access provides the infrastructure required to display, update, create, or search for records stored in the Information Management for z/OS database. This infrastructure consists of the following:
Core REXXModules 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 users profile (user data cache). Obtains and frees a HLAPI session for each request. Manages the HLAPI environment cache. Handles error recovery.
BLQWRGET:
4 5 6
Using HLAPI/REXX, reads a record from the Information Management for z/OS database. Loads the record data into the users session data cache.6
No undocumented or unsupported interfaces are used by Web Access. A Common Gateway Interface (CGI)-like interface. A cached copy of the record data for use by other Web Access routines and business logic user exits.
Chapter 1. Overview
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 cacheBLQWRGET 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 cacheKey fields from the Web users people record profile, including fields such as the users date format and time zone. Privilege class (P-Class)The authority codes for each privilege class are cached. HLAPI environmentsEach 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 cacheThe 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/child
BLQPARMS cacheThe 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 cacheA 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 users 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 browsers Back button or refresh or reload the HTML.
Business logic exit pointsThough 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_exitRuns before each HTML page is displayed. Validation_exitRuns when the user leaves an HTML page or files a record. Postfile_create_exitRuns after a record is created. Postfile_update_exitRuns after a record is updated. In addition, your business logic can control what information is displayed on the users 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/OS

Components 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
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 PALTs
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.
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 UW87419 UW92102 UW92212 & UW92213 UW92070 & UW92071 UW92090 UW92186 UW92562
8
APAR fixed OW53441 OW54084 OW54215 OW54576 OW54626 OW55367 OW55489
Check the PSP bucket, UPGRADE INFO710 SUBSET HOYB120, for the latest maintenance.
10
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 later
2.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 BLX-PROC Location and description 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
Name BLG-Source
Location and description 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)
13
Name httpd.conf
Location and description 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 members, 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 Information 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 database. 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 easier 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 MODELDB 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
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.
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. CLASSTypically MASTER ii. APPLID Your user ID iii. SESSThe 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
4. Submit the JCL and examine the output. There should be no error messages (it should complete with CC=0).11
2.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.
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
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.
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/* Protect /IMWAmaster/* IMWA 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.
13
A 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
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 ServerTerm /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWAPIT /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 /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWSWRT/*.REXX /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWSWRT/*.BIN
Service /IMWA/*.REXX Service /IMWA/*.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 Pass Pass /IMWA/attachments/* /IMWA/* /IMWAmaster/* /usr/lpp/InfoMan/web/tmp/* /usr/lpp/InfoMan/web/html/* /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
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 AgentLog RefererLog ErrorLog CgiErrorLog /usr/lpp/InfoMan/web/logs/httpd-log /usr/lpp/InfoMan/web/logs/agent-log /usr/lpp/InfoMan/web/logs/referer-log /usr/lpp/InfoMan/web/logs/httpd-errors /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/BLQPARMS
2.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_memberChange 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_dsnameChange to reflect the names of your RFTDD and SBLMFMT data sets. Include a rft_dsname parameter for each data set. error_log_pathThis needs to be the same as the path defined in your ErrorLog directive in the httpd.conf file. attachment_pathThis 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_sizeSet 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
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_optionset to B apimsg_optionset to B spool_intervalset to a value greater than 0 debug
apiset 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.
Refer to Appendix C, Web Access configuration parameters on page 163 for additional information regarding the configuration file.
14
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 page
24
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.
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 browsers 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
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 users 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.
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 user's 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 users home page and authority over certain records are as follows:
BLQALSTAnalyst role BLQMGTManager role BLQSUPPSupport role BLQUSERUser role
The following classes are used behind the scenes:

BLQADMNThe behind-the-scenes class that determines whether you are allowed to perform Web Administration tasks 17 BLQWORKThe 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 user's date format and time zone specifications from the users 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
Although BLQUSER20 is a privilege class used by some users, it is also a special class of sorts. BLQUSER has very basic authorities. If a user logs on to Web Access for the first time and is not in any privilege class, this user will be placed in BLQUSER. BLQUSER is also used by Web Access to perform privilege class checks for users, such as checking to see if the user is in a class and what authorities a given class has. Since users will automatically be added to BLQUSER if they are not in any other privilege class, you do not need to add them to this class. But if a user is in another privilege class, and you also want that user in BLQUSER, you will need to add that user. The following parameters are in your Web Access configuration file (BLQPARMS). As shipped, they are set to the following values. Refer to Appendix C, Web Access configuration parameters on page 163 for more information about these parameters.
application_idIMWAUSER privilege_classBLQUSER admin_classBLQADMN word_idIMWAADM work_classBLQWORK
IMWAUSER and IMWAADM are not TSO user IDs and require no special RACF setup. If you do not like those names, you can change them in your Web Access configuration file and in the eligible user lists in the privilege class records. The only places that these entries show up is in the HLAPI log and in the record history for the privilege class identified by the privilege_class parameter when Web Access adds a user to that class. New people records are also created using the ID identified by work_id. The privilege_class, admin_class, and work_class parameters identify privilege class records BLQUSER, BLQADMN, and BLQWORK. You can use these records or change them. They primarily show up in the HLAPI log. One special note about the admin_class is that, since its only 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 switch roles on your Web Access home page. Therefore, we recommend that you do not specify any privilege class used to provide record access (including your Master class) as the admin_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 your user. Each of these classes (as well as BLQUSER) has a unique home page on Web Access that 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 may also want to modify lookup reference records to provide your own set of canned searches that appear on a particular home page. These topics are described in Chapter 8, Using existing privilege class records on page 83.
20
The 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
Part 2
Part
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
31
32
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
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
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 create_view update_view retrieve_view search_view copy_view PROBLEM S0032 P BLQVPROB BLQ0P001.html BLQVPROB BLQ0P101.html BLQVPROB BLQ0P200.html BLQVPROB BLQ0P301.html BLQWSRLP.html 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
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 exitData 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 exitEnables you to add or remove data when the user is updating or creating a record and enforces your process. Post-file user exitsAfter the file, you can do additional processing. TSXsCalled from any of the business logic user exits. TSXs or TSPsCalled by the record update or record create coded in a data view. JavaScript in the HTMLUsed in auto-filling fields, navigation, help processing, and validating required fields.
37
The home pageControls 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
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.
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 user's 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
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:
IncidentBLQVINC ProblemBLQVPROB ChangeBLQVCHNG ActivityBLQVACT RequestBLQVREQ WorkBLQVWORK PeopleBLQVPEOP SolutionBLQVSOL
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 23
For example, the date a record was created and the user who last modified it. Remember to use the Web Administration page to reload the configuration file whenever you change it.
42
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 54
5.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
Record identifiers in HTML layouts

The rnid_SWord_List parameter in the BLQPARMS configuration file is used to list the s-word indexes for record ID fields. When record ID fields for any of the s-words in the rnid_SWord_list parameter appear in an HTML layout, the following additional processing is performed: 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 S12DF

S-word indexes S12DE (Approver) and S12DF (Approval Status) are used for approval processing. When a data attribute record for S12DE or S12DF is included in a display HTML layout, 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 Web solution provided with Web Access also uses approval processing, you may want to review the Web Access-supplied data view for change records (BLQVCHNG) to see how it includes these data attribute records.
Parent child s-word index S0CBC

When processing HTML layouts for change or request records, and an HTML layout contains a 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 S0C09

When using type-based HTML for create, update, or inquiry, do not include the data attribute record for S0C09 (Type) in a type-based group, or in a layout that includes type-based groups. In display or print layout, this restriction does not apply. Type-based HTML is described in Chapter 10, Type-based HTML on page 101.
25
Since S0CCF is the currently displayed record, the hyperlink is not needed.
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&DATEDate Created BLQ&TIMETime Created BLQ&CLAEClass Created BLQ&RLOCCreate Source BLQ&DATMDate Modified BLQ&TIMMTime Modified BLQ&USER User Modified BLQ&RLOUUpdate Source
46
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 users home page based on that users 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.
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:
XFreeform text LList DAll 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
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 S0E01.1 S0E01.2 S0E01.3 S0E01.4 = = = = = 4 'This is the first line of freeform text.' 'Here's the second line. The third is blank.' '' '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 ?USER_PROFILE_ID ?ROLE User Analyst Support Manager Administrator ACTIVITY CHANGE INCIDENT PEOPLE PROBLEM REQUEST SOLUTION WORK CREATE UPDATE COPY Values Description The ID of the current user's people record. The current user's role.
?RECORD_TYPE
The type of record with which the current user is working. These values may vary, depending on your implementation.
?MODE
How the current user is working with the record (create, update, or copy).
49
Variable name ?CALLER_ID
Values
Description 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. 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_NAME
?VIEW_TYPE ?PEOPLE_VIEW_NAME
PIDT_NAME DATA_VIEW_NAME BLQVPEOP
The type of data model used for the current record. Record access is defined in your BLQPARMS file. The data model used to access people records. The user's 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. 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. The current user's external date format. The user sets the external date format in his or her profile. The default is MM/DD/YYYY. In addition to these values, your Information Management for z/OS administrator can also set up a user-defined format.
?PEOPLE_VIEW_TYPE
DATA_VIEW_NAME
?DATE_FORMAT
MM/DD/YY MM-DD-YY MM.DD.YY MM/DD/YYYY MM-DD-YYYY 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 YYYYDDD
50
Variable name ?TIME_ZONE
Values NZT EAT EAST 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 1 0
Description The current user's time zone. The user sets the time zone in his or her profile. The default is ET (North America eastern with daylight saving time).
?FILE
User clicked Finish to file the record. 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.
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 create_view update_view retrieve_view search_view copy_view history_view print_view text_append dar_shadows dar_shadows PROBLEM S0032 P BLQVPROB BLQ0P001.html BLQVPROB BLQ0P101.html BLQVPROB BLQ0P200.html BLQVPROB BLQ0P301.html BLQWSRLP.html BLQVPROB BLQ0P001.html BLQVPROB BLQ0P205.html BLQVPROB BLQ0P206.html S0E01 S0BEE S5140 S5141 S5142 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
Example 5-3 Hardcode model on the transaction

data_view_name='BLQVPROB' rnid_symbol='00000025' control.1='data_view_name' control.2='rnid_symbol' control.0=2 parms='RETRIEVE,CONTROL,,OUTPUT' address 'LINK' 'BLGYRXM' parms
Or, 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 the record type or its s-word as defined in the BLQPARMS file. In this example, the name is PROBLEM. Using the same sample code as above to retrieve a problem record, you can dynamically obtain the data model type and name to pass on the HLAPI/REXX transaction, as shown in Example 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.Retrieve rnid_symbol='00000025' control.1=modeltype control.2='rnid_symbol' control.0=2 /* Assign modeltype to control PDB */ */
*/
*/ */ */ */ */
parms='RETRIEVE,CONTROL,,OUTPUT' address 'LINK' 'BLGYRXM' parms
The record access variables are summarized in Table 5-2.

Table 5-2 Record access variables
CFG.recordtypename CFG.recordsword CFG.index.recordfunction Index of the directives for the specified record type. Index of the directives for the specified record type. This is an alternate method of deriving the index. Data model name for the specified record type and function.
53
CFG.index.recordfunction.?viewtype
Data model type for the specified record type and function. Values are: DATA_VIEW_NAME PIDT_NAME Default HTML file for the specified record type and function.
CFG.index.recordfunction.?htmlfile
Where:
recordtypename recordsword index recordfunction
Record type name as specified in the record_type directive Record type s-word as specified in the record_type directive Value of CFG.recordtypename or CFG.recordsword 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
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: Exit 200 error_item error_text /* Module exit /* 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 on page 48, you can set the status to OPEN by coding the following.
Example 5-6 Set the status to OPEN
S0BEE = OPEN S0BEE.?type = D
This updates your local variables, but it does not externalize the changes to Web Access. To externalize 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 subroutine provided with the BLQUEXIT template and passing the s-word variable name to it. A subsequent call to the Save_Pool_Data subroutine (which is also provided with the BLQUEXIT template) actually adds or replaces the variables in the REXX global variable pool. Update_Data must be called for each new or modified variable that you want to externalize. Save_Pool_Data updates the REXX global variable pool en masse, so it only needs 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, since the BLQUEXIT template automatically calls it for you immediately before exiting. As you can see 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 by the 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 REXX global variable pool. You could exit at that point, you could Signal EndREXX to go directly to the EndREXX label and exit, or you could do any of a variety of things, whatever your logic dictates. You may also want to change the Exit statement or implement different Exit statements as required by your business logic. You should code the Exit statement based on Web Access guidelines described later.
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 Returned Example Snnnn, where Snnnn is the s-word variable name N/A S0BEE = OPEN S0BEE.?type = D Call Update_Data S0BEE
Changed
Changed tests if the record data value was changed.
Table 5-4 Changed
Input Returned 0 Example The value was not changed. /* if the status was changed */ if Changed(S0BEE) then Snnnn, where Snnnn is the s-word variable name 1 The value 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 Returned 0 Example The value was not just changed. /* if status was just changed */ if Just_Changed('S0BEE') then Snnnn, where Snnnn is the s-word variable name 1 The value 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 Returned Example Profile ID Name callers_name = Userid_to_Name(S14FD) callers_name = Userid_to_Name(?caller_id) callers_name = Userid_to_Name('JSMITH')
56
Parse_Name
Parse_Name parses a name into searchable formats. An input name in a typical format such as John Smith is returned in a string of four words, for example:
Smith/John Smith/J Smith John
Table 5-7 Parse_Name

Input Returned Example Name lastname/firstname lastname/firstinitial lastname firstname set_of_names = Parse_Name(S0B59) set_of_names = Parse_Name('John Smith')
Add_Separator
Add_Separator inserts the HLAPI separator character between words. Usage is for multiple response fields.
Table 5-8 Add_Separator
Input Returned Example Blank separated string of words Input string with blanks replaced by separator character list_of_names = Add_Separator(set_of_names)
Error handling
As you develop your business logic routines, you may need to handle errors that your logic detects. For some types of errors, you may want to stop processing, collect diagnostic information, and display the information back to the user. BLGUEXIT provides error handling routines that you can use if you detect a fatal error. Depending on the error and which routine you invoke, you can also set simple message text and a condition code to include in the information displayed to the user, where.
ccthe condition code variable textthe message text variable
Non-fatal errors can also be returned to Web Access on the Exit statement. This is described later. The following routines can be used to handle fatal errors.
API_Bombed
API_Bombed is an error handler for HLAPI/REXX failures. If your business logic invokes HLAPI/REXX calls that fail with fatal errors, you can do the following to collect diagnostics and exit:
Signal API_Bombed
Before 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 processing flows to Bomb_Out.
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
Example 5-10 shows the exit processing provided by the BLQUEXIT template. Notice how the 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: Exit 200 error_item error_text /* Module exit /* Return completion code */ */
Exit statement syntax

At a minimum, you must return a completion code on the Exit statement. It must be the first argument returned. Valid completion codes are 200 and 201. Use completion code 201 to signify a fatal error. The syntax for the Exit statement varies based on the completion code. The variations are documented below. Data that can be optionally returned is enclosed in brackets [ ].
Example 5-11 Success
Exit 200
Success.
Example 5-12 Field in error
Exit 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, that text is displayed at the top of the page. The user can correct the error and retry.
Example 5-13 Override HTML page
Exit 200 'HTML' html_page [message_text]
Where html_page is the file name of the HTML page to be displayed, and message_text is message text. Return the HTML keyword and an html_page to override processing and display the specified html_page. If you provide message_text, the text is displayed at the top of the page. Since changes to the REXX global variable pool are not discarded, you should only redirect the page if all data collected up to that point is valid.
Example 5-14 Fatal error
Exit 201
Fatal error. No processing is performed. Changes to data in the REXX global variable pool are discarded. Any diagnostic or error data that may have been collected is displayed.
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
26
For 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,OUTPUT'
60
One technique you could use to invoke a HLAPI/REXX transaction is demonstrated in Example 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.Problem modeltype=CFG.problem_index.Retrieve.?viewtype call value modeltype, CFG.problem_index.Retrieve rnid_symbol='00000025' control.1=modeltype control.2='rnid_symbol' control.0=2 input.='' input.1.?name='S0BEE' input.2.?name='S0E0F' input.0=2 /* Assign modeltype to control PDB */ /* Assign record ID to control PDB */ */
/* Retrieve status /* Retrieve description
*/ */
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 if cc > 0 then Signal API_Bombed /* set cc to rc from call /* handle fatal API error
*/ */ */
61
62
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.
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
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 selection
66
When you build HTML for any mode, choose the layouts as appropriate. For example, if you are creating the display-mode HTML, you should select History Data so that you can view the history data associated with a record. Not all layouts are needed for a given mode. Leave unwanted layouts unchecked so that they will not be included in the HTML generated for that given mode. If desired, you can overtype the HTML file name generated on the Create HTML page. These default to the Root HTML whose name you provided on the Web Administration page, along with the record type information from the configuration file (BLQPARMS) and the indexing data from the data view record. You can also overtype the HTML title, which defaults to the name that appears on the 3270 data 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 and as 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 the HTML. 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. This example shows that HTML was created for the Reporter Information, Details, and Tracking Information 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 to review the HTML generated for the Reporter Information task. Assuming that record ID 89 is an existing problem record in your Information Management database, Figure 6-5 on page 69 displays 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. If you want to test the generated HTML by changing the record contents, note the HTML file, and then use the Test HTML section of the Web Administration page.
67
Figure 6-4 Generated HTML page
68
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.
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.
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.
29
70
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
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
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
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.
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 box
76
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
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 page
7.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
Figure 7-7 Print Record task specification
Now 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), and what 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 should define them in a group. Using a group is a quick way to include a certain set of fields in a certain 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 HTML generator to build your HTML from your data view record specifications, you can request that groups have boxes drawn around them (see Figure 7-9 on page 81). All of the Web Access HTML is built with boxes around groups. In the Web Access problem record, the Reporter Information task has several associated groups and fields (see Figure 7-8 on page 80).
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
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 view's 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).
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
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).
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 roleUses BLQWADMN.html as the home page HTML.31 Analyst roleUses BLQWALST.html as the home page HTML. Manager roleUses BLQWMGT.html as the home page HTML. Support roleUses BLQWSUPP.html as the home page HTML. User roleUses 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 company's 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
If you want to define different roles and home pages, there are several steps that you must take: 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
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 BLQWALSTLookup work items for analyst role BLQWMGTLookup work items for management role BLQWSUPPLookup work items for support role BLQWUSERLookup 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
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 page
88
Depending on which lookup record you copied, there may be predefined search results that display at the bottom of the HTML. These predefined searches are defined in the lookup record, and all of the Web Access lookup records except BLQWUSER include them. You can change 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 the BLQWALST lookup record.
Figure 8-6 Changing predefined search results
The Item column needs to stay in the same format. Use w.1 - w.x consecutively. The w is for Web and the number corresponds to the $.labelx and $.datax values that appear in the HTML. 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. The Related information column contains the actual search arguments. In all of the searches in the example shown in Figure 8-6, the first argument is an s-word index. In these cases, the s-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:
S5078Incident S0B01Problem S0B06Change S0B07Activity S500BWork S5002Request S0B05Solution S0031People
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
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.
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
Figure 9-2 Problem Completion Information page
9.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 5141 5142 5143 5144 5145 5146 5147 5148 5149 514A 514B 514C 514D 514E 514F 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 515A 515B 515C 515D XDAR/A1 XDAR/A2 XDAR/A3 XDAR/A4 XDAR/A5 XDAR/B1 XDAR/B2 XDAR/B3 XDAR/B4 XDAR/B5 XDAR/C1 XDAR/C2 XDAR/C3 XDAR/C4 XDAR/C5 XDAR/D1 XDAR/D2 XDAR/D3 XDAR/D4 XDAR/D5 XDAR/E1 XDAR/E2 XDAR/E3 XDAR/E4 XDAR/E5 XDAR/E6 XDAR/E7 XDAR/E8 XDAR/E9 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
Example 9-1 BLQPARMS file

record_type create_view update_view retrieve_view search_view copy_view history_view print_view text_append dar_shadows dar_shadows PROBLEM S0032 P BLQVPROB BLQ0P001.html BLQVPROB BLQ0P101.html BLQVPROB BLQ0P200.html BLQVPROB BLQ0P301.html BLQWSRLP.html BLQVPROB BLQ0P001.html BLQVPROB BLQ0P205.html BLQVPROB BLQ0P206.html S0E01 S0BEE S5140 S5141 S5142 S0C0E S5154 S5155 S5156 S5157 S5158
9.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 S5141 BLQ&PSA2 S5142 BLQ&PSA3 Problem initial status Problem tracking status Problem closing Status
9.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.
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
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.
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
Figure 9-6 Shadow a field in a task
It is also possible to use multiple shadow data attribute records within one group or task. For example, you could specify BLQ&PSA1, BLQ&PSA2, BLQ&PSA3, and BLQ&PSAL all in one group (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
99
100
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.
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 record
102
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 record
104
On the Details HTML page, we get the Software Details group.
Figure 10-4 The Software Details group box
10.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.
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
The following corresponding groups are defined in the BLQVPROB data view record, as shown in Figure 10-6.
Figure 10-6 The BLQVPROB data view record
The Group ID must start with the @ sign for groups based on type. You must also use a second character to help identify the group. In our example, D helps us remember that those groups are for the Details task, and C helps us remember that those groups are for the Completion Information task. The second character serves as a visual reminder when we are picking the fields and groups that comprise a given task. The remaining six characters are used to match up to the type value specified above. The six characters must be a subset of one 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 in the record, Web Access uses a value of BLANK@ for S0C09. For example, assume that the user is doing a search. Typically, type is not a required field on a search. So, it is possible that the 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 you defined, the user would end up seeing no type group at all. To avoid that, Web Access will use a value of BLANK@ for S0C09, and if you define a @DBLANK@ type group, the fields in that 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.35
35
Note: You might see a group called @ATTACH. This is a special group used to attach documents, not a type-based group.
107
Figure 10-7 Groups and fields in the Details task
10.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
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.
109
Table 11-1 Web Access style sheet classes

Class pagetitle Used for The title at the top of each page Attribute font-family font-size font-weight color required Required fields background-color border-color Value verdana 14pt bold black #FFF7DE #A5A684 #CCCCCC #CCCCCC #A5A684 solid 1px 1px 1px 2px #ffffff #99ccff #ffffff bold red 10pt center 4px right verdana 8pt verdana 10pt bold white none verdana 10pt normal black
border-style border-top-width border-right-width border-bottom-width border-left-width optional srlodd srleven error_message Optional fields Odd rows in a search results list Even rows in a search results list Error messages that appear at the top of a page background-color background-color background-color font-weight color font-size text-align padding-top buttons lp_button Buttons at the bottom of a page List processor buttons Add, Edit, and Remove The menu items that appear down the left side of a page and across the top of a page text-align font-family font-size font-family font-size font-weight color text-decoration lp_table List processor data font-family font-size font-weight color
submenu
110
Class lp_row_even lp_row_odd approver_table
Used for Even rows on a list processor table Odd rows on a list processor table Change approver table
Attribute background-color background-color font-family font-size font-weight color border-collapse
Value #99ccff #ffffff verdana 10pt normal black separate #32CD32 black red verdana 10pt normal black double verdana 10pt bold black
approved pending reject fft_table_with_audit_data
Change approver Approved status Change approver Pending status Change approver Reject status. Freeform text data for records accessed in display mode
color color color font-family font-size font-weight color border-style
fft_table_with_audit_data_caption
Freeform text field labels for records accessed in display mode
font-family font-size font-weight color
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 table Used for (All Web Access pages are tables. This tag controls the table elements on the page not controlled by other styles.) Attribute font-family font-size color td.menu Formatting the text that makes up the menu across the top of a page. padding-top padding-bottom background-color td.menuframe The menu down the left side of a page. vertical-align background-color a a (anchor) elements that do not have a class coded. this includes anchors, such as the record numbers in search results lists. color Value verdana 10pt black 4px 5px #50589F top #50589F #333399
Chapter 11. Updating the style file
111
Tag a:hover
Used for The hover pseudo-class for a (anchor) elements that don't have a class coded. This sets the hover for anchors, such as the record numbers in search results lists. The hover pseudo-class for a (anchor) elements that have class=submenu. This sets the hover for the menu items that appear down the left side of a page and across the top of a page.
Attribute background-color
Value #d3d3d3
a.submenu:hover
color background-color
#9fcfcf #50589F
112
Part 3
Part
Administration
Part 3 covers Web administration tasks and procedures.
113
114
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.
36
Refer to Appendix C, Web Access configuration parameters on page 163 for information regarding the configuration file.
115
12.1 Tasks
The following are the administrative tasks that are available on the Web Administration page.
Figure 12-1 The Web Administration page
12.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
View Trace
This task displays the contents of the ErrorLog file (httpd-errors) in your browser. This file contains REXX trace, debugging messages, and other information helpful when trying to track data or user problems. It can be viewed as a flat file or in a text box (which allows easier cut and paste).
Drop User Information Pool

This task destroys the cached data for all users (their current class, time zone, and date format). The data will be re-cached the next time each user performs a transaction that interacts with the Web server.
Drop HTML Cache

Use this feature when making changes to any HTML pages so that other users will be able to obtain the most current HTML page updates.
Drop Privilege Class Pool

If changes are made to any of the privilege class records, select this option to allow the most current information in the record to be accessed.
Reload Configuration File

This task causes the configuration file pointed to by the environment variable INFOMANWEBTOOLKITCONF (in the httpd.envvars file) to be refreshed. This is commonly referred to as the BLQPARMS file.
Free Pools
This task releases all the sessions the Web server has with the BLX-SP so that the sessions can be used. Certain errors detected by the Web server do not allow BLQWSWRT to receive control when a Web transaction completes. When this occurs, the session is not freed. If this occurs enough times, Web users will receive the message No free sessions on their browsers. Using this link should free those sessions, avoiding the need to stop and restart the Web server. Look in the ErrorLog file (httpd-errors) for errors and correct them. Using free pools will lead to storage shortages on the Web server.
Recycle HLAPI
This 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 allows future requests to use updated data model records that were cached, privilege classes that were cached, and cached PMF panels.
Validate HTML
This is a link to a Web site that enables you to verify the syntax of your HTML pages. Refer to the instructions at the Web site for more information.37
Test Web Server

Clicking this link verifies that you are properly communicating with the HTTP Web server.
Debug Options
This is a feature that should help debug REXX code, as well as turn on PDB tracing in the HLAPILOG.
37
This Web site is on the Internet. However, your company's 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 Users Guide, Version 7.1, SC31-8756 (BLGU2E10), pages 235-239.
118
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 users user ID from SAF or remove that users 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
Part 4
Part
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
121
122
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
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 user's 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 user's profile and prefill those fields. Set the reporter or requester ID (S14FD) to the user's 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' S0BEE.?type = 'D' Call Update_Data 'S0BEE' /* Set default status /* Set data type /* 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
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 hasn't 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 user's 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 user's 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 users 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 user's 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 = 'BLQYREPA'
126
control.1 control.2 control.3 control.4 control.5 control.0
= = = = = =
'module' 'routine' 'data_view_name' 'rnid_symbol' 'alias_table' 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 = 11 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_Bombed 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 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 End End /* End do loop Return */ */
*/
127
Note: The subroutine Get_Coordinator_Data retrieves information from the coordinator's 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 users 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 coordinator's 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_Bombed
128
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 Return */ */
*/ */ */ */
BLQUXVAL
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.
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' End
130
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 Do S50E5.?type = 'D' S50E5 = Parse_Name(S500D) S50E5 = Add_Separator(S50E5) Call Update_Data 'S50E5' End If Changed('S5106') Then Do S50E6.?type = 'D' S50E6 = Parse_Name(S5106) S50E6 = Add_Separator(S50E6) Call Update_Data 'S50E6' End If Changed('S5105') Then Do S50E7.?type = 'D' S50E7 = Parse_Name(S5105) S50E7 = Add_Separator(S50E7) Call Update_Data 'S50E7' End If Changed('S151F') Then Do S50E8.?type = 'D' S50E8 = Parse_Name(S151F) S50E8 = Add_Separator(S50E8) Call Update_Data 'S50E8' End
/* Approver Name */
/* Backup Name
*/
/* Manager Name */
/* Name (in people record ) */
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.' End
132
Note: The following code runs when a problem or incident is closed. It verifies the completion date and 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 with a problem or incident, and the Changed subroutine provided with the BLQUEXIT template is used to test that the status (S0BEE) is newly CLOSED. The HLAPI/REXX USERTSP transaction is invoked to convert the date occurred (S0C3D) and date completed (S0C40) from the user's 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 date and time completed are verified as being after the date and time occurred. If not, you are redirected to the Completion Information page (BLQ0P104.html) to specify a valid completion date and time. The duration between the date and time completed and the date and time occurred 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 total duration field (S50B9). The Update_data subroutine provided with the BLQUEXIT template is used to put the total 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 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' DATE_FORMAT = ?date_format TIME_ZONE = ?time_zone control.1 = 'DATE_FORMAT'; control.2 = 'TIME_ZONE'; control.0 = 2; tsp_name CDATE.1 CDATE.2 CDATE.0 CONVERT = = = = = 'BLQTXCVT' S0C3D S0C40 2 'EXTTOINT' = = = = 'tsp_name' 'CDATE.' 'CONVERT' 3 /* /* /* /* /* Date converter TSX Date occurred Date completed Values to be converted Convert external to internal */ */ */ */ */ /* Set the API transaction /* Date calculations need user /* settings... */ */ */
input.1.?name input.2.?name input.3.?name input.0
/* Put tsx name in input variable*/
parms=trans',CONTROL,INPUT,OUTPUT' address 'LINK' 'BLGYRXM' parms cc = rc if cc \= 0 then signal API_Bombed /* code goes here */ date1 = output.uintdate.1 date2 = output.uintdate.2
/* call the API
*/ */ */
/* Save the return code /* Bad return code?
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 user's 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' DATE_FORMAT = ?date_format /* Set the API transaction /* Date calculations need user */ */
134
TIME_ZONE
= ?time_zone
/* settings...
*/
control.1 = 'DATE_FORMAT'; control.2 = 'TIME_ZONE'; control.0 = 2; tsp_name CDATE.1 CDATE.2 CDATE.0 CONVERT = = = = = 'BLQTXCVT' S0C43 S0C40 2 'EXTTOINT' = = = = 'tsp_name' 'CDATE.' 'CONVERT' 3 /* /* /* /* /* Date converter TSX Actual start date Date completed Values to be converted Convert external to internal */ */ */ */ */
parms=trans',CONTROL,INPUT,OUTPUT' address 'LINK' 'BLGYRXM' parms cc = rc if cc \= 0 then signal API_Bombed
/* call the API
*/ */ */
/* Save the return code /* Bad return code?
/* 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
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: Exit 200 error_item error_text /* Module exit /* 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 + mm
136
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
*/ */ */ */ */ */ */
137
end if msg_rec='' then if Changed('S0C49') then do msg_rec='BLQMRSET' input.='' tsp_name='BLGTRPND' input.1.?name='tsp_name' input.2.?name='rnid_symbol' input.0=2 parms=trans',,INPUT' address 'LINK' 'BLGYRXM' parms cc = rc if cc \= 0 then signal API_Bombed end
/* If status wasn't set to Locked*/ /* If due date changed */ /* Set notification message rnid */ /* Clear input stem variable /* Set the TSX name */ */
/* Put tsx name in input variable*/ /* Put rnid in input variable */
/* call the API /* Save the return code /* Bad return code?
*/ */ */
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 msg_tsx='BLQTCHGA' input.1.?name='tsp_name' input.2.?name='rnid_symbol' input.3.?name='msg_rec' input.4.?name='msg_tsx' input.0=4 /* Set the tsx name /* Set e-mail tsx /* /* /* /* Put Put Put Put
*/ */ */ */ */ */ */
@002C*/ */
tsx name in input variable*/ rnid in input variable */ e-mail message in i/p var */ e-mail message tsx in i/p */
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 if cc \= 0 then signal API_Bombed end end /* Save the return code /* Bad return code? */ */
138
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' tsp_name=CFG_Email_TSX rnid_symbol=S0CCF /* Set the API transaction /* Set the tsx name /* Get and set the rnid
*/ */ */ */ */
*/ */ @002C*/ */
/* 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' input.1.?name='tsp_name' input.2.?name='rnid_symbol' input.3.?name='msg_rec' input.4.?name='msg_tsx' input.0=4 parms=trans',,INPUT' address 'LINK' 'BLGYRXM' parms /* Set e-mail tsx (builds e-mail)*/ /* /* /* /* Put Put Put Put tsx name in input variable*/ rnid in input variable */ e-mail message in i/p var */ e-mail message tsx in i/p */
/* 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 if cc \= 0 then signal API_Bombed end /* Save the return code /* Bad return code?
*/ */
139
Note: The following code sends e-mail to a user who reports an incident or makes a request. It is confirmation that the users 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 Program 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' tsp_name=CFG_Email_TSX rnid_symbol=S0CCF /* Set the API transaction /* Set the tsx name /* Get and set the rnid
*/ */ */
*/ */ @002C*/ */
/* 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' input.1.?name='tsp_name' input.2.?name='rnid_symbol' input.3.?name='msg_rec' input.4.?name='msg_tsx' input.0=4 parms=trans',,INPUT' address 'LINK' 'BLGYRXM' parms /* Set e-mail tsx (builds e-mail)*/ /* /* /* /* Put Put Put Put tsx name in input variable*/ rnid in input variable */ e-mail message in i/p var */ e-mail message tsx in i/p */
/* Call the API
*/
if blg_rc = 12 & blg_reas = 901 then /* ignore no e-mail address */ rc = 0 cc = rc if cc \= 0 then signal API_Bombed end /* Save the return code /* Bad return code? */ */
140
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 solution's 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 S0BEE upper 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 isn't 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 */ */
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 input.1.?name='S0CE6' input.0=1 /* Search for RNPD/problemrnid /* Put rnpd problem id on chain
*/
*/ */
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 /* Don't 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
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 = control.2 = control.0 = rnid_symbol 'RNID_SYMBOL' prob_viewtype 2 = 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: Exit 200 error_item error_text /* Module exit /* Return completion code */ */
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 users 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 users format and time zone
TSX BLQTXDAT takes the user's 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 43
The function defaults to current date if you do not provide a value in this parameter. By default, next_week is a date in Base date format (an integer starting January 1 in the year 1).
144
Example: A-5 Using BLGTXDAT to return current data and time in users preferred format
trans = 'USERTSP' tsp_name = 'BLQTXDAT' time_zone date_format control.1 control.2 control.0 = = = = = /* Run TSX to get date and time */
?time_zone ?date_format 'time_zone' 'date_format' 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 /* /* now = output.uexttime /* /* Date in user's external format AND time zone. Time in user's 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, today's 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.44
Converting a date in the users 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, today's date adjusted for the user's current time zone) in the user's 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.
145
Example: A-6 Using BLGTXCVT to convert users external format date to database 5 internal format
tsp_name CDATE.1 CDATE.0 CONVERT = = = = 'BLQTXCVT' today 1 'EXTTOINT' = = = = /* /* /* /* Date converter TSX Date in external format Values to be converted Convert external to internal /* TSX to run /* Stem with the dates. /* What to do. */ */ */ */ */ */ */
input.1.?name input.2.?name input.3.?name input.0 output. output.0 = '' = 0
'tsp_name' 'CDATE.' 'CONVERT' 3
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 users 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 users external date format (see Example A-7).
Example: A-7 Using BLGTXCVT to convert database 5 internal format date to a users external format
tsp_name CDATE.1 CDATE.0 CONVERT = = = = 'BLQTXCVT' /* next_week_int 1 /* 'INTTOEXT' /* = = = = 'tsp_name' 'CDATE.' 'CONVERT' 3 Date converter TSX /* Date in external format Values to be converted Convert internal to external /* TSX to run /* Stem with the dates. /* What to do. */ */ */ */ */ */ */
input.1.?name input.2.?name input.3.?name input.0 output. output.0 = '' = 0
parms = trans',CONTROL,INPUT,OUTPUT' address 'LINK' 'BLGYRXM' parms next_week = output.uextdate.1 S0C47 = next_week
146
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 formatAny 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 user's time zone preference.46 Internal formatThere 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 formatDates in YYYYMMDD format (that are used by the REXX Date() function). Standard format dates can easily be translated to internal format. Base formatDates 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.
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 user's 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 CDATE.1 CDATE.2 CDATE.0 CONVERT = = = = = 'BLQTXCVT' S0C3D S0C40 2 'EXTTOINT' = = = = 'tsp_name' 'CDATE.' 'CONVERT' 3 /* /* /* /* /* Date converter TSX Date occurred Date completed Values to be converted Convert external to internal */ */ */ */ */
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
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 solution's business logic.
149
Table 12-1 Web Access TSXs and message model records

Process Change approval BLQMRSET BLQMANOT Record assigned BLQMCNOT BLQNPNOT BLQMINOT Record opened BLQMRNOT Request opened Change reapproval Activity assigned Change assigned Problem assigned Incident opened BLQTNREP BLQTNCNM Message model records BLQMAPPR Change approval BLQTCHGA Message TSX
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:
BLQTCHGAChange approval
Messages are sent to the eligible users in approver privilege classes whose approval status is Pending.
BLQTNCNMRecord assigned
A message is sent to the assignee identified by s-word index 50C5.

BLQTNREPRecord 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. approve or reject this record. Click on the link below to
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=!S0CCF
150
Example: A-12 BLQMANOT: Activity assigned

Change 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 required by !P00D5 !P0288. Description: !S0E0F Activity Description Text: !T0E01
Example: A-13 BLQMCNOT: Change assigned

Change record was requested phone number: The change is !S0CCF has been assigned to you. This change by !S0B59 (e-mail: !S01D1, !S0B2D). The current status is !S0BEE. required by !P00D5 !P0288.
Description: !S0E0F Change Description Text: !T0E01
Example: A-14 BLQMPNOT: Problem assigned

Problem record !S0CCF has been assigned to you to fix. This problem was reported by !S0B59 (e-mail: !S01D1, phone number: !S0B2D) on !P00E3 at !P0293. The current status is !S0BEE, the severity is !S7D42 and the priority is !S0BE7. A fix is required by !P00D5 !P0288. Description: !S0E0F Problem Description Text: !T0E01
Example: A-15 BLQMINOT: Incident opened

Incident record !S0CCF was created for you on !S0C34 at !S0C61. Description: !S0E0F Description text: !T0E01
Example: A-16 BLQMRNOT: Request opened

Request record !S0CCF was created for you on !S0C34 at !S0C61. Description: !S0E0F Description text: !T0E01
151
152
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.
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 browsers 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 browsers 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
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 Users 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 company's 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 user's 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
Figure B-1 Specifying your date format
Using 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.
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 BLQ&AT01 BLQ&AT02 BLQ&AT03 BLQ&AT04 BLQ&AT05 BLQ&AT06 BLQ&AT07 BLQ&AT08 Freeform text S-word 5201 5202 5203 5204 5205 5206 5207 5208 Use Attachment 1 Attachment 2 Attachment 3 Attachment 4 Attachment 5 Attachment 6 Attachment 7 Attachment 8
158
Data attribute RNID BLQ&AT09 BLQ&AT10
Freeform text S-word 5209 520A
Use Attachment 9 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 BLQ&AUSR BLQ&ADES BLQ&ANAM BLQ&ATTI BLQ&DATA BLQ&TIMA BLQ&DATM BLQ&TIMM BLQ&USER BLQ&RLOU Use Attachment user Attachment description Attachment name Attachment index Attachment date Attachment time Date modified Time modified User modified Update source
Add 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 BLQ&ANAM BLQ&ADES BLQ&ATTI BLQ&AUSR BLQ&DATA BLQ&TIMA S-word 5117 5116 5118 5115 5113 5114 Description Attachment name Attachment Description Attachment index Attachment user Attachment date Attachment time
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 person's 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: S0EF7The 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
S0ED1The existence of this field in a task causes history (journal) data to be formatted using Show_History?(). S12DE or S12DFCauses Show_Approvers?() to be added to the HTML. S0CBCIn a change record, causes Show_Childern?() to be added. S-words with special meaning in update/create-mode task HTML: S1152Causes Select_With_My_Classes?() to be added. S0CD0In 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.
161
162
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 servers 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.
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 server's 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. nameComponent 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. optionThe 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
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): CLLAPI chains messages and passes them from the LLAPI to the HLAPI for conversion into message PDBs. PLLAPI writes messages to the APIPRINT data set. BPerforms 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
default_data_storage_size
Specifies how much additional storage is allocated to hold default response data from an alias table when your application is creating records. When the HLAPI creates records, it calculates the size of the response buffer it needs by totalling the lengths of all the input data PDBs and adding the specified default data storage size. When the HLAPI performs create response processing, it always checks to make sure the response will not overlay storage. If the response will overlay storage, the HLAPI transaction ends with an error code. The drop-in problem and change management Web solution provided with Web Access does not use default response data. However, if your unique application uses default data, code this to meet your needs.
hlimsg_option
Contains a one-character HLAPI message option parameter (C, P, or B): CHLAPI chains messages on the PDB message chain. PHLAPI writes messages to the HLAPILOG data set. BPerforms 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 HLAPILOG can 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. C is recommended for production servers to maximize performance.
model_database
Contains a one-character ID number of the database where the data model records are stored. This directive is optional. If omitted, database 5 is the default.
session_member
Contains a seven- or eight-character load library session parameter member name that Information Management for z/OS uses for this session. Session member names cannot contain imbedded blanks.
spool_interval
Specifies the number of minutes that the HLAPI spools the activity logs HLAPILOG and APIPRINT when messages are printed. If the HLAPI is spooling to a data set, and this time interval has passed, the activity logs are recycled and new log information is written starting at the top of the data set, writing over any existing information. If you specify 0, the HLAPI does not log messages, and the settings in APIMSG_OPTION and HLIMSG_OPTION are ignored. Set this value to 1440 for non-production Web Access Web servers. Use 0 for production servers to maximize performance.
table_count
Indicates the maximum number of alias tables, data views, and PIDTs that the HLAPI can maintain in storage during the life of a Information Management for z/OS session. It is recommended that you use a value of at least 50 for table_count.
text_width
Specifies the maximum number of characters contained on a freeform text line. In update and create mode, lines will be wrapped to this value. Display and print lines are formatted to this length. This value defaults to 60 if you specify a value of 0 or a value greater than 132. Text width can be any value between 1 and 132. The default of 60 works well with the generated HTML. If you expect users to update freeform text using the 3270 panels, you may want to use 72, or possibly 80. When both the Web and 3270 users will be using freeform text, you will have to experiment with text width and set it to a value that allows all users to be able to view freeform text easily.
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
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 browsers 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.
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 users 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 user's 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 search_view update_view retrieve_view CLASS S0B1C J BLQCLASS BLQCLASS 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
You can use views or PIDTs or mix them for the same record type. Each record_type directive begins a new grouping.
record_type name s-word html_qualifier
nameA unique single word in uppercase that is used to identify the type of record that this directive applies to, for example, PROBLEM. s-wordAn S followed by a four-digit hexadecimal number that is the record s-word index for this record type, for example, S0032. html_qualifierOne 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
nameData 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_fileDefault 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
nameData view used when a new record of this type is created by Web Access. html_fileDefault 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
nameData view used when a new record of this type is retrieved by Web Access. html_fileDefault 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
nameData view used by Web Access when searching for records of this type. html_fileDefault 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_fileHTML file used to display and format the records located in the search.
text_append s-word s-word
s-wordFreeform 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.
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
nameData view used when a record of this type is updated by Web Access. html_fileDefault 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
nameUsed 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_fileDefault 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_fileHTML 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_fileHTML 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
box_display html_file
html_fileHTML 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_file
html_fileHTML template file used when generating update and create HTML when <fieldset> tags are used.
box_inquiry html_file
html_fileHTML template file used when generating inquiry HTML when <fieldset> tags are used.
HL01_during_build YES | NO
Causes a new HLAPI session with the BLX-SP to be performed just prior to generating HTML. This insures that the latest changes made to data model records are used when the 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 nnn
UNIX System Services mode used when new HTML files are created in a directory. This directive is optional. If omitted, the default is 755.
model_rnid_prefix
One 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 without actually changing the database. Web Access appends a number from 01 to max_sessions to this prefix to form the RNID of the model record for each HLAPI session Web Access uses.
table_display html_file
html_fileHTML template file used when generating display and print HTML when <table> tags are used to format groups of HTML fields.
table_input html_file
html_fileHTML template file used when generating create and update HTML when <table> tags are used to format groups of HTML fields.
table_inquiry html_file
html_fileHTML template file used when generating inquiry HTML when <table> tags are used to format groups of HTML fields.
validation_checker
S-word used to induce a known error into an update or create transaction so that the file of the record does not occur. When the only data error indicated by the HLAPI is the s-word for validation_checker, all other input data is valid. When an error is not induced, and all the 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 a record. The validation_checker s-word is in the form S followed by the four-digit hexadecimal s-word index. You may want to use S0BCC as your validation_checker s-word since Web Access provides a data attribute record for it that you can use. Refer to 5.2.2, Special processing s-words and table names on page 44 for more information about the validation checker.
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 rnid_SWord_list rnid_SWord_list rnid_SWord_list S0CCF S0CD8 S0CE0 S1294 S0CD0 S0CD9 S0CE1 S1299 S0CD1 S0CD2 S0CD3 S0CD4 S0CD5 S0CD7 S0CDA S0CDB S0CDC S0CDD S0CDE S0CDF S0CE4 S0CE5 S0CE6 S1291 S1292 S1293 S129A
174
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-5312
Other 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 Users Guide, Version 7.1, SC31-8739 (BLGR8E10) Tivoli Information Management for z/OS Desktop Users 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)
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 Users 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-4826
How 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
Index
Symbols
.js files 39, 154 =DATE 47 =TIME 47 ?CALLER_ID 50, 126 ?DATE_FORMAT 50, 144 ?FILE 51, 131 ?MODE 49, 124, 131, 137, 139140 ?PEOPLE_VIEW_NAME 50 ?PEOPLE_VIEW_TYPE 50 ?RECORD_TYPE 49, 124, 131, 133134, 137, 139141 ?ROLE 49, 124 ?SEPARATOR_CHARACTER 51 ?TIME_ZONE 51, 144 ?TYPE 124 ?USER_PROFILE_ID 49, 128 ?VIEW_NAME 50 ?VIEW_TYPE 50 @ signs 107 @ATTACH 107 _view suffix 36 API operating characteristics 3 return code option 118 API_Bombed 57 apimsg_option 23, 119, 166167 APIPRINT 23, 167 data set 166 application_id 29, 119, 165 approval processing 45 approved class 111 approver_html 172 approver_table class 111 assisted-entry panels 91 ATTACH 46 reserved table name 160 table 160 attachment_path 2122, 26, 168 ATTRIBUTE directive 164 audit information 34, 46, 75 Auto Build file 25, 6364, 67, 70 process 70 Auto_Build_file 70, 172
Numerics
3270 access 63 applications 34, 42, 71 data view record panel layouts 67 summary panel 73 deleting people records 120 privilege class records 120 panels 71, 167 screens 43, 147 users 147, 160, 167 using Information Management for z/OS 72
B
background-color 110112 Base date format 145, 147 BLANK@ 107 BLG01053 46 BLG01439 141 BLG0J100 17 BLG1TDAR 72 BLGCLDSN 164 macros 13 BLGDVLAY 154 BLGPARMS 15 BLG-Source 13 data session 15 BLGTDMBL 7172 BLGTNMAN 17 BLGTPRIV 83 BLGTRPND 137 BLGUEXIT 57 BLGUT18 44, 63, 70, 119, 154 BLGUT6J 15 BLQ&0ED1 44 BLQ&0EF7 44 BLQ&9999 46 BLQ&APST 45 BLQ&APVR 45 BLQ&AUSR 160 BLQ&CLAE 46 BLQ&CLRL 85 BLQ&DATA 160
A
a class 111 a.submenu_hover class 112 a_hover class 112 activity logs 167 notification 139 Add_Separator 57, 131 AddType directives 21 ADDUSER 19 admin_class 2829, 115, 119, 165 Administer Web hyperlink 115 administrator role 84, 165 alias tables 8, 1213, 126, 167 analyst role 28, 84 APARs 10, 72
177
BLQ&DATE 46 BLQ&DATM 46 BLQ&DFMT 43, 147 BLQ&PSA1 9596, 99 BLQ&PSA2 95, 99 BLQ&PSA3 95, 99 BLQ&PSAL 9596, 99 BLQ&PTYP 105, 107 BLQ&RLOC 46 BLQ&RLOU 46 BLQ&RNPD 141 BLQ&ROLE 85 BLQ&TIMA 160 BLQ&TIME 46 BLQ&TIMM 46 BLQ&USER 46 BLQ&UTZN 44 BLQ0C105.html 134 BLQ0I001.html 124 BLQ0P002.html 131 BLQ0P104.html 133 BLQADMN 17, 23, 26, 2829, 118 BLQALST 15, 17, 2829 BLQATTCH 158160 BLQBATCH 25, 70 BLQCLASS 170 BLQHOME 7, 83, 90 BLQHOME.REXX 23, 40 BLQJNAVM.js 40 BLQJNAVU.js 40 BLQMANOT 139 BLQMAPPR 15, 18, 137 BLQMCNOT 139 BLQMGT 17, 2829 BLQMINOT 140 BLQMPNOT 139 BLQMRNOT 140 BLQMRSET 18, 137 BLQPARMS 14, 2023, 29, 33, 36, 40, 42, 45, 47, 5053, 67, 70, 9394, 98, 116117, 123, 137, 139141, 163, 174 cache 7 BLQPARMS.conf 163 blqstyle.css 109, 111 BLQSUPP 17, 2829 BLQTCHGA 137 BLQTNCNM 139 BLQTNREP 140 BLQTXCVT 133134, 144148 BLQTXDAT 144145, 147 BLQUEXIT 48, 5455, 58, 124, 126, 128129, 131, 133134, 137, 139, 141 BLQUSER 17, 2829, 120, 165 BLQUT18J 16 BLQUXFIL 123, 137 BLQUXPRE 123124 BLQUXVA 56 BLQUXVAL 123, 129, 148149 BLQVACT 41 BLQVCHNG 41, 45
BLQVINC 41 BLQVPEOP 41, 4344, 50, 160 BLQVPROB 34, 37, 41, 6567, 70, 73, 81, 95, 105, 107, 154 BLQVREQ 41 BLQVRPEO 126, 128 BLQVSOL 41 BLQVWORK 41 BLQWA9TB.html. 45 BLQWA9TR.html 45 BLQWA9TT.html 45 BLQWADMN 87 BLQWADMN.html 84 BLQWALST 15, 87, 89 BLQWALST.html 84 BLQWAPII 21 BLQWAPIT 21 BLQWCINI 21 BLQWCTRM 21 BLQWMGT 87 BLQWMGT.html 84 BLQWORK 2829, 165 BLQWRGET 5, 144 BLQWRVAL 6 BLQWSUPP 87 BLQWSUPP.html 84 BLQWSWRT 5, 117 BLQWUSER 40, 87, 89 BLQWUSER.html 8384 BLQYREPA 126 BLXPRM 12 member 15 BLX-PROC 12, 14 BLX-SP 12, 117, 173 parameters 15 Bomb_Out 58 border-bottom-width 110 border-collapse 111 border-color 110 border-left-width 110 border-right-width 110 border-style 110111 border-top-width 110 box_display 173 box_input 173 box_inquiry 173 boxes 79, 81 BTN6STA1 91 BTN6STAT 91 building the home page 40 business logic 3, 33, 37, 39, 4244, 47, 49, 5253, 55, 57, 60, 83, 118, 124, 129, 137, 144, 148 exit points 7, 48 routine directives 169 routines 38 predisplay_exit routine 6 REXX routines 48 user exits 7 validation_exit routine 6
178
buttons class 110 bypass_panel_processing 119, 166
C
cached data 45, 7, 39, 98, 115, 117119, 154155, 165166, 168, 170 cascading style sheets 109 CDATE compound variable 148 CFG.index.recordfunction 5253 CFG.recordsword 5253 CFG.recordtypename 5253 change approval 137 notification 139 Changed subroutine 56 check-in processing 39 check-out processing 39 CHIRON.BLQVPROB 155 CLASS directive 164 class_count 119, 166 color attribute 110112 conditionally required fields scheme 101 configuration directives 164 file 7, 14, 2021, 23, 2829, 33, 3637, 42, 45, 63, 70, 98, 115116, 119, 163, 174 parameter 164 file content syntax 164 information 3 server 11 CONVERT variable 148 copy_pidt 171 copy_view 171 Core REXX 5, 7, 36 create HTML option 118 create_pidt 171 create_view 170171 create-mode HTML 6566
DATA_VIEW_NAME 50, 52 database 4 72 database 5 16, 72 databases directive 166 DATAVIEW directive 164 Date (REXX function) 133134 date format selecting 43 Date() 144149 DATE_FORMAT 44, 145 debug api 23, 119 option directives 164 options 117 default HTML page 51 default_data_storage_size 119, 167 determining your home page 83 DFLTGRP 19 directives that control the Information Management API 166 display-mode HTML 42, 67 DMRDB session 13, 16 name 16 drop-in solution 3 dropping HTML cache 117119 privilege class pool 117, 119 user information pool 117, 120
E
e-mail notification 17, 39, 48, 123 email_tsx 123, 137, 139140, 169 environment variable 163 EQUAL_SIGN_PROCESSING 136, 141 error handling 57 recovery 5 error_log_path 22, 168 error_message class 110 ErrorLog directive 168 file 117 external date format 50, 147 externalizing local variables 55 EXTTOINT 148
D
dar_shadows 172 parameter 98 statement 94 data attribute records 16, 33, 37, 4142, 4446, 63, 7172, 76, 81, 85, 91, 9397, 99, 101, 105, 107108, 119, 147, 154, 157160, 172173 data model records 3, 11, 14, 16, 3335, 4142, 47, 50, 63, 7172, 117, 173 database 16, 72 data session 13, 16 database 15 data set name directives 164 data storage size 167 data validation errors 46 records 16, 33, 119 data view records 16, 3337, 41, 43, 46, 51, 63, 65, 67, 7072, 75, 79, 8182, 93, 95, 9798, 105, 107, 119, 126, 128, 141, 154, 157, 159160, 167, 171172
F
fft_table_with_audit_data class 111 fft_table_with_audit_data_caption class 111 field prompt 72 find_all_pidt 172 find_all_view 172 font-family 110111 font-size 110111 font-weight 110111 free pools 117 freeform text 72, 81, 158, 160, 167, 171 data 49 FTP 119
Index
179
G
general control directives 165 generic database search directives 172 get profile data 118 Get_Coordinator_Data 124, 128 Get_People_Data 124, 126 GetAPIdata 39 global variable pool 169 variables 48 groups 79, 8182 based on type 107 GWAPI 5, 21 REXX DLL 20 interface 4
html_path 2526, 168 html_poolbad_ssi 169 html_prolog_ssi 169 HTMLcache 119 HTTP protocol request 5 Server 34, 1114, 1820, 2223 for Web Access 10 for z/OS 5 Planning, Installing, and Using 1112, 1819 server 165 Web server 117 http.conf 23 httpd.conf 14, 2023, 168 httpd.envvars 1314, 117, 163 httpd-errors 23, 117
H
hardware requirements 10 HFS 5, 14, 2022, 33 hhmm2min 133134 history data 77 display 44 HL01_during_build 173 HLAPI 38 environment cache 5 HL14 transaction 148 log 29 session 5, 165 initialization 165 HLAPI/REXX CREATE transaction 141 fatal error 57 functionality 47 interface 3, 5 RETRIEVE transaction 52, 126, 128 SEARCH transaction 141 transactions 51, 53 UPDATE transaction 141 USERTSP transaction 133134, 137, 139140, 144 HLAPILOG 23, 117, 167 hlimsg_option 23, 119, 167 hlq.BLGDVLAY 154 home_page_exit 38, 40, 47, 83, 169 HTML 3, 14 cache 6, 98, 118 directory 155 elements 109 generate process 70 generation 172 generator 25, 37, 64, 70, 7679, 82, 98, 157 member name option 118 view 33 html_down_ssi 168 html_epilog_ssi 168 html_file 170 html_file_mode 173 html_mailto_ssi 169 html_page 5960
I
IBMUSER 28 ICSPARM parameter 14 images directory 155 IMWAADM 2829 IMWAUSER 19, 2829 IMWX00 20 incident notification 140 indexing data 67 INFOMANWEBTOOLKITCONF 14, 22, 116117, 163 Information Management for z/OS database 35, 7, 23, 33, 38, 63, 124, 126, 128, 131 HLAPI 38 Operation and Maintenance Reference 10, 14 Panel Modification Facility Guide 34, 46, 71 Planning and Installation Guide and Reference 10, 1415, 44 World Wide Web Interface Guide 3 installation reference table 10, 12 Integration Facility 71, 91 internal date format 147 INTOEXT 148 IP network 4 IRCs 118 ISPF 118119
J
Java Desktop 71, 157158, 160 JavaScript 3740, 90, 148 JESSPOOL 19 Just_Changed 56, 129
L
LDAP directory 5 list data 49 LLAPI 168 message option parameter 166 local status variable 48 lookup directive 164 records 40, 87, 89
180
lp_button class 110 lp_row_even class 111 lp_row_odd class 111 lp_table class 110
M
manager role 28, 84 Map directive 21, 168 max_attachment_size 22, 168 max_hits 170 max_searches 169 max_sessions 165, 173 max_user_searches 170 message model record 137, 139140 message_text 59 model_database 119, 167 model_rnid_prefix 119, 173 MODELDB 72 parameter 14 msg_rec 137, 139140 msg_tsx 137, 139140
postfile_create_exit 7, 47, 123, 169 postfile_update_exit 7, 47, 123, 169 predefined searches 89 predisplay user exit 37 predisplay_exit 67, 47, 123, 169 print record 76 processing 44 privilege class 27 cache 6 list processor format 83 records 30 privilege_class 29, 119, 165166 problem notification 139 Program Directory 9 PTFs 10, 72
Q
queued e-mail notification 39 queued notification 123 QueueIt 58
N
NAMA/ 45 nested panels 101 non-HLAPI/REXX fatal error 58 notification feature 17 TSX 137, 139140
R
RACF 5, 29 functions 19 Program Control support 19 read/write database 16, 72 read-only database 72 record access directives 51 variables 53 history data 82 ID fields 45 identifier conflicts 11 type directives 170 types 24 record_type 3637, 171 directives 37, 43, 164 parameter 98 statement 94 transaction directives 42 record-specific tasks 79 recycling HLAPI 117, 119 Redbooks Web site 176 Contact us xiii REFERENCE directive 164 reject class 111 reloading configuration file 117, 119 request notification 140 required class 110 resource queues 39 restricted variables 54 retrieve_pidt 171 retrieve_view 171 REXX 14 compound variables 48, 51 global variable pool 4849, 51, 5455, 5859, 124, 126, 128129, 133134, 141 global variables 49, 131, 139140
O
optional class 110 OUTPUT.UEXTDATE.n 148 OUTPUT.UINTDATE.n 148
P
padding-bottom 111 padding-top 110111 pagetitle class 110 PALTs 8 Panel Layout Definition panel 34 Parse_Name 57, 131 Pass directive 2122, 168 PATH statement 22 PDB message chain 167 PDBs 126, 128, 141, 166167 tracing 117 pending class 111 people records 43, 50, 120, 124, 126, 128, 156 PIDT_NAME 50, 52 PIDTs 8, 1213, 36, 44, 5152, 63, 70, 119, 141, 154, 167, 171172 PIPTs 8 PMF panels 117 session 13 pop-up calendars 40 post-file user exits 37, 39
Index
181
routines 22 SYMBOL function 48 rft_dsname 22, 119, 164 RFTDD 13, 22, 164 data set 16 RFTs 8, 13, 164 rnid_SWord_List 45, 174 run a TSP/TSX option 118
S
S0BCC 46, 173 S0C09 45, 101, 105, 107108 S0CBC 45, 161 S0CCF 45 S0CD0 161 S0E01 49 S0ED1 44, 161 S0EF7 44, 76, 160 S1152 46, 161 S12DE 45, 161 S12DF 45, 161 SAF 120 directory 5 Save_Pool_Data 55, 58 saved_user_searches 170 saved_user_transactions 170 SAVESRCH 46 reserved table name 160 SBLMDICT 12 SBLMFMT 1213, 22 SBLMMOD1 12, 1416, 19, 23 SBLMPNLS 12, 15 SBLMRCDS 12 data set 16 SBLMSAMP 12, 1516 SBLMTSX 1213, 22 data set 17 scrolling banners 40 search results list 170 HTML files 36 SEARCH transaction 141 search_pidt 171 search_view 171 searching 33 Select_With_My_Classes?() 161 server address spaces 39 side include (SSI) directives 168 session data cache 5, 7 variables 170 session_member 22, 119, 167 session-parameters member 3, 44 SetAPIdata 39 shadow s-words 91, 9394, 9798, 172 Show_Approvers?() 161 Show_Childern?() 161 Show_History?() 161 SMP/E installation 10, 12, 14, 18, 20 SMTP parameters 17
Snnnn.?type compound variable 48 software requirements 10 sorting tables 40 spool_interval 23, 119, 166167 SRL See search results list srleven class 110 srlodd class 110 SSI See server side include ssi_type_and_path 168 Standard date format 147 standard tasks 79 static data views 16 STCGRP 19 style files 154 sheet 109 Style File 69 submenu class 110 SUMHIST 82 summary data 78 support role 28, 84 surrogate user ID 19 s-words to left-zero pad and create hyperlinks 174
T
table class 111 table_count 119, 167 table_display 173 table_input 173 table_inquiry 173 TCP/IP network 5 protocol 4 td.menu class 111 td.menuframe class 111 test HTML option 118 Web server 117 text_append 171 text_width 119, 167 text-align 110 text-decoration 110 time zone setting 43 Time() 144, 147 TIME_ZONE 44, 145 timeout_interval 119, 168 TIMEZONE parameter 43 reference record 147 Tivoli logo 155 today variable 145 total_minutes 149 tracking information 131 transaction directives 43 Translate() 144 TSCAVDA 39
182
TSO/E REXX reference 144 TSPs 37, 39, 47, 118 tsx_dsname 22, 119, 164 TSXs 13, 3739, 47, 118, 144, 154, 169 data sets 7 execs 12 ttpd.conf 168 type-based HTML 45, 102
WEBSRV 19 word_id 29 work_class 2829, 119, 165166 work_id 29, 119, 166 WTO 39
X
XDAR 94
U
Universal Time 145 universal time 4344, 147 UNIX directory 155 UNIX System Services 45, 18, 20, 33, 39, 70, 88, 155, 173 path and file reference directive 168 Update_Data 5556, 124, 128129, 131, 133134 update_pidt 172 update_view 172 user data cache 5 preferences HTML 44 role 28, 84 user ID/privilege class directives 165 user profile directives 170 Userid_to_Name 56, 129 UT See universal time
Y
your_port_number 11, 18 your_sblmrcds_pds 16
V
validate HTML 117 validation checker data attribute record 46 s-word 46 patterns 91, 9798, 106 user exit 3738 VALIDATION directive 164 validation_checker 173 validation_exit 67, 47, 56, 123, 170 VAR state 48 variable pools 38 vertical-align 111 view configuration file 116 trace 117 VSAM panel data sets 8
W
Web Access data view 34 utilities 13 Web Administration 2728 page 115, 118 Web Connector for OS/390 158 web_master 165 WEBPROC 1213, 20
Index
183
184
Back cover

Move your help desk to the Web Get tips for installing Web Access Learn about the HTML generator
IBM Tivoli Web Access for Information Management is a sophisticated Web application that combines the power of Information Management for z/OS with the flexibility and usability of a Web browser to enable customers to manage their business environments from the Web. A drop-in problem and change management solution designed for help desk, developer, manager, and end user personnel is provided, along with a toolkit for customization support. Also included with the toolkit are administrative tasks that allow you to manage your application from the Web. Web Access supports e-mail and pager notification, change approval, document attachments, and personal profiles and preferences. Using Information Management for z/OS and Web Access, you can easily add or modify record types for a customized application. The HTML generator supplied with the toolkit lets you create the HTML for your records so that you do not have to create it from scratch. Sample business logic is provided, and additional logic can be easily added by writing simple REXX routines. To provide a complete solution, a guidebook is required. This IBM Redbook describes product usage, installation, customization, and other pertinent information regarding the product.
INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION
BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.
For more information: ibm.com/redbooks
SG24-6823-00
ISBN 073842613X

IBM Tivoli Web Access For Information Management Sg246823

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

IBM Tivoli Web Access For Information Management Sg246823

Diunggah oleh

Hak Cipta:

Format Tersedia

Front cover

IBM Tivoli Web Access for Information Management

101 102 105 108

123 124 129 137 144

IBM Tivoli Web Access for Information Management

Copyright IBM Corp. 2003. All rights reserved.

IBM Tivoli Web Access for Information Management

Hereafter, called simply Web Access.

Copyright IBM Corp. 2003

The Evolution of Tivoli Information Management

The team that wrote this redbook

IBM Tivoli Web Access for Information Management

Become a published author

IBM Tivoli Web Access for Information Management

Send your comments in an Internet note to:

IBM Tivoli Web Access for Information Management

Copyright IBM Corp. 2003

IBM Tivoli Web Access for Information Management

Copyright IBM Corp. 2003

1.1 Data flow

1.1.1 The details

HTTP Server for z/OS

Database, Data Model Records

Business Logic BLQUXPRE BLQUXFIL BLQUXVAL

Session data (cached record)

Tivoli Web Access

IBM Tivoli Web Access for Information Management

HTTP Server for z/OS

IBM Tivoli Web Access for Information Management

Information Management for z/OS

IBM Tivoli Web Access for Information Management

Copyright IBM Corp. 2003

2.1.1 Hardware and software prerequisites

APAR fixed OW53441 OW54084 OW54215 OW54576 OW54626 OW55367 OW55489

IBM Tivoli Web Access for Information Management

2.1.2 Check for record identifier conflicts

Hopefully, you get the following message:

2.1.3 Ensure that the HTTP Sever is installed and working

2.2 Performing the SMP/E installation

2.2.1 Installation reference table

IBM Tivoli Web Access for Information Management

2.3 Customizing your Information Management installation

IBM Tivoli Web Access for Information Management

2.3.1 Update your session member

2.3.2 Update your BLX-SP parameters

2.3.3 Update your IBM panels

2.3.4 Load the sample records into your data session

IBM Tivoli Web Access for Information Management

2.3.7 Verify your Information Management customizations

2.3.8 Set up e-mail notification

2.3.9 Configure your HTTP Server for Web Access

IBM Tivoli Web Access for Information Management

IBM Tivoli Web Access for Information Management

Service /IMWA/*.REXX Service /IMWA/*.BIN

Service /IMWAmaster/*.REXX /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWSWRT/*.REXX

b. Add the following statement:

2.3.10 Update your BLQPARMS file

IBM Tivoli Web Access for Information Management

2.3.11 Start the HTTP Server

2.3.12 Verify your Web Access installation

2.3.13 Generate HTML

Figure 2-1 The Web Administration page

Service /IMWA/.REXX Service /IMWA/.BIN

Service /IMWAmaster/.REXX /usr/lpp/InfoMan/web/html/IMWX00.so:IMWX00/usr/lpp/InfoMan/web/rexx/BLQWSWRT/.REXX