Progress SHADOW Z User Manual

Z/ENTERPRISE WEB SERVER

Administration Guide

Version 5

manual is also copyrighted and all rights are reserved. This manual may not, in whole or in part, be copied, photocopied, translated, or reduced to any electronic medium or machine-readable form without prior consent, in writing, from Progress Software Corporation.

The information in this manual is subject to change without notice, and Progress Software Corporation assumes no responsibility for any errors that may appear in this document.

The references in this manual to specific platforms supported are subject to change. A (and design), Actional, Actional (and design), Affinities Server, Allegrix, Allegrix (and design), Apama, Business

Empowerment, ClientBuilder, ClientSoft, ClientSoft (and Design), Clientsoft.com, DataDirect (and design), DataDirect Connect, DataDirect Connect64, DataDirect Connect OLE DB, DataDirect Technologies, DataDirect XQuery, DataXtend, Dynamic Routing Architecture, EasyAsk, EdgeXtend, Empowerment Center, eXcelon, Fathom, IntelliStream, Neon, Neon New Era of Networks, O (and design), ObjectStore, OpenEdge, PDF, PeerDirect, Persistence, Persistence (and design), POSSENET, Powered by Progress, PowerTier, ProCare, Progress, Progress DataXtend, Progress Dynamics, Progress Business Empowerment, Progress Empowerment Center, Progress Empowerment Program, Progress Fast Track, Progress OpenEdge, Progress Profiles, Progress Results, Progress Software Developers Network, ProVision, PS Select, SequeLink, Shadow, ShadowDirect, Shadow Interface, Shadow Web Interface, ShadowWeb Server, Shadow TLS, SOAPStation, Sonic ESB, SonicMQ, Sonic Orchestration Server, Sonic Software (and design), SonicSynergy, SpeedScript, Stylus Studio, Technical Empowerment, Voice of Experience, WebSpeed, and Your Software, Our Technology-Experience the Connection are registered trademarks of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and/or other countries. AccelEvent, Apama Dashboard Studio, Apama Event Manager, Apama Event Modeler, Apama Event Store, AppsAlive, AppServer, ASPen, ASP-in-a-Box, BusinessEdge, Cache-Forward, DataDirect Spy, DataDirect SupportLink, DataDirect XML Converters, Future Proof, Ghost Agents, GVAC, Looking Glass, ObjectCache, ObjectStore Inspector, ObjectStore Performance Expert, Pantero, POSSE, ProDataSet, Progress ESP Event Manager, Progress ESP Event Modeler, Progress Event Engine, Progress RFID, PSE Pro, SectorAlliance, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, Sonic, Sonic Business Integration Suite, Sonic Process Manager, Sonic Collaboration Server, Sonic Continuous Availability Architecture, Sonic Database Service, Sonic Workbench, Sonic XML Server, The Brains Behind BAM, WebClient, and Who Makes Progress are trademarks or service marks of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and other countries.

IBM is a registered trademark of IBM Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Any other trademarks or service marks contained herein are the property of their respective owners.

DataDirect Shadow for ODBC includes: Software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http:/www.openssl.org/).

Software Foundation. All rights reserved. The names, "Ant", "Axis", "crossdb" "Xalan," "wsfx", "wsif" "poi," "Xalan", "Tomcat", "lucene", "Xerces" and/or "Apache Software Foundation" must not be used to endorse or promote products derived from the Product without prior written permission. Any product derived from the Product may not be called "Apache", nor may "Apache" appear in their name, without prior written permission. For written permission, please contact apache@apache.org.

Software developed by The Legion Of The Bouncy Castle (http://www.bouncycastle.org). Copyright © 2000 -2006. Software developed by The Cryptix Foundation Limited. Copyright © 1995-2005. All rights reserved. Software developed by The Hypersonic SQL Group. Copyright © 1995-2000. Software developed by Free Software Foundation, Inc. Copyright (C) 1991, 1999.

Chapter 1: Shadow z/Enterprise Web Server - An Overview . . . . . . . . . . . . . . . . . . 1-1

What is Shadow z/Enterprise Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Why Use It? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Shadow z/Enterprise Web Server Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Threading Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Product Capabilities and Benefits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Fast, Simple Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Easily Understandable (Native MVS Web Server) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

High Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

Comprehensive Management, Monitoring, and Control Capabilities . . . . . . . . . . . . . . . . . . 1-6

Extreme Scalability Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

Top-Notch Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

How Shadow z/Enterprise Web Server Is Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

Optional Shadow Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8

Executing IMS Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8

Comparison Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9

Executing CICS Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10

Chapter 2: Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

An Overview of the Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

How Shadow z/Enterprise Web Server Processes Transactions. . . . . . . . . . . . . . . . . . . . . . . . 2-1

When the URL Matches a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

When the URL Does Not Match a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

Using Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

Structure of a Rule (Event Procedure) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

Creating, Enabling, and Accessing a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

Creating the Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

Enabling the Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

Accessing the Rule Using a Web Browser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13

Deploying Shadow z/Enterprise Web Server at Your Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14

Setting Up the Mainframe Side. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14

Setting up the Client Side. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17

Chapter 3: The Shadow Event Facility (SEF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

What It Does . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

How It Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Event Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Event Procedure Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Event Procedure Rulesets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Naming Convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Shadow z/Enterprise Web Server Administration Guide iii

Start-up Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Event Procedure Data Set Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Enabling Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Enabling and Disabling Event Procedure Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Structure of an Event Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Event Procedure Header Statement (Required). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5

Process Section Header Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

Header-Only Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

SEF Event Procedure Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

WWW Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

REXX Dynamic Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7

Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7

GLVEVENT Temporary Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

Event Related Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

Event Procedure Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

Accessing SEF Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10

Controlling SEF from a Batch Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11

Return Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11

Chapter 4: Defining Event Procedure Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Different Event Procedure Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Authorization (ATH) Event Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

How ATH Event Procedures Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

ATH Event Procedure Criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

ATH Event Procedure Header Keywords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

ATH Event Procedure Process Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

ATH Event Procedure Return Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

ATH Event Procedure REXX Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

ATH Event Procedure Access Type Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7

Command (CMD) Rule Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8

How CMD Rule Event Procedures Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8

CMD Rule Event Procedure Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9

CMD Rule Event Procedure Criterion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9

CMD Rule Event Procedure Header Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10

CMD Rule Event Procedure Process Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10

CMD Rule Event Procedure Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10

Special Considerations for STOP Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

CMD Rule Event Procedure REXX Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

Exception (EXC) Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12

How EXC Event Procedures Work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12

EXC Event Procedure Criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12

EXC Event Procedure Header Keywords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13

EXC Event Procedure Process Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13

EXC Event Procedure Return Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13

EXC Event Procedure REXX Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14

Global Variable (GLV) Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

How GLV Event Procedures Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

GLV Event Procedure Criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

GLV Event Procedure Header Keywords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

GLV Event Procedure Process Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

iv Shadow z/Enterprise Web Server Administration Guide

GLV Event Procedure Return Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16

GLV Event Procedure REXX Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16

Time-of-Day (TOD) Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17

How TOD Event Procedures Work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17

TOD Event Procedure Criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17

TOD Event Procedure Header Keywords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19

TOD Event Procedure Process Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19

TOD Event Procedure Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19

TOD Event Procedure REXX Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19

Type (TYP) Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20

TYP Event Procedure Criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20

TYP Event Procedure Header Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

TYP Event Procedure Process Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

TYP Event Procedure Return Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

TYP Event Procedure REXX Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

WWW Event Procedure Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

What Are WWW Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

How WWW Rules Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

WWW Rule Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22

Syntax of WWW Rule Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24

WWW URL-to-Rule Matching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-31

WWW Rule Header Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-31

WWW Rule Process Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32

WWW Event-Related Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33

Chapter 5: Web Transaction Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

About Web Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Userid Prompting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Controlled Transaction Paradigm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Levels of Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

MVS Security Subsystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Client Authorization (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Effective Userid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5

Security Option Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

Distributed Transaction Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

The Master Ruleset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

Subordinate Rulesets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9

Security Attributes Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10

Security Processing Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11

Implementing Distributed Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

Specifying Web Transaction Security Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13

WWW Header Statement Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13

Configuring Secure Sockets Layer (SSL) Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14

WWW Header Security Parameters and Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15

AUTHREQ ( YES | NO | LOCK ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15

RUNAUTH( NONE | CLIENT | proxy-id ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16

RESOURCE (string ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17

SSL( NO | COND | YES | LOCK | LOCKCOND ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17

Shadow z/Enterprise Web Server Subsystem Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19

Setting Limits for the Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19

v Shadow z/Enterprise Web Server Administration Guide

Protecting Subsystem Command and Control Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . 5-21

Chapter 6: Writing Web Transactions in REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Shadow/REXX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

/*REXX Process Sections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

/*REXX Statement Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Coding the Process Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

Shadow/REXX Built-in Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

Chapter 7: File Serving Using the Shadow z/Enterprise Web Server . . . . . . . . . . . 7-1

UNIX File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

MVS File System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

Files Supported Directly by Shadow z/Enterprise Web Server. . . . . . . . . . . . . . . . . . . . . . . . . 7-2

File Sharing and Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

How Shadow z/Enterprise Web Server Handles Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3

Building File Serving WWW Rules Using FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3

Coding a FILE Process Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4

/*FILE Transaction Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4

/*FILE Statement Keyword Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5

Parsing URLs to Supply Missing FILE Keyword Values. . . . . . . . . . . . . . . . . . . . . . . . . . 7-10

Inline File Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13

Examples of /*FILE Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14

Chapter 8: HTML Extension Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

HTML Extension Facility Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Insert Variable Text Into the Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

HTTP Response Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Conditional Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Iteration Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2

Other Control Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2

Merging Data From Other Server Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2

Scope of the HTML Extension Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2

Text Format Data Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2

MIME Content Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3

HTML Extension Processing Enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3

Shadow z/Enterprise Web Server File Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3

Execution Time Efficiency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3

Limits on Various Syntactical Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3

Rules for Coding HTML Extension Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4

HTML Extension Statement Escape Delimiters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4

No Continuation of Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5

Single Statement Per Source Record (Except Text Insertions) . . . . . . . . . . . . . . . . . . . . . 8-6

Mixed Case Coding Allowed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6

Reserved Words Not Valid as Variable Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6

Using Statement Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6

Run-time Operand Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8

HTML Extension Text Insertion Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10

HTML Extension Run-time Condition Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11

IF Statement Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11

ELSE Statement Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12

vi Shadow z/Enterprise Web Server Administration Guide

ENDIF Statement Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12

Condition Statement Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12

HTML Extension Iteration Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13

Using Named Iteration Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13

DO Statement Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13

LEAVE Statement Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14

NEXT Statement Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14

ENDDO Statement Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15

Operation of Iterative Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15

Iterative Group Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16

Other HTML Extension Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17

DATE Statement Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17

TIME Statement Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17

EXIT Statement Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18

DB2 Result Set Cursor Advance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18

HTTP Response Control Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18

HTML Extension Merge Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19

Interface with /*EXECSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19

Special /*EXECSQL Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20

Chapter 9: Automated State Management Facility (ASMF) . . . . . . . . . . . . . . . . . . . 9-1

What is a Stateless Protocol?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

Persistent Session Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

What is ASMF?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2

Why Use ASMF? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2

What Constitutes State Information? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2

Transmitting State Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2

Server-Side State Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4

Using HTTP Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5

Using HTML Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6

Using State Information Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6

State Information Set Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7

State Information Set Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8

GLVSTATE Variable Inventory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8

Collection Control Variable Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10

Collection Status Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12

Using COOKIE-Type Information Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13

How Cookies Work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14

Creating a COOKIE-type Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15

The “Official” HTTP Cookie Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15

Possible Anomalies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15

Making HTTP Cookies Work Reliably . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16

Some Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16

Chapter 10: Executing User Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

/*PROGRAM Process Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

Executable Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

Where is CGI? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2

Location of Program Load Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2

Coding /*PROGRAM Process Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3

Shadow z/Enterprise Web Server Administration Guide vii

Using Other REXX Interpreters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4

Executing a Non-Shadow/REXX Interpreter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4

Run-Time Environments of Non-Shadow/REXX Interpreters. . . . . . . . . . . . . . . . . . . . . . 10-5

APIs for Non-Shadow/REXX Interpreters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5

Writing C/370 Web Transaction Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6

Writing COBOL Web Transaction Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6

Writing PL/I Web Transaction Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7

Chapter 11: Writing DB2-Based Web Applications . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

Shadow/REXXTOOLs DB2/SQL Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

/*EXECSQL Process Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

Operation of /*EXECSQL Sections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

Coding /*EXECSQL Process Sections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2

SQL Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5

/*EXECSQL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6

Chapter 12: Shadow AutoHTML for IMS/TM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1

AutoHTML Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1

Setting Up AutoHTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1

Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2

Setting Up Defaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2

Generating the Default Format Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3

Generating the Default HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5

Making the Formats Available to Shadow z/Enterprise Web Server . . . . . . . . . . . . . . . . 12-6

Enabling the Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7

Testing the Shadow Supplied IMS Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7

Generating Maps/HTML from Custom Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8

Generating the HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10

Making the Formats Available to Shadow z/Enterprise Web Server . . . . . . . . . . . . . . . 12-12

(Optional) Customizing the Rule(s). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-12

The /*EXECIMS Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13

(Optional) Customizing Your HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18

Editing the HTML File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18

Making the File Available to Shadow z/Enterprise Web Server . . . . . . . . . . . . . . . . . . . 12-18

Rule Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18

The IMS Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18

The KEYBOARD Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-19

The IMSINIT Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-21

The IMSENTRY Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-21

Chapter 13: Shadow AutoHTML for CICS/TS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1

An Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1

How it Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3

Installing the AutoHTML for CICS/TS Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3

Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3

Understanding the Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4

Getting Started Using BMS Source Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5

Step 1. Defining the Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5

Step 2. Creating the Customization Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10

viii Shadow z/Enterprise Web Server Administration Guide

Step 3. Connecting a BMS Mapset to Customization Orders. . . . . . . . . . . . . . . . . . . . . 13-20

Step 4. Generating HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-28

Step 5. (Optional) Generating HTML Template Load Modules . . . . . . . . . . . . . . . . . . . 13-29

Step 6. Refreshing HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-32

Getting Started Using Non-BMS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-33

Step 1. Defining the Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-34

Step 2. Creating the Customization Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-37

Step 3. Connecting a Transaction ID to Customization Orders . . . . . . . . . . . . . . . . . . . 13-47

Step 4. Generating HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-55

Step 5. Refreshing HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-58

Executing a CICS Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-59

The Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-59

The URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-59

The Web Browser Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-59

Chapter 14: Shadow Data Mapping Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1

How It Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1

Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2

Recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2

Data Mapping Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2

The ISPF Panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3

Map Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3

Map Extract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4

Map Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-7

Map Copy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10

Map Refresh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-11

Generate RPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-11

Map Merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-15

HTML Generation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-16

Using Data Maps in Client Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-17

Chapter 15: Using Shadow Interface for ADABAS . . . . . . . . . . . . . . . . . . . . . . . . . 15-1

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1

How It Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1

Obtaining Data from a Single ADABAS File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2

Merging Output in the Data Mapping Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2

Making the SQL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3

Executing the Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3

Using SDADEX and SDADDM to Obtain Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5

Using SDADEX to Extract ADABAS Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5

Using SDADDM to Import ADABAS Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-16

Using Table Definitions for SDADEX Output and SDADDM Input . . . . . . . . . . . . . . . . . 15-17

Using Table Joins to Obtain Data from Multiple ADABAS Files . . . . . . . . . . . . . . . . . . . . . . 15-20

Dynamically Building an ADABAS Data Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-22

Using Cursor Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-22

Identifying and Authenticating ADABAS Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-23

Losing Client Connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-23

Using Tracing to Identify Problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-23

Compatibility with Other Software AG Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-24

Shadow z/Enterprise Web Server Administration Guide ix

Chapter 16: Using the Shadow Interface for VSAM . . . . . . . . . . . . . . . . . . . . . . . . 16-1

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1

How It Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2

Obtaining Data from a VSAM File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2

Maintaining Output in the Shadow Data Mapping Facility . . . . . . . . . . . . . . . . . . . . . . . . 16-3

Making the SQL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3

Using the Shadow Data Mapping Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-5

Defining VSAM Data Set Maps to the Shadow Data Mapping Facility. . . . . . . . . . . . . . . 16-5

Designating the Alternate Indexes for a VSAM Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-7

Defining Multiple VSAM Logical Records Within the Same Physical File. . . . . . . . . . . . . . . . 16-8

Chapter 17: Using the OS/390 UNIX OpenEdition

Hierarchical File System (HFS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1

Setting up HFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1

OpenEdition and HFS Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2

OpenEdition Security Subsystem (RACF) Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2

Started-task Userid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2

Default Runtime Userid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-3

Server Start-up Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-3

OEHFS Parameter (Required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-3

HFSAUTHMODE Parameter (Required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-4

DOCUMENTROOT Parameter (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-4

SEFV31COMPATIBLE Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5

Ruleset Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5

HFSROOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5

HFSROOT vs. DOCUMENTROOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6

WWW Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6

URL Criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-7

PATH Keyword Operand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-7

WELCOMEPAGE Keyword Operand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-7

Displaying the Web Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-7

Appendix A: Trace Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Trace Browse Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Order of Trace Browse Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

The Trace Browse Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

Using the Specification Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

Using the PROFILE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7

Positioning Trace Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8

Changing Trace Browse Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9

Displaying Extra Columns of Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9

Trace Browse Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9

Using Labels in the MSGNO Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12

Locating Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13

Using the FIND Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14

Finding Character Strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14

Finding With DISPLAY Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-15

Row Information Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-17

Printing Trace Browse Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-17

x Shadow z/Enterprise Web Server Administration Guide

Appendix B: Trace Browse Archival Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

What It Is. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

How It Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

DIV Data Sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Event Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2

Trace Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2

Archival Facility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2

Message Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3

Configuring Automatic Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3

Using the Trace Browse Archival Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5

Appendix C: Starting a Test Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

Setting Up Shadow Server to Run under TSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

Test Copies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

Using the Debugging Control Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

Using the Code/370 Debug Tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2

Appendix D: Server Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1

Appendix E: Supported SMF Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1

Units of Time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1

SMF Type 05 Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1

SMF Type 06 Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3

Appendix F: Language Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-1

Appendix G: Processing Web Transactions and URLs . . . . . . . . . . . . . . . . . . . . . . G-1

Uniform Resource Locators (URL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-1

How the Web Server Handles URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-2

Handling Inbound Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-2

Supported URL Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-2

Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-3

Special Characters and URL Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-3

Rescanning to a New URL Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-4

Rescan Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-4

Error Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-4

FLUSH Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-4

Shadow/REXX Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-4

Other WWW Transaction Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-5

Recovery From Server Detecte d Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-5

Transaction Level Recovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-6

A Word About HyperText Transfer Protocol (HTTP). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-7

TCP/IP Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-8

Application Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-8

Transport Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-8

Internet Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-10

Network Interface Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-10

Appendix H: Transaction Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . H-1

Shadow z/Enterprise Web Server Administration Guide xi

xii Shadow z/Enterprise Web Server Administration Guide

About this Publication

This book contains user information about the Shadow z/Enterprise Web Server™. This guide expands on the concepts and information presented in the Shadow z/Enterprise Web Server Getting Started Guide. If you do not find the information in this manual, refer to the Getting Star ted Guide or one of the publications in the related set of manuals.

How this Publication is Organized

This book contains the following chapters:

 Chapter 1, “Shadow z/Enterprise Web Server - An Overview,” provides an introduction

to Shadow z/Enterprise Web Server by reviewing information covered in the Shadow z/Enterprise Web Server Getting S tarted Guide and covering additional info rmation on

re-scanning to a new URL, error recovery, flush requests, and more in-depth information on HTTP and TCP/IP.

 Ch ap te r 2, “Qu ick Start,” provides a summary about Shadow z/Enterprise Web

Server’s event based architecture that matches incoming URLs to predefined event procedures or rules.

 Chapter 3, “The Shadow Event Facility (SEF),” covers the structure of an event

procedure (header statements an d process sections), the different types of variables, and how to control SEF from a batch environment.

 Chapter 4, “Defining Event Procedure Types,” covers the different event procedures

types, what they do, how they work, and the valid syntax for each.

 Chapter 5, “Web Transaction Security,” covers security parameters and subsyste m

security.

 Chapter 6, “Writing Web Transactions in REXX,” covers the syntax for coding /*REXX

process sections.

 Chapter 7, “File Serving Using the Shadow z/Enterprise Web Server,” discusses

supported files, how Shadow z/Enterprise Web Server han dles files, and how to build WWW rules using /*FILE.

 Chapter 8, “HTML Extension Facility,” covers the rules for coding HTML extension

statements, run-time condition checking, iteration statements, and merge processing.

 Chapter 9, “Automated State Management Facility (ASMF),” covers state information,

which provides the ability to “remember” information at the end of a client/server interaction if the information has some bearing on a future anticipated interaction.

 Chapter 10, “Executing User Programs,” describes the basics of the /*PROGRAM

process section, such as what programs can be executed, where they must reside, and how to code the process section; discusses the use of other REXX interpreters; and covers instructions related to writing transaction programs in C/370, COBOL, and PL/I.

 Chapter 11, “Writing DB2-Based Web Applications,” covers the operation and coding

of the /*EXECSQL process section. It also covers SQL statements for the /*EXECSQL

Shadow z/Enterprise Web Server Administration Guide xiii

section. The Shadow/REXXTOOLs DB2/SQL interface is discussed in the HTML online documentation and the Shadow z/Enterprise Web Server Programming Reference Guide.

 Chapter 12, “Shadow AutoHTML for IMS/TM,” discusses how to use the Shadow

AutoHTML™ for IMS/TM feature. This chapter includes a discussion of how to format the /*EXECIMS section. The Shadow z/Enterprise Web Server Installation Guide covers how to configure the system so you can use Shadow AutoHTML.

 Chapter 13, “Shadow AutoHTML for CICS/TS,” discusses how to use the Shadow

AutoHTML™ for CICS/TS feature. This chapter details the installation and configuration required, the administration of the Shadow AutoHTML for CICS/TS feature, and the steps required to execute a CICS transaction.

 Chapter 14, “Shadow Data Mapping Facility,” discusses the data mapping facility,

including how it works, what it does, and its various related ISPF pane ls.

 Chapter 15, “Using Shadow Interface for ADABAS,” covers the new add-on

component to Shadow z/Enterprise Web Server that provides reliable, high performance access to ADABAS data from the desktop.

 Ch ap te r 16 , “Us ing the Shadow Interface for VSAM,” covers the new add-on

component to Shadow z/Enterprise Web Server that provides reliable, high performance access to VSAM data.

 Chapter 17, “Using the OS/390 UNIX OpenEdition Hierarchical File System (HFS),”

covers support for the OS/390 UNIX System Services Hierarchical File System (HFS).

 Appendix A, “Trace Browse,” covers the different features of the Trace Browse

Facility, such as how it works, changing columns (or displaying extra columns), and locating messages.

 Appendix B, “Trace Browse Archival Facility,” discusses the basics of the Trace

Browse Archival Facility, how it works, handling backups and extracts, and configuring automatic backups.

 Appendix C, “Starting a Test Version,” covers using the debugging control screen,

setting up the server to run under TSO, and using the code/370 debug tool.

 Appendix D, “Server Error Codes,” lists the different server error codes and their

descriptions.

 Appendix E, “Supported SMF Fields,” explains the records that are written by Shadow

z/Enterprise Web Server whenever a URL is executed (Offset, Field Name, Field Type/Value, and Description ).

 Ap pe nd ix F, “Language Codes,” lists the country codes and the language.  Appendix G, “Processing Web Transactions and URLs,” includes information on

Internet protocols, application layer protocols, the client/server roles in HTTP, what is a URL, how the Web server handle URLs, what happens when a match is made to an inbound request, and when and why a rescans to a new URL occurs.

 Ap pe nd ix H, “Transaction Status Codes,” provides a list of internal Shadow

transaction status codes.

xiv Shadow z/Enterprise Web Server Administration Guide

Shadow Products and Publications

For a comprehensive list of the current Shadow product, visit the following website:

http://www.datadirect.com/solutions/mai nframes/index.ssp

You can access and download all of the current Shadow publications by navigating within this website to the following location:

http://www.datadirect.com/products/shad ow/documentation/ index.ssp

xv Shadow z/Enterprise Web Server Administration Guide

Working with Shadow Support

Shadow Support provides a number of ways for you to obtain assist ance fo r our product s. All product support inquiries are handled by the same support group, regardless if you are a trial or a licensed customer. The following are available support options:

Support Option

E-mail To contact Shadow Support via

How to Access How it Works This Option is Best for:

e-mail, please use the following link:

shadowsupport@datadirect. com

E-mail is available for receipt 24 hours a day, 7 days a week and is answered between 9AM-7PM CST Monday through Friday.

Phone To contact Shadow Support,

please visit the following Web site and select the “Phone” link:

http:// www.datadirect.com/ support/contactus/phone/ index.ssp

Internet To access Internet Shadow

Support, please visit the following Web site:

http:// www.datadirect.com/ support/index.ssp

E-mail goes to the support queue, which is continuously monitored by a staff of crossfunctional technical experts. It is answered in the order it is received. It is logged in the support database and assigned a trouble ticket number for tracking purposes.

During normal working hours you will be transferred to a technical expert within the Customer Support group. Y ou may be required to page a support person via our phone mail system after hours.

The DataDirect Technologies Website is maintained to provide current, relevant materials to support our customers. Links to a searchable Knowledge Base and various technical tips are available from the DataDirect Technologies Website. In addition, software updates and product documentation can be downloaded from the Web site. The DataDirect Technologies Website also allows you to track open support incidents.

This type of support is excellent for low to medium priority requests. It is a proven method for providing further information on critical problems that may have been phoned in. E-mail is a convenient way of sending us a list of lower priority items you have collected at a time that is convenient for you.

This type of support is best for high priority requests and initial installation questions. Use this option for any obvious system errors or anytime you need the most rapid reply to your question.

This option provides immediate access to documentation, updated client-side Drivers, and our product Knowledge Base. The Knowledge Base is a collection of questions answered by Customer Support. Use this option to answer your own questions or to get a better understanding of what customers ask on an ongoing basis.

Account Manager

To contact your Sales Representative (U.S.),please visit the following Web site and select the “Phone” link:

http:// www.datadirect.com/

Your Sales Representative is your account manager. This person is ultimately responsible for your complete satisfaction with the Shadow product.

support/contactus/phone/ index.ssp

xvi Shadow z/Enterprise Web Server Administration Guide

Contact your Sales Representative for pricing information, contract details, password renewal, or if you feel your needs are not being met.

CHAPTER 1:

Shadow z/Enterprise Web Server - An Overview

The Shadow z/Enterprise Web Server allows you to unite the power of the Internet with the rich resources of legacy System 390/MVS applications and data to fully exploit the growing revolution in eBusiness. Topics include:

What is Shadow z/Enterprise Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Why Use It? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Shadow z/Enterprise Web Server Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Threading Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Product Capabilities and Benefits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Fast, Simple Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Easily Understandable (Native MVS Web Server) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

High Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

Comprehensive Management, Monitoring, and Control Capabilities . . . . . . . . . . . . . 1-6

Extreme Scalability Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

Top-Notch Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

How Shadow z/Enterprise Web Server Is Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

Optional Shadow Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8

Executing IMS Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8

Comparison Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9

Executing CICS Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10

What is Shadow z/Enterprise Web Server

Shadow z/Enterprise Web Server is a native MVS Web server that provides controlled access to MVS data and applications using a Web browser, such as Netscape Navigator™ or Internet Explorer™. It does not require an intermediate server, nor is it limited to simple file transfers or screen scraping. Shadow z/Enterprise Web Server is an MVS transaction processor product designed specifically to connect MVS resident resources to the World Wide Web (WWW).

How It Works

Shadow z/Enterprise Web Server is an OS/390-based product that is installed and initiated as a started task within OS/390. Once installed, Shadow z/Enterprise Web Server “listens” for Web client sessions (URLs), inbound from the Internet or an intranet. Each inbound session is assigned to a thread, an individu al un it of work in OS/ 39 0 that is used for authorization, data access, transaction access, monitoring, and control.

The URLs from the client are matched against pre-defined rules, or event procedures, established within Shadow z/Enterprise Web Server to enforce a controlled-transaction paradigm. Because Shadow z/Enterprise Web Server can access all standard

Shadow z/Enterprise Web Server Administration Guide 1-1

Shadow z/Enterprise Web Server - An Overview

OS/390 functions, rules ensure that only pre-approved actions can be taken by users. Rules process the URLs and return HTML or binary data via HTTP to the client.

Why Use It?

eCommerce began with a scattering of consumer-oriented Web-based retail sites. But innovation and the redesign of business models has take n e Comme rce beyon d its simple beginnings to create a new definition of what it means to exploit the powers of the Internet or intranet. The Web is changing the way the world does business. For those who can exploit it creatively, the rewards can be enormous:

 In cr ea se d pr odu c tivit y  Reduced expenses  Increased efficiency of business processes  Strategic advantage over competitors

Shadow z/Enterprise Web Server Architecture

Shadow z/Enterprise Web Server uses a simple two-tier architecture that provides direct Web-to-mainframe access, thus eliminating the need for mid-tier Web servers. The result is a comprehensive access environment for integrating System/390 and the Internet. By eliminating the need for gateways:

 Production is enhanced.  Learning curves are lowered.  There are no performance bottlenecks.  It uses maximum throughput and fast response time, regardle ss of th e nu m be r of

users.

 There is higher availability of data.  There is no gateway to purchase, install, or maintain.  There are no additional components to fail.  The IT investment in legacy systems is preserved.

How It Works

A key component of the Shadow event-based architecture is the concept of an event procedure, or rule. Rules are site-defined actions to be taken by Shadow z/Enterprise Web Server in response to inbound URLs. Once a rule is defined using the Shadow Event Facility™ (SEF) component, it may be made immediately available for execution.

Rules, typically defined by a designated Webmaster, can perform a variety of processing roles, such as:

 Ru n a SQL statemen t.  Execute CICS programs, IMS transactions, or TSO/E command procedures.  Transmit authorized OS/390 files to the client.  Execute customized REXX-language scripting procedures.  Execute customer-written programs in COBOL, PL/I, or C.  Execute powerful built-in facilities that provide turnkey access to data files or existing

OS/390 applications.

Figure 1–1 illustrates the basic architecture of Shadow z/Enterprise Web Server.

1-2 Shadow z/Enterprise Web Server Administration Guide

Shadow z/Enterprise Web Server Architecture

Figure 1–1. The Basic Architecture for Shadow z/Enterprise Web Server

Accessing Rules Using URLs

Web browsers use URLs (Uniform Request Locators) to access Web resources. The following is a URL:

http://www.neonsys.com:80/NEON /SAMPDATA/htxother .htm

The first portion of the URL identifies the TCP/IP address of the OS/390 system and the port assigned to Shadow z/Enterprise Web Server. When an HTTP (Hypertext Transfer Protocol) request arrives, the second part of the URL is passed to Shadow z/Enterprise Web Server, which compares the URL to a list of pre-defined rules, or event procedures, created in the Shadow Event Facility (SEF). Table 1–1 shows how Shadow z/Enterprise Web Server handles URLs.

Table 1–1. How Shadow z/Enterprise Web Server (SWS) Handles URLs

Discarded once it arrives at the port SWS matches this to a rule (event procedure)

http://www.neonsys.com:80 /NEON/SAMPDATA/htxother.htm

When a match is found, Shadow z/Enterprise Web Server executes the associated event and the results are returned from the OS/390 system to Shadow z/Ente rprise Web Server, which converts the information into an HTML data stream before sending the results back to the client. Relational tables may be formatted as HTML tables. Additionally, Shadow z/ Enterprise Web Server supports all standard MIME (Multimedia Internet Mail Extension) file types for transfer to the client.

Shadow z/Enterprise Web Server Administration Guide 1-3

Shadow z/Enterprise Web Server - An Overview

Distributed Transaction Administration

To facilitate administration and to prevent accidental or malicious misuse of security related parameters, Shadow z/Enterprise Web Server provides both a master list of event procedures and the ability to create subordinate lists. This allows diverse groups to still have responsibility for writing and maintaining Web transactions definitions, which can be grouped by application, user community, resou rce requirements, or by any breakdown that offers administrative convenience.

Controlled Transaction Paradigm

Shadow z/Enterprise Web Server provides another point of control. This is known as the controlled transaction paradigm and ensures that only desired access is provided to users. Execution privileges may be granted at the event level, DBMS level, OS/390 level, or transaction level.

Threading Architecture

Inside the Shadow z/Enterprise Web Server address space, there are two dedicated listener threads (TCBs) for communication processing. One thread handles IBM TCP/IP; the other handles Interlink TCP/IP. These threads are responsible for all inbound session requests.

Inbound session requests are handled by binding a socket to a well-known port number and then establishing a listen queue. The TCP/IP communication thread then issues an accept for each inbound session request. A unique child thread (attachment TCB) is created for every inbound session request and is dedicated to the sessio n an d kept for as long as the session is active.

There are several reasons for this architectural decision:

 Minimize CPU overhead  Offer parallel processing  Maximize scalability  Use existing security  Offer isolation  Simplify accounting  Improve manageability

CPU overhead

The overhead of thread creation, user authentication, transaction program initiation, and database thread allocation is incurred only once . After all the initialization steps have been completed, a direct path is available for passing database requests from the client application directly to the host database. This approach is now recommended by IBM as the most efficient way of communicating with DB2, enhancing both capacity an d response time.

Parallel processing

The creation of a dedicated thread for each client application allows Shadow z/Enterprise Web Server to exploit the multiprocessing and multiprogramming capabilities of IBM mainframes and OS/390. Over a period of many years, IBM has steadily expanded the

1-4 Shadow z/Enterprise Web Server Administration Guide

Product Capabilities and Benefits

multiprocessing capabilities of its hardware and the multiprogramming facilities of its software. These capabilities can be exploited only by products that create multiple units of dispatchability (TCBs or SRBs).

Scalability

The dedicated thread approach provides the highest degree of scalability for the client/ server computing environment. Because Shadow z/Enterprise Web Server creates threads for all client sessions, rather than using the services of CICS or IMS, it avoids scalability issues inherent in those subsystems. The only limits are those physical constraints imposed by OS/390 or the subsystem itself (i.e., DB2 thread limits).

Security

Shadow z/Enterprise Web Server creates an ACEE control block for each client support thread. This ACEE is initialized with the current userid provided by Shadow z/Enterprise Web Server on behalf of the client. This approach ensures that all client actions ha ve been authenticated by the existing security system.

Isolation

Multiple threads may be active concurrently without affecting each other. In addition, both OS/390 and DB2 provide task-level resource cleanup. This mean s that if a thre ad fails, a ll related OS/390 and DB2 resources are released automatically and any da tabase changes are rolled back automatically without affecting other threads.

Accounting

OS/390 tracks resource utilization by threads. Because one and only one thread is responsible for all work done on behalf of the client, the dedicated server thread is charged for all of the resources used by the client. Shadow z/Enterprise Web Server creates standard SMF records that detail usage by subsystem and user connection.

Manageability

Threads are the smallest unit of dispatchability and control in the OS/390 environment. Threads are also the fundamental unit of DB2 connectivity. Shadow z/Enterprise Web Server exploits its dedicated threads to implement several automated and manual controls. These controls include a CPU throttling facility and a thread cancellation mechanism.

Product Capabilities and Benefits

Shadow z/Enterprise Web Server provides direct Web access to MVS with several capabilities and benefits.

Fast, Simple Implementation

Implementation of Shadow z/Enterprise Web Server is quick and easy. No intermediate server is required, and programming requirements on the host are kept to a minimum through the use of supplied functions and capabilities. Existing programs and transactions

Shadow z/Enterprise Web Server Administration Guide 1-5

Shadow z/Enterprise Web Server - An Overview

can be executed, often with no changes to the transaction code. IT departments can take advantage of browser or “thin client” application development and leverage the lower cost of application development and maintenance with high quality OS/390 data and business access logic.

Easily Understandable (Native MVS Web Server)

Shadow z/Enterprise Web Server is a native MVS Web server. It is not UNIX-based, nor is it derived from early UNIX Web server source code implementations. Sh adow z/Enterprise Web Server was designed on MVS for MVS. This means your systems programmers do not need to spend hours researching unfamiliar system configuration options or adding new and unfamiliar security control paradigms to your configuration. Users, developers, and security administrators already know which security limits are imposed and how they are configured and administered.

High Performance

Shadow z/Enterprise Web Server was built with high performance as a key consideration in all aspects of product development. The performance characteristics of Shadow z/ Enterprise Web Server are maintained whether a few or tens-of-thousands of users are using the software. This is possible because there are no built-in bottlenecks, such as mid-tier Web servers, or other architectural limitations.

Comprehensive Management, Monitoring, and Control Capabilities

To ensure speedy development, you need rapid access to detailed diagnostics. Shadow z/Enterprise Web Server provides a detailed monitoring and trace facility for end-to-end diagnostics and rapid resolution of development problems and a diagnostic facility. Together, the Shadow z/Enterprise Web Server product’s trace and the Shadow Diagnostic Facility provide the most complete, powerful, and flexible set of administration tools available in the OS/390 middleware arena.

The Trace Facility

Shadow z/Enterprise Web Server incorporates an extensive trace facility that is implemented by adding trace records to a trace buffer maintaine d in virtual storage . Trace operations are performed entirely with memory-to-memory instructions, and nothing is written to disk until the session is complete, at which point the trace information is automatically saved on disk. This approach combines the performance advantages of memory-to-memory tracing with the non-volatility of standard disk storage.

Trace records are created for a wide variety of events in the Shadow z/Enterprise Web Server address space. Specifically, trace records are written for SQL operations, IMS calls, CICS calls, communication events (LU 6.2, TCP/IP, and messages), thread attach and detach events, RPC events, message events, and errors (abends). It is even possible for an RPC to add its own trace messages to trace records for diagnostic purposes.

The Shadow Diagnostic Facility

The Shadow Diagnostic Facility (SDF), an ISPF application shipped with Shadow z/ Enterprise Web Server, provides an interface to the controls and diagnostics. Using this facility, administrators can reset controls, view, filter, and search the trace data, and

1-6 Shadow z/Enterprise Web Server Administration Guide

display all currently active users. This display can also be used to reconstruct the session of any currently active user or, with authorization, to terminate any active session.

The Shadow Diagnostic Facility includes a security mechanism that allows you to restrict what each user can do with SDF.

Extreme Scalability Capabilities

Shadow z/Enterprise Web Server offers extreme scalability, whether users number in the hundreds or hundreds-of-thousands by providing unparalleled ability to maintain response times within pre-established services levels as numbers of users grow. End-to-end multithreaded capabilities exploit all available hardware and operating system facilities for processing on the client and server components.

Extreme scalability ensures that applications will perform as designed both today and in the future, adapting easily to volume increases and new technologies that accompany internal and external corporate change. Multiple address space load balancing, workload management, and dynamic thread pooling enable high volume user access. The result is that you can leverage single-platform applications, participate in e-business opportunities, engage in personalized marketing, and provide a global workgroup environment quickly and easily.

How Shadow z/Enterprise Web Server Is Used

Top-Notch Security

Shadow z/Enterprise Web Server supports a full range of System/390 security systems, such as RACF, ACF2, and Top Secret, to validate userids and passwords p rovided e ither directly by the user or via LAN authentication mechanisms. The ability to use existing security is of paramount importance in protecting OS/390-MVS assets and ensuring rapid application development. Shadow z/Enterprise Web Server supports the highest client/ server security standard in practical use today: Secure Socket Layer (SSL). The support of SSL and GSK SSL meets the most demanding security needs in the industry.

How Shadow z/Enterprise Web Server Is Used

Shadow z/Enterprise Web Server is being used in a growing number of enterprises around the globe to bring the resources and power o f the main fram e to Web applications.

 A worldwide shipping firm uses Shadow z/Enterprise Web Server to allow employees

to access its OS/390 applications and data from any port that has a telephone line.

 A major university allows students to retrieve curriculum and grade infor mation and to

 One of Europe’s largest insurance companies uses Shadow z/Enterprise Web Server

for intranet applications and external investment management programs.

 One of the world’s largest aircraft manufacturers uses Shadow z/Enterprise Web

Server to browser-enable its employee time-keeping system.

Whenever production Web applications for OS/390 are required with a need for minimal development time and maximum security, companies are finding the most efficient and cost-effective solution to be Shadow z/Enterprise Web Server.

Shadow z/Enterprise Web Server Administration Guide 1-7

Shadow z/Enterprise Web Server - An Overview

Connection

3270 Terminal

VTAM

IMS MPP

Optional Shadow Interfaces

The optional Shadow Interface™ components for DB2, IMS/DB, IMS/TM, CICS/TS, VSAM, ADABAS, and Natural simplify, speed, and streamline your access to OS/390 resources. In most cases, the Shadow Interfaces provide a method to execute legacy programs from Web browsers without any modification to the host code. Existing OS/390based applications can be executed, returning data in HTML format. This functionality allows you to reuse existing business and access logic that is at the heart of many production applications today.

Shadow Interfaces eliminate the need for coding remote procedure calls (RPCs) on the host and, when used with the Data Mapping Facility (DMF), display the results in the format you designate, without the need to sort or parse returned data. With Shadow Interfaces, you gain the speed and simplicity of a desktop tool, cut development time significantly, increase productivity, and reduce time to market for applications.

Shadow z/Enterprise Web Server can be used with interfaces for:

 DB2, IMS/DB, and ADABAS databases  IMS and CICS transactions  VSAM data  Natural programs  Sequential files and PDSs  RPC stored procedures for data sources such as:

− IDMS

− Oracle for the System/390

− CA Datacom

− CA Sapphire

− Total

− M204

Executing IMS Transactions

Shadow z/Enterprise Web Server provides access to IMS transactions across the Internet using Web browsers.

Figure 1–2. Executing an IMS Transaction on a 3270 Terminal

The Figure 1–2 shows IMS on a 3270 Terminal while Figure 1–3 shows the same transaction using a Web browser and Shadow z/Enterprise Web Server.

1-8 Shadow z/Enterprise Web Server Administration Guide

Executing IMS Transactions

TCP/IP

Web Browser

SWS

IMS

Figure 1–3. Executing an IMS Transaction Using the Shadow z/Enterprise Web Server

You can use an (optional) interface, such as a program (Shadow/REXX, COBOL, PL/1, C, C++ or Assembler) or a non-program interface (Data Mapping or RPC) to retrieve the information.

Comparison Table

Table 1.

3270 Terminal Web browser

1. The form is filled-in on screen. Press the appropriate key to transmit.

2. 3270 screen loads data into the buffer and passes it to the connection using LU2 protocol. The information is then passed onto VTAM.

3. VTAM passes data to IMS. 3. TCP/IP passes messages to SWS.

4. IMS identifies the transaction code from the message and schedules the appropriate message processing program (MPP).

5. MPP receives the message from IMS and processes the transaction.

6. MPP passes the results back to IMS. 6. SWS passes the results to TCP/IP.

7. IMS passes the message to VTAM , which passes it back to terminal via connection using LU2 protocol.

8. Results are displayed on the screen. 8. Results are displayed on the screen.

1. The form is filled-in on screen. Press Enter to transmit.

2. Web browser puts data into a string (URL) and passes it to TCP/IP using HTTP.

4. SWS strips the destination information and matches the remaining value against a sitedefined WWW rule (event procedure). The transaction is scheduled for processing.

5. The event procedure is processed.

7. TCP/IP passes the information back to the PC using HTTP protocol.

Once Shadow z/Enterprise Web Server is installed, the only setup task is to define an event procedure for each IMS transaction invoked through the Shadow z/Enterprise Web Server.

Shadow z/Enterprise Web Server Administration Guide 1-9

Shadow z/Enterprise Web Server - An Overview

EXCI

Web Browser

SWS

CICS

Pro-

gram

TCP/IP

AutoHTML

Shadow z/Enterprise Web Server provides a feature known as Shadow AutoHTML™, which generates a base level of HTML for rapid deployment of a first generation Web application. The base HTML can be modified to further enhance the application by using standard point and click Web development tools.

Executing CICS Transactions

Shadow z/Enterprise Web Server provides access to CICS transactions across the Internet using Web browsers. without involving any modifications to the CICS code. This means existing CICS programs can be executed and data returned in easily form atted HTML.

From one URL, many existing physical CICS programs can be accessed to create one new “logical” view of the data.

For CICS access, Shadow z/Enterprise Web Server uses technology known as the Transaction Server for CICS, which connects to CICS via an EXCI (External CICS Interface).

Summary

Shadow z/Enterprise Web Server is the product of choice for uniting the power of the Internet with the rich resources of legacy System 390/MVS applications and data to fully support IT initiatives in e-commerce and e-engineering. With Shadow z/Enterprise Web Server, you’re assured of the scalability, security, performance, reliability, and control to confidently combine the Internet and OS/390 data and applications.

Many enterprises use Shadow z/Enterprise Web Server to:

 Web-enable mainframe applications without custom coding  Support e-initiatives by enabling global information-sharing without a gateway  Leverage existing production infrastructures and in-house System/390 expertise  Speed time to market by installing in less than one day, without on-site assistance or

interruption of operations

Figure 1–4. Executing a CICS Transaction

1-10 Shadow z/Enterprise Web Server Administration Guide

Summary

 Combine mainframe performance, reliability, security, and control while exploiting the

cost-effectiveness and eBusiness opportunities of the Internet

 Provide automatic generation of HTML for CICS and IMS transactions  Accommodate up to hundreds of thousands of users with no performance degradation

or downtime

 Eliminate the need for gateway hardware, software or application coding  Keep data on System/390 with no migration or loss of data integrity  In co rp or at e ce nt ra lize d, fully inte ra ctiv e on lin e mo nit or ing , co nt ro l, and dia gnos tics

capabilities

 Speed and simplify development of new and composite applications

Shadow z/Enterprise Web Server Administration Guide 1-1 1

Shadow z/Enterprise Web Server - An Overview

1-12 Shadow z/Enterprise Web Server Administration Guide

CHAPTER 2:

Quick Start

A key component of the Shadow z/Enterprise Web Server is its even t based architecture that matches incoming URLs to predefined event procedures or rules. These rules are site -defined actions that allow you to perform a variety of processing roles. Topics include:

An Overview of the Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

How Shadow z/Enterprise Web Server Processes Transactions. . . . . . . . . . . . . . . . . . . 2-1

When the URL Matches a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

When the URL Does Not Match a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

Using Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

Structure of a Rule (Event Procedure) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

Creating, Enabling, and Accessing a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

Creating the Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

Enabling the Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

Accessing the Rule Using a Web Browser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13

Deploying Shadow z/Enterprise Web Server at Your Site . . . . . . . . . . . . . . . . . . . . . . . 2-14

Setting Up the Mainframe Side. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14

Setting up the Client Side. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17

An Overview of the Process

Before the information/procedure can be accessed on the mainframe, a “rule” must be created and enabled on the mainframe. To access the rule from the PC, use your Web browser and send the appropriate URL.

Rule

(Event Procedure) A rule is a member within an MVS PDS data set that contains executable procedures.

URL

This is the acronym for Uniform Resource Locator. URLs:

 Identify the Internet service protocol, such as HTTP or FTP  Specify the location of a file on the World Wide Web, network, or hard drive

Shadow z/Enterprise Web Server uses URLs to access rules. The following is a URL:

http://www.neonsys.com/NEON/SAM PDATA/htxother.htm

How Shadow z/Enterprise Web Server Processes Transactions

Unlike other Web servers, Shadow z/Enterprise Web Server does not attempt to match the URL to an MVS file system entity. Instead, it looks up the URL value in a list of WWW rule event procedure definitions.

Shadow z/Enterprise Web Server Administration Guide 2-1

Quick Start

Executes

WWW Rule

Event

Matches

SWS

Client (Web Browser)

1,2

6,7

Tip: Naming Data Sets

Name the members in the data sets to correspond to the URL. That way, you can easily find the rule to edit.

For example, “/NEON/SAMPDATA/htxother.htm” would be stored in the SAMPDATA file with HTXOTHER as one of the members.

Shadow z/Enterprise Web Server processes the URL

http://www.neonsys.com/NEON/SA MPDATA/htxother.ht m

as shown in Table 2–1.

Table 2–1. How Shadow z/Enterprise Web Server (SWS) Handles URLs

Discarded once it arrives at the port SWS matches this to a rule (event procedure)

http://www.neonsys.com / NEON/SAMPDATA/htxot her.htm

When the URL Matches a Rule

Figure 2–1 shows what happens when the URL finds a matching rule.

Figure 2–1. Finding a match on an inbound request

1. The client uses a Web browser and sends the URL to Shadow z/Enterprise Web Server.

2. Shadow z/Enterprise Web Server stores the inbound input URL ( then creates the current URL by stripping the destination information (address).

3. It uses the current URL (stored in the against the event procedure rule.

WWW.INPUTURL),

WWW.CURRENTURL) as the criteria to match

2-2 Shadow z/Enterprise Web Server Administration Guide

4. When the match is made, the rule is executed. (This process is discussed in detail later.) The results can be buffered before being sent back to Shadow z/Enterprise Web Server.

5. Shadow z/Enterprise Web Server receives the results and creates the HTTP header.

6. Shadow z/Enterprise Web Server sends this information to the client without altering the information.

7. The client displays the information.

SWS

Client (Web Browser)

1,2

9,10

Match

Event

Matches

Re-scan

Executes

WWW Rule

When the URL Does Not Match a Rule

Figure 2–2 shows what happens when the URL does not match a rule.

Figure 2–2. Re-scanning to a new URL

Using Rules

1. The client uses a Web browser and sends the URL to Shadow z/Enterprise Web Server.

2. Shadow z/Enterprise Web Server stores the inbound input URL ( then creates the current URL by stripping the destination information (address).

3. It uses the current URL as the criteria to match against the event procedure rule, but no match is found.

4. This information is sent back to Shadow z/Enterprise Web Server for processing.

5. Shadow z/Enterprise Web Server issues an internal re-scan request, which overwrites the current URL.

6. The server redirects the client request to the newly created current URL. The new URL is treated as though it were the original URL sent by the client. (Many error recovery processes are generated internally by a re-scan.)

7. After a match is made to an event procedure rule, the rule is then executed.

8. Shadow z/Enterprise Web Server receives the results and creates the HTTP header.

9. Shadow z/Enterprise Web Server sends this information to the client without altering the information.

10. The client displays the information.

WWW.INPUTURL),

Using Rules

Rules give added security by allowing you to “control transactions.” Once the URL matches a rule, only those actions explicitly def ine d in the ru le ar e pe rf or m ed . This

Shadow z/Enterprise Web Server Administration Guide 2-3

Quick Start

includes data files and programs available to Web clients and under what conditions and authorization each transaction is processed.

Structure of a Rule (Event Procedure)

The following is a WWW rule:

/*WWW /NEON/HTMLFILE/* AUTHREQ (NO) /*FILE DATATYPE(PDS) DDNAME(HTMFILE ) CONTENTTYPE(text/html)FORMAT(text)

The WWW event procedure can contain:

 Header-only rules (no process section). The following is an example of a header-

only rule:

/*WWW /NEON/HTMLFILE/* AUTHREQ (NO)

Note:

Header-only rules are only allowed for WWW rules. They are used to specify generic processing attributes for the transaction process.

 Process section headers. This includes /*REXX, /*FILE, and

/*PROGRAM). Using the above rule example, the fo llowing is the process section header statement:

/*FILE DATATYPE(PDS) DDNAME(HTMFILE )

Note:

Not all process sections need data contents.

 Process section contents. Using the above rule example, the following is the

process section data statement.

CONTENTTYPE(text/html)FORMAT(text)

Header Statements (Required)

The “/*WWW” header statement tells the Shadow z/Enterprise Web Server application which inbound URL to use to process this rule, the authorization required, and whether to generate a trace.

The header statement must:

 Be the first statement within the PDS member. If the first statement is not valid, then

the PDS member cannot be enabled nor proc es sed .

 Begin in the first input column (discounting record numbering) of the first record within

the event procedure member. If a valid header statement is not present, the PDS member cannot be enabled as an event procedure.

2-4 Shadow z/Enterprise Web Server Administration Guide

SYNTAX FOR HEADER STATEMENTS

Use the following format to create header statements:

/*WWW criterion ( keyword ( ke yword... ) cont )* /

Where:

criterion

Specifies the path rule. For example, “ length for a WWW URL criterion value is 128 bytes.

keyword (optional)

Defines properties of the rule and the attributes to be used in processing the event. Keywords are used to specify security attributes. For example, “

AUTHREQ(NO)”.

cont (optional)

Designates a continuation character when the information continues on the next line.

 “-” strips trailing blanks from the end of the continued line and from the

beginning of the continuation line.

/NEON/HTMLFILE/*”. The maximum

Using Rules

 “+” interprets the string literally (blanks are not stripped).

*/ (optional)

Indicates the closing delimiter (“

*/”). If you add information after the closing

delimiter, the system ignores it.

Process Section Header Statements

The process section immediately follows the header and defines the procedural process to be executed. There are two parts to the process section: the process section header statement and the process section data contents. The following is a process section:

/*FILE DATATYPE(PDS) DDNAME(HTMFILE) ( Process section header) CONTENTTYPE(text/html)-(Process section data) FORMAT(text)(Process section data)

A process section header does the following:

 Defines a procedural or non-procedural specification for processing a rule each time it

is triggered by a matching URL.

 Begins with control statements that define the content type. Control statements begin

with “

/*typename”, where typename refers to the content type that is known to the

system. The following types are recognized:

/*REXX/* TSOSRV /*EXECCICS /*FILE/* EXECIMS /*EXECSQL /*PROGRAM

 Begins in the first input column (discounting record numbering) of a record.

Shadow z/Enterprise Web Server Administration Guide 2-5

Quick Start

SYNTAX FOR PROCESS SECTION HEADERS

Use the following format to create process section header statements:

/*typename ( keyword ( , keywo rd ...) cont )*/

Where:

typename

Specifies the name of the process section beginning the section header statement.

keyword(s)

Describes the contents of the section, or provides parameter specifications to the “type” compiler/interpreter routine.

cont (optional)

Designates a continuation character when the information continues on the next line.

 “-” strips trailing blanks from the end of the continued line and from the

beginning of the continuation line.

 “+” interprets the string literally (blanks are not stripped).

*/ (optional)

Indicates the closing delimiter (“ delimiter, the system ignores it.

*/”). If you add information after the closing

Creating, Enabling, and Accessing a Rule

Once Shadow z/Enterprise Web Server is installed, you can do the following:

1. Create the rule on the mainframe.

2. Enable the rule from the mainframe.

3. Access the rule from your Web browser.

Creating the Rule

In this example, the HTML tags are in the body of the process section, but they could just as easily been placed in a separate data set. If you put the HTML in a separate data set, use the option 2, FILES, from the Shadow z/Enterprise Web Server Prima ry Option Menu to display and control HTML data files.

There are two methods to create a rule. You can either:

 Type all the information.  Rename an existing rule and edit it.

Typing the Information

To create a rule called HELLO by typing all the information:

2-6 Shadow z/Enterprise Web Server Administration Guide

Creating, Enabling, and Accessing a Rule

--Shadow z/Enterprise Web Server - SEF Ruleset Entry Profile ------- SSID: xWSy COMMAND ===>

Display Only the Ruleset Named ===> * ( * = display all ru lesets ) Limit Display to These Rule Types ===> * ( * = display all types)

Require Current Member Statist ics ===> Y ( N = bypass directo ry reads ) Confirm Mass Changes ===> Y ( N = bypass confirm ations ) Display Entry Selection Panel ===> Y ( N = bypass entry p anel )

1. Start the Shadow z/Enterprise Web Server ISPF interface to access the Shadow z/ Enterprise Web Server Primary Option me nu:

2. Select E for SEF Control option.

3. Press Enter. The system displays the SWS Event Facility Control panel, offering the following options:

 Global Variables - Display and Update Global Variables  SEF Rule Management - Control SEF Event Procedures & Libraries  Show Selection Panel at Entry ===> Y  Command Test - View Results of Interactive Command Requests  Files - Display Data File

4. Select the SEF Rule Management option.

5. Press Enter. The system displays the SEF Ruleset Entry Profile panel:

Figure 2–3. SEF Ruleset Entry Profile

6. Press Enter to display all the rulesets.

7. Move the cursor to the left of the ruleset row, and type figure:

Shadow z/Enterprise Web Server Administration Guide 2-7

S, as shown in the following

Quick Start

SEF Event Procedure Rulesets - Using SEF V4 Conf iguration -- Row 1 to 10 of 10 COMMAND ===> SCROLL ===> PAGE Line Commands: S Select E Enable D Di sable U Utilities A Set Auto-Enable Z Re set Auto-Enable

RULESET STATUS AE CNT VV. MM CREATED MODIFI ED SIZE INIT M OD ID ATH DISABLED N 25 01.0 8 95/11/07 00/05/2 4 11:53 2044 3357 125 7 USERID CMD ENABLED Y 4 01.0 5 98/05/20 98/08/0 3 14:23 464 404 15 9 USERID EXC DISABLED N 13 01.0 0 95/11/07 99/05/3 0 19:25 1314 1349 100 5 USERID GLV DISABLED N 1 01.0 9 95/11/07 96/05/0 7 10:38 92 100 9 2 USERID S NEON ENABLED Y 94 01.1 5 95/11/02 01/02/2 2 15:48 4540 3411 130 3 USERID SWSCNTL ENABLED Y 20 01.3 0 95/11/08 99/04/0 6 09:20 2346 948 156 7 USERID TEST ENABLED Y 161 01.0 1 97/11/19 01/04/0 6 16:13 4122 3666 115 1 USERID TOD DISABLED N 3 01.0 2 95/11/07 00/12/0 5 10:53 179 171 11 7 USERID TYP DISABLED Y 3 01.1 5 96/01/27 99/03/1 6 11:47 794 572 79 4 USERID WWW ENABLED Y 25 01.0 0 95/11/02 01/01/3 0 16:51 3322 1904 184 9 USERID **END**

SEF Event Procedure List for N EON.xWSy.NEON.EXE Row 1 to 15 of 94 COMMAND ===> S HELLO SCROLL ===> PAGE Line Commands: S ISPF Edit E Enable D Disab le A Set Auto-Enable Z Reset Auto -Enable B Set Aut o/Enable C Disable/R eset Auto

MEMBER STATUS AE TYP VV.M M CREATED MODI FIED SIZE INIT MO D ID ALLCLASS ENABLED Y WWW 01.0 1 00/10/26 00/10/2 6 16:42 6 6 0 USERID ASMFA100 ENABLED Y WWW 01.0 2 99/03/07 99/03/0 7 19:54 23 23 1 USERID BLINK ENABLED Y WWW 01.0 5 00/10/26 00/10/2 7 10:19 57 56 0 USERID CHECKSSL ENABLED Y WWW 01.0 2 97/04/08 00/03/3 1 12:26 26 24 1 0 USERID CICENTRY ENABLED Y WWW 01.0 4 00/05/15 00/05/1 9 15:45 7 7 0 USERID CICEXEC1 DISABLED N *** 01.0 0 00/12/28 00/12/2 8 12:27 12 12 0 USERID CICS ENABLED Y WWW 01.0 1 98/11/07 98/11/1 2 11:22 22 22 0 USERID CICSEXCI ENABLED Y WWW 01.0 0 98/03/09 98/03/0 9 08:54 173 173 0 USERID CICSEXIT ENABLED Y WWW 01.0 3 98/11/07 00/07/1 7 17:36 58 57 0 USERID CICSINIT ENABLED Y WWW 01.1 1 98/11/07 00/07/1 7 17:44 25 26 0 USERID CICSNTRY DISABLED N *** 01.2 4 00/05/22 01/01/2 6 14:57 5 5 0 USERID CICS1 ENABLED Y WWW 01.0 0 98/09/22 98/09/2 2 11:46 19 19 0 USERID DEMOTOKN ENABLED Y WWW 01.1 1 96/04/24 00/03/3 1 12:36 197 204 9 USERID DEMO01 ENABLED Y WWW 01.6 9 95/11/02 00/03/2 4 17:01 383 24 38 2 USERID DEMO02 ENABLED Y WWW 01.5 0 95/11/02 99/03/1 7 10:16 244 24 24 3 USERID F1=HELP F2=SPLIT F3= END F4=RETUR N F5=RFIND F6= RCHANGE F7=UP F8=DOWN F9= SWAP F10=LEFT F11=RIGHT F12= RETRIEVE

Figure 2–4. Selecting a Ruleset from the SEF Event Procedure Rulesets

8. Press Enter.

9. On the command line, type S HELLO, as shown in Figure 2–5.

2-8 Shadow z/Enterprise Web Server Administration Guide

Figure 2–5. Creating a New Rule

Creating, Enabling, and Accessing a Rule

/*WWW /NEON/hello ******************************* ****************** ********************* ** * * * This URL causes the data f ollowing the /*FIL E statement to be * * transmitted to the Web Cli ent. This URL dem onstrates the HELLO * * function of /*FILE process sections. By def ault, the outbound * * data stream is sent as tex t/html data. * * * ******************************* ****************** ********************* ** /*FILE DATATYPE(HELLO)

<html> <head> <title>Hello World Test</title> </head> <BODY> <H1>HELLO WORLD!</H1> <P> This rule test the operation of HELLO /*FILE proc ess sections. <P> <HR> <P> </BODY> </HTML> **************************** Botto m of Data ****************** **********

10. Press Enter. This runs the ISPF Editor and names the new rule.

11. Type the rule. For example, Figure 2–6 shows a sample rule.

Figure 2–6. Typing a Sample Rule

12. Press F3 to exit.

Editing an Existing Rule

To create a new rule called HELLO1 by using an existing rule called INLINE, do the following:

1. On the command line, type S HELLO1 and press Enter. This runs the ISPF Editor and names the rule.

2. On the command line, type COPY INLINE, as shown in Figure 2–7.

3. Press Enter. This copies the rule

Shadow z/Enterprise Web Server Administration Guide 2-9

INLINE into HELLO1.

Quick Start

File Edit Confirm Menu Ut ilities Compilers Test Help

EDIT NEON.xWSy.NEON.EXEC (HELLO1) - 01.0 Co lumns 00001 00072 Command ===> COPY INLINE

EDIT NEON.xWSy.NEON.EXEC (HELLO1) - Mem ber INLINE copied Command ===>

Scroll ===> PAGE ****** *********************** ****** Top of Data ******************** ********** ==MSG> -Warning- The UNDO comm and is not availab le until you change ==MSG> your edit pro file using the com mand RECOVERY ON. 000100 /*WWW /NEON/INLINE 000110 *********************** ****************** ********************* ********** 000120 * * 000130 * This URL causes th e data following t he /*FILE statement t o be * 000140 * transmitted to the Web Client. This URL demonstrates the INLINE * 000150 * function of /*FILE process sections. By default, the out bound * 000160 * data stream is sen t as text/html dat a. * 000170 * * 000180 *********************** ****************** ********************* ********** 000190 /*FILE DATATYPE(INLINE) 000200 000300 <html> 000400 <head> 000500 <title>Inline FILE Oper ation Test</title> 000600 </head> 000700 <BODY> 000800 <H1>Inline File Operati on Test</H1> 000900 <P> 001000 This rule test the operation of INLINE /*FIL E process sections. 001100 <P> 001200 <HR> 001300 <P> 001400 </BODY> 001500 </HTML> ****** ************************** ** Bottom of Data ************* ***************

Figure 2–7. Creating a New Rule from an Existing Rule

4. Edit the highlighted areas shown in Figure 2–8 as appropriate. In the exa mple, edit the highlighted areas to match the information in the previously created (Figure 2–6).

HELLO rule

2-10 Shadow z/Enterprise Web Server Administration Guide

For example, change the references to the INLINE file:

Figure 2–8. Editing a Copy of an Existing Rule

/*FILE DATATYPE(INLINE)

Creating, Enabling, and Accessing a Rule

To reference the

/*FILE DATATYPE(HELLO1)

5. Press F3 to exit.

Enabling the Rule

To enable the HELLO rule:

1. Start the Shadow z/Enterprise Web Server ISPF interface.

2. Select E for the SEF Control option.

3. Press Enter. The system displays the SWS Event Facility Control panel, offering the following options:

4. Select the SEF Rule Management option.

5. Press Enter. The system displays the SEF Ruleset Entry Profile panel:

HELLO1 file:

6. Press Enter to display all the rulesets.

7. Move the cursor to the left of the ruleset row, and type S.

8. Press Enter. The system displays the following panel:

Figure 2–9. Selecting a Ruleset from the SEF Event Procedure Rulesets

Shadow z/Enterprise Web Server Administration Guide 2-1 1

Quick Start

SEF Event Procedure List for N EON.xWSy.NEON.EXE Row 1 to 15 of 94 COMMAND ===> L HELLO SCROLL ===> PAGE Line Commands: S ISPF Edit E Enable D Disab le A Set Auto-Enable Z Reset Auto -Enable B Set Aut o/Enable C Disable/R eset Auto

9. On the command line, type L HELLO, as shown in Figure 2–10.

Figure 2–10. Locating a Rule from the SEF Event Procedure List

10. Press Enter. The list will automatically scroll to display the member at the top of the panel.

11. Move the cursor to the left of the Figure 2–11.

2-12 Shadow z/Enterprise Web Server Administration Guide

HELLO rule member row, and type E, as shown in

Creating, Enabling, and Accessing a Rule

SEF Event Procedure List for N EON.xWSy.NEON.EX R ow 23 to 37 of 94 COMMAND ===> SCROLL ===> PAGE Line Commands: S ISPF Edit E Enable D Disab le A Set Auto-Enable Z Reset Auto -Enable B Set Aut o/Enable C Disable/R eset Auto

MEMBER STATUS AE TYP VV.M M CREATED MODI FIED SIZE INIT MO D ID E HELLO DISABLED N *** 01.0 1 00/07/18 00/07/1 8 15:10 24 24 1 USERID HELLO1 DISABLED N *** 01.0 0 01/04/10 01/04/1 0 16:11 24 24 0 USERID HTXDTTM ENABLED Y WWW 01.0 7 98/05/14 00/03/3 1 13:29 51 22 3 6 USERID HTXDTTME ENABLED Y WWW 01.0 0 99/01/18 99/01/1 8 15:50 31 31 0 USERID IMP ENABLED Y WWW 01.0 1 00/05/12 00/06/2 7 11:15 22 22 0 USERID IMS ENABLED Y WWW 01.4 2 98/05/04 01/01/1 6 13:06 22 42 0 USERID IMSENTRP ENABLED Y WWW 01.0 4 00/06/06 00/06/3 0 16:54 5 5 0 USERID IMSENTRY ENABLED Y WWW 01.1 9 98/05/05 99/09/2 8 16:11 5 5 0 USERID IMSEXEC ENABLED Y WWW 01.0 0 98/10/16 98/10/1 6 15:53 15 15 0 USERID IMSEXIT ENABLED Y WWW 01.1 5 98/06/24 99/09/1 1 11:31 58 10 0 USERID IMSINIP ENABLED Y WWW 01.1 3 00/05/12 00/06/3 0 16:53 35 17 0 USERID IMSINIT ENABLED Y WWW 01.1 3 98/08/13 99/06/0 2 14:40 35 28 0 USERID IMSMENU DISABLED N *** 01.0 1 99/06/25 01/01/1 6 13:07 22 22 0 USERID IMSTEST DISABLED N *** 01.0 2 99/04/12 00/09/1 4 12:12 18 18 1 USERID IMSTESTP ENABLED Y WWW 01.7 7 00/06/27 00/06/3 0 11:54 330 95 0 USERID F1=HELP F2=SPLIT F3= END F4=RETUR N F5=RFIND F6= RCHANGE F7=UP F8=DOWN F9= SWAP F10=LEFT F11=RIGHT F12= RETRIEVE

Figure 2–11. Enabling a Rule

12. Press Enter. The rule is now enabled.

Accessing the Rule Using a Web Browser

To access a rule using a Web browser:

1. Start your Web browser.

2. Enter the appropriate URL for your system. For example:

http://<your_company_informati on>/neon/hello

http://<your_company_informati on>:<port_number>/neo n/hello

Figure 2–12 illustrates the resulting display in your Web browser.

Shadow z/Enterprise Web Server Administration Guide 2-13

Quick Start

Figure 2–12. A Rule Displayed in the browser

Deploying Shadow z/Enterprise Web Server at Your Site

The following is an overview of what you will need to do to deploy Shadow z/Enterprise Web Server at your site.

Setting Up the Mainframe Side

Before you can do anything, you will need to install Shadow z/Enterprise Web Server with the necessary options. If you are unsure which opti on s you ne ed , inst all wh at yo u kn ow you need and add the other options later. Th e n:

1. Start a test version to verify the server is running correctly. See Appendix C, “Starting a Test Version,” for more information.

2. Review the installation data sets and sample files until you are familiar with their basic functionality.

Allocate Data Sets

Now you are ready to begin allocating event procedure data sets, new data files, and a separate load library. To begin:

1. Either:

 Allocate a new event procedure set for new Web transaction definitions.  Allocate a new event procedure set offline, under TSO. (It becomes immediately

accessible from the ISPF panel without restarting the server subsystem.)

2. Name the members in the data sets to correspond to the URL. That way, you can easily find the rule or file to edit.

 Rule example: In the URL “/NEON/INLINE”, the INLINE ruleset member would

be stored in the ruleset.

 File example: In the URL “/NEON/SAMPDATA/NEWFILE.HT M”, the NEWFILE

ruleset member would be stored in the

3. Allocate a new data file to contain your HTML and other data members. Use the online

SWS.HTML.DATA data set as a model for new HTML data set allocation.

2-14 Shadow z/Enterprise Web Server Administration Guide

SAMPDATA ruleset.

Deploying Shadow z/Enterprise Web Server at Your Site

To specify operational parameters for this new data set, code a DEFINE FILE statement within the start-up time parameterization EXEC, ySW

xIN00. (If you do

not provide a DEFINE FILE statement, the data set is not visible to the ISPF panels until after it is used to process a Web transaction.)

Note:

You must do the fol lowing to use the new data set:

 Provide a DD JCL statement for the new data set within the Shadow z/

Enterprise Web Server started task JCL.

 Restart the subsystem so the data set can be used.

4. Allocate a separate load library to contain user written Web transaction programs.

5. Use the Shadow z/Enterprise Web Server product’s load library as a model for the new load library allocation. Then, in the product’s start-up JCL, allocate this library to the

SWSRPCLB ddname. Shadow z/Enterprise Web Server always tries to load user

written transaction programs from it.

Note:

You must do the fol lowing to use the new load library:

 Provide a DD JCL statement for the new load library within the Shadow z/

Enterprise Web Server started task JCL.

 Restart the subsystem so the load library can be used.

WHY ALLOCATE SEPARATE DATA SETS

Allocating separate data sets has the following benefits:

 Migrations to new versions of the Shadow z/Enterprise Web Server are easier if

you do not mix your own Web transaction definitions, HTML files, or Web transaction program load modules with those supplied by Shadow.

 It prepares you to implement detailed security controls and distributed transaction

administration later.

 The SWSRPCLB load library does not require APF authorization. Because most

sites require extra administrative procedures before modifications can be made to an APF-authorized library, placing user written programs within a separate library makes some administrative steps unnecessary.

Shadow z/Enterprise Web Server Administration Guide 2-15

Quick Start

Developing a Plan

1. Review the following:

 The ISPF panels and what each does. For example, to enable/disable rules, use

the SEF Control Options menu.

 Chapter 17, “Using the OS/390 UNIX OpenEdition Hierarchical File System

(HFS),” to use off-the-shelf web-authoring tools to create HTML files and to move files from a test to a production environment.

2. Begin a rudimentary outline of the structure your company needs. As you learn more about the Shadow z/Enterprise Web Server functionality, you can add to the outline. Consider the following:

 Which event procedure rules will the user need to access? How do you want the

access controlled—by userid and password?

 When the information is returned, how should it be displayed on the user’s

screen?

→ SEF Rule Management option from the SWS Primary

 How are the users accessing your system—Internet, intranet, or both? What level

of security do you need in the different areas?

 Will different departments handle their own updates? If yes, then you will need to

use subordinate rulesets.

Setting Up a Test Environment

Setting up a test environment allows you to familiarize yourself with the concepts that you outlined in the planning phase.

1. Start with a few ideas and experiment with them. When you get the results you want, add more features.

For example, choose a couple of start-up parameters, create some HTML forms and a couple of rules. After enabling the rules, open a Web browser, create the URL, and send it. Did you get the results you wanted? Make modifications, as needed.

2. Change the environment. Add a few more parameters and data sets. Test as you go.

3. When you are ready, change the security parameters to the master ruleset, and then allow others to test the environment.

Moving to Production

Once you receive the results you want and you are certain that the security works, move the appropriate files, such as the data sets , to the production version. See Chapter 17, “Using the OS/390 UNIX OpenEdition Hierarchical File System (HFS),” for an expedient way to move files.

2-16 Shadow z/Enterprise Web Server Administration Guide

Setting up the Client Side

To set up the client side:

1. Open the Web browser.

2. Enter the URL.

3. If prompted, enter the userid and password.

4. Press Enter to transmit.

5. View the results.

Deploying Shadow z/Enterprise Web Server at Your Site

Shadow z/Enterprise Web Server Administration Guide 2-17

Quick Start

2-18 Shadow z/Enterprise Web Server Administration Guide

CHAPTER 3:

The Shadow Event Facility (SEF)

This chapter expands on the concepts and information presented in the Shadow z/Enterprise Web Server Getting Started Guide about the Shadow Event Facility. This chapter also includes information

about event matching and how it works, event procedure execution, event procedure ruleset s, naming conventions, start-up parameters, data set format, enabling and disabling event procedures, and the structure of an event procedure. Topics include:

What It Does . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

How It Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Event Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Event Procedure Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Event Procedure Rulesets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Naming Convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Start-up Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Event Procedure Data Set Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Enabling Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Enabling and Disabling Event Procedure Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Structure of an Event Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Event Procedure Header Statement (Required). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5

Process Section Header Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

Header-Only Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

SEF Event Procedure Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

WWW Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

REXX Dynamic Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7

Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7

GLVEVENT Temporary Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

Event Related Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

Event Procedure Return Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

Accessing SEF Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10

Controlling SEF from a Batch Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11

Return Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11

What It Does

The Shadow Event Facility (SEF) is a built-in feature and the foundation of the Shadow z/ Enterprise Web Server WWW rule mechanism. With it, administrators can tailor their system using high-level language routines.

How It Works

When an event occurs (Shadow z/Enterprise Web Server receives a URL), SEF build s an event matching argument string by stripping off the destination information from the URL. It uses this information to search through a list of enabled event procedure rules until a match is found. SEF then executes the matching event.

Shadow z/Enterprise Web Server Administration Guide 3-1

The Shadow Event Facility (SEF)

In addition to matching URL requests to WWW rules, SEF contains more generalized event-to-rule matching capability. This allows you to schedule custom tailored procedures in response to processing events encountered during server operation, such as “trigger” the server to respond to a real-time event. Some of the more generalized event-to-rule matching capabilities of SEF include:

Authorization Rules (ATH)

These are used to customize logon and logoff operations, control access to the programmable facilities of the Shadow Diagnostic Facility (SDF), and limit access to various server owned resources.

Exception Rules (EXC)

These are used to customize the server’s response and handling conditions, such as SQL failures or when resource usage limit is exceeded.

SQL Rules (SQL)

These are used to capture, modify, or disallow processing for any server-based dynamic SQL operation.

Time-Of-Day Rules (TOD)

These are used to implement server administration tasks, such as refreshing web accessible data file from an external source. TOD rules fire at a specific interval, date, or time.

Event Types

The Shadow Event Facility recognizes the event types listed in Table 3–1.

Table 3–1. Event Types

Event Type Description

ATH Authorization events are generated by the server when authorization processing must be done.

The event procedure can either do the required processing or allow default ACF/2 or RACF processing to make the final decision.

CMD Command events control client/server and Web access to the mainframe by using SEF to

manage the environments on the host.

DIS Disable events are pseudo-events generated by the system whenever an event procedure is

being disabled. This allows a procedure to be executed when it is disabled in order to perform termination processing.

ENA Enable events are pseudo-events generated by the system whenever an event procedure is

being enabled. This allows a procedure to be executed when it is enabled so it can perform initialization processing.

EXC Exception events are generated by the system when some action must be taken (for example,

when a long-running data base transaction has exceeded a predefined time limit). The event procedure can decide what action to take in response to the event.

GLV Glo bal variable events are generated by the system whenever 1) the value of a global variable

symbol is changed and 2) the SEFGLVEVENTS start-up parameter is set to allow them.

TOD Time-of-day events are generated by the system at specified times.

3-2 Shadow z/Enterprise Web Server Administration Guide

Event Matching

Table 3–1. Event Types

Event Type Description

TYP Language types are not actually events, but rather, they are procedures that are an integral part

of SEF. TYP allows you to prototype new process section types by building a compiler/ interpreter in REXX, which is then processed on behalf of WWW events procedures.

WWW World Wide Web events are generated by the system whenever an HTTP transaction arrives.

This is the primary means of transaction processing implemented in the Shadow z/Enterprise Web Server.

Event Matching

When an event occurs, SEF builds an event matching argument string based on the event type. SEF uses this string to search through the list of enabled event procedure rules until one (or more) matches are found between the event argument string and the event procedure “criterion.” When a match is found, SEF “triggers” or “fires” the matching event procedure to execute.

Least to Most Specific

Event procedure criterion values are allowed to contain a wildcard character. This means a single event can match more than one event procedure. Event procedures are matched to the event argument and executed, in order, from the least to most specific match.

Event Procedure Execution

Normally, you want event procedure rules to run in direct response to an actual event; occasionally, you may need to specify that a procedure b e allowed to initialize or terminate itself. Whenever a procedure is scheduled for execution, a pre-instantiated variable, PHASE, contains information about whether the procedure was invoked for initialization, termination, or normal event processing.

Event Procedure Rulesets

Event procedure data sets (rulesets) are MVS PDS data sets. Each member of the ruleset is either active (enabled) or inactive (disabled) and can be either:

 One event procedure rule.  A REXX-language subroutine, which can be called by one or more event procedures

contained within the same PDS ruleset.

Naming Convention

All event procedure data set names must use the following Shadow z/Enterprise Web Server naming convention. All data sets must:

 Start with the same prefix (for example, “SWS.xxxxxx.”).  End with the same suffix (for example, “.EXEC”).

1 Refer to the Shadow z/Enterprise Web Server Getting Started Guide for more information.

Shadow z/Enterprise Web Server Administration Guide 3-3

The Shadow Event Facility (SEF)

 Contain a maximum of one qualifier between the pre-defined prefix and suffix. This

mid-level qualifier is the ruleset or event procedure set name.

Start-up Parameters

Shadow z/Enterprise Web Server’s startup parameters specify which MVS data set prefix and suffix values to use. The Shadow Event Facility then scans the MVS catalog and preloads enabled event procedures sets into storage. When a request is matched to an event, the SEF executes the matching event and the designated rule definition.

Event Procedure Data Set Format

Each event procedure ruleset contains one or more PDS members, which must be allocated to contain either fixed or variable length records. We recommend you use numbered, RECFM(FB) data sets.

Enabling Event Procedures

Each member within an event procedure ruleset can be enabled and matched to the event type specified in the event procedure header. Enabled members are read into storage, compiled into an internal form, and then stored so they can be paired to event matching criterion values.

Note:

Only procedures that are enabled can be matched. Disabled procedures are ignored.

Enabling and Disabling Event Procedure Rules

A single event procedure rule can be enabled or disab l ed by:

 Flagging the event procedure with the PDS as “auto-enabled”.  Using product ISPF panels.

If the rule is auto-enabled, the Shadow Event Facility enables it at start-up. If it is not autoenabled, the rule must be explicitly enabled using the ISPF interface after start-up.

Memory of the auto-enablement attribute is maintained across subsystem start-ups through the use of a bit within the PDS ISPF statistics. If you edit the member offline, the auto-enablement is reset and the rule is no longer auto-enabled.

Note:

If you display a ruleset that is PDSMAN managed, the system may reset the autoenable flag from Y to N. To change the flag back to Y, you must manually edit it. For this reason, it is recommended that you exclude SWS rulesets and SEF rulesets from PDSMAN management.

Structure of an Event Procedure

With the exception of WWW event procedures, each member in the PDS event procedure ruleset consists of two parts:

3-4 Shadow z/Enterprise Web Server Administration Guide

Structure of an Event Procedure

 A procedure header statement  One process section, which must be /*REXX (the member cannot be enabled without

it)

The WWW event procedure can contain:

 Header-only rules (no proces s section)  Process sections using /*REXX, /*FILE, and /*PROGRAM

The following is an example of a WWW event procedure containing a valid header statement, a process section, and section contents:

/*WWW /NEON/HTMLFILE/* AUTHREQ( NO) /*FILE DATATYPE(PDS) DDNAME(HTM FILE) CONTENTTYPE(text/html)-

FORMAT(BINARY)

Event Procedure Header Statement (Required)

Header statements must:

 Be the first statement within the PDS member. If the first statement is not valid, then

the PDS member cannot be enabled nor can it be processed by SEF.

 Begin in the first input column (discounting record numbering) of the first record within

the event procedure member. If a valid header statement is not present, the PDS member cannot be enabled as an event procedure.

Format

/*xxx criterion ( keyword ( keyword... ) cont )*/

Where

/*xxx

Must be the first five characters on the header statement line. valid Shadow z/Enterprise Web Server event types:

 ATH - Authorization event procedures  CMD - Command event procedures  EXC - Exception event procedures  GLV - Global variable event procedures  TOD - Time-of-day event procedures  TYP - Language processing 'type' definition  WWW - World Wide Web transaction definition

criterion

Specifies the pattern match value (the event triggering criteria) for processing the event procedure rule.

xxx is one of the

For example:

/NEON/HTMLFILE/*

Shadow z/Enterprise Web Server Administration Guide 3-5

The Shadow Event Facility (SEF)

The exact contents and meaning of the criterion string are defined separately for each event type. The maximum length for URL criterion values is 50 bytes for all event types except WWW, which allows 128 bytes.

keyword (optional)

Use one or more keywords to define:

 Properties of the event procedure.  Attributes to be used in processing of the event. At present, keywords are

used for specifying WWW security attributes.

For example:

cont (optional)

Use a continuation character after the header line keyword when the header statement continues on the next line. T wo continuation characters a re recognized:

 “-” strips trailing blanks from the end of the continued line and from the

beginning of the continuation line.

 “+” interprets the string literally (blanks are not stripped).

*/ (optional)

If you use a closing delimiter (“ follows all other keywords, the system ignores it. No information can follow the closing delimiter.

AUTHREQ(NO)

*/”) at the end of the header statement and it

Process Section Header Statements

Except for WWW event procedures (where header-only rules are allowed), there must be at least one process section present within each event procedure member. See the Shadow z/Enterprise Web Server Getting Started Guide for more information on process section headers.

Header-Only Rules

See the Shadow z/Enterprise Web Server Getting Started Guide.

SEF Event Procedure Variables

By referencing the variable name within the Shadow/REXX (/*REXX) procedure, SEF event procedure variables are always accessible to a Shadow/REXX (/*REXX) process section without requiring special interface function calls to access or set the value of an SEF variable.

WWW Event Procedures

Because section types other than /*REXX can execute a high-level language program in WWW event procedures, SEF event variables are accessible only under controlled circumstances. This usually requires the use of an access API function, such as the SWSVALUE function.

3-6 Shadow z/Enterprise Web Server Administration Guide

Types of Event Procedure Variables

Event procedures use the following types of variables:

 REXX dynamic variables  Event related variables  Global variables  GLVEVENT temporary variables

REXX Dynamic Variables

REXX dynamic variables are variables that get created during execution of a REXXlanguage process section whenever you reference or set the value of a variable.

How They Work

REXX dynamic variables exist only during execution of a REXX-language procedure and are freed when the REXX environment is deleted. Generally, they are not accessed by any non-REXX procedure or function, except as explicitly noted in API functions.

Example:

SEF Event Procedure Variables

In this example, a REXX-language simple variable, variable within the REXX code. The REXX-language compound variable symbol

stemvar.I sets the value InitValue.

do I = 1 to COUNT stemvar.I = “InitValue”

end

Not all Variable Symbols are Dynamic

Within a Shadow/REXX procedure, not all compound variable symbols are dynamic.

 If a compound variable has one of the stem values listed in the global variables

section, it is a global variable.

 If a compound variable has the “GLVEVENT.” prefix, it is a GLVEVENT temporary

variable.

Intercepting and performing specia l pro ces sin g for these reserved stem values is an automatic feature of Shadow/REXX.

Global Variables

Global variables are special variables; Shadow z/Enterprise Web Server stores global variable in a checkpoint data set. The values are persistent across restarts of the product and are shared by all event procedures that execute within the system.

COUNT or I sets the value of the

Global variables begin with one of the following stem values:

 “GLOBAL.”  “GLOBALn.” where n is an integ er fro m 1 to 9

Shadow z/Enterprise Web Server Administration Guide 3-7

The Shadow Event Facility (SEF)

How They Work

When a global variable is referenced by a Shadow/REXX-language procedu re or by the Web transaction API SWSVALUE function, the subsystem retrieves the value from its checkpoint data set. When a global variable is updated, its new value is saved. Whenever the value of a “ generated to intercept the change and perform additional processing.

Note:

GLV events are only generated when the subsystem parameter SEFGLVEVENTS is set to YES during start-up.

GLOBAL.” or “GLOBALn.” variable is changed, a GLV event can be

GLVEVENT Temporary Variables

GLVEVENT temporary variables:

 Are designed primarily for use by the high-level language routines that create and

interrogate variables during execution.

 Begin with the “GLVEVENT.” stem value.

How They Work

GLVEVENT temporary variables are similar to event related variables because they exist only for the duration of the event being processed and are deleted when the event is completed.

These variables can be created or accessed from non-Shadow/REXX procedures using the SWSVALUE function or referenced by name within a Shadow/REXX procedure.

Refer to Chapter 9, “Automated State Management Facility (ASMF),” for more information.

Event Related Variables

Event related variables are created by the Shadow Event Facility whenever an event occurs. They are used to pass informatio n ab o ut the event to the event procedure that is matched to the event. For example, the inbound URL transmitted from the Web browser.

How They Work

Event related variables:

 Ca n be refer en ce d direc tly by Shad ow/REXX-language process sections.  Are only accessible to non-Shadow/REXX procedures using the SWSVALUE Shadow

z/Enterprise Web Server API function.

WWW.INPUTURL variable receives a copy of the

3-8 Shadow z/Enterprise Web Server Administration Guide

SEF Event Procedure Variables

Changing Event Related Variables

Some event related variable values can be altered during execution; however, most are read-only. If you change the value of an event related variable, it can affect how the event is subsequently processed by Shadow z/Enterprise Web Server.

Note:

You cannot cre ate new event related variables.

Changes are Cumulative

The first rule that an event triggers gets the original event information; rules for the same event executing later get modified copies of this information. Even if a rule modifies an event related variable, all rules eligible to execute for an event still execute.

Because the values of read-only event related variables do not change, all rules that execute for a single event get the same event data.

The PHASE Variable

Event related variables are specific to the event type with one exception: SEF always creates the event related variable PHASE before any event procedure is invoked. The PHASE variable can have the values listed in Table 3–2.

Table 3–2. Values for the PHASE Var iable

PHASE Variable Value

INIT This value is set whenever the event procedure is executed as a result of being enabled.

TERM This value is set whenever the event procedure is executed as a result of being disabled.

PROC This value is set whenever the event procedure is executed as a result of being matched

Meaning

Execution of a REXX-language procedure during enablement is optional.

Execution of a REXX-language procedure during disablement is optional.

to an actual event. This is the normal execution of the procedure.

Other Event Related Variables

The remaining event related variable values are specific to the eve nt type and are only set up when the procedure is processing an actual event (such as

Refer to Chapter 4, “Defining Event Procedure Types,” for more information on event related variables and event types.

PHASE="PROC").

Event Procedure Return Values

While an actual event is processed, one or more event procedures are matched to the event and executed. As each event procedure completes, it can set a return value. For some event types, this return value is intercepted and used to control how subsequent events are processed.

Shadow z/Enterprise Web Server Administration Guide 3-9

The Shadow Event Facility (SEF)

How They Work

Not all event types use this control mechanism. Refer to Chapter 4, “Defining Event Procedure Types,” for more information.

Return Values for the Pseudo-Events

The enable (ENA) and disable (DIS) events are classified as pseudo-events because they:

 Are only optionally generated when an event procedure is enabled or disabled.  In vo ke the ev en t pr oc ed ur e th at is being enabled or disabled.

If an event procedure is invoked for enablement (the PHASE variable is set to INIT), or disablement (the PHASE variable is set to TERM), it might not return a value. The return values for the pseudo-events are shown in Table 3–3.

Table 3–3. Return Values for the Pseudo-Events

Value Returned Meaning

None Returned If no value is returned, enablement or disablement processing ends with the rule in the

desired state. "TRUE" If the character string value "TRUE" is returned, enablement or disablement also proceeds. "FALSE" If the character string "FALSE" is returned, enablement or disablement is suppressed. For

example:

• If the procedure was invoked for enablement, the event procedure is not enabled.

• If the procedure was invoked for disablement, the event procedure is not disabled. It remains enabled, unless the subsystem is terminating.

Accessing SEF Variables

Table 3–4 shows when each class of SEF event variables can be accessed.

Table 3–4. When SEF Variables Can Be Accessed

Access Type and Variable Type

Reading value of REXX dynamic variables

From Shadow/REXX Event Procedure

Intrinsic Not allowed Intrinsic

From High-Level Language Event Procedure

From Other REXX Event Procedure

Writing value of REXX dynamic variables

Reading value of event related variables

3-10 Shadow z/Enterprise Web Server Administration Guide

Intrinsic Not allowed Intrinsic

Intrinsic Using SWSV ALUE API

call

Using SWSVALUE function call

Controlling SEF from a Batch Environment

Table 3–4. When SEF Variables Can Be Accessed

Access Type and Variable Type

Writing value of event related variables

Reading value of global variables

Writing value of global variables

Reading value of GL VENENT temporary variables

Writing value of GL VEVENT temporary variables

From Shadow/REXX Event Procedure

Allowed only for certain variables

By reference or using SWSVALUE function

From High-Level Language Event Procedure

Not allowed Not allowed

Using SWSVALUE API call

From Other REXX Event Procedure

Using SWSVALUE function call

Controlling SEF from a Batch Environment

The HLQ.CNTL library contains the member SWSBATCH, which illustrates two ways in which Shadow/REXX can be invoked:

 Under a Batch Mode TMP (Preferred): SAY statements and TRACE output are

intercepted and written to

 Stand-Alone: SAY statements and TRACE output are directed to the MVS console,

which can be cumbersome if you’re trying to write and debug a new procedure.

Sample REXX Routines

The sample REXX routine is SWSBATCH in SYSEXEC. Both samples refer to a ruleset (

test.andy1) that does not exist at your site. The procedure in the sample illustrates:

 The use of all SEF commands that can be used to control rulesets  The format of other SEF commands

Return Messages

Whenever rule enablement requests are issued via an SEF command, always retrieve the messages from the external data queue to find out the status of the operation. If the enable operation fails because of an invalid rule syntax, a me ssage is issued. If no message is returned, it means the rule was successfully enabled. (This applies to the ENABLE and START command verbs).

SYSTSPRT.

Shadow z/Enterprise Web Server Administration Guide 3-1 1

The Shadow Event Facility (SEF)

Note:

A return code of zero (“0”) does not indicate the final results of processing the command; rather, it indicates the command was successfully passed to the subsystem and that some response was received. The External Data Queue must be examined to determine the actual results which occurred while processing the command.

Return Values

Whenever an ADDRESS SEF command is issued, a return code value, as shown in Table 3–5, is set for the REXX variable, RC:

Table 3–5. Return Values

Return Code Value

0 SEF COMMAND ISSUED AND RESPONSE RECEIVED 4 WARNING MESSAGE ISSUED 8 COMMAND TIME OUT ERROR 16 SEF COMMAND SYNTAX ERROR 20 TARGET SUBSYSTEM NOT ACTIVE 24 INCOMPATIBLE SUBSYSTEM VERSION 28 INTERNAL SENDMG ROUTINE FAILED 32 USER NOT AUTHORIZED TO ISSUE THIS SEF COMMAND 36 AUTHORIZATION PROCESSING ABENDED 40 HOST COMMAND FAILURE

Meaning

3-12 Shadow z/Enterprise Web Server Administration Guide

CHAPTER 4:

Defining Event Procedure Types

This chapter expands on the concepts and information presented in the Shadow z/Enterprise Web Server Getting Started Guide, describing event procedure types recognized by the Shadow Event

Facility. This chapter includes information about the structure of an event procedure, event procedure header statements and the format, process section header statements, process section header syntax, header-only rules, and SEF event procedure variables. Topics include:

Different Event Procedure Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Authorization (ATH) Event Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Command (CMD) Rule Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8

Exception (EXC) Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12

Global Variable (GLV) Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

Time-of-Day (TOD) Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17

Type (TYP) Event Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20

WWW Event Procedure Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

Different Event Procedure Types

The SEF recognizes the following event types:

 Authorization (ATH) events  Command (CMD) events  Dis ab le (DI S ) ev en ts  Enable (ENA) events  Exception (EXC) events  Global variable (GLV) events  Time-of-day (TOD) events  Language types (TYP)  Word Wide Web (WWW) events

Refer to the appropriate event types in this chapter for specific information about:

 The format of the criterion value which must be present on each event procedure

header statement

 Which keywords can be specified for each event procedure header statement  Which process types can be created within the process sections  What the valid return values are for the event type  What valid event related variables are created for each each event type

Authorization (ATH) Event Procedures

Authorization (ATH) event procedures are generated by the server when authorization processing must be done. They can be used to:

Shadow z/Enterprise Web Server Administration Guide 4-1

Defining Event Procedure Types

 Tailor the operation of the server at security control points  Perform complex , site-specific proces si ng in response to an access request  Either do the required processing or allow default ACF/2 or RACF processing to make

the final decision

How ATH Event Procedures Work

Whenever the server performs authorization pr ocessing for a controlled reso urce, an ATH event procedure is scheduled for execution. The server:

1. Generates an ATH event criterion string which describes the resource being checked or the operation being performed before invoking the validation facilities of RACF, ACF/2, orTop Secret.

2. Searches the enabled ATH rules for a matching event procedure. a. If a match is found, the ATH rule is scheduled for execution before the server

attempts to validate access using RACF, ACF/2, or Top Secret.

b. If no matching ATH procedure is found, the server relies entirely upon the

determination of the MVS security subsystem.

Each ATH procedure ends by returning one of the following signals:

 Unconditionally REJECTs access to the resource being check. The server bypasses

invocation the MVS security subsystem services and rejects the resource access request.

 Unconditionally ALLOWs access to the resource. The server bypasses MVS security

subsystem processing and immediately allows access to the resource.

 Makes no decision about access to the resource. In this case, the server proceeds by

invoking the MVS security subsystem to determine if access to the resource is allowed or denied.

ATH Event Procedure Criterion

An ATH event procedure criterion value is a string containing from 1 to 30 characters. A trailing asterisk (“ the criterion, the ATH rule is scheduled for all control points. The following example specifies an event criterion value of

/*ATH eventcriterion

Fixed Control Points

LOGON and LOGOFF ATH criterion are fixed. LOGON.WWW is the criterion value for HTTP client userid and password validation requests. LOGOFF.WWW is the criterion for client userid logoff processing requests. All third-party run-time userid logon and logoff processing is handled internally. ATH rules are not scheduled for non-client verification logon/logoff control points.

*”) can be used as a wildcard character. If a single asterisk is coded as

eventcriterion:

4-2 Shadow z/Enterprise Web Server Administration Guide

Authorization (ATH) Event Procedures

Other Control Points

All other server control point events are generated when an attempt is made to access a server provided or server controlled facility. Each control point has an associated “generalized resource name” used b y the ser ver . These na mes are fixed an d are no t user configurable.

The server constructs the ATH event matching string by placing a period following the fixed, generalized resource name. When an individual resource entity identity is known, the entity name is appended to the string following the period.

The “generalized resource names” referred to here are used to perform MVS security subsystem resource checking. Start-up parameters give the RACF “class table” name, in which these resource names must be defined. The MVS security subsystem is configured to grant or deny access to the resources, by name, within each class. The resource names in use by the server are normally configured into the MVS security subsystem at installation time. The resource names are shown in Table 4–1.

Resource Name Serv er Co nt rol led Re sou r ce

CONTROLBLOCKS View internal server control blocks using ISPF interface. CICSCONNECTIONS View or define server CICS connection entities. FILE View or control server file services ISPF interface. DATABASES View or define a database entity. SEF Access the event procedure management functions of the server. TSO Schedule outboard execution of a procedure in a TSO server managed by the

server. LINKS View or define a telecommunications link entity. MQSERIES View or define an MQSeries entity. PARMS View or set a server initialization parameter value. RPC Execute a user-written transaction program. TRACEDATA View binary data for each wraparound trace entry. TRACEBROWSE Access the wraparound trace display facility. SWS Access the server’s ISPF interface. TOKENS View or control server tokens. USERS View in-flight transaction display. GLOBALS Use ISPF interface to display/alter server global variables. DATASET Access a specific MVS data set. URL Check authorization to execute a Web transaction definition which uses resource

protection.

Table 4–1. Server Controlled Events

Shadow z/Enterprise Web Server Administration Guide 4-3

Defining Event Procedure Types

ATH Event Procedure Header Keywords

No keywords are currently defined for ATH event procedures. Only the event criterion value is allowed and required. Each ATH header statement is coded as follows:

/*ATH eventcriterion

ATH Event Procedure Process Sections

A REXX-language process section must be coded in each ATH event procedure. Headeronly ATH rules are not allowed.

ATH Event Procedure Return Values

When an ATH procedure ends, the return value set by the REXX language rule is examined by the server before invoking MVS security routines. Valid return values are shown in Table 4–2.

Return Value Action

ACCEPT If the REXX procedure returns the string “ACCEPT”, the server allows access to

the requested resource and bypasses any further processing by the MVS

security subsystem.

REJECT If the REXX procedure returns the string “REJECT”, the server denies access to

the requested resource and bypasses any further processing by the MVS

security subsystem.

The ATH rule may set the A TH.OPAUERMG variable to a message to explain the

rejection. In most validation requests, this error message is forwarded to the

requester.

Any other value If any other value (or no value) is returned, the server performs validation

checking using built-in MVS security subsystem interfaces. The final

determination to allow or deny access is made by RACF, ACF/2, or Top Secret.

Table 4–2. Valid Authorization Return Values

ATH Event Procedure REXX Variables

For any ATH event which is scheduled on behalf of an in-flight Web transaction task, the server makes the transaction’s WWW stem variables available to the ATH procedure. These variables are not available to ATH rules scheduled outside Web transaction subtasks. The WWW variables that the server maintains can be found in “WWW EventRelated Variables” on page 4-33.

In addition to the WWW variables, each ATH procedure also has access to all server wide “

GLOBAL.” variables.

ATH-specific variables are created before the ATH procedure is invoked. The exact variables created differ, depending on the type of resource check operation being performed. The variables which are instantiated for ATH procedures are based upon the resource type being checked.

4-4 Shadow z/Enterprise Web Server Administration Guide

Authorization (ATH) Event Procedures

Table 4–4 through Table 4–7 show the ATH stem variables built for each resource validation type.

ATH Stem V ariable Description

ATH.OPAURQSR Contents: The resource name string is set to LOGON or LOGOFF for

client authentication processing events. See “Fixed Control Points” on page 4-2.

Data Type: Character, Read-only

ATH.OPAUACSR Contents: The type of access being requested for the resource as a

server defined string. The access type string varies depending on the resource being validated and the operation being requested. See Table 4– 8 on page 4-7 for valid values.

Data Type: Character, Read-only

ATH.OPAURQRC Contents: This requests a return code. Valid values are:

• 00 - Request allowed

• 04 - Request must be modified

• 08 - Request failed

• 12 - Request abended

• 16 - Product address space is down Data Type: Character, Read-write

ATH.OPAUUSID Contents: This is the userid being validated for LOGON, LOGOFF, or

some task requesting access to the controlled resource. A LOGON routine may change the value of this field to cause a rule

generated userid to be used for subsequent validation processing in RACF, ACF/2, or Top Secret. All other ATH rules should not attempt to alter this variable.

Data Type: Character, Read-only (except as noted)

ATH.OPAUERMG Contents: This is a validation error message variable that can be set by

the ATH procedure. Data Type: Character, Read-write

ATH.OPAUSRID Contents: This is the full ATH event procedure criterion value set by the

server for this control point. Data Type: Character, Read-only

Table 4–3. ATH. Variables Set for ALL Rules

ATH Stem V ariable Description

ATH.AUCCID Contents: This is the CICS SYSIDNT name.

Data Type: Character, Read-only

Table 4–4. ATH. Variables Set for CICSCONNECTIONS

Shadow z/Enterprise Web Server Administration Guide 4-5

Defining Event Procedure Types

ATH Stem Variable Description

ATH.AUBKCBNA Contents: This is the control block acronym.

Data Type: Character, Read-only

ATH.AUBKCBAD Contents: This is the control block virtual storage add ress.

Data Type: Character, Read-onl y

ATH.AUBKCBLN Contents: This is the control block length.

Data Type: Numeric, Read-only

ATH.AUBKCBAS Contents: This is the Address Space ID (ASID) of the control block.

Data Type: Numeric, Read-only

Table 4–5. ATH. Variables Set for CONTROLBLOCKS

ATH Stem Variable Description

ATH.AUDBNAME Contents: This is the database name.

Data Type: Character, Read-only

ATH.AUDBTYPE Contents: This is the database type.

Data Type: Character, Read-onl y

ATH.AUDBHOST Contents: This is the database host name.

Data Type: Numeric, Read-only

Table 4–6. ATH. Variables Set for DATABASE

ATH Stem Variable Description

ATH.AUGLRQTY Contents: Used to specify the global access request type:

• A - Some type of read access

• U - Some type of update access Data Type: Character, Read-only

Table 4–7. ATH. Variables Set for GLOBALS

4-6 Shadow z/Enterprise Web Server Administration Guide

Authorization (ATH) Event Procedures

ATH Stem Variable Description

ATH.AUGLOPCH Contents: Used to specify the operation subtype value:

• A - Add a global variable

• D - Drop a global variable

• E - Check global variable existence

• F - Exist/obtain for global variable

• I - Obtain information about a global varia ble

• L - List information about a global variable

• O - Obtain a global variable

• R - Remove a global variable

• S - Subtree processing

• T - Subtree information processing

• U - Update a global variable

• V - Value processing Data Type: Character, Read-only

ATH.AUGLDELN Contents: This is the global variable’s derived name length.

Data Type: Numeric, Read-only

AT H.AUGLDENA Contents: This is the global variable’s derived name.

Data Type: Character, Read-onl y

Table 4–7. ATH. Variables Set for GLOBALS

ATH Event Procedure Access Type Values

The server generates an access type string value for each resource validation request. The string used depends on the resource being validated.

Table 4–8 gives the access type strings that the server sets.

Type String RACF Value Access Type Used For Validation Of

EXECUTE Execute RPC, URL READ Read DATASET INFO Read PARMS LIST Read CICSCONNECTIONS, FILE, DATABASE, SEF, TSO,

LINKS, MQSERIES, PARMS, TOKENS, USERS,

GLOBALS SHOW Read PARMS DISPLAY Read CONTROLBLOCKS, CICSCONNECTIONS, FILE,

DATABASE, SEF, TSO, LINKS, MQSERIES, PARMS,

TOKENS, USERS, GLOBALS, TRACEDATA,

TRACEBROWSE SET Update PARMS

T able 4–8. ATH Access Type Values

Shadow z/Enterprise Web Server Administration Guide 4-7

Defining Event Procedure Types

Type String RACF Value Access Type Used For Validation Of

CONTROL Control DATASET, LINKS, SEF, FILE, DATABASE,

CICSCONNECTIONS KILL Update Users WRITE Update CONTROLBLOCKS, CICSCONNECTIONS, FILE,

DATABASE, SEF, TSO, LINKS, MQSERIES, PARMS,

TOKENS, USERS, GLOBALS, TRACEDATA,

TRACEBROWSE, DATASET ADD Add CICSCONNECTIONS, DATABASE, LINKS, MQSERIES,

GLOBALS MODIFY Update CONTROLBLOCKS, CICSCONNECTIONS, FILE,

DATABASE, SEF, TSO, LINKS, MQSERIES, PARMS,

TOKENS, USERS, GLOBALS, TRACEDATA,

TRACEBROWSE, DATASET DEFINE Add CICSCONNECTIONS, DATABASE, LINKS, MQSERIES,

FILE CONTROL Control DATASET DELETE Delete DATASET ALTER Alter DATASET USER UserID

Password Validation

LOGOFF UserID

Logoff

LOGON

LOGOFF

T able 4–8. ATH Access Type Values

Command (CMD) Rule Event Procedures

Command rules control client/server and Web access to the mainframe by using the Shadow Event Facility (SEF) to manage the environments on the host. When viewed in conjunction with diagnostics, monitoring, and control mechanisms built into Shadow z/ Enterprise Web Server, command rules are another step in providing comprehensive Automated System Operation (ASO) capabilities.

Note:

Command rules are not subject to any security. Because these rules can access and update any part of the product without constraint, each installation needs to control who can create, enable, and disable command rules.

How CMD Rule Event Procedures Work

Whenever the server receives a command from an MVS console, a command rule event procedure is scheduled for execution. The console can be either:

 A physical console used by operations personnel

4-8 Shadow z/Enterprise Web Server Administration Guide

Command (CMD) Rule Event Procedures

 Extended software used by other products (such as NetView, CA-OPS/MVS, or

SDSF)

The command rule text consists of a command verb, followed by operands (optional). This verb string is matched against enabled command rules from the least to most specific. Command rules can:

 Examine the command text, parse out the operands, and take whatever action is

needed, such as read and set product parameters. (This means parameters can now be displayed and changed from an MVS console.)

 Access and update Shadows REXX global variables.  Communicate back to the console that entered the command using REXX SAY

statements. All SAY statement output is routed back to the console which entered the original command. This is not only useful to operators entering commands from consoles, but it also allows ASO products to communicate with, interrogate the status of, and control Shadow z/Enterprise Web Server as needed.

Command Rule Processing

All command rule processing is done using Shadow/REXX. Processing in TSO/E REXX, CA-OPMS/MVS REXX, or other programming languages is not supported at this time. When the command (CMD) procedure ends, it returns one of these values:

 RETURN - Command rule has finished execution.  RETURN “ACCEPT” - Command rule has finished execution.  RETURN “REJECT” - Command rule has rejected execution of the command.

CMD Rule Event Procedure Syntax

Command rules are triggered by either the MVS STOP/MODIFY interface or directly via an MVS command using the subsystem name chosen at startup time as the identifying parameter. For example:

SWSX command text or F SWSX, command text

MODIFY SWSX, command text

From the perspective of command rule pr oc essing, there is no difference between these methods.

Note:

The command rule event facility cannot be used for general MVS command processing. The command must be directed at a specific instance of the product identified by the subsystem name chosen at product initialization.

CMD Rule Event Procedure Criterion

A CMD rule event criterion is a string containing from 1 to 30 characters. A trailing asterisk

*”) can be used as a wildca rd characte r. If a single asterisk is coded as the cr iterion, the

(“ CMD rule is scheduled for all commands. The following example specifies an event criterion value of

eventcriterion:

/*CMD eventcriterion

Shadow z/Enterprise Web Server Administration Guide 4-9

Defining Event Procedure Types

Rule Matching Order

The event criterion can be specific or generic. The verb string is matched against all enabled command rules. Matched command rules are executed in order of least specific to most specific.

EXAMPLE

Enabled Command Rules:

/*CMD *

Matches all commands.

/*CMD SE*

Matches all commands beginning with “SE”.

/*CMD SEF

Matches command name “SEF” only.

Command Verb String:

SWSX SEF xxxxx or F SWSX,SEF x xxxx

Result: First, rule 1 is matched and executed, then rule 2, and finally rule 3.

CMD Rule Event Procedure Header Keywords

Currently, no keywords are defined for CMD event procedures. Only the event criterion value is allowed and required. Each CMD header statement is coded as follows:

/*CMD eventcriterion

CMD Rule Event Procedure Process Sections

A REXX-language process section must be coded in each CMD event procedure. Headeronly CMD rules are not allowed.

CMD Rule Event Procedure Return Values

When a CMD procedure ends, the return value set by the REXX language rule is examined by the server to control what is done with the command. Table 4–9 lists valid return values.

Return Value Action

None supplied If the REXX procedure simply executes a RETURN command, the server

sends a return code which indicates successful completion of the command rule. See “Special Considerations for STOP Rules” on page 4-

11.

Table 4–9. CMD Valid Return Values

4-10 Shadow z/Enterprise Web Server Administration Guide

Command (CMD) Rule Event Procedures

Return Value Action

ACCEPT If the REXX procedure returns the string “ACCEPT”, the server sends a

return code which states the command rule was successfully completed. See the explanation of the ACCEPTED return code in “Special Considerations for STOP Rules” on page 4-11 .

REJECT If the REXX procedure returns the string “REJECT”, the server sends a

return code which states the command rule rejected the entered command. It is the responsibility of the person implementing the command rule to state (using REXX SAY statements) the reason the command was rejected. See explanation of the REJECTED return code in“Special Considerations for STOP Rules” on page 4-11.

Table 4–9. CMD Valid Return Values

Special Considerations for STOP Rules

The MVS STOP command can also drive command rule processing. In turn, command rule processing can control or reject product shutdown.

Note:

The criterion of a STOP command rule must be STOP (or a less specific command rule that matches STOP). The MVS STOP (P) command also drives a command rule with a matching criterion of STOP but the MVS command rule with a criterion of “P”.

P command does not drive a

The return value supplied by the STOP CMD rule determines product termination. Pro duct shutdown can be controlled or rejected with STOP CMD rule processing. The valid return values and their functions in a STOP CMD rule are shown in Table 4–10.

Return Value Action

None supplied Product termination is allowed to continue. ACCEPT Product termination is not allowed to continue. REJECT Product termination is not allowed to continue.

Table 4–10. Return Values Supplied by the STOP CMD Rule

CMD Rule Event Procedure REXX Variables

Table 4–11 shows the CMD stem variables built for all rules.

Variable Description

CMD.VERB Contents: The command name entered at the console.

Data Type: Character, Read-only

Table 4–11. CMD Variables Set for ALL Rules

Shadow z/Enterprise Web Server Administration Guide 4-1 1

Defining Event Procedure Types

Variable Description

CMD.TEXT Contents: Any operands entered after the command name

at the console. Data Type: Character, Read-only

Table 4–11. CMD Variables Set for ALL Rules

Exception (EXC) Event Procedures

Exception (EXC) event procedures are generated by the system when an action must be taken (for example, when a long-running data base transaction has exceeded a predefined time limit). The EXC event procedure decides what action to take in response to the event.

How EXC Event Procedures Work

The server schedules execution of enabled EXC procedures when certain exceptional events are detected. With EXC rules, you can customize various time-slicing and timekeeping facilities of the server.

EXC Event Procedure Criterion

The criterion values for EXC event procedures are server generated exception type names, which are shown in Table 4–12.

Exception Name Description Default Server Action

CPULIMIT A transaction task has exceeded its maximum CPU

time limitation. This exception is detected only when multi-part messages are being transmitted and only at the point when a new message segment is being read.

CPUTIME A transaction task has exceeded its maximum CPU

time limitation. This exception can be detected at any time during execution of the transaction task.

IMSFAIL An IMS task detected a failing IMS operation. This

exception can occur for any type of IMS processing.

LOCKEXCLUSIVE A transaction task has exceeded its DB2 exclusive

lock time limit.

LOCKSHARE A transaction task has exceeded its DB2 shared lock

time limit.

LOCKUPDATE A transaction task has exceeded its DB2 update lock

time limit.

Terminate the transaction task.

Terminate the IMS operation and reflect error back to the client transaction task.

Terminate the transaction task.

Table 4–12. Exception Names

4-12 Shadow z/Enterprise Web Server Administration Guide

Exception (EXC) Event Procedures

Exception Name Description Default Server Action

PERSQLCPU A transaction task has exceeded its per SQL

statement CPU time limit. This exception is only detected by SQL operations executed by the server (such as for EXECSQL rules) and not when a user written high-level language program invokes long running SQL operations.

SQLFAIL A transaction task detects a SQL statement that has

failed. A SQL statement is considered to have failed if a negative SQL code is set.

This exception is only detected by SQL operations executed by the server (such as for EXECSQL rules) and not when a user written high-level language program invokes long running SQL operations.

TIMERONLIMIT A transaction task detects that a PREP ARE has

returned a timeron value that exceeds the task’s timeron limit value.

This exception is only detected for dynamic SQL operations executed by the server (such as for EXECSQL rules) and not when a user written highlevel language program invokes prepare.

WAITTIME A transaction task has exceeded its wait time limit.

This exception can be detected at any time for transaction tasks.

Terminate the transaction task.

Reflect SQL error code to the transaction task.

Terminate SQL processing a reflect error to transaction task.

Terminate the transaction task.

Table 4–12. Exception Names

EXC Event Procedure Header Keywords

No keywords are currently defined for EXC event procedures. Keywords can not follow the criterion value on the event procedure header statement.

EXC Event Procedure Process Sections

Only REXX-language process sections can be coded. Header-only rules are not allowed.

EXC Event Procedure Return Values

When an EXC procedure does not return a value, the default action is ta ken by the se rver as seen in the event procedure criterion table.

Special Return Values

For some exception types, the EXC procedure can set a special return value, which causes the server to take an alternate recovery action. F or example, it could ignore a CPU time limit overrun or increase a task’s CPU time limit value.

The run-time environment in which an exception is detected by the server varies for each type. Some exceptions are detected synchronously, within a transaction processing subtask, while others are detected asynchronously by a special server timekeeping task (the “check limits” task).

Shadow z/Enterprise Web Server Administration Guide 4-13

Defining Event Procedure Types

Samples

The EXC procedure samples distributed with the server contain a sample for each of the exception types. Instructions in the samples indicate the environment in which the exception is detected, what operational controls can be used to affect subsequent processing by the server, and what return values are valid.

EXC Event Procedure REXX Variables

The server certain REXX variables, shown in Table 4–13, to be instantiated, which are available for examination by the EXC event procedure.

Variable Name Description

EXC.OPEXSRID Contents: This is the exception name that is matched to the EXC

procedure’s criterion value. Data Type: Character, Read-only

EXC.OPEXACSR Contents: This is a string describing the default exception handling action,

which the server takes for this exception. Data Type: Character, Read-only

EXC.OPEXERMG Contents: This is an error message that can be set/changed by the EXC

event procedure. Data Type: Character, Read-write

EXC.OPEXCNTK Contents: This is a connection token value, which can be used to by the

EXC event procedure to obtain information about the transaction processing task.

Note: The token must be used to access transaction task information in cases where the exception is detected asynchronously.

Data Type: Character, Read-only

EXC.OPEXWAOK Contents: This is a variable that indicates if the EXC procedure is allowed

to perform operations that cause the current subtask to be placed in a wait state (for instance, by issuing an I/O request).

The values set for this variable are:

• 0 - Waits are not allowed

• 1 - Waits are allowed Data Type: Character, Read-only

EXC.OPEXINFO Contents: This is a variable that indicates whether the SWSINFO function

can be used by the EXC procedure. The values set for this variable are:

• 0 - SWSINFO should not be used

• 1 - SWSINFO can be used Data Type: Character, Read-onl y

Table 4–13. EXC Event Procedure REXX Variables

4-14 Shadow z/Enterprise Web Server Administration Guide

Global Variable (GLV) Event Procedures

Global variable (GLV) event procedures are generated by the system whenever the following occur:

 T he valu e of a glob al var ia ble is upda te d .  The SEFGLVEVENTS start-up parameter is set to allow them.

A GLV event procedure can be used to produce side-effects based upon the detection of an update to a global variable value.

How GLV Event Procedures Work

When the update event is detected, the SEF attempts to locate a matching GLV event procedure.

Note:

The use of GLV event procedures has a modest impact upon the virtual storage utilization of Shadow z/Enterprise Web Server subsystem.

GLV Event Procedure Criterion

You may specify a 1-to-50 byte string for the criterion value of the GLV event procedure header statement. If you specify the value in lowercase, SEF converts it internally to uppercase. Shadow z/Enterprise Web Server processes all GLV matching operations using uppercase.

The criterion value is the name of the global variable, which must be altered for this event procedure to be triggered for execution. A generic procedure can be created by using the wildcard (“

Example The sample GLV procedure below would trigger for any update to a global variable that

has a name beginning with “

*”) character.

GLOBAL.WEBTRANS.”.

/*GLV Global.Webtrans.* /*REXX .

...remainder of procedure

GLV Event Procedure Header Keywords

No keywords are supported for GLV event procedures. Keywords should not follow the criterion value on the event procedure header statement.

GLV Event Procedure Process Sections

Only REXX-language process sections can be coded. Header-only rules are not allowed.

Shadow z/Enterprise Web Server Administration Guide 4-15

Defining Event Procedure Types

GLV Event Procedure Return Values

The Shadow Event Facility is unaffected by any values returned by a GLV event procedure. The global variable value is updated in all cases, reg ardless of the retur n value set by a GLV procedure.

GLV Event Procedure REXX Variables

When a global variable change event is detected, the system extracts information about the event and creates event-related variables, shown in Table 4–14. These variables are pre-instantiated when the GLV event procedure is scheduled for execution.

You may access these data items directly, by name, from within REXX language event procedures.

Variable Name Contents

PHASE Contents: This contains a four-byte character constant which indicates the

processing phase for which the current event procedure was invoked.

• If set to INIT, the procedure is enabled either during subsystem start-up or in response to a user enable request.

• If set to PROC, the procedure runs after being matched to an actual global variable update event.

• If set to TERM, the procedure is disabled either during subsystem shut-down, or in response to a user disable request.

During procedure enablement and disablement, the only other variable that is instantiated is GLV.USER. The remaining variables are only instantiated during PROC PHASE processing.

Data Type: Character, Read-only

GLV.NAME Contents: This is 1-to-50 byte derived name of the global variable whose

modification triggered this event. Data Type: Character, Read-only

GLV.NEWVALUE Contents: This is the global variable’s value after modification. Note that the

standard REXX definitions apply to variables that have never been referenced before or have been dropped.

Data Type: Character, Read-only

GLV.OLDVALUE Contents: This is the value the global variable had before it was modified.

Note: Standard REXX definitions apply to variables that have never been referenced before or have been dropped.

Data Type: Character, Read-only

GLV.PROGRAM Contents: This is the name of the program or event procedure that updates the

global variable. Data Type: Character, Read-only

Table 4–14. GLV Event Procedure REXX Variables

4-16 Shadow z/Enterprise Web Server Administration Guide

Time-of-Day (TOD) Event Procedures

Variable Name Contents

GLV.T EXT Contents: This is the text message which describes the global variable update

event. The string, truncated at 100 bytes, contains the GLV.NAME, GLV.PROGRAM, GLV.OLDVALUE, and GLV.NEWVALUE values.

Data Type: Character, Read-only

GLV.USER Contents: This is an 8-byte (maximum length) field for communicating between

event procedures that are executing for a single event. This field can be used to pass information between multiple event procedures.

This field is initialized to binary zeroes. Data Type: Character, Read-write

Table 4–14. GLV Event Procedure REXX Variables

Refer to Chapter 9, “Automated State Management Facility (ASMF),” for more information.

Time-of-Day (TOD) Event Procedures

TOD event procedures are generated whenever the MVS timer associated with a TOD event procedure expires.

How TOD Event Procedures Work

The time or date you specified in a TOD rule’s definition determines when the MVS timer expires.

TOD Event Procedure Criterion

The TOD event procedure criterion value is specified in the following form:

/*TOD todspec, interval, endsp ec, maxexecs

Table 4–15 describes each of the components of the TOD event procedure criterion values.

Name Description

todspec

Time-of-Day Specifier. Either the time-of-day specifier or the interval must be present to define a TOD event procedure. Follow these guidelines when specifying the todspec value:

• Specify a date or time in any order. The format for specifying times and dates is given in Table 4–16 on page 4-18.

• Use either uppercase or lowercase letters.

• If the

todspec value is omitted, code the comma following it to indi-

cate its omission. An interval specification must be present if

spec is omitted.

tod-

Table 4–15. TOD Criterion and Description

Shadow z/Enterprise Web Server Administration Guide 4-17

Defining Event Procedure Types

Name Description

interval

Execution Interval Specifier. (Optional unless todspec was omitted) The interval specifier gives the amount of time units between event executions. If interval is omitted, the event procedure executes one time at the time value given by specifier are given in Table 4–16 on page 4-18.

If other specifications follow omitted, code the comma following it to indicate its omission.

todspec. The valid formats for the interval

interval, and the interval value is

endspec Ending Time-of-Day Specifier. (Optional) The specifier gives the time/

date value after which executions of this event procedure cease. The valid format for the

endspec matches the todspec format.

maxexecs Maximum Executions Specifier. (Optional) The value for maxexecs is

the number of times the event procedure is to be executed. This value is coded as an integer count value.

Table 4–15. TOD Criterion and Description

Specifier Formats

Table 4–16 gives the correct formats for coding each of the TOD event procedure specifier values:

Specifier Type Format Description

Date Any one of these formats is

acceptable:

• dd MMM year

• yy/mm/dd

• weekday

Time hh:mm:ss The time in 24-hour military format, as follows:

The day, month, year , or day of the week, depending on the format used:

• dd: A two-digit integer (01 through 31) corresponding to the date of the month

• MMM: One of the following three-character abbreviations for the name of a month: JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, or DEC

• year: A four-digit year (for example, 1996)

• yy: A two-digit integer corresponding to a year (for example, 96)

• mm: A two-digit integer (01 through 12) corresponding to a month of the year

• Weekday: The full name of a weekday (for example, SUNDAY or MONDAY)

• hh: A two-digit integer (00 through 23), indicating the hour

• mm: A two-digit integer (00 through 59), indicating the minute

• ss: (Optional) A two-digit integer (00 through 59), indicating the seconds after the minute

Table 4–16. Specifier Formats

4-18 Shadow z/Enterprise Web Server Administration Guide

Specifier Type Format Description

Time-of-Day (TOD) Event Procedures

Interval n units

Note: You can also use the 24 hour military time format described above.

Table 4–16. Specifier Formats

The frequency and type of the interval:

• n: An integer multiplier, indicating the number of interval time units

• units: One of the following time units: DAY(S), WEEK(S), HOUR(S), MINUTE(S) or MIN(S), SECOND(S) or SEC(S)

For example: 3 WEEKS

50 SECS 5 MINS 1 DAY

TOD Event Procedure Header Keywords

No keywords are currently defined for TOD event procedures other than the specifier values previously stated.

TOD Event Procedure Process Sections

Only REXX-language process sections can be coded. Header-only rules are not allowed.

TOD Event Procedure Return Values

The value returned from a TOD event procedure does not:

 Have any special meaning for the SEF  Have any effect on subsequent SEF processing

TOD Event Procedure REXX Variables

When a TOD event occurs, the system extracts information about the event and creates event related variables, shown in Table 4–17. These variables are pre-instantiate d when the TOD event procedure is scheduled for execution. You can access these data items directly, by name, from within REXX-language event procedures.

Shadow z/Enterprise Web Server Administration Guide 4-19

Defining Event Procedure Types

Variable Name Contents

PHASE Contents: This contains a 4-byte character constant which indicates the processing

phase for which the current event procedure was invoked.

• If set to INIT, the procedure is enabled either during subsystem start-up or in response to a user enable request.

• If set to PROC, the procedure runs after being matched to an actual global variable update event.

• If set to TERM, the procedure is disabled either during subsystem shut-down or in response to a user disable request.

During procedure enablement and disablement, no other event relative variables are instantiated.

Data Type: Character, Read-only

TOD.NEXTFIRE Contents: This value indicates the next time the event procedure will run.

Possible values are:

• The date and time the rule fires next, in yyyy/mm/dd hh:mm:ss format

• NONE, if the rule does not execute again

Data Type: Character, Read-only

TOD.USER Contents: This is an 8-byte (maximum length) field for communicating between

event procedures that are executing for a single event. This field can be used to pass information between multiple event procedures.

This field is initialized to binary zeroes. Data Type: Character, Read-write

Table 4–17. TOD Event Procedure REXX Variables

Type (TYP) Event Procedures

At the current time, TYP event procedures are reserved for use only by Shadow Support. They are used to develop prototypical Shadow z/Enterprise Web Server process section compiler/interpreter routines.

Warning:

You must not alter the distributed TYP event procedures in any way.

Shadow may elect to publish additional information about TYP event procedures a t a later time. We strongly recommend that you do not code your own TYP event procedures at this time

TYP Event Procedure Criterion

The criterion value must be a 1-to-8 byte process se ction “type” name. The name must be unique within the system.

4-20 Shadow z/Enterprise Web Server Administration Guide

TYP Event Procedure Header Keywords

No keywords are currently defined for TYP event procedures. Keywords cannot follow the criterion value on the event procedure header statement.

TYP Event Procedure Process Sections

Only REXX-language process sections may be coded. Header-only rules are not allowed.

TYP Event Procedure Return Values

Unpublished, at this time.

TYP Event Procedure REXX Variables

Unpublished, at this time.

WWW Event Procedure Rules

This section expands on the concepts and information presented in the Shadow z/ Enterprise Web Server Getting Started Guide. If you do not find the information in this

manual (such as how to create a WWW event/rule, input and output examples, etc.) , please refer to the Shadow z/Enterprise Web Server Getting Started Guide or one of the related publications.

WWW Event Procedure Rules

What Are WWW Rules

MVS, in its native form (catalog structure, file system naming conventions, JCL, EBCDIC code pages, and overall operating configuration), does not easily fit within the UNIX origins of the World Wide Web. Any Internet applications deployed on MVS must provide a means of translating UNIX-style requests into MVS resource designations, and then translating the responses into the expected UNIX-style formats and ASCII character sets.

Shadow z/Enterprise Web Server performs this UNIX-to-MVS resource mapping by using WWW event procedure rules.

How WWW Rules Work

WWW event procedure rules can:

 Define a native MVS data set resource to be returned for the URL and provide the

specifications needed for transforming the resource into an ASCII, browser compatible entity.

 De fin e th e optio ns ne e de d to mak e us e of a se rve r pr ov ide d turn ke y inte rf ac e fo r

extracting and formatting data from legacy systems such as CICS, IMS, DB2, ADABAS, and TSO/E.

 Execute a script or customer-written program that generates the response associated

with the requested URL.

Shadow z/Enterprise Web Server Administration Guide 4-21

Defining Event Procedure Types

WWW Rule Types

There are three types of WWW rule definitions that can be defined within Shadow z/ Enterprise Web Server.

 URL filter rules  Target WWW rules  Gateway filter rules

URL Filter Rules

A URL filter rule is a WWW rule that contains only the rule header statement (it contains

/*WWW” delimiter, URL match criterion, and optional header statement keywords, but

the “ does not contain a process section). URL filter rules are norma lly defined generically using a wildcard as the last character of the URL match criterion.

HOW THEY WORK

Header-only, URL filter rules are used to specify run-time transaction security limits or diagnostic attributes that control the MVS and server environment that are to be in effect during a subsequent procedure execution. The run-time attributes specified by URL filter rules are accumulated through each URL-to-rule match step. Each time a URL filter rule is matched, the server saves the updated attributes before it looks for another URL-to-rule match.

A header-only URL filter rule is not considered to be the ultimate target of any URL-to-rule search. URL filter rules can only set run-time security attributes and options; they do not cause an outbound response message to be generated.

SECURITY

The server provides a security administration scheme that allows certain security related parameter values to be specified only within the master WWW ruleset. URL filter rules (within the master ruleset) can be used to control run-time security attributes of all the transactions in a subordinate WWW ruleset..

During rule lookup, the server must locate a target WWW rule definition, even if one or more URL filter rules were found. Otherwise, the URL requested by the client is considered to be undefined and a “

Whenever a procedural WWW rule is matched (the rule contains a process section), these accumulated run-time attributes are put into effect just before the procedure is executed.

Example One URL filter rule attribute could specify whether the end user must provide a valid MVS

userid and password before being allowed to request a URL. When the accumulated attributes are put into effect, the server determines if a valid logon has occurred. If it has, the procedure is executed; if not, the server generates a re-scan to a recovery procedure.

URL Not Found” response is generated.

4-22 Shadow z/Enterprise Web Server Administration Guide

WWW Event Procedure Rules

Target WWW Rules

A WWW rule, which contains a process section declaration (following the

/*WWW” header statement line), is a normally a target WWW rule, unless the rule is

“ explicitly declared to be a gateway filter rule.

HOW THEY WORK

A target WWW rule’s process section is executed whenever a URL-to-rule match selects a matching rule. Execution of the process section definition is expected to generate an outbound response to the client’s original request.

Because target WWW rules generate all actual transaction responses, they are considered to be the ultimate targets of all URL-to-rule match searches. If no target WWW rule is matched while scanning for URL-to-rule matches, the URL is considered to be “

Found

.”

Once a target WWW rule has been matched and executed, the server ceases to look for additional URL-to-rule matches, because the first target rule match is considered to have responded to the client request. Unless the target WWW rule requests re-scan to a new URL value, the Web transaction ends following execution of the target rule.

Not

Target rules execute under control of the security an d environmental ru n-time options that have been accumulated during previous matches to URL filter rules and gateway filter rules.

Gateway Filter Rules

A WWW rule definition that contains a procedure (such as a process section), can be explicitly declared to be a gateway filter rule. You make this explicit specification by coding the keyword “GATEWAY” as an operand on the “

/*WWW” header statement.

HOW THEY WORK

Gateway filter rules are handled much like target WWW rules, except they:

 Are not assumed to generate a client response.  Are not considered to be the ultimate target of a URL-to-rule match search. After a

gateway filter rule is executed during URL-to-rule searching, the server continues searching until it locates a target WWW rule.

 Can re-direct subsequent processing using re-scan or flush requests.

If a target WWW rule is not located by subsequent matching, the URL request is rejected with a “ Gateway filter rules execute under control of the security and environmental run-time options that have been accumulated during previous matches to URL filter rules and gateway filter rules.

Not Found” condition even though the gateway procedure was executed.

Gateway filter rules can be used to provide a common front-end procedure that is executed each time a generic URL request is made against a set of related Web transaction definitions. The gateway can monitor query variables or cookie values and use re-scan or flush to re-direct processing until some validity requirement has been fulfilled.

Shadow z/Enterprise Web Server Administration Guide 4-23

Defining Event Procedure Types

Once the validity check is passed, the gateway exits normally and allows the server to continue its search for a target rule definition.

Example: A gateway filter rule can specify a REXX procedure or user written program that always

executes before a match to a more specific target URL strings. For example, it can be used to implement a customized HTML form-b as ed logo n /lo go ff fr on t- en d tr an sactio n which must be concluded before access to the target rules is allowed.

For such a front-end, the gateway rule is matc hed and executed first. It then che cks to see if a valid logon has already been performed. If it has, the gateway filter rule terminates normally, so subsequent processing by the server locates one of the target rules being front-ended. If the logon has not been completed, the gateway filter rule procedure could display and process a logon HTML form, which creates a timed token to remember the logon through subsequent interactions with the client.

Syntax of WWW Rule Definitions

Each WWW rule definition is coded within a separate member of a ruleset PDS(E) data set. The syntax needed to define a valid WWW rule definition contains:

 A WWW rule header statement (required)

This statement must begin in the first position of the first record wit hin the rule (disregarding optional record numbering), and it must begin with the delimiter characters “

The URL match criterion is a required positional operand that must appear on the same line, immediately following “ the URL value(s) that can be matched to this rule to trigger its selection during URLto-rule searching. For example:

/*WWW /NEON/HTMLFILE/* AUTHR EQ(NO)

Optional keyword parameters follow the URL criterion string on the first input line and can be continued on subsequent lines. These keywords define operational characteristics that are set up when a URL-to-rule match occurs. Keywords control the run-time security authorization framework and allow various diagnostic information to be selectively produced.

 A process section declaration (optional)

WWW event procedures can contain:

/*WWW”.

/*WWW” delimiter. The match criterion string gives

− Header-only rules (no process section)

− /*REXX, /*FILE, or /*PROGRAM process sections

For example:

/*FILE DATATYPE(PDS) DDNAME(HTMFILE ) CONTENTTYPE(text/html)FORMAT(BINARY)

4-24 Shadow z/Enterprise Web Server Administration Guide

WWW Event Procedure Rules

WWW Header Keywords

Many keyword parameters can be coded on the “/*WWW” rule header statement. All are optional, but if coded, they must follow the required URL matching criterion value.

The WWW header keywords fall into the following categories:

 Security administration controls  Gateway  Load balancing  Developer selectable options

Note:

If you continue a “ (“-”) at the end of a line to indicate that the statement is continued onto the following line.

SECURITY ADMINISTRATION CONTROLS

The security keywords are used to configure the run-time authorizations und er which a transaction operates. Some of these keywords can only be specified by a Shadow z/ Enterprise Web Server administrator within the master ruleset and are not available to the developer unless delegated otherwise.

/*WWW” header statement onto multiple lines, code a trailing dash

Security keywords are specifically related to server security administration and can be applied generically to groups of WWW rules. See Chapter 5, “Web Transaction Security,” for more information on the following security administration control keywords:

GATEWAY

The GATEWAY keyword declares that the WWW rule act as a gateway filter rule. This GATEWAY keyword must be explicitly coded in order to designate all gateway filter rules.

 WWW rules that contain a process section but do not have the GATEWAY keyword

explicitly coded are always processed as target WWW rules.

 WWW rules that do not contain a process section are always processed as URL filter

rules.

The distributed rule in

WWW.SWSCNTL is an application dependant example of a REXX

language logon gateway filter rule that handles HTML form-ba sed MVS logons. Use the

SWSCNTL/MENU to access this sample application.

URL /

LOAD BALANCING

The BALANCE keyword declares that requests matching the rule should be sent to members of the load balancing group to which that server belongs. Only requests sent to the load balancing group director are redirected to other members in the group. Load balancing is either defined in the startup parameters or dynamically using the ISPF

Shadow z/Enterprise Web Server Administration Guide 4-25

Defining Event Procedure Types

panels. Only other copies of Shadow z/Enterprise Web Server with load balancing configured to the same group are used for load balancing.

The Workload. To properly share the workload, e ach copy of the Shadow z/Enterprise Web Server must have access to all the same facilities, programs, and files. Workload is distributed in a round-robin fashion with the group director as one of the servers sharing the workload. When the load balancing group director sends work to another member of the load balancing group, the director will reply with the appropriate redirecting response. When the load balancing group director decides to process work itself, no such redirection takes place.

Be aware of the following when using the BALANCE keyword:

 Filter Rules: When using the BALANCE keyword on URL filter rules (such as “/*www

/fab/* balance

If a GET or HEAD request arrives with query variables encoded in th e URL or a POST request arrives, it is not considered “stateless.” As such, it will not be redirected, even if the WWW rule indicates that it will. Only GET and HEAD requests are subject to redirection.

 Target Rules: The same considerations cited for filter rules (regarding GET and

HEAD requests and the required absence of query variables) hold true for target rules. Only “stateless” requests should be redirected.

”), only “stateless” requests should be redirected.

 Redirected Rules: If an incoming requests matches a WWW rule with the BALANCE

keyword and is then redirected to a group member, the request will not be processed against another rule. Instead, the rule processing terminates when the redirection takes place.

 File Access: A FILE rule may be used with the BALANCE keyword as long as each

member of the load balancing group has the same rule and access to the files.

Note:

Each site must decide which rules will use the BALANCE keyword. Only the application designer can be certain of the best place to put rules with the BALANCE keyword and still maintain proper operation.

DEVELOPER SELECTABLE OPTIONS

Some “/*WWW” statement keywords specify developer selectable option s that can be used to control the transaction run-time environment and resource allocations needed for execution of an individual WWW rule. For instance, a developer ma y nee d to o verri de the server’s default limitation on maximum outbound response size if the rule is expected to output a very large response. Or a run-time tracing optio n may be temporarily turn ed on in order to trace an outbound response for debugging purposes.

The developer selectable options can be specified for any WWW rule and only apply to the an individual rule. The developer keywords are:

AUTHOFLUSH(integer)

This keyword parameter operates only for Web transactions that execute in “nonparsed header” mode; otherwise, it is ignored.

4-26 Shadow z/Enterprise Web Server Administration Guide

The server can automatically issue flush-to-client requests periodically while an outbound response is being composed. This parameter is the number of 32k outbound transmission buffers that must be filled before an automatic flush-toclient request is issued.

The operand value for this keyword must be in the range of 0 (zero) to 32,767. Coding 0 (zero) disables the automatic flush-to-client feature. If this keyword is not explicitly coded for a rule, the start-up parameter MAXCHAINEDBUFFERS value is used instead.

DPRTY(value)

This keyword overrides the dispatching priority of the Web transaction subtask relative to other subtasks within the server address space and allows you to raise or lower the relative priority of certain Web transaction tasks. This is useful when defining long-running DB2-based transactions to keep those tasks from slowing overall response time.

Code the operand of DPRTY as a integer between 0 (zero) and 255 with or without a leading sign. If a leading sign is used, do not code blanks between the leading sign and the integer following it.

 If no leading sign is present, the operand value gives the absolute disp atching

priority to be assigned to the transaction subtask.

WWW Event Procedure Rules

 If a leading plus or minus sign is coded, the current dispatching priority is

raised or lowered by the value given.

Only WWW procedures coded within the master ruleset may specify a net increase in a task’s dispatching priority. Any attempt to increase the priority from within a subordinate ruleset is ignored.

HTXTRACE(list)

This keyword specifies whether a pre-compile or evaluation time trace is performed when an HTML extension processing occurs while executing a WWW rule. The trace options apply only to HTML extension processing that occurs while executing a WWW rule. The HTXTRACE option is not cumulatively applied to the WWW transaction when more than a single WWW rule is matched.

If this keyword parameter is not coded, the subsystem will not trace HTML extension processing while executing this or any other WWW rule.

This parameter can be used to diagnosis problems when processing source file information containing complex HTML e xtension st atement s. The keyword has no effect if HTML extensions are not processed while the transaction is executing.

Specify one to thr ee of the keyword values shown in Table 4–18 as the operand of the HTXTRACE parameter. Sep arate multiple keywords with a single space, not a comma.

Parameter Value Meaning

HTXTRACE(ALL) Perform all traces. ALL is equivalent to specifying “HTXTRACE(EMIT EVAL

PCODE)”.

Table 4–18. HTXTRACE(EMIT EVAL PCODE)

Shadow z/Enterprise Web Server Administration Guide 4-27

Defining Event Procedure Types

Parameter Value Meaning

HTXTRACE(EMIT) Trace internal P-code elements during compilation. If a cached P-code image is

in use, the trace is not performed. In order to ensure that compile time P-code emit trace is performed, purge the cache storage for the member being processed before invoking the WWW transaction.

HTXTRACE(PCODE) Trace internal P-code elements immediately before performing evaluation and

substitution of the source file.

HTXTRACE(EVAL) Trace evaluation of each HTML extension statement as it is processed during

output of the source file.

Table 4–18. HTXTRACE(EMIT EVAL PCODE)

MAXRESPBUFFERS( integer )

This keyword parameter specifies a limit on the number of 32k, outbound HTTP response buffers that any single transaction can simultaneously hold in storage while an outbound response is being composed. The minimum value that can be specified is 0 (zero) and the maximum is 32,767. If 0 (zer o) is coded, buffer-count limit checking is not performed.

If this parameter is not coded, the server uses the setting of the start-up parameter, MAXHTTPRESPBUFFERS, as a limit on the number of outbound response buffers. If this limit is exceeded, Shadow z/Enterprise Web Server generates a

User Abend x'722' with a reason code 500 in order to cancel the

transaction procedure.

MAXRESPBYTES( integer )

This keyword parameter specifies a limit on the total number of bytes that can be transmitted in an HTTP response message. The minimum value that can be coded is 0 (zero) and the maximum is 2,147,483,647. If 0 (zero) is coded, outbound byte count limit checking is not performed.

If this parameter is not coded, the server uses the setting of the start-up parameter, MAXHTTPRESPBYTES, as a limit on the number of outbound bytes. If this limit is exceeded, Shadow z/Enterprise Web Server generates a

Abend x'722'

with a reason code 500 in order to cancel the transaction

User

procedure.

RESPMODE( SERVER | NONE )

This keyword parameter can be set to control the operational mode of the server while an outbound response is being composed by the Web transaction. Two operational modes, shown in Table 4–19, are provided.

Parameter Value Meaning

RESPMODE(NONE) The Web transaction composes and transmits an outb ound response in

non-parsed header mode.

RESPMODE(SERVER) The Web transaction composes an outbound response, and the server

monitors and transmits the response in server-parsed mode.

Table 4–19. RESPMODE Parameters

4-28 Shadow z/Enterprise Web Server Administration Guide

If the RESPMODE keyword parameter is not explicitly coded, the server executes the Web transaction using the setting of the start-up HTTPRESPMODE parameter. Server-parsed mode operation is the preferred and it is the normal operational mode.

Non-Parsed Header Mode

Non-parsed header mode requires that the user supply all the required HTTP response headers needed to communicate with the client Web browser. In this mode, the server does not examine, override, or augment the outbound HTTP response message headers output by the Web transaction. The We b transaction procedure has direct control of the outbound communications session and can even have a partial response transmitted to the client before the entire outbound response message has been composed.

The server uses this operational mode when transmitting huge files to prevent large outbound responses from occupying excessive amounts of virtual storage. Refer to the Shadow z/Enterprise Web Server Programming Reference Guide or the online HTML for information on SWSSEND, high-level language SWSSEND, ADDRESS SWSSEND, and flush-to-client operations.

Following the completion of a transaction operating in non-parsed header mode, the server never attempts to provide persistent session support; the communications session is always closed.

WWW Event Procedure Rules

Server Parsed Header Mode

In server parsed header mode, Shadow z/Enterprise Web Server buffers the complete outbound response until the Web transaction is completed. The serve r then examines whatever HTTP response headers that were explicitly output by the transaction. The generated transaction HTTP response headers could be left unchanged, altered, or removed by the server. Also, additional HTTP response headers could be inserted into the outbound response message. After reviewing the HTTP response headers, the server transmits the complete outbound response message.

PARSETRACE( NO | YES )

This keyword specifies whether the parsing of WWW event related variables is to be written to the wraparound trace dat a set (trace browse). If th e par sed variables were not previously traced during execution of the Web transaction, the trace is written when the WWW rule is matched.

If this keyword parameter is not coded, the subsystem uses the setting of the product level parameter, TRACEURLPARSE, to determine if outbound tracing is performed.

The values shown in Table 4–20 can be specified for PARSETRACE.

Parameter Value Meaning

PARSETRACE(NO) Do not generate a trace of the parsed WWW variables. PARSETRACE(YES) Generate a trace of the parsed WWW variables, if not previously traced.

Table 4–20. PARSETRACE Parameter

Shadow z/Enterprise Web Server Administration Guide 4-29

Defining Event Procedure Types

QUEUESIZE( integer )

This keyword specifies the number of entries allocated within the external data queue, which is used by Shadow/REXX to support the PUSH and PARSE PULL instructions. The queue is also used to return the results of executing a TSO request within an external TSO server address space.

Use this keyword parameter to:

 Override the default external data queue specification made by the

SEFMAXQUEUE start-up parameter.

 Increase the default queue allocation size when a large number of queued

lines are expected in a response. If the value specified for th e QUEUESIZE( ) keyword is smaller than the SEFMAXQUEUE start-up param eter, the value set for SEFMAXQUEUE is used instead.

Code the operand of QUEUESIZE( ) as an integer in the range of 1 to 1,000,000. The operand gives the absolute number of entries to be pre-allocated for the external data queue.

SENDTRACE( NO | YES )

This keyword specifies whether the transaction generates wraparound trace entries to record outbound data sent to the Web client. If this keyword parameter is not coded, the subsystem uses the setting of the product level parameter, TRACEHTML, to determine if outbound tracing is performed.

Table 4–21 shows the values that can be specified for SENDTRACE.

Parameter Value Meaning

SENDTRACE(NO) Do not generate a trace of the outbound transmission. SENDTRACE(YES) Generate a trace of the outbound transmission.

Table 4–21. SENDTRACE Parameters

WORKSIZE( integer )

This keyword specifies the size (in kilobytes) of the REXX work space to allocate while executing this WWW rule. The REXX work space is used by Shadow/REXX to contain run-time variable names, values, and evaluation areas during execution.

Use this keyword parameter to:

 Override the default work space size specification made by the SEFSIZE

start-up parameter.

 Increase the default allocation size when a large number of run-time variables

are expected. If the value specified for the WORKSIZE( ) keyword is smaller than the SEFSIZE start-up parameter, the value set for SEFSIZE is used instead.

For example, you may find this keyword useful when using the ADDRESS SQL environment of Shadow/REXXTOOLS. If a DB2 query returns a large result set, a REXX work space is needed to contain each column’s variable name and value, which could result in large space requirements.

4-30 Shadow z/Enterprise Web Server Administration Guide

Code the operand of WORKSIZE( ) as an integer in the r ang e of 48 to 2,00 0,000 . The operand value specifies the work space size to be allocated in kilobytes.

WWW URL-to-Rule Matching

The following discusses how the URL-to-rule matching and its criteria are handled.

Search Order

When the server begins a URL-to-rule search, event procedures ar e matched from the least to most specific. Unless a re-scan is done, the search ends when the first target WWW rule is matched.

Note:

URL-to-rule matching can be prematurely suspended if any gateway or target procedure issues a flush request to suspend further rule matching and terminate the current transaction normally.

Match Order

WWW Event Procedure Rules

If two or more WWW rules specify exactly the same URL match criterion string, they are matched in the following order:

 Rules defined in the master WWW ruleset are always matched before rules defined in

subordinate WWW rulesets.

 URL filter rules, consisting of only a “/*WWW” header statement, are matched before

any gateway filter rules or target WWW rules.

 Gateway filter rules are matched before any target WWW rules.

Warning:

It is possible to create a group of WWW rule definitions where some WWW rules can never be matched. Because each search proceeds from least to most specific, and searching ends when a target is located, wildcards must be used carefully. The server does not warn of unmatchable WWW rule definitions.

For example: If two like target rules are defined, only one is matched and executed at run-time. The order in which the match occurs is unpredictable. URL criterion values must be constructed so one WWW rule does not “hide” other, more specific rules.

WWW Rule Header Statements

You can specify a 1 to 128 character string for the criterion value of the WWW event procedure rule header statement. The criterion must be coded as a continuous string of non-blank characters and must appear on the first line of the rule; continuation of the URL string is not allowed.

If the value is specified in lowercase, SEF converts it, internally, to uppercase. Shadow z/ Enterprise Web Server processes all URL matching operations using uppercase URL values.

Shadow z/Enterprise Web Server Administration Guide 4-31

Defining Event Procedure Types

Character String Restrictions

 If the event procedure resides within the master WWW ruleset, the character string

that you specify as the URL matching criterion is unrestricted.

 If the event procedure resides within the subordinate WWW ruleset, the character

string that you specify as the URL matching criterion is restricted. The criterion value must begin with the string “ combination of characters is allowed after the required prefix.

 If a leading slash character (“/”) is not part of the criterion specification (allowed only

within the master ruleset), the URL value cannot be matched by an externally entered Web transaction. Only a re-scan operation can invoke an event procedure without using a leading slash character.

See “Special Characters and URL String” in the Shadow z/Enterprise Web Server Getting

Started Guide for recommendations on structuring URL criterion values.

WWW Rule Process Sections

Any of the valid process section types can be coded as part of a WWW rule to specify a procedure to be executed by the server:

/xxxxxxxx”, where xxxxxxxx is is the ruleset name. Any

 /*REXX sections for low-to-intermediate volume scripting of Web transactions  /*FILE sections to return an MVS data set as a Web transaction re sp onse  /*PROGRAM sections for high volume transaction deployment  /*EXECSQL sections for rapid creation of Web transaction responses using data

stored in a DB2 database

 /*TSOS RV sections for executing a TSO/E command processor, CLIST, REXX, or

ISPF procedure in an isolated outboard TSO/E server

WWW Rule Examples

SETTING RUN-TIME SECURITY ENVIRONMENT (URL FILTER RULE)

The following example shows a generic filter rule that sets up a run-time operational limit for more specific URL-to-rule matches within the generic group:

/*WWW /NEON/* RUNAUTH(UserN)

A third-party-proxy userid, “ procedure that begins with “

The remaining examples (shown below) run within an MVS subtask where “ as the run-time MVS userid.

UserN”, is used to execute any URL-to-rule transaction

/NEON/”.

UserN” is set

ACCESSING NATIVE MVS FILES (TARGET WWW RULE)

Whenever a URL arrives in the system, it is matched to a WWW rule, which is then executed by the server. For example:

4-32 Shadow z/Enterprise Web Server Administration Guide

WWW Event Procedure Rules

Inbound URL:

HTTP://my.server/NEON/HTMFILE/ MEMBER2

Matching WWW Rule:

/*WWW /NEON/HTMFILE/* /*FILE DATATYPE(PDS) DDNAME(HTMFILE) CO NTENTTYPE(text/html) -

FORMAT(TEXT)

In this example, the server’s built-in /*FILE procedure executes to handle the client’s request.

The /*FILE process section uses information represented by the URL wildcard character (“

MEMBER2”) to specify which PDS member to be returned to the client. Since this rule

contains a procedural specification (the /*FILE process section), it is allowed as a target of the URL-to-rule match. A return response to the client is expected.

The prior URL-to-rule match for “ while this procedural rule executes. See “Setting Run-Time Security Environment (URL Filter Rule)” on page 4-32.

/NEON/*” causes the proxy userid, “UserN”, to be set up

TURNKEY DB2 ACCESS RULE (TARGET WWW RULE)

The following WWW rule is executed by the server whenever a matching URL request arrives:

/*WWW /NEON/QSTAFF AUTHREQ(NO) /*EXECSQL SUBSYS(DSN2) PLAN(SWSCC1010) MAXBLOCKS(30) AUTOFORMAT( TITLE('Contents of Q.STAFF Tab le') BODY('bgcolor="#FFCC33"') )

select * from q.staff

Here, the server executes a SQL statement (“ dynamically formats the result set as an HTML table. Additional process section parameters can be used to refine the SQL query or allow customized HTML output.

Authorization to access the Q.STAFF table is granted or denied based upon the run-time proxy userid, “ Environment (URL Filter Rule)” on page 4-32.

UserN”, which was set up by the filter rule. See “Setting Run-Time Secu rity

select * from q.staff”) and then

WWW Event-Related Variables

Each time an inbound HTTP request is received by the Shadow z/Enterprise Web Server subsystem, the system parses the HTTP requ e st he ad e r to dete rm in e which event procedure to run. During the parse operation, various data items are extracted from the transaction header along with other environmental data elements. These items are made available to WWW rule transaction procedures and is used in composing an HTML response.

Shadow z/Enterprise Web Server Administration Guide 4-33

Defining Event Procedure Types

Using the Shadow/Rexx Interpreter

By using the variable names listed in Table 4–22 on page 4-34, Shadow/REXX can access these run-time values by name. These variables are automatically set up in the REXX-language environment before a Shadow/REXX procedure is executed.

You can see a demonstration of how a Shadow/REXX procedure is invoked and can make use of these run-time variables by accessing the sample procedure

/NEN/DEMO01.

Using Non-Shadow/REXX Interpreters

User written programs or REXX procedures executed by other (non-Shadow/REXX) interpreters must use an API interface call to r etrieve the value of these run -time variables. Use the SWSVALUE API call for user written high-level language program access, or use the SWSVALUE built-in function for non-Shadow/REXX interpreters.

Variable Name Contents

PHASE Conte nts: Contains a 4-byte character constant that indicates the

processing phase for which the current event procedure was invoked.

• If set to INIT, the procedure is being enabled either during subsystem start-up or in response to a user enable request.

• If set to PROC, the procedure is being run after being matched to an inbound HTTP transaction request.

• If set to TERM, the procedure is being disabled either during subsystem shut-down, or in response to a user disable request.

During procedure enablement and disablement, the only other variable that is instantiated is WWW.USER. The remaining variables are only instantiated during PROC phase processing.

Note: REXX procedures normally run only during the PROC phase, unless explicitly requested. See Chapter 6, “Writing Web Transactions in REXX,” for more information.

Data Type: Character, Read-only

WWW.ABENDCODE Contents: The decimal value of the last encountered abend code. The

value can be converted to displayable hexadecimal using the D2X built-in REXX function. The value is zero if no abend has occurred during processing.

Data Type: Integer, Read-only

WWW.ABENDREASON Contents: The decimal value of the last encountered abend reason code.

The value can be converted to displayable hexadecimal using the D2X built-in REXX function. The value is zero if no abend has occurred during processing.

Data Type: Integer, Read -only

WWW.ACCEPT_CHARSET Contents: The value of the “Accept-charset:” HTTP request header token.

If the “Accept-charset:” request header is not present in the inbound HTTP request, this variable is se to a NULL value.

Data Type: Character, Read-On ly

Table 4–22. WWW Event-Related Variables

4-34 Shadow z/Enterprise Web Server Administration Guide

WWW Event Procedure Rules

Variable Name Contents

WWW.ACCEPT_ENCODING Contents: The value of the “Accept-encoding:” HTTP request header

token. If the “Accept-encoding:” request header is not present in the inbound HTTP request, this variable is se to a NULL value.

Data Type: Character, Read-On ly

WWW.ACCEPT_LANGUAGE Contents: The value of the “Accept-language:” HTTP reque st header

token. If the “Accept-language:” request header is not present in the inbound HTTP request, this variable is set to a NULL value.

Data Type: Character, Read-Only Contents: Contains the number of “Accept:” HTTP request headers found

within the inbound HTTP request. If none were found, the value of this variable is zero.

Data Type: Integer, Read -Only

WWW.ACCEPT.n Contents: Variables WWW.ACCEPT.1 through WWW.ACCEPT.n (where

n is equal to the value of the variable WWW.ACCEPT.0) contain each of the tokens set for the “Accept:” HTTP request headers found in the inbound HTTP transaction. If no “Accept:” headers were present in the inbound message, then WWW.ACCEPT.0 will be set to zero, and the remaining WWW.ACCEPT.n variables will not be instantiated.

Data Type: Character, Read-On ly

WWW.AUTH Contents: Set to a character value, indicating the authorization level of the

current event procedure.

• NONE. No authorization data was sent with the inbound HTTP transaction request. The current transaction runs under the authorization of the Shadow z/Enterprise Web Server subsystem or an overriding RUNAUTH userid value.

• SENT. Authorization data was sent with the inbound HTTP transaction request, but it was not used to perform userid/password validation. In order to conserve CPU resources, userid validation is only performed when required by the security attributes of the transaction. Because userid validation is not required by the current transaction, the authorization data sent by the Web client was not processed. The current transaction is running under the authorization of the Shadow z/Enterprise Web Server subsystem or an overriding RUNAUTH userid value.

• NO. Authorization data was sent with the inbound HTTP transaction request, but the userid or password value was invalid and could not be used to log on to the system. The current transaction is running under the authorization of the Shadow z/Enterprise Web Server subsystem or an overriding RUNAUTH userid value.

• YES. The inbound HTTP transaction contained a valid userid and password, which were used to log on to the system. The current transaction runs under the authorization of the Shadow z/Enterprise Web Server subsystem, an overriding RUNAUTH userid value, or the authorization of the end user.

Data Type: Character, Read-On ly

Table 4–22. WWW Event-Related Variables

Shadow z/Enterprise Web Server Administration Guide 4-35

Defining Event Procedure Types

Variable Name Contents

WWW.AUTHDATA Contents: Contains the value of the undecoded authentication information

sent by inbound HTTP “Authorization:” request header. If no such request header was present, this variable contains a NULL string.

Data Type: Character, Read-On ly

WWW.AUTHMETHOD Contents: Contains the value of the authorization method specified in the

inbound HTTP “Authorization:” request header. If no such request header was present, this variable contains a NULL string. At present, the only allowable value for this variable is the string “BASIC”.

Data Type: Character, Read-Only

WWW.AUTHMSG Contents: Contains a string value containing the message issued by the

security subsystem when the inbound userid and password were used to process a logon request.

Data Type: Character, Read-Only

WWW.AUTHORIZATION Contents: Contains the decoded value of the “Authorization:” request

header userid and password, contained within the inbound HTTP request. If no “Authorization:” request header was present, this variable contains a NULL string. The password within the decoded authorization string has been overlaid with Xs.

Data Type: Character, Read-Only

WWW.AUXCOMPONENT Contents: For some Shadow z/Enterprise Web Server processes, external

MVS subsystems are invoked. If an exceptional condition occurs, the WWW.AUXxxxx variables are set to reflect the error.

This variable contains the name of the external component. It is set to the string “DB2” when exceptional conditions are noted during DB2 open processing or when processing an EXECSQL process section.

Data Type: Character, Read-Only

WWW.AUXRC Contents: For some Shadow z/Enterprise Web Server processes, external

MVS subsystems are invoked. If an exceptional condition occurs, the WWW.AUXxxxx variables are set to reflect the error.

This variable contains the return code set by the external component. Data Type: Integer, Read -Only

WWW.AUXREASON Contents: For some Shadow z/Enterprise Web Server processes, external

MVS subsystems are invoked. If an exceptional condition occurs, the WWW.AUXxxxx variables are set to reflect the error.

This variable contains the reason code set by the external component. Data Type: Integer, Read-Only

WWW.AUXABEND Contents: For some Shadow z/Enterprise Web Server processes, external

MVS subsystems are invoked. If an exceptional condition occurs, the WWW.AUXxxxx variables are set to reflect the error.

This variable contains the abend code set by the external component. Data Type: Integer, Read -Only

Table 4–22. WWW Event-Related Variables

4-36 Shadow z/Enterprise Web Server Administration Guide

WWW Event Procedure Rules

Variable Name Contents

WWW.AUXOTHER Contents: For some Shadow z/Enterprise Web Server processes, external

MVS subsystems are invoked. If an exceptional condition occurs, the WWW.AUXxxxx variables are set to reflect the error.

This variable contains any other code set by the external component. Data Type: Integer, Read-Only

WWW.AUXMSG Contents: For some Shadow z/Enterprise Web Server processes, external

MVS subsystems are invoked. If an exceptional condition occurs, the WWW.AUXxxxx variables are set to reflect the error.

This variable contains text information describing the exceptional condition.

Data Type: Character, Read-On ly

WWW.COOKIE Contents: Contains the value specified for the “Cookie:” HTTP request

header, if present, or a NULL string. See the Netscape Documentation at Persistent Client State HTTP Cookies for more information.

Data Type: Character, Read-On ly

WWW.COOKIE.xxxxx Contents: Contains the value of the name/value pair, xxxxx, contained

within the “Cookie:” HTTP request header. See the Netscape Documentation at Persistent Client State HTTP Cookies for more information.

Data Type: Character, Read-Only

WWW.CONTENT_LENGTH Contents: Contains the value specified for the “Content-length:” HTTP

request header, if present, or a NULL string. Data Type: Integer, Read -Only

WWW.CONTENT_TYPE Contents: Contains the value specified for the “Content-type:” HTTP

request header, if present, or a NULL string. Data Type: Character, Read-On ly

WWW.CURRENTURL Contents: The current value of the URL being used to perform matching to

Web event procedures. This is normally set to the value specified in the input HTTP transaction request, unless an intervening procedure or the subsystem has altered the match value.

The subsystem alters match values when certain errors are encountered to re-direct processing to one of the built-in SYSTEM/ERROR/nnn procedures.

User procedures can alter the match URL value by issuing “RETURN RESCAN xxxx” from an event procedure.

Data Type: Character, Read-On ly

WWW.DATE Contents: Contains the value specified for the “Date:” HTTP request

header, if present, or a NULL string. Data Type: Character, Read-Only

Table 4–22. WWW Event-Related Variables

Shadow z/Enterprise Web Server Administration Guide 4-37

Defining Event Procedure Types

Variable Name Contents

WWW.EFFECTIVEUSERID Contents: Contains the MVS userid under whose authority the Web

transaction is currently executing. The value returned when this variable is interrogated reflects the subtask-level security authorizati on controls (the ACEE control block userid) established immediately before the current transaction procedure was given control. The userid returned can be the default Web transaction RUNAUTH userid, a client userid, or a third-party proxy userid, depending on the security controls in place when this WWW rule began execution.

Note: When ATH rules are executed on behalf of Web transaction procedures, WWW variables are normally made available to the ATH rule for inspection. However, WWW.EFFECTIVEUSERID is set to NULL whenever an ATH LOGON or LOGOFF procedure is being executed.

Data Type: Character, Read-On ly

WWW.ERRORCODE Contents: Contains the value of the transaction error code field. The field

may be set by the subsystem in response to various transaction-related error events.

Data Type: Integer, Read -Only

WWW.FIELD.0 Contents: Contains the number of field name/value pai rs present within

the input HTTP transaction. This value is set to zero if no name/value pairs were present.

Data Type: Integer, Read -Only

WWW.FIELD.n.NAME Contents: Contains the name of the nth field name/value present within

the input HTTP transaction. The value of n ranges from 1 to the value set for WWW.FIELD.0.

Data Type: Character, Read-On ly

WWW.FIELD.n.VALUE Contents: Contains the value of the nth field name/value present within

the input HTTP transaction. The value of n ranges from 1 to the value set for WWW.FIELD.0. If no value was present for the nth pair, this variable contains a NULL string.

Data Type: Character, Read-On ly

WWW.FORW ARDED Contents: Contains the value specified for the “Forwarded:” HTTP request

header, if present, or a NULL string. Data Type: Character, Read-Only

WWW.FROM Contents: Contains the value specified for the “From:” HTT P request

header, if present, or a NULL string. Data Type: Character, Read-Only

WWW.HOST Contents: Contains the value of the “Host:” HTTP request header, if

transmitted, for the inbound request. It is a character string, such as “tulx.txm.com:1322”.

Data Type: Read-Only.

WWW.IF_MODIFIED_SINCE Contents: Contains the value specified for the “If-modified-since:” HTTP

request header, if present, or a NULL string. Data Type: Character, Read-On ly

Table 4–22. WWW Event-Related Variables

4-38 Shadow z/Enterprise Web Server Administration Guide

WWW Event Procedure Rules

Variable Name Contents

WWW.INPUTURL Contents: Contains the original inbound HTTP request URL value.

Data Type: Character, Read-On ly

WWW.LINE.0 Contents: Contains the number of individual lines within the inbound

HTTP request header. Each line is delimited by a CRLF combination. Data Type: Integer, Read-Only

WWW.LINE.n Contents: Contains the contents of the nth line of the inbound HTTP

request header. Each line is delimited by a CRLF combination. The line data does not contain the delimiting CRLF. The number of WWW.LINE.n variables is given by WWW.LINE.0.

Data Type: Character, Read-On ly

WWW.MATCHVALUE Contents: Contains the criterion value of the current WWW event

procedure to which the inbound URL was matched. Data Type: Character, Read-Only

WWW.MESSAGE_ID Contents: Contains the value specified for the “Message-id:” HTTP

request header, if present, or a NULL string. Data Type: Character, Read-On ly

WWW.METHOD Contents: Contains the value specified for the HTTP method specified in

the inbound transaction. Shadow z/Enterprise Web Server accepts transactions that specify the GET, POST, and HEAD methods.

Data Type: Character, Read-On ly

WWW.MIME_VERSION Contents: Contains the value specified for the “MIME-version:” HTTP

request header, if present, or a NULL string. Data Type: Character, Read-On ly

WWW.PASSWORD Contents: Contains a NULL string if no authentication data was

transmitted by the client. Otherwise, it points to a string containing the password supplied as part of the BASIC authentication method. The password string is overlaid with Xs unless the server start-up option EXPOSEWWWPASSWORD is set to YES. Note that the default value for this start-up option is NO, so the client password is normally not actually available using this variable.

Data Type: Character, Read-On ly

WWW.PRAGMA Contents: Contains the value specified for the “Pragma:” HTTP request

header, if present, or a NULL string. Data Type: Character, Read-On ly

WWW.PROTOCOL Contents: Contains the HTTP version value that was present within the

inbound HTTP request header. Data Type: Character, Read-Only

WWW.QUERY Contents: Contains the value of any encoded query data that was present

within the inbound HTTP request header. The maximum size is 32K. Data Type: Character, Read-On ly

Table 4–22. WWW Event-Related Variables

Shadow z/Enterprise Web Server Administration Guide 4-39

Defining Event Procedure Types

Variable Name Contents

WWW.REFERER Contents: Contains the value specified for the “Referer:” HTTP request

header, if present, or a NULL string. Data Type: Character, Read-On ly

WWW.SSL Contents: Set to uppercase Y if an SSL connection is in use between the

server and client. Set to uppercase N if an SSL connection is not in use. Data Type: Character, Read-Only

WWW.STATUSCODE Contents: Contains the value set by a previous procedure of the

subsystem for the HTTP response status code value. If set to zero, the subsystem substitutes value 200 (request was fulfilled). The only action of this variable is to save the status code placed into transaction-level SMF records.

Data Type: Integer, Read-Write

WWW.TEXT Contents: Contains th e entire HTT P request header.

Data Type: Character, Read-Only

WWW.USER_AGENT Contents: Contains the value specified for the “User-agent:” HTTP request

header, if present, or a NULL string. Data Type: Character, Read-Only

WWW.USERID Contents: Contains the userid, if any, present within the inbound

“Authorization:” request header. Data Type: Character, Read-Only

WWW.VAR.xxxxx Contents: Contains the value of the input variable for each inbound query

variable named xxxxx. If multiple query variables of the same name are input, the variable contains the value set only for the last of these.

Data Type: Character, Read-On ly

Table 4–22. WWW Event-Related Variables

4-40 Shadow z/Enterprise Web Server Administration Guide

CHAPTER 5:

Web Transaction Security

This chapter expands on the concepts and information presented in Shadow z/Enterprise Web Server Getting Started Guide. This chapter includes information about the controlled transaction paradigm, levels of security, types of transactions, distributed transaction administration, security attributes processing, security processing steps, implementing distributed transaction administration, and specifying web transaction security parameters. Topics include:

About Web Browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Userid Prompting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Controlled Transaction Paradigm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Levels of Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

MVS Security Subsystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Client Authorization (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Effective Userid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5

Security Option Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

Distributed Transaction Administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

The Master Ruleset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

Subordinate Rulesets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9

Security Attributes Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10

Security Processing Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11

Implementing Distributed Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

Specifying Web Transaction Security Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13

WWW Header Statement Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13

Configuring Secure Sockets Layer (SSL) Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14

WWW Header Security Parameters and Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15

AUTHREQ ( YES | NO | LOCK ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15

RUNAUTH( NONE | CLIENT | proxy-id ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16

RESOURCE (string ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17

SSL( NO | COND | YES | LOCK | LOCKCOND ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17

Shadow z/Enterprise Web Server Subsystem Security . . . . . . . . . . . . . . . . . . . . . . . . . 5-19

Setting Limits for the Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19

Protecting Subsystem Command and Control Interfaces. . . . . . . . . . . . . . . . . . . . . 5-21

About Web Browsers

Shadow z/Enterprise Web Server allows users with Web browsers to:

 Access DB2 tables via dynamic or static SQL using the high performance, built-in DB2

connection facilities provided by Shadow.

 Use CICS, IMS, and TSO/E transaction processing facilities.  Access Web transactions that use DB2, VSAM, or virtually any data storage facility of

MVS. Access is performed under strict controls imposed by the Server using services such as RACF, ACF/2, and Top Secret.

Shadow z/Enterprise Web Server Administration Guide 5-1

Web Transaction Security

 Use customizable Web transaction services built into the Shadow z/Enterprise Web

Server rule-based architecture. The built-in applications include facilities for creating Web enabled applications that:

− Serve static or run-time generated HTML or other dat a from virtually any MVS file .

This function implements the intrinsic file server model used for HTTP but allows mapping of URL requests to the native MVS file system.

− Handle form based DB2 queries and updates.

− Execute commands and procedures that execute within a TSO/E server,

managed by the product. This facility provides access to various MVS data source and APIs that are normally unavailable using any other MVS based Web server. You can create Web enabled access to facilities such as ISPF, DFHSM, CLISTs, or any other component that operates under TSO/E.

 Execute customer-written transaction programs or scripts. You can write transaction

programs using COBOL, PL/I, C, C++, and Assembler or execute command procedures written in IBM TSO/E REXX language or a third-party vendor scripting language, such as Prevail/XP OPS/REXX.

Userid Prompting

The following information applies to the use of the BASIC authentication protocol supported by all Web browsers, but might not apply to newer authentication protocols.

Part or all of an outbound response to a URL request is a n HT TP response hea der, which contains a standard status code value.

Response Status Code 401

When the client receives an HTTP 401 (“Not Authorized”) r esponse, it means the URL request is not authorized. Most browsers display a popup window that requests a userid and password. Once the user enters this information, the browser retransmits the original request, but adds an authentication header containing the encoded information.

The browser retains a copy of this information and automatically sends the same userid/ password combination in response to subsequent 401 status errors. The browser continues to use this information until the browser session is terminated.

Re-logons

Because the browser retains the userid/password information, it makes a generic “relogon,” such as you might use to switch TSO/E userids using a 3270 session, virtually impossible to provide. Generic re-logons require that the browser be closed and reopened. This appears awkward to users unless it can be customized to specific transactions.

At present, there is no way in which a server can sign al a Web browser to drop its inter nal copy of a userid and password.

Each unique (and valid) userid, password, server domain, URL, and REALM comb ination:

5-2 Shadow z/Enterprise Web Server Administration Guide

Progress SHADOW Z User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

What is Shadow z/Enterprise Web Server

How It Works

Why Use It?

Shadow z/Enterprise Web Server Architecture

How It Works

Threading Architecture

Product Capabilities and Benefits

Fast, Simple Implementation

Easily Understandable (Native MVS Web Server)

High Performance

Comprehensive Management, Monitoring, and Control Capabilities

Extreme Scalability Capabilities

How Shadow z/Enterprise Web Server Is Used

Top-Notch Security

Optional Shadow Interfaces

Executing IMS Transactions

Comparison Table

Executing CICS Transactions

Summary

An Overview of the Process

How Shadow z/Enterprise Web Server Processes Transactions

When the URL Matches a Rule

When the URL Does Not Match a Rule

Using Rules

Structure of a Rule (Event Procedure)

Creating, Enabling, and Accessing a Rule

Creating the Rule

Enabling the Rule

Accessing the Rule Using a Web Browser

Deploying Shadow z/Enterprise Web Server at Your Site

Setting Up the Mainframe Side

Setting up the Client Side

What It Does

How It Works

Event Types

Event Matching

Event Procedure Execution

Event Procedure Rulesets

Naming Convention

Start-up Parameters

Event Procedure Data Set Format

Enabling Event Procedures

Enabling and Disabling Event Procedure Rules

Structure of an Event Procedure

Event Procedure Header Statement (Required)

Process Section Header Statements

Header-Only Rules

SEF Event Procedure Variables

WWW Event Procedures

REXX Dynamic Variables

Global Variables

GLVEVENT Temporary Variables

Event Related Variables

Event Procedure Return Values

Accessing SEF Variables

Controlling SEF from a Batch Environment

Return Messages

Different Event Procedure Types

Authorization (ATH) Event Procedures

How ATH Event Procedures Work

ATH Event Procedure Criterion

ATH Event Procedure Header Keywords

ATH Event Procedure Process Sections

ATH Event Procedure Return Values

ATH Event Procedure REXX Variables

ATH Event Procedure Access Type Values

Command (CMD) Rule Event Procedures

How CMD Rule Event Procedures Work

CMD Rule Event Procedure Syntax

CMD Rule Event Procedure Criterion

CMD Rule Event Procedure Header Keywords

CMD Rule Event Procedure Process Sections

CMD Rule Event Procedure Return Values

Special Considerations for STOP Rules

CMD Rule Event Procedure REXX Variables